apiauth

type APIKeysHandler struct {
	// Store backs the keys. Required.
	Store core.APIKeyStore

	// GetSubjectScopes returns the scope set the caller may grant to
	// keys they create. Nil falls back to a permissive default of
	// {read, write, profile} — suitable for first-light deployments.
	GetSubjectScopes core.GetSubjectScopesFunc
}

type APIMiddleware struct {
	// JWT validation (uses same config as APIAuth)
	JWTSecretKey  string
	JWTIssuer     string
	JWTAudience   string
	JWTSigningAlg string

	// KeyStore for multi-tenant JWT validation. When set, the middleware uses
	// GetKeyByKid (for tokens with kid header) or GetKey (for client_id claim).
	// When nil, falls back to JWTSecretKey (single-tenant, backwards-compatible).
	KeyStore keys.KeyLookup

	// API key validation (optional)
	APIKeyStore core.APIKeyStore

	// Token header configuration
	AuthHeader string // Defaults to "Authorization"

	// LegacyQueryParamBearer is the query parameter name to check for a
	// bearer token when the Authorization header is missing (e.g., "token"
	// for ?token=...). Empty disables the path (default).
	//
	// OAuth 2.1 §5.4 retired query-param bearer carry; RFC 6750 §2.3 had
	// deprecated it in 2012. Query-carried tokens leak into browser
	// history, access logs, Referer headers, and caches. The path is
	// retained for OAuth 2.0 deployments that genuinely cannot move the
	// token to the Authorization header (the WebSocket upgrade case is
	// the typical one — see docs/DEMOS.md for the three alternatives).
	// Operators take responsibility for the leak surface; a one-time
	// warning logs at first use.
	//
	// Tracked under capability-gating umbrella #344.
	LegacyQueryParamBearer string

	// Error handling
	OnAuthError func(w http.ResponseWriter, r *http.Request, err error)

	// Blacklist enables immediate access token revocation. When set,
	// validateJWT checks the blacklist after signature verification.
	// If nil, no revocation check (stateless validation only).
	Blacklist core.TokenBlacklist

	// Introspection enables token validation via a remote introspection
	// endpoint (RFC 7662) as an alternative to local JWT/JWKS validation.
	// When set, tokens that fail local validation are sent to the
	// introspection endpoint. When local validation is not configured
	// (no JWTSecretKey, no KeyStore), introspection is the only validation path.
	// If nil, only local validation is used.
	Introspection *IntrospectionValidator

	// Validator is the transport-independent token validator (Phase 2).
	// When set, validateJWT delegates to it instead of using inline logic.
	// When nil, a validator is lazily built from the existing fields
	// (JWTSecretKey, KeyStore, Blacklist, etc.) on first use.
	Validator TokenValidator

	// TracerProvider opts the resource-server validation path into
	// SEP-414 tracing. When set, the lazily-built validator emits
	// `oneauth.signature_verify` spans, and the lookup-by-kid call
	// against KeyStore inherits the same trace context. Nil keeps
	// validation on the no-op fast path.
	TracerProvider trace.TracerProvider
	// contains filtered or unexported fields
}

type ASMetadataProxy struct {
	// contains filtered or unexported fields
}

type ASServerMetadata struct {
	// Required
	Issuer        string `json:"issuer"`
	TokenEndpoint string `json:"token_endpoint"`

	// Recommended
	JWKSURI string `json:"jwks_uri,omitempty"`

	// Optional endpoints
	AuthorizationEndpoint       string `json:"authorization_endpoint,omitempty"`
	IntrospectionEndpoint       string `json:"introspection_endpoint,omitempty"`
	RevocationEndpoint          string `json:"revocation_endpoint,omitempty"`
	RegistrationEndpoint        string `json:"registration_endpoint,omitempty"`
	UserinfoEndpoint            string `json:"userinfo_endpoint,omitempty"`
	DeviceAuthorizationEndpoint string `json:"device_authorization_endpoint,omitempty"` // RFC 8628 §4

	// Supported features
	AuthorizationDetailsTypesSupported []string `json:"authorization_details_types_supported,omitempty"` // RFC 9396
	ScopesSupported                    []string `json:"scopes_supported,omitempty"`

	// ClaimsSupported lists the claim names this AS may include in
	// issued tokens (and, once a userinfo endpoint exists, the userinfo
	// response). OIDC Discovery 1.0 §3 declares this RECOMMENDED; the
	// OpenID Foundation conformance suite emits a warning when the list
	// is absent. Advertise only claims the AS actually emits — listing
	// claims the AS does not produce misleads relying parties.
	//
	// See: OpenID Connect Discovery 1.0 §3
	ClaimsSupported []string `json:"claims_supported,omitempty"`

	ResponseTypesSupported   []string `json:"response_types_supported,omitempty"`
	GrantTypesSupported      []string `json:"grant_types_supported,omitempty"`
	TokenEndpointAuthMethods []string `json:"token_endpoint_auth_methods_supported,omitempty"`

	// TokenEndpointAuthSigningAlgValuesSupported lists the JWT alg
	// values the AS accepts on a private_key_jwt or client_secret_jwt
	// `client_assertion`. Per OIDC Discovery 1.0 §3 / RFC 8414 §2 this
	// list is REQUIRED whenever TokenEndpointAuthMethods includes
	// "private_key_jwt" or "client_secret_jwt"; "none" MUST NOT appear.
	// Typical values: "RS256", "ES256" (private_key_jwt); "HS256",
	// "HS384", "HS512" (client_secret_jwt).
	TokenEndpointAuthSigningAlgValuesSupported []string `json:"token_endpoint_auth_signing_alg_values_supported,omitempty"`

	CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported,omitempty"`
	SubjectTypesSupported         []string `json:"subject_types_supported,omitempty"`

	// AuthorizationResponseIssParameterSupported advertises RFC 9207
	// support — when true, the AS includes an `iss` query parameter on
	// every authorization response (both successful redirects with `code`
	// and error redirects). Pointer semantics distinguish absence (omit
	// from JSON) from explicit `false` (advertised as not supported).
	//
	// RFC 9207 §3:
	//   https://www.rfc-editor.org/rfc/rfc9207#section-3
	//
	// Setting this true on an AS that does NOT actually emit `iss` in
	// authorization responses is a spec violation — clients keying off
	// the advertisement will fail to validate.
	AuthorizationResponseIssParameterSupported *bool `json:"authorization_response_iss_parameter_supported,omitempty"`

	// BackchannelLogoutSupported advertises OIDC Back-Channel Logout 1.0 §3.1
	// — when true, the AS sends a signed logout_token to a client's registered
	// backchannel_logout_uri at session-revoke time. Pointer semantics: nil
	// omits the field; an explicit `false` advertises non-support to clients.
	// Set this true only when a BCLDispatcher is actually wired; otherwise
	// clients that key off the advertisement will silently miss logouts.
	BackchannelLogoutSupported *bool `json:"backchannel_logout_supported,omitempty"`

	// BackchannelLogoutSessionSupported advertises OIDC BCL 1.0 §3.1 — when
	// true, logout_tokens issued by this AS include a `sid` claim that the
	// receiver can use to revoke a single OIDC session rather than every
	// session for the subject. Pointer semantics match
	// BackchannelLogoutSupported.
	BackchannelLogoutSessionSupported *bool `json:"backchannel_logout_session_supported,omitempty"`

	// CacheMaxAge controls the Cache-Control max-age in seconds.
	// Defaults to 3600 (1 hour). Not serialized to JSON.
	CacheMaxAge int `json:"-"`
}

type AppRegistrationLookup interface {
	// GetAppRegistration returns the persisted registration for clientID, or
	// (nil, false) if no such client exists or its registration is being
	// torn down. Returning a clone is recommended so callers cannot mutate
	// store state through the returned pointer.
	GetAppRegistration(ctx context.Context, clientID string) (*core.AppRegistration, bool)
}

type AuthHooks struct {
	// OnLoginSuccess fires after a user successfully authenticates
	// (password grant, auth code exchange).
	OnLoginSuccess func(userID string)

	// OnLoginFailure fires after a failed authentication attempt.
	OnLoginFailure func(username string, err error)

	// OnScopeStepUp fires when additional scopes are requested and granted.
	// from is the original scope set, to is the expanded set.
	OnScopeStepUp func(subject string, from, to []string)
}

type AuthenticateClientRequest struct {
	// ClientID is the OAuth client identifier. For private_key_jwt this
	// may be empty; the authenticator extracts it from the assertion's
	// `iss` / `sub` claims.
	ClientID string

	// ClientSecret is the shared secret for client_secret_basic /
	// client_secret_post. Empty when authenticating via assertion.
	ClientSecret string

	// ClientAssertionType is the OAuth assertion type URN. For
	// private_key_jwt this MUST be
	// "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
	// (RFC 7521 §4.2). Empty when authenticating via secret.
	ClientAssertionType string

	// ClientAssertion is the signed JWT bearing the client's identity
	// (RFC 7523 §2.2 / OIDC Core §9). Validated against the client's
	// registered public key. Empty when authenticating via secret.
	ClientAssertion string

	// Audiences is the set of URLs the AS will accept as the assertion's
	// `aud` claim — typically the token endpoint URL AND the AS issuer
	// URL. Per OIDC Core §9 the audience SHOULD be the token endpoint
	// URL, but real-world clients (Auth0, Keycloak, Authlete) send one
	// or the other; accept both for interop. The assertion's `aud`
	// MUST match at least one entry. Required when ClientAssertion is
	// set.
	Audiences []string
}

type AuthenticateClientResponse struct {
	// ClientID is the authenticated client identifier. Equals the
	// request ClientID for the secret path; extracted from the
	// assertion `iss` / `sub` for the assertion path.
	ClientID string

	// Method names the auth method that succeeded — one of
	// "client_secret_basic", "client_secret_post", "private_key_jwt".
	// Transport bindings populate Method on the way in (basic vs post)
	// when they know which channel carried the secret; the assertion
	// path always sets it to "private_key_jwt".
	Method string
}

type AuthorizationCodeGrantRequest struct {
	Code         string
	CodeVerifier string
	RedirectURI  string
	ClientID     string

	// Client authentication credentials (only one channel populated
	// per RFC 7521 / OIDC Core §9):
	ClientSecret        string
	ClientAssertionType string
	ClientAssertion     string

	// AcceptedAudiences is the set of URLs the assertion's `aud` claim
	// MUST match (used for private_key_jwt / client_secret_jwt).
	// Empty falls back to the request URL.
	AcceptedAudiences []string
}

type AuthorizationCodeGrantResponse struct {
	Tokens *core.TokenPair
}

type AuthorizationCodeGranter interface {
	// AuthorizationCodeGrant trades an authorization code for an
	// access token (and optionally a refresh token).
	AuthorizationCodeGrant(ctx context.Context, req *AuthorizationCodeGrantRequest) (*AuthorizationCodeGrantResponse, error)
}

type AuthorizationHandler struct {
	// Store persists minted codes. Required.
	Store core.AuthorizationCodeStore

	// AppStore validates the (client_id, redirect_uri) tuple. When nil
	// the handler accepts any (client_id, redirect_uri) pair — suitable
	// for in-process tests, NOT for production. RedirectURIValidator
	// overrides this lookup when set.
	AppStore core.AppRegistrationStore

	// RedirectURIValidator, when non-nil, owns the (client_id,
	// redirect_uri) allowlist check. Overrides AppStore-based
	// validation. Use for deployments whose redirect_uri registry
	// lives outside AppStore. Return nil to accept; return an error to
	// reject (the error message goes to the user — keep it generic).
	RedirectURIValidator func(ctx context.Context, clientID, redirectURI string) error

	// IssuerURL is the AS's issuer identifier. When EmitIssParameter is
	// true the handler appends `iss=<IssuerURL>` to the redirect per
	// RFC 9207 §2. Required when EmitIssParameter is true; otherwise
	// optional.
	IssuerURL string

	// EmitIssParameter toggles RFC 9207 `iss` emission on the redirect.
	// Pair with ASServerMetadata.AuthorizationResponseIssParameterSupported
	// so the AS's advertisement matches the wire behavior.
	EmitIssParameter bool

	// RedirectOverride, when non-nil, is called with the redirect's
	// query values just before they are URL-encoded and the redirect
	// is sent. Lets conformance scenarios mutate / strip / corrupt
	// individual values (e.g. drop iss to test client behavior when
	// the AS advertises but does not emit). Production deployments
	// leave this nil.
	RedirectOverride func(values url.Values)

	// Expiry overrides DefaultAuthorizationCodeExpiry.
	Expiry time.Duration

	// AllowPlainPKCE permits `code_challenge_method=plain` per
	// RFC 7636 §4.4. OAuth 2.1 §7.5 retired plain; leaving this false
	// (default) keeps OneAuth's /authorize strict-2.1 — only S256 is
	// accepted, advertised, and verified at redemption. Operators
	// setting this true take on responsibility for the leak surface
	// the §7.5 retirement was meant to close: a plain `code_challenge`
	// IS the verifier, so any leaked authorization request equals a
	// leaked verifier. Set on OneAuthConfig.AllowPlainPKCE so the AS
	// metadata derivation and the redemption path can read the same
	// value.
	//
	// Per capability-gating umbrella #344.
	AllowPlainPKCE bool
	// contains filtered or unexported fields
}

type AuthorizationRequest struct {
	ClientID            string
	RedirectURI         string
	ResponseType        string
	Scope               string
	State               string
	CodeChallenge       string
	CodeChallengeMethod string
}

type AuthorizeMountConfig struct {
	// OneAuth is the source of AuthorizationCodeStore (required for
	// the authorize handler and the redemption path) and AppStore
	// (used by the consent screen to render client_name and by the
	// handler to validate redirect_uri allowlists). Required.
	OneAuth *OneAuth

	// IssuerURL is the AS's issuer identifier. Echoed on the redirect
	// as `iss` per RFC 9207 when EmitIssParameter is true. Required.
	IssuerURL string

	// EmitIssParameter toggles RFC 9207 `iss` emission on the
	// authorization-response redirect. Pair with
	// ASServerMetadata.AuthorizationResponseIssParameterSupported so
	// the AS's advertisement matches the wire behavior.
	EmitIssParameter bool

	// RedirectURIValidator, when non-nil, overrides AppStore-based
	// (client_id, redirect_uri) validation. See
	// AuthorizationHandler.RedirectURIValidator for details.
	RedirectURIValidator func(ctx context.Context, clientID, redirectURI string) error

	// RedirectOverride, when non-nil, lets conformance scenarios
	// mutate / strip / corrupt the redirect query values before
	// they are encoded. Production deployments leave this nil. See
	// AuthorizationHandler.RedirectOverride.
	RedirectOverride func(values url.Values)

	// Expiry overrides DefaultAuthorizationCodeExpiry. Zero keeps the
	// default.
	Expiry time.Duration

	// SubjectFromRequest returns the authenticated subject ("" if the
	// user is unauthenticated). Wire `httpauth.Middleware.GetLoggedInSubject`
	// or a cookie-reading equivalent. Required.
	SubjectFromRequest func(r *http.Request) string

	// CSRFTokenFromRequest returns the per-request CSRF token to
	// embed in the rendered HTML form. Wire `httpauth.CSRFToken`.
	// Required.
	CSRFTokenFromRequest func(r *http.Request) string

	// LoginRedirectURL is where Consent / Decide redirect
	// unauthenticated users. Empty defaults to "/auth/login".
	LoginRedirectURL string

	// LoginNextParam names the query parameter used to round-trip the
	// post-login return URL. Empty defaults to "next".
	LoginNextParam string

	// Templates overrides the built-in HTML pages. Nil uses the
	// package defaults — fine for first-light deployments and tests.
	Templates *AuthorizeTemplates

	// AutoApproveSubject short-circuits the consent screen for
	// conformance fixtures. Empty disables auto-approve. NEVER set
	// in production deployments.
	AutoApproveSubject string

	// BrowserMiddleware, when non-nil, wraps both /authorize routes.
	// Production wires `httpauth.CSRFMiddleware.Protect` here so POST
	// submissions are CSRF-protected; tests pass nil because they
	// drive the routes directly. The GET path is wrapped too so the
	// CSRF cookie is set on first render.
	BrowserMiddleware func(http.Handler) http.Handler
}

type AuthorizeTemplates struct {
	// Consent renders GET /authorize. Data: authorizeConsentData.
	Consent *template.Template

	// Error renders the §4.1.2.1 "MUST NOT redirect" error page (bad
	// client_id / redirect_uri). Data: authorizeErrorData.
	Error *template.Template
}

type AuthorizeVerificationHandler struct {
	// Authorization is the parse + validate + IssueCode + redirect
	// engine. Required.
	Authorization *AuthorizationHandler

	// AppStore resolves the client_id to its registered metadata so
	// the consent screen can render the human-readable client_name.
	// Nil renders the raw client_id; never a hard failure. When
	// AuthorizationHandler.AppStore is set this is typically the same
	// store.
	AppStore core.AppRegistrationStore

	// SubjectFromRequest returns the authenticated subject ("" if the
	// user is unauthenticated). Wire `httpauth.Middleware.GetLoggedInSubject`.
	// Required.
	SubjectFromRequest func(r *http.Request) string

	// CSRFTokenFromRequest returns the per-request CSRF token to
	// embed in the rendered form. Wire `httpauth.CSRFToken`. Required.
	CSRFTokenFromRequest func(r *http.Request) string

	// LoginRedirectURL is the URL Consent / Decide redirects
	// unauthenticated users to. The handler appends `?next=<this URL>`
	// so the user returns to the consent screen after logging in.
	// Empty defaults to `/auth/login`.
	LoginRedirectURL string

	// LoginNextParam is the query parameter name used to round-trip
	// the post-login return URL. Empty defaults to `next`.
	LoginNextParam string

	// Templates overrides the built-in HTML pages. Set any subset of
	// fields; nil fields fall back to the package defaults.
	Templates *AuthorizeTemplates

	// AutoApproveSubject, when non-empty, short-circuits the consent
	// screen and approves any well-formed request with this subject.
	// Intended for conformance fixtures and in-process tests — never
	// set this in production deployments. Pairs with
	// testutil.WithAuthorizeAutoApproveSubject.
	AutoApproveSubject string
}

type BCLDispatcher struct {
	// Issuer mints the signed logout_token. Required.
	Issuer LogoutTokenIssuer

	// Apps resolves a client_id to its registration so we can read
	// backchannel_logout_uri and backchannel_logout_session_required.
	// Required.
	Apps AppRegistrationLookup

	// RefreshStore enumerates a subject's active grants. Required for
	// subject-scoped Dispatch calls; ignored for explicit-client calls.
	RefreshStore core.RefreshTokenStore

	// HTTPClient is used for outbound POSTs. Defaults to an http.Client with
	// a 5-second per-request timeout so a stuck receiver cannot pin a
	// goroutine indefinitely.
	HTTPClient *http.Client

	// Logger receives non-fatal dispatch errors (4xx/5xx from receiver,
	// network failures, signing errors). If nil, log.Default() is used.
	Logger *log.Logger

	// SyncForTest makes Dispatch block until every POST completes. Tests use
	// this to assert the receiver was hit before they read its captured
	// state; production callers should leave it false so revocation latency
	// is not coupled to receiver responsiveness.
	SyncForTest bool

	// AllowPrivateHosts opts in to dialing receiver URIs whose resolved IP
	// is loopback / RFC1918 / link-local / unspecified / multicast. Off by
	// default — the default HTTPClient's dialer rejects such connections so
	// a (mis-configured or malicious) `backchannel_logout_uri` cannot be
	// used to make the AS POST to internal services on its behalf, even if
	// the hostname's DNS answer at dial time differs from registration time
	// (rebinding). Closed-network deployments (AS + RS in the same VPC) can
	// flip this on; admin.AppRegistrar.AllowPrivateBCLHosts is the matching
	// registration-side knob.
	AllowPrivateHosts bool
	// contains filtered or unexported fields
}

type CheckAuthorizationDetailsRequest struct {
	Token         string
	RequiredTypes []string
}

type CheckAuthorizationDetailsResponse struct{}

type CheckScopesRequest struct {
	Token          string
	RequiredScopes []string
}

type CheckScopesResponse struct{}

type ClientAuthenticator interface {
	// AuthenticateClient verifies the supplied credentials. Returns the
	// authenticated client_id and the auth method used on success.
	AuthenticateClient(ctx context.Context, req *AuthenticateClientRequest) (*AuthenticateClientResponse, error)
}

type ClientCredentialsRequest struct {
	ClientID             string
	ClientSecret         string
	Scopes               []string
	AuthorizationDetails []core.AuthorizationDetail
}

type ClientCredentialsResponse struct {
	Tokens *core.TokenPair
}

type ClientHooks struct {
	// OnRegistered fires after a new client is registered (DCR or proprietary).
	// method is "dcr" or "register".
	OnRegistered func(clientID, method string)

	// OnDeleted fires after a client is deleted.
	OnDeleted func(clientID string)

	// OnKeyRotated fires after a client's signing key is rotated.
	OnKeyRotated func(clientID string)
}

type CreateAccessTokenRequest struct {
	Subject              string
	Scopes               []string
	AuthorizationDetails []core.AuthorizationDetail

	// ClientID, when non-empty, is emitted as a `client_id` claim on the
	// access token. Used by the jwt-bearer grant to bind an access token
	// issued from an ID-JAG to the client_id the ID-JAG names, per the
	// MCP EMA flow. Empty leaves the claim off.
	ClientID string
}

type CreateAccessTokenResponse struct {
	Token     string
	ExpiresIn int64
}

type CreateIDJAGRequest struct {
	// Subject is the user identifier (RFC 7519 `sub`), taken from the
	// validated stage-1 subject_token. Required.
	Subject string

	// Audience is the ID-JAG `aud` claim — the issuer identifier of the
	// resource app's authorization server that will redeem this ID-JAG.
	// Bound from the exchange request `audience` param (RFC 8693 §2.1),
	// which is why the issuer does NOT pin an audience at construction.
	// Required: an ID-JAG with no target AS is not redeemable.
	Audience string

	// ClientID is the MCP client identifier the redeeming AS knows the
	// client by (`client_id` claim). Carried so the stage-2 redeemer can
	// bind the issued access token to the client per the draft §5
	// CIMD/DCR constraint. Optional.
	ClientID string

	// Scopes, when non-empty, is emitted as a space-delimited `scope`
	// claim so the redeeming AS can scope the eventual access token.
	Scopes []string

	// Resource is the RFC 8707 resource indicator (the MCP server URL).
	// Carried as a `resource` claim so the redeeming AS can bind the
	// eventual access token to the right MCP server. Optional.
	Resource string

	// AuthorizationDetails carries RFC 9396 detail objects through the
	// exchange when present. Optional.
	AuthorizationDetails []core.AuthorizationDetail
}

type CreateIDJAGResponse struct {
	// Token is the serialized `oauth-id-jag+jwt`. It becomes the
	// `access_token` field of the RFC 8693 exchange response (that is the
	// field RFC 8693 §2.2 uses to carry the issued token regardless of
	// its type).
	Token string

	// ExpiresIn is the ID-JAG lifetime in seconds.
	ExpiresIn int64
}

type CreateLogoutTokenRequest struct {
	// Audience is the receiving client's client_id. Per §2.4 this becomes the
	// `aud` claim and identifies which client the logout applies to. Required.
	Audience string

	// Subject is the user identifier (RFC 7519 `sub`) whose session ended.
	// Optional iff SID is set; required otherwise.
	Subject string

	// SID is the session identifier (`sid`). When the receiving client
	// registered with backchannel_logout_session_required=true the AS MUST
	// include this; otherwise SHOULD include when known. oneauth maps SID to
	// the refresh-token family ID — the closest analogue to an OIDC session
	// the library tracks today.
	SID string
}

type CreateLogoutTokenResponse struct {
	// Token is the serialized JWS. It is ready to POST as the value of the
	// `logout_token` form field per §2.5.
	Token string
}

type CredentialsValidator = accounts.CredentialsValidator

type CustomClaimsFunc func(subject string, scopes []string) (map[string]any, error)

type DeviceAuthorizationHandler struct {
	// Store persists the device authorization. Required.
	Store core.DeviceAuthorizationStore

	// VerificationURI is the absolute URL the device displays to the
	// user. RFC 8628 §3.2 makes this REQUIRED on the response. Production
	// deployments point it at the AS's HTML user-code form (a follow-up
	// PR ships this UI); tests can point it anywhere — the field is
	// echoed verbatim.
	VerificationURI string

	// VerificationURICompleteTemplate, when non-empty, is appended with
	// the user_code substituted into "%s" to produce the
	// verification_uri_complete field (RFC 8628 §3.3.1). The convenience
	// URL lets the device generate a QR code that pre-fills the form.
	// Example: "https://auth.example.com/device?user_code=%s".
	VerificationURICompleteTemplate string

	// Expiry overrides the default 15-minute authorization window.
	Expiry time.Duration

	// Interval overrides the default 5-second polling interval.
	Interval int

	// ClientAuthenticator, when non-nil, authenticates the calling client
	// before minting codes. When nil the handler accepts any client_id —
	// suitable for public-client-only deployments and tests, NOT for
	// production with confidential clients.
	ClientAuthenticator ClientAuthenticator
}

type DeviceCodeGrantRequest struct {
	DeviceCode string
	ClientID   string

	// Client authentication credentials (confidential clients only).
	ClientSecret        string
	ClientAssertionType string
	ClientAssertion     string

	AcceptedAudiences []string
}

type DeviceCodeGrantResponse struct {
	Tokens *core.TokenPair
}

type DeviceCodeGranter interface {
	// DeviceCodeGrant trades a device_code (after the user has
	// approved on the verification URI) for an access token.
	DeviceCodeGrant(ctx context.Context, req *DeviceCodeGrantRequest) (*DeviceCodeGrantResponse, error)
}

type DeviceFlowMountConfig struct {
	// OneAuth is the source of DeviceAuthStore (required for the
	// device-grant handler and the verification UI) and AppStore
	// (used by the consent screen to render client_name and by the
	// device-code redemption handler to enforce RFC 8628 §3.4
	// confidential-client authentication, issue 266). The Approve /
	// Deny helpers wire directly to the DeviceAuthStore.
	OneAuth *OneAuth

	// VerificationURI is the absolute URL the device displays to the
	// user — RFC 8628 §3.2 makes it REQUIRED on the /device/authorize
	// response. Production: <public-base-url>/device. Tests: the
	// httptest.Server URL + /device. The value is echoed verbatim to
	// the device. Required.
	VerificationURI string

	// VerificationURICompleteTemplate, when set, generates the optional
	// RFC 8628 §3.3.1 verification_uri_complete field. The user_code is
	// substituted into "%s". Example: "https://auth.example/device?user_code=%s".
	// Empty omits the field; the device falls back to verification_uri
	// and prompts the user to type the code.
	VerificationURICompleteTemplate string

	// Expiry overrides the RFC 8628 §3.4 recommended 15-minute window.
	// Zero keeps the default.
	Expiry time.Duration

	// Interval overrides the RFC 8628 §3.5 default 5-second polling
	// interval. Zero keeps the default.
	Interval int

	// ClientAuthenticator authenticates clients at POST /device/authorize.
	// Nil accepts any client_id (test-suitable). For deployments that
	// register confidential clients, wire APIAuth's ClientAuthenticator
	// here so the device-authorize call rejects unauthenticated
	// confidential clients before a code is even minted. Confidential-
	// client enforcement on the REDEMPTION path (POST /api/token) is
	// independent and driven by APIAuth.AppStore (issue 266).
	ClientAuthenticator ClientAuthenticator

	// SubjectFromRequest returns the authenticated subject ("" if the
	// user is unauthenticated). The verification UI uses this to decide
	// whether to redirect to login before showing the consent screen.
	// Wire `httpauth.Middleware.GetLoggedInSubject` or a cookie-reading
	// equivalent. Required.
	SubjectFromRequest func(r *http.Request) string

	// CSRFTokenFromRequest returns the per-request CSRF token to embed
	// in the rendered HTML forms (code-entry and consent). Wire
	// `httpauth.CSRFToken`. Required — the consent forms are rendered
	// with a hidden csrf_token input even when CSRF middleware is off
	// at the route level.
	CSRFTokenFromRequest func(r *http.Request) string

	// LoginRedirectURL is where Submit redirects unauthenticated users.
	// Empty defaults to "/auth/login" (the convention used elsewhere
	// in the library).
	LoginRedirectURL string

	// LoginNextParam names the query parameter used to round-trip the
	// post-login return URL. Empty defaults to "next".
	LoginNextParam string

	// Templates overrides the built-in HTML pages (form / consent /
	// done). Nil uses the package defaults — fine for first-light
	// deployments and tests.
	Templates *DeviceTemplates

	// VerifierMiddleware, when non-nil, wraps each of the four
	// /device and /device/approve routes. Production wires
	// `httpauth.CSRFMiddleware.Protect` here so POST submissions are
	// CSRF-protected; tests pass nil because they drive the routes
	// directly and skip CSRF validation. The /device/authorize route
	// is NOT wrapped — it is a machine-to-machine endpoint called by
	// the device, not a browser form, and CSRF does not apply.
	VerifierMiddleware func(http.Handler) http.Handler
}

type DeviceTemplates struct {
	// Form renders the GET /device code entry page. Data: deviceFormData.
	Form *template.Template

	// Consent renders the GET /device/approve consent screen. Data:
	// deviceConsentData.
	Consent *template.Template

	// Done renders the post-decision "return to your device" page.
	// Data: deviceDoneData.
	Done *template.Template
}

type DeviceVerificationHandler struct {
	// Store enumerates pending device authorizations by user_code.
	// Required.
	Store core.DeviceAuthorizationStore

	// AppStore resolves the client_id bound to a device authorization
	// to its registered metadata so the consent screen can render the
	// human-readable client_name and scope list. Nil renders the raw
	// client_id; never a hard failure.
	AppStore core.AppRegistrationStore

	// Approve transitions a pending authorization to approved and binds
	// the subject. Wire `APIAuth.ApproveDeviceAuthorization` here.
	Approve func(r *http.Request, userCode, subject string, scopes []string) error

	// Deny transitions a pending authorization to denied. Wire
	// `APIAuth.DenyDeviceAuthorization` here.
	Deny func(r *http.Request, userCode string) error

	// SubjectFromRequest returns the authenticated subject ("" if the
	// user is unauthenticated). Wire `httpauth.Middleware.GetLoggedInSubject`.
	SubjectFromRequest func(r *http.Request) string

	// CSRFTokenFromRequest returns the per-request CSRF token to embed
	// in the rendered form. Wire `httpauth.CSRFToken`.
	CSRFTokenFromRequest func(r *http.Request) string

	// LoginRedirectURL is the URL Submit redirects unauthenticated users
	// to. The handler appends a `?next=<consent_url>` query so the user
	// returns to the consent screen after logging in. Empty defaults to
	// `/auth/login`, the convention used elsewhere in the library.
	LoginRedirectURL string

	// LoginNextParam is the query parameter name used to round-trip the
	// post-login return URL. Empty defaults to `next`.
	LoginNextParam string

	// Templates overrides the built-in HTML templates. Set any subset of
	// fields; nil fields fall back to the package defaults.
	Templates *DeviceTemplates
}

type DispatchRequest struct {
	// Subject is the user identifier whose session ended.
	Subject string

	// SID is the OIDC session ID. oneauth maps this to the refresh-token
	// family ID; pass empty when no family-scoped revoke happened.
	SID string

	// ClientIDs names clients to notify directly. Useful when the trigger is
	// a single-token revoke and the AS already knows the client_id from the
	// token claims.
	ClientIDs []string
}

type DispatchResponse struct{}

type GrantError struct {
	Code        string
	Description string
	Status      int
}

type Hooks struct {
	Token    TokenHooks
	Auth     AuthHooks
	Client   ClientHooks
	Security SecurityHooks
}

type IDJAGIssuer interface {
	// CreateIDJAG mints a signed `oauth-id-jag+jwt` for the validated
	// subject, bound to the target AS (`aud`) supplied by the caller.
	CreateIDJAG(ctx context.Context, req *CreateIDJAGRequest) (*CreateIDJAGResponse, error)
}

type IDJAGIssuerConfig struct {
	// SigningKey is the IdP signing key. For HS256 pass []byte; for
	// RS256/ES256 pass the private key.
	SigningKey any

	// SigningAlg names the JWS algorithm (e.g. "RS256"). Empty falls back
	// to HS256 when SigningKey is a []byte.
	SigningAlg string

	// Issuer is the IdP issuer URL — the ID-JAG `iss` claim, and the key
	// under which the redeeming AS looks up the IdP JWKS.
	Issuer string

	// TTL bounds the ID-JAG lifetime. An ID-JAG is single-use and redeemed
	// immediately, so this stays short — long enough for two network hops
	// plus clock skew, short enough that a leaked (unredeemed) ID-JAG is
	// useless quickly. Defaults to 2 minutes when unset.
	TTL time.Duration
}

type IntrospectRequest struct {
	Token string
}

type IntrospectResponse struct {
	Result *IntrospectionResult
}

type IntrospectionHandler struct {
	// Introspector performs the actual token introspection (transport-independent).
	Introspector TokenIntrospector

	// Authenticator verifies the caller's client credentials.
	Authenticator ClientAuthenticator

	// AcceptedAudiences are the URLs the AS will accept as the
	// `aud` claim of a private_key_jwt / client_secret_jwt client
	// assertion (OIDC Core §9). Typically the introspection endpoint
	// URL plus the AS issuer URL. When empty the URL of the request
	// is used as a fallback, which works for single-host deployments
	// but breaks behind proxies that rewrite the path — populate
	// explicitly in production.
	AcceptedAudiences []string

	// TracerProvider opts the introspection endpoint into SEP-414
	// tracing. When set, ServeHTTP extracts an inbound `traceparent`
	// header and emits an `oneauth.introspect` span carrying the
	// resulting `token_active` boolean. Nil keeps tracing on the
	// no-op fast path.
	TracerProvider trace.TracerProvider
}

type IntrospectionResult struct {
	Active    bool   `json:"active"`
	Sub       string `json:"sub,omitempty"`
	Scope     string `json:"scope,omitempty"`
	ClientID  string `json:"client_id,omitempty"`
	TokenType string `json:"token_type,omitempty"`
	Exp       int64  `json:"exp,omitempty"`
	Iat       int64  `json:"iat,omitempty"`
	Iss       string `json:"iss,omitempty"`
	Jti       string `json:"jti,omitempty"`
	Aud       any    `json:"aud,omitempty"`
}

type IntrospectionValidator struct {
	// IntrospectionURL is the auth server's introspection endpoint.
	// Required.
	IntrospectionURL string

	// ClientID and ClientSecret authenticate this resource server to the
	// introspection endpoint via HTTP Basic auth (client_secret_basic).
	// Required.
	ClientID     string
	ClientSecret string

	// HTTPClient is used for introspection requests. If nil, uses
	// http.DefaultClient.
	HTTPClient *http.Client

	// CacheTTL enables response caching. If > 0, introspection responses
	// are cached for this duration. A revoked token may remain "active"
	// in the cache for up to CacheTTL after revocation.
	// Default: 0 (no caching).
	CacheTTL time.Duration

	// TracerProvider opts the introspection client into SEP-414
	// tracing. When set, ValidateWithContext emits an
	// `oneauth.introspection_client.request` span around the outbound
	// HTTP call AND injects a W3C `traceparent` header so the
	// upstream introspection endpoint can stitch its `oneauth.introspect`
	// span into the same trace. Nil keeps the path on the no-op fast
	// path with no allocation cost.
	TracerProvider trace.TracerProvider
	// contains filtered or unexported fields
}

type JTIStore interface {
	// SeenWithin reports whether `jti` was already marked seen within
	// the given lifetime. When false is returned the implementation
	// MUST also record `jti` as seen for at least `lifetime`. Single
	// call, atomic check-and-set — callers do not invoke a separate
	// Mark method.
	SeenWithin(jti string, lifetime time.Duration) bool
}

type JWTIssuerConfig struct {
	SigningKey any
	SigningAlg string
	Issuer     string
	Audience   string
	// AudienceFunc, when non-nil, is consulted on each access-token
	// mint. A non-empty return takes precedence over Audience. See
	// OneAuthConfig.AudienceFunc for the canonical use case.
	AudienceFunc        func() string
	AccessExpiry        time.Duration
	ClientKeyLookup     keys.KeyLookup            // for client_credentials authentication
	RefreshStore        core.RefreshTokenStore    // for refresh_token grant
	ValidateCredentials CredentialsValidator      // for password grant
	GetSubjectScopes    core.GetSubjectScopesFunc // for password grant (optional)
	CustomClaims        CustomClaimsFunc          // optional per-token custom-claim injection
	Hooks               TokenHooks
}

type JWTLogoutTokenIssuerConfig struct {
	// SigningKey is the AS signing key. For HS256 pass []byte; for RS256/ES256
	// pass the private key.
	SigningKey any

	// SigningAlg names the JWS algorithm (e.g. "RS256"). Empty falls back to
	// HS256 when SigningKey is a []byte.
	SigningAlg string

	// Issuer is the AS issuer URL — the value the receiver expects as the
	// `iss` claim and the key under which it looked up the AS JWKS.
	Issuer string

	// TokenTTL bounds the validity window for replay protection. The OIDC BCL
	// spec does not require `exp` but receivers are encouraged to reject
	// stale tokens; we default to 2 minutes — long enough for slow networks,
	// short enough that a leaked token isn't useful for long.
	TokenTTL time.Duration
}

type JWTValidatorConfig struct {
	KeyLookup keys.KeyLookup
	// SigningKey is an optional fallback used when KeyLookup is nil or the
	// token's kid / client_id does not resolve through it. For HS256, supply
	// []byte; for RS256/ES256, supply the verification key (*rsa.PublicKey,
	// *ecdsa.PublicKey) directly.
	SigningKey any
	SigningAlg string
	Blacklist  core.TokenBlacklist
	Issuer     string
	Audience   string
	// AudienceFunc, when non-nil, is consulted on every ValidateToken
	// call. A non-empty return takes precedence over Audience. See
	// OneAuthConfig.AudienceFunc for the canonical use case.
	AudienceFunc func() string
	Hooks        SecurityHooks

	// TracerProvider opts the signature-verify hot path into SEP-414
	// tracing. When set, ValidateToken emits an `oneauth.signature_verify`
	// span (attributes: `jwt.alg`, `jwt.kid`). Nil keeps the path on the
	// no-op fast path. Typically populated from APIAuth.TracerProvider
	// so spans nest under `oneauth.token.issue` (issuer) or under the
	// caller's span (resource server).
	TracerProvider trace.TracerProvider
}

type JwtBearerGrantRequest struct {
	Assertion            string
	Scopes               []string
	AuthorizationDetails []core.AuthorizationDetail

	// Client-authentication material. RFC 7523 §3 makes client auth
	// OPTIONAL for this grant (the assertion is itself the credential),
	// so these may be empty for public clients. When present and the
	// client is a registered confidential client, the granter
	// authenticates it; on the ID-JAG redemption path the authenticated
	// client_id is additionally bound to the ID-JAG's client_id claim.
	ClientID            string
	ClientSecret        string
	ClientAssertionType string
	ClientAssertion     string
	// AcceptedAudiences bounds the `aud` a private_key_jwt /
	// client_secret_jwt client assertion may carry (OIDC Core §9). The
	// token endpoint fills it from its configured audience list.
	AcceptedAudiences []string
}

type JwtBearerGrantResponse struct {
	Tokens *core.TokenPair
}

type JwtBearerGranter interface {
	// JwtBearerGrant validates the assertion against the configured
	// TrustedAssertionIssuers and issues an access token.
	JwtBearerGrant(ctx context.Context, req *JwtBearerGrantRequest) (*JwtBearerGrantResponse, error)
}

type JwtBearerGranterConfig struct {
	// TrustedIssuers lists upstream IdPs whose assertions the grant
	// accepts. MUST be non-empty for the grant to do anything.
	TrustedIssuers []TrustedAssertionIssuer

	// DefaultAudience / DefaultIssuer supply the RFC 7523 §3 audience
	// fallback when a TrustedAssertionIssuer entry doesn't pin one. For
	// ID-JAG redemption these identify this AS so the ID-JAG `aud`
	// (= the resource AS the client redeems at) is checked against it.
	DefaultAudience string
	DefaultIssuer   string

	// Issuer mints the access token. Required.
	Issuer TokenIssuer

	// ReplayStore enforces single-use on redeemed ID-JAG assertions. Nil
	// defaults to an in-process in-memory store — swap in a distributed
	// implementation for multi-node deployments. Plain (non-ID-JAG)
	// jwt-bearer assertions are not replay-checked; the assertion is the
	// renewable credential per RFC 7523.
	ReplayStore JTIStore

	// AppStore + Authenticator enable confidential-client authentication
	// (issue 356). When wired, a request whose client_id names a
	// registered confidential client is authenticated before issuance;
	// public / unregistered clients keep the RFC 7523 §3 assertion-only
	// path. Both nil (default) preserves the pre-356 behavior of never
	// authenticating the client on this grant.
	AppStore      core.AppRegistrationStore
	Authenticator ClientAuthenticator
}

type LogoutTokenIssuer interface {
	// CreateLogoutToken mints a signed logout_token. The returned response
	// carries the serialized JWT only; the dispatcher is responsible for
	// transporting it.
	CreateLogoutToken(ctx context.Context, req *CreateLogoutTokenRequest) (*CreateLogoutTokenResponse, error)
}

type OneAuth struct {
	// Core operation interfaces — each has minimal dependencies.
	Issuer        TokenIssuer
	Validator     TokenValidator
	Introspector  TokenIntrospector
	Revoker       TokenRevoker
	Authenticator ClientAuthenticator

	// Per-grant interfaces. Nil when the corresponding store / config
	// is not wired — the TokenEndpointHandler returns
	// unsupported_grant_type for any grant whose Granter is nil.
	AuthorizationCodeGranter AuthorizationCodeGranter
	DeviceCodeGranter        DeviceCodeGranter
	JwtBearerGranter         JwtBearerGranter
	TokenExchanger           TokenExchanger
	PasswordGranter          PasswordGranter

	// Shared state — available for transport bindings that need direct access.
	KeyStore     keys.KeyStorage
	Blacklist    core.TokenBlacklist
	RefreshStore core.RefreshTokenStore

	// Stores backing the new grant flows. Exposed on OneAuth so
	// transport bindings (DeviceVerificationHandler, the consent
	// screens) can write to them — the granter implementations only
	// read.
	AuthorizationCodeStore core.AuthorizationCodeStore
	DeviceAuthStore        core.DeviceAuthorizationStore
	AppStore               core.AppRegistrationStore

	// AllowPlainPKCE mirrors OneAuthConfig.AllowPlainPKCE. Exposed so
	// transport bindings (MountAuthorize, AS metadata derivation) can
	// read the AS-wide policy without re-plumbing the flag through
	// every config call site.
	AllowPlainPKCE bool

	// AcceptedAudiences is the set of URLs the token endpoint will
	// accept as the `aud` claim of a private_key_jwt / client_secret_jwt
	// client assertion (OIDC Core §9). Echoed into the granters so they
	// can validate confidential-client assertions.
	AcceptedAudiences []string

	// Hooks — lifecycle callbacks grouped by concern.
	Hooks Hooks
}

type OneAuthConfig struct {
	// Key management
	KeyStore keys.KeyStorage // required — stores client keys

	// Signing configuration
	SigningKey any    // []byte for HS256, *rsa.PrivateKey for RS256, etc.
	SigningAlg string // "HS256", "RS256", "ES256" — default "HS256"

	// VerifyKey is the public key for asymmetric token validation.
	// When SigningKey is a private key (RS256 / ES256), VerifyKey is
	// the matching public key handed to the validator. When SigningKey
	// is a []byte HS256 secret, VerifyKey is ignored. Nil + asymmetric
	// SigningKey causes the validator to fall back to KeyStore-based
	// key lookup.
	VerifyKey any

	// JWT configuration
	Issuer       string        // JWT iss claim
	Audience     string        // JWT aud claim (optional)
	AccessExpiry time.Duration // default 15 minutes

	// AudienceFunc, when non-nil, is consulted per token mint and per
	// validation in addition to Audience. The returned string takes
	// precedence over Audience whenever it is non-empty; an empty
	// return falls back to Audience.
	//
	// Use this when the audience cannot be known at construction
	// time. The canonical case is an in-process AS that needs to mint
	// tokens whose aud equals a resource server URL that is itself
	// only allocated later (e.g., by `httptest.NewServer` on the RS
	// side). Build the AS once, then teach the closure to look up
	// the current value when the RS comes online.
	//
	// Production deployments where the audience is a stable
	// configuration value should leave AudienceFunc nil and set
	// Audience directly. Lazy resolution adds one function call per
	// mint / validation — small but not free.
	//
	// Concurrency: AudienceFunc is invoked from the request-serving
	// goroutine. Callers backing it with mutable state must guard
	// the state themselves.
	AudienceFunc func() string

	// Token lifecycle
	Blacklist    core.TokenBlacklist    // for access token revocation (optional)
	RefreshStore core.RefreshTokenStore // for refresh token management (optional)

	// Password grant callbacks (optional — only needed if password grant is used)
	ValidateCredentials CredentialsValidator      // validates username/password
	GetSubjectScopes    core.GetSubjectScopesFunc // returns allowed scopes for the subject (user ID or client_id)

	// CustomClaims is called during access-token issuance to inject additional
	// non-standard claims into the JWT. Standard JWT claims (sub, iss, aud,
	// exp, iat, type, scopes, jti, authorization_details) cannot be overridden.
	CustomClaims CustomClaimsFunc

	// Authenticator overrides the default KeyStore-backed
	// ClientAuthenticator. Nil keeps the default behavior
	// (KeyStore-based secret + private_key_jwt assertion validation).
	Authenticator ClientAuthenticator

	// AcceptedAudiences is the set of URLs the token endpoint will
	// accept as the `aud` claim of a private_key_jwt / client_secret_jwt
	// client assertion. Typically the token endpoint URL plus the AS
	// issuer URL. Empty falls back to the request URL.
	AcceptedAudiences []string

	// PasswordGranter, when non-nil, opts the AS into OAuth 2.0 RFC 6749
	// §4.3 Resource Owner Password Credentials grant. OAuth 2.1 §7.6
	// retired ROPC (clients see the user's primary credentials; defeats
	// federation, blocks MFA and step-up auth); leaving this nil is
	// strict-2.1 compliance — the token endpoint returns
	// `unsupported_grant_type` for grant_type=password. Wire
	// apiauth.NewPasswordGranter to opt in for legacy OAuth 2.0 fleets
	// that must keep ROPC. Per capability-gating umbrella #344.
	//
	// AS metadata `grant_types_supported` must include "password" only
	// when this slot is wired; the caller wires the advertised list
	// when building ASServerMetadata.
	PasswordGranter PasswordGranter

	// Authorization code grant (RFC 6749 §4.1). When AuthorizationCodeStore
	// is non-nil the token endpoint accepts grant_type=authorization_code.
	AuthorizationCodeStore core.AuthorizationCodeStore

	// AllowPlainPKCE permits `code_challenge_method=plain` per RFC 7636
	// §4.4 on the /authorize endpoint. OAuth 2.1 §7.5 retired plain;
	// leaving this false (default) keeps OneAuth strict-2.1. Set true to
	// support OAuth 2.0 fleets that have legacy clients unable to
	// compute SHA-256. AS metadata derivation should reflect the flag
	// (`code_challenge_methods_supported` = ["S256"] when false,
	// ["S256", "plain"] when true) — callers wire this when building
	// the ASServerMetadata struct.
	//
	// Per capability-gating umbrella #344.
	AllowPlainPKCE bool

	// Device authorization grant (RFC 8628). When DeviceAuthStore is
	// non-nil the token endpoint accepts grant_type=...:device_code.
	DeviceAuthStore core.DeviceAuthorizationStore

	// AppStore drives confidential-client enforcement on the device-
	// code (issue 266) and authorization-code redemption paths.
	AppStore core.AppRegistrationStore

	// TrustedAssertionIssuers lists upstream IdPs whose JWT assertions
	// the token endpoint accepts for the jwt-bearer (RFC 7523 §2.1)
	// and token-exchange (RFC 8693) grants. Empty disables both.
	TrustedAssertionIssuers []TrustedAssertionIssuer

	// IDJAGIssuer, when non-nil, opts the token-exchange grant into
	// issuing ID-JAGs (requested_token_type=...:id-jag) for the MCP
	// Enterprise-Managed Authorization flow (SEP-990). Nil (default)
	// rejects id-jag requests with invalid_request — minting a
	// cross-domain authorization grant is a sensitive capability, off by
	// default per the capability-gating convention (#344). Wire
	// apiauth.NewJWTIDJAGIssuer (signed with the IdP key) to opt in. Only
	// consulted when TrustedAssertionIssuers is non-empty.
	IDJAGIssuer IDJAGIssuer

	// IDJAGReplayStore enforces single-use on redeemed ID-JAGs (they are
	// single-use per draft-ietf-oauth-identity-assertion-authz-grant).
	// Nil falls back to an in-process in-memory store; supply a
	// distributed implementation for multi-node deployments. Only
	// consulted when TrustedAssertionIssuers is non-empty.
	IDJAGReplayStore JTIStore

	// TracerProvider opts the validator's signature-verify hot path
	// into SEP-414 tracing. Nil keeps it on the no-op fast path.
	TracerProvider trace.TracerProvider

	// Hooks — lifecycle callbacks
	Hooks Hooks
}

type PasswordGrantRequest struct {
	Username             string
	Password             string
	Scopes               []string                   // requested (intersected with allowed)
	AuthorizationDetails []core.AuthorizationDetail // RFC 9396
	ClientID             string                     // optional — associated client
}

type PasswordGrantResponse struct {
	Subject              string // RFC 7519 sub — user ID for password grant
	AccessToken          string
	ExpiresIn            int64
	GrantedScopes        []string
	AuthorizationDetails []core.AuthorizationDetail
}

type PasswordGranter interface {
	// PasswordGrant authenticates the resource owner and returns an
	// access token. Does NOT create a refresh token — the caller
	// (TokenEndpointHandler) is responsible for that with transport
	// metadata (device info, IP) the granter cannot see.
	PasswordGrant(ctx context.Context, req *PasswordGrantRequest) (*PasswordGrantResponse, error)
}

type PasswordGranterConfig struct {
	// Issuer is the access-token minting backend. Required.
	Issuer TokenIssuer

	// ValidateCredentials authenticates the (username, password) pair.
	// Required. Returns the User on success, an error on failure;
	// the granter maps "invalid credentials" to the RFC 6749 §5.2
	// `invalid_grant` error.
	ValidateCredentials CredentialsValidator

	// GetSubjectScopes returns the scopes the authenticated user is
	// permitted to grant. Optional — when nil, a built-in default
	// scope set (read / write / profile / offline_access) is used.
	GetSubjectScopes core.GetSubjectScopesFunc

	// Hooks are the token-lifecycle callbacks fired on issuance.
	// Zero value is fine.
	Hooks TokenHooks
}

type ProtectedResourceMetadata struct {
	// Resource is the resource server's identifier (its base URL).
	// REQUIRED per RFC 9728 §3.
	Resource string `json:"resource"`

	// AuthorizationServers lists the authorization servers that the resource
	// server trusts to issue tokens. REQUIRED per RFC 9728 §3.
	AuthorizationServers []string `json:"authorization_servers"`

	// ScopesSupported lists the OAuth 2.0 scopes that this resource server
	// understands. Optional.
	ScopesSupported []string `json:"scopes_supported,omitempty"`

	// BearerMethodsSupported lists how this resource server accepts bearer
	// tokens, using the method names from RFC 6750 ("header", "body", "query").
	// Optional per RFC 9728 §2; omitted from JSON when empty. OneAuth's
	// middleware only accepts the Authorization request header field
	// (RFC 6750 §2.1), so a OneAuth-backed resource server advertises
	// ["header"] — the reference server in cmd/demo-resource-server sets this.
	BearerMethodsSupported []string `json:"bearer_methods_supported,omitempty"`

	// TokenFormatsSupported lists the token formats accepted (e.g., "jwt").
	// Optional.
	TokenFormatsSupported []string `json:"token_formats_supported,omitempty"`

	// SigningAlgsSupported lists the JWS signing algorithms the resource server
	// supports for validating tokens (e.g., "RS256", "ES256", "HS256").
	// Optional.
	SigningAlgsSupported []string `json:"resource_signing_alg_values_supported,omitempty"`

	// DocumentationURI points to human-readable documentation for the resource
	// server's API. Optional.
	DocumentationURI string `json:"resource_documentation,omitempty"`

	// IntrospectionEndpoint is the URL of the token introspection endpoint
	// (RFC 7662) that can be used to validate tokens for this resource.
	// Optional — included when the resource server supports introspection.
	IntrospectionEndpoint string `json:"introspection_endpoint,omitempty"`

	// CacheMaxAge controls the Cache-Control max-age header in seconds.
	// Defaults to 3600 (1 hour) if zero. Not serialized to JSON.
	CacheMaxAge int `json:"-"`
}

type RefreshGrantRequest struct {
	RefreshToken string
}

type RefreshGrantResponse struct {
	Tokens *core.TokenPair
}

type RevocationHandler struct {
	// Revoker performs the actual token revocation (transport-independent).
	Revoker TokenRevoker

	// Authenticator verifies the caller's client credentials.
	Authenticator ClientAuthenticator

	// AcceptedAudiences are the URLs the AS will accept as the
	// `aud` claim of a private_key_jwt / client_secret_jwt client
	// assertion (OIDC Core §9). When empty the URL of the request
	// is used as a fallback.
	AcceptedAudiences []string

	// TracerProvider opts the revocation endpoint into SEP-414 tracing.
	// When set, ServeHTTP extracts an inbound `traceparent` header and
	// emits an `oneauth.revoke` span. Nil keeps the handler on the
	// no-op fast path.
	TracerProvider trace.TracerProvider
}

type RevokeRequest struct {
	Token         string
	TokenTypeHint string
}

type RevokeResponse struct{}

type SecurityHooks struct {
	// OnTokenRejected fires when a token fails validation.
	// reason describes why (expired, bad signature, revoked, etc.).
	OnTokenRejected func(reason string)

	// OnBlacklistHit fires when a revoked token is presented.
	// This indicates token reuse after revocation — potential theft.
	OnBlacklistHit func(jti string)

	// OnAlgorithmMismatch fires when a token's alg header doesn't match
	// the stored key's algorithm. This is the CVE-2015-9235 attack vector.
	OnAlgorithmMismatch func(expected, got string)
}

type SessionsHandler struct {
	// Store backs the refresh tokens. Required.
	Store core.RefreshTokenStore

	// Hooks fires the lifecycle callbacks. The zero value is a no-op
	// dispatcher.
	Hooks TokenHooks
}

type TokenEndpointHandler struct {
	// OneAuth provides the granters and shared state. Required.
	OneAuth *OneAuth

	// RateLimiter throttles password-grant attempts by client IP +
	// username. Nil disables rate limiting.
	RateLimiter core.RateLimiter

	// TracerProvider opts the handler into SEP-414 tracing. Nil keeps
	// the no-op fast path.
	TracerProvider trace.TracerProvider
}

type TokenExchangeRequest struct {
	SubjectToken         string
	SubjectTokenType     string
	RequestedTokenType   string
	Resource             string
	Audience             string
	Scopes               []string
	AuthorizationDetails []core.AuthorizationDetail

	// ClientID is the requesting client's identifier. For the id-jag
	// output path it becomes the ID-JAG `client_id` claim — the client
	// identity the downstream (resource-app) AS knows the client by.
	ClientID string

	// Client-authentication material. Optional; when present and ClientID
	// names a registered confidential client, the granter authenticates
	// it (rejecting invalid_client on failure) before issuing.
	ClientSecret        string
	ClientAssertionType string
	ClientAssertion     string
	// AcceptedAudiences bounds a client-assertion `aud` (OIDC Core §9);
	// filled by the token endpoint from its configured audience list.
	AcceptedAudiences []string
}

type TokenExchangeResponse struct {
	Tokens *core.TokenPair
}

type TokenExchanger interface {
	// TokenExchange trades subject_token for a token with the
	// requested type / audience / resource.
	TokenExchange(ctx context.Context, req *TokenExchangeRequest) (*TokenExchangeResponse, error)
}

type TokenExchangerConfig struct {
	// TrustedIssuers lists upstream IdPs whose subject_tokens the grant
	// accepts. MUST be non-empty for the grant to do anything.
	TrustedIssuers []TrustedAssertionIssuer

	// DefaultAudience / DefaultIssuer supply the RFC 7523 §3 audience
	// fallback used when validating the subject_token and a
	// TrustedAssertionIssuer entry doesn't pin its own audience.
	DefaultAudience string
	DefaultIssuer   string

	// Issuer mints the access token for the access_token output path.
	// Required.
	Issuer TokenIssuer

	// IDJAGIssuer, when non-nil, opts the grant into
	// requested_token_type=id-jag issuance for the MCP EMA flow. Nil
	// (default) rejects id-jag requests — minting a cross-domain
	// authorization grant is off by default per #344.
	IDJAGIssuer IDJAGIssuer

	// AppStore + Authenticator enable confidential-client authentication
	// (issue 356). When wired, a request whose client_id names a
	// registered confidential client is authenticated before issuance;
	// public / unregistered clients keep the assertion-only path. Both
	// nil (default) preserves the pre-356 behavior of never
	// authenticating the client on this grant.
	AppStore      core.AppRegistrationStore
	Authenticator ClientAuthenticator
}

type TokenHooks struct {
	// OnIssued fires after an access token is successfully created.
	// subject is the token's sub claim, grantType is the OAuth grant used.
	OnIssued func(subject, grantType string)

	// OnRefreshed fires after a refresh token is rotated and a new access token issued.
	OnRefreshed func(subject string)

	// OnRevoked fires after a token is successfully revoked.
	// hint is the token_type_hint ("access_token", "refresh_token", or "").
	OnRevoked func(token, hint string)

	// OnSubjectRevoked fires when every active grant for a subject has been
	// revoked (logout-all). Subject is the affected user; sid is the OIDC
	// session ID when one is associated with the revocation (empty for
	// subject-wide revokes that are not session-scoped). clientIDs lists
	// every client that held an active grant at revoke time — captured
	// BEFORE the revoke so subscribers (notably the BCL dispatcher) can
	// notify them without having to re-query a store that, post-revoke,
	// returns nothing. Empty when no client identifiers were available.
	OnSubjectRevoked func(subject, sid string, clientIDs []string)

	// OnTokenRevoked fires when a single refresh token (or all tokens in a
	// family) is revoked, after subject + client_id are known. Provides the
	// affected subject, sid (family ID, when known), and clientID. Distinct
	// from OnRevoked so subscribers (notably BCL) get the routing identifiers
	// without having to re-parse the token. clientID is empty when the
	// trigger lacks a known client (e.g., admin-side revoke by jti).
	OnTokenRevoked func(subject, sid, clientID string)
}

type TokenInfo struct {
	// Subject is the principal the token represents (RFC 7519 sub) — a
	// user ID for human-driven flows or a client_id for
	// client_credentials.
	Subject string

	// Scopes are the granted scopes from the token.
	Scopes []string

	// AuthorizationDetails are the RFC 9396 authorization_details from the token.
	// Nil if the token has no authorization_details.
	AuthorizationDetails []core.AuthorizationDetail

	// CustomClaims are non-standard JWT claims (everything not in standardClaims).
	CustomClaims map[string]any

	// AuthType is "jwt" or "api_key".
	AuthType string
}

type TokenIntrospector interface {
	// Introspect checks a token's validity and returns its claims.
	// Returns {Active: false} on the wrapped result for any invalid token
	// (never reveals why — RFC 7662 §2.2 confidentiality).
	Introspect(ctx context.Context, req *IntrospectRequest) (*IntrospectResponse, error)
}

type TokenIssuer interface {
	// CreateAccessToken mints a JWT with the given subject, scopes, and
	// optional RFC 9396 authorization_details.
	CreateAccessToken(ctx context.Context, req *CreateAccessTokenRequest) (*CreateAccessTokenResponse, error)

	// ClientCredentials performs the full client_credentials grant:
	// authenticates the client, validates scopes/details, and returns a token pair.
	ClientCredentials(ctx context.Context, req *ClientCredentialsRequest) (*ClientCredentialsResponse, error)

	// RefreshGrant rotates a refresh token and returns a new access + refresh
	// token pair. Handles theft detection (revoked token → revoke entire family).
	RefreshGrant(ctx context.Context, req *RefreshGrantRequest) (*RefreshGrantResponse, error)
}

type TokenRevoker interface {
	// Revoke invalidates a token. The TokenTypeHint ("access_token" or
	// "refresh_token") guides which store to check first; empty hint tries both.
	Revoke(ctx context.Context, req *RevokeRequest) (*RevokeResponse, error)
}

type TokenRevokerConfig struct {
	Blacklist    core.TokenBlacklist
	RefreshStore core.RefreshTokenStore
	Hooks        TokenHooks
}

type TokenValidator interface {
	// ValidateToken parses and validates a token (signature, expiry, issuer,
	// audience, blacklist) and returns its claims.
	ValidateToken(ctx context.Context, req *ValidateTokenRequest) (*ValidateTokenResponse, error)

	// CheckScopes validates a token and verifies it carries every required scope.
	CheckScopes(ctx context.Context, req *CheckScopesRequest) (*CheckScopesResponse, error)

	// CheckAuthorizationDetails validates a token and verifies it carries
	// authorization_details entries for every required type (RFC 9396).
	CheckAuthorizationDetails(ctx context.Context, req *CheckAuthorizationDetailsRequest) (*CheckAuthorizationDetailsResponse, error)
}

type TrustedAssertionIssuer struct {
	// Issuer is the expected `iss` claim value (e.g.,
	// "https://corp-idp.example.com"). REQUIRED.
	Issuer string

	// PublicKey is a static public key for signature verification.
	// Either this or KeyFunc MUST be set. Suitable for tests and
	// single-key issuers; for production with key rotation use KeyFunc.
	PublicKey crypto.PublicKey

	// KeyFunc resolves a public key from the JWT header (typically
	// looking up `kid` against a cached JWKS). When set it takes
	// precedence over PublicKey. The token argument is the parsed
	// (but not yet signature-verified) JWT.
	KeyFunc func(token *jwt.Token) (crypto.PublicKey, error)

	// Audiences lists acceptable `aud` claim values for assertions
	// signed by this issuer. When empty, defaults to the AS's
	// JWTAudience (or its IssuerURL if no audience is configured).
	// RFC 7523 §3 requires the AS to identify itself by the audience
	// claim — the default makes the token endpoint URL implicit.
	Audiences []string

	// AcceptedAlgorithms restricts the JWT alg values accepted for
	// assertions from this issuer (e.g., {"RS256", "ES256"}). Empty
	// = accept any non-`none` algorithm advertised by the JWT library.
	// Set this in production to lock out alg-confusion attacks.
	AcceptedAlgorithms []string
}

type ValidateTokenRequest struct {
	Token string
}

type ValidateTokenResponse struct {
	Info *TokenInfo
}