dsh-jev-guard 0.5.1

package/tools/selftest-reason.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * 拒绝理由自检:那行"交给用户去终端里执行"的授权命令,必须真的能整行复制粘贴。
+ *
+ * 为什么单独有这份自检:这条理由的读者是**用户**,而且他是在**自己的终端**里粘贴 ——
+ * 工作目录是任意的。曾经这里打印的是相对路径 `node bin/guard.mjs`,只有用户恰好站在包目录
+ * 里才能用;而授权命令里的命令文本一旦被截断或引号转义写错,用户拿到的令牌就与 AI 重试的
+ * 那条命令对不上,表现为"授权了还是被拦"。两者都不会报错,只会静静地失效 —— 所以要断言。
+ *
+ * 全部离线:用合成 verdict,不联网、不碰 ~/.jev-guard。
+ *
+ * @module jev-guard/tools/selftest-reason
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { isAbsolute, join } from 'node:path'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { setLang } from '../lib/i18n.js'
+import { explain, reviseGuidance, shellName, shellQuote, toHostDecision } from '../lib/verdict.js'
+
+// 本文件的断言写的是**中文文案本身**(哪些句子必须出现 / 必须不出现),所以先把语言钉死 ——
+// 否则同一份自检在英文 locale 的机器上会无缘无故地红。英文那一侧由
+// `tools/selftest-i18n.mjs` 覆盖:它断言目录完整性、两语言键集合一致,以及英文理由的形状。
+setLang('zh-CN')
+
+let failed = 0
+let checks = 0
+
+/**
+ * @param label - 用例名。
+ * @param ok - 断言结果。
+ * @param detail - 失败细节。
+ */
+function expect(label, ok, detail = '') {
+  checks += 1
+  if (!ok) failed += 1
+  process.stdout.write(`${ok ? 'ok  ' : 'FAIL'}  ${label}${ok ? '' : `   ${detail}`}\n`)
+}
+
+/**
+ * 打印一条"跳过"说明(不计入断言数)。
+ * 为什么要专门区分:一个"在任何平台都假装通过"的断言比没有断言更糟 ——
+ * 它会让 reviewer 以为某件事验过了。
+ * @param text - 说明文本。
+ */
+function note(text) {
+  process.stdout.write(`note  ${text}\n`)
+}
+
+/** 可用来做 POSIX 引号往返的 shell;Windows 上没有,那就跳过并说明。 */
+const POSIX_SHELL = process.platform === 'win32' ? undefined : 'bash'
+
+/** 与 adapters/dsh/index.js 里同样的推导,用于断言默认路径落在包内。 */
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** 一个"被 Jev 判为危险"的合成判定 —— 非 L0,所以理由里应当带令牌提示。 */
+const riskVerdict = { action: 'block', source: 'jev', p: 0.78, model: 'jev-1.13.0', ms: 290 }
+/** 一个 L0 硬规则判定 —— 永不允许,理由里**不应**出现令牌提示。 */
+const l0Verdict = { action: 'block', source: 'static-rule', rule: { id: 'mkfs', why: '格式化文件系统', kind: 'deny' } }
+
+const CMD = 'rm -rf /home/user/jev-guard-probe-dir'
+
+// 1) 授权行用的是绝对路径,且落在包内的 bin/guard.mjs
+const hint = explain(CMD, riskVerdict, { policy: 'never', token: 'ALLOW-0A2DB6157F' })
+const m = hint.match(/ node (\S+) allow ([\s\S]*?) —— 然后重试同一条命令/)
+expect('理由里出现授权行', m !== null, hint)
+const cliPath = m?.[1] ?? ''
+expect('授权行给出的是绝对路径', isAbsolute(cliPath), cliPath)
+expect('绝对路径指向包内的 bin/guard.mjs', cliPath === join(PKG_ROOT, 'bin', 'guard.mjs'), cliPath)
+expect('授权行以 node 开头(可直接粘贴)', / node \S+ allow /.test(hint))
+expect('令牌原文出现在理由里', hint.includes('ALLOW-0A2DB6157F'))
+expect('用户被明确告知"AI 自己跑会被拒"', hint.includes('授权只在交互终端生效'))
+
+// 2) 引号转义必须能原样解析回同一条命令(用户粘进 shell 的结果 = AI 重试的那条命令)
+//
+// ⚠️ 这一段用 **bash** 做往返,只在 POSIX 平台适用。Windows 上应当验的是 **PowerShell** 形式
+// (见第 10 节),这里显式**跳过并说明**,而不是让它悄悄失败或悄悄通过 ——
+// 一个"在任何平台都假装通过"的断言比没有断言更糟。
+const quoted = m?.[2] ?? ''
+if (POSIX_SHELL) {
+  const back = execFileSync(POSIX_SHELL, ['-c', `printf %s ${quoted}`], { encoding: 'utf8' })
+  expect('粘贴后解析回的命令与原文逐字一致', back === CMD, JSON.stringify(back))
+} else {
+  note('绕过 bash 的往返用例已跳过(本平台没有 POSIX shell;Windows 走第 10 节的 PowerShell 往返)')
+}
+
+// 3) 命令里带单引号 / 双引号 / 中文时同样成立(shellQuote 的单引号转义)
+const tricky = 'rm -rf /home/user/jev-guard-probe-dir && echo "it\'s 探针,含单引号与中文"'
+const trickyHint = explain(tricky, riskVerdict, { policy: 'never', token: 'ALLOW-15537AF182' })
+const trickyQuoted = trickyHint.match(/ allow ([\s\S]*?) —— 然后重试同一条命令/)?.[1] ?? ''
+if (POSIX_SHELL) {
+  const trickyBack = execFileSync(POSIX_SHELL, ['-c', `printf %s ${trickyQuoted}`], { encoding: 'utf8' })
+  expect('含引号/中文的命令也能原样解析回来', trickyBack === tricky, JSON.stringify(trickyBack))
+} else {
+  note('含引号/中文的 bash 往返已跳过(同上)')
+}
+
+// 4) 长命令**不得**被截断:令牌是对完整命令文本求哈希的,截断后用户授权就匹配不上。
+//    (理由末尾" 命令:<文本>"那一段允许截断到 300 字符,但授权行不行。)
+const longCmd = `rm -rf /home/user/jev-guard-probe-dir/${'sub-dir-'.repeat(50)}`
+const longHint = explain(longCmd, riskVerdict, { policy: 'never', token: 'ALLOW-DEADBEEF00' })
+const longQuoted = longHint.match(/ allow ([\s\S]*?) —— 然后重试同一条命令/)?.[1] ?? ''
+expect('长命令的授权行未被截断', longQuoted.includes('sub-dir-'.repeat(50)) && longQuoted.length > 300, String(longQuoted.length))
+if (POSIX_SHELL) {
+  const longBack = execFileSync(POSIX_SHELL, ['-c', `printf %s ${longQuoted}`], { encoding: 'utf8' })
+  expect('长命令也能原样解析回来', longBack === longCmd, String(longBack.length))
+} else {
+  expect('长命令的授权行长度与原文一致(不经 shell 直接比对)', longQuoted.length >= longCmd.length, `${longQuoted.length} vs ${longCmd.length}`)
+}
+
+// 5) L0 硬规则:令牌越过不了硬地板,所以理由里**不该**出现授权行(免得用户白试)
+const l0Hint = explain('mkfs.ext4 /dev/sdb1', l0Verdict, { policy: 'never', token: 'ALLOW-0A2DB6157F' })
+expect('L0 拦截的理由里没有授权提示', !l0Hint.includes('allow ') && !l0Hint.includes('ALLOW-0A2DB6157F'), l0Hint)
+expect('L0 拦截的理由仍说明不是用户手动拒绝', l0Hint.includes('不是用户手动拒绝'))
+
+// 6) token 缺失时不给出授权行(没什么可授权的)
+expect('没有令牌时不出现授权提示', !explain(CMD, riskVerdict, { policy: 'never' }).includes('allow '))
+
+// 7) 宿主侧映射与理由同源:deny 的 reason 就是 explain 的输出
+const deny = toHostDecision(CMD, riskVerdict, 'never', { token: 'ALLOW-0A2DB6157F' })
+expect('never 策略下映射为 deny', deny.kind === 'deny')
+expect('deny 的理由同样带绝对路径授权行', deny.reason.includes(join(PKG_ROOT, 'bin', 'guard.mjs')) && deny.reason.includes('ALLOW-0A2DB6157F'))
+expect('allow 判定不产生理由', toHostDecision('ls', { action: 'allow', source: 'prefilter' }, 'never').kind === 'allow')
+
+// 8) 策略分叉:同一个 escalate,在 never 下是"没有弹窗 + 给令牌",在 ask 下是"已弹审批窗 + 不给令牌"。
+//    实测教训(2026-09-20):ask 模式的弹窗里原样显示了 never 模式那句"本会话没有审批提示",
+//    还附了一条让用户去终端授权的命令 —— 指着眼前的弹窗说没有弹窗。
+const TRUNC = 'truncate -s 0 /home/user/jev-guard-demo/notes.txt'
+/** 一个"必须人工确认"的 L0 ask 判定(kind='ask',与 kind='deny' 的硬地板相对)。 */
+const askRuleVerdict = { action: 'escalate', source: 'static-rule', rule: { id: 'truncate-file', why: '把文件截断/覆盖为空', kind: 'ask' }, token: 'ALLOW-5031AC2085' }
+
+const askEsc = toHostDecision(TRUNC, askRuleVerdict, 'ask', { token: 'ALLOW-5031AC2085' })
+expect('ask 策略下 escalate 映射为 ask(宿主会弹审批框)', askEsc.kind === 'ask', askEsc.kind)
+expect('ask 策略的理由说明宿主已发起审批请求', askEsc.reason.includes('审批请求'), askEsc.reason.slice(0, 140))
+expect('ask 策略的理由不再说"本会话没有审批提示"', !askEsc.reason.includes('本会话没有审批提示'))
+expect('ask 策略下不再附令牌授权行(人就在弹窗前面)', !askEsc.reason.includes('ALLOW-5031AC2085'), askEsc.reason.slice(0, 200))
+expect('ask 策略的理由里没有"复制到终端"那句', !askEsc.reason.includes('allow '))
+
+const neverEsc = toHostDecision(TRUNC, askRuleVerdict, 'never', { token: 'ALLOW-5031AC2085' })
+expect('never 策略下 escalate 映射为 deny', neverEsc.kind === 'deny', neverEsc.kind)
+expect('never 策略仍然说没有审批提示', neverEsc.reason.includes('本会话没有审批提示'))
+expect('never 策略仍然附令牌授权行', neverEsc.reason.includes('ALLOW-5031AC2085'))
+
+// 8b) 模式相关路由(2026-09-20 用户决定,见 docs/DECISIONS.md D13)。
+//     改动前:只有 escalate 会看审批策略,revise / block 一律直接拒绝。审计证据 —— 一天里
+//     **9 条 revise 拒绝发生在 approval=ask 模式下**(全是 cp / sed -i / git add 这类维护动作),
+//     人就在场却拿不到弹窗,等于让一个 50% 的判断替人做决定。
+//     改动后:ask 模式下 revise 与 Jev 高分的 block 都转人工审批;never 模式(全自动,没人可问)
+//     保持直接拒绝。**例外**是 L0 的 deny 类硬规则:两种模式都拦死,不弹窗也不发令牌。
+const reviseVerdict = { action: 'revise', source: 'jev', p: 0.58, model: 'jev-1.13.0', ms: 240 }
+
+const askBlock = toHostDecision(CMD, riskVerdict, 'ask', { token: 'ALLOW-0A2DB6157F' })
+expect('ask 策略下 Jev 高分的 block 转人工审批', askBlock.kind === 'ask', askBlock.kind)
+expect('ask 策略下 block 的理由说明已发起审批请求', askBlock.reason.includes('审批请求'), askBlock.reason.slice(0, 140))
+expect('ask 策略下 block 不再附令牌授权行(人就在弹窗前面)', !askBlock.reason.includes('ALLOW-0A2DB6157F'))
+
+const neverBlock = toHostDecision(CMD, riskVerdict, 'never', { token: 'ALLOW-0A2DB6157F' })
+expect('never 策略下 Jev 高分的 block 仍然是 deny', neverBlock.kind === 'deny', neverBlock.kind)
+expect('never 策略下 block 仍附令牌授权行', neverBlock.reason.includes('ALLOW-0A2DB6157F'))
+
+const askRevise = toHostDecision(CMD, reviseVerdict, 'ask', { token: 'ALLOW-0A2DB6157F' })
+expect('ask 策略下 revise 转人工审批', askRevise.kind === 'ask', askRevise.kind)
+expect('ask 策略下 revise 的抬头改成"需要人工确认"', askRevise.reason.includes('需要人工确认'), askRevise.reason.slice(0, 70))
+expect('ask 策略下 revise 不再附令牌授权行', !askRevise.reason.includes('ALLOW-0A2DB6157F'))
+
+const neverRevise = toHostDecision(CMD, reviseVerdict, 'never', { token: 'ALLOW-0A2DB6157F' })
+expect('never 策略下 revise 仍然是 deny', neverRevise.kind === 'deny', neverRevise.kind)
+expect('never 策略下 revise 仍附令牌授权行', neverRevise.reason.includes('ALLOW-0A2DB6157F'))
+expect('never 策略下 revise 的抬头仍是"暂缓"', neverRevise.reason.includes('[暂缓'), neverRevise.reason.slice(0, 70))
+
+// 例外:L0 的 deny 类硬规则 = 绝对闸门。两种模式都拦死,既不弹窗也不给令牌。
+const askL0 = toHostDecision('mkfs.ext4 /dev/sdb1', l0Verdict, 'ask', { token: 'ALLOW-0A2DB6157F' })
+expect('ask 策略下 L0 硬拒绝**不**转人工(绝对闸门)', askL0.kind === 'deny', askL0.kind)
+expect('L0 硬拒绝的理由里没有令牌授权行', !askL0.reason.includes('ALLOW-0A2DB6157F'))
+expect('L0 硬拒绝的理由仍说"禁止自动执行"', askL0.reason.includes('禁止自动执行'), askL0.reason.slice(0, 170))
+
+// 两个路由开关可以单独关掉(配置层就能回退,不必改代码)
+const askReviseOff = toHostDecision(CMD, reviseVerdict, 'ask', { reviseInAskMode: 'deny', token: 'ALLOW-0A2DB6157F' })
+expect('reviseInAskMode=deny 时退回直接拒绝', askReviseOff.kind === 'deny', askReviseOff.kind)
+const askBlockOff = toHostDecision(CMD, riskVerdict, 'ask', { blockInAskMode: 'deny', token: 'ALLOW-0A2DB6157F' })
+expect('blockInAskMode=deny 时退回直接拒绝', askBlockOff.kind === 'deny', askBlockOff.kind)
+
+// explain 的抬头也要跟着**路由结果**走(弹窗里显示的就是这句)
+const routedHead = explain(CMD, reviseVerdict, { policy: 'ask', routedToHuman: true })
+expect('已转人工时 revise 的抬头是"需要人工确认"', routedHead.includes('[需要人工确认]'), routedHead.slice(0, 70))
+const deniedHead = explain(CMD, reviseVerdict, { policy: 'ask', routedToHuman: false })
+expect('未转人工时 revise 的抬头仍是"暂缓"', deniedHead.includes('[暂缓'), deniedHead.slice(0, 70))
+
+// revise 的三种降级模板**两种出路都要带**:转人工时是弹窗正文,被拒时是给模型的教案。
+const routedGuidance = reviseGuidance(CMD, reviseVerdict, { policy: 'ask', routedToHuman: true })
+expect('转人工的 revise 理由仍带三种降级模板', routedGuidance.includes('可以尝试的更安全形式'), routedGuidance.slice(-200))
+expect('转人工的 revise 理由带令牌以外的降级建议', routedGuidance.includes('只读/演练') || routedGuidance.includes('作用域'))
+
+// 9) shellQuote:单引号包裹 + 按**平台**分叉的转义(POSIX `'\''` vs PowerShell `''`)
+expect("shellQuote(POSIX) 转义单引号", shellQuote("a'b", 'linux') === "'a'\\''b'", shellQuote("a'b", 'linux'))
+expect('shellQuote(POSIX) 包裹普通文本', shellQuote('ls -la', 'linux') === "'ls -la'", shellQuote('ls -la', 'linux'))
+expect("shellQuote(win32) 用双写单引号转义", shellQuote("a'b", 'win32') === "'a''b'", shellQuote("a'b", 'win32'))
+expect('shellQuote(win32) 包裹普通文本', shellQuote('ls -la', 'win32') === "'ls -la'", shellQuote('ls -la', 'win32'))
+expect('两种平台的引号**确实不同**(不能互相套用)',
+  shellQuote("a'b", 'win32') !== shellQuote("a'b", 'linux'))
+expect('shellName 说得出该开哪个终端', shellName('win32') === 'PowerShell' && shellName('linux').includes('POSIX'), shellName('linux'))
+
+// 授权行必须跟着平台走 —— 否则 Windows 用户拿到的是**语法不通**的一行(实测见下)
+const winReason = explain("rm -rf /tmp/it's", riskVerdict, { policy: 'never', token: 'ALLOW-0A2DB6157F', platform: 'win32' })
+expect('win32 平台的理由里用 PowerShell 形式', winReason.includes("'rm -rf /tmp/it''s'"), winReason.slice(winReason.indexOf('命令:') - 120, winReason.indexOf('命令:')))
+expect('win32 平台的理由里点明用 PowerShell', winReason.includes('PowerShell'))
+const posixReason = explain("rm -rf /tmp/it's", riskVerdict, { policy: 'never', token: 'ALLOW-0A2DB6157F', platform: 'linux' })
+expect('linux 平台的理由里仍用 POSIX 形式', posixReason.includes("'rm -rf /tmp/it'\\''s'"), posixReason.slice(0, 80))
+
+// 10) 引号的**真机往返**:把转义后的形式喂给真正的 shell,要求逐字节还原。
+//     本机(WSL)有 bash;若还能找到 Windows PowerShell,就顺带把 win32 那一半也验了 ——
+//     这正是"Windows 上引号是另一套语法"这件事的决定性证据。
+const backPosix = execFileSync('bash', ['-c', `printf %s ${shellQuote("a'b c", 'linux')}`], { encoding: 'utf8' })
+expect('POSIX 形式过 bash 往返还原', backPosix === "a'b c", JSON.stringify(backPosix))
+
+/**
+ * 找一个**能真正执行**的 Windows PowerShell。
+ *
+ * 候选同时覆盖两种视角,而且**用"跑一下试试"来判断可用性**,不是只看文件在不在:
+ *   · 在 Windows 上跑本文件时,`pwsh` / `powershell` 就在 PATH 上;
+ *   · 在 WSL 上跑本文件时,要走 `/mnt/c/...` 下的 .exe(互操作)。
+ * 只看 `/mnt/c/...` 会让 Windows 侧的运行**反而跳过**这条最该在 Windows 上做的断言 ——
+ * 本自检第一次在 Windows 上跑就是这样跳过的。
+ *
+ * @returns 可执行名/路径,或 undefined。
+ */
+function findWindowsPowerShell() {
+  const candidates = [
+    process.env.JEV_GUARD_PWSH,
+    'pwsh',
+    'powershell',
+    '/mnt/c/Program Files/PowerShell/7/pwsh.exe',
+    '/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe',
+  ].filter(Boolean)
+  for (const candidate of candidates) {
+    try {
+      execFileSync(candidate, ['-NoProfile', '-Command', '[Console]::Out.Write(1)'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+      return candidate
+    } catch {
+      // 试下一个
+    }
+  }
+  return undefined
+}
+
+const pwsh = findWindowsPowerShell()
+if (pwsh) {
+  const roundTrip = text => execFileSync(pwsh, ['-NoProfile', '-Command', `[Console]::Out.Write(${shellQuote(text, 'win32')})`], { encoding: 'utf8' })
+  const backWin = roundTrip("a'b c")
+  expect('PowerShell 形式过真实 PowerShell 往返还原', backWin === "a'b c", JSON.stringify(backWin))
+  // 反例:旧的 POSIX 形式在 PowerShell 里**语法都不成立** —— 这就是修复的理由
+  let posixInPwshFailed = false
+  try {
+    execFileSync(pwsh, ['-NoProfile', '-Command', `[Console]::Out.Write(${shellQuote("a'b", 'linux')})`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+  } catch {
+    posixInPwshFailed = true
+  }
+  expect('反例成立:POSIX 形式在 PowerShell 里解析失败(所以必须分叉)', posixInPwshFailed)
+} else {
+  expect('PowerShell 往返用例(本机找不到 PowerShell,跳过)', true)
+}
+
+process.stdout.write(`\n${failed === 0 ? '全部通过' : `${failed} 项失败`}(${checks} 例)\n`)
+process.exit(failed === 0 ? 0 : 1)

package/tools/selftest-rules.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * L0 规则自检:验证 `where: 'command'` 的锚定语义。
+ *
+ * 为什么单独一个文件:测试用例里必须出现危险命令的**字面量**,而把它们写进
+ * bash 命令文本会被阀门自己拦下(2026-09-20 真发生过两次)。把字面量放进文件、
+ * 用 `node tools/selftest-rules.mjs` 调用,就不会经过命令文本扫描。
+ *
+ * 2026-09-20 第二次修正后,这里同时钉住两个**方向相反**的偏差(同一个根因:锚定只做了一半):
+ *   · 假阳:命令开头型规则原来全是全文匹配 → "引号里的数据 / 注释 / 赋值 / 代码字符串"也命中。
+ *   · 漏判:锚定的 `^` 没有 `m` 标志 → 多行脚本(heredoc)与多行 `-c` 里的真命令看不见;
+ *     包装器列表也只有 sudo/env/command/nohup/time → `| xargs …`、`timeout 30 …` 全漏。
+ *   A 组防假阳,B 组防漏判,C 组防"包装器把散文也当成命令",D 组防灾难性回溯。
+ *
+ * @module jev-guard/tools/selftest-rules
+ */
+
+import { staticRule, RULE_STATS } from '../lib/rules.js'
+
+/** `[命令, 期望命中的规则 id 或不命中(null), 说明]` */
+const CASES = [
+  ['git push --force origin main', 'git-force-push', '命令位置:行首'],
+  ['cd /tmp && git push --force origin main', 'git-force-push', '命令位置:&& 之后'],
+  ['sudo git push -f origin main', 'git-force-push', '命令位置:sudo 包装'],
+  ['git push --force-with-lease origin main', null, '--force-with-lease 是安全形式,不该命中'],
+  ['echo "git push --force origin main" > /tmp/x', null, '散文:把命令当文本写进参数 → 交给 Jev'],
+  ['node tools/report-result.mjs --evidence "远端强推被拦"', null, '散文:中文描述,不该命中'],
+
+  ['rm -rf /', 'rm-root', '命令位置:行首的根目录删除'],
+  ['cd / && rm -rf /', 'rm-root', '命令位置:&& 之后'],
+  ['echo "rm -rf / 会毁掉机器" > notes.txt', null, '散文:文档里提到它 → 交给 Jev'],
+
+  ['find / -name "*.log" -delete', 'find-delete', '命令位置'],
+  ['df -h && rm -rf ~', 'rm-rf-home-root', '命令位置:&& 之后(整个家目录)'],
+  ['rm -rf ~/Photos', null, '普通子目录:规则只锚"整个家目录",这里交给 Jev 判'],
+  ['ls -la', null, '无关命令'],
+  ['df -h', null, '无关命令'],
+  // 2026-09-20 实拦案例:原先的 `>\s*[^\s|]+\s*$` 分支会把「以重定向结尾」的正常命令
+  // 误判成"把文件截断为空",例如下面这几条。现在只认显式的空写形态。
+  ['node bin/guard.mjs selftest 2>/dev/null', null, '普通重定向:不该命中'],
+  ['echo hello > /tmp/out.txt', null, '普通重定向:不该命中'],
+  ['cat log.txt > /tmp/copy.txt', null, '普通重定向:不该命中'],
+  ['echo "" > start.sh', 'truncate-file', '显式空写:命中'],
+  ['truncate -s 0 /home/user/notes.md', 'truncate-file', '显式截断:命中'],
+  ['DROP TABLE users', 'drop-database', '命令位置'],
+  ['psql -c "DROP TABLE users"', null, '藏在引号里 → 交给 Jev(实测 p 很高)'],
+  ['git reset --hard HEAD~1', 'git-reset-hard', '命令位置'],
+  ['kubectl delete namespace production', 'kubectl-delete-ns', '命令位置'],
+  ['dd if=/dev/zero of=/dev/sda bs=1M', 'block-device-write', '命令位置'],
+  ['mkfs.ext4 /dev/sdb1', 'mkfs', '命令位置'],
+
+  // ── A 组:数据位不该命中(2026-09-20 第二次修正前,这里全是假阳)────────────────
+  ['echo "mkfs.ext4 /dev/sdb1"', null, 'A 数据:双引号参数里提到 → 交给 Jev'],
+  ["printf '%s\\n' 'mkfs.ext4 /dev/sdb1'", null, 'A 数据:单引号参数'],
+  ['python3 -c "print(\'mkfs.ext4 /dev/sdb1\')"', null, 'A 数据:python -c 里的字符串'],
+  ["python3 - <<'PY'\nprint('mkfs.ext4 /dev/sdb1')\nPY", null, 'A 数据:python heredoc 里的字符串(实测假阳原形)'],
+  ['c.startswith(\'mkfs.ext4 /dev/sdb1\')', null, 'A 数据:代码里的字符串比较(实测假阳原形)'],
+  ['# mkfs.ext4 /dev/sdb1', null, 'A 数据:注释'],
+  ["X='mkfs.ext4 /dev/sdb1'", null, 'A 数据:变量赋值'],
+  ['grep -rn mkfs.ext4 /dev/sdb1 README.md', null, 'A 数据:grep 参数里提到'],
+  ['echo "dd if=/dev/zero of=/dev/sda bs=1M"', null, 'A 数据:引号里的块设备写入'],
+
+  // ── B 组:真执行必须命中,尤其是多行与包装器(这些在修正前会漏)──────────────────
+  ["bash - <<'SH'\ngit push --force origin main\nSH", 'git-force-push', 'B 真执行:多行 heredoc(缺 m 标志时漏)'],
+  ['bash -c "\ngit push --force origin main\n"', 'git-force-push', 'B 真执行:多行 bash -c'],
+  ["bash - <<'SH'\nrm -rf /\nSH", 'rm-root', 'B 真执行:多行 heredoc'],
+  ["bash - <<'SH'\nmkfs.ext4 /dev/sdb1\nSH", 'mkfs', 'B 真执行:多行 heredoc'],
+  ["psql - <<'SQL'\nDROP DATABASE prod;\nSQL", 'drop-database', 'B 真执行:多行 heredoc(缺 m 标志时漏)'],
+  ['echo x | xargs git push --force origin main', 'git-force-push', 'B 真执行:| xargs 包装'],
+  ['echo x | xargs -0 mkfs.ext4 /dev/sdb1', 'mkfs', 'B 真执行:xargs 带选项'],
+  ['timeout 30 rm -rf /', 'rm-root', 'B 真执行:timeout 包装'],
+  ['nice -n 5 git push --force origin main', 'git-force-push', 'B 真执行:nice 带选项'],
+  ['find . -type f -exec mkfs.ext4 /dev/sdb1 {} \\;', 'mkfs', 'B 真执行:find -exec'],
+  ['sudo timeout 60 xargs -0 mkfs.ext4 /dev/sdb1', 'mkfs', 'B 真执行:多级包装'],
+
+  // ── C 组:包装器吞参数只认 ASCII 词/flag/路径,中文散文不该被顺带命中 ─────────────
+  ['xargs 删除 mkfs.ext4 /dev/sdb1', null, 'C 散文:包装器后面是中文 → 交给 Jev'],
+  ['用 mkfs.ext4 /dev/sdb1 格式化会丢数据', null, 'C 散文:行首不是命令'],
+]
+
+let failed = 0
+process.stdout.write(
+  `L0 规则:deny ${RULE_STATS.deny} / ask ${RULE_STATS.ask} / 锚定到命令位置 ${RULE_STATS.anchored}`
+  + ` / 全文匹配例外 ${RULE_STATS.anywhere}(应为 2:redirect-to-device 与 fork-bomb)\n\n`,
+)
+
+for (const [command, wantId, note] of CASES) {
+  const hit = staticRule(command)
+  const gotId = hit ? hit.id : null
+  const ok = gotId === wantId
+  if (!ok) failed += 1
+  process.stdout.write(`${ok ? 'ok  ' : 'FAIL'}  ${String(gotId ?? '—').padEnd(20)} ${command.replace(/\n/g, '⏎').slice(0, 62).padEnd(62)} ${note}\n`)
+}
+
+// ── D 组:包装器允许"吞一串参数",必须保证不会灾难性回溯 ──────────────────────────
+// 4KB 的纯包装器前缀(没有规则命中)是最坏输入:正则要尝试各种切分。
+const longInput = `xargs ${'-0 a/b=c '.repeat(400)}ls -la`
+const started = performance.now()
+staticRule(longInput)
+const elapsed = performance.now() - started
+const perfOk = elapsed < 50
+if (!perfOk) failed += 1
+process.stdout.write(`\n${perfOk ? 'ok  ' : 'FAIL'}  长输入无灾难性回溯(4KB 包装器前缀,${elapsed.toFixed(1)}ms < 50ms)\n`)
+
+const total = CASES.length + 1
+process.stdout.write(failed === 0 ? `\n全部通过(${total} 例,含 1 例性能)\n` : `\n${failed} 例失败 / 共 ${total} 例\n`)
+process.exit(failed === 0 ? 0 : 1)

package/tools/selftest-token.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * 一次性放行令牌自检:绑定命令、一次性、不越过 L0、与 gate 的接线。
+ *
+ * 全部在临时目录里做(显式 tokenPath),不碰 ~/.jev-guard。
+ *
+ * @module jev-guard/tools/selftest-token
+ */
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { evaluateCommand } from '../lib/gate.js'
+import { explain } from '../lib/verdict.js'
+import { canonicalize, commandToken, consumeToken, grantToken, readTokens, resolveTokenPath, revokeToken } from '../lib/token.js'
+
+let failed = 0
+let checks = 0
+
+/**
+ * @param label - 用例名。
+ * @param ok - 断言结果。
+ * @param detail - 失败细节。
+ */
+function expect(label, ok, detail = '') {
+  checks += 1
+  if (!ok) failed += 1
+  process.stdout.write(`${ok ? 'ok  ' : 'FAIL'}  ${label}${ok ? '' : `   ${detail}`}\n`)
+}
+
+const dir = await mkdtemp(join(tmpdir(), 'jev-guard-token-'))
+const tokenPath = join(dir, 'allow.txt')
+
+const CMD = 'rm -f /home/user/notes.md'
+const OTHER = 'rm -f /home/user/other.md'
+
+// 1) 令牌与命令绑定
+expect('同一命令得到同一令牌', commandToken(CMD) === commandToken(CMD))
+expect('空白差异不影响令牌', commandToken('rm  -f   /x') === commandToken('rm -f /x'))
+expect('不同命令令牌不同', commandToken(CMD) !== commandToken(OTHER))
+expect('令牌形态正确', /^ALLOW-[0-9A-F]{10}$/.test(commandToken(CMD)), commandToken(CMD))
+expect('规范化折叠空白', canonicalize(' a \n  b ') === 'a b')
+
+// 2) 路径解析:空串回落默认(与 audit 同一教训)
+expect('空 tokenPath → 默认路径', resolveTokenPath({ tokenPath: '' }).endsWith('allow.txt'))
+expect('显式 tokenPath 生效', resolveTokenPath({ tokenPath }) === tokenPath)
+
+// 3) 写令牌 → 消费一次 → 第二次失败
+await grantToken(CMD, { tokenPath, note: '自检' })
+expect('令牌已写入', (await readTokens(tokenPath)).includes(commandToken(CMD)))
+const first = await consumeToken(CMD, { tokenPath })
+expect('第一次消费成功', first.ok === true)
+const second = await consumeToken(CMD, { tokenPath })
+expect('第二次消费失败(一次性)', second.ok === false)
+expect('消费后文件里已无该令牌', !(await readTokens(tokenPath)).includes(commandToken(CMD)))
+const persisted = await readFile(tokenPath, 'utf8')
+expect('文件里留有注释便于人工核对', persisted.includes('#') || persisted === '')
+
+// 4) 撤销
+await grantToken(CMD, { tokenPath })
+const revoked = await revokeToken(commandToken(CMD), { tokenPath })
+expect('撤销成功', revoked.removed === 1)
+expect('撤销后无令牌', (await readTokens(tokenPath)).length === 0)
+
+// 5) 与 gate 接线:L0 硬规则不受令牌影响;可放行的判定可被令牌放行
+const cfg = { apiKey: process.env.TYPESAFE_API_KEY, tokenPath, tokens: true }
+
+const l0 = await evaluateCommand('mkfs.ext4 /dev/sdb1', cfg)
+expect('L0 deny 仍然拦截(令牌不越过硬地板)', l0.action === 'block' && l0.source === 'static-rule')
+await grantToken('mkfs.ext4 /dev/sdb1', { tokenPath })
+const l0After = await evaluateCommand('mkfs.ext4 /dev/sdb1', cfg)
+expect('即使给了令牌,L0 deny 依旧拦截', l0After.action === 'block', `实得 ${l0After.action}/${l0After.source}`)
+// L0 deny 连"令牌提示"都不该出现在理由里 —— 给了也放行不了,别误导调用方。
+const l0Reason = explain('mkfs.ext4 /dev/sdb1', l0After, { policy: 'never', token: l0After.token })
+expect('L0 deny 的理由里不出现令牌提示', !l0Reason.includes('ALLOW-'), l0Reason.slice(0, 120))
+
+if (process.env.TYPESAFE_API_KEY) {
+  // 需要联网的路径:确保同一条命令先被判为 revise/block,再凭令牌放行
+  const offline = { ...cfg, timeoutMs: 5000 }
+  const probe = 'rm -rf /home/user/jev-guard-token-probe-dir'
+  const judged = await evaluateCommand(probe, offline)
+  if (judged.action !== 'allow') {
+    await grantToken(probe, { tokenPath })
+    const withToken = await evaluateCommand(probe, offline)
+    expect('令牌把 revise/block 改成放行', withToken.action === 'allow' && withToken.source === 'token',
+      `判定=${judged.action} 实得=${withToken.action}/${withToken.source}`)
+    expect('放行记录里带被覆盖的原动作', withToken.overridden === judged.action, String(withToken.overridden))
+    const replay = await evaluateCommand(probe, offline)
+    expect('令牌用掉后不能重放', replay.action !== 'allow' || replay.source !== 'token',
+      `实得 ${replay.action}/${replay.source}`)
+  } else {
+    process.stdout.write(`note  探针命令被判为 allow(p=${judged.p}),跳过"令牌覆盖判定"用例\n`)
+  }
+} else {
+  process.stdout.write('note  没有 TYPESAFE_API_KEY,跳过联网用例\n')
+}
+
+await rm(dir, { recursive: true, force: true })
+process.stdout.write(failed === 0 ? `\n全部通过(${checks} 例)\n` : `\n${failed} 例失败 / 共 ${checks} 例\n`)
+process.exit(failed === 0 ? 0 : 1)