auth

type APIKeyAuthenticator[T any] struct {
	// contains filtered or unexported fields
}

type APIKeyConfig[T any] struct {
	// Header is the header name used for key extraction.
	// Default: "X-API-Key" when Header and Query are both empty.
	Header string

	// Prefix trims an optional scheme prefix from Header value.
	// Example: "ApiKey" for "Authorization: ApiKey <key>".
	Prefix string

	// Query is an optional query parameter fallback.
	Query string

	// Validator checks whether the extracted key is valid.
	Validator APIKeyValidator[T]
}

type APIKeyValidator[T any] func(key string, r *http.Request) (user T, ok bool, err error)

type Authenticator[T any] interface {
	Authenticate(r *http.Request) (T, error)
}

type BasicAuthenticator[T any] struct {
	// contains filtered or unexported fields
}

type BasicConfig[T any] struct {
	// Validator checks whether username/password are valid.
	Validator BasicValidator[T]

	// Realm is used by BasicErrorHandler for WWW-Authenticate.
	// Default: "Restricted".
	Realm string
}

type BasicValidator[T any] func(username, password string, r *http.Request) (user T, ok bool, err error)

type ErrorFunc func(err error, ctx *credo.Context) error

type JWTAdvanced[T any] struct {
	// KeyFunc overrides SigningKey/SigningKeys selection entirely
	// (e.g. JWKS lookup).
	KeyFunc jwt.Keyfunc

	// NewClaims creates the claims value tokens are parsed into.
	// Default: a JSON object map (jwt.MapClaims).
	NewClaims func() jwt.Claims

	// ParseToken converts a validated *jwt.Token into the user value T,
	// with access to the raw token (header, signature, typed claims).
	// Configuring both ParseToken and JWTConfig.ParseClaims is a
	// constructor error.
	ParseToken func(token *jwt.Token) (T, error)

	// ParserOptions are appended after the options the framework derives
	// from the simple tier, so on conflict the last (advanced) option
	// wins.
	ParserOptions []jwt.ParserOption
}

type JWTAuthenticator[T any] struct {
	// contains filtered or unexported fields
}

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

type JWTConfig[T any] struct {
	// Header is the header name used to read the token.
	// Default: "Authorization".
	Header string

	// Prefix is the token scheme prefix in Header.
	// Default: "Bearer".
	Prefix string

	// Query is an optional query parameter name for token fallback.
	// Example: "token".
	Query string

	// Cookie is an optional cookie name for token fallback.
	// Example: "jwt".
	Cookie string

	// SigningMethod is the expected token alg (e.g. HS256, RS256).
	// Default: HS256.
	SigningMethod string

	// SigningKey is the default key used to validate signatures.
	// It is also used as a fallback when SigningKeys is configured but
	// an incoming token does not include a kid header.
	SigningKey any

	// SigningKeys is an optional key set selected by token header kid.
	// If token kid is present, it must exist in this map.
	SigningKeys map[string]any

	// Issuer, when set, requires the token's iss claim to match exactly.
	Issuer string

	// Audience, when set, requires the token's aud claim to contain AT
	// LEAST ONE of the listed values. This any-of rule is the standard
	// RFC 7519 validator practice: a token may be addressed to several
	// audiences, and the recipient accepts it if it identifies itself
	// with any of them.
	Audience []string

	// Leeway widens time-based claim validation (exp, nbf, iat) by the
	// given duration in both directions, absorbing clock skew between
	// the token issuer and this server.
	Leeway time.Duration

	// RequireExpiry rejects tokens that carry no exp claim. By default
	// (matching golang-jwt v5), exp is validated only when present —
	// a token without exp never expires. Set this when tokens are
	// expected to be short-lived.
	RequireExpiry bool

	// ParseClaims converts the validated token's claims into the user
	// value T. This is the simple-tier counterpart of
	// [JWTAdvanced.ParseToken]; configuring both is a constructor error.
	// When neither is set, the raw claims value is type-asserted to T.
	ParseClaims func(claims JWTClaims) (T, error)

	// Advanced exposes golang-jwt primitives directly. Most applications
	// never need it; see [JWTAdvanced].
	Advanced JWTAdvanced[T]
}