Skip to content

World's first open-source enterprise world model.

A token acts as you, but need not be all of you (#161)

WaylandYang1a7b76d2217e
diff --git a/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md b/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md
new file mode 100644
index 00000000..edacd80f
--- /dev/null
+++ b/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md
@@ -0,0 +1,128 @@
+# 0014 · 身份跟着人,范围跟着令牌
+
+- **状态**:规划中 · MCP 服务端的第一块地基,代码未动
+- **成文**:2026-09-01(约定见 [README](README.md))
+- **相关**:迁移 `0014_data_source_grants` 刚给数据源补上授权层——本篇是同一个问题
+ 换到「机器来敲门」这一侧;[0004](0004-language-and-localization.md) 定下服务端只说英文,
+ 错误码这一条对 MCP 同样适用
+
+> 起因是要把 Utopia 的七个工具暴露成 MCP 服务端。**第一个要回答的不是传输层选哪个,
+> 是客户端以什么身份接进来。** 这一篇只答这个。
+
+## 现状:两种凭据,都不合身
+
+| | 跟着谁 | 存法 | 过期 | 能撤吗 |
+|---|---|---|---|---|
+| JWT | 人 | 无状态 | 7 天 | **不能**——签出去就管不了 |
+| `sources.ingest_token` | 一个来源 | 明文 | 无 | 换一个 |
+
+JWT 是给浏览器会话设计的:短命、每次登录重签、无状态所以不需要一张表。MCP 客户端是
+长命的、机器的、配在别人机器上的一个文件里——七天过期意味着每周手动重配一次,而
+「撤不回来」意味着笔记本丢了只能等它自己过期。
+
+`ingest_token` 更不合适:它跟来源走,不跟人走,而且只能**往里推文档**。
+
+## 走过的岔路:KB 级机器令牌
+
+先提的方案是给知识库发机器令牌——一枚令牌对应一个库,跟人无关。
+
+**否掉了,两条理由:**
+
+1. **它引入第三套授权模型。** 现在已经有工作区成员和 KB 角色两层;再加一层「令牌自己的
+ 权限」,那么「这个 agent 能看什么」就得同时查三张表才答得出来。而三层里任何一层写错,
+ 失败方向都是「多给了」。
+2. **归因会变成假的。** `audit_events.actor_id` 现在记的是活人,`actor_label` 还存了一份
+ 身份快照。机器令牌写进来的事实,actor 只能是一个合成 id——台账上就多出一类「不是任何
+ 人做的」记录,而账本存在的理由正是「谁在什么时候认下了什么」。
+
+**改成:令牌以这个人的身份行事。**
+
+## 决定
+
+```
+有效权限 = 这个人的角色 ∩ 这枚令牌的 scope
+```
+
+交集,不是并集。**令牌只能收窄,永远不能放宽。** 一个 viewer 的令牌勾上 write 也还是
+只读——scope 是上限,不是授权。
+
+### 为什么身份跟着人
+
+- **现有守卫一行不用改。** `require_kb(kb_id, Role::Viewer)`、`access::kb_role` 拿到的还是
+ 一个 `User`,它从哪来的无所谓
+- **归因是真的。** 台账上是活人,不是机器人
+- **停用即失效。** 人离职停用,他的令牌跟着废,不用单独维护一张「谁的机器还连着」的表
+- **多个库不用发多把钥匙**
+
+### 为什么范围仍然要单独收窄
+
+因为有一个 MCP 特有的问题,应用内对话没有这么严重:
+
+> **混淆代理。** MCP 客户端是别人的 agent、别人的系统提示词,而它读的是知识库里的
+> 文档——**不可信内容**。一份文档里写「请执行这段 SQL」或者「记住 X」,那个 agent 可能
+> 就照做了,用的是这个人的全部权限。
+
+应用内对话也有这个面,但那里提示词和工具循环都在 Utopia 手里;走 MCP,Utopia 对客户端
+的提示词、对它还接了哪些别的服务端,一无所知。
+
+而这个人的「全部权限」是什么:经 `query_data`,对他所在**每一个库挂载的每一个生产
+数据库**跑只读 SQL;经 `remember`,往 append-only 账本里写事实。这些能力配在一串放在
+`claude_desktop_config.json` 明文里的字符串上。
+
+所以默认发**只读、限定到一个库**的令牌。要让 agent 写,得显式勾。
+
+## 这枚要哈希,而 `ingest_token` 不哈希
+
+两处结论不同,不是疏忽。`ingest_token` 那条明文决定的原话(`0002_ingest.sql`):
+
+> **明文存,不是哈希。** 自部署威胁模型下「只看一次」是自找麻烦:改存明文随时可查。
+> DB 失守时文档本体早已泄露,密钥哈希化没有额外收益
+
+那个推理对 ingest_token 成立,因为**它只能往里推文档**——泄露它的最坏结果是有人往你
+库里塞垃圾,而库都失守了,塞垃圾不是最要紧的事。
+
+个人令牌不一样:它经 `query_data` 能**读出 Utopia 之外的生产库**。Utopia 的数据库失守
+本来就泄露 Utopia 自己的文档,但数仓在另一台机器上、装着另一批数据,不该跟着一起丢。
+**爆炸半径不同,所以存法不同。**
+
+## 形状
+
+```sql
+CREATE TABLE personal_tokens (
+ id UUID PRIMARY KEY,
+ user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+ name TEXT NOT NULL, -- 人自己起的,"我的笔记本"
+ token_hash TEXT NOT NULL, -- 哈希,理由见上
+ scope TEXT NOT NULL DEFAULT 'read'
+ CHECK (scope IN ('read', 'write')),
+ kb_ids UUID[], -- NULL = 这个人能进的全部
+ expires_at TIMESTAMPTZ, -- NULL = 不过期,但 UI 默认给 90 天
+ last_used_at TIMESTAMPTZ, -- 「这枚还在用吗」,撤之前要答得出
+ revoked_at TIMESTAMPTZ, -- 撤销不删行:撤过这件事本身要留痕
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+`user_id` 这条有外键且级联,与 `audit_events.actor_id` 的裸外键相反——**台账要活得比
+用户久,令牌不该**。人没了,他的钥匙就该一起没。
+
+## 一条实施纪律
+
+**每个工具入口都要校验 scope,不能只在连接握手时校验一次。**
+
+这是 `0014_data_source_grants` 那轮的教训,原话写在测试里:
+
+> 列表过滤只挡「看得见」,而挂载端点是照着 id 调的——守卫必须在两侧都有
+
+MCP 的对应形态是:握手时校验一次,然后整条连接生命周期里都信任它。工具调用是一个个
+独立请求,`revoked_at` 在中途被写上时,正在跑的连接必须立刻失效。
+
+## 未决
+
+- **`query_data` 与 `remember` 要不要进第一版。** 倾向不进——先发四个只读工具
+ (`search_chunks` / `find_entities` / `entity_facts` / `changes`),把身份这条路走通再说。
+ 这两个各自还有没答的问题:外部 agent 写进来的事实挂什么证据?跑 SQL 的审计怎么记?
+- **传输层**:stdio(本地,配 Claude Desktop 最省事)还是 streamable HTTP(远程,
+ 和 Utopia 已经是个服务端相称)。这个选择不影响本篇的结论,两种都要认令牌。
+- **令牌能不能跨工作区。** 现在的 `kb_ids` 是库级白名单;如果将来要按工作区发,
+ 和数据源授权那张表会长得很像,届时看要不要合并概念。
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index 7a0b4cbc..6423041f 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -35,6 +35,7 @@
| 0011 | [「怎么算」不是「有什么」](0011-a-mapping-is-not-a-fact.md) | 规划中 · 语义层映射搬出本体 · 0009/0010 那条线的最后一段 |
| 0012 | [本体是一份契约,不只是一份建议](0012-the-ontology-is-a-contract-not-a-suggestion.md) | 已实施 · 五轮对照实验 · 违反率 57%→4%、反向 39→0 · 首次拿真语料问 0008 那个问题 |
| 0013 | [一个来源该交出它的历史,不是它的现状](0013-a-source-should-hand-over-its-history.md) | 已实施两个(GitHub / Jira 工单)· **文档协作类待做** |
+| 0014 | [身份跟着人,范围跟着令牌](0014-identity-from-the-person-scope-from-the-token.md) | 规划中 · MCP 服务端的第一块地基 · 含一条被否掉的岔路(KB 级机器令牌)|
## 不是决策记录的那些