凭据管理 fatatalia/dsh-credentials-admin

dsh-credentials-admin — 凭据管理设置页插件

在 dsh Web 的 Settings → 凭据管理 分区里，管理 $DSH_HOME/.credentials.yaml 的 refs: 段长期凭据：列出、新增、覆盖、删除。

一句话设计原则：值只进不出。 界面能写新值，但永远不会显示、也不能取回任何已配置的值 —— 连值的长度都不给。这是设计，不是遗漏。

dsh 版本兼容性

要求 dsh ≥ 0.1.7-rc.1（已在 0.1.7-rc.1 实测通过）。

- Typert strict codec 必须带 create() 工厂（2026-09-24）：0.1.7 起客户端 typert registry 对 strict codec 同样严格校验（dsh-typert-registry/lib/client.js 要求 codec.create 是函数），缺失则打开设置卡片即报 typert: <id> result strict codec has no create() factory。client.js 与 index.js 两处 codec 均已补 create()（服务端 gateway 走 codec.create().parse(v)）。

它做什么

| 能做 | 不能做（有意为之） |
| 列出 refs: 里所有凭据名 + 是否已配置 | 显示 / 复制 / 下载已配置的值 |
| 新增一条（名字 + 值） | 改 records: 段（浏览器会话 secret、Models 页的 API key） |
| 覆盖已有的值 | 改 env / .env 分层的凭据 |
| 删除一条 | 重命名（换名 = 新增 + 删旧，两步） |

改完立即生效：dsh 的 credentials provider 监听该文件，引用这些名字的脚本下次读取就能拿到新值，不用重启。

架构

两层，零 dsh 本体改动：

浏览器 (client.js) host (index.js)
Settings → 凭据管理 ──── Typert RPC ────▶ credentialsAdmin（TypertRemoteService） list / set / unset 读-改-写 refs 段（行级编辑） dsh-atomic-write：文件锁 + 原子写 credentials-local 解析器：写前自校验

为什么自己写盘：官方把 refs: 定义为只读缝 —— CredentialRef 只做 env → managed store → .env 分层解析，唯一的官方写路径 modifyRecord 只管 records:。管理 refs: 属于扩展能力，所以自建（共用锁 + 写前自校验 + 只碰 refs: 段），全程不修改 dsh 本体。

三条硬纪律

1. 永不回显已配置的值。 list 只返回 { name, configured }；服务端不存在任何"读单个 ref 明文"的方法，所以浏览器端就算被改也拿不到旧值。日志只记名字，绝不记值。
2. 只动 refs: 段。 行级编辑，records: 段一字不改。写完立刻用 dsh 官方的 parseCredentialsDocument 自校验 —— 解析器不接受就整体放弃，绝不落盘半成品。
3. 与 dsh 共用同一把写锁。 @deepseek-ai/dsh-atomic-write 的 withFileLock 锁的是 <file>.lock（wx 创建），与 credentials provider 完全一致，所以"我写 refs"与"它写 records"不会互相覆盖。

目录

dsh-credentials-admin/
├── index.js # host：credentialsAdmin remote service + refs 行级编辑纯函数 ├── client.js # 浏览器 bundle：Settings → 凭据管理 分区 ├── scripts/selftest.mjs # 自测（只读真实文件做兼容性校验，不打印值） ├── cordis.patch.yml # bundle patch（插入 host 插件行） └── package.json

挂载

在 dsh profile（如 $DSH_HOME/profiles/web/package.json）里加依赖并登记 bundle：

{
"dependencies": {
"dsh-credentials-admin": "link:/path/to/dsh-credentials-admin"
},
"dsh": {
"profile": {
"bundles": ["…", "dsh-credentials-admin"]
}
}
}

生效方式：client 半由 dsh web 现场从磁盘读取并经 /plugins/??… 组合路由下发，改完刷新页面即生效；host 半改动需要重启主实例。

配置

cordis.patch.yml 插入的插件行接受两个可选项，默认值通常够用：

| 字段 | 默认 | 说明 |
| filename | $DSH_HOME/.credentials.yaml | 托管凭据文档路径；DSH_HOME 未设置时用 ~/.dsh |
| lockWaitMs | 5000 | 等待写锁的上限（dsh 侧同锁默认 2s，这里放宽以容忍并发窗口） |

输入约束：

- 凭据名匹配 ^[A-Za-z_][A-Za-z0-9_]*$ —— POSIX 名，不能以数字开头
- 值长度上限 8192 字符（挡住"把整个文件内容误粘贴进值框"这类事故）
- 空值 = 不存在：在 dsh 里空值与缺失等价，所以要清空请用删除，不要保存空值

RPC 接口

命名空间 credentialsAdmin，三个方法：

| 方法 | 参数 | 成功返回 |
| list | — | { refs: [{ name, configured }], file, updatedAt }（文件不存在 → refs: []，不算错误） |
| set | { name, value } | { name, replaced } |
| unset | { name } | { name, removed } |

失败一律 throw RemoteError(code, message)，错误码：read-failed / bad-name / empty-value / too-long / write-failed。

⚠️ 不要自己包 { ok, value } 信封。 Typert 的 RPC 层已经替调用方包了一层；host 再包一层，客户端 result.value 拿到的是信封而不是数据 —— 症状是列表恒显示「共 0 条凭据」且不报错（RPC 层认为调用成功）。官方 dsh-api-settings-controller 的 credentialsController 就是「直接返回业务数据 + throw RemoteError」，照它写。

自测

node scripts/selftest.mjs

31 项断言：行级编辑纯函数（增 / 改 / 删 / 转义 / 边界）、与 dsh 官方解析器的兼容性、结构异常时的拒绝行为。只读真实凭据文件用于兼容性校验（内容不打印、不写入），所有写入都在内存文本上完成。

踩过的坑

- 方法名不能用 remove：client 侧 RemoteNamespaceService 原型上已有 remove()，同名会被 API gateway 以 client api: method "credentialsAdmin/remove" conflicts with its namespace service 拒绝，整个分区挂不起来。已改名 unset。
- 不要自包 RPC 信封：见上方 RPC 接口的警告。这个坑的隐蔽之处在于它不报错 —— 修完命名冲突后，页面能挂载了，却显示「共 0 条」，而 RPC 层一切正常。

限制

- 只管 refs: 段；records: 段、env、.env 层不在此处管理。
- 不支持重命名（请新增 + 删旧）。
- 无审计日志：文件里不记录「谁在何时改了哪个名字」，进程日志也只记「refs 已更新」。