Help us shape the future of Go! Take the 2026 Go Developer Survey

aauth

package module
v0.0.0-...-ad34a9a Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 3, 2026 License: MIT Imports: 25 Imported by: 0

README ¶

AAuth for Go

Go packages for AAuth, a protocol that tells an API which software agent is calling it and on whose behalf. The agent signs every HTTP request with its own key. The API checks that signature and the token sent with it. When the API needs more than the agent's identity, it asks for a token that names the person the agent acts for and what that person allowed.

There is a package for each party in the protocol: the agent, the Agent Provider that vouches for it, the API (called a Resource), and the servers that speak for the person or for the API. How AAuth works introduces them.

Each server role is an http.Handler that you mount in your own HTTPS server, and each client sends its requests through the *http.Client you give it. Your service decides whom to trust, authenticates people and stores state; the packages sign, check and decide.

Get started

You need Go 1.25 or later. In a new directory:

go mod init example.com/hello-aauth
go get gitlab.com/sidecat-dev/aauth-go@6fcdb1e

Then save the getting-started program as main.go, and run it:

go mod tidy
go run .

It starts an Agent Provider and an API on loopback ports, with TLS, and has an agent call the API. Get started walks through the output and the code. In a clone of this repository, go run ./example/gettingstarted runs the same program.

Install

The module has no release tags: you build against a commit on main, named by its hash.

go get gitlab.com/sidecat-dev/aauth-go@6fcdb1e

go get records the commit in go.mod as a pseudo-version, v0.0.0-20261102114704-6fcdb1ef51b0. Commit go.mod and go.sum with your code, so that every build uses the same commit. To move to a later commit, run go get again with its hash.

Package What it does Guide
agent Signs an agent's requests and checks the tokens it receives, one step per call Agent
agentprovider Issues Agent tokens and publishes the provider's keys Agent Provider
resource Checks requests to an API before your handler runs Resource
personserver Knows which person an agent acts for, and issues tokens that say so Person Server
accessserver Decides access for an API from the API's own rules Access Server
supervisionserver, supervision Approves or refuses an agent's requests for the person Supervision Server
r3 and r3/vocab/*, budgets, events Operation lists, spending caps and events, used by the roles R3, Budgets, Events
aauth, signaturekey, jose Tokens, HTTP signatures and keys, used by the roles
testutil, */storetest In-memory stores for tests, and the contracts a durable store must pass
diagnostics Shows the local cause of each refusal a handler sends Errors

Documentation

  • docs/: how AAuth works, a guide for each role and each feature, and what to do about each error.
  • USE-IN-YOUR-SERVICE.md: the full reference for running each role in a service.
  • CONFORMANCE.md: how the conformance suite measures the library, and what its latest run says and does not say.
  • INTERPRETATIONS.md: the choices made where a draft leaves room.
  • SPECIFICATIONS.md: the exact draft text implemented.
  • SECURITY.md: how to report a vulnerability, and what your service is responsible for.
  • CONTRIBUTING.md: how to change the code and run its tests.

Status

The packages implement the core AAuth protocol and HTTP Signature Keys, and the R3, Budgets, Events, Supervision and Bootstrap drafts, each described, with its limits, in the guides under docs/features and docs/roles. APIs can change from one commit to the next.

aauth-rust implements the same drafts in Rust. The two are tested against each other over HTTPS, in both directions. INTERPRETATIONS.md records each choice this library makes where a draft leaves room.

License

MIT; see LICENSE.

Documentation ¶

Overview ¶

Package aauth implements the Core token profiles and validation primitives used by the AAuth role packages in this module.

Start with VerifyAgentToken, VerifyPersonToken, VerifyResourceToken or VerifyAuthToken to check an individual token. MintAgentToken creates an Agent token with an issuer-owned signing key. These Core checks do not verify an HTTP request or apply application access policy; the resource package provides handlers that compose those checks. See USE-IN-YOUR-SERVICE.md for the tested service example and GLOSSARY.md for roles, token fields, key resolution and clocks.

The current implementation covers direct Agent and Person identity access, Resource-managed opaque sessions, immediate and deferred three-party PS authorization, immediate four-party federation, bounded AS approval and payment waits, mission-bound authorization through both topologies, parent-mediated one-level sub-agents (VerifySubagentToken), bounded Agent-token, Agent-binding and three-party revocation, and one same-Person-Server Resource call chain. It also includes Person-Server-hosted interaction and baseline or Resource-held delivery of the auth-token requirement. The guides under docs/features give each feature's limits.

Index ¶

Constants ¶

View Source 
const (
	AgentTokenType    = "aa-agent+jwt"
	PersonTokenType   = "aa-person+jwt"
	ResourceTokenType = "aa-resource+jwt"
	AuthTokenType     = "aa-auth+jwt"

	AgentDiscoveryDocument    = "aauth-agent.json"
	ResourceDiscoveryDocument = "aauth-resource.json"
	PersonDiscoveryDocument   = "aauth-person.json"
	AccessDiscoveryDocument   = "aauth-access.json"
)
View Source 
const MaximumAuthTokenLifetime = time.Hour

MaximumAuthTokenLifetime is the Core upper bound from iat to exp.

View Source 
const ResourceLinkRelation = "aauth-resource"

ResourceLinkRelation is the link relation type that names the resource metadata document governing what a response or an HTML page describes.

Variables ¶

View Source 
var (
	// ErrInvalidPresentedToken maps to invalid_presented_token.
	ErrInvalidPresentedToken = errors.New("aauth: presented token is invalid")
	// ErrExpiredPresentedToken maps to expired_presented_token.
	ErrExpiredPresentedToken = errors.New("aauth: presented token is expired")
	// ErrPresentedTokenMismatch means a verified presented token is not the
	// one the resource token names; it maps to invalid_resource_token.
	ErrPresentedTokenMismatch = errors.New("aauth: resource token does not match the presented token")
)
View Source 
var (
	// ErrInvalidSubagentToken maps to invalid_subagent_token: the sub-agent
	// token is malformed or unverifiable, is not a sub-agent token, does not
	// name the signing parent in parent_agent, has another issuer or Person
	// Server than its parent, or reuses the parent's key.
	ErrInvalidSubagentToken = errors.New("aauth: sub-agent token is invalid")
	// ErrExpiredSubagentToken maps to expired_subagent_token.
	ErrExpiredSubagentToken = errors.New("aauth: sub-agent token is expired")
)
View Source 
var ErrRevocationLimitReached = errors.New("aauth: revocation entry limit reached")

ErrRevocationLimitReached is returned by a revocation store that already holds as many entries for the request's issuer as it allows. The endpoint answers 429 rate_limited and records nothing.

View Source 
var ErrRevocationUnavailable = errors.New("aauth: revocation_unavailable")

ErrRevocationUnavailable is the caller's reading of a revocation 200 whose body is present but is not the Protocol -11 response object. The caller MAY revoke again later.

Functions ¶

func AddResourceLinks(header http.Header, issuers ...string) error

AddResourceLinks adds one Link field naming the metadata document of each resource identifier, for example to the response of a developer portal or of the page at a resource's documentation_uri.

func EncodeRevocationReport ¶ 

func EncodeRevocationReport(downstream []DownstreamRevocation) ([]byte, error)

EncodeRevocationReport returns the body of a revocation 200 that reports downstream outcomes, {"downstream":[...]}. An empty report returns nil: the recipient then answers 200 with no body and no Content-Type.

func EncodeRevocationRequest ¶ 

func EncodeRevocationRequest(request RevocationRequest) ([]byte, error)

EncodeRevocationRequest returns the Protocol 11 request body {jti, exp}.

func FormatAAuthAccess ¶ 

func FormatAAuthAccess(token string) (string, error)

FormatAAuthAccess validates an opaque session token for use as an AAuth-Access field value.

func FormatAgentTokenRequirement ¶ 

func FormatAgentTokenRequirement() string

FormatAgentTokenRequirement returns the canonical parameterless agent-token AAuth-Requirement field value.

func FormatAuthTokenRequirement ¶ 

func FormatAuthTokenRequirement(value AuthTokenRequirement) (string, error)

FormatAuthTokenRequirement returns the canonical AAuth-Requirement field value for a Core auth-token requirement.

func FormatCapabilities ¶ 

func FormatCapabilities(capabilities []string) (string, error)

FormatCapabilities returns one canonical AAuth-Capabilities field value.

func FormatInteractionRequirement ¶ 

func FormatInteractionRequirement(value InteractionRequirement) (string, error)

FormatInteractionRequirement returns the canonical AAuth-Requirement field value for a Core interaction requirement.

func FormatInteractionVisitURL ¶ 

func FormatInteractionVisitURL(interactionURL, code, callback string) (string, error)

FormatInteractionVisitURL returns the user-facing URL for an interaction: {url}?code={code}, with &callback={callback} when callback is not empty. An Agent uses it to direct the person with its own callback; a Person Server uses it to send the person to a Resource's interaction with its per-flow callback. url must be HTTPS without query or fragment, code an emitted interaction code, and callback a URL ValidateInteractionCallback accepts with loopback allowed.

func FormatPersonTokenRequirement ¶ 

func FormatPersonTokenRequirement() string

FormatPersonTokenRequirement returns the canonical parameterless person-token AAuth-Requirement field value. 

func FormatResourceLinks(issuers ...string) (string, error)

FormatResourceLinks returns a Link field value naming the metadata document of each resource identifier, in order. A response that describes several resources may carry one link for each.

func FormatSessionAuthorization ¶ 

func FormatSessionAuthorization(token string) (string, error)

FormatSessionAuthorization validates an opaque session token and formats an Authorization field value using the AAuth scheme.

func InteractionCallbackURL ¶ 

func InteractionCallbackURL(callback string, failure InteractionCallbackError) (string, error)

InteractionCallbackURL returns where an interaction host sends the person when the interaction ends: callback itself when failure is empty, or {callback}?error={failure} when the interaction cannot be completed. failure must be empty or one of the registered callback errors.

func MatchInteractionCode ¶ 

func MatchInteractionCode(expected, entered string) bool

MatchInteractionCode compares an emitted interaction code with human input. Input comparison is case-insensitive, ignores grouping hyphens, and accepts the Crockford transcription aliases I/L for 1 and O for 0.

func MintAgentToken ¶ 

func MintAgentToken(issuer string, key jose.SigningKey, request AgentTokenRequest, now time.Time, jti string) (string, error)

MintAgentToken creates an agent token with the supplied issuer key.

func MintAuthToken ¶ 

func MintAuthToken(key jose.SigningKey, claims AuthTokenClaims) (string, error)

MintAuthToken creates a proof-bound authorization assertion.

func MintAuthTokenCore ¶ 

func MintAuthTokenCore(key jose.SigningKey, claims AuthTokenClaims) (string, error)

MintAuthTokenCore validates only the Core claim layer and deliberately leaves raw companion claims to a typed companion package. Calling it directly does not establish companion authorization.

func MintPersonToken ¶ 

func MintPersonToken(key jose.SigningKey, claims PersonTokenClaims) (string, error)

MintPersonToken constructs a proof-bound, resource-directed person token.

func MintResourceToken ¶ 

func MintResourceToken(key jose.SigningKey, claims ResourceTokenClaims) (string, error)

MintResourceToken creates a short-lived resource assertion.

func MintResourceTokenCore ¶ 

func MintResourceTokenCore(key jose.SigningKey, claims ResourceTokenClaims) (string, error)

MintResourceTokenCore validates only the Core claim layer and deliberately leaves raw companion claims to a typed companion package. Calling it directly does not establish companion authorization.

func MissionS256 ¶ 

func MissionS256(exactJSON []byte) string

MissionS256 returns the unpadded base64url SHA-256 identifier used for exact mission-blob and accepted-update bytes.

func NormalizeInteractionCode ¶ 

func NormalizeInteractionCode(code string) (string, error)

NormalizeInteractionCode prepares human-entered Crockford base32 for comparison. It removes grouping hyphens, folds case, and accepts I/L for 1 and O for 0. The returned value contains at least eight canonical symbols.

func ParseAAuthAccess ¶ 

func ParseAAuthAccess(values []string) (string, error)

ParseAAuthAccess validates one AAuth-Access field value and returns its opaque session token.

func ParseAgentTokenRequirement ¶ 

func ParseAgentTokenRequirement(values []string) error

ParseAgentTokenRequirement verifies an agent-token AAuth-Requirement field. Unknown parameters are ignored as required by AAuth Core.

func ParseCapabilities ¶ 

func ParseCapabilities(values []string) ([]string, error)

ParseCapabilities parses the AAuth-Capabilities field as an RFC 9651 List of Tokens. Parameters on capability items are extension data and are ignored, whatever their type. An absent field means that the Agent declared no capabilities.

func ParsePersonTokenRequirement ¶ 

func ParsePersonTokenRequirement(values []string) error

ParsePersonTokenRequirement verifies a person-token AAuth-Requirement field. Unknown parameters are ignored as required by AAuth Core.

func ParseScope ¶ 

func ParseScope(value string) ([]string, error)

ParseScope validates and splits one space-delimited OAuth scope value.

func ParseSessionAuthorization ¶ 

func ParseSessionAuthorization(values []string) (string, error)

ParseSessionAuthorization validates one Authorization field carrying the AAuth scheme and returns its opaque session token.

func ReadInteractionCallback ¶ 

func ReadInteractionCallback(rawQuery string) error

ReadInteractionCallback reads the raw query a callback URL received. It returns nil when the interaction completed and an InteractionCallbackError when the query carries error. The recipient must then not treat the pending request as completable and must surface the error to its caller. An unregistered or repeated error value, or a query that cannot be parsed, is reported as server_error.

func ReadRevocationResponse ¶ 

func ReadRevocationResponse(response *http.Response, maxBytes int64) error

ReadRevocationResponse reads the body of a revocation 200 of at most maxBytes and validates it as ReadRevocationReport does, discarding the report. A PS answering an AP reports nothing, and callers that need the downstream report use ReadRevocationReport.

func ResourceLinkElement ¶ 

func ResourceLinkElement(issuer string) (string, error)

ResourceLinkElement returns an HTML link element for the head of a page, such as the one at a resource's documentation_uri, naming the resource's metadata document.

func ResourceMetadataURL ¶ 

func ResourceMetadataURL(issuer string) (string, error)

ResourceMetadataURL returns the well-known metadata URL of a resource identifier.

func ValidateAgentIdentifier ¶ 

func ValidateAgentIdentifier(identifier string) error

ValidateAgentIdentifier validates the AAuth URI identifier grammar. A local part without + names a top-level Agent; one with + is a parent's local part, one +, and a non-empty discriminator, since + is reserved as the delimiter and delegation is one level deep. Which form an Agent has is decided by parent_agent (ValidateAgentRelationship), never by this shape.

func ValidateAgentIssuer ¶ 

func ValidateAgentIssuer(agent, issuer string) error

ValidateAgentIssuer requires an Agent identifier's domain to match its Agent Provider issuer.

func ValidateAgentRelationship ¶ 

func ValidateAgentRelationship(agent, parent string) error

ValidateAgentRelationship enforces top-level and single-level sub-agent naming alongside the authoritative parent_agent relationship.

func ValidateCurrentAuthTokenContext ¶ 

func ValidateCurrentAuthTokenContext(claims AuthTokenClaims, expected AuthTokenContext) error

ValidateCurrentAuthTokenContext binds verified claims to one request.

func ValidateEndpoint ¶ 

func ValidateEndpoint(endpoint string) error

ValidateEndpoint validates an HTTPS protocol endpoint while allowing paths.

func ValidateHTTPSURL ¶ 

func ValidateHTTPSURL(value string) error

ValidateHTTPSURL checks an optional metadata display URI. The drafts require https and say nothing about query or fragment, so those are accepted.

func ValidateInteractionCallback ¶ 

func ValidateInteractionCallback(callback string, allowLoopback bool) error

ValidateInteractionCallback checks a callback URL before an interaction host redirects to it. A callback is an absolute HTTPS URL with a lowercase host and no userinfo, query or fragment, so that an error can be appended as its only query. With allowLoopback, http://localhost and http://127.0.0.1 with any port are also accepted.

func ValidateMissionS256 ¶ 

func ValidateMissionS256(value string) error

ValidateMissionS256 checks the exact unpadded base64url SHA-256 syntax used by mission references.

func ValidatePersonTokenContext ¶ 

func ValidatePersonTokenContext(claims PersonTokenClaims, resourceIdentifier string, requestKey jose.JWK) error

ValidatePersonTokenContext binds verified claims to one resource request.

func ValidateRevocationRequest ¶ 

func ValidateRevocationRequest(request RevocationRequest) error

ValidateRevocationRequest validates a revocation request.

func ValidateScopeValue ¶ 

func ValidateScopeValue(value string) error

ValidateScopeValue validates one OAuth scope-token value. Scope values are visible ASCII other than quotation mark and backslash.

func ValidateServerIdentifier ¶ 

func ValidateServerIdentifier(identifier string) error

ValidateServerIdentifier enforces the AAuth scheme-and-host identifier form.

func ValidateTokenReference ¶ 

func ValidateTokenReference(reference TokenReference) error

ValidateTokenReference validates a token's issuer and JTI identity; the wire request is RevocationRequest.

Types ¶

type AccessMode ¶ 

type AccessMode string

AccessMode is a credential-flow value from the current AAuth registry. The Resource package provides explicit compositions for all four Core modes. 

const (
	AccessModeAgentToken   AccessMode = "agent-token"
	AccessModePersonToken  AccessMode = "person-token"
	AccessModeSessionToken AccessMode = "session-token"
	AccessModeAuthToken    AccessMode = "auth-token"
)

type AccessServerMetadata ¶ 

type AccessServerMetadata struct {
	Metadata
	AuthTokenEndpoint  string `json:"auth_token_endpoint"`
	RevocationEndpoint string `json:"revocation_endpoint,omitempty"`
}

AccessServerMetadata is /.well-known/aauth-access.json (Core, Access Server Metadata).

func DecodeAccessServerMetadata ¶ 

func DecodeAccessServerMetadata(exact []byte, issuer string) (AccessServerMetadata, error)

DecodeAccessServerMetadata verifies one exact aauth-access.json document fetched from issuer. See DecodePersonServerMetadata for the shared checks.

type AgentProviderMetadata ¶ 

type AgentProviderMetadata struct {
	Metadata
	CallbackEndpoint         string `json:"callback_endpoint,omitempty"`
	EventEndpoint            string `json:"event_endpoint,omitempty"`
	LocalhostCallbackAllowed bool   `json:"localhost_callback_allowed,omitempty"`
}

AgentProviderMetadata is /.well-known/aauth-agent.json (Core, Agent Provider Metadata). EventEndpoint is the Events companion's member.

func DecodeAgentProviderMetadata ¶ 

func DecodeAgentProviderMetadata(exact []byte, issuer string) (AgentProviderMetadata, error)

DecodeAgentProviderMetadata verifies one exact aauth-agent.json document fetched from issuer. See DecodePersonServerMetadata for the shared checks.

type AgentTokenClaims ¶ 

type AgentTokenClaims struct {
	Issuer           string                     `json:"iss"`
	DWK              string                     `json:"dwk"`
	Subject          string                     `json:"sub"`
	JTI              string                     `json:"jti"`
	Confirmation     Confirmation               `json:"cnf"`
	IssuedAt         int64                      `json:"iat"`
	ExpiresAt        int64                      `json:"exp"`
	NotBefore        int64                      `json:"nbf,omitempty"`
	PersonServer     string                     `json:"ps,omitempty"`
	ParentAgent      string                     `json:"parent_agent,omitempty"`
	AdditionalClaims map[string]json.RawMessage `json:"-"`
}

AgentTokenClaims are the Core claims of an aa-agent+jwt.

func VerifyAgentToken ¶ 

func VerifyAgentToken(ctx context.Context, compact string, resolver signaturekey.KeyResolver, clock Clock) (AgentTokenClaims, error)

VerifyAgentToken verifies compact-token trust and claims. The caller must still bind the result to the request key and receiving operation.

func VerifySubagentToken ¶ 

func VerifySubagentToken(
	ctx context.Context,
	compact string,
	parent AgentTokenClaims,
	resolver signaturekey.KeyResolver,
	clock Clock,
) (AgentTokenClaims, error)

VerifySubagentToken verifies a sub-agent's Agent token carried as a request parameter for parent-mediated authorization (Protocol -11, Sub-Agents). Parent must be the freshly verified claims of the top-level Agent that signed this request. Verify the parent's compact token with VerifyAgentToken at the current protocol time before calling this helper; cached claims from an earlier verification are not sufficient. This helper receives only the parent claims and cannot reverify the parent's signature or expiry. The child token is verified on its own terms; then its authoritative parent_agent must name that parent, both tokens must share one issuer, a child ps claim must equal the parent's (Bootstrap copies it), and the child must hold a distinct confirmation key. A grandchild fails because its parent is itself a sub-agent.

A failure wraps ErrExpiredSubagentToken or ErrInvalidSubagentToken. The caller still applies its request-window iat check, any Agent-token revocation state and its policy.

type AgentTokenRequest ¶ 

type AgentTokenRequest struct {
	Agent            string
	PersonServer     string
	ParentAgent      string
	PublicKey        jose.JWK
	NotBefore        time.Time
	Lifetime         time.Duration
	AdditionalClaims map[string]json.RawMessage
}

AgentTokenRequest is the issuer-validated input to agent-token creation.

type ApprovedMission ¶ 

type ApprovedMission struct {
	S256      string
	Encoded   string
	ExactJSON []byte
	Blob      MissionBlob
}

ApprovedMission keeps the parsed mission beside the exact bytes its s256 identifies. Unknown mission-blob members remain intact in ExactJSON.

func DecodeMission ¶ 

func DecodeMission(s256, encoded string) (ApprovedMission, error)

DecodeMission verifies an approval's s256 and decodes its exact mission bytes. Unknown members are ignored semantically and retained byte-for-byte.

func EncodeMission ¶ 

func EncodeMission(blob MissionBlob) (ApprovedMission, error)

EncodeMission validates and deterministically encodes a mission blob.

func (ApprovedMission) ApprovesTool ¶ 

func (mission ApprovedMission) ApprovesTool(name string) bool

ApprovesTool reports whether name exactly matches a tool recorded in the approved mission. The protocol defines no tool-name normalization and does not make this local planning aid an enforceable permission at a Resource.

type AuditDocument ¶ 

type AuditDocument struct {
	ExactJSON []byte
	Entry     AuditEntry
}

AuditDocument keeps a parsed audit entry beside its exact JSON bytes. Unknown additive members remain intact in ExactJSON and are untrusted.

func DecodeAudit ¶ 

func DecodeAudit(exactJSON []byte) (AuditDocument, error)

DecodeAudit preserves exact request bytes and decodes the source-defined members. Unknown additive members remain available in ExactJSON.

func EncodeAudit ¶ 

func EncodeAudit(entry AuditEntry) (AuditDocument, error)

EncodeAudit validates and deterministically encodes an audit entry. The returned document does not alias caller-owned raw JSON.

type AuditEntry ¶ 

type AuditEntry struct {
	MissionS256 string          `json:"mission_s256"`
	Action      string          `json:"action"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters,omitempty"`
	Result      json.RawMessage `json:"result,omitempty"`
}

AuditEntry is the source-defined record of one action already performed within a mission. Parameters and Result are absent or JSON objects. Description is untrusted raw Markdown and must be sanitized before display. Action, Parameters, and Result are also untrusted Agent input; a host must validate them before application-specific processing or rendering.

func (AuditEntry) Validate ¶ 

func (entry AuditEntry) Validate() error

Validate checks the Core Audit Endpoint request shape.

type AuthTokenClaims ¶ 

type AuthTokenClaims struct {
	Issuer           string                     `json:"iss"`
	DWK              string                     `json:"dwk"`
	Audience         string                     `json:"aud"`
	JTI              string                     `json:"jti"`
	PersonServer     string                     `json:"ps"`
	Subject          string                     `json:"sub"`
	Confirmation     Confirmation               `json:"cnf"`
	IssuedAt         int64                      `json:"iat"`
	ExpiresAt        int64                      `json:"exp"`
	NotBefore        int64                      `json:"nbf,omitempty"`
	Scope            string                     `json:"scope,omitempty"`
	Account          *string                    `json:"account,omitempty"`
	MissionS256      string                     `json:"mission_s256,omitempty"`
	Tenant           string                     `json:"tenant,omitempty"`
	AdditionalClaims map[string]json.RawMessage `json:"-"`
}

AuthTokenClaims are the current Core claims of an aa-auth+jwt.

func VerifyAuthToken ¶ 

func VerifyAuthToken(ctx context.Context, compact string, resolver signaturekey.KeyResolver, clock Clock) (AuthTokenClaims, error)

VerifyAuthToken verifies compact-token trust and claims. Call ValidateCurrentAuthTokenContext to bind the result to one request. Known R3 and Budgets claims fail closed until their companion package is integrated with this API.

func VerifyAuthTokenCore ¶ 

func VerifyAuthTokenCore(
	ctx context.Context,
	compact string,
	resolver signaturekey.KeyResolver,
	clock Clock,
) (AuthTokenClaims, error)

VerifyAuthTokenCore verifies only Core trust and claims while returning immutable copies of raw companion claims. A typed companion verifier must consume every recognized authorization claim before policy or use.

type AuthTokenContext ¶ 

type AuthTokenContext struct {
	Issuer            string
	DiscoveryDocument string
	Resource          string
	PersonServer      string
	Subject           string
	RequestKey        jose.JWK
	RequiredScopes    []string
}

AuthTokenContext names the request context that verified auth-token claims must match.

type AuthTokenRequirement ¶ 

type AuthTokenRequirement struct {
	ResourceToken string
}

AuthTokenRequirement is the Core requirement that carries a resource token for obtaining an auth token.

func ParseAuthTokenRequirement ¶ 

func ParseAuthTokenRequirement(values []string) (AuthTokenRequirement, error)

ParseAuthTokenRequirement parses one or more AAuth-Requirement field lines containing the Core auth-token requirement.

type Clock ¶ 

type Clock interface {
	Now() time.Time
}

Clock supplies protocol time without imposing a process-global clock.

type ClockFunc ¶ 

type ClockFunc func() time.Time

ClockFunc adapts a function to Clock.

func (ClockFunc) Now ¶ 

func (clock ClockFunc) Now() time.Time

type Confirmation ¶ 

type Confirmation struct {
	JWK jose.JWK `json:"jwk"`
}

Confirmation is the RFC 7800 confirmation claim used by AAuth.

type DownstreamRevocation ¶ 

type DownstreamRevocation struct {
	Recipient string          `json:"recipient"`
	Error     RevocationError `json:"error,omitempty"`
}

DownstreamRevocation is one entry of the downstream report in a revocation response: an Access Server reports to a Person Server each Resource it revoked at. Error is empty when the revocation there succeeded.

func ReadRevocationReport ¶ 

func ReadRevocationReport(response *http.Response, maxBytes int64) ([]DownstreamRevocation, error)

ReadRevocationReport reads the body of a revocation 200 of at most maxBytes and returns its downstream report. An absent body means the revocation was recorded with nothing reported. A present body MUST be application/json and one JSON object whose optional downstream member is an array of objects; members are matched by exact name and unknown members are ignored. Anything else, including JSON null, is ErrRevocationUnavailable.

type ErrorCode ¶ 

type ErrorCode string

ErrorCode is an AAuth problem-details error member.

type InteractionAnswer ¶ 

type InteractionAnswer struct {
	Answer string `json:"answer"`
}

InteractionAnswer is the Person Server's answer to one question. Answer is untrusted text from the host policy and must be handled as such by the Agent application.

type InteractionAnswerDocument ¶ 

type InteractionAnswerDocument struct {
	ExactJSON []byte
	Answer    InteractionAnswer
}

InteractionAnswerDocument keeps a parsed answer beside its exact JSON bytes. Unknown additive members remain untrusted in ExactJSON.

func DecodeInteractionAnswer ¶ 

func DecodeInteractionAnswer(exactJSON []byte) (InteractionAnswerDocument, error)

DecodeInteractionAnswer preserves exact bytes and decodes one answer.

func EncodeInteractionAnswer ¶ 

func EncodeInteractionAnswer(answer InteractionAnswer) (InteractionAnswerDocument, error)

EncodeInteractionAnswer validates and deterministically encodes one answer.

type InteractionCallbackError ¶ 

type InteractionCallbackError string

InteractionCallbackError is the error query parameter an interaction host adds to a callback URL when the interaction cannot be completed (Core, Interaction Callback Errors). It implements error, so a callback recipient can surface it to its caller unchanged. 

const (
	// InteractionCallbackAccessDenied reports that the person declined.
	InteractionCallbackAccessDenied InteractionCallbackError = "access_denied"
	// InteractionCallbackUserAbandoned reports that the person opened the
	// interaction but did not complete it.
	InteractionCallbackUserAbandoned InteractionCallbackError = "user_abandoned"
	// InteractionCallbackServerError reports an internal failure at the party
	// handling the interaction.
	InteractionCallbackServerError InteractionCallbackError = "server_error"
	// InteractionCallbackTemporarilyUnavailable reports that the interaction
	// service is temporarily unavailable. The caller may retry.
	InteractionCallbackTemporarilyUnavailable InteractionCallbackError = "temporarily_unavailable"
	// InteractionCallbackInteractionExpired reports that the interaction
	// session expired before the person completed it.
	InteractionCallbackInteractionExpired InteractionCallbackError = "interaction_expired"
)

func InteractionCallbackErrorFor ¶ 

func InteractionCallbackErrorFor(code ErrorCode) InteractionCallbackError

InteractionCallbackErrorFor returns the callback error that reports a pending request ended with the polling error code: access_denied for denied, user_abandoned for abandoned, interaction_expired for expired, and server_error for anything else.

func (InteractionCallbackError) Error ¶ 

func (value InteractionCallbackError) Error() string

Error returns the registered error value.

func (InteractionCallbackError) PollingError ¶ 

func (value InteractionCallbackError) PollingError() ErrorCode

PollingError returns the polling error a pending request ends with when its interaction ended with value: denied for access_denied, abandoned for user_abandoned, expired for interaction_expired, and server_error for server_error, temporarily_unavailable and any unregistered value.

func (InteractionCallbackError) Valid ¶ 

func (value InteractionCallbackError) Valid() bool

Valid reports whether value is one of the five registered callback errors.

type InteractionQuestion ¶ 

type InteractionQuestion struct {
	Description string `json:"description,omitempty"`
	Question    string `json:"question"`
	MissionS256 string `json:"mission_s256,omitempty"`
}

InteractionQuestion is one source-defined question for a person. Description and Question are untrusted raw Markdown and must be sanitized before display.

func (InteractionQuestion) Validate ¶ 

func (question InteractionQuestion) Validate() error

Validate checks the source-defined question members.

type InteractionQuestionDocument ¶ 

type InteractionQuestionDocument struct {
	ExactJSON []byte
	Question  InteractionQuestion
}

InteractionQuestionDocument keeps the parsed question beside the exact JSON bytes authenticated by the Agent. Unknown additive members remain untrusted in ExactJSON.

func DecodeInteractionQuestion ¶ 

func DecodeInteractionQuestion(exactJSON []byte) (InteractionQuestionDocument, error)

DecodeInteractionQuestion preserves exact bytes and decodes one question. Relay-only url, code, and max_wait members are rejected by this focused API.

func EncodeInteractionQuestion ¶ 

func EncodeInteractionQuestion(question InteractionQuestion) (InteractionQuestionDocument, error)

EncodeInteractionQuestion validates and deterministically encodes a question.

type InteractionRelay ¶ 

type InteractionRelay struct {
	Type        InteractionRelayType
	Description string
	URL         string
	Code        string
	MaxWait     time.Duration
	MissionS256 string
}

InteractionRelay is the Resource's instruction for an interaction that the Person Server may present. Description is untrusted raw Markdown and must be sanitized before display.

func (InteractionRelay) Validate ¶ 

func (relay InteractionRelay) Validate() error

Validate checks the source-defined interaction relay members.

type InteractionRelayCompletion ¶ 

type InteractionRelayCompletion struct {
	Status InteractionRelayStatus `json:"status"`
}

InteractionRelayCompletion is the terminal body used by this implementation profile after the Person Server stops waiting. Completion of the underlying operation is signalled at the Resource's own pending URL.

func (InteractionRelayCompletion) Validate ¶ 

func (completion InteractionRelayCompletion) Validate() error

Validate checks the source-defined relay status.

type InteractionRelayCompletionDocument ¶ 

type InteractionRelayCompletionDocument struct {
	ExactJSON  []byte
	Completion InteractionRelayCompletion
}

InteractionRelayCompletionDocument preserves the exact terminal response.

func DecodeInteractionRelayCompletion ¶ 

func DecodeInteractionRelayCompletion(exactJSON []byte) (InteractionRelayCompletionDocument, error)

DecodeInteractionRelayCompletion preserves exact bytes and decodes a terminal relay state.

func EncodeInteractionRelayCompletion ¶ 

func EncodeInteractionRelayCompletion(completion InteractionRelayCompletion) (InteractionRelayCompletionDocument, error)

EncodeInteractionRelayCompletion validates and deterministically encodes a terminal relay state.

type InteractionRelayDocument ¶ 

type InteractionRelayDocument struct {
	ExactJSON []byte
	Relay     InteractionRelay
}

InteractionRelayDocument keeps the parsed relay beside the exact JSON bytes authenticated by the Agent. Unknown additive members remain untrusted in ExactJSON.

func DecodeInteractionRelay ¶ 

func DecodeInteractionRelay(exactJSON []byte) (InteractionRelayDocument, error)

DecodeInteractionRelay preserves exact bytes and decodes one interaction or payment relay. Question-only members are rejected by this focused API.

func EncodeInteractionRelay ¶ 

func EncodeInteractionRelay(relay InteractionRelay) (InteractionRelayDocument, error)

EncodeInteractionRelay validates and deterministically encodes a relay.

type InteractionRelayStatus ¶ 

type InteractionRelayStatus string

InteractionRelayStatus is the Person Server's reported relay state. 

const (
	InteractionRelayPending     InteractionRelayStatus = "pending"
	InteractionRelayInteracting InteractionRelayStatus = "interacting"
)

type InteractionRelayType ¶ 

type InteractionRelayType string

InteractionRelayType identifies an interaction that the Person Server can relay to the person. Core defines interaction and payment relays separately from question interactions. 

const (
	InteractionRelayInteraction InteractionRelayType = "interaction"
	InteractionRelayPayment     InteractionRelayType = "payment"
)

type InteractionRequirement ¶ 

type InteractionRequirement struct {
	URL  string
	Code string
}

InteractionRequirement tells an agent where a person can complete an interaction and which human-readable code correlates that interaction with the pending request. The code is not an authorization credential.

func ParseInteractionRequirement ¶ 

func ParseInteractionRequirement(values []string) (InteractionRequirement, error)

ParseInteractionRequirement parses one or more AAuth-Requirement field lines containing the Core interaction requirement.

type InteractionVisit ¶ 

type InteractionVisit struct {
	Code     string
	Callback string
}

InteractionVisit is what an interaction URL receives in its query: the interaction code and, when the party that sent the person has a browser flow of its own, the callback URL to return the person to.

func ParseInteractionVisit ¶ 

func ParseInteractionVisit(rawQuery string, options InteractionVisitOptions) (InteractionVisit, error)

ParseInteractionVisit reads the code and optional callback from the raw query of a request to an interaction URL, as sent by an Agent or by a Person Server: {url}?code={code}&callback={callback}. It does not judge the code: pass it to the role that issued it, which counts a malformed code as a failed attempt. A missing or repeated code, a repeated callback, or a callback that is not an HTTPS URL without query or fragment is refused. Other query members are ignored.

type InteractionVisitOptions ¶ 

type InteractionVisitOptions struct {
	// AllowLoopbackCallback accepts an http://localhost or http://127.0.0.1
	// callback. An Agent may send one only when its Agent Provider metadata
	// sets localhost_callback_allowed, so leave this false unless the host
	// has checked that metadata for the requesting Agent.
	AllowLoopbackCallback bool
}

InteractionVisitOptions selects what ParseInteractionVisit accepts.

type Metadata ¶ 

type Metadata struct {
	Issuer              string   `json:"issuer"`
	JWKSURI             string   `json:"jwks_uri,omitempty"`
	AcceptSignatureAlgs []string `json:"accept_signature_algs,omitempty"`
	Name                string   `json:"name,omitempty"`
	Description         string   `json:"description,omitempty"`
	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"`
}

Metadata holds the members every AAuth metadata document defines the same way (Core, Metadata Documents). Name and Description are untrusted display text; Description is Markdown and must be sanitized before rendering. AcceptSignatureAlgs, when present, is exactly the set of JWS algorithms the server's verifier accepts at every endpoint.

type MissionApproval ¶ 

type MissionApproval struct {
	S256         string            `json:"s256"`
	Mission      string            `json:"mission"`
	Capabilities []string          `json:"capabilities,omitempty"`
	PersonTokens map[string]string `json:"person_tokens,omitempty"`
}

MissionApproval is the successful mission-endpoint response. Mission is the unpadded base64url encoding of the exact approved mission JSON.

type MissionBlob ¶ 

type MissionBlob struct {
	Agent             string        `json:"agent"`
	ApprovedAt        time.Time     `json:"approved_at"`
	ExpiresAt         *time.Time    `json:"expires_at,omitempty"`
	Description       string        `json:"description"`
	ApprovedTools     []MissionTool `json:"approved_tools,omitempty"`
	ApprovedResources []string      `json:"approved_resources,omitempty"`
}

MissionBlob is the Person Server-approved mission content. Its encoded JSON bytes, rather than a re-encoding of this value, are the object identified by s256. The blob carries no approver member: the approver is always the Person Server that returns or serves the mission, named beside s256 by the iss of a person token, the ps claim of a resource or auth token, or the Person Server a request is made to.

type MissionCompletion ¶ 

type MissionCompletion struct {
	Action  string `json:"action"`
	Summary string `json:"summary"`
}

MissionCompletion is the Agent-authored proposal that a mission is finished.

type MissionCompletionDocument ¶ 

type MissionCompletionDocument struct {
	ExactJSON  []byte
	Completion MissionCompletion
}

MissionCompletionDocument keeps a parsed completion proposal beside its exact JSON bytes. Unknown additive members remain intact in ExactJSON. Core does not define a digest identifier for a completion proposal.

func DecodeMissionCompletion ¶ 

func DecodeMissionCompletion(exactJSON []byte) (MissionCompletionDocument, error)

DecodeMissionCompletion preserves a completion proposal's exact bytes and decodes its protocol-defined members.

func EncodeMissionCompletion ¶ 

func EncodeMissionCompletion(completion MissionCompletion) (MissionCompletionDocument, error)

EncodeMissionCompletion validates and deterministically encodes a completion proposal.

type MissionProposal ¶ 

type MissionProposal struct {
	Description string        `json:"description"`
	Tools       []MissionTool `json:"tools,omitempty"`
	Resources   []string      `json:"resources,omitempty"`
}

MissionProposal is the Agent-authored request body sent to a Person Server's mission endpoint. Description and tool descriptions are untrusted Markdown and must be sanitized before rendering.

func (MissionProposal) Validate ¶ 

func (proposal MissionProposal) Validate() error

Validate checks the protocol-defined shape of a mission proposal.

type MissionRead ¶ 

type MissionRead struct {
	Mission ApprovedMission
	Updates []MissionUpdateDocument
}

MissionRead is a verified mission read: the approved mission and its accepted updates, each checked against the s256 that names it.

func DecodeMissionRead ¶ 

func DecodeMissionRead(exactJSON []byte, s256 string) (MissionRead, error)

DecodeMissionRead verifies one exact mission-read response for the mission named s256: the response names that mission, its mission bytes hash to it, and each update's bytes hash to the update's own s256. Unknown members are ignored.

type MissionReadResponse ¶ 

type MissionReadResponse struct {
	S256    string              `json:"s256"`
	Mission string              `json:"mission"`
	Updates []MissionReadUpdate `json:"updates"`
}

MissionReadResponse is a Person Server's answer to the owning Agent's signed GET of its mission's own URL, {mission_endpoint}/{mission_s256}. Mission carries the same bytes the approval returned (Core, Mission Identifier), and Updates the accepted updates in the order they were accepted, since a party auditing a mission reads both (Core, Mission Update).

func NewMissionReadResponse ¶ 

func NewMissionReadResponse(mission ApprovedMission, updates []MissionUpdateDocument) MissionReadResponse

NewMissionReadResponse builds the answer to a mission read from the approved mission and its accepted updates, in acceptance order.

type MissionReadUpdate ¶ 

type MissionReadUpdate struct {
	S256    string `json:"s256"`
	Encoded string `json:"encoded"`
}

MissionReadUpdate is one accepted update as a mission read serves it: the update's s256 and the unpadded base64url of the exact bytes it names.

type MissionTool ¶ 

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

MissionTool is one tool named in a mission proposal or approved mission. Description is untrusted Markdown and must be sanitized before rendering. The protocol records this declaration; it does not make the declaration an enforceable permission at a remote Resource.

type MissionUpdate ¶ 

type MissionUpdate struct {
	Action      string `json:"action"`
	Description string `json:"description"`
}

MissionUpdate is the Agent-authored body that records changed work without changing the approved mission blob or its identifier.

type MissionUpdateDocument ¶ 

type MissionUpdateDocument struct {
	S256      string
	ExactJSON []byte
	Update    MissionUpdate
}

MissionUpdateDocument keeps a parsed update beside the exact JSON bytes its S256 identifies. Unknown additive members remain intact in ExactJSON.

func DecodeMissionUpdate ¶ 

func DecodeMissionUpdate(s256 string, exactJSON []byte) (MissionUpdateDocument, error)

DecodeMissionUpdate verifies an update's identifier, preserves its exact bytes, and decodes its protocol-defined members.

func EncodeMissionUpdate ¶ 

func EncodeMissionUpdate(update MissionUpdate) (MissionUpdateDocument, error)

EncodeMissionUpdate validates and deterministically encodes an update.

type MissionUpdateResponse ¶ 

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

MissionUpdateResponse is the successful mission-update response.

type Permission ¶ 

type Permission string

Permission is a decision returned by an AAuth permission endpoint. 

const (
	PermissionGranted Permission = "granted"
	PermissionDenied  Permission = "denied"
)

func ParsePermission ¶ 

func ParsePermission(value string) (Permission, error)

ParsePermission validates a permission decision.

type PersonServerMetadata ¶ 

type PersonServerMetadata struct {
	Metadata
	AuthTokenEndpoint      string   `json:"auth_token_endpoint"`
	PersonTokenEndpoint    string   `json:"person_token_endpoint"`
	MissionEndpoint        string   `json:"mission_endpoint,omitempty"`
	PermissionEndpoint     string   `json:"permission_endpoint,omitempty"`
	AuditEndpoint          string   `json:"audit_endpoint,omitempty"`
	InteractionEndpoint    string   `json:"interaction_endpoint,omitempty"`
	MissionControlEndpoint string   `json:"mission_control_endpoint,omitempty"`
	RevocationEndpoint     string   `json:"revocation_endpoint,omitempty"`
	ScopesSupported        []string `json:"scopes_supported,omitempty"`
	ClaimsSupported        []string `json:"claims_supported,omitempty"`
}

PersonServerMetadata is /.well-known/aauth-person.json (Core, Person Server Metadata). AuthTokenEndpoint and PersonTokenEndpoint are required; an empty optional endpoint means the Person Server does not offer it.

func DecodePersonServerMetadata ¶ 

func DecodePersonServerMetadata(exact []byte, issuer string) (PersonServerMetadata, error)

DecodePersonServerMetadata verifies one exact aauth-person.json document fetched from issuer: one unambiguous JSON object, an issuer member equal to issuer byte for byte (a missing one is signaturekey error issuer_missing and a different one issuer_mismatch, as Core, Metadata Documents requires), the required members present, https for jwks_uri and the display URIs, and https without query or fragment for the token and mission endpoints (Core, Endpoint and Other URLs). Unknown members are ignored.

type PersonTokenClaims ¶ 

type PersonTokenClaims struct {
	Issuer       string       `json:"iss"`
	DWK          string       `json:"dwk"`
	Audience     string       `json:"aud"`
	Subject      string       `json:"sub"`
	Confirmation Confirmation `json:"cnf"`
	JTI          string       `json:"jti"`
	IssuedAt     int64        `json:"iat"`
	ExpiresAt    int64        `json:"exp"`
	NotBefore    int64        `json:"nbf,omitempty"`
	MissionS256  string       `json:"mission_s256,omitempty"`
	Tenant       string       `json:"tenant,omitempty"`
}

PersonTokenClaims identify one person to one resource and bind that identity to the agent's current request key. A person token carries no authorization.

func VerifyPersonToken ¶ 

func VerifyPersonToken(ctx context.Context, compact string, resolver signaturekey.KeyResolver, clock Clock) (PersonTokenClaims, error)

VerifyPersonToken verifies compact-token trust and claims. Call ValidatePersonTokenContext to bind the result to one resource and request key.

type PresentedToken ¶ 

type PresentedToken struct {
	Type         string
	Issuer       string
	JTI          string
	PersonServer string
	Subject      string
	MissionS256  string
	Tenant       string
	ExpiresAt    time.Time
	Person       *PersonTokenClaims
	Auth         *AuthTokenClaims
}

PresentedToken is a verified presented_token of either type. Exactly one of Person and Auth is set.

func VerifyPresentedToken ¶ 

func VerifyPresentedToken(
	ctx context.Context,
	compact string,
	resource ResourceTokenClaims,
	resolver signaturekey.KeyResolver,
	clock Clock,
) (PresentedToken, error)

VerifyPresentedToken verifies the presented_token of a token request against the already verified resource token that names it. An auth token is verified at the Core layer only: it returns raw companion claims and does not establish Budgets or R3 authority. The caller still checks that the named Person Server is the expected one, and revocation.

type ProblemError ¶ 

type ProblemError struct {
	Type              string
	Title             string
	Status            int
	Code              ErrorCode
	Detail            string
	Instance          string
	MissionStatus     string
	TerminationReason string
	Reason            string
}

ProblemError is an AAuth RFC 9457 error response. Code is the required AAuth "error" extension member. Reason is the Markdown reason a supervisor or the person gave for refusing a mission request, untrusted for display.

func DecodeProblemResponse ¶ 

func DecodeProblemResponse(response *http.Response) (*ProblemError, error)

DecodeProblemResponse validates and consumes an AAuth problem-details body.

func (*ProblemError) Error ¶ 

func (problem *ProblemError) Error() string

type RateLimitedError ¶ 

type RateLimitedError struct {
	Problem    *ProblemError
	RetryAfter time.Duration
}

RateLimitedError is a recipient's definite 429 rate_limited refusal of a revocation request together with its required Retry-After feedback. It is returned only when the recipient supplied exactly one valid Retry-After; otherwise the plain *ProblemError is returned and no delay is implied. RetryAfter is the delay as supplied (zero when an HTTP-date is not in the future). The caller decides whether and when to repeat the request.

func (*RateLimitedError) Error ¶ 

func (failure *RateLimitedError) Error() string

func (*RateLimitedError) Unwrap ¶ 

func (failure *RateLimitedError) Unwrap() error

Unwrap returns the underlying problem so errors.As finds *ProblemError.

type Requirement ¶ 

type Requirement string

Requirement is an extension-friendly AAuth requirement token. 

const (
	RequirementInteraction   Requirement = "interaction"
	RequirementApproval      Requirement = "approval"
	RequirementClarification Requirement = "clarification"
	RequirementClaims        Requirement = "claims"
	RequirementAgentToken    Requirement = "agent-token"
	RequirementPersonToken   Requirement = "person-token"
	RequirementAuthToken     Requirement = "auth-token"
)

func ParseRequirement ¶ 

func ParseRequirement(values []string) (Requirement, error)

ParseRequirement returns the generic requirement token while leaving requirement-specific parameters to the corresponding focused parser.

type ResourceInteraction ¶ 

type ResourceInteraction struct {
	URL  string `json:"url"`
	Code string `json:"code"`
}

ResourceInteraction describes a resource-owned user interaction carried by a resource token. 

type ResourceLink struct {
	// Target is the absolute metadata URL, exactly as the link carried it.
	Target string
	// Issuer is Target without the well-known suffix. A metadata document
	// fetched from Target is accepted only when its issuer equals Issuer.
	Issuer string
}

ResourceLink is one admissible aauth-resource link: a server identifier followed by /.well-known/aauth-resource.json. It is a statement by whoever controls the response or page that carried it, not by the resource it names, and it plays no part in key discovery or in what a response requires.

func ParseResourceLinkTarget ¶ 

func ParseResourceLinkTarget(target string) (ResourceLink, error)

ParseResourceLinkTarget accepts exactly a server identifier followed by /.well-known/aauth-resource.json. A relative target, a path before the suffix, a query, a fragment, a port, userinfo, or any other form is refused, and an Agent must not fetch it.

func ResourceLinksFromHTML ¶ 

func ResourceLinksFromHTML(document []byte) []ResourceLink

ResourceLinksFromHTML returns the admissible aauth-resource targets of the link elements in one HTML document, in order and without duplicates. The document is untrusted input: it is scanned, never rendered or executed, and a document larger than 1 MiB is not scanned. Every link element is read, not only those in head, and an href is used as written, without resolving it against the page URL, so only an absolute target can be admissible.

func ResourceLinksFromHeader ¶ 

func ResourceLinksFromHeader(values []string) []ResourceLink

ResourceLinksFromHeader returns the admissible aauth-resource targets of the Link field lines of one response, in order and without duplicates. Links with another relation and targets of any other form are omitted. Field values longer than 8 KiB in total are not scanned. The links say nothing about the response that carries them; a requirement is read only from AAuth-Requirement.

type ResourceMetadata ¶ 

type ResourceMetadata struct {
	Metadata
	AccessMode                    string            `json:"access_mode,omitempty"`
	AuthorizationEndpoint         string            `json:"authorization_endpoint,omitempty"`
	ScopeDescriptions             map[string]string `json:"scope_descriptions,omitempty"`
	SignatureWindow               *int64            `json:"signature_window,omitempty"`
	AdditionalSignatureComponents []string          `json:"additional_signature_components,omitempty"`
	RevocationEndpoint            string            `json:"revocation_endpoint,omitempty"`
	R3Vocabularies                map[string]string `json:"r3_vocabularies,omitempty"`
	BudgetUnits                   json.RawMessage   `json:"budget_units,omitempty"`
	UsageEndpoint                 string            `json:"usage_endpoint,omitempty"`
}

ResourceMetadata is /.well-known/aauth-resource.json (Core, Resource Metadata). JWKSURI is optional here: a Resource that only verifies Agent signatures has no keys to publish. AccessMode is advisory, and an empty one means agent-token. SignatureWindow is nil when the Resource uses the default of 60 seconds. R3Vocabularies is the R3 companion's member, and BudgetUnits and UsageEndpoint are the Budgets companion's; BudgetUnits is kept as its exact JSON, which the budgets package parses.

func DecodeResourceMetadata ¶ 

func DecodeResourceMetadata(exact []byte, issuer string) (ResourceMetadata, error)

DecodeResourceMetadata verifies one exact aauth-resource.json document fetched from issuer. See DecodePersonServerMetadata for the shared checks; authorization_endpoint and usage_endpoint are endpoint URLs, and signature_window must be positive.

type ResourceTokenClaims ¶ 

type ResourceTokenClaims struct {
	Issuer           string                     `json:"iss"`
	DWK              string                     `json:"dwk"`
	Audience         string                     `json:"aud"`
	JTI              string                     `json:"jti"`
	PersonServer     string                     `json:"ps"`
	Subject          string                     `json:"sub"`
	PresentedJTI     string                     `json:"presented_jti"`
	AgentJKT         string                     `json:"agent_jkt"`
	IssuedAt         int64                      `json:"iat"`
	ExpiresAt        int64                      `json:"exp"`
	NotBefore        int64                      `json:"nbf,omitempty"`
	Scope            string                     `json:"scope,omitempty"`
	Account          *string                    `json:"account,omitempty"`
	LoginHint        string                     `json:"login_hint,omitempty"`
	MissionS256      string                     `json:"mission_s256,omitempty"`
	Tenant           string                     `json:"tenant,omitempty"`
	Interaction      *ResourceInteraction       `json:"interaction,omitempty"`
	AdditionalClaims map[string]json.RawMessage `json:"-"`
}

ResourceTokenClaims are the current Core claims of an aa-resource+jwt.

func VerifyResourceToken ¶ 

func VerifyResourceToken(ctx context.Context, compact string, resolver signaturekey.KeyResolver, clock Clock) (ResourceTokenClaims, error)

VerifyResourceToken verifies compact-token trust and claims. The caller must still bind the result to the agent, recipient, and retained person context. Known R3 and Budgets claims fail closed until their companion package is integrated with this API.

func VerifyResourceTokenCore ¶ 

func VerifyResourceTokenCore(
	ctx context.Context,
	compact string,
	resolver signaturekey.KeyResolver,
	clock Clock,
) (ResourceTokenClaims, error)

VerifyResourceTokenCore verifies only Core trust and claims while returning immutable copies of raw companion claims. A typed companion verifier must consume every recognized authorization claim before policy or use.

type RevocationAttempt ¶ 

type RevocationAttempt struct {
	Recipient string
	Error     RevocationError
	Pending   bool
	// RetryAfter is the delay before a pending attempt can progress: the one
	// the recipient asked for, or the default polling interval.
	RetryAfter time.Duration
	// Downstream is the recipient's own report of the revocations it made.
	Downstream []DownstreamRevocation
	// Cause is a local diagnostic for an attempt that did not record. It is
	// never sent on the wire.
	Cause error
}

RevocationAttempt reports how one revocation a server sent to one recipient ended. Exactly one of three outcomes holds: Error is empty and Pending is false when the recipient recorded the revocation; Pending is true when the recipient answered 202 or 429 rate_limited, or had not answered when the sender stopped waiting, so the revocation there is not yet terminal; otherwise Error names why it did not record. Revoking again after RetryAfter continues a pending attempt and re-attempts a failed one.

func (RevocationAttempt) Recorded ¶ 

func (attempt RevocationAttempt) Recorded() bool

Recorded reports whether the recipient recorded the revocation.

type RevocationError ¶ 

type RevocationError string

RevocationError names how a revocation sent to one recipient ended when the recipient did not record it. It is the error member of a downstream entry in a revocation response. 

const (
	// RevocationUnsupported means the recipient publishes no
	// revocation_endpoint or answered unsupported_iss. It honors the token
	// until its exp.
	RevocationUnsupported RevocationError = "revocation_unsupported"
	// RevocationUnavailable means the recipient did not respond, timed out, or
	// answered with a 5xx or a malformed response. The caller may revoke again
	// later.
	RevocationUnavailable RevocationError = "revocation_unavailable"
)

type RevocationLimits ¶ 

type RevocationLimits struct {
	// Requests is how many revocation requests one caller may send in each
	// Window. Polls of a pending revocation are not counted. Zero selects 600.
	Requests int
	// Window is the length of the rate window. Zero selects one minute.
	Window time.Duration
	// MaxLifetime bounds how far past the current time a revocation's exp may
	// lie. It is the longest lifetime the recipient accepts for any token; a
	// later exp is invalid_request. Zero selects 24 hours.
	MaxLifetime time.Duration
}

RevocationLimits bounds what a revocation endpoint accepts from one verified caller. A recipient that accepts revocations from any verified issuer answers rate_limited beyond either bound.

type RevocationRequest ¶ 

type RevocationRequest struct {
	Reference TokenReference
	// ExpiresAt is the token's exp claim. A recipient may discard its
	// revocation state once the token can no longer be valid.
	ExpiresAt time.Time
}

RevocationRequest is one token-revocation request: the token's identity and its expiration. The wire body carries only jti and exp; the issuer is the verified signer of the request, never a body member.

func DecodeRevocationRequest ¶ 

func DecodeRevocationRequest(body io.Reader, maxBytes int64, issuer string) (RevocationRequest, error)

DecodeRevocationRequest reads a revocation request body of at most maxBytes. The issuer is the verified signer of the request; a body member named iss is ignored like any other extension member.

type SystemClock ¶ 

type SystemClock struct{}

SystemClock uses the current system time.

func (SystemClock) Now ¶ 

func (SystemClock) Now() time.Time

type TokenReference ¶ 

type TokenReference struct {
	Issuer string `json:"iss"`
	JTI    string `json:"jti"`
}

TokenReference identifies one token in its issuer's JTI namespace.

type TokenValidationCode ¶ 

type TokenValidationCode string

TokenValidationCode identifies a stable compact-token failure class. 

const (
	TokenValidationExpired              TokenValidationCode = "expired"
	TokenValidationInvalidKey           TokenValidationCode = "invalid_key"
	TokenValidationUnsupportedAlgorithm TokenValidationCode = "unsupported_algorithm"
	TokenValidationNotYetValid          TokenValidationCode = "not_yet_valid"
)

type TokenValidationError ¶ 

type TokenValidationError struct {
	Code  TokenValidationCode
	Cause error
}

TokenValidationError preserves a validation cause for protocol adapters.

func (*TokenValidationError) Error ¶ 

func (failure *TokenValidationError) Error() string

func (*TokenValidationError) SignatureKeyError ¶ 

func (failure *TokenValidationError) SignatureKeyError() *signaturekey.Error

SignatureKeyError maps token validation to the Signature-Key error registry.

func (*TokenValidationError) Unwrap ¶ 

func (failure *TokenValidationError) Unwrap() error

type UnsupportedTokenClaimError ¶ 

type UnsupportedTokenClaimError struct {
	TokenType string
	Claim     string
	Reason    string
}

UnsupportedTokenClaimError identifies a token member that this API cannot safely interpret. A companion-aware API may accept the same token only after validating that companion's complete claim set.

func (*UnsupportedTokenClaimError) Error ¶ 

func (failure *UnsupportedTokenClaimError) Error() string

Source Files ¶

View all Source files

Directories ¶

Path Synopsis
Package accessserver implements four-party AAuth Core authorization and immediate R3 class and per-call authorization.
 Package accessserver implements four-party AAuth Core authorization and immediate R3 class and per-call authorization.
storetest
Package storetest supplies executable contracts for accessserver stores.
 Package storetest supplies executable contracts for accessserver stores.
Package agent implements Agent-side AAuth protocol calls.
 Package agent implements Agent-side AAuth protocol calls.
Package agentprovider issues current AAuth Agent tokens, publishes Agent Provider discovery, and composes explicit two-key and single-durable-key hosted profiles, the source-defined self-hosted composition, and the public Events inbox through host policy and storage interfaces.
 Package agentprovider issues current AAuth Agent tokens, publishes Agent Provider discovery, and composes explicit two-key and single-durable-key hosted profiles, the source-defined self-hosted composition, and the public Events inbox through host policy and storage interfaces.
storetest
Package storetest provides reusable contracts for Agent Provider stores.
 Package storetest provides reusable contracts for Agent Provider stores.
Package budgets implements the AAuth Budgets protocol companion.
 Package budgets implements the AAuth Budgets protocol companion.
Package diagnostics exposes local causes of AAuth role HTTP problems without placing private diagnostics in protocol responses.
 Package diagnostics exposes local causes of AAuth role HTTP problems without placing private diagnostics in protocol responses.
internal/genwriter command
genwriter emits the combinations needed to preserve standard optional http.ResponseWriter interfaces without claiming unsupported capabilities.
 genwriter emits the combinations needed to preserve standard optional http.ResponseWriter interfaces without claiming unsupported capabilities.
Package events implements the reusable values and validation rules from the AAuth Events companion specification.
 Package events implements the reusable values and validation rules from the AAuth Events companion specification.
example
agentidentity command
The agentidentity example runs direct Agent identity access with no Person Server, Access Server, person token, resource token, or auth token.
 The agentidentity example runs direct Agent identity access with no Person Server, Access Server, person token, resource token, or auth token.
audit command
The audit example runs one mission-bound local action and records it at the Person Server.
 The audit example runs one mission-bound local action and records it at the Person Server.
bootstrap command
The bootstrap example runs the repository's two-key and single-durable-key hosted Agent profiles.
 The bootstrap example runs the repository's two-key and single-durable-key hosted Agent profiles.
budget command
The budget example first acquires a fixed Budget reactively from an ordinary Person-token call, then runs two declared MCP operations through a proactive direct R3 Budget grant.
 The budget example first acquires a fixed Budget reactively from an ordinary Person-token call, then runs two declared MCP operations through a proactive direct R3 Budget grant.
budgetfourparty command
The budgetfourparty example shows one proactive fixed-price Budget crossing a Resource, Person Server, Access Server, Agent, and protected Resource call.
 The budgetfourparty example shows one proactive fixed-price Budget crossing a Resource, Person Server, Access Server, Agent, and protected Resource call.
callchaining command
The callchaining example runs one immediate two-resource call chain entirely in process.
 The callchaining example runs one immediate two-resource call chain entirely in process.
events command
The events example runs the public AAuth Events path: the Agent Provider issues a subscribe token, the Agent registers it with a Resource, and the Resource delivers one event back through the Agent Provider.
 The events example runs the public AAuth Events path: the Agent Provider issues a subscribe token, the Agent registers it with a Resource, and the Resource delivers one event back through the Agent Provider.
federatedpayment command
The federatedpayment example drives AS payment, approval and token delivery through in-process HTTP.
 The federatedpayment example drives AS payment, approval and token delivery through in-process HTTP.
fourparty command
The fourparty example runs immediate missionless Core, mission-bound Core, and direct MCP R3 flows entirely in process.
 The fourparty example runs immediate missionless Core, mission-bound Core, and direct MCP R3 flows entirely in process.
gettingstarted command
An Agent calls an API over TLS on this machine.
 An Agent calls an API over TLS on this machine.
hostedservice command
The hosted-service example composes the launch-profile paths on one set of AAuth roles.
 The hosted-service example composes the launch-profile paths on one set of AAuth roles.
interactionquestion command
The interaction-question example sends missionless and mission-bound questions from an Agent to its Person Server and returns retained answers.
 The interaction-question example sends missionless and mission-bound questions from an Agent to its Person Server and returns retained answers.
interactionrelay command
The interaction-relay example forwards missionless and mission-bound Resource-hosted interactions to a Person Server and observes engagement.
 The interaction-relay example forwards missionless and mission-bound Resource-hosted interactions to a Person Server and observes engagement.
mission command
The mission example runs one deferred mission-bound three-party journey in process.
 The mission example runs one deferred mission-bound three-party journey in process.
permission command
The permission example runs missionless and mission-bound local-action decisions entirely in process.
 The permission example runs missionless and mission-bound local-action decisions entirely in process.
psconsent command
The psconsent example runs deferred three-party Person Server consent entirely in process.
 The psconsent example runs deferred three-party Person Server consent entirely in process.
r3threeparty command
The r3threeparty example runs direct MCP class authorization through an Agent Provider, Agent, Person Server, and Resource.
 The r3threeparty example runs direct MCP class authorization through an Agent Provider, Agent, Person Server, and Resource.
resourcesession command
The resourcesession example runs the direct Resource-managed interaction path.
 The resourcesession example runs the direct Resource-managed interaction path.
revocation command
The revocation example runs issuer-driven Agent- and Auth-token revocation, caller-controlled retry, and explicit Person-token recovery in process.
 The revocation example runs issuer-driven Agent- and Auth-token revocation, caller-controlled retry, and explicit Person-token recovery in process.
selfhosted command
The self-hosted example publishes ordinary Agent Provider metadata and JWKS, self-issues a short-lived Agent token, obtains one local-action permission from the token's Person Server, and uses the same key for one signed Resource call.
 The self-hosted example publishes ordinary Agent Provider metadata and JWKS, self-issues a short-lived Agent token, obtains one local-action permission from the token's Person Server, and uses the same key for one signed Resource call.
subagent command
The subagent example runs one-level parent-mediated authorization in process: the parent asks its hosted Agent Provider for a sub-agent token with its own signed request, the parent obtains every credential from the Person Server, and only the sub-agent calls the Resource.
 The subagent example runs one-level parent-mediated authorization in process: the parent asks its hosted Agent Provider for a sub-agent token with its own signed request, the parent obtains every credential from the Person Server, and only the sub-agent calls the Resource.
supervision command
The supervision example runs one person's Agents under two supervision servers entirely in process.
 The supervision example runs one person's Agents under two supervision servers entirely in process.
threeparty command
The threeparty example runs immediate Person Server authorization entirely in process.
 The threeparty example runs immediate Person Server authorization entirely in process.
verifyagent command
The verifyagent example checks an Agent token, then verifies a signed request at a Resource.
 The verifyagent example checks an Agent token, then verifies a signed request at a Resource.
internal
docscheck
Package docscheck holds the test that keeps README.md and docs/ honest: each quoted Go sample still appears in the compiled file it names, and each relative link and heading anchor resolves.
 Package docscheck holds the test that keeps README.md and docs/ honest: each quoted Go sample still appears in the compiled file it names, and each relative link and heading anchor resolves.
exampleutil
Package exampleutil contains small in-memory role stores shared by runnable examples.
 Package exampleutil contains small in-memory role stores shared by runnable examples.
httpapi
Package httpapi contains the small HTTP/JSON conventions shared by the AAuth role packages.
 Package httpapi contains the small HTTP/JSON conventions shared by the AAuth role packages.
interaction
jsonstrict
Package jsonstrict rejects JSON object-member ambiguity before a value is decoded into Go structs, whose field matching is case-insensitive.
 Package jsonstrict rejects JSON object-member ambiguity before a value is decoded into Go structs, whose field matching is case-insensitive.
r3dispatch
Package r3dispatch selects the strict R3 verifier for tokens that name any recognized R3 claim.
 Package r3dispatch selects the strict R3 verifier for tokens that name any recognized R3 claim.
r3fetch
Package r3fetch performs one bounded, role-authenticated R3 artifact fetch.
 Package r3fetch performs one bounded, role-authenticated R3 artifact fetch.
revocation
Package revocation holds the token-revocation mechanics shared by the Person Server, Access Server and Resource roles: verifying a revocation caller, bounding what one caller may send, sending a signed revocation and polling its pending URL, and tracking a cascade until each downstream revocation has a terminal outcome.
 Package revocation holds the token-revocation mechanics shared by the Person Server, Access Server and Resource roles: verifying a revocation caller, bounding what one caller may send, sending a signed revocation and polling its pending URL, and tracking a cascade until each downstream revocation has a terminal outcome.
specmodel
Package specmodel exposes the checked-in map from pinned editor-source headings to implementation ownership and proof seams.
 Package specmodel exposes the checked-in map from pinned editor-source headings to implementation ownership and proof seams.
specmodel/cmd/generate command
Command generate refreshes requirement occurrences after the heading map and exact editor sources have been reviewed.
 Command generate refreshes requirement occurrences after the heading map and exact editor sources have been reviewed.
specmodel/cmd/verify command
Command verify checks the protocol model against an exact editor-source directory.
 Command verify checks the protocol model against an exact editor-source directory.
upstreamtoken
Package upstreamtoken verifies the auth token a calling Agent presented to an intermediary, when the intermediary passes it on as upstream_token.
 Package upstreamtoken verifies the auth token a calling Agent presented to an intermediary, when the intermediary passes it on as upstream_token.
Package jose implements the bounded JOSE profile used by AAuth.
 Package jose implements the bounded JOSE profile used by AAuth.
Package personserver implements AAuth Person Server protocol handlers and host-facing policy and storage boundaries.
 Package personserver implements AAuth Person Server protocol handlers and host-facing policy and storage boundaries.
storetest
Package storetest checks reusable Person Server store contracts.
 Package storetest checks reusable Person Server store contracts.
r3
Package r3 implements the vocabulary-neutral values and proof rules of AAuth Rich Resource Requests.
 Package r3 implements the vocabulary-neutral values and proof rules of AAuth Rich Resource Requests.
internal/wirejson
Package wirejson provides the closed, duplicate-rejecting JSON grammar shared by R3 vocabulary adapters.
 Package wirejson provides the closed, duplicate-rejecting JSON grammar shared by R3 vocabulary adapters.
storetest
Package storetest checks reusable R3 store contracts.
 Package storetest checks reusable R3 store contracts.
vocab/asyncapi
Package asyncapi implements the R3 AsyncAPI operation grammar and a focused self-contained AsyncAPI 3.0/3.1 JSON definition adapter.
 Package asyncapi implements the R3 AsyncAPI operation grammar and a focused self-contained AsyncAPI 3.0/3.1 JSON definition adapter.
vocab/graphql
Package graphql implements the R3 GraphQL operation grammar.
 Package graphql implements the R3 GraphQL operation grammar.
vocab/grpc
Package grpc implements the R3 gRPC operation grammar and derives fully qualified methods from complete binary FileDescriptorSet input.
 Package grpc implements the R3 gRPC operation grammar and derives fully qualified methods from complete binary FileDescriptorSet input.
vocab/internal/discoveryendpoint
Package discoveryendpoint contains the shared discovery-endpoint profile used by the seven standard R3 vocabularies.
 Package discoveryendpoint contains the shared discovery-endpoint profile used by the seven standard R3 vocabularies.
vocab/mcp
Package mcp implements the R3 MCP operation grammar and native tools/list definition adapter.
 Package mcp implements the R3 MCP operation grammar and native tools/list definition adapter.
vocab/odata
Package odata implements the R3 OData operation grammar and derives an unambiguous structural subset from self-contained CSDL Edmx 4.0 metadata.
 Package odata implements the R3 OData operation grammar and derives an unambiguous structural subset from self-contained CSDL Edmx 4.0 metadata.
vocab/openapi
Package openapi implements the R3 OpenAPI operation grammar and a self-contained OpenAPI 3.0/3.1 Paths definition adapter.
 Package openapi implements the R3 OpenAPI operation grammar and a self-contained OpenAPI 3.0/3.1 Paths definition adapter.
vocab/standard
Package standard constructs explicit operation and native-definition registries for the seven standard R3 vocabularies.
 Package standard constructs explicit operation and native-definition registries for the seven standard R3 vocabularies.
vocab/wsdl
Package wsdl implements the R3 WSDL operation grammar and a self-contained WSDL 1.1 service/binding definition adapter.
 Package wsdl implements the R3 WSDL operation grammar and a self-contained WSDL 1.1 service/binding definition adapter.
vocabtest
Package vocabtest checks the two independent extension contracts implemented by an R3 vocabulary: operation grammar/algebra and native authoritative definition parsing.
 Package vocabtest checks the two independent extension contracts implemented by an R3 vocabulary: operation grammar/algebra and native authoritative definition parsing.
Package resource implements direct Agent and Person identity access, Resource-managed opaque sessions, and explicit Person-Server-authorized or federated auth-token access.
 Package resource implements direct Agent and Person identity access, Resource-managed opaque sessions, and explicit Person-Server-authorized or federated auth-token access.
storetest
Package storetest provides reusable contracts for Resource stores.
 Package storetest provides reusable contracts for Resource stores.
Package signaturekey implements the selected HTTP Signature-Key and HTTP Message Signatures profile used by AAuth.
 Package signaturekey implements the selected HTTP Signature-Key and HTTP Message Signatures profile used by AAuth.
Package supervision implements the wire values of AAuth Supervision, the interface between a Person Server and a supervision server (SS) that decides on the person's behalf, and the Person Server's client for it.
 Package supervision implements the wire values of AAuth Supervision, the interface between a Person Server and a supervision server (SS) that decides on the person's behalf, and the Person Server's client for it.
Package supervisionserver implements the supervision server (SS) role of AAuth Supervision: the server a person connects to their Person Server, which the Person Server consults for every supervision decision about the Agents routed to it.
 Package supervisionserver implements the supervision server (SS) role of AAuth Supervision: the server a person connects to their Person Server, which the Person Server consults for every supervision decision about the Agents routed to it.
Package testutil supplies in-memory stores for local development, examples and tests that compose the public protocol roles.
 Package testutil supplies in-memory stores for local development, examples and tests that compose the public protocol roles.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.