circle-ir 3.108.0 → 3.111.0

package/dist/analysis/passes/sink-filter-pass.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sink-filter-pass.d.ts","sourceRoot":"","sources":["../../../src/analysis/passes/sink-filter-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAwB,MAAM,sBAAsB,CAAC;AACzG,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAye9E,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,sBAAsB;IACtB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,qBAAa,cAAe,YAAW,YAAY,CAAC,gBAAgB,CAAC;IACnE,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,QAAQ,CAAC,QAAQ,EAAG,UAAU,CAAU;IAExC,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,gBAAgB;CA8pBxC;AAMD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,KAAK,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AA4I1G,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EACjC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,EACxB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,OAAO,EAAE,OAAO,EAChB,GAAG,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,EACrB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC3B,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC/B,QAAQ,CAAC,EAAE,MAAM,GAChB,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CA6E5B;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EACjC,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,EAC3C,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,GACvB,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CA2C5B"}
+{"version":3,"file":"sink-filter-pass.d.ts","sourceRoot":"","sources":["../../../src/analysis/passes/sink-filter-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAwB,MAAM,sBAAsB,CAAC;AACzG,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AA6iB9E,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,sBAAsB;IACtB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,qBAAa,cAAe,YAAW,YAAY,CAAC,gBAAgB,CAAC;IACnE,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,QAAQ,CAAC,QAAQ,EAAG,UAAU,CAAU;IAExC,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,gBAAgB;CA8zBxC;AAkRD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,KAAK,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AA4I1G,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EACjC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,EACxB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,OAAO,EAAE,OAAO,EAChB,GAAG,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,EACrB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC3B,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC/B,QAAQ,CAAC,EAAE,MAAM,GAChB,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CA6E5B;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EACjC,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,EAC3C,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,GACvB,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CA2C5B"}

package/dist/analysis/passes/sink-filter-pass.js

@@ -39,6 +39,65 @@ const JS_XSS_SANITIZERS = [
     /\bbypassSecurityTrust/, // Angular
 ];
 // ---------------------------------------------------------------------------
+// Stage 16 — JS log_injection (CWE-117) sanitizer patterns.
+// (cognium-dev #216 sanitizer-wrapped FP — Sprint 52)
+// ---------------------------------------------------------------------------
+//
+// Common CRLF-stripping / log-sanitization helpers. Used by Stage 16 both as
+// an inline check on the sink line AND as a backward-scan check via the
+// `isAssignedFromSanitizerPattern` helper.
+const JS_LOG_INJECTION_SANITIZERS = [
+    /\bstripCrlf\s*\(/,
+    /\bstripCRLF\s*\(/,
+    /\bremoveNewlines\s*\(/,
+    /\bsanitizeLogValue\s*\(/,
+    // Inline CRLF-stripping regex literal: .replace(/[\r\n]/g, '')
+    /\.replace\(\s*\/\[\s*\\r\s*\\n\s*\]\/[gimsu]*\s*,\s*['"`]['"`]\s*\)/,
+    // Inline CRLF sequence: .replace(/\r\n/g, '')
+    /\.replace\(\s*\/\\r\\n\/[gimsu]*\s*,\s*['"`]['"`]\s*\)/,
+];
+// ---------------------------------------------------------------------------
+// Stage 17 — Python ldap_injection (CWE-90) regex-strip wrapper recognition.
+// (cognium-dev #216 sanitizer-wrapped FP — Sprint 52)
+// ---------------------------------------------------------------------------
+//
+// Built-in Python LDAP sanitizer call-site names. Augmented at scan time with
+// derived wrapper functions detected via `findPythonLdapStripWrappers`.
+const PY_BUILTIN_LDAP_SANITIZERS = ['escape_filter_chars', 'filter_format'];
+// Python `def name(param):` followed (within a few lines) by
+// `return re.sub(r"[<class>]", "", param)` where the character class contains
+// at least three of the LDAP filter metacharacters from RFC 4515.
+const PY_LDAP_METACHARS = ['(', ')', '=', '*', '\\'];
+const PY_DEF_RE = /^\s*def\s+([A-Za-z_]\w*)\s*\(\s*([A-Za-z_]\w*)\s*\)\s*:\s*$/;
+const PY_LDAP_STRIP_RETURN_RE = /^\s*return\s+re\.sub\(\s*r?["']\[([^"'\]]+)\]["']\s*,\s*r?["']["']\s*,\s*([A-Za-z_]\w*)\s*\)\s*$/;
+// ---------------------------------------------------------------------------
+// Stage 18 — Python xxe (CWE-611) parser-variable / wrapper recognition.
+// (cognium-dev #216 sanitizer-wrapped FP — Sprint 52)
+// ---------------------------------------------------------------------------
+//
+// `XMLParser(...resolve_entities=False...)` constructor — when present in the
+// 30 lines above an xxe sink (same enclosing scope), the parser is hardened
+// and the sink is safe.
+const PY_XML_PARSER_HARDENED_RE = /\bXMLParser\s*\([^)]*\bresolve_entities\s*=\s*False\b[^)]*\)/;
+// ---------------------------------------------------------------------------
+// Stage 19 — Python sql_injection regex-allowlist-quoter wrapper suppression.
+// (cognium-dev #215 — Sprint 53; Python port of Java Stage 15 #191)
+// ---------------------------------------------------------------------------
+//
+// Python f-string SQL where identifier interpolations route through an
+// in-file helper that validates with `re.fullmatch(allowlist, name)`
+// + `raise`, and values flow through bind placeholders (?, %s, :name),
+// is a parameterized query with an identifier-interpolation wrapper.
+// Helper is the sanitizer; bind placeholder proves values do not concat.
+const PY_SQL_EXEC_METHODS = new Set(['execute', 'executemany']);
+// Recognises Python `re.fullmatch(r"<regex>", …)` / `re.match(r"^<…>$", …)`
+// — fullmatch is implicitly anchored; match requires explicit `^…$`.
+const PY_INLINE_FULLMATCH_RE = /\bre\s*\.\s*fullmatch\s*\(\s*r?"((?:[^"\\]|\\.)*)"/g;
+const PY_INLINE_MATCH_ANCHORED_RE = /\bre\s*\.\s*match\s*\(\s*r?"\^((?:[^"\\]|\\.)*)\$"/g;
+// Bind placeholders: `?` (sqlite3/odbc), `%s` (psycopg2/mysqlclient),
+// `:name` (named placeholders). All proof of bind-arg routing.
+const PY_BIND_PLACEHOLDER_RE = /\?|%s|:[A-Za-z_]\w*/;
+// ---------------------------------------------------------------------------
 // Stage 9 — Java code_injection (CWE-094) FP reduction allowlists.
 // (cognium-dev #155, #156, #159, #160 — Sprint 42)
 // ---------------------------------------------------------------------------
@@ -1167,9 +1226,446 @@ export class SinkFilterPass {
                 return true;
             });
         }
+        // Stage 16 — JS log_injection (CWE-117) sanitizer suppression.
+        // (cognium-dev #216 sanitizer-wrapped FP — Sprint 52)
+        //
+        // Gate (any suppresses the sink):
+        //   (a) sink line contains an inline call to a known CRLF-stripping
+        //       helper (stripCrlf, sanitizeLogValue, .replace(/[\r\n]/g, ''))
+        //   (b) sink line references a variable assigned within 30 lines
+        //       above from a sanitizer-pattern RHS
+        if (['javascript', 'typescript'].includes(language)) {
+            const sourceLines = ctx.code.split('\n');
+            filtered = filtered.filter(sink => {
+                if (sink.type !== 'log_injection')
+                    return true;
+                const sinkLineText = sourceLines[sink.line - 1] ?? '';
+                if (JS_LOG_INJECTION_SANITIZERS.some(p => p.test(sinkLineText)))
+                    return false;
+                const varNames = extractSourceIdentifiers(sinkLineText);
+                for (const v of varNames) {
+                    if (isAssignedFromSanitizerPattern(sourceLines, sink.line, v, JS_LOG_INJECTION_SANITIZERS)) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+        }
+        // Stage 17 — Python ldap_injection (CWE-90) regex-strip wrapper
+        // recognition. (cognium-dev #216 sanitizer-wrapped FP — Sprint 52)
+        //
+        // Scan file for module-level wrapper functions whose body is
+        //   return re.sub(r"[<class>]", "", <param>)
+        // where the character class contains at least three of the LDAP filter
+        // metacharacters ( ) = * \. Treat such wrappers (plus the built-in
+        // `escape_filter_chars` / `filter_format`) as LDAP sanitizers.
+        //
+        // Gate (any suppresses the sink):
+        //   (a) sink line contains a direct call to a known LDAP sanitizer
+        //   (b) sink line references a variable assigned within 30 lines above
+        //       from a known LDAP sanitizer call
+        if (language === 'python') {
+            const sourceLines = ctx.code.split('\n');
+            const wrappers = findPythonLdapStripWrappers(sourceLines);
+            const allLdapSanitizers = [...PY_BUILTIN_LDAP_SANITIZERS, ...wrappers];
+            if (allLdapSanitizers.length > 0) {
+                const ldapPatterns = allLdapSanitizers.map(name => new RegExp(`\\b${escapeRegex(name)}\\s*\\(`));
+                filtered = filtered.filter(sink => {
+                    if (sink.type !== 'ldap_injection')
+                        return true;
+                    const sinkLineText = sourceLines[sink.line - 1] ?? '';
+                    if (ldapPatterns.some(p => p.test(sinkLineText)))
+                        return false;
+                    const varNames = extractSourceIdentifiers(sinkLineText);
+                    for (const v of varNames) {
+                        if (isAssignedFromSanitizerPattern(sourceLines, sink.line, v, ldapPatterns)) {
+                            return false;
+                        }
+                    }
+                    return true;
+                });
+            }
+        }
+        // Stage 18 — Python xxe (CWE-611) parser-variable / wrapper recognition.
+        // (cognium-dev #216 sanitizer-wrapped FP — Sprint 52)
+        //
+        // When an xxe sink (fromstring/parse/etc.) appears within the same
+        // enclosing function as an `XMLParser(...resolve_entities=False...)`
+        // constructor, the parser is hardened and the sink is safe. Covers:
+        //   - wrapper functions (`def safe_parse(...): parser = XMLParser(...);
+        //     return ET.fromstring(b, parser)`) — sink inside wrapper body
+        //   - class methods (`def parse_direct(self): parser = XMLParser(...);
+        //     return ET.fromstring(self.xml, parser)`)
+        //
+        // Scope safety: the backward scan stops at the first `def` line so the
+        // safe parser in a sibling/preceding function never suppresses an unsafe
+        // sink in a different function. Recall lock: `XMLParser(resolve_entities
+        // =True)` does NOT match the hardened regex, so /wrong /fake routes
+        // (which build their own unsafe parsers) still fire.
+        if (language === 'python') {
+            const sourceLines = ctx.code.split('\n');
+            filtered = filtered.filter(sink => {
+                if (sink.type !== 'xxe')
+                    return true;
+                const lookback = 30;
+                const lo = Math.max(0, sink.line - 1 - lookback);
+                for (let i = sink.line - 2; i >= lo; i--) {
+                    const ln = sourceLines[i] ?? '';
+                    if (PY_XML_PARSER_HARDENED_RE.test(ln))
+                        return false;
+                    // Function boundary: stop scanning when we leave the sink's
+                    // enclosing def, so a hardened parser in a sibling function never
+                    // suppresses an unsafe sink in this function.
+                    if (/^\s*def\s+\w+\s*\(/.test(ln))
+                        break;
+                }
+                return true;
+            });
+        }
+        // Stage 19 — Python sql_injection regex-allowlist-quoter wrapper
+        // suppression. (cognium-dev #215 — Sprint 53; port of Java Stage 15)
+        //
+        // Gate (all must hold to drop the sink):
+        //   (a) sink method is cursor.execute / cursor.executemany
+        //   (b) sink first arg is an f-string (`f"…{x}…"`) with ≥1 interpolation
+        //   (c) every `{…}` interpolation is a literal OR a bare identifier
+        //       whose assignment within 30 lines above is `<helper>(<arg>)`
+        //       — an in-file helper call
+        //   (d) the f-string literal segments contain a bind placeholder
+        //       (`?`, `%s`, or `:name`)
+        //   (e) at least one such helper's body contains `re.fullmatch(<allowlist>,…)`
+        //       (or anchored `re.match(^…$,…)`) AND a `raise` statement
+        //
+        // Together (a)–(e) prove the SQL is parameterized for values with
+        // identifier interpolation routed through a validated quoter.
+        if (language === 'python') {
+            const sourceLines = ctx.code.split('\n');
+            filtered = filtered.filter(sink => {
+                if (sink.type !== 'sql_injection')
+                    return true;
+                const method = sink.method ?? '';
+                if (!PY_SQL_EXEC_METHODS.has(method))
+                    return true;
+                const sinkLineText = sourceLines[sink.line - 1] ?? '';
+                // Find the f-string first argument: f"…" or f'…'
+                const fstrMatch = sinkLineText.match(/\bf"((?:[^"\\]|\\.)*)"|\bf'((?:[^'\\]|\\.)*)'/);
+                if (!fstrMatch)
+                    return true;
+                const fstrBody = fstrMatch[1] ?? fstrMatch[2] ?? '';
+                const { literals, interps } = splitPyFstringTokens(fstrBody);
+                if (interps.length === 0)
+                    return true;
+                // Gate (d): bind placeholder in literal segments
+                if (!literals.some(lit => PY_BIND_PLACEHOLDER_RE.test(lit)))
+                    return true;
+                // Gate (c) + (e): every interpolation must be a literal or
+                // resolve through an in-file helper with the regex-allowlist+raise
+                // shape. At least one helper match is required.
+                let sawHelperWithGuard = false;
+                for (const interp of interps) {
+                    const t = interp.trim();
+                    if (t === '')
+                        return true;
+                    // Literal-shape interp: bare number / quoted string — accept.
+                    if (/^-?\d+$/.test(t) || /^"(?:[^"\\]|\\.)*"$/.test(t) || /^'(?:[^'\\]|\\.)*'$/.test(t)) {
+                        continue;
+                    }
+                    // Direct in-line helper call: `{helper(arg)}` — extract name.
+                    let helperName = null;
+                    const directCall = t.match(/^([A-Za-z_]\w*)\s*\(/);
+                    if (directCall) {
+                        helperName = directCall[1] ?? null;
+                    }
+                    else if (/^[A-Za-z_]\w*$/.test(t)) {
+                        // Bare identifier — scan backward for assignment from helper call.
+                        helperName = findPythonAssignedHelperCall(t, sink.line, sourceLines);
+                        if (helperName === null)
+                            return true;
+                    }
+                    else {
+                        // Any other expression shape (attribute access, arithmetic,
+                        // method chain) disqualifies — too permissive otherwise.
+                        return true;
+                    }
+                    const body = findPythonFunctionBody(helperName, sourceLines);
+                    if (body && pythonBodyHasInlineRegexAllowlistRaise(body)) {
+                        sawHelperWithGuard = true;
+                    }
+                }
+                if (!sawHelperWithGuard)
+                    return true;
+                return false;
+            });
+        }
         return { sources, sinks: filtered, sanitizers };
     }
 }
+// ---------------------------------------------------------------------------
+// Sprint 52 helpers — shared sanitizer-assignment backward scan utilities.
+// ---------------------------------------------------------------------------
+/**
+ * Escape regex metacharacters in an identifier or literal for use inside a
+ * RegExp template. Identifiers from `def NAME(...)` matches are already
+ * `[A-Za-z_]\w*`-restricted, but kept defensively.
+ */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Reserved keywords across JS/TS/Python that should not be treated as
+ * source-identifier candidates by `extractSourceIdentifiers`.
+ */
+const RESERVED_KEYWORDS = new Set([
+    // JS/TS
+    'if', 'else', 'return', 'const', 'let', 'var', 'function', 'class', 'new',
+    'this', 'for', 'while', 'do', 'break', 'continue', 'switch', 'case',
+    'default', 'try', 'catch', 'finally', 'throw', 'typeof', 'instanceof',
+    'in', 'of', 'await', 'async', 'import', 'export', 'from', 'as', 'void',
+    'null', 'undefined', 'true', 'false', 'super', 'extends', 'static',
+    // Python
+    'def', 'lambda', 'yield', 'pass', 'with', 'global', 'nonlocal', 'and',
+    'or', 'not', 'is', 'None', 'True', 'False', 'raise', 'except', 'elif',
+    'self', 'cls', 'print',
+    // Common stdlib roots that show up everywhere and would balloon scans.
+    'console', 'req', 'res', 'request', 'response',
+]);
+/**
+ * Extract identifier-shaped tokens from a source line. Skips keywords and
+ * single-character names. Used by Stages 16-17 to find candidate variables
+ * whose assignment lines should be scanned backward.
+ */
+function extractSourceIdentifiers(text) {
+    const out = [];
+    const re = /\b([A-Za-z_]\w+)\b/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const name = m[1];
+        if (!RESERVED_KEYWORDS.has(name))
+            out.push(name);
+    }
+    return out;
+}
+/**
+ * Scan upward from `sinkLine` (1-based) for an assignment to `varName`. If
+ * the RHS of that assignment matches any of the supplied sanitizer regexes,
+ * return true. Stops at the first assignment found (no `varName` reassignment
+ * tracking — a benign reassignment after a tainted one is the common shape,
+ * so first-assignment-found-above-the-sink is the precision-correct choice).
+ *
+ * Shared by Stages 16 (JS log_injection) and 17 (Python ldap_injection).
+ */
+function isAssignedFromSanitizerPattern(sourceLines, sinkLine, varName, sanitizerPatterns, lookback = 30) {
+    const escapedVar = escapeRegex(varName);
+    // Match `[<keyword>?] varName = <rhs>` for both JS (`const|let|var`) and
+    // Python (bare assignment) shapes.
+    const assignRe = new RegExp(`(?:\\b(?:const|let|var|final|String)\\s+)?\\b${escapedVar}\\s*=\\s*(.+)`);
+    // Scope boundary: stop at a function declaration so a sibling function's
+    // assignment to the same variable name never crosses scope.
+    const fnBoundaryRe = /^\s*(?:def\s+\w+\s*\(|function\s+\w+\s*\(|\w+\s*[:=]\s*(?:async\s+)?\(?[^)]*\)?\s*=>)/;
+    const lo = Math.max(0, sinkLine - 1 - lookback);
+    for (let i = sinkLine - 2; i >= lo; i--) {
+        const ln = sourceLines[i] ?? '';
+        const m = ln.match(assignRe);
+        if (m) {
+            const rhs = (m[1] ?? '').trim();
+            return sanitizerPatterns.some(p => p.test(rhs));
+        }
+        if (fnBoundaryRe.test(ln))
+            break;
+    }
+    return false;
+}
+/**
+ * Find module-level Python functions whose body is a single
+ * `return re.sub(r"[<class>]", "", param)` line where the character class
+ * contains at least three of the LDAP filter metacharacters `( ) = * \`.
+ *
+ * Returns the function names. Conservative scan window: looks at the first
+ * three non-blank lines after the `def` to find the `return re.sub(...)`.
+ */
+function findPythonLdapStripWrappers(sourceLines) {
+    const out = [];
+    for (let i = 0; i < sourceLines.length; i++) {
+        const defMatch = sourceLines[i].match(PY_DEF_RE);
+        if (!defMatch)
+            continue;
+        const fnName = defMatch[1];
+        const param = defMatch[2];
+        // Scan next non-blank/comment line for the return re.sub(...) pattern.
+        for (let j = i + 1; j < Math.min(i + 4, sourceLines.length); j++) {
+            const body = sourceLines[j];
+            if (/^\s*$/.test(body) || /^\s*#/.test(body))
+                continue;
+            const ret = body.match(PY_LDAP_STRIP_RETURN_RE);
+            if (!ret)
+                break;
+            const charClass = ret[1];
+            const argName = ret[2];
+            if (argName !== param)
+                break;
+            const metaCount = PY_LDAP_METACHARS.filter(c => charClass.includes(c)).length;
+            if (metaCount >= 3)
+                out.push(fnName);
+            break;
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Stage 19 (#215) Python helpers — f-string interp split, function body
+// scan via indent depth, and inline regex-allowlist+raise recognition.
+// ---------------------------------------------------------------------------
+/**
+ * Stage 19 (#215) — split a Python f-string body into literal segments and
+ * brace interpolations. Returns parallel arrays. Conservative: only flat
+ * `{<expr>}` interpolations are recognised (no nested f-strings, no
+ * format-specs after `:` since `:` overlaps with named-bind placeholders).
+ * Escape sequence `{{`/`}}` is preserved as literal text.
+ */
+function splitPyFstringTokens(body) {
+    const literals = [];
+    const interps = [];
+    let i = 0;
+    let cur = '';
+    while (i < body.length) {
+        const ch = body[i] ?? '';
+        if (ch === '{' && body[i + 1] === '{') {
+            cur += '{';
+            i += 2;
+            continue;
+        }
+        if (ch === '}' && body[i + 1] === '}') {
+            cur += '}';
+            i += 2;
+            continue;
+        }
+        if (ch === '{') {
+            literals.push(cur);
+            cur = '';
+            i++;
+            let depth = 1;
+            let expr = '';
+            while (i < body.length && depth > 0) {
+                const ch2 = body[i] ?? '';
+                if (ch2 === '{') {
+                    depth++;
+                    expr += ch2;
+                    i++;
+                    continue;
+                }
+                if (ch2 === '}') {
+                    depth--;
+                    if (depth === 0) {
+                        i++;
+                        break;
+                    }
+                    expr += ch2;
+                    i++;
+                    continue;
+                }
+                expr += ch2;
+                i++;
+            }
+            // Strip any trailing format-spec (after `:` at depth 0) — but only
+            // when there's a non-trivial spec so we don't false-strip identifiers
+            // containing `:` (which shouldn't happen syntactically anyway).
+            const colonIdx = expr.indexOf(':');
+            const interp = colonIdx >= 0 ? expr.substring(0, colonIdx) : expr;
+            interps.push(interp);
+            continue;
+        }
+        cur += ch;
+        i++;
+    }
+    literals.push(cur);
+    return { literals, interps };
+}
+/**
+ * Stage 19 (#215) — find the helper-name assigned to `varName` within 30
+ * lines above `sinkLine` (1-based). Returns the helper function name if
+ * the RHS is a bare `helper(<arg>)` call, otherwise null.
+ */
+function findPythonAssignedHelperCall(varName, sinkLine, sourceLines) {
+    if (!/^[A-Za-z_]\w*$/.test(varName))
+        return null;
+    const lo = Math.max(0, sinkLine - 31);
+    const assignRe = new RegExp(`^\\s*${varName}\\s*=\\s*([A-Za-z_]\\w*)\\s*\\(`);
+    for (let i = sinkLine - 2; i >= lo; i--) {
+        const ln = sourceLines[i] ?? '';
+        const m = ln.match(assignRe);
+        if (m)
+            return m[1] ?? null;
+    }
+    return null;
+}
+/**
+ * Stage 19 (#215) — locate a Python function body by name using indent
+ * depth. Returns the body lines (between the `def` and the first line whose
+ * indent is ≤ the `def` line's indent) or null when not found.
+ *
+ * Conservative textual scan — does not handle decorators across multiple
+ * lines or nested functions with the same name. Sufficient for the
+ * regex-allowlist guard recognition.
+ */
+function findPythonFunctionBody(funcName, sourceLines) {
+    if (!/^[A-Za-z_]\w*$/.test(funcName))
+        return null;
+    const sigRe = new RegExp(`^(\\s*)def\\s+${funcName}\\s*\\(`);
+    for (let i = 0; i < sourceLines.length; i++) {
+        const ln = sourceLines[i] ?? '';
+        const m = ln.match(sigRe);
+        if (!m)
+            continue;
+        const baseIndent = (m[1] ?? '').length;
+        const body = [];
+        for (let j = i + 1; j < sourceLines.length; j++) {
+            const ln2 = sourceLines[j] ?? '';
+            if (ln2.trim() === '') {
+                body.push(ln2);
+                continue;
+            }
+            const indentMatch = ln2.match(/^(\s*)/);
+            const indent = (indentMatch?.[1] ?? '').length;
+            if (indent <= baseIndent)
+                break;
+            body.push(ln2);
+        }
+        return body;
+    }
+    return null;
+}
+/**
+ * Stage 19 (#215) — true if the Python function body contains
+ *   `re.fullmatch(r"<strict-anchored-regex>", …)`  OR
+ *   `re.match(r"^<…>$", …)`
+ * AND a `raise` statement. The two need not be in the same `if`; the
+ * combination proves the parameter is validated and any non-allowlisted
+ * input terminates execution before the function returns.
+ */
+function pythonBodyHasInlineRegexAllowlistRaise(bodyLines) {
+    // Strip inline `# …` comments from each line so words like "raise" or
+    // `re.fullmatch` appearing in commentary don't trigger a false guard
+    // detection. Conservative: this does not handle `#` inside string
+    // literals, but the surrounding code already operates on textual lines
+    // and the false-suppression risk from a `#` inside a string is bounded
+    // by the other gates (must also have anchored regex + bind placeholder).
+    const stripped = bodyLines.map(ln => ln.replace(/#.*$/, ''));
+    const text = stripped.join('\n');
+    if (!/\braise\s+/.test(text))
+        return false;
+    PY_INLINE_FULLMATCH_RE.lastIndex = 0;
+    let m;
+    while ((m = PY_INLINE_FULLMATCH_RE.exec(text)) !== null) {
+        if (isImplicitlyAnchoredAllowlistRegex(m[1] ?? ''))
+            return true;
+    }
+    PY_INLINE_MATCH_ANCHORED_RE.lastIndex = 0;
+    while ((m = PY_INLINE_MATCH_ANCHORED_RE.exec(text)) !== null) {
+        if (isImplicitlyAnchoredAllowlistRegex(m[1] ?? ''))
+            return true;
+    }
+    return false;
+}
 /**
  * Evaluate a simple arithmetic expression containing only digits, spaces, and
  * the operators +, -, *, /, and parentheses. Uses a recursive descent parser