@goodandready/dsh-approval-gate 0.1.23 → 0.1.25

package/lib/learning.js

@@ -0,0 +1,229 @@
+// lib/learning.js
+// Confirmation Learning with Hard Critical Category Exclusion (#79, #81).
+// Tracks manual user approvals and auto-promotes routine safe operations after N-1 confirmations.
+// Strictly excludes destructive, secret, privilege-escalation, and system-level operations.
+
+import { isCriticalOperation } from "./engine.js";
+
+export const DEFAULT_MIN_CONFIRMATIONS = 2;
+export const DEFAULT_MAX_LEARNED_RULES = 100;
+
+export const EXCLUSION_REASONS = Object.freeze({
+  CRITICAL_OPERATION: "critical-category-excluded",
+  SECRETS_EXCLUDED: "secrets-category-excluded",
+  DESTRUCTIVE_EXCLUDED: "destructive-category-excluded",
+  SYSTEM_PATHS_EXCLUDED: "system-paths-category-excluded",
+  PRIVILEGE_EXCLUDED: "privilege-category-excluded",
+});
+
+const SECRETS_PATTERNS = [
+  /\.env\b/i,
+  /[\\/]\.ssh[\\/]/i,
+  /[\\/]\.aws[\\/]/i,
+  /\/etc\/(?:shadow|gshadow|sudoers)/i,
+  /\b(?:id_rsa|id_ed25519|id_ecdsa|private[._-]?key)\b/i,
+];
+
+const DESTRUCTIVE_PATTERNS = [
+  /\b(?:rm|shred|wipefs)\b/i,
+  /\btruncate\s+-s\s+0\b/i,
+  />\s*\/dev\/(?:null|zero|sd[a-z]|nvme)/i,
+];
+
+const SYSTEM_PATH_PATTERNS = [
+  /^\/(?:etc|boot|sys|proc|root|dev)\b/i,
+  /[\\/](?:Windows[\\/]System32|Program Files)/i,
+];
+
+const PRIVILEGE_PATTERNS = [
+  /\b(?:sudo|su|doas)\b/i,
+  /\bchmod\s+(-[a-zA-Z]*\s+)?(?:777|666)\b/i,
+  /\bchown\s+(-[a-zA-Z]*\s+)?root\b/i,
+];
+
+/**
+ * Checks if an operation is strictly eligible for confirmation learning (#81).
+ *
+ * @param {string} [toolName]
+ * @param {string} [command]
+ * @param {Record<string, any>} [execution]
+ * @returns {{ canLearn: boolean, reason?: string }}
+ */
+export function canLearnOperation(toolName, command, execution) {
+  const args = execution?.arguments || execution || {};
+  const cmd = String(command || args?.command || "").trim();
+  const tool = String(toolName || execution?.name || "").trim();
+  const target = String(
+    args?.TargetFile ||
+    args?.target_file ||
+    args?.targetPath ||
+    args?.path ||
+    args?.file ||
+    ""
+  ).trim();
+
+  // 1. Critical operations check (#52, #81)
+  if (isCriticalOperation(tool, cmd, execution)) {
+    return { canLearn: false, reason: EXCLUSION_REASONS.CRITICAL_OPERATION };
+  }
+
+  // 2. Destructive operations exclusion
+  if (cmd && DESTRUCTIVE_PATTERNS.some((p) => p.test(cmd))) {
+    return { canLearn: false, reason: EXCLUSION_REASONS.DESTRUCTIVE_EXCLUDED };
+  }
+
+  // 3. Secrets and credentials exclusion
+  if ((cmd && SECRETS_PATTERNS.some((p) => p.test(cmd))) || (target && SECRETS_PATTERNS.some((p) => p.test(target)))) {
+    return { canLearn: false, reason: EXCLUSION_REASONS.SECRETS_EXCLUDED };
+  }
+
+  // 4. System paths exclusion
+  if ((cmd && SYSTEM_PATH_PATTERNS.some((p) => p.test(cmd))) || (target && SYSTEM_PATH_PATTERNS.some((p) => p.test(target)))) {
+    return { canLearn: false, reason: EXCLUSION_REASONS.SYSTEM_PATHS_EXCLUDED };
+  }
+
+  // 5. Privilege escalation exclusion
+  if (cmd && PRIVILEGE_PATTERNS.some((p) => p.test(cmd))) {
+    return { canLearn: false, reason: EXCLUSION_REASONS.PRIVILEGE_EXCLUDED };
+  }
+
+  return { canLearn: true };
+}
+
+/**
+ * Normalizes an execution to a stable cache/lookup key for learning.
+ * @param {string} toolName
+ * @param {string} command
+ * @param {Record<string, any>} [args]
+ * @returns {string}
+ */
+export function normalizeLearningKey(toolName, command, args = {}) {
+  const tool = String(toolName || "").trim().toLowerCase();
+  const cmd = String(command || args?.command || "").trim().replace(/\s+/g, " ");
+  if (cmd) return `${tool}:${cmd}`;
+  const target = String(args?.TargetFile || args?.path || args?.file || "").trim();
+  return `${tool}:${target}`;
+}
+
+/**
+ * Manages confirmation counts and learned rules (#79, #81).
+ */
+export class ConfirmationLearner {
+  /**
+   * @param {{ minConfirmations?: number, maxLearnedRules?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.minConfirmations = options.minConfirmations || DEFAULT_MIN_CONFIRMATIONS;
+    this.maxLearnedRules = options.maxLearnedRules || DEFAULT_MAX_LEARNED_RULES;
+    /** @type {Map<string, Map<string, { count: number, learned: boolean, command: string, tool: string, timestamp: number }>>} */
+    this.sessions = new Map();
+  }
+
+  /**
+   * @private
+   */
+  _getSessionMap(sessionId) {
+    const key = sessionId || "default";
+    let map = this.sessions.get(key);
+    if (!map) {
+      map = new Map();
+      this.sessions.set(key, map);
+    }
+    return map;
+  }
+
+  /**
+   * Records a manual human confirmation for an execution.
+   *
+   * @param {string} sessionId
+   * @param {{ name: string, arguments?: any }} execution
+   * @returns {{ learned: boolean, count: number, threshold: number, excluded?: boolean, reason?: string }}
+   */
+  recordConfirmation(sessionId, execution) {
+    const toolName = execution?.name || "";
+    const command = execution?.arguments?.command || "";
+
+    const check = canLearnOperation(toolName, command, execution);
+    if (!check.canLearn) {
+      return { learned: false, count: 0, threshold: this.minConfirmations, excluded: true, reason: check.reason };
+    }
+
+    const sessionMap = this._getSessionMap(sessionId);
+    const key = normalizeLearningKey(toolName, command, execution?.arguments);
+    const existing = sessionMap.get(key) || { count: 0, learned: false, command, tool: toolName, timestamp: Date.now() };
+
+    existing.count += 1;
+    existing.timestamp = Date.now();
+
+    if (existing.count >= this.minConfirmations) {
+      existing.learned = true;
+    }
+
+    sessionMap.set(key, existing);
+
+    // Enforce maxLearnedRules eviction (FIFO)
+    if (sessionMap.size > this.maxLearnedRules) {
+      const oldestKey = sessionMap.keys().next().value;
+      if (oldestKey) sessionMap.delete(oldestKey);
+    }
+
+    return {
+      learned: existing.learned,
+      count: existing.count,
+      threshold: this.minConfirmations,
+      key,
+    };
+  }
+
+  /**
+   * Checks if an execution matches a learned rule in the session.
+   *
+   * @param {string} sessionId
+   * @param {{ name: string, arguments?: any }} execution
+   * @returns {{ learned: boolean, rule?: any }}
+   */
+  isLearned(sessionId, execution) {
+    const toolName = execution?.name || "";
+    const command = execution?.arguments?.command || "";
+
+    // Double-check hard exclusion: critical items can NEVER be learned
+    if (!canLearnOperation(toolName, command, execution).canLearn) {
+      return { learned: false };
+    }
+
+    const sessionMap = this._getSessionMap(sessionId);
+    const key = normalizeLearningKey(toolName, command, execution?.arguments);
+    const entry = sessionMap.get(key);
+
+    if (entry && entry.learned) {
+      return { learned: true, rule: { ...entry, key } };
+    }
+
+    return { learned: false };
+  }
+
+  /**
+   * Returns list of all learned rules for a session.
+   * @param {string} sessionId
+   * @returns {Array<any>}
+   */
+  getLearnedRules(sessionId) {
+    const sessionMap = this._getSessionMap(sessionId);
+    const rules = [];
+    for (const [key, entry] of sessionMap.entries()) {
+      if (entry.learned) {
+        rules.push({ key, ...entry });
+      }
+    }
+    return rules;
+  }
+
+  clearSession(sessionId) {
+    const key = sessionId || "default";
+    this.sessions.delete(key);
+  }
+
+  reset() {
+    this.sessions.clear();
+  }
+}

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/reviewer.js

@@ -0,0 +1,134 @@
+// lib/reviewer.js
+// Independent Second-Model AI Reviewer with Separation of Duties (#62).
+// Prevents an agent from approving its own commands by routing safety reviews to an isolated observer model.
+
+export const SAFETY_REVIEWER_SYSTEM_PROMPT = `You are an independent security reviewer observing an autonomous AI agent.
+Your sole responsibility is to protect user data, credentials, and system integrity.
+The agent cannot approve its own risky actions. You must review the tool call and evidence dossier.
+Deny or ask for confirmation if:
+1. Operations mutate files outside declared project boundaries.
+2. Operations attempt credential leakage, reverse shell, port scanning, or privilege escalation.
+3. Operations cause destructive mass deletion or service termination.
+Always respond in JSON: {"approved": boolean, "verdict": "allow"|"deny"|"ask", "reason": string}`;
+
+export const DEFAULT_REVIEWER_AGENT_ID = "security-reviewer-v1";
+
+/**
+ * Asserts separation of duties: primary agent cannot act as its own reviewer (#62).
+ *
+ * @param {string} agentId - The agent requesting or generating the tool execution
+ * @param {string} reviewerId - The independent reviewer agent id
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function assertSeparationOfDuties(agentId, reviewerId) {
+  const agent = String(agentId || "").trim();
+  const reviewer = String(reviewerId || "").trim();
+
+  if (agent && reviewer && agent.toLowerCase() === reviewer.toLowerCase()) {
+    return {
+      valid: false,
+      error: "self-approval-forbidden: primary agent cannot act as its own security reviewer (#62)",
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Independent Security Reviewer for second-model AI validation (#62).
+ */
+export class IndependentReviewer {
+  /**
+   * @param {{ reviewerId?: string, reviewerClient?: any, fallbackVerdict?: string }} [options]
+   */
+  constructor(options = {}) {
+    this.reviewerId = options.reviewerId || DEFAULT_REVIEWER_AGENT_ID;
+    this.reviewerClient = options.reviewerClient || null;
+    this.fallbackVerdict = options.fallbackVerdict || "ask";
+  }
+
+  /**
+   * Reviews an execution request with separation of duties enforcement (#62).
+   *
+   * @param {{ name: string, arguments?: any }} execution
+   * @param {Record<string, any>} [context]
+   * @returns {Promise<{
+   *   approved: boolean,
+   *   verdict: "allow" | "deny" | "ask",
+   *   reason: string,
+   *   reviewerId: string,
+   *   separationOfDuties: boolean,
+   *   timestamp: number
+   * }>}
+   */
+  async review(execution, context = {}) {
+    const agentId = context?.agentId || context?.agent?.id || execution?.agentId || "agent-main";
+    const reviewerId = context?.reviewerId || this.reviewerId;
+
+    // Enforce Separation of Duties (#62)
+    const sep = assertSeparationOfDuties(agentId, reviewerId);
+    if (!sep.valid) {
+      return {
+        approved: false,
+        verdict: "deny",
+        reason: sep.error,
+        reviewerId,
+        separationOfDuties: false,
+        timestamp: Date.now(),
+      };
+    }
+
+    // If no external model client is configured, return safe fallback
+    if (!this.reviewerClient) {
+      return {
+        approved: false,
+        verdict: this.fallbackVerdict,
+        reason: "no-independent-reviewer-model-configured",
+        reviewerId,
+        separationOfDuties: true,
+        timestamp: Date.now(),
+      };
+    }
+
+    try {
+      const payload = {
+        tool: execution?.name,
+        arguments: execution?.arguments,
+        dossier: context?.dossier,
+        track: context?.track,
+        riskBucket: context?.riskBucket,
+      };
+
+      let response = null;
+      if (typeof this.reviewerClient.classify === "function") {
+        response = await this.reviewerClient.classify(payload, {
+          systemPrompt: SAFETY_REVIEWER_SYSTEM_PROMPT,
+        });
+      } else if (typeof this.reviewerClient === "function") {
+        response = await this.reviewerClient(payload);
+      }
+
+      const verdict = response?.verdict === "allow" ? "allow" : (response?.verdict === "deny" ? "deny" : "ask");
+      const approved = verdict === "allow";
+
+      return {
+        approved,
+        verdict,
+        reason: response?.reason || "independent-reviewer-verdict",
+        reviewerId,
+        separationOfDuties: true,
+        timestamp: Date.now(),
+      };
+    } catch (err) {
+      // Reviewer errors fail closed
+      return {
+        approved: false,
+        verdict: "ask",
+        reason: `independent-reviewer-error: ${err?.message || err}`,
+        reviewerId,
+        separationOfDuties: true,
+        timestamp: Date.now(),
+      };
+    }
+  }
+}