xypriss 9.9.6 → 9.10.0

package/README.md

@@ -58,6 +58,7 @@ This separation allows each layer to operate in its optimal domain: compiled nat
 - **Security-First Architecture** — 12+ built-in security middleware modules including CSRF protection, XSS prevention, and intelligent rate limiting.
 - **Advanced Radix Routing (V2)** — Ultra-fast, modular routing engine with support for typed path parameters, declarative guards, and native API versioning.
 - **Real-Time System Intelligence** — Native access to CPU, memory, disk, network, battery, and process metrics directly from the application layer.
+- **XStatic Engine** — High-performance static serving via **Zero-Copy IPC Delegation**. Handsoff file delivery directly to the native XHSC (Go) core to bypass the Node.js event loop and memory overhead. Optimized for extreme concurrency and low latency.
 - **Filesystem Engine & Binary Streaming** — High-performance filesystem operations, duplicate detection, and robust **Zero-Copy Ranged Streaming** via `res.sendFile()`, optimized for media delivery and large assets.
 - **File Upload Management** — Production-ready multipart/form-data handling with automatic validation, error handling, and the `getMimes()` helper for extension-to-mime mapping.
 - **Environment Security Shield** — Military-grade protection for sensitive variables. Direct `process.env` access is masked via a native Proxy to prevent accidental leakage, forcing the use of secure, typed APIs.
@@ -167,6 +168,8 @@ app.start();
 - [Features Overview](https://xypriss.nehonix.com/docs/FEATURES_OVERVIEW) - Comprehensive feature list
 - [Router Engine V2](./docs/routing/README.md) - Rich modular routing
 - [Advanced Routing & XyGuard API](./docs/routing/ADVANCED_ROUTING.md) - Declarative guards and modularity
+- [XStatic Native Serving](./docs/core/XSTATIC.md) - Zero-Copy static file delegation
+- [Native Binary Streaming](./docs/core/response-sendfile.md) - res.sendFile() technical guide
 
 ### Security
 

package/dist/cjs/src/index.js

@@ -19,6 +19,7 @@ var getIp = require('./utils/getIp.js');
 var ProjectDiscovery = require('./utils/ProjectDiscovery.js');
 var XemsPlugin = require('./plugins/builtin/xems/XemsPlugin.js');
 var getMime = require('./utils/getMime.js');
+var XStatic = require('./server/components/static/XStatic.js');
 var FiUp = require('./FiUp.js');
 
 /***************************************************************************
@@ -88,6 +89,7 @@ exports.identifyProjectRoot = ProjectDiscovery.identifyProjectRoot;
 exports.xems = XemsPlugin.xems;
 exports.getMime = getMime.getMime;
 exports.getMimes = getMime.getMimes;
+exports.XStatic = XStatic.XStatic;
 exports.initializeFileUpload = FiUp.initializeFileUpload;
 exports.uploadAny = FiUp.uploadAny;
 exports.uploadArray = FiUp.uploadArray;

package/dist/cjs/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":[null],"names":["configLoader","XyPrissRouter"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;AAsBiF;AACjF;AAEA;AACA;AAqBA;AACA,IAAI,OAAO,UAAU,KAAK,WAAW,EAAE;IACnCA,yBAAY,CAAC,qBAAqB,EAAE;AACxC;AA+BA;;AAEG;SACa,MAAM,GAAA;IAClB,OAAO,IAAIC,sBAAa,CAAC;AACrB,QAAA,aAAa,EAAE,KAAK;AACpB,QAAA,WAAW,EAAE,KAAK;AAClB,QAAA,MAAM,EAAE,KAAK;AAChB,KAAA,CAAC;AACN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":[null],"names":["configLoader","XyPrissRouter"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;AAsBiF;AACjF;AAEA;AACA;AAqBA;AACA,IAAI,OAAO,UAAU,KAAK,WAAW,EAAE;IACnCA,yBAAY,CAAC,qBAAqB,EAAE;AACxC;AA+BA;;AAEG;SACa,MAAM,GAAA;IAClB,OAAO,IAAIC,sBAAa,CAAC;AACrB,QAAA,aAAa,EAAE,KAAK;AACpB,QAAA,WAAW,EAAE,KAAK;AAClB,QAAA,MAAM,EAAE,KAAK;AAChB,KAAA,CAAC;AACN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/src/middleware/built-in/security/HoneypotTarpit.js

@@ -68,6 +68,21 @@ var UriNormalizer = require('./UriNormalizer.js');
  * ```
  */
 class HoneypotTarpit {
+    /**
+     * Registers custom trap patterns to expand the honeypot surface.
+     *
+     * @param {object} custom - Object containing custom patterns to trap.
+     */
+    static registerCustomTraps(custom) {
+        if (custom.exact)
+            custom.exact.forEach(p => this.CUSTOM_EXACT_TRAPS.add(p.toLowerCase()));
+        if (custom.prefixes)
+            custom.prefixes.forEach(p => this.CUSTOM_PREFIX_TRAPS.add(p.toLowerCase()));
+        if (custom.suffixes)
+            custom.suffixes.forEach(p => this.CUSTOM_SUFFIX_TRAPS.add(p.toLowerCase()));
+        if (custom.segments)
+            custom.segments.forEach(p => this.CUSTOM_SEGMENT_TRAPS.add(p.toLowerCase()));
+    }
     // ─────────────────────────────────────────────────────────────────────────
     // Public API
     // ─────────────────────────────────────────────────────────────────────────
@@ -110,7 +125,31 @@ class HoneypotTarpit {
         return (HoneypotTarpit.matchesExactTrap(normalized) ||
             HoneypotTarpit.matchesPrefixTrap(normalized) ||
             HoneypotTarpit.matchesSuffixTrap(normalized) ||
-            HoneypotTarpit.matchesSegmentTrap(normalized));
+            HoneypotTarpit.matchesSegmentTrap(normalized) ||
+            HoneypotTarpit.CUSTOM_EXACT_TRAPS.has(normalized) ||
+            HoneypotTarpit.matchesCustomPrefix(normalized) ||
+            HoneypotTarpit.matchesCustomSuffix(normalized) ||
+            HoneypotTarpit.matchesCustomSegment(normalized));
+    }
+    static matchesCustomPrefix(path) {
+        for (const p of this.CUSTOM_PREFIX_TRAPS)
+            if (path.startsWith(p))
+                return true;
+        return false;
+    }
+    static matchesCustomSuffix(path) {
+        const last = path.split("/").pop() ?? "";
+        for (const s of this.CUSTOM_SUFFIX_TRAPS)
+            if (last.endsWith(s))
+                return true;
+        return false;
+    }
+    static matchesCustomSegment(path) {
+        const segments = path.split("/").filter(Boolean);
+        for (const s of segments)
+            if (this.CUSTOM_SEGMENT_TRAPS.has(s))
+                return true;
+        return false;
     }
     /**
      * Sends a minimal HTTP 403 Forbidden response and terminates the connection.
@@ -505,6 +544,13 @@ HoneypotTarpit.SEGMENT_TRAPS = new Set([
     "actuator",
     "heapdump",
 ]);
+/**
+ * Custom user-defined traps registered at runtime.
+ */
+HoneypotTarpit.CUSTOM_EXACT_TRAPS = new Set();
+HoneypotTarpit.CUSTOM_PREFIX_TRAPS = new Set();
+HoneypotTarpit.CUSTOM_SUFFIX_TRAPS = new Set();
+HoneypotTarpit.CUSTOM_SEGMENT_TRAPS = new Set();
 
 exports.HoneypotTarpit = HoneypotTarpit;
 //# sourceMappingURL=HoneypotTarpit.js.map

package/dist/cjs/src/middleware/built-in/security/HoneypotTarpit.js.map

@@ -1 +1 @@
-{"version":3,"file":"HoneypotTarpit.js","sources":["../../../../../../src/middleware/built-in/security/HoneypotTarpit.ts"],"sourcesContent":[null],"names":["UriNormalizer"],"mappings":"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"}
+{"version":3,"file":"HoneypotTarpit.js","sources":["../../../../../../src/middleware/built-in/security/HoneypotTarpit.ts"],"sourcesContent":[null],"names":["UriNormalizer"],"mappings":"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"}

package/dist/cjs/src/plugins/core/PermissionManager.js

@@ -130,14 +130,14 @@ class PermissionManager {
             logDenial("Privileged hook must be explicitly whitelisted by string declaration. Wildcard '*' does not grant privileged capabilities.", solutionPrivileged);
             return false;
         }
-        // 2. Lifecycle Hooks: Always allowed for engine stability (unless denied)
-        if (isLifecycleHook)
+        // 2. Lifecycle Hooks: Engines stability fallback
+        const allowLifecycle = this.server.options?.plugins?.allowLifecycleByDefault ?? false;
+        if (isLifecycleHook && allowLifecycle)
             return true;
         // 3. Standard Hook Logic
         if (policy === "deny") {
             // "deny" policy = Whitelist mode
-            if (isLifecycleHook)
-                return true; // Lifecycle is always whitelisted by default
+            // Whitelist mode: only allow if in allowedHooks (or explicitly enabled by server options above)
             if (allowedHooks === "*")
                 return true;
             if (Array.isArray(allowedHooks) && allowedHooks.includes(hookId)) {

package/dist/cjs/src/plugins/core/PermissionManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"PermissionManager.js","sources":["../../../../../src/plugins/core/PermissionManager.ts"],"sourcesContent":[null],"names":["Logger","HOOK_ID_MAP","HOOK_METADATA","OFFICIAL_PLUGINS","__sys__","PluginHookIds"],"mappings":"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"}
+{"version":3,"file":"PermissionManager.js","sources":["../../../../../src/plugins/core/PermissionManager.ts"],"sourcesContent":[null],"names":["Logger","HOOK_ID_MAP","HOOK_METADATA","OFFICIAL_PLUGINS","__sys__","PluginHookIds"],"mappings":"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"}

package/dist/cjs/src/server/components/static/IXStaticSchem.js

@@ -0,0 +1,30 @@
+'use strict';
+
+var reliantType = require('reliant-type');
+
+const IXStaticSchem = reliantType.Mod.deepPartial(reliantType.Interface({
+    /**
+     * Size of the negative-lookup LRU cache.
+     * Stores non-existent paths to prevent DDoS via disk hits.
+     * @default 5000
+     */
+    lruCacheSize: "number?",
+    /**
+     * Default Cache-Control max-age for all static routes.
+     * Can be a number (seconds) or string (e.g., "1d").
+     */
+    defaultMaxAge: "number?|string?",
+    /**
+     * Enable/Disable zero-copy file transfer via sendfile(2).
+     * @default true
+     */
+    zeroCopy: "boolean?",
+    /**
+     * Maximum number of concurrent goroutines for static I/O in Go engine.
+     * @default 1024
+     */
+    concurrencyPool: "number?",
+}));
+
+exports.IXStaticSchem = IXStaticSchem;
+//# sourceMappingURL=IXStaticSchem.js.map

package/dist/cjs/src/server/components/static/IXStaticSchem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IXStaticSchem.js","sources":["../../../../../../src/server/components/static/IXStaticSchem.ts"],"sourcesContent":[null],"names":["Mod","Interface"],"mappings":";;;;MAEa,aAAa,GAAGA,eAAG,CAAC,WAAW,CACxCC,qBAAS,CAAC;AACN;;;;AAIG;AACH,IAAA,YAAY,EAAE,SAAS;AAEvB;;;AAGG;AACH,IAAA,aAAa,EAAE,iBAAiB;AAEhC;;;AAGG;AACH,IAAA,QAAQ,EAAE,UAAU;AAEpB;;;AAGG;AACH,IAAA,eAAe,EAAE,SAAS;AAC7B,CAAA,CAAC;;;;"}

package/dist/cjs/src/server/components/static/MetaCache.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * Lightweight LRU Cache for negative path lookups (anti-DDoS).
+ */
+class XStaticMetaCache {
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+        this.cache = new Map();
+        this.keys = [];
+    }
+    get(path) {
+        const item = this.cache.get(path);
+        if (!item)
+            return null;
+        if (Date.now() > item.expires) {
+            this.delete(path);
+            return null;
+        }
+        return { exists: item.exists };
+    }
+    set(path, exists, ttlMs = 30000) {
+        if (this.cache.has(path)) {
+            this.delete(path);
+        }
+        else if (this.keys.length >= this.maxSize) {
+            const oldest = this.keys.shift();
+            if (oldest)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(path, { exists, expires: Date.now() + ttlMs });
+        this.keys.push(path);
+    }
+    delete(path) {
+        this.cache.delete(path);
+        const idx = this.keys.indexOf(path);
+        if (idx > -1)
+            this.keys.splice(idx, 1);
+    }
+}
+
+exports.XStaticMetaCache = XStaticMetaCache;
+//# sourceMappingURL=MetaCache.js.map

package/dist/cjs/src/server/components/static/MetaCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetaCache.js","sources":["../../../../../../src/server/components/static/MetaCache.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;AAEG;MACU,gBAAgB,CAAA;AAKzB,IAAA,WAAA,CAAoB,OAAe,EAAA;QAAf,IAAA,CAAA,OAAO,GAAP,OAAO;AAJnB,QAAA,IAAA,CAAA,KAAK,GACT,IAAI,GAAG,EAAE;QACL,IAAA,CAAA,IAAI,GAAa,EAAE;IAEW;AAE/B,IAAA,GAAG,CAAC,IAAY,EAAA;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;AACjC,QAAA,IAAI,CAAC,IAAI;AAAE,YAAA,OAAO,IAAI;QACtB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE;AAC3B,YAAA,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;AACjB,YAAA,OAAO,IAAI;QACf;AACA,QAAA,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;IAClC;AAEO,IAAA,GAAG,CAAC,IAAY,EAAE,MAAe,EAAE,QAAgB,KAAK,EAAA;QAC3D,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;AACtB,YAAA,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;QACrB;aAAO,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE;YACzC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE;AAChC,YAAA,IAAI,MAAM;AAAE,gBAAA,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;QACzC;QAEA,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;AAC7D,QAAA,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB;AAEQ,IAAA,MAAM,CAAC,IAAY,EAAA;AACvB,QAAA,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QACnC,IAAI,GAAG,GAAG,EAAE;YAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1C;AACH;;;;"}

package/dist/cjs/src/server/components/static/XStatic.js

@@ -0,0 +1,356 @@
+'use strict';
+
+var Logger = require('../../../shared/logger/Logger.js');
+var UriNormalizer = require('../../../middleware/built-in/security/UriNormalizer.js');
+require('../../../index.js');
+var IXStaticSchem = require('./IXStaticSchem.js');
+var quickLogger = require('../../../shared/logger/quickLogger.js');
+var MetaCache = require('./MetaCache.js');
+var ConfigurationManager = require('../../../ConfigurationManager.js');
+
+/***************************************************************************
+ * XyPriss - Fast And Secure
+ *
+ * XStatic - High-Performance, Sandboxed Static File Serving.
+ * Optimized with Meta-Cache (LRU) and XHSC (Go) Zero-Copy delegation.
+ ***************************************************************************/
+/**
+ * **XStatic** — High-performance, sandboxed static file server for XyPriss.
+ *
+ * XStatic handles static asset delivery through a two-layer architecture:
+ *
+ * 1. **TypeScript layer** — responsible for URI normalization, dotfile/sandbox
+ *    security enforcement, and LRU meta-cache (anti-DDoS I/O shield).
+ * 2. **XHSC (Go) layer** — takes over once the request is validated, streaming
+ *    the file directly from disk to the TCP socket using zero-copy (`sendfile`),
+ *    native ETags, `304 Not Modified`, and `206 Partial Content` (Range requests).
+ *
+ * ### Architectural Flow
+ * ```
+ * Request
+ *   → URI Normalization
+ *   → Dotfile / Restricted File Check
+ *   → Sandbox Enforcement (Project Root + Directory Jail)
+ *   → LRU Meta-Cache (negative cache — blocks repeated 404 storms)
+ *   → Filesystem Existence Check
+ *   → XHSC Zero-Copy Delegation (Go)
+ *   → Response
+ * ```
+ *
+ * ### Basic Usage
+ * ```typescript
+ * import { XStatic } from "xypriss";
+ *
+ * const app  = createServer(options);
+ * const xs   = new XStatic(app, __sys__);
+ *
+ * xs.define("/assets", "./public");
+ * xs.define("/docs",   "./documentation");
+ *
+ * // Explicit opt-out of sandbox (e.g. user-upload directory)
+ * xs.define("/avatars", "/var/www/uploads/avatars", {
+ *   allowOutsideRoot: true,
+ *   unsafe: true,
+ * });
+ * ```
+ *
+ * ### Global Configuration (via `createServer`)
+ * ```typescript
+ * const app = createServer({
+ *   static: {
+ *     zeroCopy:       true,   // Enable sendfile() syscall in XHSC
+ *     ConcurrencyPool: 1024,  // Max goroutines for disk I/O
+ *     lruCacheSize:   5000,   // Entries kept in negative meta-cache
+ *     dotfiles:       "deny", // Block .env, .git, etc.
+ *     defaultMaxAge:  86400,  // Default Cache-Control max-age (seconds)
+ *   },
+ * });
+ * ```
+ *
+ * @remarks
+ * XStatic is **instance-scoped** by design. Avoid singleton patterns when
+ * running under XMS (XyPriss MultiServer) to prevent cross-instance route
+ * leakage and memory pressure.
+ *
+ * @see {@link StaticOptions}  for per-route configuration.
+ * @see {@link IXStatic}       for global configuration shape.
+ * @see {@link XStaticMetaCache} for LRU cache implementation details.
+ */
+class XStatic {
+    /**
+     * Creates a new `XStatic` instance bound to the given server and system API.
+     *
+     * Reads the `"static"` key from the application config (`Configs.get`),
+     * initialises the LRU meta-cache with the configured size (default: **5 000**
+     * entries), and wires up internal loggers.
+     *
+     * @param app - The XyPriss application instance to register middleware on.
+     * @param sys - The XHSC system handle (`__sys__`), which exposes the sandboxed
+     *   `fs` and `path` APIs as well as the project root (`__root__`).
+     *
+     * @throws {Error} If the global `"static"` configuration block fails Zod schema
+     *   validation (see {@link validateConfigs}).
+     *
+     * @example
+     * ```typescript
+     * const xs = new XStatic(app, __sys__);
+     * ```
+     */
+    constructor(app, sys) {
+        this.app = app;
+        this.sys = sys;
+        this.globalConfig = ConfigurationManager.CM.get("static") || {};
+        this.metaCache = new MetaCache.XStaticMetaCache(this.globalConfig.lruCacheSize || 5000);
+        this.logger = app.logger || Logger.Logger.getInstance();
+        this.qLog = quickLogger.QuickLogger.for("XStatic");
+        this.logger.debug("server", "XStatic initialized with Zero-Copy delegation support.");
+        this.validateConfigs();
+    }
+    /**
+     * Validates the global static configuration block at startup.
+     *
+     * Performs two sequential checks:
+     *
+     * 1. **Dotfiles type guard** — ensures `dotfiles` is either `"allow"` or
+     *    `"deny"` when provided as a plain string.
+     * 2. **Zod schema validation** — runs `IXStaticSchem.safeParse` against the
+     *    full config object to catch unknown or malformed fields.
+     *
+     * @throws {Error} `"Invalid configuration for 'dotfiles'"` — if `dotfiles` is
+     *   present but not a string.
+     * @throws {Error} `"Invalid dotfiles mode. Expected one of 'allow' or 'deny',
+     *   but got: '<value>'"` — if the dotfiles string is not a recognised mode.
+     * @throws {Error} Zod validation message — if the config object fails the
+     *   `IXStaticSchem` schema.
+     *
+     * @internal
+     */
+    validateConfigs() {
+        const c = this.globalConfig;
+        const sdc = ["allow", "deny"];
+        if (c.dotfiles != null &&
+            !["string", "string"].includes(typeof c.dotfiles)) {
+            throw new Error("Invalid configuration for 'dotfiles'");
+        }
+        if (c.dotfiles &&
+            typeof c.dotfiles === "string" &&
+            !sdc.includes(c.dotfiles)) {
+            throw new Error(`Invalid dotfiles mode. Expected one of ${sdc.map((s) => `'${s}'`).join(" or ")}, but got: '${c.dotfiles}'`);
+        }
+        const validatedConfigs = IXStaticSchem.IXStaticSchem.safeParse(this.globalConfig);
+        if (!validatedConfigs.success) {
+            throw new Error(validatedConfigs.errors[0].message);
+        }
+    }
+    /**
+     * Registers a static file route on the application.
+     *
+     * Mounts an async middleware on `route` that handles the full request
+     * lifecycle: URI normalization → dotfile/restricted-file protection →
+     * sandbox enforcement → LRU cache lookup → filesystem check →
+     * XHSC zero-copy delegation.
+     *
+     * ---
+     *
+     * ### Security Layers
+     *
+     * **1 — Dotfile & Restricted File Protection**
+     *
+     * Controlled by `globalConfig.dotfiles` (default: `"deny"`). When in deny
+     * mode, any file whose name starts with `"."` (e.g. `.env`, `.git`) or
+     * appears in a custom restricted list is rejected with `403 Forbidden` before
+     * any disk access occurs.
+     *
+     * **2 — Sandbox Enforcement** *(skipped when `options.unsafe` or
+     * `options.allowOutsideRoot` is `true`)*
+     *
+     * - **Project Root Check** — the resolved `dir` must be inside the project
+     *   root (`sys.__root__`). Prevents accidentally serving system directories.
+     * - **Directory Jail** — the resolved request path must be strictly inside
+     *   `dir`. Blocks path-traversal attacks (`../../etc/passwd`).
+     *
+     * **3 — LRU Meta-Cache (Anti-DDoS I/O Shield)**
+     *
+     * Paths that have previously resolved to `"not found"` are cached in memory.
+     * Subsequent requests for the same missing path are rejected at the cache
+     * layer — zero disk I/O, pure RAM response — protecting against flood
+     * attacks that enumerate non-existent files.
+     *
+     * ---
+     *
+     * ### Zero-Copy Delegation to XHSC (Go)
+     *
+     * Once a request passes all validation steps, TypeScript sends a single IPC
+     * signal to the XHSC worker: `"request #<id> may read <absolutePath>"`.
+     * XHSC then streams the file directly from disk to the client TCP socket
+     * using `sendfile()`, bypassing the V8/Node.js heap entirely. HTTP-level
+     * concerns (ETag generation, `304 Not Modified`, `206 Partial Content` for
+     * Range requests) are all handled natively by Go's `http.ServeContent`.
+     *
+     * ---
+     *
+     * @param route - The URL prefix to mount (e.g. `"/assets"`). Automatically
+     *   normalised via {@link UriNormalizer.normalizePath}.
+     * @param dir   - The filesystem directory to serve from (e.g. `"./public"`).
+     *   Relative paths are resolved against the process working directory.
+     * @param options - Optional per-route overrides. See {@link StaticOptions}.
+     *
+     * @returns `void` — the middleware is registered as a side effect.
+     *
+     * @throws This method does not throw. Internal errors are caught, logged via
+     *   the application logger, and forwarded to `next()` so the request chain
+     *   can continue (or fall through to a global error handler).
+     *
+     * @example
+     * ```typescript
+     * // Serve ./public under /assets (fully sandboxed, dotfiles denied)
+     * xs.define("/assets", "./public");
+     *
+     * // Custom Cache-Control for long-lived build artefacts (1 week)
+     * xs.define("/dist", "./build", { maxAge: 604800 });
+     *
+     * // User-uploaded content outside the project root (explicit opt-out)
+     * xs.define("/uploads", "/var/www/uploads", {
+     *   allowOutsideRoot: true,
+     *   unsafe: true,
+     * });
+     * ```
+     *
+     * @see {@link StaticOptions} for the full list of per-route options.
+     * @see {@link serve} for the deprecated alias.
+     */
+    define(route, dir, options = {}) {
+        const normalizedRoute = UriNormalizer.UriNormalizer.normalizePath(route);
+        // Middleware registration
+        this.app.use(normalizedRoute, async (req, res, next) => {
+            try {
+                // 1. Path Calculation (Strip mount point)
+                let relativePath = req.path;
+                if (req.path === normalizedRoute) {
+                    relativePath = "/";
+                }
+                else {
+                    const prefix = normalizedRoute.endsWith("/")
+                        ? normalizedRoute
+                        : `${normalizedRoute}/`;
+                    if (req.path.startsWith(prefix)) {
+                        relativePath = req.path.substring(normalizedRoute.length);
+                    }
+                }
+                // Remove leading slash for join/basename operations
+                const cleanRelative = relativePath.startsWith("/")
+                    ? relativePath.substring(1)
+                    : relativePath;
+                const fileName = cleanRelative.split("/").pop() || "";
+                // 2. Dotfile & Restricted File Protection (Global Policy)
+                const dotfileConfig = this.globalConfig.dotfiles || "deny";
+                const dotfileMode = typeof dotfileConfig === "object"
+                    ? dotfileConfig.mode
+                    : dotfileConfig;
+                const customRestricted = typeof dotfileConfig === "object"
+                    ? dotfileConfig.custom || []
+                    : [];
+                if (dotfileMode === "deny") {
+                    const isRestricted = fileName.startsWith(".") ||
+                        customRestricted.includes(fileName);
+                    if (isRestricted) {
+                        this.qLog.warn(
+                        // "security",
+                        `Blocked attempt to access restricted file: ${fileName}`);
+                        res.status(403).end("Forbidden: Access Denied");
+                        return next();
+                    }
+                }
+                const fullPath = this.sys.path.join(dir, relativePath);
+                // 3. Path Normalization & Security Check (Sandbox)
+                const resolvedPath = this.sys.path.resolve(fullPath);
+                const rootDir = this.sys.path.resolve(dir);
+                const projectRoot = this.sys.__root__;
+                if (!options.allowOutsideRoot &&
+                    !options.unsafe &&
+                    projectRoot) {
+                    // Check 1: Is the defined directory inside the project root?
+                    if (!rootDir.startsWith(projectRoot)) {
+                        this.qLog.warn(
+                        //    "security",
+                        `Blocked attempt to serve directory outside project root: ${rootDir}`);
+                        res.status(403).end("Forbidden: Project Root Violation");
+                        return next();
+                    }
+                    // Check 2: Is the requested file inside the defined directory? (Standard Jail)
+                    if (!resolvedPath.startsWith(rootDir)) {
+                        this.qLog.warn(
+                        // "security",
+                        `Blocked attempt to access file outside static root: ${resolvedPath}`);
+                        res.status(403).end("Forbidden: Sandbox Violation");
+                        return next();
+                    }
+                }
+                // 4. LRU Meta-Cache (Anti-DDoS)
+                const cacheHit = this.metaCache.get(resolvedPath);
+                if (cacheHit && !cacheHit.exists) {
+                    return next();
+                }
+                // 5. Existence Check (with Meta-Cache Protection)
+                if (!this.sys.fs.exists(resolvedPath)) {
+                    this.metaCache.set(resolvedPath, false);
+                    return next();
+                }
+                // Skip if it's a directory
+                if (this.sys.fs.isDir(resolvedPath)) {
+                    return next();
+                }
+                // 6. Delegation to XHSC (Go)
+                const worker = this.app._xhscWorker;
+                if (worker) {
+                    res.status(0);
+                    // Handle Cache-Control (Local option > Global config)
+                    const maxAge = options.maxAge ?? this.globalConfig.defaultMaxAge;
+                    if (maxAge !== undefined) {
+                        res.setHeader("Cache-Control", `public, max-age=${maxAge}`);
+                    }
+                    worker.delegateStatic(req.id, resolvedPath);
+                    res.end();
+                    return next();
+                }
+                else {
+                    res.status(500).send("[XStatic] High-performance static serving requires XHSC Clustering mode.");
+                }
+            }
+            catch (err) {
+                this.logger.error("server", `XStatic failure: ${err}`);
+                next();
+            }
+        });
+        this.logger.debug("server", `Static route defined: ${normalizedRoute} -> ${dir}`);
+    }
+    /**
+     * @deprecated Use {@link define} instead. Will be removed in a future release.
+     *
+     * Alias for {@link define} — kept for beta compatibility only.
+     *
+     * @param route   - The URL prefix to mount (e.g. `"/assets"`).
+     * @param dir     - The filesystem directory to serve from.
+     * @param options - Optional per-route overrides. See {@link StaticOptions}.
+     *
+     * @example
+     * ```typescript
+     * // ❌ Deprecated — avoid in new code
+     * xs.serve("/assets", "./public");
+     *
+     * // ✅ Preferred
+     * xs.define("/assets", "./public");
+     * ```
+     */
+    serve(_route, _dir, _options = {}) {
+        const msg = "XStatic.serve() is deprecated. Please use XStatic.define().";
+        this.qLog.error(
+        // "server",
+        msg);
+        // this.define(route, dir, options);
+        throw new Error(msg);
+    }
+}
+
+exports.XStatic = XStatic;
+//# sourceMappingURL=XStatic.js.map

package/dist/cjs/src/server/components/static/XStatic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"XStatic.js","sources":["../../../../../../src/server/components/static/XStatic.ts"],"sourcesContent":[null],"names":["Configs","XStaticMetaCache","Logger","QuickLogger","IXStaticSchem","UriNormalizer"],"mappings":"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"}

package/dist/cjs/src/server/const/default.js

@@ -311,6 +311,7 @@ const DEFAULT_OPTIONS = {
         },
     },
     plugins: {
+        allowLifecycleByDefault: false, // Zero-Trust Security: Plugins must explicitly whitelist their hooks. This default prevents unknown plugins from accessing sensitive lifecycle events (start, ready, stop).
         routeOptimization: {
             enabled: false, // Disabled by default for performance
             analysisInterval: 300000, // 5 minutes