Files
XHChat/docs/api.md
T

4.0 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/mls-local-key 读取当前设备的公开认证密钥,供本机安全码计算
POST /api/v1/mls-credential 当前设备登记带认证密钥签名的 MLS 签名公钥
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 对象。已登记公钥仅允许原值重试。

下一阶段将增加 /conversations 和 /attachments。后续加入 /groups、/calls、/posts、/backups、/push 与独立的管理接口。