@goodandready/dsh-approval-gate 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.10
+
+- Policy: точное определение сессионной политики апрува в `readKnobs` через `approval.effectivePolicy(session)`, историю событий `session.eventAt` и пресет `danger-full-access` (Refs: #140).
+- Execution: корректный пропуск некритичных команд в режиме «Полный доступ» (`never`) без ложного поднятия `ask` и автоматического отказа DSH `Error: the user rejected tool` (Refs: #140).
+- Observability: форматирование `sessionTag` с получением строкового идентификатора сессии `session.id` / `session.name` вместо `[object Object]` (Refs: #140).
+
+## 0.1.9
+
+- Inspect: декомпозиция `lib/inspect.js` с выносом `checkEnvExfiltration` в `lib/inspect-env.js`, строгое соблюдение порога 600 строк (Refs: #35).
+- Security: автоматическое маскирование и redaction чувствительных данных, токенов и паролей в сетевых URL и аудиторских логах `redactUrl` и `redactCredentials` (Refs: #42).
+- Paths: интеграция `resolveSafePath` как основного примитива безопасности файловых путей и защита от symlink и path traversal обходов (Refs: #94, #137).
+- Engine: интеграция 5-уровневого каскада принятия решений `SecurityEngine` (P0 Hard-Deny -> P1 Grants -> P2 Static -> P3 LLM -> P4 Ask) в хук `tools/pre-execute` и рантайм-гард `tools.guard` (Refs: #122).
+- Messages: расширенная мультиязычная локализация причин блокировки (ru, en, zh) с контекстными подсказками безопасных альтернатив `hintPrefix` и `ruleHints` (Refs: #131).
+- Sync: автоматический тест контроля паритета рантайм-файлов и синхронизация метаданных публичных релизов (Refs: #138).
+
 ## 0.1.8
 
 - Paths: нормализация разделителей путей `normalizeSeparators` для кроссплатформенной обработки Windows (`\`) и POSIX (`/`) слешей (Refs: #109).

package/README.md

@@ -57,10 +57,18 @@ graph LR
 
 | Module | Responsibility |
 |---|---|
-| lib/index.js | Registers the monotonic tools.guard and pre-execution approval hook; wires the shell and file-write inspectors into DSH. |
+| lib/index.js | Registers the monotonic tools.guard and pre-execution approval hook; wires SecurityEngine into DSH. |
+| lib/engine.js | Coordinates the 5-tier decision cascade (P0 Hard-Deny, P1 Grants, P2 Static, P3 LLM, P4 Ask). |
+| lib/bands.js | Fast two-band prefilter for critical hard-denials (Band 0) and zero-overhead safe inspections (Band 1). |
+| lib/breaker.js | Session circuit breaker protecting against infinite agent retry loops upon security denials. |
+| lib/grants.js | Temporary scoped session grant store with TTL and usage limits. |
+| lib/canonical.js | Canonical serialization and hashing of tool execution calls. |
+| lib/paths.js | Path normalization, home expansion, and symlink/traversal boundary verification via resolveSafePath. |
 | lib/tokenizer.js | Tokenizes bounded Bash syntax, tracks operators/heredocs, and extracts parameter/command substitutions. |
 | lib/inspect.js | Evaluates safety rules, inspects command argv and expansions, and returns pass, deny, or ask decisions. |
-| lib/messages.js | Provides English, Simplified Chinese, and Russian rule names, explanations, and formatted messages. |
+| lib/inspect-env.js | Inspects and prevents environment exfiltration, procfs reads, and secret dumping. |
+| lib/redact.js | Masks sensitive credentials, authorization headers, and query tokens in audit messages and URLs. |
+| lib/messages.js | Provides English, Simplified Chinese, and Russian rule names, contextual hints, and formatted messages. |
 | cordis.patch.yml | Declares the host-side plugin bundle and optional tool configuration. |
 
 The guard runs before the tool body. A recognized dangerous action is denied even if a prompt could otherwise be shown. Uncertain syntax or targets are sent to DSH approval; DSH policy still decides whether a prompt is available.

package/lib/engine.js

@@ -35,7 +35,7 @@ export class SecurityEngine {
    *
    * @param {{ name: string, arguments?: any }} execution - Tool call
    * @param {{ sessionId?: string, knobs?: any }} [context] - Context options
-   * @returns {{ verdict: "allow" | "deny" | "ask", stage: "P0" | "P1" | "P2" | "P3" | "P4", reason: string, detail?: string }}
+   * @returns {{ verdict: "allow" | "deny" | "ask", stage: "P0" | "P1" | "P2" | "P3" | "P4", reason: string, detail?: string, hit?: any }}
    */
   decide(execution, context = {}) {
     const sessionId = context.sessionId || "default";
@@ -46,14 +46,15 @@ export class SecurityEngine {
     const bandVerdict = this.bands.evaluate(toolName, command);
     if (bandVerdict === "deny") {
       this.breaker.countDeny(sessionId);
-      return { verdict: "deny", stage: "P0", reason: "band-hard-deny", detail: command };
+      const hit = { deny: true, reason: "band-hard-deny", detail: command, snippet: command };
+      return { verdict: "deny", stage: "P0", reason: "band-hard-deny", detail: command, hit };
     }
 
     // Inspect execution for hard denials and syntax checks
     const hit = inspectExecution(execution, this.inspectConfig);
     if (hit.deny) {
       this.breaker.countDeny(sessionId);
-      return { verdict: "deny", stage: "P0", reason: hit.reason || "hard-deny", detail: hit.detail || hit.snippet };
+      return { verdict: "deny", stage: "P0", reason: hit.reason || "hard-deny", detail: hit.detail || hit.snippet, hit };
     }
 
     // P1: Session Grants
@@ -61,24 +62,36 @@ export class SecurityEngine {
       const grantMatch = this.grantRegistry.decide(toolName, execution.arguments, context);
       if (grantMatch === "allow") {
         this.breaker.resetConsecutive(sessionId);
-        return { verdict: "allow", stage: "P1", reason: "session-grant" };
+        return { verdict: "allow", stage: "P1", reason: "session-grant", hit };
       }
     }
 
     // If Circuit Breaker is tripped, suspend auto-mode and force P4 Human Ask
     if (this.breaker.isTripped(sessionId)) {
+      const breakerHit = {
+        ask: true,
+        reason: "circuit-breaker-tripped",
+        detail: "Circuit breaker tripped due to repeated security denials. Manual confirmation required.",
+        snippet: command || toolName,
+      };
       return {
         verdict: "ask",
         stage: "P4",
         reason: "circuit-breaker-tripped",
-        detail: "Circuit breaker tripped due to repeated security denials. Manual confirmation required."
+        detail: breakerHit.detail,
+        hit: breakerHit,
       };
     }
 
+    // P4: Human Ask if syntax is unparseable or uncertain
+    if (hit.ask) {
+      return { verdict: "ask", stage: "P4", reason: hit.reason || "uncertain-syntax", detail: hit.detail || hit.snippet, hit };
+    }
+
     // P2: Static Rules / Safe Allow
     if (bandVerdict === "allow") {
       this.breaker.resetConsecutive(sessionId);
-      return { verdict: "allow", stage: "P2", reason: "safe-allow" };
+      return { verdict: "allow", stage: "P2", reason: "safe-allow", hit };
     }
 
     // P3: Optional Semantic Classifier
@@ -87,24 +100,19 @@ export class SecurityEngine {
         const cls = this.classifier(execution, context);
         if (cls && cls.verdict === "allow") {
           this.breaker.resetConsecutive(sessionId);
-          return { verdict: "allow", stage: "P3", reason: cls.reason || "classifier-allow" };
+          return { verdict: "allow", stage: "P3", reason: cls.reason || "classifier-allow", hit };
         }
         if (cls && cls.verdict === "deny") {
           this.breaker.countDeny(sessionId);
-          return { verdict: "deny", stage: "P3", reason: cls.reason || "classifier-deny" };
+          const clsHit = { deny: true, reason: cls.reason || "classifier-deny", snippet: command || toolName };
+          return { verdict: "deny", stage: "P3", reason: cls.reason || "classifier-deny", detail: cls.reason, hit: clsHit };
         }
       } catch (err) {
         // Classifier error fails closed to P4 Ask
       }
     }
 
-    // P4: Human Ask (uncertain syntax or unlisted command)
-    if (hit.ask) {
-      return { verdict: "ask", stage: "P4", reason: hit.reason || "uncertain-syntax", detail: hit.detail || hit.snippet };
-    }
-
     // Safe default for unclassified commands
-    return { verdict: "allow", stage: "P2", reason: "unmatched-allow" };
+    return { verdict: "allow", stage: "P2", reason: "unmatched-allow", hit };
   }
 }
-

package/lib/index.js

@@ -1,3 +1,4 @@
+import { SecurityEngine } from "./engine.js";
 // dsh-approval-gate - approval gate for DeepSeek Harness.
 //
 // Registers tools.guard on the tool runtime and denies dangerous bash
@@ -43,8 +44,15 @@ export function isUnattended(knobs) {
   return policies.includes(policy);
 }
 
-/** Effective permission knobs, as the harness exposes them. */
-function readKnobs(ctx) {
+/**
+ * Effective permission knobs, as the harness exposes them.
+ * Resolves session-level approval policy if an active execution carrying a session is provided.
+ *
+ * @param {any} ctx - Cordis context
+ * @param {any} [execution] - Optional tool execution carrying agent/session
+ * @returns {{ policy: string, sandbox: string }}
+ */
+export function readKnobs(ctx, execution) {
   const read = (name) => {
     try {
       return ctx && typeof ctx.get === "function" ? ctx.get(name) : undefined;
@@ -54,8 +62,84 @@ function readKnobs(ctx) {
   };
   const approval = read("approval");
   const shell = read("shell");
+
+  const agent = execution && execution.agent;
+  const session = agent && (agent.session || (typeof agent === "object" && typeof agent.eventAt === "function" ? agent : undefined));
+
+  let policy = "";
+
+  // 1. Live approval service effectivePolicy(session)
+  if (approval && session && typeof approval.effectivePolicy === "function") {
+    try {
+      policy = approval.effectivePolicy(session) || "";
+    } catch {
+      // ignore
+    }
+  }
+
+  // 2. Direct session property fallback
+  if (!policy && session && typeof session.approvalPolicy === "string") {
+    policy = session.approvalPolicy;
+  }
+
+  // 3. Fallback: inspect session events backwards for approval/policy
+  if (!policy && session && typeof session.eventAt === "function" && typeof session.seq === "number") {
+    try {
+      for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+        const event = session.eventAt(seq);
+        if (event && event.type === "approval/policy" && event.data && event.data.policy) {
+          policy = event.data.policy;
+          break;
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // 4. Fallback: inspect session events for permission/preset === 'danger-full-access'
+  if (!policy && session && typeof session.eventAt === "function" && typeof session.seq === "number") {
+    try {
+      for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+        const event = session.eventAt(seq);
+        if (event && event.type === "permission/preset" && event.data && event.data.preset) {
+          if (event.data.preset === "danger-full-access") {
+            policy = "never";
+          }
+          break;
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // 5. In-memory session.events array fallback (common in mocks / tests)
+  if (!policy && session && Array.isArray(session.events)) {
+    try {
+      for (let i = session.events.length - 1; i >= 0; i -= 1) {
+        const event = session.events[i];
+        if (event && event.type === "approval/policy" && event.data && event.data.policy) {
+          policy = event.data.policy;
+          break;
+        }
+        if (event && event.type === "permission/preset" && event.data && event.data.preset === "danger-full-access") {
+          policy = "never";
+          break;
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // 6. Global static fallback from approval service config
+  if (!policy && approval && approval.config && approval.config.policy) {
+    policy = approval.config.policy;
+  }
+
   return {
-    policy: (approval && approval.config && approval.config.policy) || "",
+    policy: policy || "",
     sandbox: (shell && shell.sandboxMode) || "",
   };
 }
@@ -98,27 +182,49 @@ export function apply(ctx, config) {
   };
   const unattendedPolicies = cfg.unattendedPolicies || DEFAULT_UNATTENDED_POLICIES.slice();
   const forcedUnattended = cfg.unattended === true;
+  const engine = cfg.engine || new SecurityEngine({
+    inspectConfig: { toolName: toolName, fileWriteTools: fileWriteTools },
+  });
+
   const hasPreExecute = ctx && typeof ctx.on === "function";
   if (hasPreExecute) {
     ctx.on("tools/pre-execute", function (execution, next) {
-      const hit = inspectExecution(execution, { toolName: toolName, fileWriteTools: fileWriteTools });
-      if (!hit.ask) return next();
-      const knobs = readKnobs(ctx);
-      if (forcedUnattended || isUnattended({ policy: knobs.policy, unattendedPolicies })) {
-        // No one can answer here: an allowed command proceeds. Denials are the guard's job
-        // and do not depend on this decision.
-        return next();
+      const knobs = readKnobs(ctx, execution);
+      const who = sessionTag(execution);
+      const sessionId = (execution && execution.agent && (execution.agent.session || execution.agent)) || "default";
+      const decision = engine.decide(execution, { sessionId, knobs });
+
+      if (decision.verdict === "ask") {
+        if (forcedUnattended || isUnattended({ policy: knobs.policy, unattendedPolicies })) {
+          return next();
+        }
+        const hit = decision.hit || {
+          ask: true,
+          reason: decision.reason,
+          detail: decision.detail,
+          snippet: decision.detail || (execution && execution.arguments && execution.arguments.command),
+        };
+        return { kind: "ask", reason: askMessage(hit, who, translate, ctx && ctx.logger) };
       }
-      return { kind: "ask", reason: askMessage(hit, sessionTag(execution), translate, ctx && ctx.logger) };
+      return next();
     });
   }
 
   const guard = function (execution) {
-    const hit = inspectExecution(execution, { toolName: toolName, fileWriteTools: fileWriteTools });
-    if (!hit.deny && !(hit.ask && !hasPreExecute)) return undefined;
     const who = sessionTag(execution);
-    logBlocked(ctx, hit, who);
-    return denyMessage(hit, who, translate, ctx && ctx.logger);
+    const sessionId = (execution && execution.agent && (execution.agent.session || execution.agent)) || "default";
+    const decision = engine.decide(execution, { sessionId });
+
+    if (decision.verdict === "deny" || (decision.verdict === "ask" && !hasPreExecute)) {
+      const hit = decision.hit || {
+        deny: true,
+        reason: decision.reason,
+        snippet: decision.detail || (execution && execution.arguments && execution.arguments.command) || execution.name,
+      };
+      logBlocked(ctx, hit, who);
+      return denyMessage(hit, who, translate, ctx && ctx.logger);
+    }
+    return undefined;
   };
 
   const mount = function () {
@@ -151,6 +257,8 @@ export {
   hashCall,
   sortKeys,
 } from "./canonical.js";
-export { expandHome } from "./paths.js";
+export { expandHome, resolveSafePath, isPathTraversal, canonicalizeFsPath } from "./paths.js";
 export { splitSubcommands } from "./tokenizer.js";
-
+
+
+export { redactCredentials, redactUrl } from "./redact.js";

package/lib/inspect-env.js

@@ -0,0 +1,57 @@
+// lib/inspect-env.js
+// Inspection of environment exfiltration, memory dumps, and bare env commands.
+
+export function basename(path) {
+  const parts = String(path).replace(/\\/g, "/").split("/");
+  return parts[parts.length - 1] || "";
+}
+
+/**
+ * Inspects argv and command strings for process environment leaks and credential dumping.
+ *
+ * @param {string[]} words - Command words
+ * @param {string} [fullCommand] - Full unparsed command string
+ * @returns {{ deny: boolean, reason?: string, detail?: string }}
+ */
+export function checkEnvExfiltration(words, fullCommand = "") {
+  if (!Array.isArray(words) || words.length === 0) return { deny: false };
+  const cmd = basename(words[0]);
+
+  // 1. Reading /proc/*/environ
+  if (fullCommand && /\/proc\/(?:self|\$\$|\d+)\/environ\b/i.test(fullCommand)) {
+    return { deny: true, reason: "env-dump-leak", detail: "Attempted read of process environ file" };
+  }
+
+  // 2. Bare env
+  if (cmd === "env") {
+    if (words.length === 1) {
+      return { deny: true, reason: "env-dump-leak", detail: "Bare env command dumps all process secrets" };
+    }
+    const nonEnvWords = words.slice(1).filter((w) => !w.startsWith("-"));
+    const onlyAssignments = nonEnvWords.length > 0 && nonEnvWords.every((w) => w.includes("="));
+    if (nonEnvWords.length === 0 || onlyAssignments) {
+      return { deny: true, reason: "env-dump-leak", detail: "env invocation without command dumps environment" };
+    }
+  }
+
+  // 3. Bare printenv or sensitive key read
+  if (cmd === "printenv") {
+    if (words.length === 1) {
+      return { deny: true, reason: "env-dump-leak", detail: "Bare printenv command dumps all process secrets" };
+    }
+    for (const w of words.slice(1)) {
+      if (/(?:secret|token|key|password|credential|auth|dsh_)/i.test(w)) {
+        return { deny: true, reason: "env-dump-leak", detail: "printenv querying sensitive variable" };
+      }
+    }
+  }
+
+  // 4. export without assignment
+  if (cmd === "export") {
+    if (words.length === 1 || (words.length === 2 && words[1] === "-p")) {
+      return { deny: true, reason: "env-dump-leak", detail: "export without assignment dumps environment" };
+    }
+  }
+
+  return { deny: false };
+}

package/lib/inspect.js

@@ -1,54 +1,12 @@
-
-export function checkEnvExfiltration(words, fullCommand = "") {
-  if (!Array.isArray(words) || words.length === 0) return { deny: false };
-  const cmd = basename(words[0]);
-
-  // 1. Reading /proc/*/environ
-  if (fullCommand && /\/proc\/(?:self|\$\$|\d+)\/environ\b/i.test(fullCommand)) {
-    return { deny: true, reason: "env-dump-leak", detail: "Attempted read of process environ file" };
-  }
-
-  // 2. Bare env
-  if (cmd === "env") {
-    if (words.length === 1) {
-      return { deny: true, reason: "env-dump-leak", detail: "Bare env command dumps all process secrets" };
-    }
-    const nonEnvWords = words.slice(1).filter((w) => !w.startsWith("-"));
-    const onlyAssignments = nonEnvWords.length > 0 && nonEnvWords.every((w) => w.includes("="));
-    if (nonEnvWords.length === 0 || onlyAssignments) {
-      return { deny: true, reason: "env-dump-leak", detail: "env invocation without command dumps environment" };
-    }
-  }
-
-  // 3. Bare printenv or sensitive key read
-  if (cmd === "printenv") {
-    if (words.length === 1) {
-      return { deny: true, reason: "env-dump-leak", detail: "Bare printenv command dumps all process secrets" };
-    }
-    for (const w of words.slice(1)) {
-      if (/(?:secret|token|key|password|credential|auth|dsh_)/i.test(w)) {
-        return { deny: true, reason: "env-dump-leak", detail: "printenv querying sensitive variable" };
-      }
-    }
-  }
-
-  // 4. export without assignment
-  if (cmd === "export") {
-    if (words.length === 1 || (words.length === 2 && words[1] === "-p")) {
-      return { deny: true, reason: "env-dump-leak", detail: "export without assignment dumps environment" };
-    }
-  }
-
-  return { deny: false };
-}
-
+import { checkEnvExfiltration } from "./inspect-env.js";
+export { checkEnvExfiltration } from "./inspect-env.js";
 import { DYNAMIC_MARKER, HEREDOC_OPS, REDIR_OPS, SPLIT_OPS, tokenize, readCommandSubstitution, readBacktick, readParameterExpansion } from "./tokenizer.js";
-import { expandHome, isProtectedConfigPath } from "./paths.js";
+import { expandHome, isProtectedConfigPath, resolveSafePath, isPathTraversal, canonicalizeFsPath, normalizeSeparators } from "./paths.js";
 import { askMessage, denyMessage, sessionTag } from "./messages.js";
 
 export { DYNAMIC_MARKER, tokenize, splitSubcommands } from "./tokenizer.js";
 export { askMessage, denyMessage, sessionTag } from "./messages.js";
-export { expandHome, isProtectedConfigPath } from "./paths.js";
+export { expandHome, isProtectedConfigPath, resolveSafePath, isPathTraversal, canonicalizeFsPath, normalizeSeparators } from "./paths.js";
 
 // Pure command/path inspector for dsh-approval-gate.
 // No Cordis imports: unit tests run this without the harness.
@@ -522,6 +480,13 @@ export function inspectBashCommand(command, depth) {
 
     for (const redirect of redirectsOf(seg)) {
       if (redirect.dynamic) return ask("dynamic-redirect", "expanded redirect target cannot be verified", redirect.path);
+      const isRel = !/^(?:\/|[A-Za-z]:\/|\/\/)/.test(normalizeSeparators(redirect.path));
+      if (isRel && isPathTraversal(redirect.path, process.cwd())) {
+        return deny("path-traversal", redirect.path);
+      }
+      if (!isRel && isPathTraversal(redirect.path, "/")) {
+        return deny("path-traversal", redirect.path);
+      }
       if (isProtectedPath(redirect.path)) return deny("secret-write", redirect.path);
     }
 
@@ -596,7 +561,16 @@ export function inspectExecution(execution, config) {
   if (typeof name === "string" && fileTools.has(name)) {
     const path = pathFromArgs(args);
     if (!path) return ask("unknown-write-target", "file write target could not be identified", name);
-    if (isProtectedPath(path)) return deny("secret-write", path);
+    if (config.workspaceDir) {
+      const safeCheck = resolveSafePath(path, config.workspaceDir);
+      if (!safeCheck.safe) return deny("path-traversal", safeCheck.reason || "path-traversal-escape", path);
+      if (isProtectedPath(safeCheck.canonical || path)) return deny("secret-write", path);
+    } else {
+      if (isPathTraversal(path, process.cwd())) {
+        return deny("path-traversal", "path-traversal-escape", path);
+      }
+      if (isProtectedPath(path)) return deny("secret-write", path);
+    }
   }
   return allow();
 }

package/lib/messages.js

@@ -1,3 +1,4 @@
+import { redactCredentials } from "./redact.js";
 export const LOCALE_NS = "dsh-approval-gate";
 
 export const MESSAGES = Object.freeze({
@@ -6,6 +7,7 @@ export const MESSAGES = Object.freeze({
     detectedLabel: "Detected",
     commandLabel: "Command",
     parseReasonLabel: "Parse reason",
+    hintPrefix: "Hint",
     detailProcessSubstitution: "process substitution needs confirmation",
     detailUnclosedProcessSubstitution: "unclosed process substitution",
     detailUnclosedCommandSubstitution: "unclosed command substitution",
@@ -45,12 +47,24 @@ export const MESSAGES = Object.freeze({
     ruleEval: "Dynamic shell evaluation",
     ruleNestedShell: "Nested shell depth limit",
     ruleInterpreterPayload: "Unsafe interpreter payload",
+    ruleEnvDumpLeak: "Process environment or credential exfiltration",
+    rulePathTraversal: "Directory traversal attack detected",
+    ruleBandHardDeny: "Command matched Band 0 critical security blocklist",
+    ruleCircuitBreakerTripped: "Circuit breaker tripped due to repeated security denials",
+    hintRecursiveRm: "Specify exact target files instead of recursive deletion",
+    hintPathTraversal: "Keep operations strictly within the project directory",
+    hintSecretWrite: "Modify configuration via settings or environment variables, not raw file overwrite",
+    hintEnvDumpLeak: "Query specific non-secret environment variables individually",
+    hintCircuitBreakerTripped: "Request manual operator approval before attempting new system commands",
+    hintDestructiveSql: "Use migrations or execute non-destructive database operations",
+    hintCurlPipe: "Download the script, inspect its content, and execute locally",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
     detectedLabel: "检测到",
     commandLabel: "命令",
     parseReasonLabel: "解析原因",
+    hintPrefix: "建议",
     detailProcessSubstitution: "进程替换需要确认",
     detailUnclosedProcessSubstitution: "进程替换未闭合",
     detailUnclosedCommandSubstitution: "命令替换未闭合",
@@ -58,24 +72,24 @@ export const MESSAGES = Object.freeze({
     detailUnclosedParameterExpansion: "参数展开未闭合",
     detailUnclosedSingleQuote: "单引号未闭合",
     detailUnclosedDoubleQuote: "双引号未闭合",
-    detailDanglingEscape: "转义符不完整",
-    detailInvalidHeredoc: "here-document 定界符无效",
-    detailUnterminatedHeredoc: "未找到 here-document 结束标记",
-    detailUnsupportedGrouping: "分析器不支持此 shell 分组语法",
+    detailDanglingEscape: "未完成的转义符",
+    detailInvalidHeredoc: "无效的 heredoc 定界符",
+    detailUnterminatedHeredoc: "未找到 heredoc 结束符",
+    detailUnsupportedGrouping: "分析器不支持该 shell 分组语法",
     detailUnsupported: "不支持的 shell 语法",
-    approvalRequired: "需要审批",
-    askUnknown: "无法完整检查此命令；允许前请先检查",
-    askUnparseable: "无法完整检查 shell 语法；允许前请先检查",
-    askUnknownFormat: "无法检查此工具调用格式；允许前请先检查",
-    askUnknownWriteTarget: "无法识别文件写入目标；允许前请先检查",
-    askDynamicCommand: "无法验证展开后的命令名称；允许前请先检查",
-    askDynamicArguments: "无法验证敏感命令展开后的参数；允许前请先检查",
-    askDynamicRedirect: "无法验证展开后的重定向目标；允许前请先检查",
-    askScriptFile: "守卫无法读取脚本内容；允许前请先检查",
-    askShellStdin: "守卫无法完整检查 shell 输入；允许前请先检查",
-    askInterpreterPayload: "未能完整分析解释器的副作用；允许前请先检查",
-    askCredentialInArgv: "展开后的授权凭据会成为进程参数；请使用安全的凭据 API 帮助程序或在允许前检查",
-    ruleUnknown: "命中安全阻止规则",
+    approvalRequired: "需要批准",
+    askUnknown: "命令无法完整检查；请在允许前进行审查",
+    askUnparseable: "Shell 语法无法完整检查；请在允许前进行审查",
+    askUnknownFormat: "工具调用格式无法检查；请在允许前进行审查",
+    askUnknownWriteTarget: "无法识别文件写入目标；请在允许前进行审查",
+    askDynamicCommand: "无法验证展开后的命令名；请在允许前进行审查",
+    askDynamicArguments: "敏感命令的展开参数无法验证；请在允许前进行审查",
+    askDynamicRedirect: "展开后的重定向目标无法验证；请在允许前进行审查",
+    askScriptFile: "卫兵无法获取脚本文件内容；请在允许前进行审查",
+    askShellStdin: "卫兵无法完整获取 Shell 输入；请在允许前进行审查",
+    askInterpreterPayload: "解释器副作用未完全分析；请在允许前进行审查",
+    askCredentialInArgv: "展开后的授权凭据作为进程参数传递；请使用凭据安全的 API 辅助工具，或在允许前进行审查",
+    ruleUnknown: "命中阻止性安全规则",
     ruleRecursiveRm: "递归删除文件",
     ruleProcessSignal: "终止进程",
     ruleServiceControl: "更改服务状态",
@@ -84,35 +98,47 @@ export const MESSAGES = Object.freeze({
     ruleFindDelete: "find -delete",
     ruleDestructiveSql: "破坏性 SQL",
     ruleSecretWrite: "写入受保护的敏感文件",
-    ruleDeviceWrite: "写入设备或受保护文件",
+    ruleDeviceWrite: "写入系统设备或受保护文件",
     ruleMkfsDevice: "格式化文件系统",
-    ruleCurlPipe: "将下载内容传递给 shell",
-    ruleEval: "动态 shell 求值",
-    ruleNestedShell: "嵌套 shell 超出检查深度",
-    ruleInterpreterPayload: "不安全的解释器代码",
+    ruleCurlPipe: "将下载内容通过管道传入 shell",
+    ruleEval: "动态 shell 执行 (eval)",
+    ruleNestedShell: "超出嵌套 shell 深度限制",
+    ruleInterpreterPayload: "不安全的解释器执行代码",
+    ruleEnvDumpLeak: "尝试泄露环境变量与敏感凭据",
+    rulePathTraversal: "检测到路径穿越攻击",
+    ruleBandHardDeny: "命令匹配 Band 0 关键安全黑名单",
+    ruleCircuitBreakerTripped: "因连续多次安全拒绝，断路熔断器已触发",
+    hintRecursiveRm: "请指定具体目标文件，避免递归删除",
+    hintPathTraversal: "请将操作限制在项目根目录内",
+    hintSecretWrite: "请通过设置或环境变量修改配置，不要直接覆盖敏感配置文件",
+    hintEnvDumpLeak: "请单独查询非敏感环境变量，避免全量导出",
+    hintCircuitBreakerTripped: "请在尝试新的系统命令前请求操作员人工授权",
+    hintDestructiveSql: "请使用版本化数据库迁移，或执行非破坏性查询",
+    hintCurlPipe: "先将脚本下载到本地检查内容，再安全执行",
   },
   ru: {
     blockedPrefix: "Заблокировано правилом dsh-approval-gate",
     detectedLabel: "Обнаружено",
     commandLabel: "Команда",
-    parseReasonLabel: "Причина синтаксического анализа",
-    detailProcessSubstitution: "процессная подстановка требует подтверждения",
-    detailUnclosedProcessSubstitution: "незакрытая процессная подстановка",
+    parseReasonLabel: "Причина разбора",
+    hintPrefix: "Подсказка",
+    detailProcessSubstitution: "подстановка процесса требует подтверждения",
+    detailUnclosedProcessSubstitution: "незакрытая подстановка процесса",
     detailUnclosedCommandSubstitution: "незакрытая подстановка команды",
-    detailUnclosedBacktick: "незакрытая подстановка команды в обратных кавычках",
-    detailUnclosedParameterExpansion: "незакрытое расширение параметров",
+    detailUnclosedBacktick: "незакрытая подстановка в обратных кавычках",
+    detailUnclosedParameterExpansion: "незакрытое расширение параметра",
     detailUnclosedSingleQuote: "незакрытая одинарная кавычка",
     detailUnclosedDoubleQuote: "незакрытая двойная кавычка",
     detailDanglingEscape: "незавершённое экранирование",
     detailInvalidHeredoc: "неверный разделитель here-document",
-    detailUnterminatedHeredoc: "завершитель here-document не найден",
-    detailUnsupportedGrouping: "группировка шелла не поддерживается анализатором",
-    detailUnsupported: "неподдерживаемый синтаксис шелла",
+    detailUnterminatedHeredoc: "ограничитель here-document не найден",
+    detailUnsupportedGrouping: "группировка shell не поддерживается анализатором",
+    detailUnsupported: "неподдерживаемый синтаксис shell",
     approvalRequired: "Требуется подтверждение",
     askUnknown: "Команда не может быть проверена полностью; проверьте её перед подтверждением",
-    askUnparseable: "Синтаксис шелла не может быть проверен полностью; проверьте его перед подтверждением",
+    askUnparseable: "Синтаксис shell не может быть проверен полностью; проверьте его перед подтверждением",
     askUnknownFormat: "Формат вызова инструмента не может быть проверен; проверьте его перед подтверждением",
-    askUnknownWriteTarget: "Целевой файл для записи не определён; проверьте его перед подтверждением",
+    askUnknownWriteTarget: "Цель записи файла не может быть определена; проверьте её перед подтверждением",
     askDynamicCommand: "Развёрнутое имя команды не может быть проверено; проверьте его перед подтверждением",
     askDynamicArguments: "Развёрнутые аргументы чувствительной команды не могут быть проверены; проверьте их перед подтверждением",
     askDynamicRedirect: "Развёрнутая цель перенаправления не может быть проверена; проверьте её перед подтверждением",
@@ -135,22 +161,34 @@ export const MESSAGES = Object.freeze({
     ruleEval: "Динамическое выполнение шелла (eval)",
     ruleNestedShell: "Превышен лимит вложенности шелла",
     ruleInterpreterPayload: "Небезопасный исполняемый код интерпретатора",
+    ruleEnvDumpLeak: "Попытка утечки переменных окружения и секретов",
+    rulePathTraversal: "Обнаружена попытка обхода каталогов (path traversal)",
+    ruleBandHardDeny: "Команда заблокирована критическим списком безопасности Band 0",
+    ruleCircuitBreakerTripped: "Предохранитель сессии сработал из-за повторяющихся блокировок",
+    hintRecursiveRm: "Указывайте конкретные файлы вместо рекурсивного удаления",
+    hintPathTraversal: "Ограничьте операции пределами рабочего каталога проекта",
+    hintSecretWrite: "Изменяйте настройки через UI или переменные окружения, не перезаписывайте секретные файлы напрямую",
+    hintEnvDumpLeak: "Запрашивайте конкретные несекретные переменные по отдельности",
+    hintCircuitBreakerTripped: "Запросите подтверждение оператора перед повторной отправкой системных команд",
+    hintDestructiveSql: "Используйте версионированные миграции или выполняйте неразрушающие запросы",
+    hintCurlPipe: "Скачайте скрипт локально, проверьте его содержимое и выполните безопасно",
   },
 });
 
 export function sessionTag(execution) {
   const agent = execution && execution.agent;
   if (typeof agent === "string") return " (session " + agent + ")";
-  if (agent && agent.session) return " (session " + String(agent.session) + ")";
+  if (agent && agent.session) {
+    const s = agent.session;
+    const sid = typeof s === "string" ? s : (s.id || s.name || s.sessionId || s.sessionKey);
+    return sid ? " (session " + String(sid) + ")" : "";
+  }
   return "";
 }
 
 function safeSnippet(value) {
-  return String(value || "")
-    .replace(/[\r\n\t\u0000-\u001f]+/g, " ")
-    .replace(/(authorization\s*:\s*(?:bearer|token)\s+)\S+/gi, "$1[redacted]")
-    .replace(/((?:password|passwd|secret|token|api[_-]?key)\s*[:=]\s*)[^\s,;]+/gi, "$1[redacted]")
-    .slice(0, 120);
+  const flattened = String(value || "").replace(/[\r\n\t\u0000-\u001f]+/g, " ");
+  return redactCredentials(flattened).slice(0, 120);
 }
 
 function translated(translate, key, logger) {
@@ -183,6 +221,19 @@ const RULE_KEYS = Object.freeze({
   "nested-shell": "ruleNestedShell",
   "interpreter-payload": "ruleInterpreterPayload",
   "env-dump-leak": "ruleEnvDumpLeak",
+  "path-traversal": "rulePathTraversal",
+  "band-hard-deny": "ruleBandHardDeny",
+  "circuit-breaker-tripped": "ruleCircuitBreakerTripped",
+});
+
+const HINT_KEYS = Object.freeze({
+  "recursive-rm": "hintRecursiveRm",
+  "path-traversal": "hintPathTraversal",
+  "secret-write": "hintSecretWrite",
+  "env-dump-leak": "hintEnvDumpLeak",
+  "circuit-breaker-tripped": "hintCircuitBreakerTripped",
+  "destructive-sql": "hintDestructiveSql",
+  "curl-pipe": "hintCurlPipe",
 });
 
 const ASK_KEYS = Object.freeze({
@@ -213,10 +264,15 @@ const DETAIL_KEYS = Object.freeze({
 });
 
 export function denyMessage(hit, who, translate, logger) {
-  const key = RULE_KEYS[hit && hit.reason] || "ruleUnknown";
+  const reason = hit && hit.reason;
+  const key = RULE_KEYS[reason] || "ruleUnknown";
   const snippet = safeSnippet(hit && hit.snippet);
   const parts = [translated(translate, "blockedPrefix", logger), translated(translate, key, logger)];
   if (snippet) parts.push(translated(translate, "detectedLabel", logger) + ": " + snippet);
+  const hintKey = HINT_KEYS[reason];
+  if (hintKey) {
+    parts.push(translated(translate, "hintPrefix", logger) + ": " + translated(translate, hintKey, logger));
+  }
   if (who) parts.push(who.trim());
   return parts.join(" — ") + ".";
 }

package/lib/paths.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 // lib/paths.js
 // Cross-platform path normalization, home expansion, canonicalization, and path boundary traversal protection for dsh-approval-gate.
 
@@ -146,18 +147,28 @@ export function isPathTraversal(p, baseDir = "/workspace") {
   // Detect encoded traversal sequences
   if (/(?:%2e|%2f|%5c|\.\.)(?:%2e|%2f|%5c|\.\.)/i.test(p)) return true;
 
-  const normBase = canonicalizeFsPath(baseDir);
-  const isAbsolute = /^(?:\/|[A-Za-z]:\/|\/\/)/.test(normalizeSeparators(p));
+    const norm = normalizeSeparators(p);
+  if (/^\/dev\/(?:null|zero|stdout|stderr|fd\/\d+)$/.test(norm)) {
+    return false;
+  }
+
+  const isAbsolute = /^(?:\/|[A-Za-z]:\/|\/\/)/.test(norm);
 
-  let candidate = "";
+  const normBase = canonicalizeFsPath(baseDir);
   if (isAbsolute) {
-    candidate = canonicalizeFsPath(p);
-  } else {
-    candidate = canonicalizeFsPath(`${normBase}/${p}`);
+    // For absolute path, it is a traversal only if caller specifies a strict baseDir and candidate is outside
+    const candidate = canonicalizeFsPath(p);
+    if (baseDir && baseDir !== "/" && normBase !== "/") {
+      if (candidate === normBase) return false;
+      return !candidate.startsWith(normBase.endsWith("/") ? normBase : `${normBase}/`);
+    }
+    return false;
   }
 
+  // Relative path traversal checking
+  const candidate = canonicalizeFsPath(`${normBase}/${p}`);
   if (candidate === normBase) return false;
-  return !(candidate.startsWith(normBase.endsWith("/") ? normBase : `${normBase}/`));
+  return !candidate.startsWith(normBase.endsWith("/") ? normBase : `${normBase}/`);
 }
 
 /**
@@ -168,6 +179,12 @@ export function isPathTraversal(p, baseDir = "/workspace") {
  * @returns {{ safe: boolean, path: string, canonical: string, reason?: string }}
  */
 export function resolveSafePath(p, baseDir = "/workspace") {
+  if (typeof p !== "string" || p.trim() === "") {
+    return { safe: false, reason: "empty-path", path: p, canonical: "" };
+  }
+
+  const normBase = canonicalizeFsPath(baseDir);
+
   if (isPathTraversal(p, baseDir)) {
     return {
       safe: false,
@@ -176,9 +193,42 @@ export function resolveSafePath(p, baseDir = "/workspace") {
       canonical: canonicalizeFsPath(p),
     };
   }
-  const normBase = canonicalizeFsPath(baseDir);
+
   const isAbsolute = /^(?:\/|[A-Za-z]:\/|\/\/)/.test(normalizeSeparators(p));
   const resolved = isAbsolute ? canonicalizeFsPath(p) : canonicalizeFsPath(`${normBase}/${p}`);
+
+  if (isAbsolute && baseDir && normBase !== "/" && !resolved.startsWith(normBase.endsWith("/") ? normBase : `${normBase}/`) && resolved !== normBase) {
+    return {
+      safe: false,
+      reason: "path-traversal-escape",
+      path: p,
+      canonical: resolved,
+    };
+  }
+
+  // Inspect filesystem symlinks if the target file or its parent directory exists
+  try {
+    if (fs.existsSync(resolved)) {
+      const real = fs.realpathSync(resolved);
+      const normReal = canonicalizeFsPath(real);
+      if (!normReal.startsWith(normBase.endsWith("/") ? normBase : `${normBase}/`) && normReal !== normBase) {
+        return {
+          safe: false,
+          reason: "symlink-traversal-escape",
+          path: p,
+          canonical: normReal,
+        };
+      }
+      return {
+        safe: true,
+        path: p,
+        canonical: normReal,
+      };
+    }
+  } catch {
+    // Non-filesystem paths or missing directories fall back safely to lexical canonical
+  }
+
   return {
     safe: true,
     path: p,
@@ -267,4 +317,4 @@ export function isProtectedConfigPath(p, env = process.env) {
 
   return false;
 }
-
+

package/lib/redact.js

@@ -0,0 +1,47 @@
+// lib/redact.js
+// Sensitive credential and URL masking for audit logs, approval messages, and traces.
+
+const SENSITIVE_QUERY_PARAMS = /([?&](?:token|key|api_key|apikey|access_token|secret|password|passwd|auth|client_secret)=)[^&#\s]+/gi;
+const USER_INFO_CREDENTIALS = /((?:https?|ftp|ssh|git):\/\/[^:@\/\s]+:)[^@\/\s]+(@)/gi;
+const AUTH_HEADERS = /((?:authorization|proxy-authorization)\s*:\s*(?:bearer|basic|token)\s+)\S+/gi;
+const SENSITIVE_ASSIGNMENTS = /((?:^|[\s,;])(?:password|passwd|secret|token|api[_-]?key|access[_-]?key)\s*[:=]\s*)[^\s,;]+/gi;
+const PRIVATE_KEY_BLOCK = /-----BEGIN [A-Z ]+ PRIVATE KEY-----[\s\S]*?-----END [A-Z ]+ PRIVATE KEY-----/g;
+const TOKEN_PREFIX_PATTERNS = /\b(?:ghp_[a-zA-Z0-9]{30,}|gho_[a-zA-Z0-9]{30,}|github_pat_[a-zA-Z0-9_]{30,}|xox[baprs]-[0-9a-zA-Z-]+|AKIA[0-9A-Z]{16})\b/g;
+
+/**
+ * Redacts credentials in userinfo and sensitive query params from a URL string.
+ *
+ * @param {string} urlStr
+ * @returns {string}
+ */
+export function redactUrl(urlStr) {
+  if (typeof urlStr !== "string" || urlStr.trim() === "") return "";
+  let redacted = urlStr.replace(USER_INFO_CREDENTIALS, "$1***$2");
+  redacted = redacted.replace(SENSITIVE_QUERY_PARAMS, "$1***");
+  return redacted;
+}
+
+/**
+ * Sanitizes and masks sensitive credentials, tokens, passwords, and URLs in arbitrary text.
+ *
+ * @param {string} text - Arbitrary command, snippet, or log text
+ * @returns {string} Text with sensitive tokens masked with ***
+ */
+export function redactCredentials(text) {
+  if (typeof text !== "string") return "";
+  if (text.trim() === "") return text;
+
+  let out = text;
+  // 1. Private key blocks
+  out = out.replace(PRIVATE_KEY_BLOCK, "[REDACTED PRIVATE KEY]");
+  // 2. URLs with user:pass@host
+  out = redactUrl(out);
+  // 3. Authorization headers
+  out = out.replace(AUTH_HEADERS, "$1***");
+  // 4. Secret variable assignments
+  out = out.replace(SENSITIVE_ASSIGNMENTS, "$1***");
+  // 5. Well-known token prefixes
+  out = out.replace(TOKEN_PREFIX_PATTERNS, "***");
+
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Host-only command safety gate for DeepSeek Harness: blocks recognized dangerous operations and requests DSH approval when a command cannot be inspected.",
   "type": "module",
   "main": "lib/index.js",