Cryptographic
identity for
any agent.

// Build RFC 9421 signature headers for any outgoing HTTP request
const body    = { task: 'summarize', url: 'https://example.com/doc' }
const headers = agent.signRequest('POST', '/api/task', body)

// headers includes:
// Signature-Input: sig1=("@method" "@path" "content-digest");
//   keyid="https://envoys.me/agents/[email protected]";
//   created=1714000000;nonce="…"
// Signature:       sig1=:base64EdDSASig:
// Content-Digest:  sha-256=:base64Hash:

await fetch('https://api.peer.ai/task', {
  method:  'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body:    JSON.stringify(body),
})

// Recipient resolves the keyid URL, fetches public key, verifies.
// No Envoys account needed on the receiving end.

// Verify an incoming RFC 9421-signed request (SDK).
// Public-key pinning is ON by default — first-seen public key is
// auto-recorded per address; subsequent contact with a different key
// fails verification (catches account-compromise silent rotation).
const result = await Envoys.verifyRequest(
  req.method, req.path, req.headers, req.body,
  { allowlist: ['[email protected]'] }  // optional: only accept these senders
)

if (!result.verified) {
  return res.status(401).json({ error: result.error })
}

// Always populated even on failure — log "we tried to verify a request from X"
console.log(result.address, result.keyid, result.publicKey)

// If you've confirmed a rotation out-of-band, clear the pin:
// Envoys.resetPin('[email protected]')

// Or manually resolve + verify
const pubkey = await Envoys.resolvePublicKey(address)
const ok     = Envoys.verify(payload, signatureHeader, pubkey)

// Sign your /.well-known/agent.json with JWS so consumers can
// verify it hasn't been tampered with. EdDSA over Ed25519 (RFC 8037).
const card = {
  name:    'Echo Agent',
  url:     'https://echo.example.com',
  version: '1.0.0',
  skills:  [{ id: 'echo', name: 'Echo' }],
}

const jws = agent.signAgentCard(card)
// → "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6Imh0dHBzOi8vLi4uIn0.
//    eyJuYW1lIjoiRWNobyBBZ2VudCI....base64url payload....
//    .signature_bytes_base64url"

// Anyone — no Envoys account needed — verifies it.
// kid header points at your address URL; verifier resolves it.
const result = await Envoys.verifyAgentCard(jws)

if (result.verified) {
  console.log(`Card from ${result.address}`, result.card)
}

# Step 1 — Generate an Ed25519 keypair locally (private key never leaves)
openssl genpkey -algorithm ed25519 -out priv.pem
openssl pkey -in priv.pem -pubout -out pub.pem

# Step 2 — Create an account
curl -sX POST https://envoys.me/accounts/register \
  -H 'Content-Type: application/json' \
  -d '{"handle":"your-handle"}'

# → { "account_key": "ak_...", "handle": "your-handle" }

# Step 3 — Register an agent (send your public key, keep private key)
curl -sX POST https://envoys.me/agents/register \
  -H 'Authorization: Bearer ak_...' \
  -H 'Content-Type: application/json' \
  -d "{\"name\":\"playground\",\"public_key\":\"$(cat pub.pem)\"}"

# → { "address":      "[email protected]",
#     "agent_key":    "agt_...",
#     "public_key":   "-----BEGIN PUBLIC KEY-----...",
#     "pop_verified": false }

# Optional pop + pop_created fields prove key possession — the SDKs send them automatically

# Resolve any agent's public key — no auth required, anyone can verify
curl 'https://envoys.me/agents/[email protected]'

# → { "address": "...", "public_key": "-----BEGIN PUBLIC KEY-----...",
#     "pop_verified": true | false,
#     "verified_handle": { "domain": "...", "verified_at": ... } | null }

# Full key history — detect silent rotations against your pin
curl 'https://envoys.me/agents/[email protected]/key-history'

# → { "address": "...", "current_key": "...", "revoked": false,
#     "history": [{ "public_key": "...", "valid_from": ..., "valid_until": ..., "reason": "register" }, ...] }

# CRL-style feed — poll hourly, invalidate cached pins for any address that rotated
curl 'https://envoys.me/agents/revocations?since=1714000000000'

# → { "since": ..., "now": ..., "events": [{ "address": "...", "ts": ..., "event": "rotation" | "revocation" }] }

# Anchor your handle to a real-world domain (auth: account_key)
curl -sX POST https://envoys.me/accounts/me/verify-handle \
  -H 'Authorization: Bearer ak_...' \
  -H 'Content-Type: application/json' \
  -d '{"domain":"acme.com"}'

# → returns DNS TXT record to add at _envoys-handle.acme.com,
#   then POST /accounts/me/verify-handle/check to complete verification