Files
XHChat/docs/api.md
T

58 lines
6.4 KiB
Markdown
Raw 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 |
| 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} | 查看群组详情或执行邀请、接受、拒绝、改名、升降管理员、移除、退出或解散 |
| 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/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 成员可以查看其他有效成员,群主与管理员还可查看待处理邀请。群主可解散、调整管理员和移除成员。管理员可改名、邀请好友和移除普通成员。
群组密文投递使用 `/groups/{id}/epochs` 和 `/groups/{id}/messages`。群主发布带 membershipVersion 的世代,选取每个有效成员的一台已登记 MLS 设备,提交其他设备的 Welcome。GET epochs 返回当前有效世代的设备名单和本设备获准接收的 Welcome,旧世代仅向在本次成员资格期间加入过该世代的设备返回。POST messages 接受当前世代的 MLS PrivateMessage,GET messages 通过 after 游标返回本设备有权读取的密文。
有效成员可通过 `GET /groups/{id}/devices` 获取群内有效设备凭据。群主通过 `POST /groups/{id}/devices/{device}/claim` 一次性领取其他有效成员的设备密钥包。邀请待接受的账号、已离群的账号和撤销设备无法访问群设备目录。
成员变更后旧世代不能发消息。绑定设备被撤销后需以替代设备发布新世代。重新加入的成员只能补拉本次加入以来的世代。服务端校验外层格式和投递授权,MLS 内容验证由客户端执行。
下一阶段将增加 /conversations、/calls、/posts、/backups、/push 与独立的管理接口。