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 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 CleanupExpiredTokensRequest struct{}

type CleanupExpiredTokensResponse struct{}

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

type CreateAPIKeyResponse struct {
	FullKey string
	APIKey  *APIKey
}

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

type CreateRefreshTokenResponse struct {
	Token *RefreshToken
}

type GetAPIKeyByIDRequest struct {
	KeyID string
}

type GetAPIKeyByIDResponse struct {
	APIKey *APIKey
}

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

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

type ListSubjectAPIKeysRequest struct {
	Subject string
}

type ListSubjectAPIKeysResponse struct {
	APIKeys []*APIKey
}

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 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
	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).
	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 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"
	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"`

	// 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 UpdateAPIKeyLastUsedRequest struct {
	KeyID string
}

type UpdateAPIKeyLastUsedResponse struct{}

type ValidateAPIKeyRequest struct {
	FullKey string
}

type ValidateAPIKeyResponse struct {
	APIKey *APIKey
}