auth

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

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 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 /Health/ 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 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. If empty, SecretEnv is consulted; if
	// SecretEnv is also empty, "JWT_SECRET" is consulted as a last resort.
	Secret string

	// SecretEnv is the environment variable name to read the secret from
	// when Secret is empty. Useful for the canonical config-file shape:
	//
	//   - type: hmac
	//     secret_env: SUPABASE_JWT_SECRET
	SecretEnv 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
}

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

	// AllowDevMode, when true, skips real authentication and injects
	// DevClaims when no Authorization header is present. Only honour this
	// in non-production builds; the constructor does not gate on env.
	AllowDevMode bool

	// DevClaims is injected when AllowDevMode is true and the request has
	// no credentials. Defaults to a non-nil empty *Claims.
	DevClaims *Claims
}

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
}

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, signals JWKS-based key resolution. The current
	// implementation does not auto-fetch JWKS (matching the legacy template
	// behaviour) — callers that need JWKS should populate Secret with a
	// fetched key or supply a KeyFunc.
	JWKSURL string

	// Secret is the symmetric secret (HS*) or PEM-encoded public key
	// (RS*/ES*). When empty the validator falls back to os.Getenv("JWT_SECRET").
	Secret string

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

type KeyValidator interface {
	ValidateKey(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
}