core

type APIKey struct {
	KeyID      string     `json:"key_id"`   // Public identifier (e.g., "oa_abc123...")
	KeyHash    string     `json:"key_hash"` // bcrypt hash of the secret portion
	Subject    string     `json:"subject"`  // Principal the key represents (RFC 7519 sub) — user ID for user-bound keys, client_id for service accounts
	Name       string     `json:"name"`     // User-defined label
	Scopes     []string   `json:"scopes"`   // Allowed scopes
	CreatedAt  time.Time  `json:"created_at"`
	ExpiresAt  *time.Time `json:"expires_at,omitempty"` // Optional expiry
	LastUsedAt time.Time  `json:"last_used_at"`
	RevokedAt  *time.Time `json:"revoked_at,omitempty"`
	Revoked    bool       `json:"revoked"`
}

type APIKeyStore interface {
	// CreateAPIKey creates a new API key for the given subject. The full key
	// (keyID + "_" + secret) is only returned here.
	CreateAPIKey(ctx context.Context, req *CreateAPIKeyRequest) (*CreateAPIKeyResponse, error)

	// GetAPIKeyByID retrieves an API key by its public ID.
	GetAPIKeyByID(ctx context.Context, req *GetAPIKeyByIDRequest) (*GetAPIKeyByIDResponse, error)

	// ValidateAPIKey validates a full API key and returns the key metadata if valid.
	ValidateAPIKey(ctx context.Context, req *ValidateAPIKeyRequest) (*ValidateAPIKeyResponse, error)

	// RevokeAPIKey marks an API key as revoked.
	RevokeAPIKey(ctx context.Context, req *RevokeAPIKeyRequest) (*RevokeAPIKeyResponse, error)

	// ListSubjectAPIKeys returns all API keys owned by a subject (without secrets).
	ListSubjectAPIKeys(ctx context.Context, req *ListSubjectAPIKeysRequest) (*ListSubjectAPIKeysResponse, error)

	// UpdateAPIKeyLastUsed updates the last-used timestamp.
	UpdateAPIKeyLastUsed(ctx context.Context, req *UpdateAPIKeyLastUsedRequest) (*UpdateAPIKeyLastUsedResponse, error)
}

type AccountLockout struct {
	MaxAttempts  int           // consecutive failures before lockout (default: 5)
	LockDuration time.Duration // how long the lockout lasts (default: 15 min)
	// contains filtered or unexported fields
}

type AppRegistration struct {
	ClientID                  string    `json:"client_id"`
	ClientDomain              string    `json:"client_domain"`
	SigningAlg                string    `json:"signing_alg"`
	AuthorizationDetailsTypes []string  `json:"authorization_details_types,omitempty"` // RFC 9396
	CreatedAt                 time.Time `json:"created_at"`
	Revoked                   bool      `json:"revoked"`

	// RFC 7591 / 7592 client metadata (populated by DCR; see issue 157).
	ClientName              string   `json:"client_name,omitempty"`
	ClientURI               string   `json:"client_uri,omitempty"`
	RedirectURIs            []string `json:"redirect_uris,omitempty"`
	GrantTypes              []string `json:"grant_types,omitempty"`
	Scope                   string   `json:"scope,omitempty"`
	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`

	// RFC 7592 management credentials. Issued when the management protocol
	// is implemented (issue 168); empty for legacy registrations.
	RegistrationAccessToken string `json:"registration_access_token,omitempty"`
	RegistrationClientURI   string `json:"registration_client_uri,omitempty"`

	// OIDC Back-Channel Logout 1.0 — per-client push endpoint. When set, the
	// AS POSTs a signed logout_token to BackchannelLogoutURI whenever a
	// session that touched this client is revoked (issue 261).
	// BackchannelLogoutSessionRequired toggles whether the logout_token MUST
	// carry a sid claim — true means the client tracks sessions per spec §2.2.
	// Empty BackchannelLogoutURI disables dispatch for this client.
	BackchannelLogoutURI             string `json:"backchannel_logout_uri,omitempty"`
	BackchannelLogoutSessionRequired bool   `json:"backchannel_logout_session_required,omitempty"`

	// DPoPBoundAccessTokens is the RFC 9449 §5.2 client metadata: when
	// true, the token endpoint refuses this client's token requests that
	// carry no DPoP proof, so every token it receives is sender-constrained.
	// False leaves DPoP per-request opt-in for this client, unless
	// OneAuthConfig.RequireDPoP demands it of every client.
	DPoPBoundAccessTokens bool `json:"dpop_bound_access_tokens,omitempty"`

	// RequirePushedAuthorizationRequests is the RFC 9126 §6 client
	// metadata: when true, /authorize refuses this client's requests that
	// don't arrive through PAR, the per-client form of
	// AuthorizationHandler.RequirePushedRequests.
	RequirePushedAuthorizationRequests bool `json:"require_pushed_authorization_requests,omitempty"`
}

type AppRegistrationStore interface {
	// SaveApp inserts or replaces the registration for req.App.ClientID.
	SaveApp(ctx context.Context, req *SaveAppRequest) (*SaveAppResponse, error)

	// GetApp returns the registration for req.ClientID, or ErrAppNotFound.
	GetApp(ctx context.Context, req *GetAppRequest) (*GetAppResponse, error)

	// ListApps returns every registration in the store. Order is unspecified.
	ListApps(ctx context.Context, req *ListAppsRequest) (*ListAppsResponse, error)

	// DeleteApp removes the registration for req.ClientID. Returns ErrAppNotFound
	// if no such registration exists.
	DeleteApp(ctx context.Context, req *DeleteAppRequest) (*DeleteAppResponse, error)
}

type ApproveDeviceAuthorizationRequest struct {
	UserCode        string
	ApprovedSubject string
	GrantedScopes   []string // optional — overrides Authorization.Scopes when non-nil (consent UI may narrow scope)
}

type ApproveDeviceAuthorizationResponse struct {
	Authorization *DeviceAuthorization
}

type AuthorizationCode struct {
	// Code is the high-entropy identifier the client redeems with.
	// 256-bit, hex-encoded; unguessable.
	Code string `json:"code"`

	// ClientID is the OAuth client the code was issued to. RFC 6749
	// §4.1.3 requires the redemption request's authenticated client_id
	// to match this value.
	ClientID string `json:"client_id"`

	// RedirectURI is the verbatim redirect_uri parameter from the
	// initial /authorize request. The redemption handler requires the
	// token request to send the same value (RFC 6749 §4.1.3).
	RedirectURI string `json:"redirect_uri"`

	// Scopes is the granted scope set, carried forward unchanged to the
	// issued access token. The consent UI may narrow this set relative
	// to the requested scopes.
	Scopes []string `json:"scopes,omitempty"`

	// Subject is the principal (RFC 7519 `sub`) who approved the
	// authorization. Bound to the issued access token.
	Subject string `json:"subject"`

	// CodeChallenge is the PKCE challenge (RFC 7636 §4.2) the client
	// committed to at /authorize time. Empty when the client did not
	// supply PKCE; the apiauth handler rejects empty challenges by
	// default (OAuth 2.1 makes PKCE mandatory for public clients and
	// SHOULD-mandatory for all clients).
	CodeChallenge string `json:"code_challenge,omitempty"`

	// DPoPJKT is the RFC 7638 thumbprint of the DPoP key the client
	// named in the `dpop_jkt` authorization request parameter, empty
	// when the client sent none (RFC 9449 §10).
	//
	// When set, the token request redeeming this code MUST carry a DPoP
	// proof for the same key. That extends the binding back across the
	// front channel: without it the key first appears at the token
	// endpoint, so an intercepted code can be redeemed with the
	// attacker's key and yields a token bound to the attacker.
	//
	// The protection only holds when the client uses a fresh key per
	// authorization request, which §10 states plainly. A client reusing
	// one key gains nothing here that PKCE does not already give it.
	DPoPJKT string `json:"dpop_jkt,omitempty"`

	// CodeChallengeMethod is the transformation the client applied to
	// the verifier — "S256" (RFC 7636 §4.2) or "plain". Only S256 is
	// advertised in AS metadata; "plain" is rejected by the apiauth
	// handler.
	CodeChallengeMethod string `json:"code_challenge_method,omitempty"`

	// AuthorizationDetails carries the RFC 9396 fine-grained
	// authorization payload from /authorize through to the issued
	// access token. Nil when the request had no authorization_details.
	AuthorizationDetails []AuthorizationDetail `json:"authorization_details,omitempty"`

	// IssuedAt is when the AS minted the code. Useful for telemetry
	// and as the anchor for any future "max code age" enforcement.
	IssuedAt time.Time `json:"issued_at"`

	// ExpiresAt is the deadline after which a redemption returns
	// invalid_grant. RFC 6749 §4.1.2 recommends ≤10 minutes; the
	// apiauth handler defaults to 60s (OAuth 2.1 alignment).
	ExpiresAt time.Time `json:"expires_at"`

	// UsedAt is when the code was redeemed, zero while it is unused. Set
	// once, by ConsumeAuthorizationCode.
	UsedAt time.Time `json:"used_at,omitempty"`

	// IssuedTokenID is the `jti` of the access token the redemption
	// minted, and IssuedTokenExpiresAt its expiry. The store keeps a used
	// record until IssuedTokenExpiresAt, after which there is nothing
	// left to revoke.
	IssuedTokenID        string    `json:"issued_token_id,omitempty"`
	IssuedTokenExpiresAt time.Time `json:"issued_token_expires_at,omitempty"`

	// IssuedRefreshFamily is the family of the refresh token the
	// redemption minted, empty when it minted none.
	IssuedRefreshFamily string `json:"issued_refresh_family,omitempty"`

	// ReuseDetected is set when the code is presented after it was used.
	// The redemption that minted the tokens checks it after recording
	// them, so a reuse racing the first redemption still revokes.
	ReuseDetected bool `json:"reuse_detected,omitempty"`
}

type AuthorizationCodeStore interface {
	// CreateAuthorizationCode inserts a new authorization code. The
	// Code field MUST be unique across all non-expired records — the
	// caller has already generated it via cryptographic RNG, so a
	// collision is a programmer error and surfaces as a generic error
	// (not a typed sentinel). Mirrors the DeviceAuthorizationStore
	// collision contract.
	CreateAuthorizationCode(ctx context.Context, req *CreateAuthorizationCodeRequest) (*CreateAuthorizationCodeResponse, error)

	// GetAuthorizationCode returns the binding for the given code, or
	// ErrAuthorizationCodeNotFound. Does NOT filter by expiry — the
	// caller (the token endpoint handler) checks IsExpired so it can
	// surface a distinct invalid_grant vs expired error.
	GetAuthorizationCode(ctx context.Context, req *GetAuthorizationCodeRequest) (*GetAuthorizationCodeResponse, error)

	// DeleteAuthorizationCode removes the binding. Called by the token
	// endpoint on an expired code and by callers cleaning up rejected
	// flows. Returns ErrAuthorizationCodeNotFound when no record matches.
	DeleteAuthorizationCode(ctx context.Context, req *DeleteAuthorizationCodeRequest) (*DeleteAuthorizationCodeResponse, error)

	// ConsumeAuthorizationCode marks an unused code used and returns the
	// record as it was. For a code already used it sets ReuseDetected and
	// returns ErrAuthorizationCodeUsed together with the record, whose
	// Issued* fields name the tokens to revoke. A missing code is
	// ErrAuthorizationCodeNotFound.
	ConsumeAuthorizationCode(ctx context.Context, req *ConsumeAuthorizationCodeRequest) (*ConsumeAuthorizationCodeResponse, error)

	// RecordAuthorizationCodeTokens stores the tokens a redemption minted
	// on the used record and reports ReuseDetected, read in the same
	// atomic step. A missing code is ErrAuthorizationCodeNotFound.
	RecordAuthorizationCodeTokens(ctx context.Context, req *RecordAuthorizationCodeTokensRequest) (*RecordAuthorizationCodeTokensResponse, error)

	// CleanupExpired removes every record whose RetainUntil is at or
	// before the current wall-clock time, so a used code outlives its own
	// expiry until the access token it produced has expired. Production
	// deployments run this on a timer; tests call it explicitly.
	CleanupExpired(ctx context.Context, req *CleanupExpiredAuthorizationCodesRequest) (*CleanupExpiredAuthorizationCodesResponse, error)
}

type AuthorizationDetail struct {
	// Type is the authorization details type identifier (required).
	Type string `json:"type"`

	// Locations is an array of URIs indicating where the requested
	// resource can be found.
	Locations []string `json:"locations,omitempty"`

	// Actions is an array of strings describing the operations to be
	// performed on the resource.
	Actions []string `json:"actions,omitempty"`

	// DataTypes is an array of strings describing the types of data
	// being requested.
	DataTypes []string `json:"datatypes,omitempty"`

	// Identifier is a string identifying a specific resource at the API.
	Identifier string `json:"identifier,omitempty"`

	// Privileges is an array of strings representing privilege levels.
	Privileges []string `json:"privileges,omitempty"`

	// Extra holds API-specific extension fields. These are flattened into
	// the top-level JSON object (not nested under an "extra" key).
	Extra map[string]any `json:"-"`
}

type CleanupExpiredAuthorizationCodesRequest struct{}

type CleanupExpiredAuthorizationCodesResponse struct {
	Removed int
}

type CleanupExpiredDeviceAuthsRequest struct{}

type CleanupExpiredDeviceAuthsResponse struct {
	Removed int
}

type CleanupExpiredPushedRequestsRequest struct{}

type CleanupExpiredPushedRequestsResponse struct {
	Removed int
}

type CleanupExpiredTokensRequest struct{}

type CleanupExpiredTokensResponse struct{}

type Confirmation struct {
	JKT string `json:"jkt,omitempty"`
}

type ConsumeAuthorizationCodeRequest struct {
	Code string
}

type ConsumeAuthorizationCodeResponse struct {
	Code *AuthorizationCode
}

type ConsumePushedAuthorizationRequestRequest struct {
	RequestURI string
}

type ConsumePushedAuthorizationRequestResponse struct {
	// Consumed is true only for the call that flipped the record from
	// unused to used. A second call on the same reference gets false, so
	// the caller can refuse it: of two approvals racing on one pushed
	// request, only one may issue a code.
	Consumed bool
}

type CreateAPIKeyRequest struct {
	Subject   string
	Name      string
	Scopes    []string
	ExpiresAt *time.Time
}

type CreateAPIKeyResponse struct {
	FullKey string
	APIKey  *APIKey
}

type CreateAuthorizationCodeRequest struct {
	Code *AuthorizationCode
}

type CreateAuthorizationCodeResponse struct{}

type CreateDeviceAuthorizationRequest struct {
	Authorization *DeviceAuthorization
}

type CreateDeviceAuthorizationResponse struct{}

type CreatePushedAuthorizationRequestRequest struct {
	Request *PushedAuthorizationRequest
}

type CreatePushedAuthorizationRequestResponse struct {
	Request *PushedAuthorizationRequest
}

type CreateRefreshTokenRequest struct {
	Subject    string
	ClientID   string
	DeviceInfo map[string]any
	Scopes     []string

	// Confirmation binds the refresh token to a proof-of-possession key
	// (RFC 9449 §5). Non-nil means only a client that can prove possession
	// of that key may redeem it; rotation carries the binding forward.
	// Nil issues a plain bearer refresh token.
	Confirmation *Confirmation
}

type CreateRefreshTokenResponse struct {
	Token *RefreshToken
}

type DeleteAppRequest struct {
	ClientID string
}

type DeleteAppResponse struct{}

type DeleteAuthorizationCodeRequest struct {
	Code string
}

type DeleteAuthorizationCodeResponse struct{}

type DeleteDeviceAuthorizationRequest struct {
	DeviceCode string
}

type DeleteDeviceAuthorizationResponse struct{}

type DeletePushedAuthorizationRequestRequest struct {
	RequestURI string
}

type DeletePushedAuthorizationRequestResponse struct{}

type DenyDeviceAuthorizationRequest struct {
	UserCode string
}

type DenyDeviceAuthorizationResponse struct{}

type DeviceAuthorization struct {
	// DeviceCode is the high-entropy identifier the device polls with.
	// 256-bit, hex-encoded; unguessable.
	DeviceCode string `json:"device_code"`

	// UserCode is the short, human-typeable identifier the user enters on
	// the verification URI. RFC 8628 §6.1 recommends a constrained
	// charset; this implementation uses 8 chars from
	// BCDEFGHJKLMNPQRSTVWXZ23456789 (ambiguity-resistant).
	UserCode string `json:"user_code"`

	// ClientID is the OAuth client that initiated the device flow.
	ClientID string `json:"client_id"`

	// Scopes is the scope set requested at /device/authorize. Carried
	// forward unchanged to the issued access token.
	Scopes []string `json:"scopes,omitempty"`

	// RequestedAudience captures an optional RFC 8707 `audience` parameter
	// the device passed at /device/authorize. Empty when not requested.
	RequestedAudience string `json:"requested_audience,omitempty"`

	// Status tracks the lifecycle. See DeviceAuthorizationStatus values.
	Status DeviceAuthorizationStatus `json:"status"`

	// ApprovedSubject is the user (RFC 7519 `sub`) who approved this
	// authorization. Populated only when Status == Approved.
	ApprovedSubject string `json:"approved_subject,omitempty"`

	// CreatedAt is when the device authorization was created. Pinned at
	// creation time so polling-interval enforcement can reason from it.
	CreatedAt time.Time `json:"created_at"`

	// ExpiresAt is the deadline after which a polling request returns
	// expired_token. RFC 8628 §3.4 recommends 15 minutes.
	ExpiresAt time.Time `json:"expires_at"`

	// LastPolledAt is the last time the device polled the token endpoint
	// with this device_code. Used to enforce the `interval` rate limit and
	// emit `slow_down`.
	LastPolledAt time.Time `json:"last_polled_at,omitempty"`

	// IntervalSeconds is the current minimum polling interval the device
	// MUST respect. Starts at the AS default (5s per RFC 8628 §3.5) and
	// may grow when the AS emits `slow_down`.
	IntervalSeconds int `json:"interval_seconds"`
}

type DeviceAuthorizationStatus string

type DeviceAuthorizationStore interface {
	// CreateDeviceAuthorization inserts a new device authorization.
	// device_code and user_code MUST be unique across all non-expired
	// records — the caller has already generated them via cryptographic
	// RNG, so a collision is a programmer error and surfaces as a
	// generic error (not a typed sentinel).
	CreateDeviceAuthorization(ctx context.Context, req *CreateDeviceAuthorizationRequest) (*CreateDeviceAuthorizationResponse, error)

	// GetByDeviceCode returns the authorization for the given device_code,
	// or ErrDeviceAuthorizationNotFound. Does NOT filter by status or
	// expiry — the caller (the token endpoint handler) checks both.
	GetByDeviceCode(ctx context.Context, req *GetByDeviceCodeRequest) (*GetByDeviceCodeResponse, error)

	// GetByUserCode returns the authorization for the given user_code (case-
	// insensitive comparison), or ErrDeviceAuthorizationNotFound.
	GetByUserCode(ctx context.Context, req *GetByUserCodeRequest) (*GetByUserCodeResponse, error)

	// ApproveDeviceAuthorization transitions a pending authorization to
	// approved and binds the subject + scopes that the user consented to.
	// Returns ErrDeviceAuthorizationNotFound when no pending record matches
	// user_code.
	ApproveDeviceAuthorization(ctx context.Context, req *ApproveDeviceAuthorizationRequest) (*ApproveDeviceAuthorizationResponse, error)

	// DenyDeviceAuthorization transitions a pending authorization to
	// denied. Returns ErrDeviceAuthorizationNotFound when no pending
	// record matches user_code.
	DenyDeviceAuthorization(ctx context.Context, req *DenyDeviceAuthorizationRequest) (*DenyDeviceAuthorizationResponse, error)

	// UpdatePollingState records a poll attempt. Always updates
	// LastPolledAt; raises IntervalSeconds by 5 when SlowDown is true.
	UpdatePollingState(ctx context.Context, req *UpdatePollingStateRequest) (*UpdatePollingStateResponse, error)

	// DeleteDeviceAuthorization removes the authorization. Used by the
	// token endpoint on successful exchange (prevents replay) and by
	// callers cleaning up rejected flows. Returns
	// ErrDeviceAuthorizationNotFound when no record matches.
	DeleteDeviceAuthorization(ctx context.Context, req *DeleteDeviceAuthorizationRequest) (*DeleteDeviceAuthorizationResponse, error)

	// CleanupExpired enumerates the store and removes every record whose
	// ExpiresAt is at or before the current wall-clock time. Production
	// deployments run this on a timer; tests call it explicitly.
	CleanupExpired(ctx context.Context, req *CleanupExpiredDeviceAuthsRequest) (*CleanupExpiredDeviceAuthsResponse, error)
}

type GetAPIKeyByIDRequest struct {
	KeyID string
}

type GetAPIKeyByIDResponse struct {
	APIKey *APIKey
}

type GetAppRequest struct {
	ClientID string
}

type GetAppResponse struct {
	App *AppRegistration
}

type GetAuthorizationCodeRequest struct {
	Code string
}

type GetAuthorizationCodeResponse struct {
	Code *AuthorizationCode
}

type GetByDeviceCodeRequest struct {
	DeviceCode string
}

type GetByDeviceCodeResponse struct {
	Authorization *DeviceAuthorization
}

type GetByUserCodeRequest struct {
	UserCode string
}

type GetByUserCodeResponse struct {
	Authorization *DeviceAuthorization
}

type GetPushedAuthorizationRequestRequest struct {
	RequestURI string
}

type GetPushedAuthorizationRequestResponse struct {
	Request *PushedAuthorizationRequest
}

type GetRefreshTokenRequest struct {
	Token string
}

type GetRefreshTokenResponse struct {
	Token *RefreshToken
}

type GetSubjectScopesFunc func(subject string) ([]string, error)

type GetSubjectTokensRequest struct {
	Subject string
}

type GetSubjectTokensResponse struct {
	Tokens []*RefreshToken
}

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

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

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

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

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

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

type ListAppsRequest struct{}

type ListAppsResponse struct {
	Apps []*AppRegistration
}

type ListSubjectAPIKeysRequest struct {
	Subject string
}

type ListSubjectAPIKeysResponse struct {
	APIKeys []*APIKey
}

type PushedAuthorizationRequest struct {
	RequestURI string     `json:"request_uri"`
	ClientID   string     `json:"client_id"`
	Payload    url.Values `json:"payload"`
	Consumed   bool       `json:"consumed"`
	CreatedAt  time.Time  `json:"created_at"`
	ExpiresAt  time.Time  `json:"expires_at"`
}

type PushedAuthorizationRequestStore interface {
	// CreatePushedAuthorizationRequest inserts a new record. RequestURI
	// MUST be unique among live records. The caller generates it with a
	// CSPRNG, so a collision is a programmer error and surfaces as a
	// generic error rather than a typed sentinel, matching the
	// AuthorizationCodeStore contract.
	CreatePushedAuthorizationRequest(ctx context.Context, req *CreatePushedAuthorizationRequestRequest) (*CreatePushedAuthorizationRequestResponse, error)

	// GetPushedAuthorizationRequest returns the record for a request_uri
	// or ErrPushedRequestNotFound. It does NOT filter by expiry or
	// consumption: the authorization endpoint checks both so it can tell
	// a client that its reference expired rather than that it never
	// existed.
	GetPushedAuthorizationRequest(ctx context.Context, req *GetPushedAuthorizationRequestRequest) (*GetPushedAuthorizationRequestResponse, error)

	// ConsumePushedAuthorizationRequest marks a record redeemed. Called
	// before an authorization code is issued against it; the response's
	// Consumed is true only for the call that marked it, which makes it
	// the single-use gate. Returns ErrPushedRequestNotFound when no record
	// matches.
	//
	// Marking rather than deleting is deliberate: a client that replays a
	// consumed reference should be told its request was already used,
	// which a deleted record cannot distinguish from one that never
	// existed. CleanupExpired reclaims the row afterwards.
	ConsumePushedAuthorizationRequest(ctx context.Context, req *ConsumePushedAuthorizationRequestRequest) (*ConsumePushedAuthorizationRequestResponse, error)

	// DeletePushedAuthorizationRequest removes a record. For callers
	// tearing down an abandoned flow. Returns ErrPushedRequestNotFound
	// when no record matches.
	DeletePushedAuthorizationRequest(ctx context.Context, req *DeletePushedAuthorizationRequestRequest) (*DeletePushedAuthorizationRequestResponse, error)

	// CleanupExpiredPushedRequests drops every record past its expiry,
	// consumed or not. Production deployments run this on a timer; tests
	// call it directly.
	CleanupExpiredPushedRequests(ctx context.Context, req *CleanupExpiredPushedRequestsRequest) (*CleanupExpiredPushedRequestsResponse, error)
}

type RateLimiter interface {
	// Allow returns true if the operation is permitted for the given key.
	// Returns false if the rate limit has been exceeded.
	Allow(key string) bool
}

type RecordAuthorizationCodeTokensRequest struct {
	Code           string
	TokenID        string
	TokenExpiresAt time.Time
	RefreshFamily  string
}

type RecordAuthorizationCodeTokensResponse struct {
	ReuseDetected bool
}

type RefreshToken struct {
	Token                string                `json:"token"`                           // 64-char hex token value
	TokenHash            string                `json:"token_hash"`                      // SHA256 hash for storage (optional)
	Subject              string                `json:"subject"`                         // Principal the token represents (RFC 7519 sub) — user ID for user-bound tokens, client_id for client_credentials
	ClientID             string                `json:"client_id"`                       // Optional client/app identifier
	DeviceInfo           map[string]any        `json:"device_info"`                     // User agent, IP, etc.
	Family               string                `json:"family"`                          // Token family for rotation tracking
	Generation           int                   `json:"generation"`                      // Increments on rotation
	Scopes               []string              `json:"scopes"`                          // Granted scopes
	AuthorizationDetails []AuthorizationDetail `json:"authorization_details,omitempty"` // RFC 9396
	Confirmation         *Confirmation         `json:"confirmation,omitempty"`          // RFC 9449 §5 sender-constraint; nil = plain bearer
	CreatedAt            time.Time             `json:"created_at"`
	ExpiresAt            time.Time             `json:"expires_at"`
	LastUsedAt           time.Time             `json:"last_used_at"`
	RevokedAt            *time.Time            `json:"revoked_at,omitempty"`
	Revoked              bool                  `json:"revoked"`
}

type RefreshTokenStore interface {
	// CreateRefreshToken creates a new refresh token for the given subject.
	CreateRefreshToken(ctx context.Context, req *CreateRefreshTokenRequest) (*CreateRefreshTokenResponse, error)

	// GetRefreshToken retrieves a refresh token by its value.
	GetRefreshToken(ctx context.Context, req *GetRefreshTokenRequest) (*GetRefreshTokenResponse, error)

	// RotateRefreshToken invalidates old token and creates new one in same family.
	// Returns ErrTokenReused if the old token was already revoked (theft detection),
	// including when a concurrent call rotated it first: only one caller may
	// get a new token. The new token keeps the old one's ExpiresAt, so a family
	// lives at most TokenExpiryRefreshToken from its first issue however often
	// it is refreshed (RFC 9700 §4.14.2).
	RotateRefreshToken(ctx context.Context, req *RotateRefreshTokenRequest) (*RotateRefreshTokenResponse, error)

	// RevokeRefreshToken marks a token as revoked.
	RevokeRefreshToken(ctx context.Context, req *RevokeRefreshTokenRequest) (*RevokeRefreshTokenResponse, error)

	// RevokeSubjectTokens revokes all refresh tokens belonging to a subject.
	RevokeSubjectTokens(ctx context.Context, req *RevokeSubjectTokensRequest) (*RevokeSubjectTokensResponse, error)

	// RevokeTokenFamily revokes all tokens in a family (theft detection).
	RevokeTokenFamily(ctx context.Context, req *RevokeTokenFamilyRequest) (*RevokeTokenFamilyResponse, error)

	// GetSubjectTokens lists all active (non-revoked, non-expired) refresh
	// tokens for a subject.
	GetSubjectTokens(ctx context.Context, req *GetSubjectTokensRequest) (*GetSubjectTokensResponse, error)

	// CleanupExpiredTokens removes expired tokens (for maintenance).
	CleanupExpiredTokens(ctx context.Context, req *CleanupExpiredTokensRequest) (*CleanupExpiredTokensResponse, error)
}

type RevokeAPIKeyRequest struct {
	KeyID string
}

type RevokeAPIKeyResponse struct{}

type RevokeRefreshTokenRequest struct {
	Token string
}

type RevokeRefreshTokenResponse struct{}

type RevokeSubjectTokensRequest struct {
	Subject string
}

type RevokeSubjectTokensResponse struct{}

type RevokeTokenFamilyRequest struct {
	Family string
}

type RevokeTokenFamilyResponse struct{}

type RotateRefreshTokenRequest struct {
	OldToken string
}

type RotateRefreshTokenResponse struct {
	Token *RefreshToken
}

type SaveAppRequest struct {
	App *AppRegistration
}

type SaveAppResponse struct{}

type TokenBlacklist interface {
	// Revoke adds a token ID to the blacklist. The entry should be kept
	// until expiry (when the token would naturally expire anyway).
	Revoke(jti string, expiry time.Time) error

	// IsRevoked returns true if the token ID has been revoked and hasn't expired.
	IsRevoked(jti string) bool
}

type TokenError struct {
	Error            string `json:"error"`
	ErrorDescription string `json:"error_description,omitempty"`
}

type TokenPair struct {
	AccessToken          string                `json:"access_token"`
	TokenType            string                `json:"token_type"` // "Bearer", or "DPoP" when the token is sender-constrained (RFC 9449 §5)
	ExpiresIn            int64                 `json:"expires_in"` // Seconds until access token expires
	RefreshToken         string                `json:"refresh_token,omitempty"`
	Scope                string                `json:"scope,omitempty"`
	AuthorizationDetails []AuthorizationDetail `json:"authorization_details,omitempty"` // RFC 9396

	// IssuedTokenType identifies the type of token issued (RFC 8693 §2.2,
	// REQUIRED for token-exchange responses; absent for other grants).
	// Common values:
	//   urn:ietf:params:oauth:token-type:access_token
	//   urn:ietf:params:oauth:token-type:refresh_token
	//   urn:ietf:params:oauth:token-type:jwt
	IssuedTokenType string `json:"issued_token_type,omitempty"`
}

type TokenRequest struct {
	GrantType            string                `json:"grant_type"`                      // "password", "refresh_token", "client_credentials", "urn:ietf:params:oauth:grant-type:jwt-bearer", "urn:ietf:params:oauth:grant-type:token-exchange"
	Username             string                `json:"username,omitempty"`              // For password grant
	Password             string                `json:"password,omitempty"`              // For password grant
	RefreshToken         string                `json:"refresh_token,omitempty"`         // For refresh_token grant
	Scope                string                `json:"scope,omitempty"`                 // Requested scopes
	ClientID             string                `json:"client_id,omitempty"`             // Client identifier (for client_credentials, optional for others)
	ClientSecret         string                `json:"client_secret,omitempty"`         // Client secret (for client_credentials via client_secret_post)
	AuthorizationDetails []AuthorizationDetail `json:"authorization_details,omitempty"` // RFC 9396

	// Assertion is the signed JWT for grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
	// (RFC 7523 §2.1). The AS validates the assertion against a configured
	// trusted-issuer registry and issues an access token in exchange.
	Assertion string `json:"assertion,omitempty"`

	// DeviceCode is the high-entropy identifier returned by
	// /device/authorize (RFC 8628 §3.2) that the device polls with at
	// grant_type=urn:ietf:params:oauth:grant-type:device_code.
	DeviceCode string `json:"device_code,omitempty"`

	// Code is the high-entropy authorization code returned to the
	// client via the /authorize redirect (RFC 6749 §4.1.2). Sent on
	// grant_type=authorization_code along with CodeVerifier and
	// RedirectURI.
	Code string `json:"code,omitempty"`

	// CodeVerifier is the PKCE verifier (RFC 7636 §4.1) the client
	// committed to via code_challenge at /authorize time. Required on
	// grant_type=authorization_code when the original authorization
	// request included a code_challenge.
	CodeVerifier string `json:"code_verifier,omitempty"`

	// RedirectURI is the verbatim redirect_uri the client used at the
	// /authorize step. RFC 6749 §4.1.3 requires it on the
	// authorization_code redemption so the AS can re-check binding.
	RedirectURI string `json:"redirect_uri,omitempty"`

	// ClientAssertionType + ClientAssertion authenticate the *client*
	// itself — distinct from Assertion (which authenticates the
	// resource owner via the jwt-bearer grant). Per RFC 7521 §4.2 +
	// RFC 7523 §2.2 + OIDC Core §9, ClientAssertionType MUST be
	// "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" and
	// ClientAssertion is a signed JWT with iss == sub == client_id.
	// Used by the private_key_jwt and client_secret_jwt token-endpoint
	// authentication methods.
	ClientAssertionType string `json:"client_assertion_type,omitempty"`
	ClientAssertion     string `json:"client_assertion,omitempty"`

	// SubjectToken / SubjectTokenType / RequestedTokenType / Resource / Audience
	// support grant_type=urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693).
	// SubjectToken is the credential representing the party on whose behalf
	// the request is made; SubjectTokenType identifies its kind (e.g.,
	// urn:ietf:params:oauth:token-type:jwt). RequestedTokenType (optional)
	// identifies the desired output token kind; defaults to access_token.
	SubjectToken       string `json:"subject_token,omitempty"`
	SubjectTokenType   string `json:"subject_token_type,omitempty"`
	RequestedTokenType string `json:"requested_token_type,omitempty"`
	Resource           string `json:"resource,omitempty"`
	Audience           string `json:"audience,omitempty"`
}

type TrustedProxies []netip.Prefix

type UpdateAPIKeyLastUsedRequest struct {
	KeyID string
}

type UpdateAPIKeyLastUsedResponse struct{}

type UpdatePollingStateRequest struct {
	DeviceCode string
	PolledAt   time.Time
	SlowDown   bool
}

type UpdatePollingStateResponse struct {
	Authorization *DeviceAuthorization
}

type ValidateAPIKeyRequest struct {
	FullKey string
}

type ValidateAPIKeyResponse struct {
	APIKey *APIKey
}