PEAC Protocol

Signed action records for AI agents, APIs, MCP tools, and gateways.

Automated systems already call APIs, run MCP tools, make gateway decisions, report payment events, and provision resources across system boundaries.

PEAC records those actions, decisions, and events as portable signed interaction records, so another party can verify what happened later without relying on screenshots, private logs, or unverifiable assertions.

Record locally. Verify across boundaries.

Start fast

• Verify a sample offline: docs/guides/offline-sample-index.md
• Compare verification paths: docs/guides/verification-options.md
• Wire PEAC into MCP, OpenTelemetry, or a gateway: docs/guides/integration-patterns.md
• Choose by role: docs/START_HERE.md

What PEAC records

PEAC is useful when a system does work and another party later needs to verify what happened without trusting that system's logs.

These are orientation examples, not partnership claims or exclusive integration targets. PEAC records what those systems report; it does not replace them.

PEAC does not make those decisions. It records what another system reported, binds it to an issuer and time, and makes it portable for verification.

What a PEAC record preserves

A PEAC record is signed evidence about an interaction.

A counterparty can verify the record locally with the issuer's public key or through a self-hosted verifier. Records can also be exported into portable bundles for audit, review, dispute, compliance, or incident workflows.

How it works

1. A system performs work
   API call, MCP tool run, agent action, gateway decision,
   payment event, provisioning event, runtime observation, or audit event

2. The system issues a signed PEAC record
   facts + policy/context + result + time + issuer + signature

3. A counterparty verifies the record
   locally, in CI, or through a self-hosted verifier using issuer keys

4. The record travels
   audit review, dispute review, compliance workflow, incident report,
   exported bundle, or another system boundary

PEAC records what another system reported. It does not decide whether an action was allowed, authenticate the actor, settle payment, operate the runtime, or replace logs and traces.

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.

Choose your path

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

Quickstart: verify a sample offline

pnpm dlx @peac/cli samples generate -o ./s
pnpm dlx @peac/cli verify ./s/valid/basic-record.jws --public-key ./s/bundles/sandbox-jwks.json

Expected:

Signature valid (offline).

For browser and self-hosted verifier paths, see docs/guides/verification-options.md. For the full shipped sample set, see docs/guides/offline-sample-index.md.

Quickstart: verify one record in code

npm install @peac/protocol @peac/crypto

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

const recordJws = response.headers.get('PEAC-Receipt');

if (!recordJws) {
  throw new Error('Missing PEAC-Receipt header');
}

const result = await verifyLocal(recordJws, publicKey, {
  issuer: 'https://api.example.com',
});

if (!result.valid) {
  throw new Error(`${result.code}: ${result.message}`);
}

console.log(result.claims.iss, result.claims.kind, result.claims.type);

This quickstart shows the developer path for one record. Operational latency and throughput baselines are tracked separately in docs/SLO.md.

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

Where PEAC fits

PEAC is useful when an action crosses a system, organization, protocol, agent, gateway, payment, provisioning, or audit boundary and the local log is not enough.

PEAC does not replace those systems. It gives them a portable records layer: what was reported, by whom, when, under which context, and with which verifiable signature.

If you work around MCP, A2A, x402, paymentauth / MPP, ACP, AP2-style commerce, UCP-style commerce, runtime governance, OpenTelemetry, or internal platform workflows, PEAC is the signed-record layer beside those systems, not a replacement for them.

Why PEAC

Modern systems often need proof that travels beyond the system that produced the log.

• Logs are local. PEAC records are portable and independently verifiable.
• Traces correlate execution. PEAC records preserve signed claims across organizational boundaries.
• Auth, policy, runtime, and payment systems decide whether actions may happen. PEAC records what another system reported happened.

For reviewers and operators

PEAC is designed to be reviewed as protocol infrastructure, not as a hosted control plane.

The reference verifier is self-hostable. Verification can also be performed locally when the record and issuer public key are available.

Use cases

Practical recipes under docs/SOLUTIONS/:

• API record issuance
• MCP tool-call records
• MCP gateway records
• Agent action records
• Gateway export records
• Commerce mandate records
• Commerce evidence bundle
• Cloudflare x402 + PEAC
• Runtime evidence export
• Provisioning lifecycle verification
• Regulatory audit trail

Try it in 5 minutes

• Verify a record locally with verifyLocal() or pnpm dlx @peac/cli verify.
• Generate sample records and verify one offline with just a public key:
  bash

  pnpm dlx @peac/cli samples generate -o ./s
  pnpm dlx @peac/cli verify ./s/valid/basic-record.jws --public-key ./s/bundles/sandbox-jwks.json
  

• Start the MCP server: npx -y @peac/mcp-server.

The pnpm dlx @peac/cli ... and npx ... commands above run without cloning this repository. The examples below are repo-local: clone the repository first, then run:

pnpm install --frozen-lockfile
pnpm build
pnpm demo:all

pnpm demo:all runs the start-here examples end to end. The individual commands below are optional targeted demos you can run after that setup.

• Run the minimal example: pnpm --filter @peac/example-minimal demo.
• Run the MCP gateway records example:
  bash

  pnpm --filter @peac/example-mcp-gateway-receipts demo
  pnpm --filter @peac/example-mcp-gateway-receipts demo:tamper
  

• Run the provisioning lifecycle example:
  bash

  pnpm --filter @peac/example-provisioning-lifecycle run issue
  pnpm --filter @peac/example-provisioning-lifecycle run verify
  

• Self-host the reference verifier: surfaces/reference-verifier/.

Implementations and surfaces

Extended package catalog: docs/README_LONG.md.

Artifacts

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 a records layer, not a runtime control plane. It records what another system reported and makes that record portable, signed, and verifiable across boundaries.

PEAC does not authorize actions, validate credentials, process payments, settle transactions, operate agents, host workflows, manage vaults, assign trust scores, or replace observability systems. Full boundary: docs/WHERE-IT-FITS.md.

Security

• JWS signature verification is required before trusting any record 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 record 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.
• Integration patterns — MCP, OpenTelemetry, and gateway integration patterns using shipped surfaces.
• Verification options, Offline sample index — verifier paths and sample records.
• How it works, Artifacts, Where it fits, What PEAC standardizes.
• Use cases — practical 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