8.8 KiB
API 设计
所有业务接口使用 /api/v1,JSON 请求及响应。受保护接口通过 Authorization Bearer 接收短期会话令牌。错误结构为 {"error":{"code":"…","message":"…"}}。Web 与桌面端各自持有会话。服务端只保存令牌摘要。
| 方法 | 路径 | 请求与响应 |
|---|---|---|
| GET | /healthz、/readyz | 分别检查进程和 PostgreSQL、Redis |
| POST | /api/v1/auth/challenge | 返回 2 分钟单次使用的 challenge |
| POST | /api/v1/auth/register | 接收 username、password、deviceName、platform、publicKey、challenge、signature,返回 201 和 token、user、device |
| POST | /api/v1/auth/login | 同上,返回 200 |
| POST | /api/v1/auth/logout | 使当前会话失效,返回 204 |
| GET | /api/v1/me | 返回账号和当前设备 |
| GET | /api/v1/devices | 返回当前账号的设备列表,signedIn 表示有未过期会话,lastActiveAt 来自登录与 WebSocket 心跳 |
| DELETE | /api/v1/devices/{id} | 撤销指定设备和其全部会话,返回 204 |
| POST | /api/v1/realtime/ticket | 返回 30 秒单次 WebSocket 票据 |
| GET | /api/v1/realtime | 通过子协议 xhchat.v1 和 ticket.票据升级,服务器选择 xhchat.v1,连接建立后发送 ready 事件 |
| GET | /api/v1/contacts | 返回好友、来往申请和当前账号的黑名单 |
| GET | /api/v1/contacts/search?username= | 按完整用户名查找,返回可见的联系人状态 |
| POST | /api/v1/contacts/{id} | 请求体包含 action,可选 alias 和 category,成功返回 204 |
| POST | /api/v1/inbox | 接收 messageId、recipientDevice 和 Base64 编码的 MLS 封包,返回字符串 sequence |
| GET | /api/v1/inbox?after= | 按当前设备和递增游标取最多 64 条封包 |
| GET | /api/v1/contacts/{id}/devices | 返回已接受联系人的有效设备与公开身份密钥 |
| POST | /api/v1/key-packages | 当前设备发布带设备签名的 MLS KeyPackage,成功返回 204 |
| GET | /api/v1/key-packages | 返回当前设备尚可领取的密钥包数量 available |
| GET | /api/v1/mls-local-key | 读取当前设备的公开认证密钥,供本机安全码计算 |
| POST | /api/v1/mls-credential | 当前设备登记带认证密钥签名的 MLS 签名公钥 |
| POST | /api/v1/attachments/{id}?recipient= | 已接受好友设备上传附件密文,使用 application/octet-stream,成功返回 204 |
| GET | /api/v1/attachments/{id} | 原发送或接收设备获取附件密文 |
| GET / POST | /api/v1/groups | 列出当前账号所属群组与邀请,或创建群组 |
| GET / POST | /api/v1/groups/{id} | 查看群组详情或执行邀请、接受、拒绝、改名、升降管理员、转让群主、移除、退出或解散 |
| POST | /api/v1/groups/{id}/preferences | 更新当前账号的 pinned 和 muted,可只传其中一项 |
| POST | /api/v1/groups/{id}/seen | 提交当前设备已同步的消息游标 sequence,成功返回 204 |
| GET | /api/v1/groups/{id}/devices | 获取群成员的有效设备与 MLS 公钥 |
| POST | /api/v1/groups/{id}/devices/{device}/claim | 群主一次性领取群成员设备的 KeyPackage |
| GET / POST | /api/v1/groups/{id}/epochs | 读取当前设备可访问的会话信息或由群主发布新世代 |
| GET / POST | /api/v1/groups/{id}/messages | 使用 after 游标补拉群密文或向当前世代提交群密文 |
| POST | /api/v1/groups/{id}/attachments/{attachment}?epoch= | 当前世代设备上传附件密文,使用 application/octet-stream,成功返回 204 |
| GET | /api/v1/groups/{id}/attachments/{attachment} | 本次群成员资格仍有效且属于原会话的设备下载已发布附件 |
| POST | /api/v1/contacts/{id}/devices/{device}/claim | 为当前设备原子领取一个联系人的未使用 KeyPackage |
用户名为 3–32 位 ASCII 字母、数字或下划线,忽略大小写。密码最少 12 个 Unicode 字符,最多 256 字节。platform 为 web 或 windows。公钥、签名和 challenge 使用无填充 Base64URL。设备使用 Ed25519 签名 UTF-8 字符串 XHChat device authentication v1\n 后紧接 challenge。该签名仅用于证明基础设备密钥持有权。
联系人操作包含 request、accept、reject、cancel、delete、block、unblock 和 preferences。变更后 WebSocket 发送 contacts_changed,客户端重新获取授权后的列表。
设备投递当前要求双方是已接受的联系人,且两个设备均未撤销。接口校验 MLS 1.0 PrivateMessage 和 Welcome 的外层类型与长度,客户端负责完整协议验证。相同发送设备、接收设备、消息 ID 和封包的重试返回原游标,内容不同返回 409。WebSocket 的 inbox_changed 仅提示当前设备补拉。投递保留期由 XHCHAT_ENVELOPE_RETENTION 配置,默认 720 小时。
密钥包与签名均使用标准 Base64。设备以已有的 Ed25519 密钥签名 UTF-8 前缀 XHChat MLS KeyPackage v1\n{userId}\n{deviceId}\n 和原始 MLS 封包的拼接。服务端验证签名和外层格式,密钥包可在发布后的 24 小时内领取一次。客户端仍需独立验证设备公钥信任和完整 MLS 对象。重试发布同一封包不会再次开放领取。
MLS 凭据由标准 Base64 的 publicKey 和 signature 组成,使用 UTF-8 前缀 XHChat MLS credential v1\n{userId}\n{deviceId}\n 后接 32 字节 MLS Ed25519 公钥。设备目录返回可选的 mls 对象。已登记公钥仅允许原值重试。
附件密文上限为 8 MiB 加 16 字节认证标签。重复提交相同 ID 和密文为幂等操作。附件按投递保留期清理,文件名和密钥只通过 MLS 消息传递。
群组详情包含十进制字符串 membershipVersion。已接受成员变化会递增版本,待处理邀请和角色变化保留版本。active 成员可以查看其他有效成员,群主与管理员还可查看待处理邀请。群主可解散、调整管理员和移除成员。管理员可改名、邀请好友和移除普通成员。
群主可使用 transfer 和有效成员的 target 转让群主。转让会将原群主设为普通成员,更新群版本,由新群主创建后续 MLS 会话。公告使用现有 MLS 密文投递接口,客户端验证公告来自该会话经核验的群主设备。
创建或更新群资料和成员后,受影响账号的在线客户端收到 {"type":"group_list_changed"},再用授权 API 刷新。邀请相关提示发送给管理者和被邀请人。提示只包含类型字段,不传群号、群名或成员资料。
群组密文投递使用 /groups/{id}/epochs 和 /groups/{id}/messages。群主发布带 membershipVersion 的世代,选取每个有效成员的一台已登记 MLS 设备,提交其他设备的 Welcome。GET epochs 返回当前有效世代的设备名单和本设备获准接收的 Welcome,旧世代仅向在本次成员资格期间加入过该世代的设备返回。POST messages 接受当前世代的 MLS PrivateMessage,GET messages 通过 after 游标返回本设备有权读取的密文。
群世代和密文提交后,WebSocket 向该世代的设备发送 group_changed,包含 type 和 groupId。新投递给其他设备的密文在该账号未开启免打扰时附带 notify: true。客户端收到提示、重连或到达兜底轮询周期时,按持久化的游标向授权接口补拉。提示由 Redis 尽力送达,数据库保存投递记录。
群列表和详情返回当前账号的 pinned 和 muted。群列表先排序置顶群,随后按创建时间排序。设置修改后,同一账号的在线设备收到刷新提示。离开群组或被移除后,当前成员资格的设置随之清除。
群列表同时返回当前设备的 unread,上限为 100,用于客户端显示 99+。统计当前成员资格内、设备获准接收且由其他设备发送的密文投递。sequence 是正整数字符串,须指向当前设备在该群有权读取的消息,更新不会回退游标。成员列表和其他账号的 API 响应不包含该设备的查看状态。
有效成员可通过 GET /groups/{id}/devices 获取群内有效设备凭据。群主通过 POST /groups/{id}/devices/{device}/claim 一次性领取其他有效成员的设备密钥包。邀请待接受的账号、已离群的账号和撤销设备无法访问群设备目录。
成员变更后旧世代不能发消息。绑定设备被撤销后需以替代设备发布新世代。重新加入的成员只能补拉本次加入以来的世代。服务端校验外层格式和投递授权,MLS 内容验证由客户端执行。
群附件上传后尚不可下载。原上传设备通过同一世代的群消息提交 attachmentId 发布附件。每个附件最多绑定一条消息,接收端将投递字段与 MLS 密文中的附件标识核对。未发布的附件随保留期清理,已发布附件随关联消息的保留期清理。上传与下载限制与私聊附件共用。
下一阶段将增加 /conversations、/calls、/posts、/backups、/push 与独立的管理接口。