authserver

type CIMDRunConfig struct {
	// Enabled activates CIMD client lookup when true.
	Enabled bool `json:"enabled" yaml:"enabled"`

	// CacheMaxSize is the maximum number of CIMD documents held in the LRU cache.
	// Defaults to 256 when Enabled is true and this field is zero.
	CacheMaxSize int `json:"cache_max_size,omitempty" yaml:"cache_max_size,omitempty"`

	// CacheFallbackTTL is the fixed TTL applied to every cached CIMD document.
	// Cache-Control header parsing is not yet implemented; all entries use this value.
	// Format: Go duration string (e.g. "5m", "10m", "1h").
	// Defaults to 5 minutes when Enabled is true and this field is omitted.
	CacheFallbackTTL string `json:"cache_fallback_ttl,omitempty" yaml:"cache_fallback_ttl,omitempty" example:"5m"`
}

type Config struct {
	// Issuer is the issuer identifier for this authorization server.
	// This will be included in the "iss" claim of issued tokens.
	Issuer string

	// AuthorizationEndpointBaseURL overrides the base URL used for the authorization_endpoint
	// in the OAuth discovery document. When empty, defaults to Issuer.
	AuthorizationEndpointBaseURL string

	// KeyProvider provides signing keys for JWT operations.
	// Supports key rotation by returning multiple public keys for JWKS.
	// If nil, an ephemeral key will be auto-generated (development only).
	//
	// Production: Use keys.NewFileProvider() or keys.NewProviderFromConfig()
	// Testing: Use a mock or keys.NewGeneratingProvider()
	KeyProvider keys.KeyProvider

	// HMACSecrets contains the symmetric secrets used for signing authorization codes
	// and refresh tokens (opaque tokens). Unlike the asymmetric SigningKey which
	// signs JWTs for distributed verification, these secrets are used internally
	// by the authorization server only.
	// Current secret must be at least 32 bytes and cryptographically random.
	// Must be consistent across all replicas in multi-instance deployments.
	// Supports secret rotation via the Rotated field.
	HMACSecrets *servercrypto.HMACSecrets

	// AccessTokenLifespan is the duration that access tokens are valid.
	// If zero, defaults to 1 hour.
	AccessTokenLifespan time.Duration

	// RefreshTokenLifespan is the duration that refresh tokens are valid.
	// If zero, defaults to 7 days.
	RefreshTokenLifespan time.Duration

	// AuthCodeLifespan is the duration that authorization codes are valid.
	// If zero, defaults to 10 minutes.
	AuthCodeLifespan time.Duration

	// DelegationTokenLifespan is the maximum lifetime for delegated tokens issued
	// via RFC 8693 token exchange. The actual lifetime is the minimum of this value
	// and the subject token's remaining lifetime. If zero, defaults to 15 minutes.
	DelegationTokenLifespan time.Duration

	// Upstreams contains configurations for connecting to upstream IDPs.
	// At least one upstream is required - the server delegates authentication to the upstream IDP.
	// Multiple upstreams form a sequential authorization chain.
	Upstreams []UpstreamConfig

	// UpstreamFactory, when set, is used instead of DefaultUpstreamFactory to
	// construct each configured upstream's OAuth2Provider. Two reasons to set it:
	//
	//   - Connection reuse. DefaultUpstreamFactory builds a private HTTP client
	//     per upstream, so a process that reconstructs the server to change its
	//     upstream set creates a fresh connection pool each time. A factory that
	//     passes a shared client via upstream.WithHTTPClient /
	//     upstream.WithOAuth2HTTPClient creates none. Key the sharing by
	//     distinct trust posture rather than by host: two upstreams can share a
	//     host while differing in CAFilePath, AllowPrivateIPs or
	//     InsecureAllowHTTP. An injected client stays owned by the caller — see
	//     upstream.IdleConnectionCloser — who is then responsible for its pool,
	//     its TLS trust and its dial-time SSRF guard.
	//   - Per-upstream failure isolation. Upstream construction inside New is
	//     otherwise all-or-nothing: one unreachable or mistyped issuer_url fails
	//     the whole call. A factory owning construction can apply a per-upstream
	//     deadline and substitute a provider for a single failing upstream while
	//     the rest serve.
	//
	// The factory cannot drop an upstream: every entry in Upstreams must yield a
	// provider, and returning a nil provider with a nil error is rejected by New
	// rather than producing an upstream that panics on the first authorization
	// request. To serve without an upstream, omit it from Upstreams; to keep its
	// slot in the chain, return a substitute provider.
	//
	// SECURITY: the returned provider validates the upstream's ID tokens and
	// resolves user identity. A factory that returns a permissive provider
	// bypasses upstream authentication for that leg of the chain. Delegate to
	// DefaultUpstreamFactory for upstreams you do not need to customize.
	UpstreamFactory UpstreamProviderFactory

	// UpstreamFilter, when set, narrows the upstream authorization chain after the
	// first leg resolves (see handlers.WithUpstreamFilter). When nil, all
	// configured upstreams are walked — the current behavior. Pass nil itself,
	// not a nil-valued concrete pointer implementing UpstreamFilter — a typed-nil
	// interface value is non-nil and will still be wired in. Has no effect with
	// fewer than 2 configured upstreams; Validate rejects that combination.
	UpstreamFilter handlers.UpstreamFilter

	// ScopesSupported lists the OAuth 2.0 scope values advertised in discovery documents.
	// If nil or empty, defaults to registration.DefaultScopes (["openid", "profile", "email", "offline_access"]).
	// This is advertised in /.well-known/openid-configuration and
	// /.well-known/oauth-authorization-server discovery endpoints.
	ScopesSupported []string

	// BaselineClientScopes is a baseline set of OAuth 2.0 scopes the embedded
	// DCR handler unions into every newly registered client's scope set. Empty
	// means current behavior is preserved (DCR registers exactly what the client
	// requested, or the intersection of registration.DefaultScopes with
	// ScopesSupported if the client requested none).
	// All entries must also be present in ScopesSupported. When ScopesSupported
	// is empty, the validation gate uses registration.DefaultScopes as the
	// superset — so standard OIDC scopes (e.g. "offline_access") work without
	// enumerating ScopesSupported explicitly.
	BaselineClientScopes []string

	// AllowedAudiences is the list of valid resource URIs that tokens can be issued for.
	// Per RFC 8707, the "resource" parameter in authorization and token requests is
	// validated against this list. MCP clients are required to include the resource
	// parameter, so this should be configured with the canonical URIs of all MCP servers
	// this authorization server issues tokens for.
	//
	// Security: An empty list means NO audiences are permitted (secure default).
	// When empty, any request with a "resource" parameter will be rejected with
	// "invalid_target". Configure this for proper MCP specification compliance.
	AllowedAudiences []string

	// CIMDEnabled enables the CIMD storage decorator so the authorization server
	// accepts HTTPS URLs as client_id values without prior DCR registration.
	//
	// A resolved CIMD client is write-through persisted into the underlying
	// storage (see CIMDStorageDecorator.fetch) so that token-endpoint session
	// rehydration finds it. That row is marked DCR-issued and therefore
	// expires (DefaultDCRClientTTL, currently 30 days), but disabling
	// CIMDEnabled does not itself evict or invalidate any row a prior enabled
	// period already persisted — GetClient is instead wrapped to refuse any
	// URL-shaped client_id outright while CIMDEnabled is false (see
	// decorateStorageForCIMD / storage.NewCIMDShapeGuardStorage), so such a
	// row simply cannot be resolved for as long as CIMD stays disabled.
	// Re-enabling CIMDEnabled before that TTL expires makes the stale
	// snapshot resolvable again without a fresh document fetch, until the row
	// expires or a new fetch overwrites it. Document rotation and revocation
	// generally follow the same rule: an existing persisted row keeps
	// authenticating from its stored snapshot, with no re-validation of
	// scopes, redirect URIs, or auth method, until it is naturally re-fetched
	// or its TTL lapses.
	CIMDEnabled bool

	// CIMDCacheMaxSize is the maximum number of CIMD documents held in the LRU
	// cache. Zero is replaced by a default (256) in applyDefaults when CIMDEnabled
	// is true.
	CIMDCacheMaxSize int

	// CIMDCacheFallbackTTL is the fixed TTL applied to all cached CIMD documents
	// (Cache-Control header parsing is not yet implemented). Zero is replaced by
	// a default (5 minutes) in applyDefaults when CIMDEnabled is true.
	CIMDCacheFallbackTTL time.Duration

	// InsecureAllowHTTP permits an http:// issuer URL for non-localhost hosts.
	// Only set this for in-cluster Kubernetes deployments on a trusted network.
	// Production deployments reachable outside the cluster MUST use https://.
	InsecureAllowHTTP bool

	// TrustedIssuers lists external OIDC issuers whose tokens are accepted as
	// RFC 8693 subject tokens or RFC 7523 JWT-bearer assertions. See the
	// identically named field on RunConfig for the full doc comment, including
	// the fail-closed AllowedActors semantics and the audience/scope constraints
	// operators must account for.
	TrustedIssuers []tokenexchange.TrustedIssuer

	// AllowConfidentialClientRegistration permits DCR of confidential clients
	// (client_secret_basic / client_secret_post). See RunConfig for the full
	// semantics; disabling it does not revoke already-minted secrets.
	AllowConfidentialClientRegistration bool

	// AllowPrivateKeyJWTRegistration permits DCR of clients using
	// private_key_jwt authentication. See RunConfig for the full semantics.
	AllowPrivateKeyJWTRegistration bool

	// ForceConfidentialRedirectURIs lists redirect URIs that are always
	// registered as confidential clients, even when the DCR request declares
	// "none". See the identically named field on RunConfig for the full
	// semantics and rationale.
	ForceConfidentialRedirectURIs []string

	// InsecureAllowConfidentialOverLoopbackHTTP opts in to confidential clients
	// when Issuer is a plain-HTTP loopback URL. See the identically named field
	// on RunConfig for the full semantics and rationale.
	InsecureAllowConfidentialOverLoopbackHTTP bool

	// DelegateClients are pre-provisioned confidential OAuth clients in their
	// resolved runtime form. ClientSecret has already been read from its file
	// or environment-variable reference. See RunConfig.DelegateClients for the
	// serialized configuration.
	DelegateClients []DelegateClient

	// DisableTokenExchange prevents registration and advertisement of the RFC
	// 8693 grant. The zero value preserves the released behavior. It is set only
	// when canonical inbound_grants explicitly omits token_exchange.
	DisableTokenExchange bool

	// SPIFFETrust is the validated, immutable runtime SPIFFE trust model. It
	// must be constructed with NewSPIFFETrustConfig; a nil value means no
	// SPIFFE associations are configured. The serialized declarations live on
	// RunConfig and are converted at the RunConfig-to-Config boundary.
	SPIFFETrust *SPIFFETrustConfig
}

type DCRUpstreamConfig struct {
	// DiscoveryURL is the exact RFC 8414 / OIDC Discovery document URL to
	// fetch at runtime. The resolver issues a single GET against this URL
	// (no well-known-path fallback) and reads registration_endpoint,
	// authorization_endpoint, token_endpoint,
	// token_endpoint_auth_methods_supported, and scopes_supported from the
	// response. Per RFC 8414 §3.3, the document's "issuer" field must
	// exactly match the upstream issuer configured on the parent
	// run-config.
	//
	// Use this field when the upstream publishes discovery metadata at a
	// path that differs from the issuer-derived well-known paths — for
	// example a multi-tenant IdP whose metadata lives at
	// https://idp.example.com/tenants/acme/.well-known/openid-configuration.
	//
	// Mutually exclusive with RegistrationEndpoint.
	DiscoveryURL string `json:"discovery_url,omitempty" yaml:"discovery_url,omitempty"`

	// RegistrationEndpoint is the RFC 7591 registration endpoint URL used
	// directly, bypassing discovery. Because no discovery is performed,
	// server-capability fields (token_endpoint_auth_methods_supported,
	// scopes_supported) are unavailable on this code path; the caller is
	// expected to also supply AuthorizationEndpoint, TokenEndpoint, and an
	// explicit Scopes list on the parent OAuth2UpstreamRunConfig. Auth
	// method falls back to the resolver's default (client_secret_basic).
	//
	// Mutually exclusive with DiscoveryURL.
	RegistrationEndpoint string `json:"registration_endpoint,omitempty" yaml:"registration_endpoint,omitempty"`

	// InitialAccessTokenFile is the path to a file containing the RFC 7591
	// initial access token presented to the registration endpoint. Mutually
	// exclusive with InitialAccessTokenEnvVar. Both may be omitted for open
	// registration endpoints.
	//nolint:lll // field tags require full JSON+YAML names
	InitialAccessTokenFile string `json:"initial_access_token_file,omitempty" yaml:"initial_access_token_file,omitempty"`

	// InitialAccessTokenEnvVar is the name of an environment variable
	// containing the RFC 7591 initial access token. Mutually exclusive with
	// InitialAccessTokenFile.
	//nolint:lll // field tags require full JSON+YAML names
	InitialAccessTokenEnvVar string `json:"initial_access_token_env_var,omitempty" yaml:"initial_access_token_env_var,omitempty"`

	// SoftwareID is the RFC 7591 "software_id" registration metadata value,
	// identifying the client software independent of any particular
	// registration instance.
	SoftwareID string `json:"software_id,omitempty" yaml:"software_id,omitempty"`

	// SoftwareStatement is the RFC 7591 "software_statement" JWT asserting
	// metadata about the client software, signed by a party the authorization
	// server trusts.
	SoftwareStatement string `json:"software_statement,omitempty" yaml:"software_statement,omitempty"`
}

type DelegateClient struct {
	// ClientID is the OAuth client_id this client presents at the token endpoint.
	ClientID string

	// ClientSecret is the resolved (plaintext) client secret.
	ClientSecret string //nolint:gosec // G117: field legitimately holds sensitive data

	// Scopes are the OAuth scopes this client may request.
	Scopes []string

	// Audiences are the RFC 8707 resource values this client may request a token for.
	Audiences []string
}

type DelegateClientRunConfig struct {
	// ClientID is the OAuth client_id this client presents at the token endpoint.
	ClientID string `json:"client_id" yaml:"client_id"`

	// ClientSecretFile is the path to a file containing the client secret.
	// If both this and ClientSecretEnvVar are set, the file takes precedence.
	ClientSecretFile string `json:"client_secret_file,omitempty" yaml:"client_secret_file,omitempty"`

	// ClientSecretEnvVar is the name of an environment variable containing
	// the client secret. One of ClientSecretFile or ClientSecretEnvVar is
	// required.
	//nolint:lll // field tags require full JSON+YAML names
	ClientSecretEnvVar string `json:"client_secret_env_var,omitempty" yaml:"client_secret_env_var,omitempty"`

	// Scopes are the OAuth scopes this client may request. Required, and
	// must be a subset of RunConfig.ScopesSupported: a declared client must
	// not receive every supported scope just because this was left empty.
	Scopes []string `json:"scopes" yaml:"scopes"`

	// Audiences are the RFC 8707 resource values this client may request a
	// token for. Required, and must be a subset of RunConfig.AllowedAudiences:
	// a declared client must not receive every allowed audience just because
	// this was left empty.
	Audiences []string `json:"audiences" yaml:"audiences"`
}

type DeprecatedFieldPath struct {
	Path        string
	Replacement string
}

type IdentityFromTokenRunConfig struct {
	// SubjectPath is the dot-notation path to the subject (user ID) field.
	// Required when IdentityFromToken is set.
	SubjectPath string `json:"subject_path" yaml:"subject_path"`

	// NamePath is the dot-notation path to the display name field.
	NamePath string `json:"name_path,omitempty" yaml:"name_path,omitempty"`

	// EmailPath is the dot-notation path to the email address field.
	EmailPath string `json:"email_path,omitempty" yaml:"email_path,omitempty"`
}

type InboundGrantCapabilities struct {
	TokenExchange bool
	JWTBearer     bool
}

type InboundGrantsRunConfig struct {
	// SPIFFEClientAuth associates SPIFFE principal patterns with explicit OAuth
	// client identities and permissions. See SPIFFEClientAuthRunConfig.
	SPIFFEClientAuth []SPIFFEClientAuthRunConfig `json:"spiffe_client_auth,omitempty" yaml:"spiffe_client_auth,omitempty"`

	// TokenExchange configures RFC 8693 inbound clients and issuer policies.
	TokenExchange *TokenExchangeInboundGrantRunConfig `json:"token_exchange,omitempty" yaml:"token_exchange,omitempty"`

	// JWTBearer configures RFC 7523 issuer policies.
	JWTBearer *JWTBearerInboundGrantRunConfig `json:"jwt_bearer,omitempty" yaml:"jwt_bearer,omitempty"`
}

type JWTBearerInboundGrantRunConfig struct {
	IssuerPolicies []JWTBearerIssuerPolicyRunConfig `json:"issuer_policies,omitempty" yaml:"issuer_policies,omitempty"`
}

type JWTBearerIssuerPolicyRunConfig struct {
	IssuerRef         string                       `json:"issuer_ref" yaml:"issuer_ref"`
	MaxAssertionAge   string                       `json:"max_assertion_age" yaml:"max_assertion_age"`
	SubjectBindings   []tx.JWTBearerSubjectBinding `json:"subject_bindings" yaml:"subject_bindings"`
	AcceptedAudiences []string                     `json:"accepted_audiences,omitempty" yaml:"accepted_audiences,omitempty"`
}

type NormalizedInboundGrants struct {
	DelegateClients  []DelegateClientRunConfig
	TrustedIssuers   []tx.TrustedIssuer
	Capabilities     InboundGrantCapabilities
	DeprecatedFields []DeprecatedFieldPath
}

type OAuth2UpstreamRunConfig struct {
	// AuthorizationEndpoint is the URL for the OAuth authorization endpoint.
	AuthorizationEndpoint string `json:"authorization_endpoint" yaml:"authorization_endpoint"`

	// TokenEndpoint is the URL for the OAuth token endpoint.
	TokenEndpoint string `json:"token_endpoint" yaml:"token_endpoint"`

	// ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.
	// Mutually exclusive with DCRConfig: when DCRConfig is set, ClientID is obtained
	// at runtime via RFC 7591 Dynamic Client Registration and must be left empty.
	ClientID string `json:"client_id" yaml:"client_id"`

	// ClientSecretFile is the path to a file containing the OAuth 2.0 client secret.
	// Mutually exclusive with ClientSecretEnvVar. Optional for public clients using PKCE.
	ClientSecretFile string `json:"client_secret_file,omitempty" yaml:"client_secret_file,omitempty"`

	// ClientSecretEnvVar is the name of an environment variable containing the client secret.
	// Mutually exclusive with ClientSecretFile. Optional for public clients using PKCE.
	ClientSecretEnvVar string `json:"client_secret_env_var,omitempty" yaml:"client_secret_env_var,omitempty"`

	// RedirectURI is the callback URL where the upstream IDP will redirect after authentication.
	// When not specified, defaults to `{issuer}/oauth/callback`.
	RedirectURI string `json:"redirect_uri,omitempty" yaml:"redirect_uri,omitempty"`

	// Scopes are the OAuth scopes to request from the upstream IDP.
	Scopes []string `json:"scopes,omitempty" yaml:"scopes,omitempty"`

	// UserInfo contains configuration for fetching user information.
	// Optional: when nil, the upstream OAuth2 provider derives a deterministic
	// subject by SHA-256-hashing the access token (with a "tk-" prefix) instead
	// of calling a userinfo endpoint. OIDC providers always derive Subject from
	// the ID token and are unaffected.
	UserInfo *UserInfoRunConfig `json:"userinfo,omitempty" yaml:"userinfo,omitempty"`

	// TokenResponseMapping configures custom field extraction from non-standard token responses.
	// When set, the token exchange bypasses golang.org/x/oauth2 and extracts fields using
	// the configured dot-notation paths.
	//nolint:lll // field tags require full JSON+YAML names
	TokenResponseMapping *TokenResponseMappingRunConfig `json:"token_response_mapping,omitempty" yaml:"token_response_mapping,omitempty"`

	// IdentityFromToken extracts user identity (subject, name, email) directly from the
	// OAuth2 token-endpoint response body using gjson dot-notation paths. When set, the
	// embedded auth server skips the userinfo HTTP call entirely. Mirrors the CRD type
	// (cmd/thv-operator/api/v1beta1.IdentityFromTokenConfig) — the authoritative
	// trust-model and uniqueness documentation lives there.
	//nolint:lll // field tags require full JSON+YAML names
	IdentityFromToken *IdentityFromTokenRunConfig `json:"identity_from_token,omitempty" yaml:"identity_from_token,omitempty"`

	// AdditionalAuthorizationParams are extra query parameters to include in
	// authorization requests. Useful for provider-specific parameters like
	// Google's access_type=offline.
	//nolint:lll // field tags require full JSON+YAML names
	AdditionalAuthorizationParams map[string]string `json:"additional_authorization_params,omitempty" yaml:"additional_authorization_params,omitempty"`

	// DCRConfig enables RFC 7591 Dynamic Client Registration against the
	// upstream authorization server. When set, the client credentials are
	// obtained at runtime rather than being pre-provisioned via ClientID /
	// ClientSecretFile / ClientSecretEnvVar, and ClientID must be left empty.
	// Mutually exclusive with ClientID.
	DCRConfig *DCRUpstreamConfig `json:"dcr_config,omitempty" yaml:"dcr_config,omitempty"`

	// CAFilePath is the path to a PEM CA bundle added to the system roots.
	CAFilePath string `json:"ca_file_path,omitempty" yaml:"ca_file_path,omitempty"`

	// AllowPrivateIPs permits the upstream provider's HTTP client to connect to
	// private IP ranges (RFC-1918, link-local). When DCRConfig is set, this
	// also gates the DCR discovery and registration calls made on this
	// upstream's behalf (see pkg/authserver/runner/dcr_adapter.go), so a
	// single flag covers the whole upstream rather than needing a separate
	// DCR-specific setting. Use only when the upstream is hosted inside the
	// same cluster and has no public endpoint. HTTP-scheme restrictions are
	// unchanged — HTTPS is still required for non-localhost hosts. Defaults
	// to false.
	AllowPrivateIPs bool `json:"allow_private_ips,omitempty" yaml:"allow_private_ips,omitempty"`

	// InsecureAllowHTTP permits plain-HTTP authorization and token endpoint URLs
	// for this upstream. Only for in-cluster development environments (e.g. an
	// OAuth2 provider served over HTTP in a kind cluster) where TLS is not
	// available. Never set this in production.
	//nolint:lll // field tags require full JSON+YAML names
	InsecureAllowHTTP bool `json:"insecure_allow_http,omitempty" yaml:"insecure_allow_http,omitempty"`
}

type OIDCUpstreamRunConfig struct {
	// IssuerURL is the OIDC issuer URL for automatic endpoint discovery.
	// Must be a valid HTTPS URL.
	IssuerURL string `json:"issuer_url" yaml:"issuer_url"`

	// ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.
	ClientID string `json:"client_id" yaml:"client_id"`

	// ClientSecretFile is the path to a file containing the OAuth 2.0 client secret.
	// Mutually exclusive with ClientSecretEnvVar. Optional for public clients using PKCE.
	ClientSecretFile string `json:"client_secret_file,omitempty" yaml:"client_secret_file,omitempty"`

	// ClientSecretEnvVar is the name of an environment variable containing the client secret.
	// Mutually exclusive with ClientSecretFile. Optional for public clients using PKCE.
	ClientSecretEnvVar string `json:"client_secret_env_var,omitempty" yaml:"client_secret_env_var,omitempty"`

	// RedirectURI is the callback URL where the upstream IDP will redirect after authentication.
	// When not specified, defaults to `{issuer}/oauth/callback`.
	RedirectURI string `json:"redirect_uri,omitempty" yaml:"redirect_uri,omitempty"`

	// Scopes are the OAuth scopes to request from the upstream IDP.
	// If not specified, defaults to ["openid", "offline_access"].
	// When using AdditionalAuthorizationParams with provider-specific refresh
	// token mechanisms (e.g., Google's access_type=offline), set explicit scopes
	// to avoid sending both offline_access and the provider-specific parameter.
	Scopes []string `json:"scopes,omitempty" yaml:"scopes,omitempty"`

	// UserInfoOverride allows customizing UserInfo fetching behavior for OIDC providers.
	// By default, the UserInfo endpoint is discovered automatically via OIDC discovery.
	UserInfoOverride *UserInfoRunConfig `json:"userinfo_override,omitempty" yaml:"userinfo_override,omitempty"`

	// AdditionalAuthorizationParams are extra query parameters to include in
	// authorization requests. Useful for provider-specific parameters like
	// Google's access_type=offline.
	//nolint:lll // field tags require full JSON+YAML names
	AdditionalAuthorizationParams map[string]string `json:"additional_authorization_params,omitempty" yaml:"additional_authorization_params,omitempty"`

	// SubjectClaim names the validated ID-token claim to use as the upstream
	// subject. Defaults to "sub" when empty. Set for IdPs where "sub" isn't
	// stable per user (e.g. Entra/Azure AD's "oid"). See upstream.OIDCConfig.
	SubjectClaim string `json:"subject_claim,omitempty" yaml:"subject_claim,omitempty"`

	// CAFilePath is the path to a PEM CA bundle added to the system roots.
	CAFilePath string `json:"ca_file_path,omitempty" yaml:"ca_file_path,omitempty"`

	// AllowPrivateIPs permits the OIDC discovery and token HTTP clients to
	// connect to private IP ranges (RFC-1918, link-local). Use only when the
	// upstream is hosted inside the same cluster and has no public endpoint.
	// HTTP-scheme restrictions are unchanged — HTTPS is still required for
	// non-localhost hosts. Defaults to false.
	AllowPrivateIPs bool `json:"allow_private_ips,omitempty" yaml:"allow_private_ips,omitempty"`

	// InsecureAllowHTTP permits a plain-HTTP issuer URL and HTTP discovery
	// endpoints for this upstream. Only for in-cluster development environments
	// (e.g. Dex served over HTTP in a kind cluster) where TLS is not available.
	// Never set this in production.
	//nolint:lll // field tags require full JSON+YAML names
	InsecureAllowHTTP bool `json:"insecure_allow_http,omitempty" yaml:"insecure_allow_http,omitempty"`
}

type RunConfig struct {
	// SchemaVersion is the version of the RunConfig schema.
	SchemaVersion string `json:"schema_version" yaml:"schema_version"`

	// Issuer is the issuer identifier for this authorization server.
	// This will be included in the "iss" claim of issued tokens.
	// Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash.
	Issuer string `json:"issuer" yaml:"issuer"`

	// AuthorizationEndpointBaseURL overrides the base URL used for the authorization_endpoint
	// in the OAuth discovery document. When set, the discovery document will advertise
	// `{authorization_endpoint_base_url}/oauth/authorize` instead of `{issuer}/oauth/authorize`.
	// All other endpoints remain derived from the issuer.
	//nolint:lll // field tags require full JSON+YAML names
	AuthorizationEndpointBaseURL string `json:"authorization_endpoint_base_url,omitempty" yaml:"authorization_endpoint_base_url,omitempty"`

	// SigningKeyConfig configures the signing key provider for JWT operations.
	// If nil or empty, an ephemeral signing key will be auto-generated (development only).
	SigningKeyConfig *SigningKeyRunConfig `json:"signing_key_config,omitempty" yaml:"signing_key_config,omitempty"`

	// HMACSecretFiles contains file paths to HMAC secrets for signing authorization codes
	// and refresh tokens (opaque tokens).
	// First file is the current secret (must be at least 32 bytes), subsequent files
	// are for rotation/verification of existing tokens.
	// If empty, an ephemeral secret will be auto-generated (development only).
	HMACSecretFiles []string `json:"hmac_secret_files,omitempty" yaml:"hmac_secret_files,omitempty"`

	// TokenLifespans configures the duration that various tokens are valid.
	// If nil, defaults are applied (access: 1h, refresh: 7d, authCode: 10m).
	TokenLifespans *TokenLifespanRunConfig `json:"token_lifespans,omitempty" yaml:"token_lifespans,omitempty"`

	// DelegationTokenLifespan is the maximum lifetime for delegated tokens issued
	// via RFC 8693 token exchange. Specified as a Go duration string (e.g., "15m").
	// If empty, defaults to 15 minutes.
	DelegationTokenLifespan string `json:"delegation_token_lifespan,omitempty" yaml:"delegation_token_lifespan,omitempty"`

	// Upstreams configures connections to upstream Identity Providers for
	// interactive authorization. It may be empty only when DelegateClients or a
	// TrustedIssuer with JWTBearerGrant enables token-only operation.
	// Multiple upstreams are supported for sequential authorization chains.
	Upstreams []UpstreamRunConfig `json:"upstreams" yaml:"upstreams"`

	// ScopesSupported lists the OAuth 2.0 scope values advertised in discovery documents.
	// If empty, defaults to registration.DefaultScopes (["openid", "profile", "email", "offline_access"]).
	ScopesSupported []string `json:"scopes_supported,omitempty" yaml:"scopes_supported,omitempty"`

	// BaselineClientScopes is a baseline set of OAuth 2.0 scopes unioned into every
	// DCR registration. All values must appear in ScopesSupported; the auth server
	// rejects this RunConfig at startup otherwise. Empty means current behavior is
	// preserved (registered scope = client-requested, or the intersection of
	// DefaultScopes with ScopesSupported if the client requested none).
	// When ScopesSupported is empty, the subset check uses registration.DefaultScopes
	// (the same set applyDefaults would substitute at startup) — so
	// BaselineClientScopes containing standard OIDC scopes works without enumerating
	// ScopesSupported explicitly.
	//nolint:lll // field tags require full JSON+YAML names
	BaselineClientScopes []string `json:"baseline_client_scopes,omitempty" yaml:"baseline_client_scopes,omitempty"`

	// AllowedAudiences is the list of valid resource URIs that tokens can be issued for.
	// Per RFC 8707, the "resource" parameter in authorization and token requests is
	// validated against this list. Required for MCP compliance.
	AllowedAudiences []string `json:"allowed_audiences" yaml:"allowed_audiences"`

	// Storage configures the storage backend for the auth server.
	// If nil, defaults to in-memory storage.
	Storage *storage.RunConfig `json:"storage,omitempty" yaml:"storage,omitempty"`

	// DisableUpstreamTokenInjection prevents the upstream swap middleware from being added.
	// When true, the embedded auth server handles OAuth flows for clients, but instead of
	// injecting upstream IdP tokens the proxy strips the client's credential headers
	// (Authorization, Cookie, Proxy-Authorization) after the JWT is validated — the
	// backend receives an unauthenticated request. Incompatible with token exchange
	// and AWS STS, which would re-add credentials after the strip.
	//nolint:lll // field tags require full JSON+YAML names
	DisableUpstreamTokenInjection bool `json:"disable_upstream_token_injection,omitempty" yaml:"disable_upstream_token_injection,omitempty"`

	// CIMD controls client_id metadata document support. When enabled, the
	// embedded authorization server accepts HTTPS URLs as client_id values
	// and resolves them via the CIMD protocol instead of requiring DCR.
	CIMD *CIMDRunConfig `json:"cimd,omitempty" yaml:"cimd,omitempty"`

	// InsecureAllowHTTP permits an http:// issuer URL for non-localhost hosts.
	// Only set this for in-cluster Kubernetes deployments on a trusted network.
	// Production deployments reachable outside the cluster MUST use https://.
	//nolint:lll // field tags require full JSON+YAML names
	InsecureAllowHTTP bool `json:"insecure_allow_http,omitempty" yaml:"insecure_allow_http,omitempty"`

	// TrustedIssuers lists external OIDC trust declarations.
	//
	// This legacy field is deprecated; RFC 8693 and JWT-bearer policies embedded in these entries
	// remain supported for compatibility. New configurations should put policy
	// under InboundGrants and reference a named trusted issuer.
	//
	// See tokenexchange.TrustedIssuer for the per-issuer field reference, and
	// docs/arch/17-token-exchange-delegation.md for the trust model, consent
	// signals, and operator-facing constraints (audience/scope bounding,
	// subject namespace qualification, required client binding) that aren't
	// visible from the config shape alone.
	//nolint:lll // field tags require full JSON+YAML names
	TrustedIssuers []tokenexchange.TrustedIssuer `json:"trusted_issuers,omitempty" yaml:"trusted_issuers,omitempty"`

	// AllowConfidentialClientRegistration permits Dynamic Client Registration
	// of confidential clients: when true, /oauth/register accepts
	// token_endpoint_auth_method values client_secret_basic and
	// client_secret_post in addition to "none" (still the default on
	// omission) and mints a client_secret returned exactly once. Confidential
	// clients are restricted to https non-loopback redirect URIs, and
	// registrations idle for more than DefaultDCRClientTTL (30 days) are
	// evicted and must re-register. This gates registration only: disabling
	// it does not revoke or reject already-minted secrets at the token
	// endpoint.
	//
	// Security: /oauth/register is unauthenticated, so this issues client
	// secrets to any caller. Combining it with InsecureAllowHTTP is rejected
	// by Validate.
	//nolint:lll // field tags require full JSON+YAML names
	AllowConfidentialClientRegistration bool `json:"allow_confidential_client_registration,omitempty" yaml:"allow_confidential_client_registration,omitempty"`

	// AllowPrivateKeyJWTRegistration permits Dynamic Client Registration of
	// clients using private_key_jwt authentication. This is independent of
	// AllowConfidentialClientRegistration and defaults to false. Registration
	// behavior is controlled independently by the DCR handler and discovery
	// metadata.
	//
	// Security: /oauth/register is unauthenticated. Unlike
	// AllowConfidentialClientRegistration, this is NOT rejected when combined
	// with InsecureAllowHTTP: registration never returns a secret for a
	// private_key_jwt client, so there is nothing for cleartext HTTP to
	// expose.
	//nolint:lll // field tags require full JSON+YAML names
	AllowPrivateKeyJWTRegistration bool `json:"allow_private_key_jwt_registration,omitempty" yaml:"allow_private_key_jwt_registration,omitempty"`

	// ForceConfidentialRedirectURIs lists redirect URIs that must be registered
	// as confidential clients regardless of the token_endpoint_auth_method the
	// DCR request declares. A registration whose redirect_uris contains an
	// EXACT match for one of these entries is issued a real client_secret and
	// reported back as token_endpoint_auth_method "client_secret_post", even
	// if the request said "none" or omitted the field.
	//
	// This exists for MCP clients (Perplexity is the known case) that declare
	// themselves public (token_endpoint_auth_method: "none") per RFC 7591 but
	// then refuse to proceed because the response carries no client_secret —
	// a self-contradictory request no conformant server can satisfy as
	// written. RFC 7591 §3.2.1 permits the server to substitute metadata, so
	// this takes such a client at its word that it wants a secret.
	//
	// Exact matching is deliberate: it is not a way to obtain a usable
	// credential for another client. An attacker who registers with someone
	// else's callback URI is issued a secret for a client whose authorization
	// codes are delivered to that someone else's redirect endpoint, not to
	// the attacker — the secret is useless without also controlling the
	// callback.
	//
	// Requires AllowConfidentialClientRegistration; every entry must be a
	// valid https non-loopback URI (Validate rejects loopback entries — the
	// same restriction AllowConfidentialClientRegistration itself enforces
	// exists so secrets do not land in distributed native apps, and this
	// override must not bypass it). Remove an entry once the client is fixed
	// to handle "none" registrations correctly.
	//nolint:lll // field tags require full JSON+YAML names
	ForceConfidentialRedirectURIs []string `json:"force_confidential_redirect_uris,omitempty" yaml:"force_confidential_redirect_uris,omitempty"`

	// InsecureAllowConfidentialOverLoopbackHTTP opts in to confidential clients
	// when Issuer is a plain-HTTP loopback URL. Without this flag, that
	// combination is rejected: a loopback http:// issuer is normally fine for
	// local development (the traffic never leaves the machine), but client
	// secrets would otherwise travel over cleartext. Defaults to false. Has no
	// effect when there are no confidential clients or Issuer is https.
	//
	// Applies identically to delegate clients and DCR-registered clients. The
	// Kubernetes CRD requires the explicit opt-in for a delegate client with an
	// HTTP issuer; the shared transport validator enforces that its host is
	// loopback — see EmbeddedAuthServerConfig's doc comment.
	//
	// private_key_jwt registration has no equivalent flag or transport
	// restriction: unlike confidential registration, it never returns a
	// client_secret (or any other secret) in the DCR response, so there is
	// nothing here for cleartext HTTP to expose.
	//nolint:lll // field tags require full JSON+YAML names
	InsecureAllowConfidentialOverLoopbackHTTP bool `` /* 127-byte string literal not displayed */

	// DelegateClients declares confidential OAuth clients to register at
	// authorization-server startup, including clients intended for RFC 8693
	// token exchange.
	//
	// This legacy field is deprecated; use InboundGrants.TokenExchange.DelegateClients.
	//
	// Independent of AllowConfidentialClientRegistration: declaring a client
	// here does not require or enable self-service confidential DCR, and
	// setting that flag does not declare or enable any client here. They
	// govern different endpoints — this field is static configuration the
	// operator controls directly, while the flag is admission policy for the
	// unauthenticated /oauth/register endpoint.
	//
	// See DelegateClientRunConfig for the per-client field reference.
	DelegateClients []DelegateClientRunConfig `json:"delegate_clients,omitempty" yaml:"delegate_clients,omitempty"`

	// SPIFFETrustDomains declares SPIFFE trust roots. Each declaration must be
	// referenced by an InboundGrants.SPIFFEClientAuth entry.
	SPIFFETrustDomains []SPIFFETrustDomainRunConfig `json:"spiffe_trust_domains,omitempty" yaml:"spiffe_trust_domains,omitempty"`

	// InboundGrants declares canonical inbound grant configuration, including
	// SPIFFE client authentication, delegate clients, and issuer policy. A
	// non-nil value explicitly controls grant-family enablement.
	InboundGrants *InboundGrantsRunConfig `json:"inbound_grants,omitempty" yaml:"inbound_grants,omitempty"`
}

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

type SPIFFEAuthenticationMethod string

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

type SPIFFEBundleEndpointProfile string

type SPIFFEBundleEndpointSourceRunConfig struct {
	URL string `json:"url" yaml:"url"`

	// Profile selects how the endpoint's TLS connection is authenticated:
	// SPIFFEBundleEndpointProfileHTTPSWeb (Web PKI) or
	// SPIFFEBundleEndpointProfileHTTPSSPIFFE (a separately distributed
	// X.509-SVID root). Required, since the future bundle loader cannot
	// otherwise know which trust anchor to use for the initial connection.
	Profile SPIFFEBundleEndpointProfile `json:"profile" yaml:"profile"`
}

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

type SPIFFEBundleSourceRunConfig struct {
	Type SPIFFEBundleSourceType `json:"type" yaml:"type"`

	Endpoint    *SPIFFEBundleEndpointSourceRunConfig    `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
	WorkloadAPI *SPIFFEWorkloadAPIBundleSourceRunConfig `json:"workload_api,omitempty" yaml:"workload_api,omitempty"`
}

type SPIFFEBundleSourceType string

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

type SPIFFEClientAuthRunConfig struct {
	// TrustDomainRef identifies the SPIFFE trust-domain declaration governing
	// this association policy.
	TrustDomainRef string `json:"trust_domain_ref" yaml:"trust_domain_ref"`

	// PrincipalPattern is a concrete SPIFFE ID or a terminal /* pattern within
	// the declared trust domain.
	PrincipalPattern string `json:"principal_pattern" yaml:"principal_pattern"`

	// ClientID is the explicit OAuth client_id. It is never derived from a
	// SPIFFE ID.
	ClientID string `json:"client_id" yaml:"client_id"`

	Methods []SPIFFEAuthenticationMethod `json:"methods" yaml:"methods"`

	// Resources are RFC 8707 resource indicators this association may
	// request. Must be a subset of the server's allowed_audiences allowlist
	// (RunConfig.AllowedAudiences) — the same RFC 8707 resource-URI list
	// DelegateClientRunConfig.Audiences is validated against. Distinct from
	// Audiences: a resource permission does not imply the same value is also
	// a permitted token audience, or vice versa.
	Resources []string `json:"resources,omitempty" yaml:"resources,omitempty"`

	// Audiences are RFC 8693 token audiences this association may request.
	// This is an independent request dimension from Resources: it is not
	// bounded by allowed_audiences (which is an RFC 8707 resource-URI list)
	// and may contain non-URI logical audience identifiers.
	Audiences []string `json:"audiences" yaml:"audiences"`

	// Scopes are OAuth scopes granted to this association. They must be a
	// subset of the server's effective supported scopes.
	Scopes []string `json:"scopes" yaml:"scopes"`

	// GrantTypes are the OAuth grant types this association may use. Client
	// authentication does not by itself confer any grant.
	GrantTypes []string `json:"grant_types" yaml:"grant_types"`
}

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

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

type SPIFFETrustDomainRunConfig struct {
	// Name uniquely identifies this declaration and is referenced by
	// InboundGrants.SPIFFEClientAuth entries.
	Name string `json:"name" yaml:"name"`

	// TrustDomain is the SPIFFE trust domain accepted by this declaration.
	TrustDomain string `json:"trust_domain" yaml:"trust_domain"`

	// Methods explicitly enables the supported credential types for this trust
	// domain. No authentication method is enabled when the list is empty.
	Methods []SPIFFEAuthenticationMethod `json:"methods" yaml:"methods"`

	// BundleSource declares exactly one future trust-bundle source. It is
	// validated for shape only; fetching or loading a bundle from it is a
	// later step.
	BundleSource SPIFFEBundleSourceRunConfig `json:"bundle_source" yaml:"bundle_source"`
}

type SPIFFEWorkloadAPIBundleSourceRunConfig struct{}

type Server interface {
	// Handler returns an http.Handler that serves all OAuth/OIDC endpoints:
	//   - /.well-known/openid-configuration (OIDC Discovery)
	//   - /.well-known/oauth-authorization-server (RFC 8414 OAuth AS Metadata)
	//   - /.well-known/jwks.json (JSON Web Key Set)
	//   - /oauth/authorize (Authorization endpoint)
	//   - /oauth/token (Token endpoint)
	//   - /oauth/callback (Upstream IDP callback)
	//   - /oauth/register (Dynamic Client Registration, RFC 7591)
	//
	// The handler uses internal routing - the consumer doesn't need to know
	// about the endpoint structure.
	Handler() http.Handler

	// IDPTokenStorage returns storage for upstream IDP tokens.
	// Returns nil if no upstream IDP is configured.
	IDPTokenStorage() storage.UpstreamTokenStorage

	// UpstreamTokenRefresher returns a refresher that can refresh expired upstream
	// tokens using the upstream provider's refresh token grant.
	// Returns nil if no upstream IDP is configured.
	UpstreamTokenRefresher() storage.UpstreamTokenRefresher

	// DCRStore returns the persistent DCR credential store the server is wired
	// against. This is the same DCRCredentialStore used by the upstream-DCR
	// resolver at boot, so callers can read RFC 7591 client registrations
	// without bypassing the storage backend the server itself reads from.
	//
	// SECURITY: the returned interface surfaces raw `client_secret` and
	// `registration_access_token` values. Callers MUST NOT log or render the
	// returned values; treat the handle the same way you would treat a
	// secrets manager client. Intended for admin / diagnostic code paths and
	// integration tests, not for general consumers.
	//
	// Lifecycle: the returned handle's lifetime is bound to Server.Close —
	// methods invoked after Close have backend-specific behavior (a
	// MemoryStorage continues to serve reads; a RedisStorage will error on
	// its closed connection pool).
	DCRStore() storage.DCRCredentialStore

	// Close releases resources held by the server. It drains the upstream idle
	// connections (see the CloseIdleConnections function) and then closes
	// storage. Do not call it on a server whose storage is shared with another
	// live server; retire that one with CloseIdleConnections instead.
	Close() error
}

type SigningKeyRunConfig struct {
	// KeyDir is the directory containing PEM-encoded private key files.
	// All key filenames are relative to this directory.
	// In Kubernetes, this is typically a mounted Secret volume.
	KeyDir string `json:"key_dir,omitempty" yaml:"key_dir,omitempty"`

	// SigningKeyFile is the filename of the primary signing key (relative to KeyDir).
	// This key is used for signing new tokens.
	SigningKeyFile string `json:"signing_key_file,omitempty" yaml:"signing_key_file,omitempty"`

	// FallbackKeyFiles are filenames of additional keys for verification (relative to KeyDir).
	// These keys are included in the JWKS endpoint for token verification but are NOT
	// used for signing new tokens. Useful for key rotation.
	FallbackKeyFiles []string `json:"fallback_key_files,omitempty" yaml:"fallback_key_files,omitempty"`
}

type TokenExchangeInboundGrantRunConfig struct {
	DelegateClients []DelegateClientRunConfig            `json:"delegate_clients,omitempty" yaml:"delegate_clients,omitempty"`
	IssuerPolicies  []TokenExchangeIssuerPolicyRunConfig `json:"issuer_policies,omitempty" yaml:"issuer_policies,omitempty"`
}

type TokenExchangeIssuerPolicyRunConfig struct {
	IssuerRef              string   `json:"issuer_ref" yaml:"issuer_ref"`
	ExpectedAudience       string   `json:"expected_audience" yaml:"expected_audience"`
	ActorClaim             string   `json:"actor_claim,omitempty" yaml:"actor_claim,omitempty"`
	AllowedActors          []string `json:"allowed_actors,omitempty" yaml:"allowed_actors,omitempty"`
	ActorMatcher           string   `json:"actor_matcher,omitempty" yaml:"actor_matcher,omitempty"`
	AllowedDelegateClients []string `json:"allowed_delegate_clients" yaml:"allowed_delegate_clients"`
	AllowMayAct            bool     `json:"allow_may_act,omitempty" yaml:"allow_may_act,omitempty"`
}

type TokenLifespanRunConfig struct {
	// AccessTokenLifespan is the duration that access tokens are valid.
	// If empty, defaults to 1 hour.
	AccessTokenLifespan string `json:"access_token_lifespan,omitempty" yaml:"access_token_lifespan,omitempty"`

	// RefreshTokenLifespan is the duration that refresh tokens are valid.
	// If empty, defaults to 7 days (168h).
	RefreshTokenLifespan string `json:"refresh_token_lifespan,omitempty" yaml:"refresh_token_lifespan,omitempty"`

	// AuthCodeLifespan is the duration that authorization codes are valid.
	// If empty, defaults to 10 minutes.
	AuthCodeLifespan string `json:"auth_code_lifespan,omitempty" yaml:"auth_code_lifespan,omitempty"`
}

type TokenResponseMappingRunConfig struct {
	// AccessTokenPath is the dot-notation path to the access token (required).
	AccessTokenPath string `json:"access_token_path" yaml:"access_token_path"`

	// ScopePath is the dot-notation path to the scope. Defaults to "scope".
	ScopePath string `json:"scope_path,omitempty" yaml:"scope_path,omitempty"`

	// RefreshTokenPath is the dot-notation path to the refresh token. Defaults to "refresh_token".
	RefreshTokenPath string `json:"refresh_token_path,omitempty" yaml:"refresh_token_path,omitempty"`

	// ExpiresInPath is the dot-notation path to the expires_in value. Defaults to "expires_in".
	ExpiresInPath string `json:"expires_in_path,omitempty" yaml:"expires_in_path,omitempty"`
}

type UpstreamConfig struct {
	// Name uniquely identifies this upstream.
	// Used for routing decisions and session binding in multi-upstream scenarios.
	// If empty when only one upstream is configured, defaults to "default".
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Type specifies the provider type: "oidc" or "oauth2".
	Type UpstreamProviderType `json:"type" yaml:"type"`

	// OAuth2Config contains OAuth 2.0 provider configuration.
	// Used when Type is "oauth2". Must be nil when Type is "oidc".
	OAuth2Config *upstream.OAuth2Config `json:"oauth2_config,omitempty" yaml:"oauth2_config,omitempty"`

	// OIDCConfig contains OIDC provider configuration (uses discovery).
	// Used when Type is "oidc". Must be nil when Type is "oauth2".
	OIDCConfig *upstream.OIDCConfig `json:"oidc_config,omitempty" yaml:"oidc_config,omitempty"`
}

type UpstreamProviderFactory func(ctx context.Context, cfg *UpstreamConfig) (upstream.OAuth2Provider, error)

type UpstreamProviderType string

type UpstreamRunConfig struct {
	// Name uniquely identifies this upstream.
	// Used for routing decisions and session binding in multi-upstream scenarios.
	// If empty when only one upstream is configured, defaults to "default".
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Type specifies the provider type: "oidc" or "oauth2".
	Type UpstreamProviderType `json:"type" yaml:"type"`

	// OIDCConfig contains OIDC-specific configuration.
	// Required when Type is "oidc", must be nil when Type is "oauth2".
	OIDCConfig *OIDCUpstreamRunConfig `json:"oidc_config,omitempty" yaml:"oidc_config,omitempty"`

	// OAuth2Config contains OAuth 2.0-specific configuration.
	// Required when Type is "oauth2", must be nil when Type is "oidc".
	OAuth2Config *OAuth2UpstreamRunConfig `json:"oauth2_config,omitempty" yaml:"oauth2_config,omitempty"`
}

type UserInfoFieldMappingRunConfig struct {
	// SubjectFields is an ordered list of field names to try for the user ID.
	// The first non-empty value found will be used.
	// Default: ["sub"]
	SubjectFields []string `json:"subject_fields,omitempty" yaml:"subject_fields,omitempty"`

	// NameFields is an ordered list of field names to try for the display name.
	// The first non-empty value found will be used.
	// Default: ["name"]
	NameFields []string `json:"name_fields,omitempty" yaml:"name_fields,omitempty"`

	// EmailFields is an ordered list of field names to try for the email address.
	// The first non-empty value found will be used.
	// Default: ["email"]
	EmailFields []string `json:"email_fields,omitempty" yaml:"email_fields,omitempty"`
}

type UserInfoRunConfig struct {
	// EndpointURL is the URL of the userinfo endpoint.
	EndpointURL string `json:"endpoint_url" yaml:"endpoint_url"`

	// HTTPMethod is the HTTP method to use for the userinfo request.
	// If not specified, defaults to GET.
	HTTPMethod string `json:"http_method,omitempty" yaml:"http_method,omitempty"`

	// AdditionalHeaders contains extra headers to include in the userinfo request.
	// Useful for providers that require specific headers (e.g., GitHub's Accept header).
	AdditionalHeaders map[string]string `json:"additional_headers,omitempty" yaml:"additional_headers,omitempty"`

	// FieldMapping contains custom field mapping configuration for non-standard providers.
	// If nil, standard OIDC field names are used ("sub", "name", "email").
	FieldMapping *UserInfoFieldMappingRunConfig `json:"field_mapping,omitempty" yaml:"field_mapping,omitempty"`
}