前言¶
DSH 的凭证可以保存在本地凭证文件中。对于希望保留原文件路径、把明文凭证改成密码保护密文的使用方式，dsh-encrypt 提供了一个 bundle 形态插件。下面介绍它的定位、安装、启用和常用操作。
这是什么¶
dsh-encrypt 是由 yauntyour 维护的 DSH 凭证加密插件，许可证为 MIT，当前版本为 0.1.0-rc.12。
它把 $DSH_HOME/.credentials.yaml 做成单文件双形态：未设密码时是明文 YAML；设置密码后，同一文件原地替换为 AES-256-GCM 密文文档。密钥由 Argon2id 派生，文档和条目使用 SHA3-256 指纹做完整性检查。
插件随 profile 启动，属于 bundle 形态：dsh.bundle.patch 进入 cordis.patch.yml。
核心功能¶
- 单文件双形态：明文 YAML 与密文 JSON 原地互转，不产生第二个文件、不迁移路径。
- 加密：AES-256-GCM；每条凭证独立随机 nonce；引用名绑定为 GCM AAD。
- 完整性：SHA3-256 条目级与文档级指纹；损坏文件启动即被拒绝。
- 密码派生：Argon2id；旧版 scrypt(v2) 密文仍可解锁，并在解锁时自动升级。
- Web 输入：浏览器计算密码 SHA3-256 摘要，后端仅接收 digest；原始密码不离开浏览器。
- 解锁防爆破：连续失败计数持久化；达阈值后指数退避，返回 HTTP 429 + Retry-After。
- 输出脱敏：HTTP 响应体与 WebSocket 文本帧中的凭证值替换为
[REDACTED:dsh-encrypt]。 - 发行自校验：构建时生成
lib/integrity-manifest.json，启动逐文件校验；用于发现安装损坏，不作为防恶意改包的信任根。 - 免密票据：解锁成功后签发 256 位票据，默认仅 HttpOnly Cookie。
- 本机限制：解锁、设密、改密和免密设置要求 Host 回环且 socket 回环。
- 永久密文：设密后文件永不回退明文；外部明文替换在解锁态被立即重加密，在锁定/启动态被拒绝。
- 内存清理：密文只在被使用时解密，中间 Buffer 立即清零；密钥在锁定/卸载时清零。
- 请求级解密：明文只存活于单次操作，不缓存、不进日志。
- 文件与运行：热重载、原子写、文件锁（POSIX 强制 0600）、自动化解锁
DSH_CREDENTIAL_PASSWORD。 - 运行时护栏：加载时探测运行中 dsh 版本，跨线抛
UNSUPPORTED_DSH。
安装与启用¶
环境¶
Node.js >= 24
DSH @deepseek-ai/dsh@0.0.1-rc.1+
兼容运行时 dsh 0.1.0-rc.7 线（实测组合；跨线明确报 UNSUPPORTED_DSH）
依赖线记录如下：
- 接缝包精确钉版：
cordis 4.0.1、dsh-credentials等0.1.0-rc.6 - 独立包范围版：
@node-rs/argon2、chokidar、yaml
@node-rs/argon2 为带预编译二进制的原生依赖。极少平台组合缺失时，可以运行：
pnpm rebuild @node-rs/argon2
打包并安装¶
先做本地打包，再安装到 web profile：
corepack enable
pnpm install --frozen-lockfile
pnpm pack
dsh plugin --profile web add ./dsh-encrypt-0.1.0-rc.12.tgz
源码目录安装¶
如果要在本机直接指向源码目录安装，可以用：
dsh plugin --profile web add "D:/Developments/DSH/DSH-Encrypt"
挂载 Web 密码路由¶
bundle patch 只插入 provider 行；浏览器路由是独立组合行。在 $DSH_HOME/profiles/web/cordis.patch.yml 用户层追加 dsh-encrypt-web 行：
- insert:
- id: dsh-encrypt-web
name: 'dsh-encrypt/web'
config:
trustedHosts: []
如果是 LAN/隧道部署，需要把放行的权威来源写进 trustedHosts。如果配置中用 !!js 表达式引用 ctx.webRuntime，必须加行级 inject: [webRuntime]。
例如：
- insert:
- id: dsh-encrypt-web
name: 'dsh-encrypt/web'
inject: [webRuntime]
config:
trustedHosts: []
验证安装¶
经过上面的步骤后，检查当前 profile 的配置输出：
dsh --profile web --dump-config | grep dsh-encrypt
期望结果：dsh-encrypt 与 dsh-encrypt-web 两个行在，且基础 credentials 行被禁用。
典型用法¶
设置加密密码¶
输入两次至少 8 字符密码。完成后，同一文件原地替换为密文文档，进程保持解锁。
解锁¶
解锁时校验密码摘要并派生密钥，随后恢复模型调用。
修改密码¶
输入当前密码后，全部条目重加密，并作废旧票据。
免密登录¶
滑块支持以下取值：
0：每次1-30：天-1：永远
这些免密设置均仅本机可用。
适用场景与注意¶
适合希望保留原 .credentials.yaml 路径、把明文凭证切换为密码保护密文的本地或单机部署。
注意：
- 插件以当前 dsh 进程权限运行；安装前应检查源码与许可证。
- 忘记密码不可恢复；删除
.credentials.yaml后，设置页仍要求先建立新密码，随后才能重新配置凭证。 allowEnvFallback: false可关闭继承环境与.env回退，变成严格仅文件策略。- 发行文件一致性自校验用于发现安装损坏，不作为防恶意改包的信任根。
- 仅本机密码操作依赖 Host 回环且 socket 回环；带代理转发头的请求不会被当成本机请求。
结尾¶
dsh-encrypt 把 DSH 凭证的加密收在同一个文件里：设置密码后文件保持密文，浏览器只提交摘要，请求按需解密，输出做脱敏，并保留爆破锁定与完整性检查。
