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

docs/protocol.md

@@ -12,18 +12,18 @@
 |---|---|---|
 | `channel_id` | 16 B | 随机,客户端生成 |
 | `item_id` | 16 B | 随机,客户端生成 |
-| `K` | 32 B | 频道密钥,仅 enc 模式,只存在于 URL fragment |
+| `K` | 32 B | 频道密钥,仅 enc 模式,按账号加密封装；可选能力链接使用 fragment |
 | `A` | 32 B | 管理密钥,独立随机,只存在于所有者链接 |
 | `W` | 32 B | 写密钥,仅 raw 模式且成员可上传时 |
 | `S` | 32 B | 终端密钥,每个频道每个终端各生成一个,仅存本地 |
 
 ## 2. 模式与链接
 
-频道创建时二选一,之后不可更改。
+只有一个频道模型。创建时可选择是否启用端到端加密，默认 enc；raw 表示不加密内容。账号成员、所有者、加入规则、线程、目录、日志和权限完全共用，差别限于客户端的负载加解密。创建后不能改变加密方式。
 
 | | enc(默认) | raw |
 |---|---|---|
-| 负载 | AES-256-GCM 密文 | 原样字节,服务端可见 |
+| 负载 | AES-256-GCM 密文 | 共享条目结构的明文,服务端可见 |
 | 所有者链接 | `/c/{id}#k=<K>&a=<A>` | `/c/{id}#a=<A>[&w=<W>]` |
 | 成员链接 | `/c/{id}#k=<K>` | `/c/{id}[#w=<W>]` |
 | 读权限 | 持 `T_read` | 知道 id 即可(能力链接) |
@@ -70,7 +70,8 @@ raw 模式下 `T_owner` 同样由 `A` 派生;`T_write = W`。
 | 1 | SNAPSHOT | 该条目是频道的「最新快照」,取代之前的快照条目 |
 | 2 | GATED | 不通过实时推送内联分发,只能按条目拉取,并计下载次数 |
 | 3 | ENC | 负载为 AES-GCM 密文,必须与频道模式一致 |
-| 4-7 | 保留 | 必须为 0 |
+| 4 | CONTROL | 频道结构控制条目 |
+| 5-7 | 保留 | 必须为 0 |
 
 服务端拒绝不符合上述规则的封装,但从不解析负载。
 
@@ -120,15 +121,21 @@ meta_len (u16) ‖ meta_json (UTF-8) ‖ content_bytes ...
 | `size` | 可选,内容总字节数(流式时可省略) |
 | `ts` | 毫秒时间戳,仅供参考,排序以 seq 为准 |
 | `dev` | 可选,设备名 |
+| `thread_id` | 可选,频道 thread ID |
+| `folder_id` | 可选,文件的虚拟文件夹 ID |
 
 第 1 帧起,`data` 全部是内容字节。小内容(文本、JSON)一帧完成,没有额外开销。
 
-**raw 模式**:负载就是内容字节,没有 meta。条目名称等信息由用户在上传时放进 `X-WD-Label`(明文,≤255 B)。
+**频道 thread 与文件夹**:客户端把 thread/folder 元数据放在上述共享元数据中（enc 时加密，raw 时服务端可见）。thread 的创建、重命名,文件夹的创建/重命名,以及条目移动等操作以 `kind=other` 的 CONTROL 条目追加到同一频道日志;控制正文是版本化 JSON,仅客户端识别。它们不增加服务端表或第二套同步协议。新内容必须归属已创建的 thread；前端新建频道后自动发布“常规”thread 创建记录。GATED 的 announce 不含元数据，但 file.published 加密目录记录可在不下载内容时提供名称和归属；没有目录记录时显示通用占位符。
+
+**raw 模式（API 契约 2）**:负载使用与 enc 相同的 `u16 meta_len ‖ meta_json ‖ content` 条目结构，只是不加密。名称、thread/folder ID 与其他元数据对服务端可见。旧版“纯字节、无元数据”的 raw 负载不属于新应用契约，旧客户端会被 API 主版本检查拒绝。
 
 **未完成的条目**:没有 FINAL 的条目是「进行中」,接收方可以渐进消费(流式播放、边收边写),但必须标记为不完整,直到收到已认证的 FINAL。
 
 ## 8. 日志、序号与条目生命周期
 
+`CONTROL=0x10` 标记频道结构控制条目；保留位为 `0xE0`。控制条目必须是非 GATED、非 SNAPSHOT 的 FINAL 单帧，payload 最多 16,400 B；其生命周期为频道生命周期，不受普通内容 TTL 或 max_items 淘汰。每频道最多 4096 条控制记录，仍计入总字节配额。加密和非加密频道使用相同控制正文与日志处理。
+
 频道维护一条服务端排序的**日志**,每条记录的序号 `seq` 是 u64,频道内单调递增。
 
 | kind | 值 | 内容 |
@@ -164,11 +171,12 @@ meta_len (u16) ‖ meta_json (UTF-8) ‖ content_bytes ...
 - 终端通过显式的加入请求(`POST .../seats`)占用一个席位;创建者的终端在创建时自动入席。席位已满则拒绝新终端(`seats_full`),已入席的终端可重复加入(幂等)和重连。未入席的终端访问频道返回 `not_joined`。
 - 不同频道使用不同的 `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。
 
 ## 11. 创建与验证码
 
-创建频道是匿名接口,需要防刷。验证码**完全交给 [Cap](https://github.com/tiagozip/cap)**(基于 SHA-256 工作量证明的验证码),本协议不定义、也不实现任何 PoW。
+创建频道需要账号登录，仍需要防刷。验证码**完全交给 [Cap](https://github.com/tiagozip/cap)**(基于 SHA-256 工作量证明的验证码),本协议不定义、也不实现任何 PoW。
 
 流程:
 1. 前端从 `GET /api/v1/info` 读到 `captcha.enabled` 和 `captcha.api_endpoint`。
@@ -180,10 +188,11 @@ meta_len (u16) ‖ meta_json (UTF-8) ‖ content_bytes ...
 
 ## 12. 设置
 
-频道设置对服务端可见,服务端据此执行:
+频道设置对服务端可见,服务端据此执行。`name` 是共享频道名,所有加入者都从频道信息中读取:
 
 | 设置 | 默认 | 范围 |
 |---|---|---|
+| `name` | 无 | 可选,最多 48 个字符;所有频道成员和服务端可见 |
 | `seats` | 2 | 1..64(服务端可配置上限) |
 | `members_can_upload` | true | |
 | `delete_policy` | `own` | `owner_only` / `own` / `anyone` |
@@ -320,3 +329,28 @@ meta_len (u16) ‖ meta_json (UTF-8) ‖ content_bytes ...
 - 协议版本在封装的 `ver` 字段和 HKDF 的 `info`(`webdrop/v1/...`)中同时体现。
 - `test-vectors/` 提供固定输入、固定输出:密钥派生、令牌、加解密、padding、封装编解码,以及篡改、重排、截断、换频道的负例,必须全部通过。
 - 本版**预留**但不实现:口令叠加(Argon2id)、短配对码(PAKE)、多快照槽。
+
+## 17. 按账号分发频道密钥
+
+频道内容仍使用共享 K 加密。创建者用自己的账号 P-256 公钥封装 owner 凭据，随创建请求的 key_package 与频道、owner 成员记录在同一事务内保存。邀请时用收件账号公钥封装 member 凭据，服务端原子保存邀请和密钥包；账号接受邀请并成为成员后，可只凭账号 session 从 /accounts/channels 取回自己的密钥包，不需要含密钥的 URL，也不要求邀请者在线。成员包不得包含管理密钥 A。
+
+密钥包沿用邀请的 ECDH、HKDF、AES-GCM，AAD 绑定收件账号与频道 ID。服务端只保存 opaque 密文；成员私钥保存在口令加密的账号保险库。成员登录后解开保险库、取回密钥包，在 Worker 内恢复频道会话；新设备生成独立 S，打开频道时才占设备席位。待接受的邀请不会自动占席位。
+
+撤销成员时同时删除密钥包和席位。此举不能收回已交付的 K 或历史明文；当前没有轮换密钥或前向保密。仅知道频道 ID 或登录账号并不足以获得密钥；新账号必须得到现有持钥 owner 的授权封装。邀请公钥仍来自服务端目录，尚无外部指纹核验。
+
+
+## 18. 频道加密文件目录
+
+文件密文帧之后，在同一发送队列追加 CONTROL file.published，正文包含 item.id、kind=file、threadId、folderId（可选）、name、mime、size、ts、deviceId、gated。记录与 thread/folder 控制记录共用 webdrop.workspace v1 正文。名称/类型/大小/原始 thread/folder 必须与文件第 0 帧元数据相符。目录允许先显示名称，但不得因此自动下载 GATED 内容。
+
+客户端只有在当前日志存在对应文件帧或 announce 时展示目录；文件墓碑清除目录可见状态，全量重放时不恢复不存在/过期文件。目录记录属于 CONTROL，仍受 4096 条控制记录和频道字节配额限制。文件移动覆盖位置索引，不重新加密原始文件，不改变最初认证的内容元数据。
+
+## 19. 空间内的频道分组
+
+界面顶层“空间”对应协议 channel，界面“频道”对应 thread。沿用 webdrop.workspace v1 CONTROL 正文：group.create {id,name}，group.rename {id,name}，thread.group {id,groupId}（null 表示未分组）；thread.create 可包含 groupId。ID 为 UUID，name 为 1–80 个非控制字符。分组仅组织频道，成员、内容密钥和日志仍归属于空间。旧创建记录不含 groupId，作为未分组频道重放。
+
+## 20. 发送者展示快照
+
+file.published.item 可携带 author {username,displayName,avatar?}；另有 item.author {itemId,author} CONTROL，为文本关联展示身份。username 使用当前账号固定用户名，displayName 最多 48 个字符，avatar 仅允许不超过 8000 字符的 PNG/JPEG/WebP data URL。头像在客户端压缩为最多 64×64 后写入加密正文，不改变内容帧、密钥派生或鉴权头。
+
+快照是持钥成员提供的展示资料，不是发送者签名。无 author 的旧记录回退设备名；客户端不得将此类内容标记为当前账号发送。结构记录随既有 CONTROL 生命周期处理，实际消息可见性仍由条目和墓碑决定。