@oculum/scanner 1.0.0

package/src/layer3/anthropic.ts

@@ -0,0 +1,2030 @@
+/**
+ * Layer 3: AI Semantic Analysis
+ * Uses Claude to perform deep security analysis including:
+ * - Taint analysis (data flow from sources to sinks)
+ * - Business logic flaw detection
+ * - Missing authorization checks
+ * - Cryptography validation
+ * - Data exposure detection
+ * - Framework-specific deep analysis
+ */
+
+import Anthropic from '@anthropic-ai/sdk'
+import OpenAI from 'openai'
+import type { Vulnerability, VulnerabilitySeverity, VulnerabilityCategory, ScanFile, ValidationStatus } from '../types'
+import {
+  isTestOrMockFile,
+  isExampleFile,
+  isScannerOrFixtureFile,
+  isEnvVarReference,
+  isPublicEndpoint,
+  isComment,
+} from '../utils/context-helpers'
+import { buildProjectContext, getFileValidationContext, type ProjectContext } from '../utils/project-context-builder'
+// Import tier system for tier-aware auto-dismiss
+import { getTierForCategory, type DetectorTier } from '../tiers'
+
+// ============================================================================
+// Cost Monitoring Types
+// ============================================================================
+
+export interface ValidationStats {
+  /** Total findings processed (input) */
+  totalFindings: number
+  /** Findings that went through AI validation */
+  validatedFindings: number
+  /** Findings confirmed as true positives */
+  confirmedFindings: number
+  /** Findings dismissed as false positives */
+  dismissedFindings: number
+  /** Findings with severity adjusted down */
+  downgradedFindings: number
+  /** Findings auto-dismissed before AI (test files, etc.) */
+  autoDismissedFindings: number
+  /** Estimated input tokens used */
+  estimatedInputTokens: number
+  /** Estimated output tokens used */
+  estimatedOutputTokens: number
+  /** Estimated cost in USD (based on Haiku pricing) */
+  estimatedCost: number
+  /** Number of API calls made */
+  apiCalls: number
+  /** Cache creation tokens (first write to cache) */
+  cacheCreationTokens: number
+  /** Cache read tokens (subsequent reads from cache) */
+  cacheReadTokens: number
+  /** Cache hit rate (0-1) */
+  cacheHitRate: number
+}
+
+export interface AIValidationResult {
+  vulnerabilities: Vulnerability[]
+  stats: ValidationStats
+}
+
+// ============================================================================
+// Phase 2: Multi-File Batching Configuration
+// ============================================================================
+
+// Number of files to include in each API call (Phase 2 optimization)
+// Batching multiple files reduces API overhead and leverages prompt caching better
+const FILES_PER_API_BATCH = 5
+
+// Number of API batches to process in parallel (Phase 3 optimization)
+// Higher values = faster scans but more API load; OpenAI handles this well
+const PARALLEL_API_BATCHES = 4
+
+// Initialize Anthropic client
+function getAnthropicClient(): Anthropic {
+  const apiKey = process.env.ANTHROPIC_API_KEY
+  if (!apiKey) {
+    throw new Error('ANTHROPIC_API_KEY environment variable is not set')
+  }
+  return new Anthropic({ apiKey })
+}
+
+// Initialize OpenAI client
+let openaiClient: OpenAI | null = null
+function getOpenAIClient(): OpenAI {
+  if (!openaiClient) {
+    const apiKey = process.env.OPENAI_API_KEY
+    if (!apiKey) {
+      throw new Error('OPENAI_API_KEY environment variable is not set')
+    }
+    openaiClient = new OpenAI({ apiKey })
+  }
+  return openaiClient
+}
+
+// GPT-5-mini pricing constants (per 1M tokens)
+const GPT5_MINI_PRICING = {
+  input: 0.25,      // $0.25 per 1M tokens
+  cached: 0.025,    // $0.025 per 1M tokens (10% of input)
+  output: 2.00,     // $2.00 per 1M tokens
+}
+
+// ============================================================================
+// Smart Auto-Dismiss Rules (No AI needed - instant filtering)
+// ============================================================================
+
+interface AutoDismissRule {
+  name: string
+  check: (finding: Vulnerability, fileContent?: string) => boolean
+  reason: string
+}
+
+const AUTO_DISMISS_RULES: AutoDismissRule[] = [
+  // Test files - often contain intentional "vulnerable" patterns for testing
+  {
+    name: 'test_file',
+    check: (finding) => isTestOrMockFile(finding.filePath),
+    reason: 'Finding in test/mock file',
+  },
+
+  // Example/demo code - not production code
+  {
+    name: 'example_file',
+    check: (finding) => isExampleFile(finding.filePath),
+    reason: 'Finding in example/demo file',
+  },
+
+  // Documentation files
+  {
+    name: 'documentation_file',
+    check: (finding) => /\.(md|mdx|txt|rst)$/i.test(finding.filePath),
+    reason: 'Finding in documentation file',
+  },
+
+  // Scanner/security tool code itself
+  {
+    name: 'scanner_code',
+    check: (finding) => isScannerOrFixtureFile(finding.filePath),
+    reason: 'Finding in scanner/fixture code',
+  },
+
+  // Environment variable references (not hardcoded secrets)
+  {
+    name: 'env_var_reference',
+    check: (finding) => {
+      if (finding.category !== 'hardcoded_secret' && finding.category !== 'high_entropy_string') {
+        return false
+      }
+      return isEnvVarReference(finding.lineContent)
+    },
+    reason: 'Uses environment variable (not hardcoded)',
+  },
+
+  // Public health check endpoints don't need auth
+  {
+    name: 'health_check_endpoint',
+    check: (finding) => {
+      if (finding.category !== 'missing_auth') return false
+      return isPublicEndpoint(finding.lineContent, finding.filePath)
+    },
+    reason: 'Public health check endpoint (auth not required)',
+  },
+
+  // CSS/Tailwind classes flagged as high entropy
+  {
+    name: 'css_classes',
+    check: (finding) => {
+      if (finding.category !== 'high_entropy_string') return false
+      const cssIndicators = ['flex', 'grid', 'text-', 'bg-', 'px-', 'py-', 'rounded', 'shadow', 'hover:', 'dark:']
+      const lowerLine = finding.lineContent.toLowerCase()
+      const matchCount = cssIndicators.filter(ind => lowerLine.includes(ind)).length
+      return matchCount >= 2
+    },
+    reason: 'CSS/Tailwind classes (not a secret)',
+  },
+
+  // Comment lines shouldn't be flagged for most categories
+  {
+    name: 'comment_line',
+    check: (finding) => {
+      // Some categories are valid in comments (e.g., TODO security)
+      if (finding.category === 'ai_pattern') return false
+      return isComment(finding.lineContent)
+    },
+    reason: 'Code comment (not executable)',
+  },
+
+  // Info severity already - no need to validate
+  // BUT: Only auto-dismiss info-severity for Tier A (core) findings
+  // Tier B (ai_assisted) findings MUST go through AI validation even at info severity
+  // because detectors may have pre-downgraded them based on partial context
+  {
+    name: 'info_severity_core_only',
+    check: (finding) => {
+      if (finding.severity !== 'info') return false
+      // Only auto-dismiss info-severity for Tier A (core) findings
+      // Tier B should always go through AI for proper validation
+      const tier = getTierForCategory(finding.category, finding.layer)
+      return tier === 'core'
+    },
+    reason: 'Already info severity for core detector (low priority)',
+  },
+
+  // Generic success/error messages in ai_pattern
+  {
+    name: 'generic_message',
+    check: (finding) => {
+      if (finding.category !== 'ai_pattern') return false
+      const genericPatterns = [
+        /['"`](success|done|ok|completed|finished|saved|updated|deleted|created)['"`]/i,
+        /['"`]something went wrong['"`]/i,
+        /['"`]an error occurred['"`]/i,
+        /console\.(log|info|debug)\s*\(\s*['"`][^'"]+['"`]\s*\)/i,
+      ]
+      return genericPatterns.some(p => p.test(finding.lineContent))
+    },
+    reason: 'Generic UI message (not security-relevant)',
+  },
+
+  // Type definitions with 'any' - often necessary for third-party libs
+  {
+    name: 'type_definition_any',
+    check: (finding) => {
+      if (finding.category !== 'ai_pattern') return false
+      if (!finding.title.toLowerCase().includes('any')) return false
+      // Check if it's in a .d.ts file or type definition context
+      if (finding.filePath.includes('.d.ts')) return true
+      const typeDefPatterns = [/^type\s+\w+\s*=/, /^interface\s+\w+/, /declare\s+(const|let|var|function|class)/]
+      return typeDefPatterns.some(p => p.test(finding.lineContent.trim()))
+    },
+    reason: 'Type definition (not runtime code)',
+  },
+
+  // setTimeout/setInterval magic numbers - code style, not security
+  {
+    name: 'timeout_magic_number',
+    check: (finding) => {
+      if (finding.category !== 'ai_pattern') return false
+      return /set(Timeout|Interval)\s*\([^,]+,\s*\d+\s*\)/.test(finding.lineContent)
+    },
+    reason: 'Timeout value (code style, not security)',
+  },
+]
+
+/**
+ * Apply smart auto-dismiss rules to filter obvious false positives
+ * Returns findings that should be sent to AI validation
+ */
+export function applyAutoDismissRules(findings: Vulnerability[]): {
+  toValidate: Vulnerability[]
+  dismissed: Array<{ finding: Vulnerability; rule: string; reason: string }>
+} {
+  const toValidate: Vulnerability[] = []
+  const dismissed: Array<{ finding: Vulnerability; rule: string; reason: string }> = []
+
+  for (const finding of findings) {
+    let wasDismissed = false
+
+    for (const rule of AUTO_DISMISS_RULES) {
+      if (rule.check(finding)) {
+        dismissed.push({
+          finding,
+          rule: rule.name,
+          reason: rule.reason,
+        })
+        wasDismissed = true
+        break
+      }
+    }
+
+    if (!wasDismissed) {
+      toValidate.push(finding)
+    }
+  }
+
+  return { toValidate, dismissed }
+}
+
+// ============================================================================
+// Security Analysis Prompt (Layer 3)
+// ============================================================================
+
+// System prompt for security analysis
+const SECURITY_ANALYSIS_PROMPT = `You are an expert security code reviewer. Analyze the provided code for security vulnerabilities.
+
+Focus on these specific vulnerability types:
+
+1. **Taint Analysis (Data Flow)**
+   - Track user input from sources (req.query, req.params, req.body, searchParams, URL parameters)
+   - To dangerous sinks (eval, dangerouslySetInnerHTML, exec, SQL queries, file operations)
+   - Flag any path where untrusted data reaches a dangerous function without sanitization
+
+2. **SQL Injection**
+   - String concatenation in SQL queries
+   - Template literals with user input in queries
+   - Missing parameterized queries
+
+3. **XSS (Cross-Site Scripting)**
+   - User input rendered without escaping
+   - dangerouslySetInnerHTML with user data
+   - innerHTML assignments
+   - NOTE: React/Next.js JSX automatically escapes content, so {variable} in JSX is NOT XSS
+
+4. **Command Injection**
+   - exec, spawn, execSync with user input
+   - Shell command construction with variables
+
+5. **Missing Authorization**
+   - API routes that modify data without auth checks
+   - Database writes in GET handlers
+   - Missing permission checks before sensitive operations
+
+6. **Insecure Deserialization**
+   - JSON.parse on untrusted data without validation
+   - eval of serialized data
+
+7. **Cryptography Validation** 
+   - Weak algorithms: MD5 (for security), SHA1 (for security), DES, RC4
+   - Insecure random: Math.random() for tokens/keys/secrets
+   - Hardcoded encryption keys or IVs (not from env vars)
+   - ECB mode usage (patterns indicate cipher mode)
+   - Low iteration counts for PBKDF2 (< 10000)
+   - Short key lengths (< 256 bits for symmetric)
+   - Missing salt for password hashing
+   - createCipher() instead of createCipheriv()
+
+8. **Data Exposure Detection**
+   - Logging sensitive data: console.log with passwords, tokens, secrets, API keys
+   - Stack traces exposed to clients: err.stack in response
+   - Returning entire user objects (may include password hash)
+   - Debug endpoints left in code: /debug, /test, /_internal routes
+   - Verbose error messages exposing internal details
+   - Sensitive data in error responses
+
+9. **Framework-Specific Security**
+
+   **Next.js:**
+   - Server actions ('use server') without authentication
+   - Client components ('use client') accessing non-NEXT_PUBLIC_ env vars
+   - Middleware that returns NextResponse.next() without auth checks
+   - getServerSideProps without session validation
+   - Exposed API routes without rate limiting
+
+   **React:**
+   - Sensitive data stored in useState (visible in devtools)
+   - dangerouslySetInnerHTML with props/state
+   - useEffect making authenticated API calls without token validation
+
+   **Express:**
+   - Missing helmet() middleware for security headers
+   - CORS with origin: "*" in production
+   - Missing body-parser limits (DoS risk)
+   - Trust proxy without verification
+   - Error handlers exposing stack traces
+
+IMPORTANT - DO NOT FLAG THESE AS VULNERABILITIES (common false positives):
+
+**Framework Patterns (Safe by Design):**
+- Next.js middleware using request.url for redirects (standard pattern)
+- React/Next.js JSX rendering variables like {user.name} (auto-escaped by React)
+- Supabase/Firebase client creation with NEXT_PUBLIC_ environment variables
+- Using headers().get('host') in Next.js server actions
+
+**Data Handling (Low Risk):**
+- JSON.parse on data from YOUR OWN database (the app wrote it, it's trusted). Do NOT report this as a vulnerability. At most, you may mention an info-level robustness note if there is no error handling, but generally you should omit it.
+- JSON.parse on localStorage data (same-origin, XSS is a separate issue). This is also not a security vulnerability. At most, you may suggest an info-level robustness improvement, and usually it is not worth mentioning.
+- Passing user's own data to external APIs (user embedding their own content).
+- Error messages that use error.message in catch blocks or are returned to the client as a generic error string are standard error handling. Treat them as LOW/INFO hardening at most, and DO NOT mark them as medium/high unless the message clearly includes credentials, secrets, or full stack traces.
+- Generic configuration or feature messages like "OpenAI API key not configured" or "service disabled" are operational information, not security vulnerabilities. Treat them as info at most, or ignore them.
+
+**Authentication Patterns (Context Matters):**
+- Internal server-side functions only called from trusted code paths (OAuth callbacks, etc.)
+- Functions with userId parameters called with session.user.id from authenticated contexts
+- Service role keys used in server-side code with proper auth checks elsewhere
+- API routes that call getCurrentUserId() and use the result (the auth check IS the userId call)
+
+**BYOK (Bring Your Own Key) Patterns:**
+- User-provided API keys in BYOK mode are INTENTIONAL - the user wants to use their own key
+- This is a feature, not a vulnerability - don't flag it unless there's actual abuse potential
+- When a BYOK key is only used TRANSIENTLY in memory for a single provider call (and is never logged or stored), and the route is authenticated, do NOT report this as a medium/high vulnerability. At most, you may surface a low/info note reminding the developer not to log or persist keys.
+- Frontend components sending a BYOK key to an authenticated backend endpoint for one-shot use are expected behavior, not a vulnerability. Do NOT flag these as data_exposure or dangerous_function unless the key is logged, stored, or echoed back to the client.
+- Only raise medium/high BYOK findings when keys are clearly stored (e.g., written to a database or long-term logs), logged in plaintext, or accepted by unauthenticated endpoints that attackers could abuse at scale.
+
+**What TO Flag (Real Vulnerabilities):**
+- SQL string concatenation with user input
+- eval() or Function() with user-controlled strings
+- Missing auth checks where sensitive data could be accessed by wrong user
+- Actual hardcoded secrets (real API keys, not env var references)
+- Command injection (exec/spawn with user input)
+
+Respond ONLY with a JSON array of findings. Each finding must have:
+{
+  "lineNumber": <number>,
+  "severity": "critical" | "high" | "medium" | "low",
+  "category": "sql_injection" | "xss" | "command_injection" | "missing_auth" | "dangerous_function",
+  "title": "<short title>",
+  "description": "<detailed explanation of the vulnerability>",
+  "suggestedFix": "<how to fix it>"
+}
+
+If no vulnerabilities are found, return an empty array: []
+
+CRITICAL: Only report REAL vulnerabilities with HIGH confidence. Be conservative - it's better to miss a low-confidence issue than to report false positives. The code is likely using modern frameworks with built-in protections.`
+
+interface AIFinding {
+  lineNumber: number
+  severity: VulnerabilitySeverity
+  category: VulnerabilityCategory
+  title: string
+  description: string
+  suggestedFix: string
+}
+
+export interface Layer3Context {
+  /** Middleware configuration from project scan */
+  middlewareConfig?: {
+    hasAuthMiddleware: boolean
+    authType?: string
+    protectedPaths: string[]
+  }
+  /** Auth helper context */
+  authHelpers?: {
+    hasThrowingHelpers: boolean
+    summary: string
+  }
+  /** Additional context string */
+  additionalContext?: string
+}
+
+/**
+ * Build auth context string for AI prompt
+ */
+function buildAuthContextForPrompt(ctx?: Layer3Context): string {
+  if (!ctx) return ''
+  
+  const parts: string[] = []
+  
+  if (ctx.middlewareConfig?.hasAuthMiddleware) {
+    parts.push(`**IMPORTANT AUTH CONTEXT**: This project uses ${ctx.middlewareConfig.authType || 'auth'} middleware.`)
+    if (ctx.middlewareConfig.protectedPaths.length > 0) {
+      parts.push(`Protected paths: ${ctx.middlewareConfig.protectedPaths.join(', ')}`)
+    } else {
+      parts.push('All /api/** routes are protected by default.')
+    }
+    parts.push('Routes under these paths are ALREADY AUTHENTICATED - do NOT flag them as "missing auth".')
+    parts.push('Client components calling these protected API routes are also safe - the backend handles auth.')
+  }
+  
+  if (ctx.authHelpers?.hasThrowingHelpers) {
+    parts.push('')
+    parts.push('**AUTH HELPER FUNCTIONS**: This project uses throwing auth helpers that guarantee authenticated context:')
+    parts.push(ctx.authHelpers.summary)
+    parts.push('Code after these helper calls is GUARANTEED to be authenticated. Do NOT flag "missing auth" after these calls.')
+  }
+  
+  if (ctx.additionalContext) {
+    parts.push('')
+    parts.push(ctx.additionalContext)
+  }
+  
+  return parts.length > 0 ? '\n\n' + parts.join('\n') : ''
+}
+
+export async function analyzeWithAI(
+  file: ScanFile,
+  context?: Layer3Context
+): Promise<Vulnerability[]> {
+  const client = getAnthropicClient()
+
+  // Prepare the code with line numbers for reference
+  const numberedCode = file.content
+    .split('\n')
+    .map((line, i) => `${i + 1}: ${line}`)
+    .join('\n')
+
+  // Build auth context for the prompt
+  const authContext = buildAuthContextForPrompt(context)
+
+  const userMessage = `Analyze this ${file.language} file for security vulnerabilities:
+
+File: ${file.path}${authContext}
+
+\`\`\`${file.language}
+${numberedCode}
+\`\`\`
+
+Return ONLY a JSON array of findings.`
+
+  try {
+    const response = await client.messages.create({
+      model: 'claude-3-5-haiku-20241022',
+      max_tokens: 4096,
+      system: SECURITY_ANALYSIS_PROMPT,
+      messages: [
+        {
+          role: 'user',
+          content: userMessage,
+        },
+      ],
+    })
+
+    // Extract text content from response
+    const textContent = response.content.find((block: { type: string }) => block.type === 'text')
+    if (!textContent || textContent.type !== 'text') {
+      console.error('No text content in AI response')
+      return []
+    }
+
+    // Parse the JSON response
+    const findings = parseAIResponse(textContent.text)
+
+    // Convert to Vulnerability format
+    return findings.map((finding, index) => ({
+      id: `ai-${file.path}-${finding.lineNumber}-${index}`,
+      filePath: file.path,
+      lineNumber: finding.lineNumber,
+      lineContent: getLineContent(file.content, finding.lineNumber),
+      severity: finding.severity,
+      category: finding.category,
+      title: finding.title,
+      description: finding.description,
+      suggestedFix: finding.suggestedFix,
+      confidence: 'high' as const,
+      layer: 3 as const,
+    }))
+  } catch (error) {
+    console.error('AI analysis error:', error)
+    return []
+  }
+}
+
+// Parse the AI response JSON
+function parseAIResponse(response: string): AIFinding[] {
+  try {
+    // Try to extract JSON from the response
+    const jsonMatch = response.match(/\[[\s\S]*\]/)
+    if (!jsonMatch) {
+      return []
+    }
+
+    const parsed = JSON.parse(jsonMatch[0])
+    
+    // Validate the structure
+    if (!Array.isArray(parsed)) {
+      return []
+    }
+
+    return parsed.filter(item => 
+      typeof item.lineNumber === 'number' &&
+      typeof item.severity === 'string' &&
+      typeof item.category === 'string' &&
+      typeof item.title === 'string' &&
+      typeof item.description === 'string'
+    ).map(item => ({
+      lineNumber: item.lineNumber,
+      severity: validateSeverity(item.severity),
+      category: validateCategory(item.category),
+      title: item.title,
+      description: item.description,
+      suggestedFix: item.suggestedFix || 'Review and fix the security issue',
+    }))
+  } catch (error) {
+    console.error('Failed to parse AI response:', error)
+    return []
+  }
+}
+
+function validateSeverity(severity: string): VulnerabilitySeverity {
+  const valid: VulnerabilitySeverity[] = ['critical', 'high', 'medium', 'low']
+  return valid.includes(severity as VulnerabilitySeverity) 
+    ? severity as VulnerabilitySeverity 
+    : 'medium'
+}
+
+function validateCategory(category: string): VulnerabilityCategory {
+  const valid: VulnerabilityCategory[] = [
+    'sql_injection', 'xss', 'command_injection', 'missing_auth',
+    'dangerous_function', 'hardcoded_secret', 'high_entropy_string',
+    'sensitive_variable', 'security_bypass', 'insecure_config',
+    'suspicious_package', 'cors_misconfiguration', 'root_container',
+    'weak_crypto', 'sensitive_url', 'ai_pattern', 'dangerous_file',
+    'data_exposure',  // NEW: for logging/exposing sensitive data
+  ]
+  return valid.includes(category as VulnerabilityCategory)
+    ? category as VulnerabilityCategory
+    : 'dangerous_function'
+}
+
+function getLineContent(content: string, lineNumber: number): string {
+  const lines = content.split('\n')
+  return lines[lineNumber - 1]?.trim() || ''
+}
+
+// Batch analyze multiple files (with rate limiting)
+export async function batchAnalyzeWithAI(
+  files: ScanFile[],
+  context?: Layer3Context,
+  maxConcurrent: number = 3
+): Promise<Vulnerability[]> {
+  const vulnerabilities: Vulnerability[] = []
+  
+  // Process files in batches to avoid rate limits
+  for (let i = 0; i < files.length; i += maxConcurrent) {
+    const batch = files.slice(i, i + maxConcurrent)
+    const results = await Promise.all(
+      batch.map(file => analyzeWithAI(file, context).catch(err => {
+        console.error(`AI analysis failed for ${file.path}:`, err)
+        return []
+      }))
+    )
+    vulnerabilities.push(...results.flat())
+    
+    // Small delay between batches to avoid rate limits
+    if (i + maxConcurrent < files.length) {
+      await new Promise(resolve => setTimeout(resolve, 500))
+    }
+  }
+
+  return vulnerabilities
+}
+
+// ============================================================================
+// High-Context Validation Prompt (Section 3 Generalised Rules)
+// ============================================================================
+
+/**
+ * This prompt encodes the generalised security rules from CURRENTTASK.md Section 3.
+ * It is designed to work with full-file content and project context.
+ */
+const HIGH_CONTEXT_VALIDATION_PROMPT = `You are an expert security code reviewer acting as a "Second-opinion AI Reviewer" for vulnerability findings from an automated scanner.
+
+Your PRIMARY task: AGGRESSIVELY REJECT false positives and marginal findings. Only keep findings that are clearly exploitable or represent real security risk.
+
+**CORE PHILOSOPHY**: A professional scanner should surface very few, high-confidence findings. When in doubt, REJECT the finding or downgrade to info.
+
+## Input Format
+You will receive:
+1. **Project Context** - Architectural information about auth, data access, and secrets handling
+2. **Full File Content** - The entire file with line numbers
+3. **Candidate Findings** - List of potential vulnerabilities to validate
+
+## Core Validation Principles
+
+### 3.1 Authentication & Access Control
+Recognise these SAFE patterns (downgrade to info or REJECT entirely):
+- **Middleware-protected routes**: If project context shows auth middleware (Clerk, NextAuth, Auth0, custom), routes under protected paths are ALREADY GUARDED - do NOT flag as missing auth
+- **Auth helper functions that THROW**: Functions like getCurrentUserId(), getSession(), auth() that throw/abort on missing auth guarantee authenticated context. Code AFTER these calls is authenticated.
+  - Do NOT suggest "if (!userId)" checks after calling throwing helpers - the check is redundant
+  - If helper throws, it returns Promise<string> not Promise<string|null> - userId is guaranteed non-null
+  - Common throwing helpers: getCurrentUserId(), requireAuth(), getUser(), auth().protect(), getSession() with throw
+- **User-scoped queries**: Database queries filtered by user_id/tenant_id from authenticated session
+- **Guard patterns**: Early returns or throws when auth fails (if (!user) return/throw)
+
+Flag as REAL vulnerability (keep high severity) ONLY when:
+- Route has no visible auth check AND is NOT covered by middleware AND has no throwing auth helper
+- Sensitive operations without user scoping (cross-tenant access possible)
+- Auth checks that can be bypassed (e.g., checking wrong variable)
+
+**CRITICAL CONTRADICTION HANDLING**:
+- If we detect both "protected by middleware" and "missing auth" on the same route - REJECT the "missing auth" finding
+- If we detect both "uses throwing auth helper" and "missing auth" - REJECT the "missing auth" finding
+- Client components calling these protected API routes should NOT be flagged for "missing auth"
+- Adding "if (!userId)" after a throwing helper is a FALSE POSITIVE - reject it
+
+### 3.2 Deserialization & Unsafe Parsing
+Distinguish by INPUT ORIGIN and error handling:
+- **Application-controlled data** (database, config, localStorage): Low risk - downgrade to info
+  - JSON.parse on data YOUR app wrote is trusted
+  - Failures affect robustness, not security
+  - If ALSO wrapped in try-catch: REJECT the finding entirely
+- **External/untrusted data** (HTTP request body, URL params): Higher risk
+  - With try-catch: downgrade to low, suggest SCHEMA VALIDATION (zod/joi/yup) not more try-catch
+  - Without try-catch: keep as medium, suggest both try-catch AND schema validation
+- **request.json() / req.json()**: NOT a dangerous function
+  - This is the standard way to parse request bodies in modern frameworks
+  - Only suggest schema validation if none is visible nearby
+  - Severity: info at most
+
+**CRITICAL JSON.parse RULES**:
+- Do NOT suggest "add try/catch" when JSON.parse is ALREADY inside a try-catch block - this creates contradictory advice
+- If JSON.parse is in try-catch with app-controlled data: REJECT the finding
+- Prefer suggesting schema validation over generic try-catch for user input
+- For sensitive sinks (DB writes, code execution): medium severity
+- For display-only uses: low/info severity
+
+### 3.3 Logging & Error Handling
+Distinguish LOGS vs RESPONSES with this severity ladder:
+
+**Response Sinks (res.json, NextResponse.json, return) - Higher Risk:**
+- Full error object or stack trace in response → **HIGH severity**
+- Detailed internal fields (debug, trace, internal) → **MEDIUM severity**  
+- error.message only or static error strings → **LOW/INFO severity** (this is the RECOMMENDED pattern)
+
+**Log Sinks (console.log, logger.info) - Lower Risk:**
+- Logging error objects for debugging → **INFO severity** (hygiene, not security)
+- Logging userId, query strings → **INFO severity** (privacy note)
+- Logging passwords/secrets → **MEDIUM+ severity**
+- JSON.stringify(error) in logs → **INFO severity**
+
+**CRITICAL ERROR HANDLING RULES**:
+- "error.message" in responses is usually SAFE and should NOT be HIGH severity
+- HIGH severity is ONLY for responses that expose stacks, internal fields, or raw error objects
+- Logging errors is STANDARD PRACTICE - don't flag it as a security issue unless it logs secrets
+
+### 3.4 XSS vs Prompt Injection
+Keep these SEPARATE:
+- **XSS**: Writing untrusted data into DOM/HTML sinks without escaping
+  - innerHTML with dynamic user data: flag as XSS
+  - React JSX {variable}: NOT XSS (auto-escaped)
+  - dangerouslySetInnerHTML with static content: info severity
+- **Prompt Injection**: User content in LLM prompts
+  - NOT XSS - different threat model
+  - Downgrade to low/info unless clear path to high-impact actions
+  - Never label prompt issues as XSS
+
+### 3.5 Secrets, BYOK, and External Services
+Distinguish these patterns:
+- **Hardcoded secrets**: Real API keys in code = critical/high
+- **Environment variables**: process.env.SECRET = safe (REJECT finding)
+- **BYOK (Bring Your Own Key)**: User provides their own key for AI services
+  - This is a FEATURE, not a vulnerability
+  - Distinguish TRANSIENT USE vs STORAGE:
+    - Transient use (key in request body → API call → discarded): info severity, this is the IDEAL pattern
+    - Storage (key saved to database): check for user-scoping and encryption
+  - Severity ladder:
+    - Authenticated + transient use: info (feature, not vuln)
+    - Authenticated + user-scoped storage: low (suggest encryption at rest)
+    - Unauthenticated: medium (cost/abuse risk)
+    - Cross-tenant storage: medium (data isolation risk)
+  - Do NOT describe transient BYOK keys as "stored without encryption" - they are NOT stored
+
+### 3.6 DOM Sinks and Bootstrap Scripts
+Recognise LOW-RISK patterns:
+- Static scripts reading localStorage for theme/preferences
+- Setting attributes from config without user input
+- innerHTML with string literals only (no interpolation)
+
+Flag as REAL when:
+- User input flows to innerHTML/eval without sanitization
+- Template literals with \${userInput} in DOM sinks
+
+### 3.7 AI/LLM-Specific Patterns
+
+**Prompt Injection (ai_prompt_injection):**
+- User input in system prompt WITHOUT delimiters (code fences, XML tags, separators) -> **HIGH** (real risk)
+- User input in system prompt WITH clear delimiters -> **INFO** (properly fenced)
+- Static prompts with no user interpolation -> **REJECT** (false positive)
+- Prompt templates using proper parameterization/placeholders -> **REJECT**
+
+**LLM Output Execution (ai_unsafe_execution):**
+- LLM output fed to eval()/Function()/exec() WITHOUT sandbox -> **CRITICAL** (arbitrary code execution)
+- LLM output to execution WITH sandbox (vm2, isolated-vm) -> **MEDIUM** (risk mitigated)
+- LLM output to execution WITH validation AND sandbox -> **LOW** (well-protected)
+- LLM output used for display only (console.log, UI) -> **REJECT** (not execution)
+- Generated SQL from LLM without parameterization -> **CRITICAL** (SQL injection)
+- Generated SQL with parameterized queries -> **MEDIUM** (logic may still be wrong)
+
+**Agent Tool Permissions (ai_overpermissive_tool):**
+- Tool with unrestricted file/network/exec access -> **HIGH** (overpermissive)
+- Tool without user context verification -> **MEDIUM** (missing authorization)
+- Tool with proper scoping, allowlists, and user verification -> **LOW** or **REJECT**
+- Test files with tool definitions -> **INFO** or **REJECT**
+
+**Hallucinated Dependencies (suspicious_package):**
+- Package not found in registry -> **CRITICAL** (likely AI-hallucinated name)
+- Very new package (less than 7 days old) with low downloads and typosquat pattern -> **HIGH**
+- Legitimate looking package with source/repo but low popularity -> **MEDIUM** (needs review)
+- Known legitimate package with unusual name (in allowlist) -> **REJECT**
+
+**CRITICAL AI PATTERN RULES**:
+- AI code generation often produces non-existent package names - flag these prominently
+- Prompt injection is NOT the same as XSS - different threat model and severity
+- Sandboxed code execution (vm2, isolated-vm) significantly reduces risk
+- Agent tools need both access restrictions AND user context verification
+
+### 3.8 RAG Data Exfiltration (ai_rag_exfiltration)
+Retrieval Augmented Generation systems can leak sensitive data across tenant boundaries.
+
+**Unscoped Retrieval Queries:**
+- Vector store query WITHOUT user/tenant filter -> **HIGH** (cross-tenant data access)
+  - .query(), .search(), .similaritySearch() without filter/where/userId/tenantId parameter
+  - LangChain retriever.invoke() without metadata filter
+  - Pinecone/Chroma/Weaviate query without namespace or metadata filter
+- Query WITH proper scoping (filter by userId/tenantId) -> **REJECT** (properly scoped)
+- Query with RLS-enabled Supabase tables -> **LOW/INFO** (verify RLS policy)
+
+**Raw Context Exposure:**
+- Raw sourceDocuments/chunks returned in API response -> **MEDIUM** (data leak to client)
+- Raw context returned WITHOUT authentication -> **HIGH** (public data leak)
+- Filtered response (only IDs, titles, metadata) -> **REJECT** (properly filtered)
+- Response filtering visible nearby (.map, sanitize, redact) -> **INFO**
+
+**Context Logging:**
+- Logging retrieved documents (debug) -> **INFO** (hygiene, not direct risk)
+- Logging full prompts with context -> **LOW** (audit concern if logs are accessible)
+- Persisting prompts/context to database -> **MEDIUM** (sensitive data retention)
+
+**CRITICAL RAG RULES**:
+- Cross-tenant data access is the PRIMARY risk - always check for user/tenant scoping
+- Authenticated endpoints exposing context are MEDIUM; unauthenticated are HIGH
+- Debug logging is INFO severity - it's not a direct vulnerability
+- If RLS or middleware protection is visible, downgrade significantly
+
+### 3.9 AI Endpoint Protection (ai_endpoint_unprotected)
+AI/LLM API endpoints can incur significant costs and enable data exfiltration.
+
+**No Authentication + No Rate Limiting -> HIGH:**
+- Endpoint calls OpenAI/Anthropic/etc. without any auth check or rate limit
+- Anyone on the internet can abuse the endpoint and run up API costs
+- Potential for prompt exfiltration or model abuse
+
+**Has Rate Limiting but No Authentication -> MEDIUM:**
+- Rate limit provides some protection against abuse
+- Still allows anonymous access to AI functionality
+- Suggest adding authentication
+
+**Has Authentication but No Rate Limiting -> LOW:**
+- Authenticated users could still abuse the endpoint
+- Suggest adding rate limiting for cost control
+- severity: low (suggest improvement)
+
+**Has Both Auth and Rate Limiting -> INFO/REJECT:**
+- Properly protected endpoint
+- REJECT if both are clearly present
+- INFO if you want to note the good pattern
+
+**BYOK (Bring Your Own Key) Endpoints:**
+- If user provides their own API key, risk is LOWER
+- User pays for their own usage - cost abuse is their problem
+- Downgrade severity by one level for BYOK patterns
+
+**Protected by Middleware:**
+- If project context shows auth middleware protecting the route, downgrade to INFO
+- Internal/admin routes should be INFO or REJECT
+
+**CRITICAL ENDPOINT RULES**:
+- Cost abuse is real - unprotected AI endpoints can bankrupt a startup
+- Rate limiting alone isn't enough - need auth to prevent anonymous abuse
+- BYOK endpoints have lower risk since user bears the cost
+- Check for middleware protection before flagging
+
+### 3.10 Schema/Tooling Mismatch (ai_schema_mismatch)
+AI-generated structured outputs need validation before use in security-sensitive contexts.
+
+**Unvalidated AI Output Parsing:**
+- JSON.parse(response.content) without schema validation -> **MEDIUM**
+  - AI may return malformed or unexpected structures
+  - Suggest zod/ajv/joi validation
+- AI output to EXECUTION SINK (eval, exec, query) without validation -> **HIGH**
+  - Direct path to code/SQL injection
+- AI output to DISPLAY only (console.log, UI render) -> **REJECT**
+  - Not a security issue for display purposes
+- OpenAI Structured Outputs (json_schema in request) -> **REJECT**
+  - API-level validation provides guarantees
+
+**Weak Schema Patterns:**
+- response: any at API boundary -> **MEDIUM** (no type safety)
+- z.any() or z.unknown() -> **LOW** (defeats purpose of validation)
+- z.passthrough() -> **INFO** (allows extra properties, minor concern)
+- Specific schema defined and used -> **REJECT** (properly validated)
+
+**Tool Parameter Validation:**
+- Tool parameter -> file path without validation -> **HIGH** (path traversal)
+- Tool parameter -> shell command without validation -> **CRITICAL** (command injection)
+- Tool parameter -> URL without validation -> **HIGH** (SSRF)
+- Tool parameter -> DB query without validation -> **HIGH** (SQL injection)
+- Tool parameter with allowlist check visible -> **LOW/REJECT** (mitigated)
+
+**CRITICAL SCHEMA RULES**:
+- The severity depends on WHERE the AI output is used, not just that it's parsed
+- Execution sinks (eval, exec, query, fs) need HIGH severity without validation
+- Display-only usage is NOT a security issue
+- Schema validation (zod, ajv, joi) significantly reduces risk
+- OpenAI Structured Outputs provide API-level guarantees
+
+## False Positive Patterns (ALWAYS REJECT - keep: false)
+
+1. **CSS/Styling flagged as secrets**:
+   - Tailwind classes, gradients, hex colors, rgba/hsla
+   - style={{...}} objects, CSS-in-JS
+
+2. **Development URLs in dev contexts**:
+   - localhost in test/mock/example files
+   - URLs via environment variables
+
+3. **Test/Example/Scanner code**:
+   - Files with test, spec, mock, example, fixture in path
+   - Scanner's own rule definitions
+   - Documentation/README files
+
+4. **TypeScript 'any' in safe contexts**:
+   - Type definitions, .d.ts files
+   - Internal utilities (not API boundaries)
+
+5. **Public endpoints**:
+   - /health, /healthz, /ready, /ping, /status
+   - /webhook with signature verification nearby
+
+6. **Generic AI patterns that are NOT security issues**:
+   - console.log with non-sensitive data → REJECT
+   - TODO/FIXME reminders (not security-critical) → REJECT
+   - Magic number timeouts → REJECT
+   - Verbose/step-by-step comments → REJECT
+   - Generic error messages → REJECT or downgrade to info
+   - Basic validation patterns (if (!data) return) → REJECT
+
+7. **Style/Code quality issues (NOT security)**:
+   - Empty functions (unless auth-critical)
+   - Generic success messages
+   - Placeholder comments in non-security code
+
+## Response Format
+
+For each candidate finding, return:
+\`\`\`json
+{
+  "index": <number>,
+  "keep": true | false,
+  "reason": "<brief explanation referencing specific code/context>",
+  "adjustedSeverity": "critical" | "high" | "medium" | "low" | "info" | null,
+  "validationNotes": "<optional: additional context for the developer>"
+}
+\`\`\`
+
+## Severity Guidelines
+- **critical/high**: Realistically exploitable, should block deploys - ONLY for clear vulnerabilities
+- **medium/low**: Important but non-blocking, hardening opportunities - use sparingly
+- **info**: Robustness/hygiene tips, not direct security risks - use for marginal cases you want to keep
+
+## Decision Framework
+1. **Default to REJECTION** (keep: false) for:
+   - Style/code quality issues
+   - Marginal findings with unclear exploitation path
+   - Patterns that are standard practice (basic auth checks, error logging)
+   - Anything in test/example/documentation files
+
+2. **Downgrade to info** when:
+   - Finding has some merit but low practical risk
+   - Context shows mitigating factors
+   - Better as a "nice to know" than an action item
+
+3. **Keep with original/higher severity** ONLY when:
+   - Clear, exploitable vulnerability
+   - No visible mitigating factors in context
+   - Real-world attack scenario is plausible
+
+**REMEMBER**: You are the last line of defense against noise. A finding that reaches the user should be CLEARLY worth their time. When in doubt, REJECT.`
+
+interface ValidationResult {
+  index: number
+  keep: boolean
+  reason: string
+  adjustedSeverity?: VulnerabilitySeverity | null
+  validationNotes?: string
+}
+
+// Cache for project context (built once per scan)
+let cachedProjectContext: ProjectContext | null = null
+
+/**
+ * Helper function to make API calls with retry logic for rate limiting
+ * Implements exponential backoff for 429 (rate limit) errors
+ */
+async function makeAnthropicRequestWithRetry<T>(
+  requestFn: () => Promise<T>,
+  maxRetries: number = 3,
+  initialDelayMs: number = 1000
+): Promise<T> {
+  let lastError: Error | null = null
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await requestFn()
+    } catch (error: any) {
+      lastError = error
+
+      // Check if it's a rate limit error (429)
+      const isRateLimit = error?.status === 429 || error?.message?.includes('rate limit')
+
+      if (isRateLimit && attempt < maxRetries) {
+        // Exponential backoff: 1s, 2s, 4s
+        const delayMs = initialDelayMs * Math.pow(2, attempt)
+        console.log(`[AI Validation] Rate limit hit, retrying in ${delayMs}ms (attempt ${attempt + 1}/${maxRetries})`)
+        await new Promise(resolve => setTimeout(resolve, delayMs))
+        continue
+      }
+
+      // If not rate limit or max retries reached, throw
+      throw error
+    }
+  }
+
+  throw lastError || new Error('Max retries exceeded')
+}
+
+/**
+ * Helper to make OpenAI requests with retry logic for rate limits
+ */
+async function makeOpenAIRequestWithRetry<T>(
+  requestFn: () => Promise<T>,
+  maxRetries = 3,
+  initialDelayMs = 1000
+): Promise<T> {
+  let lastError: Error | null = null
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await requestFn()
+    } catch (error: any) {
+      lastError = error
+
+      // Check if it's a rate limit error (429) - but NOT insufficient_quota
+      const isRateLimit = error?.status === 429 && error?.code !== 'insufficient_quota'
+
+      if (isRateLimit && attempt < maxRetries) {
+        const delayMs = initialDelayMs * Math.pow(2, attempt)
+        console.log(`[OpenAI Validation] Rate limit hit, retrying in ${delayMs}ms (attempt ${attempt + 1}/${maxRetries})`)
+        await new Promise(resolve => setTimeout(resolve, delayMs))
+        continue
+      }
+
+      // If it's a quota error or max retries reached, throw
+      throw error
+    }
+  }
+
+  throw lastError || new Error('Max retries exceeded')
+}
+
+// ============================================================================
+// OpenAI Provider Implementation (GPT-5-mini)
+// ============================================================================
+
+/**
+ * Validate findings using OpenAI GPT-5-mini
+ * This mirrors the Anthropic validation flow but uses OpenAI's API
+ */
+async function validateWithOpenAI(
+  findings: Vulnerability[],
+  files: ScanFile[],
+  projectContext: ProjectContext | undefined,
+  stats: ValidationStats
+): Promise<AIValidationResult> {
+  const client = getOpenAIClient()
+
+  // Build or use cached project context
+  const context = projectContext || cachedProjectContext || buildProjectContext(files)
+  if (!projectContext && !cachedProjectContext) {
+    cachedProjectContext = context
+    console.log('[OpenAI Validation] Built project context:', {
+      hasAuthMiddleware: context.auth.hasGlobalMiddleware,
+      authProvider: context.auth.authProvider,
+      orm: context.dataAccess.orm,
+      framework: context.frameworks.primary,
+    })
+  }
+
+  // Group findings by file for efficient validation
+  const findingsByFile = new Map<string, Vulnerability[]>()
+  for (const finding of findings) {
+    const existing = findingsByFile.get(finding.filePath) || []
+    existing.push(finding)
+    findingsByFile.set(finding.filePath, existing)
+  }
+
+  const validatedFindings: Vulnerability[] = []
+  const fileEntries = Array.from(findingsByFile.entries())
+
+  // Track metrics (thread-safe accumulator)
+  let totalApiBatches = 0
+  const statsLock = {
+    apiCalls: 0,
+    estimatedInputTokens: 0,
+    estimatedOutputTokens: 0,
+    cacheReadTokens: 0,
+    estimatedCost: 0,
+    validatedFindings: 0,
+    confirmedFindings: 0,
+    dismissedFindings: 0,
+    downgradedFindings: 0,
+  }
+
+  const totalFileBatches = Math.ceil(fileEntries.length / FILES_PER_API_BATCH)
+  console.log(`[OpenAI Validation] Processing ${fileEntries.length} files in ${totalFileBatches} API batch(es) (${PARALLEL_API_BATCHES} parallel)`)
+
+  // Create all batch definitions
+  const allBatches: Array<{
+    batchNum: number
+    fileBatch: Array<[string, Vulnerability[]]>
+  }> = []
+
+  for (let batchStart = 0; batchStart < fileEntries.length; batchStart += FILES_PER_API_BATCH) {
+    const fileBatch = fileEntries.slice(batchStart, batchStart + FILES_PER_API_BATCH)
+    const batchNum = Math.floor(batchStart / FILES_PER_API_BATCH) + 1
+    allBatches.push({ batchNum, fileBatch })
+  }
+
+  // Process a single batch - returns validated findings for that batch
+  const processBatch = async (
+    batchDef: { batchNum: number; fileBatch: Array<[string, Vulnerability[]]> }
+  ): Promise<Vulnerability[]> => {
+    const { batchNum, fileBatch } = batchDef
+    const batchFindings: Vulnerability[] = []
+
+    // Prepare file data for batch request
+    const fileDataList: Array<{ file: ScanFile; findings: Vulnerability[]; filePath: string }> = []
+    const filesWithoutContent: Array<{ filePath: string; findings: Vulnerability[] }> = []
+
+    for (const [filePath, fileFindings] of fileBatch) {
+      const file = files.find(f => f.path === filePath)
+      if (!file) {
+        filesWithoutContent.push({ filePath, findings: fileFindings })
+      } else {
+        fileDataList.push({ file, findings: fileFindings, filePath })
+      }
+    }
+
+    // Handle files without content
+    for (const { findings: fileFindings } of filesWithoutContent) {
+      for (const f of fileFindings) {
+        batchFindings.push({
+          ...f,
+          validatedByAI: false,
+          validationStatus: 'not_validated' as ValidationStatus,
+          validationNotes: 'File content not available for validation',
+        })
+      }
+    }
+
+    if (fileDataList.length === 0) {
+      return batchFindings
+    }
+
+    try {
+      // Build multi-file validation request
+      const validationRequest = buildMultiFileValidationRequest(
+        fileDataList.map(({ file, findings: fileFindings }) => ({ file, findings: fileFindings })),
+        context
+      )
+
+      // Call OpenAI GPT-5-mini with retry logic
+      const response = await makeOpenAIRequestWithRetry(async () =>
+        client.chat.completions.create({
+          model: 'gpt-5-mini-2025-08-07',
+          messages: [
+            { role: 'system', content: HIGH_CONTEXT_VALIDATION_PROMPT },
+            { role: 'user', content: validationRequest },
+          ],
+          max_completion_tokens: 4096,
+        })
+      )
+
+      // Track API call stats (accumulate to shared stats)
+      statsLock.apiCalls++
+
+      // Extract token usage from OpenAI response
+      const usage = response.usage
+      if (usage) {
+        const promptTokens = usage.prompt_tokens || 0
+        const completionTokens = usage.completion_tokens || 0
+        const cachedTokens = (usage as any).prompt_tokens_details?.cached_tokens || 0
+        const freshInputTokens = promptTokens - cachedTokens
+
+        statsLock.estimatedInputTokens += freshInputTokens
+        statsLock.estimatedOutputTokens += completionTokens
+        statsLock.cacheReadTokens += cachedTokens
+
+        console.log(`[OpenAI] Batch ${batchNum} tokens: ${promptTokens} input (${cachedTokens} cached), ${completionTokens} output`)
+
+        const freshCost = (freshInputTokens * GPT5_MINI_PRICING.input) / 1_000_000
+        const cachedCost = (cachedTokens * GPT5_MINI_PRICING.cached) / 1_000_000
+        const outputCost = (completionTokens * GPT5_MINI_PRICING.output) / 1_000_000
+        statsLock.estimatedCost += freshCost + cachedCost + outputCost
+      }
+
+      // Parse response content
+      const content = response.choices[0]?.message?.content
+      if (!content) {
+        for (const { findings: fileFindings } of fileDataList) {
+          for (const f of fileFindings) {
+            batchFindings.push({
+              ...f,
+              validatedByAI: false,
+              validationStatus: 'not_validated' as ValidationStatus,
+              validationNotes: 'No valid response from OpenAI',
+            })
+          }
+        }
+        return batchFindings
+      }
+
+      // Parse multi-file response
+      const expectedFiles = fileDataList.map(({ filePath }) => filePath)
+      const validationResultsMap = parseMultiFileValidationResponse(content, expectedFiles)
+
+      // Apply results per file
+      for (const { filePath, findings: fileFindings } of fileDataList) {
+        const fileResults = validationResultsMap.get(filePath)
+
+        if (!fileResults || fileResults.length === 0) {
+          const singleFileResults = parseValidationResponse(content)
+          if (singleFileResults.length > 0 && fileDataList.length === 1) {
+            const processedFindings = applyValidationResults(fileFindings, singleFileResults)
+            for (const processed of processedFindings) {
+              statsLock.validatedFindings++
+              if (processed.validationStatus === 'confirmed') statsLock.confirmedFindings++
+              else if (processed.validationStatus === 'dismissed') statsLock.dismissedFindings++
+              else if (processed.validationStatus === 'downgraded') statsLock.downgradedFindings++
+              batchFindings.push(processed)
+            }
+          } else {
+            for (const f of fileFindings) {
+              statsLock.validatedFindings++
+              statsLock.confirmedFindings++
+              batchFindings.push({
+                ...f,
+                validatedByAI: true,
+                validationStatus: 'confirmed' as ValidationStatus,
+                validationNotes: 'Kept by default - no explicit validation result',
+              })
+            }
+          }
+        } else {
+          const processedFindings = applyValidationResults(fileFindings, fileResults)
+          for (const processed of processedFindings) {
+            statsLock.validatedFindings++
+            if (processed.validationStatus === 'confirmed') statsLock.confirmedFindings++
+            else if (processed.validationStatus === 'dismissed') statsLock.dismissedFindings++
+            else if (processed.validationStatus === 'downgraded') statsLock.downgradedFindings++
+            batchFindings.push(processed)
+          }
+        }
+      }
+
+    } catch (error) {
+      console.error(`[OpenAI Validation] Error in batch ${batchNum}:`, error)
+      for (const { findings: fileFindings } of fileDataList) {
+        for (const f of fileFindings) {
+          batchFindings.push({
+            ...f,
+            validatedByAI: false,
+            validationStatus: 'not_validated' as ValidationStatus,
+            validationNotes: 'Validation failed due to API error',
+          })
+        }
+      }
+    }
+
+    return batchFindings
+  }
+
+  // Process batches in parallel groups
+  const startTime = Date.now()
+  for (let i = 0; i < allBatches.length; i += PARALLEL_API_BATCHES) {
+    const parallelGroup = allBatches.slice(i, i + PARALLEL_API_BATCHES)
+    const batchNums = parallelGroup.map(b => b.batchNum).join(', ')
+    console.log(`[OpenAI Validation] Processing batches ${batchNums} in parallel`)
+
+    const results = await Promise.all(parallelGroup.map(processBatch))
+    for (const batchResults of results) {
+      validatedFindings.push(...batchResults)
+    }
+    totalApiBatches += parallelGroup.length
+  }
+  const totalDuration = Date.now() - startTime
+
+  // Copy accumulated stats back
+  stats.apiCalls = statsLock.apiCalls
+  stats.estimatedInputTokens = statsLock.estimatedInputTokens
+  stats.estimatedOutputTokens = statsLock.estimatedOutputTokens
+  stats.cacheReadTokens = statsLock.cacheReadTokens
+  stats.estimatedCost = statsLock.estimatedCost
+  stats.validatedFindings = statsLock.validatedFindings
+  stats.confirmedFindings = statsLock.confirmedFindings
+  stats.dismissedFindings = statsLock.dismissedFindings
+  stats.downgradedFindings = statsLock.downgradedFindings
+
+  // Calculate cache hit rate
+  const totalCacheableTokens = stats.cacheCreationTokens + stats.cacheReadTokens
+  stats.cacheHitRate = totalCacheableTokens > 0
+    ? stats.cacheReadTokens / totalCacheableTokens
+    : 0
+
+  // Log validation stats
+  const avgTimePerFile = fileEntries.length > 0
+    ? (totalDuration / fileEntries.length).toFixed(2)
+    : '0'
+
+  console.log(`[OpenAI Validation] Stats:`)
+  console.log(`  - Total findings: ${stats.totalFindings}`)
+  console.log(`  - AI validated: ${stats.validatedFindings}`)
+  console.log(`  - Confirmed: ${stats.confirmedFindings}`)
+  console.log(`  - Dismissed: ${stats.dismissedFindings}`)
+  console.log(`  - Downgraded: ${stats.downgradedFindings}`)
+  console.log(`  - API calls: ${stats.apiCalls}`)
+  console.log(`  - Performance:`)
+  console.log(`    - Total API batches: ${totalApiBatches}`)
+  console.log(`    - Avg time per file: ${avgTimePerFile}s`)
+  console.log(`  - Token usage:`)
+  console.log(`    - Input (fresh): ${stats.estimatedInputTokens} tokens`)
+  console.log(`    - Cached: ${stats.cacheReadTokens} tokens`)
+  console.log(`    - Output: ${stats.estimatedOutputTokens} tokens`)
+  console.log(`  - Estimated cost: $${stats.estimatedCost.toFixed(4)}`)
+
+  return { vulnerabilities: validatedFindings, stats }
+}
+
+/**
+ * Validate Layer 1/2 findings using AI with HIGH-CONTEXT validation
+ *
+ * Key improvements over previous version:
+ * 1. Sends FULL FILE CONTENT (not just snippets) for better context
+ * 2. Includes PROJECT CONTEXT (auth patterns, data access, etc.)
+ * 3. Uses generalised rules from Section 3 of the security model
+ */
+export async function validateFindingsWithAI(
+  findings: Vulnerability[],
+  files: ScanFile[],
+  projectContext?: ProjectContext
+): Promise<AIValidationResult> {
+  // Initialize stats tracking
+  const stats: ValidationStats = {
+    totalFindings: findings.length,
+    validatedFindings: 0,
+    confirmedFindings: 0,
+    dismissedFindings: 0,
+    downgradedFindings: 0,
+    autoDismissedFindings: 0,
+    estimatedInputTokens: 0,
+    estimatedOutputTokens: 0,
+    estimatedCost: 0,
+    apiCalls: 0,
+    cacheCreationTokens: 0,
+    cacheReadTokens: 0,
+    cacheHitRate: 0,
+  }
+
+  if (findings.length === 0) {
+    return { vulnerabilities: [], stats }
+  }
+
+  // Check for provider override (GPT-5-mini is default for 47% cost savings)
+  const aiProvider = process.env.AI_PROVIDER || 'openai'
+  if (aiProvider === 'anthropic') {
+    console.log('[AI Validation] Using Anthropic provider (Claude 3.5 Haiku)')
+    // Fall through to Anthropic implementation below
+  } else {
+    console.log('[AI Validation] Using OpenAI provider (GPT-5-mini)')
+    return validateWithOpenAI(findings, files, projectContext, stats)
+  }
+
+  // Anthropic implementation
+  console.log('[AI Validation] Initializing Anthropic client...')
+  const client = getAnthropicClient()
+
+  // Build or use cached project context
+  const context = projectContext || cachedProjectContext || buildProjectContext(files)
+  if (!projectContext && !cachedProjectContext) {
+    cachedProjectContext = context
+    console.log('[AI Validation] Built project context:', {
+      hasAuthMiddleware: context.auth.hasGlobalMiddleware,
+      authProvider: context.auth.authProvider,
+      orm: context.dataAccess.orm,
+      framework: context.frameworks.primary,
+    })
+  }
+
+  // Group findings by file for efficient validation
+  const findingsByFile = new Map<string, Vulnerability[]>()
+  for (const finding of findings) {
+    const existing = findingsByFile.get(finding.filePath) || []
+    existing.push(finding)
+    findingsByFile.set(finding.filePath, existing)
+  }
+
+  const validatedFindings: Vulnerability[] = []
+
+  // Phase 2: Multi-file batching
+  // Instead of one API call per file, batch multiple files into single requests
+  // This reduces API overhead and leverages prompt caching more effectively
+  const fileEntries = Array.from(findingsByFile.entries())
+
+  // Track metrics
+  let totalBatchWaitTime = 0
+  let totalApiBatches = 0
+
+  // Calculate how many API batches we'll make
+  const totalFileBatches = Math.ceil(fileEntries.length / FILES_PER_API_BATCH)
+
+  console.log(`[AI Validation] Phase 2: Processing ${fileEntries.length} files in ${totalFileBatches} API batch(es) (${FILES_PER_API_BATCH} files/batch)`)
+
+  // Process files in batches - each batch is ONE API call with multiple files
+  for (let batchStart = 0; batchStart < fileEntries.length; batchStart += FILES_PER_API_BATCH) {
+    const fileBatch = fileEntries.slice(batchStart, batchStart + FILES_PER_API_BATCH)
+    const batchNum = Math.floor(batchStart / FILES_PER_API_BATCH) + 1
+
+    console.log(`[AI Validation] API Batch ${batchNum}/${totalFileBatches}: ${fileBatch.length} files`)
+
+    // Prepare file data for batch request
+    const fileDataList: Array<{ file: ScanFile; findings: Vulnerability[]; filePath: string }> = []
+    const filesWithoutContent: Array<{ filePath: string; findings: Vulnerability[] }> = []
+
+    for (const [filePath, fileFindings] of fileBatch) {
+      const file = files.find(f => f.path === filePath)
+      if (!file) {
+        // Can't validate without file content
+        filesWithoutContent.push({ filePath, findings: fileFindings })
+      } else {
+        fileDataList.push({ file, findings: fileFindings, filePath })
+      }
+    }
+
+    // Handle files without content - mark as not validated
+    for (const { findings } of filesWithoutContent) {
+      for (const f of findings) {
+        validatedFindings.push({
+          ...f,
+          validatedByAI: false,
+          validationStatus: 'not_validated' as ValidationStatus,
+          validationNotes: 'File content not available for validation',
+        })
+      }
+    }
+
+    // Skip API call if no files with content
+    if (fileDataList.length === 0) {
+      continue
+    }
+
+    const batchStartTime = Date.now()
+
+    try {
+      // Build multi-file validation request
+      const validationRequest = buildMultiFileValidationRequest(
+        fileDataList.map(({ file, findings }) => ({ file, findings })),
+        context
+      )
+
+      // Use Anthropic prompt caching with multi-file request
+      const response = await makeAnthropicRequestWithRetry(() =>
+        client.messages.create({
+          model: 'claude-3-5-haiku-20241022',
+          max_tokens: 4096, // Increased for multi-file responses
+          system: [
+            {
+              type: 'text',
+              text: HIGH_CONTEXT_VALIDATION_PROMPT,
+              cache_control: { type: 'ephemeral' }, // Cache for 5 minutes
+            },
+          ],
+          messages: [{ role: 'user', content: validationRequest }],
+        })
+      )
+
+      // Track API call stats
+      stats.apiCalls++
+      totalApiBatches++
+
+      // Extract cache metrics from usage
+      const usage = response.usage
+      if (usage) {
+        // DEBUG: Log full usage object to understand token breakdown
+        console.log(`[DEBUG] Batch ${batchNum} - Full API Response Usage:`)
+        console.log(JSON.stringify(usage, null, 2))
+        console.log(`[DEBUG] Breakdown:`)
+        console.log(`  - input_tokens: ${usage.input_tokens || 0}`)
+        console.log(`  - output_tokens: ${usage.output_tokens || 0}`)
+        // @ts-ignore
+        console.log(`  - cache_creation_input_tokens: ${usage.cache_creation_input_tokens || 0}`)
+        // @ts-ignore
+        console.log(`  - cache_read_input_tokens: ${usage.cache_read_input_tokens || 0}`)
+
+        stats.estimatedInputTokens += usage.input_tokens || 0
+        stats.estimatedOutputTokens += usage.output_tokens || 0
+
+        // @ts-ignore - cache fields not in types yet
+        const cacheCreation = usage.cache_creation_input_tokens || 0
+        // @ts-ignore
+        const cacheRead = usage.cache_read_input_tokens || 0
+
+        stats.cacheCreationTokens += cacheCreation
+        stats.cacheReadTokens += cacheRead
+      }
+
+      const textContent = response.content.find((block: { type: string }) => block.type === 'text')
+      if (!textContent || textContent.type !== 'text') {
+        // No valid response - mark all findings as not validated
+        for (const { findings } of fileDataList) {
+          for (const f of findings) {
+            validatedFindings.push({
+              ...f,
+              validatedByAI: false,
+              validationStatus: 'not_validated' as ValidationStatus,
+              validationNotes: 'No valid response from AI',
+            })
+          }
+        }
+        continue
+      }
+
+      // Parse multi-file response
+      const expectedFiles = fileDataList.map(({ filePath }) => filePath)
+      const validationResultsMap = parseMultiFileValidationResponse(textContent.text, expectedFiles)
+
+      // Apply results per file
+      for (const { filePath, findings } of fileDataList) {
+        const fileResults = validationResultsMap.get(filePath)
+
+        if (!fileResults || fileResults.length === 0) {
+          // No results for this file - try single-file parsing as fallback
+          // This handles cases where AI doesn't follow multi-file format
+          const singleFileResults = parseValidationResponse(textContent.text)
+
+          if (singleFileResults.length > 0 && fileDataList.length === 1) {
+            // Single file in batch, use single-file parsing
+            const processedFindings = applyValidationResults(findings, singleFileResults)
+            for (const processed of processedFindings) {
+              stats.validatedFindings++
+              if (processed.validationStatus === 'confirmed') {
+                stats.confirmedFindings++
+              } else if (processed.validationStatus === 'dismissed') {
+                stats.dismissedFindings++
+              } else if (processed.validationStatus === 'downgraded') {
+                stats.downgradedFindings++
+              }
+              validatedFindings.push(processed)
+            }
+          } else {
+            // Keep findings but mark as validation failed for this file
+            console.warn(`[AI Validation] No results for ${filePath}, keeping findings unvalidated`)
+            for (const f of findings) {
+              stats.validatedFindings++
+              stats.confirmedFindings++ // Keep by default
+              validatedFindings.push({
+                ...f,
+                validatedByAI: true,
+                validationStatus: 'confirmed' as ValidationStatus,
+                validationNotes: 'Kept by default - no explicit validation result',
+              })
+            }
+          }
+        } else {
+          // Apply validation results for this file
+          const processedFindings = applyValidationResults(findings, fileResults)
+
+          for (const processed of processedFindings) {
+            stats.validatedFindings++
+            if (processed.validationStatus === 'confirmed') {
+              stats.confirmedFindings++
+            } else if (processed.validationStatus === 'dismissed') {
+              stats.dismissedFindings++
+            } else if (processed.validationStatus === 'downgraded') {
+              stats.downgradedFindings++
+            }
+            validatedFindings.push(processed)
+          }
+        }
+      }
+
+    } catch (error) {
+      console.error(`[AI Validation] Error in batch ${batchNum}:`, error)
+      // Fallback: keep all findings but mark as not validated
+      for (const { findings } of fileDataList) {
+        for (const f of findings) {
+          validatedFindings.push({
+            ...f,
+            validatedByAI: false,
+            validationStatus: 'not_validated' as ValidationStatus,
+            validationNotes: 'Validation failed due to API error',
+          })
+        }
+      }
+    }
+
+    const batchDuration = Date.now() - batchStartTime
+    totalBatchWaitTime += batchDuration
+  }
+
+  // Calculate cache hit rate
+  const totalCacheableTokens = stats.cacheCreationTokens + stats.cacheReadTokens
+  stats.cacheHitRate = totalCacheableTokens > 0
+    ? stats.cacheReadTokens / totalCacheableTokens
+    : 0
+
+  // Calculate estimated cost with cache pricing
+  // Claude 3.5 Haiku pricing (claude-3-5-haiku-20241022):
+  // - Base input: $0.80/1M tokens
+  // - 5m cache writes: $1.00/1M tokens
+  // - Cache hits: $0.08/1M tokens
+  // - Output: $4.00/1M tokens
+  //
+  // Note: input_tokens from Anthropic API represents only fresh (non-cached) tokens
+  // Cache tokens are reported separately and billed at different rates
+
+  const freshInputCost = (stats.estimatedInputTokens * 0.80) / 1_000_000
+  const cacheWriteCost = (stats.cacheCreationTokens * 1.00) / 1_000_000
+  const cacheReadCost = (stats.cacheReadTokens * 0.08) / 1_000_000
+  const outputCost = (stats.estimatedOutputTokens * 4.00) / 1_000_000
+
+  stats.estimatedCost = freshInputCost + cacheWriteCost + cacheReadCost + outputCost
+
+  // Log validation stats with cache metrics and performance
+  console.log(`[AI Validation] Stats:`)
+  console.log(`  - Total findings: ${stats.totalFindings}`)
+  console.log(`  - AI validated: ${stats.validatedFindings}`)
+  console.log(`  - Confirmed: ${stats.confirmedFindings}`)
+  console.log(`  - Dismissed: ${stats.dismissedFindings}`)
+  console.log(`  - Downgraded: ${stats.downgradedFindings}`)
+  console.log(`  - API calls: ${stats.apiCalls}`)
+  console.log(`  - Performance (Phase 2 Multi-File Batching):`)
+  console.log(`    - Files per API batch: ${FILES_PER_API_BATCH}`)
+  console.log(`    - Total API batches: ${totalApiBatches}`)
+  console.log(`    - Total validation time: ${(totalBatchWaitTime / 1000).toFixed(2)}s`)
+  console.log(`    - Avg time per file: ${fileEntries.length > 0 ? (totalBatchWaitTime / fileEntries.length / 1000).toFixed(2) : 0}s`)
+  console.log(`  - Cache metrics:`)
+  console.log(`    - Cache writes: ${stats.cacheCreationTokens.toLocaleString()} tokens`)
+  console.log(`    - Cache reads: ${stats.cacheReadTokens.toLocaleString()} tokens`)
+  console.log(`    - Cache hit rate: ${(stats.cacheHitRate * 100).toFixed(1)}%`)
+  console.log(`  - Token usage:`)
+  console.log(`    - Input (total): ${stats.estimatedInputTokens.toLocaleString()} tokens`)
+  console.log(`    - Output: ${stats.estimatedOutputTokens.toLocaleString()} tokens`)
+  console.log(`  - Estimated cost: $${stats.estimatedCost.toFixed(4)}`)
+
+  // Clear cache after validation complete
+  cachedProjectContext = null
+
+  return { vulnerabilities: validatedFindings, stats }
+}
+
+/**
+ * Build a high-context validation request with full file content
+ */
+function buildHighContextValidationRequest(
+  file: ScanFile,
+  findings: Vulnerability[],
+  projectContext: ProjectContext
+): string {
+  // Add line numbers to full file content
+  const numberedContent = file.content
+    .split('\n')
+    .map((line, i) => `${String(i + 1).padStart(4, ' ')} | ${line}`)
+    .join('\n')
+
+  // Build candidate findings list
+  const candidatesText = findings.map((f, idx) => {
+    return `### Candidate ${idx}
+- **Rule**: ${f.title}
+- **Category**: ${f.category}
+- **Original Severity**: ${f.severity}
+- **Line**: ${f.lineNumber}
+- **Detection Layer**: ${f.layer}
+- **Description**: ${f.description}
+- **Flagged Code**: \`${f.lineContent.trim()}\``
+  }).join('\n\n')
+
+  // Get file-specific context
+  const fileContext = getFileValidationContext(file, projectContext)
+
+  return `## Project Context
+${projectContext.summary}
+
+${fileContext}
+
+## Full File Content
+\`\`\`${file.language || getLanguageFromPath(file.path)}
+${numberedContent}
+\`\`\`
+
+## Candidate Findings to Validate (${findings.length} total)
+
+${candidatesText}
+
+---
+
+Please validate each candidate finding. Return a JSON array with your decision for each.
+Remember: Be AGGRESSIVE in rejecting false positives. Use the full file context and project architecture to make informed decisions.`
+}
+
+/**
+ * Build a multi-file validation request (Phase 2 optimization)
+ * Batches multiple files into a single API call to reduce overhead
+ */
+function buildMultiFileValidationRequest(
+  fileDataList: Array<{ file: ScanFile; findings: Vulnerability[] }>,
+  projectContext: ProjectContext
+): string {
+  const filesContent = fileDataList.map(({ file, findings }, fileIndex) => {
+    // Add line numbers to full file content
+    const numberedContent = file.content
+      .split('\n')
+      .map((line, i) => `${String(i + 1).padStart(4, ' ')} | ${line}`)
+      .join('\n')
+
+    // Build candidate findings list with file-specific indices
+    const candidatesText = findings.map((f, idx) => {
+      return `### Candidate ${idx}
+- **Rule**: ${f.title}
+- **Category**: ${f.category}
+- **Original Severity**: ${f.severity}
+- **Line**: ${f.lineNumber}
+- **Detection Layer**: ${f.layer}
+- **Description**: ${f.description}
+- **Flagged Code**: \`${f.lineContent.trim()}\``
+    }).join('\n\n')
+
+    // Get file-specific context
+    const fileContext = getFileValidationContext(file, projectContext)
+
+    return `
+================================================================================
+FILE ${fileIndex + 1}: ${file.path}
+================================================================================
+
+${fileContext}
+
+### Full File Content
+\`\`\`${file.language || getLanguageFromPath(file.path)}
+${numberedContent}
+\`\`\`
+
+### Candidate Findings to Validate (${findings.length} total)
+
+${candidatesText}`
+  }).join('\n\n')
+
+  return `## Project Context
+${projectContext.summary}
+
+${filesContent}
+
+---
+
+## Response Format
+
+For EACH file, provide a JSON object with the file path and validation results.
+Return a JSON array where each element has:
+- "file": the file path (e.g., "${fileDataList[0]?.file.path || 'path/to/file.ts'}")
+- "validations": array of validation results for that file's candidates
+
+Example response format:
+\`\`\`json
+[
+  {
+    "file": "src/auth.ts",
+    "validations": [
+      { "index": 0, "keep": true, "reason": "Valid finding", "adjustedSeverity": null, "validationNotes": "..." },
+      { "index": 1, "keep": false, "reason": "False positive because..." }
+    ]
+  },
+  {
+    "file": "src/api.ts",
+    "validations": [
+      { "index": 0, "keep": true, "reason": "...", "adjustedSeverity": "high", "validationNotes": "..." }
+    ]
+  }
+]
+\`\`\`
+
+Remember: Be AGGRESSIVE in rejecting false positives. Use the full file context and project architecture to make informed decisions.`
+}
+
+/**
+ * Parse multi-file validation response (Phase 2)
+ * Returns a map of file path -> validation results
+ */
+function parseMultiFileValidationResponse(
+  response: string,
+  expectedFiles: string[]
+): Map<string, ValidationResult[]> {
+  const resultMap = new Map<string, ValidationResult[]>()
+
+  try {
+    // Extract the first top-level JSON array from the response
+    const extractTopLevelArray = (text: string): string | null => {
+      const startIndex = text.indexOf('[')
+      if (startIndex === -1) return null
+
+      let depth = 0
+      let inString = false
+      let stringChar: '"' | "'" | null = null
+      let escape = false
+
+      for (let i = startIndex; i < text.length; i++) {
+        const ch = text[i]
+
+        if (inString) {
+          if (escape) {
+            escape = false
+            continue
+          }
+
+          if (ch === '\\') {
+            escape = true
+            continue
+          }
+
+          if (stringChar && ch === stringChar) {
+            inString = false
+            stringChar = null
+          }
+          continue
+        }
+
+        if (ch === '"' || ch === "'") {
+          inString = true
+          stringChar = ch as '"' | "'"
+          continue
+        }
+
+        if (ch === '[') {
+          depth++
+        } else if (ch === ']') {
+          depth--
+          if (depth === 0) {
+            return text.slice(startIndex, i + 1)
+          }
+        }
+      }
+
+      return null
+    }
+
+    const jsonSlice = extractTopLevelArray(response)
+    if (!jsonSlice) {
+      console.error('[AI Validation] Multi-file: No JSON array found in response')
+      return resultMap
+    }
+
+    const parsed = JSON.parse(jsonSlice)
+    if (!Array.isArray(parsed)) {
+      console.error('[AI Validation] Multi-file: Parsed result is not an array')
+      return resultMap
+    }
+
+    // Process each file's results
+    for (const fileResult of parsed) {
+      if (!fileResult.file || !Array.isArray(fileResult.validations)) {
+        console.warn('[AI Validation] Multi-file: Invalid file result structure, skipping')
+        continue
+      }
+
+      const filePath = fileResult.file
+      const validations: ValidationResult[] = fileResult.validations
+        .filter((item: any) =>
+          typeof item.index === 'number' &&
+          typeof item.keep === 'boolean'
+        )
+        .map((item: any) => ({
+          index: item.index,
+          keep: item.keep,
+          reason: item.reason || '',
+          adjustedSeverity: item.adjustedSeverity || null,
+          validationNotes: item.validationNotes || undefined,
+        }))
+
+      resultMap.set(filePath, validations)
+    }
+
+    // Log any files that weren't in the response
+    for (const expectedFile of expectedFiles) {
+      if (!resultMap.has(expectedFile)) {
+        console.warn(`[AI Validation] Multi-file: No results for ${expectedFile}`)
+      }
+    }
+
+  } catch (error) {
+    console.error('[AI Validation] Multi-file: Failed to parse response:', error)
+  }
+
+  return resultMap
+}
+
+/**
+ * Apply validation results to findings
+ */
+function applyValidationResults(
+  findings: Vulnerability[],
+  validationResults: ValidationResult[]
+): Vulnerability[] {
+  const processed: Vulnerability[] = []
+
+  for (let i = 0; i < findings.length; i++) {
+    const finding = findings[i]
+    const validation = validationResults.find(v => v.index === i)
+
+    if (!validation) {
+      // No validation result - keep with warning
+      processed.push({
+        ...finding,
+        validatedByAI: true,
+        validationStatus: 'confirmed' as ValidationStatus,
+        validationNotes: 'No explicit validation result - kept by default',
+      })
+      continue
+    }
+
+    if (validation.keep) {
+      // Keep the finding
+      const adjustedFinding: Vulnerability = {
+        ...finding,
+        validatedByAI: true,
+        confidence: 'high',
+      }
+
+      if (validation.adjustedSeverity && validation.adjustedSeverity !== finding.severity) {
+        // Severity was adjusted
+        adjustedFinding.originalSeverity = finding.severity
+        adjustedFinding.severity = validation.adjustedSeverity
+        adjustedFinding.validationStatus = 'downgraded' as ValidationStatus
+        adjustedFinding.validationNotes = validation.validationNotes || validation.reason || 'Severity adjusted by AI validation'
+      } else {
+        // Confirmed at original severity
+        adjustedFinding.validationStatus = 'confirmed' as ValidationStatus
+        adjustedFinding.validationNotes = validation.validationNotes || validation.reason
+      }
+
+      processed.push(adjustedFinding)
+    } else {
+      // Finding was dismissed
+      console.log(`[AI Validation] Rejected: ${finding.title} at ${finding.filePath}:${finding.lineNumber} - ${validation.reason}`)
+      // Don't add to processed - finding is removed
+    }
+  }
+
+  return processed
+}
+
+/**
+ * Get language identifier from file path
+ */
+function getLanguageFromPath(path: string): string {
+  const ext = path.split('.').pop()?.toLowerCase()
+  const langMap: Record<string, string> = {
+    ts: 'typescript',
+    tsx: 'tsx',
+    js: 'javascript',
+    jsx: 'jsx',
+    py: 'python',
+    rb: 'ruby',
+    go: 'go',
+    java: 'java',
+    php: 'php',
+    cs: 'csharp',
+    json: 'json',
+    yaml: 'yaml',
+    yml: 'yaml',
+  }
+  return langMap[ext || ''] || ext || 'text'
+}
+
+function parseValidationResponse(response: string): ValidationResult[] {
+  try {
+    // Extract the first top-level JSON array from the response.
+    // The model may include prose before/after the JSON, so we cannot
+    // assume the entire response is valid JSON.
+    const extractTopLevelArray = (text: string): string | null => {
+      const startIndex = text.indexOf('[')
+      if (startIndex === -1) return null
+
+      let depth = 0
+      let inString = false
+      let stringChar: '"' | "'" | null = null
+      let escape = false
+
+      for (let i = startIndex; i < text.length; i++) {
+        const ch = text[i]
+
+        if (inString) {
+          if (escape) {
+            escape = false
+            continue
+          }
+
+          if (ch === '\\') {
+            escape = true
+            continue
+          }
+
+          if (stringChar && ch === stringChar) {
+            inString = false
+            stringChar = null
+          }
+          continue
+        }
+
+        if (ch === '"' || ch === "'") {
+          inString = true
+          stringChar = ch as '"' | "'"
+          continue
+        }
+
+        if (ch === '[') {
+          depth++
+        } else if (ch === ']') {
+          depth--
+          if (depth === 0) {
+            return text.slice(startIndex, i + 1)
+          }
+        }
+      }
+
+      return null
+    }
+
+    const jsonSlice = extractTopLevelArray(response)
+    if (!jsonSlice) return []
+
+    const parsed = JSON.parse(jsonSlice)
+    if (!Array.isArray(parsed)) return []
+
+    return parsed
+      .filter(item =>
+        typeof item.index === 'number' &&
+        typeof item.keep === 'boolean'
+      )
+      .map(item => ({
+        index: item.index,
+        keep: item.keep,
+        reason: item.reason || '',
+        adjustedSeverity: item.adjustedSeverity || null,
+        validationNotes: item.validationNotes || undefined,
+      }))
+  } catch (error) {
+    console.error('Failed to parse validation response:', error)
+    return []
+  }
+}