pinialt/mcp-verified-approval

# mcp-verified-approval MCP 的 verified-approval（经验证的批准）扩展参考实现——为敏感工具调用提供按调用、经 passkey 验证的人类批准机制。 ## 这是什么 MCP 服务器暴露了可供 LLM 代理自主调用的工具。对于大多数工具，现有的建议性注解（`destructiveHint`、`readOnlyHint` 等）以及由客户端渲染的确认对话框就足够了。但对于具有高风险后果的工具——如执行交易、部署基础设施、删除数据、转账——由驱动代理的同一客户端所渲染的确认对话框是不够的：同一进程可以通过编程方式消除对话框，遵从注入了“点击是”指令的提示，或者依赖用户预先授权的自动批准模式。该对话框只是一种用户体验上的设计便利，而不是一种强制执行的基元。 本仓库是一个提议的 MCP 扩展的参考实现，旨在填补这一空白。工具通过 `_meta` 注解将自身标记为需要批准；服务器发布一个挑战，其值绑定到规范化参数的哈希上；用户通过针对已注册凭证的 WebAuthn 断言来授权调用；服务器独立验证签名并拒绝参数替换。完整的规范（包括规范性要求、威胁模型和残余风险）位于 [`sep-draft/SEP-DRAFT.md`](./sep-draft/SEP-DRAFT.md) 中。 ``` sequenceDiagram participant User participant Client participant Server participant Authenticator Note over Client,Server: initialize: server declares verifiedApproval capability Note over User,Authenticator: prerequisite: at least one credential enrolled Client->>Server: tools/list Server-->>Client: tool listing with verified-approval _meta annotation Client->>Server: approval/challenge/create (toolName, arguments) Server-->>Client: challenge (nonce + actionHash, displayText, expiresAt) Client->>User: present displayText User->>Authenticator: gesture (biometric / hardware tap) Authenticator-->>Client: signed assertion bound to challenge Client->>Server: tools/call (name, arguments, _meta evidence) Server->>Server: verify signature → recompute action hash → consume challenge Server-->>Client: tool result (or structured approval error) ``` 该提案在结构上是增补性的：不带注解的工具其行为与现在完全一致，而不实现该交互流程的客户端也能正常与所有未注解的工具进行交互。 ## 状态 该 SEP 已在 [modelcontextprotocol/modelcontextprotocol#2672](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2672) 开放审查。参考实现已实现端到端工作：15 个集成测试覆盖了 §4.8 验证规则、§4.4.2 注册防御、§4.10 错误原因以及按调用交互流程。WebAuthn 断言路径已在 macOS Touch ID 以及通过 Mac → iPhone 混合传输的 iCloud Keychain 同步 passkey 上进行了硬件测试。 ## 仓库结构 ``` mcp-verified-approval/ Reference library (shared / server / client subpath exports) shared/ Types shared by the demo workspaces server/ Demo MCP server consuming the library server/test/ Integration test suite client/ Browser-based demo client sep-draft/ SEP markdown draft verification/ Per-phase verification reports docs/ Project context and design decisions ``` 位于 `mcp-verified-approval/` 的库是规范的接口层——服务器门控、客户端交互流程、共享协议词汇表，通过三个子路径导入导出。演示工作区（`server/`、`client/`、`shared/`）使用该库，针对真实的 MCP 服务器和浏览器客户端进行端到端演练。`verification/` 下的验证报告记录了 SEP 中引用的实证发现；`docs/` 包含了持续更新的设计决策日志。 ## 快速开始 需要 Node ≥ 20。 ``` git clone git@github.com:pinialt/mcp-verified-approval.git cd mcp-verified-approval npm install npm test ``` 所有 15 个测试均应通过。若要使用浏览器运行演示： ``` npm run dev ``` 这将构建该库，在端口 3030 启动演示 MCP 服务器，并在端口 5173 启动浏览器客户端。在 Safari 或 Chrome 中打开 `http://localhost:5173`，通过页面内的按钮注册一个 passkey，然后发起一笔交易。首次运行会生成一个特定于部署的服务器标识符，并将其持久化到 `server/.serverid`（已被 gitignore）；后续运行将复用该标识符。 ## 阅读顺序 适合希望深入了解该工作的人员： - **规范。** [`sep-draft/SEP-DRAFT.md`](./sep-draft/SEP-DRAFT.md) 是完整的规范。§3 构建了问题框架；§4 定义了通信格式和验证规则；§8 记录了威胁模型和残余风险。 - **规范的实现。** [`mcp-verified-approval/src/server/index.ts`](./mcp-verified-approval/src/server/index.ts) 实现了 `createApprovalGate`，这是服务器端的强制执行基元。SEP §4.8 中的十四个验证步骤与 `verifyApprovalForCall` 中的检查一一对应。 - **实证发现。** [`verification/phase-4-mitigation-1.md`](./verification/phase-4-mitigation-1.md) 记录了将验证器类别的声明从使用时保证缩小为能力过滤器的测试——这一实证观察塑造了 §4.7 和 §8.3.1。`verification/` 下的其他报告涵盖了早期的阶段。 - **集成套件。** [`server/test/`](./server/test/) 将每个测试映射到一项规范性要求：参数绑定、重放拒绝、过期挑战处理、验证器类别强制执行、签名计数器回归、注册防御、错误原因区分以及能力声明。 ## 硬件覆盖范围 WebAuthn 断言路径已在 macOS Touch ID（通过 Chrome，传输方式广播为 `["internal"]`）以及 iCloud Keychain 同步 passkey（通过 Mac → iPhone 混合传输，传输方式广播为 `["hybrid", "internal"]`）上进行了硬件测试。USB 安全密钥（例如 YubiKey 级别）、仅限 NFC 的验证器以及 Windows Hello 尚未被覆盖。传输类别过滤器会将仅限 `["internal"]` 的凭证从 `cross-platform` 策略工具中排除（无论供应商是谁）；非 Apple 硬件理论上可以工作，但尚未经过验证测试。 ## 许可证 MIT。请参阅 [LICENSE](./LICENSE)。 ## 贡献 本仓库是支持活跃中 SEP 的参考实现。欢迎通过 GitHub Issues 提交错误报告、问题和讨论。对于实质性的设计提案或规范更改，SEP PR 才是合适的场所——规范的接口层是规范本身，而不是库的 API。使实现与 SEP 保持一致的库级别修复始终是受欢迎的。

标签：CISA项目, MCP, MITM代理, Passkey, WebAuthn, 人机交互验证, 区块链/金融级安全, 多因素认证, 大模型安全, 安全助手, 密钥签名校验, 工具调用验证, 抗自动化攻击, 敏感操作授权, 智能体安全, 自动化攻击, 防止提示词注入, 零信任架构