auth

type APIKeyConfig struct {
	// Header is the HTTP header name carrying the API key.
	// Defaults to "X-API-Key" when empty.
	Header string
}

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

type Claims struct {
	UserID string         `json:"user_id"`
	Email  string         `json:"email"`
	OrgID  string         `json:"org_id"`
	Role   string         `json:"role"`
	Roles  []string       `json:"roles"`
	Raw    map[string]any `json:"raw,omitempty"`
}

type ClerkOpts struct {
	// JWKSURL is the Clerk instance's JWKS endpoint, e.g.
	// https://<your-subdomain>.clerk.accounts.dev/.well-known/jwks.json
	// (typically read from CLERK_JWKS_URL). Required unless KeyFunc is set.
	JWKSURL string

	// Issuer, when set, is enforced (iss). Clerk's issuer is the instance's
	// Frontend API URL, e.g. https://<your-subdomain>.clerk.accounts.dev.
	// Strongly recommended in production so a token minted for a different
	// Clerk instance is rejected.
	Issuer string

	// Audience, when set, is enforced (aud).
	Audience string

	// KeyFunc overrides JWKS fetching. Set it to inject a pre-built keyfunc
	// (tests, or a custom JWKS client); when nil the validator builds one
	// from JWKSURL via [JWKSKeyfunc].
	KeyFunc jwt.Keyfunc
}

type Config struct {
	// Provider is one of "jwt", "api_key", "both", "none". Required.
	Provider string

	// JWT configures JWT validation. Used when Provider is "jwt" or "both".
	JWT JWTConfig

	// APIKey configures API key validation. Used when Provider is
	// "api_key" or "both". A [KeyValidator] must be supplied separately
	// via [Validator.SetKeyValidator] or [Config.KeyValidator].
	APIKey APIKeyConfig

	// SkipMethods is the list of fully-qualified Connect procedure names
	// that bypass auth (in addition to the built-in gRPC health-check skip).
	SkipMethods []string

	// KeyValidator validates API keys. Required when APIKey auth is enabled.
	KeyValidator KeyValidator

	// TokenValidators, when non-empty, replaces the built-in single-secret
	// JWT path with an ordered fallback chain. Each entry validates the
	// bearer token independently; the first to accept wins. Use this when
	// a service must accept tokens from more than one issuer — typically
	// during an auth-provider migration (e.g. Supabase HMAC tokens
	// alongside Auth0 JWKS tokens).
	//
	// When empty the legacy JWT (single secret / JWKSURL) path is used,
	// preserving backwards compatibility for projects that only need one
	// validator.
	TokenValidators []TokenValidator

	// UserResolver, when non-nil, projects the raw decoded JWT payload onto
	// [Claims]. Use it when provider-specific claim shapes (Supabase
	// user_metadata, Auth0 app_metadata, Clerk org_permissions, etc.) need
	// to drive the Claims you hand to downstream code.
	//
	// When nil the validator uses built-in shape extraction (sub, email,
	// org_id, role, roles) and still attaches the full payload to
	// Claims.Raw so downstream code can inspect it.
	UserResolver UserResolver
}

type FirebaseOpts struct {
	// ProjectIDs is the set of accepted Firebase project IDs (typically read
	// from FIREBASE_PROJECT_IDS, comma-separated). A token is accepted only
	// when its aud is one of these AND its iss is
	// securetoken.google.com/<that same project>. At least one is required.
	// Accepting several lets one binary serve clients from multiple Firebase
	// projects.
	ProjectIDs []string

	// KeyFunc overrides Google's JWKS endpoint (tests, or a custom key
	// source). When nil the validator builds one from the well-known
	// Firebase JWKS URL via [JWKSKeyfunc].
	KeyFunc jwt.Keyfunc
}

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

type HMACValidatorConfig struct {
	// SigningMethod is the expected JWT alg (e.g. "HS256"). Required.
	SigningMethod string

	// Secret is the symmetric secret. Required — this package reads no
	// environment variable of its own, so the key a validator trusts is
	// always the key its constructor was handed. Pass it from the app's
	// typed config (declare the field `sensitive: true` and it arrives from
	// the environment's secret provider, never as an inline manifest
	// value); an app accepting several issuers passes each their own.
	Secret string

	// Issuer, when set, is enforced via jwt.WithIssuer.
	Issuer string

	// Audience, when set, is enforced via jwt.WithAudience.
	Audience string

	// Resolver, when non-nil, is given the raw JWT payload so projects can
	// project provider-specific shapes onto [Claims] (and into Claims.Raw).
	// Nil means use the built-in shape extraction.
	Resolver UserResolver

	// RolesClaim names the claim roles are read from; see [JWTConfig.RolesClaim].
	RolesClaim string
}

type InterceptorOptions struct {
	// SkipMethods overrides Config.SkipMethods when non-nil.
	SkipMethods []string
}

type JWKSSnapshot struct {
	// File is a path to a snapshot document. It is re-read when its content
	// changes, so a re-delivery on key rotation needs no restart.
	File string

	// Inline is a snapshot document delivered as a config value (the
	// secret-store path). It is parsed once, at construction.
	Inline string

	// MaxAge bounds how old a snapshot's delivered_at may be. Zero means
	// [DefaultJWKSSnapshotMaxAge].
	MaxAge time.Duration

	// Issuer, when set, must equal the snapshot's issuer member (if the
	// snapshot names one): a snapshot published for another issuer is
	// refused, not merged. [NewValidator] fills it from JWTConfig.Issuer.
	Issuer string
}

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

type JWKSValidatorConfig struct {
	// SigningMethod is the expected JWT alg. Defaults to "RS256".
	SigningMethod string

	// KeyFunc resolves the signing key for the token. Required.
	KeyFunc jwt.Keyfunc

	// Issuer, when set, is enforced via jwt.WithIssuer.
	Issuer string

	// Audience, when set, is enforced via jwt.WithAudience.
	Audience string

	// Resolver, when non-nil, projects the raw JWT payload onto [Claims].
	Resolver UserResolver

	// RolesClaim names the claim roles are read from; see [JWTConfig.RolesClaim].
	RolesClaim string
}

type JWTConfig struct {
	// SigningMethod is the expected JWT alg value (e.g. "HS256", "RS256").
	// Defaults to "RS256" when empty.
	SigningMethod string

	// Issuer, when set, is enforced via jwt.WithIssuer.
	Issuer string

	// Audience, when set, is enforced via jwt.WithAudience.
	Audience string

	// JWKSURL, when set, is the issuer's JWKS endpoint. [NewValidator]
	// fetches it ONCE at construction (so an unreachable or malformed
	// endpoint fails at server boot, not on the first request) and refreshes
	// it in the background for the life of the process — the same
	// [JWKSKeyfunc] machinery [Clerk] and [Firebase] use. This is the path
	// every standard OIDC issuer (Auth0, Keycloak, Zitadel, Supabase, Okta)
	// takes.
	//
	// Mutually exclusive with Secret: two key sources for one validator is a
	// configuration error, and [NewValidator] rejects it rather than picking
	// a winner. A service that must genuinely accept tokens from more than
	// one issuer composes them explicitly via [Config.TokenValidators].
	JWKSURL string

	// JWKSDiscover, when set and JWKSURL is empty, yields the JWKS URL by
	// asking the issuer (OIDC discovery). It runs on EVERY live attempt, so
	// with a [JWKSSnapshot] an issuer that is down at boot — discovery
	// included — still lets the validator start. Same exclusivity as JWKSURL.
	JWKSDiscover func(ctx context.Context) (string, error)

	// JWKSSnapshot is the optional offline fallback key source. With it,
	// an issuer that is unreachable at boot no longer prevents startup when a
	// fresh snapshot exists; see [JWKSSnapshot] for exactly what is trusted.
	// Requires JWKSURL or JWKSDiscover.
	JWKSSnapshot JWKSSnapshot

	// Secret is the symmetric secret (HS*) or PEM-encoded public key
	// (RS*/ES*). Mutually exclusive with JWKSURL.
	Secret string

	// KeyFunc, when non-nil, fully overrides key resolution. Useful for tests
	// and for callers wiring custom JWKS clients.
	KeyFunc jwt.Keyfunc

	// RolesClaim names the claim [Claims.Roles] is read from. Empty or "auto"
	// reads the flat `roles` array and, when the token has none, Zitadel's
	// `urn:zitadel:iam:org:project:<audience>:roles` map (every project's, when
	// Audience is unset). Set it to read exactly one claim: a flat array, a
	// space or comma separated string, or a Zitadel-shaped role map.
	RolesClaim string
}

type KeyValidator interface {
	ValidateKey(ctx context.Context, key string) (*Claims, error)
}

type KeyValidatorFunc func(ctx context.Context, key string) (*Claims, error)

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

type TokenValidator interface {
	// ValidateToken parses tokenString and returns the parsed Claims. The
	// returned error must be non-nil iff the token is invalid for THIS
	// validator. MultiValidator uses error to decide whether to try the
	// next validator in the chain.
	ValidateToken(tokenString string) (*Claims, error)
}

type UserResolver interface {
	// Resolve receives the full decoded JWT payload (as a map, the
	// shape jwt-go hands us) and must return a populated [Claims]. The
	// raw payload should typically be copied onto Claims.Raw so
	// downstream callers can still inspect provider-specific fields.
	Resolve(rawClaims map[string]any) (*Claims, error)
}

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