auth

type DisplayNamer interface {
	DisplayName() string
}

type OAuthProvider interface {
	// Name returns the provider identifier (e.g., "slack").
	Name() string
	// AuthorizeURL builds the URL to redirect the user to for authorization.
	AuthorizeURL(state, redirectURI string) string
	// ExchangeCode exchanges an authorization code for user info.
	ExchangeCode(ctx context.Context, code, redirectURI string) (*OAuthUser, error)
}

type OAuthUser struct {
	ProviderID  string          // Provider-specific user ID
	Email       string          // User email
	DisplayName string          // User display name
	TeamID      string          // Optional workspace/org ID
	TeamName    string          // Optional workspace/org name
	AvatarURL   string          // Optional profile picture URL
	RawData     json.RawMessage // Full provider response
	// Groups is the directory group membership the provider asserted, read
	// out of a verified token. It is authorization input, so a provider must
	// only populate it from something the issuer signed.
	//
	// nil and empty mean the same thing to consumers — "this identity is in
	// none of the groups we asked about" — which, under a configured role
	// mapping, revokes the mapped roles. Whether a mapping is applied to a
	// given provider at all is decided by the caller, not by this field.
	Groups []string
	// GroupsOverage says the issuer refused to inline the group list and
	// handed us a pointer to it instead — Microsoft Entra ID does this past
	// roughly 200 memberships, dropping `groups` and substituting
	// `_claim_names` / `_claim_sources` aimed at a Microsoft Graph endpoint.
	//
	// It is the one case where an empty Groups must NOT be read as "in no
	// groups": membership is *unknown*, not empty. dbbat does not follow the
	// pointer, so a consumer that maps groups to authorization has to leave
	// what it cannot establish alone — otherwise the most heavily grouped
	// people in a tenant are exactly the ones a login silently demotes.
	GroupsOverage bool
}

type PKCEProvider interface {
	OAuthProvider
	// AuthorizeURLWithPKCE builds the authorization URL and returns the code
	// verifier whose S256 challenge it carries.
	AuthorizeURLWithPKCE(ctx context.Context, state, redirectURI string) (authorizeURL, verifier string, err error)
	// ExchangeCodeWithVerifier exchanges an authorization code, presenting
	// the verifier minted by AuthorizeURLWithPKCE.
	ExchangeCodeWithVerifier(ctx context.Context, code, redirectURI, verifier string) (*OAuthUser, error)
}