aauth

type AccessServerMetadata struct {
	ServerMetadata
	// AuthTokenEndpoint is where PSes send token requests (§9.1).
	// REQUIRED.
	AuthTokenEndpoint string `json:"auth_token_endpoint"`
	// RevocationEndpoint is where a PS revokes a person token it presented
	// to this AS, and a resource a resource token whose aud is this AS
	// (§11.12). RECOMMENDED.
	RevocationEndpoint string `json:"revocation_endpoint,omitempty"`
}

type Agent struct {
	// ID is the agent identifier (the token's sub), stable across rotations.
	ID AgentIdentifier
	// Issuer is the agent provider URL. For a self-hosted agent this is a
	// domain the operator controls, publishing /.well-known/aauth-agent.json.
	// Empty for purely local deployments verified via SelfSignedResolver.
	Issuer string
	// PS is the agent's Person Server URL (optional ps claim).
	PS string
	// TokenTTL bounds minted tokens; capped at 24h per draft -11 §5.3.1.
	TokenTTL time.Duration

	// Key is the agent's signing key. It signs both self-issued agent
	// tokens and HTTP messages; its public half appears in cnf.jwk. Any
	// supported crypto.Signer works (Ed25519 or P-256; see [GenerateKey]),
	// including keys held in a platform keystore.
	Key crypto.Signer
	// contains filtered or unexported fields
}

type AgentClaims struct {
	DWK         string `json:"dwk"`                    // well-known doc name for key discovery
	PS          string `json:"ps,omitempty"`           // the agent's Person Server URL (optional)
	ParentAgent string `json:"parent_agent,omitempty"` // parent id; set marks a sub-agent
	Cnf         Cnf    `json:"cnf"`                    // confirmation claim carrying the agent's public key
	// RegisteredClaims carries iss, sub, jti, iat, exp.
	jwt.RegisteredClaims
}

type AgentIdentifier struct {
	Name          string // the agent name
	Discriminator string // sub-agent discriminator; non-empty marks a sub-agent
	Domain        string // the agent's domain
}

type AgentOption func(*Agent)

type AgentProviderMetadata struct {
	ServerMetadata
	// CallbackEndpoint is the agent's HTTPS callback endpoint (§7.3).
	CallbackEndpoint string `json:"callback_endpoint,omitempty"`
	// EventEndpoint is where the AP receives event tokens from resources
	// (AAuth Events).
	EventEndpoint string `json:"event_endpoint,omitempty"`
	// LocalhostCallbackAllowed permits localhost callbacks. Default false.
	LocalhostCallbackAllowed bool `json:"localhost_callback_allowed,omitempty"`
}

type ApprovedMission struct {
	// S256 identifies the mission, with the PS, everywhere it appears: the
	// mission_s256 of tokens and PS requests.
	S256 string
	// Blob is the exact mission bytes S256 covers. Keep it: re-encoding
	// Mission would not reproduce the identifier.
	Blob []byte
	// Mission is the parsed blob.
	Mission *Mission
	// Capabilities the PS can provide on the person's behalf right now.
	Capabilities []string
	// PersonTokens maps approved resources to person tokens carrying
	// mission_s256; they are also cached for [PSClient.PersonToken].
	PersonTokens map[string]string
}

type AuditRequest struct {
	// MissionS256 names the mission whose log the record belongs to
	// (§8.2.1). REQUIRED.
	MissionS256 string `json:"mission_s256"`
	// Action identifies what was performed (REQUIRED).
	Action string `json:"action"`
	// Description says what was done and the outcome (Markdown, optional).
	Description string `json:"description,omitempty"`
	// Parameters are the arguments that were used.
	Parameters map[string]any `json:"parameters,omitempty"`
	// Result carries the outcome of the action.
	Result map[string]any `json:"result,omitempty"`
}

type AuthClaims struct {
	DWK         string `json:"dwk"`                    // "aauth-person.json" (PS) or "aauth-access.json" (AS)
	PS          string `json:"ps"`                     // the PS the person is represented by
	Scope       string `json:"scope,omitempty"`        // authorized scopes, space-separated
	Account     string `json:"account,omitempty"`      // the account the authorization is for (§11.11)
	MissionS256 string `json:"mission_s256,omitempty"` // the mission it was issued under (§8)
	Tenant      string `json:"tenant,omitempty"`       // the person's organization; (iss, tenant) names it
	Cnf         Cnf    `json:"cnf"`                    // the agent's key
	// RegisteredClaims carries iss, sub, aud, jti, iat, exp.
	jwt.RegisteredClaims
	// contains filtered or unexported fields
}

type AuthResponseVerifyOptions struct {
	// TokenVerifyOptions verifies the auth token's signature under its
	// issuer's key (the PS in three-party, the AS in four-party). A nil
	// Resolver skips signature verification: the agent trusts its PS, so
	// it is not required, but it is RECOMMENDED to detect errors early.
	TokenVerifyOptions
	// Resource is the resource token the agent exchanged, as returned by
	// [VerifyResourceChallenge]: the auth token's iss must be its aud,
	// and the auth token's aud its iss (the resource the agent intends to
	// access).
	Resource *ResourceClaims
	// Agent is the agent; cnf.jwk must be its key.
	Agent *Agent
	// Presented is the token the agent presented to the resource; the auth
	// token's sub must equal its sub.
	Presented string
}

type AuthTokenParams struct {
	// Issuer is the PS's or AS's server identifier (iss).
	Issuer string
	// DWK is WellKnownPerson for a PS (the default) or WellKnownAccess for
	// an AS.
	DWK string
	// PS is the person's PS (ps). Empty means Issuer, which is correct for
	// a PS; an AS sets the PS that sent the token request.
	PS string
	// Resource is the resource token verified with [VerifyResourceToken]:
	// aud becomes its iss, and sub, account, mission_s256, and tenant are
	// copied from it.
	Resource *ResourceClaims
	// Presented is the verified presented_token returned with Resource;
	// its exp bounds the auth token's.
	Presented PresentedToken
	// Agent is the verified agent token that signed the token request (at
	// an AS, the agent_token parameter). Its exp bounds the auth token's,
	// and its key is bound unless Subagent is set.
	Agent *AgentClaims
	// Subagent is the verified subagent_token of a parent-mediated request
	// (§10.2.3): the auth token binds the sub-agent's key.
	Subagent *AgentClaims
	// UpstreamExpiresAt is the exp of the verified upstream_token in call
	// chaining (§10.1.1). MissionExpiresAt is the mission's expires_at.
	// Each, when set, bounds the auth token's exp.
	UpstreamExpiresAt time.Time
	MissionExpiresAt  time.Time
	// Scope is the granted scope, space-separated.
	Scope string
	// TTL is the requested lifetime; zero or more than one hour means one
	// hour.
	TTL time.Duration
	// Now is the issuance time; zero means time.Now.
	Now time.Time
}

type AuthTokenRequest struct {
	// ResourceToken is the resource token to redeem. REQUIRED.
	ResourceToken string `json:"resource_token"`
	// PresentedToken is the token the agent presented to the resource that
	// issued ResourceToken — the person token on the first challenge of a
	// grant, the auth token on a step-up or per-call challenge — whose jti
	// the resource token's presented_jti names. REQUIRED. Its exp bounds
	// the auth token issued.
	PresentedToken string `json:"presented_token"`
	// UpstreamToken is the person or auth token the calling agent presented
	// to the requester, in call chaining (§10.1.1).
	UpstreamToken string `json:"upstream_token,omitempty"`
	// SubagentToken is a sub-agent's agent token, when a parent requests
	// on its behalf (§10.2.3).
	SubagentToken string `json:"subagent_token,omitempty"`
	TokenRequestHints
}

type AuthTokenResponse struct {
	AuthToken string `json:"auth_token"` // the issued aa-auth+jwt
	ExpiresIn int64  `json:"expires_in"` // token lifetime in seconds
}

type AuthTokenVerifyOptions struct {
	TokenVerifyOptions
	// CheckSubject is the record check of draft -11 §9.4.3.2 step 4: it
	// confirms that (iss, sub) matches, or establishes, the resource's
	// record for this person (§13.7). It runs last, on an otherwise valid
	// token; its error is returned unchanged. sub is unique within iss
	// only: a resource MUST NOT match a sub from one issuer against a
	// record established under another.
	CheckSubject func(ctx context.Context, iss, sub string) error
}

type ChainRouter struct {
	// PersonServer is the PS to send the downstream person token and auth
	// token requests to: the iss of an upstream person token, the ps of an
	// upstream auth token. Its endpoints are discovered from its metadata.
	PersonServer string
	// UpstreamToken is the raw upstream token to send as upstream_token.
	UpstreamToken string
	// MissionS256 is the mission the upstream token carries, if any; the PS
	// evaluates the downstream request against it. The intermediary does
	// not send mission_s256 of its own (§7.1).
	MissionS256 string
	// UpstreamExpiresAt is the upstream token's exp. Downstream person and
	// auth tokens expire no later; after it the intermediary uses a later
	// token from the calling agent.
	UpstreamExpiresAt time.Time
	// contains filtered or unexported fields
}

type Clarification struct {
	Question string   // the Markdown question to answer
	Timeout  int      // seconds until the server times out the request (0 if unset)
	Options  []string // discrete answer choices, when the question has them
}

type ClarificationPost struct {
	Action                string `json:"action"`                           // clarification_response or updated_request
	ClarificationResponse string `json:"clarification_response,omitempty"` // the answer text (Markdown, agent-asserted)
	ResourceToken         string `json:"resource_token,omitempty"`         // replacement resource token
	PresentedToken        string `json:"presented_token,omitempty"`        // the token presented to obtain ResourceToken
	Justification         string `json:"justification,omitempty"`          // reason for an updated request
}

type ClarificationReply struct {
	Text           string // the answer, for a clarification_response
	ResourceToken  string // a replacement resource token, for an updated_request
	PresentedToken string // the token presented to obtain ResourceToken (REQUIRED with it)
	Justification  string // optional (RECOMMENDED) reason accompanying an updated_request
	Cancel         bool   // withdraw the request (DELETE the pending URL)
}

type Cnf struct {
	JWK *JWK   `json:"jwk,omitempty"` // the confirmation public key
	JKT string `json:"jkt,omitempty"` // RFC 7638 thumbprint (alternative to JWK)
}

type DeferredOptions struct {
	// PreferWaitSeconds is sent as `Prefer: wait=N` on polling GETs to
	// request long-poll behavior. 0 omits the header.
	PreferWaitSeconds int
	// DefaultPollInterval applies when a 202 carries no Retry-After
	// (spec default: 5s).
	DefaultPollInterval time.Duration
	// MaxPolls bounds the polling loop as a safety valve. 0 = unbounded
	// (the context deadline is then the only limit).
	MaxPolls int
	// Sign re-signs each polling GET. Deferred polling of a signed endpoint
	// keeps presenting the agent's identity; leave nil for unsigned polls.
	Sign func(*http.Request) error
	// OnRequirement is invoked once per distinct AAuth-Requirement header
	// seen on a 202 (e.g. requirement=interaction; url=…; code=…) so the
	// caller can surface the interaction to the user while polling continues.
	OnRequirement func(Requirement)
	// HandleRequirement, when set, is invoked like OnRequirement (once per
	// distinct AAuth-Requirement on a 202, before the next poll) for a
	// requirement the caller satisfies itself — for example an auth-token
	// requirement delivered as a deferred response (draft -11 §6.5.1),
	// after which Sign presents the auth token on the polls. An error
	// stops polling and is returned.
	HandleRequirement func(Requirement) error
	// OnClarification answers a requirement=clarification 202 (§7.3): given
	// the question, it returns the agent's reply. If nil, a clarification
	// requirement is treated as an ordinary pending state (polling continues
	// without answering — which will eventually time out server-side).
	OnClarification func(Clarification) (ClarificationReply, error)
}

type InteractionRequest struct {
	// Type is InteractionTypeInteraction, InteractionTypePayment, or
	// InteractionTypeQuestion. REQUIRED.
	Type string `json:"type"`
	// Description is Markdown context for the user.
	Description string `json:"description,omitempty"`
	// URL and Code are the interaction URL and code to relay (interaction
	// and payment types).
	URL  string `json:"url,omitempty"`
	Code string `json:"code,omitempty"`
	// MaxWait is the most seconds the PS SHOULD hold the relay's deferred
	// response before resolving it (interaction and payment types).
	MaxWait int `json:"max_wait,omitempty"`
	// Question is the Markdown question for the user (question type).
	Question string `json:"question,omitempty"`
	// MissionS256 names the mission the request belongs to.
	MissionS256 string `json:"mission_s256,omitempty"`
}

type InteractionResponse struct {
	Answer string `json:"answer,omitempty"`
}

type JWK struct {
	Kty string `json:"kty"`           // key type; "OKP" (Ed25519) or "EC" (P-256)
	Crv string `json:"crv,omitempty"` // curve; "Ed25519" or "P-256"
	X   string `json:"x,omitempty"`   // base64url public key (OKP) or x coordinate (EC)
	Y   string `json:"y,omitempty"`   // base64url y coordinate (EC only)
	Kid string `json:"kid,omitempty"` // key id; the RFC 7638 thumbprint
	Alg string `json:"alg,omitempty"` // fully-specified algorithm; "Ed25519" or "ES256"
	Use string `json:"use,omitempty"` // intended use; "sig"
}

type JWKS struct {
	Keys []JWK `json:"keys"` // the key set
}

type JWKSCache struct {
	// MinRefresh is the minimum interval between fetches for one issuer
	// (default DefaultJWKSMinRefresh).
	MinRefresh time.Duration
	// MaxAge is the age at which a cached set is discarded (default
	// DefaultJWKSMaxAge).
	MaxAge time.Duration
	// TTL is the freshness lifetime when a response has no cache headers
	// (default DefaultJWKSTTL).
	TTL time.Duration
	// MaxEntries bounds the number of cached issuers (default
	// DefaultJWKSMaxEntries); the least recently fetched entry is evicted.
	MaxEntries int
	// Now returns the current time; nil means time.Now.
	Now func() time.Time
	// contains filtered or unexported fields
}

type JWKSResolver struct {
	// HTTPClient performs discovery fetches; nil uses [DiscoveryClient],
	// which reaches only public https destinations. A client supplied here
	// SHOULD apply the same egress admission (signature-key §7.3).
	HTTPClient *http.Client
	// Cache holds fetched key sets; nil uses DefaultJWKSCache.
	Cache *JWKSCache
}

type KeyRefresher interface {
	RefreshKey(ctx context.Context, iss, dwk, kid string, cnf *JWK) (crypto.PublicKey, error)
}

type KeyResolver interface {
	ResolveKey(ctx context.Context, iss, dwk, kid string, cnf *JWK) (crypto.PublicKey, error)
}

type Limiter interface {
	Allow(ctx context.Context, key string) (ok bool, retryAfter time.Duration)
}

type LimiterFunc func(ctx context.Context, key string) (bool, time.Duration)

type MissingComponentsError struct {
	Required []string // every component the verifier requires
	Missing  []string // the required components the signature omitted
}

type Mission struct {
	// Agent is the agent identifier the mission belongs to. REQUIRED.
	Agent string `json:"agent"`
	// ApprovedAt is the ISO 8601 approval time; it makes s256 globally
	// unique. REQUIRED.
	ApprovedAt string `json:"approved_at"`
	// ExpiresAt is the ISO 8601 time after which the PS treats the mission
	// as terminated. Optional; it caps person and auth tokens.
	ExpiresAt string `json:"expires_at,omitempty"`
	// Description is the approved Markdown scope, which MAY differ from the
	// proposal. REQUIRED.
	Description string `json:"description"`
	// ApprovedTools may be used without per-call permission (§7.7).
	ApprovedTools []MissionTool `json:"approved_tools,omitempty"`
	// ApprovedResources records the resources pre-approved from the
	// proposal; not a limit.
	ApprovedResources []string `json:"approved_resources,omitempty"`
}

type MissionAction struct {
	Action      string `json:"action"`
	Description string `json:"description,omitempty"` // what changed (update)
	Summary     string `json:"summary,omitempty"`     // what was accomplished (completion)
}

type MissionApproval struct {
	// S256 is the mission identifier: the unpadded base64url SHA-256 of
	// the bytes Mission decodes to. REQUIRED.
	S256 string `json:"s256"`
	// Mission is the mission blob, base64url without padding. REQUIRED.
	Mission string `json:"mission"`
	// Capabilities the PS can currently provide on the person's behalf;
	// the agent unions them with its own (§11.7). Not part of the blob.
	Capabilities []string `json:"capabilities,omitempty"`
	// PersonTokens maps each approved resource to a person token carrying
	// mission_s256 = S256.
	PersonTokens map[string]string `json:"person_tokens,omitempty"`
}

type MissionProposal struct {
	// Description is Markdown describing what the agent intends to
	// accomplish. REQUIRED.
	Description string `json:"description"`
	// Tools the agent wants to use.
	Tools []MissionTool `json:"tools,omitempty"`
	// Resources the agent expects to access, as server identifiers; the PS
	// issues a person token for each it approves. Not a limit on the
	// mission.
	Resources []string `json:"resources,omitempty"`
}

type MissionStatusError struct {
	Code              string `json:"error"`                        // mission_terminated
	MissionStatus     string `json:"mission_status"`               // terminated
	TerminationReason string `json:"termination_reason,omitempty"` // a Termination* value, optional
}

type MissionTool struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

type MissionUpdateResponse struct {
	S256 string `json:"s256"`
}

type PSClient struct {
	// BaseURL of the PS, e.g. "https://ps.example". It is the PS's issuer
	// when Discover has not replaced it.
	BaseURL string
	// AuthTokenEndpoint is the auth token endpoint (§7.2); default
	// BaseURL+"/token". Earlier drafts called it the token endpoint.
	AuthTokenEndpoint string
	// PersonTokenEndpoint is the person token endpoint (§7.1); default
	// BaseURL+"/person".
	PersonTokenEndpoint string
	// PermissionEndpoint is the permission endpoint (§7.7); default
	// BaseURL+"/permission".
	PermissionEndpoint string
	// AuditEndpoint is the audit endpoint (§7.8); default BaseURL+"/audit".
	AuditEndpoint string
	// InteractionEndpoint is the interaction endpoint (§7.6); default
	// BaseURL+"/interaction".
	InteractionEndpoint string
	// MissionEndpoint is the mission endpoint (§8); default
	// BaseURL+"/mission".
	MissionEndpoint string
	// Agent is the identity this client acts as. Required.
	Agent *Agent
	// HTTPClient makes requests; nil uses [EgressClient], which reaches only
	// public https destinations. The PS may be named by an upstream token
	// and advertises its own endpoints, so a client that reaches internal
	// addresses is an explicit opt-in: set HTTPClient (for example to
	// http.DefaultClient in local development).
	HTTPClient *http.Client
	// PreferWaitSeconds sets `Prefer: wait=N` on requests that may defer.
	PreferWaitSeconds int
	// OnRequirement is invoked when a deferred (202) response carries an
	// AAuth-Requirement — e.g. requirement=interaction with the URL and code
	// the user must visit. The agent surfaces it; polling continues.
	OnRequirement func(Requirement)
	// OnClarification answers a requirement=clarification 202 (§7.5) that
	// arrives during a deferred request. Nil leaves clarifications
	// unanswered (the request eventually times out server-side).
	OnClarification func(Clarification) (ClarificationReply, error)
	// RefreshMargin is how long before its exp a cached token is replaced
	// rather than presented (draft -11 §7.9.1); zero means
	// DefaultRefreshMargin.
	RefreshMargin time.Duration
	// contains filtered or unexported fields
}

type PendingStatus struct {
	// Status is "pending", or "interacting" once the user has arrived at an
	// interaction endpoint. Unrecognized values MUST be treated as pending.
	Status string `json:"status"`
	// Clarification, when present with requirement=clarification (§7.3.1),
	// is a Markdown question the recipient must answer before proceeding.
	Clarification string `json:"clarification,omitempty"`
	// Timeout is the optional deadline (seconds) to answer a clarification.
	Timeout int `json:"timeout,omitempty"`
	// Options are discrete answer choices, when the question has them.
	Options []string `json:"options,omitempty"`
}

type PermissionRequest struct {
	// Action identifies what the agent wants to do (e.g. a tool name).
	// REQUIRED.
	Action string `json:"action"`
	// Description is an optional Markdown string: what and why.
	Description string `json:"description,omitempty"`
	// Parameters carries the arguments the agent intends to pass.
	Parameters map[string]any `json:"parameters,omitempty"`
	// MissionS256 names the mission the request belongs to (§8.2.1); the
	// PS evaluates the request against the mission and its log.
	MissionS256 string `json:"mission_s256,omitempty"`
}

type PermissionResponse struct {
	Permission string `json:"permission"` // "granted" or "denied"
	// Reason optionally explains a denial (Markdown).
	Reason string `json:"reason,omitempty"`
}

type PersonClaims struct {
	DWK         string `json:"dwk"`                    // "aauth-person.json"
	Cnf         Cnf    `json:"cnf"`                    // the agent's key
	MissionS256 string `json:"mission_s256,omitempty"` // the mission the agent operates under (§8)
	Tenant      string `json:"tenant,omitempty"`       // the person's organization (OpenID Enterprise)
	// RegisteredClaims carries iss, sub, aud, jti, iat, exp.
	jwt.RegisteredClaims
	// contains filtered or unexported fields
}

type PersonServerMetadata struct {
	ServerMetadata
	// AuthTokenEndpoint is where agents send auth token requests (§7.2).
	// REQUIRED. Earlier drafts called it token_endpoint.
	AuthTokenEndpoint string `json:"auth_token_endpoint"`
	// PersonTokenEndpoint is where agents request a person token for a
	// resource (§7.1). REQUIRED.
	PersonTokenEndpoint string `json:"person_token_endpoint"`
	// MissionEndpoint is where an agent proposes, updates, and completes
	// the missions it owns (§8); a mission's own URL is
	// {mission_endpoint}/{mission_s256}.
	MissionEndpoint string `json:"mission_endpoint,omitempty"`
	// PermissionEndpoint is where agents request permission for actions no
	// remote resource governs (§7.7).
	PermissionEndpoint string `json:"permission_endpoint,omitempty"`
	// AuditEndpoint is where agents log actions performed (§7.8).
	AuditEndpoint string `json:"audit_endpoint,omitempty"`
	// InteractionEndpoint is where agents relay interactions to the user
	// through the PS (§7.6).
	InteractionEndpoint string `json:"interaction_endpoint,omitempty"`
	// MissionControlEndpoint is the PS's mission control plane, for parties
	// other than the owning agent (§8.6); defined by a companion
	// specification.
	MissionControlEndpoint string `json:"mission_control_endpoint,omitempty"`
	// RevocationEndpoint is where an agent provider revokes an agent token
	// it issued, and a resource a resource token this PS holds (§11.12).
	// RECOMMENDED.
	RevocationEndpoint string `json:"revocation_endpoint,omitempty"`
	// ScopesSupported lists the scope values the PS supports, including
	// identity and enterprise scopes. RECOMMENDED.
	ScopesSupported []string `json:"scopes_supported,omitempty"`
	// ClaimsSupported lists the identity claim names the PS can provide.
	// RECOMMENDED.
	ClaimsSupported []string `json:"claims_supported,omitempty"`
}

type PersonTokenParams struct {
	// Issuer is the PS's server identifier (iss).
	Issuer string
	// Resource is the resource the token identifies the person to (aud).
	// The PS MUST validate it as a server identifier (§7.1).
	Resource string
	// Subject is the person's directed identifier at Resource (sub),
	// unique within Issuer (§14.1). It MUST NOT be copied from an upstream
	// token (§10.1.1.2).
	Subject string
	// Agent is the verified agent token that signed the request. Its exp
	// bounds the token's, and its key is bound unless Subagent is set.
	Agent *AgentClaims
	// Subagent, when a parent requests on behalf of a sub-agent, is the
	// subagent_token verified with [VerifySubagentToken]; the issued
	// token binds the sub-agent's key (§10.2.3).
	Subagent *AgentClaims
	// MissionS256 names the mission the token is issued under, after the
	// PS has verified it exists, is active, and belongs to the agent (or
	// was copied from the upstream token). MissionExpiresAt, when set, is
	// the mission's expires_at, which bounds the token.
	MissionS256      string
	MissionExpiresAt time.Time
	// UpstreamExpiresAt is the exp of the verified upstream_token in call
	// chaining (§10.1.1), which bounds the token.
	UpstreamExpiresAt time.Time
	// Tenant is the person's organization, when known.
	Tenant string
	// TTL is the requested lifetime; zero or more than one hour means one
	// hour (§7.1.2).
	TTL time.Duration
	// Now is the issuance time; zero means time.Now.
	Now time.Time
	// InsecureSkipIdentifierCheck accepts a Resource that is not a server
	// identifier, for development and tests against local servers.
	InsecureSkipIdentifierCheck bool
}

type PersonTokenRequest struct {
	// Resource is the resource the person token is for, a server
	// identifier (§11.1.1); it becomes the token's aud. REQUIRED.
	Resource string `json:"resource"`
	// MissionS256 names the mission the agent operates under (§8). Not
	// sent with UpstreamToken, which carries the mission itself.
	MissionS256 string `json:"mission_s256,omitempty"`
	// SubagentToken is a sub-agent's agent token, when a parent obtains a
	// person token on its behalf (§10.2.3); the issued token binds the
	// sub-agent's key.
	SubagentToken string `json:"subagent_token,omitempty"`
	// UpstreamToken is the person or auth token the calling agent
	// presented, when a resource acting as an agent needs a person token
	// for a downstream resource (§10.1.1).
	UpstreamToken string `json:"upstream_token,omitempty"`
	TokenRequestHints
}

type PersonTokenResponse struct {
	PersonToken string `json:"person_token"` // the issued aa-person+jwt
	ExpiresIn   int64  `json:"expires_in"`   // token lifetime in seconds
}

type PresentedToken interface {
	// PersonServer is the PS whose namespace the token's sub belongs to:
	// the iss of a person token, the ps of an auth token.
	PersonServer() string
	// contains filtered or unexported methods
}

type ProblemError struct {
	Status int    // the HTTP status
	Code   string // the error member, e.g. mission_not_found
	Detail string // the detail member, if any
	// RetryAfter is the response's Retry-After, when it carried one in
	// seconds (REQUIRED with rate_limited).
	RetryAfter time.Duration
}

type RequestVerifyOptions struct {
	// Window is the signature validity window for created. A signature
	// older than the window is rejected as invalid ([ErrSignatureInvalid]);
	// one further ahead of the verifier's clock than the window is rejected
	// as clock skew ([ErrClockSkew]). Zero means DefaultSignatureWindow.
	Window time.Duration
	// RequiredComponents lists covered components the server requires in
	// addition to the base set (e.g. a resource's
	// additional_signature_components).
	RequiredComponents []string
	// RequireBodyCoverage requires content-digest and content-type to be
	// covered on a request with a body. PS, AS, and revocation endpoints set
	// it (draft -11 §11.3.3.1).
	RequireBodyCoverage bool
	// Now returns the verifier's current time; nil means time.Now.
	Now func() time.Time
}

type Requirement struct {
	// Requirement is the requirement value, one of the Requirement*
	// constants or an extension value.
	Requirement string
	// ResourceToken accompanies requirement=auth-token.
	ResourceToken string
	// URL accompanies requirement=interaction (where the user goes).
	URL string
	// Code accompanies requirement=interaction (shown to the user).
	Code string
}

type ResourceChallengeOptions struct {
	// TokenVerifyOptions verifies the resource token's signature: the
	// resource's key, discovered at {iss}/.well-known/aauth-resource.json
	// by a [JWKSResolver], or pinned.
	TokenVerifyOptions
	// Resource is the resource the agent sent the request to; the token's
	// iss must equal it.
	Resource string
	// Agent is the agent; agent_jkt must be its key's thumbprint.
	Agent *Agent
	// PS is the agent's own person server; the token's ps must equal it.
	PS string
	// Presented is the token the agent presented on the request that was
	// challenged (a person token or an auth token); the resource token's
	// sub and presented_jti must match it.
	Presented string
}

type ResourceClaims struct {
	DWK          string               `json:"dwk"`                    // "aauth-resource.json"
	PS           string               `json:"ps"`                     // the PS the person is represented by
	PresentedJTI string               `json:"presented_jti"`          // jti of the token the request presented
	AgentJKT     string               `json:"agent_jkt"`              // thumbprint of the agent's signing key
	Scope        string               `json:"scope,omitempty"`        // requested scopes, space-separated
	Account      string               `json:"account,omitempty"`      // the account at the resource (§11.11)
	LoginHint    string               `json:"login_hint,omitempty"`   // who the authorization is for; agents pass it unchanged
	MissionS256  string               `json:"mission_s256,omitempty"` // copied from the presented token
	Tenant       string               `json:"tenant,omitempty"`       // copied from the presented token
	Interaction  *ResourceInteraction `json:"interaction,omitempty"`  // resource's own interaction requirement
	// RegisteredClaims carries iss (the resource), aud (PS or AS), sub,
	// jti, iat, exp.
	jwt.RegisteredClaims
}

type ResourceInteraction struct {
	URL  string `json:"url"`  // the resource's interaction endpoint
	Code string `json:"code"` // interaction code to present there
}

type ResourceMetadata struct {
	ServerMetadata
	// AccessMode is the declared access mode (AccessMode*). Advisory.
	AccessMode string `json:"access_mode,omitempty"`
	// AuthorizationEndpoint is where agents request authorization ahead of
	// a challenge (§6.6).
	AuthorizationEndpoint string `json:"authorization_endpoint,omitempty"`
	// ScopeDescriptions maps scope values to Markdown for consent display
	// (§11.10).
	ScopeDescriptions map[string]string `json:"scope_descriptions,omitempty"`
	// SignatureWindow is the signature validity window in seconds for the
	// created timestamp (§11.3.4). Zero means the default, 60.
	SignatureWindow int `json:"signature_window,omitempty"`
	// AdditionalSignatureComponents are HTTP message components agents
	// MUST cover when signing requests to this resource, beyond the base
	// set (§11.3.3.1).
	AdditionalSignatureComponents []string `json:"additional_signature_components,omitempty"`
	// RevocationEndpoint is where the issuer of an auth token or person
	// token for this resource revokes it (§11.12). RECOMMENDED for a
	// resource that accepts person tokens.
	RevocationEndpoint string `json:"revocation_endpoint,omitempty"`
}

type ResourceTokenParams struct {
	// Resource is the resource's own identifier (iss).
	Resource string
	// Audience is the party that will redeem the token: the resource's AS
	// in four-party. Empty means three-party: the PS the presented token
	// names (the iss of a person token, the ps of an auth token, §6.7).
	Audience string
	// Scope is the requested scope, space-separated (§11.10).
	Scope string
	// Account echoes the account parameter of the authorization request
	// (§11.11).
	Account string
	// LoginHint, for a resource that knows who the authorization is for.
	LoginHint string
	// Interaction, when the resource requires its own user-facing flow
	// before the PS can issue an auth token (§7.2.3).
	Interaction *ResourceInteraction
	// TTL is the requested lifetime; zero or more than five minutes means
	// five minutes (§6.7.1).
	TTL time.Duration
	// Now is the issuance time; zero means time.Now.
	Now time.Time
}

type ResourceTokenVerifyOptions struct {
	// TokenVerifyOptions verifies the resource token (the resource's key)
	// and, unless PresentedResolver is set, the presented token.
	TokenVerifyOptions
	// Audience is the recipient's own identifier: the PS in three-party,
	// the AS in four-party (step 1).
	Audience string
	// PS is the person server the token's ps claim must name: at a PS its
	// own identifier, at an AS the PS that sent the token request (step 3).
	PS string
	// AgentJKT is the RFC 7638 thumbprint of the key that signed the token
	// request, or, for a parent-mediated sub-agent request, of the
	// subagent_token's cnf.jwk (step 2).
	AgentJKT string
	// PresentedToken is the presented_token parameter of the token request
	// (§7.2.1, §9.1.1). Required.
	PresentedToken string
	// PresentedResolver, when set, locates the presented token's issuer
	// key instead of Resolver.
	PresentedResolver KeyResolver
	// CheckMission, when set and the resource token carries mission_s256,
	// verifies that the mission is active and before its expires_at
	// (step 4; a PS MUST). Its error is returned unchanged.
	CheckMission func(ctx context.Context, missionS256 string) error
}

type RevocationClient struct {
	// Signer signs the revocation and its polls under the jwks_uri scheme
	// (§11.3.2). Required.
	Signer ServerSigner
	// HTTPClient makes requests; nil uses [DiscoveryClient], which reaches
	// only public https destinations: the endpoint comes from the
	// recipient's metadata.
	HTTPClient *http.Client
	// PreferWaitSeconds, when positive, is sent as Prefer: wait=N: how
	// long the caller will wait for the cascade before a 202.
	PreferWaitSeconds int
}

type RevocationOutcome struct {
	Recipient string `json:"recipient"`       // the downstream party's identifier
	Error     string `json:"error,omitempty"` // RevocationUnsupported or RevocationUnavailable
}

type RevocationRequest struct {
	// JTI names the token to revoke within the caller's namespace.
	// REQUIRED.
	JTI string `json:"jti"`
	// Exp is the revoked token's own exp (seconds since the epoch), which
	// bounds how long the recipient remembers the revocation. REQUIRED.
	Exp int64 `json:"exp"`
}

type RevocationResponse struct {
	Downstream []RevocationOutcome `json:"downstream,omitempty"`
}

type SelfSignedResolver struct{}

type ServerCaller struct {
	// ID is the caller's identity: its issuer, the iss of every token it
	// mints.
	ID string
	// DWK is the metadata document its key was discovered through, which
	// names its role (e.g. aauth-person.json for a PS).
	DWK string
	// Kid is the key that signed the request.
	Kid string
}

type ServerMetadata struct {
	// Issuer is the server's HTTPS URL (REQUIRED). It MUST equal the URL
	// the document was fetched from minus /.well-known/{dwk}
	// ([FetchMetadata] checks this) and is the iss of the JWTs the server
	// issues.
	Issuer string `json:"issuer"`
	// JWKSURI is the URL of the server's JSON Web Key Set. REQUIRED for an
	// agent provider, PS, and AS; for a resource only when it issues
	// resource tokens or makes signed calls (§11.2.4).
	JWKSURI string `json:"jwks_uri,omitempty"`
	// AcceptSignatureAlgs lists the fully-specified JWS algorithms the
	// server's verifier accepts, exactly the set, with the semantics of the
	// Accept-Signature-Alg response header. One list per server.
	AcceptSignatureAlgs []string `json:"accept_signature_algs,omitempty"`
	// Name is a human-readable display name.
	Name string `json:"name,omitempty"`
	// Description is Markdown describing the server, for consent screens
	// and dashboards. Implementations MUST sanitize it before rendering.
	Description string `json:"description,omitempty"`
	// LogoURI, LogoDarkURI, DocumentationURI, TOSURI, and PolicyURI are
	// https URLs for the server's logo (and dark-background variant),
	// developer documentation, terms of service, and privacy policy.
	LogoURI          string `json:"logo_uri,omitempty"`
	LogoDarkURI      string `json:"logo_dark_uri,omitempty"`
	DocumentationURI string `json:"documentation_uri,omitempty"`
	TOSURI           string `json:"tos_uri,omitempty"`
	PolicyURI        string `json:"policy_uri,omitempty"`
}

type ServerSigner struct {
	// Issuer is the server's issuer (its server identifier, §11.1.1),
	// sent as the id parameter.
	Issuer string
	// DWK is the server's metadata document name: WellKnownPerson,
	// WellKnownAccess, WellKnownAgent, or WellKnownResource.
	DWK string
	// Kid identifies Key in the JWKS at the server's jwks_uri. That JWKS
	// entry MUST carry a fully-specified alg (§11.4).
	Kid string
	// Key is the server's signing key.
	Key crypto.Signer
}

type SignatureError struct {
	// Code is the required error member.
	Code string
	// RequiredInput accompanies invalid_input: the covered components the
	// server requires (an Inner List of Strings).
	RequiredInput []string
	// Params carries any other members, each in its RFC 9651 serialized
	// form (a token, a quoted string, an inner list, ...). Unknown members
	// are preserved; recipients ignore what they don't know.
	Params map[string]string
	// AcceptSchemes, when set, overrides the Accept-Signature-Scheme list
	// WriteSignatureError sends with unsupported_scheme (for example
	// jwks_uri on an endpoint for server-signed requests). It is not part
	// of the Signature-Error header.
	AcceptSchemes []string
}

type SignatureKey struct {
	Label  string            // the dictionary key; matches the Signature-Input label
	Scheme string            // the scheme token, e.g. "jwt" or "jwks_uri"
	Params map[string]string // String-valued parameters (jwt; id, dwk, kid)
}

type StaticResolver map[string]JWKS

type TokenError struct {
	Code string // the §11.9.3 error code
	Err  error  // the underlying failure, if any
}

type TokenRequestHints struct {
	// Justification is Markdown declaring why access is requested; the PS
	// presents it as agent-asserted content and asks clarification
	// questions about it (§7.5).
	Justification string `json:"justification,omitempty"`
	// LoginHint is a hint about who to authorize ([OpenID.Core]). When a
	// resource token carries login_hint, the agent sends it unchanged.
	LoginHint string `json:"login_hint,omitempty"`
	// Tenant and DomainHint follow OpenID Connect Enterprise Extensions.
	Tenant     string `json:"tenant,omitempty"`
	DomainHint string `json:"domain_hint,omitempty"`
	// Prompt is a space-delimited list of none, login, consent, and
	// select_account.
	Prompt string `json:"prompt,omitempty"`
	// Platform is the agent's runtime platform, from the AAuth Platform
	// Value registry (agent-attested).
	Platform string `json:"platform,omitempty"`
	// Device is a short printable label for the user's dashboard, at most
	// 64 characters (agent-attested).
	Device string `json:"device,omitempty"`
	// Capabilities are the capability values (§11.7) the agent can handle
	// for this request — the body form of AAuth-Capabilities, which is not
	// used on PS endpoints. Without interaction, a PS that must reach the
	// person answers user_unreachable.
	Capabilities []string `json:"capabilities,omitempty"`
}

type TokenVerifyOptions struct {
	// Resolver locates the issuer's token-signing key. Required.
	Resolver KeyResolver
	// Signature tunes HTTP message-signature verification in the
	// VerifyAndExtract helpers. Its clock (Now) and validity window
	// (Window) also bound how far a token's iat may be ahead of the
	// verifier's clock before it is refused as clock skew (§11.5.2).
	Signature RequestVerifyOptions
	// InsecureSkipIdentifierCheck accepts an iss (and ps) that is not a
	// server identifier (§11.1.1: https, host only, lowercase), for
	// development and tests against local servers. Never set it in
	// production.
	InsecureSkipIdentifierCheck bool
}

type Transport struct {
	// Agent is the identity every request is signed as. Required.
	Agent *Agent
	// PS obtains person tokens and auth tokens. Optional: without it,
	// person-token and auth-token requirements fail with an error
	// (identity-only deployments; an agent with no PS surfaces the
	// requirement as an error, §6.4).
	PS *PSClient
	// MissionS256, when set, is the mission person tokens are requested
	// under (§7.1, §8); it flows into resource tokens and auth tokens. It
	// is not sent with UpstreamToken, which carries the mission itself.
	MissionS256 string
	// UpstreamToken, for an intermediary in call chaining (§10.1.1), is the
	// person or auth token the calling agent presented to it. It is sent
	// as upstream_token in the person and auth token requests to PS — the
	// person server the upstream token names — so the tokens are issued
	// for that person. UpstreamExpiresAt is its exp: no downstream token
	// outlives it, and once it passes the intermediary needs a later token
	// from the calling agent. See [ChainRouter.Transport].
	UpstreamToken     string
	UpstreamExpiresAt time.Time
	// Base is the underlying RoundTripper (default http.DefaultTransport).
	Base http.RoundTripper
	// ResourceVerify verifies the signature of resource tokens in
	// auth-token challenges (§6.7.3). A nil Resolver uses a
	// [JWKSResolver], which discovers the resource's key at
	// {iss}/.well-known/aauth-resource.json.
	ResourceVerify TokenVerifyOptions
	// AuthVerify, when its Resolver is set, also verifies the signature of
	// auth tokens the PS returns (§9.4.4 step 1, SHOULD). A nil Resolver
	// runs the claim checks only: the agent trusts its PS.
	AuthVerify TokenVerifyOptions
	// OnRequirement surfaces interaction requirements (URL + code) that
	// arrive while a request is deferred.
	OnRequirement func(Requirement)
	// MaxBodyBytes bounds request-body buffering (default 4 MiB).
	MaxBodyBytes int64
	// RefreshMargin is how long before its exp a cached auth token is
	// replaced rather than presented (default DefaultRefreshMargin, five
	// minutes, §7.9.1). Person tokens follow PS.RefreshMargin.
	RefreshMargin time.Duration
	// MaxClockSkewWait bounds the wait before re-presenting a request a
	// resource refused with clock_skew (default 10 seconds). A negative
	// value disables the retry.
	MaxClockSkewWait time.Duration
	// contains filtered or unexported fields
}

type UnsupportedSchemeError struct {
	Scheme   string   // the scheme presented
	Accepted []string // the schemes the verifier accepts here
}

type UpstreamVerifyOptions struct {
	// TokenVerifyOptions locates the upstream token's issuer key.
	TokenVerifyOptions
	// Intermediary is the verified agent token of the intermediary making
	// the downstream request — at the PS the one that signed it, at the AS
	// the agent_token parameter. The intermediary is its own agent
	// provider, so its iss is its resource identifier, which the upstream
	// token's aud must equal (step 3, §10.1.1.1).
	Intermediary *AgentClaims
	// PS is, at a PS, its own identifier, and at an AS, the PS that signed
	// the request. A person token's iss, or an auth token's ps, must equal
	// it (step 2).
	PS string
	// AtAS selects the AS's issuer rule: an auth token's iss is not checked
	// beyond its signature. At a PS (false), an auth token's iss must be
	// the PS or an issuer TrustAuthIssuer accepts.
	AtAS bool
	// TrustAuthIssuer, at a PS, reports whether iss is an AS this PS
	// presented a person token to for the token's aud and sub (§9.1.1).
	// Nil accepts only the PS itself.
	TrustAuthIssuer func(iss, aud, sub string) bool
}

type VerifyAgentTokenOptions struct {
	// Resolver locates the token-signature key. Required.
	Resolver KeyResolver
	// RequireProviderClaims enforces the draft -11 agent-token profile
	// strictly (§5.3.3, §11.5.2): iss must be a server identifier
	// (§11.1.1), dwk must equal WellKnownAgent, jti must be present, and a
	// ps claim, when present, must be a server identifier. Self-hosted
	// local deployments MAY relax this (signature-key §3.8 makes iss/dwk
	// SHOULD; the AAuth agent-token profile makes them MUST — set true for
	// cross-domain interop).
	RequireProviderClaims bool
	// Signature tunes HTTP message-signature verification in
	// VerifyAndExtractAgent (validity window, required components, clock).
	Signature RequestVerifyOptions
}

type VerifyServerOptions struct {
	// Resolver discovers the caller's key from (id, dwk, kid); nil uses a
	// JWKSResolver with DefaultJWKSCache and [DiscoveryClient], which
	// reaches only public https destinations. Discovery verifies that the
	// metadata issuer equals id (issuer_missing / issuer_mismatch).
	Resolver KeyResolver
	// DWKs, when non-empty, restricts the metadata documents (roles)
	// accepted, e.g. []string{WellKnownPerson} at an AS token endpoint.
	DWKs []string
	// TrustSigner, when set, is consulted before any fetch; returning
	// false rejects the caller with invalid_key. Verifiers SHOULD check id
	// against expected origins (signature-key §7.3); a verifier that
	// accepts unknown signers obtains an origin-bound pseudonym, not an
	// authorized identity.
	TrustSigner func(id, dwk string) bool
	// Signature tunes HTTP message-signature verification. PS, AS, and
	// revocation endpoints should set RequireBodyCoverage (§11.3.3.1).
	Signature RequestVerifyOptions
	// InsecureSkipIdentifierCheck accepts an id that is not a server
	// identifier (§11.1.1: https, host only, lowercase), for development
	// and tests against local servers. Never set it in production.
	InsecureSkipIdentifierCheck bool
}