@oddessentials/odd-ai-reviewers 1.7.4 → 1.9.0

package/dist/agents/control_flow/vulnerability-detector.js

@@ -8,6 +8,88 @@
  */
 import ts from 'typescript';
 import { getLogger } from './logger.js';
+import { detectSafeSources, filterSafeSources } from './safe-source-detector.js';
+import { ScopeStack, isScopeNode, nodeIdentityKey, registerNodeDeclarations, extractBindingsFromAssignmentTarget, extractBindingNames, } from './scope-stack.js';
+// =============================================================================
+// Assignment operator detection — includes compound assignments (+=, ??=, etc.)
+// that can propagate taint from the RHS to the LHS variable.
+// =============================================================================
+const ASSIGNMENT_OPERATORS = new Set([
+    ts.SyntaxKind.EqualsToken, // =
+    ts.SyntaxKind.PlusEqualsToken, // +=
+    ts.SyntaxKind.BarBarEqualsToken, // ||=
+    ts.SyntaxKind.QuestionQuestionEqualsToken, // ??=
+    ts.SyntaxKind.AmpersandAmpersandEqualsToken, // &&=
+]);
+function isAssignmentOperator(kind) {
+    return ASSIGNMENT_OPERATORS.has(kind);
+}
+function getObjectLiteralPropertyKey(prop) {
+    if (ts.isPropertyAssignment(prop)) {
+        if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) {
+            return prop.name.text;
+        }
+    }
+    if (ts.isShorthandPropertyAssignment(prop)) {
+        return prop.name.text;
+    }
+    return undefined;
+}
+function getObjectLiteralPropertyValue(prop) {
+    if (ts.isPropertyAssignment(prop)) {
+        return prop.initializer;
+    }
+    if (ts.isShorthandPropertyAssignment(prop)) {
+        return prop.name;
+    }
+    return undefined;
+}
+function getObjectBindingElementLookupKey(element) {
+    if (element.propertyName) {
+        if (ts.isIdentifier(element.propertyName) || ts.isStringLiteral(element.propertyName)) {
+            return element.propertyName.text;
+        }
+        return undefined;
+    }
+    if (ts.isIdentifier(element.name)) {
+        return element.name.text;
+    }
+    // Defensive fallback: in valid TS, nested binding patterns always have propertyName
+    // (handled above), so this branch is unreachable. Kept for robustness.
+    const nestedBindings = extractBindingNames(element.name);
+    return nestedBindings[0]?.name;
+}
+function getExcludedObjectRestKeys(elements, restIndex) {
+    const excludedKeys = new Set();
+    for (let i = 0; i < restIndex; i++) {
+        const el = elements[i];
+        if (!el)
+            continue;
+        const key = getObjectBindingElementLookupKey(el);
+        if (key)
+            excludedKeys.add(key);
+    }
+    return excludedKeys;
+}
+/**
+ * Collect property keys that are explicitly destructured before the rest element
+ * in a destructuring assignment target (Expression-based LHS).
+ *
+ * This is the assignment-path counterpart to `getExcludedObjectRestKeys` which
+ * operates on `BindingElement[]` from declaration patterns.
+ */
+function getExcludedAssignmentRestKeys(bindings, restIndex) {
+    const excludedKeys = new Set();
+    for (let i = 0; i < restIndex; i++) {
+        const binding = bindings[i];
+        if (!binding || binding.isRest)
+            continue;
+        const key = binding.propertyKey ?? binding.name;
+        if (key)
+            excludedKeys.add(key);
+    }
+    return excludedKeys;
+}
 /**
  * Built-in sink patterns for common vulnerability types.
  */
@@ -136,9 +218,19 @@ export class VulnerabilityDetector {
         this.findSinks(sourceFile, filePath, detectedSinks);
         // Step 2: Find all sources (user input)
         this.findSources(sourceFile, filePath, detectedSources);
-        // Step 3: Track taint propagation
-        this.trackTaint(sourceFile, filePath, detectedSources, taintedVariables);
-        // Step 4: Match sinks to tainted data
+        // Step 3: Detect safe sources and filter them out (prevents false positives)
+        const safeSources = detectSafeSources(sourceFile, filePath);
+        const filteredSources = filterSafeSources(detectedSources, safeSources);
+        for (const ss of safeSources) {
+            this.logger.log('debug', 'vulnerability', 'Safe source detected', {
+                patternId: ss.patternId,
+                variableName: ss.variableName,
+                file: filePath,
+            });
+        }
+        // Step 4: Track taint propagation
+        this.trackTaint(sourceFile, filePath, filteredSources, taintedVariables);
+        // Step 5: Match sinks to tainted data
         for (const sink of detectedSinks) {
             const affectedVariable = this.findAffectedVariable(sink, taintedVariables, sourceFile);
             if (affectedVariable) {
@@ -150,6 +242,7 @@ export class VulnerabilityDetector {
             file: filePath,
             sinksFound: detectedSinks.length,
             sourcesFound: detectedSources.length,
+            safeSourcesDetected: safeSources.length,
             taintedVars: taintedVariables.length,
             vulnerabilities: vulnerabilities.length,
         });
@@ -268,23 +361,30 @@ export class VulnerabilityDetector {
      * Find user input sources in the source file.
      */
     findSources(sourceFile, filePath, sources) {
+        const scope = new ScopeStack();
         const visit = (node) => {
+            const isScope = isScopeNode(node);
+            if (isScope)
+                scope.enterScope(node);
+            registerNodeDeclarations(node, scope);
             // Check property access for source patterns
             if (ts.isPropertyAccessExpression(node)) {
-                this.checkPropertyAccessForSource(node, sourceFile, filePath, sources);
+                this.checkPropertyAccessForSource(node, sourceFile, filePath, sources, scope);
             }
             // Check element access (e.g., req['body'])
             if (ts.isElementAccessExpression(node)) {
-                this.checkElementAccessForSource(node, sourceFile, filePath, sources);
+                this.checkElementAccessForSource(node, sourceFile, filePath, sources, scope);
             }
             ts.forEachChild(node, visit);
+            if (isScope)
+                scope.leaveScope();
         };
         visit(sourceFile);
     }
     /**
      * Check if property access is a taint source.
      */
-    checkPropertyAccessForSource(node, sourceFile, filePath, sources) {
+    checkPropertyAccessForSource(node, sourceFile, filePath, sources, scope) {
         const propName = node.name.text;
         let objectName = '';
         if (ts.isIdentifier(node.expression)) {
@@ -295,15 +395,12 @@ export class VulnerabilityDetector {
             const objectMatches = !pattern.objects ||
                 pattern.objects.some((obj) => objectName.toLowerCase() === obj.toLowerCase());
             if (nameMatches && objectMatches) {
-                const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                const binding = this.findAssignedBinding(node, sourceFile, filePath, scope);
                 sources.push({
-                    location: {
-                        file: filePath,
-                        line: line + 1,
-                        column: character,
-                    },
+                    location: binding?.location ?? this.nodeLocation(node, sourceFile, filePath),
                     expression: node.getText(sourceFile),
-                    variableName: this.findAssignedVariable(node, sourceFile) || propName,
+                    variableName: binding?.variableName ?? (this.findAssignedVariable(node, sourceFile) || propName),
+                    declarationKey: binding?.declarationKey ?? null,
                 });
                 break;
             }
@@ -312,7 +409,7 @@ export class VulnerabilityDetector {
     /**
      * Check element access for source patterns (e.g., req['body']).
      */
-    checkElementAccessForSource(node, sourceFile, filePath, sources) {
+    checkElementAccessForSource(node, sourceFile, filePath, sources, scope) {
         if (!ts.isStringLiteral(node.argumentExpression))
             return;
         const propName = node.argumentExpression.text;
@@ -325,15 +422,12 @@ export class VulnerabilityDetector {
             const objectMatches = !pattern.objects ||
                 pattern.objects.some((obj) => objectName.toLowerCase() === obj.toLowerCase());
             if (nameMatches && objectMatches) {
-                const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                const binding = this.findAssignedBinding(node, sourceFile, filePath, scope);
                 sources.push({
-                    location: {
-                        file: filePath,
-                        line: line + 1,
-                        column: character,
-                    },
+                    location: binding?.location ?? this.nodeLocation(node, sourceFile, filePath),
                     expression: node.getText(sourceFile),
-                    variableName: this.findAssignedVariable(node, sourceFile) || propName,
+                    variableName: binding?.variableName ?? (this.findAssignedVariable(node, sourceFile) || propName),
+                    declarationKey: binding?.declarationKey ?? null,
                 });
                 break;
             }
@@ -357,84 +451,585 @@ export class VulnerabilityDetector {
         }
         return null;
     }
+    findAssignedBinding(node, sourceFile, filePath, scope) {
+        let current = node.parent;
+        while (current) {
+            if (ts.isVariableDeclaration(current) && ts.isIdentifier(current.name)) {
+                return {
+                    variableName: current.name.text,
+                    declarationKey: nodeIdentityKey(current, sourceFile),
+                    location: this.nodeLocation(current, sourceFile, filePath),
+                };
+            }
+            if (ts.isBinaryExpression(current) &&
+                isAssignmentOperator(current.operatorToken.kind) &&
+                ts.isIdentifier(current.left)) {
+                const decl = scope.resolveDeclaration(current.left.text);
+                return {
+                    variableName: current.left.text,
+                    declarationKey: decl ? nodeIdentityKey(decl, sourceFile) : null,
+                    location: decl
+                        ? this.nodeLocation(decl, sourceFile, filePath)
+                        : this.nodeLocation(current.left, sourceFile, filePath),
+                };
+            }
+            current = current.parent;
+        }
+        return null;
+    }
+    nodeLocation(node, sourceFile, filePath) {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+        return {
+            file: filePath,
+            line: line + 1,
+            column: character,
+        };
+    }
     /**
      * Track taint propagation through variable assignments.
+     * Uses a scope stack to resolve identifiers to their declaring nodes,
+     * keying taint entries by declaration identity instead of raw name.
      */
     trackTaint(sourceFile, filePath, sources, tainted) {
         // Initialize tainted variables from sources
+        // Sources don't have declaration keys yet — they'll be resolved during the walk
         for (const source of sources) {
             tainted.push({
                 name: source.variableName,
+                declarationKey: source.declarationKey,
                 sourceLocation: source.location,
                 taintedAt: source.location,
             });
         }
+        const scope = new ScopeStack();
         // Track taint through assignments
         const visit = (node) => {
+            const isScope = isScopeNode(node);
+            if (isScope)
+                scope.enterScope(node);
+            // Register all declaration types (var/let/const, destructuring, params, catch)
+            registerNodeDeclarations(node, scope);
+            // Resolve declaration keys for initial source entries when we encounter
+            // their declaring variable. This ensures taint entries for `const userInput = req.body.data`
+            // get a proper declarationKey so scope-based matching works in findTaintInExpression.
+            // Match by BOTH name AND source location to avoid assigning the wrong key when
+            // the same variable name is declared in multiple scopes (e.g., two handlers each
+            // doing `const data = req.body.data`).
+            if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+                const varName = node.name.text;
+                const declKey = nodeIdentityKey(node, sourceFile);
+                const declStart = node.getStart();
+                const declEnd = node.getEnd();
+                const { line: declStartLine } = sourceFile.getLineAndCharacterOfPosition(declStart);
+                const { line: declEndLine } = sourceFile.getLineAndCharacterOfPosition(declEnd);
+                for (const entry of tainted) {
+                    if (entry.name === varName &&
+                        entry.declarationKey === null &&
+                        entry.taintedAt.file === filePath) {
+                        // Check the source falls within the declaration's line range
+                        // (handles multi-line initializers like `const x =\n  req.body.y`)
+                        const srcLine = entry.taintedAt.line - 1; // zero-based
+                        if (srcLine < declStartLine || srcLine > declEndLine) {
+                            continue;
+                        }
+                        // When column data is available, verify via absolute position
+                        // to prevent mismatches when two same-named variables share a line
+                        if (entry.taintedAt.column !== undefined) {
+                            const sourceAbsPos = ts.getPositionOfLineAndCharacter(sourceFile, srcLine, entry.taintedAt.column);
+                            if (sourceAbsPos < declStart || sourceAbsPos >= declEnd) {
+                                continue;
+                            }
+                        }
+                        entry.declarationKey = declKey;
+                    }
+                }
+            }
+            // Resolve declaration keys for taint entries created by assignment expressions
+            // (e.g., `let q; q = req.body.query;` or `q += req.body.query;`).
+            // The taint source line falls within the BinaryExpression span, not within
+            // a VariableDeclaration, so the block above won't match.
+            // We resolve the LHS identifier via the scope stack.
+            if (ts.isBinaryExpression(node) &&
+                isAssignmentOperator(node.operatorToken.kind) &&
+                ts.isIdentifier(node.left)) {
+                const varName = node.left.text;
+                const assignStart = node.getStart();
+                const assignEnd = node.getEnd();
+                const { line: assignStartLine } = sourceFile.getLineAndCharacterOfPosition(assignStart);
+                const { line: assignEndLine } = sourceFile.getLineAndCharacterOfPosition(assignEnd);
+                for (const entry of tainted) {
+                    if (entry.name === varName &&
+                        entry.declarationKey === null &&
+                        entry.taintedAt.file === filePath) {
+                        const srcLine = entry.taintedAt.line - 1; // zero-based
+                        if (srcLine < assignStartLine || srcLine > assignEndLine)
+                            continue;
+                        const decl = scope.resolveDeclaration(varName);
+                        if (decl) {
+                            entry.declarationKey = nodeIdentityKey(decl, sourceFile);
+                        }
+                    }
+                }
+            }
             if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
                 const varName = node.name.text;
-                const taintSource = this.findTaintInExpression(node.initializer, tainted, sourceFile);
+                const taintSource = this.findTaintInExpression(node.initializer, tainted, sourceFile, scope);
                 if (taintSource) {
                     const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                    const declKey = nodeIdentityKey(node, sourceFile);
                     tainted.push({
                         name: varName,
+                        declarationKey: declKey,
                         sourceLocation: taintSource.sourceLocation,
                         taintedAt: { file: filePath, line: line + 1, column: character },
                     });
                 }
             }
+            // Destructuring variable declarations: const { a, b } = expr  or  const [a, b] = expr
+            if (ts.isVariableDeclaration(node) &&
+                !ts.isIdentifier(node.name) &&
+                node.initializer &&
+                (ts.isObjectBindingPattern(node.name) || ts.isArrayBindingPattern(node.name))) {
+                const bindings = extractBindingNames(node.name);
+                const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                const taintedAt = { file: filePath, line: line + 1, column: character };
+                const declKey = nodeIdentityKey(node, sourceFile);
+                if (ts.isArrayLiteralExpression(node.initializer) && ts.isArrayBindingPattern(node.name)) {
+                    // Per-element taint for array patterns with array literal initializers
+                    let idx = 0;
+                    for (const element of node.name.elements) {
+                        if (ts.isOmittedExpression(element)) {
+                            idx++;
+                            continue;
+                        }
+                        const isRest = element.dotDotDotToken !== undefined;
+                        const elementBindings = extractBindingNames(element.name);
+                        if (isRest) {
+                            // Rest captures remaining elements — taint if any remaining is tainted
+                            let restTainted = null;
+                            for (let ri = idx; ri < node.initializer.elements.length; ri++) {
+                                const rhsElem = node.initializer.elements[ri];
+                                if (rhsElem) {
+                                    restTainted = this.findTaintInExpression(rhsElem, tainted, sourceFile, scope);
+                                    if (restTainted)
+                                        break;
+                                }
+                            }
+                            if (restTainted) {
+                                for (const b of elementBindings) {
+                                    tainted.push({
+                                        name: b.name,
+                                        declarationKey: declKey,
+                                        sourceLocation: restTainted.sourceLocation,
+                                        taintedAt,
+                                    });
+                                }
+                            }
+                        }
+                        else {
+                            const rhsElem = node.initializer.elements[idx];
+                            if (rhsElem) {
+                                const elemTaint = this.findTaintInExpression(rhsElem, tainted, sourceFile, scope);
+                                if (elemTaint) {
+                                    for (const b of elementBindings) {
+                                        tainted.push({
+                                            name: b.name,
+                                            declarationKey: declKey,
+                                            sourceLocation: elemTaint.sourceLocation,
+                                            taintedAt,
+                                        });
+                                    }
+                                }
+                            }
+                        }
+                        idx++;
+                    }
+                }
+                else if (ts.isObjectLiteralExpression(node.initializer) &&
+                    ts.isObjectBindingPattern(node.name)) {
+                    // Per-element taint for object patterns with object literal initializers
+                    // Match each binding element to its corresponding RHS property by key
+                    for (const [elementIndex, element] of node.name.elements.entries()) {
+                        const localBindings = extractBindingNames(element.name);
+                        // Rest elements (...rest) capture all remaining properties.
+                        // Taint rest bindings only from properties that remain after earlier
+                        // named bindings are removed from the rest object.
+                        if (element.dotDotDotToken) {
+                            const excludedKeys = getExcludedObjectRestKeys(node.name.elements, elementIndex);
+                            for (const prop of node.initializer.properties) {
+                                if (ts.isSpreadAssignment(prop)) {
+                                    const spreadTaint = this.findTaintInExpression(prop.expression, tainted, sourceFile, scope);
+                                    if (spreadTaint) {
+                                        for (const b of localBindings) {
+                                            tainted.push({
+                                                name: b.name,
+                                                declarationKey: declKey,
+                                                sourceLocation: spreadTaint.sourceLocation,
+                                                taintedAt,
+                                            });
+                                        }
+                                        break;
+                                    }
+                                    continue;
+                                }
+                                const propKey = getObjectLiteralPropertyKey(prop);
+                                if (propKey && excludedKeys.has(propKey))
+                                    continue;
+                                const propValue = getObjectLiteralPropertyValue(prop);
+                                if (propValue) {
+                                    const elemTaint = this.findTaintInExpression(propValue, tainted, sourceFile, scope);
+                                    if (elemTaint) {
+                                        for (const b of localBindings) {
+                                            tainted.push({
+                                                name: b.name,
+                                                declarationKey: declKey,
+                                                sourceLocation: elemTaint.sourceLocation,
+                                                taintedAt,
+                                            });
+                                        }
+                                        break; // One tainted property is enough to taint rest
+                                    }
+                                }
+                            }
+                            continue;
+                        }
+                        // Determine the property key: explicit propertyName or implicit (same as local name)
+                        const lookupKey = getObjectBindingElementLookupKey(element);
+                        if (!lookupKey)
+                            continue;
+                        let rhsValue;
+                        for (const prop of node.initializer.properties) {
+                            if (getObjectLiteralPropertyKey(prop) === lookupKey) {
+                                rhsValue = getObjectLiteralPropertyValue(prop);
+                                break;
+                            }
+                        }
+                        if (rhsValue) {
+                            const elemTaint = this.findTaintInExpression(rhsValue, tainted, sourceFile, scope);
+                            if (elemTaint) {
+                                for (const b of localBindings) {
+                                    tainted.push({
+                                        name: b.name,
+                                        declarationKey: declKey,
+                                        sourceLocation: elemTaint.sourceLocation,
+                                        taintedAt,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                else {
+                    // Conservative: check entire initializer for taint, apply to all bindings
+                    const taintSource = this.findTaintInExpression(node.initializer, tainted, sourceFile, scope);
+                    if (taintSource) {
+                        for (const b of bindings) {
+                            tainted.push({
+                                name: b.name,
+                                declarationKey: declKey,
+                                sourceLocation: taintSource.sourceLocation,
+                                taintedAt,
+                            });
+                        }
+                    }
+                }
+            }
             if (ts.isBinaryExpression(node) &&
-                node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+                isAssignmentOperator(node.operatorToken.kind) &&
                 ts.isIdentifier(node.left)) {
                 const varName = node.left.text;
-                const taintSource = this.findTaintInExpression(node.right, tainted, sourceFile);
+                const taintSource = this.findTaintInExpression(node.right, tainted, sourceFile, scope);
                 if (taintSource) {
                     const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                    // Resolve the LHS to its declaration
+                    const decl = scope.resolveDeclaration(varName);
+                    const declKey = decl ? nodeIdentityKey(decl, sourceFile) : null;
                     tainted.push({
                         name: varName,
+                        declarationKey: declKey,
                         sourceLocation: taintSource.sourceLocation,
                         taintedAt: { file: filePath, line: line + 1, column: character },
                     });
                 }
             }
+            // Destructuring assignment taint propagation:
+            // [a, b] = expr  or  ({a, b} = expr)
+            if (ts.isBinaryExpression(node) &&
+                isAssignmentOperator(node.operatorToken.kind) &&
+                (ts.isArrayLiteralExpression(node.left) || ts.isObjectLiteralExpression(node.left))) {
+                const bindings = extractBindingsFromAssignmentTarget(node.left);
+                const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                const taintedAt = { file: filePath, line: line + 1, column: character };
+                if (ts.isArrayLiteralExpression(node.right) || ts.isObjectLiteralExpression(node.right)) {
+                    // Tier 1 — Per-element taint: evaluate each RHS element individually
+                    if (ts.isArrayLiteralExpression(node.right)) {
+                        for (const binding of bindings) {
+                            if (binding.isRest) {
+                                // Rest element captures remaining RHS elements — conservatively taint
+                                // if ANY remaining element is tainted
+                                const restStart = binding.index ?? 0;
+                                let restTainted = null;
+                                for (let ri = restStart; ri < node.right.elements.length; ri++) {
+                                    const rhsElem = node.right.elements[ri];
+                                    if (rhsElem) {
+                                        restTainted = this.findTaintInExpression(rhsElem, tainted, sourceFile, scope);
+                                        if (restTainted)
+                                            break;
+                                    }
+                                }
+                                if (restTainted) {
+                                    const decl = scope.resolveDeclaration(binding.name);
+                                    tainted.push({
+                                        name: binding.name,
+                                        declarationKey: decl ? nodeIdentityKey(decl, sourceFile) : null,
+                                        sourceLocation: restTainted.sourceLocation,
+                                        taintedAt,
+                                    });
+                                }
+                            }
+                            else if (binding.index !== undefined || binding.parentIndex !== undefined) {
+                                const lookupIndex = binding.index ?? binding.parentIndex;
+                                const rhsElem = lookupIndex !== undefined ? node.right.elements[lookupIndex] : undefined;
+                                if (rhsElem) {
+                                    const elemTaint = this.findTaintInExpression(rhsElem, tainted, sourceFile, scope);
+                                    if (elemTaint) {
+                                        const decl = scope.resolveDeclaration(binding.name);
+                                        tainted.push({
+                                            name: binding.name,
+                                            declarationKey: decl ? nodeIdentityKey(decl, sourceFile) : null,
+                                            sourceLocation: elemTaint.sourceLocation,
+                                            taintedAt,
+                                        });
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    else {
+                        // Object literal RHS: match by property key
+                        const rhsObj = node.right;
+                        for (const [bindingIndex, binding] of bindings.entries()) {
+                            const lookupKey = binding.propertyKey ?? binding.name;
+                            // For nested bindings with outerKeys (e.g. { a: { b } } = { a: { b: ... } }),
+                            // traverse into the RHS object following the outer key path first
+                            let targetObj = rhsObj;
+                            let traversalFailed = false;
+                            if (binding.outerKeys) {
+                                for (const outerKey of binding.outerKeys) {
+                                    let nestedValue;
+                                    for (const prop of targetObj.properties) {
+                                        if (getObjectLiteralPropertyKey(prop) === outerKey) {
+                                            nestedValue = getObjectLiteralPropertyValue(prop);
+                                            break;
+                                        }
+                                    }
+                                    if (nestedValue && ts.isObjectLiteralExpression(nestedValue)) {
+                                        targetObj = nestedValue;
+                                    }
+                                    else {
+                                        traversalFailed = true;
+                                        break;
+                                    }
+                                }
+                            }
+                            if (traversalFailed)
+                                continue;
+                            // Find matching RHS property in the (possibly nested) target object
+                            let rhsValue;
+                            for (const prop of targetObj.properties) {
+                                if (getObjectLiteralPropertyKey(prop) === lookupKey) {
+                                    rhsValue = getObjectLiteralPropertyValue(prop);
+                                    break;
+                                }
+                            }
+                            if (rhsValue) {
+                                const elemTaint = this.findTaintInExpression(rhsValue, tainted, sourceFile, scope);
+                                if (elemTaint) {
+                                    const decl = scope.resolveDeclaration(binding.name);
+                                    tainted.push({
+                                        name: binding.name,
+                                        declarationKey: decl ? nodeIdentityKey(decl, sourceFile) : null,
+                                        sourceLocation: elemTaint.sourceLocation,
+                                        taintedAt,
+                                    });
+                                }
+                            }
+                            else if (binding.isRest) {
+                                const excludedKeys = getExcludedAssignmentRestKeys(bindings, bindingIndex);
+                                let restTaint = null;
+                                for (const prop of targetObj.properties) {
+                                    if (ts.isSpreadAssignment(prop)) {
+                                        restTaint = this.findTaintInExpression(prop.expression, tainted, sourceFile, scope);
+                                        if (restTaint)
+                                            break;
+                                        continue;
+                                    }
+                                    const propKey = getObjectLiteralPropertyKey(prop);
+                                    if (propKey && excludedKeys.has(propKey))
+                                        continue;
+                                    const propValue = getObjectLiteralPropertyValue(prop);
+                                    if (!propValue)
+                                        continue;
+                                    restTaint = this.findTaintInExpression(propValue, tainted, sourceFile, scope);
+                                    if (restTaint)
+                                        break;
+                                }
+                                if (restTaint) {
+                                    const decl = scope.resolveDeclaration(binding.name);
+                                    tainted.push({
+                                        name: binding.name,
+                                        declarationKey: decl ? nodeIdentityKey(decl, sourceFile) : null,
+                                        sourceLocation: restTaint.sourceLocation,
+                                        taintedAt,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                else {
+                    // Tier 2 — Conservative-all: RHS is a non-literal expression,
+                    // mark ALL extracted bindings as tainted
+                    const taintSource = this.findTaintInExpression(node.right, tainted, sourceFile, scope);
+                    if (taintSource) {
+                        for (const binding of bindings) {
+                            const decl = scope.resolveDeclaration(binding.name);
+                            tainted.push({
+                                name: binding.name,
+                                declarationKey: decl ? nodeIdentityKey(decl, sourceFile) : null,
+                                sourceLocation: taintSource.sourceLocation,
+                                taintedAt,
+                            });
+                        }
+                    }
+                }
+            }
             ts.forEachChild(node, visit);
+            if (isScope)
+                scope.leaveScope();
         };
         visit(sourceFile);
     }
     /**
      * Find if an expression uses a tainted variable.
+     * Resolves identifiers to their declaring nodes via the scope stack,
+     * then matches by declaration identity key rather than raw name.
+     * Falls back to name-based matching for taint entries without a declaration key
+     * (e.g., initial source entries that weren't resolved during the walk).
      */
-    findTaintInExpression(node, tainted, _sourceFile) {
+    findTaintInExpression(node, tainted, sourceFile, scope) {
         if (ts.isIdentifier(node)) {
-            return tainted.find((t) => t.name === node.text) || null;
+            if (scope) {
+                const decl = scope.resolveDeclaration(node.text);
+                if (decl) {
+                    // Scope resolved the identifier to a specific declaration.
+                    // Only check taint entries that match this exact declaration.
+                    // Do NOT fall back to name-based matching — scope resolution is authoritative.
+                    const declKey = nodeIdentityKey(decl, sourceFile);
+                    return (tainted.find((t) => t.declarationKey === declKey && (!t.name || t.name === node.text)) || null);
+                }
+            }
+            // Fallback: name-based match ONLY when scope could not resolve the identifier
+            // (undeclared global, no scope stack available, or identifier not found in any scope)
+            return tainted.find((t) => t.declarationKey === null && t.name === node.text) || null;
+        }
+        // FR-016: Explicit template literal taint detection.
+        // If any interpolated expression in a template literal is tainted,
+        // the entire template expression is tainted.
+        if (ts.isTemplateExpression(node)) {
+            for (const span of node.templateSpans) {
+                const taintSource = this.findTaintInExpression(span.expression, tainted, sourceFile, scope);
+                if (taintSource)
+                    return taintSource;
+            }
+            return null;
         }
         let found = null;
         node.forEachChild((child) => {
             if (!found) {
-                found = this.findTaintInExpression(child, tainted, _sourceFile);
+                found = this.findTaintInExpression(child, tainted, sourceFile, scope);
             }
         });
         return found;
     }
     /**
      * Find the affected variable for a sink.
+     *
+     * Parses the sink's AST sub-tree to find identifiers, resolves each to its
+     * declaration via the scope stack, and matches against tainted entries by
+     * declaration identity key. Falls back to name-based matching for taint
+     * entries without a declaration key.
      */
     findAffectedVariable(sink, tainted, sourceFile) {
-        // Parse the sink expression to find referenced variables
+        // Build a scope stack to resolve identifiers in the sink
+        const scope = new ScopeStack();
+        const sinkLine = sink.location.line; // 1-based
+        // Collect all identifier names referenced in the sink expression text.
+        // We need to find the AST node for the sink and walk its identifiers.
+        let sinkNode = null;
+        const findSinkNode = (node) => {
+            const isScope = isScopeNode(node);
+            if (isScope)
+                scope.enterScope(node);
+            // Register all declaration types
+            registerNodeDeclarations(node, scope);
+            // Check if this node matches the sink location
+            const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+            if (line + 1 === sinkLine && node.getText(sourceFile) === sink.expression) {
+                sinkNode = node;
+            }
+            ts.forEachChild(node, findSinkNode);
+            if (isScope)
+                scope.leaveScope();
+        };
+        findSinkNode(sourceFile);
+        // Walk identifiers in the sink node and match against tainted declarations
+        if (sinkNode) {
+            // Re-walk up to and including the sink node to have scope in correct state
+            const scope2 = new ScopeStack();
+            let result = null;
+            const walkForMatch = (node) => {
+                const isScope = isScopeNode(node);
+                if (isScope)
+                    scope2.enterScope(node);
+                registerNodeDeclarations(node, scope2);
+                // If we found the sink node, search its identifiers
+                if (node === sinkNode) {
+                    const match = this.findTaintInExpression(node, tainted, sourceFile, scope2);
+                    if (match) {
+                        result = match;
+                        if (isScope)
+                            scope2.leaveScope();
+                        return true;
+                    }
+                }
+                let found = false;
+                node.forEachChild((child) => {
+                    if (!found) {
+                        found = walkForMatch(child);
+                    }
+                });
+                if (isScope)
+                    scope2.leaveScope();
+                return found;
+            };
+            walkForMatch(sourceFile);
+            // Scope-based resolution is authoritative when the sink node was found.
+            // Return the result (which may be null) without falling through to text-based matching.
+            return result;
+        }
+        // Fallback: text-based matching ONLY for cases where AST node wasn't found.
+        // Uses escaped name to prevent regex metacharacter injection.
         const sinkText = sink.expression;
         for (const taintedVar of tainted) {
-            // Check if the tainted variable is used in the sink
-            // Trust: ANALYZED_CODE - Variable name extracted from analyzed source, not user input
-            // Control: Word boundaries (\b) prevent pattern injection from identifier names
-            // See docs/security/regex-threat-model.md
-            // eslint-disable-next-line security/detect-non-literal-regexp -- Analyzed code identifier
-            const varPattern = new RegExp(`\\b${taintedVar.name}\\b`);
+            const escaped = taintedVar.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            // eslint-disable-next-line security/detect-non-literal-regexp -- Escaped analyzed code identifier
+            const varPattern = new RegExp(`\\b${escaped}\\b`);
             if (varPattern.test(sinkText)) {
                 return taintedVar;
             }
         }
         // Also check for common patterns where taint flows through function params
-        // This is a simplified check - full taint tracking would be more complex
         const functionParams = this.extractFunctionParams(sourceFile, sink.location.line);
         for (const param of functionParams) {
             const taintedParam = tainted.find((t) => t.name === param);