aauth-go

A Go implementation of the AAuth protocol: agent identity and authorization across trust domains, with no shared secrets and no per-server pre-registration. Every agent holds its own signing key (Ed25519 by default, or ES256) and a self-describing token that binds it; any party can verify the token and every request it signs.

The module covers every role: agent, resource, Person Server (PS), Access Server (AS), and hosted agent provider (AP). Each is a library you embed in your own services.

To our knowledge this is the first Go implementation of the protocol (the draft's Implementation Status section lists TypeScript, .NET, Python, and Java).

Drafts implemented

Draft	Version	Constant
AAuth Protocol	draft-hardt-oauth-aauth-protocol-11	aauth.ProtocolDraft
HTTP Signature Keys	draft-hardt-httpbis-signature-key-09	aauth.SignatureKeyDraft
AAuth Bootstrap	draft-hardt-aauth-bootstrap-02	aauth.BootstrapDraft

The drafts are works in progress, and each revision can change the wire format; the module's minor version moves with them until the protocol stabilizes. Upgrading from v0.1 (draft -09)? See the migration guide and the changelog. For an interactive tour of the protocol, see explorer.aauth.dev.

Contents

• Install
• Packages
• Quick start: agent
• Quick start: resource
• Quick start: hosted AP, PS, and AS
• Protocol coverage
• Design notes
• Security notes
• Sandbox
• Examples
• Testing
• License

Install

go get github.com/aauth-dev/aauth-go

Requires Go 1.26 or later. The full API reference is on pkg.go.dev.

import aauth "github.com/aauth-dev/aauth-go"

Packages

Package	Contents
aauth	The protocol vocabulary shared by every role: identifiers, keys, tokens (mint, issue, verify), HTTP message signatures, metadata, requirements, deferred responses, revocation, errors, and the agent-side PSClient and Transport. Resources use it directly.
personserver	Person Server as an http.Handler: person and auth token endpoints, pending requests, missions, permission, audit, interaction, revocation, and federation to access servers.
accessserver	Access Server as an http.Handler (AS token endpoint, revocation), plus Client (PS to AS over HTTP) and Server.Local (in-process PS-AS collapse).
agentprovider	Hosted agent provider: agent token issuance, two-key and single-key refresh, sub-agent tokens, and a Client for agents (Enroll, TokenSource).
ratelimit	In-memory token bucket implementing aauth.Limiter for single-instance deployments.
interactioncode	Interaction code generation and canonicalization (Crockford base32).
sandbox	Every role together for development, behind the aauth-sandbox command: development CA, consent pages, message trace and a signing helper.

Quick start: agent

A self-hosted agent is its own agent provider (bootstrap §4.3): it holds a key, mints its own agent tokens, and serves /.well-known/aauth-agent.json and its JWKS (Agent.JWKS) at its issuer. Wrap an http.Client with Transport and AAuth disappears from application code:

id, err := aauth.ParseAgentIdentifier("aauth:[email protected]")
if err != nil {
	return err
}
agent, err := aauth.NewAgent(id,
	aauth.WithIssuer("https://agent.example"),    // serves aauth-agent.json and the JWKS
	aauth.WithPersonServer("https://ps.example"), // the ps claim
)
if err != nil {
	return err
}

ps := aauth.NewPSClient("https://ps.example", agent)
if _, err := ps.Discover(ctx); err != nil { // endpoints from aauth-person.json
	return err
}

hc := &http.Client{Transport: aauth.NewTransport(agent, ps)}
res, err := hc.Get("https://files.example/files")

For each request the transport signs with the agent's key and answers requirement=agent-token, person-token, and auth-token challenges (401, or a 202 deferred delivery): it obtains a person token, redeems the resource token at the PS, verifies what it receives, caches tokens per resource with a five-minute refresh margin, and retries. Set Transport.OnRequirement to show the user an interaction URL and code while a request waits for them.

An agent whose tokens come from a hosted provider uses aauth.WithTokenSource, for example with agentprovider.Client.TokenSource.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗