1// Package provider defines the Provider interface and UserInfo type used for
 2// external authentication in the webui.
 3//
 4// Each concrete provider (GitHub, GitLab, OIDC, …) implements Provider and is
 5// registered by passing it to the auth handler at server startup.
 6// The generic authorization-code flow (state, cookie) is handled by the auth
 7// handler; providers only need to supply endpoints and profile fetching.
 8//
 9// The Provider interface is deliberately protocol-agnostic: it works for both
10// OAuth 2.0 providers (GitHub, legacy systems) and OpenID Connect providers
11// (GitLab, Gitea, Keycloak, Google). OIDC is simply OAuth 2.0 + a standard
12// identity layer; the same AuthURL/Exchange flow applies to both.
13package provider
14
15import "context"
16
17// Provider represents an external identity provider.
18type Provider interface {
19	// Name returns the machine-readable identifier, e.g. "github".
20	Name() string
21
22	// HumanName returns a user-facing display label, e.g. "GitHub".
23	HumanName() string
24
25	// AuthURL returns the URL the browser should be redirected to in order
26	// to begin the authorization-code flow.
27	AuthURL(state, callbackURL string) string
28
29	// Exchange converts an authorization code into a normalised UserInfo.
30	// The callbackURL must match the one used in AuthURL.
31	Exchange(ctx context.Context, code, callbackURL string) (*UserInfo, error)
32}
33
34// UserInfo holds the normalised user profile returned by a provider after a
35// successful authorization-code exchange. Fields may be empty when the
36// provider does not supply them.
37type UserInfo struct {
38	Login      string
39	Email      string
40	Name       string
41	AvatarURL  string
42	// PublicKeys holds SSH or GPG public keys associated with the account,
43	// if the provider exposes them. Used to pre-populate identity key data.
44	PublicKeys []string
45}