auth

type AuthConfig struct {
	// ResourceURI is the canonical URI of this MCP server (RFC 8707 resource indicator).
	ResourceURI string

	// AuthorizationServers lists the authorization server URLs this server trusts.
	// At least one is required per RFC 9728.
	AuthorizationServers []string

	// ScopesSupported lists the OAuth scopes this server understands.
	ScopesSupported []string

	// MCPPath is the MCP endpoint path (e.g., "/mcp"). Used to construct
	// the well-known URI: /.well-known/oauth-protected-resource/<mcpPath>
	MCPPath string

	// Validator, if set, is automatically wired with ScopesSupported as its
	// AllScopes field (if not already populated). This ensures that 401
	// WWW-Authenticate responses include the full scope list, allowing clients
	// to request broad scopes upfront and avoid scope step-up round-trips.
	//
	// Without this wiring, Validator.AllScopes defaults to empty and 401
	// responses omit the scope= parameter, forcing clients through a
	// narrow-to-broad scope dance. See #50.
	Validator *JWTValidator
}

type AuthExtension struct{}

type BackChannelLogoutConfig struct {
	// Issuer is the expected `iss` claim value (the AS issuer URL).
	// Required. Mirrors the same iss the AS publishes on its
	// /.well-known/openid-configuration document.
	Issuer string

	// Audience is the expected `aud` claim value — typically the
	// resource server's client_id registered with the AS.
	// Required. The spec mandates aud validation against the
	// registered client_id (§ 2.6).
	Audience string

	// JWKSURL is the AS JWKS endpoint used to fetch the signing
	// key for the logout_token via its kid header. Required.
	// Wrapped in oneauth's JWKSKeyStore for cached lookups.
	JWKSURL string

	// JTIStore stores seen `jti` values for replay protection.
	// Default: a fresh MemoryJTIStore. Multi-replica deployments
	// should swap for a Redis / SQL backed impl so a replay seen
	// on replica A is also rejected on replica B.
	JTIStore JTIStore

	// ReplayWindow is the TTL applied to recorded jtis — how long
	// a jti remains visible to JTIStore.Seen. Default 10 minutes.
	// Set this to at least 2x the AS's max-clock-skew tolerance so
	// a delayed-replay attack can't slip past the eviction.
	ReplayWindow time.Duration

	// AllowedClockSkew is the leeway applied to exp / iat / nbf
	// checks during JWT validation. Default 60s. The spec is silent
	// on a concrete value; a minute is the common floor across OIDC
	// libraries.
	AllowedClockSkew time.Duration

	// Now returns the current time. Defaults to time.Now. Tests
	// inject a fixed clock so exp / iat / replay-window assertions
	// are deterministic.
	Now func() time.Time
}

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

type ClientCredentialsSource = client.ClientCredentialsSource

type ClientCredentialsTokenSource struct {
	// ServerURL is the MCP server URL (used for PRM discovery).
	ServerURL string

	// ClientID identifies the client at the AS. Required.
	ClientID string

	// ClientSecret authenticates the client via HTTP Basic / form POST.
	// Mutually exclusive with PrivateKeyPEM.
	ClientSecret string

	// PrivateKeyPEM is the PKCS#8 PEM-encoded private key used to mint
	// the client_assertion JWT. Mutually exclusive with ClientSecret.
	// Must match the public key the AS associates with ClientID.
	PrivateKeyPEM string

	// SigningAlgorithm is the JWS alg for the assertion (e.g. "ES256", "RS256").
	// Required when PrivateKeyPEM is set. Must match the AS's registered
	// signing_alg for this client.
	SigningAlgorithm string

	// KeyID, when non-empty, is emitted as the JWS `kid` header so the AS
	// can pick the right registered key. Optional.
	KeyID string

	// Scopes to request. If empty, inherits from PRM scopes_supported.
	Scopes []string

	// HTTPClient overrides the discovery and token-request HTTP client.
	// Useful in tests with httptest.Server.
	HTTPClient *http.Client

	// AllowInsecure permits http:// AS endpoints. Required for the
	// conformance mock AS; production deployments should leave this false
	// so AS HTTPS is enforced.
	AllowInsecure bool

	// ASMetadataStore caches AS metadata across discovery calls when
	// multiple sources target the same AS.
	ASMetadataStore client.ASMetadataStore

	// OnToken fires after a successful token fetch by the underlying
	// ClientCredentialsSource. Use to persist the credential outside the
	// in-memory cache.
	OnToken func(*client.ServerCredential)
	// contains filtered or unexported fields
}

type ClientRegistrationRequest = client.ClientRegistrationRequest

type ClientRegistrationResponse = client.ClientRegistrationResponse

type DiscoverOption func(*discoverConfig)

type EnterpriseManagedTokenSource struct {
	// ServerURL is the MCP server URL. Used for PRM discovery and as the
	// `resource` form value on the IdP token exchange.
	ServerURL string

	// ClientID identifies this MCP client at the MCP authorization server.
	// Required.
	ClientID string

	// ClientSecret authenticates the MCP client at the AS via
	// `client_secret_basic` (RFC 6749 §2.3.1) on the jwt-bearer grant
	// request. Required.
	ClientSecret string

	// IdpClientID is the client identity sent on the IdP token exchange.
	// SEP-990 §6.1 notes the IdP "needs to be aware of the MCP Client's
	// client_id that it normally uses with the MCP Server"; this field
	// names the client at the IdP, which may differ from ClientID above.
	// Optional — empty falls back to the unauthenticated token-exchange
	// path (AuthMethodNone), which the conformance fixture accepts.
	IdpClientID string

	// IdpIDToken is the signed ID token issued by the IdP for the user.
	// Required. Sent as the RFC 8693 `subject_token`.
	IdpIDToken string

	// IdpTokenEndpoint is the URL of the IdP token endpoint that performs
	// the RFC 8693 token exchange. Required. The conformance scenario
	// provides this directly in MCP_CONFORMANCE_CONTEXT rather than
	// requiring a separate IdP discovery step.
	IdpTokenEndpoint string

	// AllowInsecure permits http:// AS endpoints. The conformance mock AS
	// uses HTTP; production deployments leave this false.
	AllowInsecure bool

	// HTTPClient overrides the discovery and token-request HTTP client.
	HTTPClient *http.Client

	// ASMetadataStore caches AS metadata across discovery calls.
	ASMetadataStore client.ASMetadataStore
	// contains filtered or unexported fields
}

type IntrospectionConfig struct {
	// IntrospectionURL is the OAuth 2.0 Token Introspection endpoint
	// (RFC 7662). Required.
	IntrospectionURL string

	// ClientID and ClientSecret authenticate this resource server to
	// the introspection endpoint via HTTP Basic auth
	// (client_secret_basic). Both required.
	ClientID     string
	ClientSecret string

	// HTTPClient overrides the HTTP client used for introspection
	// requests. Nil means http.DefaultClient. Set this when a deployment
	// needs custom timeouts, mTLS, or to point at a sidecar proxy.
	HTTPClient *http.Client

	// CacheTTL bounds the staleness window for introspection responses.
	// A revoked token MAY remain "active" in the cache for up to
	// CacheTTL after the authorization server actually revokes it —
	// this is the load-bearing knob for the prod-events walkthrough's
	// "token revocation as auth-visibility step" demo. Default 0 (no
	// caching, every request hits the AS). Recommended 30s.
	CacheTTL time.Duration

	// ResourceMetadataURL is included in WWW-Authenticate headers on
	// 401 responses (RFC 9728). Same field as on JWTConfig.
	ResourceMetadataURL string

	// RequiredScopes are checked on every request (global minimum).
	// 403 + WWW-Authenticate scope hint on missing scopes.
	RequiredScopes []string

	// AllScopes is the complete set of scopes this server supports.
	// Included in WWW-Authenticate 401 headers for client scope
	// selection — same shape as JWTConfig.AllScopes.
	AllScopes []string

	// TenantMapper extracts (tenant, subject) from the introspection
	// response. nil means the default realm-from-issuer-URL mapper —
	// the right choice for any Keycloak deployment whose realm =
	// tenant. Override when a deployment maps tenant from a custom
	// claim, but note that oneauth's IntrospectionResult today carries
	// only RFC 7662 well-known fields; custom-claim mapping requires
	// extending oneauth (tracked as a future enhancement).
	TenantMapper TenantMapper
}

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

type JTIStore interface {
	// Seen returns whether the jti has been recorded within its TTL
	// window. Used by the BCL receiver to reject replays. Spec §2.6:
	// "If the Logout Token has been seen before, [the receiver] MUST
	// reject the request as a replay."
	Seen(ctx context.Context, req SeenRequest) (SeenResponse, error)

	// Record stores a jti with the given TTL. Re-recording an existing
	// jti is allowed and resets its TTL — the spec does not require
	// monotonic-only recording, and forcing it would complicate the
	// in-memory impl for no observable gain.
	Record(ctx context.Context, req RecordRequest) (RecordResponse, error)
}

type JWTConfig struct {
	// JWKSURL is the authorization server's JWKS endpoint for key discovery.
	JWKSURL string

	// Issuer is the expected "iss" claim in tokens.
	Issuer string

	// Audience is the expected "aud" claim — this MCP server's canonical URI (RFC 8707).
	Audience string

	// ResourceMetadataURL is the URL of this server's Protected Resource Metadata
	// document (RFC 9728). Included in WWW-Authenticate headers.
	ResourceMetadataURL string

	// RequiredScopes are checked on every request (global minimum).
	RequiredScopes []string

	// AllScopes is the complete set of scopes this server supports.
	// Included in WWW-Authenticate 401 headers for client scope selection.
	AllScopes []string

	// TracerProvider optionally enables SEP-414 instrumentation of
	// token validation: a sub-span per JWKS key lookup plus
	// mcp.auth.* attributes (method / subject / issuer / scopes /
	// cache_hit) on the active dispatch span set up by
	// server.WithTracerProvider. Nil (or core.NoopTracerProvider{})
	// is the default — zero spans, zero attributes, zero allocation
	// added to the validation path. ext/auth depends on the core
	// abstraction only for its own spans.
	TracerProvider mcpcore.TracerProvider

	// OneauthTracerProvider opts oneauth's internal work (JWKS
	// HTTP fetch, refresh, signature verify, etc.) into emitting
	// its own spans, threading them through oneauth v0.1.14's
	// tracing surface via keys.WithTracerProvider on the
	// JWKSKeyStore. Nil = oneauth-internal work stays opaque (the
	// pre-v0.1.14 behavior); ext/auth's own auth.jwks_lookup span
	// still emits if TracerProvider above is set, just without
	// child spans showing oneauth's internal HTTP / parsing work.
	//
	// Pass commonotel.UnderlyingOTelTP(tp) when you want oneauth's
	// spans to share the same OTel pipeline as the rest of the
	// process — the typical production setup.
	//
	// Type is the OTel SDK's trace.TracerProvider directly (not
	// mcpkit's core.TracerProvider) because oneauth's API takes the
	// SDK type, and ext/auth already pulls OTel transitively
	// through oneauth v0.1.14.
	OneauthTracerProvider oteltrace.TracerProvider
}

type JWTValidator struct {

	// ResourceMetadataURL is included in WWW-Authenticate headers on 401 responses.
	ResourceMetadataURL string

	// RequiredScopes are checked on every request. Empty means no global scope requirement.
	RequiredScopes []string

	// AllScopes is included in WWW-Authenticate 401 headers to guide client scope selection.
	// Per spec: clients use this to request scopes upfront, reducing step-up round-trips.
	AllScopes []string

	// CacheTTL enables a validated-token cache when > 0. Tokens validated
	// within the TTL window return cached claims without re-verifying the
	// JWT signature. This avoids redundant crypto during LLM agent loops
	// making rapid sequential tool calls with the same token.
	// Default: 0 (no caching). Recommended: 30s-60s.
	CacheTTL time.Duration

	// CacheMaxSize limits the number of cached tokens to prevent memory
	// growth under token flooding. When the cache exceeds this size, new
	// tokens are validated but not cached. Default: 1000.
	// Future: consider hashicorp/golang-lru for proper LRU eviction.
	CacheMaxSize int
	// contains filtered or unexported fields
}

type LogoutListener func(ctx context.Context, sub, sid string)

type MCPAuthInfo struct {
	// ResourceMetadataURL is the PRM endpoint URL (from WWW-Authenticate or well-known).
	ResourceMetadataURL string

	// PRM is the parsed Protected Resource Metadata document.
	PRM *ProtectedResourceMetadata

	// AuthorizationServers from the PRM document.
	AuthorizationServers []string

	// ASMetadata is the discovered authorization server metadata.
	ASMetadata *client.ASMetadata
}

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

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

type OAuthTokenSource struct {
	// ServerURL is the MCP server URL (used for PRM discovery and as resource indicator).
	ServerURL string

	// ClientID for pre-registered clients. Takes priority over CIMD and DCR.
	ClientID string

	// ClientSecret for confidential clients (empty for public clients).
	ClientSecret string

	// ClientMetadataURL is a CIMD URL (draft-ietf-oauth-client-id-metadata-document).
	// When set and no ClientID is provided, this URL is used as the client_id.
	// Per MCP spec: SHOULD support Client ID Metadata Documents.
	ClientMetadataURL string

	// EnableDCR enables Dynamic Client Registration (RFC 7591) as a fallback
	// when no ClientID or ClientMetadataURL is set. Per MCP spec: MAY support DCR.
	EnableDCR bool

	// DCRMeta overrides the default DCR registration request.
	// If nil, DefaultClientRegistration() is used.
	DCRMeta *ClientRegistrationRequest

	// Scopes to request. Leave empty for the default lazy behavior: the
	// source acquires no token until a server 401/403 selects the scope via
	// WWW-Authenticate, then uses that (falling back to PRM scopes_supported
	// only when the challenge carries no scope=). Setting Scopes explicitly
	// pins them and acquires eagerly on the first Token call. TokenForScopes
	// merges challenge scopes into this set as step-up occurs.
	Scopes []string

	// CredStore persists tokens across sessions (optional).
	CredStore client.CredentialStore

	// ASMetadataStore caches authorization server metadata across discovery
	// calls. Share a single store across multiple OAuthTokenSource instances
	// connecting to MCP servers behind the same AS to avoid redundant
	// discovery fetches. Optional.
	ASMetadataStore client.ASMetadataStore

	// OnToken is an optional callback invoked after a successful token
	// acquisition or refresh by the underlying oneauth AuthClient. Use
	// this to persist tokens to an external store (disk, database, secret
	// manager) without implementing a full CredentialStore.
	//
	// Fires ONLY for the refresh_token grant path in the underlying
	// AuthClient — not for initial LoginWithBrowser calls in today's
	// OAuthTokenSource.Token() flow (which re-runs the full browser flow
	// instead of using refresh tokens). This is a latent capability until
	// the browser-login flow learns to use refresh tokens (follow-up).
	//
	// Thread safety: the callback is invoked synchronously while the
	// underlying AuthClient mutex is held (same contract as
	// CredentialStore.SetCredential). Callbacks must not re-enter
	// AuthClient or OAuthTokenSource methods, or they will deadlock.
	//
	// See oneauth#82 for the underlying pushdown. Issue #137.
	OnToken func(*client.ServerCredential)

	// OpenBrowser opens the authorization URL (nil = platform default).
	OpenBrowser func(url string) error

	// HTTPClient is used for discovery and DCR requests.
	// If nil, http.DefaultClient is used.
	HTTPClient *http.Client

	// AllowInsecure skips HTTPS enforcement on AS endpoints.
	// Only set this for local development/testing.
	AllowInsecure bool
	// contains filtered or unexported fields
}

type ProtectedResourceMetadata struct {
	Resource             string   `json:"resource"`
	AuthorizationServers []string `json:"authorization_servers"`
	ScopesSupported      []string `json:"scopes_supported,omitempty"`
}

type RecordRequest struct {
	JTI string
	TTL time.Duration
}

type RecordResponse struct{}

type SeenRequest struct {
	JTI string
}

type SeenResponse struct {
	Found bool
}

type TenantMapper func(*apiauth.IntrospectionResult) (tenant, subject string)

type ToolDefLookup interface {
	ToolDef(name string) (core.ToolDef, bool)
}

type ToolScopeOption func(*toolScopeConfig)