@oculum/scanner 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Scanner Types and Interfaces
+ * Defines the core data structures for the security scanning engine
+ */
+export type VulnerabilitySeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+export type VulnerabilityCategory = 'hardcoded_secret' | 'high_entropy_string' | 'sensitive_variable' | 'security_bypass' | 'dangerous_function' | 'sql_injection' | 'xss' | 'command_injection' | 'insecure_config' | 'missing_auth' | 'suspicious_package' | 'cors_misconfiguration' | 'root_container' | 'dangerous_file' | 'ai_pattern' | 'sensitive_url' | 'weak_crypto' | 'data_exposure' | 'ai_prompt_injection' | 'ai_unsafe_execution' | 'ai_overpermissive_tool' | 'ai_rag_exfiltration' | 'ai_endpoint_unprotected' | 'ai_schema_mismatch';
+export type ValidationStatus = 'confirmed' | 'downgraded' | 'dismissed' | 'not_validated';
+export interface Vulnerability {
+    id: string;
+    filePath: string;
+    lineNumber: number;
+    lineContent: string;
+    severity: VulnerabilitySeverity;
+    category: VulnerabilityCategory;
+    title: string;
+    description: string;
+    suggestedFix?: string;
+    confidence: 'high' | 'medium' | 'low';
+    layer: 1 | 2 | 3;
+    requiresAIValidation?: boolean;
+    validatedByAI?: boolean;
+    validationStatus?: ValidationStatus;
+    validationNotes?: string;
+    originalSeverity?: VulnerabilitySeverity;
+}
+export interface ScanFile {
+    path: string;
+    content: string;
+    language: string;
+    size: number;
+}
+export interface SeverityCounts {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    info: number;
+}
+export type CategoryCounts = Partial<Record<VulnerabilityCategory, number>>;
+export interface ScanResult {
+    repoName: string;
+    repoUrl: string;
+    branch: string;
+    filesScanned: number;
+    filesSkipped: number;
+    vulnerabilities: Vulnerability[];
+    severityCounts: SeverityCounts;
+    categoryCounts: CategoryCounts;
+    hasBlockingIssues: boolean;
+    scanDuration: number;
+    timestamp: string;
+    validationStats?: {
+        totalFindings: number;
+        validatedFindings: number;
+        confirmedFindings: number;
+        dismissedFindings: number;
+        downgradedFindings: number;
+        autoDismissedFindings: number;
+        estimatedInputTokens: number;
+        estimatedOutputTokens: number;
+        estimatedCost: number;
+        apiCalls: number;
+        cacheCreationTokens: number;
+        cacheReadTokens: number;
+        cacheHitRate: number;
+    };
+}
+export interface ScanProgress {
+    status: 'fetching' | 'scanning_layer1' | 'scanning_layer2' | 'scanning_layer3' | 'complete' | 'failed';
+    currentFile?: string;
+    filesProcessed: number;
+    totalFiles: number;
+    vulnerabilitiesFound: number;
+}
+export interface SecretPattern {
+    name: string;
+    pattern: RegExp;
+    severity: VulnerabilitySeverity;
+    description: string;
+}
+export interface ConfigRule {
+    name: string;
+    filePatterns: string[];
+    check: (content: string, filePath: string) => ConfigViolation[];
+}
+export interface ConfigViolation {
+    line: number;
+    lineContent: string;
+    message: string;
+    severity: VulnerabilitySeverity;
+}
+export interface SensitiveVariablePattern {
+    pattern: RegExp;
+    severity: VulnerabilitySeverity;
+    description: string;
+}
+export interface AIAnalysisRequest {
+    filePath: string;
+    content: string;
+    context: string;
+}
+export interface AIFinding {
+    lineNumber: number;
+    lineContent: string;
+    severity: VulnerabilitySeverity;
+    category: VulnerabilityCategory;
+    title: string;
+    description: string;
+    suggestedFix: string;
+}
+export declare const SCANNABLE_EXTENSIONS: string[];
+export declare const SPECIAL_FILES: string[];
+export declare const MAX_FILE_SIZE: number;
+/**
+ * Scan mode determines the depth and cost of the scan
+ *
+ * - 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 type ScanMode = 'full' | 'incremental';
+/**
+ * Scan depth controls AI usage independent of full vs incremental mode
+ *
+ * - cheap: Layer 1 + Layer 2 only. No AI validation, no Layer 3.
+ *          Only Tier A (core) findings are surfaced.
+ *          Target: <5s for typical PR scans.
+ *
+ * - validated: Layer 1 + Layer 2 + AI validation on selected findings. No Layer 3.
+ *              Tier A is surfaced directly, Tier B goes through AI validation.
+ *              Target: <15s with <10 AI calls.
+ *
+ * - deep: Layer 1 + Layer 2 + AI validation + Layer 3 semantic analysis.
+ *         Full analysis for initial onboarding or deep security audits.
+ *         Target: Complete thoroughness, cost secondary.
+ *
+ * ## Workflow Profile Recommendations:
+ *
+ * | Workflow       | Default Depth | Rationale                            |
+ * |----------------|---------------|--------------------------------------|
+ * | GitHub PR      | cheap         | Fast feedback, high-signal findings  |
+ * | VS Code        | validated     | Interactive, balance depth + speed   |
+ * | CLI (default)  | cheap         | Fast local scans                     |
+ * | CLI --deep     | deep          | Thorough analysis when requested     |
+ * | Onboarding     | deep          | Full picture on first scan           |
+ */
+export type ScanDepth = 'cheap' | 'validated' | 'deep';
+export interface ScanModeConfig {
+    /** The scan mode */
+    mode: ScanMode;
+    /** For incremental scans: paths of changed files */
+    changedFiles?: string[];
+    /** For incremental scans: base commit/branch to diff against */
+    baseBranch?: string;
+    /** Whether to skip AI validation entirely (for very fast scans) */
+    skipAIValidation?: boolean;
+    /** Whether to skip Layer 3 deep analysis (reduces cost) */
+    skipLayer3?: boolean;
+    /** Maximum files to send to AI validation (cost control) */
+    maxAIValidationFiles?: number;
+    /** Maximum files for Layer 3 analysis (cost control) */
+    maxLayer3Files?: number;
+    /** Scan depth mode (cheap/validated/deep) - controls AI usage */
+    scanDepth?: ScanDepth;
+    /** Whether to exclude test files from scanning (default: true) */
+    excludeTestFiles?: boolean;
+    /** Whether to exclude seed files from scanning (default: true) */
+    excludeSeedFiles?: boolean;
+    /** Custom file path patterns to exclude (glob format) */
+    customExclusions?: string[];
+}
+/**
+ * Default configurations for each scan mode
+ */
+export declare const SCAN_MODE_DEFAULTS: Record<ScanMode, Partial<ScanModeConfig>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Scanner Types and Interfaces
+ * Defines the core data structures for the security scanning engine
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCAN_MODE_DEFAULTS = exports.MAX_FILE_SIZE = exports.SPECIAL_FILES = exports.SCANNABLE_EXTENSIONS = void 0;
+// Supported file extensions for scanning
+exports.SCANNABLE_EXTENSIONS = [
+    '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+    '.py', '.rb', '.php', '.go', '.java', '.cs',
+    '.env', '.yaml', '.yml', '.json', '.toml',
+    '.dockerfile', '.sh', '.bash',
+];
+// Files to always scan regardless of extension
+exports.SPECIAL_FILES = [
+    'Dockerfile',
+    'docker-compose.yml',
+    'docker-compose.yaml',
+    '.env',
+    '.env.local',
+    '.env.production',
+    '.env.development',
+    'package.json',
+    'requirements.txt',
+    'Gemfile',
+    'go.mod',
+];
+// Max file size to scan (50KB as per PRD)
+exports.MAX_FILE_SIZE = 50 * 1024;
+/**
+ * Default configurations for each scan mode
+ */
+exports.SCAN_MODE_DEFAULTS = {
+    full: {
+        mode: 'full',
+        skipAIValidation: false,
+        skipLayer3: false,
+        maxAIValidationFiles: 50,
+        maxLayer3Files: 15,
+    },
+    incremental: {
+        mode: 'incremental',
+        skipAIValidation: false,
+        skipLayer3: true, // Skip expensive Layer 3 for incremental
+        maxAIValidationFiles: 20,
+        maxLayer3Files: 5,
+    },
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAkKH,yCAAyC;AAC5B,QAAA,oBAAoB,GAAG;IAClC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC5C,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK;IAC3C,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;IACzC,aAAa,EAAE,KAAK,EAAE,OAAO;CAC9B,CAAA;AAED,+CAA+C;AAClC,QAAA,aAAa,GAAG;IAC3B,YAAY;IACZ,oBAAoB;IACpB,qBAAqB;IACrB,MAAM;IACN,YAAY;IACZ,iBAAiB;IACjB,kBAAkB;IAClB,cAAc;IACd,kBAAkB;IAClB,SAAS;IACT,QAAQ;CACT,CAAA;AAED,0CAA0C;AAC7B,QAAA,aAAa,GAAG,EAAE,GAAG,IAAI,CAAA;AA4EtC;;GAEG;AACU,QAAA,kBAAkB,GAA8C;IAC3E,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,gBAAgB,EAAE,KAAK;QACvB,UAAU,EAAE,KAAK;QACjB,oBAAoB,EAAE,EAAE;QACxB,cAAc,EAAE,EAAE;KACnB;IACD,WAAW,EAAE;QACX,IAAI,EAAE,aAAa;QACnB,gBAAgB,EAAE,KAAK;QACvB,UAAU,EAAE,IAAI,EAAE,yCAAyC;QAC3D,oBAAoB,EAAE,EAAE;QACxB,cAAc,EAAE,CAAC;KAClB;CACF,CAAA"}

package/dist/utils/auth-helper-detector.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Auth Helper Detector
+ *
+ * Detects authentication helper functions that throw on missing auth,
+ * return non-null types, and provide security guarantees.
+ *
+ * When these helpers are called, subsequent code is GUARANTEED to have
+ * an authenticated user - no additional `if (!userId)` checks are needed.
+ */
+import type { ScanFile } from '../types';
+export interface AuthHelper {
+    /** Name of the helper function */
+    name: string;
+    /** File where it's defined (if detected) */
+    definedIn?: string;
+    /** Whether it throws on missing auth (vs returning null) */
+    throwsOnMissing: boolean;
+    /** Return type if detected (e.g., 'string', 'User', 'Promise<string>') */
+    returnType?: string;
+    /** Whether return type is non-null */
+    returnsNonNull: boolean;
+    /** Pattern that matches calls to this helper */
+    callPattern: RegExp;
+}
+export interface AuthHelperContext {
+    /** All detected auth helpers */
+    helpers: AuthHelper[];
+    /** Whether the project has any throwing auth helpers */
+    hasThrowingHelpers: boolean;
+    /** Summary for AI validation */
+    summary: string;
+}
+/**
+ * Detect auth helper functions in the codebase
+ */
+export declare function detectAuthHelpers(files: ScanFile[]): AuthHelperContext;
+/**
+ * Check if a code line uses a throwing auth helper
+ * Returns the helper if found, undefined otherwise
+ */
+export declare function usesThrowingAuthHelper(lineContent: string, surroundingContent: string, helpers: AuthHelper[]): AuthHelper | undefined;
+/**
+ * Check if a file has auth helper calls before a given line
+ * This indicates the code after the call is in authenticated context
+ */
+export declare function hasAuthHelperCallBefore(content: string, lineNumber: number, helpers: AuthHelper[]): {
+    hasCall: boolean;
+    helper?: AuthHelper;
+    callLine?: number;
+};
+/**
+ * Check if code suggests user ID is already validated
+ * Detects patterns like: const userId = await getCurrentUserId()
+ */
+export declare function isUserIdAlreadyValidated(content: string, lineNumber: number, helpers: AuthHelper[]): boolean;
+//# sourceMappingURL=auth-helper-detector.d.ts.map

package/dist/utils/auth-helper-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-helper-detector.d.ts","sourceRoot":"","sources":["../../src/utils/auth-helper-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAMxC,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,eAAe,EAAE,OAAO,CAAA;IACxB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,cAAc,EAAE,OAAO,CAAA;IACvB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,OAAO,EAAE,UAAU,EAAE,CAAA;IACrB,wDAAwD;IACxD,kBAAkB,EAAE,OAAO,CAAA;IAC3B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAA;CAChB;AA6ED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,iBAAiB,CA6CtE;AAuFD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,EAC1B,OAAO,EAAE,UAAU,EAAE,GACpB,UAAU,GAAG,SAAS,CAYxB;AA+BD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,UAAU,EAAE,GACpB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAkE9D;AAoCD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,UAAU,EAAE,GACpB,OAAO,CAuBT"}

package/dist/utils/auth-helper-detector.js

@@ -0,0 +1,360 @@
+"use strict";
+/**
+ * Auth Helper Detector
+ *
+ * Detects authentication helper functions that throw on missing auth,
+ * return non-null types, and provide security guarantees.
+ *
+ * When these helpers are called, subsequent code is GUARANTEED to have
+ * an authenticated user - no additional `if (!userId)` checks are needed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectAuthHelpers = detectAuthHelpers;
+exports.usesThrowingAuthHelper = usesThrowingAuthHelper;
+exports.hasAuthHelperCallBefore = hasAuthHelperCallBefore;
+exports.isUserIdAlreadyValidated = isUserIdAlreadyValidated;
+// ============================================================================
+// Well-Known Auth Helper Patterns
+// ============================================================================
+/**
+ * Common patterns for auth helpers that THROW on missing auth
+ * These are functions that guarantee authenticated context after call
+ */
+const THROWING_AUTH_HELPER_PATTERNS = [
+    // Generic patterns
+    {
+        namePattern: /^(get|fetch|require|ensure)(Current)?(User|UserId|Auth|Session|Principal)(Id)?$/i,
+        callPattern: /\b(get|fetch|require|ensure)(Current)?(User|UserId|Auth|Session|Principal)(Id)?\s*\(/gi,
+        description: 'Auth helper that retrieves authenticated user',
+    },
+    // Clerk patterns
+    {
+        namePattern: /^auth$/,
+        callPattern: /\bauth\s*\(\s*\)/gi,
+        description: 'Clerk auth() helper',
+    },
+    {
+        namePattern: /^currentUser$/,
+        callPattern: /\bcurrentUser\s*\(\s*\)/gi,
+        description: 'Clerk currentUser() helper',
+    },
+    // NextAuth patterns
+    {
+        namePattern: /^getServerSession$/,
+        callPattern: /\bgetServerSession\s*\(/gi,
+        description: 'NextAuth getServerSession()',
+    },
+    {
+        namePattern: /^getSession$/,
+        callPattern: /\bgetSession\s*\(/gi,
+        description: 'Session helper',
+    },
+    // Supabase patterns
+    {
+        namePattern: /^getUser$/,
+        callPattern: /\bsupabase\.auth\.getUser\s*\(/gi,
+        description: 'Supabase getUser()',
+    },
+];
+/**
+ * Patterns that indicate a function THROWS on missing auth
+ */
+const THROWING_INDICATORS = [
+    /throw\s+new\s+(Error|UnauthorizedError|AuthError|HttpException)/i,
+    /throw\s+.*401/i,
+    /throw\s+.*unauthorized/i,
+    /throw\s+.*unauthenticated/i,
+    /return\s+.*401/i,
+    /NextResponse\.json\s*\([^)]*401/i,
+    /res\.status\s*\(\s*401\s*\)/i,
+    /redirect\s*\(\s*['"`].*login/i,
+];
+/**
+ * Patterns that indicate NON-NULL return type
+ */
+const NON_NULL_RETURN_PATTERNS = [
+    /:\s*Promise<string>/i, // : Promise<string>
+    /:\s*string(?!\s*\|)/i, // : string (not string | null)
+    /:\s*Promise<User>/i, // : Promise<User>
+    /:\s*User(?!\s*\|)/i, // : User (not User | null)
+    /:\s*Promise<\w+>(?!\s*\|)/i, // : Promise<SomeType>
+    /\w+!$/i, // Non-null assertion in return
+];
+// ============================================================================
+// Detection Functions
+// ============================================================================
+/**
+ * Detect auth helper functions in the codebase
+ */
+function detectAuthHelpers(files) {
+    const helpers = [];
+    const detectedNames = new Set();
+    // First pass: find auth helper definitions
+    for (const file of files) {
+        // Skip non-code files
+        if (!/\.(ts|tsx|js|jsx)$/i.test(file.path))
+            continue;
+        // Look for function definitions that look like auth helpers
+        const functionMatches = findAuthHelperDefinitions(file.content, file.path);
+        for (const helper of functionMatches) {
+            if (!detectedNames.has(helper.name)) {
+                detectedNames.add(helper.name);
+                helpers.push(helper);
+            }
+        }
+    }
+    // Add well-known helpers if not already detected
+    for (const pattern of THROWING_AUTH_HELPER_PATTERNS) {
+        const nameMatch = pattern.namePattern.source.replace(/[\^\$\\b]/g, '');
+        if (!detectedNames.has(nameMatch)) {
+            // Check if this pattern is used in any file
+            const isUsed = files.some(f => pattern.callPattern.test(f.content));
+            if (isUsed) {
+                helpers.push({
+                    name: nameMatch,
+                    throwsOnMissing: true, // Assume throwing for well-known patterns
+                    returnsNonNull: true,
+                    callPattern: pattern.callPattern,
+                });
+            }
+        }
+    }
+    // Generate summary
+    const throwingHelpers = helpers.filter(h => h.throwsOnMissing);
+    const summary = generateAuthHelperSummary(helpers);
+    return {
+        helpers,
+        hasThrowingHelpers: throwingHelpers.length > 0,
+        summary,
+    };
+}
+/**
+ * Find auth helper function definitions in a file
+ */
+function findAuthHelperDefinitions(content, filePath) {
+    const helpers = [];
+    const lines = content.split('\n');
+    // Patterns for function definitions
+    const funcDefPatterns = [
+        // async function getCurrentUserId(): Promise<string> { ... throw
+        /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\([^)]*\)\s*(?::\s*([^{]+))?\s*\{/gi,
+        // const getCurrentUserId = async (): Promise<string> => { ... throw
+        /(?:export\s+)?const\s+(\w+)\s*=\s*(?:async\s*)?\([^)]*\)\s*(?::\s*([^=]+))?\s*=>/gi,
+    ];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const pattern of funcDefPatterns) {
+            pattern.lastIndex = 0;
+            const match = pattern.exec(line);
+            if (!match)
+                continue;
+            const funcName = match[1];
+            const returnType = match[2]?.trim();
+            // Check if this looks like an auth helper by name
+            const isAuthHelperName = THROWING_AUTH_HELPER_PATTERNS.some(p => p.namePattern.test(funcName));
+            if (!isAuthHelperName)
+                continue;
+            // Look ahead for throwing patterns and return type
+            const functionBody = extractFunctionBody(lines, i);
+            const throwsOnMissing = THROWING_INDICATORS.some(p => p.test(functionBody));
+            const returnsNonNull = returnType
+                ? NON_NULL_RETURN_PATTERNS.some(p => p.test(`: ${returnType}`))
+                : false;
+            // Create call pattern for this helper
+            const callPattern = new RegExp(`\\b${escapeRegex(funcName)}\\s*\\(`, 'gi');
+            helpers.push({
+                name: funcName,
+                definedIn: filePath,
+                throwsOnMissing,
+                returnType,
+                returnsNonNull: returnsNonNull || throwsOnMissing, // If it throws, the return is non-null
+                callPattern,
+            });
+        }
+    }
+    return helpers;
+}
+/**
+ * Extract function body for analysis (up to closing brace)
+ */
+function extractFunctionBody(lines, startLine, maxLines = 50) {
+    let braceCount = 0;
+    let started = false;
+    const bodyLines = [];
+    for (let i = startLine; i < Math.min(lines.length, startLine + maxLines); i++) {
+        const line = lines[i];
+        bodyLines.push(line);
+        for (const char of line) {
+            if (char === '{') {
+                braceCount++;
+                started = true;
+            }
+            else if (char === '}') {
+                braceCount--;
+                if (started && braceCount === 0) {
+                    return bodyLines.join('\n');
+                }
+            }
+        }
+    }
+    return bodyLines.join('\n');
+}
+/**
+ * Check if a code line uses a throwing auth helper
+ * Returns the helper if found, undefined otherwise
+ */
+function usesThrowingAuthHelper(lineContent, surroundingContent, helpers) {
+    // Check if any throwing helper is called in the surrounding context
+    const throwingHelpers = helpers.filter(h => h.throwsOnMissing);
+    for (const helper of throwingHelpers) {
+        helper.callPattern.lastIndex = 0;
+        if (helper.callPattern.test(surroundingContent)) {
+            return helper;
+        }
+    }
+    return undefined;
+}
+/**
+ * Well-known auth helper call patterns - used as fallback when no helpers are detected
+ * These patterns are common across frameworks and should be recognized even without project analysis
+ */
+const WELL_KNOWN_AUTH_CALL_PATTERNS = [
+    // Generic throwing auth patterns
+    { pattern: /\bgetCurrentUserId\s*\(/i, name: 'getCurrentUserId' },
+    { pattern: /\bgetCurrentUser\s*\(/i, name: 'getCurrentUser' },
+    { pattern: /\brequireAuth\s*\(/i, name: 'requireAuth' },
+    { pattern: /\brequireUser\s*\(/i, name: 'requireUser' },
+    { pattern: /\bensureAuth\s*\(/i, name: 'ensureAuth' },
+    { pattern: /\bensureAuthenticated\s*\(/i, name: 'ensureAuthenticated' },
+    { pattern: /\bverifyAuth\s*\(/i, name: 'verifyAuth' },
+    { pattern: /\bcheckAuth\s*\(/i, name: 'checkAuth' },
+    { pattern: /\bvalidateAuth\s*\(/i, name: 'validateAuth' },
+    { pattern: /\bassertAuth\s*\(/i, name: 'assertAuth' },
+    { pattern: /\bgetAuth\s*\(/i, name: 'getAuth' },
+    { pattern: /\bfetchCurrentUser\s*\(/i, name: 'fetchCurrentUser' },
+    // Clerk
+    { pattern: /\bauth\s*\(\s*\)\.protect\s*\(/i, name: 'auth().protect' },
+    { pattern: /\bcurrentUser\s*\(\s*\)/i, name: 'currentUser' },
+    // NextAuth
+    { pattern: /\bgetServerSession\s*\(/i, name: 'getServerSession' },
+    // Supabase
+    { pattern: /\bsupabase\.auth\.getUser\s*\(/i, name: 'supabase.auth.getUser' },
+    // Destructuring pattern
+    { pattern: /const\s+\{\s*user\s*\}\s*=\s*await\s+auth/i, name: 'destructured auth' },
+];
+/**
+ * Check if a file has auth helper calls before a given line
+ * This indicates the code after the call is in authenticated context
+ */
+function hasAuthHelperCallBefore(content, lineNumber, helpers) {
+    const lines = content.split('\n');
+    const throwingHelpers = helpers.filter(h => h.throwsOnMissing);
+    // Increase search window from 30 to 100 lines for better coverage
+    const searchStart = Math.max(0, lineNumber - 100);
+    // Look backwards from the current line
+    for (let i = lineNumber - 1; i >= searchStart; i--) {
+        const line = lines[i];
+        // Check detected helpers first
+        for (const helper of throwingHelpers) {
+            helper.callPattern.lastIndex = 0;
+            if (helper.callPattern.test(line)) {
+                return { hasCall: true, helper, callLine: i + 1 };
+            }
+        }
+        // Stop at function boundaries (for module-level helpers, we still check inside function)
+        if (/\b(function|async function|=>|export\s+default)\b/.test(line) && /\{/.test(line)) {
+            // If this is the route handler definition line, continue checking inside it
+            if (i !== lineNumber - 1) {
+                break;
+            }
+        }
+    }
+    // FORWARD SEARCH: Always search forward into the function body
+    // This catches auth helpers called INSIDE the route handler, not just before it
+    // Example: export async function GET() { const userId = await getCurrentUserId(); ... }
+    const endLine = Math.min(lines.length, lineNumber + 30);
+    for (let i = lineNumber; i < endLine; i++) {
+        const line = lines[i];
+        // Check detected helpers
+        for (const helper of throwingHelpers) {
+            helper.callPattern.lastIndex = 0;
+            if (helper.callPattern.test(line)) {
+                return { hasCall: true, helper, callLine: i + 1 };
+            }
+        }
+        // Also check well-known patterns (fallback for single-file scans)
+        for (const known of WELL_KNOWN_AUTH_CALL_PATTERNS) {
+            if (known.pattern.test(line)) {
+                return {
+                    hasCall: true,
+                    helper: {
+                        name: known.name,
+                        throwsOnMissing: true,
+                        returnsNonNull: true,
+                        callPattern: known.pattern,
+                    },
+                    callLine: i + 1
+                };
+            }
+        }
+        // Stop at another function boundary (but not the current line)
+        if (i > lineNumber && /\bexport\s+(async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH)\s*\(/i.test(line)) {
+            break;
+        }
+    }
+    return { hasCall: false };
+}
+/**
+ * Generate summary for AI validation
+ */
+function generateAuthHelperSummary(helpers) {
+    if (helpers.length === 0) {
+        return 'No auth helper functions detected.';
+    }
+    const throwing = helpers.filter(h => h.throwsOnMissing);
+    const lines = [];
+    lines.push('### Auth Helper Functions');
+    lines.push('');
+    if (throwing.length > 0) {
+        lines.push('**Throwing auth helpers** (guarantee authenticated context when called):');
+        for (const h of throwing) {
+            const location = h.definedIn ? ` (defined in ${h.definedIn})` : '';
+            lines.push(`- \`${h.name}()\`${location}`);
+        }
+        lines.push('');
+        lines.push('When these helpers are called at the start of a function, subsequent code is GUARANTEED to have an authenticated user. Do NOT flag "missing auth" or suggest `if (!userId)` checks after these calls.');
+    }
+    return lines.join('\n');
+}
+/**
+ * Escape special regex characters
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Check if code suggests user ID is already validated
+ * Detects patterns like: const userId = await getCurrentUserId()
+ */
+function isUserIdAlreadyValidated(content, lineNumber, helpers) {
+    const lines = content.split('\n');
+    const contextStart = Math.max(0, lineNumber - 20);
+    const context = lines.slice(contextStart, lineNumber).join('\n');
+    // Check for throwing helper calls
+    const throwingHelpers = helpers.filter(h => h.throwsOnMissing);
+    for (const helper of throwingHelpers) {
+        helper.callPattern.lastIndex = 0;
+        if (helper.callPattern.test(context)) {
+            return true;
+        }
+    }
+    // Check for common validation patterns
+    const validationPatterns = [
+        /const\s+(?:userId|user_id|currentUserId)\s*=\s*await/i,
+        /if\s*\(\s*!(?:userId|user_id|user|session)\s*\)/i, // Already has the check
+        /(?:userId|user_id)\s*\|\|\s*throw/i,
+        /auth\(\)\.protect\(\)/i, // Clerk protect
+    ];
+    return validationPatterns.some(p => p.test(context));
+}
+//# sourceMappingURL=auth-helper-detector.js.map