AgentMesh Wire Protocol v1.0 全解析:面向 AI Agent 的端到端加密消息协议

原创2026-09-18 18:52:271,926 阅读
文章标签:人工智能AI 安全治理可信 AI策略引擎认证鉴权身份认证Agent 沙箱零信任可观测性安全治理

AgentMesh Wire Protocol v1.0 全解析:面向 AI Agent 的端到端加密消息协议

本篇文章基于 docs/specs/AGENTMESH-WIRE-1.0.md 展开,并结合 Agent Governance Toolkit 仓库中 Python / TypeScript SDK 的源码实现进行纵深解读。读完本文,你将掌握:AgentMesh 的 DID 身份模型与密钥体系、X3DH 密钥协商与 Double Ratchet 双棘轮加密的完整参数与状态机、JSON 帧结构与 KNOCK 意图握手协议、Registry/Relay 服务的设计、Ed25519-Timestamp 认证与治理集成方式,以及协议版本化与安全模型。无论你是要在 Python、TypeScript、Rust、.NET 还是 Go 中实现 AgentMesh 兼容客户端,本文都能作为一份可直接对照规范的实战指南。

AgentMesh Wire Protocol v1.0 是 Agent Governance Toolkit(AGT)为 AI Agent 之间端到端加密消息传输定义的线路协议规范。它解决的是多智能体系统中最棘手的问题之一:两个自治 Agent 如何在不可信的传输链路上建立加密会话、交换消息,同时让治理层(策略引擎、信任评分、审计日志)在加解密之前完成"允许/拒绝"决策。本规范覆盖 1:1 点对点消息,1:N 群组消息明确留待 v2 使用 MLS(RFC 9420)实现。

1. 协议定位:传输层与治理层分离

1.1 设计目标

规范开篇明确了协议的六个核心目标:

  • 机密性(Confidentiality):只有通信双方能解密消息;
  • 前向保密(Forward secrecy):当前密钥泄露不会导致历史消息被解密;
  • 泄露后安全(Post-compromise security):棘轮(ratchet)能在密钥泄露后"自愈";
  • 认证(Authentication):消息通过密码学绑定到 Agent 身份;
  • 重放保护(Replay protection):每个消息密钥单次使用;
  • 离线投递(Offline delivery):通过 store-and-forward 机制为离线 Agent 持久化消息。

1.2 与 AGT 治理层的关系

这是本规范最重要的架构决策:AgentMesh 定义的是传输层,而 AGT 的治理层(策略引擎、信任评分、审计日志)环绕在传输层之外运作——在传输层加密或解密之前,先评估消息是否允许发送或接收。治理与传输刻意分离,以便两者独立演进。

规范给出了清晰的层级图:AGT Governance Layer (Policy → Trust → Audit) 输出 allow/deny 决策,向下传给 AgentMesh Wire Protocol (X3DH → Ratchet → Envelope),再由 Transport (WebSocket / gRPC) 承载密文。这一分层设计在源码中有直接印证,例如 agent-governance-python/agent-mesh/src/agentmesh/encryption/channel.py 等加密模块与 agent-governance-python/agent-mesh/src/agentmesh/governance/ 治理模块在包结构上就是分离的。

1.3 设计原则

  1. 标准优先(Standards first):每个密码学操作都引用已发布的 RFC 或规范,不搞自研加密;
  2. 身份统一(One identity, everywhere):所有 SDK 与服务共享同一套 Agent 身份格式;
  3. 多语言可实现(Crypto in every language):协议必须能用经过审计的库在 Python、TypeScript、Rust、.NET、Go 中实现;
  4. 治理可分离(Governance-separable):治理决策发生在传输层动作之前,传输层永不做出策略决策;
  5. Relay 是服务而非特性(Relay is a service, not a feature):store-and-forward 是可部署的服务,不内嵌进 SDK;
  6. 协议版本化(Protocol versioning):每个帧都携带版本字段,未来版本(含 MLS 群组支持)可协商。

2. 标准基础:全部引用公开 RFC 与 CC0 规范

组件 标准 参考
密钥协商 X3DH Signal X3DH 规范(CC0)
会话加密 Double Ratchet Signal Double Ratchet 规范(CC0)
Diffie-Hellman X25519 RFC 7748
密钥派生 HKDF-SHA256 RFC 5869
对称加密 ChaCha20-Poly1305 RFC 8439
签名 Ed25519 RFC 8032
身份 DID W3C DID Core
未来群组消息 MLS RFC 9420

2.1 为什么 v1 选 Signal Protocol 而非 MLS

规范用一张对比表给出了决策依据:

标准 Signal Protocol MLS(RFC 9420)
点对点消息 原生支持 支持(2 人群组)
群组消息 N×(N-1)/2 个会话 原生树形棘轮
实现复杂度 中等 高
AGT 现有实现 Python(61 个测试) 无
生态采用 WhatsApp、Signal、Google Messages Cisco Webex、Wire(新兴)
规范成熟度 10+ 年 RFC 于 2023 年发布

选择 Signal Protocol 的原因:AGT 已有可用的 Python 实现、Agent 间场景以点对点为主、五种语言的实现负担可控。MLS 通过第 15 节定义的版本协商机制预留给 v2 群组消息。

3. Agent 身份:自验证 DID

3.1 身份格式与指纹

所有 Agent 遵循 W3C DID Core 规范,用 DID(去中心化标识符)标识:

did:agentmesh:<fingerprint>

其中指纹为:

fingerprint = base58btc(sha256(ed25519_public_key)[0:20])

即 Agent Ed25519 公钥的 20 字节截断 SHA-256 哈希,用 base58btc(比特币字母表)编码。其性质包括:

  • 自验证(Self-verifying):任何持有公钥的人都能重新计算指纹;
  • 紧凑(Compact):27-28 个字符,如 did:agentmesh:3J98t1WpEZ73CNmQvie;
  • 无需注册表往返即可完成基础验证;
  • 抗碰撞(Collision-resistant):160 位哈希提供 2^80 碰撞阻力。

3.2 身份收敛决策(ADR)

规范记录了一条 ADR 决策:将 Python 的 did:mesh: 与 TypeScript 的 did:agentmesh: 统一收敛为单一的 did:agentmesh:<fingerprint> 格式,理由是指纹由公钥派生、自验证,且 did:agentmesh: 前缀更贴合包命名。迁移策略是:已有 did:mesh: 标识符通过兼容 shim 继续有效,新身份必须使用 did:agentmesh:。

值得说明的是,从当前仓库源码看,TypeScript SDK 的 agent-governance-typescript/src/encryption/mesh-client.ts 中 computeCanonicalDid 仍按 did:mesh:<sha256(public_key)[:32]>(16 字节摘要)派生 DID 以匹配 Python 服务端实现,这与规范收敛到 did:agentmesh:(20 字节 base58btc)的 ADR 属于实现与规范之间的演进过渡状态,读者在跨 SDK 对接时需以各自版本的注册表/中继实现为准。

3.3 密钥材料

每个 Agent 持有五类密钥:

密钥 类型 用途 生命周期
身份密钥(IK) Ed25519 签名、DID 派生 长期
身份密钥(IK-X) X25519 DH 运算(由 IK 派生) 与 IK 相同
签名预密钥(SPK) X25519 X3DH,由 IK 签名 定期轮换(建议 7 天)
一次性预密钥(OPK) X25519 X3DH,使用即消耗 单次使用
棘轮密钥 X25519 Double Ratchet DH 步骤 每消息轮次

3.4 Ed25519 到 X25519 的转换

身份密钥是 Ed25519(用于签名),而 X3DH 需要 X25519(用于 DH)。转换使用 RFC 7748 第 4.1 节定义的 birational map:

x25519_private = ed25519_sk_to_curve25519(ed25519_private_key)
x25519_public  = ed25519_pk_to_curve25519(ed25519_public_key)

这是 libsodium(crypto_sign_ed25519_pk_to_curve25519)、@noble/curves(edwardsToMontgomeryPub)等库的标准操作。源码层面,Python 实现在 agent-governance-python/agent-mesh/src/agentmesh/encryption/x3dh.py 中通过 PyNaCl 的 crypto_sign_ed25519_sk_to_curve25519 / crypto_sign_ed25519_pk_to_curve25519 完成转换;TypeScript 实现在 agent-governance-typescript/src/encryption/x3dh.ts 中通过 sha512(seed) 取前 32 字节并按 RFC 7748 §5 clamp(privateKey[0] &= 248; privateKey[31] &= 127; privateKey[31] |= 64)实现,两种实现路径等价。

4. 密码学原语:单一强制密码套件

4.1 密码套件

协议只定义一个强制密码套件:

AGENTMESH_X25519_CHACHA20POLY1305_SHA256
原语 算法 参数
DH X25519 RFC 7748
AEAD ChaCha20-Poly1305 RFC 8439,96 位 nonce,128 位 tag
哈希 SHA-256 FIPS 180-4
KDF HKDF-SHA256 RFC 5869
签名 Ed25519 RFC 8032
密钥编码 原始 32 字节 X25519 使用小端 u-coordinate

4.2 HKDF 用法

所有密钥派生使用 HKDF-SHA256(RFC 5869),带域特定的 info 字符串:

用途 Salt Info 输出长度
X3DH 共享密钥 0x00 * 32(零块) "AgentMesh_X3DH_v1" 32 字节
根密钥棘轮 当前根密钥 "AgentMesh_Ratchet_v1" 64 字节(32 root + 32 chain)
链密钥 → 消息密钥 — 以 0x01 为 HMAC-SHA256 32 字节
链密钥 → 下一链 — 以 0x02 为 HMAC-SHA256 32 字节

X3DH HKDF 输入(Signal 规范):0xFF * 32 字节串 F 前缀到 IKM 之前(IKM = F || DH1 || DH2 || DH3 <a href="https://link.gitcode.com/i/8e60ac11857ac1393172f58b9512df6e" target="_blank">|| DH4]),HKDF 的 salt 是零块(0x00 * 32),不是 F。规范特别指出,早期草案错误地把 F 用作 salt,相关修正记录在 [docs/security/audits/2026-06-22-x3dh-kdf-spec-fix.md。

这个细节在源码中有极其生动的印证:TypeScript 的 x3dh.ts 注释记录了此前 TS 端错误地把 F 作为 HKDF salt、把裸 DH 拼接作为 IKM,导致与已修正的 Python SDK 之间出现"握手成功但第一条消息解密报 invalid tag"的跨运行时互操作问题;修正后 kdf() 统一实现为 hkdf(sha256, F_PREFIX || ikm, ZERO_SALT, X3DH_INFO, 32),并在 agent-governance-python/agent-mesh/tests/test_x3dh.py 中通过 test_kdf_uses_zero_salt_and_prepends_f_to_ikm 测试固定了盐/IKM 语义,防止回归。

4.3 AEAD 构造

消息用 ChaCha20-Poly1305(RFC 8439)加密:

nonce      = random(12)                    # 96-bit random nonce
aad        = header_bytes || associated_data
ciphertext = ChaCha20Poly1305.encrypt(key, nonce, plaintext, aad)
output     = nonce || ciphertext           # nonce prepended

关联数据(AAD) 将密文绑定到消息头和 Agent 身份,防止头部篡改:

aad = serialize(header) || sender_did_bytes || recipient_did_bytes

5. 密钥管理:预密钥包与轮换策略

5.1 预密钥包(Pre-Key Bundle)

Agent 向注册表发布预密钥包,供异步会话建立使用:

{
  "version": 1,
  "agent_did": "did:agentmesh:3J98t1WpEZ73CNmQvie",
  "identity_key": "<base64url(x25519_public)>",
  "signed_pre_key": {
    "key_id": 42,
    "public_key": "<base64url(x25519_public)>",
    "signature": "<base64url(ed25519_signature)>"
  },
  "one_time_pre_keys": [
    { "key_id": 100, "public_key": "<base64url(x25519_public)>" },
    { "key_id": 101, "public_key": "<base64url(x25519_public)>" }
  ],
  "timestamp": "2026-04-21T19:00:00Z"
}

5.2 签名预密钥轮换

签名预密钥建议每 7 天轮换一次。轮换后注册表必须保留上一把 SPK 14 天,以便在途的会话建立完成。

5.3 一次性预密钥补充

OPK 使用即消耗。Agent 建议在注册表上维持至少 10 把 OPK,当数量低于 5 时补充。TypeScript SDK 的默认行为是连接时生成并上传 20 把 OPK(oneTimePrekeyCount,默认 20,见 mesh-client.ts),每把 X3DH 发起成功即被对方消耗一把。

6. X3DH 密钥协商:完整流程与参数

完全遵循 Signal X3DH 规范,参数如下:

curve = X25519
hash  = SHA-256
info  = "AgentMesh_X3DH_v1"

6.1 发起方流程(Initiator Flow)

  1. 从注册表获取接收方的预密钥包;
  2. 验证 SPK 签名(对 SPK 公钥的 Ed25519 签名);
  3. 生成临时 X25519 密钥对(EK);
  4. 计算 DH 值:
    • DH1 = DH(IK_sender, SPK_recipient)
    • DH2 = DH(EK_sender, IK_recipient)
    • DH3 = DH(EK_sender, SPK_recipient)
    • DH4 = DH(EK_sender, OPK_recipient)(若有 OPK)
  5. 派生共享密钥:SK = HKDF(salt = 0x00*32, IKM = 0xFF*32 || DH1||DH2||DH3[||DH4], info = "AgentMesh_X3DH_v1", 32);
  6. 以 SK 初始化 Double Ratchet(发送方角色)。

6.2 响应方流程(Responder Flow)

  1. 接收包含发送方 IK、EK 和所用 OPK ID 的初始消息;
  2. 计算对应的 DH 值(角色对调);
  3. 派生相同的共享密钥 SK;
  4. 以 SK 初始化 Double Ratchet(接收方角色);
  5. 删除已消耗的 OPK。

6.3 关联数据(Associated Data)

AD = sender_identity_key_x25519 || recipient_identity_key_x25519

AD 传给 Double Ratchet,并绑定进每条消息的 AEAD。

6.4 源码级印证

  • Python 的 X3DHKeyManager 实现于 agent-governance-python/agent-mesh/src/agentmesh/encryption/x3dh.py,测试 test_x3dh.py 覆盖了 20+ 场景:完整交换、无 OPK 交换、OPK 消耗、重用 OPK 报错、篡改 SPK 签名拒绝、伪造身份密钥拒绝等(如 test_full_exchange_with_otk、test_otk_consumed_after_use、test_tampered_spk_signature_rejected)。
  • TypeScript 的 x3dh.ts initiate() 依次计算 DH1/DH2/DH3,存在 OPK 时追加 DH4;respond()(L227-L261)按角色对调计算,并在 usedOneTimeKeyId 存在时校验并删除对应 OPK(this.oneTimePreKeys.delete(usedOneTimeKeyId))。
  • 预密钥包验证(verifyBundle)在 x3dh.ts:校验 Ed25519 身份密钥存在且为 32 字节、SPK 签名为 64 字节、SPK 与身份密钥均为 32 字节,最后用 Ed25519 公钥验证 SPK 签名,确保预密钥确实由包的所有者生成而非攻击者注入。

7. Double Ratchet:逐消息前向保密

完全遵循 Signal Double Ratchet 规范,参数如下。

7.1 棘轮状态

state = {
  dh_self:      X25519KeyPair,       # 当前 DH 棘轮密钥对
  dh_remote:    X25519PublicKey,      # 对端当前 DH 棘轮密钥
  root_key:     bytes[32],           # 根链密钥
  chain_send:   bytes[32] | null,    # 发送链密钥
  chain_recv:   bytes[32] | null,    # 接收链密钥
  n_send:       uint32,              # 发送消息计数器
  n_recv:       uint32,              # 接收消息计数器
  pn:           uint32,              # 上一发送链长度
  skipped:      Map<(bytes, uint32), bytes[32]>  # 跳过的消息密钥
}

7.2 对称棘轮(KDF 链)

message_key    = HMAC-SHA256(chain_key, 0x01)
next_chain_key = HMAC-SHA256(chain_key, 0x02)

TypeScript 实现于 agent-governance-typescript/src/encryption/ratchet.ts 的 kdfChain(),与规范完全一致。

7.3 DH 棘轮步骤

当收到消息的 DH 公钥与 dh_remote 不同时触发:

  1. 缓存当前接收链的跳过消息密钥;
  2. dh_output = DH(dh_self.private, new_dh_remote);
  3. root_key, chain_recv = KDF_ROOT(root_key, dh_output);
  4. 生成新 DH 密钥对:dh_self = X25519.generate();
  5. dh_output = DH(dh_self.private, new_dh_remote);
  6. root_key, chain_send = KDF_ROOT(root_key, dh_output);
  7. 重置发送/接收计数器。

根密钥 KDF 在 ratchet.ts 中实现为 hkdf(sha256, dhOutput, rootKey, "AgentMesh_Ratchet_v1", 64),前 32 字节为新 root key、后 32 字节为新链密钥,输出长度与规范一致。

7.4 跳过的消息密钥

每会话最大跳过密钥数:100(可配置)。超过此上限必须以错误拒绝消息。跳过密钥建议持久化以便会话恢复。

值得注意:TypeScript 实现额外增加了一个总量上限 MAX_SKIPPED_KEYS_TOTAL = 2000(ratchet.ts),防止会话跨多次 DH 棘轮步骤后 skippedKeys 无界增长,其注释明确"镜像了 Python 核心实现的 _MAX_SKIPPED_KEYS_TOTAL"——这是规范基线之上各语言实现自行加固的典型例子。

7.5 会话序列化

棘轮状态必须可序列化为 JSON 以便持久化:

{
  "dh_self_private": "<hex>",
  "dh_self_public": "<hex>",
  "dh_remote_public": "<hex>",
  "root_key": "<hex>",
  "chain_key_send": "<hex>",
  "chain_key_recv": "<hex>",
  "n_send": 0,
  "n_recv": 0,
  "pn": 0,
  "skipped_keys": { "<dh_pub_hex>:<n>": "<message_key_hex>" }
}

8. 消息信封:JSON 帧格式

8.1 通用帧格式

所有协议帧都是带 type 字段和 version 字段的 JSON 对象:

{
  "v": 1,
  "type": "<frame_type>",
  "from": "did:agentmesh:<fingerprint>",
  "to": "did:agentmesh:<fingerprint>",
  "id": "<uuid>",
  "ts": "<ISO-8601>",
  ...帧特有字段
}

8.2 帧类型

类型 方向 用途
connect 客户端 → Relay 注册在线状态、认证
disconnect 客户端 → Relay 优雅断开
knock Agent → Agent(经 Relay) 携带意图的会话发起
knock_accept Agent → Agent(经 Relay) 带策略条件接受会话
knock_reject Agent → Agent(经 Relay) 带原因拒绝会话
message Agent → Agent(经 Relay) 加密的应用消息
ack Agent → Agent(经 Relay) 投递确认
prekey_request 客户端 → Registry 获取预密钥包
prekey_response Registry → 客户端 预密钥包
prekey_upload 客户端 → Registry 发布预密钥包
heartbeat 客户端 → Relay 保活 + 在线状态
error 任意 → 任意 错误响应

8.3 消息帧(核心加密帧)

{
  "v": 1,
  "type": "message",
  "from": "did:agentmesh:sender",
  "to": "did:agentmesh:recipient",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ts": "2026-04-21T19:00:00Z",
  "header": {
    "dh": "<base64url(sender_dh_public_key)>",
    "pn": 5,
    "n": 0
  },
  "ciphertext": "<base64url(nonce || encrypted_payload)>"
}

头部字段:

  • dh — 发送方当前 DH 棘轮公钥(32 字节,base64url);
  • pn — 上一发送链长度(用于跳过密钥计算);
  • n — 当前发送链中的消息序号。

密文: 12 字节 nonce 前置到 ChaCha20-Poly1305 输出之前。

TypeScript 发送路径完全按此构造:send() 在 mesh-client.ts 中调用 session.channel.send(...) 后,将 encrypted.header.dhPublicKey / previousChainLength / messageNumber 分别映射为帧的 dh / pn / n,密文 base64url 编码(实现中实际使用标准 base64 Buffer 编码,解码侧与之对应)。

8.4 初始消息(X3DH)

会话的第一条消息包含 X3DH 建立数据:

{
  "v": 1,
  "type": "message",
  "from": "did:agentmesh:sender",
  "to": "did:agentmesh:recipient",
  "id": "...",
  "ts": "...",
  "x3dh": {
    "identity_key": "<base64url(sender_x25519_identity_key)>",
    "ephemeral_key": "<base64url(sender_ephemeral_key)>",
    "used_opk_id": 100
  },
  "header": { "dh": "...", "pn": 0, "n": 0 },
  "ciphertext": "..."
}

x3dh 字段只在会话的第一条消息中出现。接收方在解密前用它执行 X3DH 响应方流程。

9. KNOCK 意图协议:治理门控的会话握手

KNOCK 是一种携带意图(intent-carrying)的握手,先于会话建立。它允许接收方在接受会话前评估发起方声明的意图——与 AGT 治理层集成。

9.1 KNOCK 帧

{
  "v": 1,
  "type": "knock",
  "from": "did:agentmesh:sender",
  "to": "did:agentmesh:recipient",
  "id": "...",
  "ts": "...",
  "intent": {
    "action": "delegate_task",
    "description": "Process customer refund #12345",
    "capabilities_required": ["payments:write", "crm:read"],
    "trust_minimum": 700
  },
  "signature": "<base64url(ed25519_signature_over_canonical_intent)>"
}

9.2 KNOCK 接受

{
  "v": 1,
  "type": "knock_accept",
  "from": "did:agentmesh:recipient",
  "to": "did:agentmesh:sender",
  "id": "...",
  "ts": "...",
  "knock_id": "<原始 knock 的 id>",
  "conditions": {
    "max_messages": 100,
    "ttl_seconds": 3600,
    "allowed_actions": ["payments:write"]
  },
  "signature": "<base64url(ed25519_signature)>"
}

9.3 KNOCK 拒绝

{
  "v": 1,
  "type": "knock_reject",
  "from": "did:agentmesh:recipient",
  "to": "did:agentmesh:sender",
  "id": "...",
  "knock_id": "<原始 knock 的 id>",
  "reason": "insufficient_trust",
  "signature": "<base64url(ed25519_signature)>"
}

9.4 治理集成

接受 KNOCK 之前,接收方的治理层评估:

  1. 发送方 DID 是否已注册且激活?
  2. 发送方信任分是否达到 trust_minimum?
  3. 发送方是否持有 capabilities_required?
  4. 声明的 intent.action 是否通过策略引擎?

只有所有检查通过,接收方才发送 knock_accept 并进入 X3DH 密钥交换。

9.5 源码级实现细节

TypeScript 的 MeshClient 对 KNOCK 做了大量工程化加固(mesh-client.ts):

  • 超时与竞态处理:knockTimeout 默认 10 秒,超时后等待方统一以"拒绝"收尾;timedOut 标志防止慢处理器的 knock_accept 在计时器已判负之后发出;
  • 待决队列(knockPending):若加密消息先于 KNOCK 判决到达(Relay 不保证帧间顺序),handleMessage 会等待 KNOCK 决议后再决定是否解密;
  • 会话自动引导:发起方在 KNOCK 帧内嵌 establishment(含 ik/ek/otk),接收方接受后即可自动 bootstrap 响应方会话,无需等第一条密文才手工 acceptSession(),消除了 "No encrypted session" 竞态(注释中称为 vendored agentmesh-sdk patch #4b);
  • Pre-KNOCK 缓冲:对"KNOCK 判决前到达的加密帧"按 peer 缓冲,默认每 peer 5 条、TTL 3000ms、全局最多 100 个 peer 缓冲,超限驱逐最旧 peer(Gap-G4 修复);
  • 明文降级防护:是否按 legacy 明文处理完全由接收方自身的操作者配置(plaintextPeers 白名单)决定,绝不信任帧上发送方可控的 plaintext 布尔值;且 e2eVerifiedSet 是单向闩锁——一旦某 peer 成功解密过一条消息,该 peer 终生不再按明文路径处理(Gap-G3 修复,防恶意 Relay 用垃圾密文强制关会话后降级攻击)。

10. Registry API:注册表服务

注册表是存储 Agent 元数据、预密钥包并提供发现的 REST 服务。

10.1 端点

方法 路径 用途
POST /v1/agents 注册 Agent
GET /v1/agents/{did} 获取 Agent 元数据
DELETE /v1/agents/{did} 注销 Agent
PUT /v1/agents/{did}/prekeys 上传预密钥包
GET /v1/agents/{did}/prekeys 获取预密钥包(消耗一把 OPK)
GET /v1/agents/{did}/presence 获取在线状态/最后可见时间
POST /v1/agents/{did}/reputation 提交信誉反馈
GET /v1/discover 按能力搜索 Agent

10.2 Agent 注册

POST /v1/agents
Authorization: Ed25519-Timestamp <did> <timestamp> <signature>

{
  "did": "did:agentmesh:3J98t1WpEZ73CNmQvie",
  "public_key": "<base64url(ed25519_public)>",
  "capabilities": ["data:read", "data:write"],
  "metadata": {
    "name": "trading-agent",
    "framework": "langchain",
    "version": "1.0.0"
  }
}

10.3 预密钥获取

GET /v1/agents/did:agentmesh:3J98t1WpEZ73CNmQvie/prekeys
Authorization: Ed25519-Timestamp <did> <timestamp> <signature>

响应包含一把 OPK(原子消耗):

{
  "identity_key": "<base64url>",
  "signed_pre_key": { "key_id": 42, "public_key": "<base64url>", "signature": "<base64url>" },
  "one_time_pre_key": { "key_id": 100, "public_key": "<base64url>" }
}

如果 OPK 耗尽,one_time_pre_key 为 null,发起方执行 3-DH(不含 DH4)。

源码印证:TypeScript 的 MeshClient.registerSelf()(mesh-client.ts)生成 SPK 与 oneTimePrekeyCount 把 OPK,携带能力列表(自动附加 displayName 以便按名 discover)与元数据完成注册,然后上传预密钥;注册采用 POP(proof-of-possession)模式,服务端验证 Ed25519(public_key || timestamp) 后返回规范 DID 并回写为 active DID,保证后续 registry 查询与 relay connect.from 与服务端视图一致。

11. Relay 服务:Store-and-Forward 中继

中继为可能离线的 Agent 提供 store-and-forward 投递。

11.1 架构

Agent A ──WebSocket──► Relay ──WebSocket──► Agent B
                         │
                    ┌────▼─────┐
                    │ Inbox DB │  (离线消息)
                    └──────────┘

11.2 连接

{
  "v": 1,
  "type": "connect",
  "from": "did:agentmesh:sender",
  "auth": {
    "timestamp": "2026-04-21T19:00:00Z",
    "signature": "<base64url(ed25519_sign(timestamp))>"
  }
}

11.3 Store-and-Forward

  • 离线 Agent 的消息存储在 Relay 的 inbox 数据库中;
  • TTL:72 小时(按部署可配置);
  • 投递: 重连时 Relay 推送所有待处理消息;
  • 排序: 消息按每个发送方的发送顺序投递;
  • 去重: 消息 id(UUID)用于幂等投递;
  • 确认: 接收方发送 ack 帧,Relay 从 inbox 删除。

11.4 心跳

{
  "v": 1,
  "type": "heartbeat",
  "from": "did:agentmesh:sender",
  "ts": "2026-04-21T19:00:00Z"
}

间隔:30 秒。Relay 在 3 次心跳未收到(90 秒)后将 Agent 标记为离线。

11.5 仅密文存储

Relay 只存储密文,无法解密消息。Relay 能看到:发送方 DID、接收方 DID、消息 ID、时间戳和不可读的密文。这是刻意设计——Relay 对内容不可信。

源码印证:TypeScript MeshClient.connect()(mesh-client.ts)连接后发送含 public_key/timestamp/signature 的 connect 帧,随后发送 fetch_pending 帧请求离线期间排队的消息;收到 pending_messages 帧后逐条走标准 handleMessage 路径解密(handlePendingMessages,L961-L993)。同时,中继在另一连接以相同 DID 认证时会发送 WebSocket 关闭码 4006(WS_CLOSE_SESSION_REPLACED,L144),客户端据此识别"会话被顶替"且不得自动重连,以免两个连接互相顶替形成死循环。

12. 认证:Ed25519-Timestamp 与 SPIFFE/SVID

12.1 Ed25519-Timestamp(默认)

所有 registry 与 relay 请求的默认认证方案:

Authorization: Ed25519-Timestamp <did> <iso8601_timestamp> <base64url(signature)>

其中 signature = Ed25519.sign(private_key, utf8(iso8601_timestamp))。

服务端验证:

  1. 时间戳在重放窗口(±5 分钟)内;
  2. DID 已注册;
  3. 签名对已注册公钥有效。

12.2 SPIFFE/SVID(企业版)

适用于具备 PKI 基础设施的企业部署:

Authorization: Bearer <SVID-JWT>

其中 SVID JWT 包含映射到 DID 的 Agent SPIFFE ID。

12.3 认证模式选择

部署在 relay/registry 配置中声明认证模式:

auth_mode: "ed25519"   # 默认 — 随处可用
# auth_mode: "svid"    # 企业 — 需要 SPIFFE 基础设施
# auth_mode: "hybrid"  # 两种都接受

13. 治理集成:策略在加解密前后介入

13.1 发送前策略检查

加密和发送消息前,治理层评估:

result = policy_engine.evaluate({
    "action": "agentmesh.send",
    "sender": sender_did,
    "recipient": recipient_did,
    "intent": knock_intent,       # 来自打开本会话的 KNOCK
    "message_number": n_send,
    "session_age_seconds": elapsed,
})
if not result.allowed:
    raise PermissionError(result.reason)

13.2 接收后策略检查

将解密内容返回应用之前:

result = policy_engine.evaluate({
    "action": "agentmesh.receive",
    "sender": sender_did,
    "recipient": self_did,
    "content_hash": sha256(plaintext),
})

13.3 审计

每次消息发送/接收尝试都记录到 AGT 审计追踪:

{
  "event": "agentmesh.message",
  "direction": "send",
  "sender": "did:agentmesh:...",
  "recipient": "did:agentmesh:...",
  "message_id": "...",
  "session_id": "...",
  "policy_decision": "allow",
  "timestamp": "..."
}

14. 协议版本化

14.1 版本字段

每个帧都包含 "v": <integer>。本规范定义 v: 1。

14.2 版本协商

connect 帧中,客户端声明支持的版本:

{
  "v": 1,
  "type": "connect",
  "supported_versions": [1],
  ...
}

Relay 以双方共同支持的最高版本响应。

14.3 未来版本

版本 描述
1 本规范(Signal Protocol,点对点)
2(规划中) MLS 群组消息(RFC 9420)
3(规划中) 后量子密钥封装(ML-KEM)

15. 安全考量

15.1 信任模型

  • Relay 对内容不可信(只见密文),但对投递可信(可以丢弃或延迟消息);
  • Registry 对预密钥分发可信(被攻破的注册表可通过替换预密钥执行中间人攻击);
  • Agent 通过绑定到其 DID 的 Ed25519 签名认证。

15.2 前向保密

Double Ratchet 提供前向保密:每个消息密钥从棘轮状态派生、用后即弃。攻破当前棘轮状态只泄露未来消息(未来消息由 DH 棘轮步骤的后泄露安全保护)。

15.3 重放保护

  • 每个消息密钥单次使用(由链棘轮派生);
  • Relay 按消息 id(UUID)去重;
  • 跳过的消息密钥有可配置上限(默认 100)。

15.4 拒绝服务(DoS)

  • Relay 实施每 Agent 速率限制(可配置);
  • Registry 实施预密钥上传速率限制;
  • KNOCK 协议允许接收方在密钥交换前拒绝会话。

15.5 已知限制

  • v1 无群组消息——仅点对点;
  • v1 无后量子密钥交换——仅 X25519;
  • Relay 可观察流量模式(谁和谁通信、何时、消息大小);
  • 无工作流级关联——治理评估单条消息,不评估消息序列。

16. 测试向量(Test Vectors)

16.1 X3DH 测试向量

规范当前给出的是占位框架(Alice/Bob 密钥对与期望共享密钥待填入),并注明:完整测试向量将从参考 Python 实现生成,并在规范定稿前与 TypeScript 实现交叉验证。值得注意,上文提到的 TypeScript kdf() 已导出以便测试套件对照与 AGT Python SDK 共享的跨运行时已知答案向量固定派生密钥(见 x3dh.ts),这正是交叉验证机制在源码中的落地。

16.2 Double Ratchet 测试向量

一次完整的 5 消息会话(含期望的中间棘轮状态)将作为 JSON 文件提供于 tests/vectors/ratchet-v1.json。

16.3 信封序列化测试向量

每种帧类型的规范 JSON 序列化将提供于 tests/vectors/envelope-v1.json。

17. 附录要点

17.1 知识产权与在先技术(Appendix A)

本规范是独立的洁净室设计(clean-room design),完全基于公开、自由许可的标准构建:IETF RFC(BCP 78 可自由实现)、CC0 许可的 Signal Foundation 规范、W3C 规范(免版税)以及 AGT 团队对 Agent 特有功能(KNOCK 协议、治理集成、Registry API、Relay 语义)的原创设计。规范不声称密码学原语上的新颖性,其创新贡献在于将成熟原语与 Agent 特有治理相结合:策略门控会话、携带意图的握手、信任评分身份、确定性审计追踪。

17.2 推荐密码学库(Appendix B)

实现必须使用经过审计的知名密码学库,禁止自研加密实现:

  • Python:PyNaCl(libsodium,Apache 2.0,已是 AGT 依赖)提供 X25519/Ed25519;cryptography(Apache 2.0 / BSD,已是 AGT 依赖)提供 HKDF、ChaCha20-Poly1305;
  • TypeScript/JavaScript:@noble/curves(MIT,审计过、零依赖)提供 X25519/Ed25519;@noble/ciphers(MIT)提供 ChaCha20-Poly1305;@noble/hashes(MIT)提供 HKDF、SHA-256、HMAC;
  • Rust:x25519-dalek(BSD-3-Clause)、ed25519-dalek(BSD-3-Clause,已是 AGT 依赖)、chacha20poly1305 与 hkdf(RustCrypto 项目,MIT / Apache 2.0);
  • .NET:libsodium-core 或 NSec(MIT,libsodium 绑定);
  • Go:golang.org/x/crypto(BSD-3-Clause)提供 X25519、Ed25519、HKDF、ChaCha20-Poly1305。

17.3 教程与演示路线图(Appendix C)

规范实现后计划提供的文档:E2E 加密 Agent 消息教程(5 种语言)、KNOCK 协议与基于意图的会话教程、Relay + Registry 部署教程(Docker Compose + Helm)、双 Agent 加密对话演示、多 Agent 任务委派演示(KNOCK → 加密信道 → 任务交接 → 审计追踪)、离线 Agent 投递演示、Registry REST API 参考(OpenAPI)、Relay WebSocket 协议参考。

18. 参考资料

  1. Signal X3DH 规范(CC0);
  2. Signal Double Ratchet 规范(CC0);
  3. RFC 7748 — Elliptic Curves for Security(X25519);
  4. RFC 5869 — HKDF;
  5. RFC 8439 — ChaCha20 and Poly1305;
  6. RFC 8032 — Ed25519;
  7. RFC 9420 — MLS;
  8. W3C DID Core 规范;
  9. SPIFFE/SVID 规范。

延伸阅读: 与本文密切相关的还有 docs/specs/AGENTMESH-IDENTITY-TRUST-1.0.md(身份与信任评分)、docs/specs/AGENTMESH-TRUST-COORDINATION-1.0.md(信任协调)与 docs/specs/MCP-SECURITY-GATEWAY-1.0.md(MCP 安全网关);Python 参考实现的加密模块位于 agent-governance-python/agent-mesh/src/agentmesh/encryption/,TypeScript 实现位于 agent-governance-typescript/src/encryption/(含 x3dh.ts、ratchet.ts、mesh-client.ts、registry-client.ts),Rust 实现位于 agent-governance-rust/agentmesh/src/。

登录后查看全文
agent-governance-toolkit