feat(api)!: fold devices into users and report member presence
Contract 7.0.0 (breaking). Devices become an attribute of the account;
members are managed per user, and only unauthenticated guests keep a
per-terminal registration.
- rename seats -> max_members, seats_used -> members_used,
seats_full -> members_full, SeatJoined -> JoinResult, the `seats`
stream control message -> `members`, and POST /channels/{id}/seats ->
POST /channels/{id}/join (stored channel settings are migrated on start)
- drop per-terminal encrypted device labels and the seat list/release
endpoints; add GET/DELETE /channels/{id}/guests for guest terminals
- authenticate account members by account session only: the terminal key
is optional for logged-in accounts, no seat row is written for them,
and gated-download grants are counted per user (per terminal for guests)
- GET /channels/{id}/members now returns online, devices and
online_devices per account; presence is tracked in memory from active
WebSocket/SSE subscriptions and is not pushed over the stream
- owner invitation list no longer returns accounts that already joined
This commit is contained in:
justme committed
1 parent
0fd2a269d9
commit
d946fc5e8a
35 files changed
+517
-490
No files matched your search
+13
-14
@@ -25,7 +25,7 @@
|
||||
| `K` | 32 B | 空间/临时频道访问凭据；新工作区内容加密不使用它，可选能力链接使用 fragment |
|
||||
| `A` | 32 B | 管理密钥,独立随机,只存在于所有者链接 |
|
||||
| `W` | 32 B | 写密钥,仅 raw 模式且成员可上传时 |
|
||||
| `S` | 32 B | 终端密钥,每个频道每个终端各生成一个,仅存本地 |
|
||||
| `S` | 32 B | 访客终端密钥,每个频道每个访客终端各生成一个,仅存本地;登录账号不需要 |
|
||||
|
||||
## 2. 模式与链接
|
||||
|
||||
@@ -130,7 +130,7 @@ meta_len (u16) ‖ meta_json (UTF-8) ‖ content_bytes ...
|
||||
| `mime` | 可选 |
|
||||
| `size` | 可选,内容总字节数(流式时可省略) |
|
||||
| `ts` | 毫秒时间戳,仅供参考,排序以 seq 为准 |
|
||||
| `dev` | 可选,设备名 |
|
||||
| `dev` | 已弃用(v7 起客户端不再写入,读取时忽略);发送者以服务端记录的账号为准 |
|
||||
| `thread_id` | 可选,频道 thread ID |
|
||||
| `folder_id` | 可选,文件的虚拟文件夹 ID |
|
||||
|
||||
@@ -161,7 +161,7 @@ meta_len (u16) ‖ meta_json (UTF-8) ‖ content_bytes ...
|
||||
**推送规则**:
|
||||
- 非 GATED 条目以 frame 记录推送给订阅者。服务端强制:**非 GATED 条目必须是单帧且带 FINAL**(`frame_index = 0`)。
|
||||
- GATED 条目只推送一条 announce,字节通过条目拉取接口取得(见 api.md),`from=0` 的拉取计入下载次数。
|
||||
- `from>0` 只有在同一终端此前已对同一条目成功发起 `from=0` 后才是有效续传;服务端按资源、条目和终端绑定这份续传许可,任意跳到中间帧不能绕过下载次数。
|
||||
- `from>0` 只有在同一下载方(登录账号按用户,访客按终端)此前已对同一条目成功发起 `from=0` 后才是有效续传;服务端按资源、条目和下载方绑定这份续传许可,任意跳到中间帧不能绕过下载次数。
|
||||
- 因此客户端上传**多帧条目(文件)或带下载上限的条目时,必须设置 GATED**。
|
||||
- 同一条目的所有帧,SNAPSHOT 与 GATED 标志必须一致;FINAL 不能早于已存在的更大序号;已有 FINAL 之后不能再追加更大序号的帧。GATED 条目的帧允许乱序到达(并行上传),条目拉取只返回从起点开始连续的帧。
|
||||
|
||||
@@ -175,16 +175,15 @@ meta_len (u16) ‖ meta_json (UTF-8) ‖ content_bytes ...
|
||||
|
||||
带 SNAPSHOT 的条目取代频道中之前的快照条目(最后写入者胜)。快照必须是**非 GATED 的单帧**(整份状态不超过一帧,约 1 MiB),所以新快照一被接受,服务端就在同一个事务里删除旧快照并产生一条 `reason = 4` 的 tombstone。一个频道在 v1 里只有一个快照槽,多文档请使用多个频道。
|
||||
|
||||
## 10. 终端与成员人数
|
||||
## 10. 用户、设备与成员人数
|
||||
|
||||
- 终端在本地为每个频道生成随机 `S`,请求中带 `S`;服务端保存 `SHA-256(S)` 作为终端标识。
|
||||
- 终端通过显式的加入请求(`POST .../seats`)建立设备席位;创建者的当前终端在创建时自动入席。席位用于设备级认证、命名和撤销，不限制同一账号可加入的设备数量。未入席的终端访问频道返回 `not_joined`。
|
||||
- 频道设置字段 `seats` 保留原线格式名称，但 v5 起表示**最大成员人数**。owner 和每个唯一账号各计一人，同一账号的额外设备不增加人数。成员人数达到上限时，新的账号成员加入返回 `seats_full`。
|
||||
- 未登录访客没有可跨设备识别的账号身份，每个访客终端按一个访客成员计入上限；因此访客在多台设备加入会占多个名额。若希望严格按自然人去重，应要求加入者登录账号。
|
||||
- 不同频道使用不同的 `S`,避免服务端把同一设备关联起来。
|
||||
- 终端可以加密一个设备名上传,所有者能看到设备列表和设备名,并可以释放单个设备席位。
|
||||
- 终端可更新自己的名称;所有者也可重命名任意设备席位。enc 模式重命名仍使用同一份加密设备标签,并将 AAD 绑定目标 endpoint hash;raw 模式标签仍为明文。撤销设备席位后,该终端不能继续读取频道，但账号成员身份和其人数名额保留；撤销账号成员/邀请才释放该账号名额。
|
||||
- **设备名格式(enc)**:`iv(12 B 随机) ‖ AES-256-GCM(K_label, utf8 名称) ‖ tag(16 B)`,AAD = `"WD1L"`(4 B ASCII)‖ `channel_id` ‖ `endpoint_hash`(32 B,即 `SHA-256(S)`)。总长不超过 256 B,所以名称最多 228 字节 UTF-8。使用派生子密钥 `K_label` 而不是直接用 `K_enc`,避免同一密钥同时用于 HKDF 和 AES-GCM;AAD 绑定终端,服务端无法把一个终端的设备名挪到另一个席位上。raw 模式下设备名是明文 UTF-8。
|
||||
- **成员是用户(账号)**。设备只是账号的属性：同一账号可在任意多台设备登录，只占一个成员名额；账号成员的请求凭有效的账号 session 鉴权，不再需要终端密钥，也不登记终端。
|
||||
- **访客**是未登录的终端：本地为每个频道生成随机 `S`，请求中带 `S`，服务端保存 `SHA-256(S)` 作为访客标识，并通过显式的加入请求（`POST .../join`）登记。未加入的访客访问频道返回 `not_joined`；所有者可以列出（`GET .../guests`）并移除（`DELETE .../guests/{endpoint_hash}`）访客。
|
||||
- 频道设置字段 `max_members`（v7 前叫 `seats`）是**最大成员人数**。owner 和每个唯一账号各计一人，同一账号的额外设备不增加人数；访客没有可跨设备识别的账号身份，每个访客终端按一个访客成员计入上限，因此访客在多台设备加入会占多个名额。成员人数达到上限时，新的成员加入返回 `members_full`。若希望严格按自然人去重，应要求加入者登录账号。
|
||||
- 不同频道使用不同的 `S`（仅访客），避免服务端把同一访客终端关联起来。
|
||||
- 受限下载（GATED）的计数单位是「下载方」：登录账号按用户，访客按终端；同一下载方对同一条目重复发起 `from=0` 才算续传。
|
||||
- 在线状态由服务端按账号统计（`members` 接口的 `online`、`devices`、`online_devices`），只来自内存里的订阅登记，不写库。
|
||||
- **已移除**：每终端的加密设备名（`K_label`、AAD `WD1L`、`PUT .../seats/me` 与 `.../seats/{hash}/label`）和设备席位清单。设备名只在账号设备管理里存在（`/accounts/devices`）。`K_label` 的派生仍保留在 §3，为已发布的测试向量保持稳定，但不再被使用。
|
||||
|
||||
## 11. 创建与验证码
|
||||
|
||||
@@ -205,7 +204,7 @@ meta_len (u16) ‖ meta_json (UTF-8) ‖ content_bytes ...
|
||||
| 设置 | 默认 | 范围 |
|
||||
|---|---|---|
|
||||
| `name` | 无 | 可选,最多 48 个字符;所有频道成员和服务端可见 |
|
||||
| `seats`(v5 起为成员人数上限) | 2 | 1..64(服务端可配置上限);每个账号计一人,其多设备不增加人数 |
|
||||
| `max_members`(v7 前叫 `seats`,最大成员人数) | 2 | 1..64(服务端可配置上限);每个账号计一人,其多设备不增加人数 |
|
||||
| `members_can_upload` | true | |
|
||||
| `delete_policy` | `own` | `owner_only` / `own` / `anyone` |
|
||||
| `ttl_seconds` | 86400 | 最长 604800,每个条目从创建起算 |
|
||||
@@ -346,7 +345,7 @@ meta_len (u16) ‖ meta_json (UTF-8) ‖ content_bytes ...
|
||||
|
||||
## 17. 账号凭据与频道域密钥
|
||||
|
||||
空间访问凭据用于服务端资源/终端鉴权，不是频道内容根。创建者用自己的账号 P-256 公钥封装 Owner 凭据，随空间、默认频道、Owner 成员记录原子保存。账号接受空间邀请后，可凭账号 session 从 `/accounts/channels` 取回自己的空间凭据；设备席位仍在实际打开空间时建立。
|
||||
空间访问凭据用于服务端资源/终端鉴权，不是频道内容根。创建者用自己的账号 P-256 公钥封装 Owner 凭据，随空间、默认频道、Owner 成员记录原子保存。账号接受空间邀请后，可凭账号 session 从 `/accounts/channels` 取回自己的空间凭据；账号成员不登记终端，实际打开空间时只确认成员关系（`POST .../join` 幂等）。
|
||||
|
||||
内容加密密钥由浏览器生成。每个频道各有独立 `chat` 与 `files` 域，每域从 epoch 1 开始使用随机 32 B key。域信封沿用账号 ECDH、HKDF、AES-GCM，AAD 绑定账号、空间 ID、频道 ID、域名与 epoch。服务端保存 opaque 密文，只向通过频道/域读取授权的账号返回信封。每条消息、文件和加密发布元数据使用独立随机 32 B 对象密钥；对象密钥由域 key 的 AES-GCM 封装，AAD 绑定空间、频道、域、epoch 和 item ID。
|
||||
|
||||
|
||||
Reference in new issue
Block a user