convez.ai
MCP ServerSegurançaIntermediário
peacprotocol

PEAC Protocol - Registros de Ações Assinados

peacprotocol/peac

Registre e verifique ações de IA com assinaturas portáveis entre sistemas

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que registra ações automatizadas de agentes IA, APIs e gateways como registros assinados e portáveis. Permite que terceiros verifiquem eventos (chamadas API, execuções de ferramentas MCP, decisões de gateway, transações) sem depender de logs privados ou afirmações não verificáveis, criando auditoria criptográfica entre limites de sistema.

Instalação

$npx convez-ai peacprotocol/peac

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
15
Forks
7
Acompanhando
3
Saúde
87%
Último commit
há 1 semana
Versão
v0.16.5
Issues abertas
34
Contribuidores
2

Casos de uso

  • Auditoria de ações de agentes IA em múltiplos sistemas
  • Verificação de chamadas API sem confiar em logs privados
  • Rastreamento criptográfico de decisões de gateway e provisioning
  • Compliance e conformidade regulatória para automações
  • Prova verificável de eventos de pagamento e transações

Veredito

PEAC resolve um problema legítimo: auditoria verificável de ações automatizadas sem depender da confiança em logs internos. Bem arquitetado para fluxos de integração multi-party e conformidade, mas tem curva de aprendizado moderada por envolver conceitos criptográficos. Recomendado para sistemas que precisam de auditoria confiável entre limites de confiança.

README

A tradução para o português deste README ainda está na fila.

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.

License: Apache 2.0 Latest Release npm downloads CI Status

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.

EventFamiliar surfacesExample record
API callStripe-style APIs, Cloudflare Workers, Vercel functions, internal HTTP servicesrequest, response, usage, access decision, policy-visible outcome
MCP tool runMCP servers, Smithery-listed tools, internal MCP serverstool input/output reference, tool result, issuer, timestamp, signature
Agent actionA2A handoffs, agent-framework steps, Microsoft AGT-style runtime eventsaction invoked, delegated, approved, denied, cancelled, or timed out
Gateway decisionCloudflare, Portkey, Kong, API gateways, AI gatewaysaccess, routing, export, or boundary decision reported by a gateway
Payment eventx402, paymentauth / MPP, ACP, AP2-style commerce flowspayment request, authorization, settlement observation, mandate, dispute context
Provisioning eventStripe Projects-style provider setup, Vercel deployments, GitHub Actions, Terraform-managed resourcescatalog, provider link, account, credential, budget, subscription, domain, deployment, or resource lifecycle event

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.

FieldMeaning
Factswhat the producing system reported happened
Policy or contextthe terms, policy, protocol, or configuration context that applied
Resultallowed, denied, completed, failed, observed, settled, disputed, or another profile-specific outcome
Timewhen the interaction was recorded
Issuerwhich service, runtime, gateway, or agent system issued the record
Signaturea verifiable signature over the record

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

If you...PEAC helps you...Start here
Run an API or metered serviceissue signed records for requests, responses, usage, and policy-visible outcomesAPI Provider Quickstart
Build MCP tools or agent workflowsattach records to tool runs, command execution, handoffs, lifecycle events, and agent actionsMCP Integration Kit or npx -y @peac/mcp-server
Build payment, gateway, or commerce flowspreserve signed evidence around access, payment, settlement, mandate, gateway, and dispute events without operating the payment systemMCP gateway records or Commerce evidence bundle
Track provisioning or resource lifecycle eventsrecord catalog, provider-link, account, credential, budget, subscription, domain, deployment, and resource eventsProvisioning lifecycle records
Need audit or review evidenceexport portable records and bundles that can be referenced beside logs, traces, SIEMs, reports, and audit repositoriesWhere PEAC fits
Need to verify a recordverify a signed PEAC record with the issuer's public key or a self-hosted verifierAgent Operator Quickstart

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

Quickstart: verify one record

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.

SurfaceWhat PEAC adds
APIs and HTTP servicessigned records for requests, responses, usage, and policy-visible outcomes
MCP tools and agent workflowsrecords for tool runs, command execution, handoffs, lifecycle events, and agent actions
Gateway and commerce systemsrecords for access, payment, settlement, mandate, gateway, export, and dispute events
Provisioning systemsrecords for provider links, accounts, credentials, budgets, subscriptions, domains, deployments, and resources
Runtime and evaluation systemsportable observations from local runtime, policy, evaluation, and control systems
Observability and audit systemsverifiable records that complement logs, traces, SIEMs, reports, bundles, and audit repositories

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.

NeedRead
Supported versions and disclosure processSECURITY.md
Measured local verification baselinesdocs/SLO.md
Stability classes and archived surfacesdocs/STABILITY-CONTRACT.md
Compatibility and deprecation statusdocs/COMPATIBILITY_MATRIX.md
External standards referencesdocs/STANDARDS_LEDGER.md
Release-line invariant snapshotsdocs/baselines/

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/:

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:
    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.
  • Run the minimal example: pnpm --filter @peac/example-minimal demo.
  • Run the MCP gateway records example:
    pnpm --filter @peac/example-mcp-gateway-receipts demo
    pnpm --filter @peac/example-mcp-gateway-receipts demo:tamper
    
  • Run the provisioning lifecycle example:
    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

SurfaceWhere
TypeScript issuance and verification@peac/protocol
CLI and local tools@peac/cli
MCP server@peac/mcp-server
HTTP middleware and Go supportpackages/middleware-express/, sdks/go/
Commerce, runtime, provenance, and protocol mappingspackages/mappings/, packages/adapters/
Self-hostable reference verifierapps/api/, surfaces/reference-verifier/
Examples and recipesexamples/, docs/SOLUTIONS/

Extended package catalog: docs/README_LONG.md.

Artifacts

ArtifactRole
/.well-known/peac.txtMachine-readable terms
PEAC-ReceiptHTTP response header carrying a signed interaction record
verifyLocal()Offline verification once issuer keys are available
peac-bundle/0.1Portable 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 a records layer, not a runtime control plane. It records what another system attested 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

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

Ver o original no GitHub

Bom para

Relacionados