World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-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.mdnew file mode 100644index 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.mdindex 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 级机器令牌)|## 不是决策记录的那些