tokenexchange

type ActorDeniedError struct {
	// Reason is the client-facing reason. It must be one of the ActorDeniedReason
	// constants. Any other value, including the zero value, is a server error.
	Reason ActorDeniedReason
	// contains filtered or unexported fields
}

type ActorDeniedReason string

type ActorProfile struct {
	// Name is the validator's registered name, for logs.
	Name string
	// ActorTokenType is the actor_token_type the client must send.
	ActorTokenType string
	// ActorValidatorRegistration is the registration that Name selects.
	ActorValidatorRegistration
}

type ActorRequest struct {
	// ActorToken is the raw actor credential presented by the client. It is always set
	// when the validator is called. Do not log it or put it in an error.
	ActorToken string
	// ActorTokenType is the actor_token_type parameter. The caller guarantees it is a
	// type the client is allowed to present.
	ActorTokenType string
	// ClientID is the authenticated client that asked for the ID-JAG. It is always set.
	ClientID string
	// Grant describes the user the ID-JAG is issued for.
	Grant GrantOwner
	// Target describes the gateway the ID-JAG is for. It is always set when the
	// validator is called. A validator that does not decide by target may ignore it.
	Target ActorTarget
}

type ActorResult struct {
	// AgentID names the agent instance. ToolHive places it in the act claim as sub, next
	// to the issuer registered for the validator. It must follow the rules in
	// ActorTokenValidator. The zero value is a server error.
	AgentID string
	// ExpiresAt is when the actor credential stops being valid. The issuing code caps
	// the ID-JAG's lifetime at this time. Times are compared in whole seconds. A value
	// at or before the time ToolHive checks the result, but less than 60 seconds
	// before it, is answered as actor_token_expired. A value 60 or more seconds before
	// it is a server error, as is the zero value.
	ExpiresAt time.Time
	// CredentialSubject identifies the credential for audit logs. It never enters a
	// token. The zero value means no subject is recorded.
	CredentialSubject string
}

type ActorTarget struct {
	// Issuer is the issuer of the target authorization server as configured. It
	// becomes the ID-JAG's aud claim. It is always set when the validator is called.
	Issuer string
	// Resource is the resource the client requested, which is one of the target's
	// configured resources. It is always set.
	Resource string
}

type ActorTokenValidator interface {
	ValidateActor(ctx context.Context, req ActorRequest) (ActorResult, error)
}

type ActorValidatorRegistration struct {
	// Validator checks the actor token. Required.
	Validator ActorTokenValidator
	// ActIssuer is the value of act.iss in every ID-JAG built from this
	// validator's answer. It is the namespace in which AgentID is unique
	// (RFC 7519 section 4.1.2). It is often the actor token's issuer, but it does
	// not have to be: ToolHive never compares it to the token. Consumers may key
	// agent policy on (act.iss, act.sub), so changing ActIssuer renames every
	// agent. ToolHive emits it exactly as configured. Several registrations may
	// share an ActIssuer. Their validators must then not return the same AgentID,
	// which ToolHive cannot check.
	//
	// ToolHive does not check that a SPIFFE AgentID belongs to the trust domain
	// named by a spiffe:// ActIssuer. A validator that accepts JWT-SVIDs must
	// verify each SVID against the bundle of the trust domain in its sub; that
	// check is the binding. A later release may refuse, at issuance, an AgentID
	// outside the trust domain of a spiffe:// ActIssuer.
	ActIssuer string
}

type ConfiguredClientPolicy struct {
	// AllowedSourceClients are the client_id values, besides the client
	// itself, whose self-issued subject tokens the client may exchange on the
	// default path. The exchange-grant path accepts only these clients, not the
	// client's own tokens, so startup requires the list with
	// exchange_refresh_tokens.
	AllowedSourceClients []string
	// SubjectTokenAudiences are the audiences a self-issued subject token must
	// carry (one of them, matched exactly) on every exchange path, including
	// the client's own tokens. They are input only and never grant an
	// access-token audience. Empty means no requirement on the default path
	// but refuses on the exchange-grant path, which is why startup requires
	// the list with exchange_refresh_tokens.
	SubjectTokenAudiences []string
	// ExchangeRefreshTokens caps the lifetime of refresh tokens this client may
	// obtain through token exchange, keyed by the token-type URN of the grant
	// (oauthproto.TokenTypeIDJAG or oauthproto.TokenTypeRefreshToken). A missing
	// key means that grant kind is refused, so look up with the comma-ok form.
	// Every present value is > 0 and <= 720h, as config validation enforces. Nil
	// when the client has no exchange_refresh_tokens block.
	ExchangeRefreshTokens map[string]time.Duration
	// IDJAGTargets are the authorization servers this client may ask for an
	// ID-JAG for, keyed by the issuer exactly as configured. Request-time
	// lookup of the audience parameter is exact. Nil when the client has no
	// id_jag block.
	IDJAGTargets map[string]IDJAGTarget
	// ActorProfile is the actor-token check ID-JAG issuance runs for this
	// client. Nil when the client has no actor profile. It is set only for
	// clients configured at startup, never for dynamically registered ones.
	ActorProfile *ActorProfile
}

type FactoryOption func(*factoryOptions)

type GrantOwner struct {
	// Subject is the user's sub claim as ToolHive knows it. It is always set.
	Subject string
	// SubjectIdentifier is the grant's sub_id as the raw RFC 9493 JSON text. Parse it;
	// do not compare it as text. The zero value means the grant has none.
	SubjectIdentifier string
	// Upstream is the user's identity at the upstream provider. It is the zero value
	// when the server does not record upstream identities (see
	// authserver.Config.SubjectIdentifierAudiences). A validator that needs it returns a plain error
	// when it is missing, not a denial. ToolHive passes either a complete identity,
	// with all four members set, or the zero value.
	Upstream UpstreamIdentity
}

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

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

type IDJAGTarget struct {
	// Issuer is the target authorization server's issuer as configured. It is
	// the request's audience and the ID-JAG's aud.
	Issuer string
	// ClientID is the delegate client's client_id at the target.
	ClientID string
	// Resources are the resource values the client may request.
	Resources []string
	// Lifetime is how long each ID-JAG lives.
	Lifetime time.Duration
	// RequiredSubjectClaims are the subject claims every ID-JAG for this target
	// must carry, as configuration tokens (upstream_subject, sub_id).
	RequiredSubjectClaims []string
}

type JWTBearerAssertionValidator interface {
	ValidateJWTBearerAssertion(
		ctx context.Context, rawToken string, defaultAudiences []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. When empty, the plain
	// JWT-bearer grant accepts the token endpoint, and the ID-JAG grant accepts
	// the token endpoint and this server's issuer identifier, unless the issuer
	// is also an allowed resource audience. A configured list replaces both
	// defaults.
	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 RefreshTokenHandler struct {
	// contains filtered or unexported fields
}

type RefreshTokenOption func(*refreshTokenOptions)

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 UpstreamIdentity struct {
	// Issuer is the upstream's issuer URL.
	Issuer string
	// Subject is the upstream's raw sub from its validated ID token.
	Subject string
	// StableClaim names the upstream claim ToolHive keys users on, for example
	// "uid" or "oid", or "sub".
	StableClaim string
	// StableValue is that claim's value for this user. A validator can bind users by
	// a claim that is specific to one issuer.
	StableValue string
}

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
	// Claims holds every verified claim as decoded, registered ones included.
	// It is shared with the validator's decode result: treat it as read-only
	// and deep-copy before handing it to code that may modify it.
	Claims map[string]any
}