dsh-vault — 加密凭据保险库插件

    

dsh-vault 是一个面向 DeepSeek Harness 的安全加密插件：把你在使用 AI 过程中产生的用户名、邮箱、手机号、密码、二次动态密钥（TOTP） 以及开发工作流中常用的 SSH 连接、API Key、Secret、OAuth access/refresh token 等敏感凭据加密存储，并通过模型工具提供增删改查、检索、密码生成与动态验证码生成能力。

安全性与实现

• 零外部依赖：全部加密基于 Node 内置 node:crypto（AES-256-GCM 认证加密 + scrypt 密钥派生 + RFC 6238 TOTP），不引入任何第三方加密库。
• 主密码：所有条目由 scrypt(主密码, 盐) 派生的 256 位密钥经 AES-256-GCM 加密。密钥永不落盘；进程内解锁后缓存复用（避免每次写入重复 scrypt），重启后重新派生。
• 防篡改：GCM 认证标签 + 文档内固定明文的校验信封，错误主密码、密文被改动都会立即失败，绝不返回垃圾数据。
• 磁盘无明文：加密文档中不含任何明文凭据；每个条目独立随机 nonce。
• 原子写入：复用 harness 的 writeFileAtomic + 文件锁，任何时刻磁盘上都是完整的新/旧文档；进程内写入串行化、跨进程写入加锁。
• 检索不泄密：vault_search 只返回摘要（id/标题/分类/用户名/邮箱/手机/主机/端口/URL/标签），绝不返回密码、密钥、令牌与 TOTP 密钥；完整凭据只能通过 vault_get 按 id 显式读取。

条目模型

每条记录包含一个 title、一个可选 kind 分类，以及任意组合的字段：

工具

| 工具 | 作用 | |---|---| | vault_add | 新增条目（上述字段任意组合；空字符串/空数组字段会被忽略） | | vault_get | 按 id 读取完整条目（含全部密钥） | | vault_search | 跨标题/分类/用户名/邮箱/手机/主机/端口/URL/备注/标签/自定义字段（含数字/布尔/嵌套值；空格分隔多词 OR 命中）检索；可选 createdAfter/createdBefore 毫秒时间戳过滤；返回无密摘要；limit 须为 1–100 的整数 | | vault_update | 按 id 更新字段（未提供的字段保留；空字符串清除该字段；title 可改名；rotationDays: 0 清除轮换 = 永不轮换） | | vault_compare | 逐字段比较两个条目（onlyA/onlyB/differ/equal）——只返回字段名，绝不返回密钥值 | | vault_rename | 一次调用即可重命名条目（vault_update 的快捷方式） | | vault_delete | 软删除条目（移入回收站，磁盘上仍加密保留） | | vault_restore / vault_purge / vault_restore_recent | 从回收站恢复 / 永久删除 / 撤销最近一次删除 | | vault_lock / vault_unlock | 显式锁定保险库（清空内存密钥）/ 重新解锁 | | vault_totp | 为存储的 otpSecret（或直接传入的 Base32/otpauth URI）生成当前 6 位动态验证码 | | vault_generate_password | 生成强随机密码（长度/字符集/分组可选）或易记口令短语（passphrase: true，EFF 词表，words/separator/wordDigits） | | vault_strength | 零依赖密码强度评估（0–100 分，weak/fair/strong/very strong） | | vault_password_history | 列出条目的历史密码(1Password/Bitwarden 风格,最新在前,上限 10 条;不含当前密码) | | kind: card | 银行卡/信用卡条目:cardNumber/cardExpiry(MM/YY)/cardCvv/cardHolder;搜索摘要只暴露有效期和持卡人(绝不显示卡号和 CVV);Bitwarden JSON 导出映射为 card 条目(type 3,自动识别卡品牌) | | vault_password_rollback | 将条目密码回滚到某条历史记录(当前密码先归档,可逆) | | vault_recovery_code / vault_verify_recovery / vault_recovery_status | 一次性保险库恢复码（1Password/Bitwarden 风格）:32 位代码仅显示一次,只保存其 SHA-256 哈希;可验证代码持有;查询是否已设置 | | vault_rekey | 原地升级 scrypt KDF 参数并重加密 | | vault_backup | 带时间戳的加密备份，支持保留策略：超过 maxBackups（默认 10）的旧备份自动清理 | | vault_import_csv | 从 CSV 批量导入凭据（自定义列变为 fields；overwrite: true 合并字段到已有条目，不再产生重复） | | vault_bulk_delete | 按 query/kind/tag 或显式 ids 批量软删除条目;需 confirm: true（默认仅试运行）;回收站可恢复 | | vault_apply_tags | 按查询批量增/删/替换条目标签（支持 dry-run，不含密钥） | | vault_totp_uri | 为存储的或裸 TOTP 密钥生成 otpauth:// 配置 URI | | vault_switch / vault_list | 按名称切换当前保险库 / 列出可用保险库 | | vault_rotation | 报告已过期 / 待轮换 / 即将过期的凭据；soonWindowDays（1-90，默认 7）调整即将窗口（不含密钥） | | vault_health | 保险库健康扫描：弱密码/复用凭据、未启用 2FA、不安全的 http:// 站点,以及整体安全评分（0–100） | | vault_watchtower | 每个条目的风险分析(借鉴 1Password Watchtower / Bitwarden):标记弱密码、键盘序列、嵌入年份、常见密码、跨条目复用、http 站点、缺 2FA、过期——带 0–100 评分与 good/warn/poor 判定(不含机密);条目行显示 ⚠ 徽标 | | vault_breach_check | Watchtower 风格泄露扫描：对接 Have I Been Pwned（k-anonymity,仅发送 SHA-1 前缀）,附离线常见密码兜底 | | vault_integrity | 校验磁盘上的保险库文件可正确解密并与内存中的 store 一致 | | vault_merge | 合并一个条目到另一个；keepSource: true 保留源条目 | | vault_attach / vault_attachments / vault_attachment / vault_detach | 给条目附加文件（私钥、证书、配置、恢复码）——base64 存于加密条目内随库加密;列出/读取/移除 | | vault_quick_add | 快速录入（标题 + 一个密钥），支持 tags/notes | | vault_expiry | 设置/清除过期（expiresAt: 0 移除） | | vault_stats | 概览计数，含 trashCount（不含密钥） | | vault_verify | 校验单个条目或审计全部条目（all: true）：按 kind 检查完整性、端口/过期合理性（不含密钥） | | vault_duplicates | 查找重复分组：mode = both（默认）/ title / content（不含密钥） | | vault_report | 可打印清单，含到期/轮换列与统计页脚（不含密钥） | | vault_export / vault_import | 整库加密备份/迁移（独立导出密码） | | vault_backup / vault_backup_now | 时间戳加密备份,文件名 <库名>-backups-YYYY-MM-DD_HH-MM-SS-<hex>.json（库名+日期一目了然）;自动保留最近 N 份 | | vault_restore_backup | 从备份还原:mode: "merge"（默认）把备份条目复制进当前库,出现在条目列表;mode: "replace" 整体覆盖（先写安全快照） | | vault_vault_rename / vault_vault_delete | 重命名命名库（文件移动,当前会话跟随）或永久删除（default 库受保护） | | vault_match_url | 按 URL 查找匹配的登录条目（Bitwarden/1Password 风格:精确主机、子域、父域、路径前缀;www./端口归一化）,带 0–100 评分——绝不返回密码 | | vault_fill | 按 host/URL/用户名/标题匹配条目并返回其凭据 | | vault_env | 把标记 env 的条目（tags 含 env）渲染为 KEY=VALUE 行 | | vault_export_bitwarden / vault_import_bitwarden | Bitwarden/Vaultwarden JSON 互通（完整字段映射,支持覆盖） | | vault_import_bitwarden_encrypted | 解密 Bitwarden 口令保护 JSON 导出（PBKDF2/Argon2id + HKDF → AES-256-CBC + HMAC）并导入,需提供导出口令 | | vault_import_manager_csv | 密码管理器 CSV 自动识别表头：Bitwarden（login_uri/login_username/…）、1Password 8、Dashlane、NordPass、Keeper、LastPass（fav/grouping/extra）；支持 dryRun 预览 | | vault_import_kdbx | KeePass KDBX：3.1 与 4.x、AES-KDF 或 Argon2（RFC 9106）、AES-256-CBC 或 ChaCha20 载荷、支持 keyfile | | vault_export_1password | 导出为 1Password 1PUX 归档（ZIP + export.data）,可导入 1Password 或用 vault_import_1password 再导入;条目类别映射 login/信用卡/API 凭据/服务器 | | vault_import_1password / vault_import_1pif | 1Password 1PUX（ZIP）与旧版 1PIF 文本导出 | | vault_import_enpass | Enpass JSON 导出（文件夹→标签、类型化字段、TOTP） | | vault_import_keepass_xml | KeePass 2.x XML 导出（明文或 ****** 掩码值） | | vault_import_chrome / vault_import_keychain | 从 Chrome Login Data（macOS 钥匙串 / Linux 钥匙环或 peanuts / Windows DPAPI）或 macOS 钥匙串导入密码（默认只读互联网密码 inet——真正用于网站登录的条目,classes: ["genp"] 可改读通用密码；会话缓存 + 预览,避免授权弹窗轰炸）；所有文件导入均支持 dryRun 预览 | | vault_import_firefox | Firefox 配置导入（logins.json + key4.db,NSS 3DES / PBES2-AES,支持主密码） | | vault_search_system | 在 Chrome / 钥匙串中搜索站点与用户名——绝不暴露密码 | | vault_session_open | 在真实浏览器窗口中打开指定网址,供用户手动登录（密码、二次验证、验证码）——对禁止嵌入的网站也能捕获登录态 | | vault_session_collect | 收集已打开浏览器会话的全部 cookie（含 HttpOnly）,保存为 cookie 条目 | | vault_session_import | 从粘贴的 JSON cookie 数组（开发者工具导出格式）或原始 Cookie 头字符串保存会话 cookie——无需浏览器的替代方案 | | vault_session_import_file | 导入 Netscape cookie-jar 文件（curl -b / wget / 浏览器扩展导出；与 vault_session_export 输出的格式一致） | | vault_session_list | 列出已保存的登录会话、cookie 数量、已过期与 7 天内过期数量（不含值） | | vault_session_export | 将会话导出为 Cookie 请求头、Netscape cookie-jar 文件（curl -b）、原始 JSON（Playwright addCookies 格式）或可直接运行的 Playwright 片段 | | vault_session_close | 关闭已打开的浏览器登录会话（已收集的 cookie 仍保留在保险库中） | | vault_session_prune | 移除已保存会话中的过期 cookie（无过期的会话 cookie 保留）;preview: true 只报告不修改 | | vault_copy | 复制条目（含密钥）到另一个命名保险库 | | vault_templates | 内建 + 用户自定义模板（save/list/remove,KeePassXC 风格）;内建模板新增 Wi-Fi、服务器、数据库、身份、银行账户、银行卡（借鉴 1Password） | 内建 + 用户自定义模板（save/list/remove,KeePassXC 风格） |

典型开发场景：存一条 SSH 凭据（kind: ssh + host/port/username/password 或 privateKey），开发时让模型 vault_search 找主机、vault_get 取连接信息；存 API 网关的 api-key/oauth 条目管理 access/refresh token 轮换。

安装

dsh-vault 是一个 bundle(声明 dsh.bundle 的包):安装到 profile 后,它的 cordis.patch.yml 会自动插入 vault 插件行(按包名 dsh-vault 引用,主密码经 DSH_VAULT_PASSWORD 环境变量注入)。包内含自包含构建脚本,git 安装时会自动编译 lib/。

以下四种安装方式均已端到端实测通过(安装 → bundle 层被识别 → 插件激活且 7 个 vault_* 工具全部注册 → vault_add/vault_get 真实往返成功 → 卸载移除 layer):

方式一：从 npm 安装(最省事)

dsh plugin --profile web add dsh-vault

npm 包自带预构建的 lib/ 产物,无需 allowBuilds、无需本地编译,安装即用。启动前设置主密码:

export DSH_VAULT_PASSWORD='你的强主密码'

方式二：从 GitHub 安装(锁 tag 或 commit)

dsh plugin --profile web add github:Ox0400/dsh-vault#v0.1.1

git 安装拉取的是源码,prepare 脚本会在安装时构建 lib/。pnpm ≥10 默认阻止 git 依赖执行构建脚本。实测流程:

1. 执行 add 命令——会因 allowBuilds 失败,并打印需要放行的精确键(含仓库 URL 与解析后的 commit hash 的那行):

``text allowBuilds: dsh-vault@https://codeload.github.com/Ox0400/dsh-vault/tar.gz/<sha>: true ``

2. 把该精确键追加到 profile 的 pnpm-workspace.yaml($DSH_HOME/profiles/<name>/pnpm-workspace.yaml):

``yaml packages: - . allowBuilds: dsh-vault@https://codeload.github.com/Ox0400/dsh-vault/tar.gz/<sha>: true ``

3. 重新执行 add——pnpm 现在会运行 prepare 脚本,构建 lib/ 并完成安装。

建议锁定 tag/commit 再安装,避免上游推送改变安装时执行的代码。允许构建 = 允许该包的代码在你的机器上于安装时执行;只对你信任的源码授予。

方式三：本地路径安装到 profile

dsh plugin --profile web add /绝对/路径/to/dsh-vault

pnpm 将 checkout 链接进 profile;只要 lib/ 存在(必要时先在 checkout 里执行 pnpm build)即被识别为 bundle。

方式四：本地 tarball 安装

npm pack && dsh plugin --profile web add ./dsh-vault-0.1.1.tgz

tarball 自带预构建 lib/ 产物,无需构建或 allowBuilds。

dsh plugin --profile web remove dsh-vault 卸载(同时移除依赖与 layer)。

配置

示例：

- id: vault
  name: dsh-vault
  config:
    masterPasswordEnv: DSH_VAULT_PASSWORD
    accessMode: ask
    autoCapture: true

autoCapture: true 时，当你在对话中分享凭据（如 "我的 npm token 是 npm_…"），助手会提议存入；你同意后立即调用 vault_add。autoCapture 关闭时，只有你明确要求才保存。设置页显示当前模式（只读 / 写入前询问 / 自动读写）可用下拉切换，还有自动捕获开关（检测对话中的凭据 → 提议保存）、类型筛选、健康与轮换摘要、回收站视图、以及默认遮罩的密钥字段（显示/隐藏切换）。

首次调用任一工具时自动创建保险库；之后每次启动用主密码重新解锁。忘记主密码 = 数据永久丢失（无后门，这是设计使然）。

开发

本地 clone 开发:

git clone git@github.com:Ox0400/dsh-vault.git
cd dsh-vault
pnpm install    # 安装 devDependencies(typescript/tsdown/vitest 等)
pnpm build      # 构建 host 侧 lib/*.js 与浏览器 bundle lib/client.js
pnpm test       # 运行 41 项 vitest 测试

> 测试需要 harness 的 dsh-llm/dsh-system-prompt 等 peer 包,在 harness monorepo 内开发时由 workspace 链接提供。

常用命令:

# 单元 + 集成测试（vitest，41 项）
pnpm test            # 或 npx vitest run

# 类型检查
pnpm typecheck       # tsc -p tsconfig.json --noEmit

# 构建（host 侧 lib/*.js 与浏览器 bundle lib/client.js）
pnpm build           # = build:host (tsc) + build:client (tsdown)

# 打包发布（可选：npm pack 产物可直接 `dsh plugin add ./dsh-vault-0.1.1.tgz`）
npm pack

仓库内所有测试通过：41/41（crypto/TOTP/密码生成/store CRUD/网关/集成）。

打包与发布

本包是标准 npm bundle:

• dsh.bundle.patch → cordis.patch.yml(安装到 profile 后自动应用的 layer)
• dsh.client → 浏览器端声明(exports["./client"] 指向 lib/client.js)
• prepare 脚本 → git 安装时自包含构建(tsc host + tsdown client)
• 运行时依赖全部走 peerDependencies(由宿主 harness 提供,避免重复实例)

可选发布途径:

npm pack                  # 产出 tarball → dsh plugin add ./dsh-vault-0.1.1.tgz
npm publish --access public   # 发布 npm → dsh plugin add dsh-vault

安全边界与已知限制

• 主密码强度决定保险库强度；建议 ≥ 16 字符高熵。
• scrypt 成本参数（N=32768, r=8, p=1）已持久化在文档中，可随版本提升，旧文档仍可解密。
• 明文凭据仅存在于进程内存与 vault_get 显式读取期间；vault_search/vault_update 的输出均不含密码、密钥与令牌。vault_get 返回的秘密会进入该次工具调用结果（模型上下文），调用方应避免在对话中复述。
• 本插件面向单机/个人部署；团队共享保险库不在范围内。