@goodandready/dsh-approval-gate 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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).
+- Security: синтаксический разбор составных цепочек shell-команд `splitSubcommands` по операторам `&&`, `||`, `;`, `|`, `&` с сохранением кавычек и подстановок (Refs: #113).
+- Security: автоматический предохранитель сессии `CircuitBreaker` (блокировка зацикливания агента при 3 подряд или 20 общих отказах с принудительным запросом человека) (Refs: #110).
+- Engine: двухполосная предварительная фильтрация `BandsEngine`: Band 0 (Hard Deny regex) для мгновенной блокировки деструктивных команд и Band 1 (Safe Allow glob) для нулевой задержки на рутинных командах инспекции (Refs: #112).
+- Engine: 5-уровневый каскад принятия решений `SecurityEngine` (P0 Hard-Deny -> P1 Grants -> P2 Static Rules -> P3 LLM -> P4 Human Ask) с координацией предохранителя и правил (Refs: #122).
+
 ## 0.1.5
 
 - Security: block recursive `rm` with uppercase `-R` and `-Rf` flags in compliance with POSIX standard (Refs: #28).

package/lib/bands.js

@@ -0,0 +1,125 @@
+// 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)
+
+export const DEFAULT_DENY_PATTERNS = Object.freeze([
+  /\b(?:nc|ncat|netcat)\s+.*-e\s+/i,
+  /\/dev\/tcp\/\d+\.\d+\.\d+\.\d+\/\d+/i,
+  /\/dev\/udp\/\d+\.\d+\.\d+\.\d+\/\d+/i,
+  /\bmkfs(?:\.[a-z0-9]+)?\s+/i,
+  /\bdd\s+.*of=\/dev\/(?:sd|hd|vd|xvd|nvme|mmcblk|loop|mapper)/i,
+  /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/,
+  /\bchmod\s+(?:-R\s+)?(?:0?777|a\+rwx)\s+\/(?!tmp)/i,
+  /\bchown\s+(?:-R\s+)?root\b/i,
+  /\b(?:shutdown|reboot|poweroff|halt)\s*(?:-|$)/i,
+]);
+
+export const DEFAULT_ALLOW_GLOBS = Object.freeze([
+  "git status*",
+  "git diff*",
+  "git log*",
+  "git branch*",
+  "git show*",
+  "ls*",
+  "pwd*",
+  "cat *",
+  "head *",
+  "tail *",
+  "wc *",
+  "which *",
+  "whereis *",
+  "whoami*",
+  "node --version*",
+  "node -v*",
+  "npm test*",
+  "npm --version*",
+  "npm -v*",
+  "pnpm test*",
+  "pnpm --version*",
+  "pnpm -v*",
+  "yarn test*",
+  "cargo test*",
+  "cargo check*",
+  "cargo --version*",
+  "pytest*",
+  "python --version*",
+  "python3 --version*",
+  "echo *",
+]);
+
+export const DEFAULT_READ_ONLY_TOOLS = Object.freeze([
+  "read",
+  "read_file",
+  "readFile",
+  "view_file",
+  "glob",
+  "grep",
+  "find_files",
+  "search_code",
+  "file_search",
+  "list_dir",
+  "list_directory",
+]);
+
+/**
+ * Compile a prefix-glob into an anchored RegExp.
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+export function compileGlob(pattern) {
+  let source = "";
+  for (const ch of pattern) {
+    if (ch === "*") source += ".*";
+    else if (ch === "?") source += ".";
+    else source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`, "i");
+}
+
+export class BandsEngine {
+  /**
+   * @param {{ denyPatterns?: Array<RegExp|string>, allowGlobs?: Array<RegExp|string>, readOnlyTools?: Array<string> }} [options]
+   */
+  constructor(options = {}) {
+    this.denyPatterns = (options.denyPatterns || DEFAULT_DENY_PATTERNS).map((p) =>
+      typeof p === "string" ? new RegExp(p, "i") : p
+    );
+    this.allowGlobs = (options.allowGlobs || DEFAULT_ALLOW_GLOBS).map((g) =>
+      typeof g === "string" ? compileGlob(g) : g
+    );
+    this.readOnlyTools = new Set(options.readOnlyTools || DEFAULT_READ_ONLY_TOOLS);
+  }
+
+  /**
+   * Evaluates an execution request through Band 0 and Band 1.
+   * @param {string} tool - Tool name
+   * @param {string} [command] - Normalized command text (for bash)
+   * @returns {"deny" | "allow" | "unmatched"}
+   */
+  evaluate(tool, command) {
+    if (this.readOnlyTools.has(tool)) {
+      return "allow";
+    }
+
+    if (typeof command === "string" && command.trim().length > 0) {
+      const text = command.trim();
+
+      // Band 0: Hard Deny
+      for (const pattern of this.denyPatterns) {
+        if (pattern.test(text)) {
+          return "deny";
+        }
+      }
+
+      // Band 1: Safe Allow
+      for (const glob of this.allowGlobs) {
+        if (glob.test(text)) {
+          return "allow";
+        }
+      }
+    }
+
+    return "unmatched";
+  }
+}

package/lib/breaker.js

@@ -0,0 +1,223 @@
+// lib/breaker.js
+// 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,
+   *   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;
+    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();
+  }
+
+  /**
+   * Register a state change listener callback.
+   * @param {(event: CircuitTransitionEvent) => void} fn
+   * @returns {() => void} Unsubscribe function
+   */
+  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: CIRCUIT_STATE_ACTIVE,
+        history: [],
+      };
+      this.sessions.set(key, 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 }));
+  }
+
+  /**
+   * Whether the breaker is currently tripped for this session.
+   * @param {string} [sessionId]
+   * @returns {boolean}
+   */
+  isTripped(sessionId) {
+    const state = this._getOrCreate(sessionId);
+    return Boolean(state && state.tripped);
+  }
+
+  /**
+   * Record a security denial. Returns true if this call tripped the breaker.
+   * @param {string} [sessionId]
+   * @returns {boolean}
+   */
+  countDeny(sessionId) {
+    const key = sessionId || "default";
+    const state = this._getOrCreate(key);
+    state.consecutive += 1;
+    state.total += 1;
+
+    const wasTripped = state.tripped;
+    const isConsecutiveTrip = state.consecutive >= this.maxConsecutive;
+    const isTotalTrip = state.total >= this.maxTotal;
+
+    if ((isConsecutiveTrip || isTotalTrip) && !wasTripped) {
+      state.tripped = true;
+      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;
+  }
+
+  /**
+   * Reset the consecutive counter on an allowed operation.
+   * @param {string} [sessionId]
+   */
+  resetConsecutive(sessionId) {
+    const key = sessionId || "default";
+    const state = this._getOrCreate(key);
+    if (state.consecutive > 0) {
+      state.consecutive = 0;
+    }
+  }
+
+  /**
+   * Fully resume auto-mode after human approval or admin action.
+   * @param {string} [sessionId]
+   * @param {string} [reason="manual-human-resume"]
+   */
+  resume(sessionId, reason = "manual-human-resume") {
+    const key = sessionId || "default";
+    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");
+    }
+  }
+
+  /**
+   * Clear all session tracking states.
+   */
+  clear() {
+    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

@@ -0,0 +1,110 @@
+// lib/engine.js
+// 5-tier Security Decision Engine for dsh-approval-gate.
+// Waterfall:
+// P0: Hard Deny (Bands Band 0 + inspectExecution hard denials + protected files)
+// P1: Session Grants (scoped temporary allowances)
+// P2: Static Rules / Safe Allow (Bands Band 1 + safe read-only commands)
+// P3: Optional Semantic Classifier
+// P4: Human Ask Fallback (uncertain syntax / ambiguous commands / tripped breaker)
+
+import { BandsEngine } from "./bands.js";
+import { CircuitBreaker } from "./breaker.js";
+import { SessionGrantStore } from "./grants.js";
+import { inspectExecution } from "./inspect.js";
+
+export class SecurityEngine {
+  /**
+   * @param {{
+   *   bands?: BandsEngine,
+   *   breaker?: CircuitBreaker,
+   *   inspectConfig?: { toolName?: string, fileWriteTools?: string[] },
+   *   classifier?: ((execution: any, context?: any) => { verdict: "allow"|"deny", reason?: string }),
+   *   grantRegistry?: { decide: (tool: string, args: any, context?: any) => "allow"|"no-match" }
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.bands = options.bands || new BandsEngine(options);
+    this.breaker = options.breaker || new CircuitBreaker(options);
+    this.inspectConfig = options.inspectConfig || {};
+    this.classifier = options.classifier || null;
+    this.grantRegistry = options.grantRegistry || new SessionGrantStore(options);
+  }
+
+  /**
+   * 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 }}
+   */
+  decide(execution, context = {}) {
+    const sessionId = context.sessionId || "default";
+    const toolName = execution && execution.name;
+    const command = execution && execution.arguments && execution.arguments.command;
+
+    // Fast-path Band 0 Hard Deny
+    const bandVerdict = this.bands.evaluate(toolName, command);
+    if (bandVerdict === "deny") {
+      this.breaker.countDeny(sessionId);
+      return { verdict: "deny", stage: "P0", reason: "band-hard-deny", detail: command };
+    }
+
+    // Inspect execution for hard denials and syntax checks
+    const hit = inspectExecution(execution, this.inspectConfig);
+    if (hit.deny) {
+      this.breaker.countDeny(sessionId);
+      return { verdict: "deny", stage: "P0", reason: hit.reason || "hard-deny", detail: hit.detail || hit.snippet };
+    }
+
+    // P1: Session Grants
+    if (this.grantRegistry && typeof this.grantRegistry.decide === "function") {
+      const grantMatch = this.grantRegistry.decide(toolName, execution.arguments, context);
+      if (grantMatch === "allow") {
+        this.breaker.resetConsecutive(sessionId);
+        return { verdict: "allow", stage: "P1", reason: "session-grant" };
+      }
+    }
+
+    // If Circuit Breaker is tripped, suspend auto-mode and force P4 Human Ask
+    if (this.breaker.isTripped(sessionId)) {
+      return {
+        verdict: "ask",
+        stage: "P4",
+        reason: "circuit-breaker-tripped",
+        detail: "Circuit breaker tripped due to repeated security denials. Manual confirmation required."
+      };
+    }
+
+    // P2: Static Rules / Safe Allow
+    if (bandVerdict === "allow") {
+      this.breaker.resetConsecutive(sessionId);
+      return { verdict: "allow", stage: "P2", reason: "safe-allow" };
+    }
+
+    // P3: Optional Semantic Classifier
+    if (this.classifier && typeof this.classifier === "function") {
+      try {
+        const cls = this.classifier(execution, context);
+        if (cls && cls.verdict === "allow") {
+          this.breaker.resetConsecutive(sessionId);
+          return { verdict: "allow", stage: "P3", reason: cls.reason || "classifier-allow" };
+        }
+        if (cls && cls.verdict === "deny") {
+          this.breaker.countDeny(sessionId);
+          return { verdict: "deny", stage: "P3", reason: cls.reason || "classifier-deny" };
+        }
+      } catch (err) {
+        // Classifier error fails closed to P4 Ask
+      }
+    }
+
+    // P4: Human Ask (uncertain syntax or unlisted command)
+    if (hit.ask) {
+      return { verdict: "ask", stage: "P4", reason: hit.reason || "uncertain-syntax", detail: hit.detail || hit.snippet };
+    }
+
+    // Safe default for unclassified commands
+    return { verdict: "allow", stage: "P2", reason: "unmatched-allow" };
+  }
+}
+

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

@@ -130,3 +130,27 @@ export function apply(ctx, config) {
   }
   return mount();
 }
+
+export { SecurityEngine } from "./engine.js";
+export { BandsEngine } from "./bands.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,8 +1,10 @@
 import { DYNAMIC_MARKER, HEREDOC_OPS, REDIR_OPS, SPLIT_OPS, tokenize, readCommandSubstitution, readBacktick, readParameterExpansion } from "./tokenizer.js";
+import { expandHome } from "./paths.js";
 import { askMessage, denyMessage, sessionTag } from "./messages.js";
 
-export { DYNAMIC_MARKER, tokenize } from "./tokenizer.js";
+export { DYNAMIC_MARKER, tokenize, splitSubcommands } from "./tokenizer.js";
 export { askMessage, denyMessage, sessionTag } from "./messages.js";
+export { expandHome } from "./paths.js";
 
 // Pure command/path inspector for dsh-approval-gate.
 // No Cordis imports: unit tests run this without the harness.
@@ -36,11 +38,12 @@ export function basename(path) {
   return parts[parts.length - 1] || "";
 }
 
-export function isProtectedPath(path) {
+export function isProtectedPath(path, env = process.env) {
   if (typeof path !== "string" || path.trim() === "") return false;
-  const normalized = path.replace(/\\/g, "/");
+  const expanded = expandHome(path, env);
+  const normalized = expanded.replace(/\\/g, "/");
   if (normalized.includes("/etc/sudoers.d/")) return true;
-  const base = basename(path);
+  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;

package/lib/paths.js

@@ -0,0 +1,25 @@
+// lib/paths.js
+// Home path expansion and path boundary helpers for dsh-approval-gate.
+
+/**
+ * Expand `~`, `${HOME}`, `$HOME`, and `%USERPROFILE%` at the start of or within a path.
+ *
+ * @param {string} p - Path or string containing path references
+ * @param {Record<string, string|undefined>} [env] - Environment dictionary (defaults to process.env)
+ * @returns {string} Normalized path with home expanded
+ */
+export function expandHome(p, env = process.env) {
+  if (typeof p !== "string" || p.trim() === "") return p;
+  const home = (env && (env.HOME || env.USERPROFILE)) || "";
+  if (!home) return p;
+  const cleanHome = home.replace(/[/\\]+$/, "");
+
+  let res = p;
+  // Expand leading ~ or ~/ or ~\
+  res = res.replace(/^~(?=$|[/\\])/, cleanHome);
+  // Expand ${HOME} and $HOME
+  res = res.replace(/\$\{HOME\}|\$HOME/g, cleanHome);
+  // Expand %USERPROFILE% (Windows)
+  res = res.replace(/%USERPROFILE%/gi, cleanHome);
+  return res;
+}

package/lib/tokenizer.js

@@ -317,3 +317,64 @@ export function tokenize(src) {
   return { ok: true, tokens: tokens };
 }
 
+
+/**
+ * Splits a complex shell command line into individual subcommands across pipeline
+ * and sequence operators (&&, ||, ;, |, &).
+ * Respects single quotes, double quotes, subshells $(...), backticks, and heredocs.
+ *
+ * @param {string} command - Raw shell command
+ * @returns {Array<{ command: string, argv: string[], operator: string|null, tokens: Array<any>, ok: boolean }>}
+ */
+export function splitSubcommands(command) {
+  if (typeof command !== "string" || command.trim() === "") return [];
+  const tok = tokenize(command);
+  const result = [];
+  let currentTokens = [];
+  let prevOp = null;
+
+  function pushSub(tokens, op) {
+    if (!tokens.length) return;
+    const words = tokens
+      .filter((t) => t.kind === "word")
+      .map((t) => t.value);
+    const subStr = tokens
+      .map((t) => {
+        if (t.kind === "heredoc") return `<<${t.marker}`;
+        return t.value;
+      })
+      .join(" ")
+      .trim();
+    result.push({
+      command: subStr,
+      argv: words,
+      operator: op,
+      tokens: tokens,
+      ok: tok.ok,
+    });
+  }
+
+  for (const t of tok.tokens) {
+    if (t.kind === "op" && SPLIT_OPS.has(t.value)) {
+      pushSub(currentTokens, prevOp);
+      currentTokens = [];
+      prevOp = t.value;
+      continue;
+    }
+    currentTokens.push(t);
+  }
+
+  pushSub(currentTokens, prevOp);
+
+  if (result.length === 0 && command.trim().length > 0) {
+    result.push({
+      command: command.trim(),
+      argv: command.trim().split(/\s+/),
+      operator: null,
+      tokens: [],
+      ok: false,
+    });
+  }
+
+  return result;
+}

package/package.json

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