@goodandready/dsh-approval-gate 0.1.12 → 0.1.14

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,
@@ -370,3 +397,56 @@ export {
 export { expandHome, resolveSafePath, isPathTraversal, canonicalizeFsPath } from "./paths.js";
 export { splitSubcommands } from "./tokenizer.js";
 export { redactCredentials, redactUrl } from "./redact.js";
+export {
+  CommandDispatcher,
+  isReviewerAgent,
+  extractFilePath,
+  TOOL_KIND_SHELL,
+  TOOL_KIND_FILE_WRITE,
+  TOOL_KIND_FILE_READ,
+  TOOL_KIND_NETWORK,
+  TOOL_KIND_GENERIC,
+} from "./dispatcher.js";
+export {
+  parseGitArgv,
+  classifyGitOperation,
+  inspectGitCommand,
+  GIT_CATEGORY_READ,
+  GIT_CATEGORY_MUTATE_LOCAL,
+  GIT_CATEGORY_REMOTE,
+  GIT_CATEGORY_DESTRUCTIVE,
+} from "./parsers/git.js";
+export {
+  isDevicePath,
+  extractRedirects,
+  inspectRedirectSecurity,
+  inspectSilentErrors,
+  inspectPipelines,
+} from "./parsers/shell-cmds.js";
+export {
+  isLoopbackHost,
+  isLoopbackUrl,
+  isLoopbackCommand,
+} 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";