apiauth

type APIAuth struct {
	// Stores
	RefreshTokenStore core.RefreshTokenStore
	APIKeyStore       core.APIKeyStore

	// JWT configuration
	JWTSecretKey  string // Secret key for signing JWTs (HMAC)
	JWTIssuer     string // Issuer claim (e.g., "myapp")
	JWTAudience   string // Audience claim (e.g., "api")
	JWTSigningAlg string // Signing algorithm (defaults to HS256)

	// Asymmetric JWT keys (optional — when set, these take precedence over JWTSecretKey)
	JWTSigningKey any // crypto.PrivateKey (*rsa.PrivateKey or *ecdsa.PrivateKey) for signing
	JWTVerifyKey  any // crypto.PublicKey (*rsa.PublicKey or *ecdsa.PublicKey) for verification

	// Token configuration
	AccessTokenExpiry  time.Duration // Defaults to 15 minutes
	RefreshTokenExpiry time.Duration // Defaults to 7 days

	// Callbacks
	ValidateCredentials CredentialsValidator                              // Validates username/password
	GetSubjectScopes    core.GetSubjectScopesFunc                         // Returns allowed scopes for the subject (user ID or client_id)
	OnLoginSuccess      func(userID string, r *http.Request)              // Optional: for logging/analytics
	OnLoginFailure      func(username string, r *http.Request, err error) // Optional: for logging/analytics

	// CustomClaimsFunc is called during token creation to inject additional claims
	// into the JWT (e.g., client_id, max_rooms for relay-scoped tokens).
	// Standard claims (sub, iss, aud, exp, iat, type, scopes) cannot be overridden.
	// If nil, no custom claims are added (backwards-compatible).
	CustomClaimsFunc func(userID string, scopes []string) (map[string]any, error)

	// ClientKeyStore provides client credential lookup for the client_credentials
	// grant type (RFC 6749 §4.4). When set, the token endpoint accepts
	// grant_type=client_credentials and authenticates clients via KeyStore.
	// When nil, client_credentials requests return unsupported_grant_type.
	ClientKeyStore keys.KeyLookup

	// ClientAuthenticator authenticates clients at the token endpoint
	// (and is also used by the introspection / revocation handlers).
	// When set, all client authentication on the token endpoint
	// (client_secret_basic, client_secret_post, private_key_jwt) goes
	// through this interface — supporting the assertion-based methods
	// is the entire point of plumbing it here. When nil, the token
	// endpoint falls back to the legacy inline lookup against
	// ClientKeyStore (secret-based methods only).
	ClientAuthenticator ClientAuthenticator

	// AcceptedAudiences are the URLs the AS will accept as the `aud`
	// claim of a private_key_jwt / client_secret_jwt client assertion
	// at the token endpoint (OIDC Core §9). Typically the token
	// endpoint URL plus the AS issuer URL. When empty, the URL of the
	// request is used as a fallback (single-host deployments only).
	AcceptedAudiences []string

	// TrustedAssertionIssuers lists upstream IdPs whose JWT assertions
	// the token endpoint will accept for the jwt-bearer grant
	// (RFC 7523 §2.1) and the token-exchange grant with
	// subject_token_type=urn:ietf:params:oauth:token-type:jwt
	// (RFC 8693 §2.1.1). When empty, both grants return
	// unsupported_grant_type.
	//
	// See JwtBearerGrantType, TokenExchangeGrantType, and
	// TrustedAssertionIssuer for details.
	TrustedAssertionIssuers []TrustedAssertionIssuer

	// Rate limiting (optional)
	RateLimiter core.RateLimiter

	// Blacklist enables immediate access token revocation. When set,
	// ValidateAccessToken checks the blacklist after signature verification.
	// Tokens include a jti (JWT ID) claim for blacklist lookup.
	// If nil, tokens are validated by signature + expiry only (stateless).
	Blacklist core.TokenBlacklist

	// TokenHooks fires on token lifecycle events handled directly by APIAuth
	// (logout / logout-all). The HTTP-facing APIAuth is wired field-by-field
	// rather than via OneAuthConfig; callers who want logout-all to drive
	// the OIDC Back-Channel Logout dispatcher must populate
	// TokenHooks.OnSubjectRevoked here. Leaving it zero keeps HandleLogout /
	// HandleLogoutAll behaviorally unchanged.
	TokenHooks TokenHooks

	// DeviceAuthStore enables the RFC 8628 device authorization grant.
	// When non-nil the token endpoint accepts
	// grant_type=urn:ietf:params:oauth:grant-type:device_code and the
	// caller is expected to mount DeviceAuthorizationHandler at the
	// /device/authorize path. Nil keeps the token endpoint behaviorally
	// identical to its pre-#117 surface.
	DeviceAuthStore core.DeviceAuthorizationStore

	// AppStore lets the token endpoint look up a registered client's
	// `token_endpoint_auth_method` to decide whether confidential-client
	// authentication is required on the device-code redemption path
	// (issue 266).
	//
	// When nil, the device-grant handler accepts the form `client_id`
	// alone for backward compatibility with the v0.1.23 wire protocol.
	//
	// When non-nil, AppStore becomes the source of truth: the device
	// authorization's bound client_id MUST resolve to a registered
	// AppRegistration, otherwise the redemption is rejected with
	// `invalid_client`. The handler does NOT silently downgrade to the
	// unauthenticated path on lookup failure — opting into AppStore is
	// opting into strict enforcement. Production deployments with
	// confidential device clients MUST wire it so a stolen device_code
	// cannot be redeemed without the registered client's credentials.
	AppStore core.AppRegistrationStore

	// TracerProvider opts the /token endpoint into SEP-414 tracing.
	// When set, ServeHTTP extracts an inbound W3C `traceparent` header
	// and emits a single `oneauth.token.issue` span with the parsed
	// grant type as an attribute. Nil keeps the handler on the no-op
	// fast path. The same TracerProvider should usually be passed to
	// IntrospectionHandler, RevocationHandler, JWKSHandler, and the
	// JWKSKeyStore so all spans share one trace.
	TracerProvider trace.TracerProvider
	// contains filtered or unexported fields
}

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"

	// TokenQueryParam is the query parameter name to check for a token as fallback
	// when the Authorization header is missing (e.g., "token" for ?token=...).
	// Empty string disables query param extraction (default).
	TokenQueryParam 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".
	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 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
}

type CreateAccessTokenResponse struct {
	Token     string
	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 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 Hooks struct {
	Token    TokenHooks
	Auth     AuthHooks
	Client   ClientHooks
	Security SecurityHooks
}

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
	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
	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 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

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

	// 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"

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

	// 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

	// 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 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"`

	// 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 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)

	// PasswordGrant authenticates a user with username/password and returns
	// an access token. Does NOT create a refresh token — the caller's
	// responsibility (via RefreshTokenStore.CreateRefreshToken), since refresh
	// tokens may carry transport-specific metadata (device info, IP, etc.).
	PasswordGrant(ctx context.Context, req *PasswordGrantRequest) (*PasswordGrantResponse, 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
}