feat(api): bind encrypted workspaces to accounts and devices

docs/api.md

@@ -1,4 +1,6 @@
-# API v1
+# API 契约 2.1
+
+URL 基础路径保留 `/api/v1`，`/info.contract_version` 为 `2.1.0`。旧主版本客户端会被契约预检拒绝。创建频道/分享以及所有 owner 管理操作必须携带有效账号 session；公开链接仍允许访客按频道加入规则访问。
 
 基础路径 `/api/v1`。所有请求和响应的二进制数据格式见 [protocol.md](protocol.md)。前端托管在独立域名,服务端需要配置 CORS 白名单。
 
@@ -10,8 +12,8 @@
 | `Authorization` | `Bearer <base64url(令牌)>` |
 | `X-WD-Endpoint` | `base64url(S)`,终端密钥,用于席位 |
 | `X-WD-Cap` | 创建频道时的 Cap 验证码 token(服务端启用验证码时必填,见 protocol §11) |
-| `X-WD-Label` | raw 模式条目标签,≤255 B |
 | `X-WD-Max-Downloads` | 第 0 帧上带,条目的下载上限,0 为不限 |
+| `X-WD-Account` | 账号 session token。与频道/分享的能力令牌分开；创建、管理和账号成员请求必填，访客省略 |
 
 raw 模式的读请求不需要令牌,但仍需要 `X-WD-Endpoint`。
 
@@ -28,17 +30,32 @@ WebSocket 无法设置头,令牌通过 `Sec-WebSocket-Protocol` 传递:`wd.v1, w
 
 ## 3. 接口
 
+### 账号与保险库
+
+用户名为 3–32 位 ASCII 字母、数字、`_` 或 `-`，大小写不敏感。客户端 PBKDF2-SHA256（600,000 次）派生口令根，再分别派生登录凭据和 AES-GCM 保险库密钥。登录凭据仅经 HTTPS 发送；服务端再用随机 salt 和 PBKDF2-SHA256（210,000 次）存储慢哈希，数据库里的哈希不能直接用于登录。服务端不接收口令根或保险库密钥。二进制字段使用标准 Base64，保险库密文最大 1.3 MB。
+
+- `POST /api/v1/accounts` 注册 `{username,salt,verifier,vault,public_key}`。public_key 为 P-256 ECDH 公钥 JWK 的 JSON 字符串；私钥只在客户端加密保险库中保存。
+- `POST /api/v1/accounts/salt` 请求 `{username}`，返回 `{salt}`，供客户端派生登录凭据。
+- `POST /api/v1/accounts/session` 请求 `{username,verifier,device_id?,device_name?}`。成功返回 `{username,token}`；session token 随机生成，只保存 SHA-256，期限 30 天。
+- `GET /api/v1/accounts/vault` 使用 `Authorization: Bearer <token>` 读取 `{revision,vault}`。
+- `PUT /api/v1/accounts/vault` 使用同一鉴权，发送 `{revision,vault}`。revision 乐观并发控制；冲突返回 `409 vault_conflict`，客户端必须先读取并合并，不能静默覆盖。
+- `DELETE /api/v1/accounts/session` 撤销当前 bearer session；退出登录时调用。
+- `GET /api/v1/accounts/users/{username}/key` 已登录用户查询收件账号公开邀请密钥。
+- `GET /api/v1/accounts/invitations` 返回当前账号的邀请，payload 为绑定收件用户名和频道 ID 的 ECDH + HKDF + AES-GCM 密文。
+
+没有邮箱找回流程。忘记密码后保险库无法恢复。保险库仅同步资源凭据和草稿清单，不同步设备 S、设备名、缓存、原始文件或发送队列。浏览器存储按账号与访客分库；切换账号会中止订阅并清空内存会话。资源清单移除使用带时间戳的墓碑同步，避免旧设备将条目恢复。
+
 ### `GET /api/v1/info`
 返回服务端能力:协议版本、限制、验证码配置(`captcha.provider`、`captcha.enabled`、`captcha.api_endpoint`,即 Cap widget 要连接的地址)、传输能力。验证码的 secret 不会出现在这里。`transports.http3` 只是部署层(反向代理或 Kestrel 配置)声明已启用 HTTP/3,服务端进程本身不内置 QUIC。
 
 ### `POST /api/v1/channels`
-创建频道。服务端启用验证码时需要 `X-WD-Cap`;验证服务不可用时返回 `503 captcha_unavailable`,与「用户没通过验证」(`428 captcha_required`)区分。
+创建者必须登录。只有一套频道/成员/线程模型，`mode=enc|raw` 仅决定客户端内容是否端到端加密，不改变业务权限。创建者自动写入该频道的 owner 成员记录并占一个设备席位。服务端启用验证码时还需要 `X-WD-Cap`。
 
 ```json
 {
   "id": "<channel_id>",
   "mode": "enc",
-  "settings": { "seats": 2, "members_can_upload": true, "delete_policy": "own",
+  "settings": { "name": "工作设备", "seats": 2, "members_can_upload": true, "delete_policy": "own",
                 "ttl_seconds": 86400, "max_items": 1000, "file_max_downloads": 10 },
   "read_hash": "<sha256(T_read)>",
   "write_hash": "<sha256(T_write)>",
@@ -49,13 +66,19 @@ WebSocket 无法设置头,令牌通过 `Sec-WebSocket-Protocol` 传递:`wd.v1, w
 raw 模式省略 `read_hash`;`write_hash` 仅在成员可上传时提供。创建者的终端(`X-WD-Endpoint`)自动入席。返回 `201`,响应体与「读取频道信息」相同(`ChannelInfo`)。
 
 ### `GET /api/v1/channels/{id}`
-返回 `ChannelInfo`:设置、模式、席位占用、`oldest_seq`、`last_seq`、时间。**不占席位**,任意角色可调用,用于加入前预览和核对模式。
+返回 `ChannelInfo`:设置(包含所有成员共享的频道名)、模式、席位占用、`oldest_seq`、`last_seq`、时间。**不占席位**,任意角色可调用,用于加入前预览和核对模式。频道名是普通设置,服务端可见。
 
 ### `POST /api/v1/channels/{id}/seats`
 加入频道,占用一个席位。幂等:同一终端重复调用返回同一席位。席位已满返回 `403 seats_full`。读取频道信息和 owner 管理接口不占席位;频道内容、席位信息/设备名等其余操作要求终端已入席,否则返回 `403 not_joined`。
 
+可发送 JSON `{password}`。默认 `join_policy=open,allow_guests=true`，允许持链接的陌生人设备加入。`allow_guests=false` 要求账号登录；`join_policy=invite` 要求该账号已受邀。频道主、已加入的账号成员和受邀账号无需再次输入频道密码。密码由服务端保存加盐 PBKDF2 哈希，从不通过频道信息返回。成员账号和设备身份独立：同一账号可占多个独立设备席位；账号成员的读写请求必须出示对应账号 session 和该设备 S。
+
+`GET /channels/{id}/members` 返回频道内账号成员及 `owner|member` 角色。`GET/POST /channels/{id}/invitations` 由频道主查询/发送 `{username,payload}` 邀请；payload 只含客户端加密的成员链接。`DELETE /channels/{id}/invitations/{username}` 撤销邀请、成员授权与该账号的设备席位，并阻止重新加入，直到再次邀请。不能移除频道主。设备面板踢出访客也会阻止该 S 重新加入。
+
+频道设置、成员权限、邀请、加入密码与加密模式统一作用于同一 Channel。每次上传、发言、线程/目录控制条目写入均经服务器校验账号或访客设备、频道成员/席位与写入权限，不能靠客户端隐藏按钮绕过。WebSocket 账号 session 经 `wd.account.<base64url(token)>` 子协议传递，并在推送循环中重新检查有效性。
+
 ### `PATCH /api/v1/channels/{id}/settings`
-所有者修改设置。`ttl_seconds` 的修改从现在起算。
+所有者修改设置。可通过 `name` 更新共享频道名,传空字符串清除名称;`ttl_seconds` 的修改从现在起算。
 
 ### `DELETE /api/v1/channels/{id}`
 所有者删除整个频道和全部密文。
@@ -96,8 +119,9 @@ WebSocket → SSE → 长轮询,每一级失败自动降级。心跳间隔 20
 
 ### 席位
 - `GET /api/v1/channels/{id}/seats`:所有者查看(终端哈希、加密设备名、加入时间)。
-- `PUT /api/v1/channels/{id}/seats/me`:终端上传加密设备名(≤256 B)。
-- `DELETE /api/v1/channels/{id}/seats/{endpoint_hash}`:所有者释放席位。
+- `PUT /api/v1/channels/{id}/seats/me`:终端上传设备名(≤256 B);enc 模式加密,raw 模式明文。
+- `PUT /api/v1/channels/{id}/seats/{endpoint_hash}/label`:所有者为指定设备更新名称;enc 模式的密文绑定目标 endpoint hash,raw 模式明文。设备也可用 `/seats/me` 更新自己的名称。
+- `DELETE /api/v1/channels/{id}/seats/{endpoint_hash}`:所有者移除该设备的席位,其活动订阅随后会被拒绝。
 
 ## 4. 便捷分享接口
 
@@ -189,3 +213,15 @@ WebSocket → SSE → 长轮询,每一级失败自动降级。心跳间隔 20
 | `captcha_required` | 428 | 需要验证码:缺少 `X-WD-Cap`,或 token 无效、已用过 |
 | `captcha_unavailable` | 503 | 验证码服务暂时不可用(服务端到 Cap 的调用失败),可稍后重试 |
 | `rate_limited` | 429 | 限流 |
+
+### 按账号恢复频道密钥
+
+- `GET /api/v1/accounts/channels`：只需 `X-WD-Account`，返回当前账号已加入频道的 `{channel_id,role,payload,created_at}` 密钥包；不返回其他账号或未接受邀请的密钥包，不占席位。
+- `PUT /api/v1/channels/{id}/key-package`：需要该频道 owner 能力和 owner 账号，仅更新当前 owner 自己的 `{payload}`，用于补齐已创建频道的账号密钥包。
+- 创建频道可携带 `key_package`（1–16384 字符 opaque 密文），与频道和 owner 成员记录原子保存。前端必须提供；底层 API 允许省略供纯协议客户端使用。
+- 发送邀请时原子保存收件账号的密钥包；接受后仍可跨设备领取。撤销邀请/成员同时删除密钥包，删除频道清理全部密钥包。
+
+
+### 账号设备与资料
+
+GET /accounts/devices 返回本账号设备 {id,name,created_at,last_seen,current}。PATCH /accounts/devices/{id} 发送 {name}；DELETE 撤销该设备全部登录 sessions 与频道席位，不移除账号成员。新客户端登录时携带稳定浏览器 device_id（UUID）和设备名，各设备单独记录。个人名称/头像存储在客户端加密保险库，修改后按 modifiedAt 合并，不写入服务端明文账号表。昵称不改变固定用户名或参与密钥派生。