PEAC Protocol

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

Automated systems call APIs, run tools, make gateway decisions, initiate commerce flows, and provision resources across organizational boundaries.

PEAC lets those systems issue portable signed interaction records so another party can verify what the issuer reported, locally, offline, or across system boundaries, without relying only on screenshots or private logs.

Record locally. Verify across boundaries.

PEAC Protocol is open-source software published and maintained by Originary, with contributions from the community.

This repository contains the official source code, releases, and developer tooling distributed under the Apache-2.0 license.

Verify a record offline

Generate the shipped sample records, then verify one locally with the generated issuer key set. The verification step does not fetch keys or call a remote verifier. pnpm dlx may download the CLI if it is not already cached.

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).

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

What PEAC records

A PEAC record is a signed statement about an interaction or challenge: what the issuing system reported, not an independently established fact.

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

At a high level, PEAC records can preserve:

The required Wire 0.2 payload claims are peac_version, kind, type, iss, iat, and jti. The protected JWS header also carries the required signing and type-discrimination parameters, including alg, kid, and typ. Policy, occurred_at, actor, representation, pillars, and extensions are optional or profile-dependent. The normative envelope is defined in docs/specs/WIRE-0.2.md.

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, or compliance workflows.

How it works

1. A system observes or reports an interaction
   API call, MCP tool run, agent action, gateway decision,
   payment event, or provisioning event

2. An issuer creates a signed PEAC record
   describing what that issuer reports about the interaction

3. A counterparty verifies the signature, structure, and accepted bindings
   locally, in CI, or through a self-hosted verifier, using the issuer's
   public key

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

The issuer is the entity that signs the record. It may be the system that performed the work, an observer, a gateway, an adapter, or a runtime reporting an event; those roles stay separate.

Full loop: docs/HOW-IT-WORKS.md. Artifact vocabulary (record, receipt, bundle, report): docs/ARTIFACTS.md.

What PEAC does not do

PEAC does not authorize actions, validate credentials, process payments, settle transactions, operate agents, assign trust scores, or replace observability systems.

Full boundary, compared surface by surface: docs/WHERE-IT-FITS.md. Protocol scope: docs/WHAT-PEAC-STANDARDIZES.md.

Evidence workflows

Worked, offline-verifiable examples for common evidence shapes. Each adds no new wire format, schema field, or registry entry beyond what already ships. The PEAC records below preserve issuer-reported claims. Any linked payment, timestamp, transparency, or other external proof must also be evaluated under its own verification rules and trust model.

These workflows establish signature validity and the internal consistency of the supplied evidence. They do not, by themselves, establish settlement finality, approver authority, accounting correctness, real-world completeness, or the validity of an underlying event.

Full recipe catalog: docs/SOLUTIONS/. Full example catalog: examples/README.md.

Choose your path

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

Use PEAC in code

pnpm add @peac/protocol

@peac/protocol re-exports the common crypto helpers, so a single package covers key generation, issuance, and local verification. The example below issues one concrete payment record; the same issuance and local-verification path applies to other PEAC record profiles.

import { generateKeypair, issue, verifyLocal } from '@peac/protocol';

const ISSUER = 'https://api.example.com';

async function main(): Promise<void> {
  // The issuer holds the private key; a verifier needs only the public key.
  const { privateKey, publicKey } = await generateKeypair();

  // Issue one signed record in the current Interaction Record Format.
  const { jws } = await issue({
    iss: ISSUER,
    kind: 'evidence',
    type: 'org.peacprotocol/payment',
    pillars: ['commerce'],
    extensions: {
      'org.peacprotocol/commerce': {
        payment_rail: 'x402',
        amount_minor: '1000',
        currency: 'USD',
      },
    },
    privateKey,
    kid: 'https://api.example.com/keys/1',
  });

  // Verify locally with the public key, binding the expected issuer. No network
  // request is made: the key is supplied here, not discovered remotely.
  const result = await verifyLocal(jws, publicKey, { issuer: ISSUER });

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

  console.log(`verified record from ${result.claims.iss}`);
  console.log(`kind: ${result.claims.kind}, type: ${result.claims.type}`);
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

Expected:

verified record from https://api.example.com
kind: evidence, type: org.peacprotocol/payment

For a longer walkthrough that also reads back typed extensions, see examples/minimal/ (pnpm --filter @peac/example-minimal demo). Full CLI command catalog: packages/cli/README.md.

Run repository examples

These commands are repo-local: clone the repository, install, and build first.

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

pnpm demo:all runs the start-here examples end to end. Individually:

• Minimal example: pnpm --filter @peac/example-minimal demo
• MCP gateway records: pnpm --filter @peac/example-mcp-gateway-receipts demo and pnpm --filter @peac/example-mcp-gateway-receipts demo:tamper
• Gateway decision evidence: pnpm --filter @peac/example-gateway-decision-evidence demo and pnpm --filter @peac/example-gateway-decision-evidence demo:tamper
• Provisioning lifecycle: pnpm --filter @peac/example-provisioning-lifecycle run issue and pnpm --filter @peac/example-provisioning-lifecycle run verify
• MCP server: see the @peac/mcp-server guide
• Self-hosted reference verifier: surfaces/reference-verifier/

Implementations and runtime support

PEAC is pre-1.0. Stability is defined per surface in the Stability Contract, not by this table. This README is informative; normative requirements live in the Spec Index.

Operational and enterprise review

PEAC supports audit and compliance workflows built on portable signed records. Using PEAC does not itself establish compliance with any regulation, framework, or certification.

Verification requires signature validation before relying on record claims. verifyLocal() and the documented CLI --public-key path do not silently fall back to issuer discovery or other network access. Remote key-discovery paths apply SSRF protections and bounded resource limits.

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

Protocol status and versioning

• Current format: Interaction Record Format 0.2 (interaction-record+jwt; repository shorthand: 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.

Contributing and license

Bug fixes, documentation, tests, and interoperability reports are welcome as pull requests. Changes to the wire format, schemas, registries, or public API need a design discussion first: open an issue before sending the pull request.

Apache-2.0. See LICENSE.

PEAC Protocol is open-source software published and maintained by Originary, with contributions from the community.

It is licensed under Apache-2.0 and may be independently implemented and self-hosted. Use and verification do not require an Originary-hosted service.

Docs · GitHub · Discussions