在 protect-mcp 中离线验证 Ed25519 签名收据:`/verify-receipt` 命令实战指南
发布时间:2026/9/11 20:24:49来源:尧图网络
在 protect-mcp 中离线验证 Ed25519 签名收据/verify-receipt命令实战指南【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents/verify-receipt是 protect-mcp 插件提供的单文件签名收据验证命令用于对每一次 Claude Code 工具调用产生的 Ed25519 签名决策收据进行完全离线的真实性校验退出码 0 表示有效、1 表示被篡改、2 表示结构畸形。读完本文你将掌握该命令的完整调用方式、三层退出码的精确语义、收据 JSON 的字段结构与 JCS 规范化原理并学会结合仓库内的测试夹具与链式审计命令/audit-chain构建一套可复现的收据完整性验证工作流。命令定位为何需要离线验证protect-mcp 是当前仓库中的一个 Claude Code 插件核心机制是每一条工具调用先经过 Cedar 策略评估每一次 allow/deny 决策都使用 Ed25519 签名生成防篡改收据。其工作流由 hooks/hooks.json 中的两个钩子驱动PreToolUse钩子调用npx protect-mcp evaluate完成 Cedar 策略评估PostToolUse钩子调用npx protect-mcp sign对决策结果签名并写入./receipts/timestamp.json。/verify-receipt正是与这套签名机制配对的校验端。它的设计目标见 命令文档 与 插件 README是完全离线验证过程只使用veritasacta/verify这一 npm 包不发起任何网络请求不查询厂商不依赖任何 vendor lookup不需要账号或云端服务不信任运营方任何拿到收据文件的第三方都能独立验证真实性支持在气隙air-gapped环境运行。这意味着收据的真伪不再依赖签名者自证而是任何验者都可以用公开算法独立复核。命令用法在 Claude Code 中通过斜杠命令调用参数为收据文件的相对或绝对路径/verify-receipt ./receipts/2026-04-15T10-30-00Z.json./receipts/是PostToolUse钩子默认的收据输出目录对应hooks.json中${PROTECT_MCP_RECEIPTS:-./receipts/}的默认值文件按时间戳命名。也可以传入任意位置的.json文件命令对路径本身没有限制。命令内部执行流程/verify-receipt在底层是一段按顺序执行 6 个步骤的验证管线读取收据 JSON 文件将指定路径的收据读入内存校验结构检查必需字段是否存在、类型是否正确这一步对应退出码 2 的判定依据提取公钥与签名从public_key与signature字段取出验签材料重建规范形式对签名覆盖的所有其他字段执行 JCSRFC 8785规范化得到确定的字节序列验证 Ed25519 签名用公钥对规范字节做 Ed25519RFC 8032签名验算报告结果根据结果输出对应文案并以相应退出码结束。其中第 4 步是整条链路正确性的关键JSON 对象在序列化时字段顺序并不确定同样的语义内容可能产生不同字节流导致同一份数据签不出、验不过。JCS 通过字典序排序对象键并规范化数值表示保证同一份 JSON 数据永远得到同一串字节签名才具有可复现性。底层实现一条命令完成验证命令的实现极其简洁直接调用官方验证 CLInpx veritasacta/verify $1其中$1即用户提供的收据路径。veritasacta/verify会内部完成上述 6 步流程并通过退出码向调用方Bash 工具返回验证结论。npx首次运行时会从 npm 拉取该包之后可离线复用如果希望完全离线分发可以预先将包纳入本地依赖。退出码语义与应对动作验证结果完全由退出码承载这是/verify-receipt的契约核心退出码含义应向用户报告0收据有效签名验证通过Verified. Receipt authentic.收据真实可信1签名不匹配——收据被篡改TAMPERED. Signature does not match payload.签名与载荷不符2收据结构畸形Malformed. Missing required fields or invalid structure.缺少必需字段或结构无效该退出码约定不仅在命令文档中定义也被仓库的测试体系作为断言基准见 test/README.md 中的 8 项往返测试场景表其中第 7、8 项分别断言合法收据被veritasacta/verify接受退出码 0与被篡改的收据被拒绝退出码 1。面向用户的结果呈现命令在 Bash 工具中执行后Agent 需要按三种情况向用户输出格式化结果。收据有效时Verified ✓ Receipt: rec_8f92a3b1 Tool: Bash Decision: allow (policy: autoresearch-safe) Signed at: 2026-04-15T10:30:00.000Z Signer: 4437ca56815c0516... Chain link: parentrec_3d1ab7c2 ✓展示内容包括收据 ID、被审计的工具名、决策结果含策略名、签名时间、签名者公钥前缀以及链式链接是否完整。收据被篡改时TAMPERED ✗ The signature does not match the payload. This receipt has been modified since it was signed. Receipt ID: rec_8f92a3b1 Expected signer: 4437ca56815c0516... Possible causes: - A field was edited after signing (most common) - The signature was copied from a different receipt - The public key was replaced Compare this receipt against a known-good copy to identify the altered field.此时应向用户提示三类最可能的篡改原因并建议与已知良好的副本对比以定位被改动的字段。仓库的测试正是围绕这一点设计的见 test/README.md 第 8 项关键回归守卫——翻转已签名收据中的decision字段后Ed25519 签名必须失效veritasacta/verify必须返回 1 而非 0。收据结构畸形时MALFORMED ✗ The file is not a valid Veritas Acta receipt. Missing or invalid fields: list the specific structural issues A valid receipt must include: receipt_id, receipt_version, issuer_id, event_time, tool_name, decision, public_key, signature.畸形意味着文件根本不是一份合法的 Veritas Acta 收据可能是签名端 bug也可能是伪造者并不了解该格式。报告时应具体列出缺失或类型错误的字段。收据格式字段级拆解一份合法收据的字段集合定义于 agents/receipt-verifier.md{ receipt_id: rec_hash, receipt_version: 1.0, issuer_id: string, event_time: ISO 8601 UTC, tool_name: string, decision: allow | deny, policy_id: string, policy_digest: sha256:hex, input_hash: sha256:hex, parent_receipt_id: rec_hash | null, public_key: hex 64 chars, signature: hex 128 chars }字段要点public_key为 64 个十六进制字符32 字节 Ed25519 公钥signature为 128 个十六进制字符64 字节签名input_hash、policy_digest使用 SHA-256 内容寻址用于将工具输入与所用策略绑定进签名parent_receipt_id指向链上一条收据是哈希链审计的链接字段创世收据为null。仓库同时提供了一份与draft-farley-acta-signed-receipts草案对齐的 JSON Schema 校验文件 test/expected/receipt-schema.json其中定义了 v2 信封结构顶层必须包含v固定为整数 2、typedecision_receipt或gateway_restraint、algorithm固定为ed25519、kid、issuer、issued_at、payload至少含tool与decisiondecision取值限定为allow/deny与signature。这从实现侧印证了签名覆盖整个决策载荷的设计决策事实集中在payload中作为一个整体被签名。验证原理从密码学原语到审计链agents/receipt-verifier.md 给出了验证环节依赖的三类原语及其直觉理解Ed25519RFC 8032Edwards 曲线数字签名32 字节公钥 64 字节签名确定性算法、性能高、安全模型成熟。它好比信封上的火漆封印——任何人可查看封印并核对是否出自发件人信封一旦被拆动封印即破裂。JCSRFC 8785JSON Canonicalization Scheme字典序排序对象键、产出确定性字节序列。如同封口前先把词条按字母序排好使封印图案可预期。SHA-256用于内容寻址与链式链接如同账本上的编号页码——有人撕掉一页编号就会出现跳号。单收据验证的完整流程是解析 JSON → 提取public_key与signature→ 对签名覆盖的全部其他字段做 JCS 规范化 → 用公钥验证规范字节上的 Ed25519 签名 → 若通过再沿parent_receipt_id回溯校验整条链的完整性。值得注意的是从源码结构看当前仓库的验证工具链veritasacta/verify已将 JCS 规范化与 Ed25519 验算封装为npx veritasacta/verify path的单命令调用因此/verify-receipt无需自行实现密码学逻辑。从单收据到整链审计与/audit-chain配合/verify-receipt只验证一份收据若要审计完整审计轨迹应使用 commands/audit-chain.md 中的/audit-chain命令。它支持三种形态/audit-chain # 校验 ./receipts/ 下全部收据 /audit-chain --last 50 # 仅校验最近 50 条 /audit-chain --dir /var/log/receipts # 指定其他目录其内部实现为列出目录下全部*.json→ 按event_time排序建立时间序 → 逐条独立验签 → 核对每条收据的parent_receipt_id与上一条receipt_id是否一致。链式链接检查可通过--chain标志交给veritasacta/verify批量完成npx veritasacta/verify --chain $RECEIPT_DIR/*.json两者的分工是/verify-receipt回答这份收据本身真不真/audit-chain回答整条审计轨迹有没有被插入、删除、分叉。结合 agents/receipt-verifier.md 的诊断指引常见的链式失败可归因于三类攻击收据被插入两笔合法收据之间多了一条、收据被删除链中出现断点、链被分叉后只保留了某一分支。用仓库测试验证命令契约仓库为验证命令的契约提供了可直接运行的回归测试见 plugins/protect-mcp/test 目录test/fixtures/test-policy.cedar供测试使用的 Cedar 策略覆盖 Read 放行、安全 Bash 命令放行、rm -rf/dd/mkfs/shred等破坏性命令禁止、无作用域 Write/Edit 禁止test/fixtures/pretool-allow-read.json、pretool-deny-bash-destructive.json等夹具模拟 PreToolUse 输入test/README.md定义 8 项往返测试完整覆盖 evaluate → sign → verify 闭环其中第 58 项直接检验签名与验签链路签名产出收据文件、收据符合 Schema、veritasacta/verify接受合法收据、篡改收据被拒绝test/run-tests.sh全量往返需 node ≥ 18、npx、python3与 test/verify-fixtures.sh仅静态校验只需 python3适合离线 CI。在本地验证veritasacta/verify的行为时可以直接对测试产出的收据执行npx veritasacta/verify receipts/2026-04-15T10-30-00Z.json退出码 0 / 1 / 2 即对应上述有效 / 篡改 / 畸形三种结论。常见问题与排查要点退出码 1签名不匹配收据在签名后被修改过。优先与已知良好副本做逐字段对比定位改动也需考虑签名是否从其他收据复制而来、公钥是否被替换。退出码 2结构畸形缺少必需字段或类型错误。按本文收据格式一节的 12 个字段逐一核对也可用 test/expected/receipt-schema.json 做 Schema 校验。链式断裂使用/audit-chain定位断点后检查断点处的parent_receipt_id是否指向一条存在的收据判断是插入、删除还是签名端引用了错误的父引用。批量场景需要一次校验多个收据时veritasacta/verify支持接收多个文件参数如npx veritasacta/verify receipts/*.json/audit-chain即基于此能力实现整链扫描。参考资源仓库内命令文档plugins/protect-mcp/commands/verify-receipt.md链式审计命令plugins/protect-mcp/commands/audit-chain.md验证专家 Agent收据格式与故障诊断plugins/protect-mcp/agents/receipt-verifier.mdCedar 策略专家 Agentplugins/protect-mcp/agents/policy-enforcer.md插件总览与安装方式plugins/protect-mcp/README.md钩子配置签名端plugins/protect-mcp/hooks/hooks.json测试与 Schemaplugins/protect-mcp/test/README.md、plugins/protect-mcp/test/expected/receipt-schema.json相关标准依次为 RFC 8032Ed25519、RFC 8785JCS以及 IETF Internet-Draftdraft-farley-acta-signed-receipts收据格式规范可在标准文档站点查阅原文。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
网站建设高端定制企业官网