@goodandready/dsh-approval-gate 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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).

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/package.json

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