前言¶
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 憑證的加密收在同一個文件裏：設置密碼後文件保持密文，瀏覽器只提交摘要，請求按需解密，輸出做脫敏，並保留爆破鎖定與完整性檢查。
