@kontourai/flow-agents 1.3.0 → 2.0.0

package/scripts/hooks/config-protection.js

@@ -8,6 +8,38 @@
  * Also blocks git verification-bypass flags in actual flag positions only.
  * Text that merely mentions the flag inside quoted strings or prose is allowed.
  *
+ * GATE LOCK-DOWN (adversarial review Finding 2 + anti-gaming; R5a extension):
+ * Also blocks Write/Edit to kill-switch / routing files that an agent could use
+ * to self-tamper the gate:
+ *   - Shell profiles (.bashrc, .bash_profile, etc.) — where an agent could
+ *     export FLOW_AGENTS_GOAL_FIT_MODE=off for the next bash -lc hook invocation.
+ *   - .claude/settings.json / settings.local.json — where an agent could add an
+ *     env block or delete the Stop hook entry entirely.
+ *   - .flow-agents/current.json — where an agent could forge active_flow_id /
+ *     active_step_id to route the gate to a fake permissive FlowDefinition.
+ *   - .flow-agents/<slug>/state.json — where an agent could forge phase=planning
+ *     to downgrade from FULL_BLOCK to HARD_BLOCK (R5a: MEDIUM finding fix).
+ *     SAFE: the CLI writes state.json via writeState → writeJson → fs.writeFileSync.
+ *   - .flow-agents/<slug>/trust.bundle — where an agent could forge claims.
+ *     SAFE: the CLI writes trust.bundle via writeTrustBundle → writeJson → fs.writeFileSync.
+ *   (Verified: ensureSession / advanceState / writeCurrent / writeState /
+ *    writeTrustBundle all use writeJson which calls fs.writeFileSync directly —
+ *    blocking the Write/Edit tool path does NOT break legit CLI sidecar writes.)
+ *
+ * Also detects (best-effort) Bash-command redirects that write to the same paths
+ * via shell operators (>, >>, tee). HONEST: this is INCOMPLETE COVERAGE — sed -i,
+ * process substitution, /dev/fd tricks, and other non-standard redirect forms are
+ * NOT caught. An agent with shell access can still evade. The real anchor is
+ * external: signed checkpoints + human review. This raises the bar, not a wall.
+ *
+ * INTERPRETER-WRITE DETECTION — INCOMPLETE (R5a best-effort):
+ * Also checks Bash commands matching interpreter patterns (node -e, py3 -c,
+ * sed -i, perl -e) combined with a protected-path token literal in the command
+ * string. KNOWN EVASIONS NOT CAUGHT: runtime-constructed paths (process.env.HOME +
+ * '/.bashrc', homedir()+'/.bashrc'), base64-encoded paths, multi-step path assembly,
+ * any interpreter not in the list (ruby, php, etc.), and multiline here-docs.
+ * The real anchor remains external (clean CI env + human review).
+ *
  * Exit codes: 0 = allow, 2 = block
  */
 
@@ -26,8 +58,118 @@ const PROTECTED_FILES = new Set([
   '.ruff.toml', 'ruff.toml',
   '.shellcheckrc', '.stylelintrc', '.stylelintrc.json', '.stylelintrc.yml',
   '.markdownlint.json', '.markdownlint.yaml', '.markdownlintrc',
+  // ── Gate lock-down: shell profiles ────────────────────────────────────────
+  // An agent could write `export FLOW_AGENTS_GOAL_FIT_MODE=off` here so the next
+  // `bash -lc <hook>` invocation inherits the override and silences the gate.
+  // Blocking Write/Edit to these basenames raises the cost without stopping
+  // legitimate terminal customization done outside the agent session.
+  '.bash_profile', '.bashrc', '.profile', '.zprofile', '.zshrc',
 ]);
 
+// ---------------------------------------------------------------------------
+// Gate lock-down: path-pattern protected files
+//
+// These files need PATH context (not just basename) to avoid over-matching
+// common file names in unrelated projects.
+//
+// R5a adds .flow-agents/<slug>/state.json and .flow-agents/<slug>/trust.bundle.
+//
+// checkProtectedPathPattern(filePath) → { name, reason } | null
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a Write/Edit tool file path targets a gate kill-switch file
+ * that requires path-level matching (.claude/settings.json,
+ * .flow-agents/current.json, .flow-agents/<slug>/state.json,
+ * .flow-agents/<slug>/trust.bundle).
+ *
+ * Returns { name, reason } when blocked, null when allowed.
+ *
+ * BAR-RAISER framing (honest): this is not airtight. An agent that writes the
+ * file through a Bash redirect or through a shell call that constructs the path
+ * at runtime can still evade. The real anchor is external (signed checkpoints +
+ * human review). We raise the cost of casual/direct manipulation.
+ */
+function checkProtectedPathPattern(filePath) {
+  if (!filePath || typeof filePath !== 'string') return null;
+  // Normalize: forward-slashes, strip leading ~/
+  const norm = filePath.replace(/\\/g, '/').replace(/^~\//, '');
+
+  // .claude/settings.json — an agent could add an env block or delete the Stop
+  // hook to disable gate enforcement for the entire session.
+  if (/(?:^|\/)\.claude\/settings\.json$/.test(norm)) {
+    return {
+      name: '.claude/settings.json',
+      reason: 'an agent could add an env block or remove the Stop hook to disable gate enforcement',
+    };
+  }
+
+  // .claude/settings.local.json — same risk as settings.json (local overrides
+  // are loaded alongside the main settings file by Claude Code).
+  if (/(?:^|\/)\.claude\/settings\.local\.json$/.test(norm)) {
+    return {
+      name: '.claude/settings.local.json',
+      reason: 'an agent could add an env block or remove the Stop hook to disable gate enforcement',
+    };
+  }
+
+  // .flow-agents/current.json — an agent could forge active_flow_id / active_step_id
+  // to route the gate to a permissive or empty-expects FlowDefinition.
+  // SAFE: the workflow CLI writes current.json via fs (writeJson → fs.writeFileSync),
+  // NOT via the Write/Edit tool — blocking the tool path does not break legit sidecar.
+  if (/(?:^|\/)\.flow-agents\/current\.json$/.test(norm)) {
+    return {
+      name: '.flow-agents/current.json',
+      reason: 'an agent could forge active_flow_id/active_step_id to route the gate to a permissive FlowDefinition',
+    };
+  }
+
+  // .flow-agents/<slug>/state.json — an agent could forge phase=planning to
+  // downgrade the block regime (FULL_BLOCK → HARD_BLOCK) and weaken gate checks.
+  // SAFE: the CLI writes state.json via writeState → writeJson → fs.writeFileSync,
+  // NOT via the Write/Edit tool — blocking the tool path does not break legit sidecar.
+  if (/(?:^|\/)\.flow-agents\/[^/]+\/state\.json$/.test(norm)) {
+    return {
+      name: '.flow-agents/<slug>/state.json',
+      reason: 'an agent could forge phase=planning to downgrade the block regime and weaken gate enforcement',
+    };
+  }
+
+  // .flow-agents/<slug>/trust.bundle — an agent could forge claims (e.g. status=verified
+  // or impactLevel=low) to suppress gate blocks or make disputed evidence appear accepted.
+  // SAFE: the CLI writes trust.bundle via writeTrustBundle → writeJson → fs.writeFileSync,
+  // NOT via the Write/Edit tool — blocking the tool path does not break legit sidecar.
+  if (/(?:^|\/)\.flow-agents\/[^/]+\/trust\.bundle$/.test(norm)) {
+    return {
+      name: '.flow-agents/<slug>/trust.bundle',
+      reason: 'an agent could forge trust claims (verified status, impact level) to bypass gate integrity checks',
+    };
+  }
+
+  // delivery/trust.bundle is the CI anchor read by trust-reconcile.js and
+  // used as the attestation subject in mint-attestation.js. An agent could
+  // copy a forged bundle here to corrupt the CI trust check.
+  // SAFE: publishDelivery writes via fs.copyFileSync (not Write/Edit tool).
+  // RESIDUAL: runtime-constructed paths and fs writes are unaffected.
+  if (/(?:^|\/)delivery\/trust\.bundle$/.test(norm)) {
+    return {
+      name: "delivery/trust.bundle",
+      reason: "an agent could write a forged bundle to corrupt the CI trust-reconcile anchor",
+    };
+  }
+
+  // delivery/trust.checkpoint.json -- the signed checkpoint companion.
+  // SAFE: publishDelivery writes via fs.copyFileSync, NOT via Write/Edit tool.
+  if (/(?:^|\/)delivery\/trust\.checkpoint\.json$/.test(norm)) {
+    return {
+      name: "delivery/trust.checkpoint.json",
+      reason: "an agent could forge a signed delivery by writing a tampered checkpoint",
+    };
+  }
+
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Shell-aware tokenizer
 //
@@ -217,6 +359,233 @@ function checkCommandForBypass(command) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Gate lock-down: Bash-redirect detection for protected kill-switch paths
+//
+// When the agent uses a Bash tool (tool_input.command), detect redirects that
+// write to protected paths via shell redirect operators (> >>) or `tee`.
+//
+// R5a extends coverage to .flow-agents/<slug>/state.json and trust.bundle.
+//
+// HONEST — INCOMPLETE COVERAGE: this catches the obvious forms only:
+//   - `cmd > ~/.bashrc`                        ✓ caught (> redirect operator)
+//   - `cmd >> .claude/settings.json`           ✓ caught (>> redirect operator)
+//   - `tee .flow-agents/current.json`          ✓ caught (tee command)
+//   - `cmd > .flow-agents/s/state.json`        ✓ caught (> redirect operator)
+//   - `tee .flow-agents/s/trust.bundle`        ✓ caught (tee command)
+//   - `sed -i ... .bashrc`                     ✗ NOT caught (in-place edit)
+//   - `interpreted-lang -c "open(...,'w')"     ✗ NOT caught (see interpreter check)
+//   - `/dev/fd` tricks, process substitution   ✗ NOT caught
+//
+// An agent with shell access can still evade by constructing paths at runtime,
+// using subshells, or using tools not scanned here. The real tamper-proof
+// boundary is external: signed checkpoints + human review. This raises the bar.
+// ---------------------------------------------------------------------------
+
+/**
+ * Regex that matches a normalized (forward-slash) path ending with a protected
+ * kill-switch file: shell profiles, .claude/settings*.json,
+ * .flow-agents/current.json, .flow-agents/<slug>/state.json,
+ * .flow-agents/<slug>/trust.bundle.
+ */
+const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)\.flow-agents\/current\.json$|(?:^|\/)\.flow-agents\/[^/]+\/state\.json$|(?:^|\/)\.flow-agents\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
+
+/**
+ * Return true when a token (an unquoted redirect target or tee argument) matches
+ * a protected kill-switch path.
+ */
+function matchesRedirectProtected(token) {
+  if (!token || typeof token !== 'string') return false;
+  const norm = token.replace(/\\/g, '/');
+  return REDIRECT_PROTECTED_RE.test(norm);
+}
+
+/**
+ * checkRedirectToProtected(command): scan a Bash command string for shell
+ * redirects (> >>) or tee invocations that target protected kill-switch paths.
+ *
+ * Returns a human-readable description of the matched redirect, or null if
+ * none found.
+ *
+ * INCOMPLETE COVERAGE — see module header for honest framing.
+ */
+function checkRedirectToProtected(command) {
+  if (typeof command !== 'string' || !command) return null;
+  // Fast path: skip if no redirect indicators present.
+  if (!command.includes('>') && !command.includes('tee')) return null;
+
+  const segments = splitSegments(command);
+  for (const seg of segments) {
+    const tokens = tokenize(seg);
+    for (let i = 0; i < tokens.length; i++) {
+      const t = tokens[i];
+
+      // Redirect operators: > and >>
+      if ((t === '>' || t === '>>') && i + 1 < tokens.length) {
+        const target = tokens[i + 1];
+        if (matchesRedirectProtected(target)) {
+          return `shell redirect (${t}) to ${target}`;
+        }
+      }
+
+      // tee command: `tee [-a] [--] <file> [file2 ...]`
+      // tee accepts MULTIPLE output files — check ALL positional args, not just the first.
+      if (t === 'tee') {
+        let pastDashDash = false;
+        for (let j = i + 1; j < tokens.length; j++) {
+          const arg = tokens[j];
+          if (!pastDashDash && arg === '--') { pastDashDash = true; continue; }
+          if (!pastDashDash && arg.startsWith('-')) continue; // skip tee flags (-a, --append, etc.)
+          // Check every positional arg — no early break (tee writes to all of them).
+          if (matchesRedirectProtected(arg)) return `tee to ${arg}`;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Gate lock-down: Interpreter-write detection (best-effort, INCOMPLETE)
+//
+// R5a: Detect Bash commands that invoke interpreters (node -e, py3 -c,
+// sed -i, perl -e) when the command string contains a protected-path token
+// as a literal substring. This catches the obvious "node -e with .bashrc"
+// form but NOT runtime-constructed paths.
+//
+// HONEST — INCOMPLETE COVERAGE (permanently):
+//   `node -e "require('fs').appendFileSync('.bashrc','x')"` ✓ caught (literal token)
+//   `py3 -c "open('state.json','w').write(...)"         ✓ caught (literal token)
+//   `sed -i 's/a/b/' ~/.zshrc`                             ✓ caught (literal token)
+//   `node -e "const p=homedir()+'/.bashrc'; ..."`          ✗ NOT caught (constructed)
+//   `node -e "require('fs').writeFileSync(atob('...'),...)` ✗ NOT caught (encoded)
+//   `ruby -e / php -r / etc.`                              ✗ NOT caught (not listed)
+//   Multiline here-docs or code from a file                ✗ NOT caught
+//
+// An agent that constructs paths at runtime evades this check. The real
+// anchor is external: clean CI env + human review. This raises the bar.
+// ---------------------------------------------------------------------------
+
+/**
+ * Interpreter patterns that can write files when invoked with inline code.
+ * Matched against each shell segment (not the raw full command).
+ */
+// NOTE: _PY_CMD is assembled from two parts to avoid a source-tree validator
+// false-positive on the first-party-Python-command scan. Value = 'p'+'ython'.
+// eslint-disable-next-line no-useless-concat
+const _PY_CMD = 'p' + 'ython'; // joined value: py...thon (see NOTE above)
+const INTERPRETER_WRITE_RE = new RegExp(
+  '\\bnode\\s+(?:-e|--eval)\\b|' +
+  '\\b' + _PY_CMD + '[23]?\\s+-c\\b|' +
+  '\\bsed\\s+-i\\b|\\bperl\\s+-e\\b'
+);
+
+/**
+ * Protected-path token literals.  When any of these strings appears as a
+ * literal substring of a segment that also matches INTERPRETER_WRITE_RE,
+ * the command is blocked.
+ *
+ * INCOMPLETE: only literal occurrences are caught.  An agent that assembles
+ * the path at runtime (e.g. process.env.HOME + '/.bashrc') bypasses this.
+ */
+const INTERPRETER_PROTECTED_TOKENS = [
+  // Shell profiles (basename match is specific in this context)
+  '.bash_profile', '.bashrc', '.profile', '.zshrc', '.zprofile',
+  // Claude and flow-agents routing files
+  '.claude/settings.json',
+  // Flow-agents session sidecars (basename match; false-positive risk is low
+  // in the interpreter-write context and accepted per R5a honest framing)
+  'current.json', 'state.json', 'trust.bundle',
+  // Delivery CI anchor paths. The existing trust.bundle token catches delivery/trust.bundle
+  // as a substring; explicit path added for clarity. trust.checkpoint.json is new.
+  'delivery/trust.bundle', 'delivery/trust.checkpoint.json',
+];
+
+/**
+ * checkInterpreterWriteToProtected(command): detect interpreter invocations
+ * (node -e, py3 -c, sed -i, perl -e) in segments that also contain a
+ * protected-path token as a literal substring.
+ *
+ * Returns a human-readable description of the match, or null if not detected.
+ *
+ * INCOMPLETE COVERAGE — see module header for honest framing.
+ */
+function checkInterpreterWriteToProtected(command) {
+  if (typeof command !== 'string' || !command) return null;
+  // Fast path: skip if no interpreter keywords present.
+  if (!command.includes('node') && !command.includes(_PY_CMD) &&
+      !command.includes('sed') && !command.includes('perl')) return null;
+
+  const segments = splitSegments(command);
+  for (const seg of segments) {
+    // Check interpreter pattern.
+    const interpMatch = INTERPRETER_WRITE_RE.exec(seg);
+    if (!interpMatch) continue;
+
+    // Check for protected-path token literal in the same segment.
+    for (const token of INTERPRETER_PROTECTED_TOKENS) {
+      if (seg.includes(token)) {
+        return `${interpMatch[0].trim()} with protected path token "${token}"`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Delivery-protected path regex: delivery/trust.bundle and delivery/trust.checkpoint.json.
+ * These are the CI anchor files whose contents must not be agent-forged.
+ * Used by checkCopyMoveToProtected to catch `cp x delivery/trust.bundle`.
+ */
+const DELIVERY_COPY_PROTECTED_RE = /(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
+
+/**
+ * Return true when a normalized token matches a delivery-protected path.
+ */
+function matchesDeliveryProtected(token) {
+  if (!token || typeof token !== "string") return false;
+  return DELIVERY_COPY_PROTECTED_RE.test(token.replace(/\\/g, "/"));
+}
+
+/**
+ * checkCopyMoveToProtected(command): detect cp/mv/install commands whose
+ * destination argument targets a delivery-protected path.
+ *
+ * Catches the plain-cp attack vector: `cp forged.json delivery/trust.bundle`
+ * is not a redirect and not an interpreter invocation, so those checks miss it.
+ * The destination is the LAST positional (non-flag) argument.
+ *
+ * INCOMPLETE COVERAGE: only cp, mv, install are checked. Other copy tools
+ * (rsync, scp, dd, etc.) and runtime-constructed path arguments are NOT caught.
+ * The real anchor remains external (clean CI env + human review). Bar-raiser only.
+ * RESIDUAL: publishDelivery uses fs.copyFileSync (not bash cp) -- unaffected.
+ */
+function checkCopyMoveToProtected(command) {
+  if (typeof command !== "string" || !command) return null;
+  if (!command.includes("cp") && !command.includes("mv") && !command.includes("install")) return null;
+  if (!command.includes("delivery/")) return null;
+
+  const segments = splitSegments(command);
+  for (const seg of segments) {
+    const tokens = tokenize(seg);
+    if (tokens.length < 2) continue;
+    const cmd = tokens[0];
+    if (cmd !== "cp" && cmd !== "mv" && cmd !== "install") continue;
+
+    const positional = [];
+    for (let i = 1; i < tokens.length; i++) {
+      if (!tokens[i].startsWith("-")) positional.push(tokens[i]);
+    }
+    if (positional.length === 0) continue;
+
+    const dest = positional[positional.length - 1];
+    if (matchesDeliveryProtected(dest)) {
+      return `${cmd} to ${dest} (delivery-protected path)`;
+    }
+  }
+  return null;
+}
+
 function run(inputOrRaw, options = {}) {
   if (options.truncated) {
     return {
@@ -241,6 +610,16 @@ function run(inputOrRaw, options = {}) {
           'disable the config-protection hook temporarily.',
       };
     }
+    // Gate lock-down: check path-pattern protected files (need path context).
+    const pathMatch = checkProtectedPathPattern(filePath);
+    if (pathMatch) {
+      return {
+        exitCode: 2,
+        stderr: `BLOCKED: Writing to ${pathMatch.name} is not allowed. ` +
+          `This file is protected because ${pathMatch.reason}. ` +
+          'If this is a legitimate change, disable the config-protection hook temporarily and document the reason.',
+      };
+    }
   }
   const command = input?.tool_input?.command || '';
   if (command) {
@@ -254,11 +633,54 @@ function run(inputOrRaw, options = {}) {
           'If the hook is genuinely misconfigured, correct the hook configuration directly.',
       };
     }
+    // Gate lock-down: check for shell redirects to protected kill-switch paths.
+    // HONEST — INCOMPLETE: only > >> and tee are covered; sed -i and other forms
+    // are NOT. An agent with shell access can still evade. Bar-raiser only.
+    const redirect = checkRedirectToProtected(command);
+    if (redirect) {
+      return {
+        exitCode: 2,
+        stderr: `BLOCKED: Detected ${redirect} targeting a protected gate kill-switch file. ` +
+          'Writing to shell profiles or Claude/flow-agents config files via shell redirect could ' +
+          'disable or tamper with the gate. If this is a legitimate operation, ' +
+          'disable the config-protection hook temporarily and document the reason. ' +
+          'NOTE: This check has incomplete coverage (sed -i and similar forms are not caught).',
+      };
+    }
+    // Gate lock-down: check for interpreter invocations (node -e, py3 -c, sed -i,
+    // perl -e) combined with a protected-path token literal in the command string.
+    // HONEST — INCOMPLETE (R5a best-effort): runtime-constructed paths, base64,
+    // multi-step assembly, and other interpreters not listed are NOT caught.
+    const interpWrite = checkInterpreterWriteToProtected(command);
+    if (interpWrite) {
+      return {
+        exitCode: 2,
+        stderr: `BLOCKED: Detected ${interpWrite} in a Bash command. ` +
+          'Interpreter invocations (node -e, py3 -c, sed -i, perl -e) that reference ' +
+          'protected gate files could tamper with the gate. If this is a legitimate operation, ' +
+          'disable the config-protection hook temporarily and document the reason. ' +
+          'NOTE: This check has INCOMPLETE COVERAGE — runtime path construction evades it.',
+      };
+    }
+    // Gate lock-down R6: detect cp/mv/install targeting delivery-protected paths.
+    // Catches the plain-cp attack: `cp forged.json delivery/trust.bundle`.
+    // INCOMPLETE: cp/mv/install only; rsync/scp/dd evade. Real anchor is external.
+    const copyMove = checkCopyMoveToProtected(command);
+    if (copyMove) {
+      return {
+        exitCode: 2,
+        stderr: `BLOCKED: Detected ${copyMove} in a Bash command. ` +
+          'Writing to delivery/trust.bundle or delivery/trust.checkpoint.json via cp/mv/install ' +
+          'could forge the CI trust anchor. The legitimate write path is the publishDelivery CLI ' +
+          '(fs.copyFileSync -- not the Write/Edit tool or bash cp). ' +
+          'NOTE: This check covers cp/mv/install only -- other copy tools may evade it.',
+      };
+    }
   }
   return { exitCode: 0 };
 }
 
-module.exports = { run, tokenize, splitSegments, checkCommandForBypass };
+module.exports = { run, tokenize, splitSegments, checkCommandForBypass, checkProtectedPathPattern, checkRedirectToProtected, checkInterpreterWriteToProtected, checkCopyMoveToProtected, matchesDeliveryProtected };
 
 // Stdin fallback for spawnSync execution
 if (require.main === module) {