circle-ir 4.14.2 → 4.16.0

package/dist/analysis/taint-propagation.js

@@ -7,6 +7,7 @@
 import { CodeGraph } from '../graph/index.js';
 import { walkBackwardDefs } from './dfg-walk.js';
 import { sanitizerCoversSink } from './sanitizer-index.js';
+import { HTML_CONTEXT_ENCODER_METHODS, HTML_CONTEXT_ENCODER_UNCOVERED_SINKS } from './constant-propagation/patterns.js';
 /**
  * Build a line → sanitizers index from a list of sanitizers.
  *
@@ -30,11 +31,19 @@ function buildSanitizersByLine(sanitizers) {
  * Accepts either a CodeGraph (preferred) or the legacy (dfg, calls, ...) signature
  * for backward compatibility with existing call sites and tests.
  */
+/** Number of `${…}` interpolations in a JS/TS template-literal argument. */
+function templateInterpolationCount(expression) {
+    if (!expression.trimStart().startsWith('`'))
+        return 0;
+    return (expression.match(/\$\{/g) ?? []).length;
+}
 /** True when `+` appears outside string literals. */
 function concatOutsideStrings(expression) {
     return expression.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g, ' ').includes('+');
 }
-export function propagateTaint(graphOrDfg, callsOrSources, sourcesOrSinks, sinksOrSanitizers, sanitizersArg) {
+export function propagateTaint(graphOrDfg, callsOrSources, sourcesOrSinks, sinksOrSanitizers, sanitizersArg, 
+/** Optional source text — used when DFG defs lack `expression` (Java locals). */
+sourceCode) {
     let graph;
     let sources;
     let sinks;
@@ -63,6 +72,7 @@ export function propagateTaint(graphOrDfg, callsOrSources, sourcesOrSinks, sinks
     const taintedVars = [];
     const flows = [];
     const javaConcat = graph.ir.meta.language === 'java';
+    const jsLike = graph.ir.meta.language === 'javascript' || graph.ir.meta.language === 'typescript';
     const reachableSinks = new Map();
     // Use pre-computed indexes from CodeGraph — no local map building needed
     const defsByLine = graph.defsByLine;
@@ -77,27 +87,51 @@ export function propagateTaint(graphOrDfg, callsOrSources, sourcesOrSinks, sinks
         ? buildSanitizersByLine(sanitizers)
         : graph.sanitizersByLine;
     const defById = graph.defById;
+    const sourceLines = typeof sourceCode === 'string' ? sourceCode.split('\n') : [];
+    const lineText = (line) => {
+        const raw = sourceLines[line - 1];
+        return raw !== undefined ? raw : undefined;
+    };
     // Step 1: Identify initial tainted definitions (from sources)
-    const rawInitialTaint = findInitialTaint(sources, callsByLine, defsByLine);
+    const rawInitialTaint = findInitialTaint(sources, callsByLine, defsByLine, graph.chainsByFromDef, jsLike, lineText);
     // Filter variables added via the "next-line" heuristic that are actually the
     // result of a sanitizer call.  The source variable itself (tv.line ===
     // tv.sourceLine) is always tainted; next-line additions need an extra check.
-    const initialTaint = rawInitialTaint.filter(tv => {
+    const filteredInitialTaint = rawInitialTaint.filter(tv => {
         if (tv.line === tv.sourceLine)
             return true;
+        if (graph.taintBarrierDefIds.has(tv.defId))
+            return false;
         const sanCheck = checkSanitized(tv.sourceLine, tv.line, tv.sourceType, sanitizersByLine);
         return !sanCheck.sanitized;
     });
+    // Propagation is a BFS that credits each definition to the first seed that
+    // reaches it. A bare function parameter (`interprocedural_param`) is only
+    // speculative evidence, and its line usually precedes the handler that
+    // reads real input, so seeding it first let it claim definitions that a
+    // real source also reaches: `const ident = async (x) => x; … v = await
+    // ident(req.query.u)` credited `v` to `x`, and the flow was then dropped
+    // as parameter-only. Seed real sources first so they win any shared
+    // definition; parameter-only reach is unchanged.
+    const initialTaint = [
+        ...filteredInitialTaint.filter(tv => tv.sourceType !== 'interprocedural_param'),
+        ...filteredInitialTaint.filter(tv => tv.sourceType === 'interprocedural_param'),
+    ];
     taintedVars.push(...initialTaint);
     // Step 2: Propagate taint through def-use chains
-    const propagatedTaint = propagateThroughChains(initialTaint, graph.chainsByFromDef, defById, sanitizersByLine);
-    taintedVars.push(...propagatedTaint);
+    const propagatedTaint = propagateThroughChains(initialTaint, graph.chainsByFromDef, defById, sanitizersByLine, graph.taintBarrierDefIds, lineText);
+    // #589: variables that survived only an HTML-encoder hop (`survivesOnlyFor`)
+    // are not general taint, so they stay out of the reported `taintedVars`; they
+    // still seed the sink check below, which lets them reach only the sink types
+    // the encoder does not clean (`trust_boundary`).
+    taintedVars.push(...propagatedTaint.filter(tv => !tv.survivesOnlyFor));
     // Combine all tainted definitions
     const allTaintedDefIds = new Set();
     const taintByDefId = new Map();
-    for (const tv of taintedVars) {
+    for (const tv of [...taintedVars, ...propagatedTaint.filter(tv => tv.survivesOnlyFor)]) {
         allTaintedDefIds.add(tv.defId);
-        taintByDefId.set(tv.defId, tv);
+        if (!yieldsToRealSource(taintByDefId.get(tv.defId), tv))
+            taintByDefId.set(tv.defId, tv);
     }
     // Step 3: Check which sinks are reachable from tainted variables
     for (const sink of sinks) {
@@ -125,7 +159,11 @@ export function propagateTaint(graphOrDfg, callsOrSources, sourcesOrSinks, sinks
                 //     A constant prefix must not hide a later tainted operand
                 //     (cognium-dev#627).
                 const expr = typeof arg.expression === 'string' ? arg.expression : '';
-                const compoundConcat = javaConcat && !!arg.variable && expr !== arg.variable && concatOutsideStrings(expr);
+                // cognium-dev#563: a JS/TS template literal names its first
+                // interpolated identifier as `arg.variable`; a sanitized first value
+                // (`${n}` from `parseInt`) must not hide a raw `${to}` after it.
+                const compoundConcat = !!arg.variable && expr !== arg.variable && ((javaConcat && concatOutsideStrings(expr)) ||
+                    (jsLike && templateInterpolationCount(expr) > 1));
                 const candidateUses = arg.variable && !compoundConcat
                     ? usesAtSink.filter(u => u.variable === arg.variable)
                     : usesAtSink;
@@ -146,6 +184,10 @@ export function propagateTaint(graphOrDfg, callsOrSources, sourcesOrSinks, sinks
                                         continue;
                                 }
                                 const taintInfo = taintByDefId.get(use.def_id);
+                                // #589: taint that survived only an HTML-encoder hop is clean for
+                                // every sink type except the ones it still reaches.
+                                if (taintInfo?.survivesOnlyFor && !taintInfo.survivesOnlyFor.has(sink.type))
+                                    continue;
                                 if (taintInfo) {
                                     // Check if sanitized.
                                     //
@@ -215,12 +257,142 @@ export function propagateTaint(graphOrDfg, callsOrSources, sourcesOrSinks, sinks
 /**
  * Find initial tainted definitions from sources.
  */
-function findInitialTaint(sources, callsByLine, defsByLine) {
+/** Locations of sources that name exactly one parameter binding (#586, #587). */
+const PARAM_SCOPED_SOURCE_RE = /^(?:GraphQL \w+\.\w+ resolver args|Express handler destructured request) /;
+/**
+ * True when `code` (one trimmed source line) is an `if` / `else if` / `while`
+ * header whose parenthesised condition closes on that same line.
+ */
+function isCompleteConditionHeader(code) {
+    if (!code)
+        return false;
+    const m = /^(?:\}\s*)?(?:else\s+)?(?:if|while)\s*\(/.exec(code);
+    if (!m)
+        return false;
+    // Blank out string / char literals so their parens do not count.
+    const text = code.slice(m[0].length - 1).replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`/g, '""');
+    let depth = 0;
+    for (const ch of text) {
+        if (ch === '(')
+            depth++;
+        else if (ch === ')' && --depth === 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * True when `code` (one trimmed source line) holds a second statement after a
+ * `;` (`a := f(); b := "x"`). A `for (…;…;…)` header and a trailing comment
+ * or closing brace do not count.
+ */
+function hasSecondStatement(code) {
+    if (!code || /^for\b/.test(code))
+        return false;
+    const text = code.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`/g, '""');
+    return /;\s*(?!\/\/|\/\*|#|\}|\)|$)\S/.test(text);
+}
+/**
+ * #490: on a line that holds several statements, true when the one statement
+ * that defines `variable` is positively known not to read `via`. The data-flow
+ * graph links a use to every definition on its line, so in
+ * `const q = req.query.q; const tool = "ls";` the handler parameter `req` would
+ * otherwise reach `tool`. Returns false whenever the defining statement cannot
+ * be isolated (no match, more than one match, a destructuring or other form the
+ * scan does not read) so the line-granular behaviour is kept.
+ */
+function lineDefinitionLacksUse(lineCode, variable, via) {
+    if (!/^[A-Za-z_$][\w$]*$/.test(variable) || !/^[A-Za-z_$][\w$]*$/.test(via))
+        return false;
+    // Blank string / char / template literals so `;` and identifiers inside them do not count.
+    let text = lineCode.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`/g, m => '"' + ' '.repeat(Math.max(0, m.length - 2)) + '"');
+    // Drop a trailing `//` comment. Any `/` left over may open a regex literal
+    // (`/;/.test(q)`) whose `;` or `=` would mislead the scan, so keep the
+    // line-granular behaviour.
+    text = text.replace(/(^|[\s;{}])\/\/.*$/, '$1');
+    if (text.includes('/'))
+        return false;
+    const name = variable.replace(/\$/g, '\\$');
+    // A second write to the variable on the line (compound assignment, `++`/`--`,
+    // or a destructuring assignment target such as `[a, b] = [b, a]`) means the
+    // first initializer is not its only value.
+    if (new RegExp(String.raw `(?<![.\w$])${name}\s*(?:\*\*|<<|>>>?|&&|\|\||\?\?|[-+*%&|^])=`).test(text))
+        return false;
+    if (new RegExp(String.raw `(?<![.\w$])${name}\s*(?:\+\+|--)|(?:\+\+|--)\s*${name}(?![\w$])`).test(text))
+        return false;
+    for (const d of text.matchAll(/[\[{]([^[\]{}]*)[\]}]\s*=(?![=>])/g)) {
+        if (new RegExp(String.raw `(?<![.\w$])${name}(?![\w$])`).test(d[1]))
+            return false;
+    }
+    const declRe = new RegExp(String.raw `(?<![.\w$])${name}\s*(?::=|=|:[^=;]*=)(?![=>])`, 'g');
+    const matches = [...text.matchAll(declRe)];
+    if (matches.length !== 1)
+        return false;
+    const m = matches[0];
+    // The initializer runs to the next `;` at its own nesting depth, or to the
+    // closer of the block / call it sits in. When neither is on this line the
+    // initializer wraps (`'ls ' +` / `(` then `q);` below), so it cannot be judged.
+    let depth = 0;
+    let end = -1;
+    for (let i = m.index + m[0].length; i < text.length; i++) {
+        const c = text[i];
+        if (c === '(' || c === '[' || c === '{')
+            depth++;
+        else if (c === ')' || c === ']' || c === '}') {
+            if (--depth < 0) {
+                end = i;
+                break;
+            }
+        }
+        else if (c === ';' && depth === 0) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0)
+        return false;
+    const bounded = text.slice(m.index + m[0].length, end).trim();
+    if (bounded === '' || /[-+*%&|^!~<>=?:,.([{]$/.test(bounded))
+        return false;
+    // Judge the original text of the initializer: an identifier inside a literal
+    // (`$"make {q}"`, `f"{q}"`, `${q}`) counts as a read. Blanking keeps offsets.
+    const rhs = lineCode.slice(m.index + m[0].length, end);
+    return !new RegExp(String.raw `(?<![.\w$])${via.replace(/\$/g, '\\$')}(?![\w$])`).test(rhs);
+}
+function findInitialTaint(sources, callsByLine, defsByLine, chainsByFromDef, jsLike = false, lineText) {
     const tainted = [];
     for (const source of sources) {
         // Find definitions on the same line as the source
         const defsOnLine = defsByLine.get(source.line) ?? [];
+        // cognium-dev#490: `q := r.FormValue("q"); x := "fixed"` puts two
+        // statements on the source line. Only the source's own binding, and a
+        // same-line definition the data-flow graph derives from it
+        // (`w := r.FormValue("w"); cmd := "x " + w`), is tainted; an unrelated
+        // neighbour statement's definition is not.
+        let seedable = null;
+        // The whole line, not just the text from the source: a statement before the
+        // read (`const tool = "ls"; const q = req.query.q;`) is a second statement too.
+        const lineCode = lineText?.(source.line)?.trim() || source.code;
+        if (source.variable && hasSecondStatement(lineCode)) {
+            const own = defsOnLine.filter(d => d.variable === source.variable);
+            if (own.length > 0) {
+                seedable = new Set(own.map(d => d.id));
+                for (const d of own) {
+                    for (const c of chainsByFromDef.get(d.id) ?? []) {
+                        const to = defsOnLine.find(o => o.id === c.to_def);
+                        if (!to)
+                            continue;
+                        // The graph links a use to every definition on its line; keep the
+                        // neighbour only when its own statement reads the linked variable.
+                        if (c.via && lineCode && lineDefinitionLacksUse(lineCode, to.variable, c.via))
+                            continue;
+                        seedable.add(c.to_def);
+                    }
+                }
+            }
+        }
         for (const def of defsOnLine) {
+            if (seedable && !seedable.has(def.id))
+                continue;
             // cognium-dev #308 (from cognium-ai#326 / #289): an
             // `interprocedural_param` source names exactly one parameter
             // (`source.variable`, set for Java/C#). Every parameter shares the
@@ -230,12 +402,22 @@ function findInitialTaint(sources, callsByLine, defsByLine) {
             // the bogus taint into `cmd.ExecuteReader()`. Taintable neighbours
             // (`string tableName`) get their own source, so restricting the seed
             // to the named parameter loses nothing.
-            if (source.type === 'interprocedural_param' &&
+            // cognium-dev#586 / #587: framework parameter sources (GraphQL resolver
+            // `args`, Express destructured request keys) also name exactly one
+            // binding; `parent` / `context` / `res` share the signature line.
+            if ((source.type === 'interprocedural_param' || PARAM_SCOPED_SOURCE_RE.test(source.location ?? '')) &&
                 source.variable &&
                 def.kind === 'param' &&
                 def.variable !== source.variable) {
                 continue;
             }
+            // A parameter source stands for the parameter's binding only. Other
+            // definitions that share the signature line are not the parameter:
+            // `const ident = async (x) => x;` defines `ident` there, and seeding it
+            // tainted every `ident(…)` result with the parameter's taint (#490).
+            if (source.type === 'interprocedural_param' && def.kind !== 'param') {
+                continue;
+            }
             tainted.push({
                 variable: def.variable,
                 defId: def.id,
@@ -256,13 +438,40 @@ function findInitialTaint(sources, callsByLine, defsByLine) {
         // purely by line adjacency, then `propagateThroughChains` carries the
         // bogus taint forward to any sink that consumes `cmd` later in the
         // method — that was the FP-03 root cause from issue #101.
-        const defsNextLine = defsByLine.get(source.line + 1) ?? [];
+        //
+        // cognium-dev#596: a source inside a complete `if (…)` / `while (…)` header
+        // (`if (request.getParameter("a") != null)`) is a condition, not the start
+        // of an expression that continues on the next line. The next line is the
+        // body, so `target = "safe";` there must not be seeded by adjacency.
+        //
+        // cognium-dev#563: a source line that is a complete assignment
+        // (`const qty = parseInt(req.query.qty, 10);`) does not continue on the
+        // next line either; a local declared there (`const label = 'units';`)
+        // is a new statement and gets no taint by adjacency. JavaScript /
+        // TypeScript only, the languages this was measured on: in Java the next
+        // line can overwrite a servlet field (`name = "abc";`) that other
+        // requests share, and SecuriBench StrongUpdates4 expects that flow kept.
+        const closesOwnStatement = jsLike && defsOnLine.length > 0 && /;\s*(?:\/\/.*)?$/.test(source.code ?? '');
+        const defsNextLine = isCompleteConditionHeader(source.code)
+            ? []
+            : (defsByLine.get(source.line + 1) ?? []).filter(d => !(closesOwnStatement && d.kind === 'local'));
+        // cognium-dev#490: a source with no binding of its own (a handler signature)
+        // seeds the first body line by adjacency. When that line holds several
+        // statements, a definition whose own statement reads nothing defined on the
+        // source line (`const tool = "ls";` beside `const q = req.query.q;`) is not
+        // a continuation of it.
+        const nextCode = lineText && !source.variable ? lineText(source.line + 1)?.trim() : undefined;
+        const nextMulti = !!nextCode && hasSecondStatement(nextCode);
+        const sourceLineNames = [...new Set(defsOnLine.map(d => d.variable))];
         for (const def of defsNextLine) {
             // Only include if there's a call on the source line
             const callsOnSourceLine = callsByLine.get(source.line) ?? [];
             if (callsOnSourceLine.length > 0) {
                 if (source.variable && def.variable !== source.variable)
                     continue;
+                if (nextMulti && sourceLineNames.length > 0 &&
+                    sourceLineNames.every(n => lineDefinitionLacksUse(nextCode, def.variable, n)))
+                    continue;
                 tainted.push({
                     variable: def.variable,
                     defId: def.id,
@@ -296,17 +505,53 @@ function findInitialTaint(sources, callsByLine, defsByLine) {
     }
     return tainted;
 }
+/**
+ * #589: true when `variable` still appears in a def expression after HTML-encoder
+ * calls are masked — e.g. `escapeHtml(a) + b` keeps `b` as a raw operand.
+ */
+function identifierOutsideHtmlEncoderCalls(variable, expression, sans) {
+    if (!expression || !sans || sans.length === 0)
+        return false;
+    if (!/^[A-Za-z_$][\w$]*$/.test(variable))
+        return false;
+    const refs = [];
+    for (const san of sans) {
+        if (!isHtmlContextEncoder(san))
+            continue;
+        const m = /(?:(\w+)\.)?(\w+)\(\)/.exec(san.method);
+        if (!m?.[2])
+            continue;
+        refs.push({ receiver: m[1], methodName: m[2] });
+    }
+    if (refs.length === 0)
+        return false;
+    const masked = maskSanitizerCalls(expression, refs);
+    if (masked === expression)
+        return false;
+    const re = new RegExp(`(?:^|[^A-Za-z0-9_$])${variable.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:[^A-Za-z0-9_$]|$)`);
+    return re.test(blankStringLiterals(masked));
+}
+/**
+ * True when `next` is a bare-parameter seed and `existing` already credits the
+ * same definition to a real source: the real source keeps the definition.
+ */
+function yieldsToRealSource(existing, next) {
+    return existing !== undefined &&
+        next.sourceType === 'interprocedural_param' &&
+        existing.sourceType !== 'interprocedural_param';
+}
 /**
  * Propagate taint through def-use chains.
  * Accepts a pre-computed chainsByFromDef index (from CodeGraph) — no internal
  * adjacency list building needed.
  */
-function propagateThroughChains(initialTaint, chainsByFromDef, defById, sanitizersByLine) {
+function propagateThroughChains(initialTaint, chainsByFromDef, defById, sanitizersByLine, taintBarrierDefIds, lineText) {
     const propagated = [];
     const taintedDefIds = new Set(initialTaint.map(t => t.defId));
     const taintInfoByDefId = new Map();
     for (const t of initialTaint) {
-        taintInfoByDefId.set(t.defId, t);
+        if (!yieldsToRealSource(taintInfoByDefId.get(t.defId), t))
+            taintInfoByDefId.set(t.defId, t);
     }
     // BFS to propagate taint
     const queue = [...initialTaint.map(t => t.defId)];
@@ -318,14 +563,32 @@ function propagateThroughChains(initialTaint, chainsByFromDef, defById, sanitize
             continue;
         const outgoingChains = chainsByFromDef.get(currentDefId) ?? [];
         for (const chain of outgoingChains) {
-            if (visited.has(chain.to_def))
+            // A measure/test of the value or a constant-table lookup (#568, #667).
+            if (taintBarrierDefIds.has(chain.to_def))
                 continue;
             const targetDef = defById.get(chain.to_def);
             if (!targetDef)
                 continue;
+            // #490: the graph links a use to every definition on its line; on a line
+            // with a second statement the link holds only when the use is in the
+            // definition's own statement.
+            if (chain.via && lineText) {
+                const code = lineText(targetDef.line)?.trim();
+                if (code && hasSecondStatement(code) && lineDefinitionLacksUse(code, targetDef.variable, chain.via))
+                    continue;
+            }
             // Check if there's a sanitizer between source and this def
             const sanitizeCheck = checkSanitized(currentTaint.sourceLine, targetDef.line, currentTaint.sourceType, sanitizersByLine);
-            if (!sanitizeCheck.sanitized) {
+            const sansAtTarget = sanitizersByLine.get(targetDef.line);
+            // #589: decide encoder-only per operand, not per line. A raw sibling on
+            // `escapeHtml(a) + b` is unrestricted even though the line has an encoder.
+            const viaName = chain.via || currentTaint.variable;
+            const rawOperand = identifierOutsideHtmlEncoderCalls(viaName, targetDef.expression ?? lineText?.(targetDef.line), sansAtTarget);
+            const effectivelySanitized = sanitizeCheck.sanitized && !rawOperand;
+            // #589: a hop through a context-specific HTML encoder keeps the taint
+            // alive for the sink types the encoder does not clean (`trust_boundary`).
+            const encoderOnly = effectivelySanitized && sanitizersAreHtmlContextEncoders(sansAtTarget);
+            if (!effectivelySanitized || encoderOnly) {
                 const newTaint = {
                     variable: targetDef.variable,
                     defId: targetDef.id,
@@ -333,7 +596,28 @@ function propagateThroughChains(initialTaint, chainsByFromDef, defById, sanitize
                     sourceType: currentTaint.sourceType,
                     sourceLine: currentTaint.sourceLine,
                     confidence: currentTaint.confidence * 0.95, // Decay confidence slightly
+                    ...(encoderOnly
+                        ? { survivesOnlyFor: HTML_CONTEXT_ENCODER_UNCOVERED_SINKS }
+                        : currentTaint.survivesOnlyFor ? { survivesOnlyFor: currentTaint.survivesOnlyFor } : {}),
                 };
+                const existing = taintInfoByDefId.get(targetDef.id);
+                if (visited.has(chain.to_def)) {
+                    // #589: first-wins `visited` kept an encoder-only predecessor; a later
+                    // unrestricted chain must replace it and keep propagating.
+                    if (!existing?.survivesOnlyFor)
+                        continue;
+                    if (newTaint.survivesOnlyFor)
+                        continue;
+                    const idx = propagated.findIndex(t => t.defId === targetDef.id);
+                    if (idx >= 0)
+                        propagated[idx] = newTaint;
+                    else
+                        propagated.push(newTaint);
+                    taintedDefIds.add(targetDef.id);
+                    taintInfoByDefId.set(targetDef.id, newTaint);
+                    queue.push(targetDef.id);
+                    continue;
+                }
                 propagated.push(newTaint);
                 taintedDefIds.add(targetDef.id);
                 taintInfoByDefId.set(targetDef.id, newTaint);
@@ -443,6 +727,11 @@ function maskSanitizerCalls(expr, refs) {
     }
     return out;
 }
+function maskLengthOf(expr) {
+    return expr
+        .replace(/\b(?:len|strlen|count)\s*\(\s*[\w$.]+\s*\)/g, ' 0 ')
+        .replace(/[\w$.]+\s*\.\s*(?:length|size|count)\s*(?:\(\s*\))?(?![\w$(])/g, ' 0 ');
+}
 function blankStringLiterals(expr) {
     return expr
         .replace(/"(?:[^"\\]|\\.)*"/g, '""')
@@ -466,22 +755,79 @@ export function identifierOutsideSanitizerCalls(variable, calls, sanitizers, sin
     for (const call of calls) {
         if (refs.some(r => r.methodName === call.method_name))
             continue;
-        for (const arg of call.arguments) {
+        // A same-line guard (`IsLocalUrl(next); Redirect(next)`) is not a
+        // partial wrap. Only a call with an argument that itself contains the
+        // sanitizer call can leave a raw operand: in that argument, or in a
+        // sibling argument of the same call (`Printf("%s %s", clean(a), b)`).
+        const masked = call.arguments.map(arg => {
             const expr = arg.expression ?? '';
-            if (!expr)
-                continue;
-            // A same-line guard (`IsLocalUrl(next); Redirect(next)`) is not a
-            // partial wrap. Only an argument that itself contains the sanitizer
-            // call can leave a raw sibling operand.
-            const masked = maskSanitizerCalls(expr, refs);
-            if (masked === expr)
+            return { expr, masked: expr ? maskSanitizerCalls(expr, refs) : expr };
+        });
+        if (!masked.some(m => m.masked !== m.expr))
+            continue;
+        for (const m of masked) {
+            if (!m.masked)
                 continue;
-            if (re.test(blankStringLiterals(masked)))
+            // A sibling that passes only the value's length (`len(s)`,
+            // `s.length()`, `s.size()`) carries no attacker-controlled text.
+            const text = m.masked === m.expr ? maskLengthOf(m.masked) : m.masked;
+            if (re.test(blankStringLiterals(text)))
                 return true;
         }
     }
     return false;
 }
+/**
+ * True when `variable` appears in `text` once covering sanitizer calls are
+ * removed. Returns `null` when no covering sanitizer call is found in `text`
+ * (the caller cannot tell a wrapped operand from a raw one).
+ *
+ * #589: `mixed = escapeHtml(a) + b` keeps `b`; `both = escapeHtml(a) +
+ * escapeHtml(b)` keeps nothing.
+ */
+export function identifierOutsideSanitizerCallsInText(variable, text, sanitizers, sinkType) {
+    const refs = sanitizerCallRefs(sanitizers, sinkType);
+    if (refs.length === 0)
+        return null;
+    const masked = maskSanitizerCalls(text, refs);
+    if (masked === text)
+        return null;
+    if (!/^[A-Za-z_$][\w$]*$/.test(variable))
+        return true;
+    const re = new RegExp(`(?:^|[^A-Za-z0-9_$])${variable.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:[^A-Za-z0-9_$]|$)`);
+    return re.test(blankStringLiterals(masked));
+}
+/**
+ * True when every operand of `text` sits inside a covering sanitizer call:
+ * after those calls are removed and string literals blanked, no identifier is
+ * left. `shlex.quote(request.args.get("t"))` qualifies; `quote(a) + b` does
+ * not (#582).
+ */
+export function expressionFullyWrappedBySanitizer(text, sanitizers, sinkType) {
+    const refs = sanitizerCallRefs(sanitizers, sinkType);
+    if (refs.length === 0)
+        return false;
+    const masked = maskSanitizerCalls(text, refs);
+    if (masked === text)
+        return false;
+    // A qualified call (`os.path.basename(x)`) leaves its module prefix (`os. `) behind.
+    const rest = blankStringLiterals(masked).replace(/\b[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*\.(?=\s)/g, ' ');
+    return !/[A-Za-z_]/.test(rest);
+}
+/** Last segment of a sanitizer's method name, without the call parens (`ESAPI.encoder().encodeForHTML()` -> `encodeForHTML`). */
+function sanitizerMethodTail(san) {
+    const m = san.method ?? '';
+    return m.replace(/\(\)$/, '').split('.').pop() ?? '';
+}
+/** #589: a method-call sanitizer that is a context-specific HTML / markup encoder. */
+function isHtmlContextEncoder(san) {
+    if (san.type === 'derived_html_encoder')
+        return true; // same-file wrapper of an HTML encoder (#589)
+    return san.type === 'method_call' && HTML_CONTEXT_ENCODER_METHODS.has(sanitizerMethodTail(san));
+}
+function sanitizersAreHtmlContextEncoders(sans) {
+    return !!sans && sans.length > 0 && sans.every(isHtmlContextEncoder);
+}
 function checkSanitized(fromLine, toLine, sinkType, sanitizersByLine, ctx) {
     const isKnownSinkType = KNOWN_SINK_TYPES.has(sinkType);
     // Per-line fast path — preserves 3.154.0 semantics for site #1 (propagation
@@ -490,6 +836,9 @@ function checkSanitized(fromLine, toLine, sinkType, sanitizersByLine, ctx) {
     const sanitizersAtTarget = sanitizersByLine.get(toLine);
     if (sanitizersAtTarget && sanitizersAtTarget.length > 0) {
         for (const san of sanitizersAtTarget) {
+            // #589: an HTML-context encoder does not clean a `trust_boundary` sink.
+            if (HTML_CONTEXT_ENCODER_UNCOVERED_SINKS.has(sinkType) && isHtmlContextEncoder(san))
+                continue;
             if (isKnownSinkType) {
                 // H8 (#254 3.171.0): Set-backed lookup — O(1) after first call.
                 if (sanitizerCoversSink(san, sinkType)) {
@@ -526,6 +875,8 @@ function checkSanitized(fromLine, toLine, sinkType, sanitizersByLine, ctx) {
             if (!sansAtLine || sansAtLine.length === 0)
                 continue;
             for (const san of sansAtLine) {
+                if (HTML_CONTEXT_ENCODER_UNCOVERED_SINKS.has(sinkType) && isHtmlContextEncoder(san))
+                    continue;
                 if (isKnownSinkType) {
                     // H8 (#254 3.171.0): Set-backed lookup — O(1) after first call.
                     if (sanitizerCoversSink(san, sinkType)) {