Files

86 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 |
| POST | /api/v1/auth/password | currentPassword、newPassword,校验当前密码后修改,结束全部会话,返回 204 |
| POST | /api/v1/auth/logout-others | 结束当前账号除调用令牌以外的全部会话,返回 204 |
| GET | /api/v1/auth/history | 最近 50 次成功登录记录,包含 id、deviceName、platform、createdAt、currentDevice |
| GET | /api/v1/me | 返回账号和当前设备 |
| GET | /api/v1/devices | 返回当前账号的设备列表,signedIn 表示有未过期会话,lastActiveAt 来自登录与 WebSocket 心跳 |
| POST | /api/v1/devices/{id} | name,修改当前账号有效设备名称,返回 204,后续登录保留手动名称 |
| 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 封包及可选的布尔值 silent,返回字符串 sequence |
| GET | /api/v1/inbox?after= | 按当前设备和递增游标取最多 64 条封包 |
| GET | /api/v1/inbox/unread | 返回当前设备的未读数,以联系人账号 ID 为键,省略为零的项 |
| POST | /api/v1/inbox/seen | 传 senderDevice 和字符串 sequence,更新当前设备对该发送设备的已查看游标 |
| 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 |
| POST / DELETE | /api/v1/groups/{id}/invite-link | 群主生成或撤销一次性链接。生成返回 `code` 和 `expiresAt`,撤销返回 204 |
| POST | /api/v1/group-invites/redeem | 登录后提交 `code`,成功返回 `groupId`,供用户打开邀请并接受或拒绝 |
| 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、mute、unmute、pin 和 unpin。联系人列表和搜索返回当前账号的 `muted` 与 `pinned`。备注、分组、免打扰和置顶的变更只给设置者的设备发送 `contacts_changed`,客户端重新获取列表。
设备投递当前要求双方是已接受的联系人,且两个设备均未撤销。接口校验 MLS 1.0 PrivateMessage 和 Welcome 的外层类型与长度,客户端负责完整协议验证。相同发送设备、接收设备、消息 ID 和封包的重试返回原游标,内容不同返回 409。`inbox_changed` 提示授权设备补拉。新的 PrivateMessage 投递在 `silent` 未开启且接收账号未静音此联系人时附带 `contactId` 和 `notify: true`。客户端对编辑、撤回和已读回执发送 `silent: true`。Welcome、重试及静音投递只发送补拉提示。投递保留期由 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 密文投递接口,客户端验证公告来自该会话经核验的群主设备。
邀请链接有效 24 小时,重新生成、撤销或群主转让会使当前链接失效。服务端保存邀请码的 SHA-256 摘要。单次领取和创建待接受邀请在同一事务内完成,领取后须接受邀请才可访问成员和加密会话。链接使用 URL 片段,客户端在确认领取时才把邀请码发给当前服务。
创建或更新群资料和成员后,受影响账号的在线客户端收到 `{"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 与独立的管理接口。