@agentunion/fastaun-browser 0.5.0 → 0.5.1

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

@@ -56,16 +56,16 @@ 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。
 
 示例：
 
@@ -268,20 +268,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")   # 已知成员列表
-```
-
 ## 接收加密消息
 
 ### 推送接收
@@ -325,240 +311,6 @@ await client._upload_prekey()
 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 天）
 ```
 
 ---