tokenexchange

type Handler struct {
	*oauth2.HandleHelper
	// contains filtered or unexported fields
}

type JWTBearerAssertionValidator interface {
	ValidateJWTBearerAssertion(ctx context.Context, rawToken, tokenEndpoint string) (*ValidatedClaims, error)
}

type JWTBearerGrantPolicy struct {
	MaxAssertionAge string                    `json:"max_assertion_age" yaml:"max_assertion_age"`
	SubjectBindings []JWTBearerSubjectBinding `json:"subject_bindings" yaml:"subject_bindings"`
	// AcceptedAudiences is the set of "this AS" identity strings an
	// assertion's "aud" claim must intersect — e.g. to support migrating
	// this server's issuer/token-endpoint URL, or exposing it under more
	// than one valid name. Each value uniquely identifies this
	// authorization server for this grant; it is NOT a resource/API
	// identifier — a bare resource audience is deliberately not accepted
	// here, that would let any RFC 8707 resource-scoped token satisfy the
	// grant instead of only tokens minted for this AS. Defaults to
	// [tokenEndpoint] when empty, preserving prior exact-match behavior.
	AcceptedAudiences []string `json:"accepted_audiences,omitempty" yaml:"accepted_audiences,omitempty"`
	// contains filtered or unexported fields
}

type JWTBearerHandler struct {
	*oauth2.HandleHelper
	// contains filtered or unexported fields
}

type JWTBearerSubjectBinding struct {
	Subject          string   `json:"subject" yaml:"subject"`
	AllowedResources []string `json:"allowed_resources" yaml:"allowed_resources"`
}

type MayActClaim struct {
	Sub string `json:"sub"`
	// Iss, when present, qualifies Sub's namespace. RFC 8693 §4.4: "the
	// combination of the two claims 'iss' and 'sub' are sometimes necessary
	// to uniquely identify an authorized actor." Without it, Sub alone could
	// name a party in some other issuer's namespace while still being
	// compared against a ToolHive client ID by checkDelegationConsent — a
	// namespace-confusion bug, not just a missing feature. validateMayActShape
	// requires Iss, when present, to equal this authorization server's own
	// issuer, so by the time checkDelegationConsent reads Sub it is
	// guaranteed to be in ToolHive's own client namespace.
	Iss string `json:"iss,omitempty"`
}

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

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

type SubjectTokenValidator interface {
	Validate(ctx context.Context, rawToken string) (*ValidatedClaims, error)
}

type TrustedIssuer struct {
	// Name optionally identifies this trust declaration for canonical issuer_ref references.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// IssuerURL is the expected "iss" claim value (exact match).
	IssuerURL string `json:"issuer_url" yaml:"issuer_url"`
	// ExpectedAudience is the expected "aud" claim value that must appear
	// in an RFC 8693 subject token's audience list (a resource/API identifier,
	// not a client ID — required for delegation unless JWTBearerGrant is
	// configured; see looksLikeResourceIdentifier). RFC 7523 assertions use
	// the token endpoint as their audience instead.
	//
	// This legacy field is deprecated; configure RFC 8693 policy under
	// inbound_grants.token_exchange.issuer_policies.
	// See docs/arch/17-token-exchange-delegation.md ("ID/access-token
	// discrimination") for why and its limits.
	ExpectedAudience string `json:"expected_audience" yaml:"expected_audience"`
	// JWKSURL is the URL to fetch the issuer's JSON Web Key Set from.
	// If empty, it is resolved via OIDC discovery at {IssuerURL}/.well-known/openid-configuration.
	JWKSURL string `json:"jwks_url,omitempty" yaml:"jwks_url,omitempty"`
	// InsecureAllowHTTP permits plain-HTTP OIDC discovery and JWKS fetches
	// for THIS issuer only. Development and testing only — never set in
	// production. Does not relax the private-IP guard; see AllowPrivateIPs.
	// Deliberately per-issuer: this server's own InsecureAllowHTTP must not
	// silently permit plaintext discovery for every trusted external issuer
	// too — a network attacker who can intercept that traffic could
	// substitute a JWKS and forge subject tokens for that issuer's
	// namespace.
	InsecureAllowHTTP bool `json:"insecure_allow_http,omitempty" yaml:"insecure_allow_http,omitempty"`
	// AllowPrivateIPs permits OIDC discovery and JWKS fetches for THIS
	// issuer to resolve to a private or loopback address. Use only when the
	// issuer is hosted inside the same cluster and has no public endpoint.
	AllowPrivateIPs bool `json:"allow_private_ips,omitempty" yaml:"allow_private_ips,omitempty"`
	// CAFilePath is the path to a PEM CA bundle added to the system roots when
	// fetching this issuer's OIDC discovery document and JWKS. Trust is additive
	// and scoped to this issuer: the public roots still apply, and no other
	// issuer's client is affected.
	CAFilePath string `json:"ca_file_path,omitempty" yaml:"ca_file_path,omitempty"`
	// ActorClaim names the claim identifying the client that requested the
	// subject token from THIS EXTERNAL ISSUER (used by AllowedActors below).
	// Values are in the external issuer's namespace, NOT ToolHive client
	// IDs. Defaults to "azp"; use "appid" for Microsoft Entra v1, "cid" for
	// Okta. The special value "client_id" reads ValidatedClaims.ClientID
	// instead of Extra (assignClaim routes it to that field) — it is still
	// the external token's client_id claim, not a ToolHive one.
	ActorClaim string `json:"actor_claim,omitempty" yaml:"actor_claim,omitempty"`
	// AllowedActors is the allowlist of ActorClaim values authorized to
	// exchange a subject token from this issuer when it carries no
	// "may_act" claim. ActorMatcher can additionally authorize a token by
	// matching its complete verified claims map; either signal is sufficient.
	// When both are empty, only may_act-bearing tokens are accepted, and only
	// if AllowMayAct is also true for this issuer. By itself names no
	// ToolHive client — see AllowedDelegateClients and
	// docs/arch/17-token-exchange-delegation.md ("Accepted limitations" #1).
	AllowedActors []string `json:"allowed_actors,omitempty" yaml:"allowed_actors,omitempty"`
	// ActorMatcher is an admin-authored CEL expression evaluated against the
	// complete signature-verified JWT claims map as "claims". A true result
	// authorizes delegation alongside AllowedActors; a syntax or type error
	// fails configuration validation. An expression that compiles but does
	// not return bool is NOT caught at that point, though — it compiles
	// successfully and is only rejected the first time it is evaluated
	// against a real token, denying that token (and every one after it, since
	// the expression will never return bool). Any other runtime evaluation
	// error denies the token the same way.
	ActorMatcher string `json:"actor_matcher,omitempty" yaml:"actor_matcher,omitempty"`
	// AllowedDelegateClients restricts which ToolHive client IDs may
	// exchange a subject token from this issuer, for BOTH consent paths.
	// Required (validateTrustedIssuer rejects empty/absent); "*" permits
	// any confidential client holding the grant. See
	// docs/arch/17-token-exchange-delegation.md ("Accepted limitations" #1).
	//nolint:lll // field tags require full JSON+YAML names
	AllowedDelegateClients []string `json:"allowed_delegate_clients,omitempty" yaml:"allowed_delegate_clients,omitempty"`
	// AllowMayAct permits this external issuer's may_act claim to authorize
	// delegation. It defaults to false; external issuers must be opted in
	// explicitly because may_act bypasses AllowedActors and ActorMatcher. It
	// does not affect self-issued subject tokens. When enabled,
	// AllowedDelegateClients must name specific ToolHive clients rather than
	// use the wildcard.
	AllowMayAct bool `json:"allow_may_act,omitempty" yaml:"allow_may_act,omitempty"`
	// JWTBearerGrant optionally enables the plain RFC 7523 JWT-bearer grant.
	// It accepts assertions from this issuer without client authentication and
	// limits their maximum age, subjects, and RFC 8707 resources. It is
	// independent from RFC 8693 delegation policy.
	//
	// This legacy field is deprecated; configure RFC 7523 policy under
	// inbound_grants.jwt_bearer.issuer_policies.
	JWTBearerGrant *JWTBearerGrantPolicy `json:"jwt_bearer_grant,omitempty" yaml:"jwt_bearer_grant,omitempty"`
}

type ValidatedClaims struct {
	// Subject is the user identity from the "sub" claim (required for delegation).
	Subject string
	// Issuer is the token issuer from the "iss" claim.
	Issuer string
	// Audience is the list of intended recipients from the "aud" claim.
	Audience []string
	// Expiry is the token expiration time from the "exp" claim.
	Expiry time.Time
	// IssuedAt is the token issuance time from the "iat" claim.
	IssuedAt time.Time
	// JWTID is the unique token identifier from the "jti" claim.
	JWTID string
	// Name is the user's display name from the custom "name" claim.
	Name string
	// Email is the user's email address from the custom "email" claim.
	Email string
	// ClientID is the OAuth client ID from the custom "client_id" claim.
	ClientID string
	// Scopes is the space-delimited scope string assembled from the "scope"
	// or "scp" claim. RFC 9068 §2.2.1 spells it "scope" as a JSON string, but
	// fosite's default JWT claims strategy (token/jwt/claims_jwt.go) writes
	// scopes as a JSON array under "scp" instead, unless ScopeField is
	// explicitly set to String or Both — this server does not set it, so a
	// genuine ToolHive-issued access token used as a subject token carries
	// "scp", not "scope". When both are present, "scope" wins. Empty if the
	// subject token carries neither claim.
	Scopes string
	// MayAct holds the authorized actor from the "may_act" claim (RFC 8693 §4.4).
	// Nil when the subject token does not carry a may_act claim.
	MayAct *MayActClaim
	// ExternalActor is the external actor claim value when the allowlist
	// authorization path matched. It is empty when ActorMatcher alone
	// authorized the token, because a matcher need not identify an actor.
	// It is never populated from token claims by buildValidatedClaims or
	// assignClaim, and is empty for self-issued and may_act-bearing tokens.
	ExternalActor string
	// ExternalActorAuthorized reports that the external issuer authorized
	// delegation through AllowedActors or ActorMatcher. It is separate from
	// ExternalActor because ActorMatcher can authorize without an actor claim.
	// It is false for self-issued and may_act-bearing tokens.
	ExternalActorAuthorized bool
	// ExternalIssuer is set by the external-issuer validation path
	// (validateExternalToken in multi_issuer_validator.go) to that issuer's
	// IssuerURL, for EVERY external token it validates — unlike
	// ExternalActor, this is set regardless of whether the token carries a
	// may_act claim. It exists so the handler can record provenance (which
	// issuer a delegation actually originated from) even for a
	// may_act-bearing external token, which leaves ExternalActor unset.
	// Empty for self-issued tokens. Like ExternalActor, it is never
	// populated from token claims by buildValidatedClaims or assignClaim —
	// it comes from the already-validated issuer config the token matched,
	// not from anything token-supplied, so it cannot be spoofed via claims.
	ExternalIssuer string
	// AllowedDelegateClients is set for EVERY external token — like
	// ExternalIssuer and unlike ExternalActor, it does not depend on whether
	// the token carries a may_act claim (see validateExternalToken). That
	// matters: the may_act path bypasses AllowedActors and ActorMatcher
	// entirely, so it is the path that most needs this restriction to still
	// apply. It is set to that issuer's configured
	// TrustedIssuer.AllowedDelegateClients, and is never populated
	// from token claims by buildValidatedClaims or assignClaim, and the
	// validator never compares it against anything: the validator does not
	// know the authenticated ToolHive client, so checkDelegationConsent
	// (handler.go) is the one that checks actorID against this list. Nil
	// means the issuer did not configure AllowedDelegateClients, which is
	// permissive — any ToolHive client may use the allowlisted external
	// actor, same as before this field existed.
	AllowedDelegateClients []string
	// Extra contains all non-standard claims not captured by other fields.
	Extra map[string]any
}