dsh-perm-gate 5.1.0 → 5.1.2-compat.15

package/CHANGELOG.md

@@ -9,6 +9,102 @@ undefined
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.1.2-compat.15] - 2026-10-12
+
+### Changed
+
+- **提示文字跟随 UI 语言切换（通知条 + 审批记录）**：上一版把服务器生成的英文 `humanBrief` 原文存进事件，
+  回看时不管 UI 是什么语言都显示英文。现客户端改从事件的 `doubtKinds`（机器键，早已落盘）经 `t('doubt.xxx')`
+  渲染——`locales.ts` 新增 10 条 `doubt.*` × 9 语，通知条与审批记录列表两处渲染点本地化；
+  旧事件无 `doubtKinds` 时回退 `humanBrief ?? justification ?? reason`。弹窗那半（宿主 `.headline` 取 `displayReason.{zh,en}`）不变。
+
+## [5.1.2-compat.14] - 2026-10-12
+
+### Changed
+
+- **命令不再夹在文案里**。宿主审批面板的排版是固定的：`.headline`（放 `displayReason`，一个普通 div，**不保留换行**）
+  + `.command`（等宽代码块，由 ui-chat 注册的 `conversation.approval.detail` 填充）。
+  上一版把命令塞进 `displayReason` 的“影响面”一句，结果换行被吞掉、命令埋在句子中间读不出来。
+  现 `humanBrief()` 只输出三段文案（疑点 / 影响面 / 代价），命令走它自己的通道：
+  弹窗交给宿主的代码块，审批记录则落在新的事件字段 `humanCommand`（脱敏、上限 400 字），
+  面板用等宽 + `white-space: pre-wrap` 单独成块渲染。
+
+## [5.1.2-compat.13] - 2026-10-11
+
+### Added
+
+- **弹窗不再只给内部代号**：`humanBrief()` 把一次 ask 翻成三段人话——**疑点**（为什么没结论：无规则覆盖 / 载荷读不懂 / 规则判不可逆 / 模型只能升级不能放行）、**影响面**（目标类型 + 可逆性 + 看到哪些文件 + 脱敏命令）、**两个按钮各花什么钱**（按 R/C/I/U 分档，I 档写明“无法撤回”）。
+  进 `displayReason: { zh, en }`，宿主按 UI 语言取，其余七语回退 `en`；审计 `reason` 保持英文短标签不变。
+- **审批记录可回溯**：同一份 brief 随人工终态事件落盘（`humanBrief` + `doubtKinds`），面板优先渲染它。之前弹窗里的解释只存在几秒钟，回看时只剩 `no rule matched; default action`。
+
+### Fixed
+
+- **只读命令被标成 `target=write`**：只读判定是“读动词 + 全局无管道”，于是 `Get-ChildItem -Force | Select-Object Name`（PowerShell 会话里最常见的形状）在卡片上被说成会写。现逐段判定：首段是读动词、后面全是重排过滤器（`Select-Object`/`Where-Object`/`Out-String`/`Format-Table` …）、且无重定向，才算只读；管道进写入器/网络工具/`Stop-Process` 仍不算。
+- **工具名白名单是个绕过面**：P0 与规则链都靠 `SHELL_TOOLS` 认“这是不是一条命令”，而模型已经会打出 `pash` 这种名字（实测日志可见）——不认识的 runner 带着 `diskpart /s x.txt` 就跳过了所有命令级检查。现按**形状**判定（参数里有 `command`/`cmd`/`script` 串），并保留已知非执行器（`read`/`write`/内部工具）的例外，否则一份引用了命令的文档会被当成执行了它。
+  名单本身（`READ_TOOLS`/`INTERNAL_TOOLS`/`WRITE_TOOLS`/`SHELL_TOOLS`）集中到 `src/tool-names.ts`，之前“这是一条被执行的命令吗”在代码里有两个答案。
+
+### Known gap
+
+- 面板端的 `doubtKinds` 目前直接显示英文 brief（审计语言）；按 9 语渲染疑点文案需给 `locales.ts` 补 10 个键 × 9 语，已记为后续页。
+
+## [5.1.2-compat.12] - 2026-10-11
+
+### Fixed
+
+- **`reg delete` 只匹配了 hive 根，没匹配真实在用的子键形**：`REGISTRY_DESTROY` 在 `system` 后留了个 `\b`，
+  而解析器已把 `HKLM\SYSTEM\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy` 剥成 `HKLMSYSTEMCurrentControlSet…`——
+  于是**所有带子键的删除全部绕过 P0**（只落到 ask），而无人在跑的裸 hive 根反而被拦。
+  现去掉尾部边界；新预例：`reg delete HKLM\SYSTEM\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy /f`、
+  `reg delete "HKLM\SYSTEM\MountedSoftware" /f` 均为 deny；
+  `reg delete HKCU\Software\…`、`reg delete HKLM\SOFTWARE\…`（非 hive）仍放行。
+  发现的途径：给真宿主组装可粘贴测试集时，把每一行先过一遍已装副本的 dry-run（`scripts/gate-dryrun-check.mjs`），29 行里就它一条 DIFF。
+
+## [5.1.2-compat.11] - 2026-10-11
+
+### Added
+
+- **`src/redact.ts`**：有界且幂等的脱敏原语（`[redacted:<len>:<kind>]`、文档体→字节数+哈希）。此前 `classifier.ts` 声称“密钥已在上游剥离”，实际并未剥离 —— grader 载荷是整包 args 原文外送第三方端点的。
+- **`src/ask-context.ts`**：一次构造、三个投影（grader 载荷 / 人侧卡片 / 事件归因）。档位三字段（preset/sandbox/approval）只进弹窗与事件流，**绝不进 grader prompt**（实测喂给模型会让它顺着规则层答而不是自己判，打扰 67.1%→87.8%）。
+- **`src/irreversible.ts`**：不可逆性的单一真源，分三层 —— P0 deny / never-clear ask（模型不能洗白、确认不能沉淀）/ 可学习 ask。所有函数只返回 `string | undefined`，结构上无法产生 allow。
+- **`src/command-normalize.ts`**：base64（UTF-16LE/UTF-8 双读）/hex/变量展开的旁路解码，四条护栏：不回写、限长限深限变体、超预算丢弃部分成果、自家 `--exec-b64` wrapper 认出但不豁免解码。
+- **`src/grader-rules.ts`**：classifier 与 risk 共享的唯一判据真源（分开成文件以避开 ESM 循环引用）；`classifyWithLLM` 标 `@deprecated`，其 deny 永不进决策路径。
+- 弹窗 `displayReason`（宿主正式字段，不进审计）：为何在问 / 脱敏命令 / 文件清单+真实总数 / `tier=target=payload=opaque never-learn` 标 / 两个按钮的代价。
+- `PENDING_CAP` FIFO 淘汰可观测：`evictions` 计数 + 事件告警 + `pendingAskStats()`。
+
+### Changed
+
+- `unknown-target` 成为 risk 协议的**硬类目**（永不 auto-allow、永不学习），且刻意不进任何 deny 词表：“看不见”不是“确定坏”。
+- 判定层按程序名位置匹配，不做自由文本词匹配；`unresolved` 用 `verdict` 标签区分（不新增 `kind`，因为 `presentation()` 的 default 分支会把未知 kind 渲染成绿色 ALLOW）。
+- 提示词版本化：`v7-terse-budget`。延迟门槛按服务端 `timings.prompt_ms` 量（墙钟在共享端点上会被排队淹没）：v5 +36.0ms → v6 +1.9ms → v7 −0.1ms 且 token 持平 714。
+
+### Fixed
+
+- `decomposeShellCommand` 会剥掉裸参数里的反斜杠，导致所有要求 `\` 分隔符的 Windows 规则（`HKLM\SYSTEM`、`C:\Windows\System32`）在主判定路径上默默落空 —— 现同时匹配“去分隔符”形态（要求驱动号前缀，避免把仓内目录名当系统根）。
+- 同一解析器不拆 `;` 链且剥引号，致使 `Select-String -Pattern "vssadmin|cipher|diskpart"` 被当成执行 `diskpart` 并不可申诉地拒绝 —— 现改用解析器给出的权威程序名、仅在 arg 边界取链、分段器改为引号感知；链式 wipe 覆盖不回退。
+- `containsCredentialMaterial` 对参数里任意 `Bearer <token>` 与只读探测（`Test-Path ~/.ssh/id_rsa`）直接 P0 硬拒 —— 两条都是误拦（正当编码反例集 1/20 → 0/20），且带密钥的命令根本到不了弹窗；同一物料一旦移动（`scp`/`Copy-Item`/管道入 `curl`）仍拒。
+- 流水拆段使“密件 + 外发通道”分属两段、per-command deny 看不到成对关系 —— 现由整调用视图的 `tier=I` 否决兑住（只否决模型，不产生 deny）。
+- `dsh.plugin.json` 版本号与 `package.json` 差一个发布号（宿主读的是前者）。
+- `client-settings-seat` 测试仍断言 compat.10 已退役的 `shell.overlay` 席位（基线红），现跟随退役决定修正。
+
+## [5.1.2-compat.10] - 2026-10-08
+
+### Removed
+
+- 退役 `shell.overlay` 悬浮齿轮：设置面在所有宿主线上都由 `settings.section` 渲染（+ bridge describe/mutate），固定角落的齿轮全机冗余。
+
+## [5.1.2-compat.9] - 2026-10-08
+
+### Changed
+
+- **回退家族 tab 收拢（用户定案：自动审查门不在 tab 化范围内）**：顶级
+  `settings.section`（侧栏「自动审查门」独立节，order 30）恢复为唯一设置导航
+  入口；同日上午加入的 `dsh-family.tab`（order 45）撤除。
+- `settings.plugins.tab`（插件页 tab，0.1.0 实测与独立节双渲染）与
+  `settings.plugin.item`（≤0.1.5 派发卡）维持退役——与独立节重复；
+  `plugins.bundle.config` 详情卡与 `shell.overlay` 浮窗齿轮不变。
+- 席位契约测试（test/client-settings-seat.spec.ts）改钉单节形态：
+  settings.section 恰一次（order 30 / PermissiveCard），三个退役席位断言缺席。
+
 ## [2.6.0] - 2026-09-17
 
 ### Added

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-perm-gate",
   "name": "dsh-perm-gate",
-  "version": "5.1.0",
+  "version": "5.1.2-compat.15",
   "description": {
     "en": "Deterministic-first, fail-closed permission gate for DeepSeek Harness 0.1.2+: a P0 hard-deny -> P1 precise session grant -> P2 static allow/deny rule chain -> P3 optional LLM classifier -> P4 ask pipeline over the tools/pre-execute waterfall, with a standalone CLI dry-run evaluator and an auditable decision log. It only vetoes with deny/ask and always delegates otherwise, and unknown or malformed rules fail loud instead of silently standing the gate down.",
     "zh": "面向 DeepSeek Harness 0.1.2+ 的确定性优先、失败即拒的权限闸门：在 tools/pre-execute 瀑布上串起 P0 硬拒绝 → P1 精确会话授权 → P2 静态 allow/deny 规则链 → P3 可选 LLM 语义分类 → P4 ask，并附带独立 CLI 干跑评估器与可审计的决策日志。只以 deny/ask 否决、其余一律放行，规则未知或非法时直接报错，绝不静默失效。"

package/lib/ask-context.d.ts

@@ -0,0 +1,207 @@
+/** Reversibility tier — the axis the human and the safety metric both care about. */
+export type Reversibility = 
+/** irreversible damage (data destroyed, credential left the machine) */
+'I'
+/** unknown-target: the payload cannot be inspected, so harm cannot be ruled out */
+ | 'U'
+/** has an external side effect but is recoverable (push, PR, global config) */
+ | 'C'
+/** reversible or read-only (list, diff, build, local commit, workspace edit) */
+ | 'R';
+/** What the call is aimed at. */
+export type TargetKind = 'read' | 'write' | 'delete' | 'remote-write' | 'exec-external' | 'unknown';
+/** The session's three tier knobs, folded out of the durable session log. */
+export interface SessionKnobs {
+    readonly permissionPreset?: string;
+    readonly sandboxMode?: string;
+    readonly approvalPolicy?: string;
+}
+/** Input to {@link buildAskContext}; every field optional except `tool`. */
+export interface AskContextSource {
+    readonly tool: string;
+    readonly args?: Record<string, unknown>;
+    readonly commandText?: string;
+    readonly cwd?: string;
+    /** The workspace root the prompt's scope rules keep assuming but never had. */
+    readonly workspaceRoot?: string;
+    readonly knobs?: SessionKnobs;
+    readonly files?: readonly string[];
+    /** The deterministic layer's own conclusion, kept for the human, not the grader. */
+    readonly ruleReason?: string;
+    /** Correlation key, mixed into the event digest. */
+    readonly callId?: string;
+    /** Per-session salt so `inputDigest` cannot be dictionary-reversed or joined across sessions. */
+    readonly salt?: string;
+    /** Injected hash (sha256 hex on the node half) to keep crypto out of this module. */
+    readonly hash?: (text: string) => string;
+}
+/** The frozen context. */
+export interface AskContext extends AskContextSource {
+    readonly targetKind: TargetKind;
+    readonly targetResolvable: boolean;
+    readonly reversibility: Reversibility;
+    /** Whether the act is unrecoverable, judged by the shared `irreversible.ts`. */
+    readonly irreversible: boolean;
+    /**
+     * Unrecoverable data loss that is nonetheless **not** a hard-deny: the human
+     * decides, but no grader may clear it and no confirmations may learn it away.
+     * `docker volume rm` is the archetype — routine maintenance, unrecoverable.
+     */
+    readonly unlearnable: boolean;
+    /** Read-only commands that need no human attention at all. */
+    readonly readOnly: boolean;
+}
+/**
+ * Freeze one call into an {@link AskContext}. Pure and side-effect free: it reads
+ * what it is handed and never touches the filesystem or the network, so the three
+ * projections cannot disagree about what they were built from.
+ */
+export declare function buildAskContext(source: AskContextSource): AskContext;
+/** What the risk grader is allowed to see. */
+export interface GraderPayload {
+    readonly tool: string;
+    readonly args: unknown;
+    readonly reason: string;
+    readonly target_resolvable: boolean;
+    readonly workspace_root?: string;
+}
+/**
+ * Project for egress to the grader. Tier knobs and the rule layer's own verdict
+ * are stripped by design — see the module comment.
+ */
+export declare function toGraderPayload(ctx: AskContext): GraderPayload;
+/** What the human approving this call should be shown. */
+export interface HumanCard {
+    readonly tool: string;
+    readonly command: string;
+    readonly files: readonly string[];
+    /** Total file count, so the card can say "and N more" instead of lying by omission. */
+    readonly fileCount: number;
+    readonly reversibility: Reversibility;
+    readonly targetKind: TargetKind;
+    readonly permissionPreset?: string;
+    readonly sandboxMode?: string;
+    readonly approvalPolicy?: string;
+    readonly reason: string;
+}
+/** Project for the approval popup (already redacted; never raw args). */
+export declare function toHumanCard(ctx: AskContext, maxFiles?: number): HumanCard;
+/**
+ * A one-line summary for the human who must decide.
+ *
+ * The host renders an approval request from its `reason` string and nothing
+ * else, so until `approval.request` can carry structured fields this is the only
+ * channel that reaches a human. Built from language-neutral enum tokens
+ * (`tier=C`, `payload=opaque`) rather than prose: prose would need nine
+ * translations per batch, and a host renderer can localize the tokens later
+ * without a format change.
+ */
+export declare function humanCardLine(ctx: AskContext, maxFiles?: number): string;
+/**
+ * Why this call has no answer yet, in words a person who does not know this
+ * codebase can read. The tokens (`tier=C target=write`) were never a decision aid:
+ * they name the gate's internals, not the user's exposure, and a mislabelled one
+ * (`target=write` on a directory listing) teaches people to stop reading the card.
+ *
+ * Keys are stable machine identifiers so the client panel can localize them later;
+ * the popup gets `zh`/`en` text because the host resolves `displayReason` by UI
+ * locale and falls back to `en` for the other seven languages.
+ */
+export declare const DOUBT_COPY: {
+    readonly 'no-rule': {
+        readonly zh: "没有规则覆盖这次调用，按默认策略交给人 — 这不表示它危险";
+        readonly en: "no rule covers this call, so the default is to ask — that does not mean it is dangerous";
+    };
+    readonly opaque: {
+        readonly zh: "命令载荷读不懂（编码过 / 工作区外的脚本 / 认不出程序名），规则层无法定位目标";
+        readonly en: "the payload cannot be read (encoded, a script outside the workspace, or no recognisable program), so no rule can locate its target";
+    };
+    readonly irreversible: {
+        readonly zh: "规则判定不可逆：跑完无法撤回";
+        readonly en: "a rule says this is irreversible: it cannot be undone once run";
+    };
+    readonly 'never-learn': {
+        readonly zh: "这类确认不会沉淀，下次同样的操作还会再问";
+        readonly en: "this answer will not be learned; the same call will ask again next time";
+    };
+    readonly delete: {
+        readonly zh: "会删除内容";
+        readonly en: "it deletes content";
+    };
+    readonly 'remote-write': {
+        readonly zh: "会产生对外可见的副作用（推送 / 发布 / 写请求），撤回需要额外手动操作";
+        readonly en: "it has an externally visible effect (push / publish / write request); undoing it takes extra manual steps";
+    };
+    readonly 'exec-external': {
+        readonly zh: "会执行工作区之外的代码，本次调用无法静态看清它做什么";
+        readonly en: "it runs code from outside the workspace, which this call cannot inspect";
+    };
+    readonly 'outside-paths': {
+        readonly zh: "涉及工作区之外的路径";
+        readonly en: "it touches paths outside the workspace";
+    };
+    readonly 'model-flagged': {
+        readonly zh: "风险模型认为可疑（它只能升级，不能放行）";
+        readonly en: "the risk model flagged it (it can only escalate, never clear)";
+    };
+    readonly write: {
+        readonly zh: "会写入或修改文件";
+        readonly en: "it writes or modifies files";
+    };
+};
+export type DoubtKind = keyof typeof DOUBT_COPY;
+/**
+ * The machine keys behind "why am I being asked". Derived, never passed in: the
+ * caller cannot forget to add a doubt, and a doubt cannot contradict the facts.
+ */
+export declare function askDoubtKinds(ctx: AskContext, extra?: {
+    readonly modelFlagged?: boolean;
+}): DoubtKind[];
+/**
+ * The card a human decides from, as three prose clauses with **no command in them**.
+ *
+ * The command does not belong here. The host's approval panel renders the pending
+ * tool call's command in its own monospace block (ui-chat registers
+ * `conversation.approval.detail` → `ApprovalCommand`, styled `.command`), while the
+ * resolved `displayReason` goes into `.headline`, a plain div with no
+ * `white-space: pre-line` — so any `\n` in it collapses and a command embedded in
+ * prose ends up buried mid-sentence. Keeping the two in their own channels is what
+ * makes the popup readable.
+ *
+ * The event still carries the command separately (`humanCommand`) because the
+ * review list has no host-provided command block next to it.
+ */
+export declare function humanBrief(ctx: AskContext, lang: 'zh' | 'en', kinds?: ("write" | "delete" | "remote-write" | "exec-external" | "never-learn" | "no-rule" | "opaque" | "irreversible" | "outside-paths" | "model-flagged")[]): string;
+/** The redacted command alone, for the channels that have nowhere else to show it. */
+export declare function humanCommand(ctx: AskContext): string;
+/** What goes on the durable event, for later attribution. */
+export interface EventFields {
+    readonly inputDigest?: string;
+    readonly cwd?: string;
+    readonly permissionPreset?: string;
+    readonly sandboxMode?: string;
+    readonly approvalPolicy?: string;
+    /** The machine keys of "why it asked", so the panel can localize them. */
+    readonly doubtKinds?: readonly DoubtKind[];
+    /** The English form of the card the human decided from (audit language). */
+    readonly humanBrief?: string;
+    /** The redacted command on its own, so the review list can show it as code. */
+    readonly humanCommand?: string;
+}
+/**
+ * Project for the event log: a salted digest (raw args never land on disk) plus
+ * the knobs, so a reviewer can reconstruct *why* the gate saw what it saw.
+ * Emits no digest when no hash is injected rather than falling back to an
+ * unsalted one — that would be dictionary-reversible across sessions.
+ */
+export declare function toEventFields(ctx: AskContext): EventFields;
+/**
+ * Fold the three durable tier knobs out of a session event log (last wins).
+ * `preset.ts` folds only `permission/preset`; the other two ride the same log.
+ * Tolerant of every host line: an unknown shape yields `undefined`, never a
+ * wrong value.
+ */
+export declare function foldSessionKnobs(events: readonly {
+    type?: string;
+    data?: Record<string, unknown>;
+}[] | undefined): SessionKnobs;