xypriss 9.10.19 → 9.10.21

package/dist/src/types/mod/security.d.ts

@@ -1,1478 +0,0 @@
-import { BrowserOnlyConfig, TerminalOnlyConfig } from "../../middleware/built-in/security";
-/**
- * @fileoverview Security-related type definitions for XyPriss integration
- *
- * This module contains all security-related types including authentication,
- * authorization, encryption, and security policies.
- *
- * @version 4.5.11
- * @author XyPrissJS Team
- * @since 2025-01-06
- */
-/**
- * Security configuration levels.
- *
- * Predefined security levels that automatically configure
- * appropriate security measures:
- * - basic: Essential security features
- * - enhanced: Additional security layers
- * - maximum: All security features enabled
- */
-export type SecurityLevel = "basic" | "enhanced" | "maximum";
-/**
- * CSRF Protection Configuration
- *
- * Protects against Cross-Site Request Forgery attacks by requiring tokens.
- * Can be enabled/disabled or configured with custom options.
- *
- * @example Enable with defaults:
- * ```typescript
- * csrf: true
- * ```
- *
- * @example Disable:
- * ```typescript
- * csrf: false
- * ```
- *
- * @example Custom configuration:
- * ```typescript
- * csrf: {
- *   cookieName: '__Host-csrf-token',
- *   cookieOptions: {
- *     httpOnly: true,
- *     sameSite: 'strict',
- *     secure: process.env.NODE_ENV === 'production'
- *   }
- * }
- * ```
- */
-export interface CSRFConfig {
-    /** CSRF token cookie name */
-    cookieName?: string;
-    /** CSRF token cookie options */
-    cookieOptions?: {
-        httpOnly?: boolean;
-        sameSite?: boolean | "lax" | "strict" | "none";
-        secure?: boolean;
-    };
-}
-/**
- * XyRS - XyPriss Request Signature Configuration
- *
- * Validates request signatures using the XP-Request-Sig header.
- * Provides API authentication by requiring a secret signature on all requests.
- *
- * @example Enable with secret:
- * ```typescript
- * requestSignature: {
- *   secret: "my-secret-api-key"
- * }
- * ```
- *
- * @example Custom configuration:
- * ```typescript
- * requestSignature: {
- *   secret: "my-secret-api-key",
- *   errorMessage: "API key required",
- *   statusCode: 403,
- *   caseSensitive: false
- * }
- * ```
- */
-export interface RequestSignatureConfig {
-    /** Custom header name for the signature (default: "XP-Request-Sig") */
-    headerName?: string;
-    /** The secret value that must match the header */
-    secret: string;
-    /** Custom error message for blocked requests */
-    errorMessage?: string;
-    /** HTTP status code for blocked requests */
-    statusCode?: number;
-    /** Enable debug logging */
-    debug?: boolean;
-    /** Case-sensitive comparison */
-    caseSensitive?: boolean;
-    /** Trim whitespace from header value */
-    trimValue?: boolean;
-    /** Maximum allowed header length to prevent DoS (default: 512) */
-    maxHeaderLength?: number;
-    /** Rate limiting: max failed attempts before temporary block (default: 5) */
-    maxFailedAttempts?: number;
-    /** Rate limiting: block duration in milliseconds (default: 15 minutes) */
-    blockDuration?: number;
-    /** Disable rate limiting entirely (default: false) */
-    disableRateLimiting?: boolean;
-    /** Scale factor for rate limiting thresholds (default: 1.0) */
-    rateLimitScaleFactor?: number;
-    /** Minimum secret length requirement (default: 32) */
-    minSecretLength?: number;
-    /** Enable timing attack protection (default: true) */
-    timingSafeComparison?: boolean;
-    /** Reject requests with suspicious patterns (default: true) */
-    rejectSuspiciousPatterns?: boolean;
-}
-/**
- * Helmet Security Headers Configuration
- *
- * Sets various HTTP headers to help protect against common attacks.
- * Can be enabled/disabled or configured with custom header options.
- *
- * @example Enable with defaults:
- * ```typescript
- * helmet: true
- * ```
- *
- * @example Custom CSP:
- * ```typescript
- * helmet: {
- *   contentSecurityPolicy: {
- *     directives: {
- *       defaultSrc: ["'self'"],
- *       scriptSrc: ["'self'", "'unsafe-inline'"]
- *     }
- *   },
- *   hsts: { maxAge: 31536000 }
- * }
- * ```
- */
-export interface HelmetConfig {
-    /** Content Security Policy configuration */
-    contentSecurityPolicy?: {
-        /** CSP directives - flexible configuration allowing any CSP directive */
-        directives?: Record<string, string | string[]>;
-    } | boolean;
-    /** HTTP Strict Transport Security configuration */
-    hsts?: {
-        maxAge: number;
-        includeSubDomains?: boolean;
-        preload?: boolean;
-    };
-    /** Cross-Origin Embedder Policy */
-    crossOriginEmbedderPolicy?: boolean | {
-        policy: "require-corp" | "credentialless";
-    };
-    /** Cross-Origin Opener Policy */
-    crossOriginOpenerPolicy?: boolean | {
-        policy: "same-origin" | "same-origin-allow-popups" | "unsafe-none";
-    };
-    /** Cross-Origin Resource Policy */
-    crossOriginResourcePolicy?: boolean | {
-        policy: "same-origin" | "same-site" | "cross-origin";
-    };
-    /** DNS Prefetch Control */
-    dnsPrefetchControl?: boolean | {
-        allow: boolean;
-    };
-    /** Frameguard (X-Frame-Options) */
-    frameguard?: boolean | {
-        action: "deny" | "sameorigin" | "allow-from";
-        domain?: string;
-    };
-    /** Hide Powered By header */
-    hidePoweredBy?: boolean | {
-        setTo?: string;
-    };
-    /** IE No Open */
-    ieNoOpen?: boolean;
-    /** No Sniff */
-    noSniff?: boolean;
-    /** Origin Agent Cluster */
-    originAgentCluster?: boolean;
-    /** Permitted Cross Domain Policies */
-    permittedCrossDomainPolicies?: boolean | {
-        permittedPolicies: "none" | "master-only" | "by-content-type" | "all";
-    };
-    /** Referrer Policy */
-    referrerPolicy?: boolean | {
-        policy: string | string[];
-    };
-    /** XSS Filter */
-    xssFilter?: boolean;
-}
-/**
- * XSS Protection Configuration
- *
- * Protects against Cross-Site Scripting attacks by sanitizing input.
- * Can be enabled/disabled or configured with custom sanitization rules.
- *
- * @example Enable with defaults:
- * ```typescript
- * xss: true
- * ```
- *
- * @example Custom configuration:
- * ```typescript
- * xss: {
- *   blockOnDetection: true,
- *   customPatterns: [/custom-pattern/g],
- *   whitelist: { a: ['href', 'title'] }
- * }
- * ```
- */
-export interface XSSConfig {
-    /** Block requests on XSS detection */
-    blockOnDetection?: boolean;
-    /** Custom XSS patterns to detect */
-    customPatterns?: RegExp[];
-    /** Whitelist of allowed tags and attributes */
-    whitelist?: {
-        [tag: string]: string[];
-    };
-}
-/**
- * SQL Injection Protection Configuration
- *
- * Detects and prevents SQL injection attacks in request data.
- * Can be enabled/disabled or configured with custom detection rules.
- *
- * @example Enable with defaults:
- * ```typescript
- * sqlInjection: true
- * ```
- *
- * @example Custom configuration:
- * ```typescript
- * sqlInjection: {
- *   blockOnDetection: true,
- *   riskThreshold: 'medium',
- *   customPatterns: [/custom-sql-pattern/g]
- * }
- * ```
- */
-export interface SQLInjectionConfig {
-    /** Block requests on SQL injection detection */
-    blockOnDetection?: boolean;
-    /** Risk threshold for SQL injection detection */
-    riskThreshold?: "low" | "medium" | "high";
-    /** Custom SQL injection patterns to detect */
-    customPatterns?: RegExp[];
-    /** Enable contextual analysis to reduce false positives */
-    contextualAnalysis?: boolean;
-    /** Strict mode - more aggressive detection */
-    strictMode?: boolean;
-    /** Log detected attempts */
-    logAttempts?: boolean;
-    /** False positive threshold (0-1) */
-    falsePositiveThreshold?: number;
-    /** Maximum allowed length for input strings before triggering 'Excessive length' detection */
-    maxLength?: number;
-}
-/**
- * Path Traversal Protection Configuration
- *
- * Detects and prevents directory traversal attacks while allowing legitimate file paths.
- *
- * @example Enable with defaults:
- * ```typescript
- * pathTraversal: true
- * ```
- *
- * @example Custom configuration:
- * ```typescript
- * pathTraversal: {
- *   blockOnDetection: true,
- *   allowedPaths: ['/uploads/', '/public/'],
- *   allowedExtensions: ['.jpg', '.png', '.pdf'],
- *   maxDepth: 3
- * }
- * ```
- */
-export interface PathTraversalConfig {
-    /** Block requests on path traversal detection */
-    blockOnDetection?: boolean;
-    /** Allowed base paths */
-    allowedPaths?: string[];
-    /** Allowed file extensions */
-    allowedExtensions?: string[];
-    /** Maximum allowed path depth */
-    maxDepth?: number;
-    /** Strict mode */
-    strictMode?: boolean;
-    /** Log detected attempts */
-    logAttempts?: boolean;
-    /** False positive threshold (0-1) */
-    falsePositiveThreshold?: number;
-}
-/**
- * Command Injection Protection Configuration
- *
- * Detects and prevents OS command injection attacks with context awareness.
- *
- * @example Enable with defaults:
- * ```typescript
- * commandInjection: true
- * ```
- *
- * @example Custom configuration:
- * ```typescript
- * commandInjection: {
- *   blockOnDetection: true,
- *   contextualAnalysis: true,
- *   allowedCommands: ['git', 'npm']
- * }
- * ```
- */
-export interface CommandInjectionConfig {
-    /** Block requests on command injection detection */
-    blockOnDetection?: boolean;
-    /** Enable contextual analysis */
-    contextualAnalysis?: boolean;
-    /** Allowed commands (whitelist) */
-    allowedCommands?: string[];
-    /** Strict mode */
-    strictMode?: boolean;
-    /** Log detected attempts */
-    logAttempts?: boolean;
-    /** False positive threshold (0-1) */
-    falsePositiveThreshold?: number;
-}
-/**
- * XXE (XML External Entity) Protection Configuration
- *
- * Prevents XXE attacks in XML parsing.
- *
- * @example Enable with defaults:
- * ```typescript
- * xxe: true
- * ```
- *
- * @example Custom configuration:
- * ```typescript
- * xxe: {
- *   blockOnDetection: true,
- *   allowDTD: false,
- *   allowExternalEntities: false
- * }
- * ```
- */
-export interface XXEConfig {
-    /** Block requests on XXE detection */
-    blockOnDetection?: boolean;
-    /** Allow DTD declarations */
-    allowDTD?: boolean;
-    /** Allow external entities */
-    allowExternalEntities?: boolean;
-    /** Maximum entity expansions */
-    maxEntityExpansions?: number;
-    /** Strict mode */
-    strictMode?: boolean;
-    /** Log detected attempts */
-    logAttempts?: boolean;
-}
-/**
- * LDAP Injection Protection Configuration
- *
- * Detects and prevents LDAP injection attacks.
- *
- * @example Enable with defaults:
- * ```typescript
- * ldapInjection: true
- * ```
- *
- * @example Custom configuration:
- * ```typescript
- * ldapInjection: {
- *   blockOnDetection: true,
- *   strictMode: true
- * }
- * ```
- */
-export interface LDAPInjectionConfig {
-    /** Block requests on LDAP injection detection */
-    blockOnDetection?: boolean;
-    /** Strict mode */
-    strictMode?: boolean;
-    /** Log detected attempts */
-    logAttempts?: boolean;
-    /** False positive threshold (0-1) */
-    falsePositiveThreshold?: number;
-}
-/**
- * Compression Configuration
- *
- * Response compression to reduce bandwidth and improve performance.
- * Can be enabled/disabled or configured with custom compression settings.
- *
- * @example Enable with defaults:
- * ```typescript
- * compression: true
- * ```
- *
- * @example Custom compression:
- * ```typescript
- * compression: {
- *   level: 6, // compression level (1-9)
- *   threshold: 1024, // minimum response size to compress
- *   filter: (req, res) => {
- *     // custom filter logic
- *     return /json|text|javascript|css/.test(res.get('Content-Type'));
- *   }
- * }
- * ```
- */
-export interface CompressionConfig {
-    /** Compression level (1-9) */
-    level?: number;
-    /** Minimum response size to compress (in bytes) */
-    threshold?: number;
-    /** Custom filter function for compression */
-    filter?: (req: any, res: any) => boolean;
-}
-/**
- * HTTP Parameter Pollution Protection Configuration
- *
- * Prevents HTTP Parameter Pollution attacks by handling duplicate parameters.
- * Can be enabled/disabled or configured with custom parameter handling.
- *
- * @example Enable with defaults:
- * ```typescript
- * hpp: true
- * ```
- *
- * @example Custom configuration:
- * ```typescript
- * hpp: {
- *   whitelist: ['tags', 'categories'], // allow arrays for these params
- *   checkQuery: true,
- *   checkBody: true
- * }
- * ```
- */
-export interface HPPConfig {
-    /** Whitelist of allowed parameters for arrays */
-    whitelist?: string[];
-    /** Check query parameters for duplicates */
-    checkQuery?: boolean;
-    /** Check body parameters for duplicates */
-    checkBody?: boolean;
-}
-/**
- * MongoDB Injection Protection Configuration
- *
- * Sanitizes MongoDB queries to prevent NoSQL injection attacks.
- * Can be enabled/disabled or configured with custom sanitization rules.
- *
- * @example Enable with defaults:
- * ```typescript
- * mongoSanitize: true
- * ```
- *
- * @example Custom configuration:
- * ```typescript
- * mongoSanitize: {
- *   replaceWith: '_',
- *   onSanitize: ({ req, key }) => {
- *     console.warn(`Sanitized MongoDB key: ${key} from ${req.ip}`);
- *   }
- * }
- * ```
- */
-export interface MongoSanitizeConfig {
-    /** Replacement character for sanitized keys */
-    replaceWith?: string;
-    /** Custom callback function for sanitization */
-    onSanitize?: (options: {
-        req: any;
-        key: string;
-    }) => void;
-}
-/**
- * @deprecated Morgan is not supported in XyPriss.
- * Using morgan may expose your application to undocumented behaviors and integration
- * failures with the XHSC engine. This type is kept only to surface a compile-time
- * error when used; it will always fail at runtime.
- *
- * Use the Xyphra plugin for secure, native request logging:
- * @see https://github.com/Nehonix-Team/xyphra
- */
-export interface MorganConfig {
-    /** @deprecated See MorganConfig */
-    [key: string]: never;
-}
-/**
- * Slow Down Configuration
- *
- * Progressive delays for rate limiting to prevent abuse.
- * Can be enabled/disabled or configured with custom delay patterns.
- *
- * @example Enable with defaults:
- * ```typescript
- * slowDown: true
- * ```
- *
- * @example Custom slow down:
- * ```typescript
- * slowDown: {
- *   windowMs: 15 * 60 * 1000, // 15 minutes
- *   delayAfter: 100, // delay after 100 requests
- *   delayMs: (used, req) => {
- *     const delayAfter = req.slowDown?.limit || 100;
- *     return (used - delayAfter) * 500; // 500ms per request over limit
- *   }
- * }
- * ```
- */
-export interface SlowDownConfig {
-    /** Time window for slow down (in milliseconds) */
-    windowMs?: number;
-    /** Number of requests before delay starts */
-    delayAfter?: number;
-    /** Custom delay function */
-    delayMs?: (used: number, req: any) => number;
-}
-/**
- * Route pattern matching configuration for security rules
- */
-export interface RoutePattern {
-    /** Route path pattern (supports wildcards like /api/*, exact paths like /login, or regex) */
-    path: string | RegExp;
-    /** HTTP methods to apply this rule to (if not specified, applies to all methods) */
-    methods?: string[];
-}
-/**
- * Security module route configuration
- * Allows selective application of security modules to specific routes
- */
-export interface SecurityModuleRouteConfig {
-    /** Routes to exclude from this security module */
-    excludeRoutes?: (string | RegExp | RoutePattern)[];
-    /** Routes to include for this security module (if specified, only these routes will be protected) */
-    includeRoutes?: (string | RegExp | RoutePattern)[];
-}
-/**
- * Security Configuration Interface
- *
- * Defines comprehensive security settings for XyPriss applications.
- * Each security feature can be enabled/disabled or configured with detailed options.
- *
- * @example
- * ```typescript
- * const securityConfig: SecurityConfig = {
- *   level: 'enhanced',
- *   helmet: {
- *     contentSecurityPolicy: {
- *       directives: { defaultSrc: ["'self'"] }
- *     }
- *   },
- *   cors: {
- *     origin: 'https://myapp.com',
- *     credentials: true
- *   },
- *   bruteForce: {
- *     windowMs: 15 * 60 * 1000,
- *     max: 100
- *   },
- *   routeConfig: {
- *     pathTraversal: {
- *       excludeRoutes: ['/api/templates/*', '/api/content/*']
- *     }
- *   }
- * };
- * ```
- */
-export interface SecurityConfig {
-    /**
-     * Strategic route bypass configuration.
-     * Routes defined here will bypass content-based security detectors (XSS, SQLi, Path Traversal, etc.).
-     * This is recommended for routes handling rich text or complex payloads where false positives are likely.
-     * Access control policies (CORS, Device restrictions, Signatures) remain active.
-     */
-    _ignore?: (string | RegExp)[];
-    /**
-     * Absolute route bypass configuration.
-     * Routes defined here will bypass the ENTIRE security middleware stack, including device restrictions,
-     * request signatures, and content detectors. Use with extreme caution.
-     */
-    _ignoreAll?: (string | RegExp)[];
-    /** Security level preset */
-    level?: SecurityLevel;
-    /**
-     * Route-based security configuration
-     * Allows you to selectively apply security modules to specific routes
-     *
-     * @example
-     * ```typescript
-     * routeConfig: {
-     *   xss: {
-     *     excludeRoutes: ['/api/safe-content/*']
-     *   },
-     *   pathTraversal: {
-     *     excludeRoutes: ['/api/templates/*', { path: '/api/content/*', methods: ['POST'] }]
-     *   },
-     *   sqlInjection: {
-     *     includeRoutes: ['/api/db/*', '/api/query/*']
-     *   }
-     * }
-     * ```
-     */
-    routeConfig?: {
-        xss?: SecurityModuleRouteConfig;
-        sqlInjection?: SecurityModuleRouteConfig;
-        pathTraversal?: SecurityModuleRouteConfig;
-        commandInjection?: SecurityModuleRouteConfig;
-        xxe?: SecurityModuleRouteConfig;
-        ldapInjection?: SecurityModuleRouteConfig;
-    };
-    /**
-     * CSRF Protection Configuration
-     *
-     * Protects against Cross-Site Request Forgery attacks by requiring tokens.
-     * Can be enabled/disabled or configured with custom options.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * csrf: true
-     * ```
-     *
-     * @example Disable:
-     * ```typescript
-     * csrf: false
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * csrf: {
-     *   cookieName: '__Host-csrf-token',
-     *   cookieOptions: {
-     *     httpOnly: true,
-     *     sameSite: 'strict',
-     *     secure: process.env.NODE_ENV === 'production'
-     *   }
-     * }
-     * ```
-     */
-    csrf?: boolean | CSRFConfig;
-    /**
-     * Helmet Security Headers Configuration
-     *
-     * Sets various HTTP headers to help protect against common attacks.
-     * Can be enabled/disabled or configured with custom header options.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * helmet: true
-     * ```
-     *
-     * @example Custom CSP:
-     * ```typescript
-     * helmet: {
-     *   contentSecurityPolicy: {
-     *     directives: {
-     *       defaultSrc: ["'self'"],
-     *       scriptSrc: ["'self'", "'unsafe-inline'"]
-     *     }
-     *   },
-     *   hsts: { maxAge: 31536000 }
-     * }
-     * ```
-     */
-    helmet?: boolean | HelmetConfig;
-    /**
-     * XSS Protection Configuration
-     *
-     * Protects against Cross-Site Scripting attacks by sanitizing input.
-     * Can be enabled/disabled or configured with custom sanitization rules.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * xss: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * xss: {
-     *   blockOnDetection: true,
-     *   customPatterns: [/custom-pattern/g],
-     *   whitelist: { a: ['href', 'title'] }
-     * }
-     * ```
-     */
-    xss?: boolean | XSSConfig;
-    /**
-     * SQL Injection Protection Configuration
-     *
-     * Detects and prevents SQL injection attacks in request data.
-     * Can be enabled/disabled or configured with custom detection rules.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * sqlInjection: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * sqlInjection: {
-     *   blockOnDetection: true,
-     *   riskThreshold: 'medium',
-     *   customPatterns: [/custom-sql-pattern/g]
-     * }
-     * ```
-     */
-    sqlInjection?: boolean | SQLInjectionConfig;
-    /**
-     * Path Traversal Protection Configuration
-     *
-     * Detects and prevents directory traversal attacks while allowing legitimate file paths.
-     * Can be enabled/disabled or configured with custom detection rules.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * pathTraversal: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * pathTraversal: {
-     *   blockOnDetection: true,
-     *   allowedPaths: ['/uploads/', '/public/'],
-     *   allowedExtensions: ['.jpg', '.png', '.pdf'],
-     *   maxDepth: 3
-     * }
-     * ```
-     */
-    pathTraversal?: boolean | PathTraversalConfig;
-    /**
-     * Command Injection Protection Configuration
-     *
-     * Detects and prevents OS command injection attacks with context awareness.
-     * Can be enabled/disabled or configured with custom detection rules.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * commandInjection: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * commandInjection: {
-     *   blockOnDetection: true,
-     *   contextualAnalysis: true,
-     *   allowedCommands: ['git', 'npm']
-     * }
-     * ```
-     */
-    commandInjection?: boolean | CommandInjectionConfig;
-    /**
-     * XXE (XML External Entity) Protection Configuration
-     *
-     * Prevents XXE attacks in XML parsing.
-     * Can be enabled/disabled or configured with custom detection rules.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * xxe: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * xxe: {
-     *   blockOnDetection: true,
-     *   allowDTD: false,
-     *   allowExternalEntities: false
-     * }
-     * ```
-     */
-    xxe?: boolean | XXEConfig;
-    /**
-     * LDAP Injection Protection Configuration
-     *
-     * Detects and prevents LDAP injection attacks.
-     * Can be enabled/disabled or configured with custom detection rules.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * ldapInjection: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * ldapInjection: {
-     *   blockOnDetection: true,
-     *   strictMode: true
-     * }
-     * ```
-     */
-    ldapInjection?: boolean | LDAPInjectionConfig;
-    /**
-     * Brute Force Protection Configuration
-     *
-     * Specialized protection against brute force attacks on authentication endpoints.
-     * More aggressive than general rate limiting, designed for login/password attempts.
-     * Can be enabled/disabled or configured with custom protection rules.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * bruteForce: true
-     * ```
-     *
-     * @example Custom brute force protection:
-     * ```typescript
-     * bruteForce: {
-     *   windowMs: 15 * 60 * 1000, // 15 minutes
-     *   max: 5, // only 5 attempts per window (stricter than rateLimit)
-     *   message: 'Too many login attempts, account temporarily locked.',
-     *   standardHeaders: true
-     * }
-     * ```
-     */
-    bruteForce?: boolean | RateLimitConfig;
-    /**
-     * Honeypot Tarpit Configuration (Bot & Scanner Neutralization)
-     *
-     * Instantly blocks vulnerability scanners by performing an ultra-fast O(1)
-     * lookup on common malicious payload signatures (e.g., `/.env`, `/.git`).
-     * Prevents wasted CPU cycles from regex ReDoS and framework routing.
-     * By default, this is implicitly **TRUE**.
-     *
-     * @example Disable honeypot tarpit (Not recommended)
-     * ```typescript
-     * honeypotTarpit: false
-     * ```
-     */
-    honeypotTarpit?: boolean;
-    /**
-     * Rate Limiting Configuration
-     *
-     * General rate limiting to prevent abuse and control request frequency.
-     * Can be enabled/disabled or configured with custom rate limiting rules.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * rateLimit: true
-     * ```
-     *
-     * @example Custom rate limiting:
-     * ```typescript
-     * rateLimit: {
-     *   windowMs: 15 * 60 * 1000, // 15 minutes
-     *   max: 100, // limit each IP to 100 requests per windowMs
-     *   message: 'Too many requests, please try again later.',
-     *   standardHeaders: true
-     * }
-     * ```
-     */
-    rateLimit?: boolean | RateLimitConfig;
-    /**
-     * CORS Configuration
-     *
-     * Cross-Origin Resource Sharing settings for API access control.
-     * Can be enabled/disabled or configured with custom CORS policies.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * cors: true
-     * ```
-     *
-     * @example Custom CORS policy:
-     * ```typescript
-     * cors: {
-     *   origin: ['https://myapp.com', 'https://admin.myapp.com'],
-     *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
-     *   allowedHeaders: ['Content-Type', 'Authorization'],
-     *   credentials: true,
-     *   maxAge: 86400
-     * }
-     * ```
-     */
-    cors?: boolean | CORSConfig;
-    /**
-     * Compression Configuration
-     *
-     * Response compression to reduce bandwidth and improve performance.
-     * Can be enabled/disabled or configured with custom compression settings.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * compression: true
-     * ```
-     *
-     * @example Custom compression:
-     * ```typescript
-     * compression: {
-     *   level: 6, // compression level (1-9)
-     *   threshold: 1024, // minimum response size to compress
-     *   filter: (req, res) => {
-     *     // custom filter logic
-     *     return /json|text|javascript|css/.test(res.get('Content-Type'));
-     *   }
-     * }
-     * ```
-     */
-    compression?: boolean | CompressionConfig;
-    /**
-     * HTTP Parameter Pollution Protection Configuration
-     *
-     * Prevents HTTP Parameter Pollution attacks by handling duplicate parameters.
-     * Can be enabled/disabled or configured with custom parameter handling.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * hpp: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * hpp: {
-     *   whitelist: ['tags', 'categories'], // allow arrays for these params
-     *   checkQuery: true,
-     *   checkBody: true
-     * }
-     * ```
-     */
-    hpp?: boolean | HPPConfig;
-    /**
-     * MongoDB Injection Protection Configuration
-     *
-     * Sanitizes MongoDB queries to prevent NoSQL injection attacks.
-     * Can be enabled/disabled or configured with custom sanitization rules.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * mongoSanitize: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * mongoSanitize: {
-     *   replaceWith: '_',
-     *   onSanitize: ({ req, key }) => {
-     *     console.warn(`Sanitized MongoDB key: ${key} from ${req.ip}`);
-     *   }
-     * }
-     * ```
-     */
-    mongoSanitize?: boolean | MongoSanitizeConfig;
-    /**
-     * @deprecated Morgan is not supported in XyPriss. This field has no effect and
-     * will be removed in a future version.
-     *
-     * Using morgan in a XyPriss application may expose your application to undocumented
-     * internal behaviors, telemetry risks, and integration failures with the XHSC engine.
-     *
-     * Use the Xyphra plugin for secure, native request logging:
-     * @see https://github.com/Nehonix-Team/xyphra
-     *
-     * @example Correct approach:
-     * ```typescript
-     * plugins: {
-     *   register: [
-     *     XyphraPlugin({ anonymizeIp: true })
-     *   ]
-     * }
-     * ```
-     */
-    morgan?: never;
-    /**
-     * Slow Down Configuration
-     *
-     * Progressive delays for rate limiting to prevent abuse.
-     * Can be enabled/disabled or configured with custom delay patterns.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * slowDown: true
-     * ```
-     *
-     * @example Custom slow down:
-     * ```typescript
-     * slowDown: {
-     *   windowMs: 15 * 60 * 1000, // 15 minutes
-     *   delayAfter: 100, // delay after 100 requests
-     *   delayMs: (used, req) => {
-     *     const delayAfter = req.slowDown?.limit || 100;
-     *     return (used - delayAfter) * 500; // 500ms per request over limit
-     *   }
-     * }
-     * ```
-     */
-    slowDown?: boolean | SlowDownConfig;
-    /** Encryption configuration */
-    encryption?: EncryptionConfig;
-    /** Authentication configuration */
-    authentication?: AuthenticationConfig;
-    /**
-     * Browser-Only Protection Configuration
-     *
-     * Blocks non-browser requests (cURL, Postman, scripts) while allowing legitimate browser access.
-     * Useful for APIs that should only be accessed through web browsers.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * browserOnly: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * browserOnly: {
-     *   requireSecFetch: true,
-     *   blockAutomationTools: true,
-     *   allowOriginRequests: true,
-     *   errorMessage: "Browser access required"
-     * }
-     * ```
-     */
-    browserOnly?: boolean | BrowserOnlyConfig;
-    /**
-     * Terminal-Only Protection Configuration
-     *
-     * Blocks browser requests while allowing terminal/API tools.
-     * Perfect for API-only endpoints or development tools.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * terminalOnly: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * terminalOnly: {
-     *   blockSecFetch: true,
-     *   allowedTools: ["curl", "wget"],
-     *   blockBrowserIndicators: true,
-     *   debug: true
-     * }
-     * ```
-     */
-    terminalOnly?: boolean | TerminalOnlyConfig;
-    /**
-     * Mobile-Only Protection Configuration
-     *
-     * Blocks browser requests while allowing mobile app access.
-     * Perfect for APIs that should only be accessed through mobile applications.
-     *
-     * @example Enable with defaults:
-     * ```typescript
-     * mobileOnly: true
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * mobileOnly: {
-     *   blockBrowserIndicators: true,
-     *   allowedPlatforms: ['ios', 'android'],
-     *   requireMobileHeaders: true,
-     *   customUserAgentPatterns: [/MyApp/i],
-     *   errorMessage: "Mobile app access required"
-     * }
-     * ```
-     */
-    mobileOnly?: boolean | import("../../middleware/built-in/security/MobileOnlyProtector").MobileOnlyConfig;
-    /**
-     * Device Access Control Configuration
-     *
-     * Comprehensive device-based access control allowing multiple device types.
-     * Enables fine-grained control over which devices can access your API.
-     *
-     * @example Allow only mobile apps:
-     * ```typescript
-     * deviceAccess: {
-     *   mobileOnly: true
-     * }
-     * ```
-     *
-     * @example Allow mobile apps and browsers:
-     * ```typescript
-     * deviceAccess: {
-     *   mobileOnly: true,
-     *   browserOnly: true
-     * }
-     * ```
-     *
-     * @example Allow all except browsers:
-     * ```typescript
-     * deviceAccess: {
-     *   mobileOnly: true,
-     *   terminalOnly: true,
-     *   browserOnly: false
-     * }
-     * ```
-     */
-    deviceAccess?: {
-        /** Allow only browser requests */
-        browserOnly?: boolean | BrowserOnlyConfig;
-        /** Allow only terminal/API tool requests */
-        terminalOnly?: boolean | TerminalOnlyConfig;
-        /** Allow only mobile app requests */
-        mobileOnly?: boolean | import("../../middleware/built-in/security/MobileOnlyProtector").MobileOnlyConfig;
-    };
-    /**
-     * XyRS - XyPriss Request Signature Configuration
-     *
-     * Validates request signatures using the XP-Request-Sig header.
-     * Provides API authentication by requiring a secret signature on all requests.
-     *
-     * @example Enable with secret:
-     * ```typescript
-     * requestSignature: {
-     *   secret: "my-secret-api-key"
-     * }
-     * ```
-     *
-     * @example Custom configuration:
-     * ```typescript
-     * requestSignature: {
-     *   secret: "my-secret-api-key",
-     *   errorMessage: "API key required",
-     *   statusCode: 403,
-     *   caseSensitive: false
-     * }
-     * ```
-     */
-    requestSignature?: boolean | RequestSignatureConfig;
-}
-/**
- * Encryption configuration interface.
- *
- * Settings for data encryption including algorithm
- * selection and key management.
- *
- * @interface EncryptionConfig
- *
- * @example
- * ```typescript
- * const encryptionConfig: EncryptionConfig = {
- *   algorithm: 'aes-256-gcm',
- *   keySize: 256
- * };
- * ```
- */
-export interface EncryptionConfig {
-    /** Encryption algorithm to use */
-    algorithm?: string;
-    /** Key size in bits */
-    keySize?: number;
-}
-/**
- * Authentication configuration interface.
- *
- * Configuration for various authentication methods
- * including JWT and session-based authentication.
- *
- * @interface AuthenticationConfig
- *
- * @example
- * ```typescript
- * const authConfig: AuthenticationConfig = {
- *   jwt: {
- *     secret: 'your-jwt-secret',
- *     expiresIn: '24h',
- *     algorithm: 'HS256',
- *     issuer: 'your-app',
- *     audience: 'your-users'
- *   },
- *   session: {
- *     secret: 'your-session-secret',
- *     name: 'sessionId',
- *     cookie: {
- *       maxAge: 86400000, // 24 hours
- *       secure: true,
- *       httpOnly: true,
- *       sameSite: 'strict'
- *     }
- *   }
- * };
- * ```
- */
-export interface AuthenticationConfig {
-    /** JWT authentication configuration */
-    jwt?: JWTConfig;
-    /** Session authentication configuration */
-    session?: SessionConfig;
-}
-/**
- * JWT (JSON Web Token) configuration interface.
- *
- * Configuration for JWT-based authentication including
- * signing algorithms and token validation.
- *
- * @interface JWTConfig
- *
- * @example
- * ```typescript
- * const jwtConfig: JWTConfig = {
- *   secret: 'your-256-bit-secret',
- *   expiresIn: '24h',
- *   algorithm: 'HS256',
- *   issuer: 'your-application',
- *   audience: 'your-users'
- * };
- * ```
- */
-export interface JWTConfig {
-    /** Secret key for signing tokens */
-    secret: string;
-    /** Token expiration time (e.g., '24h', '7d', '30m') */
-    expiresIn?: string;
-    /** Signing algorithm */
-    algorithm?: string;
-    /** Token issuer */
-    issuer?: string;
-    /** Token audience */
-    audience?: string;
-}
-/**
- * Session configuration interface.
- *
- * Configuration for session-based authentication including
- * cookie settings and storage options.
- *
- * @interface SessionConfig
- *
- * @example
- * ```typescript
- * const sessionConfig: SessionConfig = {
- *   secret: 'your-session-secret',
- *   name: 'connect.sid',
- *   cookie: {
- *     maxAge: 86400000, // 24 hours
- *     secure: true,
- *     httpOnly: true,
- *     sameSite: 'strict'
- *   },
- *   store: 'redis'
- * };
- * ```
- */
-export interface SessionConfig {
-    /** Secret for signing session cookies */
-    secret: string;
-    /** Session cookie name */
-    name?: string;
-    /** Cookie configuration */
-    cookie?: SessionCookieConfig;
-    /** Session store type */
-    store?: "memory" | "redis" | "custom";
-}
-/**
- * Session cookie configuration interface.
- *
- * Detailed configuration for session cookies including
- * security and expiration settings.
- *
- * @interface SessionCookieConfig
- *
- * @example
- * ```typescript
- * const cookieConfig: SessionCookieConfig = {
- *   maxAge: 86400000, // 24 hours
- *   secure: true,
- *   httpOnly: true,
- *   sameSite: 'strict'
- * };
- * ```
- */
-export interface SessionCookieConfig {
-    /** Cookie expiration time in milliseconds */
-    maxAge?: number;
-    /** Require HTTPS for cookie transmission */
-    secure?: boolean;
-    /** Prevent client-side JavaScript access */
-    httpOnly?: boolean;
-    /** SameSite cookie attribute */
-    sameSite?: boolean | "lax" | "strict" | "none";
-}
-/**
- * SSL/TLS configuration interface.
- *
- * Configuration for SSL/TLS encryption including
- * certificates and security options.
- *
- * @interface SSLConfig
- *
- * @example
- * ```typescript
- * const sslConfig: SSLConfig = {
- *   key: fs.readFileSync('path/to/private-key.pem', 'utf8'),
- *   cert: fs.readFileSync('path/to/certificate.pem', 'utf8'),
- *   ca: fs.readFileSync('path/to/ca-certificate.pem', 'utf8'),
- *   passphrase: 'your-passphrase'
- * };
- * ```
- */
-export interface SSLConfig {
-    /** Private key for SSL certificate */
-    key: string;
-    /** SSL certificate */
-    cert: string;
-    /** Certificate Authority certificate */
-    ca?: string;
-    /** Passphrase for private key */
-    passphrase?: string;
-}
-/**
- * CORS (Cross-Origin Resource Sharing) configuration interface.
- *
- * Configuration for CORS policies including allowed origins,
- * methods, and headers.
- *
- * By default, all headers are allowed to be developer-friendly.
- * You can restrict headers by specifying the allowedHeaders array.
- *
- * @interface CORSConfig
- *
- * @example
- * ```typescript
- * // Allow all origins (default - developer-friendly)
- * const corsConfig: CORSConfig = {
- *   origin: '*',
- *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
- *   credentials: true
- * };
- *
- * // Restrict specific origins (production)
- * const restrictiveCorsConfig: CORSConfig = {
- *   origin: ['https://example.com', 'https://app.example.com'],
- *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
- *   allowedHeaders: ['Content-Type', 'Authorization'],
- *   credentials: true
- * };
- *
- * // Advanced patterns with RegExp (powerful and flexible)
- * const advancedCorsConfig: CORSConfig = {
- *   origin: [
- *     /^localhost:\d+$/,           // localhost:3000, localhost:8080, etc.
- *     /^127\.0\.0\.1:\d+$/,        // 127.0.0.1:3000, etc.
- *     /^::1:\d+$/,                 // IPv6 localhost
- *     /\.test\.com$/,              // *.test.com
- *     'https://production.com'     // Exact match
- *   ],
- *   methods: ['GET', 'POST'],
- *   credentials: true
- * };
- * ```
- */
-export interface CORSConfig {
-    /** Allowed origins - can be string, RegExp, array of mixed types, or boolean */
-    origin?: string | RegExp | (string | RegExp)[] | boolean;
-    /** Allowed HTTP methods */
-    methods?: string[];
-    /**
-     * Allowed headers - if not specified, all headers are allowed by default.
-     * Specify this array to restrict which headers are allowed.
-     */
-    allowedHeaders?: string[];
-    /** Allow credentials in CORS requests */
-    credentials?: boolean;
-}
-/**
- * Rate limiting configuration interface.
- *
- * Configuration for rate limiting including time windows,
- * request limits, and custom messages.
- *
- * @interface RateLimitConfig
- *
- * @example
- * ```typescript
- * // String message
- * const rateLimitConfig: RateLimitConfig = {
- *   windowMs: 900000, // 15 minutes
- *   max: 100, // 100 requests per window
- *   message: 'Too many requests, please try again later',
- *   standardHeaders: true,
- *   legacyHeaders: false
- * };
- *
- * // Object message (more flexible)
- * const rateLimitConfig: RateLimitConfig = {
- *   windowMs: 900000,
- *   max: 100,
- *   message: {
- *     error: 'Rate limit exceeded',
- *     message: 'Too many requests, please try again later',
- *     retryAfter: 900
- *   },
- *   standardHeaders: true,
- *   legacyHeaders: false
- * };
- * ```
- */
-export interface RateLimitConfig {
-    /** Time window in milliseconds */
-    windowMs?: number;
-    /** Maximum requests per window */
-    max?: number;
-    /** Message to send when limit is exceeded (string or object) */
-    message?: string | {
-        error?: string;
-        message?: string;
-        retryAfter?: number;
-        [key: string]: any;
-    };
-    /** Include standard rate limit headers */
-    standardHeaders?: boolean;
-    /** Include legacy rate limit headers */
-    legacyHeaders?: boolean;
-    /**
-     * Custom function to determine if a request should be skipped by the rate limiter.
-     *
-     * @param req The incoming request object
-     * @param res The server response object
-     * @returns {boolean} True if the request should bypass rate limiting, false otherwise.
-     *
-     * @note IMPORTANT: If this function is provided, the `excludePaths` setting is
-     * ignored by default (it behaves as if `excludePaths` was empty) to prevent
-     * conflicting exclusion rules.
-     *
-     * @example
-     * ```typescript
-     * skip: (req) => req.path.startsWith('/public/') || req.ip === '127.0.0.1'
-     * ```
-     */
-    skip?: (req: any, res: any) => boolean;
-    /**
-     * List of paths or patterns to exclude from rate limiting.
-     *
-     * @type {(string | RegExp)[]}
-     *
-     * - Strings starting with '/' are matched exactly or as a prefix.
-     * - Regular expressions are tested against the `req.path`.
-     *
-     * @note By default, XyPriss excludes common endpoints like `/health`, `/ping`,
-     * and static asset folders (`/static/`, `/assets/`).
-     *
-     * @warning This property is ignored if a `skip` function is defined.
-     *
-     * @example
-     * ```typescript
-     * excludePaths: ['/api/v1/status', /^\/internal\//]
-     * ```
-     */
-    excludePaths?: (string | RegExp)[];
-}
-/**
- * Route-specific security configuration interface.
- *
- * Security settings that can be applied to individual
- * routes or route groups.
- *
- * @interface RouteSecurityConfig
- *
- * @example
- * ```typescript
- * const routeSecurityConfig: RouteSecurityConfig = {
- *   auth: true,
- *   roles: ['admin', 'moderator'],
- *   permissions: ['read:users', 'write:posts'],
- *   encryption: true,
- *   sanitization: true,
- *   validation: true
- * };
- * ```
- */
-export interface RouteSecurityConfig {
-    /** Require authentication */
-    auth?: boolean;
-    /** Required user roles */
-    roles?: string[];
-    /** Required permissions */
-    permissions?: string[];
-    /** Enable response encryption */
-    encryption?: boolean;
-    /** Enable input sanitization */
-    sanitization?: boolean;
-    /** Enable input validation */
-    validation?: boolean;
-}
-//# sourceMappingURL=security.d.ts.map