@goodandready/dsh-approval-gate 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.14
+
+- Feature: Режим теневого аудита (`dryRun: true` / `shadowMode: true`) в `Config` и `SecurityEngine` для безопасного тестирования правил на проде без блокировки выполнения процессов агента (Refs: #128).
+- Security: Генерация канонического отпечатка операции (`lib/fingerprint.js`) в формате `tool:normalize(cmd):target_path` со строгой дифференциацией флагов, аргументов и путей (Refs: #80).
+- Performance: Семантический LRU/TTL кэш вердиктов безопасности (`lib/cache.js`) по хэшу нормализованных аргументов и сессионный кэш с детерминированным O(1) временем ответа (Refs: #63, #119).
+- Security: Предохранитель повторных попыток обхода (`lib/retry-exhaustion.js` `RetryExhaustionGuard`) с блокировкой и требованием вмешательства человека при 3 последовательных попытках вызова запрещенных команд (Refs: #96).
+- Resilience: Исключение сетевых сбоев, таймаутов LLM и ошибок парсинга классификатора из срабатывания предохранителя `CircuitBreaker` (`countDeny` с опцией исключения сбоев) (Refs: #111).
+- Quality: Журнал аномалий и качества сессии (`lib/ledger.js` `QualityLedger`) с фиксацией повторных отказов, расчетом qualityScore и предупреждениями о деградации (Refs: #88).
+- Security: Изоляция журнала аудита от контекста сессии (`lib/audit-log.js` `AuditLogger`) с записью в append-only файл `~/.dsh/approval-gate-audit.jsonl` для предотвращения indirect prompt injection (Refs: #56).
+
 ## 0.1.13
 
 - Architecture: выделение `CommandDispatcher` (`lib/dispatcher.js`) для полной изоляции синтаксического разбора аргументов и классификации типов инструментов от движка принятия решений `SecurityEngine` (Refs: #133).
@@ -33,19 +43,14 @@
 - Policy: оптимизация сканирования истории событий сессии в `readKnobs` — однопроходный поиск, ограничение глубины до 100 событий и кэширование политики сессии на `_gateCachedPolicy` (Refs: #148).
 - Schema: поддержка `.volatile()` на полях конфигурации, явные поля `workspaceDir` и `engine`, полифилл для DSH UI формы настроек и функция разворачивания реактивных боксов `plainConfig` (Refs: #142, #150, #151).
 - Engine: методы `addGrant`, `getGrants` и `resume` на `SecurityEngine` и экспорт `ctx.approvalGate` для управления грантами и сбросом предохранителя (Refs: #152).
-- Tokenizer: исправление передачи маркера heredoc (`marker: heredoc.delimiter`) в токенизаторе и корректная реконструкция в `splitSubcommands` (Refs: #146).
-- Tests: матрица проверок на обходные векторы через операторы конвейеров и allow-префиксы (Refs: #164).
 
 ## 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).
+- Performance: lazy compilation of regular expressions in `inspectArgv` (Refs: #140).
+- Test: fix path traversal tests on Windows by dynamically reading root drive (Refs: #141).
 
 ## 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).

package/lib/audit-log.js

@@ -0,0 +1,76 @@
+// lib/audit-log.js
+// Isolated append-only audit logger for dsh-approval-gate (#56).
+// Logs gate decisions to ~/.dsh/approval-gate-audit.jsonl out-of-band to prevent prompt injection.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { computeFingerprint } from "./fingerprint.js";
+import { redactCredentials } from "./redact.js";
+
+export const DEFAULT_AUDIT_LOG_RELATIVE = path.join(".dsh", "approval-gate-audit.jsonl");
+
+export class AuditLogger {
+  /**
+   * @param {{ logPath?: string, disabled?: boolean }} [options]
+   */
+  constructor(options = {}) {
+    this.disabled = options.disabled === true;
+    if (options.logPath) {
+      this.logPath = options.logPath;
+    } else {
+      const home = os.homedir ? os.homedir() : (process.env.HOME || process.env.USERPROFILE || "");
+      this.logPath = home ? path.join(home, DEFAULT_AUDIT_LOG_RELATIVE) : "";
+    }
+  }
+
+  /**
+   * Write an audit record to the isolated log file.
+   *
+   * @param {{
+   *   sessionId?: string,
+   *   execution?: any,
+   *   decision: { verdict: string, stage?: string, reason?: string, detail?: string, dryRun?: boolean },
+   *   dryRun?: boolean
+   * }} record
+   */
+  log(record) {
+    if (this.disabled || !this.logPath) return;
+
+    try {
+      const now = Date.now();
+      const execution = record.execution || {};
+      const decision = record.decision || {};
+      const tool = String(execution.name || execution.tool || "").trim();
+      const rawCmd = execution.arguments && typeof execution.arguments.command === "string"
+        ? execution.arguments.command
+        : "";
+      const redactedCmd = rawCmd ? redactCredentials(rawCmd) : undefined;
+      const fp = computeFingerprint(execution);
+
+      const entry = {
+        timestamp: now,
+        iso: new Date(now).toISOString(),
+        sessionId: record.sessionId || "default",
+        tool,
+        command: redactedCmd,
+        verdict: decision.verdict,
+        stage: decision.stage,
+        reason: decision.reason,
+        detail: decision.detail,
+        fingerprint: fp,
+        dryRun: Boolean(record.dryRun || decision.dryRun),
+      };
+
+      const line = JSON.stringify(entry) + "\n";
+      const dir = path.dirname(this.logPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.appendFileSync(this.logPath, line, "utf8");
+    } catch {
+      // Security audit failures fail open to prevent DoS,
+      // but never leak errors into agent prompt.
+    }
+  }
+}

package/lib/breaker.js

@@ -166,10 +166,16 @@ export class CircuitBreaker {
 
   /**
    * Record a security denial. Returns true if this call tripped the breaker.
+   * Excludes network faults and classifier errors from tripping the breaker (#111).
+   *
    * @param {string} [sessionId]
+   * @param {{ isNetworkFault?: boolean, isClassifierError?: boolean }} [options]
    * @returns {boolean}
    */
-  countDeny(sessionId) {
+  countDeny(sessionId, options = {}) {
+    if (options && (options.isNetworkFault || options.isClassifierError)) {
+      return false;
+    }
     const key = sessionId || "default";
     const state = this._getOrCreate(key);
     state.consecutive += 1;
@@ -191,6 +197,25 @@ export class CircuitBreaker {
     return false;
   }
 
+  /**
+   * Identifies whether an error represents a network fault or classifier timeout (#111).
+   * @param {any} err
+   * @returns {boolean}
+   */
+  static isFaultOrTimeout(err) {
+    if (!err) return false;
+    const msg = String(err.message || err).toLowerCase();
+    return (
+      msg.includes("timeout") ||
+      msg.includes("econnrefused") ||
+      msg.includes("enotfound") ||
+      msg.includes("etimedout") ||
+      msg.includes("network") ||
+      msg.includes("fetch failed") ||
+      msg.includes("socket hang up")
+    );
+  }
+
   /**
    * Reset the consecutive counter on an allowed operation.
    * @param {string} [sessionId]
@@ -231,4 +256,3 @@ export class CircuitBreaker {
     this.sessions.clear();
   }
 }
-

package/lib/cache.js

@@ -0,0 +1,146 @@
+// lib/cache.js
+// Semantic LRU/TTL verdict cache for dsh-approval-gate (#63, #119).
+// Caches deterministic security decisions by canonical operation fingerprint.
+
+import { computeFingerprintHash } from "./fingerprint.js";
+
+export const DEFAULT_CACHE_MAX_SIZE = 1000;
+export const DEFAULT_CACHE_TTL_MS = 300_000; // 5 minutes
+
+export class VerdictCache {
+  /**
+   * @param {{ maxSize?: number, defaultTtlMs?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.maxSize = options.maxSize || DEFAULT_CACHE_MAX_SIZE;
+    this.defaultTtlMs = options.defaultTtlMs !== undefined ? options.defaultTtlMs : DEFAULT_CACHE_TTL_MS;
+    /** @type {Map<string, { decision: any, expiresAt: number, sessionId?: string, timestamp: number }>} */
+    this.entries = new Map();
+  }
+
+  /**
+   * Generates a stable cache key for execution in a session context.
+   *
+   * @param {any} execution
+   * @param {{ sessionId?: string, cwd?: string, sessionScoped?: boolean }} [context]
+   * @returns {string}
+   */
+  makeKey(execution, context = {}) {
+    const hash = computeFingerprintHash(execution, { cwd: context.cwd });
+    if (context.sessionScoped && context.sessionId) {
+      return `${context.sessionId}:${hash}`;
+    }
+    return hash;
+  }
+
+  /**
+   * Retrieves a cached verdict if present and not expired.
+   * Promotes the entry to most recently used.
+   *
+   * @param {string} key
+   * @returns {any | undefined} Cached decision object or undefined
+   */
+  get(key) {
+    if (!this.entries.has(key)) return undefined;
+    const entry = this.entries.get(key);
+    const now = Date.now();
+
+    if (entry.expiresAt > 0 && now > entry.expiresAt) {
+      this.entries.delete(key);
+      return undefined;
+    }
+
+    // Refresh LRU order: delete and re-insert
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+
+    return { ...entry.decision, cached: true, cacheHitAt: now };
+  }
+
+  /**
+   * Stores a decision in the cache.
+   * Only caches deterministic verdicts ("allow" or "deny").
+   *
+   * @param {string} key
+   * @param {any} decision
+   * @param {{ ttlMs?: number, sessionId?: string }} [options]
+   */
+  set(key, decision, options = {}) {
+    if (!key || !decision) return;
+    // Do not cache transient or uncertain verdicts unless explicit
+    if (decision.verdict !== "allow" && decision.verdict !== "deny") {
+      return;
+    }
+
+    const ttl = options.ttlMs !== undefined ? options.ttlMs : this.defaultTtlMs;
+    const now = Date.now();
+    const expiresAt = ttl > 0 ? now + ttl : 0;
+
+    // If key already exists, delete it first to ensure correct insertion order
+    if (this.entries.has(key)) {
+      this.entries.delete(key);
+    } else if (this.entries.size >= this.maxSize) {
+      // Evict oldest (first key in iteration)
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== undefined) {
+        this.entries.delete(oldestKey);
+      }
+    }
+
+    this.entries.set(key, {
+      decision: {
+        verdict: decision.verdict,
+        stage: decision.stage,
+        reason: decision.reason,
+        detail: decision.detail,
+        hit: decision.hit,
+      },
+      expiresAt,
+      sessionId: options.sessionId,
+      timestamp: now,
+    });
+  }
+
+  has(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return false;
+    if (entry.expiresAt > 0 && Date.now() > entry.expiresAt) {
+      this.entries.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  delete(key) {
+    return this.entries.delete(key);
+  }
+
+  clear() {
+    this.entries.clear();
+  }
+
+  clearSession(sessionId) {
+    if (!sessionId) return;
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.sessionId === sessionId || key.startsWith(`${sessionId}:`)) {
+        this.entries.delete(key);
+      }
+    }
+  }
+
+  prune() {
+    const now = Date.now();
+    let count = 0;
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.expiresAt > 0 && now > entry.expiresAt) {
+        this.entries.delete(key);
+        count += 1;
+      }
+    }
+    return count;
+  }
+
+  get size() {
+    return this.entries.size;
+  }
+}

package/lib/engine.js

@@ -1,7 +1,7 @@
 // lib/engine.js
 // 5-tier Security Decision Engine for dsh-approval-gate.
 // Waterfall:
-// P0: Hard Deny (Bands Band 0 + inspectExecution hard denials + protected files)
+// P0: Hard Deny (Bands Band 0 + inspectExecution hard denials + protected files + retry exhaustion)
 // P1: Session Grants (scoped temporary allowances)
 // P2: Static Rules / Safe Allow (Bands Band 1 + safe read-only commands)
 // P3: Optional Semantic Classifier
@@ -11,15 +11,26 @@ import { BandsEngine } from "./bands.js";
 import { CircuitBreaker } from "./breaker.js";
 import { SessionGrantStore } from "./grants.js";
 import { inspectExecution } from "./inspect.js";
+import { VerdictCache } from "./cache.js";
+import { RetryExhaustionGuard } from "./retry-exhaustion.js";
+import { QualityLedger } from "./ledger.js";
+import { AuditLogger } from "./audit-log.js";
 
 export class SecurityEngine {
   /**
    * @param {{
    *   bands?: BandsEngine,
    *   breaker?: CircuitBreaker,
-   *   inspectConfig?: { toolName?: string, fileWriteTools?: string[] },
+   *   cache?: VerdictCache,
+   *   retryGuard?: RetryExhaustionGuard,
+   *   ledger?: QualityLedger,
+   *   auditLogger?: AuditLogger,
+   *   inspectConfig?: { toolName?: string, fileWriteTools?: string[], workspaceDir?: string },
    *   classifier?: ((execution: any, context?: any) => { verdict: "allow"|"deny", reason?: string }),
-   *   grantRegistry?: { decide: (tool: string, args: any, context?: any) => "allow"|"no-match" }
+   *   grantRegistry?: { decide: (tool: string, args: any, context?: any) => "allow"|"no-match" },
+   *   dryRun?: boolean,
+   *   shadowMode?: boolean,
+   *   defaultVerdict?: "allow" | "ask"
    * }} [options]
    */
   constructor(options = {}) {
@@ -29,21 +40,115 @@ export class SecurityEngine {
     this.classifier = options.classifier || null;
     this.grantRegistry = options.grantRegistry || new SessionGrantStore(options);
     this.defaultVerdict = options.defaultVerdict || "allow";
+
+    this.dryRun = Boolean(options.dryRun || options.shadowMode);
+    this.cache = options.cache !== undefined ? options.cache : new VerdictCache();
+    this.retryGuard = options.retryGuard !== undefined ? options.retryGuard : new RetryExhaustionGuard();
+    this.ledger = options.ledger !== undefined ? options.ledger : new QualityLedger();
+    this.auditLogger = options.auditLogger !== undefined ? options.auditLogger : new AuditLogger();
   }
 
   /**
    * Evaluates an execution request through the P0-P4 waterfall.
    *
    * @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, hit?: any }}
+   * @param {{ sessionId?: string, knobs?: any, cwd?: string }} [context] - Context options
+   * @returns {{ verdict: "allow" | "deny" | "ask", stage: "P0" | "P1" | "P2" | "P3" | "P4", reason: string, detail?: string, hit?: any, dryRun?: boolean, cached?: boolean }}
    */
   decide(execution, context = {}) {
     try {
       const sessionId = context.sessionId || "default";
-    const toolName = execution && execution.name;
-    const command = execution && execution.arguments && execution.arguments.command;
+      const toolName = execution && execution.name;
+      const command = execution && execution.arguments && execution.arguments.command;
+
+      // Check Retry Exhaustion guard (#96)
+      if (this.retryGuard && this.retryGuard.isExhausted(sessionId)) {
+        const exhHit = {
+          deny: true,
+          reason: "retry-exhaustion",
+          detail: "Retry exhaustion: consecutive blocked attempts exceeded threshold",
+          snippet: command || toolName,
+        };
+        const exhDecision = { verdict: "deny", stage: "P0", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit };
+        if (this.ledger) this.ledger.record(sessionId, "exhaustion", { reason: "retry-exhaustion", tool: toolName });
+        if (this.auditLogger) this.auditLogger.log({ sessionId, execution, decision: exhDecision, dryRun: this.dryRun });
+
+        if (this.dryRun) {
+          return { verdict: "allow", stage: "P0", dryRun: true, originalVerdict: "deny", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit };
+        }
+        return exhDecision;
+      }
+
+      // Check Verdict Cache (#63, #119)
+      const cacheKey = this.cache ? this.cache.makeKey(execution, context) : null;
+      if (this.cache && cacheKey) {
+        const cached = this.cache.get(cacheKey);
+        if (cached) {
+          if (this.dryRun && (cached.verdict === "deny" || cached.verdict === "ask")) {
+            return {
+              verdict: "allow",
+              stage: cached.stage,
+              dryRun: true,
+              originalVerdict: cached.verdict,
+              reason: cached.reason,
+              detail: cached.detail,
+              hit: cached.hit,
+              cached: true,
+            };
+          }
+          return cached;
+        }
+      }
+
+      const decision = this._evaluateWaterfall(execution, context, sessionId, toolName, command);
+
+      // Post-decision hooks: ledger, retryGuard, cache, audit
+      if (decision.verdict === "deny") {
+        if (this.retryGuard) this.retryGuard.recordVerdict(sessionId, execution, "deny");
+        if (this.ledger) this.ledger.record(sessionId, "deny", { reason: decision.reason, detail: decision.detail, tool: toolName });
+        if (this.cache && cacheKey) this.cache.set(cacheKey, decision, { sessionId });
+      } else if (decision.verdict === "allow") {
+        if (this.retryGuard) this.retryGuard.recordVerdict(sessionId, execution, "allow");
+        if (this.ledger) this.ledger.record(sessionId, "allow", { reason: decision.reason, detail: decision.detail, tool: toolName });
+        if (this.cache && cacheKey) this.cache.set(cacheKey, decision, { sessionId });
+      } else if (decision.verdict === "ask") {
+        if (this.ledger) this.ledger.record(sessionId, "ask", { reason: decision.reason, detail: decision.detail, tool: toolName });
+      }
 
+      if (this.auditLogger) {
+        this.auditLogger.log({ sessionId, execution, decision, dryRun: this.dryRun });
+      }
+
+      // Shadow Mode (#128)
+      if (this.dryRun && (decision.verdict === "deny" || decision.verdict === "ask")) {
+        return {
+          verdict: "allow",
+          stage: decision.stage,
+          dryRun: true,
+          originalVerdict: decision.verdict,
+          reason: decision.reason,
+          detail: decision.detail,
+          hit: decision.hit,
+        };
+      }
+
+      return decision;
+    } catch (err) {
+      return {
+        verdict: "ask",
+        stage: "P4",
+        reason: "inspect-error",
+        detail: String(err && err.message || err),
+        hit: { ask: true, reason: "inspect-error", detail: String(err && err.message || err) },
+      };
+    }
+  }
+
+  /**
+   * Internal evaluation of P0-P4 waterfall.
+   * @private
+   */
+  _evaluateWaterfall(execution, context, sessionId, toolName, command) {
     // Fast-path Band 0 Hard Deny
     const bandVerdict = this.bands.evaluate(toolName, command);
     if (bandVerdict === "deny") {
@@ -70,6 +175,7 @@ export class SecurityEngine {
 
     // If Circuit Breaker is tripped, suspend auto-mode and force P4 Human Ask
     if (this.breaker.isTripped(sessionId)) {
+      if (this.ledger) this.ledger.record(sessionId, "breaker", { reason: "circuit-breaker-tripped", tool: toolName });
       const breakerHit = {
         ask: true,
         reason: "circuit-breaker-tripped",
@@ -110,7 +216,8 @@ export class SecurityEngine {
           return { verdict: "deny", stage: "P3", reason: cls.reason || "classifier-deny", detail: cls.reason, hit: clsHit };
         }
       } catch (err) {
-        // Classifier error fails closed to P4 Ask
+        // Classifier error fails closed to P4 Ask (#111: does not trip breaker)
+        if (this.ledger) this.ledger.record(sessionId, "error", { reason: "classifier-error", detail: String(err && err.message || err), tool: toolName });
         return { verdict: "ask", stage: "P4", reason: "classifier-error", detail: String(err && err.message || err), hit: null };
       }
     }
@@ -121,15 +228,6 @@ export class SecurityEngine {
       return { verdict: "ask", stage: "P4", reason: "unmatched-ask", hit: askHit };
     }
     return { verdict: "allow", stage: "P2", reason: "unmatched-allow", hit };
-    } catch (err) {
-      return {
-        verdict: "ask",
-        stage: "P4",
-        reason: "inspect-error",
-        detail: String(err && err.message || err),
-        hit: { ask: true, reason: "inspect-error", detail: String(err && err.message || err) },
-      };
-    }
   }
 
   addGrant(options) {
@@ -146,7 +244,21 @@ export class SecurityEngine {
     return [];
   }
 
+  getLedgerSummary(sessionId) {
+    return this.ledger ? this.ledger.getSummary(sessionId) : null;
+  }
+
+  isRetryExhausted(sessionId) {
+    return this.retryGuard ? this.retryGuard.isExhausted(sessionId) : false;
+  }
+
+  clearCache() {
+    if (this.cache) this.cache.clear();
+  }
+
   resume(sessionId, reason) {
+    if (this.retryGuard) this.retryGuard.reset(sessionId);
+    if (this.cache) this.cache.clearSession(sessionId);
     return this.breaker.resume(sessionId, reason);
   }
 }

package/lib/fingerprint.js

@@ -0,0 +1,100 @@
+// lib/fingerprint.js
+// Canonical operation fingerprint generator for dsh-approval-gate (#80).
+// Format: tool:normalize(cmd):target_path
+// Strict: flag or argument variations produce distinct fingerprints.
+
+import { createHash } from "node:crypto";
+import { extractFilePath } from "./dispatcher.js";
+import { canonicalizeFsPath, normalizeSeparators } from "./paths.js";
+
+/**
+ * Normalizes command whitespace while preserving quotes.
+ *
+ * @param {string} cmd
+ * @returns {string}
+ */
+export function normalizeCommandString(cmd) {
+  if (typeof cmd !== "string") return "";
+  const trimmed = cmd.trim();
+  if (!trimmed) return "";
+
+  let result = "";
+  let inSingle = false;
+  let inDouble = false;
+  let lastWasSpace = false;
+
+  for (let i = 0; i < trimmed.length; i += 1) {
+    const ch = trimmed[i];
+    if (ch === "'" && !inDouble) {
+      inSingle = !inSingle;
+      result += ch;
+      lastWasSpace = false;
+    } else if (ch === '"' && !inSingle) {
+      inDouble = !inDouble;
+      result += ch;
+      lastWasSpace = false;
+    } else if (/\s/.test(ch) && !inSingle && !inDouble) {
+      if (!lastWasSpace) {
+        result += " ";
+        lastWasSpace = true;
+      }
+    } else {
+      result += ch;
+      lastWasSpace = false;
+    }
+  }
+
+  return result.trim();
+}
+
+/**
+ * Generates a canonical fingerprint for an operation.
+ * Format: tool:normalized_cmd:target_path
+ *
+ * @param {{ name?: string, tool?: string, arguments?: any } | string} execution
+ * @param {{ cwd?: string }} [options]
+ * @returns {string}
+ */
+export function computeFingerprint(execution, options = {}) {
+  let tool = "";
+  let args = {};
+
+  if (typeof execution === "string") {
+    tool = execution.trim().toLowerCase();
+  } else if (execution && typeof execution === "object") {
+    tool = String(execution.name || execution.tool || "").trim().toLowerCase();
+    args = execution.arguments || {};
+    if (typeof args === "string") {
+      try {
+        args = JSON.parse(args);
+      } catch {
+        args = { raw: args };
+      }
+    }
+  }
+
+  const rawCmd = args && typeof args.command === "string" ? args.command : "";
+  const normalizedCmd = normalizeCommandString(rawCmd);
+
+  let targetPath = (args && (args.cwd || extractFilePath(args))) || options.cwd || "";
+  if (typeof targetPath === "string" && targetPath.trim()) {
+    targetPath = canonicalizeFsPath(normalizeSeparators(targetPath.trim()));
+  } else {
+    targetPath = "";
+  }
+
+  return `${tool}:${normalizedCmd}:${targetPath}`;
+}
+
+/**
+ * Computes sha256 hash of the canonical operation fingerprint.
+ *
+ * @param {{ name?: string, tool?: string, arguments?: any } | string} execution
+ * @param {{ cwd?: string, algorithm?: string }} [options]
+ * @returns {string}
+ */
+export function computeFingerprintHash(execution, options = {}) {
+  const fp = computeFingerprint(execution, options);
+  const algo = options.algorithm || "sha256";
+  return createHash(algo).update(fp, "utf8").digest("hex");
+}

package/lib/index.js

@@ -1,5 +1,6 @@
 import { SecurityEngine } from "./engine.js";
 import { BandsEngine } from "./bands.js";
+import { AuditLogger } from "./audit-log.js";
 import Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -205,6 +206,12 @@ export const Config = Schema.object({
   workspaceDir: Schema.string().default("").volatile(),
   /** Default verdict for unclassified commands: 'allow' (default) or 'ask' (fail-closed) (#163). */
   defaultVerdict: Schema.union(["allow", "ask"]).default("allow").volatile(),
+  /** Dry-run / shadow mode for safe testing of rules on production (#128). */
+  dryRun: Schema.boolean().default(false).volatile(),
+  /** Shadow mode alias for dryRun (#128). */
+  shadowMode: Schema.boolean().default(false).volatile(),
+  /** Path to append-only audit log file (#56). */
+  auditLogPath: Schema.string().default("").volatile(),
   /** Security engine instance (internal/testing). */
   engine: Schema.any().hidden(),
 });
@@ -248,12 +255,18 @@ export function apply(ctx, config) {
     inspectConfig: { toolName: toolName, fileWriteTools: fileWriteTools, workspaceDir: cfg.workspaceDir || "" },
     bands: new BandsEngine({ toolRegistry: ctx && ctx.tools }),
     defaultVerdict: cfg.defaultVerdict || "allow",
+    dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
+    auditLogger: new AuditLogger({ logPath: cfg.auditLogPath || undefined }),
   });
 
   const gateService = {
     engine,
     addGrant: (options) => engine.addGrant(options),
     resume: (sessionId, reason) => engine.resume(sessionId, reason),
+    cache: engine.cache,
+    retryGuard: engine.retryGuard,
+    ledger: engine.ledger,
+    getLedgerSummary: (sessionId) => engine.getLedgerSummary(sessionId),
   };
   if (ctx && typeof ctx === "object") {
     if (typeof ctx.provide === "function") {
@@ -282,6 +295,13 @@ export function apply(ctx, config) {
         return { kind: "ask", reason: askMessage(hit, who, translate, ctx && ctx.logger) };
       }
 
+      if (decision.dryRun) {
+        if (ctx && ctx.logger && typeof ctx.logger.info === "function") {
+          ctx.logger.info(`[dsh-approval-gate:DRY-RUN] would block rule=${decision.reason} (${decision.originalVerdict})${who}`);
+        }
+        return next();
+      }
+
       if (decision.verdict === "ask") {
         if (decision.reason === "circuit-breaker-tripped") {
           const hit = decision.hit || {
@@ -325,6 +345,13 @@ export function apply(ctx, config) {
       return denyMessage(hit, who, translate, ctx && ctx.logger);
     }
 
+    if (decision.dryRun) {
+      if (ctx && ctx.logger && typeof ctx.logger.info === "function") {
+        ctx.logger.info(`[dsh-approval-gate:DRY-RUN] would block rule=${decision.reason} (${decision.originalVerdict})${who}`);
+      }
+      return undefined;
+    }
+
     if (decision.verdict === "deny" || (decision.verdict === "ask" && !hasPreExecute)) {
       const hit = decision.hit || {
         deny: true,
@@ -400,4 +427,26 @@ export {
   isLoopbackHost,
   isLoopbackUrl,
   isLoopbackCommand,
-} from "./loopback.js";
+} from "./loopback.js";
+export {
+  computeFingerprint,
+  computeFingerprintHash,
+  normalizeCommandString,
+} from "./fingerprint.js";
+export {
+  VerdictCache,
+  DEFAULT_CACHE_MAX_SIZE,
+  DEFAULT_CACHE_TTL_MS,
+} from "./cache.js";
+export {
+  RetryExhaustionGuard,
+  DEFAULT_MAX_RETRY_ATTEMPTS,
+} from "./retry-exhaustion.js";
+export {
+  QualityLedger,
+  MAX_LEDGER_EVENTS_PER_SESSION,
+} from "./ledger.js";
+export {
+  AuditLogger,
+  DEFAULT_AUDIT_LOG_RELATIVE,
+} from "./audit-log.js";

package/lib/ledger.js

@@ -0,0 +1,164 @@
+// lib/ledger.js
+// Quality and Anomaly Ledger for dsh-approval-gate (#88).
+// Tracks session health, consecutive denials, and execution anomalies.
+
+export const MAX_LEDGER_EVENTS_PER_SESSION = 50;
+
+/**
+ * @typedef {Object} LedgerEvent
+ * @property {number} timestamp
+ * @property {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
+ * @property {string} reason
+ * @property {string} [detail]
+ * @property {string} [tool]
+ */
+
+/**
+ * @typedef {Object} SessionLedger
+ * @property {string} sessionId
+ * @property {number} totalDecisions
+ * @property {number} allowedCount
+ * @property {number} deniedCount
+ * @property {number} askCount
+ * @property {number} anomalyCount
+ * @property {number} consecutiveDenies
+ * @property {boolean} breakerTripped
+ * @property {boolean} retryExhausted
+ * @property {LedgerEvent[]} recentEvents
+ */
+
+export class QualityLedger {
+  constructor() {
+    /** @type {Map<string, SessionLedger>} */
+    this.sessions = new Map();
+  }
+
+  /**
+   * @private
+   */
+  _getOrCreate(sessionId) {
+    const key = sessionId || "default";
+    let ledger = this.sessions.get(key);
+    if (!ledger) {
+      ledger = {
+        sessionId: key,
+        totalDecisions: 0,
+        allowedCount: 0,
+        deniedCount: 0,
+        askCount: 0,
+        anomalyCount: 0,
+        consecutiveDenies: 0,
+        breakerTripped: false,
+        retryExhausted: false,
+        recentEvents: [],
+      };
+      this.sessions.set(key, ledger);
+    }
+    return ledger;
+  }
+
+  /**
+   * Record a decision or system event in the ledger.
+   *
+   * @param {string} sessionId
+   * @param {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
+   * @param {{ reason?: string, detail?: string, tool?: string }} [details]
+   */
+  record(sessionId, type, details = {}) {
+    const ledger = this._getOrCreate(sessionId);
+    const now = Date.now();
+
+    const event = {
+      timestamp: now,
+      type,
+      reason: details.reason || "",
+      detail: details.detail ? String(details.detail).slice(0, 200) : undefined,
+      tool: details.tool || "",
+    };
+
+    ledger.recentEvents.push(event);
+    if (ledger.recentEvents.length > MAX_LEDGER_EVENTS_PER_SESSION) {
+      ledger.recentEvents.shift();
+    }
+
+    if (type === "allow") {
+      ledger.totalDecisions += 1;
+      ledger.allowedCount += 1;
+      ledger.consecutiveDenies = 0;
+    } else if (type === "deny") {
+      ledger.totalDecisions += 1;
+      ledger.deniedCount += 1;
+      ledger.consecutiveDenies += 1;
+      if (ledger.consecutiveDenies > 1) {
+        ledger.anomalyCount += 1;
+      }
+    } else if (type === "ask") {
+      ledger.totalDecisions += 1;
+      ledger.askCount += 1;
+    } else if (type === "exhaustion") {
+      ledger.retryExhausted = true;
+      ledger.anomalyCount += 1;
+    } else if (type === "breaker") {
+      ledger.breakerTripped = true;
+      ledger.anomalyCount += 1;
+    } else if (type === "error") {
+      ledger.anomalyCount += 1;
+    }
+  }
+
+  /**
+   * Returns a quality summary for the session.
+   *
+   * @param {string} sessionId
+   * @returns {{
+   *   sessionId: string,
+   *   totalDecisions: number,
+   *   allowedCount: number,
+   *   deniedCount: number,
+   *   askCount: number,
+   *   anomalyCount: number,
+   *   consecutiveDenies: number,
+   *   qualityScore: number,
+   *   degradationWarning: boolean,
+   *   recentEvents: LedgerEvent[]
+   * }}
+   */
+  getSummary(sessionId) {
+    const ledger = this._getOrCreate(sessionId);
+    const total = ledger.totalDecisions;
+
+    // Quality score: 1.0 down towards 0.0 based on denial & anomaly ratio
+    let score = 1.0;
+    if (total > 0) {
+      const penalty = (ledger.deniedCount * 0.2 + ledger.anomalyCount * 0.3) / total;
+      score = Math.max(0, Math.min(1.0, 1.0 - penalty));
+    }
+
+    const degradationWarning = ledger.consecutiveDenies >= 2 ||
+      ledger.retryExhausted ||
+      ledger.breakerTripped ||
+      (total >= 3 && ledger.deniedCount / total >= 0.5);
+
+    return {
+      sessionId: ledger.sessionId,
+      totalDecisions: ledger.totalDecisions,
+      allowedCount: ledger.allowedCount,
+      deniedCount: ledger.deniedCount,
+      askCount: ledger.askCount,
+      anomalyCount: ledger.anomalyCount,
+      consecutiveDenies: ledger.consecutiveDenies,
+      qualityScore: Number(score.toFixed(2)),
+      degradationWarning,
+      recentEvents: ledger.recentEvents.map((e) => ({ ...e })),
+    };
+  }
+
+  reset(sessionId) {
+    const key = sessionId || "default";
+    this.sessions.delete(key);
+  }
+
+  clear() {
+    this.sessions.clear();
+  }
+}

package/lib/messages.js

@@ -60,6 +60,7 @@ export const MESSAGES = Object.freeze({
     ruleSilentErrorMasked: "Suppression of command failure or error stream",
     ruleChmodChown: "Permission or ownership mutation",
     ruleReviewerReadOnly: "Reviewer agent is strictly isolated in read-only mode",
+    ruleRetryExhaustion: "Exhausted repeated attempts to bypass safety gate",
     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",
@@ -72,6 +73,7 @@ export const MESSAGES = Object.freeze({
     hintSilentErrorMasked: "Allow standard error output to be captured and handle non-zero exit codes explicitly",
     hintChmodChown: "Avoid modifying file permissions or system directory ownership directly",
     hintReviewerReadOnly: "Reviewer agents may only read repository files, not run commands or modify files",
+    hintRetryExhaustion: "Repeated denials detected; manual operator intervention required",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
@@ -99,7 +101,7 @@ export const MESSAGES = Object.freeze({
     askDynamicCommand: "无法验证展开后的命令名；请在允许前进行审查",
     askDynamicArguments: "敏感命令的展开参数无法验证；请在允许前进行审查",
     askDynamicRedirect: "展开后的重定向目标无法验证；请在允许前进行审查",
-    askScriptFile: "卫兵无法获取脚本文件内容；请在允许前进行审查",
+    askScriptFile: "脚本文件内容不可见；请在允许前进行审查",
     askShellStdin: "卫兵无法完整获取 Shell 输入；请在允许前进行审查",
     askInterpreterPayload: "解释器副作用未完全分析；请在允许前进行审查",
     askCredentialInArgv: "展开后的授权凭据作为进程参数传递；请使用凭据安全的 API 辅助工具，或在允许前进行审查",
@@ -131,6 +133,7 @@ export const MESSAGES = Object.freeze({
     ruleSilentErrorMasked: "屏蔽错误输出或强制忽略退出码",
     ruleChmodChown: "修改权限或所有权",
     ruleReviewerReadOnly: "审查者代理处于只读隔离模式",
+    ruleRetryExhaustion: "多次尝试绕过安全网关已达上限",
     hintRecursiveRm: "请指定具体目标文件，避免递归删除",
     hintPathTraversal: "请将操作限制在项目根目录内",
     hintSecretWrite: "请通过设置或环境变量修改配置，不要直接覆盖敏感配置文件",
@@ -143,6 +146,7 @@ export const MESSAGES = Object.freeze({
     hintSilentErrorMasked: "请保留标准错误输出，并明确处理非零退出码",
     hintChmodChown: "避免直接修改系统目录所有权或文件权限",
     hintReviewerReadOnly: "审查者代理仅可读取项目文件，禁止执行命令或修改文件",
+    hintRetryExhaustion: "检测到重复拒绝；需要操作员手动介入",
   },
 });
 
@@ -202,6 +206,7 @@ const RULE_KEYS = Object.freeze({
   "silent-error-masked": "ruleSilentErrorMasked",
   "chmod-chown": "ruleChmodChown",
   "reviewer-read-only": "ruleReviewerReadOnly",
+  "retry-exhaustion": "ruleRetryExhaustion",
 });
 
 const HINT_KEYS = Object.freeze({
@@ -217,6 +222,7 @@ const HINT_KEYS = Object.freeze({
   "silent-error-masked": "hintSilentErrorMasked",
   "chmod-chown": "hintChmodChown",
   "reviewer-read-only": "hintReviewerReadOnly",
+  "retry-exhaustion": "hintRetryExhaustion",
 });
 
 const ASK_KEYS = Object.freeze({
@@ -273,4 +279,4 @@ export function askMessage(hit, who, translate, logger) {
   if (snippet) parts.push(translated(translate, "commandLabel", logger) + ": " + snippet);
   if (who) parts.push(who.trim());
   return parts.join(" — ") + ".";
-}
+}

package/lib/retry-exhaustion.js

@@ -0,0 +1,171 @@
+// lib/retry-exhaustion.js
+// Anti-replay and Retry Exhaustion guard for dsh-approval-gate (#96).
+// Blocks looping/thrashing agents attempting repeated bypasses after consecutive denials.
+
+export const DEFAULT_MAX_RETRY_ATTEMPTS = 3;
+
+/**
+ * Extracts base command root from execution for grouping repeated bypass attempts.
+ *
+ * @param {any} execution
+ * @returns {string}
+ */
+export function extractCommandRoot(execution) {
+  if (!execution) return "";
+  const tool = String(execution.name || execution.tool || "").trim().toLowerCase();
+  const args = execution.arguments || {};
+  if (tool === "bash" || tool === "sh" || tool === "shell") {
+    const cmd = typeof args.command === "string" ? args.command.trim() : "";
+    if (!cmd) return "bash";
+    const parts = cmd.split(/[\s;&|]+/);
+    for (const p of parts) {
+      const clean = p.replace(/^['"]+|['"]+$/g, "").trim();
+      if (!clean) continue;
+      if (clean === "sudo" || clean === "env" || clean === "nohup") continue;
+      return clean;
+    }
+    return "bash";
+  }
+  const path = args.path || args.file || args.target;
+  if (typeof path === "string") return `${tool}:${path}`;
+  return tool;
+}
+
+/**
+ * @typedef {Object} RetrySessionState
+ * @property {string} lastRoot
+ * @property {number} rootRetries
+ * @property {number} totalDenies
+ * @property {boolean} exhausted
+ * @property {number} trippedAt
+ * @property {string[]} recentRoots
+ */
+
+export class RetryExhaustionGuard {
+  /**
+   * @param {{ maxAttempts?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.maxAttempts = options.maxAttempts || DEFAULT_MAX_RETRY_ATTEMPTS;
+    /** @type {Map<string, RetrySessionState>} */
+    this.sessions = new Map();
+  }
+
+  /**
+   * @private
+   */
+  _getOrCreate(sessionId) {
+    const key = sessionId || "default";
+    let state = this.sessions.get(key);
+    if (!state) {
+      state = {
+        lastRoot: "",
+        rootRetries: 0,
+        totalDenies: 0,
+        exhausted: false,
+        trippedAt: 0,
+        recentRoots: [],
+      };
+      this.sessions.set(key, state);
+    }
+    return state;
+  }
+
+  /**
+   * Check if session has exhausted retries.
+   *
+   * @param {string} [sessionId]
+   * @returns {boolean}
+   */
+  isExhausted(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    return Boolean(state && state.exhausted);
+  }
+
+  /**
+   * Get consecutive denials count for session.
+   *
+   * @param {string} [sessionId]
+   * @returns {number}
+   */
+  getConsecutiveDenials(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    return state ? state.rootRetries : 0;
+  }
+
+  /**
+   * Record a verdict for session and evaluate exhaustion threshold.
+   *
+   * @param {string} sessionId
+   * @param {any} execution
+   * @param {"allow" | "deny" | "ask"} verdict
+   * @returns {boolean} True if this verdict caused exhaustion to trip
+   */
+  recordVerdict(sessionId, execution, verdict) {
+    const state = this._getOrCreate(sessionId);
+    const root = extractCommandRoot(execution);
+
+    if (verdict === "deny") {
+      state.totalDenies += 1;
+      if (state.lastRoot === root) {
+        state.rootRetries += 1;
+      } else {
+        state.lastRoot = root;
+        state.rootRetries = 1;
+      }
+
+      state.recentRoots.push(root);
+      if (state.recentRoots.length > 10) {
+        state.recentRoots.shift();
+      }
+
+      if (state.rootRetries >= this.maxAttempts && !state.exhausted) {
+        state.exhausted = true;
+        state.trippedAt = Date.now();
+        return true;
+      }
+    } else if (verdict === "allow") {
+      state.rootRetries = 0;
+      state.lastRoot = "";
+    }
+
+    return false;
+  }
+
+  /**
+   * Reset consecutive denies without clearing total denies or exhaustion.
+   *
+   * @param {string} [sessionId]
+   */
+  resetConsecutive(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    if (state && state.rootRetries > 0) {
+      state.rootRetries = 0;
+      state.lastRoot = "";
+    }
+  }
+
+  /**
+   * Resume / reset a session to active state.
+   *
+   * @param {string} [sessionId]
+   */
+  reset(sessionId) {
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    if (state) {
+      state.lastRoot = "";
+      state.rootRetries = 0;
+      state.exhausted = false;
+      state.trippedAt = 0;
+      state.recentRoots = [];
+    }
+  }
+
+  clear() {
+    this.sessions.clear();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "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",
@@ -51,4 +51,4 @@
     "approval-gate",
     "safety"
   ]
-}
+}