storage

type ClientRegistry interface {
	// ClientManager provides client lookup (GetClient)
	fosite.ClientManager

	// RegisterClient registers a new OAuth client.
	// This supports both static configuration and dynamic client registration (RFC 7591).
	// Returns ErrAlreadyExists if a client with the same ID already exists.
	RegisterClient(ctx context.Context, client fosite.Client) error
}

type Config struct {
	// Type specifies the storage backend type. Defaults to memory.
	Type Type
}

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

type MemoryStorageOption func(*MemoryStorage)

type PendingAuthorization struct {
	// ClientID is the ID of the OAuth client making the authorization request.
	ClientID string

	// RedirectURI is the client's callback URL where we'll redirect after authentication.
	RedirectURI string

	// State is the client's original state parameter for CSRF protection.
	State string

	// PKCEChallenge is the client's PKCE code challenge.
	PKCEChallenge string

	// PKCEMethod is the PKCE challenge method (must be "S256").
	PKCEMethod string

	// Scopes are the OAuth scopes requested by the client.
	Scopes []string

	// InternalState is our randomly generated state for correlating upstream callback.
	InternalState string

	// UpstreamPKCEVerifier is the PKCE code_verifier for the upstream IDP authorization.
	// This is generated when redirecting to the upstream IDP and used when exchanging
	// the authorization code. See RFC 7636.
	UpstreamPKCEVerifier string

	// UpstreamNonce is the OIDC nonce parameter sent to the upstream IDP for ID Token
	// replay protection. This is validated against the nonce claim in the returned
	// ID Token. See OIDC Core Section 3.1.2.1.
	UpstreamNonce string

	// CreatedAt is when the pending authorization was created.
	CreatedAt time.Time
}

type PendingAuthorizationStorage interface {
	// StorePendingAuthorization stores a pending authorization request.
	// The state is used to correlate the upstream IDP callback.
	StorePendingAuthorization(ctx context.Context, state string, pending *PendingAuthorization) error

	// LoadPendingAuthorization retrieves a pending authorization by internal state.
	// Returns ErrNotFound if the state does not exist.
	// Returns ErrExpired if the pending authorization has expired.
	LoadPendingAuthorization(ctx context.Context, state string) (*PendingAuthorization, error)

	// DeletePendingAuthorization removes a pending authorization.
	// Returns ErrNotFound if the state does not exist.
	DeletePendingAuthorization(ctx context.Context, state string) error
}

type ProviderIdentity struct {
	// UserID is the internal user ID this identity belongs to.
	UserID string

	// ProviderID identifies the upstream provider (e.g., "google", "github").
	ProviderID string

	// ProviderSubject is the subject identifier from the upstream provider.
	ProviderSubject string

	// LinkedAt is when this identity was linked to the user.
	LinkedAt time.Time

	// LastUsedAt is when this identity was last used to authenticate.
	LastUsedAt time.Time
}

type RunConfig struct {
	// Type specifies the storage backend type. Defaults to "memory".
	Type string `json:"type,omitempty" yaml:"type,omitempty"`
}

type Stats struct {
	Clients               int
	AuthCodes             int
	AccessTokens          int
	RefreshTokens         int
	PKCERequests          int
	UpstreamTokens        int
	PendingAuthorizations int
	InvalidatedCodes      int
	ClientAssertionJWTs   int
	Users                 int
	ProviderIdentities    int
}

type Storage interface {
	// Embed segregated interfaces for IDP tokens, pending authorizations, client registry,
	// and user management for multi-IDP support.
	UpstreamTokenStorage
	PendingAuthorizationStorage
	ClientRegistry
	UserStorage

	// AuthorizeCodeStorage provides authorization code storage for the Authorization Code
	// Grant (RFC 6749 Section 4.1). Authorization codes are one-time-use and short-lived.
	// CreateAuthorizeCodeSession stores by code, GetAuthorizeCodeSession retrieves by code,
	// InvalidateAuthorizeCodeSession marks as used (subsequent Gets return ErrInvalidatedAuthorizeCode).
	oauth2.AuthorizeCodeStorage

	// AccessTokenStorage provides access token session storage. Methods use "signature"
	// (derived from token value) as the key for O(1) lookup when validating tokens.
	// The stored fosite.Requester contains the full authorization context including
	// the Session with expiration times via session.GetExpiresAt(fosite.AccessToken).
	oauth2.AccessTokenStorage

	// RefreshTokenStorage provides refresh token session storage. CreateRefreshTokenSession
	// accepts an accessSignature to link refresh tokens to their access tokens for rotation.
	// RotateRefreshToken uses requestID to invalidate both the refresh token and all
	// related access tokens from the same authorization grant.
	oauth2.RefreshTokenStorage

	// TokenRevocationStorage provides token revocation per RFC 7009. RevokeAccessToken
	// and RevokeRefreshToken take requestID (not signature) because RFC 7009 requires
	// revoking a refresh token SHOULD also invalidate associated access tokens, which
	// requires finding all tokens by their common grant identifier.
	oauth2.TokenRevocationStorage

	// PKCERequestStorage provides PKCE challenge/verifier storage (RFC 7636).
	// Stores the code_challenge during authorization, validates code_verifier during
	// token exchange. Keyed by the same code/signature as the authorization code.
	pkce.PKCERequestStorage

	// Close releases any resources held by the storage implementation.
	// This should be called when the storage is no longer needed.
	Close() error
}

type Type string

type UpstreamTokenStorage interface {
	// StoreUpstreamTokens stores the upstream IDP tokens for a session.
	StoreUpstreamTokens(ctx context.Context, sessionID string, tokens *UpstreamTokens) error

	// GetUpstreamTokens retrieves the upstream IDP tokens for a session.
	// Returns ErrNotFound if the session does not exist.
	// Returns ErrExpired if the tokens have expired.
	// Returns ErrInvalidBinding if binding validation fails.
	GetUpstreamTokens(ctx context.Context, sessionID string) (*UpstreamTokens, error)

	// DeleteUpstreamTokens removes the upstream IDP tokens for a session.
	// Returns ErrNotFound if the session does not exist.
	DeleteUpstreamTokens(ctx context.Context, sessionID string) error
}

type UpstreamTokens struct {
	// ProviderID identifies which upstream provider issued these tokens.
	// Example values: "google", "github", "okta"
	ProviderID string

	// Token values from the upstream IDP
	AccessToken  string
	RefreshToken string
	IDToken      string
	ExpiresAt    time.Time

	// UserID is the internal ToolHive user ID (references User.ID).
	// This is NOT the upstream provider's subject - it's our stable internal identifier.
	// In multi-IDP scenarios, the same UserID may have tokens from multiple providers.
	UserID string

	// UpstreamSubject is the "sub" claim from the upstream IDP's ID token.
	// This enables validation that tokens match the expected upstream identity
	// and supports audit logging of which upstream identity was used.
	UpstreamSubject string

	// ClientID is the OAuth client that initiated the authorization.
	// Tokens should only be accessible to the same client that obtained them.
	ClientID string
}

type User struct {
	// ID is the internal, stable user identifier (UUID format).
	// This value is used as the "sub" claim in ToolHive-issued JWTs.
	ID string

	// CreatedAt is when the user account was created.
	CreatedAt time.Time

	// UpdatedAt is when the user account was last modified.
	UpdatedAt time.Time
}

type UserStorage interface {
	// CreateUser creates a new user account.
	// Returns ErrAlreadyExists if a user with the same ID already exists.
	CreateUser(ctx context.Context, user *User) error

	// GetUser retrieves a user by their internal ID.
	// Returns ErrNotFound if the user does not exist.
	GetUser(ctx context.Context, id string) (*User, error)

	// DeleteUser removes a user account.
	// Returns ErrNotFound if the user does not exist.
	DeleteUser(ctx context.Context, id string) error

	// CreateProviderIdentity links a provider identity to a user.
	// For account linking scenarios, caller MUST verify user owns the target User
	// (typically via active authenticated session) before linking a new provider.
	// Returns ErrAlreadyExists if this provider identity is already linked.
	CreateProviderIdentity(ctx context.Context, identity *ProviderIdentity) error

	// GetProviderIdentity retrieves a provider identity by provider ID and subject.
	// This is the primary lookup path during authentication callbacks.
	// Returns ErrNotFound if the identity does not exist.
	GetProviderIdentity(ctx context.Context, providerID, providerSubject string) (*ProviderIdentity, error)

	// UpdateProviderIdentityLastUsed updates the LastUsedAt timestamp for a provider identity.
	// This should be called after each successful authentication via this identity.
	// The timestamp supports OIDC auth_time claim when clients use max_age parameter.
	// Returns ErrNotFound if the identity does not exist.
	UpdateProviderIdentityLastUsed(ctx context.Context, providerID, providerSubject string, lastUsedAt time.Time) error

	// GetUserProviderIdentities returns all provider identities linked to a user.
	// This enables queries like "when did this user last authenticate via any provider"
	// which is needed for OIDC max_age enforcement.
	// Returns an empty slice (not error) if the user exists but has no linked identities.
	// Returns ErrNotFound if the user does not exist.
	GetUserProviderIdentities(ctx context.Context, userID string) ([]*ProviderIdentity, error)
}