dsh-vault 1.10.73 → 1.10.74-rc.2

package/README-zh.md

@@ -8,6 +8,8 @@
 [![已收录: awesome-dsh-plugin](https://img.shields.io/badge/已收录-awesome--dsh--plugin-2ea44f)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/README.zh.md#L2869)
 [![已收录: awesome-deepseek-harness](https://img.shields.io/badge/已收录-awesome--deepseek--harness-2ea44f)](https://github.com/Dominic789654/awesome-deepseek-harness/blob/main/README.zh-CN.md#L903)
 
+[English](README.md) | **中文**
+
 dsh-vault 是一个面向 DeepSeek Harness 的安全加密插件：把你在使用 AI 过程中产生的**用户名、邮箱、手机号、密码、二次动态密钥（TOTP）** 以及开发工作流中常用的 **SSH 连接、API Key、Secret、OAuth access/refresh token** 等敏感凭据加密存储，并通过模型工具提供增删改查、检索、密码生成与动态验证码生成能力。
 
 **安全性与实现**
@@ -225,7 +227,7 @@ echo "$DEMO_API_KEY"
 两个前提要知道:
 
 - **只有打了 `env` 标签的条目才会被导出。** 一个都没打时,输出的是
-  "no entries are tagged for environment export";先在 UI 里给条目的标签加上 `env`,或让助手执行 `vault_update { id, tags: ["env"] }`。
+  `dsh-vault: nothing to export — no entry carries the "env" tag.`;先在 UI 里给条目的标签加上 `env`,或让助手执行 `vault_update { id, tags: ["env"] }`。
 - 名字默认由标题 + 字段推导(`DASHSCOPE` + `apiKey` → `DASHSCOPE_API_KEY`);想固定名字就在条目的 `envKeys` 里指定 —— 见[环境变量导出](#环境变量导出)。
 
 
@@ -237,7 +239,7 @@ echo "$DEMO_API_KEY"
 | `env` | **命令** | 打印带该标签的条目 |
 | `envKeys` | 条目的**字段**(可选) | 固定确切名字,例如 `["DASHSCOPE_API_KEY"]`;旧的单数写法 `envKey` 仍作为"只写一个"的简写接受 |
 
-除此之外没有任何叫 `env*` 的东西:`list --json` / `show` 只报 `envKeys`(该条目会导出的名字,也就是 `get` 接受的名字)与 `envTagged`(是否被 `env` 包含)。
+除此之外没有任何叫 `env*` 的东西:`list --json` / `show` 只报 `envKeys`(该条目会导出的名字,也就是 `get` 接受的名字)、`envTagged`(是否被 `env` 包含)与 `hasTotp`(`totp` 能否为它生成动态码)。
 
 ### 2. 有哪些命令
 
@@ -251,6 +253,8 @@ dsh-vault get my-entry                     # 取该条目的主密钥,仅 stdout
 dsh-vault get my-entry --field apiKey      # 取指定字段
 dsh-vault get my-entry --mask              # 只确认存在,不打印值
 dsh-vault show my-entry                    # 非敏感字段的 JSON
+dsh-vault totp my-entry                    # 当前的 TOTP 动态码(只有 6 位数字)
+dsh-vault totp my-entry --json             # 附带 digits / period / secondsRemaining
 dsh-vault env                              # 带 env 标签的条目 → KEY=VALUE
 dsh-vault env --mask                       # 人类视角,两段都是 KEY=VALUE:
 #   ## exported items
@@ -263,6 +267,8 @@ dsh-vault verify                           # 校验主密码,stdout 无输出
 
 密钥只走 stdout,其余(进度、错误)走 stderr,所以 `$(dsh-vault get …)` 与管道都正常;退出码 `0` 成功、`1` 运行错误、`2` 用法错误。
 
+`totp` 是为了让脚本能自动完成两步验证、又完全不碰长期密钥:`code=$(dsh-vault totp my-entry)` 只输出六位数字。如果你用 `get my-entry --field otpSecret`,打印的是**密钥本身** —— 只有确实要把密钥导入别处时才那么做。`--json` 会多给一个 `secondsRemaining`,脚本据此等一个新窗口,而不是硬闯即将过期的码。
+
 ### 3. shell 引号:不是 `export $(…)`
 
 正确的是 `eval "$(dsh-vault env)"`;`export $(dsh-vault env)` 是错的。命令替换会**按空白拆分**,而且**不会**去掉 CLI 输出的引号 —— 值里只要有一个空格就会被拆成多个词,所有值还会带上字面引号:
@@ -320,7 +326,7 @@ npm i -g dsh-vault && dsh-vault list                 # 全局
 npx dsh-vault list                                   # 或者干脆不装
 ```
 
-读命令(`list`、`get`、`env`、`show`、`verify`、`export-env`)只依赖 Node,所以全局与 `npx` 都能直接用;**只有写保险库**才需要 harness 运行时,而插件环境一定有。
+读命令(`list`、`get`、`env`、`show`、`totp`、`verify`、`export-env`)只依赖 Node,所以全局与 `npx` 都能直接用;**只有写保险库**才需要 harness 运行时,而插件环境一定有。
 
 profile 这条路还有两个注意点:垫片可能被之后在该目录执行的 `pnpm install` 清掉;`pnpm dsh plugin --profile web add dsh-vault` 会依据包的 `dsh.bundle` 声明重整 `dsh.profile.bundles` —— 如果你自己的 patch 层**也**插入了这个插件,就会**挂两份**,要先删掉 patch 层那一行。
 
@@ -401,10 +407,33 @@ k-anonymity **没有**隐藏的东西,直说:
 | **完整** | 全部,含批量导入导出、浏览器会话、备份与保险库文件操作 |
 | **自定义…** | 基础 + 任选: 管理 / 导入导出 / 浏览器会话 / 备份与文件 |
 
-也可在插件配置里写 `tools: basic|standard|full|custom`;界面选择优先,并保存在 `<vault 目录>/access.json`。
+也可在插件配置里写 `tools: basic|standard|full|custom`;界面选择优先,并保存在 `<vault 目录>/tools.json`(工具集是进程级设置,不随保险库变化)。
 
 ## 配置
 
+> [!WARNING] 安全:不要把主密码明文写进配置
+> profile patch(`cordis.patch.yml` / `cordis.yml`)是很容易被提交进 git、截图或进日志的配置文件 ——
+> 一行明文的 `masterPassword:` 就等于泄露了整个加密保险库的钥匙。请一律使用
+> `masterPasswordEnv` 并把真实密码放进进程/ shell 环境(例如 `export DSH_VAULT_PASSWORD='…'`)。
+> 凭据类插件的证据化检查清单见
+> [community-plugin-audit handbook](https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/security/community-plugin-audit.md)。
+>
+> ```yaml
+> # ✗ 不要 —— 配置文件里写明文主密码
+> - id: vault
+>   name: dsh-vault
+>   config:
+>     masterPassword: 'my-secret'
+> ```
+>
+> ```yaml
+> # ✓ 应该 —— 引用环境变量,并让文件本身保持 0600
+> - id: vault
+>   name: dsh-vault
+>   config:
+>     masterPasswordEnv: DSH_VAULT_PASSWORD
+> ```
+
 | 配置项 | 说明 |
 |---|---|
 | `masterPassword` | 直接配置主密码（会出现在 cordis.yml 中，不推荐） |
@@ -441,7 +470,7 @@ 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       # 运行 420 项 vitest 测试
+pnpm test       # 运行 489 项 vitest 测试
 ```
 
 > 测试需要 harness 的 `dsh-llm`/`dsh-system-prompt` 等 peer 包,在 harness monorepo 内开发时由 workspace 链接提供。
@@ -449,7 +478,7 @@ pnpm test       # 运行 420 项 vitest 测试
 常用命令:
 
 ```sh
-# 单元 + 集成测试（vitest，420 项）
+# 单元 + 集成测试（vitest，489 项）
 pnpm test            # 或 npx vitest run
 
 # 类型检查
@@ -462,7 +491,7 @@ pnpm build           # = build:host (tsc) + build:client (tsdown)
 npm pack
 ```
 
-仓库内所有测试通过：420/420（crypto/TOTP/密码生成/store CRUD/网关/集成）。
+仓库内所有测试通过：489/489（crypto/TOTP/密码生成/store CRUD/网关/集成）。
 
 浏览器侧检查跑在真实 `dsh web` 上（不属于 vitest），且**一律拒绝在 default 库上运行**：
 
@@ -504,7 +533,8 @@ UI 不写死颜色，而是读取宿主的设计变量：本地语义层映射
 - `dsh.bundle.patch` → `cordis.patch.yml`(安装到 profile 后自动应用的 layer)
 - `dsh.client` → 浏览器端声明(`exports["./client"]` 指向 `lib/client.js`)
 - `prepare` 脚本 → git 安装时自包含构建(`tsc` host + `tsdown` client)
-- 运行时依赖全部走 `peerDependencies`(由宿主 harness 提供,避免重复实例)
+- 运行时依赖只有 `playwright-core`(懒加载,仅浏览器登录会话使用);其余全部由宿主通过
+  `peerDependencies` 提供,不会产生重复实例
 
 可选发布途径:
 

package/README.md

@@ -80,7 +80,7 @@ Each record has a `title`, an optional `kind`, and any combination of fields:
 | `vault_duplicates` | Find duplicate groups: `mode` = `both` (default) / `title` / `content` (no secrets) |
 | `vault_report` | Printable inventory with expiry/rotation columns and a stats footer (no secrets) |
 | `vault_export` / `vault_import` | Portable encrypted backup/migration of the whole vault (separate export password) |
-| `vault_backup` / `vault_backup_now` | Timestamped encrypted backup named `<vault>-backups-YYYY-MM-DD_HH-MM-SS-<hex>.json` (owning vault + date visible); retention pruning keeps the newest N |
+| `vault_backup` / `vault_backup_now` | Timestamped encrypted backup named `<vault>-backups-YYYY-MM-DD_HH-MM-SS-<hex>.json` (owning vault + date visible); retention pruning keeps the newest N (`maxBackups`, default 10) |
 | `vault_restore_backup` | Restore from a backup: `mode: "merge"` (default) copies the backup entries INTO the current vault so they appear in the entries list; `mode: "replace"` overwrites the whole vault with a safety snapshot first |
 | `vault_vault_rename` / `vault_vault_delete` | Rename a named vault (file moves, active session follows) or permanently delete one (default vault protected) |
 | `vault_match_url` | Find login entries matching a URL (Bitwarden/1Password-style: exact host, subdomain, parent domain, path-prefix; www./port normalization) with a 0–100 score — never returns the password |
@@ -237,7 +237,7 @@ echo "$DEMO_API_KEY"
 Two things worth knowing:
 
 - **Only `env`-tagged entries are exported.** With none tagged you get
-  "no entries are tagged for environment export"; tag one in the UI (the
+  `dsh-vault: nothing to export — no entry carries the "env" tag.`; tag one in the UI (the
   entry's tags field) or with `vault_update { id, tags: ["env"] }`.
 - The name is derived from the title and field (`DASHSCOPE` + `apiKey` →
   `DASHSCOPE_API_KEY`) unless the entry sets `envKeys` — see
@@ -253,7 +253,8 @@ Two things worth knowing:
 | `envKeys` | an entry **field** (optional) | pin exact names, e.g. `["DASHSCOPE_API_KEY"]`; the old singular `envKey` is accepted as a one-element shorthand |
 
 Nothing else is called `env*`: `list --json` / `show` report `envKeys` (the names
-an entry exports — what `get` accepts) and `envTagged` (whether `env` includes it).
+an entry exports — what `get` accepts), `envTagged` (whether `env` includes it)
+and `hasTotp` (whether `totp` can produce a code for it).
 
 ### 2. The commands
 
@@ -267,6 +268,8 @@ dsh-vault get my-entry                     # the entry's primary secret, stdout
 dsh-vault get my-entry --field apiKey      # one named field
 dsh-vault get my-entry --mask              # confirm it exists without printing it
 dsh-vault show my-entry                    # non-secret metadata as JSON
+dsh-vault totp my-entry                    # the current TOTP code (digits only)
+dsh-vault totp my-entry --json             # + digits, period, secondsRemaining
 dsh-vault env                              # env-tagged entries as KEY=VALUE
 dsh-vault env --mask                       # human view, both sections as KEY=VALUE:
 #   ## exported items
@@ -281,6 +284,13 @@ Secrets go to stdout and everything else (progress, errors) to stderr, so
 `$(dsh-vault get …)` and pipelines behave. Exit codes: `0` ok, `1` runtime
 error, `2` usage error.
 
+`totp` exists so a script can automate two-factor login without ever handling the
+long-lived secret: `code=$(dsh-vault totp my-entry)` prints six digits and nothing
+else. `get my-entry --field otpSecret` would print the **secret** instead — use it
+only when a tool genuinely needs to enrol the secret elsewhere. `--json` adds
+`secondsRemaining`, which is what lets a caller wait for a fresh window rather
+than race an expiring code.
+
 ### 3. Shell quoting: not `export $(…)`
 
 `eval "$(dsh-vault env)"` is right; `export $(dsh-vault env)` is wrong. Command
@@ -349,7 +359,7 @@ npm i -g dsh-vault && dsh-vault list                 # globally
 npx dsh-vault list                                   # or not at all
 ```
 
-The read commands (`list`, `get`, `env`, `show`, `verify`, `export-env`) depend
+The read commands (`list`, `get`, `env`, `show`, `totp`, `verify`, `export-env`) depend
 on Node alone, which is why the global and `npx` forms work. Only *writing* to a
 vault needs the harness runtime, and the plugin always has it.
 
@@ -464,7 +474,7 @@ Switch profiles in **Settings → Credentials → Permissions → Model tools**
 | **Full** | everything, incl. bulk import/export, browser sessions, backups and vault-file operations |
 | **Custom…** | core + any of: Management / Import-export / Browser sessions / Backups & files |
 
-`tools: basic|standard|full|custom` can also be set in the plugin config; the UI choice wins and is stored in `<vault dir>/access.json`.
+`tools: basic|standard|full|custom` can also be set in the plugin config; the UI choice wins and is stored in `<vault dir>/tools.json` (the process-wide tool catalog is not per vault).
 
 ## Configuration
 
@@ -529,7 +539,7 @@ git clone git@github.com:Ox0400/dsh-vault.git
 cd dsh-vault
 pnpm install    # installs devDependencies (typescript/tsdown/vitest, …)
 pnpm build      # builds host lib/*.js and the browser bundle lib/client.js
-pnpm test       # runs the 420 vitest tests
+pnpm test       # runs the 489 vitest tests
 ```
 
 > Tests need harness peer packages such as `dsh-llm`/`dsh-system-prompt`; inside the harness monorepo these resolve via workspace links.
@@ -537,13 +547,13 @@ pnpm test       # runs the 420 vitest tests
 Common commands:
 
 ```sh
-pnpm test          # unit + integration tests (vitest, 420)
+pnpm test          # unit + integration tests (vitest, 489)
 pnpm typecheck     # tsc -p tsconfig.json --noEmit
 pnpm build         # = build:host (tsc) + build:client (tsdown)
 npm pack           # optional: tarball for `dsh plugin add ./dsh-vault-0.1.1.tgz`
 ```
 
-All 420 tests pass (crypto / TOTP / password generation / store CRUD / gateway / integration).
+All 489 tests pass (crypto / TOTP / password generation / store CRUD / gateway / integration).
 
 Browser checks run against a real `dsh web` instead of vitest, and every one of
 them refuses to operate on the default vault:
@@ -601,7 +611,8 @@ This package is a standard npm bundle:
 - `dsh.bundle.patch` → `cordis.patch.yml` (the layer applied automatically when a profile lists this bundle)
 - `dsh.client` → browser-side declaration (`exports["./client"]` points at `lib/client.js`)
 - `prepare` script → self-contained build on git install (`tsc` host + `tsdown` client)
-- Runtime dependencies are all `peerDependencies` (provided by the host harness — no duplicate instances)
+- Runtime dependencies: only `playwright-core` (lazily `require`d, used by browser login sessions).
+  Everything else the host provides via `peerDependencies`, so there are no duplicate instances
 
 Distribution options:
 

package/lib/cli.js

@@ -25,6 +25,7 @@ import { createInterface } from 'node:readline';
 import { ReadStream } from 'node:tty';
 import { openVault, defaultVaultPath } from "./store.js";
 import { envLinesFor, envPairsForEntry, maskSecret, primarySecret, shellQuote } from "./env-export.js";
+import { parseTotpSecret, totp } from "./totp.js";
 function packageVersion() {
     try {
         const require = createRequire(import.meta.url);
@@ -44,8 +45,9 @@ Commands:
   list                    List entries with their env name (never secrets)
   get <id|title|ENVKEY>   Print one field of an entry (default: its main secret)
   show <id|title|ENVKEY>  Print an entry's non-secret fields as JSON
+  totp <id|title|ENVKEY>  Print the entry's current TOTP code (needs otpSecret)
   env                     Print env-TAGGED entries as KEY=VALUE lines (an entry
-                          must carry the tag "env"; "list" marks those [env]).
+                          must carry the tag "env"; "list" groups those first).
                           One value only? "get <entry>" needs no tag.
   export-env <path>       Write those lines to a file (mode 0600)
   verify                  Check the master password (nothing on stdout)
@@ -61,13 +63,13 @@ Options:
 list options:
   --kind <k>              Only entries of this kind
   --tag <t>               Only entries carrying this tag
-                          (each row also shows the env name that "get" accepts,
-                          the count of further keys in parentheses, and [env]
-                          when the entry is included in "dsh-vault env")
+                          (each row also shows the env name that "get" accepts
+                          and the count of further keys in parentheses)
 
 JSON output ("list --json", "show") reports per entry:
   envKeys                 the env names it exports (what "get" accepts)
   envTagged               whether "dsh-vault env" includes it
+  hasTotp                 whether "totp <entry>" can produce a code
 
 get options:
   --field <name>          apiKey | secret | accessToken | refreshToken | privateKey
@@ -76,6 +78,14 @@ get options:
   --mask                  Print a masked value (first 4 chars + ***)
   --all                   Print the whole entry as JSON (every secret — opt-in)
 
+totp options:
+  (none beyond the common options; --json adds digits, period and secondsRemaining)
+
+  The code is the only thing on stdout, so 2FA can be automated:
+    code=$(dsh-vault totp TwoFactor)
+  "get <entry> --field otpSecret" prints the long-lived SECRET instead — use
+  "totp" when a script needs a code, so the secret stays out of logs and history.
+
 env options:
   --prefix <P>            Prefix for derived key names (an explicit envKey is kept verbatim)
   --kind <k>              Only entries of this kind
@@ -219,7 +229,13 @@ async function promptHidden(prompt) {
 }
 async function readStdinLine() {
     const rl = createInterface({ input: process.stdin });
-    const line = await new Promise(res => rl.once('line', res));
+    // Zero-byte input (</dev/null, a `pass` lookup that failed, a CI step with no
+    // secret set) emits `close` but never `line`, so waiting only for `line` hung
+    // forever and the empty-password check below was unreachable.
+    const line = await new Promise(res => {
+        rl.once('line', res);
+        rl.once('close', () => res(''));
+    });
     rl.close();
     return line;
 }
@@ -255,6 +271,11 @@ async function resolvePassword(parsed, io) {
  * prints exactly the value `env` would emit for that key.
  */
 export function resolveEntry(store, needle) {
+    // `''` is a substring of every title, so an empty argument used to match a
+    // single entry and print its secret with exit 0.
+    if (needle.trim().length === 0) {
+        throw new Error('an empty name matches every entry — pass an id, a title, an envKey or an exported key');
+    }
     const entries = store.list();
     const byId = entries.find(e => e.id === needle);
     if (byId !== undefined)
@@ -324,6 +345,9 @@ function publicFields(entry) {
             out[key] = value;
     }
     out.hasSecret = primarySecret(entry) !== undefined;
+    // Presence only — the same level of detail as hasSecret, so a script can find
+    // the entries `totp` accepts without pulling any secret into a transcript.
+    out.hasTotp = typeof entry.otpSecret === 'string' && entry.otpSecret.length > 0;
     // ONE name for "the env names this entry exports": `envKeys`. It used to be a
     // configured `envKeys` plus a computed `exportedKeys`, which read as two
     // similar things — the computed list is the useful one (it already starts with
@@ -333,7 +357,7 @@ function publicFields(entry) {
     out.envTagged = (entry.tags ?? []).includes('env');
     return out;
 }
-const COMMANDS = new Set(['list', 'get', 'show', 'env', 'export-env', 'verify']);
+const COMMANDS = new Set(['list', 'get', 'show', 'totp', 'env', 'export-env', 'verify']);
 /** Run one CLI invocation; returns the process exit code. */
 export async function runCli(argv, io) {
     const parsed = parseArgs(argv);
@@ -359,6 +383,7 @@ export async function runCli(argv, io) {
         list: ['kind', 'tag'],
         get: ['field', 'fields', 'mask', 'all'],
         show: [],
+        totp: [],
         env: ['prefix', 'kind', 'keys-only', 'mask', 'explain', 'file'],
         'export-env': ['prefix', 'kind', 'keys-only'],
         verify: [],
@@ -371,6 +396,15 @@ export async function runCli(argv, io) {
         io.err(`accepted: ${[...allowed].map(f => `--${f}`).join(' ')}\n`);
         return 2;
     }
+    // `get my-entry --field` (no value) set the flag to `true`, which stringFlag
+    // reads as "not given" — so the command quietly printed the primary secret
+    // instead of the field the user asked for.
+    const needsValue = ['field', 'fields', 'kind', 'tag', 'prefix', 'file', 'vault', 'path'];
+    const valueless = needsValue.filter(name => parsed.flags.get(name) === true);
+    if (valueless.length > 0) {
+        io.err(`dsh-vault: ${valueless.map(f => `--${f}`).join(', ')} needs a value\n`);
+        return 2;
+    }
     const json = parsed.flags.get('json') === true;
     const mask = parsed.flags.get('mask') === true;
     const keysOnly = parsed.flags.get('keys-only') === true;
@@ -469,15 +503,64 @@ export async function runCli(argv, io) {
             else {
                 value = fieldValue(entry, name);
             }
-            if (typeof value !== 'string' || value.length === 0) {
+            // Absent, empty and non-string are three different answers. Reporting all
+            // of them as "has no field" made `--field expiresAt` (a number) and
+            // `--field tags` (an array) look like fields that do not exist.
+            if (value === undefined) {
                 io.err(`dsh-vault: "${entry.title}" has no field "${name}"\n`);
                 return 1;
             }
+            if (value === null || (typeof value === 'string' && value.length === 0)) {
+                io.err(`dsh-vault: "${entry.title}" field "${name}" is empty\n`);
+                return 1;
+            }
             const textual = name === 'username' || name === 'url' || name === 'notes' || name.startsWith('fields.');
-            const shown = mask && !textual ? maskSecret(value) : value;
+            // Strings keep the old masking rule; anything else is printed as JSON so
+            // booleans, timestamps and tags stay usable from a script.
+            const shown = typeof value === 'string'
+                ? (mask && !textual ? maskSecret(value) : value)
+                : JSON.stringify(value);
             io.out(json ? `${JSON.stringify({ id: entry.id, title: entry.title, field: name, value: shown })}\n` : `${shown}\n`);
             return 0;
         }
+        if (parsed.command === 'totp') {
+            const needle = parsed.positional[0];
+            if (needle === undefined) {
+                io.err('dsh-vault: totp needs an entry id, title or env key\n');
+                return 2;
+            }
+            const entry = resolveEntry(store, needle).entry;
+            const secret = typeof entry.otpSecret === 'string' && entry.otpSecret.length > 0 ? entry.otpSecret : undefined;
+            if (secret === undefined) {
+                io.err(`dsh-vault: "${entry.title}" has no TOTP secret\n`);
+                io.err('hint: "show <entry>" lists non-secret fields; the secret goes in the entry\'s otpSecret field.\n');
+                return 1;
+            }
+            const nowMs = Date.now();
+            let parsedSecret;
+            let code;
+            try {
+                parsedSecret = parseTotpSecret(secret);
+                code = totp(secret, nowMs);
+            }
+            catch (err) {
+                io.err(`dsh-vault: "${entry.title}" has an unusable otpSecret: ${err instanceof Error ? err.message : String(err)}\n`);
+                return 1;
+            }
+            if (!json) {
+                // Digits only: the whole point is `code=$(dsh-vault totp …)` in a script.
+                io.out(`${code}\n`);
+                return 0;
+            }
+            // `secondsRemaining` is what lets a caller wait for a fresh window instead
+            // of racing an expiring code, which is the classic 2FA automation bug.
+            const secondsRemaining = parsedSecret.periodSeconds - Math.floor(nowMs / 1000) % parsedSecret.periodSeconds;
+            io.out(`${JSON.stringify({
+                id: entry.id, title: entry.title, code,
+                digits: parsedSecret.digits, period: parsedSecret.periodSeconds, secondsRemaining,
+            })}\n`);
+            return 0;
+        }
         // env / export-env
         const prefix = stringFlag(parsed, 'prefix') ?? '';
         const kind = stringFlag(parsed, 'kind');
@@ -560,7 +643,7 @@ export async function runCli(argv, io) {
             io.err('  Tag one entry and run it again:\n');
             io.err('    UI:        Settings → Credentials → the entry → tags → env\n');
             io.err('    assistant: vault_update { id, tags: ["env"] }\n');
-            io.err('  `dsh-vault list` marks tagged entries with [env] and shows the name each exports.\n');
+            io.err('  `dsh-vault list` groups tagged entries under "Exported by `env`" and shows each name.\n');
             io.err('  Only need one value? `dsh-vault get <entry>` needs no tag at all.\n');
         }
         return 0;

package/lib/client.js

@@ -510,197 +510,197 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var VaultSection_module_css_default = {
-			"detailBox": "t_j5va_detailBox",
+			"auditChipActive": "t_j5va_auditChipActive",
+			"badgeBtn": "t_j5va_badgeBtn",
+			"trashButton": "t_j5va_trashButton",
+			"pwHistPwd": "t_j5va_pwHistPwd",
+			"detailTotp": "t_j5va_detailTotp",
 			"secretField": "t_j5va_secretField",
-			"pwBar": "t_j5va_pwBar",
-			"customKeyInput": "t_j5va_customKeyInput",
-			"riskDanger": "t_j5va_riskDanger",
-			"strengthStars": "t_j5va_strengthStars",
-			"pwWeak": "t_j5va_pwWeak",
+			"saveButton": "t_j5va_saveButton",
+			"error": "t_j5va_error",
+			"modeAuto": "t_j5va_modeAuto",
+			"checkField": "t_j5va_checkField",
+			"editorActions": "t_j5va_editorActions",
+			"dangerButton": "t_j5va_dangerButton",
+			"pwFair": "t_j5va_pwFair",
+			"tabActive": "t_j5va_tabActive",
+			"toolbar": "t_j5va_toolbar",
+			"histAdd": "t_j5va_histAdd",
+			"lenChipActive": "t_j5va_lenChipActive",
+			"emptyBox": "t_j5va_emptyBox",
+			"reportBox": "t_j5va_reportBox",
+			"pwMeter": "t_j5va_pwMeter",
+			"tabs": "t_j5va_tabs",
+			"detailRemain": "t_j5va_detailRemain",
+			"recentSearch": "t_j5va_recentSearch",
+			"recentLabel": "t_j5va_recentLabel",
+			"tagRow": "t_j5va_tagRow",
+			"tagCount": "t_j5va_tagCount",
+			"recentChip": "t_j5va_recentChip",
+			"tagManagerHead": "t_j5va_tagManagerHead",
+			"pwHistRow": "t_j5va_pwHistRow",
+			"status": "t_j5va_status",
+			"kindIcon": "t_j5va_kindIcon",
 			"importActions": "t_j5va_importActions",
-			"genOpts": "t_j5va_genOpts",
-			"vaultTarget": "t_j5va_vaultTarget",
-			"vaultManageRow": "t_j5va_vaultManageRow",
-			"importName": "t_j5va_importName",
-			"iconFieldWrap": "t_j5va_iconFieldWrap",
-			"copied": "t_j5va_copied",
-			"field": "t_j5va_field",
+			"reportLine": "t_j5va_reportLine",
+			"strengthTrack": "t_j5va_strengthTrack",
 			"rowExpired": "t_j5va_rowExpired",
-			"dangerButton": "t_j5va_dangerButton",
-			"auditChips": "t_j5va_auditChips",
-			"reportTitle": "t_j5va_reportTitle",
-			"healthBar": "t_j5va_healthBar",
-			"pwStrong": "t_j5va_pwStrong",
-			"tagName": "t_j5va_tagName",
-			"healthSummary": "t_j5va_healthSummary",
-			"lenChip": "t_j5va_lenChip",
-			"genOptRow": "t_j5va_genOptRow",
-			"exportChips": "t_j5va_exportChips",
-			"riskBanner": "t_j5va_riskBanner",
-			"searchBox": "t_j5va_searchBox",
 			"list": "t_j5va_list",
-			"moreButton": "t_j5va_moreButton",
-			"genHist": "t_j5va_genHist",
-			"reportLine": "t_j5va_reportLine",
-			"kindChip": "t_j5va_kindChip",
+			"bulkItem": "t_j5va_bulkItem",
+			"auditIssues": "t_j5va_auditIssues",
+			"pwBar": "t_j5va_pwBar",
+			"exportChips": "t_j5va_exportChips",
 			"customEq": "t_j5va_customEq",
-			"detailActions": "t_j5va_detailActions",
-			"identity": "t_j5va_identity",
-			"auditRow": "t_j5va_auditRow",
+			"pwHistBox": "t_j5va_pwHistBox",
+			"auditChip": "t_j5va_auditChip",
+			"kindChip": "t_j5va_kindChip",
+			"rowMain": "t_j5va_rowMain",
+			"favToggle": "t_j5va_favToggle",
+			"policyField": "t_j5va_policyField",
+			"lenChip": "t_j5va_lenChip",
+			"copyAllBtn": "t_j5va_copyAllBtn",
 			"toolbarDivider": "t_j5va_toolbarDivider",
-			"bulkCount": "t_j5va_bulkCount",
-			"histAdd": "t_j5va_histAdd",
-			"pinOff": "t_j5va_pinOff",
-			"brandGlyph": "t_j5va_brandGlyph",
-			"detailItem": "t_j5va_detailItem",
-			"empty": "t_j5va_empty",
-			"kindIcon": "t_j5va_kindIcon",
-			"auditWhen": "t_j5va_auditWhen",
-			"auditChipActive": "t_j5va_auditChipActive",
-			"badge": "t_j5va_badge",
+			"importRow": "t_j5va_importRow",
+			"field": "t_j5va_field",
+			"emojiPicker": "t_j5va_emojiPicker",
+			"actionGroup": "t_j5va_actionGroup",
+			"strengthStrong": "t_j5va_strengthStrong",
+			"vaultSwitch": "t_j5va_vaultSwitch",
+			"customFieldRows": "t_j5va_customFieldRows",
+			"inlineField": "t_j5va_inlineField",
 			"rowCheck": "t_j5va_rowCheck",
-			"riskWarn": "t_j5va_riskWarn",
-			"attachAdd": "t_j5va_attachAdd",
-			"tagRow": "t_j5va_tagRow",
+			"srOnly": "t_j5va_srOnly",
+			"modeReadonly": "t_j5va_modeReadonly",
+			"histUpdate": "t_j5va_histUpdate",
+			"clearButton": "t_j5va_clearButton",
+			"dueBadge": "t_j5va_dueBadge",
+			"riskBanner": "t_j5va_riskBanner",
+			"attachBox": "t_j5va_attachBox",
+			"kindChipActive": "t_j5va_kindChipActive",
 			"importList": "t_j5va_importList",
-			"emptyHint": "t_j5va_emptyHint",
-			"detailDeleteBtn": "t_j5va_detailDeleteBtn",
-			"gridRow": "t_j5va_gridRow",
-			"policyBar": "t_j5va_policyBar",
-			"addButton": "t_j5va_addButton",
-			"editor": "t_j5va_editor",
-			"genHistItem": "t_j5va_genHistItem",
-			"totp": "t_j5va_totp",
-			"badgeOk": "t_j5va_badgeOk",
+			"moreWrap": "t_j5va_moreWrap",
+			"highBadge": "t_j5va_highBadge",
+			"dupGroup": "t_j5va_dupGroup",
+			"genOpts": "t_j5va_genOpts",
+			"selectActive": "t_j5va_selectActive",
+			"badge": "t_j5va_badge",
+			"badgeWarn": "t_j5va_badgeWarn",
+			"riskWarn": "t_j5va_riskWarn",
+			"strengthFair": "t_j5va_strengthFair",
 			"tabPane": "t_j5va_tabPane",
-			"recentClear": "t_j5va_recentClear",
-			"kindChipActive": "t_j5va_kindChipActive",
-			"row": "t_j5va_row",
-			"kindFilter": "t_j5va_kindFilter",
-			"dupMerge": "t_j5va_dupMerge",
-			"brandGlyphSm": "t_j5va_brandGlyphSm",
-			"rowDue": "t_j5va_rowDue",
-			"tagActions": "t_j5va_tagActions",
-			"vaultSwitch": "t_j5va_vaultSwitch",
-			"recentLabel": "t_j5va_recentLabel",
-			"badgeActive": "t_j5va_badgeActive",
-			"gridDetail": "t_j5va_gridDetail",
-			"detailCode": "t_j5va_detailCode",
+			"colorFieldWrap": "t_j5va_colorFieldWrap",
+			"customFieldRow": "t_j5va_customFieldRow",
+			"actionPrimary": "t_j5va_actionPrimary",
+			"bulkBar": "t_j5va_bulkBar",
+			"tagName": "t_j5va_tagName",
+			"reportTitle": "t_j5va_reportTitle",
 			"actionBtn": "t_j5va_actionBtn",
-			"lockedTag": "t_j5va_lockedTag",
+			"rowSelected": "t_j5va_rowSelected",
+			"histDanger": "t_j5va_histDanger",
 			"pinStar": "t_j5va_pinStar",
-			"toolbarFilters": "t_j5va_toolbarFilters",
-			"modeAuto": "t_j5va_modeAuto",
-			"policyField": "t_j5va_policyField",
-			"revealButton": "t_j5va_revealButton",
-			"modeAsk": "t_j5va_modeAsk",
-			"actionGroupLabel": "t_j5va_actionGroupLabel",
-			"status": "t_j5va_status",
-			"rowMain": "t_j5va_rowMain",
+			"actionGroups": "t_j5va_actionGroups",
+			"importDesc": "t_j5va_importDesc",
+			"vaultHeader": "t_j5va_vaultHeader",
 			"pinOn": "t_j5va_pinOn",
+			"detailActions": "t_j5va_detailActions",
+			"vaultManageRow": "t_j5va_vaultManageRow",
+			"tagActions": "t_j5va_tagActions",
+			"row": "t_j5va_row",
+			"editor": "t_j5va_editor",
+			"totp": "t_j5va_totp",
+			"auditWhen": "t_j5va_auditWhen",
+			"reportSub": "t_j5va_reportSub",
+			"pwStrong": "t_j5va_pwStrong",
+			"colorSwatch": "t_j5va_colorSwatch",
 			"gridInput": "t_j5va_gridInput",
-			"histLink": "t_j5va_histLink",
-			"title": "t_j5va_title",
-			"lockedBanner": "t_j5va_lockedBanner",
-			"selectActive": "t_j5va_selectActive",
-			"backupButton": "t_j5va_backupButton",
-			"toolbar": "t_j5va_toolbar",
-			"importDesc": "t_j5va_importDesc",
-			"auditIssues": "t_j5va_auditIssues",
-			"editorActions": "t_j5va_editorActions",
-			"gridName": "t_j5va_gridName",
-			"uriCode": "t_j5va_uriCode",
-			"section": "t_j5va_section",
-			"badgeLink": "t_j5va_badgeLink",
+			"pwWeak": "t_j5va_pwWeak",
 			"favActive": "t_j5va_favActive",
-			"colorFieldWrap": "t_j5va_colorFieldWrap",
-			"detailRemain": "t_j5va_detailRemain",
-			"strengthTrack": "t_j5va_strengthTrack",
-			"searchKbd": "t_j5va_searchKbd",
-			"histUpdate": "t_j5va_histUpdate",
-			"actionPrimary": "t_j5va_actionPrimary",
-			"dupNames": "t_j5va_dupNames",
-			"totpCopy": "t_j5va_totpCopy",
-			"pwHistRow": "t_j5va_pwHistRow",
+			"listCompact": "t_j5va_listCompact",
+			"brandGlyph": "t_j5va_brandGlyph",
+			"modeAsk": "t_j5va_modeAsk",
+			"customValueInput": "t_j5va_customValueInput",
+			"detailCode": "t_j5va_detailCode",
+			"gridDetail": "t_j5va_gridDetail",
+			"sortButton": "t_j5va_sortButton",
+			"urlGlyph": "t_j5va_urlGlyph",
+			"badgeLink": "t_j5va_badgeLink",
+			"strengthStars": "t_j5va_strengthStars",
+			"gridRow": "t_j5va_gridRow",
 			"badgeDanger": "t_j5va_badgeDanger",
-			"toolbarMain": "t_j5va_toolbarMain",
-			"strengthStrong": "t_j5va_strengthStrong",
-			"auditChip": "t_j5va_auditChip",
-			"pwFair": "t_j5va_pwFair",
-			"totpRing": "t_j5va_totpRing",
-			"tab": "t_j5va_tab",
-			"customFieldRows": "t_j5va_customFieldRows",
-			"favToggle": "t_j5va_favToggle",
-			"emojiBtn": "t_j5va_emojiBtn",
-			"tabActive": "t_j5va_tabActive",
-			"intro": "t_j5va_intro",
-			"pwLabel": "t_j5va_pwLabel",
-			"trashButton": "t_j5va_trashButton",
-			"hit": "t_j5va_hit",
-			"histDanger": "t_j5va_histDanger",
+			"healthBar": "t_j5va_healthBar",
 			"histNeutral": "t_j5va_histNeutral",
+			"section": "t_j5va_section",
+			"emptyHint": "t_j5va_emptyHint",
+			"totpCopy": "t_j5va_totpCopy",
+			"kindFilter": "t_j5va_kindFilter",
+			"recentClear": "t_j5va_recentClear",
+			"gridName": "t_j5va_gridName",
+			"pwLabel": "t_j5va_pwLabel",
+			"auditRow": "t_j5va_auditRow",
 			"editorBody": "t_j5va_editorBody",
-			"highBadge": "t_j5va_highBadge",
-			"detailTotp": "t_j5va_detailTotp",
-			"reportJump": "t_j5va_reportJump",
-			"strengthFair": "t_j5va_strengthFair",
-			"colorSwatch": "t_j5va_colorSwatch",
-			"importRow": "t_j5va_importRow",
-			"exportChip": "t_j5va_exportChip",
-			"recentSearch": "t_j5va_recentSearch",
-			"recentChip": "t_j5va_recentChip",
+			"searchBox": "t_j5va_searchBox",
+			"healthSummary": "t_j5va_healthSummary",
+			"uriCode": "t_j5va_uriCode",
+			"toolbarFilters": "t_j5va_toolbarFilters",
+			"policyBar": "t_j5va_policyBar",
+			"histLink": "t_j5va_histLink",
+			"tab": "t_j5va_tab",
+			"genOptRow": "t_j5va_genOptRow",
+			"lockedBanner": "t_j5va_lockedBanner",
 			"strengthWeak": "t_j5va_strengthWeak",
-			"emptyBox": "t_j5va_emptyBox",
-			"pwHistPwd": "t_j5va_pwHistPwd",
+			"empty": "t_j5va_empty",
+			"addButton": "t_j5va_addButton",
+			"brandGlyphSm": "t_j5va_brandGlyphSm",
+			"riskDanger": "t_j5va_riskDanger",
+			"lockedTag": "t_j5va_lockedTag",
+			"reportLineLink": "t_j5va_reportLineLink",
+			"actionGroupLabel": "t_j5va_actionGroupLabel",
+			"identity": "t_j5va_identity",
+			"hit": "t_j5va_hit",
+			"colorPalette": "t_j5va_colorPalette",
+			"rowDue": "t_j5va_rowDue",
+			"dupMerge": "t_j5va_dupMerge",
 			"scoreRing": "t_j5va_scoreRing",
-			"modeReadonly": "t_j5va_modeReadonly",
-			"badgeWarn": "t_j5va_badgeWarn",
-			"saveButton": "t_j5va_saveButton",
-			"bulkBar": "t_j5va_bulkBar",
+			"totpRing": "t_j5va_totpRing",
+			"badgeOk": "t_j5va_badgeOk",
+			"dupNames": "t_j5va_dupNames",
+			"vaultTarget": "t_j5va_vaultTarget",
 			"moreMenu": "t_j5va_moreMenu",
-			"dueBadge": "t_j5va_dueBadge",
-			"urlGlyph": "t_j5va_urlGlyph",
-			"retryButton": "t_j5va_retryButton",
+			"auditChips": "t_j5va_auditChips",
+			"customKeyInput": "t_j5va_customKeyInput",
+			"revealButton": "t_j5va_revealButton",
+			"iconFieldWrap": "t_j5va_iconFieldWrap",
+			"intro": "t_j5va_intro",
+			"pwHistTime": "t_j5va_pwHistTime",
+			"attachAdd": "t_j5va_attachAdd",
+			"searchKbd": "t_j5va_searchKbd",
 			"lenChips": "t_j5va_lenChips",
-			"lenChipActive": "t_j5va_lenChipActive",
+			"headerMessage": "t_j5va_headerMessage",
+			"detailDeleteBtn": "t_j5va_detailDeleteBtn",
 			"strengthFill": "t_j5va_strengthFill",
-			"tagManager": "t_j5va_tagManager",
-			"srOnly": "t_j5va_srOnly",
-			"resultCount": "t_j5va_resultCount",
-			"attachBox": "t_j5va_attachBox",
-			"tabs": "t_j5va_tabs",
-			"bulkItem": "t_j5va_bulkItem",
-			"reportBox": "t_j5va_reportBox",
+			"pinOff": "t_j5va_pinOff",
+			"deleteButton": "t_j5va_deleteButton",
 			"rowActions": "t_j5va_rowActions",
-			"pwHistBox": "t_j5va_pwHistBox",
-			"reportLineLink": "t_j5va_reportLineLink",
-			"tagCount": "t_j5va_tagCount",
-			"actionGroups": "t_j5va_actionGroups",
-			"pwMeter": "t_j5va_pwMeter",
-			"colorPalette": "t_j5va_colorPalette",
-			"copyAllBtn": "t_j5va_copyAllBtn",
-			"customValueInput": "t_j5va_customValueInput",
+			"detailItem": "t_j5va_detailItem",
+			"badgeActive": "t_j5va_badgeActive",
+			"moreButton": "t_j5va_moreButton",
+			"toolbarMain": "t_j5va_toolbarMain",
+			"reportJump": "t_j5va_reportJump",
+			"tagManager": "t_j5va_tagManager",
+			"genHistItem": "t_j5va_genHistItem",
+			"title": "t_j5va_title",
 			"inlineInput": "t_j5va_inlineInput",
-			"emojiPicker": "t_j5va_emojiPicker",
-			"moreWrap": "t_j5va_moreWrap",
+			"bulkCount": "t_j5va_bulkCount",
+			"emojiBtn": "t_j5va_emojiBtn",
+			"copied": "t_j5va_copied",
+			"resultCount": "t_j5va_resultCount",
+			"exportChip": "t_j5va_exportChip",
+			"importName": "t_j5va_importName",
+			"retryButton": "t_j5va_retryButton",
+			"backupButton": "t_j5va_backupButton",
 			"gridActions": "t_j5va_gridActions",
-			"badgeBtn": "t_j5va_badgeBtn",
-			"dupGroup": "t_j5va_dupGroup",
-			"deleteButton": "t_j5va_deleteButton",
-			"pwHistTime": "t_j5va_pwHistTime",
-			"sortButton": "t_j5va_sortButton",
-			"tagManagerHead": "t_j5va_tagManagerHead",
-			"actionGroup": "t_j5va_actionGroup",
-			"error": "t_j5va_error",
-			"vaultHeader": "t_j5va_vaultHeader",
-			"checkField": "t_j5va_checkField",
-			"clearButton": "t_j5va_clearButton",
-			"headerMessage": "t_j5va_headerMessage",
-			"reportSub": "t_j5va_reportSub",
-			"rowSelected": "t_j5va_rowSelected",
-			"listCompact": "t_j5va_listCompact",
-			"customFieldRow": "t_j5va_customFieldRow",
-			"inlineField": "t_j5va_inlineField"
+			"genHist": "t_j5va_genHist",
+			"detailBox": "t_j5va_detailBox"
 		};
 		//#endregion
 		//#region src/client/VaultSection.tsx

package/lib/store.js

@@ -977,15 +977,27 @@ export class VaultStore {
             }
             throw error;
         }
-        const parsed = JSON.parse(raw);
+        // Name the file in every failure below: a vault can live at an explicit
+        // --path, and "Unexpected token 'o'" or "version undefined" told the user
+        // neither which file was damaged nor that it was damaged at all.
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`${this.path} is not valid JSON — it is corrupt or not a vault file`);
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error(`${this.path} is not a vault file (expected a JSON object)`);
+        }
         if (parsed.version !== VAULT_FORMAT_VERSION) {
-            throw new Error(`unsupported vault format version ${parsed.version} (expected ${VAULT_FORMAT_VERSION})`);
+            throw new Error(`${this.path} has unsupported vault format version ${JSON.stringify(parsed.version)} (expected ${VAULT_FORMAT_VERSION})`);
         }
         if (!parsed.kdf || parsed.kdf.algo !== 'scrypt' || !parsed.kdf.saltHex) {
-            throw new Error('vault document is missing valid KDF parameters');
+            throw new Error(`${this.path} is missing valid KDF parameters`);
         }
         if (!parsed.verify) {
-            throw new Error('vault document is missing its password-verification envelope');
+            throw new Error(`${this.path} is missing its password-verification envelope`);
         }
         return { file: parsed, created: false };
     }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-vault",
-  "version": "1.10.73",
+  "version": "1.10.74-rc.2",
   "bin": {
-    "dsh-vault": "./lib/cli.js"
+    "dsh-vault": "lib/cli.js"
   },
   "description": "Encrypted credential vault for DeepSeek Harness: store and retrieve usernames, emails, phone numbers, passwords, TOTP secrets, SSH/API-key/OAuth developer credentials through model tools and a Settings UI page.",
   "type": "module",
@@ -88,6 +88,8 @@
     "e2e:theme": "node tests/e2e/theme-check.mjs",
     "e2e:polish": "node tests/e2e/polish-check.mjs",
     "e2e:contrast": "node tests/e2e/contrast-audit.mjs",
-    "e2e:prompt": "node tests/e2e/cli-prompt.mjs"
+    "e2e:prompt": "node tests/e2e/cli-prompt.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "postpublish": "node scripts/release-check.mjs --version"
   }
 }