oauth

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

type AutheoryProviderOptions struct {
	// Issuer is the expected upstream issuer, for example
	// https://auth.autheory.app. It is required.
	Issuer string

	// ClientID is the adapter's own upstream client registration id. The adapter
	// never derives a request's client id from it: a request that omits its
	// upstream client id fails closed with invalid_request.
	ClientID string

	// DiscoveryURL overrides the discovery document URL. Zero value means the
	// issuer plus /.well-known/oauth-authorization-server.
	DiscoveryURL string

	// TokenEndpoint, JWKSURI, and AuthorizationEndpoint override the endpoints
	// the discovery document publishes. Each must be an https URL.
	TokenEndpoint         string
	JWKSURI               string
	AuthorizationEndpoint string

	// HTTPClient is reused for every discovery, token, and JWKS call. Redirects
	// are refused regardless; a caller-supplied transport keeps its own
	// connection policy.
	HTTPClient *http.Client

	// AllowPrivateHosts disables the framework's non-public-host guard on the
	// calls the adapter makes with the framework's own transport. It is off by
	// default; local development and loopback test suites opt in explicitly.
	AllowPrivateHosts bool

	// FetchTimeout bounds one discovery, token, or JWKS call. Zero means the
	// framework default shared with discovery and JWKS fetching.
	FetchTimeout time.Duration

	// Now overrides the clock used for token expiry and key caching. Zero means
	// time.Now().UTC.
	Now func() time.Time

	// AllowedAuthorizedParties is an exact-match allow-list applied to the
	// validated token's azp claim (falling back to client_id). It is the default
	// for expectation sets that do not carry their own list.
	AllowedAuthorizedParties []string
}

type AuthorizationCodeRecord struct {
	Code                string
	ClientID            string
	RedirectURI         string
	Resource            string
	CodeChallenge       string
	CodeChallengeMethod string
	ExpiresAt           time.Time
}

type AuthorizationCodeStore interface {
	Put(ctx context.Context, rec *AuthorizationCodeRecord) error
	Consume(ctx context.Context, code string) (*AuthorizationCodeRecord, error)
}

type AuthorizationRequest struct {
	UpstreamClientID    string
	CallbackURL         string
	CodeChallenge       string
	CodeChallengeMethod string
	State               string
	Resource            string
	Scopes              []string
	Hints               map[string]string
}

type AuthorizationServerMetadata struct {
	Issuer                            string   `json:"issuer"`
	AuthorizationEndpoint             string   `json:"authorization_endpoint,omitempty"`
	TokenEndpoint                     string   `json:"token_endpoint,omitempty"`
	RegistrationEndpoint              string   `json:"registration_endpoint,omitempty"`
	JWKSURI                           string   `json:"jwks_uri,omitempty"`
	RevocationEndpoint                string   `json:"revocation_endpoint,omitempty"`
	DeviceAuthorizationEndpoint       string   `json:"device_authorization_endpoint,omitempty"`
	ResponseTypesSupported            []string `json:"response_types_supported,omitempty"`
	GrantTypesSupported               []string `json:"grant_types_supported,omitempty"`
	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported,omitempty"`
	CodeChallengeMethodsSupported     []string `json:"code_challenge_methods_supported,omitempty"`
	ScopesSupported                   []string `json:"scopes_supported,omitempty"`
	SubjectTypesSupported             []string `json:"subject_types_supported,omitempty"`
	IDTokenSigningAlgValuesSupported  []string `json:"id_token_signing_alg_values_supported,omitempty"`
	// AuthorizationResponseIssParameterSupported advertises RFC 9207 `iss` on
	// authorization responses. It is opt-in and false by default: omitempty
	// keeps every document that does not set it byte-identical to its pre-RFC
	// 9207 shape (an absent member means false, RFC 8414 section 2), so only a
	// surface that provably sends `iss` sets it. The field is a typed bool, so
	// the wire value is always the JSON boolean `true` while present: no
	// non-boolean state can reach the document.
	AuthorizationResponseIssParameterSupported bool `json:"authorization_response_iss_parameter_supported,omitempty"`
}

type AuthorizationServerMetadataOption func(*AuthorizationServerMetadata, *url.URL) error

type BearerTokenClaims struct {
	Subject   string
	Audience  string
	Scopes    []string
	ExpiresAt time.Time
}

type BearerTokenClaimsValidator func(ctx *apptheory.Context, token string) (*BearerTokenClaims, error)

type BearerTokenRecord struct {
	Token     string
	Subject   string
	Audience  string
	Scope     string
	Scopes    []string
	ExpiresAt time.Time
}

type BearerTokenValidationOptions struct {
	RequiredAudience string
	RequiredScopes   []string
	// RequiredAudienceFunc returns the route-derived audience the token must be
	// bound to. When set it takes precedence over RequiredAudience, so audience
	// can be the exact matched route URL.
	RequiredAudienceFunc func(*apptheory.Context) (string, error)
	// RequiredScopesFunc returns the route-derived scope set the token must
	// carry. When set it takes precedence over RequiredScopes.
	RequiredScopesFunc func(*apptheory.Context) ([]string, error)
	Now                func() time.Time
}

type BearerTokenValidator func(ctx *apptheory.Context, token string) error

type CodeExchangeRequest struct {
	Code             string
	UpstreamClientID string
	CallbackURL      string
	CodeVerifier     string
}

type DynamicClientRegistrationPolicy struct {
	AllowedRedirectURIs []string
	RequirePublicClient bool // token_endpoint_auth_method must be "none"
	RequireRefreshToken bool // grant_types must include "refresh_token" (if grant_types provided)
}

type DynamicClientRegistrationRequest struct {
	ClientName              string   `json:"client_name,omitempty"`
	RedirectURIs            []string `json:"redirect_uris,omitempty"`
	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
	GrantTypes              []string `json:"grant_types,omitempty"`
	ResponseTypes           []string `json:"response_types,omitempty"`
	Scope                   string   `json:"scope,omitempty"`
}

type DynamicClientRegistrationResponse struct {
	ClientID string `json:"client_id"`
	// ClientSecret is omitted for public clients.
	ClientSecret          string `json:"client_secret,omitempty"`
	ClientIDIssuedAt      int64  `json:"client_id_issued_at,omitempty"`
	ClientSecretExpiresAt int64  `json:"client_secret_expires_at,omitempty"`
}

type JWKSValidatorOptions struct {
	// Issuer is the expected token issuer. It is required.
	Issuer string

	// JWKSURI is the absolute HTTPS JSON Web Key Set URL. When it is empty,
	// DiscoveryURL bootstraps it.
	JWKSURI string

	// DiscoveryURL is the absolute OIDC discovery document URL. It is consulted
	// only when JWKSURI is empty, and its document issuer must equal Issuer
	// before its jwks_uri is trusted.
	DiscoveryURL string

	// HTTPClient is reused for every discovery and JWKS fetch. Redirects are
	// disabled regardless: a 3xx response fails closed.
	HTTPClient *http.Client

	// Now overrides the clock used for exp/nbf, cache expiry, and cooldown.
	Now func() time.Time

	// ClockSkew is the tolerance applied to exp and nbf.
	ClockSkew time.Duration

	// FetchTimeout bounds one discovery or JWKS fetch. Zero means the default of
	// 10s, shared with the TypeScript and Python validators; an HTTPClient that
	// already carries its own Timeout keeps that Timeout unless FetchTimeout is
	// set explicitly.
	FetchTimeout time.Duration

	// AllowPrivateHosts disables the non-public-host check on the framework's
	// discovery/JWKS transport. It is off by default and the framework never
	// enables it: local development and the repository's loopback test suites
	// opt in explicitly. A caller-supplied HTTPClient keeps its own connection
	// policy either way.
	AllowPrivateHosts bool

	// CacheTTL is how long a fetched key stays usable before a refresh. Zero
	// means the default.
	CacheTTL time.Duration

	// RefreshCooldown bounds how often one unknown kid may trigger fetches.
	// Zero means the default.
	RefreshCooldown time.Duration

	// MaxRefreshPerKid bounds the refresh fetches a single unknown kid may
	// trigger beyond the fetch that populates the cache. Zero means the default
	// of 1.
	MaxRefreshPerKid int

	// MaxKidLength bounds a kid string before it may enter any cache. Zero means
	// the default of 256.
	MaxKidLength int

	// MaxWindowEntries bounds the per-kid refresh-window map. Zero means the
	// default of 1024.
	MaxWindowEntries int

	// MaxKeyEntries bounds the cached signing keys. Zero means the default of
	// 128.
	MaxKeyEntries int

	// MaxUnknownKidFetches is the global key-set fetch budget inside one
	// UnknownKidFetchWindow. Zero means the default of 32.
	MaxUnknownKidFetches int

	// UnknownKidFetchWindow is the rolling window of MaxUnknownKidFetches. Zero
	// means the default of 60s.
	UnknownKidFetchWindow time.Duration

	// AllowedAZP is an exact-match allow-list for the token's azp claim, falling
	// back to client_id. An empty list disables the check.
	AllowedAZP []string

	// RequiredAudience derives the route-bound audience. A non-empty result must
	// equal one aud entry exactly; there is no substring or wildcard match.
	RequiredAudience func(*apptheory.Context) (string, error)

	// RequiredScopes derives the route-bound scope set. Every entry must be
	// present in the token.
	RequiredScopes func(*apptheory.Context) ([]string, error)
}

type MCPServerConfig struct {
	// MCPPath overrides the conventional /mcp endpoint path.
	MCPPath string

	// AuthorizationServerIssuer is the configured OAuth authorization server
	// issuer advertised by RFC 9728 discovery.
	AuthorizationServerIssuer string

	// JWKSURI is the configured JSON Web Key Set URL used to validate access
	// tokens. It is not the protected resource's own key set and is therefore
	// not advertised by RFC 9728 discovery.
	JWKSURI string

	// AllowedHostnames is an optional trusted-host allowlist for discovery.
	// When it is empty the discovery origin is derived from the
	// deployment-authoritative `host` header alone, and forwarded-host headers
	// are ignored. When it is non-empty, forwarded-host headers may be honored,
	// but only a request whose canonical authority is on this list produces
	// metadata; anything else fails closed with HTTP 400
	// `{"error":"invalid_request_host"}`.
	AllowedHostnames []string
}

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

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

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

type Provider interface {
	// Discovery returns the upstream metadata after verifying the discovery
	// document: the document issuer must equal the configured issuer before any
	// published endpoint is trusted.
	Discovery(ctx context.Context) (*ProviderMetadata, error)

	// AuthorizationURL builds the absolute upstream authorize URL a browser is
	// redirected to from the facade's /authorize surface.
	AuthorizationURL(req AuthorizationRequest) (string, error)

	// ExchangeCode performs the server-side upstream code exchange, presenting
	// the facade's own client and PKCE verifier.
	ExchangeCode(ctx context.Context, req CodeExchangeRequest) (*TokenSet, error)

	// Refresh performs an upstream refresh presenting the OAuth client that owns
	// the recorded upstream material.
	Refresh(ctx context.Context, req RefreshRequest) (*TokenSet, error)

	// ValidateAccessToken validates an upstream access token against the caller's
	// expectations and returns safe, non-secret claims. It never mutates the
	// token.
	ValidateAccessToken(ctx context.Context, token string, expected TokenExpectations) (*TokenClaims, error)
}

type ProviderError struct {
	Class   ProviderErrorClass
	Op      string
	Message string
	// contains filtered or unexported fields
}

type ProviderErrorClass string

type ProviderMetadata struct {
	Issuer                                     string   `json:"issuer"`
	AuthorizationEndpoint                      string   `json:"authorization_endpoint"`
	TokenEndpoint                              string   `json:"token_endpoint"`
	JWKSURI                                    string   `json:"jwks_uri"`
	CodeChallengeMethodsSupported              []string `json:"code_challenge_methods_supported"`
	AuthorizationResponseIssParameterSupported bool     `json:"authorization_response_iss_parameter_supported"`
	ResourceParameterSupported                 bool     `json:"resource_parameter_supported"`
}

type RefreshRequest struct {
	RefreshMaterial  string
	UpstreamClientID string
}

type RefreshTokenRecord struct {
	Token     string
	ClientID  string
	Subject   string
	Resource  string
	ExpiresAt time.Time
}

type RefreshTokenStore interface {
	Put(ctx context.Context, rec *RefreshTokenRecord) error
	Get(ctx context.Context, token string) (*RefreshTokenRecord, error)
	Consume(ctx context.Context, token string) (*RefreshTokenRecord, error)
	Delete(ctx context.Context, token string) error
}

type RequireBearerTokenOptions struct {
	// ResourceMetadataURL is used to build the RFC9728 discovery challenge.
	//
	// The middleware reads no environment variable. When this and
	// ResourceMetadataURLFunc are both empty the challenge is the bare
	// `Bearer` form with no resource_metadata parameter, so a missing
	// configuration fails closed to an unadvertised discovery endpoint rather
	// than to a value an injected MCP_ENDPOINT could influence.
	ResourceMetadataURL string

	// ResourceMetadataURLFunc returns the route-derived protected-resource
	// metadata URL for the matched route. When set it takes precedence over
	// ResourceMetadataURLTemplate and ResourceMetadataURL, so the challenge is
	// route-derived rather than family-wide.
	ResourceMetadataURLFunc func(*apptheory.Context) (string, error)

	// ResourceMetadataURLTemplate is an absolute HTTPS URL template whose
	// `{param}` placeholders are interpolated from the matched route's path
	// parameters, so a per-actor route (`/mcp/{actor}`) advertises that actor's
	// own RFC 9728 metadata URL with no hand-rolled resolver. It is explicit
	// application configuration: the middleware reads no environment variable.
	//
	// Pass the CDK construct's route-derived template straight through, for
	// example `AppTheoryRemoteMcpServer.protectedResourceMetadataUrl` on the
	// adopter's own configuration surface.
	//
	// The template is validated when the middleware is constructed — it must be
	// an absolute HTTPS URL with no userinfo, query, fragment, or percent
	// escape and no "." or ".." path segment, and its placeholders must appear
	// in the path and name route parameters. A malformed template panics at
	// registration rather than advertising a broken discovery URL, so a bad
	// template fails closed at startup instead of at request time.
	//
	// At request time a placeholder that the matched route does not supply, or
	// whose value is not a safe single path segment (see
	// isSafeResourceMetadataURLTemplateValue), makes the middleware emit the
	// bare `Bearer` challenge. It never advertises a literal placeholder.
	//
	// When set it takes precedence over ResourceMetadataURL; ResourceMetadataURLFunc
	// still takes precedence over it.
	ResourceMetadataURLTemplate string

	// Validator is called for every request. If it is omitted, or if it returns
	// an error, the request is rejected with 401.
	Validator BearerTokenValidator

	// ClaimsValidator is preferred for new code because it can distinguish
	// unauthorized token failures from forbidden audience/scope failures and
	// expose safe claims to downstream handlers.
	ClaimsValidator BearerTokenClaimsValidator

	// RequiredScopesFunc returns the route-derived scope set used to build the
	// 403 insufficient_scope remediation challenge. It is consulted only when a
	// validator reports ErrBearerTokenInsufficientScope.
	RequiredScopesFunc func(*apptheory.Context) ([]string, error)
	// contains filtered or unexported fields
}

type TokenClaims struct {
	Subject         string    `json:"subject"`
	Audience        string    `json:"audience"`
	Scopes          []string  `json:"scopes"`
	ExpiresAt       time.Time `json:"expires_at"`
	AuthorizedParty string    `json:"authorized_party"`
}

type TokenExpectations struct {
	ExpectedIssuer           string
	ExpectedAudience         string
	RequiredScopes           []string
	AllowedAuthorizedParties []string
}

type TokenSet struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	TokenType    string `json:"token_type"`
	ExpiresIn    int    `json:"expires_in"`
	Scope        string `json:"scope"`
	IDToken      string `json:"id_token"`
}