核心用法
SettlementWitness 是一款专为 Agent 生态设计的结算收据验证工具，核心功能是本地验证 SAR v0.1 协议的签名收据。用户通过 python3 scripts/verify_receipt.py 命令即可执行验证，支持单文件验证、批量自测（--self-test）以及针对篡改收据的负面测试。验证流程包括：解析收据 JSON、使用 RFC 8785 规范重新计算规范摘要、校验 receipt_id 与摘要匹配、最后通过 Ed25519 算法验证签名有效性。工具内置公钥注册表，默认支持离线运行，仅在用户显式请求时才涉及网络操作。
验证结果以结构化 JSON 返回，包含 valid（密码学有效性）、verdict（签发者声明：PASS/FAIL/INDETERMINATE）、错误详情等字段。需要特别强调的是，valid: true 仅证明收据未被篡改且签名有效，不代表任务实际成功——verdict 字段才反映签发者对任务是否达标的正式判定。
显著优点
本地优先架构是该工具的最大亮点。核心验证逻辑完全离线执行，不依赖任何网络连接，这在网络不稳定或对数据外泄敏感的场景下极具价值。用户可以在完全隔离的环境中确认收据真伪，满足零信任安全架构的需求。
密码学严谨性体现在对标准的严格遵循：RFC 8785 JSON Canonicalization Scheme 确保摘要在不同实现间的一致性，Ed25519 提供现代、高效的椭圆曲线签名方案。相比自建摘要算法，采用标准规范显著降低了互操作性风险。
透明可审计体现在完整的自测套件和负面测试支持。用户可以通过篡改测试直观验证工具确实会拒绝无效收据，而非虚假返回成功。开源 MIT-0 许可证和清晰的代码结构（818 行/7 文件）也便于安全审计。
灵活集成能力体现在可选的远程收据签发接口。对于需要第三方背书的场景，用户可显式调用 DefaultVerifier 服务获取签名收据，再回归本地验证流程，形成"签发-验证"分离的安全模型。
潜在缺点与局限性
来源可信度限制是首要考量。项目由个人开发者（nutstrut）维护，安全认证报告将其定为 T3 级别来源，相比企业级 T1/T2 来源，长期维护承诺和社区背书相对薄弱。用户需自行承担供应链风险，建议持续关注 GitHub 仓库活跃度。
密钥管理依赖构成运营风险。本地验证依赖内置的公钥注册表，当 DefaultVerifier 轮换签名密钥时，旧版本工具将无法验证新收据。虽然可通过 SAR_KEYS_REGISTRY_PATH 环境变量手动指定新注册表，但这增加了运维复杂度，且密钥轮换通知机制尚不明确。
功能边界需清晰认知。工具明确声明不执行用户任务、不托管资金、不证明法律结算最终性。部分用户可能误解 verdict: PASS 为业务层面的担保，实际上它只是签发者的主观声明，与智能合约最终性、法律约束力无关。
可选远程功能的数据暴露。虽然远程收据签发是显式 opt-in 功能，但调用时会将 task_id、spec、output 发送至第三方服务器。对于包含敏感商业数据或隐私信息的任务，这一数据外泄路径需要纳入风险评估。
适合的目标群体
- 多 Agent 协作系统的架构师：需要验证跨 Agent 任务完成声明的真实性，防止恶意或故障 Agent 伪造完成证据
- 零信任安全实践者：追求本地可验证性，不愿将核心安全逻辑外包给远程服务
- 结算/支付 adjacent 系统的开发者：需要在最终资金释放前获得密码学层面的完成证明
- 审计与合规团队：需要可追溯、可复现的验证记录，支持证据链的完整性校验
- 离线或边缘环境部署者：网络连接不可靠或安全策略禁止外联的场景
使用风险与注意事项
性能层面：Python 依赖项（cryptography、jcs）在首次安装时需编译原生扩展，在资源受限环境可能耗时较长。建议预构建或在容器化环境中准备镜像。
依赖项风险：虽然 cryptography 和 jcs 均为成熟安全库，但任何依赖都引入供应链攻击面。建议锁定版本、定期审查 CVE、考虑使用依赖签名验证工具。
验证结果误读风险：需建立内部文档明确区分 valid（密码学有效）与 verdict（业务状态），防止运维人员将 valid: true && verdict: FAIL 误解为可继续下游处理。
密钥轮换监控：建议建立针对 DefaultVerifier 密钥轮换的监控机制（如订阅 GitHub Releases、监控 .well-known 端点变化），避免生产环境因密钥过期导致验证失败。
远程 API 可用性：虽然本地验证不依赖网络，但若业务流程包含远程收据签发环节，需评估 defaultverifier.com 的服务等级协议和故障降级策略。