docs: describe login-only spaces and the 8.0.0 contract [CI]

docs/api.md

@@ -2,9 +2,9 @@
 
 账户资料使用 `GET/PATCH /accounts/profile`；头像为 PNG/JPEG/WebP data URI，禁止远程 URL 和 SVG。不提供旧资料导入。
 空间结构使用 `GET /spaces/{id}/structure`，包含 revision、channels、groups、folders、locations。频道与分组分别通过 `/spaces/{id}/channels` 和 `/spaces/{id}/groups` 创建；响应同时包含完整结构快照和服务端新建实体及 ID。其他字段通过 PATCH 重命名；频道归属通过 `PUT /spaces/{id}/channels/{channelId}/group` 修改。文件夹通过 `/spaces/{id}/folders` 创建及 PATCH 重命名，文件归属通过 `PUT /spaces/{id}/locations` 修改。
-频道、分组和目录写操作需要账号会话和空间写权限；允许上传的访客可以关联和移动自己的资源，文件移动必须满足每个条目的作者或管理权限，跨空间、跨频道的错误分组/目录关联被拒绝。结构修改后通知订阅设备重新拉取。
+频道、分组和目录写操作需要账号会话和空间写权限；允许上传的成员可以关联和移动自己的资源，文件移动必须满足每个条目的作者或管理权限，跨空间、跨频道的错误分组/目录关联被拒绝。结构修改后通知订阅设备重新拉取。
 
-URL 基础路径保留 `/api/v1`，`/info.contract_version` 为 `7.0.0`。v7 把「设备」收束为账号的属性：成员只按用户管理，`seats` 系列命名改为 `max_members` / `members_used` / `members_full`，去掉设备名与设备清单接口，访客改走 `/guests`，登录账号不再需要终端密钥。v6 引入账号签名根密钥、设备证书和频道对象签名事件；不兼容的旧主版本客户端会被契约预检拒绝。账号资料与空间结构由服务端管理。创建频道/分享以及所有 owner 管理操作必须携带有效账号 session；公开链接仍允许访客按频道加入规则访问。
+URL 基础路径保留 `/api/v1`，`/info.contract_version` 为 `8.0.0`。v8 让频道强制登录：去掉未登录访客（设置 `allow_guests`、`/guests` 接口、访客终端席位），频道与空间的所有接口都要求账号会话，缺少时返回 `401 account_required`；便捷分享（`/shares`）不受影响。v7 把「设备」收束为账号的属性：成员只按用户管理，`seats` 系列命名改为 `max_members` / `members_used` / `members_full`，去掉设备名与设备清单接口，登录账号不再需要终端密钥。v6 引入账号签名根密钥、设备证书和频道对象签名事件；不兼容的旧主版本客户端会被契约预检拒绝。账号资料与空间结构由服务端管理。创建频道/分享以及所有 owner 管理操作必须携带有效账号 session；频道链接只对登录账号有效，未登录的人先登录再按加入规则加入。
 
 `GET /info` 的 `defaults` 包含 `channel`、`share` 创建设置；省略创建请求的 settings 时服务端使用相同默认值。`choices.max_members` 与 `limits.max_members` 表示成员人数范围，不代表设备数。频道设置 JSON 字段为 `max_members`（旧存储里的 `seats` 在启动时迁移）。其他选项按部署限制收束，前端只格式化选项文案，不提供替代业务默认值。
 
@@ -16,24 +16,24 @@ URL 基础路径保留 `/api/v1`，`/info.contract_version` 为 `7.0.0`。v7 把
 |---|---|
 | `X-WD-Role` | `read` / `write` / `owner`,指明 `Authorization` 里的令牌属于哪种角色 |
 | `Authorization` | `Bearer <base64url(令牌)>` |
-| `X-WD-Endpoint` | `base64url(S)`,终端密钥。**只有未登录访客必填**;登录账号以 `X-WD-Account` 会话鉴权,可省略 |
+| `X-WD-Endpoint` | `base64url(S)`,终端密钥。**只用于便捷分享**(未登录的创建者与读者);频道与空间不使用,可省略 |
 | `X-WD-Cap` | 创建频道时的 Cap 验证码 token(服务端启用验证码时必填,见 protocol §11) |
 | `X-WD-Max-Downloads` | 第 0 帧上带,条目的下载上限,0 为不限 |
-| `X-WD-Account` | 账号 session token。与频道/分享的能力令牌分开；创建、管理和账号成员请求必填，访客省略 |
+| `X-WD-Account` | 账号 session token。与频道/分享的能力令牌分开；频道、空间、创建和管理请求必填 |
 | `X-WD-Event-*` | 已登记签名设备提交频道对象 FINAL 帧时必填，绑定对象 ID、域/epoch、事件类型与完整密文帧 manifest，见 protocol §21 |
 
-raw 模式的读请求不需要令牌,但仍需要 `X-WD-Endpoint`。
+raw 模式的读请求不需要令牌,但仍需要账号会话。
 
-WebSocket 无法设置头,令牌通过 `Sec-WebSocket-Protocol` 传递:`wd.v1, wd.role.<role>, wd.auth.<base64url(令牌)>, wd.ep.<base64url(S)>`,服务端回选 `wd.v1`。不要放进 URL,否则会被代理记录。
+WebSocket 无法设置头,令牌通过 `Sec-WebSocket-Protocol` 传递:`wd.v1, wd.role.<role>, wd.auth.<base64url(令牌)>, wd.account.<base64url(账号 session)>`,服务端回选 `wd.v1`。不要放进 URL,否则会被代理记录。
 
 ## 2. 权限矩阵
 
 | 操作 | 需要 |
 |---|---|
-| 读日志、拉取条目 | `read`(enc)或知道 id(raw),并已是成员(账号)或已加入的访客终端 |
+| 读日志、拉取条目 | `read`(enc)或知道 id(raw),并已是该频道的成员(账号) |
 | 追加帧 | `write`(`members_can_upload` 为 true 时)或 `owner` |
-| 删除条目 | `owner`;`delete_policy=own` 时账号等于条目作者(访客为终端哈希等于条目作者);`anyone` 时任意成员 |
-| 改设置、删频道、看和移除访客 | `owner`;这些管理操作不占成员名额 |
+| 删除条目 | `owner`;`delete_policy=own` 时账号等于条目作者;`anyone` 时任意成员 |
+| 改设置、删频道、撤销成员 | `owner`;这些管理操作不占成员名额 |
 
 ## 3. 接口
 
@@ -77,16 +77,16 @@ WebSocket 无法设置头,令牌通过 `Sec-WebSocket-Protocol` 传递:`wd.v1, w
 raw 模式省略 `read_hash`;`write_hash` 仅在成员可上传时提供。创建者自动成为频道的所有者成员。返回 `201`,响应体与「读取频道信息」相同(`ChannelInfo`)。
 
 ### `GET /api/v1/channels/{id}`
-返回 `ChannelInfo`:设置(包含所有成员共享的频道名)、模式、成员名额占用(`members_used`)、`oldest_seq`、`last_seq`、时间。`members_used` 统计唯一账号成员和匿名访客终端，不统计账号的设备数。**不占成员名额**,任意角色可调用,用于加入前预览和核对模式。频道名是普通设置,服务端可见。
+返回 `ChannelInfo`:设置(包含所有成员共享的频道名)、模式、成员名额占用(`members_used`)、`oldest_seq`、`last_seq`、时间。`members_used` 统计唯一账号成员，不统计账号的设备数。**不占成员名额**,需要账号会话,用于加入前预览和核对模式。频道名是普通设置,服务端可见。
 
 ### `POST /api/v1/channels/{id}/join`
-加入频道。登录账号只登记成员关系：账号第一次加入时占一个成员名额，同一账号的更多设备不增加名额、也不登记终端，此后仅凭账号会话鉴权（`X-WD-Endpoint` 可省略）。未登录访客登记一个终端（`X-WD-Endpoint` 必填），每个访客终端各计一个成员名额。同一账号或同一访客终端重复调用幂等。成员名额已满时返回 `403 members_full`。读取频道信息和 owner 管理接口不占成员名额；访客访问频道内容前必须已加入，否则返回 `403 not_joined`。响应 `JoinResult`：`{joined_at, members_used, members_max}`，不再返回终端标识。
+加入频道，必须带账号会话（没有则 `401 account_required`）。只登记成员关系：账号第一次加入时占一个成员名额，同一账号的更多设备不增加名额，此后仅凭账号会话鉴权。同一账号重复调用幂等。成员名额已满时返回 `403 members_full`。读取频道信息和 owner 管理接口不占成员名额；访问频道内容前必须已加入，否则返回 `403 not_joined`。响应 `JoinResult`：`{joined_at, members_used, members_max}`，不再返回终端标识。
 
-可发送 JSON `{password}`。默认 `join_policy=open,allow_guests=true`，允许持链接的陌生人设备加入。`allow_guests=false` 要求账号登录；`join_policy=invite` 要求该账号已受邀。频道主、已加入的账号成员和受邀账号无需再次输入频道密码。密码由服务端保存加盐 PBKDF2 哈希，从不通过频道信息返回。设备是账号的属性：同一账号可在任意多台设备登录，只占一个成员名额；账号成员的读写请求出示有效账号 session 即可，不再绑定到某个终端。
+可发送 JSON `{password}`。`join_policy=open` 允许持链接的登录账号加入；`join_policy=invite` 要求该账号已受邀。频道主、已加入的账号成员和受邀账号无需再次输入频道密码。密码由服务端保存加盐 PBKDF2 哈希，从不通过频道信息返回。设备是账号的属性：同一账号可在任意多台设备登录，只占一个成员名额；账号成员的读写请求出示有效账号 session 即可，不再绑定到某个终端。
 
-`GET /channels/{id}/members` 返回频道内账号成员及 `owner|member` 角色，每项附带账号级 `online`（该账号在本频道有活动 WebSocket/SSE 订阅）、`devices`（该账号的登录设备数，不小于 `online_devices`）与 `online_devices`（该账号此刻在本频道有订阅的设备数）；设备是账号的属性，不单独作为成员。在线状态只来自内存里的订阅登记，不写库、不经订阅流推送，客户端按需轮询；访客没有账号身份，不参与统计。`GET /channels/{id}/invitations` 不再返回已经成为成员的账号。邀请前，频道主调用 `GET /channels/{id}/invitations/{username}/crypto-plan` 获取服务端根据成员权限和历史设置计算的域/epoch/收件人计划。浏览器只为计划中的收件人生成并封装域密钥；随后 `POST /channels/{id}/invitations` 原子提交账号链接包与 `domain_envelopes`。服务端会重新计算计划并校验每个 epoch 和收件人，不接受前端自行增加授权或选择轮换范围。`DELETE /channels/{id}/invitations/{username}` 撤销邀请、成员授权与域密钥包，并阻止重新加入，直到再次邀请。不能移除频道主。移除访客用 `DELETE /channels/{id}/guests/{endpoint_hash}`，同样阻止该终端重新加入。
+`GET /channels/{id}/members` 返回频道内账号成员及 `owner|member` 角色，每项附带账号级 `online`（该账号在本频道有活动 WebSocket/SSE 订阅）、`devices`（该账号的登录设备数，不小于 `online_devices`）与 `online_devices`（该账号此刻在本频道有订阅的设备数）；设备是账号的属性，不单独作为成员。在线状态只来自内存里的订阅登记，不写库、不经订阅流推送，客户端按需轮询。`GET /channels/{id}/invitations` 不再返回已经成为成员的账号。邀请前，频道主调用 `GET /channels/{id}/invitations/{username}/crypto-plan` 获取服务端根据成员权限和历史设置计算的域/epoch/收件人计划。浏览器只为计划中的收件人生成并封装域密钥；随后 `POST /channels/{id}/invitations` 原子提交账号链接包与 `domain_envelopes`。服务端会重新计算计划并校验每个 epoch 和收件人，不接受前端自行增加授权或选择轮换范围。`DELETE /channels/{id}/invitations/{username}` 撤销邀请、成员授权与域密钥包，并阻止重新加入，直到再次邀请。不能移除频道主。移除访客用 `DELETE /channels/{id}/guests/{endpoint_hash}`，同样阻止该终端重新加入。
 
-频道设置、成员权限、邀请、加入密码与加密模式统一作用于同一 Channel。每次上传、发言、线程/目录控制条目写入均经服务器校验账号会话(或访客终端)、频道成员关系与写入权限，不能靠客户端隐藏按钮绕过。移除账号成员才会释放成员名额；撤销账号的某台登录设备只使该设备的会话失效，不影响成员身份。WebSocket 账号 session 经 `wd.account.<base64url(token)>` 子协议传递，并在推送循环中重新检查有效性。
+频道设置、成员权限、邀请、加入密码与加密模式统一作用于同一 Channel。每次上传、发言、线程/目录控制条目写入均经服务器校验账号会话、频道成员关系与写入权限，不能靠客户端隐藏按钮绕过。移除账号成员才会释放成员名额；撤销账号的某台登录设备只使该设备的会话失效，不影响成员身份。WebSocket 账号 session 经 `wd.account.<base64url(token)>` 子协议传递，并在推送循环中重新检查有效性。
 
 ### `PATCH /api/v1/channels/{id}/settings`
 所有者修改设置。可通过 `name` 更新共享频道名,传空字符串清除名称;`max_members` 调整成员人数上限，不能改变已有成员身份;`ttl_seconds` 的修改从现在起算。
@@ -112,7 +112,7 @@ raw 模式省略 `read_hash`;`write_hash` 仅在成员可上传时提供。创
 ### `GET /api/v1/channels/{id}/ws?from=<seq>`
 WebSocket 订阅(降级链的第一级)。服务端向下推送:
 - 二进制消息:一条日志记录。
-- 文本消息(JSON 控制消息):`{"t":"hb","seq":N}` 心跳,`{"t":"settings"}` 设置变更,`{"t":"members"}` 成员/访客变更。
+- 文本消息(JSON 控制消息):`{"t":"hb","seq":N}` 心跳,`{"t":"settings"}` 设置变更,`{"t":"members"}` 成员变更。
 
 上传仍走 HTTP `POST`,便于幂等重试。
 
@@ -123,15 +123,14 @@ SSE 订阅(降级链的第二级)。记录以 base64url 放在 `data:` 中,`id:`
 WebSocket → SSE → 长轮询,每一级失败自动降级。心跳间隔 20 秒,45 秒收不到任何消息即判定死链。重连使用指数退避(1 秒到 30 秒)加抖动,并携带 `from=last_seq+1`。
 
 ### `GET /api/v1/channels/{id}/items/{item_id}/frames?from=<index>`
-拉取条目的帧(GATED 条目的取数方式)。`from=0` 计一次下载;`from>0` 只有同一下载方（登录账号按用户，访客按终端）此前对同一条目成功启动过 `from=0` 才能续传,否则返回 `410 gone`。条目尚未 FINAL 时,响应会随帧到达持续输出,直到 FINAL。达到下载上限后返回 `410`,并在 5 分钟宽限期后删除密文,宽限期内已开始的拉取可继续续传。
+拉取条目的帧(GATED 条目的取数方式)。`from=0` 计一次下载;`from>0` 只有同一下载方（按用户）此前对同一条目成功启动过 `from=0` 才能续传,否则返回 `410 gone`。条目尚未 FINAL 时,响应会随帧到达持续输出,直到 FINAL。达到下载上限后返回 `410`,并在 5 分钟宽限期后删除密文,宽限期内已开始的拉取可继续续传。
 
 ### `DELETE /api/v1/channels/{id}/items/{item_id}`
 按 `delete_policy` 授权后删除条目,并在日志中追加 tombstone。已登记签名设备还必须提交对应 `chat.delete`/`file.delete` 事件头；服务端验证其绑定的设备证书、权限和原对象帧 manifest 后保存删除签名，浏览器验签后才应用 tombstone。
 
-### 访客
-- `GET /api/v1/channels/{id}/guests`:所有者查看未登录访客的终端(`endpoint_hash`、`joined_at`)。账号成员按用户管理(`/members`、`/invitations`),其设备不对外列出。
-- `DELETE /api/v1/channels/{id}/guests/{endpoint_hash}`:所有者移除该访客终端并禁止它再加入,其活动订阅随后被拒绝(`not_joined`);对账号终端返回 `404`。
-- 已移除:`PUT /channels/{id}/seats/me`、`PUT /channels/{id}/seats/{endpoint_hash}/label`、`GET/DELETE /channels/{id}/seats`。设备名只在账号设备管理里存在(`/accounts/devices`)。
+### 已移除的接口
+- v8:`GET /channels/{id}/guests`、`DELETE /channels/{id}/guests/{endpoint_hash}`(频道不再有未登录访客;成员按用户管理:`/members`、`/invitations`)。
+- v7:`PUT /channels/{id}/seats/me`、`PUT /channels/{id}/seats/{endpoint_hash}/label`、`GET/DELETE /channels/{id}/seats`。设备名只在账号设备管理里存在(`/accounts/devices`)。
 
 ## 4. 便捷分享接口
 
@@ -210,8 +209,9 @@ WebSocket → SSE → 长轮询,每一级失败自动降级。心跳间隔 20
 |---|---|---|
 | `bad_request` | 400 | 封装格式或参数错误 |
 | `unauthorized` | 401 | 令牌缺失或错误 |
+| `account_required` | 401 | 需要账号会话:频道与空间只接受已登录账号,账号会话缺失或已失效 |
 | `forbidden` | 403 | 角色不够 |
-| `not_joined` | 403 | 访客终端未加入或已被所有者移除,或账号不是该频道成员 |
+| `not_joined` | 403 | 账号不是该频道成员(未加入或已被所有者移除) |
 | `visitors_full` | 403 | 便捷分享的访客名额已满,且这个终端未登记 |
 | `sealed` | 409 | 便捷分享已封存,不能再修改;封存后再用所有者令牌发请求也是这个错误 |
 | `members_full` | 403 | 成员人数已满 |