aauth

package module
v0.0.0-...-1bd2d46 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2026 License: MIT Imports: 23 Imported by: 0

README

AAuth for Go

aauth-go implements the current AAuth editor-source family as ordinary Go packages. Applications compose the protocol roles they need and provide their own policy, keys, transport, clocks, and durable storage.

This is an incomplete implementation, not an official conformance suite. SPECIFICATIONS.md pins the exact source revisions; CONFORMANCE.md states what executes today and what does not.

Start here

The module requires Go 1.25 or later.

go get gitlab.com/sidecat-dev/aauth-go

Run the smallest complete authorization journey:

go run gitlab.com/sidecat-dev/aauth-go/example/threeparty@latest

It carries an Agent through a Person Server to one protected Resource call. For a standalone external module that runs an Agent and local service as separate TLS processes, persists their application state, restarts them, and then revokes the active Agent token, use walkthrough/local.

For a standalone laptop-to-hosted-service path with separate TLS processes, authenticated account linking, mission approval, MCP authorization, a fixed Budget, restart recovery, and revocation, use walkthrough/hosted.

For qualified interoperability in both directions—Go Agent to the AAuth project's TypeScript Resource, and official TypeScript Agent to Go Person Server and Resource roles—use walkthrough/interop.

For a self-hosted Agent with a local permission boundary, direct local access, an explicit hosted account-link interaction, and one account-bound hosted Resource call, run:

go run gitlab.com/sidecat-dev/aauth-go/example/selfhosted@latest

The exact application boundary is in LOCAL-AGENT-PROFILE.md. For a composed local-Agent and hosted-service profile, run:

go run gitlab.com/sidecat-dev/aauth-go/example/hostedservice@latest

To use a self-hosted Agent identity and proof key against the same reviewed mission, R3, Budget, and connector path, run:

go run gitlab.com/sidecat-dev/aauth-go/example/hostedservice@latest --self-hosted

That profile adds enrollment and refresh, local permission, host-reviewed mission approval, a Resource-validated account, an MCP operation under a fixed Budget, application-owned OAuth credential use, refusal of an exhausted Budget before a second connector dispatch, and Agent-token revocation. Its exact deployment boundary is in HOSTED-SERVICE-PROFILE.md.

Choose a journey

Need Start with
Direct Agent or Person identity example/agentidentity
Separate local TLS processes, durable state, restart, and revocation walkthrough/local
Separate laptop and hosted-service TLS processes with mission, MCP, Budget, restart, and revocation walkthrough/hosted
Go/TypeScript interoperability in both directions walkthrough/interop
Three-party authorization example/threeparty
Four-party authorization through an Access Server example/fourparty
Account-bound four-party fixed Budget through an Access Server example/budgetfourparty
Self-hosted local Agent linking to a hosted account LOCAL-AGENT-PROFILE.md, example/selfhosted
Hosted enrollment or a self-hosted Agent through the full hosted-service path HOSTED-SERVICE-PROFILE.md, example/hostedservice
Local permission or a mission lifecycle example/permission, example/mission
Person questions, relays, or consent clarification example/interactionquestion, example/interactionrelay, example/psconsent
R3 operations and fixed hard-cap Budgets example/r3threeparty, example/budget
Public or protected Event delivery example/events
Revocation and explicit re-authorization example/revocation
Parent-mediated or chained work example/subagent, example/callchaining

JOURNEYS.md is the full role-to-role catalog. Each entry names the exported API, executable evidence, and missing continuations.

Package map

Package Responsibility
aauth Core identifiers, token claims, minting, verification, and context checks
jose Focused Ed25519 JWK and compact-JWS behavior
signaturekey HTTP request proofs, credentials, discovery, and error negotiation
agentprovider Agent enrollment, Agent-token issuance, metadata, and Events inbox
agent Explicit caller-side protocol steps; no hidden polling or consequence retry
personserver Person identity, authorization, missions, permission, interaction, audit, and federation
resource Identity, sessions, authorization, R3 enforcement, Budget charging, Events, and revocation
accessserver Person-Server-authenticated authorization and R3 issuance
r3 and r3/vocab/* Vocabulary-neutral grants plus bounded MCP, OpenAPI, gRPC, GraphQL, AsyncAPI, WSDL, and OData adapters
budgets and events Typed companion-protocol values and verification
*/storetest and r3/vocabtest Reusable contracts for application stores and third-party R3 adapters

The root protocol package and the JOSE and Signature-Key packages do not depend on role packages. Role packages compose them through small policy, storage, key-resolution, clock, and transport interfaces. See ARCHITECTURE.md for the dependency graph and state owners.

Integration boundary

  • Servers are composable http.Handler values. The library does not own the application's listener or process.
  • Agent methods perform one explicit protocol step. They do not open a browser, sleep, loop, or automatically retry a consequential request.
  • Hosts decide policy and authenticate people and administrators before invoking host-side decisions.
  • Hosts supply durable store implementations and run the applicable public storetest contracts against them. The shipped examples use in-memory stores and do not prove process-restart recovery.
  • R3 adapters parse already-acquired native definitions. Network discovery, source-size limits, and dependency acquisition remain application concerns.
  • Private keys and third-party service credentials stay with the application; AAuth values carry authority, not those credentials.

Current boundary

The repository has executing paths for direct identity, three- and four-party authorization, Resource-managed sessions, hosted enrollment and refresh, missions, local permission, audit, interaction, bounded delegation and call chaining, revocation, R3, Events, and fixed-price Budgets.

It does not yet implement all of AAuth Core or every companion profile. Notable exclusions include production store adapters, key custody, TLS and deployment infrastructure, platform attestation, general request-proof replay, several deferred and mission combinations, automatic revocation fan-out, complete Signature-Key schemes, variable or streaming Budgets, and independent person, authorization, and full-profile interoperability.

Do not infer support from an exported type. Use:

Documentation

Document Use it for
PROTOCOL.md How the pinned specifications compose into roles, values, and journeys
ARCHITECTURE.md Package boundaries, state ownership, transport, policy, and proof seams
SPECIFICATIONS.md Exact editor-source commits, digests, and R3 vocabulary baselines
CONFORMANCE.md Implemented, partial, and absent behavior with executable evidence
JOURNEYS.md Runnable role-to-role paths
LOCAL-AGENT-PROFILE.md Smallest useful self-hosted local deployment
INTERPRETATIONS.md Deliberate choices where the source does not determine one implementation
SPEC-FEEDBACK.md Reproducible questions and inconsistencies found during implementation
CONTRIBUTING.md Source-grounded change and verification workflow
SECURITY.md Vulnerability reporting and deployment responsibilities

Package documentation is available through ordinary Go tooling, for example:

go doc gitlab.com/sidecat-dev/aauth-go/resource

Verify the repository

go test ./... -count=1
go test -race ./... -count=1
go vet ./...
go build ./...

To verify the machine-readable protocol map against the pinned editor-source bytes, use the command in SPECIFICATIONS.md.

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.

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, mission-bound authorization through both topologies, parent-mediated one-level sub-agents, bounded 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. See CONFORMANCE.md for exact 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.

Variables

This section is empty.

Functions

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 FormatPersonTokenRequirement 

func FormatPersonTokenRequirement() string

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

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 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 8941 List of Tokens. Parameters on capability items are extension data and are ignored. 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 ValidateAgentIdentifier 

func ValidateAgentIdentifier(identifier string) error

ValidateAgentIdentifier validates the AAuth URI identifier grammar.

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 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 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 the Core token-revocation request shape.

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 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.

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 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 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. Core defines the status values but does not define a terminal response body; see SPEC-FEEDBACK.md.

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 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 {
	Approver          string        `json:"approver"`
	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.

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 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 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 ProblemError 

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

ProblemError is an AAuth RFC 9457 error response. Code is the required AAuth "error" extension member.

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 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 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"`
	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 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 the Access Server role for immediate four-party AAuth Core and R3 class and per-call authorization.
 Package accessserver implements the Access Server role for immediate four-party AAuth Core and R3 class and per-call authorization.
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 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.
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.
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 re-authorization in process.
 The revocation example runs issuer-driven Agent- and Auth-token revocation, caller-controlled retry, and explicit re-authorization 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 immediate parent-mediated authorization entirely in process.
 The subagent example runs immediate parent-mediated authorization 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.
internal
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.
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.
Package jose implements the bounded Ed25519 JOSE profile used by AAuth.
 Package jose implements the bounded Ed25519 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 PS-authorized or federated auth-token access.
 Package resource implements direct Agent and Person identity access, Resource-managed opaque sessions, and explicit PS-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.

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.