@oculum/scanner 1.0.0

package/src/index.ts

@@ -0,0 +1,823 @@
+/**
+ * Scanner Orchestrator
+ * Coordinates all three scanning layers and produces final results
+ */
+
+import type {
+  ScanFile,
+  ScanResult,
+  Vulnerability,
+  SeverityCounts,
+  CategoryCounts,
+  VulnerabilityCategory,
+  ScanMode,
+  ScanModeConfig,
+  ScanDepth,
+} from './types'
+import { SCANNABLE_EXTENSIONS, SPECIAL_FILES, MAX_FILE_SIZE, SCAN_MODE_DEFAULTS } from './types'
+import { runLayer1Scan } from './layer1'
+import { runLayer2Scan } from './layer2'
+import { runLayer3Scan } from './layer3'
+import { validateFindingsWithAI, applyAutoDismissRules, type ValidationStats } from './layer3/anthropic'
+import { aggregateLocalhostFindings } from './layer1/urls'
+import { detectGlobalAuthMiddleware, type MiddlewareAuthConfig, getRoutePathFromFile, isRouteProtectedByMiddleware } from './utils/middleware-detector'
+import { detectAuthHelpers } from './utils/auth-helper-detector'
+import { buildFileAuthImports } from './utils/imported-auth-detector'
+// Tier system imports for filtering by scan depth
+import {
+  type DetectorTier,
+  type TierStats,
+  getTierForCategory,
+  isTierVisibleAtDepth,
+  shouldValidateWithAI,
+  computeTierStats,
+  formatTierStats,
+} from './tiers'
+
+// Maximum candidates per file to send to AI validation (cost control)
+const MAX_VALIDATION_CANDIDATES_PER_FILE = 10
+
+/**
+ * Classify vulnerabilities into tier groups for filtering
+ */
+interface TierClassification {
+  /** Tier A (core): High-precision, always visible */
+  core: Vulnerability[]
+  /** Tier B (ai_assisted): Context-heavy, needs AI validation */
+  ai_assisted: Vulnerability[]
+  /** Tier C (experimental): Hidden from users, internal use only */
+  experimental: Vulnerability[]
+}
+
+/**
+ * Classify vulnerabilities by their detector tier
+ */
+function classifyByTier(vulnerabilities: Vulnerability[]): TierClassification {
+  const result: TierClassification = {
+    core: [],
+    ai_assisted: [],
+    experimental: [],
+  }
+
+  for (const vuln of vulnerabilities) {
+    const tier = getTierForCategory(vuln.category, vuln.layer)
+    result[tier].push(vuln)
+  }
+
+  return result
+}
+
+/**
+ * Filter vulnerabilities based on scan depth and tier
+ *
+ * - cheap: Only Tier A (core) findings are surfaced
+ * - validated: Tier A visible, Tier B goes through AI validation
+ * - deep: Same as validated, plus Layer 3 semantic analysis
+ *
+ * Tier C (experimental) is NEVER surfaced to users, regardless of depth.
+ */
+function filterByTierAndDepth(
+  vulnerabilities: Vulnerability[],
+  depth: ScanDepth
+): {
+  /** Findings to surface directly (no AI validation needed) */
+  toSurface: Vulnerability[]
+  /** Findings to send through AI validation */
+  toValidate: Vulnerability[]
+  /** Findings hidden from users (Tier C) */
+  hidden: Vulnerability[]
+  /** Tier stats for logging */
+  tierStats: TierStats
+} {
+  const classified = classifyByTier(vulnerabilities)
+  const tierStats = computeTierStats(
+    vulnerabilities.map(v => ({ category: v.category, layer: v.layer }))
+  )
+
+  switch (depth) {
+    case 'cheap':
+      // Only Tier A is visible, no AI validation
+      return {
+        toSurface: classified.core,
+        toValidate: [],
+        hidden: [...classified.ai_assisted, ...classified.experimental],
+        tierStats,
+      }
+
+    case 'validated':
+    case 'deep':
+      // Tier A always surfaces, Tier B goes to AI validation
+      // For findings that already require AI validation, only include Tier A/B
+      const coreRequiringValidation = classified.core.filter(v =>
+        v.requiresAIValidation ||
+        v.category === 'high_entropy_string' ||
+        v.category === 'hardcoded_secret' ||
+        (v.category === 'sensitive_url' && v.severity !== 'info')
+      )
+      const coreNotRequiringValidation = classified.core.filter(v =>
+        !coreRequiringValidation.includes(v)
+      )
+
+      return {
+        toSurface: coreNotRequiringValidation,
+        toValidate: [...coreRequiringValidation, ...classified.ai_assisted],
+        hidden: classified.experimental,
+        tierStats,
+      }
+  }
+}
+
+export interface ScanOptions {
+  /** Enable AI-powered validation and analysis */
+  enableAI?: boolean
+  /** Maximum files to scan */
+  maxFiles?: number
+  /** Branch being scanned */
+  branch?: string
+  /** Scan mode configuration (full vs incremental) */
+  scanMode?: ScanMode | ScanModeConfig
+  /** Scan depth (cheap/validated/deep) - controls AI usage */
+  scanDepth?: ScanDepth
+}
+
+export interface ScanProgress {
+  status: 'fetching' | 'layer1' | 'layer2' | 'layer3' | 'validating' | 'complete' | 'failed'
+  message: string
+  filesProcessed: number
+  totalFiles: number
+  vulnerabilitiesFound: number
+}
+
+export type ProgressCallback = (progress: ScanProgress) => void
+
+/**
+ * Resolve scan mode configuration from options
+ *
+ * Handles both scan mode (full/incremental) and depth (cheap/validated/deep).
+ * Depth controls AI usage:
+ * - cheap: skip AI validation + skip Layer 3
+ * - validated: run AI validation, skip Layer 3
+ * - deep: run AI validation + Layer 3
+ */
+function resolveScanModeConfig(options: ScanOptions): ScanModeConfig {
+  const scanModeOption = options.scanMode
+
+  // Determine base mode
+  const mode: ScanMode = !scanModeOption ? 'full'
+    : typeof scanModeOption === 'string' ? scanModeOption
+    : scanModeOption.mode
+
+  const defaults = SCAN_MODE_DEFAULTS[mode]
+
+  // Build config from defaults + explicit overrides
+  let config: ScanModeConfig = {
+    ...defaults,
+    mode,
+    ...(typeof scanModeOption === 'object' ? scanModeOption : {}),
+  }
+
+  // Apply depth mode (default: 'cheap')
+  const depth = options.scanDepth ?? 'cheap'
+  config.scanDepth = depth
+
+  // Map depth to skipAIValidation/skipLayer3 unless explicitly overridden
+  const hasExplicitSkipAI = typeof scanModeOption === 'object' && scanModeOption.skipAIValidation !== undefined
+  const hasExplicitSkipL3 = typeof scanModeOption === 'object' && scanModeOption.skipLayer3 !== undefined
+
+  if (!hasExplicitSkipAI) {
+    config.skipAIValidation = depth === 'cheap'
+  }
+  if (!hasExplicitSkipL3) {
+    config.skipLayer3 = depth !== 'deep'
+  }
+
+  return config
+}
+
+/**
+ * Run a complete security scan on the provided files
+ * 
+ * Supports two scan modes:
+ * - full: Complete scan with AI validation on all files (initial onboarding, deep audits)
+ * - incremental: Focused scan on changed files only (CI/CD, fast feedback)
+ */
+export async function runScan(
+  files: ScanFile[],
+  repoInfo: { name: string; url: string; branch: string },
+  options: ScanOptions = {},
+  onProgress?: ProgressCallback
+): Promise<ScanResult> {
+  const startTime = Date.now()
+  const allVulnerabilities: Vulnerability[] = []
+  
+  // Resolve scan mode configuration
+  const scanModeConfig = resolveScanModeConfig(options)
+  const isIncremental = scanModeConfig.mode === 'incremental'
+  const depth = scanModeConfig.scanDepth || 'cheap'
+
+  console.log(`[Scanner] repo=${repoInfo.name} mode=${scanModeConfig.mode} depth=${depth} files=${files.length}`)
+  if (isIncremental && scanModeConfig.changedFiles) {
+    console.log(`[Scanner] repo=${repoInfo.name} incremental_files=${scanModeConfig.changedFiles.length}`)
+  }
+
+  // Report progress helper
+  const reportProgress = (
+    status: ScanProgress['status'],
+    message: string,
+    vulnerabilitiesFound: number = allVulnerabilities.length
+  ) => {
+    if (onProgress) {
+      onProgress({
+        status,
+        message,
+        filesProcessed: files.length,
+        totalFiles: files.length,
+        vulnerabilitiesFound,
+      })
+    }
+  }
+  
+  // For incremental scans, filter to only changed files for AI-heavy operations
+  // but still run static analysis on all files for context
+  const filesForAI = isIncremental && scanModeConfig.changedFiles
+    ? files.filter(f => scanModeConfig.changedFiles!.some(cf => f.path.endsWith(cf) || f.path.includes(cf)))
+    : files
+
+  try {
+    // Detect global auth middleware before scanning (always on all files for context)
+    const middlewareConfig = detectGlobalAuthMiddleware(files)
+    if (middlewareConfig.hasAuthMiddleware) {
+      console.log(`[Scanner] repo=${repoInfo.name} auth_middleware=${middlewareConfig.authType || 'unknown'} file=${middlewareConfig.middlewareFile}`)
+    }
+
+    // Build imported auth registry for cross-file middleware detection
+    const fileAuthImports = buildFileAuthImports(files)
+    const filesWithImportedAuth = Array.from(fileAuthImports.values()).filter(f => f.usesImportedAuth).length
+    if (filesWithImportedAuth > 0) {
+      console.log(`[Scanner] repo=${repoInfo.name} files_with_imported_auth=${filesWithImportedAuth}`)
+    }
+
+    // Layer 1: Surface Scan
+    reportProgress('layer1', 'Running surface scan (patterns, entropy, config)...')
+    let layer1Result = await runLayer1Scan(files)
+
+    // Aggregate repeated localhost findings
+    const layer1RawCount = layer1Result.vulnerabilities.length
+    layer1Result = {
+      ...layer1Result,
+      vulnerabilities: aggregateLocalhostFindings(layer1Result.vulnerabilities)
+    }
+    console.log(`[Layer1] repo=${repoInfo.name} findings_raw=${layer1RawCount} findings_deduped=${layer1Result.vulnerabilities.length}`)
+
+    // Layer 2: Structural Scan
+    reportProgress('layer2', 'Running structural scan (variables, logic gates)...', layer1Result.vulnerabilities.length)
+    const layer2Result = await runLayer2Scan(files, { middlewareConfig, fileAuthImports })
+
+    // Format heuristic breakdown for logging
+    const heuristicBreakdown = Object.entries(layer2Result.stats.raw)
+      .filter(([, count]) => count > 0)
+      .map(([name, count]) => `${name}:${count}`)
+      .join(',')
+    console.log(`[Layer2] repo=${repoInfo.name} findings_raw=${Object.values(layer2Result.stats.raw).reduce((a, b) => a + b, 0)} findings_deduped=${layer2Result.vulnerabilities.length} heuristic_breakdown={${heuristicBreakdown}}`)
+
+    // Combine Layer 1 and Layer 2 findings
+    const layer12Findings = [...layer1Result.vulnerabilities, ...layer2Result.vulnerabilities]
+
+    // Aggregate noisy findings BEFORE tier filtering to reduce noise
+    const beforeAggregationCount = layer12Findings.length
+    const aggregatedFindings = aggregateNoisyFindings(layer12Findings)
+    const aggregatedCount = beforeAggregationCount - aggregatedFindings.length
+
+    // Apply tier-based filtering based on scan depth
+    // This is the key integration point for the detector tier system
+    const tierFiltered = filterByTierAndDepth(aggregatedFindings, depth)
+
+    // Log tier breakdown
+    console.log(`[Scanner] repo=${repoInfo.name} tier_breakdown=${formatTierStats(tierFiltered.tierStats)}`)
+    console.log(`[Scanner] repo=${repoInfo.name} depth=${depth} tier_routing: surface=${tierFiltered.toSurface.length} validate=${tierFiltered.toValidate.length} hidden=${tierFiltered.hidden.length}`)
+
+    // For cheap scans: Tier A surfaces directly, Tier B/C are hidden
+    // For validated/deep: Tier A surfaces, Tier B goes through AI validation, Tier C hidden
+
+    // Some Tier A findings still need AI validation (entropy, secrets, AI-specific)
+    const additionalValidation = tierFiltered.toSurface.filter(v =>
+      v.requiresAIValidation ||
+      v.category === 'ai_prompt_injection' ||     // Story B1: Prompt hygiene
+      v.category === 'ai_unsafe_execution' ||     // Story B2: LLM output execution
+      v.category === 'ai_overpermissive_tool'     // Story B4: Agent tool permissions
+    )
+
+    // Surface findings that don't need validation (excluding those that do)
+    const noValidationNeeded = tierFiltered.toSurface.filter(v => !additionalValidation.includes(v))
+
+    // Combine tier-filtered validation candidates with additional ones
+    const requiresValidation = [...tierFiltered.toValidate, ...additionalValidation]
+
+    // Apply smart auto-dismiss rules BEFORE AI validation (saves API costs)
+    const { toValidate: afterAutoDismiss, dismissed: autoDismissed } = applyAutoDismissRules(requiresValidation)
+
+    // Track auto-dismiss by severity for logging
+    const autoDismissBySeverity: Record<string, number> = { info: 0, low: 0, medium: 0, high: 0, critical: 0 }
+    for (const d of autoDismissed) {
+      autoDismissBySeverity[d.finding.severity] = (autoDismissBySeverity[d.finding.severity] || 0) + 1
+    }
+    if (autoDismissed.length > 0) {
+      console.log(`[Layer2] repo=${repoInfo.name} auto_dismissed_total=${autoDismissed.length} by_severity={info:${autoDismissBySeverity.info},low:${autoDismissBySeverity.low},medium:${autoDismissBySeverity.medium},high:${autoDismissBySeverity.high}}`)
+    }
+
+    // Apply per-file cap to validation candidates (cost control)
+    // Use scan mode config for max files
+    const maxValidationFiles = scanModeConfig.maxAIValidationFiles || MAX_VALIDATION_CANDIDATES_PER_FILE
+    const cappedValidation = capValidationCandidatesPerFile(afterAutoDismiss, maxValidationFiles)
+
+    // AI Validation of selected findings (if AI is enabled and not skipped by scan mode)
+    let validatedFindings = cappedValidation
+    let capturedValidationStats: ValidationStats | undefined = undefined
+    const shouldValidate = options.enableAI !== false && !scanModeConfig.skipAIValidation && cappedValidation.length > 0
+
+    if (shouldValidate) {
+      reportProgress('validating', 'AI validating findings (entropy, secrets, AI patterns)...', cappedValidation.length)
+
+      // For incremental scans, only validate findings in changed files
+      const findingsToValidate = isIncremental && scanModeConfig.changedFiles
+        ? cappedValidation.filter(v => scanModeConfig.changedFiles!.some(cf => v.filePath.endsWith(cf) || v.filePath.includes(cf)))
+        : cappedValidation
+
+      if (findingsToValidate.length > 0) {
+        const validationResult = await validateFindingsWithAI(findingsToValidate, filesForAI)
+        validatedFindings = validationResult.vulnerabilities
+        const { stats: validationStats } = validationResult
+        capturedValidationStats = validationStats // Capture for return
+
+        console.log(`[AI Validation] repo=${repoInfo.name} depth=${depth} candidates=${findingsToValidate.length} capped_from=${requiresValidation.length} auto_dismissed=${autoDismissed.length} kept=${validationStats.confirmedFindings} rejected=${validationStats.dismissedFindings} downgraded=${validationStats.downgradedFindings}`)
+        console.log(`[AI Validation] cost_estimate: input_tokens=${validationStats.estimatedInputTokens} output_tokens=${validationStats.estimatedOutputTokens} cost=$${validationStats.estimatedCost.toFixed(4)} api_calls=${validationStats.apiCalls}`)
+
+        // Add back findings that weren't validated (not in changed files)
+        const notValidated = cappedValidation.filter(v => !findingsToValidate.includes(v))
+        validatedFindings.push(...notValidated)
+      }
+    } else if (scanModeConfig.skipAIValidation) {
+      console.log(`[AI Validation] repo=${repoInfo.name} depth=${depth} skipped=true reason=scan_mode_config`)
+    }
+
+    // Combine validated and non-validated findings
+    allVulnerabilities.push(...validatedFindings, ...noValidationNeeded)
+
+    // Layer 3: AI Semantic Analysis (new findings)
+    // Skip for incremental scans by default (configurable)
+    const shouldRunLayer3 = options.enableAI !== false && !scanModeConfig.skipLayer3
+
+    if (shouldRunLayer3) {
+      reportProgress('layer3', 'Running AI semantic analysis...', allVulnerabilities.length)
+
+      // For incremental scans, only analyze changed files
+      const filesToAnalyze = isIncremental ? filesForAI : files
+      const maxLayer3Files = scanModeConfig.maxLayer3Files || 10
+
+      // Detect auth helpers for Layer 3 context
+      const authHelperContext = detectAuthHelpers(files)
+
+      const layer3Result = await runLayer3Scan(filesToAnalyze, {
+        enableAI: options.enableAI,
+        maxFiles: maxLayer3Files,
+        projectContext: {
+          middlewareConfig: middlewareConfig.hasAuthMiddleware ? {
+            hasAuthMiddleware: true,
+            authType: middlewareConfig.authType,
+            protectedPaths: middlewareConfig.protectedPaths,
+          } : undefined,
+          authHelpers: authHelperContext.hasThrowingHelpers ? {
+            hasThrowingHelpers: true,
+            summary: authHelperContext.summary,
+          } : undefined,
+        },
+      })
+      allVulnerabilities.push(...layer3Result.vulnerabilities)
+      console.log(`[Layer3] repo=${repoInfo.name} depth=${depth} files_analyzed=${layer3Result.aiAnalyzed} findings=${layer3Result.vulnerabilities.length}`)
+    } else if (scanModeConfig.skipLayer3) {
+      console.log(`[Layer3] repo=${repoInfo.name} depth=${depth} skipped=true reason=scan_mode_config`)
+    }
+
+    // Deduplicate vulnerabilities
+    const uniqueVulnerabilities = deduplicateVulnerabilities(allVulnerabilities)
+
+    // Resolve contradictions (e.g., middleware-protected INFO vs missing-auth CRITICAL on same route)
+    const resolvedVulnerabilities = resolveContradictions(uniqueVulnerabilities, middlewareConfig)
+    
+    // Sort by severity
+    const sortedVulnerabilities = sortBySeverity(resolvedVulnerabilities)
+
+    // Compute issue-mix counts
+    const severityCounts = computeSeverityCounts(sortedVulnerabilities)
+    const categoryCounts = computeCategoryCounts(sortedVulnerabilities)
+    const hasBlockingIssues = severityCounts.critical > 0 || severityCounts.high > 0
+
+    reportProgress('complete', 'Scan complete!', sortedVulnerabilities.length)
+
+    return {
+      repoName: repoInfo.name,
+      repoUrl: repoInfo.url,
+      branch: repoInfo.branch,
+      filesScanned: files.length,
+      filesSkipped: 0, // TODO: track skipped files
+      vulnerabilities: sortedVulnerabilities,
+      severityCounts,
+      categoryCounts,
+      hasBlockingIssues,
+      scanDuration: Date.now() - startTime,
+      timestamp: new Date().toISOString(),
+      validationStats: capturedValidationStats,
+    }
+  } catch (error) {
+    reportProgress('failed', `Scan failed: ${error}`)
+    throw error
+  }
+}
+
+/**
+ * Aggregate noisy findings in the same file to reduce clutter
+ * Groups repeated findings with same filePath + category + title
+ * Especially useful for AI pattern spam
+ */
+function aggregateNoisyFindings(vulnerabilities: Vulnerability[]): Vulnerability[] {
+  // Group findings by file + category + title
+  const groups = new Map<string, Vulnerability[]>()
+  
+  for (const vuln of vulnerabilities) {
+    // Create grouping key: same file, category, and base title (without line-specific info)
+    const baseTitle = vuln.title.replace(/\s*\(\d+ instances?\)/, '').trim()
+    const key = `${vuln.filePath}|${vuln.category}|${baseTitle}`
+    
+    const existing = groups.get(key) || []
+    existing.push(vuln)
+    groups.set(key, existing)
+  }
+  
+  const result: Vulnerability[] = []
+  
+  for (const [key, group] of groups) {
+    // If only 1-2 findings, keep them as-is
+    if (group.length <= 2) {
+      result.push(...group)
+      continue
+    }
+    
+    // For 3+ similar findings in same file, aggregate into one
+    const first = group[0]
+    const lineNumbers = group.map(v => v.lineNumber).sort((a, b) => a - b)
+    const uniqueLines = [...new Set(lineNumbers)]
+    
+    // Format line numbers nicely (show first few, then "...")
+    const lineDisplay = uniqueLines.length > 5
+      ? `${uniqueLines.slice(0, 5).join(', ')}... (${uniqueLines.length} total)`
+      : uniqueLines.join(', ')
+    
+    // Keep highest severity from the group
+    const highestSeverity = group.reduce((max, v) => 
+      severityRank(v.severity) > severityRank(max.severity) ? v : max
+    , group[0]).severity
+    
+    // Create aggregated finding
+    const aggregated: Vulnerability = {
+      id: `${first.id}-aggregated`,
+      filePath: first.filePath,
+      lineNumber: uniqueLines[0], // First occurrence
+      lineContent: `${group.length} instances across this file`,
+      severity: highestSeverity,
+      category: first.category,
+      title: `${first.title.replace(/\s*\(\d+ instances?\)/, '')} (${group.length} instances)`,
+      description: `${first.description}\n\nFound ${group.length} occurrences at lines: ${lineDisplay}`,
+      suggestedFix: first.suggestedFix,
+      confidence: first.confidence,
+      layer: first.layer,
+      requiresAIValidation: first.requiresAIValidation,
+    }
+    
+    result.push(aggregated)
+  }
+  
+  return result
+}
+
+/**
+ * Cap validation candidates per file to control AI costs
+ * Prioritizes by:
+ * 1. Tier (ai_assisted findings need AI most, so they get priority)
+ * 2. Severity (critical > high > medium > low > info)
+ * 3. Category importance (secrets/URLs/auth before cosmetic patterns)
+ */
+function capValidationCandidatesPerFile(
+  vulnerabilities: Vulnerability[],
+  maxPerFile: number = MAX_VALIDATION_CANDIDATES_PER_FILE
+): Vulnerability[] {
+  // Group by file
+  const byFile = new Map<string, Vulnerability[]>()
+  for (const vuln of vulnerabilities) {
+    const existing = byFile.get(vuln.filePath) || []
+    existing.push(vuln)
+    byFile.set(vuln.filePath, existing)
+  }
+
+  const result: Vulnerability[] = []
+
+  for (const [filePath, fileVulns] of byFile) {
+    // Sort by priority: tier first (ai_assisted needs AI most), then severity, then category
+    const sorted = [...fileVulns].sort((a, b) => {
+      // Tier comparison: ai_assisted (needs AI) > core (high precision) > experimental (hidden anyway)
+      const tierPriority = (v: Vulnerability): number => {
+        const tier = getTierForCategory(v.category, v.layer)
+        if (tier === 'ai_assisted') return 10  // Highest priority - these NEED AI validation
+        if (tier === 'core') return 5           // High precision, but AI can still help
+        return 1                                 // Experimental - shouldn't even be here
+      }
+      const tierDiff = tierPriority(b) - tierPriority(a)
+      if (tierDiff !== 0) return tierDiff
+
+      // Severity comparison (higher severity = higher priority)
+      const severityDiff = severityRank(b.severity) - severityRank(a.severity)
+      if (severityDiff !== 0) return severityDiff
+
+      // Category importance (secrets/URLs/auth before AI patterns)
+      const categoryPriority = (v: Vulnerability): number => {
+        if (v.category === 'hardcoded_secret') return 10
+        if (v.category === 'high_entropy_string') return 9
+        if (v.category === 'sensitive_url') return 8
+        if (v.category === 'missing_auth') return 7
+        if (v.category === 'ai_pattern') return 3
+        return 5
+      }
+      return categoryPriority(b) - categoryPriority(a)
+    })
+
+    // Take top N per file
+    const capped = sorted.slice(0, maxPerFile)
+    result.push(...capped)
+
+    if (sorted.length > maxPerFile) {
+      console.log(`[Scanner] Capped ${filePath}: ${sorted.length} → ${maxPerFile} validation candidates`)
+    }
+  }
+
+  return result
+}
+
+/**
+ * Remove duplicate vulnerabilities (same file, line, category)
+ * Also handles cross-layer URL duplicates (sensitive_url + ai_pattern)
+ */
+function deduplicateVulnerabilities(vulnerabilities: Vulnerability[]): Vulnerability[] {
+  const seen = new Map<string, Vulnerability>()
+  const urlDedupMap = new Map<string, Vulnerability>()
+
+  for (const vuln of vulnerabilities) {
+    // Special handling for URL duplicates across layers
+    // (e.g., Layer 1 detects as sensitive_url, Layer 2 detects as ai_pattern)
+    if ((vuln.category === 'sensitive_url' || vuln.category === 'ai_pattern') &&
+        /url|localhost|127\.0\.0\.1|http/i.test(vuln.lineContent)) {
+
+      // Create compound key that ignores category differences for URLs
+      const urlKey = `${vuln.filePath}:${vuln.lineNumber}:url_finding`
+      const existing = urlDedupMap.get(urlKey)
+
+      if (!existing) {
+        urlDedupMap.set(urlKey, vuln)
+      } else {
+        // Keep Layer 1 (more specific) over Layer 2 AI pattern
+        // Or keep higher severity
+        if (vuln.layer < existing.layer ||
+            severityRank(vuln.severity) > severityRank(existing.severity)) {
+          urlDedupMap.set(urlKey, vuln)
+        }
+      }
+      continue
+    }
+
+    // Standard deduplication for non-URL findings
+    const key = `${vuln.filePath}:${vuln.lineNumber}:${vuln.category}`
+    const existing = seen.get(key)
+
+    // Keep the higher severity or higher confidence finding
+    if (!existing) {
+      seen.set(key, vuln)
+    } else if (severityRank(vuln.severity) > severityRank(existing.severity)) {
+      seen.set(key, vuln)
+    } else if (
+      severityRank(vuln.severity) === severityRank(existing.severity) &&
+      confidenceRank(vuln.confidence) > confidenceRank(existing.confidence)
+    ) {
+      seen.set(key, vuln)
+    }
+  }
+
+  // Combine URL and non-URL findings
+  return [...Array.from(seen.values()), ...Array.from(urlDedupMap.values())]
+}
+
+/**
+ * Resolve contradictions in findings
+ * 
+ * Key contradiction types:
+ * 1. Same route has both "protected by middleware" (info) AND "missing auth" (high/critical)
+ *    → Keep only the info-level "protected by middleware" finding
+ * 2. Same file has BYOK "transient use" (info) AND "key stored insecurely" (high)
+ *    → Keep only the most accurate one based on context
+ * 3. Same line has conflicting severities from different layers
+ *    → Prefer the lower severity if one explicitly notes protection
+ */
+function resolveContradictions(
+  vulnerabilities: Vulnerability[],
+  middlewareConfig?: MiddlewareAuthConfig
+): Vulnerability[] {
+  // Group findings by file path for contradiction analysis
+  const byFile = new Map<string, Vulnerability[]>()
+  for (const vuln of vulnerabilities) {
+    const existing = byFile.get(vuln.filePath) || []
+    existing.push(vuln)
+    byFile.set(vuln.filePath, existing)
+  }
+
+  const result: Vulnerability[] = []
+
+  for (const [filePath, fileVulns] of byFile) {
+    // Check for auth contradictions in this file
+    const authFindings = fileVulns.filter(v => v.category === 'missing_auth')
+    const otherFindings = fileVulns.filter(v => v.category !== 'missing_auth')
+    
+    // Identify protected routes (middleware or auth helper)
+    const protectedInfos = authFindings.filter(v => 
+      v.severity === 'info' && 
+      (v.validationNotes === 'MIDDLEWARE_PROTECTED' || 
+       v.validationNotes === 'AUTH_HELPER_PROTECTED' ||
+       v.title.includes('protected by middleware') ||
+       v.title.includes('uses auth helper'))
+    )
+    
+    // NEW: Check if this file's route is protected by middleware (even without explicit info finding)
+    // This catches Layer 3 findings that don't have the Layer 2 protection info
+    const routePath = getRoutePathFromFile(filePath)
+    const isAPIRouteProtected = routePath && middlewareConfig?.hasAuthMiddleware
+      ? isRouteProtectedByMiddleware(routePath, middlewareConfig).isProtected
+      : false
+    
+    // Also check if file is a client component calling protected API routes
+    // Client components (components/, app/ without route.ts) calling /api/** are safe
+    const isClientCallingProtectedAPI = 
+      middlewareConfig?.hasAuthMiddleware &&
+      (filePath.includes('/components/') || 
+       (filePath.includes('/app/') && !filePath.includes('route.ts')))
+    
+    // If we have protected route info findings OR the route is protected by middleware
+    if (protectedInfos.length > 0 || isAPIRouteProtected || isClientCallingProtectedAPI) {
+      // Keep the protected info findings
+      result.push(...protectedInfos)
+      
+      // For other auth findings on same file, either drop or downgrade to info
+      const otherAuthFindings = authFindings.filter(v => !protectedInfos.includes(v))
+      
+      for (const vuln of otherAuthFindings) {
+        // If it's high/critical missing auth on a protected route, drop it entirely
+        // (the middleware/helper protection supersedes)
+        if (vuln.severity === 'critical' || vuln.severity === 'high') {
+          const reason = isAPIRouteProtected 
+            ? 'API route protected by middleware' 
+            : isClientCallingProtectedAPI 
+              ? 'client component calling protected API'
+              : 'route is protected'
+          console.log(`[Contradiction] Dropping "${vuln.title}" (${vuln.severity}) - ${reason}`)
+          continue // Skip this finding
+        }
+        
+        // Keep lower severity auth findings as-is
+        result.push(vuln)
+      }
+    } else {
+      // No protection detected - keep all auth findings as-is
+      result.push(...authFindings)
+    }
+    
+    // Handle BYOK contradictions
+    const byokFindings = otherFindings.filter(v => 
+      v.category === 'ai_pattern' && v.title.toLowerCase().includes('byok')
+    )
+    const nonByokFindings = otherFindings.filter(v => 
+      !(v.category === 'ai_pattern' && v.title.toLowerCase().includes('byok'))
+    )
+    
+    if (byokFindings.length > 0) {
+      // Check if we have both transient (low) and storage (high) BYOK findings
+      const transientByok = byokFindings.filter(v => 
+        v.severity === 'low' || v.severity === 'info'
+      )
+      const storageByok = byokFindings.filter(v => 
+        v.severity === 'high' || v.severity === 'medium'
+      )
+      
+      if (transientByok.length > 0 && storageByok.length > 0) {
+        // If we detected transient usage, prefer the lower severity
+        // The higher severity ones may be false positives
+        result.push(...transientByok)
+        // Mark high-severity BYOK for review
+        for (const vuln of storageByok) {
+          result.push({
+            ...vuln,
+            severity: 'low',
+            validationNotes: `${vuln.validationNotes || ''} (downgraded: transient BYOK usage detected in same file)`.trim(),
+          })
+        }
+      } else {
+        // Keep all BYOK findings as-is
+        result.push(...byokFindings)
+      }
+    }
+    
+    // Add non-BYOK other findings
+    result.push(...nonByokFindings)
+  }
+
+  return result
+}
+
+/**
+ * Sort vulnerabilities by severity (critical first)
+ */
+function sortBySeverity(vulnerabilities: Vulnerability[]): Vulnerability[] {
+  return [...vulnerabilities].sort((a, b) => {
+    const severityDiff = severityRank(b.severity) - severityRank(a.severity)
+    if (severityDiff !== 0) return severityDiff
+    
+    // Secondary sort by confidence
+    return confidenceRank(b.confidence) - confidenceRank(a.confidence)
+  })
+}
+
+function severityRank(severity: string): number {
+  const ranks: Record<string, number> = {
+    critical: 5,
+    high: 4,
+    medium: 3,
+    low: 2,
+    info: 1,
+  }
+  return ranks[severity] || 0
+}
+
+function confidenceRank(confidence: string): number {
+  const ranks: Record<string, number> = {
+    high: 3,
+    medium: 2,
+    low: 1,
+  }
+  return ranks[confidence] || 0
+}
+
+/**
+ * Compute severity counts from vulnerabilities
+ */
+function computeSeverityCounts(vulnerabilities: Vulnerability[]): SeverityCounts {
+  const counts: SeverityCounts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 }
+
+  for (const vuln of vulnerabilities) {
+    if (vuln.severity in counts) {
+      counts[vuln.severity]++
+    }
+  }
+
+  return counts
+}
+
+/**
+ * Compute category counts from vulnerabilities
+ */
+function computeCategoryCounts(vulnerabilities: Vulnerability[]): CategoryCounts {
+  const counts: CategoryCounts = {}
+  
+  for (const vuln of vulnerabilities) {
+    const category = vuln.category as VulnerabilityCategory
+    counts[category] = (counts[category] || 0) + 1
+  }
+  
+  return counts
+}
+
+/**
+ * Helper to compute counts from vulnerabilities (for backfilling legacy scans)
+ */
+export function computeIssueMixFromVulnerabilities(vulnerabilities: Vulnerability[]): {
+  severityCounts: SeverityCounts
+  categoryCounts: CategoryCounts
+  hasBlockingIssues: boolean
+} {
+  const severityCounts = computeSeverityCounts(vulnerabilities)
+  const categoryCounts = computeCategoryCounts(vulnerabilities)
+  const hasBlockingIssues = severityCounts.critical > 0 || severityCounts.high > 0
+  
+  return { severityCounts, categoryCounts, hasBlockingIssues }
+}
+
+// Re-export types and utilities
+export * from './types'
+export { runLayer1Scan } from './layer1'
+export { runLayer2Scan } from './layer2'
+export { runLayer3Scan } from './layer3'
+export { buildProjectContext, type ProjectContext } from './utils/project-context-builder'
+export { validateFindingsWithAI, type ValidationStats, type AIValidationResult } from './layer3/anthropic'