1// Package oauth defines the Provider interface and UserInfo type used for
 2// external OAuth2 authentication in the webui.
 3//
 4// Each concrete provider (GitHub, GitLab, …) implements Provider and is
 5// registered by passing it to the auth handler at server startup.
 6// The generic oauth2 flow (PKCE, state, cookie) is handled by the auth
 7// handler; providers only need to supply endpoints and profile fetching.
 8package oauth
 9
10import "context"
11
12// Provider represents an external OAuth2 identity provider.
13type Provider interface {
14	// Name returns the machine-readable identifier, e.g. "github".
15	Name() string
16
17	// HumanName returns a user-facing display label, e.g. "GitHub".
18	HumanName() string
19
20	// AuthURL returns the URL the browser should be redirected to in order
21	// to begin the authorization-code flow.
22	AuthURL(state, callbackURL string) string
23
24	// Exchange converts an authorization code into a normalised UserInfo.
25	// The callbackURL must match the one used in AuthURL.
26	Exchange(ctx context.Context, code, callbackURL string) (*UserInfo, error)
27}
28
29// UserInfo holds the normalised user profile returned by a provider after a
30// successful OAuth2 exchange. Fields may be empty when the provider does not
31// supply them.
32type UserInfo struct {
33	Login     string
34	Email     string
35	Name      string
36	AvatarURL string
37}