nextjs-secure 0.6.0 → 0.7.0

package/dist/bot.d.cts

@@ -0,0 +1,567 @@
+import { NextRequest } from 'next/server';
+
+/**
+ * Bot Detection Types
+ * @module nextjs-secure/bot
+ */
+
+/**
+ * Bot classification categories
+ */
+type BotCategory = 'search_engine' | 'social_media' | 'monitoring' | 'seo' | 'ai_crawler' | 'feed_reader' | 'preview' | 'security' | 'scraper' | 'spam' | 'malicious' | 'unknown';
+/**
+ * Bot detection result
+ */
+interface BotDetectionResult {
+    isBot: boolean;
+    category?: BotCategory;
+    name?: string;
+    confidence: number;
+    reason?: string;
+    userAgent?: string;
+    ip?: string;
+}
+/**
+ * Known bot pattern definition
+ */
+interface BotPattern {
+    name: string;
+    pattern: RegExp;
+    category: BotCategory;
+    allowed: boolean;
+    description?: string;
+}
+/**
+ * User-Agent analysis options
+ */
+interface UserAgentOptions {
+    /**
+     * Block all detected bots
+     * @default false
+     */
+    blockAllBots?: boolean;
+    /**
+     * Allow specific bot categories
+     * @default ['search_engine', 'social_media', 'monitoring']
+     */
+    allowCategories?: BotCategory[];
+    /**
+     * Allow specific bots by name
+     * @default ['Googlebot', 'Bingbot', 'Slurp']
+     */
+    allowList?: string[];
+    /**
+     * Block specific bots by name (overrides allowList)
+     */
+    blockList?: string[];
+    /**
+     * Custom bot patterns
+     */
+    customPatterns?: BotPattern[];
+    /**
+     * Block empty user agents
+     * @default true
+     */
+    blockEmptyUA?: boolean;
+    /**
+     * Block suspicious user agents (very short, random strings)
+     * @default true
+     */
+    blockSuspiciousUA?: boolean;
+}
+/**
+ * Honeypot field configuration
+ */
+interface HoneypotOptions {
+    /**
+     * Field name for the honeypot (should look like a real field)
+     * @default '_hp_email'
+     */
+    fieldName?: string;
+    /**
+     * Additional honeypot field names
+     */
+    additionalFields?: string[];
+    /**
+     * Check for honeypot in these sources
+     * @default ['body', 'query']
+     */
+    checkIn?: ('body' | 'query' | 'headers')[];
+    /**
+     * Custom validation function
+     */
+    validate?: (value: unknown) => boolean;
+}
+/**
+ * Behavior analysis options
+ */
+interface BehaviorOptions {
+    /**
+     * Minimum time between requests from same IP (ms)
+     * @default 100
+     */
+    minRequestInterval?: number;
+    /**
+     * Maximum requests per second from same IP
+     * @default 10
+     */
+    maxRequestsPerSecond?: number;
+    /**
+     * Time window for behavior analysis (ms)
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Store for tracking request patterns
+     */
+    store?: BehaviorStore;
+    /**
+     * Identifier function for grouping requests
+     * @default IP-based
+     */
+    identifier?: (req: NextRequest) => string | Promise<string>;
+    /**
+     * Suspicious patterns to detect
+     */
+    patterns?: {
+        /**
+         * Detect sequential URL access patterns
+         * @default true
+         */
+        sequentialAccess?: boolean;
+        /**
+         * Detect unusual request timing (too regular)
+         * @default true
+         */
+        regularTiming?: boolean;
+        /**
+         * Detect missing typical browser headers
+         * @default true
+         */
+        missingHeaders?: boolean;
+    };
+}
+/**
+ * Behavior tracking store interface
+ */
+interface BehaviorStore {
+    /**
+     * Record a request
+     */
+    record(identifier: string, timestamp: number, path: string): Promise<void>;
+    /**
+     * Get request history for an identifier
+     */
+    getHistory(identifier: string, windowMs: number): Promise<RequestRecord[]>;
+    /**
+     * Clear old records
+     */
+    cleanup?(maxAge: number): Promise<void>;
+}
+/**
+ * Request record for behavior tracking
+ */
+interface RequestRecord {
+    timestamp: number;
+    path: string;
+}
+/**
+ * Behavior analysis result
+ */
+interface BehaviorAnalysisResult {
+    suspicious: boolean;
+    score: number;
+    reasons: string[];
+    requestCount: number;
+    avgInterval: number;
+}
+/**
+ * Supported CAPTCHA providers
+ */
+type CaptchaProvider = 'recaptcha' | 'hcaptcha' | 'turnstile';
+/**
+ * CAPTCHA verification options
+ */
+interface CaptchaOptions {
+    /**
+     * CAPTCHA provider
+     */
+    provider: CaptchaProvider;
+    /**
+     * Site key (public)
+     */
+    siteKey: string;
+    /**
+     * Secret key (private)
+     */
+    secretKey: string;
+    /**
+     * Minimum score threshold (for reCAPTCHA v3)
+     * @default 0.5
+     */
+    threshold?: number;
+    /**
+     * Field name for the CAPTCHA token
+     * @default 'captchaToken' or provider-specific
+     */
+    tokenField?: string;
+    /**
+     * Action name (for reCAPTCHA v3)
+     */
+    action?: string;
+    /**
+     * Skip CAPTCHA for certain conditions
+     */
+    skip?: (req: NextRequest) => boolean | Promise<boolean>;
+}
+/**
+ * CAPTCHA verification result
+ */
+interface CaptchaResult {
+    success: boolean;
+    score?: number;
+    action?: string;
+    hostname?: string;
+    errorCodes?: string[];
+    challengeTs?: string;
+}
+/**
+ * Challenge types
+ */
+type ChallengeType = 'javascript' | 'cookie' | 'pow' | 'redirect';
+/**
+ * Challenge options
+ */
+interface ChallengeOptions {
+    /**
+     * Challenge type
+     * @default 'javascript'
+     */
+    type?: ChallengeType;
+    /**
+     * Challenge difficulty (for PoW)
+     * @default 4
+     */
+    difficulty?: number;
+    /**
+     * Challenge expiry time (ms)
+     * @default 300000 (5 minutes)
+     */
+    expiryMs?: number;
+    /**
+     * Cookie name for challenge token
+     * @default '__bot_challenge'
+     */
+    cookieName?: string;
+    /**
+     * Secret for signing challenge tokens
+     */
+    secret?: string;
+}
+/**
+ * Combined bot protection options
+ */
+interface BotProtectionOptions {
+    /**
+     * User-Agent analysis options
+     */
+    userAgent?: UserAgentOptions | boolean;
+    /**
+     * Honeypot options
+     */
+    honeypot?: HoneypotOptions | boolean;
+    /**
+     * Behavior analysis options
+     */
+    behavior?: BehaviorOptions | boolean;
+    /**
+     * CAPTCHA options
+     */
+    captcha?: CaptchaOptions;
+    /**
+     * Challenge-response options
+     */
+    challenge?: ChallengeOptions | boolean;
+    /**
+     * Skip bot protection for certain conditions
+     */
+    skip?: (req: NextRequest) => boolean | Promise<boolean>;
+    /**
+     * Custom response when bot is detected
+     */
+    onBot?: (req: NextRequest, result: BotDetectionResult) => Response | Promise<Response>;
+    /**
+     * Log bot detections
+     * @default false
+     */
+    log?: boolean | ((result: BotDetectionResult) => void);
+    /**
+     * Mode: 'block' blocks bots, 'detect' only detects
+     * @default 'block'
+     */
+    mode?: 'block' | 'detect';
+}
+/**
+ * Extended context with bot detection info
+ */
+interface BotContext {
+    bot?: BotDetectionResult;
+}
+/**
+ * Bot-protected handler type
+ */
+type BotProtectedHandler<T = unknown> = (req: NextRequest, ctx: T & BotContext) => Response | Promise<Response>;
+
+/**
+ * User-Agent Analysis for Bot Detection
+ * @module nextjs-secure/bot
+ */
+
+/**
+ * Comprehensive list of known bot patterns
+ */
+declare const KNOWN_BOT_PATTERNS: BotPattern[];
+/**
+ * Default allowed bot categories
+ */
+declare const DEFAULT_ALLOWED_CATEGORIES: BotCategory[];
+/**
+ * Default allowed bot names
+ */
+declare const DEFAULT_ALLOWED_BOTS: string[];
+/**
+ * Analyze a User-Agent string for bot patterns
+ */
+declare function analyzeUserAgent(userAgent: string | null, options?: UserAgentOptions): BotDetectionResult;
+/**
+ * Check if User-Agent appears suspicious
+ */
+declare function isSuspiciousUA(userAgent: string): boolean;
+/**
+ * Check if a specific bot is allowed
+ */
+declare function isBotAllowed(botName: string, options?: UserAgentOptions): boolean;
+/**
+ * Get all known bot patterns for a category
+ */
+declare function getBotsByCategory(category: BotCategory): BotPattern[];
+/**
+ * Create a custom bot pattern
+ */
+declare function createBotPattern(name: string, pattern: RegExp | string, category: BotCategory, allowed?: boolean, description?: string): BotPattern;
+
+/**
+ * Honeypot Protection for Bot Detection
+ * @module nextjs-secure/bot
+ */
+
+/**
+ * Default honeypot field names that look legitimate
+ */
+declare const DEFAULT_HONEYPOT_FIELDS: string[];
+/**
+ * Default honeypot options
+ */
+declare const DEFAULT_HONEYPOT_OPTIONS: Required<Omit<HoneypotOptions, 'validate'>> & Pick<HoneypotOptions, 'validate'>;
+/**
+ * Check for honeypot field values in request
+ */
+declare function checkHoneypot(req: NextRequest, options?: HoneypotOptions): Promise<BotDetectionResult>;
+/**
+ * Create honeypot middleware
+ */
+declare function withHoneypot<T = unknown>(handler: (req: NextRequest, ctx: T) => Response | Promise<Response>, options?: HoneypotOptions): (req: NextRequest, ctx: T) => Promise<Response>;
+/**
+ * Generate honeypot field HTML
+ * These fields should be hidden with CSS, not display:none
+ * Bots often ignore display:none but fill visible fields
+ */
+declare function generateHoneypotHTML(options?: HoneypotOptions): string;
+/**
+ * Generate CSS for honeypot fields
+ */
+declare function generateHoneypotCSS(options?: HoneypotOptions): string;
+
+/**
+ * Behavior Analysis for Bot Detection
+ * @module nextjs-secure/bot
+ */
+
+/**
+ * Default behavior analysis options
+ */
+declare const DEFAULT_BEHAVIOR_OPTIONS: Required<Omit<BehaviorOptions, 'store' | 'identifier'>> & Pick<BehaviorOptions, 'store' | 'identifier'>;
+/**
+ * In-memory behavior tracking store with LRU eviction
+ */
+declare class MemoryBehaviorStore implements BehaviorStore {
+    private records;
+    private maxIdentifiers;
+    private accessOrder;
+    constructor(options?: {
+        maxIdentifiers?: number;
+    });
+    record(identifier: string, timestamp: number, path: string): Promise<void>;
+    getHistory(identifier: string, windowMs: number): Promise<RequestRecord[]>;
+    cleanup(maxAge: number): Promise<void>;
+    /**
+     * Get store statistics
+     */
+    getStats(): {
+        identifiers: number;
+        totalRecords: number;
+    };
+    /**
+     * Clear all records
+     */
+    clear(): void;
+}
+/**
+ * Analyze request behavior for bot patterns
+ */
+declare function analyzeBehavior(req: NextRequest, history: RequestRecord[], options?: BehaviorOptions): Promise<BehaviorAnalysisResult>;
+/**
+ * Check behavior and return bot detection result
+ */
+declare function checkBehavior(req: NextRequest, options?: BehaviorOptions): Promise<BotDetectionResult>;
+/**
+ * Get or create global behavior store
+ */
+declare function getGlobalBehaviorStore(): MemoryBehaviorStore;
+/**
+ * Create behavior analysis middleware
+ */
+declare function withBehaviorAnalysis<T = unknown>(handler: (req: NextRequest, ctx: T) => Response | Promise<Response>, options?: BehaviorOptions): (req: NextRequest, ctx: T) => Promise<Response>;
+
+/**
+ * CAPTCHA Integration for Bot Detection
+ * @module nextjs-secure/bot
+ *
+ * Supports:
+ * - Google reCAPTCHA v2 & v3
+ * - hCaptcha
+ * - Cloudflare Turnstile
+ */
+
+/**
+ * Verify CAPTCHA token with provider
+ */
+declare function verifyCaptcha(token: string, options: CaptchaOptions): Promise<CaptchaResult>;
+/**
+ * Extract CAPTCHA token from request
+ */
+declare function extractCaptchaToken(req: NextRequest, options: CaptchaOptions): Promise<string | null>;
+/**
+ * Check CAPTCHA and return bot detection result
+ */
+declare function checkCaptcha(req: NextRequest, options: CaptchaOptions): Promise<BotDetectionResult>;
+/**
+ * Create CAPTCHA verification middleware
+ */
+declare function withCaptcha<T = unknown>(handler: (req: NextRequest, ctx: T) => Response | Promise<Response>, options: CaptchaOptions): (req: NextRequest, ctx: T) => Promise<Response>;
+/**
+ * Generate reCAPTCHA v2 checkbox HTML
+ */
+declare function generateRecaptchaV2(siteKey: string, options?: {
+    theme?: 'light' | 'dark';
+    size?: 'normal' | 'compact';
+}): string;
+/**
+ * Generate reCAPTCHA v3 HTML
+ */
+declare function generateRecaptchaV3(siteKey: string, action?: string): string;
+/**
+ * Generate hCaptcha HTML
+ */
+declare function generateHCaptcha(siteKey: string, options?: {
+    theme?: 'light' | 'dark';
+    size?: 'normal' | 'compact';
+}): string;
+/**
+ * Generate Cloudflare Turnstile HTML
+ */
+declare function generateTurnstile(siteKey: string, options?: {
+    theme?: 'light' | 'dark' | 'auto';
+    size?: 'normal' | 'compact';
+}): string;
+
+/**
+ * Bot Protection Middleware
+ * @module nextjs-secure/bot
+ *
+ * Combined bot detection middleware that integrates:
+ * - User-Agent analysis
+ * - Honeypot fields
+ * - Behavior analysis
+ * - CAPTCHA verification
+ */
+
+/**
+ * Run all enabled bot detection checks
+ */
+declare function detectBot(req: NextRequest, options?: BotProtectionOptions): Promise<BotDetectionResult>;
+/**
+ * Create bot protection middleware
+ *
+ * @example
+ * ```typescript
+ * import { withBotProtection } from 'nextjs-secure/bot'
+ *
+ * export const POST = withBotProtection(handler, {
+ *   userAgent: {
+ *     blockAllBots: false,
+ *     allowList: ['Googlebot', 'Bingbot'],
+ *   },
+ *   honeypot: {
+ *     fieldName: '_hp_email',
+ *   },
+ *   behavior: {
+ *     maxRequestsPerSecond: 10,
+ *   },
+ * })
+ * ```
+ */
+declare function withBotProtection<T = unknown>(handler: (req: NextRequest, ctx: T & BotContext) => Response | Promise<Response>, options?: BotProtectionOptions): (req: NextRequest, ctx: T) => Promise<Response>;
+/**
+ * User-Agent only bot protection
+ */
+declare function withUserAgentProtection<T = unknown>(handler: (req: NextRequest, ctx: T & BotContext) => Response | Promise<Response>, options?: UserAgentOptions): (req: NextRequest, ctx: T) => Promise<Response>;
+/**
+ * Honeypot only protection
+ */
+declare function withHoneypotProtection<T = unknown>(handler: (req: NextRequest, ctx: T & BotContext) => Response | Promise<Response>, options?: HoneypotOptions): (req: NextRequest, ctx: T) => Promise<Response>;
+/**
+ * Behavior analysis only protection
+ */
+declare function withBehaviorProtection<T = unknown>(handler: (req: NextRequest, ctx: T & BotContext) => Response | Promise<Response>, options?: BehaviorOptions): (req: NextRequest, ctx: T) => Promise<Response>;
+/**
+ * CAPTCHA only protection
+ */
+declare function withCaptchaProtection<T = unknown>(handler: (req: NextRequest, ctx: T & BotContext) => Response | Promise<Response>, options: CaptchaOptions): (req: NextRequest, ctx: T) => Promise<Response>;
+/**
+ * Preset bot protection configurations
+ */
+declare const BOT_PROTECTION_PRESETS: {
+    /**
+     * Relaxed - Only blocks obvious bots
+     */
+    readonly relaxed: BotProtectionOptions;
+    /**
+     * Standard - Good balance of protection
+     */
+    readonly standard: BotProtectionOptions;
+    /**
+     * Strict - Maximum protection
+     */
+    readonly strict: BotProtectionOptions;
+    /**
+     * API - For API endpoints
+     */
+    readonly api: BotProtectionOptions;
+};
+/**
+ * Create bot protection with preset
+ */
+declare function withBotProtectionPreset<T = unknown>(handler: (req: NextRequest, ctx: T & BotContext) => Response | Promise<Response>, preset: keyof typeof BOT_PROTECTION_PRESETS, overrides?: BotProtectionOptions): (req: NextRequest, ctx: T) => Promise<Response>;
+
+export { BOT_PROTECTION_PRESETS, type BehaviorAnalysisResult, type BehaviorOptions, type BehaviorStore, type BotCategory, type BotContext, type BotDetectionResult, type BotPattern, type BotProtectedHandler, type BotProtectionOptions, type CaptchaOptions, type CaptchaProvider, type CaptchaResult, type ChallengeOptions, type ChallengeType, DEFAULT_ALLOWED_BOTS, DEFAULT_ALLOWED_CATEGORIES, DEFAULT_BEHAVIOR_OPTIONS, DEFAULT_HONEYPOT_FIELDS, DEFAULT_HONEYPOT_OPTIONS, type HoneypotOptions, KNOWN_BOT_PATTERNS, MemoryBehaviorStore, type RequestRecord, type UserAgentOptions, analyzeBehavior, analyzeUserAgent, checkBehavior, checkCaptcha, checkHoneypot, createBotPattern, detectBot, extractCaptchaToken, generateHCaptcha, generateHoneypotCSS, generateHoneypotHTML, generateRecaptchaV2, generateRecaptchaV3, generateTurnstile, getBotsByCategory, getGlobalBehaviorStore, isBotAllowed, isSuspiciousUA, verifyCaptcha, withBehaviorAnalysis, withBehaviorProtection, withBotProtection, withBotProtectionPreset, withCaptcha, withCaptchaProtection, withHoneypot, withHoneypotProtection, withUserAgentProtection };