@oculum/scanner 1.0.0

package/src/utils/middleware-detector.ts

@@ -0,0 +1,333 @@
+/**
+ * Middleware Auth Detection
+ * Detects global authentication middleware (Next.js, Express, etc.)
+ * and determines which routes are protected
+ */
+
+import type { ScanFile } from '../types'
+
+/**
+ * Configuration describing detected auth middleware
+ */
+export interface MiddlewareAuthConfig {
+  /** Whether auth middleware was detected */
+  hasAuthMiddleware: boolean
+  /** The type of auth detected */
+  authType?: 'clerk' | 'nextauth' | 'auth0' | 'custom' | 'unknown'
+  /** File path where middleware was found */
+  middlewareFile?: string
+  /** Protected path patterns (glob-like) */
+  protectedPaths: string[]
+  /** Public/excluded path patterns */
+  publicPaths: string[]
+  /** Raw matcher patterns found */
+  matchers: string[]
+  /** Additional context about the auth setup */
+  context: {
+    usesAuthProtect: boolean
+    usesGetToken: boolean
+    usesSession: boolean
+    hasPublicRoutes: boolean
+  }
+}
+
+/**
+ * Detect global auth middleware from scanned files
+ * Looks for Next.js middleware.ts, Express auth patterns, etc.
+ */
+export function detectGlobalAuthMiddleware(files: ScanFile[]): MiddlewareAuthConfig {
+  const result: MiddlewareAuthConfig = {
+    hasAuthMiddleware: false,
+    protectedPaths: [],
+    publicPaths: [],
+    matchers: [],
+    context: {
+      usesAuthProtect: false,
+      usesGetToken: false,
+      usesSession: false,
+      hasPublicRoutes: false,
+    },
+  }
+
+  // Find middleware files
+  const middlewareFile = files.find(f =>
+    /^(src\/)?middleware\.(ts|js)$/.test(f.path) ||
+    f.path.endsWith('/middleware.ts') ||
+    f.path.endsWith('/middleware.js')
+  )
+
+  if (!middlewareFile) {
+    return result
+  }
+
+  result.middlewareFile = middlewareFile.path
+  const content = middlewareFile.content
+
+  // Detect auth provider type
+  result.authType = detectAuthType(content)
+
+  if (result.authType) {
+    result.hasAuthMiddleware = true
+  }
+
+  // Extract protected path matchers
+  const { protectedPaths, publicPaths, matchers } = extractPathMatchers(content)
+  result.protectedPaths = protectedPaths
+  result.publicPaths = publicPaths
+  result.matchers = matchers
+
+  // Detect specific auth patterns
+  result.context.usesAuthProtect = /auth\.protect\(\)|auth\(\)\.protect\(\)|requireAuth\(\)/i.test(content)
+  result.context.usesGetToken = /getToken\(|getAuth\(/i.test(content)
+  result.context.usesSession = /getSession\(|getServerSession\(/i.test(content)
+  result.context.hasPublicRoutes = /isPublicRoute|publicRoutes|ignoredRoutes|excludedPaths/i.test(content)
+
+  // If we found auth imports but no explicit matchers, assume /api/** is protected
+  if (result.hasAuthMiddleware && result.protectedPaths.length === 0) {
+    // Check if middleware runs on all routes or has default API protection
+    if (!result.context.hasPublicRoutes || /\/api/i.test(content)) {
+      result.protectedPaths.push('/api/**')
+    }
+  }
+
+  return result
+}
+
+/**
+ * Detect which auth provider/library is being used
+ */
+function detectAuthType(content: string): MiddlewareAuthConfig['authType'] {
+  // Clerk patterns
+  if (/clerkMiddleware|@clerk\/nextjs|clerkClient|auth\(\)\.protect/i.test(content)) {
+    return 'clerk'
+  }
+
+  // NextAuth patterns
+  if (/next-auth|NextAuth|getServerSession|withAuth\(/i.test(content)) {
+    return 'nextauth'
+  }
+
+  // Auth0 patterns
+  if (/@auth0\/nextjs|withPageAuthRequired|withApiAuthRequired/i.test(content)) {
+    return 'auth0'
+  }
+
+  // Generic auth middleware patterns
+  if (/authMiddleware|requireAuth|verifyToken|checkAuth|isAuthenticated/i.test(content)) {
+    return 'custom'
+  }
+
+  // Check for common auth imports/usage that suggest middleware is doing auth
+  if (/authorization|bearer|jwt|session\.user|getToken/i.test(content)) {
+    return 'unknown'
+  }
+
+  return undefined
+}
+
+/**
+ * Extract path matchers from middleware config
+ */
+function extractPathMatchers(content: string): {
+  protectedPaths: string[]
+  publicPaths: string[]
+  matchers: string[]
+} {
+  const protectedPaths: string[] = []
+  const publicPaths: string[] = []
+  const matchers: string[] = []
+
+  // Next.js config.matcher pattern
+  // export const config = { matcher: [...] }
+  const matcherArrayMatch = content.match(/config\s*=\s*\{[^}]*matcher\s*:\s*\[([\s\S]*?)\]/m)
+  if (matcherArrayMatch) {
+    const matcherContent = matcherArrayMatch[1]
+    // Extract string patterns from the array
+    const patterns = matcherContent.match(/['"`]([^'"`]+)['"`]/g) || []
+    for (const p of patterns) {
+      const path = p.replace(/['"`]/g, '')
+      matchers.push(path)
+      // Classify as protected or public based on common patterns
+      if (path.includes('/api') || path.includes('/(protected)') || path.includes('/dashboard')) {
+        protectedPaths.push(path)
+      }
+    }
+  }
+
+  // Single matcher pattern
+  // export const config = { matcher: '/api/:path*' }
+  const singleMatcherMatch = content.match(/config\s*=\s*\{[^}]*matcher\s*:\s*['"`]([^'"`]+)['"`]/m)
+  if (singleMatcherMatch) {
+    const path = singleMatcherMatch[1]
+    matchers.push(path)
+    if (path.includes('/api')) {
+      protectedPaths.push(path)
+    }
+  }
+
+  // Clerk-specific: createRouteMatcher for public routes
+  // const isPublicRoute = createRouteMatcher(['/sign-in', '/sign-up', ...])
+  const publicRouteMatch = content.match(/createRouteMatcher\s*\(\s*\[([\s\S]*?)\]/m)
+  if (publicRouteMatch) {
+    const routeContent = publicRouteMatch[1]
+    const patterns = routeContent.match(/['"`]([^'"`]+)['"`]/g) || []
+    for (const p of patterns) {
+      const path = p.replace(/['"`]/g, '')
+      publicPaths.push(path)
+    }
+  }
+
+  // Look for publicRoutes/ignoredRoutes arrays
+  const publicRoutesMatch = content.match(/(publicRoutes|ignoredRoutes|excludedPaths)\s*[=:]\s*\[([\s\S]*?)\]/m)
+  if (publicRoutesMatch) {
+    const routeContent = publicRoutesMatch[2]
+    const patterns = routeContent.match(/['"`]([^'"`]+)['"`]/g) || []
+    for (const p of patterns) {
+      const path = p.replace(/['"`]/g, '')
+      publicPaths.push(path)
+    }
+  }
+
+  // If we found public paths but no explicit protected paths,
+  // assume everything else under /api is protected
+  if (publicPaths.length > 0 && protectedPaths.length === 0) {
+    protectedPaths.push('/api/**')
+  }
+
+  return { protectedPaths, publicPaths, matchers }
+}
+
+/**
+ * Check if a given route path is protected by the middleware
+ */
+export function isRouteProtectedByMiddleware(
+  routePath: string,
+  config: MiddlewareAuthConfig
+): { isProtected: boolean; reason: string } {
+  if (!config.hasAuthMiddleware) {
+    return { isProtected: false, reason: 'No auth middleware detected' }
+  }
+
+  // Normalize path
+  const normalizedPath = routePath.startsWith('/') ? routePath : `/${routePath}`
+
+  // Check if explicitly public
+  for (const publicPath of config.publicPaths) {
+    if (matchPath(normalizedPath, publicPath)) {
+      return { isProtected: false, reason: `Matches public route pattern: ${publicPath}` }
+    }
+  }
+
+  // Check if explicitly protected
+  for (const protectedPath of config.protectedPaths) {
+    if (matchPath(normalizedPath, protectedPath)) {
+      return {
+        isProtected: true,
+        reason: `Protected by ${config.authType || 'auth'} middleware (matches: ${protectedPath})`,
+      }
+    }
+  }
+
+  // Check matchers
+  for (const matcher of config.matchers) {
+    if (matchPath(normalizedPath, matcher)) {
+      return {
+        isProtected: true,
+        reason: `Protected by middleware matcher: ${matcher}`,
+      }
+    }
+  }
+
+  // Default: if we have auth middleware and no explicit public match,
+  // consider API routes as protected
+  if (normalizedPath.startsWith('/api/')) {
+    return {
+      isProtected: true,
+      reason: `API route likely protected by ${config.authType || 'auth'} middleware`,
+    }
+  }
+
+  return { isProtected: false, reason: 'Route not covered by middleware matchers' }
+}
+
+/**
+ * Extract route path from a file path (e.g., app/api/users/route.ts -> /api/users)
+ */
+export function getRoutePathFromFile(filePath: string): string | null {
+  // Next.js App Router: app/api/users/route.ts -> /api/users
+  const appRouterMatch = filePath.match(/app(\/.*?)\/route\.(ts|js)$/i)
+  if (appRouterMatch) {
+    return appRouterMatch[1]
+  }
+
+  // Next.js Pages Router: pages/api/users.ts -> /api/users
+  const pagesRouterMatch = filePath.match(/pages(\/api\/.*?)\.(ts|js)$/i)
+  if (pagesRouterMatch) {
+    return pagesRouterMatch[1]
+  }
+
+  // Express-style routes: routes/users.ts (harder to determine path)
+  // Return null for now - would need more context
+  return null
+}
+
+/**
+ * Simple glob-like path matching
+ * Supports: ** (any path), * (single segment), :param (path params)
+ */
+function matchPath(actualPath: string, pattern: string): boolean {
+  // Normalize
+  const normActual = actualPath.replace(/\/+/g, '/')
+  let normPattern = pattern.replace(/\/+/g, '/')
+
+  // Handle Next.js :path* patterns
+  normPattern = normPattern
+    .replace(/:path\*/g, '**')
+    .replace(/:\w+/g, '[^/]+')
+
+  // Convert glob to regex
+  const regexPattern = normPattern
+    .replace(/\*\*/g, '<<<DOUBLESTAR>>>')
+    .replace(/\*/g, '[^/]*')
+    .replace(/<<<DOUBLESTAR>>>/g, '.*')
+    .replace(/\//g, '\\/')
+
+  const regex = new RegExp(`^${regexPattern}$`)
+  return regex.test(normActual)
+}
+
+/**
+ * Get user-scoping patterns from file content
+ * Detects patterns like: user_id, userId, session.user.id
+ */
+export function detectUserScopingPatterns(content: string): {
+  hasUserScoping: boolean
+  patterns: string[]
+} {
+  const patterns: string[] = []
+
+  // Common user ID patterns in queries/operations
+  const userIdPatterns = [
+    /\.eq\s*\(\s*['"`]user_id['"`]/i,        // Supabase .eq('user_id', ...)
+    /\.filter\s*\(\s*user_id\s*=/i,           // Django-style
+    /where\s*\(\s*['"`]?user_id['"`]?\s*=/i,  // SQL-like
+    /userId\s*[=:]/i,                          // Generic userId
+    /user\.id\s*[=:]/i,                        // user.id
+    /session\.user\.id/i,                      // Next.js session
+    /req\.user\.id/i,                          // Express req.user
+    /getCurrentUserId\s*\(/i,                  // Custom helper
+    /getAuthUser\s*\(/i,                       // Auth helper
+    /auth\(\).*\.userId/i,                     // Clerk auth().userId
+  ]
+
+  for (const pattern of userIdPatterns) {
+    if (pattern.test(content)) {
+      patterns.push(pattern.source)
+    }
+  }
+
+  return {
+    hasUserScoping: patterns.length > 0,
+    patterns,
+  }
+}

package/src/utils/oauth-flow-detector.ts

@@ -0,0 +1,246 @@
+/**
+ * OAuth Flow Detector
+ * Detects OAuth state generation and validation across multiple files
+ * to prevent false positives when state is implemented correctly but split across files.
+ */
+
+import type { ScanFile } from '../types'
+
+export interface OAuthFlowContext {
+  /** Whether state generation is detected in any file */
+  hasStateGeneration: boolean
+  /** File where state is generated */
+  stateGenerationFile?: string
+  /** Line number where state is generated */
+  stateGenerationLine?: number
+  /** Whether state validation is detected in any file */
+  hasStateValidation: boolean
+  /** File where state is validated */
+  stateValidationFile?: string
+  /** Line number where state is validated */
+  stateValidationLine?: number
+  /** Whether PKCE code_verifier is used */
+  hasCodeVerifier: boolean
+  /** File where code_verifier is generated */
+  codeVerifierFile?: string
+  /** Detected OAuth flow type */
+  flowType: 'authorization_code' | 'client_credentials' | 'implicit' | 'pkce' | 'unknown'
+  /** OAuth providers detected */
+  providers: string[]
+}
+
+/**
+ * Patterns that indicate OAuth state generation
+ */
+const STATE_GENERATION_PATTERNS = [
+  /generateState\s*\(/i,
+  /crypto\.randomBytes.*state/i,
+  /state\s*=\s*.*random/i,
+  /setCookie.*oauth.*state/i,
+  /cookies?\(\s*\)\.set\s*\([^)]*state/i,
+  /state\s*=\s*generateRandomString/i,
+  /state\s*=\s*nanoid\s*\(/i,
+  /state\s*=\s*uuid/i,
+  /state\s*=\s*crypto\.randomUUID/i,
+  /createState\s*\(/i,
+  /oauth.*state.*=.*crypto/i,
+  /\.setState\s*\(/i,
+  /stateParam\s*=\s*/i,
+  /generateOAuthState/i,
+]
+
+/**
+ * Patterns that indicate OAuth state validation
+ */
+const STATE_VALIDATION_PATTERNS = [
+  /state\s*!==\s*storedState/i,
+  /storedState.*!==.*state/i,
+  /validateState\s*\(/i,
+  /getCookie.*oauth.*state/i,
+  /cookies?\(\s*\)\.get\s*\([^)]*state/i,
+  /verifyState\s*\(/i,
+  /checkState\s*\(/i,
+  /state\s*===\s*savedState/i,
+  /savedState\s*===\s*state/i,
+  /if\s*\(\s*!?\s*state\s*\)/i,
+  /state\s*!==\s*.*\.get\s*\(/i,
+  /\.getState\s*\(/i,
+  /compareState\s*\(/i,
+]
+
+/**
+ * Patterns that indicate PKCE code_verifier usage
+ */
+const CODE_VERIFIER_PATTERNS = [
+  /code_verifier/i,
+  /codeVerifier/i,
+  /generateCodeVerifier/i,
+  /createCodeVerifier/i,
+  /pkce/i,
+  /code_challenge/i,
+  /codeChallenge/i,
+]
+
+/**
+ * Patterns that indicate client_credentials flow (no state needed)
+ */
+const CLIENT_CREDENTIALS_PATTERNS = [
+  /grant_type.*client_credentials/i,
+  /client_credentials.*grant/i,
+  /\.clientCredentials\s*\(/i,
+  /getClientCredentialsToken/i,
+  /machine-to-machine/i,
+  /m2m.*auth/i,
+]
+
+/**
+ * Known OAuth provider patterns
+ */
+const OAUTH_PROVIDER_PATTERNS: Record<string, RegExp[]> = {
+  google: [/googleapis\.com\/oauth/i, /accounts\.google\.com/i, /google.*oauth/i],
+  github: [/github\.com\/login\/oauth/i, /api\.github\.com.*oauth/i],
+  microsoft: [/login\.microsoftonline\.com/i, /microsoft.*oauth/i, /azure.*oauth/i],
+  facebook: [/facebook\.com\/.*oauth/i, /graph\.facebook\.com/i],
+  twitter: [/twitter\.com\/oauth/i, /api\.twitter\.com.*oauth/i],
+  apple: [/appleid\.apple\.com/i, /apple.*oauth/i],
+  auth0: [/auth0\.com/i, /\.auth0\./i],
+  okta: [/okta\.com/i, /\.okta\./i],
+  clerk: [/clerk\.dev/i, /clerk\.com/i, /@clerk\//i],
+  nextauth: [/next-auth/i, /nextauth/i, /authjs/i],
+  lucia: [/lucia-auth/i, /lucia\.ts/i],
+  arctic: [/arctic/i, /oslo\/oauth/i],
+}
+
+/**
+ * Detect OAuth flow patterns across multiple files
+ */
+export function detectOAuthFlow(files: ScanFile[]): OAuthFlowContext {
+  const context: OAuthFlowContext = {
+    hasStateGeneration: false,
+    hasStateValidation: false,
+    hasCodeVerifier: false,
+    flowType: 'unknown',
+    providers: [],
+  }
+
+  const detectedProviders = new Set<string>()
+
+  for (const file of files) {
+    const content = file.content
+    const lines = content.split('\n')
+
+    // Check for state generation
+    if (!context.hasStateGeneration) {
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]
+        if (STATE_GENERATION_PATTERNS.some(p => p.test(line))) {
+          context.hasStateGeneration = true
+          context.stateGenerationFile = file.path
+          context.stateGenerationLine = i + 1
+          break
+        }
+      }
+    }
+
+    // Check for state validation
+    if (!context.hasStateValidation) {
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]
+        if (STATE_VALIDATION_PATTERNS.some(p => p.test(line))) {
+          context.hasStateValidation = true
+          context.stateValidationFile = file.path
+          context.stateValidationLine = i + 1
+          break
+        }
+      }
+    }
+
+    // Check for PKCE
+    if (!context.hasCodeVerifier) {
+      if (CODE_VERIFIER_PATTERNS.some(p => p.test(content))) {
+        context.hasCodeVerifier = true
+        context.codeVerifierFile = file.path
+      }
+    }
+
+    // Check for client_credentials flow
+    if (context.flowType === 'unknown') {
+      if (CLIENT_CREDENTIALS_PATTERNS.some(p => p.test(content))) {
+        context.flowType = 'client_credentials'
+      }
+    }
+
+    // Detect OAuth providers
+    for (const [provider, patterns] of Object.entries(OAUTH_PROVIDER_PATTERNS)) {
+      if (patterns.some(p => p.test(content))) {
+        detectedProviders.add(provider)
+      }
+    }
+  }
+
+  // Determine flow type
+  if (context.flowType === 'unknown') {
+    if (context.hasCodeVerifier) {
+      context.flowType = 'pkce'
+    } else if (context.hasStateGeneration || context.hasStateValidation) {
+      context.flowType = 'authorization_code'
+    }
+  }
+
+  context.providers = Array.from(detectedProviders)
+
+  return context
+}
+
+/**
+ * Check if OAuth state is properly implemented across files
+ */
+export function isOAuthStateImplemented(context: OAuthFlowContext): boolean {
+  // client_credentials flow doesn't need state
+  if (context.flowType === 'client_credentials') {
+    return true
+  }
+
+  // PKCE flow with code_verifier is secure even without traditional state
+  if (context.hasCodeVerifier) {
+    return true
+  }
+
+  // Both generation and validation must be present
+  return context.hasStateGeneration && context.hasStateValidation
+}
+
+/**
+ * Get a summary of the OAuth flow for logging/context
+ */
+export function getOAuthFlowSummary(context: OAuthFlowContext): string {
+  const parts: string[] = []
+
+  if (context.flowType !== 'unknown') {
+    parts.push(`Flow: ${context.flowType}`)
+  }
+
+  if (context.providers.length > 0) {
+    parts.push(`Providers: ${context.providers.join(', ')}`)
+  }
+
+  if (context.hasStateGeneration) {
+    parts.push(`State generated in: ${context.stateGenerationFile}`)
+  }
+
+  if (context.hasStateValidation) {
+    parts.push(`State validated in: ${context.stateValidationFile}`)
+  }
+
+  if (context.hasCodeVerifier) {
+    parts.push(`PKCE enabled (${context.codeVerifierFile})`)
+  }
+
+  if (isOAuthStateImplemented(context)) {
+    parts.push('✓ OAuth state properly implemented')
+  } else if (context.hasStateGeneration || context.hasStateValidation) {
+    parts.push('⚠ Partial OAuth state implementation detected')
+  }
+
+  return parts.join('; ')
+}