docs(credentials): record the third-review contracts across READMEs, catalogs, and a new Agent Note
Both provider READMEs state what actually holds: credentials-local now documents the physical-line editor, the read-modify-write under the writer lock, and a Security boundary section saying plainly that the file mode stops other OS users and not the model. sandbox-policy documents readDenyPaths and its per-backend enforcement. The llm READMEs carry the registration handle, pi-ai's credential-miss semantics, and DeepSeek's same-generation snapshot; app-boot and the CLI README stop describing $DSH_HOME/.env as an environment layer. A new Agent Note records the round (and the prior seam note cross-links it); the sandbox and core catalog pages gain readDenyPaths and AdapterRegistrationHandle with their manifest entries. The headless missing-credential snapshot re-records for the reworded guidance, pi-ai gains the Loader-composition guard its twin already had, and the deliberate provider symmetry is marked for the clone detector.
This commit is contained in:
Yichen Jiang
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
|
||||
2026-07-29-request-level-llm-config-credentials.md: 67baec4b70d0c754f22573d87fb4492de5ca16a4
|
||||
2026-07-29-request-level-llm-config-credentials.zh.md: 36182b77f4494c99b0fb08107f865f85322ece6c
|
||||
2026-07-29-request-level-llm-config-credentials.md: f12a2496a767decc3ce2b065f6be03009aec8992
|
||||
2026-07-29-request-level-llm-config-credentials.zh.md: 99fd90013a24746962ca02a5f4f18cdccd53f71a
|
||||
|
||||
@@ -26,4 +26,4 @@ Status: implemented
|
||||
|
||||
## 后果
|
||||
|
||||
上手流程端到端免重启（由 `missing-credential` headless 快照与凭据轮换组合测试固定）：无密钥启动、浏览 catalog、存入密钥、再次发起提示。demo 默认挂载 `settings-local` + `credentials-local`，不再内联任何 `!!js` 密钥接线。`runLoaderSmoke` 新增 `expectedExitCode`，使按设计出现的失败面可以被固定而非被掩盖。延后事项：wire/UI 面在任何 RPC 暴露 `describe()` 之前必须对 `role('secret')` 字段脱敏；settings 层的数组仍整体替换（deepseek 的 `models` 列表）；settings 分节无法移除组合提供的 pi-ai 路由（只能覆盖或扩展）。
|
||||
上手流程端到端免重启（由 `missing-credential` headless 快照与凭据轮换组合测试固定）：无密钥启动、浏览 catalog、存入密钥、再次发起提示。demo 默认挂载 `settings-local` + `credentials-local`，不再内联任何 `!!js` 密钥接线。`runLoaderSmoke` 新增 `expectedExitCode`，使按设计出现的失败面可以被固定而非被掩盖。延后事项：wire/UI 面在任何 RPC 暴露 `describe()` 之前必须对 `role('secret')` 字段脱敏；settings 层的数组仍整体替换（deepseek 的 `models` 列表）；settings 分节无法移除组合提供的 pi-ai 路由（只能覆盖或扩展）。对该 seam 的评审随后改造了存储的所在位置与谁可以读取它，让一个请求解析出一个配置世代，并使路由替换成为原子操作（[credential boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md)）。
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
|
||||
2026-07-30-credential-boundaries-and-atomic-registration.md: 837aa3e7b8ed30c66aad880ab2d76eee376e1854
|
||||
2026-07-30-credential-boundaries-and-atomic-registration.zh.md: a00c3d93d2dc0451ed29613c4a804b0e518264ed
|
||||
@@ -0,0 +1,41 @@
|
||||
# Agent Note: 凭据边界、按整份快照发起的请求与原子路由注册
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-30-credential-boundaries-and-atomic-registration.md) | 中文
|
||||
|
||||
> 范围：对[请求级 LLM（大语言模型）配置 seam](2026-07-29-request-level-llm-config-credentials.md)的第三轮评审——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：本轮把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
|
||||
|
||||
## 问题
|
||||
|
||||
评审发现，凭据路径正在越过它自己划下的边界泄漏。已交付的各个面在 Cordis 启动之前就把 `$DSH_HOME/.env` 提升进了 `process.env`，于是下一次运行时，`credentials-local` 会把它自己存下的每个键都判成来自环境的只读启动覆盖：`describe()` 报告 `source: 'env'` 且 `writable: false`，`set`/`unset` 以被遮蔽为由拒绝，从 web 页面或 TUI 存入的密钥既无法轮换也无法删除，而适配器还在继续使用启动时捕获的那个值。
|
||||
|
||||
存储自身的写路径重演了同一轮评审在 settings-local 修掉的那些缺陷（两条相互独立的链、从陈旧缓存渲染整份文件），还叠加了编辑器自己的缺陷：另一个键的带引号多行值内部的一条物理行会被读成赋值，CRLF 行尾会退化成 LF，多行条目报告 `writable: true` 而 `set` 总是抛错，`credentials/updated` 又在提交之后裸发，于是一个出错的观察者就能让一次已经落盘的写入看起来失败。
|
||||
|
||||
在读取一侧，文件的 `0600` 权限挡得住其他 OS 用户，却挡不住模型：它的 bash 与文件系统工具就以同一个用户身份运行。
|
||||
|
||||
与之并排的还有两个请求路径缺陷。DeepSeek 的按请求解析把连接事实保存在最后可用快照里，却仍从原始配置重新读取字面 `apiKey`，于是被 resolver 拒绝的那一代设置，照样能把自己的密钥送到上一代的端点上。配置了 `apiKeyEnv` 却解析不到值时，pi-ai 会把 `undefined` 交给 SDK，让 pi-ai 自己的环境发现拿一个毫不相干的提供方密钥完成鉴权——那是另一个租户，账单还悄悄记在它头上。而且它的路由替换是先释放旧注册、再创建新注册：只要有一条路由已被别的适配器占有，现有路由就会被全部丢掉，此后事实缓存可能与注册表中的事实相等，于是把配置改回可用状态也不会重新生效。
|
||||
|
||||
## 决策
|
||||
|
||||
**`$DSH_HOME/.env` 只归凭据提供方所有。**没有任何一个面会把它加载进 `process.env`。真正的启动环境，以及调用目录中由 bin 加载的 `.env`，仍然是那一层只读的环境来源，因此不挂载该提供方的组合，解析密钥的方式与从前完全一致，而存下的密钥跨重启仍然来源于文件、仍然可写——这一点由 Loader 组合中的一次真实重启来证明，而不是靠对 `describe()` 的单元断言。
|
||||
|
||||
**受限沙箱才是唯一真正的读取边界，而且它点名到具体文件。**`SandboxExecutionPolicy` 新增 `readDenyPaths`，由 `sandbox-policy` 默认设为 `$DSH_HOME/.env`。Seatbelt 在末尾追加一条 `deny file-read* file-write*`（SBPL 中最后一条匹配规则胜出），bwrap 则在所有工作区 bind 之后把 `/dev/null` 映射到每条路径上；Landlock 的授权是纯粹的允许列表，无法从它自己对 `/` 的读取授权中减去任何东西，因此 `confine()` 报告 `partial` 强制执行，而不是声称一条该进程其实并不具备的边界。拒绝点名的是确切路径，而不是根目录：把整个 harness home 都拒掉，会连带夺走模型对自身会话日志的成文访问权。两个 README 都直白写明残留风险——在已交付的 `danger-full-access` 默认值下没有任何东西受限，这个文件只靠 OS 用户身份保护——并记下 OS 钥匙串（keychain）提供方才是真正的答案。
|
||||
|
||||
**一次请求，一代设置。**DeepSeek 解析出的快照在端点旁一并携带凭据事实（字面密钥与引用），`resolveApiKey` 接收这份快照，而不再重新读取配置。被拒绝的那一代如今完全不再贡献任何东西。只有当一个 profile 完全没有点名凭据时，pi-ai 才交给提供方原生的发现流程；配置了引用却解析不到，就以 `MISSING_CREDENTIAL` 失败，并点名该路由与该引用。启动时的凭据探测被删除：它可能在凭据服务挂载之前就运行，并把每一种失败都报成密钥缺失，而第一次请求本就会给出准确的错误。
|
||||
|
||||
**路由替换是注册表的操作，不是调用方的一串步骤。**`registerAdapter` 返回一个携带 `replace(providers)` 的句柄：候选集合先被完整校验（冲突、名称、提供方元数据），再在一个同步区段内完成替换。被拒绝的替换会让先前的路由保持注册并继续服务，而调用方的事实缓存只有在注册表确实持有新集合之后才会推进，因此改回可用配置时会重新生效。pi-ai 的注册事实按提供方排序，因此仅仅调换键顺序的设置文档不再算作路由变更。
|
||||
|
||||
**已提交的凭据写入采用收容式发布。**`Credentials.notifyUpdated` 逐个监听器扇出 `credentials/updated`；同步抛错与异步 rejection 都只记日志，不改变已提交操作的结果，而带 `INVARIANT` 代码的失败会在每个监听器都运行完之后重抛——与 settings seam 处理 `settings/updated` 的形状相同。`installSettingsSection` 的清理现在会区分它的两个触发来源：提供方脱离时仍回退到组合的 entry 配置并重新推导，而消费方自身卸载时立即返回，不再在拆卸过程中重新注册路由。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **拒掉整个 harness home**——一个根目录本可覆盖凭据文档以及将来任何机密文件，但它同时也覆盖 `sessions/`，而 `DSH_SESSION_JSONL` 是一项成文的、模型可见的能力。用确切路径可以把拒绝范围限定在真正属于机密的东西上。
|
||||
- **把 `DSH_HOME` 从模型的 bash 环境中移除**——作为纵深防御考虑过，最终按「有真实代价的表演」不予采纳：默认 home 是 agent（智能体）能自行重建的成文约定，而这个变量正是正当工具链定位 harness 状态的途径。沙箱拒绝才是边界，藏起指针不是。
|
||||
- **本轮就交付 OS 钥匙串提供方**——只有这个设计能让模型的进程真正读不到机密，而它是一个带三种平台后端的兄弟包（package）。把它与本轮评审的其余工作放在一起评估体量，会拖慢其他每一项修复；它被记录为那个延后的答案，而不是一个「也许」。
|
||||
- **把 `readDenyPaths: []` 当作 opt-out**——schemastery 会把省略的数组填成 `[]`，因此在构造函数处空数组与省略无从分辨。于是空数组的含义就是「保护默认文档」；把凭据存在别处的部署自行点名它自己的路径，而在没人读取的路径上设一条拒绝并不产生任何代价。
|
||||
- **做成 `replaceRegistration(previous, next)` 服务方法**——这是评审给出的形状，但它要求调用方自行携带上一个句柄，也允许它传入一个不匹配的句柄。把 `replace` 挂在注册句柄上，让归属关系变成结构性的：只有持有路由的那一项注册才能替换它们。
|
||||
|
||||
## 后果
|
||||
|
||||
`update()` 邻近的行为多了成文的失败模式：凭据写入现在可能因锁截止时间到期、或磁盘文档无法解析而失败，`describe()` 对它不会改写的多行条目报告 `writable: false`。受限执行会失去对 `$DSH_HOME/.env` 的读取权限——刻意让 agent 读取自身凭据文件的部署，必须自行配置 `readDenyPaths`。`LlmAdapter` 的注册方无需改动即可继续工作（句柄本身仍可当作释放器调用），`DeepSeekConnectionOptions` 则新增了凭据字段，因此以编程方式构造该适配器必须提供 `apiKeyEnv`。延后事项：OS 钥匙串凭据提供方，以及针对两个写方编辑同一引用的逐值修订号检查（后写胜出仍是成文的解决方式）。
|
||||
Reference in New Issue
Block a user