@clear-capabilities/agentic-security-scanner 0.151.3 → 0.153.0

package/src/dataflow/exploit-prover.js

@@ -22,7 +22,7 @@
 //
 // We do NOT attempt to prove ARBITRARY satisfiability — the v2 use case.
 
-import { provablyMatches } from './string-domain.js';
+import { provablyMatches, safeSanitizerOutputRegex } from './string-domain.js';
 
 // CWE → canonical exploit input. Conservative payloads safe to display.
 const EXPLOIT_INPUTS = {
@@ -62,6 +62,31 @@ const FAMILY_METACHARS = {
 
 // Try to load z3-solver. Returns null if not installed — that's the common
 // case (we don't bundle the WASM blob).
+//
+// SCOPE NOTE (next-gen taint capability #5 rebuild): loading z3-solver here
+// is real — it is a genuine `optionalDependencies` entry in package.json,
+// and `_maybeLoadZ3` performs a real dynamic `import()`, verified against
+// an actual installed copy. What it does NOT yet do is discharge any query
+// TO Z3: `proveExploits` below still routes every feasibility verdict
+// through `smtLiteInfeasibilityCheck`'s JS-native regex check regardless of
+// whether z3 loaded; a present z3 module only labels `_exploitInputSource`
+// on the FEASIBLE branch. Making Z3 do real work here would mean
+// translating each sanitizer's `outputRegexSource` (a JS RegExp source —
+// anchors, character classes, quantifiers, alternation, optional groups;
+// see `string-domain.js`'s `SANITIZER_OUTPUT_REGEX`) into Z3's own
+// string/regex theory and asking it "does any string matching this pattern
+// also contain this metacharacter?" That translator is a real, standalone
+// undertaking, and a translation bug in it is uniquely dangerous for this
+// specific mechanism: it would manufacture a false `feasible: false`
+// (a false safety proof) rather than merely a missed detection. The
+// existing JS-native check (`_backwardSliceExcludesMetachars`) is already
+// SOUND for every regex currently in the hand-vetted catalog (all of them
+// are anchored, closed-under-repetition character classes or fixed-format
+// literals — verified by direct reading of `SANITIZER_OUTPUT_REGEX`), so
+// there is no live soundness gap this would close today. Left as a
+// deliberate, documented boundary rather than an oversight: build the
+// translator as its own reviewed capability if/when the sanitizer catalog
+// grows regex shapes the JS probe can no longer safely reason about.
 let _z3 = null;
 let _z3Loaded = false;
 async function _maybeLoadZ3() {
@@ -90,20 +115,30 @@ export function smtLiteInfeasibilityCheck(finding) {
   if (!metacharsNeeded || metacharsNeeded.length === 0) {
     return { feasible: 'unknown', reason: 'no-metachar-model' };
   }
-  // Walk the trace/chain for sanitizer regex constraints. The `string-domain`
-  // produces a regex abstract value when known sanitizers are on the path;
-  // the soft-taint table independently labels sanitizers. For v1 we check
-  // the chain entries against the known sanitizer-output regexes.
+  // Next-gen taint capability #5 (SMT path-feasibility rebuild): prefer
+  // `finding.backwardSlice` (backward.js's REAL, ordered source-to-sink
+  // path, opt-in via AGENTIC_SECURITY_BACKWARD_SLICE=1) over the
+  // trace/chain fallback below. Confirmed live, during this rebuild, that
+  // `finding.trace`/`finding.chain` are NOT a sequential path at all — they
+  // are the list of SOURCES reaching the sink (see dataflow/engine.js's own
+  // `_sourcesReachingExpr`), so a `.callee` never actually names a
+  // sanitizer in real production data; this function's own pre-rebuild
+  // unit tests only ever exercised a HAND-FABRICATED `chain` shape
+  // (`[{callee: 'htmlspecialchars'}]`) that the real engine never produces.
+  const slicePath = _backwardSliceExcludesMetachars(finding.backwardSlice, metacharsNeeded);
+  if (slicePath) return slicePath;
+  // Fallback for callers that never ran the (opt-in) backward-slice pass —
+  // kept for backward compatibility, though per the finding above it can
+  // realistically only ever return 'unknown' against real finding.trace/
+  // chain data; a caller that wants a real feasibility answer needs
+  // AGENTIC_SECURITY_BACKWARD_SLICE=1 set.
   const trace = Array.isArray(finding.trace) ? finding.trace : [];
   const chain = Array.isArray(finding.chain) ? finding.chain : [];
   const all = [...trace, ...chain];
   for (const step of all) {
     const callee = step.callee || step.label || '';
-    // Heuristic: an encodeURIComponent / parseInt / quote_plus on the path
-    // produces output that cannot contain the family's metacharacters.
     const regex = _sanitizerRegexFor(callee);
     if (!regex) continue;
-    // Test if ALL required metacharacters are excluded by this regex.
     const excludesAll = metacharsNeeded.every(mc => !regex.test(mc.repeat(8)));
     if (excludesAll) {
       return { feasible: false, reason: `sanitizer-excludes-metacharacters:${callee}` };
@@ -112,22 +147,75 @@ export function smtLiteInfeasibilityCheck(finding) {
   return { feasible: 'unknown', reason: 'no-sanitizer-on-path' };
 }
 
+// Parameterized-query API calls: a DIFFERENT kind of "safe" than a
+// regex-constrained output — the value is never concatenated into the
+// query TEXT at all, so no charset restriction on the value itself makes
+// it safe regardless of content. Kept as its own small, explicit,
+// unambiguous list (real database-driver method names, not generic
+// English words) rather than folded into `safeSanitizerOutputRegex`,
+// which models a genuinely different property (output charset).
+const _PARAMETERIZED_CALL_NAMES = new Set(['setString', 'AddWithValue', 'bindParam', 'parameterize']);
+
+// Walk `backwardSlice` (backward.js's source-first ordered path) from the
+// SINK end backward, looking for the CLOSEST sanitize/parameterize step —
+// stopping (refusing to conclude anything) the moment it crosses an OPAQUE
+// 'call' step it cannot reason about, since such a call could have undone
+// or bypassed whatever a sanitizer further upstream proved. Only a
+// sanitizer/parameterization with NOTHING but pure 'assign' aliasing
+// between it and the sink is trusted — this is the conservative,
+// sound-by-construction direction: a missed proof (returning 'unknown')
+// costs nothing but a demotion opportunity, while a WRONG proof would
+// manufacture a false safety claim for a real vulnerability.
+function _backwardSliceExcludesMetachars(backwardSlice, metacharsNeeded) {
+  if (!Array.isArray(backwardSlice) || !backwardSlice.length) return null;
+  // Reverse to walk sink-first (the array itself is stored source-first).
+  for (const step of [...backwardSlice].reverse()) {
+    if (step.kind === 'sink') continue;
+    if (step.kind === 'assign') continue; // pure alias — keep looking upstream
+    if (step.kind === 'sanitize') {
+      if (_PARAMETERIZED_CALL_NAMES.has(step.callee)) {
+        return { feasible: false, reason: `parameterized-call:${step.callee}` };
+      }
+      if (step.outputRegexSource) {
+        // `outputRegexSource` is never attacker-influenced despite flowing
+        // through a `backwardSlice` step object: `backward.js`'s own
+        // `_safeSanitizerOutputRegex` is its ONLY producer, and that
+        // function returns either `null` or one of `string-domain.js`'s
+        // SMALL, HARDCODED `SANITIZER_OUTPUT_REGEX` pattern literals
+        // (encodeURIComponent, parseInt, htmlspecialchars, …) — confirmed
+        // by direct code reading, never a value derived from scanned
+        // source text, a finding, or any other runtime input. This
+        // project's own self-scan correctly cannot see that far through
+        // the call chain and flags this defensively — a genuine false
+        // positive, not a suppressed real risk.
+        const regex = new RegExp(step.outputRegexSource, step.outputRegexFlags || ''); // agentic-security-ignore: CWE-1333
+        const excludesAll = metacharsNeeded.every((mc) => !regex.test(mc.repeat(8)));
+        if (excludesAll) {
+          return { feasible: false, reason: `sanitizer-excludes-metacharacters:${step.callee}` };
+        }
+      }
+      // A recognized-by-catalog-name sanitizer with no PROVEN output
+      // regex (e.g. a project-local function merely NAMED like a known
+      // sanitizer) cannot be trusted for a sound proof — refuse rather
+      // than guess, matching backward.js's own `outputRegexSource`
+      // header comment on exactly this hazard.
+      return { feasible: 'unknown', reason: `sanitizer-without-proven-output-shape:${step.callee || 'unknown'}` };
+    }
+    if (step.kind === 'call') {
+      // An opaque, unmodeled call between here and the sink — refuse. We
+      // cannot know whether it further transforms (or un-does a real
+      // sanitizer's effect on) the value.
+      return { feasible: 'unknown', reason: `opaque-call-on-path:${step.callee || 'unknown'}` };
+    }
+    if (step.kind === 'source') break; // reached the origin with no sanitizer found
+  }
+  return { feasible: 'unknown', reason: 'no-sanitizer-on-path' };
+}
+
 function _sanitizerRegexFor(callee) {
   if (!callee) return null;
-  const tail = String(callee).split('.').pop();
-  const table = {
-    encodeURIComponent: /^[A-Za-z0-9\-_.!~*'()%]*$/,
-    parseInt:           /^-?\d+$/,
-    parseFloat:         /^-?\d+(?:\.\d+)?$/,
-    digest:             /^[0-9a-f]+$/,
-    htmlspecialchars:   /^[^<>&"']*$/,
-    escapeHtml:         /^[^<>&"']*$/,
-    setString:          /^.*$/,   // parameterized → infeasible regardless of content
-    AddWithValue:       /^.*$/,
-    bindParam:          /^.*$/,
-    parameterize:       /^.*$/,
-  };
-  return table[tail] || null;
+  if (_PARAMETERIZED_CALL_NAMES.has(String(callee).split('.').pop())) return /^.*$/;
+  return safeSanitizerOutputRegex(callee);
 }
 
 /**
@@ -180,7 +268,7 @@ export async function proveExploits(findings, opts = {}) {
 
 export const _internal = {
   EXPLOIT_INPUTS, FAMILY_METACHARS, _sanitizerRegexFor, smtLiteInfeasibilityCheck,
-  _maybeLoadZ3,
+  _maybeLoadZ3, _backwardSliceExcludesMetachars,
 };
 
 // Re-export provablyMatches so callers don't have to thread imports.

package/src/dataflow/incremental.js

@@ -149,6 +149,18 @@ export function seedSummaryCache(summaryCache, persisted, reusableQids) {
     const summary = {
       returnTainted: !!s.returnTainted,
       mutatedParams: new Set(s.mutatedParams || []),
+      // W5.53: mutatedThisFields is a THIRD Set-valued summary field
+      // (object-instance field taint via method calls), added after this
+      // module's own serialize/reseed pair was written — omitting it here
+      // wouldn't crash (every consumer already null-guards with `&&`), but
+      // would silently drop the capability on any incremental/warm-cache
+      // scan, exactly the class of gap `_summaryEq`'s own header comment in
+      // summaries.js warns about for a different (but structurally
+      // identical) reason: a summary field that exists on some code paths
+      // and not others must be threaded through EVERY path that copies the
+      // summary shape, not just the ones exercised by this session's own
+      // tests.
+      mutatedThisFields: new Set(s.mutatedThisFields || []),
       taintedGlobals: new Set(s.taintedGlobals || []),
       findings: Array.isArray(s.findings) ? s.findings : [],
     };
@@ -195,6 +207,7 @@ export function serializeSummaries(summaryCache) {
     out[qid] = {
       returnTainted: !!summary.returnTainted,
       mutatedParams: [...(summary.mutatedParams || [])],
+      mutatedThisFields: [...(summary.mutatedThisFields || [])],
       taintedGlobals: [...(summary.taintedGlobals || [])],
       findings: Array.isArray(summary.findings) ? summary.findings.slice(0, 50) : [],
     };

package/src/dataflow/index.js

@@ -2,7 +2,7 @@
 import { runTaintEngine } from './engine.js';
 import { annotateProvenClean } from './proven-clean.js';
 import { CATALOG, matchSource, matchSinkOrSanitizer, _catalogSize } from './catalog.js';
-import { applyPathFeasibility } from './path-feasibility.js';
+import { applyPathFeasibility, buildConstantFnMap } from './path-feasibility.js';
 import { SummaryCache, entryStateFromCall } from './summaries.js';
 import { rhsReachableFunctions, shouldAnalyzeUnderRhs } from './tabulation.js';
 import { annotateBackwardSlices } from './backward.js';
@@ -12,7 +12,7 @@ import {
   serializeSummaries, commitIncrementalState,
 } from './incremental.js';
 import { buildPointsTo } from './points-to.js';
-import { buildClassHierarchy } from '../ir/class-hierarchy.js';
+import { buildClassHierarchy, annotateRTA } from '../ir/class-hierarchy.js';
 import { annotateSoftTaint } from './soft-taint.js';
 import { runIfdsTaintEngine } from './ifds.js';
 import { proveExploits } from './exploit-prover.js';
@@ -22,9 +22,13 @@ import { runPrivacyTaintEngine } from './privacy-deep-walker.js';
 
 export function runDeepAnalysis(perFileIR, callGraph, opts = {}) {
   // Path-feasibility pass over every function before the taint walk.
+  // W2.1: build the trivially-constant-helper map ONCE, from every function
+  // in the scan, before folding any single function's conditions — a
+  // constant helper in file A must resolve when called from file B.
+  const constFns = buildConstantFnMap(callGraph.functions.values());
   let totalPruned = 0;
   for (const fn of callGraph.functions.values()) {
-    const r = applyPathFeasibility(fn);
+    const r = applyPathFeasibility(fn, constFns);
     totalPruned += r.pruned;
   }
   // P2.1 — RHS-lite reachability slice. When AGENTIC_SECURITY_RHS=1 the
@@ -93,7 +97,16 @@ export function runDeepAnalysis(perFileIR, callGraph, opts = {}) {
   // (a single walk of the already-parsed IR, no fixed-point iteration) and
   // every consumer degrades to today's behavior when it finds no useful type.
   let classHierarchy = null;
-  try { classHierarchy = buildClassHierarchy(perFileIR); } catch { classHierarchy = null; }
+  try {
+    classHierarchy = buildClassHierarchy(perFileIR, callGraph);
+    // PRD W2.5 (SARD_80_F1_EXECUTION_PRD.md) — RTA-annotate so
+    // `engine.js`'s `_resolveMemberCalleeViaCHA` can resolve a
+    // parameter-typed (or otherwise non-`new`-tracked) receiver against
+    // whichever subclasses are ACTUALLY instantiated somewhere in this
+    // scan, not just the receiver's own declared/abstract type (which
+    // typically has no method BODY of its own to resolve to at all).
+    if (classHierarchy) annotateRTA(classHierarchy, perFileIR);
+  } catch { classHierarchy = null; }
   // v0.70 #2 — Steensgaard points-to / alias analysis. Built once before
   // the worklist, passed via opts so the engine can resolve aliased
   // mutations (`let a = obj; a.x = tainted; sink(obj.x)`).
@@ -150,7 +163,17 @@ export function runDeepAnalysis(perFileIR, callGraph, opts = {}) {
     });
   }
   // P1.4 — backward slice (opt-in via AGENTIC_SECURITY_BACKWARD_SLICE=1).
-  if (process.env.AGENTIC_SECURITY_BACKWARD_SLICE === '1') {
+  // Next-gen taint capability #5 (SMT path-feasibility rebuild): ALSO run
+  // this when AGENTIC_SECURITY_SYMEXEC=1 is set, even if the operator never
+  // separately set AGENTIC_SECURITY_BACKWARD_SLICE — `proveExploits`'s own
+  // infeasibility check now depends on `finding.backwardSlice` for a sound
+  // verdict (see exploit-prover.js's own header), and requiring an operator
+  // to know to independently set a SECOND, differently-named flag just to
+  // get a real answer out of the first is exactly the kind of silent,
+  // undiscoverable degradation this codebase's own verification discipline
+  // warns against — SYMEXEC's own soundness must not be a hidden function
+  // of an unrelated flag.
+  if (process.env.AGENTIC_SECURITY_BACKWARD_SLICE === '1' || process.env.AGENTIC_SECURITY_SYMEXEC === '1') {
     findings = annotateBackwardSlices(findings, perFileIR, callGraph);
   }
   // Roadmap #6 — flow-proof: prove SQL sinks reached only through a
@@ -237,4 +260,4 @@ export function runDeepAnalysis(perFileIR, callGraph, opts = {}) {
   return findings;
 }
 
-export { runTaintEngine, CATALOG, matchSource, matchSinkOrSanitizer, _catalogSize, applyPathFeasibility, SummaryCache, entryStateFromCall, rhsReachableFunctions, shouldAnalyzeUnderRhs, annotateBackwardSlices };
+export { runTaintEngine, CATALOG, matchSource, matchSinkOrSanitizer, _catalogSize, applyPathFeasibility, buildConstantFnMap, SummaryCache, entryStateFromCall, rhsReachableFunctions, shouldAnalyzeUnderRhs, annotateBackwardSlices };

package/src/dataflow/path-feasibility.js

@@ -14,21 +14,84 @@
 //
 // Patterns deliberately deferred (would need SMT or symbolic execution):
 //   - Comparisons of unrelated variables
-//   - Comparisons involving function call return values
 //   - Aliasing-aware constraint propagation
+//   - Static/instance final-field constants (PRD W2.1's other half — needs
+//     parser changes to capture field initializer values across all IR
+//     languages, not attempted here)
+//
+// W2.1: trivially-constant helper returns. Juliet's control-flow-gating
+// variants (02-22) commonly gate through a helper — `if (privateReturnsTrue())`,
+// `if (IO.staticReturnsTrueOrFalse())` — rather than an inline literal. This
+// is NOT a Juliet-specific special case: `buildConstantFnMap` (below, called
+// once per scan in dataflow/index.js) generically finds any function whose
+// ENTIRE body is `return <literal>;` and nothing else, for ANY codebase,
+// then this module resolves a call to such a function the same way it
+// already resolves `if (true)`. A function with real logic (even one extra
+// statement) is never treated as constant — this reads the function's own
+// semantics, not an answer-key label.
 //
 // Output: mutates the CFG node's `succ` array to drop unreachable edges. The
 // existing taint engine then never walks them. Logs the prune count on each
 // function so we can count how many FPs path-feasibility avoided.
 
-function evalConst(expr) {
+// A function is "trivially constant" iff its CFG, after stripping entry/exit/
+// noop bookkeeping nodes, is exactly one `return <literal>;` node. Anything
+// else (a branch, an assignment, a call, a non-literal return) disqualifies
+// it — conservative by design, since a false resolution here silently prunes
+// a REAL branch.
+function triviallyConstantValue(fn) {
+  if (!fn || !fn.cfg || !fn.cfg.nodes) return undefined;
+  const real = Object.values(fn.cfg.nodes).filter(n => n && n.kind !== 'entry' && n.kind !== 'exit' && n.kind !== 'noop');
+  if (real.length !== 1) return undefined;
+  const only = real[0];
+  if (only.kind !== 'return') return undefined;
+  if (!only.value || only.value.kind !== 'literal') return undefined;
+  return only.value.value;
+}
+
+// Builds { byQid: Map<qid, value>, byBareName: Map<lastSegment, value|AMBIGUOUS> }
+// from every function in the scan. Bare-name resolution is how the hand-rolled
+// parsers' flat dotted-string callees (`"IO.staticReturnsTrue"`,
+// `"privateReturnsTrue"`) get matched — same collision-refusal precedent as
+// `callgraph.js`'s `~bare~` key: two differently-valued same-named functions
+// refuse to resolve via bare name rather than guessing.
+const AMBIGUOUS = Symbol('ambiguous-constant-fn');
+
+export function buildConstantFnMap(functions) {
+  const byQid = new Map();
+  const byBareName = new Map();
+  for (const fn of functions) {
+    const val = triviallyConstantValue(fn);
+    if (val === undefined) continue;
+    if (fn.qid) byQid.set(fn.qid, val);
+    const bare = (fn.name || '').split('.').pop();
+    if (!bare) continue;
+    if (byBareName.has(bare)) {
+      const existing = byBareName.get(bare);
+      if (existing !== AMBIGUOUS && existing !== val) byBareName.set(bare, AMBIGUOUS);
+    } else {
+      byBareName.set(bare, val);
+    }
+  }
+  return { byQid, byBareName };
+}
+
+function _bareCalleeName(callee) {
+  if (!callee) return null;
+  if (typeof callee === 'string') return callee.split('.').pop() || null;
+  if (callee.kind === 'ident') return callee.name || null;
+  if (callee.kind === 'member') return callee.prop || null;
+  return null;
+}
+
+function evalConst(expr, constFns) {
   if (!expr) return undefined;
   switch (expr.kind) {
     case 'literal': return expr.value;
     case 'unknown': return undefined;
     case 'binary': {
-      const l = evalConst(expr.left);
-      const r = evalConst(expr.right);
+      const l = evalConst(expr.left, constFns);
+      const r = evalConst(expr.right, constFns);
       if (l === undefined || r === undefined) return undefined;
       switch (expr.op) {
         case '===': return l === r;
@@ -47,10 +110,10 @@ function evalConst(expr) {
       return undefined;
     }
     case 'logical': {
-      const l = evalConst(expr.left);
+      const l = evalConst(expr.left, constFns);
       if (l === undefined) return undefined;
-      if (expr.op === '&&') return l ? evalConst(expr.right) : l;
-      if (expr.op === '||') return l ? l : evalConst(expr.right);
+      if (expr.op === '&&') return l ? evalConst(expr.right, constFns) : l;
+      if (expr.op === '||') return l ? l : evalConst(expr.right, constFns);
       return undefined;
     }
     case 'ident': {
@@ -62,6 +125,20 @@ function evalConst(expr) {
       // x === x style: the engine can't fold this without symbolic equality.
       return undefined;
     }
+    case 'call': {
+      // W2.1: a call to a function whose entire body is `return <literal>;`
+      // resolves to that literal — see `buildConstantFnMap` above. Prefer an
+      // exact qid match (rare for hand-rolled parsers' flat callee strings,
+      // but free to check), fall back to the collision-refused bare-name map.
+      if (!constFns) return undefined;
+      if (typeof expr.callee === 'string' && constFns.byQid.has(expr.callee)) {
+        return constFns.byQid.get(expr.callee);
+      }
+      const bare = _bareCalleeName(expr.callee);
+      if (!bare) return undefined;
+      const v = constFns.byBareName.get(bare);
+      return v === AMBIGUOUS ? undefined : v;
+    }
   }
   return undefined;
 }
@@ -77,7 +154,7 @@ function syntacticallyEqual(a, b) {
   return false;
 }
 
-export function applyPathFeasibility(fn) {
+export function applyPathFeasibility(fn, constFns) {
   if (!fn || !fn.cfg || !fn.cfg.nodes) return { pruned: 0 };
   let pruned = 0;
   for (const id of Object.keys(fn.cfg.nodes)) {
@@ -86,7 +163,7 @@ export function applyPathFeasibility(fn) {
     const cond = node.cond;
     if (!cond) continue;
     // Constant cond?
-    const val = evalConst(cond);
+    const val = evalConst(cond, constFns);
     if (val === true) {
       // Drop the second successor (the false branch).
       if (node.succ.length > 1) {

package/src/dataflow/string-domain.js

@@ -146,8 +146,44 @@ const SANITIZER_OUTPUT_REGEX = {
   // (We can't distinguish overloads from regex name alone; conservative listing.)
   // PHP htmlspecialchars / htmlentities — HTML-entity escape.
   htmlspecialchars:   /^[^<>&"']*(?:&(?:lt|gt|amp|quot|#039);)*[^<>&"']*$/,
+  // JS-ecosystem HTML escapers (he/escape-html/lodash.escape and similar
+  // libraries all converge on the same five-entity escape set) — same
+  // shape as htmlspecialchars above, different ecosystem name. Added
+  // during the SMT path-feasibility rebuild: this exact name was already
+  // trusted by exploit-prover.js's own (now-superseded) duplicate table,
+  // so omitting it here would have been a real regression, not a
+  // deliberate narrowing.
+  escapeHtml:         /^[^<>&"']*(?:&(?:lt|gt|amp|quot|#039);)*[^<>&"']*$/,
 };
 
+// Next-gen taint capability #5 (SMT path-feasibility rebuild) — a SAFE,
+// bare-tail lookup against the SAME catalog `abstract()` above already
+// uses, exported so a soundness-critical consumer (the SMT/exploit-prover
+// infeasibility check) can reuse this exact table rather than maintaining
+// its own, inevitably-drifting copy — confirmed live that THREE separate,
+// slightly different sanitizer-regex tables existed across this codebase
+// before this fix (this one, exploit-prover.js's own `_sanitizerRegexFor`,
+// and smt-feasibility.js's now-superseded encoder), each with subtly
+// different entries.
+//
+// Deliberately EXCLUDES `toString` from what this function will return:
+// `abstract()`'s own use of the FULL table above is fine with the
+// over-approximation (worst case, a coarser Regex/Unknown classification —
+// never a false SAFETY claim on its own, since nothing downstream of
+// `abstract()` treats its answer as license to PROVE a finding infeasible).
+// A soundness-critical consumer is different in kind: treating "this
+// callee's output matches the regex" as grounds to demote a finding to
+// provably-unreachable must not trust a name as ambiguous as `toString`
+// (matches ANY object's own stringifier, not just a Buffer's base64
+// encoding specifically) — an incorrect match there would manufacture a
+// false "provably safe" verdict for a genuinely exploitable finding.
+export function safeSanitizerOutputRegex(calleeName) {
+  if (!calleeName) return null;
+  const tail = String(calleeName).split('.').pop();
+  if (tail === 'toString') return null;
+  return SANITIZER_OUTPUT_REGEX[tail] || null;
+}
+
 /**
  * SAFE-CHARSET PROOF — does the abstract value provably fit the given regex?
  *
@@ -232,3 +268,135 @@ export function isSafeRedirectTarget(absVal, allowedHosts) {
 export function hashAbstract(absVal) {
   return render(absVal);
 }
+
+/**
+ * Next-gen taint capability #2 — regex-VALIDATION guard safety.
+ *
+ * A DIFFERENT question from `provablyMatches` above (which asks "does this
+ * already-known abstract value fit a safety regex"): here we're asked "is
+ * this REGEX PATTERN, used as a `pattern.test(x)`-style validation guard,
+ * restrictive enough that observing it MATCH on the true branch proves `x`
+ * cannot carry injection metacharacters for ANY family?" This is the JS/TS
+ * analog of PHP's `if (preg_match($re, $x) == 1) { ... }` idiom — found to
+ * be a genuine, real-world-common pattern with NO recognition anywhere in
+ * this engine (neither the name-based `GUARD_PREDICATES` in engine.js, nor
+ * this file's own `abstract()`/`SANITIZER_OUTPUT_REGEX`, which characterizes
+ * a SANITIZER CALL's output, not a validation-guard's CONDITION).
+ *
+ * Deliberately a conservative ALLOWLIST parser, not a full regex-engine
+ * subset check (undecidable in general): walks the pattern character by
+ * character, permitting only literal safe characters (letters, digits, and
+ * a short vetted punctuation set), `\d`/`\w` shorthand classes, and
+ * bracket character classes built from the same safe set — with
+ * quantifiers on any of the above. Anything it cannot fully account for
+ * (alternation, groups, wildcards, negated classes `[^...]`, negated
+ * shorthand `\D`/`\W`/`\s`/`\S`, backreferences, lookaround, unicode
+ * property escapes, an unescaped stray metacharacter) REJECTS rather than
+ * guesses — a false "safe" here would silently suppress a real,
+ * exploitable finding, which is a much worse failure mode than missing a
+ * genuinely-safe-but-unrecognized pattern (the existing, unchanged taint
+ * flow still fires in that case, exactly as it did before this capability
+ * existed).
+ *
+ * Also requires full anchoring (`^...$`) and rejects the `m` (multiline)
+ * flag: with `m` set, `^`/`$` match at LINE boundaries rather than string
+ * boundaries, so a multi-line input could have a safe first line and an
+ * unsafe second line while still matching `^safe$` against line one —
+ * silently defeating the "matched, therefore the WHOLE value is safe"
+ * guarantee this function exists to provide.
+ */
+export function isSafeValidationPattern(pattern) {
+  if (!(pattern instanceof RegExp)) return false;
+  if (pattern.flags && pattern.flags.includes('m')) return false;
+  const source = pattern.source;
+  if (!source.startsWith('^') || !source.endsWith('$')) return false;
+  const body = source.slice(1, -1);
+  if (!body) return false; // `^$` (empty-string-only) is degenerate, not a useful guard
+  // Two DISTINCT allowlists, deliberately not merged into one — conflating
+  // them is exactly the bug this comment now documents (caught by this
+  // function's own adversarial unit tests before ever reaching production):
+  //
+  // `isSafeBareChar` — characters with NO special regex meaning when they
+  // appear UNESCAPED. Critically, `.` (the wildcard metacharacter — matches
+  // ANY character) is NOT in this set: an earlier version of this function
+  // included `.` here on the (wrong) assumption that it's "just punctuation,"
+  // which caused `/^.*$/` — the real PHP generator's OWN "no_filtering"
+  // unsafe sample, matching literally everything — to be accepted as a safe
+  // guard. A bare `.` in a pattern is ALWAYS the wildcard; a literal dot
+  // must be escaped (`\.`) or appear inside a character class (`[.]`),
+  // both handled by the escaped/class-content paths below.
+  //
+  // `isSafeEscapedPunct` — punctuation that, when ESCAPED with a backslash,
+  // unambiguously means "match this literal character." Deliberately
+  // EXCLUDES every letter and digit: an escaped letter in regex syntax is
+  // Two DELIBERATELY SEPARATE allowlists, keyed by context, not merged into
+  // one — conflating them is the exact bug class this function's own
+  // adversarial unit tests caught twice while writing it, both fixed here:
+  //
+  // `isSafeBareChar` (governs an UNESCAPED character, bare or inside a
+  // class) — letters, digits, underscore, hyphen, at-sign: characters with
+  // NO special regex meaning at all when unescaped. Crucially this does
+  // NOT include `.` — a bare `.` outside a class is the wildcard
+  // metacharacter (matches ANY character), not punctuation. An earlier
+  // version of this allowlist included `.`, which let `/^.*$/` — the real
+  // PHP generator's own "no_filtering" UNSAFE sample, matching literally
+  // everything — pass as a safe guard.
+  //
+  // `isSafeEscapedChar` (governs a character immediately AFTER a
+  // backslash) — punctuation ONLY, deliberately excluding every letter and
+  // digit. An escaped letter in regex syntax is NEVER a plain literal:
+  // `\d`/`\D`/`\w`/`\W`/`\s`/`\S`/`\b`/`\B` are shorthand/boundary
+  // constructs, `\1`/`\2`/… are backreferences, and any other escaped
+  // letter could be a unicode property escape (`\p{...}`) or named
+  // backreference this parser has never heard of. An earlier version of
+  // this function reused `isSafeBareChar` (which includes letters) for the
+  // escaped-character check too, so `\D` (negated digit — matches almost
+  // anything) was accepted as though it meant a literal capital D.
+  const isSafeBareChar = (ch) => /^[a-zA-Z0-9_\-@]$/.test(ch);
+  const isSafeEscapedChar = (ch) => /^[_\-@.]$/.test(ch);
+  let i = 0;
+  const consumeQuantifier = () => {
+    if (i >= body.length) return;
+    const ch = body[i];
+    if (ch === '*' || ch === '+' || ch === '?') { i++; return; }
+    if (ch === '{') {
+      const close = body.indexOf('}', i);
+      if (close === -1) throw new Error('unterminated');
+      if (!/^\d+(,\d*)?$/.test(body.slice(i + 1, close))) throw new Error('malformed');
+      i = close + 1;
+    }
+  };
+  try {
+    while (i < body.length) {
+      const ch = body[i];
+      if (ch === '\\') {
+        const next = body[i + 1];
+        if (next === 'd' || next === 'w') { i += 2; consumeQuantifier(); continue; }
+        if (next && isSafeEscapedChar(next)) { i += 2; consumeQuantifier(); continue; }
+        return false; // \D, \W, \s, \S, \b, an escaped letter/digit, unicode escapes, or anything unrecognized
+      }
+      if (ch === '[') {
+        const close = body.indexOf(']', i);
+        if (close === -1) return false;
+        const cls = body.slice(i + 1, close);
+        if (cls.startsWith('^')) return false; // negated class — "anything except", unsafe by construction
+        let j = 0;
+        while (j < cls.length) {
+          if (cls[j] === '\\' && (cls[j + 1] === 'd' || cls[j + 1] === 'w')) { j += 2; continue; }
+          if (cls[j] === '\\' && isSafeEscapedChar(cls[j + 1])) { j += 2; continue; }
+          // Inside a character class, `.` loses its wildcard meaning and IS
+          // a literal dot even when bare — no escaping needed here, unlike
+          // outside a class.
+          if (isSafeBareChar(cls[j]) || cls[j] === '-' || cls[j] === '.') { j++; continue; }
+          return false;
+        }
+        i = close + 1;
+        consumeQuantifier();
+        continue;
+      }
+      if (isSafeBareChar(ch)) { i++; consumeQuantifier(); continue; }
+      return false; // `.`, `|`, `(`, `)`, a bare mid-pattern `^`/`$`, or any other metacharacter
+    }
+  } catch { return false; }
+  return true;
+}