providers

type AuthorizationURLOptions struct {
	// Prompt controls the authentication UX behavior.
	// Common values:
	//   - "none": Silent authentication - no UI displayed. Returns error if login/consent required.
	//   - "login": Force re-authentication even if session exists.
	//   - "consent": Force consent even if previously granted.
	//   - "select_account": Force account selection even if only one account.
	// Multiple values can be space-separated: "login consent"
	Prompt string

	// LoginHint pre-fills the email/username field at the IdP.
	// Useful for re-authentication when the user's identity is already known.
	// Example: "user@example.com"
	LoginHint string

	// MaxAge specifies the maximum authentication age in seconds.
	// If the user's session is older than this, re-authentication is required.
	// A value of 0 is equivalent to prompt=login.
	MaxAge *int

	// ACRValues requests specific authentication context class references.
	// Space-separated string of acr_values.
	// Example: "urn:mace:incommon:iap:silver"
	ACRValues string

	// IDTokenHint is a previously issued ID token passed as a hint about the user's session.
	// Used with prompt=none to identify the user for silent re-authentication.
	IDTokenHint string

	// Nonce is forwarded to the IdP and must be echoed back in the resulting
	// id_token's `nonce` claim.
	Nonce string

	// Extra allows setting additional custom parameters not covered above.
	// These are added as query parameters to the authorization URL.
	Extra map[string]string
}

type JWKSProvider interface {
	Provider

	// JWKSURI returns the JWKS (JSON Web Key Set) URI for this provider.
	// This is used to fetch public keys for JWT signature verification.
	// Returns empty string if JWKS is not available.
	JWKSURI(ctx context.Context) (string, error)

	// IssuerURL returns the issuer URL for this provider.
	// This is used for JWT issuer validation.
	IssuerURL() string
}

type OAuth2ConfigExchanger interface {
	Exchange(ctx context.Context, code string, opts ...oauth2.AuthCodeOption) (*oauth2.Token, error)
}

type Provider interface {
	// Name returns the provider name (e.g., "google", "github", "microsoft")
	Name() string

	// DefaultScopes returns the provider's default scopes used when the client doesn't
	// request specific scopes. These are the scopes configured when the provider was created.
	DefaultScopes() []string

	// AuthorizationURL generates the URL to redirect users for authentication
	// codeChallenge and codeChallengeMethod are for PKCE (pass empty strings to disable)
	// scopes is the list of scopes to request (if empty, provider's default scopes are used)
	// opts contains optional OIDC parameters like prompt, login_hint, max_age (nil for defaults)
	//
	// OAuth 2.1 Security: PKCE is recommended for ALL client types (public and confidential)
	// to protect against Authorization Code Injection attacks. Providers should support PKCE
	// even when using client_secret authentication for defense-in-depth.
	AuthorizationURL(state string, codeChallenge string, codeChallengeMethod string, scopes []string, opts *AuthorizationURLOptions) string

	// ExchangeCode exchanges an authorization code for tokens
	// codeVerifier is for PKCE verification (pass empty string if not using PKCE)
	// Returns standard oauth2.Token
	//
	// OAuth 2.1 Security: PKCE verification provides cryptographic binding between the
	// authorization request and token exchange, preventing code injection even for
	// confidential clients with client_secret.
	ExchangeCode(ctx context.Context, code string, codeVerifier string) (*oauth2.Token, error)

	// ValidateToken validates an access token and returns user information
	ValidateToken(ctx context.Context, accessToken string) (*UserInfo, error)

	// RefreshToken refreshes an expired token using a refresh token
	// Returns standard oauth2.Token
	RefreshToken(ctx context.Context, refreshToken string) (*oauth2.Token, error)

	// RevokeToken revokes a token at the provider
	RevokeToken(ctx context.Context, token string) error

	// HealthCheck verifies that the provider is reachable and functioning correctly.
	// This is useful for readiness/liveness probes and startup validation.
	// Returns nil if the provider is healthy, or an error describing the issue.
	//
	// SECURITY WARNING: Do not expose error messages from this method to untrusted clients.
	// Error details may contain information about provider state (HTTP status codes, network errors)
	// that could be used for reconnaissance. Use this for internal monitoring only.
	HealthCheck(ctx context.Context) error
}

type TokenSource string

type UserInfo struct {
	// ID is the unique user identifier from the provider
	ID string

	// Email is the user's email address
	Email string

	// EmailVerified indicates if the email is verified
	EmailVerified bool

	// Name is the user's full name
	Name string

	// GivenName is the user's first name
	GivenName string

	// FamilyName is the user's last name
	FamilyName string

	// Picture is the URL of the user's profile picture
	Picture string

	// Locale is the user's preferred locale
	Locale string

	// Groups contains group memberships from the identity provider.
	// This is populated from the 'groups' claim in OIDC userinfo responses.
	// Providers that don't support groups will leave this empty.
	Groups []string

	// TokenSource indicates how this user was authenticated.
	// This is set to TokenSourceOAuth for normal OAuth flow tokens
	// (where the ID token is stored in the token store) or TokenSourceSSO
	// for SSO-forwarded tokens (where the Bearer token IS the ID token).
	//
	// Downstream servers can use this to determine whether to look up
	// a stored ID token or use the Bearer token directly for downstream
	// authentication (e.g., Kubernetes API authentication).
	//
	// SECURITY: This field is set server-side during token validation and
	// should NOT be trusted if received from external sources (e.g., if
	// UserInfo is deserialized from untrusted input). Always use the server's
	// ValidateToken() method to obtain a trusted UserInfo with correct TokenSource.
	TokenSource TokenSource
}