7h3-protocol

<div align="center"> <img src="./docs/assets/banner.png" alt="@7h3/protocol — AIP: Sign every message. Reject every replay." width="100%"> <br/><br/> [](https://www.npmjs.com/package/@7h3/protocol) [](https://www.npmjs.com/package/@7h3/protocol-mcp) [](https://pypi.org/project/aip7h3/) [](https://crates.io/crates/aip7h3) [](https://github.com/IceMasterT/7h3-protocol-aip/tree/main/src) [](./package.json) [](./tsconfig.json) [](./LICENSE) [](./docs/VERSIONING_POLICY.md) <br/> **您协议中缺失的签名和防重放层。** <br/> </div> --- ## 为什么存在 主流的代理协议发送的消息都是未签名的： - **MCP** 使用纯粹的 JSON-RPC 2.0 —— 没有签名，没有防重放保护。参数可以在传输过程中被修改；有效的消息可以无限期地被重放。 - **A2A** 签名 *Agent Cards* 以进行域名身份验证 —— 但不是每条消息的任务流量。 AIP 正好填补了这一空白。它是一个硬化信封，您可以将其放在 **MCP** 或 **A2A** 流量周围 —— 而不是它们的竞争对手。每条消息都会被签名、限定 TTL 并在到达处理程序之前检查重放。 当代理触发实际的副作用（写入、支付、工具调用）并且您需要防篡改、防重放和可审计性时，请使用它。 --- ## 保证 | 属性 | 机制 | |---|---| | **真实性** | HMAC-SHA256（HS256）或 Ed25519 超过规范的有效载荷 —— 真正的 WebCrypto，没有手工加密 | | **确定性** | 固定密钥顺序规范化；签名在 TS / Python / Rust 中逐字节匹配 | | **防重放** | `(sender, messageId, nonce)` 唯一性窗口 + TTL / 时钟偏移强制执行 | | **多语言** | 共享的一致性固定装置集 (`conformance/aip_v0_1.json`) 证明所有三个运行时之间的对等性 | --- ## 安装 ```bash npm install @7h3/protocol ``` Python 和 Rust SDKs 分别位于 `sdk/python` (`from aip7h3 import …`) 和 `sdk/rust` (`use aip7h3::…`)。 ### MCP 服务器（适用于 Claude Code / Claude Desktop） 配套的 `@7h3/protocol-mcp` 包为您的 AI 助手安装了五个工具，用于生成密钥、密钥对和样板。 ```bash # Claude Code claude mcp add aip -- npx @7h3/protocol-mcp ``` ```json // Claude Desktop — claude_desktop_config.json { "mcpServers": { "aip": { "command": "npx", "args": ["@7h3/protocol-mcp"] } } } ``` | 工具 | 功能 | |---|---| | `aip_generate_secret` | 32 字节 HMAC 密钥 → `AIP_SECRET` | | `aip_generate_keypair` | Ed25519 密钥对 → 环境变量 | | `aip_wrap_mcp_server` | 适用于您的 MCP 服务器的即插即用样板 | | `aip_sign` | 签名测试信封（调试 / 固定装置生成） | | `aip_verify` | 验证信封的签名和形状 | --- ## 快速开始 ### HMAC（共享密钥 —— 最简单的路径） ```ts import { createEnvelope, signEnvelopeHmac, verifyEnvelopeHmac, validateEnvelope, } from '@7h3/protocol' const secret = 'shared-secret' const envelope = await signEnvelopeHmac( createEnvelope({ sender: 'planner', recipient: 'worker', intent: 'TASK', content: 'do-the-thing' }), secret, ) const diagnostics = validateEnvelope(envelope) // 形状 / TTL / 版本检查 const ok = await verifyEnvelopeHmac(envelope, secret) // 篡改 + 身份验证检查 // → 通过您的传输的重放缓存下游检查重放 ``` ### Ed25519（非对称 —— 生产推荐） > **为什么选择 Ed25519？** HMAC 是一个共享密钥 —— 任何可以验证的对等方也可以伪造。Ed25519 是非对称的：您使用私钥签名，对等方仅使用您的公钥进行验证。破坏对等方不会影响您的签名密钥。 ```ts import { generateEd25519KeypairBase64Url, createEnvelope, signEnvelopeEd25519, verifyEnvelopeEd25519, } from '@7h3/protocol' const { privateKey, publicKey } = await generateEd25519KeypairBase64Url() const envelope = await signEnvelopeEd25519( createEnvelope({ sender: 'planner', recipient: 'worker', intent: 'TASK', content: 'do-the-thing' }), privateKey, 'k1', ) const ok = await verifyEnvelopeEd25519(envelope, publicKey) ``` --- ## MCP 硬化包装 包装任何现有的 MCP 服务器或客户端 —— 处理程序签名不变： ```ts import { wrapMcpServer, wrapMcpClient, signEnvelopeEd25519 } from '@7h3/protocol' // 服务器端 const secureServer = wrapMcpServer(myMcpHandler, { selfAgentId: 'my-server', sign: (e) => signEnvelopeEd25519(e, serverPrivateKey, 'k1'), }) // 客户端 const { send } = wrapMcpClient({ selfAgentId: 'my-client', peerAgentId: 'my-server', sign: (e) => signEnvelopeEd25519(e, clientPrivateKey, 'k1'), receive: { signatureResolver: async ({ keyId }) => ({ alg: 'ED25519', publicKey: serverPublicKey }) }, }) const response = await send({ jsonrpc: '2.0', id: 1, method: 'tools/list' }, fetch) ``` 包装器强制执行签名验证之外的四个绑定： | 绑定 | 攻击被击败 | |---|---| | **接收者** | 服务器拒绝不是发送到 `selfAgentId` 的信封 —— 跨服务器中继 | | **发送者** | 客户端仅接受来自 `peerAgentId` 的响应 —— 响应伪造 | | **关联** | 客户端强制执行 `correlationId === request messageId` —— 响应替换 | | **重放** | 默认注入 `InMemoryReplayCache` —— 重放先前请求 | 演示：`npm run aip:mcp:wrap` --- ## 线上格式 三种格式 —— 根据上下文选择： | 格式 | 用例 | |---|---| | `json` | 可读，调试友好 | | `compact` | 最小化 JSON —— 在 HTTP 上更小 | | `binary` | MessagePack（魔术 `AIPB`）—— 最高吞吐量，最低解析开销 | ```ts import { encodeEnvelope, decodeEnvelope } from '@7h3/protocol' const wire = encodeEnvelope(envelope, 'binary') // Uint8Array const back = decodeEnvelope(wire) // ProtocolEnvelope ``` --- ## 分布式重放存储（Redis） 生产部署需要跨代理实例的共享重放存储： ```ts import { createRedisReplayStore, DistributedReplayCache } from '@7h3/protocol' const store = createRedisReplayStore(redisClient, { errorBehavior: 'fallback', // 在 Redis 出现故障时降级为本地存储 —— 绝不沉默 onDegraded: (err) => telemetry.error('replay-store-degraded', err), }) const replayCache = new DistributedReplayCache(store) // 将 replayCache 传递到 receiveEnvelope 或 wrapMcpServer/wrapMcpClient ``` - 原子 `SET NX PX` 保留 —— 在并发写入下不会重复处理 - `reserveMany` 批量管道 —— 高容量处理器的低开销 - `errorBehavior: 'fallback' | 'reject' | 'allow'` —— 操作员控制降级姿态 - 参见 `docs/DISTRIBUTED_REPLAY.md` --- ## 全局密钥吊销 ```ts import { createRedisRevocationStore, withRevocationCheck } from '@7h3/protocol' const revocationStore = createRedisRevocationStore(redisClient) // 默认关闭故障 const secureResolver = withRevocationCheck(mySignatureResolver, revocationStore) // 吊销密钥 → 解析器返回 undefined → 验证失败 ``` - 缓存读取（默认 5 秒 TTL）—— 验证热路径上的低开销 - 默认关闭故障：Redis 出现故障 → 拒绝，而不允许 - 参见 `docs/KEY_REVOCATION.md` --- ## 传输适配器 零个新运行时依赖 —— 仅限 Node 内置和全局 `fetch`: ```ts import { serveMcpOverStdio, createStdioMcpClient } from '@7h3/protocol' import { createHttpMcpHandler, createHttpMcpClient } from '@7h3/protocol' ``` | 适配器 | 备注 | |---|---| | `serveMcpOverStdio` + `createStdioMcpClient` | 以换行符分隔；有序顺序链防止响应交错 | | `createHttpMcpHandler` + `createHttpMcpClient` | `node:http` 处理程序 + `fetch` 客户端；支持 `binary` 线上格式 | --- ## 框架适配器 LangChain、LlamaIndex 和 JSON-RPC 桥适配器包装 `AipAgentAdapter` 以在 AIP 信封和框架原生消息类型之间进行转换： ```ts import { LangChainAipAdapter, LlamaIndexAipAdapter, JsonRpcBridge } from '@7h3/protocol' ``` --- ## 策略和遥测 运行时策略控制传输行为、重试、速率限制和安全不变性 —— 从 `AI_RUNTIME_POLICY.yaml` 或内联加载： ```ts import { loadRuntimePolicy, validateRuntimePolicy, PolicyEnforcer } from '@7h3/protocol' const policy = await loadRuntimePolicy({ path: './AI_RUNTIME_POLICY.yaml' }) const enforcer = new PolicyEnforcer(policy) ``` 参见 `docs/TELEMETRY.md`, `docs/AI_DECISION_CARD.md`, `docs/OPERATORS.md`. --- ## 多语言对等 所有三个 SDK 都由位于 `conformance/aip_v0_1.json` 的同一一致性固定装置集驱动。签名针对所有三个运行时中的已知向量进行验证： ```bash npm test # TypeScript（131 测试 / 23 个文件） npm run conformance:python # Python unittest npm run conformance:rust # Rust cargo test（7 测试） ``` --- ## 状态 **版本：0.1.2** · 线上协议：`aip/0.1` | 什么 | 状态 | |---|---| | 核心测试套件 | ✅ 131 测试 / 23 个文件 —— 全部绿色 | | 密码学 | ✅ 真正的 WebCrypto —— HMAC-SHA256 + Ed25519（无手工加密） | | 确定性规范化 | ✅ 固定密钥顺序；字节相同于所有运行时 | | TS/Python/Rust 对等 | ✅ 共享一致性固定装置；全部通过 | | 分布式重放（Redis） | ✅ 原子 `SET NX PX`；批量管道；优雅降级 | | 全局密钥吊销（Redis） | ✅ 关闭失败；缓存读取；故障时备用服务 | | MCP 硬化包装 | ✅ 4 个绑定；全部独立测试 | | 基于属性的模糊测试 | ✅ 通过 fast-check（线路解码器，规范化，重放）测试 8 个属性 | | Redis 集成测试 | ✅ 自动跳过如果没有服务器存在 —— 没有假阳性 | | 正式模糊活动 | ✅ TypeScript mutation 套件运行干净（50k/20k 轮，0 次崩溃）；Rust 目标构建并运行（4.9M 次迭代，`canonicalize_envelope`/`decode_envelope` 中无恐慌）—— 参见 [`docs/FUZZ_CAMPAIGN.md`](./docs/FUZZ_CAMPAIGN.md) | | 独立安全审计 | ⚠️ 尚未由外部审查员执行 —— 内部 AI 辅助审查于 2026-06-05 完成，2 个错误被发现并修复（参见 [`docs/SECURITY_REVIEW_2026-06-05.md`](./docs/SECURITY_REVIEW_2026-06-05.md)）；加密原语是标准 WebCrypto；解析/重放/规范化逻辑仍未被合格的第三方审计 | | Python Ed25519 | ✅ 纯 Python 备用方案 —— 无外部包依赖；按顺序尝试 `cryptography` → `PyNaCl` → 纯 Python | | Rust crates.io 发布 | ✅ 元数据完整；`cargo publish --dry-run` 通过 —— 使用 `cargo publish` 发布时准备就绪 | | Redis HA | ✅ Sentinel、Cluster 和 Upstash 适配器模式在 [`docs/DISTRIBUTED_REPLAY.md`](./docs/DISTRIBUTED_REPLAY.md) 中有文档记录 | --- ## 文档 | 文档 | 内容 | |---|---| | [`docs/THREAT_MODEL.md`](./docs/THREAT_MODEL.md) | 完整的威胁覆盖矩阵 | | [`docs/MCP_WRAPPER.md`](./docs/MCP_WRAPPER.md) | MCP 包装器用法、传输示例、HMAC 与 Ed25519 比较 | | [`docs/DISTRIBUTED_REPLAY.md`](./docs/DISTRIBUTED_REPLAY.md) | Redis 存储设置、`errorBehavior` 表、操作指南 | | [`docs/KEY_REVOCATION.md`](./docs/KEY_REVOCATION.md) | 吊销存储设置、缓存 TTL 调整 | | [`docs/KEY_MANAGEMENT_POLICY.md`](./docs/KEY_MANAGEMENT_POLICY.md) | 密钥生命周期和轮换策略 | | [`docs/CLOCK_SKEW_POLICY.md`](./docs/CLOCK_SKEW_POLICY.md) | 时钟同步要求 | | [`docs/VERSIONING_POLICY.md`](./docs/VERSIONING_POLICY.md) | 线上冻结保证、semver 策略 | | [`docs/MIGRATION_GUIDE.md`](./docs/MIGRATION_GUIDE.md) | 变更升级路径 | | [`docs/OPERATORS.md`](./docs/OPERATORS.md) | 部署和运维参考 | | [`docs/TELEMETRY.md`](./docs/TELEMETRY.md) | 遥测钩子和可观察性 | | [`docs/SECURITY_REVIEW_2026-06-05.md`](./docs/SECURITY_REVIEW_2026-06-05.md) | AI 辅助内部安全审查 —— 发现、修复、积极发现 | | [`docs/PROJECT_EXAMINATION_2026-05-31.md`](./docs/PROJECT_EXAMINATION_2026-05-31.md) | 独立审查 —— 验证 vs 断言 | | [`CHANGELOG.md`](./CHANGELOG.md) | 完整的版本历史 | --- ## 安全 通过 [`SECURITY.md`](./SECURITY.md) 中的协调披露过程报告漏洞。 **不要为安全发现开启公共问题。** 48 小时确认 SLA；14 天关键补丁 SLA。 加密原语是标准（WebCrypto Ed25519 / HMAC-SHA256）。信封解析、规范化和重放缓存逻辑未经过正式审计。未进行独立安全审计。相应地在高风险部署中进行处理。 --- ## 贡献 参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md) —— 测试命令、线路冻结策略、一致性固定装置更新要求和 PR 工作流程。 ## 治理 参见 [`GOVERNANCE.md`](./GOVERNANCE.md) —— 单一维护者阶段、决策过程、共同维护路径（LF 最小可行治理风格）。 ## 许可证 MIT