storage

type ActiveRefreshTokenByFamilyStore interface {
	// GetActiveRefreshTokenByFamily returns the most recent (highest
	// generation) non-revoked refresh token for the family along with
	// the owning client ID.
	//
	// Returns ErrRefreshTokenFamilyNotFound when no entry for the family
	// exists in storage at all (never created, or aged out of revoked-
	// family retention). Returns ErrRefreshTokenFamilyRevoked when the
	// family exists but every member is revoked — a distinct state so
	// callers can surface "session was revoked" vs "no such session".
	GetActiveRefreshTokenByFamily(ctx context.Context, familyID string) (refreshToken, clientID string, err error)
}

type AuthorizationCode struct {
	Code        string
	ClientID    string
	RedirectURI string
	Scope       string
	// Resource is the target resource server identifier (RFC 8707)
	// This is carried from the authorization request to bind the token to a specific audience
	Resource string
	// Audience is the intended token audience (resource server identifier)
	// This is used for token validation to prevent token theft across resource servers
	Audience            string
	CodeChallenge       string
	CodeChallengeMethod string
	UserID              string
	ProviderToken       *oauth2.Token // Now uses oauth2.Token directly
	CreatedAt           time.Time
	ExpiresAt           time.Time
	Used                bool
}

type AuthorizationState struct {
	// StateID is used for internal tracking (may be server-generated if client didn't provide state)
	StateID string
	// OriginalClientState is the state parameter the client provided (empty if client didn't provide one)
	// This is returned to the client in the callback redirect
	OriginalClientState string
	ClientID            string
	RedirectURI         string
	Scope               string
	// Resource is the target resource server identifier (RFC 8707)
	// This binds the authorization to a specific resource server
	Resource string
	// Client-to-Server PKCE challenge from MCP client
	CodeChallenge string
	// Client-to-Server PKCE method from MCP client
	CodeChallengeMethod string
	// State parameter sent to provider (different from StateID)
	ProviderState string
	// Server-to-Provider PKCE verifier (OAuth 2.1)
	ProviderCodeVerifier string
	// Nonce is the OIDC nonce forwarded to the upstream IdP. Empty for non-OIDC flows.
	Nonce     string
	CreatedAt time.Time
	ExpiresAt time.Time
}

type Client struct {
	ClientID                string
	ClientSecretHash        string // bcrypt hash
	ClientType              string // "public" or "confidential"
	RedirectURIs            []string
	TokenEndpointAuthMethod string
	GrantTypes              []string
	ResponseTypes           []string
	ClientName              string
	Scopes                  []string
	CreatedAt               time.Time
}

type ClientStore interface {
	// SaveClient saves a registered client
	SaveClient(ctx context.Context, client *Client) error

	// GetClient retrieves a client by ID
	GetClient(ctx context.Context, clientID string) (*Client, error)

	// ValidateClientSecret validates a client's secret
	ValidateClientSecret(ctx context.Context, clientID, clientSecret string) error

	// ListClients lists all registered clients (for admin purposes)
	ListClients(ctx context.Context) ([]*Client, error)

	// CheckIPLimit checks if an IP has reached the client registration limit
	CheckIPLimit(ctx context.Context, ip string, maxClientsPerIP int) error
}

type Combined interface {
	TokenStore
	ClientStore
	FlowStore
}

type FlowStore interface {
	// SaveAuthorizationState saves the state of an ongoing authorization flow
	SaveAuthorizationState(ctx context.Context, state *AuthorizationState) error

	// GetAuthorizationState retrieves an authorization state by client state (StateID).
	// Use this method when validating client-initiated requests where the client
	// provides their original state parameter for CSRF protection.
	GetAuthorizationState(ctx context.Context, stateID string) (*AuthorizationState, error)

	// GetAuthorizationStateByProviderState retrieves an authorization state by provider state.
	// Use this method during provider callback validation when the OAuth provider
	// (Google, GitHub, etc.) returns with the server-generated state parameter.
	GetAuthorizationStateByProviderState(ctx context.Context, providerState string) (*AuthorizationState, error)

	// DeleteAuthorizationState removes an authorization state
	DeleteAuthorizationState(ctx context.Context, stateID string) error

	// SaveAuthorizationCode saves an issued authorization code
	SaveAuthorizationCode(ctx context.Context, code *AuthorizationCode) error

	// GetAuthorizationCode retrieves an authorization code
	GetAuthorizationCode(ctx context.Context, code string) (*AuthorizationCode, error)

	// AtomicCheckAndMarkAuthCodeUsed atomically checks if a code is unused and marks it as used.
	// This prevents race conditions in authorization code reuse detection.
	// Returns the auth code if successful, or an error if:
	// - Code not found
	// - Code expired
	// - Code already used (reuse detected)
	// SECURITY: This operation MUST be atomic to prevent concurrent code exchange attacks.
	AtomicCheckAndMarkAuthCodeUsed(ctx context.Context, code string) (*AuthorizationCode, error)

	// DeleteAuthorizationCode removes an authorization code
	DeleteAuthorizationCode(ctx context.Context, code string) error
}

type RefreshTokenFamilyByIDStore interface {
	// GetRefreshTokenFamilyByID returns the family metadata for the given
	// family ID. Returns ErrRefreshTokenFamilyNotFound when the family is
	// unknown (also for revoked families that have aged out of retention).
	GetRefreshTokenFamilyByID(ctx context.Context, familyID string) (*RefreshTokenFamilyMetadata, error)
}

type RefreshTokenFamilyMetadata struct {
	FamilyID   string
	UserID     string
	ClientID   string
	Generation int
	IssuedAt   time.Time
	Revoked    bool
	RevokedAt  time.Time // When this family was revoked (for forensics and cleanup)
}

type RefreshTokenFamilyStore interface {
	// SaveRefreshTokenWithFamily saves a refresh token with family tracking
	SaveRefreshTokenWithFamily(ctx context.Context, refreshToken, userID, clientID, familyID string, generation int, expiresAt time.Time) error

	// GetRefreshTokenFamily retrieves family metadata for a refresh token
	GetRefreshTokenFamily(ctx context.Context, refreshToken string) (*RefreshTokenFamilyMetadata, error)

	// RevokeRefreshTokenFamily revokes all tokens in a family
	RevokeRefreshTokenFamily(ctx context.Context, familyID string) error
}

type RevokedTokenStore interface {
	// RevokeJTI marks the given JTI as revoked until the supplied
	// expiration. Implementations MUST auto-expire the entry at expiresAt
	// so the denylist stays bounded; an entry persisting past exp would
	// only consume storage with no security value.
	RevokeJTI(ctx context.Context, jti string, expiresAt time.Time) error

	// IsJTIRevoked returns true if the JTI was previously revoked and the
	// entry has not yet expired. Implementations MUST be safe to call from
	// the validation hot path (no per-call allocation outside the lookup).
	IsJTIRevoked(ctx context.Context, jti string) (bool, error)
}

type TokenMetadata struct {
	UserID    string    // User who owns this token
	ClientID  string    // Client who owns this token
	IssuedAt  time.Time // Server-set on write; ignored on input
	TokenType string    // "access" or "refresh"
	Audience  string    // RFC 8707: Intended resource server identifier (for audience validation)
	Scopes    []string  // MCP 2025-11-25: Scopes granted to this token (for scope validation)
	FamilyID  string    // Refresh token family ID for session tracking
}

type TokenMetadataGetter interface {
	GetTokenMetadata(tokenID string) (*TokenMetadata, error)
}

type TokenMetadataStore interface {
	// SaveTokenMetadata persists metadata for the given tokenID.
	// metadata.IssuedAt is ignored on input; implementations populate it
	// from the wall clock at write time so the stored value reflects
	// actual write time and cannot be forged by a caller.
	SaveTokenMetadata(ctx context.Context, tokenID string, metadata TokenMetadata) error
}

type TokenRevocationStore interface {
	// RevokeAllTokensForUserClient revokes all tokens (access + refresh) for a specific user+client combination.
	// This is called when authorization code reuse is detected (OAuth 2.1 requirement).
	// Returns the number of tokens revoked and any error encountered.
	RevokeAllTokensForUserClient(ctx context.Context, userID, clientID string) (int, error)

	// GetTokensByUserClient retrieves all token IDs for a user+client combination (for testing/debugging).
	GetTokensByUserClient(ctx context.Context, userID, clientID string) ([]string, error)
}

type TokenStore interface {
	// SaveToken saves a token for a user
	SaveToken(ctx context.Context, userID string, token *oauth2.Token) error

	// GetToken retrieves a token for a user
	GetToken(ctx context.Context, userID string) (*oauth2.Token, error)

	// DeleteToken removes a token for a user
	DeleteToken(ctx context.Context, userID string) error

	// SaveUserInfo saves user information
	SaveUserInfo(ctx context.Context, userID string, info *providers.UserInfo) error

	// GetUserInfo retrieves user information
	GetUserInfo(ctx context.Context, userID string) (*providers.UserInfo, error)

	// SaveRefreshToken saves a refresh token mapping to user ID with expiry
	SaveRefreshToken(ctx context.Context, refreshToken, userID string, expiresAt time.Time) error

	// GetRefreshTokenInfo retrieves the user ID for a refresh token
	GetRefreshTokenInfo(ctx context.Context, refreshToken string) (string, error)

	// DeleteRefreshToken removes a refresh token
	DeleteRefreshToken(ctx context.Context, refreshToken string) error

	// AtomicGetAndDeleteRefreshToken atomically retrieves and deletes a refresh token.
	// This prevents race conditions in refresh token rotation and reuse detection.
	// Returns the userID, clientID, and provider token if successful, or an error if:
	// - Token not found (may indicate already used/rotated)
	// - Token expired
	// SECURITY: This operation MUST be atomic to prevent concurrent token refresh attacks.
	// SECURITY: Returns clientID for client binding validation per OAuth 2.1 Section 6.
	AtomicGetAndDeleteRefreshToken(ctx context.Context, refreshToken string) (userID string, clientID string, providerToken *oauth2.Token, err error)
}