tokenexchange

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

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 {
	// 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 the token's audience list (a resource/API identifier, not a
	// client ID — required, but not enforced; see looksLikeResourceIdentifier).
	// 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"`
	// 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; empty means only may_act-bearing tokens are
	// accepted. 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"`
	// 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"`
}

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 client identity that the external-issuer validation
	// path has already authorized for delegation, via a per-issuer actor-claim
	// allowlist match. It is set ONLY by that path (multi_issuer_validator.go),
	// after the resolved actor claim is confirmed present in the issuer's
	// AllowedActors — never populated from token claims by buildValidatedClaims
	// or assignClaim. It is empty for self-issued tokens and for external
	// tokens that carry a may_act claim (may_act is authoritative there
	// instead). A non-empty value means the validator has already authorized
	// this token's actor for delegation; it is not itself a raw claim.
	ExternalActor string
	// 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 the AllowedActors allowlist
	// 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
}