@agentunion/fastaun-browser 0.4.13 → 0.5.1

package/_packed_docs/protocol/index.md

@@ -17,12 +17,13 @@
 | 06 | [06-服务协议.md](06-服务协议.md) | 业务层：message.* / meta.* / search.* / task.* / group.* + 跨域消息路由 |
 | 07 | [07-错误码与状态机.md](07-错误码与状态机.md) | 错误码汇总、各模式状态机、重试分类 |
 | E2EE | [08-AUN-E2EE.md](08-AUN-E2EE.md) | 端到端加密安全层（横跨三种模式） |
-| E2EE-Group | [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md) | 群组 E2EE：Epoch Group Key、Membership Commitment、密钥恢复 |
+| E2EE-Group | [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md) | 群组 E2EE V2：消息级密钥、逐设备密钥包裹、成员状态签名验证 |
 | 09 | [09-安全考虑.md](09-安全考虑.md) | 威胁模型、防护措施、升级安全、验签时序 |
 | 10 | [10-Group-子协议.md](10-Group-子协议.md) | `group.*` 群组管理、群消息、邀请码、资源共享、在线状态 |
 | 11 | [11-Storage-子协议.md](11-Storage-子协议.md) | `storage.*` 对象存储、大文件上传下载、预签名 URL |
 | 12 | [12-Stream-子协议.md](12-Stream-子协议.md) | `stream.*` 实时流式传输、WebSocket 推流、HTTP SSE 拉流、跨域拉流 |
 | 15 | [15-离线推送通知协议.md](15-离线推送通知协议.md) | `push.*` 离线推送、push_notify_aid 代理、事件通知 + 背压 ack、白名单与去重 |
+| 16 | [16-系统目录保护方案.md](16-系统目录保护方案.md) | `memberdata` 与 `group_data` 的系统目录保护、目录树隐藏/读下载/写保护边界、配额归属和访问矩阵 |
 
 **附录**：A-术语表 | B-扩展性 | C-私钥管理 | D-Root CA 治理 | E-Root CA 准入 | F-Issuer CA 申请 | G-孤儿 AID | H-Auth 实现 | I-跨域消息路由 | J-客户端接入 | K-Agent Web | L-E2EE 实现 | M-JWT 实现
 
@@ -56,7 +57,8 @@
 | 群消息收发（group.send/pull） | 10 §10.5 |
 | 群成员权限（owner/admin/member） | 10 §10.2 |
 | 邀请码（group.create_invite_code） | 10 §10.7 |
-| 群资源共享（group.resources.*） | 10 §10.9 |
+| 群文件系统（group.fs.*） | 10 §10.9 |
+| 系统目录保护（memberdata / group_data） | 16 |
 | 对象存储（storage.*） | 11 |
 | 实时流传输（stream.*） | 12 |
 | 推流（WebSocket） | 12 §12.6 推流端点 |
@@ -106,7 +108,7 @@ Gateway 模式定位与职责、Gateway 发现机制、连接时序（auth.* →
 独立安全层，横跨三种连接模式。定义客户端间 E2EE 加解密（prekey_ecdh_v2 四路 ECDH / long_term_key 两级降级）、prekey 管理、密文格式、AAD 防篡改、防重放保护。无需在线协商。
 
 ### AUN-E2EE-Group
-群组端到端加密规范。Epoch Group Key 机制（group_secret + HKDF 派生）、Membership Commitment（成员列表 SHA-256 摘要）、密钥分发与恢复协议、CAS epoch 轮换、群组密文格式与 AAD、防重放与降级防护。
+群组端到端加密规范（V2，当前唯一在用版本）。每条消息使用独立随机密钥，接收方按设备分别持有密钥包裹（wrap），不依赖群级共享对称密钥。成员状态通过签名版本链（state_version/state_chain）记录，接收方可据此检测状态分叉或篡改。群组密文格式、AAD 防篡改、防重放保护。
 
 ### 09-安全考虑
 威胁模型、传输层安全、认证安全、JWT 信任模型分析、连接升级安全（降级攻击/假地址注入/信令重放）、公开 AP 同步安全、证书轮换验签时序。
@@ -122,3 +124,8 @@ Gateway 模式定位与职责、Gateway 发现机制、连接时序（auth.* →
 
 ### 15-离线推送通知协议
 目标 AID 全部设备离线时的推送机制。push_notify_aid 作为普通客户端 AID 连接 Gateway，通过 `event/push.offline_message` 事件接收推送摘要（仅元数据，不含正文），处理后回 `push.ack` RPC 释放 in-flight 槽位（默认 max_in_flight=1 串行确认，30s 超时不重试）。聚合机制：同一 target_aid 60s 冷却期内合并为一条推送（unread_count++、senders 去重追加）。鉴权：push_token 由 push_notify_aid 自签自验，Gateway 仅透传不解析；push_notify_aid 必须在 Gateway 白名单内。跨域：推送由目标 AID 所属域的 Gateway 触发，push_notify_aid 必须与目标 AID 同域。
+
+### 16-系统目录保护方案
+定义 `memberdata` 与 `group_data` 的分层保护。`memberdata` 不是隐藏目录，但根和成员槽位根不可被普通文件操作破坏，group AID 命名空间下的普通 Storage 写入必须拒绝；`group_data` 是成员个人 Storage 内部真实根，Storage 服务端必须在目录树浏览中隐藏它，读/下载按普通 read 权限处理，写入、删除、重命名、挂载、授权和状态变更必须拒绝。文档同时规定 `group_data` 空间计入真实 owner AID 配额，group.fs 是可信授权写入路径，并给出访问矩阵、生命周期、审计和测试验收要求。
+
+

package/_packed_docs/protocol//350/215/211/346/241/210-agent.md/347/255/276/345/220/215/345/215/217/350/256/256.md

@@ -203,3 +203,5 @@ description: "An example agent"
 - 是否支持多签名（多个 AID 共同背书同一个 agent.md）？当前版本不支持
 - 是否定义签名过期后的"续签"流程？当前版本依赖重新签名
 - 是否把签名字段扩展到 agent.md 以外的 Agent Web 资源（如 index.html）？超出本草案范围
+
+

package/_packed_docs/protocol//350/215/211/346/241/210-/346/213/222/347/273/235/344/277/241/345/217/267/345/215/217/350/256/256.md

@@ -247,3 +247,5 @@ Alice  ──meta.reject(scope=all, reason=unknown_sender)──> Stranger
 - 群组场景下，`meta.reject` 是定向单发还是群内广播？当前草案倾向定向，但群主/管理员角色的语义需要配合 group 子协议进一步讨论
 - reject 是否要进入 E2EE 通道？建议**是**，保持与其他 meta.* 消息一致
 - 是否在 agent.md 里声明"本 agent 是否响应 reject 信号"？当前版本不需要——所有 AUN agent 默认尊重
+
+

package/_packed_docs/protocol//351/231/204/345/275/225A-/346/234/257/350/257/255/350/241/250.md

@@ -335,3 +335,5 @@ E2EE 加密时生成的一次性 ECDH 密钥对，用于与接收方 prekey（
 - ❌ JWT Token（应使用 JWT token，小写 token）
 
 ---
+
+

package/_packed_docs/protocol//351/231/204/345/275/225B-/346/211/251/345/261/225/346/200/247/346/214/207/345/215/227.md

@@ -78,3 +78,5 @@ gateway:
 - 引入新的认证机制（保持 AID 双向挑战）
 
 ---
+
+

package/_packed_docs/protocol//351/231/204/345/275/225C-/347/247/201/351/222/245/347/256/241/347/220/206/344/270/216/350/272/253/344/273/275/346/201/242/345/244/215.md

@@ -702,3 +702,5 @@ auth.guardian_approve
 ```
 
 ---
+
+

package/_packed_docs/protocol//351/231/204/345/275/225D-Root_CA_/346/262/273/347/220/206/346/234/272/345/210/266.md

@@ -618,3 +618,5 @@ STH 用于证明某一时刻日志树的大小和根哈希。监控方应定期
 - 邮件列表：governance@aun.network
 - GitHub：https://github.com/aun-network/governance
 - 应急联系：security@aun.network
+
+

package/_packed_docs/protocol//351/231/204/345/275/225E-Root_CA_/345/207/206/345/205/245/346/265/201/347/250/213.md

@@ -603,3 +603,5 @@ A：管理局会要求整改，如果拒绝整改或整改不力，可能被吊
 - 申请咨询：`root-ca-applications@aun.network`
 - 技术支持：`technical-support@aun.network`
 - 官方网站：`https://aun.network/root-ca`
+
+

package/_packed_docs/protocol//351/231/204/345/275/225F-Issuer_CA_/347/224/263/350/257/267/346/265/201/347/250/213.md

@@ -546,3 +546,5 @@ Issuer CT 服务必须提供以下公开 HTTP 端点，不要求鉴权：
 | WebPKI Root → Intermediate → EE | Root → Registry → Issuer → Agent | 多级 CA 层级 | AUN 多一级（Registry CA） |
 
 AUN 的 Registry CA 在线签发模式借鉴了 ACME 协议的自动化理念，在保证 Root CA 离线安全的前提下，将 Issuer CA 签发时间从数周缩短到分钟级。
+
+

package/_packed_docs/protocol//351/231/204/345/275/225G-AID_/345/255/244/345/204/277/351/242/204/351/230/262/344/270/216/346/225/221/346/217/264/346/234/272/345/210/266.md

@@ -511,3 +511,5 @@ Issuer CA 运营商应将域名托管在第三方托管服务：
 - **多重保障**：技术、法律、财务多管齐下
 - **用户赋能**：提供工具让用户可以自救
 - **社区互助**：通过信任网络实现社交恢复
+
+

package/_packed_docs/protocol//351/231/204/345/275/225H-Identity/346/234/215/345/212/241/345/256/236/347/216/260/346/214/207/345/215/227.md

@@ -617,3 +617,5 @@ access_token 过期后，用 refresh_token 换取新的 access_token
 - 黑名单条目在 token 自然过期后自动清理
 
 ---
+
+

package/_packed_docs/protocol//351/231/204/345/275/225I-/350/267/250/345/237/237/346/266/210/346/201/257/350/267/257/347/224/261/345/256/236/347/216/260/346/214/207/345/215/227.md

@@ -490,3 +490,5 @@ logger.info("cross_domain_route", extra={
 3. 使用标准 message.send 方法，格式与本域一致
 4. 注意 TLS 验证、限流、监控
 
+
+

package/_packed_docs/protocol//351/231/204/345/275/225J-/345/256/242/346/210/267/347/253/257/346/216/245/345/205/245/347/244/272/344/276/213.md

@@ -400,3 +400,5 @@ ws.onmessage = async (event) => {
 ```
 
 ---
+
+

package/_packed_docs/protocol//351/231/204/345/275/225K-Agent_Web/345/217/221/347/216/260/345/215/217/350/256/256.md

@@ -128,3 +128,5 @@ https://{aid}.{issuer_domain}/{svc}
 - `index.html` 是 Agent 面向人类用户的默认首页
 
 这使 AUN 在保持去中心化身份体系的同时，也为 Agent 的公开发现、说明页、服务页和后续生态扩展提供了统一入口。
+
+

package/_packed_docs/protocol//351/231/204/345/275/225L-E2EE/345/256/236/347/216/260/346/214/207/345/215/227.md

@@ -265,3 +265,5 @@ AES-GCM + AAD 验证保证消息完整性。AAD 包含以下字段，按 Canonic
 ## L.7 兼容性说明
 
 - 发送端 **MUST** 使用 `prekey_ecdh_v2`（四路 ECDH）模式发送新消息
+
+

package/_packed_docs/protocol//351/231/204/345/275/225M-JWT/350/256/244/350/257/201/345/256/236/347/216/260/346/214/207/345/215/227.md

@@ -365,3 +365,5 @@ Auth 服务证书轮换直接影响 JWT 验证，需特别处理：
 - 证书被吊销
 
 ---
+
+

package/_packed_docs/protocol//351/231/204/345/275/225N-/345/210/206/345/270/203/345/274/217Trace/345/215/217/350/256/256.md

@@ -255,3 +255,5 @@ if effective != client_mode:
 ## 文档版本
 
 - v1.0 — 2026-05-21 初稿，定义协议字段、链路传播、开关层级、安全约束
+
+

package/_packed_docs/sdk/01-/345/277/253/351/200/237/345/274/200/345/247/213.md

@@ -202,3 +202,5 @@ client := aun.NewAUNClient(aid.Data.AID)
 6. 通过 `close()` 释放连接和后台任务。
 
 详细 API 见 [06-API手册.md](06-API手册.md)，RPC 参数见各领域的 `09-*-rpc-manual.md`。
+
+

package/_packed_docs/sdk/02-WebSocket/345/215/217/350/256/256.md

@@ -356,3 +356,5 @@ async def main():
 
 asyncio.run(main())
 ```
+
+

package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md

@@ -166,3 +166,5 @@ client.on("message.received", lambda e: print(e["payload"]))
 ```
 
 RPC 方法参数见 `09-message-rpc-manual.md`、`09-group-rpc-manual.md`、`09-storage-rpc-manual.md` 等专项手册。
+
+

package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md

@@ -260,3 +260,5 @@ RPC 方法完整参数和响应格式见：
 | 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
 | 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
 | 元信息 | [09-meta-rpc-manual.md](09-meta-rpc-manual.md) |
+
+

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 天）
 ```
 
 ---
@@ -611,3 +363,5 @@ client = AUNClient(aid)
 | 群组 E2EE 为固定启用能力 | `group_e2ee=true`，不可关闭 |
 | 默认要求前向保密 | `require_forward_secrecy=true`，无 prekey 时拒绝 long_term_key 降级 |
 | 客户端操作签名 | `group.send`/`group.kick`/`group.add_member`/`group.leave` 等操作自动附加 `client_signature`，服务端强制验签 |
+
+