@agentunion/fastaun-browser 0.5.0 → 0.5.2

package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md

@@ -41,14 +41,14 @@ await client.call("message.send", {
 })
 ```
 
-SDK 优先使用 prekey_ecdh_v2，并默认要求前向保密：
-
-1. **prekey_ecdh_v2** — 对方有预上传的 prekey，四路 ECDH（ephemeral×prekey + ephemeral×identity + sender×prekey + sender×identity），前向安全，附带发送方签名
-2. **long_term_key** — 对方无 prekey，双路 ECDH（ephemeral×recipient_identity + sender×recipient_identity）+ HKDF 派生密钥（降级模式），附带发送方签名
-
-> Python SDK 默认 `require_forward_secrecy=true`，当加密结果不满足前向保密（无论是因为无 prekey 还是 prekey 加密失败降级到 long_term_key）时拒绝发送并抛出错误。需显式配置 `require_forward_secrecy=false` 才允许降级。
-
-每条消息独立生成临时 ECDH 密钥对，实现一消息一密钥。
+当前 SDK 使用 E2EE V2 多设备 wrap 主路径：
+
+1. 发送前通过 `message.v2.bootstrap` 或 `group.v2.bootstrap` 获取接收方当前活跃设备、设备 prekey、self-sync 设备和 audit recipients。
+2. SDK 为每条消息生成独立 `master_key`、消息 nonce 和发送方临时 session key，只加密一次正文。
+3. SDK 为每个接收设备生成一条 recipient wrap。设备有可用 SPK 时使用 `3DH` wrap；缺少 SPK 的兼容场景才使用 `1DH` wrap。
+4. E2EE 信封包含 `sender_signature`、AAD、`recipients_digest` / Merkle proof，接收端必须验签、验 AAD、验 recipient proof 后再解密。
+
+每条消息独立密钥；V2 当前主路径不再使用旧 `prekey_ecdh_v2` / `long_term_key` 信封作为默认发送格式。旧术语只用于历史兼容文档或迁移排查。
 
 ## ProtectedHeaders 与可验证上下文
 
@@ -56,18 +56,20 @@ SDK 优先使用 prekey_ecdh_v2，并默认要求前向保密：
 
 `protected_headers` 会随 E2EE 信封发送，接收端可以读取，因此它提供完整性保护，不提供机密性保护。不要把访问令牌、私钥、隐私正文或其他只允许端到端可见的内容放入 `protected_headers`；这类内容应放进加密的 `payload`。
 
-推荐通过 SDK 实例级 setter 设置稳定元数据，例如 `client.set_protected_headers(...)` / `client.setProtectedHeaders(...)` / `client.SetProtectedHeaders(...)`。发送方也可以在以下 SDK 调用中传入顶层 `protected_headers` 作为单次发送的高级覆盖；`headers` 仅作为兼容旧调用的别名，不推荐新代码使用：
+推荐通过 SDK 实例级 setter 设置稳定元数据，例如 `client.set_protected_headers(...)` / `client.setProtectedHeaders(...)` / `client.SetProtectedHeaders(...)`。发送方也可以在以下 SDK 调用中传入顶层 `protected_headers` 作为单次发送的高级覆盖；`headers` 仅作为兼容旧调用的别名，不推荐新代码使用：
 
 - `message.send`
 - `message.thought.put`
 - `group.send`
 - `group.thought.put`
 
-`payload_type` 不需要应用层传入。SDK 会读取加密前 `payload.type`，自动写入 `protected_headers.payload_type`，接收端解密后会校验它与明文 `payload.type` 一致。
-
-`protected_headers` / `headers` 是 send/thought 参数的顶层字段，不放入单独的 `envelope` 入参对象，也不属于业务 `payload`。裸 WebSocket 客户端若自行发送已加密信封，需要把 protected headers 放在自构造的 E2EE 信封内并自行完成 `_auth`，服务端不会替裸 RPC 调用生成或校验明文侧的 protected headers。
+`payload_type` 不需要应用层传入。SDK 会读取加密前 `payload.type`，自动写入 `protected_headers.payload_type`，接收端解密后会校验它与明文 `payload.type` 一致。
 
-示例：
+`protected_headers` / `headers` 是 send/thought 参数的顶层字段，不放入单独的 `envelope` 入参对象，也不属于业务 `payload`。裸 WebSocket 客户端若自行发送已加密信封，需要把 protected headers 放在自构造的 E2EE 信封内并自行完成 `_auth`，服务端不会替裸 RPC 调用生成或校验明文侧的 protected headers。
+
+`agent_md` 是独立于 E2EE 的版本提示元数据，不属于 `protected_headers`，也不参与 AAD 或业务鉴权。当前 Message Service V2 P2P 信封可携带 `agent_md.sender`；SDK 也识别 `agent_md.group`。Gateway 在 RPC response / event push 的 `_meta.agent_md_etags` 中注入 `requester`、`peer`、`group`，四端 SDK 会自动写入对应 AID 的 `remote_etag` / `last_modified`，后续仍以下载后的 agent.md 签名验证作为可信依据。
+
+示例：
 
 ```python
 from aun_core import ProtectedHeaders
@@ -103,7 +105,8 @@ await client.call("group.send", {
 
 ```json
 {
-  "type": "e2ee.encrypted",
+  "type": "e2ee.p2p_encrypted",
+  "version": "v2",
   "ciphertext": "...",
   "protected_headers": {
     "device_id": "dev-123",
@@ -127,8 +130,8 @@ await client.call("group.send", {
 
 计算规则：
 
-1. 解密流程会派生出本条消息的 `message_key`。
-2. `metadata_key = HMAC-SHA256(message_key, "aun-envelope-metadata-key-v1")`。
+1. 解密流程会得到本条消息的 `master_key`。
+2. `metadata_key = HMAC-SHA256(master_key, "aun-envelope-metadata-key-v1")`。
 3. 对字典去掉 `_auth` 后做 canonical JSON：UTF-8、key 排序、紧凑分隔符。
 4. `tag = HMAC-SHA256(metadata_key, domain + "\0" + canonical_json(body))`。
 5. `domain` 对 `protected_headers` 为 `aun-protected-headers-v1`，对 `context` 为 `aun-protected-context-v1`。
@@ -268,20 +271,6 @@ result = await client.call("group.thought.get", {
 
 SDK 返回的 `result["thoughts"]` 是已解密数组。`group.thought.get` 是查询操作，重复读取同一条 thought 不按消息 replay 消费处理。
 
-### 手动操作（通常不需要）
-
-`rotate_epoch()` 是纯本地密码学 API。多客户端并发环境下，应通过服务端 CAS（`group.e2ee.get_epoch` + `group.e2ee.rotate_epoch`）确保原子性，SDK 自动编排已使用 CAS 路径。
-
-```python
-# 手动轮换 epoch（纯本地，不经过服务端 CAS 校验）
-info = client.group_e2ee.rotate_epoch("g-abc123.agentid.pub", member_aids)
-
-# 查询状态
-client.group_e2ee.has_secret("g-abc123.agentid.pub")       # 是否持有密钥
-client.group_e2ee.current_epoch("g-abc123.agentid.pub")     # 当前 epoch
-client.group_e2ee.get_member_aids("g-abc123.agentid.pub")   # 已知成员列表
-```
-
 ## 接收加密消息
 
 ### 推送接收
@@ -308,258 +297,20 @@ for msg in result["messages"]:
 
 ---
 
-## Prekey 管理
-
-连接时 SDK 自动上传 prekey，并定时轮换（默认每小时）。一般无需手动管理。
-
-手动上传 prekey：
-
-```python
-# 通过 AUNClient 上传（生成 + RPC）
-await client._upload_prekey()
-```
-
-底层 API（E2EEManager 只生成材料，不做 RPC）：
-
-```python
-prekey_material = client.e2ee.generate_prekey()
-# 返回 {"prekey_id": "...", "public_key": "...", "signature": "...", "created_at": ...}
-# 需要自行上传：await transport.call("message.e2ee.put_prekey", prekey_material)
-
----
-
-## 裸 WebSocket 开发者指南
-
-> 本节面向不使用 AUNClient 连接管理、自行管理 WebSocket 连接的开发者。
-
-### 架构说明
-
-`E2EEManager` 是纯密码学工具类，无 I/O 依赖。构造函数只需：
-
-- `identity_fn` — 返回当前身份信息的函数
-- `keystore` — 密钥存储实现
-
-所有 I/O（获取证书、获取 prekey、RPC 调用）由调用方自行处理。
-
-### 实例化 E2EEManager
-
-```python
-from aun_core.e2ee import E2EEManager
-from aun_core.keystore.local_token_store import LocalTokenStore
-
-e2ee = E2EEManager(
-    identity_fn=lambda: my_identity,
-    keystore=LocalTokenStore("~/.aun/myapp"),
-)
-```
-
-### 加密消息
-
-```python
-# 1. 获取对方证书（HTTP）和 prekey（RPC，可选）
-peer_cert_pem = await fetch_cert(peer_aid)        # 调用方实现
-prekey = await fetch_prekey(peer_aid)              # 调用方实现，可能为 None
-
-# 2. 加密（传入 prekey 会自动缓存，后续可传 None 复用缓存）
-envelope, ok = e2ee.encrypt_message(
-    to_aid="bob.agentid.pub",
-    payload={"type": "text", "text": "秘密消息"},
-    peer_cert_pem=peer_cert_pem,
-    prekey=prekey,
-)
-
-# 3. 通过自己的 WebSocket 发送
-aad = envelope["aad"]
-await my_rpc_call("message.send", {
-    "to": "bob.agentid.pub",
-    "payload": envelope,
-    "type": "e2ee.encrypted",
-    "encrypted": True,
-    "message_id": aad["message_id"],
-    "timestamp": aad["timestamp"],
-})
-```
-
-P2P 消息的投递语义来自连接阶段声明的 `delivery_mode`：
-
-- `fanout`：广播到在线实例，并保留离线历史
-- `queue`：只做单实例实时消费，不进入历史
-
-### 解密消息
-
-```python
-# 解密单条消息（内置本地防重放）
-decrypted = e2ee.decrypt_message(raw_message)
-if decrypted is not None:
-    print(decrypted["payload"])  # 明文
-```
-
-### Prekey 缓存
-
-E2EEManager 内置 prekey 缓存（TTL 默认 1 小时）：
-
-```python
-# 首次传入 prekey → 自动缓存
-envelope, ok = e2ee.encrypt_message(..., prekey=fetched_prekey)
-
-# 后续传 None → 自动复用缓存
-envelope, ok = e2ee.encrypt_message(..., prekey=None)
-
-# 手动管理
-e2ee.cache_prekey("bob.agentid.pub", prekey_dict)
-cached = e2ee.get_cached_prekey("bob.agentid.pub")
-e2ee.invalidate_prekey_cache("bob.agentid.pub")
-```
-
-### 生成 Prekey
-
-```python
-prekey_material = e2ee.generate_prekey()
-# 返回 {"prekey_id": "...", "public_key": "...", "signature": "...", "created_at": ...}
-# 自行上传到服务端
-await my_rpc_call("message.e2ee.put_prekey", prekey_material)
-```
-
-### 群组 E2EE（GroupE2EEManager）
-
-`GroupE2EEManager` 是群组 E2EE 的纯工具类，与 `E2EEManager` 平行。密码学和状态管理全自动，网络发送由调用方负责。
-
-#### 实例化
-
-```python
-from aun_core.e2ee import GroupE2EEManager
-from aun_core.keystore.local_token_store import LocalTokenStore
-
-group_e2ee = GroupE2EEManager(
-    identity_fn=lambda: my_identity,
-    keystore=LocalTokenStore("~/.aun/myapp"),
-)
-```
-
-#### 建群后创建 epoch 并分发
-
-```python
-info = group_e2ee.create_epoch(group_id, member_aids)
-# info = {epoch, commitment, distributions: [{to, payload}, ...]}
-
-for dist in info["distributions"]:
-    # 通过 P2P E2EE 发送密钥分发消息
-    envelope, _ = e2ee.encrypt_message(
-        to_aid=dist["to"], payload=dist["payload"],
-        peer_cert_pem=fetch_cert(dist["to"]),
-    )
-    await my_rpc_call("message.send", {
-        "to": dist["to"], "payload": envelope,
-        "type": "e2ee.encrypted", "encrypted": True,
-        ...
-    })
-```
-
-#### 加密群消息
-
-```python
-envelope = group_e2ee.encrypt(group_id, {"type": "text", "text": "hello"})
-await my_rpc_call("group.send", {
-    "group_id": group_id,
-    "payload": envelope,
-    "type": "e2ee.group_encrypted",
-    "encrypted": True,
-})
-```
-
-#### 解密群消息
-
-```python
-decrypted = group_e2ee.decrypt(raw_group_message)
-# 内置防重放 + 外层 group_id/from/sender_aid 校验
-# 非加密消息原样返回，解密失败返回 None
-
-# 批量解密（用于 group.pull）
-results = group_e2ee.decrypt_batch(messages)
-```
-
-#### 处理 P2P 密钥消息
-
-所有密钥协议消息（分发/请求/响应）通过 P2P E2EE 传输。收到后先 P2P 解密，再交给 `handle_incoming`：
-
-```python
-inner = e2ee.decrypt_message(p2p_message)   # P2P 层解密
-result = group_e2ee.handle_incoming(inner["payload"])
-
-if result == "distribution":
-    pass  # 密钥已自动存储
-elif result == "distribution_rejected":
-    pass  # epoch 降级被拒
-elif result == "response":
-    pass  # 密钥恢复响应已存储
-elif result == "request":
-    # 需要回复：查成员列表 → 构建响应 → P2P 发送
-    members = get_group_members(group_id)
-    response = group_e2ee.handle_key_request_msg(inner["payload"], members)
-    if response:
-        p2p_e2ee_send(inner["payload"]["requester_aid"], response)
-```
-
-#### 踢人后轮换
-
-```python
-info = group_e2ee.rotate_epoch(group_id, remaining_member_aids)
-for dist in info["distributions"]:
-    p2p_e2ee_send(dist["to"], dist["payload"])
-```
-
-配合服务端 CAS 防脑裂（推荐）：
-
-```python
-# 1. 读当前 epoch
-status = await my_rpc_call("group.e2ee.get_epoch", {"group_id": group_id})
-# 2. CAS 递增（服务端校验 admin/owner 角色 + 原子递增 + rotation_signature 验签）
-cas = await my_rpc_call("group.e2ee.rotate_epoch", {
-    "group_id": group_id, "current_epoch": status["epoch"],
-    # Python SDK 自动附加 rotation_signature 和 rotation_timestamp
-    # 裸客户端必须自行签名：sign("{group_id}|{current_epoch}|{new_epoch}|{aid}|{timestamp}")
-})
-if cas["success"]:
-    info = group_e2ee.rotate_epoch_to(group_id, cas["epoch"], member_aids)
-    for dist in info["distributions"]:
-        p2p_e2ee_send(dist["to"], dist["payload"])
-# CAS 失败说明别的 admin 先轮换了，放弃即可
-```
-
-#### 加人后轮换并分发密钥
-
-```python
-# 成员加入改变成员集，推荐先通过服务端 CAS 推进 epoch。
-status = await my_rpc_call("group.e2ee.get_epoch", {"group_id": group_id})
-cas = await my_rpc_call("group.e2ee.rotate_epoch", {"group_id": group_id, "current_epoch": status["epoch"], ...})
-if cas["success"]:
-    info = group_e2ee.rotate_epoch_to(group_id, cas["epoch"], updated_member_aids)
-    for dist in info["distributions"]:
-        p2p_e2ee_send(dist["to"], dist["payload"])
-```
-
-#### 解密失败时请求恢复
-
-当前 Python SDK 优先请求本地成员列表中的第一个候选者；零状态时退化为请求当前消息发送者。
-
-```python
-recovery = group_e2ee.build_recovery_request(
-    group_id, epoch, sender_aid=msg.get("sender_aid"),
-)
-if recovery:
-    p2p_e2ee_send(recovery["to"], recovery["payload"])
-# 频率限制：同群同 epoch 30 秒内不重复请求
-```
-
-#### 状态查询
-
-```python
-group_e2ee.has_secret(group_id)        # 是否持有密钥
-group_e2ee.current_epoch(group_id)     # 当前 epoch，无密钥返回 None
-group_e2ee.get_member_aids(group_id)   # 已知成员列表
-group_e2ee.load_all_secrets(group_id)  # {epoch: secret_bytes} 映射
-group_e2ee.cleanup(group_id)           # 清理过期旧 epoch（默认保留 7 天）
-```
+## V2 设备公钥与 SPK 管理
+
+连接成功后，SDK 会初始化本设备 V2 session，生成或加载 IK / SPK，并通过 `message.v2.put_peer_pk` 幂等注册当前 P2P 设备 SPK。群组路径会按群生成独立 group SPK，并通过 `group.v2.put_group_pk` 注册。应用层一般无需手动管理这些密钥。
+
+当前主路径的要点：
+
+- P2P 设备 SPK 的 `key_source` 为 `peer_device_prekey`，由 AID 私钥签名背书。
+- 群内独立 group SPK 的 `key_source` 为 `group_device_prekey`，按规范化后的 `group_aid` 隔离。
+- SDK 发送前通过 `message.v2.bootstrap` / `group.v2.bootstrap` 获取目标设备集合和当前 SPK。
+- 旧 SPK 会在本地保留一段安全窗口，用于解密引用旧 SPK 的历史消息；满足已消费和保留窗口条件后才销毁。
+
+裸 WebSocket 客户端如果绕过 SDK，需要自行完成同等的 SPK 生成、AID 私钥签名、注册和 bootstrap 逻辑。旧 `message.e2ee.put_prekey/get_prekey` 只用于 legacy `prekey_ecdh_v2` 信封兼容，不是当前 SDK 的默认路径。
+
+SPK 签名里的 `spk_timestamp` 使用 Unix 秒；消息、群事件和服务端 `timestamp` / `created_at` 等主路径时间字段仍使用 Unix 毫秒。
 
 ---
 
@@ -609,7 +360,7 @@ client = AUNClient(aid)
 | P2P 消息默认要求发送方签名 | 无 `sender_signature` 的消息被拒绝 |
 | 群组消息默认要求发送方签名 | `require_signature=True`，无签名或无发送方证书的消息被拒绝 |
 | 群组 E2EE 为固定启用能力 | `group_e2ee=true`，不可关闭 |
-| 默认要求前向保密 | `require_forward_secrecy=true`，无 prekey 时拒绝 long_term_key 降级 |
-| 客户端操作签名 | `group.send`/`group.kick`/`group.add_member`/`group.leave` 等操作自动附加 `client_signature`，服务端强制验签 |
+| 默认要求前向保密 | V2 优先使用设备 SPK 的 `3DH` wrap；缺少 SPK 的 `1DH` 路径仅作为兼容降级 |
+| 客户端操作签名 | SDK 会为关键操作附加 `client_signature`；Gateway 对 `send/pull/ack` 等常规 RPC 优先使用连接级身份认证，只有身份声明与连接不一致、敏感操作、能力身份或主动携签场景才执行 ECDSA 验签 |