@oculum/scanner 1.0.0

package/src/utils/diff-parser.ts

@@ -0,0 +1,272 @@
+/**
+ * Git Diff Parser
+ * Parses unified diff format to extract changed line ranges
+ * Used for incremental scanning to only flag findings on changed lines
+ */
+
+/**
+ * A hunk represents a contiguous block of changes
+ */
+export interface DiffHunk {
+  /** Starting line in the old file */
+  oldStart: number
+  /** Number of lines in old file */
+  oldLines: number
+  /** Starting line in the new file */
+  newStart: number
+  /** Number of lines in new file */
+  newLines: number
+  /** Lines that were added (line numbers in new file) */
+  addedLines: number[]
+  /** Lines that were removed (line numbers in old file) */
+  removedLines: number[]
+  /** Lines that were modified (context around changes in new file) */
+  contextLines: number[]
+}
+
+/**
+ * Parsed file diff
+ */
+export interface FileDiff {
+  /** File path (after rename if applicable) */
+  path: string
+  /** Old file path (if renamed) */
+  oldPath?: string
+  /** Whether the file was added */
+  isNew: boolean
+  /** Whether the file was deleted */
+  isDeleted: boolean
+  /** Whether the file was renamed */
+  isRenamed: boolean
+  /** Hunks containing the actual changes */
+  hunks: DiffHunk[]
+  /** All changed line numbers in the new file */
+  changedLines: Set<number>
+  /** All lines near changes (within context window) */
+  affectedLines: Set<number>
+}
+
+/**
+ * Parse a unified diff output
+ *
+ * @param diffOutput - The raw git diff output
+ * @param contextWindow - Lines around changes to consider "affected" (default: 5)
+ * @returns Map of file path to FileDiff
+ */
+export function parseDiff(diffOutput: string, contextWindow: number = 5): Map<string, FileDiff> {
+  const files = new Map<string, FileDiff>()
+
+  if (!diffOutput || diffOutput.trim() === '') {
+    return files
+  }
+
+  // Split into file sections (each starts with "diff --git")
+  const fileSections = diffOutput.split(/^diff --git /gm).filter(s => s.trim())
+
+  for (const section of fileSections) {
+    const fileDiff = parseFileSection('diff --git ' + section, contextWindow)
+    if (fileDiff) {
+      files.set(fileDiff.path, fileDiff)
+    }
+  }
+
+  return files
+}
+
+/**
+ * Parse a single file's diff section
+ */
+function parseFileSection(section: string, contextWindow: number): FileDiff | null {
+  const lines = section.split('\n')
+
+  // Extract file paths from header
+  // Format: diff --git a/path/to/file b/path/to/file
+  const headerMatch = lines[0].match(/diff --git a\/(.+) b\/(.+)/)
+  if (!headerMatch) return null
+
+  const oldPath = headerMatch[1]
+  const newPath = headerMatch[2]
+
+  // Detect file status
+  let isNew = false
+  let isDeleted = false
+  let isRenamed = oldPath !== newPath
+
+  for (const line of lines.slice(0, 10)) {
+    if (line.startsWith('new file mode')) isNew = true
+    if (line.startsWith('deleted file mode')) isDeleted = true
+    if (line.startsWith('rename from')) isRenamed = true
+  }
+
+  // Parse hunks
+  const hunks: DiffHunk[] = []
+  const changedLines = new Set<number>()
+  const affectedLines = new Set<number>()
+
+  // Find hunk headers: @@ -oldStart,oldLines +newStart,newLines @@
+  const hunkRegex = /@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/g
+  let match: RegExpExecArray | null
+
+  const sectionContent = section
+
+  while ((match = hunkRegex.exec(sectionContent)) !== null) {
+    const oldStart = parseInt(match[1], 10)
+    const oldLines = parseInt(match[2] || '1', 10)
+    const newStart = parseInt(match[3], 10)
+    const newLines = parseInt(match[4] || '1', 10)
+
+    // Find the content of this hunk (until next @@ or end)
+    const hunkStartIndex = match.index + match[0].length
+    const nextHunkMatch = /@@ -\d+/.exec(sectionContent.slice(hunkStartIndex + 1))
+    const hunkEndIndex = nextHunkMatch
+      ? hunkStartIndex + 1 + nextHunkMatch.index
+      : sectionContent.length
+
+    const hunkContent = sectionContent.slice(hunkStartIndex, hunkEndIndex)
+    const hunkLines = hunkContent.split('\n')
+
+    const addedLines: number[] = []
+    const removedLines: number[] = []
+    const contextLines: number[] = []
+
+    let newLineNum = newStart
+    let oldLineNum = oldStart
+
+    for (const line of hunkLines) {
+      if (line.startsWith('+') && !line.startsWith('+++')) {
+        // Added line
+        addedLines.push(newLineNum)
+        changedLines.add(newLineNum)
+        newLineNum++
+      } else if (line.startsWith('-') && !line.startsWith('---')) {
+        // Removed line
+        removedLines.push(oldLineNum)
+        oldLineNum++
+      } else if (line.startsWith(' ') || line === '') {
+        // Context line
+        contextLines.push(newLineNum)
+        newLineNum++
+        oldLineNum++
+      }
+    }
+
+    hunks.push({
+      oldStart,
+      oldLines,
+      newStart,
+      newLines,
+      addedLines,
+      removedLines,
+      contextLines,
+    })
+  }
+
+  // Calculate affected lines (changed lines + context window)
+  for (const line of changedLines) {
+    for (let i = Math.max(1, line - contextWindow); i <= line + contextWindow; i++) {
+      affectedLines.add(i)
+    }
+  }
+
+  return {
+    path: newPath,
+    oldPath: isRenamed ? oldPath : undefined,
+    isNew,
+    isDeleted,
+    isRenamed,
+    hunks,
+    changedLines,
+    affectedLines,
+  }
+}
+
+/**
+ * Parse a simple list of changed file paths
+ * Used when full diff isn't available (e.g., GitHub API file list)
+ */
+export function parseChangedFileList(files: string[]): Map<string, FileDiff> {
+  const result = new Map<string, FileDiff>()
+
+  for (const path of files) {
+    result.set(path, {
+      path,
+      isNew: false,
+      isDeleted: false,
+      isRenamed: false,
+      hunks: [],
+      // Without diff content, consider all lines as changed
+      changedLines: new Set(),
+      affectedLines: new Set(),
+    })
+  }
+
+  return result
+}
+
+/**
+ * Check if a finding is on a changed line
+ */
+export function isOnChangedLine(
+  filePath: string,
+  lineNumber: number,
+  diffs: Map<string, FileDiff>
+): boolean {
+  const fileDiff = diffs.get(filePath)
+  if (!fileDiff) return false
+
+  // If no specific changed lines (file list only), consider all findings relevant
+  if (fileDiff.changedLines.size === 0) return true
+
+  return fileDiff.changedLines.has(lineNumber)
+}
+
+/**
+ * Check if a finding is near a changed line (within context window)
+ */
+export function isNearChangedLine(
+  filePath: string,
+  lineNumber: number,
+  diffs: Map<string, FileDiff>
+): boolean {
+  const fileDiff = diffs.get(filePath)
+  if (!fileDiff) return false
+
+  // If no specific affected lines, consider all findings relevant
+  if (fileDiff.affectedLines.size === 0) return true
+
+  return fileDiff.affectedLines.has(lineNumber)
+}
+
+/**
+ * Get all changed file paths from diffs
+ */
+export function getChangedFilePaths(diffs: Map<string, FileDiff>): string[] {
+  return Array.from(diffs.keys()).filter(path => {
+    const diff = diffs.get(path)
+    return diff && !diff.isDeleted
+  })
+}
+
+/**
+ * Filter vulnerabilities to only those on/near changed lines
+ */
+export function filterToChangedLines<T extends { filePath: string; lineNumber: number }>(
+  findings: T[],
+  diffs: Map<string, FileDiff>,
+  options: { strictMode?: boolean } = {}
+): T[] {
+  const { strictMode = false } = options
+
+  return findings.filter(finding => {
+    // If file not in diff, it wasn't changed - exclude
+    if (!diffs.has(finding.filePath)) return false
+
+    // In strict mode, only include findings on exactly changed lines
+    if (strictMode) {
+      return isOnChangedLine(finding.filePath, finding.lineNumber, diffs)
+    }
+
+    // In normal mode, include findings near changed lines
+    return isNearChangedLine(finding.filePath, finding.lineNumber, diffs)
+  })
+}

package/src/utils/imported-auth-detector.ts

@@ -0,0 +1,320 @@
+/**
+ * Imported Auth Detector
+ *
+ * Detects auth middleware/helpers imported from other files to avoid
+ * false positives on routes that are actually protected via imports.
+ *
+ * Example: A route file that does `import { authMiddleware } from '@/lib/auth'`
+ * and wraps handlers with it should not be flagged as "missing auth".
+ */
+
+import type { ScanFile } from '../types'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ImportedAuthInfo {
+  importPath: string           // '@/lib/auth' or './middleware'
+  importedNames: string[]      // ['authMiddleware', 'requireAuth']
+  isAuthRelated: boolean       // Based on name patterns
+}
+
+export interface FileAuthImports {
+  filePath: string
+  imports: ImportedAuthInfo[]
+  usesImportedAuth: boolean    // Does the file actually use imported auth?
+}
+
+// ============================================================================
+// Patterns
+// ============================================================================
+
+/**
+ * Patterns that indicate auth-related imports by name
+ */
+const AUTH_NAME_PATTERNS = [
+  /auth/i,
+  /middleware/i,
+  /protect/i,
+  /guard/i,
+  /session/i,
+  /verify/i,
+  /secure/i,
+  /jwt/i,
+  /token/i,
+]
+
+/**
+ * Specific auth import names commonly used
+ */
+const KNOWN_AUTH_IMPORTS = new Set([
+  // Next.js / NextAuth
+  'auth',
+  'getServerSession',
+  'getSession',
+  'withAuth',
+  'getToken',
+  'NextAuth',
+  'NextAuthOptions',
+
+  // Clerk
+  'auth',
+  'currentUser',
+  'clerkMiddleware',
+  'getAuth',
+  'SignedIn',
+  'SignedOut',
+
+  // Auth0
+  'withPageAuthRequired',
+  'withApiAuthRequired',
+  'getSession',
+  'getAccessToken',
+
+  // Custom auth patterns
+  'authMiddleware',
+  'requireAuth',
+  'requireAuthentication',
+  'checkAuth',
+  'verifyAuth',
+  'protectRoute',
+  'withAuthentication',
+  'authenticated',
+  'getCurrentUser',
+  'getCurrentUserId',
+  'getUser',
+  'getUserId',
+])
+
+/**
+ * Patterns indicating auth-related import paths
+ */
+const AUTH_PATH_PATTERNS = [
+  /\/auth\//i,
+  /\/middleware/i,
+  /\/lib\/auth/i,
+  /\/utils\/auth/i,
+  /\/helpers\/auth/i,
+  /next-auth/i,
+  /@clerk/i,
+  /@auth0/i,
+  /lucia/i,
+]
+
+// ============================================================================
+// Import Extraction
+// ============================================================================
+
+/**
+ * Extract all imports from a file's content
+ */
+export function extractImports(content: string): ImportedAuthInfo[] {
+  const imports: ImportedAuthInfo[] = []
+
+  // ES6 named imports: import { x, y } from 'path'
+  const es6NamedPattern = /import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/g
+  let match
+
+  while ((match = es6NamedPattern.exec(content)) !== null) {
+    const names = match[1]
+      .split(',')
+      .map(n => n.trim().split(/\s+as\s+/)[0].trim())  // Handle 'x as y'
+      .filter(n => n.length > 0)
+    const importPath = match[2]
+
+    const isAuthRelated = isAuthRelatedImport(names, importPath)
+
+    imports.push({
+      importPath,
+      importedNames: names,
+      isAuthRelated,
+    })
+  }
+
+  // ES6 default imports: import x from 'path'
+  const defaultPattern = /import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g
+  while ((match = defaultPattern.exec(content)) !== null) {
+    const name = match[1]
+    const importPath = match[2]
+
+    // Skip if already captured as named import
+    if (imports.some(imp => imp.importPath === importPath)) continue
+
+    const isAuthRelated = isAuthRelatedImport([name], importPath)
+
+    imports.push({
+      importPath,
+      importedNames: [name],
+      isAuthRelated,
+    })
+  }
+
+  // CommonJS require: const { x } = require('path')
+  const requireDestructurePattern = /(?:const|let|var)\s+\{([^}]+)\}\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+  while ((match = requireDestructurePattern.exec(content)) !== null) {
+    const names = match[1]
+      .split(',')
+      .map(n => n.trim().split(/\s*:\s*/)[0].trim())  // Handle 'x: y' renaming
+      .filter(n => n.length > 0)
+    const importPath = match[2]
+
+    const isAuthRelated = isAuthRelatedImport(names, importPath)
+
+    imports.push({
+      importPath,
+      importedNames: names,
+      isAuthRelated,
+    })
+  }
+
+  // CommonJS require: const x = require('path')
+  const requireDefaultPattern = /(?:const|let|var)\s+(\w+)\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+  while ((match = requireDefaultPattern.exec(content)) !== null) {
+    const name = match[1]
+    const importPath = match[2]
+
+    // Skip if already captured
+    if (imports.some(imp => imp.importPath === importPath)) continue
+
+    const isAuthRelated = isAuthRelatedImport([name], importPath)
+
+    imports.push({
+      importPath,
+      importedNames: [name],
+      isAuthRelated,
+    })
+  }
+
+  return imports
+}
+
+/**
+ * Check if an import is auth-related based on names and path
+ */
+function isAuthRelatedImport(names: string[], importPath: string): boolean {
+  // Check if path is auth-related
+  if (AUTH_PATH_PATTERNS.some(p => p.test(importPath))) {
+    return true
+  }
+
+  // Check if any imported name is auth-related
+  for (const name of names) {
+    // Known auth imports
+    if (KNOWN_AUTH_IMPORTS.has(name)) {
+      return true
+    }
+
+    // Pattern-based detection
+    if (AUTH_NAME_PATTERNS.some(p => p.test(name))) {
+      return true
+    }
+  }
+
+  return false
+}
+
+// ============================================================================
+// Auth Usage Detection
+// ============================================================================
+
+/**
+ * Check if imported auth is actually used to protect routes/handlers
+ */
+export function detectImportedAuthUsage(
+  content: string,
+  authImports: ImportedAuthInfo[]
+): boolean {
+  if (authImports.length === 0) return false
+
+  const authNames = authImports.flatMap(imp => imp.importedNames)
+
+  for (const name of authNames) {
+    // Pattern 1: Handler wrapping - export const GET = authMiddleware(...)
+    const wrapperPattern = new RegExp(
+      `(?:export\\s+(?:const|function)\\s+(?:GET|POST|PUT|PATCH|DELETE|handler)\\s*=\\s*${escapeRegex(name)}\\s*\\()` +
+      `|(?:${escapeRegex(name)}\\s*\\(\\s*(?:async\\s+)?(?:function|\\())`
+    )
+    if (wrapperPattern.test(content)) {
+      return true
+    }
+
+    // Pattern 2: Middleware chain - app.use(authMiddleware)
+    const middlewareChainPattern = new RegExp(
+      `\\.(?:use|all|get|post|put|patch|delete)\\s*\\([^)]*${escapeRegex(name)}`
+    )
+    if (middlewareChainPattern.test(content)) {
+      return true
+    }
+
+    // Pattern 3: Express/Fastify route with middleware - router.get('/', requireAuth, handler)
+    const routeMiddlewarePattern = new RegExp(
+      `\\.(?:get|post|put|patch|delete)\\s*\\([^,]+,\\s*${escapeRegex(name)}`
+    )
+    if (routeMiddlewarePattern.test(content)) {
+      return true
+    }
+
+    // Pattern 4: HOC pattern - withAuth(Component)
+    const hocPattern = new RegExp(`${escapeRegex(name)}\\s*\\(\\s*\\w+\\s*\\)`)
+    if (hocPattern.test(content)) {
+      return true
+    }
+
+    // Pattern 5: Auth function call at top of handler - const session = await auth()
+    const authCallPattern = new RegExp(
+      `(?:await\\s+)?${escapeRegex(name)}\\s*\\(\\s*\\)` +
+      `|${escapeRegex(name)}\\s*\\(\\s*(?:req|request|ctx|context)\\s*[,)]`
+    )
+    if (authCallPattern.test(content)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+// ============================================================================
+// Registry Builder
+// ============================================================================
+
+/**
+ * Build a registry of files and their auth imports
+ */
+export function buildFileAuthImports(files: ScanFile[]): Map<string, FileAuthImports> {
+  const registry = new Map<string, FileAuthImports>()
+
+  for (const file of files) {
+    const allImports = extractImports(file.content)
+    const authImports = allImports.filter(imp => imp.isAuthRelated)
+
+    const usesImportedAuth =
+      authImports.length > 0 &&
+      detectImportedAuthUsage(file.content, authImports)
+
+    registry.set(file.path, {
+      filePath: file.path,
+      imports: authImports,
+      usesImportedAuth,
+    })
+  }
+
+  return registry
+}
+
+/**
+ * Check if a specific file uses imported auth protection
+ */
+export function fileUsesImportedAuth(
+  filePath: string,
+  registry: Map<string, FileAuthImports>
+): boolean {
+  return registry.get(filePath)?.usesImportedAuth ?? false
+}