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 core.CredentialsValidator                         // Validates username/password
	GetUserScopes       core.GetUserScopesFunc                            // Returns allowed scopes for a user
	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

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

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

	// Supported features
	AuthorizationDetailsTypesSupported []string `json:"authorization_details_types_supported,omitempty"` // RFC 9396
	ScopesSupported                    []string `json:"scopes_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"`
	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"`

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

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 ClientAuthenticator interface {
	// AuthenticateClient verifies the client_id and client_secret.
	AuthenticateClient(clientID, clientSecret string) error
}

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

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

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

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
	// contains filtered or unexported fields
}

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 core.CredentialsValidator // for password grant
	GetUserScopes       core.GetUserScopesFunc    // for password grant (optional)
	Hooks               TokenHooks
}

type JWTValidatorConfig struct {
	KeyLookup keys.KeyLookup
	Blacklist core.TokenBlacklist
	Issuer    string
	Audience  string
	Hooks     SecurityHooks
}

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 core.CredentialsValidator // validates username/password
	GetUserScopes       core.GetUserScopesFunc    // returns allowed scopes for a user

	// 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 PasswordGrantResult struct {
	UserID               string
	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 RevocationHandler struct {
	// Revoker performs the actual token revocation (transport-independent).
	Revoker TokenRevoker

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

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

type TokenInfo struct {
	// UserID is the subject (sub claim) — a user ID or client_id.
	UserID 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} for any invalid token (never reveals why).
	Introspect(token string) (*IntrospectionResult, error)
}

type TokenIssuer interface {
	// CreateAccessToken mints a JWT with the given subject, scopes, and
	// optional RFC 9396 authorization_details.
	// Returns the signed token string and expiry in seconds.
	CreateAccessToken(subject string, scopes []string, details []core.AuthorizationDetail) (token string, expiresIn int64, err error)

	// ClientCredentials performs the full client_credentials grant:
	// authenticates the client, validates scopes/details, and returns a token response.
	ClientCredentials(clientID, clientSecret string, scopes []string, details []core.AuthorizationDetail) (*core.TokenPair, error)

	// RefreshGrant rotates a refresh token and returns a new access + refresh token pair.
	// Handles theft detection (revoked token → revoke entire family).
	RefreshGrant(refreshToken string) (*core.TokenPair, error)

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

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

type TokenValidator interface {
	// ValidateToken parses and validates a token string (JWT signature,
	// expiry, issuer, audience, blacklist). Returns the token's claims.
	ValidateToken(token string) (*TokenInfo, error)

	// CheckScopes validates a token and verifies it contains all required scopes.
	// Returns an error if the token is invalid or scopes are insufficient.
	CheckScopes(token string, required []string) error

	// CheckAuthorizationDetails validates a token and verifies it contains
	// authorization_details entries for all required types (RFC 9396).
	CheckAuthorizationDetails(token string, requiredTypes []string) 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
}