AAuth for MCP

TypeScript packages for adding AAuth to MCP servers and agents.

AAuth is an agent-aware authentication protocol that lets AI agents prove their identity and obtain authorization using HTTP Message Signatures and JWTs.

Packages

Package	Description
@aauth/bootstrap	CLI for setting up AAuth agent keys, person server registration, and hosting
@aauth/fetch	CLI for making AAuth-authenticated HTTP requests
@aauth/protocol	Wire format: AAuth-Requirement, AAuth-Capabilities, access_mode planning, typ/dwk constants
@aauth/agent	Agent-side AAuth: signed fetch, person tokens, challenge-response, token exchange
@aauth/resource	Resource-side AAuth: token verification, challenge building, resource tokens, R3
@aauth/local-keys	Library for managing AAuth agent signing keys across hardware and software backends
@aauth/hardware-keys	Native bindings for YubiKey PIV and macOS Secure Enclave
@aauth/mcp-stdio	stdio-to-HTTP proxy with AAuth signatures
@aauth/mcp-openclaw	OpenClaw plugin for AAuth-authenticated MCP connections

How It Works

Agent                        Resource Server              Auth Server
  |                                |                          |
  |--- signed request ------------>|                          |
  |                                |                          |
  |<-- 401 + resource_token -------|                          |
  |        + auth-server URL       |                          |
  |                                |                          |
  |--- signed POST (resource_token) ------------------------->|
  |                                                           |
  |<-- auth_token --------------------------------------------|
  |                                |                          |
  |--- signed request ------------>|                          |
  |    + auth_token                |                          |
  |                                |-- verify signature       |
  |                                |-- verify auth_token      |
  |                                |-- check key binding      |
  |<-- 200 OK ---------------------|                          |

1. Agent sends a signed HTTP request to the resource server
2. Resource responds with 401 + a resource_token and auth server URL
3. Agent exchanges the resource_token at the auth server (signed request)
4. Auth server returns an auth_token (or 202 for interactive flows)
5. Agent retries with the auth_token — resource verifies signature, token, and key binding

All requests are signed with HTTP Message Signatures (RFC 9421) using Ed25519. Tokens are JWTs with aa-agent+jwt, aa-auth+jwt, and aa-resource+jwt types.

Quick Start

Agent side

import { createAAuthFetch } from '@aauth/mcp-agent'

const fetch = createAAuthFetch({
  getKeyMaterial: async () => ({
    signingKey: privateKeyJwk,
    signatureKey: { type: 'jwt', jwt: agentToken }
  })
})

const response = await fetch('https://resource.example/api')
// Handles 401 challenges, token exchange, and retry automatically

Server side

import { verifyToken, buildAAuthHeader, createResourceToken } from '@aauth/mcp-server'

// Verify an incoming signed request's token
const result = await verifyToken({ jwt, httpSignatureThumbprint })

// Build a 401 challenge
const header = buildAAuthHeader('auth-token', { resourceToken, authServer })

// Create a resource token for the challenge
const token = await createResourceToken({ resource, authServer, agent, agentJkt }, sign)

Local development

# Register an agent provider: generate a key, bind it, and bind the default
# person server (person.hello.coop)
npx @aauth/bootstrap create <your-agent-provider-url>

See @aauth/bootstrap for the full setup flow.

Protocol Support

This implementation covers the core AAuth protocol flows. The following spec features are not yet supported:

• Call chaining — multi-hop delegation where a resource acts as an agent to call downstream resources with upstream_token
• AS federation (four-party mode) — PS-to-Access-Server federation with requirement=claims for identity claim exchange

Specification

The AAuth protocol specification: github.com/dickhardt/AAuth

License

MIT