oauth

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

type AuthorizeInput struct {
	ResponseType        string `query:"response_type" required:"true" enum:"code,token" doc:"OAuth 2.0 response type"`
	ClientID            string `query:"client_id" required:"true" doc:"Client identifier"`
	RedirectURI         string `query:"redirect_uri" doc:"URI to redirect after authorization"`
	Scope               string `query:"scope" doc:"Space-separated list of requested scopes"`
	State               string `query:"state" doc:"Opaque value for CSRF protection"`
	CodeChallenge       string `query:"code_challenge" doc:"PKCE code challenge"`
	CodeChallengeMethod string `query:"code_challenge_method" enum:"S256,plain" doc:"PKCE code challenge method"`
	Nonce               string `query:"nonce" doc:"OpenID Connect nonce for replay protection"`
}

type AuthorizeOutput struct {
	Location string `header:"Location" doc:"Redirect URI with authorization code or token"`
}

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

type Config struct {
	// Issuer is the OAuth/OIDC issuer URL: the external URL clients use,
	// from which the endpoint URLs DPoP proofs must name are built.
	Issuer string

	// AccessTokenLifespan is the duration access tokens are valid
	AccessTokenLifespan time.Duration

	// RefreshTokenLifespan is the duration refresh tokens are valid
	RefreshTokenLifespan time.Duration

	// AuthCodeLifespan is the duration authorization codes are valid
	AuthCodeLifespan time.Duration

	// PrivateKey is the RSA private key for signing tokens (required). It
	// must be the same on every instance and across restarts: tokens and
	// the JWKS are tied to it.
	PrivateKey *rsa.PrivateKey

	// KeyID is the "kid" of PrivateKey, published in the JWKS and set on
	// every JWT. Default: the RFC 7638 thumbprint of the key.
	//
	// A token's kid selects the key that verifies it: KeyID selects the
	// signing key, a VerificationKeys entry selects that key, and any other
	// kid is refused. Rotate keeping the current key N and the previous
	// key N-1, as for SystemAuth (systemauth.KeyConfig.KeyID):
	//
	//  1. Pre-stage: add the new key N to VerificationKeys while N-1 still
	//     signs, so verifiers pick it up from the JWKS first.
	//  2. Promote: make N PrivateKey, move N-1 into VerificationKeys, and
	//     drop N-2.
	//
	// Never drop N-1 in the deploy that promotes N: tokens it signed are
	// still in use until they expire.
	KeyID string

	// VerificationKeys are keys published in the JWKS and accepted when
	// verifying tokens, but never used to sign: the previous signing key
	// N-1 after a rotation, and a pre-staged next key before it is
	// promoted.
	VerificationKeys []systemauth.VerificationKeyConfig

	// AllowEphemeralKey lets NewProvider generate a fresh signing key when
	// PrivateKey is nil. Development and tests only: the key changes on
	// every start and differs between instances, so tokens stop verifying
	// after a restart.
	AllowEphemeralKey bool

	// JWTAccessTokens issues access tokens as RS256 JWTs (RFC 9068, typ
	// at+jwt) signed with PrivateKey, carrying cnf.jkt when DPoP-bound,
	// instead of opaque tokens. Either way tokens are stored, so
	// revocation and introspection work.
	JWTAccessTokens bool

	// HashSecret is the secret used for HMAC operations
	HashSecret []byte

	// DPoP configures DPoP proof checking (RFC 9449).
	DPoP DPoPConfig
}

type ConsentFunc func(ctx context.Context, userID string, client fosite.Client, scopes []string) (bool, error)

type DPoPConfig struct {
	// ProofMaxAge is how old a proof's iat may be. Default: 5 minutes.
	ProofMaxAge time.Duration

	// ClockSkew is how far a proof's iat may be in the future, and is added
	// to ProofMaxAge. Default: 30 seconds.
	ClockSkew time.Duration

	// ReplayCache rejects a proof whose jti was used before. Default: an
	// in-memory cache, which suits a single instance; when several
	// instances serve the provider, pass one they share, such as
	// middleware.NewRedisReplayCache.
	ReplayCache dpopproof.ReplayCache

	// Nonces, when set, requires every proof to carry a server nonce
	// (RFC 9449 §8); see dpopproof.NewNonces.
	Nonces *dpopproof.Nonces
}

type IntrospectInput struct {
	Token         string `form:"token" required:"true" doc:"The token to introspect"`
	TokenTypeHint string `form:"token_type_hint" enum:"access_token,refresh_token" doc:"Hint about the token type"`

	// Client authentication
	Authorization string `header:"Authorization" doc:"Basic authentication header (client_id:client_secret)"`
}

type IntrospectOutput struct {
	Body IntrospectResponse
}

type IntrospectResponse struct {
	Active    bool   `json:"active" doc:"Whether the token is active"`
	Scope     string `json:"scope,omitempty" doc:"Scopes associated with the token"`
	ClientID  string `json:"client_id,omitempty" doc:"Client that requested the token"`
	Username  string `json:"username,omitempty" doc:"Resource owner username"`
	TokenType string `json:"token_type,omitempty" doc:"Token type"`
	Exp       int64  `json:"exp,omitempty" doc:"Token expiration timestamp"`
	Iat       int64  `json:"iat,omitempty" doc:"Token issue timestamp"`
	Nbf       int64  `json:"nbf,omitempty" doc:"Token not-before timestamp"`
	Sub       string `json:"sub,omitempty" doc:"Subject (user ID)"`
	Aud       string `json:"aud,omitempty" doc:"Intended audience"`
	Iss       string `json:"iss,omitempty" doc:"Token issuer"`
	Jti       string `json:"jti,omitempty" doc:"JWT ID"`
}

type JWK struct {
	Kty string `json:"kty" doc:"Key type (e.g., RSA, EC)"`
	Use string `json:"use,omitempty" doc:"Key use (sig for signature, enc for encryption)"`
	Kid string `json:"kid,omitempty" doc:"Key ID"`
	Alg string `json:"alg,omitempty" doc:"Algorithm"`
	N   string `json:"n,omitempty" doc:"RSA modulus"`
	E   string `json:"e,omitempty" doc:"RSA exponent"`
}

type JWKS struct {
	Keys []JWK `json:"keys" doc:"Array of JSON Web Keys"`
}

type JWKSOutput struct {
	Body JWKS
}

type OAuthError struct {
	Error            string `json:"error" doc:"Error code"`
	ErrorDescription string `json:"error_description,omitempty" doc:"Human-readable error description"`
	ErrorURI         string `json:"error_uri,omitempty" doc:"URI with more information about the error"`
}

type OpenIDConfigOutput struct {
	Body OpenIDConfiguration
}

type OpenIDConfiguration struct {
	Issuer                            string   `json:"issuer" doc:"OAuth 2.0 Issuer Identifier"`
	AuthorizationEndpoint             string   `json:"authorization_endpoint" doc:"URL of the authorization endpoint"`
	TokenEndpoint                     string   `json:"token_endpoint" doc:"URL of the token endpoint"`
	IntrospectionEndpoint             string   `json:"introspection_endpoint" doc:"URL of the introspection endpoint"`
	RevocationEndpoint                string   `json:"revocation_endpoint" doc:"URL of the revocation endpoint"`
	JWKSURI                           string   `json:"jwks_uri" doc:"URL of the JSON Web Key Set document"`
	ResponseTypesSupported            []string `json:"response_types_supported" doc:"List of supported response types"`
	GrantTypesSupported               []string `json:"grant_types_supported" doc:"List of supported grant types"`
	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported" doc:"List of supported token endpoint authentication methods"`
	CodeChallengeMethodsSupported     []string `json:"code_challenge_methods_supported" doc:"List of supported PKCE code challenge methods"`
	DPoPSigningAlgValuesSupported     []string `json:"dpop_signing_alg_values_supported" doc:"JWS algorithms accepted for DPoP proofs (RFC 9449)"`
}

type Option func(*API)

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

type RevokeInput struct {
	Token         string `form:"token" required:"true" doc:"The token to revoke"`
	TokenTypeHint string `form:"token_type_hint" enum:"access_token,refresh_token" doc:"Hint about the token type"`

	// Client authentication
	Authorization string `header:"Authorization" doc:"Basic authentication header (client_id:client_secret)"`
}

type RevokeOutput struct{}

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

type TokenInput struct {
	GrantType    string `form:"grant_type" required:"true" enum:"authorization_code,refresh_token,client_credentials" doc:"OAuth 2.0 grant type"`
	Code         string `form:"code" doc:"Authorization code (for authorization_code grant)"`
	RedirectURI  string `form:"redirect_uri" doc:"Redirect URI (must match authorization request)"`
	ClientID     string `form:"client_id" doc:"Client identifier (if not using Basic auth)"`
	ClientSecret string `form:"client_secret" doc:"Client secret (if not using Basic auth)"`
	RefreshToken string `form:"refresh_token" doc:"Refresh token (for refresh_token grant)"`
	Scope        string `form:"scope" doc:"Requested scopes (for refresh_token or client_credentials)"`
	CodeVerifier string `form:"code_verifier" doc:"PKCE code verifier"`

	// Basic auth credentials (alternative to form-based client auth)
	Authorization string `header:"Authorization" doc:"Basic authentication header (client_id:client_secret)"`
}

type TokenOutput struct {
	Body TokenResponse
}

type TokenResponse struct {
	AccessToken  string `json:"access_token" doc:"The access token"`
	TokenType    string `json:"token_type" doc:"Token type (typically 'Bearer')"`
	ExpiresIn    int    `json:"expires_in,omitempty" doc:"Token lifetime in seconds"`
	RefreshToken string `json:"refresh_token,omitempty" doc:"Refresh token for obtaining new access tokens"`
	Scope        string `json:"scope,omitempty" doc:"Granted scopes (may differ from requested)"`
	IDToken      string `json:"id_token,omitempty" doc:"OpenID Connect ID token"`
}