xypriss 3.0.0 → 3.2.0

package/dist/index.d.ts

@@ -1665,63 +1665,50 @@ interface CacheStrategy {
 }
 
 /**
- * @fileoverview Security-related type definitions for XyPrissJS Express 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
- */
-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.
+ * Mobile-Only Access Protector
+ * Blocks browser requests and allows only mobile app access.
+ * Multi-layered detection with strict validation to avoid false positives.
  *
  * @example Enable with defaults:
  * ```typescript
- * csrf: true
- * ```
- *
- * @example Disable:
- * ```typescript
- * csrf: false
+ * mobileOnly: true
  * ```
  *
  * @example Custom configuration:
  * ```typescript
- * csrf: {
- *   cookieName: '__Host-csrf-token',
- *   cookieOptions: {
- *     httpOnly: true,
- *     sameSite: 'strict',
- *     secure: process.env.NODE_ENV === 'production'
- *   }
+ * mobileOnly: {
+ *   blockBrowserIndicators: true,
+ *   allowedPlatforms: ['ios', 'android'],
+ *   requireMobileHeaders: true,
+ *   customUserAgentPatterns: [/MyApp/i],
+ *   errorMessage: "Mobile app access required"
  * }
  * ```
  */
-interface CSRFConfig {
-    /** CSRF token cookie name */
-    cookieName?: string;
-    /** CSRF token cookie options */
-    cookieOptions?: {
-        httpOnly?: boolean;
-        sameSite?: boolean | "lax" | "strict" | "none";
-        secure?: boolean;
-    };
+
+interface MobileOnlyConfig {
+    /** Enable/disable mobile-only protection */
+    enable?: boolean;
+    /** Block requests with browser indicators */
+    blockBrowserIndicators?: boolean;
+    /** Allowed mobile platforms */
+    allowedPlatforms?: ("ios" | "android" | "react-native" | "expo" | "flutter")[];
+    /** Require mobile-specific headers */
+    requireMobileHeaders?: boolean;
+    /** Custom User-Agent patterns to allow */
+    customUserAgentPatterns?: RegExp[];
+    /** Debug logging */
+    debug?: boolean;
+    /** Custom error message */
+    errorMessage?: string;
+    /** HTTP status code for blocked requests */
+    statusCode?: number;
+    /** Case-sensitive User-Agent matching */
+    caseSensitive?: boolean;
+    /** Trim whitespace from User-Agent */
+    trimUserAgent?: boolean;
 }
+
 /**
  * Browser-Only Protection Configuration
  *
@@ -1804,6 +1791,102 @@ interface TerminalOnlyConfig {
     /** Enable debug logging */
     debug?: boolean;
 }
+
+/**
+ * @fileoverview Security-related type definitions for XyPrissJS Express 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
+ */
+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'
+ *   }
+ * }
+ * ```
+ */
+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
+ * }
+ * ```
+ */
+interface RequestSignatureConfig {
+    /** The secret value that must match the XP-Request-Sig 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;
+}
 /**
  * Helmet Security Headers Configuration
  *
@@ -2714,6 +2797,91 @@ interface SecurityConfig {
      * ```
      */
     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 | 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 | 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.
@@ -2879,25 +3047,38 @@ interface SessionCookieConfig {
  *
  * @example
  * ```typescript
- * // Allow all headers (default - developer-friendly)
+ * // Allow all origins (default - developer-friendly)
  * const corsConfig: CORSConfig = {
  *   origin: '*',
  *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
  *   credentials: true
  * };
  *
- * // Restrict specific headers (production)
+ * // 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
+ * };
  * ```
  */
 interface CORSConfig {
-    /** Allowed origins - can be string, array of strings, or boolean */
-    origin?: string | string[] | boolean;
+    /** Allowed origins - can be string, RegExp, array of mixed types, or boolean */
+    origin?: string | RegExp | (string | RegExp)[] | boolean;
     /** Allowed HTTP methods */
     methods?: string[];
     /**
@@ -2918,6 +3099,7 @@ interface CORSConfig {
  *
  * @example
  * ```typescript
+ * // String message
  * const rateLimitConfig: RateLimitConfig = {
  *   windowMs: 900000, // 15 minutes
  *   max: 100, // 100 requests per window
@@ -2925,6 +3107,19 @@ interface CORSConfig {
  *   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
+ * };
  * ```
  */
 interface RateLimitConfig$1 {
@@ -2932,8 +3127,13 @@ interface RateLimitConfig$1 {
     windowMs?: number;
     /** Maximum requests per window */
     max?: number;
-    /** Message to send when limit is exceeded */
-    message?: string;
+    /** 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 */
@@ -4553,6 +4753,13 @@ declare class SecurityMiddleware {
     slowDown: boolean | SlowDownConfig;
     browserOnly: boolean | BrowserOnlyConfig;
     terminalOnly: boolean | TerminalOnlyConfig;
+    mobileOnly: boolean | MobileOnlyConfig;
+    deviceAccess?: {
+        browserOnly?: boolean | BrowserOnlyConfig;
+        terminalOnly?: boolean | TerminalOnlyConfig;
+        mobileOnly?: boolean | MobileOnlyConfig;
+    };
+    requestSignature: boolean | RequestSignatureConfig;
     encryption: Required<SecurityConfig>["encryption"];
     authentication: Required<SecurityConfig>["authentication"];
     routeConfig?: SecurityConfig["routeConfig"];
@@ -4563,6 +4770,8 @@ declare class SecurityMiddleware {
     private csrfMiddleware;
     private browserOnlyMiddleware;
     private terminalOnlyMiddleware;
+    private mobileOnlyMiddleware;
+    private requestSignatureMiddleware;
     private mongoSanitizeMiddleware;
     private hppMiddleware;
     private compressionMiddleware;
@@ -4575,6 +4784,7 @@ declare class SecurityMiddleware {
     private ldapInjectionDetector;
     private browserOnlyProtector?;
     private terminalOnlyProtector?;
+    private mobileOnlyProtector?;
     private logger;
     constructor(config?: SecurityConfig, logger?: Logger);
     /**
@@ -4619,6 +4829,22 @@ declare class SecurityMiddleware {
      * Check if terminal-only protection is enabled
      */
     private isTerminalOnlyEnabled;
+    /**
+     * Check if mobile-only protection is enabled
+     */
+    private isMobileOnlyEnabled;
+    /**
+     * Validate device access configuration
+     */
+    private validateDeviceAccessConfig;
+    /**
+     * Create combined middleware for browser and mobile access control
+     */
+    private createCombinedDeviceMiddleware;
+    /**
+     * Check if request is from a mobile device (using MobileOnlyProtector logic)
+     */
+    private isMobileRequest;
     /**
      * Get security configuration
      */
@@ -5214,7 +5440,7 @@ interface SecurityMiddlewareConfig {
         xssFilter?: boolean;
     };
     cors?: boolean | {
-        origin?: string | string[] | boolean;
+        origin?: string | RegExp | (string | RegExp)[] | boolean;
         methods?: string | string[];
         allowedHeaders?: string | string[];
         exposedHeaders?: string | string[];
@@ -5226,7 +5452,12 @@ interface SecurityMiddlewareConfig {
     rateLimit?: boolean | {
         windowMs?: number;
         max?: number;
-        message?: string;
+        message?: string | {
+            error?: string;
+            message?: string;
+            retryAfter?: number;
+            [key: string]: any;
+        };
         standardHeaders?: boolean;
         legacyHeaders?: boolean;
         store?: any;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xypriss",
-    "version": "3.0.0",
+    "version": "3.2.0",
     "description": "XyPriss is a lightweight, TypeScript-first, open-source Node.js web framework crafted for developers seeking a familiar Express-like API without Express dependencies. It features built-in security middleware, a robust routing system, and performance optimizations to build scalable, secure web applications effortlessly. Join our community and contribute on GitHub!",
     "main": "dist/cjs/index.js",
     "module": "dist/esm/index.js",