@goodandready/dsh-approval-gate 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.8
+
+- Paths: нормализация разделителей путей `normalizeSeparators` для кроссплатформенной обработки Windows (`\`) и POSIX (`/`) слешей (Refs: #109).
+- Paths: канонизация путей и превентивная защита от path traversal обходов (`..`, `.` сегменты) `canonicalizePath` и `isPathTraversal` (Refs: #94).
+- Security: блокировка модификации скрытых системных файлов и каталогов конфигурации (`.git`, `.env`, `.ssh`) в путях инструментов и перенаправлениях shell (Refs: #108).
+- Security: защита от утечки переменных окружения и секретов через команды `env`, `printenv`, `export` (Refs: #105).
+- Bands: безусловное разрешение безопасных read-only инструментов и инспекций файловой системы через Band 1 (`isReadOnlyTool`, `isSafeInspectionCommand`) (Refs: #120).
+
+## 0.1.7
+
+- Canonical: каноническая сериализация вызовов инструментов `canonicalizeCall` со стабильной рекурсивной сортировкой ключей и хэшированием `hashCall` (Refs: #124).
+- Grants: хранилище временных сессионных грантов `SessionGrantStore` с ограничением по времени жизни (TTL) и максимальному числу вызовов (`maxUses`) (Refs: #123).
+- Grants: поддержка точечных грантов на уровне инструмента, префикса аргументов (`commandPrefix`, `pathPrefix`, `prefix`) и регулярных выражений `argsPattern` (Refs: #132).
+- Grants: автоматическая сборка мусора и очистка просроченных/исчерпанных сессионных грантов `prune()` с таймером и счетчиком операций (Refs: #130).
+- Breaker: детальное логирование переходов состояний предохранителя сессии `CircuitBreaker` (`active -> tripped -> resumed`), история событий и поддержка подписок `onStateChange` (Refs: #121).
+
 ## 0.1.6
 
 - Security: автоматическое раскрытие домашних путей `expandHome` (`~`, `$HOME`, `${HOME}`, `%USERPROFILE%`) в путях файлов, аргументах инструментов записи и перенаправлениях shell (Refs: #114).

package/lib/bands.js

@@ -1,7 +1,7 @@
 // lib/bands.js
 // Two-band deterministic filtering engine for dsh-approval-gate.
 // Band 0: Hard Deny (fast regexes for exfiltration, fork-bombs, disk wipes)
-// Band 1: Safe Allow (prefix globs & curated safe inspection commands)
+// Band 1: Safe Allow (prefix globs & curated safe read-only inspection commands and tools)
 
 export const DEFAULT_DENY_PATTERNS = Object.freeze([
   /\b(?:nc|ncat|netcat)\s+.*-e\s+/i,
@@ -16,20 +16,50 @@ export const DEFAULT_DENY_PATTERNS = Object.freeze([
 ]);
 
 export const DEFAULT_ALLOW_GLOBS = Object.freeze([
+  // Git inspection commands
   "git status*",
   "git diff*",
   "git log*",
   "git branch*",
   "git show*",
-  "ls*",
-  "pwd*",
+  "git remote*",
+  "git tag*",
+  "git rev-parse*",
+
+  // File viewing & analysis
   "cat *",
   "head *",
   "tail *",
+  "more *",
+  "less *",
   "wc *",
+  "file *",
+  "stat *",
+  "diff *",
+
+  // Search & finding
+  "grep *",
+  "fgrep *",
+  "egrep *",
+  "rg *",
+  "ag *",
+  "find *",
+
+  // Directory listing & environment info
+  "ls*",
+  "dir*",
+  "pwd*",
   "which *",
   "whereis *",
   "whoami*",
+  "hostname*",
+  "uname*",
+  "date*",
+  "uptime*",
+  "echo *",
+  "printf *",
+
+  // Language / runtime versions & test runners
   "node --version*",
   "node -v*",
   "npm test*",
@@ -45,21 +75,32 @@ export const DEFAULT_ALLOW_GLOBS = Object.freeze([
   "pytest*",
   "python --version*",
   "python3 --version*",
-  "echo *",
 ]);
 
 export const DEFAULT_READ_ONLY_TOOLS = Object.freeze([
   "read",
   "read_file",
   "readFile",
+  "read_file_content",
   "view_file",
+  "view",
+  "show",
   "glob",
   "grep",
   "find_files",
+  "find_by_name",
   "search_code",
   "file_search",
   "list_dir",
   "list_directory",
+  "directory_list",
+  "tree",
+  "read_url_content",
+  "fetch_web_page",
+  "web_search",
+  "search_web",
+  "list_resources",
+  "read_resource",
 ]);
 
 /**
@@ -79,7 +120,11 @@ export function compileGlob(pattern) {
 
 export class BandsEngine {
   /**
-   * @param {{ denyPatterns?: Array<RegExp|string>, allowGlobs?: Array<RegExp|string>, readOnlyTools?: Array<string> }} [options]
+   * @param {{
+   *   denyPatterns?: Array<RegExp|string>,
+   *   allowGlobs?: Array<RegExp|string>,
+   *   readOnlyTools?: Array<string>
+   * }} [options]
    */
   constructor(options = {}) {
     this.denyPatterns = (options.denyPatterns || DEFAULT_DENY_PATTERNS).map((p) =>
@@ -91,6 +136,52 @@ export class BandsEngine {
     this.readOnlyTools = new Set(options.readOnlyTools || DEFAULT_READ_ONLY_TOOLS);
   }
 
+  /**
+   * Check if a tool is configured as an unconditional read-only tool.
+   * @param {string} tool
+   * @returns {boolean}
+   */
+  isReadOnlyTool(tool) {
+    return typeof tool === "string" && this.readOnlyTools.has(tool.trim());
+  }
+
+  /**
+   * Check if a command matches safe inspection patterns.
+   * @param {string} command
+   * @returns {boolean}
+   */
+  isSafeInspectionCommand(command) {
+    if (typeof command !== "string" || command.trim() === "") return false;
+    const text = command.trim();
+    for (const pattern of this.denyPatterns) {
+      if (pattern.test(text)) return false;
+    }
+    for (const glob of this.allowGlobs) {
+      if (glob.test(text)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Register an additional read-only tool name.
+   * @param {string} tool
+   */
+  addReadOnlyTool(tool) {
+    if (typeof tool === "string" && tool.trim()) {
+      this.readOnlyTools.add(tool.trim());
+    }
+  }
+
+  /**
+   * Register an additional allow-glob pattern.
+   * @param {string} globPattern
+   */
+  addAllowGlob(globPattern) {
+    if (typeof globPattern === "string" && globPattern.trim()) {
+      this.allowGlobs.push(compileGlob(globPattern.trim()));
+    }
+  }
+
   /**
    * Evaluates an execution request through Band 0 and Band 1.
    * @param {string} tool - Tool name
@@ -98,7 +189,7 @@ export class BandsEngine {
    * @returns {"deny" | "allow" | "unmatched"}
    */
   evaluate(tool, command) {
-    if (this.readOnlyTools.has(tool)) {
+    if (this.isReadOnlyTool(tool)) {
       return "allow";
     }
 
@@ -123,3 +214,4 @@ export class BandsEngine {
     return "unmatched";
   }
 }
+

package/lib/breaker.js

@@ -1,34 +1,146 @@
 // lib/breaker.js
-// Session-scoped Circuit Breaker for dsh-approval-gate.
+// Session-scoped Circuit Breaker for dsh-approval-gate with state transition events and history.
 // Protects against agent thrashing / loops when blocked by security gates.
 
 export const DEFAULT_MAX_CONSECUTIVE_DENIES = 3;
 export const DEFAULT_MAX_TOTAL_DENIES = 20;
 
+export const CIRCUIT_STATE_ACTIVE = "active";
+export const CIRCUIT_STATE_TRIPPED = "tripped";
+export const CIRCUIT_STATE_RESUMED = "resumed";
+
+/**
+ * @typedef {Object} CircuitTransitionEvent
+ * @property {string} sessionId
+ * @property {string} from
+ * @property {string} to
+ * @property {string} reason
+ * @property {number} consecutive
+ * @property {number} total
+ * @property {number} timestamp
+ */
+
 export class CircuitBreaker {
   /**
-   * @param {{ maxConsecutive?: number, maxTotal?: number }} [options]
+   * @param {{
+   *   maxConsecutive?: number,
+   *   maxTotal?: number,
+   *   logger?: { info?: (msg: string) => void, warn?: (msg: string) => void }
+   * }} [options]
    */
   constructor(options = {}) {
     this.maxConsecutive = options.maxConsecutive || DEFAULT_MAX_CONSECUTIVE_DENIES;
     this.maxTotal = options.maxTotal || DEFAULT_MAX_TOTAL_DENIES;
-    /** @type {Map<string, { consecutive: number, total: number, tripped: boolean }>} */
+    this.logger = options.logger || null;
+    /** @type {Array<(event: CircuitTransitionEvent) => void>} */
+    this.listeners = [];
+    /** @type {Map<string, { consecutive: number, total: number, tripped: boolean, state: string, history: CircuitTransitionEvent[] }>} */
     this.sessions = new Map();
   }
 
   /**
-   * Get current state snapshot for a session.
-   * @param {string} [sessionId]
-   * @returns {{ consecutive: number, total: number, tripped: boolean }}
+   * Register a state change listener callback.
+   * @param {(event: CircuitTransitionEvent) => void} fn
+   * @returns {() => void} Unsubscribe function
    */
-  get(sessionId) {
+  onStateChange(fn) {
+    if (typeof fn === "function") {
+      this.listeners.push(fn);
+    }
+    return () => {
+      const idx = this.listeners.indexOf(fn);
+      if (idx !== -1) this.listeners.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Emit a transition event to registered listeners and optional logger.
+   * @private
+   */
+  _emitTransition(sessionState, sessionId, from, to, reason) {
+    const event = {
+      sessionId,
+      from,
+      to,
+      reason,
+      consecutive: sessionState.consecutive,
+      total: sessionState.total,
+      timestamp: Date.now(),
+    };
+
+    sessionState.state = to;
+    sessionState.history.push(event);
+
+    if (this.logger) {
+      const logLine = `[dsh-approval-gate:breaker] session=${sessionId} state=${to} (was ${from}) reason=${reason} consecutive=${sessionState.consecutive} total=${sessionState.total}`;
+      if (to === CIRCUIT_STATE_TRIPPED && typeof this.logger.warn === "function") {
+        this.logger.warn(logLine);
+      } else if (typeof this.logger.info === "function") {
+        this.logger.info(logLine);
+      }
+    }
+
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Listener error must not crash the breaker
+      }
+    }
+  }
+
+  /**
+   * Internal session state fetch or initialize.
+   * @private
+   */
+  _getOrCreate(sessionId) {
     const key = sessionId || "default";
     let state = this.sessions.get(key);
     if (!state) {
-      state = { consecutive: 0, total: 0, tripped: false };
+      state = {
+        consecutive: 0,
+        total: 0,
+        tripped: false,
+        state: CIRCUIT_STATE_ACTIVE,
+        history: [],
+      };
       this.sessions.set(key, state);
     }
-    return { ...state };
+    return state;
+  }
+
+  /**
+   * Get current state snapshot for a session (backward compatible).
+   * @param {string} [sessionId]
+   * @returns {{ consecutive: number, total: number, tripped: boolean }}
+   */
+  get(sessionId) {
+    const state = this._getOrCreate(sessionId);
+    return {
+      consecutive: state.consecutive,
+      total: state.total,
+      tripped: state.tripped,
+    };
+  }
+
+  /**
+   * Get current lifecycle state string ("active" | "tripped" | "resumed").
+   * @param {string} [sessionId]
+   * @returns {string}
+   */
+  getState(sessionId) {
+    const state = this._getOrCreate(sessionId);
+    return state.state;
+  }
+
+  /**
+   * Retrieve state transition history for a session.
+   * @param {string} [sessionId]
+   * @returns {CircuitTransitionEvent[]}
+   */
+  getHistory(sessionId) {
+    const state = this._getOrCreate(sessionId);
+    return state.history.map((ev) => ({ ...ev }));
   }
 
   /**
@@ -37,8 +149,7 @@ export class CircuitBreaker {
    * @returns {boolean}
    */
   isTripped(sessionId) {
-    const key = sessionId || "default";
-    const state = this.sessions.get(key);
+    const state = this._getOrCreate(sessionId);
     return Boolean(state && state.tripped);
   }
 
@@ -49,18 +160,23 @@ export class CircuitBreaker {
    */
   countDeny(sessionId) {
     const key = sessionId || "default";
-    let state = this.sessions.get(key);
-    if (!state) {
-      state = { consecutive: 0, total: 0, tripped: false };
-      this.sessions.set(key, state);
-    }
+    const state = this._getOrCreate(key);
     state.consecutive += 1;
     state.total += 1;
+
     const wasTripped = state.tripped;
-    if (state.consecutive >= this.maxConsecutive || state.total >= this.maxTotal) {
+    const isConsecutiveTrip = state.consecutive >= this.maxConsecutive;
+    const isTotalTrip = state.total >= this.maxTotal;
+
+    if ((isConsecutiveTrip || isTotalTrip) && !wasTripped) {
       state.tripped = true;
-      return !wasTripped;
+      const reason = isConsecutiveTrip
+        ? `consecutive-threshold-exceeded (${state.consecutive}/${this.maxConsecutive})`
+        : `total-threshold-exceeded (${state.total}/${this.maxTotal})`;
+      this._emitTransition(state, key, CIRCUIT_STATE_ACTIVE, CIRCUIT_STATE_TRIPPED, reason);
+      return true;
     }
+
     return false;
   }
 
@@ -70,21 +186,30 @@ export class CircuitBreaker {
    */
   resetConsecutive(sessionId) {
     const key = sessionId || "default";
-    const state = this.sessions.get(key);
-    if (state) state.consecutive = 0;
+    const state = this._getOrCreate(key);
+    if (state.consecutive > 0) {
+      state.consecutive = 0;
+    }
   }
 
   /**
-   * Fully resume auto-mode after human approval.
+   * Fully resume auto-mode after human approval or admin action.
    * @param {string} [sessionId]
+   * @param {string} [reason="manual-human-resume"]
    */
-  resume(sessionId) {
+  resume(sessionId, reason = "manual-human-resume") {
     const key = sessionId || "default";
-    const state = this.sessions.get(key);
-    if (state) {
-      state.consecutive = 0;
-      state.total = 0;
-      state.tripped = false;
+    const state = this._getOrCreate(key);
+    const wasTripped = state.tripped;
+    const oldState = state.state;
+
+    state.consecutive = 0;
+    state.total = 0;
+    state.tripped = false;
+
+    if (wasTripped || oldState !== CIRCUIT_STATE_ACTIVE) {
+      this._emitTransition(state, key, oldState, CIRCUIT_STATE_RESUMED, reason);
+      this._emitTransition(state, key, CIRCUIT_STATE_RESUMED, CIRCUIT_STATE_ACTIVE, "session-reset-complete");
     }
   }
 
@@ -95,3 +220,4 @@ export class CircuitBreaker {
     this.sessions.clear();
   }
 }
+

package/lib/canonical.js

@@ -0,0 +1,88 @@
+// lib/canonical.js
+// Deterministic canonicalization and hashing for tool execution requests.
+// Ensures identical tool calls with different key ordering produce identical hashes.
+
+import { createHash } from "node:crypto";
+
+/**
+ * Recursively sort object keys alphabetically and normalize values.
+ *
+ * @param {any} value
+ * @returns {any}
+ */
+export function sortKeys(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  const sorted = {};
+  const keys = Object.keys(value).sort();
+  for (const k of keys) {
+    sorted[k] = sortKeys(value[k]);
+  }
+  return sorted;
+}
+
+/**
+ * Canonicalizes a tool call into a stable structure { tool: string, arguments: any }.
+ *
+ * @param {{ name?: string, tool?: string, arguments?: any } | string} executionOrTool
+ * @param {any} [args]
+ * @returns {{ tool: string, arguments: any }}
+ */
+export function canonicalizeCall(executionOrTool, args) {
+  let tool = "";
+  let rawArgs = {};
+
+  if (typeof executionOrTool === "string") {
+    tool = executionOrTool.trim();
+    rawArgs = args || {};
+  } else if (executionOrTool && typeof executionOrTool === "object") {
+    tool = String(executionOrTool.name || executionOrTool.tool || "").trim();
+    rawArgs = executionOrTool.arguments !== undefined ? executionOrTool.arguments : (args || {});
+  }
+
+  // If rawArgs is a JSON string, try to parse it
+  if (typeof rawArgs === "string") {
+    try {
+      rawArgs = JSON.parse(rawArgs);
+    } catch {
+      // Keep as string if not valid JSON
+    }
+  }
+
+  const normalizedArgs = rawArgs && typeof rawArgs === "object"
+    ? sortKeys(rawArgs)
+    : (rawArgs ?? {});
+
+  return {
+    tool,
+    arguments: normalizedArgs,
+  };
+}
+
+/**
+ * Converts a tool call to a deterministic canonical JSON string.
+ *
+ * @param {{ name?: string, tool?: string, arguments?: any } | string} executionOrTool
+ * @param {any} [args]
+ * @returns {string}
+ */
+export function canonicalString(executionOrTool, args) {
+  return JSON.stringify(canonicalizeCall(executionOrTool, args));
+}
+
+/**
+ * Computes a cryptographic hash of the canonicalized tool call.
+ *
+ * @param {{ name?: string, tool?: string, arguments?: any } | string} executionOrTool
+ * @param {any} [args]
+ * @param {string} [algorithm="sha256"]
+ * @returns {string}
+ */
+export function hashCall(executionOrTool, args, algorithm = "sha256") {
+  const str = canonicalString(executionOrTool, args);
+  return createHash(algorithm).update(str, "utf8").digest("hex");
+}

package/lib/engine.js

@@ -9,6 +9,7 @@
 
 import { BandsEngine } from "./bands.js";
 import { CircuitBreaker } from "./breaker.js";
+import { SessionGrantStore } from "./grants.js";
 import { inspectExecution } from "./inspect.js";
 
 export class SecurityEngine {
@@ -18,7 +19,7 @@ export class SecurityEngine {
    *   breaker?: CircuitBreaker,
    *   inspectConfig?: { toolName?: string, fileWriteTools?: string[] },
    *   classifier?: ((execution: any, context?: any) => { verdict: "allow"|"deny", reason?: string }),
-   *   grantRegistry?: { decide: (tool: string, args: any) => "allow"|"no-match" }
+   *   grantRegistry?: { decide: (tool: string, args: any, context?: any) => "allow"|"no-match" }
    * }} [options]
    */
   constructor(options = {}) {
@@ -26,7 +27,7 @@ export class SecurityEngine {
     this.breaker = options.breaker || new CircuitBreaker(options);
     this.inspectConfig = options.inspectConfig || {};
     this.classifier = options.classifier || null;
-    this.grantRegistry = options.grantRegistry || null;
+    this.grantRegistry = options.grantRegistry || new SessionGrantStore(options);
   }
 
   /**
@@ -57,7 +58,7 @@ export class SecurityEngine {
 
     // P1: Session Grants
     if (this.grantRegistry && typeof this.grantRegistry.decide === "function") {
-      const grantMatch = this.grantRegistry.decide(toolName, execution.arguments);
+      const grantMatch = this.grantRegistry.decide(toolName, execution.arguments, context);
       if (grantMatch === "allow") {
         this.breaker.resetConsecutive(sessionId);
         return { verdict: "allow", stage: "P1", reason: "session-grant" };
@@ -106,3 +107,4 @@ export class SecurityEngine {
     return { verdict: "allow", stage: "P2", reason: "unmatched-allow" };
   }
 }
+

package/lib/grants.js

@@ -0,0 +1,383 @@
+// lib/grants.js
+// Session-scoped temporary grants with TTL, usage limits, and automatic garbage collection.
+// Fulfills level P1 (Session Grants) in SecurityEngine.
+
+import { canonicalizeCall, hashCall } from "./canonical.js";
+
+export const DEFAULT_GRANT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+export const DEFAULT_GRANT_MAX_USES = 1;
+export const DEFAULT_AUTO_PRUNE_OPS = 50;
+
+/**
+ * Checks if candidate string starts with prefix.
+ * @param {any} val
+ * @param {string} prefix
+ * @returns {boolean}
+ */
+function matchesPrefix(val, prefix) {
+  if (typeof val !== "string" || typeof prefix !== "string") return false;
+  return val.startsWith(prefix);
+}
+
+/**
+ * Evaluates whether arguments satisfy a grant's prefix / pattern requirements.
+ *
+ * @param {any} args
+ * @param {Grant} grant
+ * @returns {boolean}
+ */
+export function matchGrantCriteria(args, grant) {
+  // 1. Specific command prefix
+  if (grant.commandPrefix) {
+    const cmd = args && typeof args.command === "string" ? args.command : "";
+    if (!matchesPrefix(cmd, grant.commandPrefix)) return false;
+  }
+
+  // 2. Specific path prefix
+  if (grant.pathPrefix) {
+    const targetPath = args && (args.path || args.target || args.file || "");
+    if (!matchesPrefix(targetPath, grant.pathPrefix)) return false;
+  }
+
+  // 3. Structured prefix match
+  if (grant.prefix) {
+    if (typeof grant.prefix === "string") {
+      const cmd = args && typeof args.command === "string" ? args.command : "";
+      if (!matchesPrefix(cmd, grant.prefix)) return false;
+    } else if (typeof grant.prefix === "object" && grant.prefix !== null) {
+      for (const [key, expectedPrefix] of Object.entries(grant.prefix)) {
+        const val = args && args[key];
+        if (!matchesPrefix(val, expectedPrefix)) return false;
+      }
+    }
+  }
+
+  // 4. Pattern matching (RegExp or predicate)
+  if (grant.argsPattern) {
+    if (typeof grant.argsPattern === "function") {
+      if (!grant.argsPattern(args)) return false;
+    } else if (typeof grant.argsPattern === "object" && grant.argsPattern !== null) {
+      for (const [key, pattern] of Object.entries(grant.argsPattern)) {
+        const val = args && args[key];
+        if (pattern instanceof RegExp) {
+          if (typeof val !== "string" || !pattern.test(val)) return false;
+        } else if (typeof pattern === "string") {
+          if (val !== pattern) return false;
+        }
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * @typedef {Object} Grant
+ * @property {string} id
+ * @property {string} sessionId
+ * @property {string} tool
+ * @property {number} createdAt
+ * @property {number} expiresAt
+ * @property {number} ttlMs
+ * @property {number} maxUses
+ * @property {number} uses
+ * @property {string} [commandPrefix]
+ * @property {string} [pathPrefix]
+ * @property {string|Record<string, string>} [prefix]
+ * @property {Record<string, RegExp|string>|Function} [argsPattern]
+ * @property {any} [match]
+ * @property {string} [callHash]
+ */
+
+export class SessionGrantStore {
+  /**
+   * @param {{
+   *   defaultTtlMs?: number,
+   *   defaultMaxUses?: number,
+   *   autoPruneOps?: number
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.defaultTtlMs = options.defaultTtlMs || DEFAULT_GRANT_TTL_MS;
+    this.defaultMaxUses = options.defaultMaxUses || DEFAULT_GRANT_MAX_USES;
+    this.autoPruneOps = options.autoPruneOps || DEFAULT_AUTO_PRUNE_OPS;
+    this._opCount = 0;
+    this._pruneTimer = null;
+    /** @type {Map<string, Grant[]>} */
+    this.sessions = new Map();
+  }
+
+  /**
+   * Check if a grant is expired at a given timestamp.
+   * @param {Grant} grant
+   * @param {number} [now]
+   * @returns {boolean}
+   */
+  isExpired(grant, now = Date.now()) {
+    return Number.isFinite(grant.expiresAt) && now > grant.expiresAt;
+  }
+
+  /**
+   * Check if a grant has exhausted its allowed uses.
+   * @param {Grant} grant
+   * @returns {boolean}
+   */
+  isExhausted(grant) {
+    return Number.isFinite(grant.maxUses) && grant.uses >= grant.maxUses;
+  }
+
+  /**
+   * Trigger automatic counter-based pruning if threshold is reached.
+   * @private
+   */
+  _maybeAutoPrune() {
+    this._opCount += 1;
+    if (this.autoPruneOps > 0 && this._opCount >= this.autoPruneOps) {
+      this._opCount = 0;
+      this.prune();
+    }
+  }
+
+  /**
+   * Issue a new temporary session grant.
+   *
+   * @param {{
+   *   sessionId?: string,
+   *   tool: string,
+   *   ttlMs?: number,
+   *   maxUses?: number,
+   *   commandPrefix?: string,
+   *   pathPrefix?: string,
+   *   prefix?: string | Record<string, string>,
+   *   argsPattern?: Record<string, RegExp|string> | Function,
+   *   match?: any,
+   *   callHash?: string,
+   *   id?: string
+   * }} options
+   * @returns {Grant}
+   */
+  addGrant(options) {
+    if (!options || typeof options.tool !== "string") {
+      throw new TypeError("addGrant requires options.tool as string");
+    }
+
+    this._maybeAutoPrune();
+
+    const sessionId = options.sessionId || "default";
+    const now = Date.now();
+    const ttlMs = options.ttlMs !== undefined ? options.ttlMs : this.defaultTtlMs;
+    const maxUses = options.maxUses !== undefined ? options.maxUses : this.defaultMaxUses;
+    const expiresAt = Number.isFinite(ttlMs) ? now + ttlMs : Infinity;
+    const id = options.id || ("grant_" + now + "_" + Math.random().toString(36).slice(2, 9));
+
+    const grant = {
+      id,
+      sessionId,
+      tool: options.tool.trim(),
+      createdAt: now,
+      expiresAt,
+      ttlMs,
+      maxUses,
+      uses: 0,
+      commandPrefix: options.commandPrefix,
+      pathPrefix: options.pathPrefix,
+      prefix: options.prefix,
+      argsPattern: options.argsPattern,
+      match: options.match,
+      callHash: options.callHash,
+    };
+
+    let list = this.sessions.get(sessionId);
+    if (!list) {
+      list = [];
+      this.sessions.set(sessionId, list);
+    }
+    list.push(grant);
+
+    return grant;
+  }
+
+  /**
+   * Evaluates if a tool execution is authorized by an active session grant.
+   * If a match is found, increments the grant usage counter and returns "allow".
+   *
+   * @param {string} toolName
+   * @param {any} args
+   * @param {{ sessionId?: string, now?: number }} [context]
+   * @returns {"allow" | "no-match"}
+   */
+  decide(toolName, args, context = {}) {
+    this._maybeAutoPrune();
+
+    const sessionId = (context && context.sessionId) || "default";
+    const now = (context && context.now) || Date.now();
+    const list = this.sessions.get(sessionId);
+
+    if (!list || list.length === 0) {
+      return "no-match";
+    }
+
+    const incomingHash = hashCall(toolName, args);
+
+    for (let i = 0; i < list.length; i++) {
+      const grant = list[i];
+
+      // Expiry & Exhaustion check
+      if (this.isExpired(grant, now) || this.isExhausted(grant)) {
+        continue;
+      }
+
+      // Tool match
+      if (grant.tool !== "*" && grant.tool !== toolName) {
+        continue;
+      }
+
+      // Hash match (if specific call was granted)
+      if (grant.callHash && grant.callHash !== incomingHash) {
+        continue;
+      }
+
+      // Prefix and pattern matching criteria
+      if (!matchGrantCriteria(args, grant)) {
+        continue;
+      }
+
+      // Generic match predicate if provided
+      if (typeof grant.match === "function") {
+        if (!grant.match(toolName, args)) {
+          continue;
+        }
+      }
+
+      // Valid grant found: increment usage and allow
+      grant.uses += 1;
+      return "allow";
+    }
+
+    return "no-match";
+  }
+
+  /**
+   * Retrieves active, non-expired grants for a session.
+   * @param {string} [sessionId]
+   * @param {number} [now]
+   * @returns {Grant[]}
+   */
+  getGrants(sessionId, now = Date.now()) {
+    const key = sessionId || "default";
+    const list = this.sessions.get(key) || [];
+    return list
+      .filter((g) => !this.isExpired(g, now) && !this.isExhausted(g))
+      .map((g) => ({ ...g }));
+  }
+
+  /**
+   * Revoke a specific grant by ID.
+   * @param {string} grantId
+   * @param {string} [sessionId]
+   * @returns {boolean} True if grant was found and revoked
+   */
+  revokeGrant(grantId, sessionId) {
+    if (sessionId) {
+      const list = this.sessions.get(sessionId);
+      if (!list) return false;
+      const idx = list.findIndex((g) => g.id === grantId);
+      if (idx !== -1) {
+        list.splice(idx, 1);
+        if (list.length === 0) this.sessions.delete(sessionId);
+        return true;
+      }
+      return false;
+    }
+
+    // Search across all sessions if sessionId not specified
+    for (const [sId, list] of this.sessions.entries()) {
+      const idx = list.findIndex((g) => g.id === grantId);
+      if (idx !== -1) {
+        list.splice(idx, 1);
+        if (list.length === 0) this.sessions.delete(sId);
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Garbage-collect expired and exhausted grants across sessions.
+   * Cleans up empty session entries to prevent memory leaks.
+   *
+   * @param {{ now?: number, sessionId?: string }} [options]
+   * @returns {{ removedCount: number, remainingCount: number, emptySessionsPruned: number }}
+   */
+  prune(options = {}) {
+    const now = options.now || Date.now();
+    let removedCount = 0;
+    let remainingCount = 0;
+    let emptySessionsPruned = 0;
+
+    const targetSessions = options.sessionId
+      ? [options.sessionId]
+      : Array.from(this.sessions.keys());
+
+    for (const sId of targetSessions) {
+      const list = this.sessions.get(sId);
+      if (!list) continue;
+
+      const active = [];
+      for (const grant of list) {
+        if (this.isExpired(grant, now) || this.isExhausted(grant)) {
+          removedCount += 1;
+        } else {
+          active.push(grant);
+          remainingCount += 1;
+        }
+      }
+
+      if (active.length === 0) {
+        this.sessions.delete(sId);
+        emptySessionsPruned += 1;
+      } else {
+        this.sessions.set(sId, active);
+      }
+    }
+
+    return { removedCount, remainingCount, emptySessionsPruned };
+  }
+
+  /**
+   * Start periodic timer-based background pruning.
+   * @param {number} [intervalMs=60000]
+   */
+  startPeriodicPrune(intervalMs = 60000) {
+    this.stopPeriodicPrune();
+    this._pruneTimer = setInterval(() => {
+      this.prune();
+    }, intervalMs);
+    if (this._pruneTimer && typeof this._pruneTimer.unref === "function") {
+      this._pruneTimer.unref();
+    }
+  }
+
+  /**
+   * Stop periodic timer-based background pruning.
+   */
+  stopPeriodicPrune() {
+    if (this._pruneTimer) {
+      clearInterval(this._pruneTimer);
+      this._pruneTimer = null;
+    }
+  }
+
+  /**
+   * Clear grants for a session or entirely.
+   * @param {string} [sessionId]
+   */
+  clear(sessionId) {
+    if (sessionId) {
+      this.sessions.delete(sessionId);
+    } else {
+      this.sessions.clear();
+    }
+  }
+}
+

package/lib/index.js

@@ -133,6 +133,24 @@ export function apply(ctx, config) {
 
 export { SecurityEngine } from "./engine.js";
 export { BandsEngine } from "./bands.js";
-export { CircuitBreaker } from "./breaker.js";
+export {
+  CircuitBreaker,
+  CIRCUIT_STATE_ACTIVE,
+  CIRCUIT_STATE_TRIPPED,
+  CIRCUIT_STATE_RESUMED,
+} from "./breaker.js";
+export {
+  SessionGrantStore,
+  DEFAULT_GRANT_TTL_MS,
+  DEFAULT_GRANT_MAX_USES,
+  matchGrantCriteria,
+} from "./grants.js";
+export {
+  canonicalizeCall,
+  canonicalString,
+  hashCall,
+  sortKeys,
+} from "./canonical.js";
 export { expandHome } from "./paths.js";
 export { splitSubcommands } from "./tokenizer.js";
+

package/lib/inspect.js

@@ -1,10 +1,54 @@
+
+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 { DYNAMIC_MARKER, HEREDOC_OPS, REDIR_OPS, SPLIT_OPS, tokenize, readCommandSubstitution, readBacktick, readParameterExpansion } from "./tokenizer.js";
-import { expandHome } from "./paths.js";
+import { expandHome, isProtectedConfigPath } 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 } from "./paths.js";
+export { expandHome, isProtectedConfigPath } from "./paths.js";
 
 // Pure command/path inspector for dsh-approval-gate.
 // No Cordis imports: unit tests run this without the harness.
@@ -40,19 +84,7 @@ export function basename(path) {
 
 export function isProtectedPath(path, env = process.env) {
   if (typeof path !== "string" || path.trim() === "") return false;
-  const expanded = expandHome(path, env);
-  const normalized = expanded.replace(/\\/g, "/");
-  if (normalized.includes("/etc/sudoers.d/")) return true;
-  const base = basename(normalized);
-  if (base === ".env" || base.startsWith(".env.")) return true;
-  if (/^credentials\.ya?ml$/i.test(base)) return true;
-  if (/^settings\.ya?ml$/i.test(base)) return true;
-  if (base === "cordis.patch.yml") return true;
-  if (/\.(pem|key|crt|p12|pfx)$/i.test(base)) return true;
-  if (/^(id_rsa|id_ed25519|id_ecdsa)$/.test(base)) return true;
-  if (/^(shadow|gshadow|shadow-|gshadow-|sudoers|authorized_keys2?)$/i.test(base)) return true;
-  if (/(?:^|[._-])(?:secret|token|credential|passwd|api[_-]?key)(?:$|[._-])/i.test(base)) return true;
-  return false;
+  return isProtectedConfigPath(path, env);
 }
 
 function wordsOf(seg) {
@@ -190,6 +222,18 @@ function inspectArgv(argv, depth, hasHeredoc) {
   const cmd = basename(argv[0]);
   const rest = argv.slice(1);
 
+  const envHit = checkEnvExfiltration(argv, argv.join(" "));
+  if (envHit.deny) {
+    return deny("env-dump-leak", envHit.detail || argv.join(" "));
+  }
+
+  if (cmd === "env") {
+    const sub = rest.filter(a => !a.startsWith("-") && !a.includes("="));
+    if (sub.length > 0) {
+      return inspectArgv(sub, depth, hasHeredoc);
+    }
+  }
+
   if (cmd === "sudo" || cmd === "command" || cmd === "builtin" || cmd === "nohup" || cmd === "time" || cmd === "nice" || cmd === "ionice" || cmd === "stdbuf" || cmd === "timeout") {
     const arity = new Set(["-u", "--user", "-g", "--group", "-p", "-s", "--signal", "-k", "--kill-after", "-o", "-e", "-i"]);
     let next = skipWrapper(rest, arity);
@@ -456,6 +500,11 @@ export function inspectBashCommand(command, depth) {
 
   const segs = splitSegments(tokens);
   for (const seg of segs) {
+    const rawWords = wordsOf(seg);
+    const envHit = checkEnvExfiltration(rawWords, command);
+    if (envHit.deny) {
+      return deny("env-dump-leak", envHit.detail || command);
+    }
     const wordTokens = wordTokensOf(seg);
     const heredocs = seg.filter(function (t) { return t.kind === "heredoc"; });
     const argv = stripPrefixes(wordsOf(seg));

package/lib/messages.js

@@ -182,6 +182,7 @@ const RULE_KEYS = Object.freeze({
   "eval": "ruleEval",
   "nested-shell": "ruleNestedShell",
   "interpreter-payload": "ruleInterpreterPayload",
+  "env-dump-leak": "ruleEnvDumpLeak",
 });
 
 const ASK_KEYS = Object.freeze({

package/lib/paths.js

@@ -1,5 +1,55 @@
 // lib/paths.js
-// Home path expansion and path boundary helpers for dsh-approval-gate.
+// Cross-platform path normalization, home expansion, canonicalization, and path boundary traversal protection for dsh-approval-gate.
+
+const PROTECTED_BASENAMES = new Set([
+  ".bashrc",
+  ".bash_profile",
+  ".bash_login",
+  ".profile",
+  ".zshrc",
+  ".zprofile",
+  ".zshenv",
+  ".cshrc",
+  "cordis.patch.yml",
+]);
+
+/**
+ * Normalizes Windows and POSIX path separators to uniform forward slashes.
+ * Collapses redundant slashes and standardizes Windows drive letters.
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+export function normalizeSeparators(p) {
+  if (typeof p !== "string") return "";
+  let s = p.trim();
+  if (s === "") return "";
+
+  // Check UNC network share (e.g. \\server\share or //server/share)
+  const isUnc = /^([\\/]{2})([^\\/]+)/.test(s);
+
+  // Convert all backslashes to forward slashes
+  s = s.replace(/\\/g, "/");
+
+  // Collapse multiple consecutive slashes
+  if (isUnc) {
+    s = "//" + s.slice(2).replace(/\/+/g, "/");
+  } else {
+    s = s.replace(/\/+/g, "/");
+  }
+
+  // Normalize Windows drive letter: c:/ -> C:/
+  s = s.replace(/^([a-zA-Z]):(\/|$)/, (_, drive, rest) => `${drive.toUpperCase()}:${rest}`);
+
+  // Strip trailing slash unless root / or C:/
+  if (s.length > 1 && s.endsWith("/")) {
+    if (!/^(?:\/|[A-Za-z]:\/)$/.test(s)) {
+      s = s.slice(0, -1);
+    }
+  }
+
+  return s;
+}
 
 /**
  * Expand `~`, `${HOME}`, `$HOME`, and `%USERPROFILE%` at the start of or within a path.
@@ -23,3 +73,198 @@ export function expandHome(p, env = process.env) {
   res = res.replace(/%USERPROFILE%/gi, cleanHome);
   return res;
 }
+
+/**
+ * Canonicalizes a path resolving dot and dot-dot segments without disk I/O.
+ *
+ * @param {string} p
+ * @param {{ env?: Record<string, string|undefined> }} [options]
+ * @returns {string}
+ */
+export function canonicalizeFsPath(p, options = {}) {
+  if (typeof p !== "string") return "";
+  let s = expandHome(p, options.env);
+  s = normalizeSeparators(s);
+  if (!s) return "";
+
+  // Check prefix: / (root), C:/ (Windows root), //server/share (UNC), or relative
+  let prefix = "";
+  if (s.startsWith("//")) {
+    const m = s.match(/^(\/\/[^/]+\/[^/]+)(?:\/|$)/);
+    if (m) {
+      prefix = m[1];
+      s = s.slice(prefix.length);
+    }
+  } else if (/^[A-Za-z]:\//.test(s)) {
+    prefix = s.slice(0, 3);
+    s = s.slice(3);
+  } else if (s.startsWith("/")) {
+    prefix = "/";
+    s = s.slice(1);
+  }
+
+  const rawSegments = s.split("/");
+  const stack = [];
+
+  for (const seg of rawSegments) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (stack.length > 0 && stack[stack.length - 1] !== "..") {
+        stack.pop();
+      } else if (!prefix) {
+        stack.push("..");
+      }
+      // If there is an absolute prefix (e.g. / or C:/), .. at root cannot escape above root
+    } else {
+      stack.push(seg);
+    }
+  }
+
+  const resolvedBody = stack.join("/");
+  if (!prefix) {
+    return resolvedBody || ".";
+  }
+  if (!resolvedBody) {
+    return prefix;
+  }
+  return prefix.endsWith("/") ? `${prefix}${resolvedBody}` : `${prefix}/${resolvedBody}`;
+}
+
+/**
+ * Checks whether a path contains directory traversal sequences attempting to escape baseDir.
+ *
+ * @param {string} p
+ * @param {string} [baseDir]
+ * @returns {boolean}
+ */
+export function isPathTraversal(p, baseDir = "/workspace") {
+  if (typeof p !== "string" || p.trim() === "") return false;
+
+  // Detect null byte injection
+  if (p.includes("\0") || /%00/i.test(p)) return true;
+
+  // 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));
+
+  let candidate = "";
+  if (isAbsolute) {
+    candidate = canonicalizeFsPath(p);
+  } else {
+    candidate = canonicalizeFsPath(`${normBase}/${p}`);
+  }
+
+  if (candidate === normBase) return false;
+  return !(candidate.startsWith(normBase.endsWith("/") ? normBase : `${normBase}/`));
+}
+
+/**
+ * Safely resolves a path relative to a base directory, verifying boundaries.
+ *
+ * @param {string} p
+ * @param {string} [baseDir]
+ * @returns {{ safe: boolean, path: string, canonical: string, reason?: string }}
+ */
+export function resolveSafePath(p, baseDir = "/workspace") {
+  if (isPathTraversal(p, baseDir)) {
+    return {
+      safe: false,
+      reason: "path-traversal-escape",
+      path: p,
+      canonical: canonicalizeFsPath(p),
+    };
+  }
+  const normBase = canonicalizeFsPath(baseDir);
+  const isAbsolute = /^(?:\/|[A-Za-z]:\/|\/\/)/.test(normalizeSeparators(p));
+  const resolved = isAbsolute ? canonicalizeFsPath(p) : canonicalizeFsPath(`${normBase}/${p}`);
+  return {
+    safe: true,
+    path: p,
+    canonical: resolved,
+  };
+}
+
+/**
+ * Checks whether a path targets protected system, git, ssh, or secret configuration.
+ *
+ * @param {string} p
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {boolean}
+ */
+export function isProtectedConfigPath(p, env = process.env) {
+  if (typeof p !== "string" || p.trim() === "") return false;
+
+  const expanded = expandHome(p, env);
+  const normalized = canonicalizeFsPath(expanded);
+  const lower = normalized.toLowerCase();
+
+  // 1. .git internal tree
+  if (
+    lower === ".git" ||
+    lower.startsWith(".git/") ||
+    lower.endsWith("/.git") ||
+    lower.includes("/.git/")
+  ) {
+    return true;
+  }
+
+  // 2. .ssh directory and key files
+  if (
+    lower === ".ssh" ||
+    lower.startsWith(".ssh/") ||
+    lower.endsWith("/.ssh") ||
+    lower.includes("/.ssh/")
+  ) {
+    return true;
+  }
+
+  // 3. System auth and security files
+  if (
+    lower === "/etc/sudoers" ||
+    lower.includes("/etc/sudoers.d/") ||
+    lower === "/etc/shadow" ||
+    lower === "/etc/gshadow" ||
+    lower.includes("/etc/pam.d/")
+  ) {
+    return true;
+  }
+
+  // 4. Shell startup files
+  const parts = normalized.split("/");
+  const base = parts[parts.length - 1];
+  const baseLower = base.toLowerCase();
+
+  if (PROTECTED_BASENAMES.has(baseLower)) {
+    return true;
+  }
+
+  // 5. Env files (.env, .env.local, .env.prod)
+  if (baseLower === ".env" || baseLower.startsWith(".env.")) {
+    return true;
+  }
+
+  // 6. Credentials and settings
+  if (/^credentials\.ya?ml$/i.test(base) || /^settings\.ya?ml$/i.test(base)) {
+    return true;
+  }
+
+  // 7. Certificates and keys
+  if (/\.(pem|key|crt|p12|pfx)$/i.test(base)) {
+    return true;
+  }
+
+  // 8. SSH key filenames anywhere
+  if (/^(id_rsa|id_ed25519|id_ecdsa|authorized_keys2?)$/i.test(base)) {
+    return true;
+  }
+
+  // 9. Generic secrets / tokens / passwords
+  if (/(?:^|[._-])(?:secret|token|credential|passwd|api[_-]?key)(?:$|[._-])/i.test(baseLower)) {
+    return true;
+  }
+
+  return false;
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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",