@goodandready/dsh-approval-gate 0.1.24 → 0.1.26

package/lib/network-sandbox.js

@@ -0,0 +1,147 @@
+// lib/network-sandbox.js
+// Mapping Network Egress Policies to DSH Sandbox Modes (#41).
+// Controls outbound socket and HTTP connections based on shell.sandboxMode.
+
+import { isLoopbackHost } from "./loopback.js";
+
+export const NETWORK_POLICIES = Object.freeze({
+  DENY_ALL: "deny-all",
+  WHITELIST_ONLY: "whitelist-only",
+  ALLOW_ALL: "allow-all",
+});
+
+export const SANDBOX_NETWORK_MAP = Object.freeze({
+  "read-only": NETWORK_POLICIES.DENY_ALL,
+  readonly: NETWORK_POLICIES.DENY_ALL,
+  isolated: NETWORK_POLICIES.DENY_ALL,
+  "workspace-write": NETWORK_POLICIES.WHITELIST_ONLY,
+  standard: NETWORK_POLICIES.WHITELIST_ONLY,
+  hybrid: NETWORK_POLICIES.WHITELIST_ONLY,
+  "danger-full-access": NETWORK_POLICIES.ALLOW_ALL,
+  full: NETWORK_POLICIES.ALLOW_ALL,
+});
+
+/**
+ * Resolves network egress policy from DSH sandbox mode (#41).
+ *
+ * @param {string} [sandboxMode]
+ * @param {Record<string, any>} [options]
+ * @returns {"deny-all" | "whitelist-only" | "allow-all"}
+ */
+export function resolveNetworkPolicy(sandboxMode, options = {}) {
+  if (options.policy && Object.values(NETWORK_POLICIES).includes(options.policy)) {
+    return options.policy;
+  }
+  const mode = String(sandboxMode || "").toLowerCase().trim();
+  return SANDBOX_NETWORK_MAP[mode] || options.defaultPolicy || NETWORK_POLICIES.WHITELIST_ONLY;
+}
+
+/**
+ * Normalizes a destination host / URL to hostname and port.
+ * @param {string} destination
+ * @returns {{ hostname: string, port: number }}
+ */
+export function parseDestination(destination) {
+  if (!destination || typeof destination !== "string") {
+    return { hostname: "", port: 80 };
+  }
+  const clean = destination.trim();
+  try {
+    if (clean.includes("://")) {
+      const u = new URL(clean);
+      return { hostname: u.hostname.toLowerCase(), port: Number(u.port) || (u.protocol === "https:" ? 443 : 80) };
+    }
+  } catch (_e) {}
+
+  // host:port format
+  if (clean.includes(":")) {
+    const [h, p] = clean.split(":");
+    return { hostname: h.toLowerCase(), port: Number(p) || 80 };
+  }
+
+  return { hostname: clean.toLowerCase(), port: 80 };
+}
+
+/**
+ * Checks whether outbound network access to destination is allowed (#41).
+ *
+ * @param {string} destination - Host, host:port, or full URL
+ * @param {string} [sandboxMode] - Active DSH sandbox mode
+ * @param {{
+ *   whitelist?: string[],
+ *   allowLoopback?: boolean,
+ *   policy?: string,
+ * }} [options]
+ * @returns {{
+ *   allowed: boolean,
+ *   policy: string,
+ *   destination: string,
+ *   hostname: string,
+ *   reason?: string
+ * }}
+ */
+export function checkNetworkAccess(destination, sandboxMode, options = {}) {
+  const policy = resolveNetworkPolicy(sandboxMode, options);
+  const { hostname } = parseDestination(destination);
+
+  // 1. Loopback check (allowed by default for internal services unless explicitly blocked)
+  const isLoopback = isLoopbackHost(hostname);
+  if (isLoopback && options.allowLoopback !== false) {
+    return {
+      allowed: true,
+      policy,
+      destination,
+      hostname,
+      reason: "loopback-allowed",
+    };
+  }
+
+  // 2. Deny-all policy (read-only sandbox mode)
+  if (policy === NETWORK_POLICIES.DENY_ALL) {
+    return {
+      allowed: false,
+      policy,
+      destination,
+      hostname,
+      reason: "sandbox-read-only-network-denied",
+    };
+  }
+
+  // 3. Allow-all policy (danger-full-access sandbox mode)
+  if (policy === NETWORK_POLICIES.ALLOW_ALL) {
+    return {
+      allowed: true,
+      policy,
+      destination,
+      hostname,
+      reason: "danger-full-access-unrestricted",
+    };
+  }
+
+  // 4. Whitelist-only policy (workspace-write / standard sandbox mode)
+  const whitelist = Array.isArray(options.whitelist) ? options.whitelist : [];
+  const isWhitelisted = whitelist.some((entry) => {
+    const entryHost = String(entry).toLowerCase().trim();
+    if (entryHost === hostname) return true;
+    if (entryHost.startsWith("*.") && hostname.endsWith(entryHost.slice(1))) return true;
+    return false;
+  });
+
+  if (isWhitelisted) {
+    return {
+      allowed: true,
+      policy,
+      destination,
+      hostname,
+      reason: "whitelist-allowed",
+    };
+  }
+
+  return {
+    allowed: false,
+    policy,
+    destination,
+    hostname,
+    reason: "not-in-network-whitelist",
+  };
+}

package/lib/race-decision.js

@@ -0,0 +1,180 @@
+// lib/race-decision.js
+// Asynchronous Race Decision & Pre-emption Claim (#50, #51).
+// Races human decision against host timeout and enables fast LLM pre-emption claim.
+
+export const DEFAULT_HUMAN_TIMEOUT_MS = 60000;
+
+export const RACE_WINNERS = Object.freeze({
+  HUMAN: "human",
+  TIMEOUT: "timeout",
+  CLAIM: "claim",
+});
+
+/**
+ * Handle coordinating human decision, host timeout, and pre-emption claims (#50, #51).
+ */
+export class RaceHumanHandle {
+  /**
+   * @param {{
+   *   timeoutMs?: number,
+   *   timeoutAction?: "allow" | "deny" | "ask",
+   *   lockedAsk?: boolean,
+   *   onClaim?: (verdict: string, reason: string) => void,
+   *   onTimeout?: () => void,
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.timeoutMs = typeof options.timeoutMs === "number" ? options.timeoutMs : DEFAULT_HUMAN_TIMEOUT_MS;
+    this.timeoutAction = options.timeoutAction || "deny";
+    this.lockedAsk = Boolean(options.lockedAsk);
+    this.onClaim = options.onClaim || null;
+    this.onTimeout = options.onTimeout || null;
+
+    this.settled = false;
+    this.winner = null;
+    this.startTime = Date.now();
+    this.timer = null;
+
+    this._resolve = null;
+    this._reject = null;
+
+    this.promise = new Promise((resolve, reject) => {
+      this._resolve = resolve;
+      this._reject = reject;
+    });
+
+    if (this.timeoutMs > 0 && this.timeoutMs < Infinity) {
+      this.timer = setTimeout(() => {
+        this._handleTimeout();
+      }, this.timeoutMs);
+    }
+  }
+
+  isSettled() {
+    return this.settled;
+  }
+
+  /**
+   * Pre-empts open human confirmation dialog when fast LLM or reviewer arrives at confident verdict (#51).
+   *
+   * @param {"allow" | "deny" | "ask"} outcome
+   * @param {string} [reason="pre-emption-claim"]
+   * @returns {{ claimed: boolean, reason?: string, winner?: string }}
+   */
+  claim(outcome, reason = "pre-emption-claim") {
+    if (this.settled) {
+      return { claimed: false, reason: "already-settled", winner: this.winner };
+    }
+
+    // Critical lockedAsk operations cannot be auto-claimed as allow
+    if (this.lockedAsk && outcome === "allow") {
+      return { claimed: false, reason: "locked-ask-cannot-be-claimed-as-allow" };
+    }
+
+    this._settle(RACE_WINNERS.CLAIM, {
+      winner: RACE_WINNERS.CLAIM,
+      verdict: outcome,
+      reason,
+      elapsedMs: Date.now() - this.startTime,
+    });
+
+    if (typeof this.onClaim === "function") {
+      this.onClaim(outcome, reason);
+    }
+
+    return { claimed: true, verdict: outcome, reason };
+  }
+
+  /**
+   * Resolves decision from human approval input.
+   * @param {Record<string, any> | string} decision
+   */
+  resolveHuman(decision) {
+    if (this.settled) return false;
+    const verdict = typeof decision === "string" ? decision : (decision?.verdict || "allow");
+    this._settle(RACE_WINNERS.HUMAN, {
+      winner: RACE_WINNERS.HUMAN,
+      verdict,
+      decision: typeof decision === "object" ? decision : { verdict },
+      elapsedMs: Date.now() - this.startTime,
+    });
+    return true;
+  }
+
+  /**
+   * Aborts the race decision handle.
+   * @param {string} [reason="aborted"]
+   */
+  abort(reason = "aborted") {
+    if (this.settled) return false;
+    this._settle(RACE_WINNERS.TIMEOUT, {
+      winner: RACE_WINNERS.TIMEOUT,
+      verdict: "deny",
+      reason,
+      elapsedMs: Date.now() - this.startTime,
+    });
+    return true;
+  }
+
+  /**
+   * @private
+   */
+  _handleTimeout() {
+    if (this.settled) return;
+
+    // Locked ask operations must fail closed on timeout
+    const resolvedVerdict = this.lockedAsk ? "deny" : this.timeoutAction;
+
+    if (typeof this.onTimeout === "function") {
+      this.onTimeout();
+    }
+
+    this._settle(RACE_WINNERS.TIMEOUT, {
+      winner: RACE_WINNERS.TIMEOUT,
+      verdict: resolvedVerdict,
+      reason: "host-timeout-expired",
+      elapsedMs: Date.now() - this.startTime,
+    });
+  }
+
+  /**
+   * @private
+   */
+  _settle(winner, result) {
+    if (this.settled) return;
+    this.settled = true;
+    this.winner = winner;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this._resolve) {
+      this._resolve(result);
+    }
+  }
+}
+
+/**
+ * Races human decision against host timeout and optional fast claims (#50, #51).
+ *
+ * @param {Promise<any>} humanPromise
+ * @param {ConstructorParameters<typeof RaceHumanHandle>[0]} [options]
+ * @returns {Promise<{
+ *   winner: "human" | "timeout" | "claim",
+ *   verdict: string,
+ *   elapsedMs: number,
+ *   reason?: string,
+ *   decision?: any
+ * }>}
+ */
+export async function raceHumanDecision(humanPromise, options = {}) {
+  const handle = new RaceHumanHandle(options);
+
+  if (humanPromise && typeof humanPromise.then === "function") {
+    humanPromise
+      .then((res) => handle.resolveHuman(res))
+      .catch((err) => handle.abort(err?.message || "human-error"));
+  }
+
+  return handle.promise;
+}

package/lib/rules-hmr.js

@@ -0,0 +1,132 @@
+// lib/rules-hmr.js
+// Hot Module Reloading for Security Rules (#43).
+// Watches .dsh/rules.yaml and declarative rule definitions using Node.js stdlib fs watchers.
+// Recompiles rules in-memory atomically without dropping active sessions or restarting dsh.
+
+import fs from "node:fs";
+
+export const DEFAULT_HMR_DEBOUNCE_MS = 150;
+
+/**
+ * Manages atomic hot reload watchers for rule definitions (#43).
+ */
+export class RulesHmrWatcher {
+  /**
+   * @param {{ debounceMs?: number, logger?: any }} [options]
+   */
+  constructor(options = {}) {
+    this.debounceMs = options.debounceMs || DEFAULT_HMR_DEBOUNCE_MS;
+    this.logger = options.logger || null;
+    /** @type {Map<string, fs.FSWatcher>} */
+    this.watchers = new Map();
+    /** @type {NodeJS.Timeout | null} */
+    this.debounceTimer = null;
+    this.reloading = false;
+  }
+
+  /**
+   * Attaches file watchers for declarative rules files.
+   *
+   * @param {any} rulesEngine - Instance of DeclarativeRulesEngine
+   * @param {string[]} filePaths - Files or directories to watch
+   * @param {(info: { path: string, timestamp: number }) => void} [onReload]
+   * @returns {number} Count of successfully watched paths
+   */
+  watch(rulesEngine, filePaths = [], onReload = null) {
+    if (!rulesEngine || !Array.isArray(filePaths)) return 0;
+    let watchedCount = 0;
+
+    for (const targetPath of filePaths) {
+      if (!targetPath || typeof targetPath !== "string") continue;
+      if (this.watchers.has(targetPath)) continue;
+
+      try {
+        if (!fs.existsSync(targetPath)) continue;
+
+        const watcher = fs.watch(targetPath, { persistent: false }, (eventType, filename) => {
+          this._handleFileChange(rulesEngine, targetPath, onReload);
+        });
+
+        watcher.on("error", (err) => {
+          if (this.logger) this.logger.warn?.(`RulesHmrWatcher error on ${targetPath}:`, err);
+          this.unwatch(targetPath);
+        });
+
+        this.watchers.set(targetPath, watcher);
+        watchedCount += 1;
+      } catch (err) {
+        if (this.logger) this.logger.warn?.(`Failed to watch ${targetPath}:`, err);
+      }
+    }
+
+    return watchedCount;
+  }
+
+  /**
+   * Unwatches a specific file path.
+   * @param {string} targetPath
+   */
+  unwatch(targetPath) {
+    const watcher = this.watchers.get(targetPath);
+    if (watcher) {
+      try {
+        watcher.close();
+      } catch (_e) {}
+      this.watchers.delete(targetPath);
+    }
+  }
+
+  /**
+   * Closes all active file watchers.
+   */
+  close() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    for (const [p, watcher] of this.watchers.entries()) {
+      try {
+        watcher.close();
+      } catch (_e) {}
+    }
+    this.watchers.clear();
+  }
+
+  /**
+   * @private
+   */
+  _handleFileChange(rulesEngine, targetPath, onReload) {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      this._triggerReload(rulesEngine, targetPath, onReload);
+    }, this.debounceMs);
+  }
+
+  /**
+   * @private
+   */
+  _triggerReload(rulesEngine, targetPath, onReload) {
+    if (this.reloading) return;
+    this.reloading = true;
+
+    try {
+      if (typeof rulesEngine.reload === "function") {
+        rulesEngine.reload();
+      } else if (typeof rulesEngine.loadRules === "function") {
+        rulesEngine.loadRules();
+      }
+
+      if (typeof onReload === "function") {
+        onReload({ path: targetPath, timestamp: Date.now() });
+      }
+    } catch (err) {
+      if (this.logger) this.logger.error?.(`Failed to reload rules for ${targetPath}:`, err);
+    } finally {
+      this.reloading = false;
+    }
+  }
+}

package/lib/timeline-service.js

@@ -0,0 +1,252 @@
+// lib/timeline-service.js
+// Session Audit Timeline and WebServer REST Service for DSH Approval Gate (#82, #60, #74, #86).
+
+import { generateDiffLines, groupHunks, formatUnifiedDiff } from "./diff-viewer.js";
+
+/**
+ * @typedef {Object} TimelineEvent
+ * @property {string} id
+ * @property {string} sessionId
+ * @property {string | number} [turnId]
+ * @property {number} timestamp
+ * @property {string} tool
+ * @property {string} [command]
+ * @property {string} [snippet]
+ * @property {'allow' | 'deny' | 'ask' | 'preempted'} verdict
+ * @property {string} [stage]
+ * @property {string} [reason]
+ * @property {number} [durationMs]
+ * @property {number | null} [expiresAt]
+ * @property {number | null} [countdownSec]
+ * @property {Object} [diffMeta]
+ */
+
+/**
+ * TimelineService: records call history per session and exposes query & webServer routes (#82).
+ */
+export class TimelineService {
+  /**
+   * @param {{ maxEventsPerSession?: number, turnCardTracker?: any }} [options]
+   */
+  constructor(options = {}) {
+    this.maxEventsPerSession = options.maxEventsPerSession || 500;
+    this.turnCardTracker = options.turnCardTracker || null;
+    /** @type {Map<string, TimelineEvent[]>} */
+    this._sessions = new Map();
+    this._nextId = 1;
+  }
+
+  /**
+   * Records a security gate event into session timeline (#82).
+   *
+   * @param {Object} raw
+   * @returns {TimelineEvent}
+   */
+  recordEvent(raw) {
+    const sid = String(raw.sessionId || "default");
+    const tid = raw.turnId !== undefined && raw.turnId !== null ? raw.turnId : "active";
+
+    let list = this._sessions.get(sid);
+    if (!list) {
+      list = [];
+      this._sessions.set(sid, list);
+    }
+
+    const id = `evt_${Date.now()}_${this._nextId++}`;
+    const timestamp = raw.timestamp || Date.now();
+    let countdownSec = null;
+    let expiresAt = null;
+
+    if (raw.verdict === "ask" && typeof raw.timeoutMs === "number" && raw.timeoutMs > 0) {
+      expiresAt = timestamp + raw.timeoutMs;
+      countdownSec = Math.max(0, Math.round(raw.timeoutMs / 1000));
+    }
+
+    /** @type {TimelineEvent} */
+    const evt = {
+      id,
+      sessionId: sid,
+      turnId: tid,
+      timestamp,
+      tool: raw.tool || "bash",
+      command: raw.command || "",
+      snippet: raw.snippet || "",
+      verdict: raw.verdict || "allow",
+      stage: raw.stage || "",
+      reason: raw.reason || "",
+      durationMs: raw.durationMs || 0,
+      expiresAt,
+      countdownSec,
+      diffMeta: raw.diffMeta || null,
+    };
+
+    list.push(evt);
+    if (list.length > this.maxEventsPerSession) {
+      list.splice(0, list.length - this.maxEventsPerSession);
+    }
+
+    // Also forward to TurnCardTracker if attached (#86)
+    if (this.turnCardTracker && typeof this.turnCardTracker.recordCall === "function") {
+      this.turnCardTracker.recordCall(sid, tid, {
+        tool: evt.tool,
+        command: evt.command,
+        snippet: evt.snippet,
+        verdict: evt.verdict,
+        reason: evt.reason,
+        durationMs: evt.durationMs,
+        timestamp: evt.timestamp,
+      });
+    }
+
+    return evt;
+  }
+
+  /**
+   * Retrieves timeline events for a given session with optional filtering (#82).
+   *
+   * @param {string} sessionId
+   * @param {Object} [options]
+   * @param {'all' | 'blocked' | 'allowed' | 'ask'} [options.filter='all']
+   * @param {number} [options.limit=100]
+   * @param {number} [options.offset=0]
+   * @returns {{ total: number, events: TimelineEvent[] }}
+   */
+  getEvents(sessionId, options = {}) {
+    const sid = String(sessionId || "default");
+    const list = this._sessions.get(sid) || [];
+    const filter = options.filter || "all";
+    const limit = typeof options.limit === "number" ? Math.max(1, options.limit) : 100;
+    const offset = typeof options.offset === "number" ? Math.max(0, options.offset) : 0;
+
+    let filtered = list;
+    if (filter === "blocked") {
+      filtered = list.filter((e) => e.verdict === "deny");
+    } else if (filter === "allowed") {
+      filtered = list.filter((e) => e.verdict === "allow");
+    } else if (filter === "ask") {
+      filtered = list.filter((e) => e.verdict === "ask");
+    }
+
+    const total = filtered.length;
+    // Return newest first
+    const reversed = filtered.slice().reverse();
+    const paginated = reversed.slice(offset, offset + limit);
+
+    return { total, events: paginated };
+  }
+
+  /**
+   * Clears timeline events for a specific session.
+   *
+   * @param {string} sessionId
+   */
+  clearSession(sessionId) {
+    const sid = String(sessionId || "default");
+    this._sessions.delete(sid);
+  }
+
+  /**
+   * Registers REST HTTP routes on ctx.webServer for browser UI interaction (#82, #74, #86).
+   *
+   * @param {any} ctx Cordis context
+   * @param {Object} [options]
+   * @param {string} [options.prefix='/dsh-approval-gate']
+   */
+  registerRoutes(ctx, options = {}) {
+    const prefix = options.prefix || "/dsh-approval-gate";
+    if (!ctx || !ctx.webServer || typeof ctx.webServer.register !== "function") {
+      return;
+    }
+
+    const jsonResponse = (res, status, data) => {
+      res.writeHead(status, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-cache, no-store, must-revalidate",
+      });
+      res.end(JSON.stringify(data));
+    };
+
+    // Route 1: GET /dsh-approval-gate/timeline
+    const timelineRoute = () =>
+      ctx.webServer.register({
+        path: `${prefix}/timeline`,
+        method: "GET",
+        handler: async (req, res) => {
+          try {
+            const url = new URL(req.url, "http://127.0.0.1");
+            const sid = url.searchParams.get("sessionId") || "default";
+            const filter = url.searchParams.get("filter") || "all";
+            const limit = parseInt(url.searchParams.get("limit") || "100", 10);
+            const data = this.getEvents(sid, { filter, limit });
+            jsonResponse(res, 200, { ok: true, sessionId: sid, ...data });
+          } catch (err) {
+            jsonResponse(res, 500, { ok: false, error: String(err && err.message || err) });
+          }
+        },
+      });
+
+    // Route 2: GET /dsh-approval-gate/turn-card
+    const turnCardRoute = () =>
+      ctx.webServer.register({
+        path: `${prefix}/turn-card`,
+        method: "GET",
+        handler: async (req, res) => {
+          try {
+            const url = new URL(req.url, "http://127.0.0.1");
+            const sid = url.searchParams.get("sessionId") || "default";
+            const tid = url.searchParams.get("turnId") || "active";
+            const lang = url.searchParams.get("lang") || "en";
+            let card = null;
+            if (this.turnCardTracker && typeof this.turnCardTracker.buildTurnCard === "function") {
+              card = this.turnCardTracker.buildTurnCard(sid, tid, { lang });
+            }
+            jsonResponse(res, 200, { ok: true, sessionId: sid, turnId: tid, card });
+          } catch (err) {
+            jsonResponse(res, 500, { ok: false, error: String(err && err.message || err) });
+          }
+        },
+      });
+
+    // Route 3: POST /dsh-approval-gate/diff
+    const diffRoute = () =>
+      ctx.webServer.register({
+        path: `${prefix}/diff`,
+        method: "POST",
+        handler: async (req, res) => {
+          try {
+            let bodyStr = "";
+            req.on("data", (chunk) => { bodyStr += chunk; });
+            req.on("end", () => {
+              try {
+                const parsed = JSON.parse(bodyStr || "{}");
+                const oldText = parsed.oldText || "";
+                const newText = parsed.newText || "";
+                const contextLines = typeof parsed.contextLines === "number" ? parsed.contextLines : 3;
+                const diffLines = generateDiffLines(oldText, newText);
+                const hunks = groupHunks(diffLines, { contextLines });
+                const diffText = formatUnifiedDiff(hunks, {
+                  oldFile: parsed.filename ? `a/${parsed.filename}` : "a/original",
+                  newFile: parsed.filename ? `b/${parsed.filename}` : "b/modified",
+                });
+                jsonResponse(res, 200, { ok: true, hunks, diffText, linesCount: diffLines.length });
+              } catch (parseErr) {
+                jsonResponse(res, 400, { ok: false, error: "invalid-json" });
+              }
+            });
+          } catch (err) {
+            jsonResponse(res, 500, { ok: false, error: String(err && err.message || err) });
+          }
+        },
+      });
+
+    if (typeof ctx.effect === "function") {
+      ctx.effect(timelineRoute, "dsh-approval-gate: timeline route");
+      ctx.effect(turnCardRoute, "dsh-approval-gate: turn-card route");
+      ctx.effect(diffRoute, "dsh-approval-gate: diff route");
+    } else {
+      timelineRoute();
+      turnCardRoute();
+      diffRoute();
+    }
+  }
+}