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
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
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.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
