@agentunion/fastaun-browser 0.5.0 → 0.5.1

package/_packed_docs/protocol/08-AUN-E2EE-Group.md

@@ -1,902 +1,296 @@
-# AUN-E2EE 群组扩展规范
-
-> 版本：1.0-draft
-> 状态：规范性文档
-> 适用范围：AUN 客户端 SDK、客户端应用、跨语言实现
-> 不适用范围：Group Service 服务端加解密实现
-> 前置依赖：[08-AUN-E2EE](./08-AUN-E2EE.md)（P2P E2EE 规范）、[10-Group-子协议](./10-Group-子协议.md)
-> 定位：**群组消息端到端加密层**，基于 Epoch Group Key 机制
-
----
-
-## 1. 目标与边界
-
-本规范定义 AUN 群组成员之间的端到端消息加密协议。
-
-### 1.1 目标
-
-- 让群组内的 N 个成员在现有 `group.send` / `event/group.message_created` 之上实现端到端加密
-- 让 Group Service 仅看到最小必要路由元数据和密文 payload
-- 保持与 P2P E2EE 一致的**无状态设计**——每条群消息独立可解密，不依赖任何历史状态
-- 为各语言 SDK 提供统一的群组密文格式、密钥分发协议和恢复机制
-
-### 1.2 服务端职责
-
-Group Service **只做**：
-
-- 认证发送方（JWT token）
-- 校验群成员权限
-- 透传 `encrypted: true` 的 payload
-- 存储和广播密文 payload
-- **Epoch 版本协调**：提供 `group.e2ee.get_epoch` 和 `group.e2ee.rotate_epoch` RPC，作为 epoch 版本的 CAS（Compare-And-Swap）同步点，确保并发轮换不冲突
-
-Group Service **绝不做**：
-
-- 加解密群消息
-- 持有或管理 group_secret 明文
-- 参与密钥协商或密钥派生
-
-### 1.3 设计原则
-
-| 原则 | 说明 |
-|------|------|
-| **无状态** | 每条消息独立派生密钥，不维护链式状态，不可能断链 |
-| **复用 P2P E2EE** | group_secret 分发完全复用 P2P E2EE 通道（prekey_ecdh_v2 / long_term_key） |
-| **不信任服务端** | group_secret 从未经过服务端明文，通过成员列表承诺辅助检测注入 |
-| **最小状态** | 每个群客户端需保存 `epoch`、`group_secret`、`commitment`、`member_aids`、`updated_at`；可选保留 `old_epochs[]` 用于历史消息解密 |
-
-### 1.4 无状态设计哲学
-
-本规范延续 P2P E2EE（[08-AUN-E2EE](./08-AUN-E2EE.md) §2）确立的**完全无状态**工程哲学。
-
-经典群组 E2EE 方案（Signal Sender Keys、MLS TreeKEM、ANP Group Session）均维护有状态的密钥链：每个 sender 持有 hash chain，接收方需要同步 chain_index，消息必须按序处理。这在 Agent 场景下带来严重的工程风险：
-
-| 有状态群组方案的代价 | AUN 场景下的问题 |
-|-------------------|----------------|
-| 每个 sender 一个 chain state | Agent 数量动态变化，状态管理复杂 |
-| 消息乱序需要缓存跳过的密钥 | Agent 通信天然异步，乱序是常态 |
-| chain_index 不同步导致断链 | 断链后整个群组通信中断，不可接受 |
-| 状态丢失不可恢复（独立 Sender Keys） | Agent 重启频繁 |
-
-AUN Group E2EE 选择 **Epoch Group Key**——每条消息从 group_secret + message_id 独立派生密钥，不维护任何链式状态：
-
-- **不可能断链**：消息乱序、丢失、客户端重启均不影响解密
-- **状态可恢复**：group_secret 在手，任何消息都能解密；丢失时可向任意成员请求补发
-- **O(n) 分发**：无需每个 sender 逐人广播 chain key（Signal/ANP 为 O(n²)）
-
-代价是放弃 epoch 内前向安全（同一 epoch 内的消息共享 group_secret），通过**缩短 epoch 生命周期**（定时轮换）来弥补。
-
----
-
-## 2. 与 AUN-Core 的关系
-
-AUN-E2EE-Group 建立在以下核心能力之上：
-
-- **P2P E2EE**（08-AUN-E2EE）：group_secret 分发通道
-- **Group 子协议**（10-Group-子协议）：群组管理、成员管理、消息传输
-- **AID + 证书链身份体系**：成员身份验证
-
-群组密文消息通过 `group.send` 承载；Group Service 无需识别 payload 内部字段。
-
----
-
-## 3. 术语
-
-### 3.1 Epoch
-
-群组密钥的版本号。每次需要轮换 group_secret 时，epoch 递增。epoch 从 1 开始。
-
-### 3.2 Group Secret
-
-群组对称密钥。256 位随机字节，用于派生每条群消息的加密密钥。每个 epoch 对应一个独立的 group_secret。
-
-### 3.3 Epoch Key Distribution
-
-通过 P2P E2EE 通道向群组成员分发 group_secret 的过程。
-
-### 3.4 Membership Commitment
-
-群成员列表的 SHA-256 摘要，用于防止服务端篡改成员列表。
-
-### 3.5 密文群消息
-
-通过 `group.send` 传输的加密群消息，`encrypted` **MUST** 为 `true`，`payload.type` **MUST** 为 `e2ee.group_encrypted`。
-
----
-
-## 4. 算法套件
-
-与 P2P E2EE 保持一致：
-
-- **MUST** 支持 `P256_HKDF_SHA256_AES_256_GCM`
-- **MAY** 支持其他套件
-
-### 4.1 密钥派生
-
-每条群消息的加密密钥从 group_secret 独立派生：
-
-```
-msg_key = HKDF-SHA256(
-    ikm    = group_secret,
-    salt   = None,
-    info   = "aun-group:{group_id}:msg:{message_id}",
-    length = 32
-)
-```
-
-- `group_id`：群组唯一标识
-- `message_id`：消息 UUID，由**发送方客户端**在加密前生成（格式 `gm-{uuid}`），写入 AAD 并参与密钥派生。注意：Group Service 会在外层消息记录中填充自己的 `message_id`，该值与 AAD 中的 `message_id` 可能不同。解密时 **MUST** 使用 AAD 中的 `message_id`。
-
-### 4.2 消息加密
-
-```
-nonce      = random(12 bytes)
-aad_bytes  = canonical_json(aad)
-ciphertext = AES-256-GCM(msg_key, nonce, plaintext, aad_bytes)
-```
-
-### 4.3 消息解密
-
-接收方从密文 payload 内部的 `aad` 字段读取 `group_id` 和 `message_id`（即发送方加密时写入的原始值），结合本地持有的 `group_secret`，执行相同的 HKDF 派生和 AES-256-GCM 解密。
-
-> **实现注意**：外层消息记录中的 `message_id`、`sender_aid` 由 Group Service 填充，可能与 AAD 中的值不同。密钥派生和 AAD 校验 **MUST** 以 payload 内部的 `aad` 为准。同时，接收方 **MUST** 校验外层 `group_id` 与 AAD 中的 `group_id` 一致，外层 `sender_aid`/`from` 与 AAD 中的 `from` 一致，不一致时拒绝解密。
-
----
-
-## 5. Epoch 生命周期
-
-### 5.1 Epoch 轮换触发条件
-
-| 触发条件 | 是否 MUST 轮换 | 说明 |
-|----------|:-----------:|------|
-| 成员被踢出（`group.kick`） | **MUST** | 离开者仍持有旧 group_secret |
-| 成员主动退出（`group.leave`） | **MUST** | 离开者仍持有旧 group_secret；剩余在线 admin/owner 负责轮换，离开者自身不执行轮换 |
-| 成员加入（`group.add_member`） | **MUST** | 新成员加入会改变成员集；服务端记录 `min_read_epoch = join_epoch + 1`，客户端 MUST 轮换后再向新成员分发新 epoch 密钥 |
-| 定时轮换 | **MAY** | 缩小密钥泄露窗口，建议每 24 小时 |
-| 管理员手动轮换 | **MAY** | 怀疑密钥泄露时主动触发 |
-| 群组解散（`group.dissolve`） | 不适用 | 群组不再存在 |
-
-### 5.2 Epoch 轮换流程
-
-```
-1. 触发者（admin/owner）生成新的 group_secret：
-   group_secret = random(32 bytes)
-   epoch += 1
-
-2. 计算 Membership Commitment（§6）
-
-3. 构建并签名 Membership Manifest（§6A）
-
-4. 通过 P2P E2EE 逐个分发给每个当前成员：
-   for member in current_members:
-       p2p_encrypt_send(member, {
-           type: "e2ee.group_key_distribution",
-           group_id,
-           epoch,
-           group_secret,           // 32 bytes, base64
-           commitment,             // SHA-256 hex
-           member_aids,            // 排序后的完整成员 AID 列表
-           distributed_by,         // 分发者 AID
-           distributed_at,         // 分发时间戳（ms）
-           manifest                // 签名的 Membership Manifest（§6A）
-       })
-
-4. 本地持久化新的 group_secret 和 epoch
-5. 安全擦除旧的 group_secret（MAY 保留至旧 epoch 消息超时）
-```
-
-### 5.2.1 Epoch CAS 轮换 RPC
-
-通过 `group.e2ee.rotate_epoch` RPC 在服务端进行 CAS（Compare-And-Swap）轮换。
-
-**必填参数**：
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `group_id` | string | 群组标识 |
-| `current_epoch` | int | 当前 epoch（CAS 条件） |
-| `rotation_signature` | string | base64 编码的 ECDSA 签名 |
-| `rotation_timestamp` | string | 签名时间戳（Unix 秒），5 分钟新鲜度窗口 |
-
-**签名输入**：`"{group_id}|{current_epoch}|{new_epoch}|{aid}|{rotation_timestamp}"`
-
-服务端 **MUST** 验证签名有效性、时间戳新鲜度，并拒绝重复签名。
-
-### 5.3 新成员加入
-
-新成员加入时 **MUST** 触发 epoch 轮换。服务端在成员写入时 **MUST** 记录加入时的 `join_epoch`，并将该成员的 `min_read_epoch` 设置为 `join_epoch + 1`（若群组尚未启用 E2EE epoch，则为 0）。因此，新成员 **MUST NOT** 获得加入前 epoch 的 group_secret。
-
-执行加入操作的 admin/owner，或成员变更事件选举出的在线 owner/admin leader，**MUST** 通过 `group.e2ee.rotate_epoch` 完成 CAS 轮换，然后通过 P2P E2EE 向当前成员（包含新成员）分发新 epoch 的 group_secret：
-
-```
-p2p_encrypt_send(new_member, {
-    type: "e2ee.group_key_distribution",
-    group_id,
-    epoch,                     // 新 epoch
-    group_secret,
-    commitment,
-    member_aids,               // 含新成员的列表
-    distributed_by,
-    distributed_at,
-    manifest                   // 签名的 Membership Manifest（§6A）
-})
-```
-
-新成员收到后只能解密新 epoch 及之后的群消息。若轮换尚未完成，服务端 **SHOULD** 拒绝新成员发送低于 `min_read_epoch` 的群组 E2EE 消息，并返回“epoch rotation pending”类错误。
-
-### 5.4 分发职责
-
-group_secret 的分发 **MUST NOT** 依赖单一节点：
-
-| 场景 | 分发者 |
-|------|--------|
-| 踢人 | 执行 `group.kick` 的 admin/owner |
-| 成员退出 | 剩余在线 admin/owner（离开者不执行轮换） |
-| 加人/审批通过/邀请码入群 | 执行操作的 admin/owner 或成员变更事件选举出的在线 owner/admin leader |
-| 定时轮换 | 任意在线 admin/owner |
-| 密钥补发 | 任意持有当前 group_secret 的成员（§8） |
-
-### 5.5 历史消息访问策略
-
-| 策略 | 行为 | 适用场景 |
-|------|------|---------|
-| **加入前历史隔离**（默认且唯一） | 加入时触发 epoch 轮换，新成员只拿到新 group_secret；服务端通过 `min_read_epoch` 阻止其使用旧 epoch | 所有群组 |
-
-如业务需要向新成员开放入群前历史，**MUST** 在应用层通过单独的历史授权、导出或重加密流程实现，不得复用加入前的 group_secret。
-
----
-
-## 6. Membership Commitment
-
-### 6.1 目的
-
-让所有群成员能够**检测**成员列表篡改。当分发者将 group_secret 发送给群成员时，附带一个基于成员列表的哈希摘要。接收方通过重算摘要来验证自己收到的成员列表是否自洽。
-
-> **局限性**：Membership Commitment 是纯哈希校验，不包含密码学签名。它能确保所有成员收到的列表一致（一致性检测），但**不能**独立阻止恶意分发者构造虚假列表。防御幽灵成员注入的有效性依赖于：(1) 合法成员能从其他渠道（如 `group.get_members` RPC）获取可信成员列表并比对；(2) 多个成员的 commitment 互相印证。
-
-### 6.2 计算方式
-
-```
-commitment = SHA-256(
-    sort(member_aids).join("|") + "|" + str(epoch) + "|" + group_id + "|" + SHA-256(group_secret).hex()
-)
-```
-
-其中：
-- `sort(member_aids)` 为所有当前群成员的 AID 按字典序升序排列
-- `SHA-256(group_secret).hex()` 为 group_secret（32 字节原始密钥）的 SHA-256 哈希的十六进制表示
-- 将 group_secret 的哈希绑定到 commitment 中，防止恶意分发者替换密钥但保持 commitment 不变
-
-### 6.3 验证流程
-
-接收方收到 `e2ee.group_key_distribution` 消息后 **MUST**：
-
-1. 验证 `commitment == SHA-256(sort(member_aids) + "|" + epoch + "|" + group_id + "|" + SHA-256(group_secret).hex())`
-2. 验证自己的 AID 在 `member_aids` 列表中
-3. 如果 `member_aids` 与本地已知的成员列表存在差异，**SHOULD** 向用户发出告警
-4. **SHOULD** 通过 `group.get_members` RPC 获取服务端成员列表进行比对（如果可用）
-
-### 6.4 防护效果
-
-| 攻击 | 防护级别 | 说明 |
-|------|:-------:|------|
-| 成员列表不一致 | ✅ 检测 | 所有人收到同一个 commitment，可互相比对 |
-| 幽灵成员注入（分发者被骗） | ⚠️ 辅助检测 | 合法成员看到完整列表后有机会发现异常 AID，但需要额外的可信成员列表源进行比对 |
-| 幽灵成员注入（分发者串通） | ❌ 无法防御 | commitment 由分发者构造，串通场景下哈希无意义 |
-| epoch 轮换阻断 | ⚠️ 需检测 | 需要客户端检测：成员变更事件后应在合理时间内收到新 epoch |
-| 选择性消息丢弃 | ❌ 无法防御 | 加密层无法解决，需消息确认/回执机制 |
-
----
-
-## 6A. Membership Manifest（成员变更授权凭证）
-
-### 6A.1 目的
-
-Membership Commitment（§6）是纯哈希检测，无法证明「谁发起了这次成员变更」。Membership Manifest 补充了密码学签名层，让接收方能验证：
-
-- **谁**发起了 epoch 轮换（`initiator_aid`）
-- **哪些成员**被添加或移除（`added`、`removed`）
-- 该操作经过了**合法授权**（ECDSA 签名）
-
-### 6A.2 Manifest 结构
-
-```json
-{
-  "manifest_version": 1,
-  "group_id": "g-abc123.agentid.pub",
-  "epoch": 2,
-  "prev_epoch": 1,
-  "member_aids": ["alice.agentid.pub", "bob.agentid.pub", "carol.agentid.pub"],
-  "added": ["carol.agentid.pub"],
-  "removed": [],
-  "initiator_aid": "alice.agentid.pub",
-  "issued_at": 1710504000000,
-  "signature": "base64(ECDSA-SHA256)"
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `manifest_version` | integer | Manifest 格式版本，当前为 `1` |
-| `group_id` | string | 群组标识 |
-| `epoch` | integer | 本次轮换后的 epoch |
-| `prev_epoch` | integer / null | 上一个 epoch（首次创建时为 `null`） |
-| `member_aids` | string[] | 本 epoch 的完整成员列表（排序） |
-| `added` | string[] | 本次新增的成员 |
-| `removed` | string[] | 本次移除的成员 |
-| `initiator_aid` | string | 发起者 AID |
-| `issued_at` | integer | 签发时间戳（ms） |
-| `signature` | string | 发起者对 manifest 内容的 ECDSA-SHA256 签名 |
-
-### 6A.3 签名载荷
-
-签名覆盖除 `signature` 字段外的所有字段，序列化方式：
-
-```
-sign_data = canonical_json(manifest_without_signature)
-// canonical_json: sort_keys=True, separators=(",",":"), ensure_ascii=False
-signature = ECDSA-SHA256(initiator_private_key, sign_data)
-```
-
-### 6A.4 验证流程
-
-接收方收到包含 `manifest` 的 `e2ee.group_key_distribution` 消息后 **SHOULD**：
-
-1. 从本地缓存获取 `initiator_aid` 的证书公钥
-2. 验证 `signature`
-3. 检查 `member_aids` 与 manifest 中 `added`/`removed` 的一致性
-4. 检查 `epoch` == `prev_epoch + 1`（首次创建时 `prev_epoch` 为 `null`）
-5. 验签失败时 **SHOULD** 拒绝该 distribution（返回 `"distribution_rejected"`）
-
-> **注意**：Manifest 验证是**建议性的**（SHOULD），不是强制性的。这是因为在某些场景下（如跨域成员加入），接收方可能尚未缓存发起者证书。实现 **MAY** 在验签失败时仍接受 distribution，但 **MUST** 在后台尝试获取发起者证书并进行延迟验证。
-
----
-
-## 7. 消息格式与 AAD
-
-### 7.1 群组密文 payload
-
-```json
-{
-  "type": "e2ee.group_encrypted",
-  "version": "1",
-  "encryption_mode": "epoch_group_key",
-  "suite": "P256_HKDF_SHA256_AES_256_GCM",
-  "epoch": 3,
-  "nonce": "base64(12 bytes)",
-  "ciphertext": "base64",
-  "tag": "base64(16 bytes)",
-  "sender_signature": "base64(ECDSA-SHA256 over ciphertext+tag+aad_bytes)",
-  "sender_cert_fingerprint": "sha256:hex",
-  "aad": {
-    "group_id": "g-abc123.agentid.pub",
-    "from": "alice.agentid.pub",
-    "message_id": "gm-550e8400-...",
-    "timestamp": 1710504000000,
-    "epoch": 3,
-    "encryption_mode": "epoch_group_key",
-    "suite": "P256_HKDF_SHA256_AES_256_GCM"
-  }
-}
-```
-
-**发送方签名**：
-
-- 发送方 **MUST** 用身份私钥对 `ciphertext_bytes + tag_bytes + aad_bytes` 执行 ECDSA-SHA256 签名
-- `sender_cert_fingerprint` 用于接收方查找发送方证书
-- 接收方 **MUST** 验证 `sender_signature`，缺失或验签失败时 **MUST** 拒绝该消息
-
-### 7.2 外层 group.send 信封
-
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "group.send",
-  "params": {
-    "group_id": "g-abc123.agentid.pub",
-    "type": "e2ee.group_encrypted",
-    "payload": { "<上述密文 payload>" },
-    "encrypted": true
-  }
-}
-```
-
-### 7.3 AAD 字段
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `group_id` | string | 群组唯一标识 |
-| `from` | string | 发送方 AID |
-| `message_id` | string | 消息唯一标识（发送方客户端生成，参与密钥派生） |
-| `timestamp` | integer | 发送时间戳（ms） |
-| `epoch` | integer | 当前密钥版本号 |
-| `encryption_mode` | string | 固定为 `epoch_group_key` |
-| `suite` | string | 算法套件标识 |
-
-AAD 序列化方式与 P2P E2EE（§8.3）一致：递归键排序 + 紧凑格式 + UTF-8 直接输出（`ensure_ascii=False`），详见 P2P E2EE §8.3 的完整规范。
-
-### 7.4 明文信封字段（服务端可见）
-
-以下字段保持为 Group Service 可见的明文，用于路由和存储：
-
-| 字段 | 说明 |
-|------|------|
-| `group_id` | 群组标识（路由用） |
-| `type` | 固定为 `e2ee.group_encrypted` |
-| `encrypted` | 固定为 `true` |
-
-`message_id`、`seq`、`sender_aid`、`created_at` 由 Group Service 自动填充到消息记录中。
-
-> **外层与 AAD 绑定校验**：接收方 **MUST** 校验外层 `group_id` 与 AAD 中的 `group_id` 一致（防止跨群路由篡改），外层 `from`/`sender_aid` 与 AAD 中的 `from` 一致（防止发送者冒充）。不一致时 **MUST** 拒绝解密。
-
----
-
-## 8. 密钥恢复机制
-
-### 8.1 场景
-
-以下场景可能导致成员缺失当前 epoch 的 group_secret：
-
-- P2P 分发消息丢失（网络故障）
-- 客户端重启后本地存储损坏
-- 成员离线期间发生了 epoch 轮换
-
-### 8.2 Epoch Key Request
-
-缺失密钥的成员 **MAY** 向群内候选成员发送密钥请求（SDK 优先从本地成员列表选择，零状态时退化为向当前消息发送者请求）：
-
-```json
-{
-  "type": "e2ee.group_key_request",
-  "group_id": "g-abc123.agentid.pub",
-  "epoch": 3,
-  "requester_aid": "bob.agentid.pub"
-}
-```
-
-此消息 **MUST** 通过 P2P E2EE 通道发送。
-
-### 8.3 Epoch Key Response
-
-收到请求的成员 **MUST** 先验证请求者确实是当前群成员（通过 `group.get_members` 或本地缓存），然后 **MAY** 回复：
-
-```json
-{
-  "type": "e2ee.group_key_response",
-  "group_id": "g-abc123.agentid.pub",
-  "epoch": 3,
-  "group_secret": "base64(32 bytes)",
-  "commitment": "sha256hex",
-  "member_aids": ["alice.agentid.pub", "bob.agentid.pub", "carol.agentid.pub"]
-}
-```
-
-此消息 **MUST** 通过 P2P E2EE 通道发送。
-
-### 8.4 安全约束
-
-- 响应者 **MUST** 验证请求者是群成员后才能回复
-- 请求者 **MUST** 验证 commitment 和 member_aids 的一致性（§6.3）
-- 实现 **SHOULD** 对 key_request 做频率限制，防止被滥用
-
-### 8.5 恢复时序
-
-密钥恢复是**异步过程**：
-
-1. 成员收到无法解密的群消息（epoch 不匹配或无密钥）
-2. SDK 自动向候选成员发送 `e2ee.group_key_request`（优先本地已知成员，零状态时向消息发送者请求）
-3. 在线成员验证请求者身份后回复 `e2ee.group_key_response`
-4. 请求者收到响应后存储 group_secret，后续 pull 或再次收到消息时才能成功解密
-
-> `group.use_invite_code` 加入群组后不保证立即拥有 group_secret。SDK 会在后续群消息解密失败时自动发起恢复请求。
-
----
-
-## 9. 客户端密钥存储
-
-### 9.1 存储位置
-
-group_secret **MUST** 持久化到本地存储。推荐存储在 FileKeyStore 的 metadata 中：
-
-```
-~/.aun/AIDs/{safe_aid}/tokens/meta.json
-```
-
-### 9.2 存储结构
-
-在 metadata 中新增 `group_secrets` 字段：
-
-```json
-{
-  "e2ee_prekeys": { "..." },
-  "group_secrets": {
-    "g-abc123.agentid.pub": {
-      "epoch": 3,
-      "secret_protection": {
-        "scheme": "dpapi",
-        "name": "group_secrets/g-abc123.agentid.pub/secret",
-        "persisted": true,
-        "blob": "base64(...)"
-      },
-      "commitment": "sha256hex...",
-      "member_aids": ["alice.agentid.pub", "bob.agentid.pub"],
-      "updated_at": 1710504000000,
-      "old_epochs": [
-        {
-          "epoch": 2,
-          "secret_protection": { "..." },
-          "commitment": "sha256hex...",
-          "member_aids": ["alice.agentid.pub", "bob.agentid.pub", "carol.agentid.pub"],
-          "updated_at": 1710500000000
-        }
-      ]
-    }
-  }
-}
-```
-
-> **说明**：`old_epochs` 数组保留旧 epoch 的密钥信息，用于解密历史消息。保留期由 `old_epoch_retention_seconds`（默认 7 天）控制，过期后由 SDK 自动清理。
-
-### 9.3 敏感字段保护
-
-- `group_secret` 的明文 **MUST NOT** 直接写入磁盘
-- **MUST** 通过 SecretStore（DPAPI / Keychain / libsecret）保护
-- 存储格式与 P2P prekey 私钥保护方式一致：明文替换为 `secret_protection` 记录
-
-保护流程：
-
-```
-写入时：
-  secret_name = f"group_secrets/{group_id}/secret"
-  record["secret_protection"] = secret_store.protect(scope, secret_name, group_secret)
-  // group_secret 明文不落盘
-
-读取时：
-  group_secret = secret_store.reveal(scope, secret_name, record["secret_protection"])
-```
-
-### 9.4 旧 Epoch 密钥保留
-
-- 实现 **MAY** 保留旧 epoch 的 group_secret 一段时间（建议 7 天），用于解密在途或离线期间的历史消息
-- 旧 epoch 密钥 **SHOULD** 在保留期过后安全擦除
-- 旧 epoch 密钥 **MUST NOT** 用于加密新消息
-
----
-
-## 10. 防重放与防篡改
-
-### 10.1 防篡改
-
-所有路由关键字段纳入 AAD（§7.3），任何篡改导致 AES-GCM tag 校验失败：
-
-- `group_id` 被篡改 → AAD mismatch → 解密异常
-- `from`（sender_aid）被替换 → AAD mismatch → 解密异常
-- `epoch` 被篡改 → HKDF 派生出错误的 msg_key → 解密失败
-- `message_id` 被篡改 → msg_key 派生不同 + AAD mismatch → 解密失败
-
-### 10.2 防重放
-
-群组消息的防重放与 P2P 一致：
-
-- 接收方 **MUST** 维护本地 `seen_messages` 集合
-- 以 `{group_id}:{sender_aid}:{message_id}` 为 key 去重
-- 同一 key 的消息 **MUST** 被拒绝
-
-### 10.3 Epoch 降级防护
-
-- 接收方 **MUST** 拒绝 epoch 低于本地已知最新 epoch 的加密消息
-- 例外：如果实现保留了旧 epoch 密钥（§9.4），**MAY** 允许解密旧 epoch 消息。实现可选择在解密结果中标记 `historical: true`，但不做强制要求
-
----
-
-## 11. 安全约定
-
-### 11.1 通用约定
-
-- 加密失败时 **MUST NOT** 静默降级为明文
-- 每条消息使用独立的随机 nonce
-- group_secret **MUST** 由密码学安全随机数生成器生成
-- 实现 **MUST NOT** 在日志中输出 group_secret 或 msg_key
-
-### 11.2 分发通道安全
-
-- group_secret 的分发 **MUST** 通过 P2P E2EE 通道（prekey_ecdh_v2 或 long_term_key 模式）
-- 分发消息的发送方身份 **MUST** 通过 P2P E2EE 的 AAD 机制验证
-- 分发消息 **SHOULD** 附带签名的 Membership Manifest（§6A）
-
-### 11.3 客户端操作签名
-
-以下群组操作 **MUST** 附加客户端 ECDSA 签名（`client_signature` 字段），服务端强制验签：
-
-- `group.send`
-- `group.add_member`
-- `group.kick`
-- `group.leave`
-- `group.update_rules`
-
-#### 11.3.1 签名生成
-
-签名数据格式：`"{method}|{aid}|{timestamp}|{params_hash}"`
-
-其中：
-- `method`：RPC 方法名（如 `group.send`）
-- `aid`：当前认证的 AID
-- `timestamp`：当前 Unix 时间戳（秒，字符串形式）
-- `params_hash`：业务参数的 SHA-256 哈希（十六进制小写），计算方法见 §11.3.2
-
-签名算法：ECDSA-SHA256，使用身份私钥签名上述字符串的 UTF-8 编码。
-
-`client_signature` 字段结构：
-
-```json
-{
-  "aid": "alice.agentid.pub",
-  "timestamp": "1775541042",
-  "params_hash": "a3b2c1d4e5f6...",
-  "signature": "<base64 DER-encoded ECDSA signature>"
-}
-```
-
-#### 11.3.2 params_hash 计算（Canonical JSON 规范）
-
-`params_hash` 的计算输入是业务参数的**规范化 JSON 序列化**（Canonical JSON for AUN），与 AAD 序列化规则（P2P E2EE §8.3）完全一致：
-
-1. **字段筛选**：排除 `client_signature` 字段和所有 `_` 前缀字段（`_auth`、`_session_id` 等由网关/服务端注入的内部字段）
-2. **键排序**：所有对象（包括嵌套对象）的键 **MUST** 按 Unicode 码点升序排列（递归排序）
-3. **紧凑格式**：无多余空白，键值对之间用 `,`，键和值之间用 `:` 分隔
-4. **UTF-8 直接输出**：非 ASCII 字符（如中文）**MUST** 直接以 UTF-8 编码输出，**MUST NOT** 转义为 `\uXXXX`
-5. **数值精度**：整数值 **MUST** 序列化为不带小数点的十进制数（如 `42` 而非 `42.0`）
-6. **布尔值**：`true` / `false`（小写）
-7. **空值**：`null`
-
-等价的 Python 实现：`json.dumps(params, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`
-
-> **设计决策：** `params_hash` 与 AAD 使用完全相同的 Canonical JSON 规范（`ensure_ascii=False`），避免协议内两套序列化规则导致实现混乱。Go 的 `json.Marshal` 和 JavaScript 的 `JSON.stringify` 天然满足 UTF-8 直接输出，无需额外转义处理。
-
-> **跨语言注意事项：**
-> - Go 的 `json.Marshal` 默认满足此规范（UTF-8 直接输出 + 自动递归键排序）
-> - Go 的 `json.Unmarshal` 将 JSON 数字解码为 `float64`，序列化时 **MUST** 避免科学计数法（如 `1.775e+12` 应为 `1775540833687`）
-> - JavaScript/TypeScript 的 `JSON.stringify` 满足 UTF-8 直接输出，但 **MUST** 确保嵌套对象键递归排序（需自定义序列化函数）
-
-`params_hash = SHA-256(canonical_json_bytes).hex()`
-
-#### 11.3.3 服务端验签
-
-服务端 **MUST**：
-
-1. 从收到的参数中提取 `client_signature`
-2. 验证 `client_signature.aid` 与当前认证 AID 一致
-3. 验证 `client_signature.timestamp` 在 ±300 秒新鲜度窗口内（防重放）
-4. 用收到的实际参数（排除 `client_signature` 和 `_` 前缀字段）按 §11.3.2 重算 `params_hash`
-5. 常量时间比较重算的 hash 与客户端声称的 `params_hash`
-6. 用客户端注册的公钥验证 ECDSA-SHA256 签名
-7. 所有步骤通过后才允许执行操作；任一步骤失败 **MUST** 返回错误码 `-32051`（ClientSignatureError）
-
-> Python SDK、Go SDK、TypeScript SDK 均自动附加 `client_signature`，裸客户端必须自行实现。
-
-### 11.4 成员移除后的安全保证
-
-- 成员被踢出或退出后 **MUST** 立即触发 epoch 轮换
-- 新的 group_secret **MUST NOT** 分发给已离开的成员
-- 旧的 group_secret 仅用于解密历史消息，不用于加密新消息
-
----
-
-## 12. 安全属性分析
-
-### 12.1 安全属性总览
-
-| 属性 | 表现 | 说明 |
-|------|:----:|------|
-| **epoch 间前向安全** | ✅ | 旧 group_secret 安全擦除后，该 epoch 历史消息不可解密 |
-| **epoch 内前向安全** | ❌ | 同一 epoch 内所有消息共享同一 group_secret |
-| **Post-compromise Security** | ⚠️ | 下次 epoch 轮换时恢复；可通过定时轮换缩短窗口 |
-| **防中间人** | ✅ | group_secret 通过已认证的 P2P E2EE 分发 |
-| **防服务端注入** | ✅ 检测 | Membership Commitment 绑定 group_secret（§6），配合 Membership Manifest 签名验证（§6A），提供密钥绑定 + 成员变更授权双重防护 |
-| **防篡改** | ✅ | AAD 覆盖所有路由关键字段 |
-| **防重放** | ✅ | 本地 seen_messages 去重 |
-
-### 12.2 与 P2P E2EE 的对比
-
-| 维度 | P2P E2EE | Group E2EE |
-|------|---------|-----------|
-| **加密模式** | prekey_ecdh_v2 / long_term_key | epoch_group_key |
-| **密钥来源** | 每消息临时 ECDH | group_secret + HKDF 派生 |
-| **前向安全** | 单消息级（每消息独立临时密钥对） | epoch 级 |
-| **状态** | 零（纯工具类） | 最小（epoch + group_secret） |
-| **可断链** | 不可能 | 不可能 |
-| **密码学操作/条** | 1×ECDH + 1×HKDF + 1×AES-GCM | 1×HKDF + 1×AES-GCM |
-
-### 12.3 与其他协议群组方案的对比
-
-| 维度 | AUN (Epoch Group Key) | Signal (Sender Keys) | MLS (TreeKEM) | ANP (独立 Sender Keys) |
-|------|:---:|:---:|:---:|:---:|
-| **epoch 轮换分发** | O(n) | O(n²) | O(log n) | O(n²) |
-| **每消息加密代价** | 1×HKDF + AES | 1×HMAC + AES | 1×HMAC + AES | 1×HMAC + AES |
-| **epoch 内前向安全** | ❌ | ✅ | ✅ | ✅ |
-| **状态量** | 2 字段 | n 个 chain state | 二叉树 | n 个 chain state |
-| **断链风险** | 无 | 有 | 有 | 有 |
-| **状态可恢复** | ✅ | ❌ | ❌ | ❌ |
-
-### 12.4 设计折中说明
-
-本方案选择 **epoch 级前向安全**（而非消息级），换取：
-
-1. **零链状态**——不维护 hash chain，不需要 seq 同步
-2. **不可能断链**——消息乱序、丢失、重启均不影响后续消息解密
-3. **状态可恢复**——任何成员均可通过 epoch_key_request 恢复密钥
-4. **O(n) 分发**——无需每个 sender 逐人广播自己的 chain key
-
-epoch 内前向安全的缺失通过**缩短 epoch 生命周期**（定时轮换）来弥补。在 Agent 通信场景中，群组通常生命周期短、成员变更频繁，epoch 自然轮换速度快，该折中是合理的。
-
----
-
-## 13. 完整交互时序
-
-### 13.1 建群并发送加密消息
-
-```
-Alice (owner)                   Group Service                 Bob (member)
-─────────────────────────────────────────────────────────────────────────
-1. group.create({name: "..."})
-   ← {group_id: "g-abc123.agentid.pub"}
-
-2. group.add_member({group_id, aid: "bob"})
-   ← {member: {...}}
-
-3. 生成 group_secret (epoch=1)
-   计算 commitment
-
-4. P2P E2EE → Bob:
-   {type: "e2ee.group_key_distribution",
-    group_id, epoch: 1,
-    group_secret, commitment, member_aids}
-                                                        5. 验证 commitment
-                                                           存储 group_secret
-
-6. 发送加密群消息:
-   msg_key = HKDF(group_secret,
-       info="aun-group:g-abc123.agentid.pub:msg:gm-xxx")
-   ciphertext = AES-GCM(msg_key, plaintext, aad)
-
-   group.send({
-     group_id, encrypted: true,
-     payload: {type: "e2ee.group_encrypted", ...}
-   })
-                              ↓ 透传密文
-                              → event/group.message_created
-                                                        7. 从信封读取 group_id, message_id
-                                                           msg_key = HKDF(group_secret,
-                                                               info="aun-group:g-abc123.agentid.pub:msg:gm-xxx")
-                                                           plaintext = AES-GCM.decrypt(...)
-```
-
-### 13.2 踢人触发 Epoch 轮换
-
-```
-Alice (owner)                   Group Service                 Bob      Carol
-────────────────────────────────────────────────────────────────────────────
-1. group.kick({group_id, aid: "bob"})
-   ← success
-
-2. 生成新 group_secret (epoch=2)
-   计算新 commitment（不含 Bob）
-
-3. P2P E2EE → Carol:
-   {type: "e2ee.group_key_distribution",
-    epoch: 2, group_secret, ...}
-                                                                    4. 验证 commitment
-                                                                       更新本地 epoch=2
-
-   × Bob 不会收到新 epoch 密钥
-   × Bob 的旧 group_secret (epoch=1) 无法解密新消息
-```
-
-### 13.3 密钥恢复
-
-```
-Carol (成员)                                              Alice (成员)
-────────────────────────────────────────────────────────────────────
-1. 收到 epoch=3 的群消息
-   本地只有 epoch=2 的 group_secret
-   解密失败
-
-2. P2P E2EE → Alice:
-   {type: "e2ee.group_key_request",
-    group_id, epoch: 3}
-
-                                                3. 验证 Carol 是群成员
-                                                   P2P E2EE → Carol:
-                                                   {type: "e2ee.group_key_response",
-                                                    epoch: 3, group_secret, commitment,
-                                                    member_aids}
-
-4. 验证 commitment
-   存储 group_secret (epoch=3)
-   重试解密群消息 → 成功
-```
-
----
-
-## 14. SDK 接口建议
-
-### 14.1 加密
-
-```python
-# 通过 AUNClient 自动处理
-await client.call("group.send", {
-    "group_id": "g-abc123.agentid.pub",
-    "payload": {"type": "text", "text": "秘密消息"},
-    "encrypt": True,
-})
-```
-
-SDK 在发送前 **MUST** 检查本地是否持有该群的 group_secret：
-- 有 → 使用 §4 的流程加密 payload
-- 无 → 抛出 `E2EEError`，提示缺少群组密钥
-
-### 14.2 解密
-
-SDK 收到 `event/group.message_created` 且 `payload.type == "e2ee.group_encrypted"` 时自动解密：
-- 从信封读取 `group_id`、`message_id`
-- 查本地 group_secret（匹配 epoch）
-- 执行 HKDF 派生 + AES-GCM 解密
-- 解密失败时 **MAY** 触发 epoch_key_request
-
-### 14.3 配置项
-
-| 配置项 | 类型 | 默认值 | 说明 |
-|--------|------|--------|------|
-| `group_e2ee` | bool | `true` | 群组 E2EE 能力声明（必选能力，始终为 true，非用户开关） |
-| `epoch_auto_rotate_interval` | int | `0` | 自动轮换间隔（秒），0 表示禁用 |
-| `old_epoch_retention_seconds` | int | `604800` | 旧 epoch 密钥保留时间（默认 7 天） |
-
----
-
-## 15. 错误码
-
-| 错误码 | 名称 | 说明 |
-|--------|------|------|
-| -32040 | `E2EE_GROUP_SECRET_MISSING` | 缺少该群的 group_secret |
-| -32041 | `E2EE_GROUP_EPOCH_MISMATCH` | 消息 epoch 与本地不匹配 |
-| -32042 | `E2EE_GROUP_COMMITMENT_INVALID` | Membership Commitment 验证失败 |
-| -32043 | `E2EE_GROUP_NOT_MEMBER` | 密钥请求者不是群成员 |
-| -32044 | `E2EE_GROUP_DECRYPT_FAILED` | 群消息解密失败 |
-
----
-
-## 16. 未来扩展方向
-
-以下功能不在本规范范围内，但设计时已预留扩展空间：
-
-### 16.1 Sender Keys 叠加（可选增强）
-
-如需 epoch 内前向安全，可在 Epoch Group Key 基础上叠加 Sender Keys hash chain：
-
-```
-sender_chain_key[0] = HKDF(group_secret, info=f"sender:{sender_aid}:epoch:{epoch}")
-sender_chain_key[i+1] = SHA-256(sender_chain_key[i])
-msg_key[i] = HKDF(sender_chain_key[i], info="msg")
-```
-
-此方案从 group_secret 确定性派生，无需额外分发（O(0) 网络开销），但需要维护每个 sender 的 chain_index 状态。详见未来的 `08-AUN-E2EE-Group-SenderKeys.md`。
-
-### 16.2 大群优化
-
-当群规模超过 500 人时，epoch 轮换的 O(n) P2P 分发可能成为瓶颈。可考虑引入树状分发或分层密钥管理。
-
----
-
-## 17. 变更记录
-
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| 1.0-draft-r5 | 2026-04 | 成员加入改为 MUST 轮换 epoch；服务端以 `min_read_epoch` 约束新成员加入前历史访问；删除加入轮换配置开关 |
-| 1.0-draft-r4 | 2026-04 | 新增 Epoch CAS 轮换 RPC 的 rotation_signature 要求（§5.2.1）；新增客户端操作签名要求（§11.3）；补充密钥恢复异步语义（§8.5）；补充外层与 AAD 绑定校验说明；升级防服务端注入安全属性 |
-| 1.0-draft-r3 | 2026-04 | Membership Commitment 绑定 group_secret 哈希（§6.2）；新增 Membership Manifest 签名机制（§6A）；群密文消息新增发送方签名（§7.1）；更新本地状态模型含 old_epochs（§9.2）；服务端角色明确 epoch CAS 协调（§1.2）；分发消息增加 manifest 字段（§5.2, §5.3） |
-| 1.0-draft-r2 | 2026-04 | group_e2ee 默认值改为 true；补充成员加入轮换策略；group.leave 明确离开者不执行轮换 |
-| 1.0-draft-r1 | 2026-04 | 修正：Membership Commitment 去掉 "Signed" 命名，明确为哈希一致性检测而非签名防伪；修正 message_id 来源为客户端生成；新增外层路由字段与 AAD 绑定校验要求 |
-| 1.0-draft | 2026-04 | 初始版本：Epoch Group Key 机制；Membership Commitment；密钥恢复协议 |
-
-
-
+# AUN-E2EE 群组扩展规范
+
+> 版本：2.0-draft
+> 状态：规范性文档
+> 适用范围：AUN 客户端 SDK、客户端应用、跨语言实现
+> 不适用范围：Group Service 服务端加解密实现
+> 前置依赖：[08-AUN-E2EE](./08-AUN-E2EE.md)（P2P E2EE 规范，V2 群组复用其 Prekey 体系、AAD 序列化规则）、[10-Group-子协议](./10-Group-子协议.md)
+> 定位：**群组消息端到端加密层**，基于 per-message 密钥 + per-recipient 包裹机制
+
+---
+
+## 1. 目标与边界
+
+本规范定义 AUN 群组成员之间的端到端消息加密协议（V2，当前唯一在用版本）。
+
+### 1.1 目标
+
+- 让群组内的 N 个成员在现有 `group.send` / `group.v2.send` / `event/group.message_created` 之上实现端到端加密
+- 让 Group Service 仅看到最小必要路由元数据和密文 payload
+- 每条消息使用独立密钥，接收方按设备分别持有密钥包裹（wrap），不依赖群级共享对称密钥
+- 为各语言 SDK 提供统一的群组密文格式、成员状态签名机制和恢复语义
+
+### 1.2 服务端职责
+
+Group Service **只做**：
+
+- 认证发送方（JWT token / AID 证书）
+- 校验群成员权限
+- 存储共享密文体（`v2_group_messages`）和逐设备密钥包裹（`v2_group_wraps`）
+- 校验消息结构完整性（recipients 排序、digest、必要审计包裹等）
+- 维护群成员状态的签名版本链（`state_version`/`state_chain`），提供分叉检测的比对基准
+- 广播加密消息通知，按设备分发对应的密钥包裹
+
+Group Service **绝不做**：
+
+- 加解密群消息
+- 持有或管理消息密钥、成员密钥明文
+- 参与密钥协商或密钥派生
+
+### 1.3 设计原则
+
+| 原则 | 说明 |
+|------|------|
+| **消息级密钥** | 每条消息使用独立随机密钥，发送方一次性会话密钥用完即弃，不维护群级长期对称密钥 |
+| **复用 P2P V2 Prekey 体系** | 接收方设备密钥包裹基于 P2P E2EE（[08-AUN-E2EE](./08-AUN-E2EE.md)）的 IK/SPK Prekey 机制，缺少群内设备 Prekey 时可回退到该设备已注册的 P2P Prekey |
+| **不信任服务端** | 消息密钥从未经过服务端明文；接收方按设备分别持有的密钥包裹只有对应设备的私钥能解开 |
+| **成员状态可验证** | 群成员集合与权限的变更通过签名的状态版本链（state_version/state_chain）記录，接收方可据此检测状态分叉或篡改 |
+
+---
+
+## 2. 与 AUN-Core 的关系
+
+AUN-E2EE-Group 建立在以下核心能力之上：
+
+- **P2P E2EE V2**（[08-AUN-E2EE](./08-AUN-E2EE.md)）：设备 Prekey（IK/SPK）注册与管理机制、AAD 序列化规则（Canonical JSON）均直接复用
+- **Group 子协议**（[10-Group-子协议](./10-Group-子协议.md)）：群组管理、成员管理、消息传输
+- **AID + 证书链身份体系**：成员身份验证
+
+群组密文消息通过 `group.v2.send` 提交，`group.send` 承载明文/兼容路径；Group Service 无需识别密文 payload 内部字段。
+
+---
+
+## 3. 术语
+
+### 3.1 Epoch
+
+群密钥版本号（uint32，从 1 开始）。用于在消息 AAD 中标记消息所属的密钥轮换周期，服务端据此拒绝使用过期版本发送的消息，与下方 State Version 是两条独立轨道。
+
+### 3.2 State Version / State Chain
+
+群成员状态（成员列表、管理员集合、审计接收者等）的签名版本号（uint32，从 0 开始，未签名任何状态时为 0）。每次 owner/admin 提交并确认一次成员状态变更，版本递增。`state_chain` 是历次已确认状态的链式记录，客户端可据此检测服务端是否篡改历史或出现并发分叉。
+
+### 3.3 State Commitment
+
+对当前群成员集合、管理员集合、审计接收者等状态字段的摘要值，绑定到 `epoch`，写入每条加密消息的 AAD 中，使消息与发送时刻的群状态可验证关联。
+
+### 3.4 Recipients Digest
+
+一条群消息的所有设备密钥包裹（recipient 行）经排序后计算得到的摘要根值，纳入发送方签名覆盖范围，用于防止服务端在按设备拆分投递时篡改或替换某个接收方的密钥包裹。
+
+### 3.5 密文群消息
+
+通过 `group.v2.send` 传输的加密群消息，`payload.type` **MUST** 为 `e2ee.group_encrypted`。
+
+---
+
+## 4. 密钥体系概述
+
+### 4.1 密钥层次
+
+| 密钥 | 生成方 | 生命周期 | 说明 |
+|------|--------|---------|------|
+| 消息密钥（对称） | 发送方，每条消息独立生成 | 单条消息 | 用于加密消息正文，从不直接传输，按接收方设备分别用密钥包裹机制加密后随消息一起发送 |
+| 发送方一次性会话密钥 | 发送方，每条消息独立生成 | 单条消息 | 用于与接收方设备的长期身份/Prekey 做密钥协商，加密后即可丢弃 |
+| 接收方设备身份密钥（IK） | 接收方，AID 级别 | 长期 | 与 AID 身份证书绑定 |
+| 接收方设备 Prekey（SPK） | 接收方，设备级别 | 定期轮换 | 群内设备 Prekey（`group_device_prekey`）通过 `group.v2.put_group_pk` 注册；缺失时回退到该设备已注册的 P2P Prekey，此时安全强度降级为仅身份密钥参与协商 |
+
+具体的密钥协商组合方式（是否使用 Prekey、密钥派生的哈希函数与输入构成）与 [08-AUN-E2EE](./08-AUN-E2EE.md) 的 P2P V2 加密模式一致，本规范不重复列出精确公式，实现请参照该文档及各语言 SDK 的密码学模块源码。
+
+### 4.2 每条消息的密钥包裹
+
+一条加密群消息只加密一次消息正文，但会为每个当前应接收该消息的设备分别生成一份密钥包裹（recipient wrap），使得只有对应设备的私钥能解出消息密钥。密钥包裹按角色分类：
+
+- `member`：普通群成员设备
+- `self_sync`：发送方自己在其他设备上的同步副本
+- `audit`：群配置的审计接收者（如有），用于合规场景下的旁路可见性，不改变成员关系
+
+---
+
+## 5. 消息生命周期
+
+### 5.1 Bootstrap（发送前的成员/密钥快照）
+
+发送方在加密消息前调用 `group.v2.bootstrap` 获取：
+
+- 当前所有（committed）成员的设备身份/Prekey 公钥列表
+- 当前 `epoch`
+- 当前 `state_version` / `state_hash` / `state_chain`
+- `committed_member_aids`：已通过状态签名确认的成员
+- `pending_adds` / `pending_removes`：尚未签名确认的成员变更
+- `e2ee_security_level`：`end_to_end`（正常受控群）或 `transport`（open/邀请码等任何人可自由加入的群，此时密钥包裹接收方集合不与"被授权成员"强绑定，安全强度退化为等价于传输层加密，不构成严格端到端）
+
+对于设置了成员审批（private/approval/closed）的群，尚未完成状态签名确认的新成员（pending）不会出现在 bootstrap 返回的设备列表中，发送方因而不会为其生成密钥包裹，实现了"未确认成员收不到密文"的天然隔离。SDK 通常对 bootstrap 结果做短期缓存，成员或状态变更后需要刷新。
+
+### 5.2 加密与发送
+
+1. 发送方生成本条消息的消息密钥与一次性会话密钥
+2. 构造 AAD（含 `group_id`、`epoch`、`message_id`、发送方身份、`state_commitment` 等，详见 §7）
+3. 用消息密钥对正文做认证加密，AAD 参与认证但不加密
+4. 为 bootstrap 返回的每个目标设备生成密钥包裹（消息密钥被目标设备的密钥协商结果加密）
+5. 对所有密钥包裹排序后计算 Recipients Digest，随同密文一起纳入发送方签名
+6. 调用 `group.v2.send` 提交完整信封（含密文、AAD、Recipients Digest、发送方签名、所有密钥包裹）
+
+服务端收到后校验成员资格、`epoch` 是否为当前值、密钥包裹排序与 Recipients Digest 是否自洽、必要审计包裹是否齐全，通过后落库并按设备拆分推送。
+
+### 5.3 拉取与解密
+
+接收方通过 `group.v2.pull` 按设备拉取属于自己的消息（服务端只返回该设备自己的那一份密钥包裹，可附带 Merkle 证明用于验证该包裹确实是发送方原始签名集合的一部分而未被服务端替换）。接收方：
+
+1. 验证发送方签名（覆盖密文、AAD、Recipients Digest）
+2. 用本机私钥解出分配给自己的消息密钥
+3. 用消息密钥解密正文并校验 AAD 一致性
+
+解密失败的常见原因：使用了已轮换的旧 Prekey、bootstrap 快照过期导致密钥包裹面向错误的设备、或密文/AAD 被篡改。恢复方式通常是刷新 bootstrap 后等待下一条消息，或依赖服务端 `group.v2.pull` 的历史消息重新拉取。
+
+### 5.4 拉取确认
+
+接收方通过 `group.v2.ack` 提交已消费到的消息序号游标，用于服务端做 retention 与增量拉取范围计算。
+
+---
+
+## 6. 成员状态签名（State Version）
+
+### 6.1 目的
+
+群成员集合、管理员集合等状态信息如果只由服务端记录，无法防止服务端篡改或伪造。V2 引入 owner/admin 对状态变更进行签名确认的两阶段流程，使状态变更可追溯、可验证、且能检测并发冲突。
+
+### 6.2 两阶段流程
+
+1. **提案**（`group.v2.propose_state`）：owner/admin 提交目标 `state_version`、状态摘要（`state_hash`）、成员快照，并附上覆盖这些字段的签名。首次状态签名（`state_version = 1`）**MUST** 由 owner 发起，此后 owner/admin 均可发起。服务端记录为待确认提案，设有自动确认超时。
+2. **确认**（`group.v2.confirm_state`）：发起者（或后续管理员）提交提案 ID 完成确认，服务端以比较并交换（CAS）方式原子推进 `state_version`，若确认前已有其他提案抢先生效则确认失败，需要基于最新状态重新发起。
+
+该机制保证并发的状态变更提案中至多一个能生效，避免服务端或多个管理员产生分叉的成员视图。
+
+### 6.3 分叉检测
+
+客户端在 bootstrap 时获得当前 `state_chain`，与本地已知的历史链做连续性比对；若发现不连续或矛盾，视为潜在的服务端篡改或并发冲突信号，应用层应提示用户或拒绝基于该状态发送敏感消息。
+
+### 6.4 Pending 成员语义
+
+新加入但尚未被状态签名确认的成员（`pending_adds`）在成员审批类群组（private/approval/closed）中不会出现在 bootstrap 的设备列表里，因而无法接收此前及此后（直到状态确认）发出的加密消息；在开放加入类群组（open/邀请码）中不做此限制，此时群组的 `e2ee_security_level` 会被标记为 `transport`（见 §5.1），提示这类群组的加密强度弱于严格端到端。
+
+---
+
+## 7. 消息格式与 AAD
+
+### 7.1 AAD 关键字段
+
+| 字段 | 说明 |
+|------|------|
+| `group_id` | 群组唯一标识 |
+| `from` / `from_device` | 发送方 AID 与设备标识 |
+| `message_id` | 消息唯一标识，发送方生成，参与认证 |
+| `epoch` | 消息所属的密钥版本号 |
+| `state_commitment` | 绑定发送时刻的成员状态摘要（`state_version`/`state_hash`/`state_chain`） |
+
+AAD 采用 Canonical JSON 序列化（递归键排序、UTF-8 直出、紧凑格式），规则与 [08-AUN-E2EE §8.3](./08-AUN-E2EE.md) 完全一致。
+
+### 7.2 外层信封
+
+密文 payload 通过 `group.v2.send` 的 `envelope` 参数提交；接收方通过 `group.v2.pull` 按设备取回，返回内容包含该设备自己的密钥包裹与（如适用）该包裹在原始签名集合中的完整性证明。
+
+---
+
+## 8. 密钥恢复与历史访问
+
+- 接收方若因设备 Prekey 轮换、bootstrap 快照过期等原因暂时无法解密某条消息，通常的恢复路径是刷新 bootstrap 快照后重试，而非向对端请求补发密钥（V2 不存在需要跨端口头传递的群级共享密钥）。
+- 新成员加入前发出的历史消息，其密钥包裹集合本就不包含新成员设备，因此新成员天然无法解密加入前的历史消息，无需额外的"历史隔离"机制。
+
+---
+
+## 9. 客户端密钥存储
+
+- 发送方一次性会话密钥用后即弃，不持久化。
+- 接收方的设备身份密钥（IK）与设备 Prekey（SPK）私钥的存储、保护方式与 [08-AUN-E2EE](./08-AUN-E2EE.md) 的 P2P V2 Prekey 存储机制一致（本地密钥库 + 平台级密钥保护，明文不落盘）。
+- 消息密钥本身不需要持久化——每条消息独立生成、独立解出、用后即弃；除非应用层自行缓存明文消息以支持离线查看。
+
+---
+
+## 10. 防重放与防篡改
+
+### 10.1 防篡改
+
+AAD 覆盖所有路由关键字段（`group_id`、`from`、`epoch`、`message_id`、`state_commitment`），任何篡改导致认证加密校验失败而拒绝解密；发送方签名进一步覆盖密文、AAD 与 Recipients Digest，防止服务端在拆分投递时替换或增删某个接收方的密钥包裹。
+
+### 10.2 防重放
+
+- 接收方 **MUST** 维护本地去重集合，以 `{group_id}:{from}:{message_id}` 为 key 拒绝重复消息。
+- `group.v2.send` 的时间戳需在合理新鲜度窗口内，超出窗口的请求会被服务端拒绝。
+
+### 10.3 Epoch/State 校验
+
+- 服务端拒绝 `epoch` 与当前群密钥版本不一致的发送请求，客户端遇到此类拒绝应刷新 bootstrap 后重试。
+- 接收方应校验消息 AAD 中的 `state_commitment` 与本地已知状态链一致，不一致时视为潜在分叉信号。
+
+---
+
+## 11. 安全约定
+
+### 11.1 通用约定
+
+- 加密失败时 **MUST NOT** 静默降级为明文
+- 每条消息使用独立的随机密钥与随机 nonce
+- 密钥材料 **MUST** 由密码学安全随机数生成器生成
+- 实现 **MUST NOT** 在日志中输出消息密钥或密钥包裹解密结果
+
+### 11.2 客户端操作签名
+
+以下群组操作 **MUST** 附加客户端 ECDSA 签名（`client_signature` 字段），服务端强制验签：
+
+- `group.send` / `group.v2.send`
+- `group.add_member`
+- `group.kick`
+- `group.leave`
+- `group.update_rules`
+
+签名生成、`params_hash` 计算规则与验签流程见 [10-Group-子协议](./10-Group-子协议.md) 及 SDK RPC 手册中对应方法的说明，本规范不重复列出。
+
+### 11.3 成员移除后的安全保证
+
+- 成员被踢出或退出后，后续消息 bootstrap 不再包含其设备，因而无法为其生成新的密钥包裹；已离开成员无法解密移除后发出的消息。
+- 已离开成员此前收到的历史消息密钥包裹不受影响（历史消息本就已经解密完成或本地缓存）。
+
+---
+
+## 12. 安全属性分析
+
+### 12.1 安全属性总览
+
+| 属性 | 表现 | 说明 |
+|------|:----:|------|
+| **消息级前向安全** | ✅ | 每条消息使用独立密钥，发送方一次性会话密钥用后即弃 |
+| **防中间人** | ✅ | 密钥协商基于已认证的设备身份密钥与 Prekey |
+| **防服务端注入** | ⚠️ | State Commitment 绑定消息到特定的已签名成员状态，State Chain 提供分叉检测，但完整防护依赖应用层对状态链连续性的主动校验 |
+| **防篡改** | ✅ | AAD 覆盖所有路由关键字段，发送方签名覆盖密文与 Recipients Digest |
+| **防重放** | ✅ | 本地去重 + 时间戳新鲜度窗口 |
+| **成员变更后的密钥隔离** | ✅ | 密钥包裹按当前 bootstrap 快照生成，新成员收不到历史消息包裹，被移除成员收不到后续消息包裹 |
+
+### 12.2 与 V1（已禁用）的本质差异
+
+V1 机制（Epoch Group Key：群级共享对称密钥 `group_secret` + 版本号 `epoch` + 通过 P2P 通道向每个成员分发同一把密钥）已在线上全面禁用，不再是当前协议的一部分。V2 用"每条消息独立密钥 + 逐设备密钥包裹"取代了群级共享密钥模型，因此不再需要 V1 中用于同步 `epoch` 的一次性 CAS 轮换 RPC；群成员/权限的变更改由 §6 的状态签名两阶段流程记录和验证。
+
+---
+
+## 13. 错误码
+
+| 错误码 | 名称 | 说明 |
+|--------|------|------|
+| -32040 | `E2EE_GROUP_KEY_MISSING` | 找不到属于本设备的密钥包裹 |
+| -32041 | `E2EE_GROUP_EPOCH_MISMATCH` | 消息 epoch 与服务端当前值不匹配 |
+| -32042 | `E2EE_GROUP_STATE_MISMATCH` | State Commitment / State Chain 校验失败 |
+| -32044 | `E2EE_GROUP_DECRYPT_FAILED` | 群消息解密失败 |
+
+---
+
+## 14. 变更记录
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 2.0-draft | 2026-07 | 重写为 V2 机制（消息级密钥 + 逐设备密钥包裹 + 状态签名两阶段流程），移除已禁用的 V1 Epoch Group Key 机制描述 |
+| 1.0-draft-r5 | 2026-04 | （V1，已废弃）成员加入改为 MUST 轮换 epoch；服务端以 `min_read_epoch` 约束新成员加入前历史访问 |
+| 1.0-draft-r4 | 2026-04 | （V1，已废弃）新增 Epoch CAS 轮换 RPC 的 rotation_signature 要求 |
+| 1.0-draft-r3 | 2026-04 | （V1，已废弃）Membership Commitment 绑定 group_secret 哈希；新增 Membership Manifest 签名机制 |
+| 1.0-draft-r2 | 2026-04 | （V1，已废弃）group_e2ee 默认值改为 true；补充成员加入轮换策略 |
+| 1.0-draft-r1 | 2026-04 | （V1，已废弃）修正 Membership Commitment 命名与 message_id 来源 |
+| 1.0-draft | 2026-04 | （V1，已废弃）初始版本：Epoch Group Key 机制 |