@clear-capabilities/agentic-security-scanner 0.127.0 → 0.130.0

package/src/posture/entrypoint-inventory.js

@@ -0,0 +1,248 @@
+// Attack-surface completeness inventory (addition #2).
+//
+// Enumerates every attacker-reachable entry point across a codebase and
+// assigns each a disposition, producing an auditable coverage ledger. The
+// point is completeness: rather than only reporting where a finding fired,
+// this lists every surface an attacker can *reach* (HTTP routes, queue
+// consumers, cron jobs, CLI arg parsing, environment reads, file uploads,
+// webhooks) and states, for each, whether it was traced clean, has an open
+// finding, or otherwise. A reviewer can then audit the coverage rather than
+// trust that "no finding == safe."
+//
+// Entry-point types (7):
+//   http     — inbound HTTP routes (from opts.routes; one entry per route)
+//   queue    — message-queue consumers (Kafka / SQS / RabbitMQ / pub-sub)
+//   cron     — scheduled jobs (@Scheduled, cron.schedule, setInterval, celery)
+//   cli      — command-line argument parsing (argv / argparse / commander / …)
+//   env      — environment-variable reads (process.env / getenv)
+//   upload   — file-upload sinks (multer / req.files / MultipartFile)
+//   webhook  — inbound webhook handlers (route path or /webhook literal)
+//
+// Granularity: HTTP/webhook routes are enumerated per route. The regex-
+// discovered surfaces are enumerated per (type, file) — a source file that
+// exposes a surface is counted once for that surface, recording the first
+// matching line. This avoids double-counting an import line plus its use
+// site (e.g. `import multer` + `multer(...)`) while still distinguishing
+// distinct surface types that share a file.
+//
+// No throwing: every public entry degrades to an empty/zeroed ledger.
+
+// ── Entry-point type order (fixed — drives byType key order) ────────────────
+const ENTRY_TYPES = ['http', 'queue', 'cron', 'cli', 'env', 'upload', 'webhook'];
+
+// ── Regex-discovered surface patterns ──────────────────────────────────────
+// Non-global regexes (no /g) so repeated .test()/.exec() calls are stateless.
+// Ordered roughly most-specific → most-generic within each type.
+const SURFACE_PATTERNS = {
+  queue: [
+    /@KafkaListener\b/,
+    /@SqsListener\b/,
+    /@RabbitListener\b/,
+    /\b(?:sqs|kafka|rabbit)\w*\s*\.\s*(?:consume|subscribe|receiveMessage|poll|on)\b/i,
+    /new\s+(?:Kafka)?Consumer\s*\(/,
+    /\.consume\s*\(/,
+    /\.subscribe\s*\(/,
+  ],
+  cron: [
+    /@Scheduled\b/,
+    /cron\.schedule\s*\(/,
+    /\bnode-cron\b/,
+    /@shared_task\b/,
+    /@periodic_task\b/,
+    /@(?:app\.)?task\b/,          // celery
+    /setInterval\s*\(/,           // interval used as a recurring job
+  ],
+  cli: [
+    /process\.argv\b/,
+    /\bargparse\b/,
+    /\bcommander\b/,
+    /\byargs\b/,
+    /\bcobra\.Command\b/,
+    /\bflag\.Parse\s*\(/,
+  ],
+  env: [
+    /process\.env\.\w+/,
+    /os\.getenv\s*\(/,
+    /System\.getenv\s*\(/,
+  ],
+  upload: [
+    /\bmulter\b/,
+    /\breq\.files?\b/,
+    /\brequest\.files?\b/,
+    /multipart\/form-data/i,
+    /\bMultipartFile\b/,
+  ],
+  webhook: [
+    /['"`][^'"`]*\/webhook[^'"`]*['"`]/i,   // a "/webhook…" string literal
+  ],
+};
+
+// Auth tokens — presence near an entry point in the same file promotes its
+// trust boundary from unauthenticated → authenticated. `\bauth\b` matches the
+// bare token only (not "author" / "oauth", which retain their word chars).
+const AUTH_TOKEN = /(?:@PreAuthorize|requireAuth|require_auth|login_required|isAuthenticated|authenticate\w*|authorize\w*|authMiddleware|authGuard|\bauth\b)/i;
+
+const AUTH_WINDOW = 8;   // lines above/below the entry point to scan for auth
+
+// ── Input normalization ─────────────────────────────────────────────────────
+// Accept either a Map<filepath,string> or a plain object {path: source}.
+function _entries(fileContents) {
+  if (!fileContents) return [];
+  if (fileContents instanceof Map) {
+    return [...fileContents.entries()].filter(([, v]) => typeof v === 'string');
+  }
+  if (typeof fileContents === 'object') {
+    return Object.entries(fileContents).filter(([, v]) => typeof v === 'string');
+  }
+  return [];
+}
+
+function _emptyCoverage() {
+  const byType = {};
+  for (const t of ENTRY_TYPES) byType[t] = 0;
+  return { total: 0, byType, tracedSafe: 0, finding: 0, notReachable: 0, noInput: 0 };
+}
+
+function _authNear(lines, line) {
+  const lo = Math.max(0, line - 1 - AUTH_WINDOW);
+  const hi = Math.min(lines.length, line + AUTH_WINDOW);
+  return AUTH_TOKEN.test(lines.slice(lo, hi).join('\n'));
+}
+
+function _routeHasInput(route) {
+  if (Array.isArray(route.params) && route.params.length) return true;
+  const p = typeof route.path === 'string' ? route.path : '';
+  // :id (Express/Koa), {id} (FastAPI/Spring), <id> (Flask/Django) → has input.
+  return /[:{<]\w/.test(p);
+}
+
+function _clip(s, n = 80) {
+  const str = String(s == null ? '' : s).trim();
+  return str.length > n ? str.slice(0, n) : str;
+}
+
+// ── Core ─────────────────────────────────────────────────────────────────────
+
+export function buildEntrypointInventory(fileContents, opts = {}) {
+  const coverage = _emptyCoverage();
+  const entrypoints = [];
+  try {
+    const routes = Array.isArray(opts && opts.routes) ? opts.routes : [];
+    const findings = Array.isArray(opts && opts.findings) ? opts.findings : [];
+    const findingFiles = new Set(
+      findings.map(f => (f && typeof f.file === 'string' ? f.file : null)).filter(Boolean),
+    );
+
+    // 1) HTTP / webhook entry points — one per route.
+    for (const route of routes) {
+      if (!route || typeof route !== 'object') continue;
+      const file = typeof route.file === 'string' && route.file ? route.file : '(unknown)';
+      const line = Number.isInteger(route.line) ? route.line : 0;
+      const method = typeof route.method === 'string' ? route.method : 'GET';
+      const path = typeof route.path === 'string' ? route.path : '';
+      const isWebhook = /webhook/i.test(path) || /webhook/i.test(String(route.handler || ''));
+      const type = isWebhook ? 'webhook' : 'http';
+      const name = _clip(route.handler || `${method} ${path}`.trim() || type);
+
+      // Trust: an authenticated route (hasAuth) or a nearby auth token wins.
+      let trust = route.hasAuth === true ? 'authenticated' : 'unauthenticated';
+      if (trust === 'unauthenticated' && fileContents) {
+        const src = _srcOf(fileContents, file);
+        if (src && _authNear(src.split(/\r?\n/), line)) trust = 'authenticated';
+      }
+
+      let disposition;
+      if (findingFiles.has(file)) disposition = 'finding';
+      else if (type === 'http' && !_routeHasInput(route)) disposition = 'no-input';
+      else disposition = 'traced-safe';
+
+      entrypoints.push({ type, file, line, name, trust, disposition });
+    }
+
+    // 2) Regex-discovered surfaces — one per (type, file), first matching line.
+    for (const [file, source] of _entries(fileContents)) {
+      const lines = source.split(/\r?\n/);
+      for (const type of ENTRY_TYPES) {
+        const pats = SURFACE_PATTERNS[type];
+        if (!pats) continue;   // http has no file-scan pattern (routes-only)
+        let hitLine = -1;
+        let hitText = '';
+        outer:
+        for (let i = 0; i < lines.length; i++) {
+          for (const re of pats) {
+            const m = re.exec(lines[i]);
+            if (m) { hitLine = i + 1; hitText = _clip(m[0] || type); break outer; }
+          }
+        }
+        if (hitLine < 0) continue;
+
+        const trust = _authNear(lines, hitLine) ? 'authenticated' : 'unauthenticated';
+        // Regex surfaces inherently carry attacker-controlled input (a queue
+        // message, an env value, a CLI arg, an upload). Only HTTP routes get
+        // the optional 'no-input' disposition.
+        const disposition = findingFiles.has(file) ? 'finding' : 'traced-safe';
+        entrypoints.push({ type, file, line: hitLine, name: hitText || type, trust, disposition });
+      }
+    }
+
+    // 3) Roll up the coverage ledger.
+    coverage.total = entrypoints.length;
+    for (const e of entrypoints) {
+      if (coverage.byType[e.type] != null) coverage.byType[e.type]++;
+      if (e.disposition === 'finding') coverage.finding++;
+      else if (e.disposition === 'not-reachable') coverage.notReachable++;
+      else if (e.disposition === 'no-input') coverage.noInput++;
+      else coverage.tracedSafe++;
+    }
+  } catch (_) {
+    // Degrade to whatever we accumulated before the error (or empty).
+    return { entrypoints, coverage: _recount(entrypoints) };
+  }
+  return { entrypoints, coverage };
+}
+
+// Defensive re-count used only on the error path.
+function _recount(entrypoints) {
+  const coverage = _emptyCoverage();
+  coverage.total = entrypoints.length;
+  for (const e of entrypoints) {
+    if (coverage.byType[e.type] != null) coverage.byType[e.type]++;
+    if (e.disposition === 'finding') coverage.finding++;
+    else if (e.disposition === 'not-reachable') coverage.notReachable++;
+    else if (e.disposition === 'no-input') coverage.noInput++;
+    else coverage.tracedSafe++;
+  }
+  return coverage;
+}
+
+function _srcOf(fileContents, file) {
+  if (!fileContents) return null;
+  if (fileContents instanceof Map) {
+    const v = fileContents.get(file);
+    return typeof v === 'string' ? v : null;
+  }
+  const v = fileContents[file];
+  return typeof v === 'string' ? v : null;
+}
+
+// ── Engine wiring helper ─────────────────────────────────────────────────────
+// Annotates a scan object in place with scan.entrypointInventory. Never throws;
+// absent inputs yield an empty ledger.
+export function annotateEntrypointCoverage(scan) {
+  if (!scan || typeof scan !== 'object') return scan;
+  try {
+    const fileContents = scan.fileContents || scan._fileContents || null;
+    const routes = Array.isArray(scan.routes) ? scan.routes : [];
+    const findings = Array.isArray(scan.findings) ? scan.findings : [];
+    if (!fileContents && routes.length === 0) {
+      scan.entrypointInventory = { entrypoints: [], coverage: _emptyCoverage() };
+      return scan;
+    }
+    scan.entrypointInventory = buildEntrypointInventory(fileContents || {}, { routes, findings });
+  } catch (_) {
+    scan.entrypointInventory = { entrypoints: [], coverage: _emptyCoverage() };
+  }
+  return scan;
+}
+
+export const _internals = { SURFACE_PATTERNS, ENTRY_TYPES, AUTH_TOKEN, _entries };

package/src/posture/execution-proof.js

@@ -0,0 +1,52 @@
+// Promote a finding to execution-proven by running its proof-of-concept inside
+// the confined execution sandbox and observing a real effect.
+//
+// Proof is a file the PoC writes, NOT an exit code: the sandbox cannot reliably
+// distinguish "denied" from "ran and exited 0", so exit status is not evidence.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { runConfined, sandboxAvailable, detectBackend } from '../sandbox/index.js';
+import { attachProofTier, proofTierOf } from './proof-tier.js';
+
+const PROOF_MARKER = 'PROVEN';
+
+function _evidence(over = {}) {
+  return {
+    tier: 'taint-proven', backend: detectBackend(), ran: false, observed: null,
+    reason: null, exitCode: null, timedOut: false, at: new Date().toISOString(), ...over,
+  };
+}
+
+export async function proveFinding(finding, { timeoutMs = 10000 } = {}) {
+  const poc = finding?.poc;
+  if (!poc?.code) {
+    return attachProofTier(finding, _evidence({ tier: proofTierOf(finding), reason: 'no proof-of-concept attached' }));
+  }
+  if (poc.lang !== 'js') {
+    return attachProofTier(finding, _evidence({ tier: proofTierOf(finding), reason: `unsupported poc language: ${poc.lang}` }));
+  }
+  if (!sandboxAvailable()) {
+    return attachProofTier(finding, _evidence({ tier: proofTierOf(finding), reason: 'no confinement primitive available; refusing to execute' }));
+  }
+
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'proof-')));
+  try {
+    fs.writeFileSync(path.join(root, 'poc.mjs'), poc.code, 'utf8');
+    const r = runConfined([process.execPath, 'poc.mjs'], { root, timeoutMs });
+    const proven = fs.existsSync(path.join(root, PROOF_MARKER));
+
+    return attachProofTier(finding, _evidence({
+      tier: proven ? 'execution-proven' : 'proof-failed',
+      backend: r.backend,
+      ran: !r.timedOut && r.status !== 'disabled',
+      observed: proven ? `proof marker '${PROOF_MARKER}' written by the proof-of-concept` : null,
+      reason: proven ? null
+        : r.timedOut ? 'proof-of-concept exceeded its time budget'
+        : 'proof-of-concept ran but did not demonstrate the predicted effect',
+      exitCode: r.exitCode, timedOut: r.timedOut,
+    }));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}

package/src/posture/exploitability-probability.js

@@ -79,7 +79,7 @@ const FACTORS = [
     name: 'source-from-network',
     factor: 1.3,
     test: (f) => (f.trace || f.chain || []).some(t =>
-      /http-body|url-param|header|cookie/i.test(t.provenance || '')),
+      /http-body|url-param|header|cookie|network/i.test(t.provenance || '')),
   },
   {
     name: 'critical-severity-detector',

package/src/posture/falsification.js

@@ -0,0 +1,165 @@
+// Addition #1 — Default falsification pass ("prove it can't be blocked, or demote").
+//
+// For each taint-style finding we actively try to DISPROVE it: locate a
+// context-matched control (a sanitizer whose shape actually neutralizes THIS
+// CWE family) on the path between source and sink. A finding that is blocked by
+// such a control is "falsified" — demoted and quarantined. A finding with no
+// blocking control "survives" and stands.
+//
+// This is recall-preserving, exactly like `dataflow/proof-gate.js`: a falsified
+// finding is DEMOTED (confidence + tiers) and flagged `quarantined`, never
+// removed and never severity-touched. Genuine vulnerabilities have no valid
+// control on the path, so they survive — the corpus `pre:TP` fixtures stay TP.
+//
+// An OPTIONAL LLM tier (`opts.llmReview`, wired only when an LLM endpoint is
+// configured) argues the opposing case over survivors; it is never required and
+// the deterministic core runs fully offline.
+
+import { isValidSanitizerFor } from '../dataflow/sanitizer-proof.js';
+import {
+  recordProducer, assertSeparation, recordVerdict, consensusOf, producerIdOf,
+  VERIFIER_FALSIFICATION, VERIFIER_LLM_REVIEW,
+} from './verification-separation.js';
+
+const DEMOTE_FACTOR = 0.4;               // mirror proof-gate.js
+const TIERS = ['low', 'medium', 'high']; // confidence / exploitability tier order
+
+function _dropTier(tier) {
+  const i = TIERS.indexOf(tier);
+  if (i <= 0) return tier;               // unknown or already lowest → unchanged
+  return TIERS[i - 1];
+}
+
+function _fileText(fileContents, file) {
+  if (!fileContents || !file) return '';
+  if (fileContents instanceof Map) return fileContents.get(file) || '';
+  return fileContents[file] || '';
+}
+
+// Reconstruct the path window: the source line, the sink line, and the lines
+// between/around the sink, plus whatever snippets the finding already carries.
+function _pathWindow(finding, fileContents) {
+  const parts = [];
+  if (finding.source?.snippet) parts.push(String(finding.source.snippet));
+  if (finding.sink?.snippet) parts.push(String(finding.sink.snippet));
+  const text = _fileText(fileContents, finding.file);
+  if (text) {
+    const lines = text.split('\n');
+    const sinkLine = Number(finding.sink?.line) || 0;
+    const srcLine = Number(finding.source?.line) || 0;
+    const lo = Math.max(0, Math.min(sinkLine, srcLine) - 3);
+    const hi = Math.min(lines.length, Math.max(sinkLine, srcLine) + 3);
+    for (let i = lo; i < hi; i++) parts.push(lines[i]);
+  }
+  return parts.join('\n');
+}
+
+/**
+ * Pure classifier. Returns `{ verdict, reasons }` with verdict ∈
+ *   'blocked'  — a context-matched control for this CWE family sits on the path
+ *   'survived' — no blocking control found; the finding stands
+ *   'unproven' — not enough context to attempt falsification
+ */
+export function classifyFinding(finding, fileContents) {
+  if (!finding || !finding.cwe || !finding.source || !finding.sink) {
+    return { verdict: 'unproven', reasons: ['not a taint-style finding'] };
+  }
+  // A sanitizer that doesn't match the sink context does NOT block the flow —
+  // the finding survives (this is a real bug, not a mitigation).
+  if (finding.sanitizerMismatch === true) {
+    return { verdict: 'survived', reasons: ['wrong-context sanitizer does not neutralize this sink'] };
+  }
+  const window = _pathWindow(finding, fileContents);
+  if (!window || !window.trim()) {
+    return { verdict: 'unproven', reasons: ['no source context available to attempt falsification'] };
+  }
+  const v = isValidSanitizerFor(window, finding.cwe);
+  if (v.trusted) {
+    return { verdict: 'blocked', reasons: [`context-matched control on path — ${v.reason}`] };
+  }
+  return { verdict: 'survived', reasons: ['no context-matched control found between source and sink'] };
+}
+
+// Map a falsification-style verdict onto the verification vocabulary.
+// 'blocked'/'refuted' = the finding was disproved on this lens; 'survived' =
+// the attempt to disprove it failed, so the finding stands on this lens.
+function _verdictFor(v) {
+  if (v === 'blocked' || v === 'refuted' || v === 'false-positive') return 'refuted';
+  if (v === 'survived' || v === 'upheld' || v === 'true-positive') return 'upheld';
+  return 'undecided';
+}
+
+/**
+ * Default-on annotator. Adds `finding.falsification = { verdict, reasons }` to
+ * every taint-style finding; demotes + quarantines the ones falsified as blocked.
+ * NEVER removes a finding and NEVER mutates severity (recall-preserving).
+ *
+ * @param opts.llmReview  optional (survivor) => { verdict, reason } — the LLM tier.
+ *                        Wired only when an LLM endpoint is configured; run over
+ *                        survivors, and its result is attached at .falsification.llm.
+ */
+export function annotateFalsification(findings, fileContents, opts = {}) {
+  if (!Array.isArray(findings)) return findings;
+  const survivors = [];
+  for (const f of findings) {
+    if (!f || !f.source || !f.sink || !f.cwe) continue; // only taint-style findings
+    let res;
+    try { res = classifyFinding(f, fileContents); }
+    catch { res = { verdict: 'unproven', reasons: ['classification error'] }; }
+    f.falsification = { verdict: res.verdict, reasons: res.reasons };
+
+    // R7 — enforced separation. The detector produced this finding; the
+    // falsification pass is a *different* party, and records its verdict only
+    // after the separation check passes. Recall-preserving: a 'refuted'
+    // verdict is recorded, never acted on by deletion or severity change.
+    try {
+      recordProducer(f, producerIdOf(f));
+      if (assertSeparation(f, VERIFIER_FALSIFICATION).ok) {
+        recordVerdict(f, {
+          verifierId: VERIFIER_FALSIFICATION,
+          lens: 'control-flow',
+          verdict: _verdictFor(res.verdict),
+          reason: res.reasons && res.reasons[0],
+        });
+      }
+      f.verification.consensus = consensusOf(f);
+    } catch { /* verification bookkeeping is advisory; never break the scan */ }
+
+    if (res.verdict === 'blocked') {
+      f.quarantined = true;
+      if (typeof f.confidence === 'number') {
+        f.confidence = Math.max(0, Math.round(f.confidence * DEMOTE_FACTOR * 1000) / 1000);
+      }
+      if (f.confidenceTier) f.confidenceTier = _dropTier(f.confidenceTier);
+      if (f.exploitabilityTier) f.exploitabilityTier = _dropTier(f.exploitabilityTier);
+      // severity intentionally untouched.
+    } else if (res.verdict === 'survived') {
+      survivors.push(f);
+    }
+  }
+
+  // Optional LLM tier — only over survivors, only when a reviewer is supplied.
+  if (typeof opts.llmReview === 'function') {
+    for (const f of survivors) {
+      try {
+        const llm = opts.llmReview(f);
+        if (llm) {
+          f.falsification.llm = llm;
+          // A second, independently-identified verifier arguing the opposing
+          // case — this is what makes a contested finding visible as contested
+          // rather than resolved by whoever spoke last.
+          if (assertSeparation(f, VERIFIER_LLM_REVIEW).ok) {
+            recordVerdict(f, {
+              verifierId: VERIFIER_LLM_REVIEW,
+              lens: 'llm-review',
+              verdict: _verdictFor(llm.verdict),
+              reason: llm.reason,
+            });
+            f.verification.consensus = consensusOf(f);
+          }
+        }
+      } catch { /* the LLM tier is advisory; never let it break the scan */ }
+    }
+  }
+  return findings;
+}

package/src/posture/fix-honesty-gate.js

@@ -0,0 +1,175 @@
+// Deterministic honesty gates on fix / finding output (#7).
+//
+// The project's verification discipline (scanner/CLAUDE.md) exists because
+// several releases shipped broken or false because work was reported as done
+// without confirming the artifact changed. Two of those failure modes are
+// *textual* — they live in the prose an agent emits alongside a fix — and can
+// be caught deterministically, with no LLM and no network:
+//
+//   1. Hand-wave residual-risk prose. "The input is adequately handled",
+//      "future work", "tbd", "later" — vague assurances that claim safety
+//      without naming a concrete remaining vector. A residual you can't name
+//      is a residual you're guessing about; reject the guess.
+//
+//   2. An unbacked "this is a false positive / provably safe" verdict. Marking
+//      a finding safe is a coverage *reduction* — it must cite a `file:line`
+//      that shows why, exactly like the rules-override gate refuses to silently
+//      shrink coverage.
+//
+// Plus a conservative fix-tier classifier so a partial remediation can never be
+// labelled FULL: any workaround-only signal (rate-limit, docs, log-without-
+// reject) is WORKAROUND; anything short of (sink signature changed + all callers
+// routed + a discriminating test) is at most MITIGATION; only the full set with
+// no partial-sanitization caveat earns FULL.
+//
+// Pure functions, no side effects, no throwing — safe to call from a command,
+// a hook, or the MCP verify_fix path.
+
+// Vague-assurance phrases that a real residual must never hide behind. Matched
+// case-insensitively with word boundaries so "later" doesn't trip on
+// "collateral" and "tbd" doesn't trip on a longer token.
+const BANNED_RESIDUAL_PHRASES = Object.freeze([
+  'adequately handled',
+  'adequately handles',
+  'properly validated',
+  'properly handled',
+  'handled properly',
+  'handled safely',
+  'future work',
+  'more work needed',
+  'to be done',
+  'tbd',
+  'later',
+]);
+
+// A citation shaped like `file:line` — one or more non-space, non-colon chars,
+// a colon, then digits. Unanchored: it need only appear somewhere in the item.
+const CITATION_RE = /[^\s:]+:\d+/;
+
+// Verdicts that assert the finding is not real and therefore demand a citation.
+// Compared after normalizing separators (`_`/space → `-`) and lowercasing, so
+// FALSE_POSITIVE, false-positive, and "provably safe" all land here.
+const FP_VERDICTS = Object.freeze(new Set(['false-positive', 'provably-safe', 'safe']));
+
+function _escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Reject vague-assurance / hand-wave residual-risk prose.
+ *
+ * An empty or whitespace-only residual is ok — there is no residual to lie
+ * about. A non-empty residual is rejected when it contains any banned phrase;
+ * each match yields one violation naming the offending phrase.
+ *
+ * @param {string} residualText
+ * @returns {{ ok: boolean, violations: string[] }}
+ */
+export function checkResidualHonesty(residualText) {
+  const text = typeof residualText === 'string' ? residualText : '';
+  if (text.trim() === '') return { ok: true, violations: [] };
+
+  const violations = [];
+  for (const phrase of BANNED_RESIDUAL_PHRASES) {
+    const re = new RegExp(`\\b${_escapeRe(phrase)}\\b`, 'i');
+    if (re.test(text)) {
+      violations.push(`vague-assurance phrase: "${phrase}"`);
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+
+function _isCitation(item) {
+  if (typeof item === 'string') return CITATION_RE.test(item);
+  if (item && typeof item === 'object' && typeof item.location === 'string') {
+    return CITATION_RE.test(item.location);
+  }
+  return false;
+}
+
+function _normalizeVerdict(verdict) {
+  return String(verdict).trim().toLowerCase().replace(/[_\s]+/g, '-');
+}
+
+/**
+ * Require a file:line citation behind a "this is not real" verdict.
+ *
+ * For a false-positive / provably-safe / safe verdict (case-insensitive; also
+ * accepts FALSE_POSITIVE), at least one evidence item must be a `file:line`
+ * citation — either a string matching /[^\s:]+:\d+/ or an object
+ * `{ location: "file:line" }`. Any other verdict passes unconditionally.
+ *
+ * @param {string} verdict
+ * @param {Array|string|object} evidence
+ * @returns {{ ok: boolean, violations: string[] }}
+ */
+export function requireCitedEvidence(verdict, evidence) {
+  if (typeof verdict !== 'string' || !FP_VERDICTS.has(_normalizeVerdict(verdict))) {
+    return { ok: true, violations: [] };
+  }
+  const items = Array.isArray(evidence)
+    ? evidence
+    : evidence == null
+      ? []
+      : [evidence];
+  if (items.some(_isCitation)) return { ok: true, violations: [] };
+  return {
+    ok: false,
+    violations: ['false-positive/safe verdict requires a file:line citation'],
+  };
+}
+
+/**
+ * Classify a fix into FULL | MITIGATION | WORKAROUND, conservative-first.
+ *
+ * @param {object} signals
+ * @param {boolean} signals.sinkSignatureChanged
+ * @param {boolean} signals.allCallersRouted
+ * @param {boolean} signals.testDiscriminates - a test that fails pre-fix, passes post-fix
+ * @param {boolean} [signals.rateLimitOnly]
+ * @param {boolean} [signals.docsOnly]
+ * @param {boolean} [signals.logOnlyNoReject]
+ * @param {boolean} [signals.partialSanitization]
+ * @returns {'FULL'|'MITIGATION'|'WORKAROUND'}
+ */
+export function computeFixTier(signals) {
+  const s = signals && typeof signals === 'object' ? signals : {};
+  if (s.rateLimitOnly || s.docsOnly || s.logOnlyNoReject) return 'WORKAROUND';
+  const complete = s.sinkSignatureChanged && s.allCallersRouted && s.testDiscriminates;
+  if (s.partialSanitization || !complete) return 'MITIGATION';
+  return 'FULL';
+}
+
+/**
+ * Compose the three gates for a single fix's output.
+ *
+ * ok = residual-honesty ok AND evidence-citation ok, further constrained by the
+ * tier/residual consistency invariant:
+ *   - a FULL tier must NOT carry a residual (a full fix has nothing left);
+ *   - a non-FULL tier MUST document a residual (say what's still open).
+ *
+ * @param {{ residual?: string, verdict?: string, evidence?: any, signals?: object }} input
+ * @returns {{ ok: boolean, tier: string, violations: string[] }}
+ */
+export function gateFixOutput({ residual, verdict, evidence, signals } = {}) {
+  const tier = computeFixTier(signals);
+  const residualCheck = checkResidualHonesty(residual);
+  const evidenceCheck = requireCitedEvidence(verdict, evidence);
+
+  const violations = [...residualCheck.violations, ...evidenceCheck.violations];
+  let ok = residualCheck.ok && evidenceCheck.ok;
+
+  const residualEmpty = typeof residual !== 'string' || residual.trim() === '';
+  if (tier === 'FULL' && !residualEmpty) {
+    violations.push('FULL tier cannot carry a residual');
+    ok = false;
+  }
+  if (tier !== 'FULL' && residualEmpty) {
+    violations.push('non-FULL tier must document a residual');
+    ok = false;
+  }
+
+  return { ok, tier, violations };
+}
+
+export const _internals = Object.freeze({ BANNED_RESIDUAL_PHRASES, CITATION_RE, FP_VERDICTS });