peacprotocol/peac
GitHub: peacprotocol/peac
PEAC 是一个为代理、API 与跨运行时交互提供可验证签名记录与便携式审计标准的开源协议。
Stars: 11 | Forks: 7
# PEAC
PEAC 是一个用于代理、工具、API 和跨运行时系统的可验证交互记录的开源标准。发布机器可读条款，返回签名记录，并离线验证：跨组织边界的便携式审计记录，无需替换身份验证、支付通道或可观测性。
**面向** 需要跨边界传递签名记录的 API 提供者、MCP 工具宿主、代理操作员、平台和审计员。
## 工作原理
```
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
```
有治理的 HTTP 响应示例：
```
HTTP/1.1 200 OK
PEAC-Receipt: eyJhbGciOiJFZERTQSIsInR5cCI6ImludGVyYWN0aW9uLXJlY29yZCtqd3QifQ...
Link: ; rel="issuer"
```
## 快速开始
**要求：** Node 24（已测试）；Node 22+（兼容）。[Go 1.26+](sdks/go/) 和 [Python 3.12+](examples/python/) 也支持。
### 验证收据
```
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);
}
```
或从命令行：
```
peac verify 'eyJhbGciOiJFZERTQSIsInR5cCI6ImludGVyYWN0aW9uLXJlY29yZCtqd3QifQ...'
```
### 发行收据
```
import { generateKeypair } from '@peac/crypto';
import { issue } from '@peac/protocol';
const { privateKey, publicKey } = await generateKeypair();
const { jws } = await issue({
iss: 'https://api.example.com',
kind: 'evidence',
type: 'org.peacprotocol/access-decision',
pillars: ['access'],
extensions: {
'org.peacprotocol/access': {
resource: 'https://api.example.com/inference/v1',
action: 'execute',
decision: 'allow',
},
},
privateKey,
kid: 'key-2026-03',
});
// Return jws in the PEAC-Receipt header
```
### 运行示例
```
pnpm install && pnpm build
pnpm --filter @peac/example-minimal demo
```
参见 [examples/minimal/](examples/minimal/) 获取完整源代码。如需 HTTP/REST、Express 中间件和 Go 示例，请参见 [docs/README_LONG.md](docs/README_LONG.md)。
## 常见用例
PEAC 在日志不足以应对的场景中最有价值：支付、跨边界验证、审计、争议审查以及多代理工作流。
- **代理商务与支付：** 证明在 paymentauth、x402、Agentic Commerce Protocol (ACP)、Stripe SPT 等支付通道及其他商务流程中提供、挑战、支付或结算的内容。参见 [paymentauth Kit](integrator-kits/paymentauth/README.md)、[ACP Kit](integrator-kits/acp/README.md)、[x402 Kit](integrator-kits/x402/README.md)。
- **审计与争议审查：** 保存跨组织边界有效的签名证据，而不仅限于本地日志。参见 [治理映射](docs/governance/)。
- **MCP 工具与 API：** 验证、发行并携带工具调用、API 响应和自动化操作的签名收据。参见 [MCP 集成套件](integrator-kits/mcp/README.md)。
- **代理到代理工作流：** 在 A2A 任务/状态转换和多代理链中携带可验证收据。参见 [A2A 集成套件](integrator-kits/a2a/README.md)。
- **运行时治理：** 将来自托管运行时（Microsoft AGT、Claude Managed Agents、OpenAI ACP）的治理决策记录为便携式签名记录。参见 [`@peac/adapter-runtime-governance`](packages/adapters/runtime-governance/)。
## 从这里开始
**[完整决策树与快速入门及集成套件](docs/START_HERE.md)**
- **我运行一个 API**：[API 提供者快速入门](docs/guides/quickstart-api-provider.md)（5 分钟，Express 中间件）
- **我运行一个 MCP 服务器**：[MCP 集成套件](integrator-kits/mcp/README.md) 或 `npx -y @peac/mcp-server`
- **我想要验证一个收据**：[代理操作员快速入门](docs/guides/quickstart-agent-operator.md)（5 分钟）
- **我构建 A2A 代理**：[A2A 集成套件](integrator-kits/a2a/README.md)
更多路径：[Go SDK](sdks/go/) | [Python 示例](examples/python/) | [paymentauth Kit](integrator-kits/paymentauth/README.md) | [ACP Kit](integrator-kits/acp/README.md) | [x402 Kit](integrator-kits/x402/README.md) | [治理映射](docs/governance/)
## 定位
| 现有系统 | PEAC 新增能力 |
| ----------------------------------------------- | ---------------------------------------------------------------- |
| **日志** | 跨组织边界的便携式签名记录 |
| **OpenTelemetry** | 与跟踪相关联的签名记录 |
| **MCP / A2A** | 与工具调用和代理交换一同携带的签名收据 |
| **AP2 / ACP (Agentic Commerce Protocol) / UCP** | 跨商务协议的费用与结果签名记录 |
| **paymentauth** | HTTP 支付身份验证挑战生成的收据 |
| **x402** | 结算记录映射与离线验证 |
| **Stripe SPT / 支付通道** | 可验证的委派与结算引用 |
| **运行时治理 (AGT、Claude MA、ACP)** | 跨边界的治理决策便携式签名记录 |
**你的堆栈中会发生变化：** 保留身份验证、保留支付、保留可观测性。添加 `/.well-known/peac.txt` 并在受治理的响应中返回 `PEAC-Receipt`。
## 工件外观
| 工件 | 描述 |
| ----------------------- | --------------------------------------------------------- |
| `/.well-known/peac.txt` | 机器可读条款 |
| `PEAC-Receipt` | 头或传输元数据中的签名交互证明 |
| `verifyLocal()` | 密钥可用时的本地验证 |
| `peac-bundle/0.1` | 便携式审计/争议包 |
## CLI
```
peac verify 'eyJhbGc...' # Verify a receipt
peac conformance run # Run conformance tests
peac reconcile a.bundle b.bundle # Merge and diff evidence bundles
peac policy init # Create peac-policy.yaml
peac policy validate policy.yaml # Validate policy syntax
peac policy generate policy.yaml # Compile to deployment artifacts
```
参见 [packages/cli/README.md](packages/cli/README.md) 获取完整命令参考。
## 版本管理
- **当前稳定版：** 交互记录格式 (`interaction-record+jwt`)
- **遗留版本：** 线格式 0.1 (`peac-receipt/0.1`) 已冻结；`verifyLocal()` 返回 `E_UNSUPPORTED_WIRE_VERSION`
参见 [docs/specs/VERSIONING.md](docs/specs/VERSIONING.md) 获取完整版本规范。
## 安全性
- 使用 JWS 签名验证后再信任任何收据声明
- 密钥发现通过 `/.well-known/peac-issuer.json` JWKS 并具备 SSRF 防护
- 内核约束在发行和验证时强制执行（失败关闭）
- 离线验证无静默网络回退
- 错误映射为 RFC 9457 问题详情
参见 [SECURITY.md](.github/SECURITY.md) 和 [docs/specs/PROTOCOL-BEHAVIOR.md](docs/specs/PROTOCOL-BEHAVIOR.md)。
## 文档
| 文档 | 目的 |
| -------------------------------------------------------------------- | ------------------------------------------------- |
| [规范索引](docs/SPEC_INDEX.md) | 规范性规格 |
| [交互记录规范](docs/specs/WIRE-0.2.md) | 收据信封、类型与扩展 |
| [架构](docs/ARCHITECTURE.md) | 内核优先设计 |
| [内核约束](docs/specs/KERNEL-CONSTRAINTS.md) | 在发行与验证时强制执行的结构限制 |
| [策略套件快速入门](docs/policy-kit/quickstart.md) | 策略编写指南 |
| [集成配置文件](docs/profiles/) | 集成配置文件（Stripe x402 等） |
| [证据载体契约](docs/specs/EVIDENCE-CARRIER-CONTRACT.md) | 传输中载体放置规则 |
| [开发者指南](docs/README_LONG.md) | 包目录、集成示例与层映射 |
## 实现
- **TypeScript**（本仓库）：发行、验证、命令行界面、中间件
- **Go**：[sdks/go/](sdks/go/) 发行与验证
- **MCP**：[MCP 服务器](packages/mcp-server/) 证据发射与验证工具
- **A2A**：[A2A 载体映射](packages/mappings/a2a/) 元数据载体、OAuth PKCE 身份面
- **gRPC**：[gRPC 传输](packages/transport/grpc/) HTTP/2 元数据绑定的载体适配器
- **DID**：[DID 解析](packages/adapters/did/) did:key 与 did:web 解析器（带缓存）
- **Express**：[Express 中间件](packages/middleware-express/) 收据中间件
- **x402**：[x402 适配器](packages/adapters/x402/) 支付证据适配器（V1 与 V2）
- **运行时治理**：[运行时治理适配器](packages/adapters/runtime-governance/ 记录来自 AGT 及其他运行时的决策
- **托管代理**：[托管代理适配器](packages/adapters/managed-agents/) 会话生命周期记录
- **供应链**：[in-toto](packages/mappings/intoto/) 与 [SLSA](packages/mappings/slsa/) 溯源映射
构建实现？[提一个议题](https://github.com/peacprotocol/peac/issues/new)。
## 贡献与许可
欢迎贡献。如需实质性变更，请先开议题。参见 [docs/SPEC_INDEX.md](docs/SPEC_INDEX.md) 获取规范性规格，以及 [docs/CI_BEHAVIOR.md](docs/CI_BEHAVIOR.md) 获取 CI 指南。
Apache-2.0。参见 [LICENSE](LICENSE)。
PEAC 协议是一个由 Originary 和社区贡献者共同维护的开源项目。
[文档](https://www.peacprotocol.org) | [GitHub](https://github.com/peacprotocol/peac) | [Originary](https://www.originary.xyz) | [讨论](https://github.com/peacprotocol/peac/discussions)
标签：API安全, CVE, GNU通用公共许可证, Go, HTTP响应头, JSON输出, JWS, MCP工具主机, Node.js, PEAC-Receipt, Python, Ruby工具, SEO: PEAC协议, SEO: 便携式审计, SEO: 可验证交互, .well-known端点, 代理操作, 便携式审计, 公钥验证, 可验证交互记录, 审计日志, 开放标准, 授权记录, 数字签名, 无后门, 日志审计, 离线验证, 签发者元数据, 组织边界审计, 访问决策, 证据类型, 跨运行时系统, 逆向工具