PEAC Protocol

Govern locally. Prove across boundaries.

When logs aren't enough, PEAC gives you portable signed records anyone can verify offline.

Portable signed records for agent, API, MCP, and cross-runtime interactions.

What you can do

• I run an API or HTTP service. Issue signed receipts on every response. API Provider Quickstart.
• I run an MCP server. Attach signed records to tool calls. MCP Integration Kit or npx -y @peac/mcp-server.
• I want to verify a receipt. Verify offline with the issuer's public key. Agent Operator Quickstart.
• I want to prove my runtime decisions. Record governance observations from managed runtimes. @peac/adapter-runtime-governance.
• I run agent-to-agent workflows. Record A2A handoff events across agent-card discovery, task lifecycle, and human-review boundaries. A2A Handoff Records.
• I want to record command execution. Use peac observe command for unsigned observations or peac record command for signed command-execution records. CLI Carrier Profile.
• I need lifecycle records from another system. Use peac emit lifecycle to issue records for caller-reported evaluation, approval, experiment, and workflow events. Lifecycle Observation Profile.

Full path-by-role tree: docs/START_HERE.md.

Verify a PEAC receipt in 60 seconds

pnpm add @peac/protocol @peac/crypto

import { verifyLocal } from '@peac/protocol';

const receipt = response.headers.get('PEAC-Receipt');
const result = await verifyLocal(receipt, publicKey, {
  issuer: 'https://api.example.com',
});

if (result.valid) {
  console.log(result.claims.iss, result.claims.kind, result.claims.type);
}

Node 24 tested, Node 22+ compatible. Go middleware and examples supported (Go 1.26+). Python via API-first examples and OpenAPI-driven flows.

How it works

1. Publish terms at /.well-known/peac.txt
2. Return PEAC-Receipt with a signed interaction record
3. Verify offline with the issuer's public key

Full loop: docs/HOW-IT-WORKS.md. Artifact vocabulary (record, receipt, bundle, report): docs/ARTIFACTS.md. Where PEAC sits next to other systems: docs/WHERE-IT-FITS.md. Protocol scope: docs/WHAT-PEAC-STANDARDIZES.md.

Solutions

Outcome-led recipes under docs/SOLUTIONS/:

• Runtime evidence export
• API record issuance
• MCP tool-call records
• Commerce evidence bundle
• Regulatory audit trail
• Cloudflare x402 + PEAC

Why PEAC

• Logs are local. PEAC records are portable.
• Traces correlate systems. PEAC records survive organizational boundaries.
• Auth and payments authorize actions. PEAC records prove what happened.

Try it in 5 minutes

• Verify a receipt locally with verifyLocal() or pnpm dlx @peac/cli verify.
• Start the MCP server: npx -y @peac/mcp-server.
• Run the x402 settlement mapping demo: pnpm install && pnpm build && pnpm --filter @peac/example-x402-upto-evidence demo.
• Record a command execution observation: pnpm dlx @peac/cli@next observe command -- echo hello. For signed command records, use peac record command with an issuer key; see the CLI Carrier Profile.
• Open an editor plugin-pack under surfaces/plugin-pack/ (Cursor, Codex, Claude Code, VS Code, Continue, Windsurf, OpenCode).
• Run the minimal example: pnpm --filter @peac/example-minimal demo.
• Self-host the reference verifier: surfaces/reference-verifier/.

Implementations and surfaces

• TypeScript core — issuance, verification, CLI, middleware (this repo).
• Go SDK — sdks/go/ with production HTTP middleware.
• MCP tools — packages/mcp-server/ evidence tools.
• Editor and plugin-pack surfaces — Cursor, Codex, Claude Code, VS Code, Continue, Windsurf, OpenCode under surfaces/plugin-pack/; canonical Smithery config.
• Express middleware — packages/middleware-express/.
• Commerce mappings — packages/adapters/x402/ (v1 + v2), packages/mappings/paymentauth/ (paymentauth / MPP), packages/mappings/acp/ (ACP delegated payment).
• Runtime governance — packages/adapters/runtime-governance/ records observations from managed runtimes including Microsoft Agent Governance Toolkit.
• A2A handoff records — docs/specs/A2A-HANDOFF-RECORDS.md and integrator-kits/a2a/.
• CLI execution records — peac observe command, peac record command, and docs/specs/CLI-CARRIER-PROFILE.md.
• Lifecycle observation records — peac emit lifecycle and docs/specs/LIFECYCLE-OBSERVATION-PROFILE.md.
• Supply-chain mappings — packages/mappings/intoto/ and packages/mappings/slsa/.
• Reference verifier (self-hostable) — apps/api/ with deployment recipes under surfaces/reference-verifier/.

Long tail (A2A, gRPC, DID, managed agents, and more): docs/README_LONG.md.

Artifacts

Artifact	Role
/.well-known/peac.txt	Machine-readable terms
PEAC-Receipt	HTTP response header carrying a signed interaction record
verifyLocal()	Offline verification once issuer keys are available
peac-bundle/0.1	Portable audit and dispute package

CLI

# One-off
pnpm dlx @peac/cli verify 'eyJhbGc...'

# Installed in your workspace
pnpm add -D @peac/cli
pnpm exec peac verify 'eyJhbGc...'

Other commands: peac observe command, peac record command, peac emit lifecycle, peac conformance run, peac reconcile a.bundle b.bundle, peac policy init|validate|generate, peac doctor. Reference: packages/cli/README.md.

Protocol boundary

PEAC is the records layer beneath runtime governance. PEAC records what another system attested; it is not a governance toolkit, policy engine, runtime control plane, payment protocol, identity protocol, trust-score system, observability dashboard, or hosted runtime. Full boundary: docs/WHERE-IT-FITS.md.

Security

• JWS signature verification required before trusting any receipt claim.
• Key discovery via /.well-known/peac-issuer.json JWKS with SSRF guards.
• Kernel constraints enforced at issuance and verification (fail-closed).
• No silent network fallback for offline verification.
• Errors mapped to RFC 9457 Problem Details.

See SECURITY.md, docs/TRUST-ARTIFACTS.md, docs/specs/PROTOCOL-BEHAVIOR.md, docs/COMPATIBILITY_MATRIX.md, and docs/specs/VERSIONING.md.

Privacy-aware verification

PEAC ships privacy-aware defaults and deployment guidance. Interaction evidence is hash-by-default on the receipt side (docs/specs/PRIVACY-PROFILE.md); the verifier separates immutable signed evidence from mutable derived metadata so retention, deletion, and rights-handling act on the right layer. Operator-facing guidance for privacy-sensitive and regulated environments (data classification, retention and deletion, deployment roles, data-subject rights, and a DPIA starter) lives in docs/privacy/. PEAC supports privacy-aware verification; it does not replace operator legal review, lawful-basis decisions, or controller obligations.

Versioning

• Current default format: interaction-record+jwt (Wire 0.2).
• Legacy: peac-receipt/0.1 (Wire 0.1) is frozen and legacy-only; verifyLocal() returns E_UNSUPPORTED_WIRE_VERSION on legacy input.

Full doctrine: docs/specs/VERSIONING.md.

Documentation

• Start Here — path by role.
• How it works, Artifacts, Where it fits, What PEAC standardizes.
• Solutions — outcome-led recipes.
• Spec Index — normative specifications, including Resource limits.
• Standards ledger — every external standard PEAC cites or implements, by status.
• Release-line baselines — historical invariant snapshots and release-line references.
• Developer Guide — package catalog and extended examples.

Contributing and license

Contributions are welcome. For substantial changes, please open an issue first.

Apache-2.0. See LICENSE.

---

PEAC Protocol is an open-source project stewarded by Originary and community contributors.

Docs · GitHub · Discussions