# PEAC Protocol

> PEAC Protocol is an open standard for verifiable interaction records: portable signed records for agent, API, MCP, gateway, provisioning, and commerce workflows.
> Last reviewed: 2026-08-09

## What is PEAC

PEAC Protocol provides cryptographically signed, offline-verifiable interaction records. Each record is a compact JWS (JSON Web Signature) using Ed25519 signatures that can be verified offline given the issuer's public key (or a pinned JWKS). PEAC complements logs, OpenTelemetry, auth, MCP, A2A, payment rails, gateways, and provisioning tools without replacing them. PEAC does not orchestrate agents, settle payments, authorize access, host records, or provide a central authority.

## What PEAC records

PEAC standardizes portable signed records for six interaction surfaces:

- **API calls**: HTTP APIs, REST services, gateways — issue a signed record proving what happened
- **MCP tool runs**: Model Context Protocol tool invocations — record tool call evidence via `@peac/mappings-mcp` and `@peac/mcp-server`
- **Agent actions**: A2A handoff observations, CLI executions, lifecycle approvals, workflow transitions
- **Gateway decisions**: Gateway export records — `org.peacprotocol/gateway-export` (v0.14.3); x402 payment flows via `@peac/adapter-x402`. Terminal gateway access decisions (allow/deny/review) use the Gateway Decision Evidence profile over `org.peacprotocol/access-decision` + the `org.peacprotocol/access` extension (v0.16.3; informative, no new registered surface)
- **Payment events**: x402, Stripe SPT, ACP, MPP/paymentauth, UCP commerce evidence — `@peac/rails-stripe`, `@peac/mappings-paymentauth`, `@peac/mappings-acp`
- **Provisioning events**: API key issuance, OAuth client registration, certificate provisioning, secret rotation, access grants — `org.peacprotocol/provisioning-lifecycle` (v0.14.2)

PEAC does not orchestrate agents, settle payments, replace auth, replace logs, enforce policy, route requests, or become an observability backend. It records neutral evidence that travels across boundaries.

## Quick Start

- Install the MCP server: `npm install -g @peac/mcp-server`
- Verify a record: `pnpm add -g @peac/cli` then `peac verify <jws>` (network JWKS), or `peac verify <jws> --public-key <jwks>` for fully offline verification (v0.15.1+)
- Issue a record: use `@peac/protocol` with `issue()` and an Ed25519 signing key
- CLI execution records: `peac record command -- <cmd>` (signed `interaction-record+jwt` record)
- GitHub: https://github.com/peacprotocol/peac
- Website: https://www.peacprotocol.org

## Key Packages

- `@peac/kernel`: Normative constants, error codes, and type definitions (Layer 0)
- `@peac/schema`: Zod validation schemas for interaction records (Layer 1)
- `@peac/crypto`: Ed25519 signing and verification (Layer 2)
- `@peac/protocol`: High-level issue and verify API (Layer 3)
- `@peac/control`: Policy-kit and purpose-binding (Layer 3)
- `@peac/policy-kit`: Policy document parsing and evaluation (Layer 3)
- `@peac/middleware-express`: Express.js middleware for automatic record issuance (Layer 3.5)
- `@peac/mcp-server`: MCP server with 5 tools for record operations (Layer 5)
- `@peac/cli`: CLI for issuing, verifying, and recording agent interactions (Layer 5)

## CLI Records (v0.14.1+)

- `peac observe command -- <cmd>`: Capture unsigned JSON observation of a CLI command
- `peac record command -- <cmd>`: Issue a signed `interaction-record+jwt` execution record (requires --issuer-key and --issuer-id)
- `peac emit lifecycle`: Emit a signed lifecycle observation record (approval, evaluation, workflow events)
- Security defaults: argv hashed by default; stdin none by default; raw capture requires explicit double opt-in

## Agent Integration

- MCP Server: 5-tool MCP server for Claude Desktop, Cursor, VS Code Copilot, and any MCP client
- A2A Mapping: `@peac/mappings-a2a` for Agent-to-Agent Protocol v1.0 handoff observation records (Microsoft AGT / AAIF compatible)
- ACP Mapping: `@peac/mappings-acp` for Agentic Commerce Protocol evidence
- UCP Mapping: `@peac/mappings-ucp` for Universal Commerce Protocol evidence; `verifyUcpHttpSignature` verifies UCP webhooks with RFC 9421 HTTP Message Signatures and RFC 9530 Content-Digest (v0.15.2)
- x402 Adapter: `@peac/adapter-x402` for HTTP 402 payment-required evidence (x402 v1 and v2)
- MPP / paymentauth Mapping: `@peac/mappings-paymentauth` for Machine Payments Protocol challenges and records
- Managed Agents: `@peac/adapter-managed-agents` for managed agent platform evidence
- Runtime Governance: `@peac/adapter-runtime-governance` for policy evaluation, safety check, compliance gate, and mode transition records (AGT / AAIF compatible; RTGOV-001..007)
- DID Resolution: `@peac/adapter-did` for did:key and did:web key resolution
- gRPC Transport: `@peac/transport-grpc` for gRPC metadata carrier
- Content Signals: `@peac/mappings-content-signals` for robots.txt, Content-Usage (AIPREF), and tdmrep.json signal parsing
- TAP Mapping (source-only): `@peac/mappings-tap` for Visa Trusted Agent Protocol proof verification with a strict issuer trust boundary (build from source; not published)
- RSL Mapping (source-only): `@peac/mappings-rsl` for RSL 1.0 (Robots Specification Layer) usage-token to control-purpose mapping (build from source; not published)
- AIPREF Mapping (source-only): `@peac/mappings-aipref` for IETF AIPREF vocabulary and Content-Usage header mapping (build from source; not published)
- OpenAI Adapter: `@peac/adapter-openai-compatible` for hash-first inference records
- Telemetry: `@peac/telemetry-otel` for bridging PEAC records to OTel spans via `peac.record.ref` span attribute
- HTTP: `PEAC-Receipt` response header carries compact JWS for any HTTP API
- Evidence Carrier Contract: universal carry interface across MCP, A2A, ACP, UCP, x402, MPP, gRPC, and HTTP

## Extension Profiles (v0.14.x)

- **Agent Action Records**: `org.peacprotocol/agent-action` (v0.14.3; 17th extension group; 6 type URIs; Section 32). Records agent decision and action evidence.
- **Commerce Mandate Records**: `org.peacprotocol/commerce-mandate` (v0.14.3; 18th extension group; 7 type URIs). Records commerce mandate grant and lifecycle states.
- **Gateway Export Records**: `org.peacprotocol/gateway-export` (v0.14.3; 19th extension group; 8 type URIs). Records gateway decisions covering x402 payment-settlement state machine.
- **Provisioning Lifecycle**: `org.peacprotocol/provisioning-lifecycle` (v0.14.2; 16th extension group; 10 `*-observed` type URIs; Section 31 PROV-LIFE-001..010; `validateProvisioningLifecycle` with recursive credential-material scanner; 21 stable error codes). Records provisioning events: credential issuance, secret rotation, service authorization. Opaque refs required (urn:, ref:, did:, sha256:).
- **Lifecycle Observation**: `org.peacprotocol/lifecycle-observation` (v0.14.1; 15th extension group; 9 type URIs; Section 30 LIFE-OBS-001..010). Records workflow approvals, evaluations, experiments, and mode transitions.
- **A2A Handoff**: `org.peacprotocol/a2a-handoff` (v0.14.1; 10 type URIs; Section 28; Microsoft AGT / AAIF compatible).
- **CLI Execution**: `org.peacprotocol/cli-execution` (v0.14.1; Section 29 CLI-EXEC-001..006).
- **Runtime Governance**: `org.peacprotocol/runtime-governance` (v0.12.10; 6 type URIs; Section 27 RTGOV-001..007).

## Payment Rails

- x402 (HTTP 402 payment flows): `@peac/adapter-x402`, `@peac/rails-x402` — x402 v1 and v2 dual-header
- MPP / paymentauth (HTTP auth payment challenges): `@peac/mappings-paymentauth`
- Stripe (SPT delegation grants): `@peac/rails-stripe`
- Razorpay: `@peac/rails-razorpay`

## Documentation

- Start Here: https://www.peacprotocol.org/start-here
- Record Categories (six interaction surfaces): https://www.peacprotocol.org/categories
  - API call: https://www.peacprotocol.org/categories/api-call
  - MCP tool run: https://www.peacprotocol.org/categories/mcp-tool-run
  - Agent action: https://www.peacprotocol.org/categories/agent-action
  - Gateway decision: https://www.peacprotocol.org/categories/gateway-decision
  - Payment event: https://www.peacprotocol.org/categories/payment-event
  - Provisioning event: https://www.peacprotocol.org/categories/provisioning-event
- When Not to Use: https://www.peacprotocol.org/when-not-to-use
- Compatibility: https://www.peacprotocol.org/compatibility
- PEAC vs Existing Systems: https://www.peacprotocol.org/vs
- Architecture: https://www.peacprotocol.org/docs/architecture/package-layering
- Error Codes: https://www.peacprotocol.org/docs/reference/error-codes
- Security: https://www.peacprotocol.org/security
- Releases: https://www.peacprotocol.org/releases
- Examples: https://www.peacprotocol.org/examples
- Anchoring Evidence Digests (external registration and timestamping): https://www.peacprotocol.org/docs/guides/anchoring-evidence-digests
- Agent Runtime Lineage Export: https://www.peacprotocol.org/docs/guides/agent-runtime-lineage-export
- Agent Spend Attribution: https://www.peacprotocol.org/docs/guides/agent-spend-attribution
- Cross-Organization Verification Handoff (one org issues a record and shares it with the public key; another org verifies it locally with no issuer callback and no shared online verification service): https://www.peacprotocol.org/docs/guides/cross-org-verification-handoff

## Technical

- Wire Format: `interaction-record+jwt` (current stable); `peac-receipt/0.1` (frozen legacy)
- Signing Algorithm: Ed25519 (RFC 8032); PEAC Ed25519 verification profile (cofactorless, shared small-order denylist, fixed-width scalar comparison) aligned across TypeScript and Go (v0.16.0+)
- Input determinism: the JWS protected header and payload are validated as I-JSON (RFC 7493) before parsing; codes E_IJSON_DUPLICATE_MEMBER_NAME, E_IJSON_NUMBER_OUT_OF_RANGE, E_IJSON_INVALID_STRING (v0.16.0+)
- Local verification handoff (v0.16.4+): I-JSON (RFC 7493) is enforced on ISSUANCE so issuance and verification apply the same admission rules to record bytes; the JWS `kid` is bounded to at most 256 UTF-8 bytes; the reference browser verifier verifies supplied-key records entirely locally with no network, storage, or service worker
- Optional replay protection: `createReplayGuard` in `@peac/protocol` classifies an already-verified record as fresh, replayed, or outside-window; composable, not wired into stateless verification (v0.16.0+)
- Portable evidence (v0.16.2+): `extractSignedReceiptFromSettlement` (`@peac/adapter-x402`) reads a signed receipt from an x402 settlement response body (Signed Offers and Receipts extension); Merkle commitment helpers in `@peac/audit` (`buildReceiptMerkleCommitment` / `generateReceiptMerkleInclusionProof` / `verifyReceiptMerkleInclusion`) commit to a sorted set of `receipt_ref`s (CT-style, RFC 9162) with offline inclusion proofs; `@peac/telemetry-otel` dual-emits `peac.record.ref` alongside legacy `peac.receipt.ref`. Offline example records: paid-resource, paid-MCP-tool, counterparty acknowledgment, agent-run lineage, action approval
- Error Format: RFC 9457 Problem Details (189 codes across 13 categories)
- Discovery: `/.well-known/peac-issuer.json` with `jwks_uri` pointing to JWKS
- Runtime: Node.js >= 22.13.0 (stable WebCrypto Ed25519)
- License: Apache-2.0
- Version: 0.16.4 (36 packages on npm latest, 13149 tests, 290 conformance requirements, 32 sections, 19 extension groups, 61 receipt types, 113 build targets)
- Maintained by Originary: https://www.originary.xyz