@oculum/scanner 1.0.0

package/dist/layer3/anthropic.js

@@ -0,0 +1,1745 @@
+"use strict";
+/**
+ * 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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyAutoDismissRules = applyAutoDismissRules;
+exports.analyzeWithAI = analyzeWithAI;
+exports.batchAnalyzeWithAI = batchAnalyzeWithAI;
+exports.validateFindingsWithAI = validateFindingsWithAI;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const openai_1 = __importDefault(require("openai"));
+const context_helpers_1 = require("../utils/context-helpers");
+const project_context_builder_1 = require("../utils/project-context-builder");
+// Import tier system for tier-aware auto-dismiss
+const tiers_1 = require("../tiers");
+// ============================================================================
+// 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() {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        throw new Error('ANTHROPIC_API_KEY environment variable is not set');
+    }
+    return new sdk_1.default({ apiKey });
+}
+// Initialize OpenAI client
+let openaiClient = null;
+function getOpenAIClient() {
+    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_1.default({ 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
+};
+const AUTO_DISMISS_RULES = [
+    // Test files - often contain intentional "vulnerable" patterns for testing
+    {
+        name: 'test_file',
+        check: (finding) => (0, context_helpers_1.isTestOrMockFile)(finding.filePath),
+        reason: 'Finding in test/mock file',
+    },
+    // Example/demo code - not production code
+    {
+        name: 'example_file',
+        check: (finding) => (0, context_helpers_1.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) => (0, context_helpers_1.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 (0, context_helpers_1.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 (0, context_helpers_1.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 (0, context_helpers_1.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 = (0, tiers_1.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
+ */
+function applyAutoDismissRules(findings) {
+    const toValidate = [];
+    const dismissed = [];
+    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.`;
+/**
+ * Build auth context string for AI prompt
+ */
+function buildAuthContextForPrompt(ctx) {
+    if (!ctx)
+        return '';
+    const parts = [];
+    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') : '';
+}
+async function analyzeWithAI(file, context) {
+    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) => 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',
+            layer: 3,
+        }));
+    }
+    catch (error) {
+        console.error('AI analysis error:', error);
+        return [];
+    }
+}
+// Parse the AI response JSON
+function parseAIResponse(response) {
+    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) {
+    const valid = ['critical', 'high', 'medium', 'low'];
+    return valid.includes(severity)
+        ? severity
+        : 'medium';
+}
+function validateCategory(category) {
+    const valid = [
+        '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)
+        ? category
+        : 'dangerous_function';
+}
+function getLineContent(content, lineNumber) {
+    const lines = content.split('\n');
+    return lines[lineNumber - 1]?.trim() || '';
+}
+// Batch analyze multiple files (with rate limiting)
+async function batchAnalyzeWithAI(files, context, maxConcurrent = 3) {
+    const vulnerabilities = [];
+    // 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.`;
+// Cache for project context (built once per scan)
+let cachedProjectContext = null;
+/**
+ * Helper function to make API calls with retry logic for rate limiting
+ * Implements exponential backoff for 429 (rate limit) errors
+ */
+async function makeAnthropicRequestWithRetry(requestFn, maxRetries = 3, initialDelayMs = 1000) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await requestFn();
+        }
+        catch (error) {
+            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(requestFn, maxRetries = 3, initialDelayMs = 1000) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await requestFn();
+        }
+        catch (error) {
+            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, files, projectContext, stats) {
+    const client = getOpenAIClient();
+    // Build or use cached project context
+    const context = projectContext || cachedProjectContext || (0, project_context_builder_1.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();
+    for (const finding of findings) {
+        const existing = findingsByFile.get(finding.filePath) || [];
+        existing.push(finding);
+        findingsByFile.set(finding.filePath, existing);
+    }
+    const validatedFindings = [];
+    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 = [];
+    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) => {
+        const { batchNum, fileBatch } = batchDef;
+        const batchFindings = [];
+        // Prepare file data for batch request
+        const fileDataList = [];
+        const filesWithoutContent = [];
+        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',
+                    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.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) / 1000000;
+                const cachedCost = (cachedTokens * GPT5_MINI_PRICING.cached) / 1000000;
+                const outputCost = (completionTokens * GPT5_MINI_PRICING.output) / 1000000;
+                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',
+                            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',
+                                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',
+                        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
+ */
+async function validateFindingsWithAI(findings, files, projectContext) {
+    // Initialize stats tracking
+    const stats = {
+        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 || (0, project_context_builder_1.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();
+    for (const finding of findings) {
+        const existing = findingsByFile.get(finding.filePath) || [];
+        existing.push(finding);
+        findingsByFile.set(finding.filePath, existing);
+    }
+    const validatedFindings = [];
+    // 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 = [];
+        const filesWithoutContent = [];
+        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',
+                    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) => 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',
+                            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',
+                                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',
+                        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) / 1000000;
+    const cacheWriteCost = (stats.cacheCreationTokens * 1.00) / 1000000;
+    const cacheReadCost = (stats.cacheReadTokens * 0.08) / 1000000;
+    const outputCost = (stats.estimatedOutputTokens * 4.00) / 1000000;
+    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, findings, projectContext) {
+    // 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 = (0, project_context_builder_1.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, projectContext) {
+    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 = (0, project_context_builder_1.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, expectedFiles) {
+    const resultMap = new Map();
+    try {
+        // Extract the first top-level JSON array from the response
+        const extractTopLevelArray = (text) => {
+            const startIndex = text.indexOf('[');
+            if (startIndex === -1)
+                return null;
+            let depth = 0;
+            let inString = false;
+            let stringChar = 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;
+                    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 = fileResult.validations
+                .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,
+            }));
+            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, validationResults) {
+    const processed = [];
+    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',
+                validationNotes: 'No explicit validation result - kept by default',
+            });
+            continue;
+        }
+        if (validation.keep) {
+            // Keep the finding
+            const adjustedFinding = {
+                ...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';
+                adjustedFinding.validationNotes = validation.validationNotes || validation.reason || 'Severity adjusted by AI validation';
+            }
+            else {
+                // Confirmed at original severity
+                adjustedFinding.validationStatus = 'confirmed';
+                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) {
+    const ext = path.split('.').pop()?.toLowerCase();
+    const langMap = {
+        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) {
+    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) => {
+            const startIndex = text.indexOf('[');
+            if (startIndex === -1)
+                return null;
+            let depth = 0;
+            let inString = false;
+            let stringChar = 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;
+                    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 [];
+    }
+}
+//# sourceMappingURL=anthropic.js.map