@aauth/local-keys

@aauth/local-keys

Library for managing AAuth agent signing keys across hardware and software backends. Supports YubiKey PIV, macOS Secure Enclave, and OS keychain — with automatic key resolution that prefers hardware keys and tolerates devices being unavailable.

Part of aauth-dev/packages-js. Protocol spec: dickhardt/AAuth.

Looking for a CLI? This package is a library. The CLI for setting up agent keys, configuring a person server, and publishing keys is @aauth/bootstrap. Run npx @aauth/bootstrap generate --agent <your-agent-url> --ps to get started (--ps with no URL binds the default person server, person.hello.coop).

Install

npm install @aauth/local-keys

Key Backends

Backend	Algorithm	Platform	Storage
yubikey-piv	ES256, RS256	Cross-platform	YubiKey slot 9e (no PIN)
secure-enclave	ES256	macOS (Apple Silicon)	Secure Enclave hardware
software	Ed25519, ES256	All	OS keychain

Hardware keys are always preferred over software keys. If a YubiKey is unplugged, signing automatically falls back to the next available key.

Algorithm identifiers are fully specified per RFC 9864, as AAuth -11 §Signature Algorithms requires: Ed25519, never the polymorphic EdDSA. Every JWK this package emits carries an alg that agrees with its kty/crv, and keys generated before 2.0.0 are normalized on read — see withFullySpecifiedAlg / assertFullySpecifiedAlg.

API

createAgentToken(options): Promise<AgentTokenResult>

The primary API for other packages. Signs an agent token and returns the ephemeral key material needed for HTTP Message Signatures.

import { createAgentToken } from '@aauth/local-keys'

const { signingKey, signatureKey } = await createAgentToken({
  delegate: 'claude',
  // agentUrl is optional — defaults to first configured agent
})

// signingKey: ephemeral private JWK for HTTP signatures
// signatureKey: { type: 'jwt', jwt: '...' } signed agent token

Key resolution is automatic: fetches the agent's published JWKS, matches against local hardware and software keys, prefers hardware, tolerates failures at every step.

discoverBackends(): BackendInfo[]

List available key backends on this machine.

import { discoverBackends } from '@aauth/local-keys'

const backends = discoverBackends()
// [{ backend: 'yubikey-piv', description: '...', algorithms: ['ES256'], deviceId: '9570775' }, ...]

resolveKey(agentUrl): Promise<ResolvedKey>

Resolve which key to use for signing. Fetches JWKS, matches thumbprints against local keys, falls back through config and keychain.

import { resolveKey } from '@aauth/local-keys'

const key = await resolveKey('https://you.github.io')
// { backend: 'yubikey-piv', keyId: '9e', kid: '2026-04-09_a3f', algorithm: 'ES256', publicJwk: {...} }

Config Management

import {
  readConfig,
  getAgentConfig,
  addKeyToAgent,
  setPersonServer,
  setHosting,
} from '@aauth/local-keys'

addKeyToAgent('https://you.github.io', 'kid-123', {
  backend: 'yubikey-piv',
  algorithm: 'ES256',
  keyId: '9e',
  deviceLabel: 'yubikey-5c-0775',
})

setPersonServer('https://you.github.io', 'https://your-ps.example')

setHosting('https://you.github.io', {
  platform: 'github-pages',
  repo: 'you/you.github.io',
})

Config File

~/.aauth/config.json:

{
  "agents": {
    "https://you.github.io": {
      "personServerUrl": "https://your-ps.example",
      "hosting": {
        "platform": "github-pages",
        "repo": "you/you.github.io"
      },
      "keys": {
        "2026-04-09_a3f": {
          "backend": "yubikey-piv",
          "algorithm": "ES256",
          "keyId": "9e",
          "deviceLabel": "yubikey-5c-0775"
        },
        "2026-04-09_b71": {
          "backend": "secure-enclave",
          "algorithm": "ES256",
          "keyId": "com.aauth.agent.2026-04-09_b71",
          "deviceLabel": "macbook-pro-dick"
        }
      }
    }
  }
}

This file is written by @aauth/bootstrap and read by every package that needs to sign as the agent.

Key Resolution

When signing, keys are resolved automatically through this fallback chain:

• Fetch {agentUrl}/.well-known/aauth-agent.json to find the JWKS
• Match published key thumbprints against locally available hardware and software keys
• Fall back to ~/.aauth/config.json registered keys
• Fall back to any available hardware key (bootstrap)
• Fall back to OS keychain software keys (backward compatibility)

Hardware keys are always preferred. Unavailable backends (e.g. unplugged YubiKey) are gracefully skipped.

License

MIT