群组托管协议
群组托管是客户端—中继协议的可选模块。群由用户创建并选择一个固定中继托管；客户端直接连接该中继，群组操作不经过账户路由 DHT 或中继 RPC。提供该能力的中继必须完整实现本模块，并在有效 RelayDescriptor 中声明 group.host.v1 能力。
作用与信任边界
托管中继验证设备、成员和角色，维护当前群状态，为事件和密钥版本排序，并向有权访问的设备分发中继秘密。当前成员共同持有客户端群秘密。群消息密钥必须同时由客户端秘密和中继秘密导出，因此中继单独不能解密群消息。
客户端通过永久保留的管理链验证成员和公钥。成员列表由客户端本地重建；封装秘密前必须完成管理验证。
中继与持有客户端秘密的一方串谋时可能解密相应消息；本协议不声明前向保密或入侵后安全性质。串谋、秘密泄露及秘密轮换的详细限制见安全边界。
协议内容
概念与核心对象
| 部分 | 内容 |
|---|---|
| 群组模型与密钥 | 固定托管、角色、分离秘密、承诺、密钥盒和群应用秘密派生 |
| 成员资格与访问控制 | 邀请、申请、成员变化、成员密钥重置、设备访问区间 |
| 群组时间线与同步 | 群时间线、数据保留与访问、首次加载与断线恢复 |
| 账户内群状态与秘密同步 | 同账户设备之间的群私有状态请求、成员私钥及历史群应用秘密同步 |
| 群消息与加密 | 信封、消息密钥派生与加解密、群消息业务对象、昵称更新 |
| 核心对象 | 群 ID、GroupState、GroupEvent 和管理链 |
方法与通知
| 部分 | 内容 |
|---|---|
| 方法公共约定 | 传输、授权、签名、列表分页、校验和错误 |
| 生命周期与同步方法 | 创建、状态查询、事件同步和关闭 |
| 准入方法 | 邀请、入群申请与审批 |
| 属性与角色管理方法 | 群属性、角色和所有权转让 |
| 成员与封禁管理方法 | 退出、移除、封禁与解除封禁 |
| 成员密钥重置方法 | 重置请求的提交、列表、批准与拒绝 |
| 密钥方法 | 密钥同步与客户端秘密轮换 |
| 消息方法 | 群消息发送与幂等重试 |
| 订阅方法 | 群订阅集合替换、订阅上限、访问权限校验与订阅后同步 |
| 通知 | 事件、申请和成员密钥重置列表变化提示 |
方法索引
以下方法均使用设备会话。
| 方法 | HTTP | WebSocket |
|---|---|---|
group.create |
POST | JSON-RPC |
group.resolve |
GET | JSON-RPC |
group.sync |
GET | JSON-RPC |
group.close |
DELETE | JSON-RPC |
group.invite.create |
POST | JSON-RPC |
group.invite.resolve |
GET | JSON-RPC |
group.invite.list |
GET | JSON-RPC |
group.invite.revoke |
DELETE | JSON-RPC |
group.application.submit |
POST | JSON-RPC |
group.application.list |
GET | JSON-RPC |
group.application.approve |
POST | JSON-RPC |
group.application.reject |
DELETE | JSON-RPC |
group.update |
PATCH | JSON-RPC |
group.role.update |
PUT | JSON-RPC |
group.owner.transfer |
POST | JSON-RPC |
group.member.leave |
DELETE | JSON-RPC |
group.member.remove |
DELETE | JSON-RPC |
group.member.ban |
PUT | JSON-RPC |
group.member.unban |
DELETE | JSON-RPC |
group.member.recovery.submit |
POST | JSON-RPC |
group.member.recovery.list |
GET | JSON-RPC |
group.member.recovery.approve |
POST | JSON-RPC |
group.member.recovery.reject |
DELETE | JSON-RPC |
group.key.sync |
GET | JSON-RPC |
group.secret.rotation.prepare |
PATCH | JSON-RPC |
group.secret.rotation.commit |
POST | JSON-RPC |
group.message.send |
POST | JSON-RPC |
group.subscribe |
N/A | JSON-RPC |
HTTP/WSS 映射和错误遵循群组方法公共约定。
通知索引
通知封装遵循客户端—中继通知约定。
一致性要求
- 请求与提交：按群方法公共约定验证完整请求、设备签名与账户绑定、批准者独立验签、字段与资源边界、HTTP/WSS 错误映射及错误披露边界；并发和故障不得留下部分状态、事件、密钥、访问区间或邀请计数。
- 管理状态：按管理链和成员资格与访问控制验证创建、属性与角色更新、转让、离群、移除、封禁/解除封禁、容量限制与成员投影；覆盖同值更新、旧链头重放、未知管理类型及管理验证失败后的暂停。
- 邀请与审批：按准入方法和成员密钥重置方法验证邀请分享、查看及使用权限、申请重试与替换、成员密钥重置、到期和连带删除；列表分页须覆盖游标、空页、列表与权限变化、未变化列表的完整遍历，以及列表结果不能替代提交时的当前状态检查。
- 秘密与轮换：按密钥模型及密钥方法验证分离秘密、承诺、两类密钥盒与派生结果、两阶段客户端轮换和中继轮换；覆盖分批与替换、迟到重试、期限不刷新、成员变化、完整覆盖、owner 换钥，以及候选材料经验证后启用。
- 密钥与私有状态恢复：按账户内群状态与秘密同步和
group.key.sync验证材料独立到达时的暂存、按已验证历史选择私钥和确认版本、历史盒与当前盒的恢复、跨页及相邻条目的盒省略规则；缺失历史密钥不阻塞管理验证和当前版本恢复。 - 事件与访问：按设备访问区间及
group.sync验证新设备入口、边界与多段区间、管理事件和消息的不同可见范围、非连续序号及密钥版本、消息认证与管理链重建；快照、通知和私有材料不能推进已验证状态或同步位置。 - 消息与昵称：按群消息与加密和幂等重试验证完整信封、随机 nonce、AAD、当前权限、结果保留、正文与附件、回复引用，以及加密昵称的本地排序、清除和重新入群边界；业务明文错误与管理事件错误分别处理。
- 订阅与通知：按订阅方法和群组通知验证集合替换、清空、上限调低、失败明细、设备访问区间保持；覆盖事件提示合并、无版本列表刷新，以及请求到期或删除后的通知。
- 保留与关闭：按数据保留与访问规则及
group.close验证消息与旧密钥裁剪、当前密钥恢复、管理事件及验签证书永久保留和不可逆关闭；关闭后不保证读取服务或消息、密钥保留。