| 1 | # 工作间（Workroom）安全模型 |
| 2 | |
| 3 | > 英文原文：[WORKROOM_SECURITY.md](../WORKROOM_SECURITY.md)。 |
| 4 | > 最后与英文同步日期（last synced with English revision）：2026-09-29。 |
| 5 | |
| 6 | ## 范围 |
| 7 | |
| 8 | 本文涵盖 Codewhale 工作间的安全边界 —— 即 |
| 9 | [RFC 3209](../rfcs/3209-workrooms.md) 中描述的那种可持久化、可寻址的容器， |
| 10 | 用来承载分线程的智能体（agent）对话。 |
| 11 | |
| 12 | 工作间**不会**引入任何新的网络服务、云依赖或默认开启的公开分享。 |
| 13 | 安全责任仍归控制运行时（runtime）API 的运营者。 |
| 14 | |
| 15 | 本文描述 v0.9 工作间表面的预期安全契约。在 v0.8.62 中， |
| 16 | 只有协议数据类型和链接解析已经落地。持久化状态、运行时 API 端点、令牌作用域、 |
| 17 | 事件存储，以及模型可见的链接解析仍属后续工作。 |
| 18 | |
| 19 | ## 原则 |
| 20 | |
| 21 | 1. **本地优先。** 将来持久化的工作间状态应当放在 Codewhale 主目录之下， |
| 22 | 由仅限用户本人的文件系统权限保护。不进行云同步，也不做第三方托管。 |
| 23 | 工作间内容永远不是遥测对象：`docs/TELEMETRY.md` 里的匿名使用计数 |
| 24 | 只收集计数和封闭枚举，任何工作间的 id、标题、链接或正文都不得加入其 schema。 |
| 25 | 该遥测现在有一个已上线的摄取端点 |
| 26 | （`https://telemetry.codewhale.net/v1/telemetry`，源码在 `telemetry-ingest/`）， |
| 27 | 这让该规则从“仅仅声明”变成“实际强制”：端点按一个**封闭**字段集做校验， |
| 28 | 只要某一批里带有已发布 schema 未点名的键，整批都会被拒绝， |
| 29 | 所以意外加入的工作间字段会在摄取时被拒，而不是被存储。 |
| 30 | 在当前 0.9.12 源码中，计数默认开启，并配有明确的告知和可持久的退出机制； |
| 31 | 此前的退出设置保持为关闭。工作间内容在每一个被接受的批次里都在结构上缺席。 |
| 32 | |
| 33 | 2. **链接里不放机密。** `codewhale://workroom/wr_...` URL 只包含不透明的 UUID。 |
| 34 | 它们不携带 API key、bearer 令牌、密码或文件路径。 |
| 35 | 拥有工作间链接的对手在没有运行时 API 访问权的情况下什么也做不了。 |
| 36 | |
| 37 | 3. **没有公开的读取路径。** 将来的工作间端点必须要求 `Authorization` |
| 38 | 头里带有有效的 bearer 令牌。不应当存在未认证的 `/workroom/...` 路由。 |
| 39 | |
| 40 | 4. **事件里不放机密。** `WorkroomEvent` 载荷绝不能包含 API key、认证令牌或 |
| 41 | 明文凭据。`ArtifactLinked` 事件类型引用的是文件路径，而不是内容。 |
| 42 | 事件的用途是索引/引用，不是重放智能体的工具输出。 |
| 43 | |
| 44 | 5. **分享必须显式。** 一个工作间默认是 `Private`。运营者可以把它标记为 |
| 45 | `Shared`，并列出允许的 bearer 令牌。运营者控制哪些令牌被签发、轮换和吊销。 |
| 46 | |
| 47 | ## 威胁模型 |
| 48 | |
| 49 | | 威胁 | 缓解措施 | |
| 50 | |---|---| |
| 51 | | 攻击者获得工作间链接 | 链接只包含不透明 UUID；解析需要运行时 API 认证 | |
| 52 | | 攻击者暴力破解工作间 ID | UUID v4（`2^122` 空间）；将来的 API 在暴露查询表面之前应当加上速率限制 | |
| 53 | | 攻击者注入恶意事件 | 将来的事件写入应当只经由受信任的运行时客户端 | |
| 54 | | 攻击者窃取工作间状态 | 将来的文件系统状态应当由操作系统用户权限和运行时认证把关 | |
| 55 | | bearer 令牌泄漏 | 运营者轮换令牌；将来的分享规则应当可以在不触及工作间状态的情况下撤销 | |
| 56 | |
| 57 | ## API 认证 |
| 58 | |
| 59 | 将来的工作间端点应当继承与其他受保护路由（`/thread`、`/app`、`/prompt` 等） |
| 60 | 相同的认证中间件： |
| 61 | |
| 62 | - 需要 `Authorization: Bearer <token>` 头 |
| 63 | - 令牌要对照运行时配置的 bearer 令牌校验 |
| 64 | - 缺失或无效时返回 401 Unauthorized |
| 65 | |
| 66 | ## 后续工作 |
| 67 | |
| 68 | | 项目 | 风险 | 状态 | |
| 69 | |---|---|---| |
| 70 | | 事件的静态加密 | 如果工作间转向多用户模型，属于第 2 阶段的范围 | 未实现 | |
| 71 | | 共享工作间的审计日志 | 如果共享令牌跨运营者使用，会很有用 | 未实现 | |
| 72 | | 令牌作用域（read/write/admin） | 目前所有令牌都有完全访问权 | 未计划 | |
| 73 |