xypriss 9.3.71 → 9.4.0

package/dist/index.d.ts

@@ -136,8 +136,6 @@ interface FileUploadConfig {
     allowedExtensions?: string[];
     /** Upload destination directory */
     destination?: string;
-    /** Custom filename function */
-    filename?: (req: any, file: any, callback: (error: Error | null, filename: string) => void) => void;
     /** Detailed limits configuration */
     limits?: {
         /** Max field name size in bytes */
@@ -155,10 +153,8 @@ interface FileUploadConfig {
     };
     /** Preserve full paths instead of just filenames */
     preservePath?: boolean;
-    /** Custom file filter function */
-    fileFilter?: (req: any, file: any, callback: (error: Error | null, acceptFile: boolean) => void) => void;
     /** Storage type */
-    storage?: 'disk' | 'memory' | 'custom';
+    storage?: "disk" | "memory" | "custom";
     /** Create parent directories if they don't exist */
     createParentPath?: boolean;
     /** Abort request on limit reached */
@@ -173,29 +169,13 @@ interface FileUploadConfig {
     parseNested?: boolean;
     /** Enable debug logging */
     debug?: boolean;
-    /** Custom multer options */
-    multerOptions?: {
-        dest?: string;
-        storage?: any;
-        limits?: {
-            fieldNameSize?: number;
-            fieldSize?: number;
-            fields?: number;
-            fileSize?: number;
-            files?: number;
-            headerPairs?: number;
-        };
-        preservePath?: boolean;
-        fileFilter?: (req: any, file: any, callback: (error: Error | null, acceptFile: boolean) => void) => void;
-        [key: string]: any;
-    };
 }
 
 /**
- * @fileoverview Core type definitions for XyPrissJS Express integration
+ * @fileoverview Core type definitions for XyPriss integration
  *
  * This module contains fundamental types and utilities used throughout
- * the Express integration system.
+ * the XyPriss integration system.
  *
  * @version 4.5.11
  * @author XyPrissJS Team
@@ -370,9 +350,9 @@ interface ResponseManipulationConfig {
     maxDepth?: number;
 }
 /**
- * Enhanced Express request interface with additional utilities.
+ * Enhanced XyPriss request interface with additional utilities.
  *
- * Extends the standard Express Request with caching, security,
+ * Extends the standard XyPriss Request with caching, security,
  * performance, and validation utilities.
  *
  * @interface EnhancedRequest
@@ -447,9 +427,9 @@ interface EnhancedRequest extends XyPrisRequest {
     session?: SessionData;
 }
 /**
- * Enhanced Express response interface with additional utilities.
+ * Enhanced XyPriss response interface with additional utilities.
  *
- * Extends the standard Express Response with caching, security,
+ * Extends the standard XyPriss Response with caching, security,
  * performance, and convenience methods.
  *
  * @interface EnhancedResponse
@@ -537,7 +517,7 @@ type RouteHandler$1 = (req: EnhancedRequest, res: EnhancedResponse, next: NextFu
 type MiddlewareFunction$1 = (req: EnhancedRequest, res: EnhancedResponse, next: NextFunction) => Promise<void> | void;
 
 /**
- * @fileoverview Cache-related type definitions for XyPrissJS Express integration
+ * @fileoverview Cache-related type definitions for XyPriss integration
  *
  * This module contains all cache-related types including configuration,
  * strategies, metrics, and backend implementations.
@@ -1036,7 +1016,7 @@ interface TerminalOnlyConfig {
 }
 
 /**
- * @fileoverview Security-related type definitions for XyPrissJS Express integration
+ * @fileoverview Security-related type definitions for XyPriss integration
  *
  * This module contains all security-related types including authentication,
  * authorization, encryption, and security policies.
@@ -2485,7 +2465,7 @@ interface RouteSecurityConfig {
 }
 
 /**
- * @fileoverview Performance-related type definitions for XyPrissJS Express integration
+ * @fileoverview Performance-related type definitions for XyPriss integration
  *
  * This module contains all performance-related types including monitoring,
  * optimization, metrics, and configuration.
@@ -2575,7 +2555,7 @@ interface AlertConfig {
 }
 
 /**
- * @fileoverview Routing-related type definitions for XyPrissJS Express integration
+ * @fileoverview Routing-related type definitions for XyPriss integration
  *
  * This module contains all routing-related types including route configuration,
  * caching, security, validation, and optimization.
@@ -3010,6 +2990,75 @@ declare class PathApi extends BaseApi {
      * console.log(clean); // -> "/users/john/images"
      */
     $normalize: (p: string) => string;
+    /**
+     * **Check Child Path Relationship**
+     *
+     * Determines if a given `child` path is strictly contained within a `parent` directory.
+     * This is a critical security utility for verifying that file operations remain
+     * within authorized boundaries.
+     *
+     * @param {string} parent - The expected parent directory.
+     * @param {string} child - The path to check.
+     * @returns {boolean} True if child is inside parent.
+     */
+    $isChild: (parent: string, child: string) => boolean;
+    /**
+     * **Secure Path Join**
+     *
+     * Joins path segments and ensures the result is strictly within the `base` path.
+     * If the resulting path attempts to escape via traversal (e.g., `../`), it
+     * throws a security error or returns a safe path.
+     *
+     * @param {string} base - The root/base directory.
+     * @param {...string[]} segments - The segments to join.
+     * @returns {string} The joined, safe path.
+     */
+    $secureJoin: (base: string, ...segments: string[]) => string;
+    /**
+     * **Get Comprehensive Path Metadata**
+     *
+     * Returns a structured object containing directory, base name, extension,
+     * filename without extension, and absolute status - all in a single high-speed call.
+     *
+     * @param {string} p - The path to evaluate.
+     * @returns {object} Metadata object: { dir, base, ext, name, isAbsolute }
+     */
+    $metadata: (p: string) => {
+        dir: string;
+        base: string;
+        ext: string;
+        name: string;
+        isAbsolute: boolean;
+    };
+    /**
+     * **Convert to Namespaced Path**
+     *
+     * Converts the path to a platform-specific namespaced path (e.g., UNC on Windows).
+     * This is essential for handling extremely long paths or network shares natively.
+     *
+     * @param {string} p - The path to convert.
+     * @returns {string} The namespaced path.
+     */
+    $toNamespacedPath: (p: string) => string;
+    /**
+     * **Normalize Separators**
+     *
+     * Standardizes all path separators (`/` or `\`) to the current operating system's
+     * primary separator format.
+     *
+     * @param {string} p - The path to handle.
+     * @returns {string} The path with uniform separators.
+     */
+    $normalizeSeparators: (p: string) => string;
+    /**
+     * **Identify Common Base Directory**
+     *
+     * Analyzes multiple paths and returns the deepest common directory shared by all.
+     *
+     * @param {...string[]} paths - Multiple paths to analyze.
+     * @returns {string} The shared parent directory.
+     */
+    $commonBase: (...paths: string[]) => string;
 }
 
 /**
@@ -3317,31 +3366,27 @@ declare class FSApi extends PathApi {
         bytes?: boolean;
     }) => string;
     /**
-     * **Write File Content ($write)**
+     * **Write File ($writeFile)**
      *
-     * Writes data to a file. This method replaces the file if it already exists, unless
-     * the `append` option is true. It ensures atomic writes where possible to prevent
-     * partial file corruption.
+     * Writes flexible data to a file. This method replaces the file if it already exists, unless
+     * the `append` option is true. Supports Buffers, plain objects (auto-JSON), arrays, and primitives.
+     * It ensures atomic writes where possible to prevent partial file corruption.
      *
      * @param {string} p - The destination file path.
-     * @param {string} data - The string data to write.
+     * @param {any} data - The data to write.
      * @param {Object} [options] - Write options.
      * @param {boolean} [options.append=false] - If true, adds data to the end of the file instead of overwriting.
      * @returns {void}
      *
      * @example
-     * // writing a new file
-     * __sys__.$write("notes.txt", "Important meeting at 10 AM");
-     *
-     * @example
-     * // Appending to a log file
-     * __sys__.$write("server.log", "[INFO] Startup ok\n", { append: true });
+     * // writing a new file with text
+     * __sys__.$writeFile("notes.txt", "Important meeting at 10 AM");
      *
      * @example
-     * // Writing to a nested path that may not exist yet
-     * __sys__.$write("data/cache/state.json", JSON.stringify(state));
+     * // Writing a JSON object directly
+     * __sys__.$writeFile("data.json", { user: "admin", active: true });
      */
-    $write: (p: string, data: string, options?: {
+    $writeFile: (p: string, data: any, options?: {
         append?: boolean;
         ensureFile?: boolean;
     }) => void;
@@ -3673,19 +3718,6 @@ declare class FSApi extends PathApi {
      * const userConfig = __sys__.$readJsonSafe("user-config.json", { theme: "dark" });
      */
     $readJsonSafe: <T = any>(p: string, defaultValue: T) => T;
-    /**
-     * **Write String to File ($writeFile)**
-     *
-     * A clearly named alias for writing string content to a file.
-     *
-     * @param {string} p - File path.
-     * @param {string} data - Content to write.
-     *
-     * @example
-     * // Writing a simple text file
-     * __sys__.$writeFile("hello.txt", "Hello World");
-     */
-    $writeFile: (p: string, data: string) => void;
     /**
      * **Write Object to JSON File ($writeJson)**
      *
@@ -3790,28 +3822,28 @@ declare class FSApi extends PathApi {
      * Appends data to the end of a file.
      *
      * @param {string} p - File path.
-     * @param {string} data - Content to append.
+     * @param {any} data - Content to append.
      */
-    $append: (p: string, data: string) => void;
+    $append: (p: string, data: any) => void;
     /**
      * **Append Line ($appendLine)**
      *
      * Appends a string followed by a platform-specific newline to a file.
      *
      * @param {string} p - File path.
-     * @param {string} line - Line content.
+     * @param {any} line - Line content.
      */
-    $appendLine: (p: string, line: string) => void;
+    $appendLine: (p: string, line: any) => void;
     /**
      * **Write If Not Exists ($writeIfNotExists)**
      *
      * Writes to a file only if it does not already exist.
      *
      * @param {string} p - File path.
-     * @param {string} data - Content to write.
+     * @param {any} data - Content to write.
      * @returns {boolean} `true` if written, `false` if file already existed.
      */
-    $writeIfNotExists: (p: string, data: string) => boolean;
+    $writeIfNotExists: (p: string, data: any) => boolean;
     /**
      * **Ensure Directory ($ensureDir)**
      *
@@ -4158,6 +4190,151 @@ declare class FSApi extends PathApi {
      * @returns {void}
      */
     $wcp(...args: Parameters<typeof this.$watchContentParallel>): void;
+    /**
+     * **Atomic Write ($atomicWrite)**
+     *
+     * Writes data to a temporary file first, and then atomically renames it over the target file.
+     * This guarantees that the target file is never in a partially written or corrupted state,
+     * even if the process crashes or power is lost during the write.
+     *
+     * @param {string} p - The destination file path.
+     * @param {any} data - The data to write.
+     * @param {Object} [options] - Options (e.g., ensureFile).
+     */
+    $atomicWrite: (p: string, data: any, options?: {
+        ensureFile?: boolean;
+    }) => void;
+    /**
+     * **Secure Shred ($shred)**
+     *
+     * Securely deletes a file from disk by overwriting its contents with random cryptographic
+     * noise multiple times before unlinking it, preventing data recovery tools from restoring the file.
+     *
+     * @param {string} p - The file path to shred.
+     * @param {number} [passes=3] - The number of overwrite passes (default: 3).
+     */
+    $shred: (p: string, passes?: number) => void;
+    /**
+     * **Tail File ($tail)**
+     *
+     * Efficiently reads the last `lines` of a file without loading the entire file into memory.
+     * Ideal for grabbing the end of massive log files.
+     *
+     * @param {string} p - The file path.
+     * @param {number} [lines=10] - Number of lines to return from the end of the file.
+     * @returns {string[]} An array of strings representing the last lines.
+     */
+    $tail: (p: string, lines?: number) => string[];
+    /**
+     * **Inline Patch ($patch)**
+     *
+     * Finds and replaces a string or regex directly inside a file. If the file is extremely large,
+     * this implementation buffers it safely rather than causing memory overflows.
+     *
+     * @param {string} p - The file path.
+     * @param {string|RegExp} searchValue - The value to find.
+     * @param {string} replaceValue - The value to replace it with.
+     * @returns {boolean} True if changes were made.
+     */
+    $patch: (p: string, searchValue: string | RegExp, replaceValue: string) => boolean;
+    /**
+     * **Split File ($split)**
+     *
+     * Fractures a large file into smaller sequential pieces based on exact byte chunks.
+     * Useful for breaking up large SQL dumps, logs, or backups for transport.
+     *
+     * @param {string} p - The file to split.
+     * @param {number} bytesPerChunk - Maximum bytes per split chunk.
+     * @param {string} [outDir] - Directory to put the chunks. Defaults to the source file's directory.
+     * @returns {string[]} Array of created chunk file paths.
+     */
+    $split: (p: string, bytesPerChunk: number, outDir?: string) => string[];
+    /**
+     * **Merge Files ($merge)**
+     *
+     * Safely binary-concatenates an array of source files into a single destination file.
+     * Useful for reconnecting files split by `$split`.
+     *
+     * @param {string[]} sourceFiles - Array of file paths to merge in order.
+     * @param {string} destFile - The destination file to create.
+     */
+    $merge: (sourceFiles: string[], destFile: string) => void;
+    /**
+     * **Lock File ($lock) & ($unlock)**
+     *
+     * Provides a rudimentary file lock mechanism by creating an exclusive `.lock` file
+     * alongside the target. Ensures atomic process cross-synchronization for shared file resources.
+     *
+     * @param {string} p - File path to lock.
+     * @returns {boolean} True if the lock was successfully acquired.
+     */
+    $lock: (p: string) => boolean;
+    /**
+     * **Unlock File ($unlock)**
+     *
+     * Releases a previously acquired lock for a file.
+     *
+     * @param {string} p - File path that was locked.
+     */
+    $unlock: (p: string) => void;
+    /**
+     * **Write Secure ($writeSecure)**
+     *
+     * Atomically writes a file with specific Unix permissions. This prevents the
+     * fraction-of-a-second race condition vulnerability of creating a file and then
+     * changing its permissions with $chmod.
+     *
+     * @param {string} p - The destination file path.
+     * @param {any} data - The data to write.
+     * @param {string} mode - Octal permission string (e.g. "0600").
+     */
+    $writeSecure: (p: string, data: any, mode: string) => void;
+    /**
+     * **Encrypt File ($encrypt)**
+     *
+     * Encrypts a file in-place using AES-256-GCM.
+     *
+     * @param {string} p - The file path to encrypt.
+     * @param {string} key - A string key (hashed internally to 256-bit).
+     */
+    $encrypt: (p: string, key: string) => void;
+    /**
+     * **Decrypt File ($decrypt)**
+     *
+     * Decrypts a previously encrypted file in-place using AES-256-GCM.
+     *
+     * @param {string} p - The file path to decrypt.
+     * @param {string} key - The exact string key used for encryption.
+     */
+    $decrypt: (p: string, key: string) => void;
+    /**
+     * **Diff Files ($diffFiles)**
+     *
+     * Quickly compares two files line-by-line using the Go engine and returns the exact mismatches.
+     *
+     * @param {string} fileA - First file path.
+     * @param {string} fileB - Second file path.
+     * @returns {Array<{line: number, file_a: string, file_b: string}>} Array of differing lines.
+     */
+    $diffFiles: (fileA: string, fileB: string) => Array<{
+        line: number;
+        file_a: string;
+        file_b: string;
+    }>;
+    /**
+     * **Top Big Files ($topBigFiles)**
+     *
+     * Scans a directory structure in Go and returns the N largest files, sorted by size.
+     * Perfect for disk space analysis dashboards.
+     *
+     * @param {string} dir - Directory to scan.
+     * @param {number} [limit=50] - Number of top files to return.
+     * @returns {Array<{path: string, size: number}>} Array of file paths and sizes.
+     */
+    $topBigFiles: (dir: string, limit?: number) => Array<{
+        path: string;
+        size: number;
+    }>;
 }
 
 /**
@@ -4215,7 +4392,8 @@ declare class SysApi extends FSApi {
      * const cores = __sys__.$cpu(true) as CpuInfo[];
      * console.log(`Core 0 Speed: ${cores[0].frequency} MHz`);
      */
-    $cpu: (cores?: boolean) => CpuUsage | CpuInfo[];
+    $cpu(cores: true): CpuInfo[];
+    $cpu(cores?: false): CpuUsage;
     /**
      * **Get Memory Usage**
      *
@@ -4276,7 +4454,8 @@ declare class SysApi extends FSApi {
      *     }
      * });
      */
-    $disks: (mount?: string) => DiskInfo[];
+    $disks(mount: string): DiskInfo | undefined;
+    $disks(): DiskInfo[];
     /**
      * **Get Network Interfaces**
      *
@@ -4800,9 +4979,9 @@ declare class XyPrissConst {
 declare const __const__: XyPrissConst;
 
 /**
- * @fileoverview Main export file for XyPrissJS Express integration types
+ * @fileoverview Main export file for XyPriss integration types
  *
- * This file provides a centralized export point for all Express integration
+ * This file provides a centralized export point for all XyPriss integration
  * types, organized into modular categories for better maintainability.
  *
  * @version 4.5.11
@@ -5197,6 +5376,8 @@ interface XyPrisRequest extends IncomingMessage {
     params: Record<string, string>;
     query: Record<string, any>;
     body: any;
+    files?: any[];
+    file?: any;
     path: string;
     originalUrl: string;
     baseUrl: string;
@@ -7139,6 +7320,20 @@ interface ServerOptions$1 {
                 idleTimeout?: number;
             };
         };
+        /**
+         * Firewall management plugin configuration.
+         *
+         * Provides automated port management and IP-based access control
+         * via native system firewall managers (ufw, iptables).
+         */
+        firewall?: {
+            /** Enable firewall management plugin */
+            enabled?: boolean;
+            /** Automatically open required ports (80, 443, and server port) */
+            autoOpen?: boolean;
+            /** List of explicitly allowed IPs or CIDR blocks */
+            allowedIPs?: string[];
+        };
         /**
          * Compression plugin configuration.
          *
@@ -7736,14 +7931,14 @@ interface UFApp {
      */
     middleware: () => XyPrissMiddlewareAPI;
     /**
-     * Multer instance for file uploads (available when fileUpload.enabled is true)
+     * Internal upload manager instance for file uploads
      */
     upload?: any;
     /**
      * Create single file upload middleware
      *
      * @param fieldname - Name of the form field
-     * @returns Multer middleware for single file upload
+     * @returns Middleware for single file upload
      *
      * @example
      * ```typescript
@@ -7759,7 +7954,7 @@ interface UFApp {
      *
      * @param fieldname - Name of the form field
      * @param maxCount - Maximum number of files (optional)
-     * @returns Multer middleware for array file upload
+     * @returns Middleware for array file upload
      *
      * @example
      * ```typescript
@@ -7774,7 +7969,7 @@ interface UFApp {
      * Create fields file upload middleware
      *
      * @param fields - Array of field configurations
-     * @returns Multer middleware for multiple fields upload
+     * @returns Middleware for multiple fields upload
      *
      * @example
      * ```typescript
@@ -7791,7 +7986,7 @@ interface UFApp {
     /**
      * Create any file upload middleware
      *
-     * @returns Multer middleware that accepts any files
+     * @returns Middleware that accepts any files
      *
      * @example
      * ```typescript
@@ -8168,63 +8363,56 @@ declare class FileUploadAPI {
     private manager;
     private logger;
     private initialized;
-    constructor();
+    private configOverride?;
+    constructor(config?: FileUploadConfig);
     /**
-     * Initialize the file upload API with configuration from Configs
-     *
-     * This method requires the Configs class to enforce a single source of truth.
-     * Configuration is accessed internally from Configs.get('fileUpload').
-     *
-     * @param configManager - The Configs class (not an instance, the class itself)
-     *
-     * @example
-     * ```typescript
-     * import { Configs } from 'xypriss';
-     *
-     * const upload = new FileUploadAPI();
-     * await upload.initialize(Configs);
-     * ```
+     * Internal auto-initialization method.
+     * Called lazily by middleware methods if not already initialized.
+     */
+    private autoInitialize;
+    /**
+     * Manually initialize the file upload API (legacy support)
      */
-    initialize(configManager: typeof ConfigurationManager): Promise<void>;
+    initialize(configManager?: any): Promise<void>;
     /**
      * Check if the file upload API is enabled
      */
     isEnabled(): boolean;
     /**
-     * Handle multer errors and convert them to proper HTTP responses
+     * Handle upload errors and convert them to proper HTTP responses
      */
-    private handleMulterError;
+    private handleUploadError;
     /**
      * Create a middleware for uploading a single file
      *
      * @param fieldname - The name of the form field containing the file
-     * @returns Express middleware function
+     * @returns Middleware function
      */
-    single(fieldname: string): (req: any, res: any, next: any) => any;
+    single(fieldname: string): (req: any, res: any, next: any) => Promise<any>;
     /**
      * Create a middleware for uploading multiple files with the same field name
      *
      * @param fieldname - The name of the form field containing the files
      * @param maxCount - Maximum number of files to accept (optional)
-     * @returns Express middleware function
+     * @returns Middleware function
      */
-    array(fieldname: string, maxCount?: number): (req: any, res: any, next: any) => any;
+    array(fieldname: string, maxCount?: number): (req: any, res: any, next: any) => Promise<any>;
     /**
      * Create a middleware for uploading multiple files with different field names
      *
      * @param fields - Array of field configurations
-     * @returns Express middleware function
+     * @returns Middleware function
      */
     fields(fields: Array<{
         name: string;
         maxCount?: number;
-    }>): (req: any, res: any, next: any) => any;
+    }>): (req: any, res: any, next: any) => Promise<any>;
     /**
      * Create a middleware for uploading any files (accepts all files)
      *
-     * @returns Express middleware function
+     * @returns Middleware function
      */
-    any(): (req: any, res: any, next: any) => any;
+    any(): (req: any, res: any, next: any) => Promise<any>;
 }
 
 declare const Upload: FileUploadAPI;
@@ -8679,7 +8867,7 @@ declare const Plugin: {
 };
 
 /**
- * XyPrissJS Express Quick Start
+ * XyPrissJS Quick Start
  * Pre-configured server instances for rapid development (tests with limited configs)
  */
 /**
@@ -9058,6 +9246,59 @@ declare function mergeWithDefaults<T extends Record<string | symbol, any>>(defau
 /** @internal — tracks visited objects to break circular refs */
 _seen?: WeakSet<object>): T;
 
+/***************************************************************************
+ * XyPrissJS - Fast And Secure
+ *
+ * @author Nehonix
+ * @license Nehonix OSL (NOSL)
+ *
+ * Copyright (c) 2025 Nehonix. All rights reserved.
+ *
+ * This License governs the use, modification, and distribution of software
+ * provided by NEHONIX under its open source projects.
+ * NEHONIX is committed to fostering collaborative innovation while strictly
+ * protecting its intellectual property rights.
+ * Violation of any term of this License will result in immediate termination of all granted rights
+ * and may subject the violator to legal action.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+ * AND NON-INFRINGEMENT.
+ * IN NO EVENT SHALL NEHONIX BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+ * OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE,
+ * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+ *
+ ***************************************************************************** */
+
+/** Result enriched with metadata for observability / debugging. */
+interface GetIpResult {
+    /** Resolved IP address (IPv4 or IPv6, normalised). */
+    ip: string;
+    /** Header / source that provided the IP. */
+    source: IpSource;
+}
+type IpSource = "cf-connecting-ip" | "true-client-ip" | "x-real-ip" | "x-forwarded-for" | "forwarded" | "x-client-ip" | "x-cluster-client-ip" | "req.ip" | "socket" | "fallback";
+/**
+ * Robustly extracts the **real** client IP from a request.
+ *
+ * Resolution order (most-specific / trustworthy first):
+ *  1. `CF-Connecting-IP`     – Cloudflare; single, authoritative value
+ *  2. `True-Client-IP`       – Akamai / Cloudflare enterprise
+ *  3. `X-Real-IP`            – Nginx single-proxy setups
+ *  4. `X-Client-IP`          – Some load balancers / Apache mod_remoteip
+ *  5. `X-Cluster-Client-IP`  – Rackspace, some Nginx configs
+ *  6. `Forwarded`            – RFC 7239 standard header
+ *  7. `X-Forwarded-For`      – De-facto standard (picks first public IP)
+ *  8. `req.ip`               – XyPrisRequest parsed value
+ *  9. `socket.remoteAddress` – Raw TCP socket
+ * 10. `"127.0.0.1"`          – Ultimate fallback (never throws)
+ *
+ * @param req       - The request object (XyPrisRequest-compatible).
+ * @param enriched  - When `true`, returns `{ ip, source }` for observability.
+ */
+declare function getIp(req: XyPrisRequest): string;
+declare function getIp(req: XyPrisRequest, enriched: true): GetIpResult;
+
 /***************************************************************************
  * XyPrissJS - Fast And Secure
  *
@@ -9084,10 +9325,10 @@ _seen?: WeakSet<object>): T;
 
 declare global {
     /**
-     * @fileoverview Comprehensive server options interface for XyPrissJS Express integration
+     * @fileoverview Comprehensive server options interface for XyPriss integration
      *
      * This interface provides complete configuration options for creating ultra-fast,
-     * secure Express servers with advanced features including caching, clustering,
+     * secure servers with advanced features including caching, clustering,
      * performance optimization, and Go integration.
      *
      * @interface ServerOptions
@@ -9139,5 +9380,5 @@ declare global {
  */
 declare function Router(): XyPrissRouter;
 
-export { ConfigurationManager as CM, ConfigurationManager as Configs, FileUploadAPI as FLA, FileUploadAPI, PerformanceMonitor, Plugin, PluginHookIds, Router, SecurityMiddleware, TrustProxy, Upload, XJsonResponseHandler, MultiServerApp as XyPMS, XyPrissRouter, XyPrissSys, __cfg__, __const__, __sys__, createCircularRefDebugger, createOptimalCache, createSafeJsonMiddleware, createServer, initializeFileUpload, mergeWithDefaults, mergeWithDefaults as mwdef, quickServer, safeJsonStringify, sendSafeJson, setupSafeJson, uploadAny, uploadArray, uploadFields, uploadSingle, xems };
-export type { ArchiveOptions, BatchRenameChange, CacheConfig, FileUploadConfig as FiUpConfig, FileUploadConfig, MonitorSnapshot, MultiServerConfig, NetworkStats, NextFunction, PerformanceConfig, PluginCreator, ProcessInfo, ProcessMonitorSnapshot, XyPrisRequest as Request, RequestHandler, XyPrisResponse as Response, RouteConfig, RouteOptions, SecurityConfig, ServerOptions$1 as ServerOptions, TrustProxyValue$1 as TrustProxyValue, UltraFastApp, XemsTypes, XyPrisRequest, XyPrisResponse, XyPrissPlugin, XyPrisRequest as XyPrissRequest, XyPrisResponse as XyPrissResponse };
+export { ConfigurationManager as CM, ConfigurationManager as Configs, FileUploadAPI as FLA, FileUploadAPI, PerformanceMonitor, Plugin, PluginHookIds, Router, SecurityMiddleware, TrustProxy, Upload, XJsonResponseHandler, MultiServerApp as XyPMS, XyPrissRouter, XyPrissSys, __cfg__, __const__, __sys__, createCircularRefDebugger, createOptimalCache, createSafeJsonMiddleware, createServer, getIp, initializeFileUpload, mergeWithDefaults, mergeWithDefaults as mwdef, quickServer, safeJsonStringify, sendSafeJson, setupSafeJson, uploadAny, uploadArray, uploadFields, uploadSingle, xems };
+export type { ArchiveOptions, BatchRenameChange, CacheConfig, FileUploadConfig as FiUpConfig, FileUploadConfig, GetIpResult, IpSource, MonitorSnapshot, MultiServerConfig, NetworkStats, NextFunction, PerformanceConfig, PluginCreator, ProcessInfo, ProcessMonitorSnapshot, XyPrisRequest as Request, RequestHandler, XyPrisResponse as Response, RouteConfig, RouteOptions, SecurityConfig, ServerOptions$1 as ServerOptions, TrustProxyValue$1 as TrustProxyValue, UltraFastApp, XemsTypes, XyPrisRequest, XyPrisResponse, XyPrissPlugin, XyPrisRequest as XyPrissRequest, XyPrisResponse as XyPrissResponse };