xypriss 9.9.7 → 9.10.1

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/api/PluginAPI.js

@@ -1,10 +1,11 @@
 'use strict';
 
+var PluginHookIds = require('../const/PluginHookIds.js');
+
 /**
  * Plugin API
  * Public API for plugin management as documented in PLUGIN_SYSTEM_GUIDE.md
  */
-// ─── Internal State ──────────────────────────────────────────────────────────
 // ─── Blocked / Private members ───────────────────────────────────────────────
 /**
  * Methods that must never be accessible from outside the module.
@@ -113,6 +114,14 @@ class PluginAPI {
         assertNonEmptyString(Sys, "XyPriss Initialization Error: To create a plugin, you MUST provide the plugin's root path or its '__sys__' instance as the second argument to Plugin.create().\n" +
             "Example: return Plugin.create({ ... }, __sys__.__root__);");
         plugin.__root__ = Sys;
+        if (!plugin.name || typeof plugin.name !== "string") {
+            throw new Error(`XyPriss Plugin Error: "name" is missing or invalid.`);
+        }
+        for (const field of ["description", "version"]) {
+            if (!plugin[field] || typeof plugin[field] !== "string") {
+                throw new Error(`XyPriss Plugin Error: "${field}" is missing or invalid on plugin "${plugin.name}".`);
+            }
+        }
         return plugin;
     }
     /**
@@ -168,7 +177,84 @@ class PluginAPI {
         return {
             name: `void-plugin-${Math.random().toString(36).slice(2, 9)}`,
             version: "1.0.0",
+            description: "A void plugin for testing purposes.",
+        };
+    }
+    /**
+     * Performs a deep inspection of a plugin instance to identify and list all required
+     * cryptographic permissions based on implemented hooks.
+     *
+     * This utility is designed for developers to use during the preparation of their
+     * `package.json` manifest (`xfpm.permissions` field).
+     *
+     * @param plugin - The XyPriss plugin instance to inspect.
+     *
+     * @example
+     * ```typescript
+     * const myPlugin = Plugin.create({ ... }, __sys__.__root__);
+     * Plugin.inspect(myPlugin);
+     * ```
+     */
+    inspect(plugin) {
+        const header = `[XyPriss Plugin Inspector] ${plugin.name} v${plugin.version}`;
+        const line = "═".repeat(header.length);
+        const c = {
+            reset: "\x1b[0m",
+            bold: "\x1b[1m",
+            dim: "\x1b[2m",
+            cyan: "\x1b[36m",
+            green: "\x1b[32m",
+            yellow: "\x1b[33m",
+            red: "\x1b[31m",
+            gray: "\x1b[90m",
+            magenta: "\x1b[35m",
         };
+        console.log(`\n${c.cyan}${line}${c.reset}`);
+        console.log(`${c.bold}${c.cyan}${header}${c.reset}`);
+        console.log(`${c.cyan}${line}${c.reset}`);
+        console.log(`${c.bold}Project Root:${c.reset} ${c.gray}${plugin.__root__ || "Not Captured"}${c.reset}`);
+        console.log(`\n${c.magenta}${c.bold}Detected Hooks & Authorized Permission IDs:${c.reset}`);
+        Object.entries(plugin);
+        const hookKeys = Object.keys(PluginHookIds.HOOK_ID_MAP);
+        let foundCount = 0;
+        // List of privileged IDs that require explicit authorization
+        const privilegedIds = [
+            "PLG.MANAGEMENT.MANAGE_PLUGINS",
+            "XHS.PERM.LOGGING.CONSOLE_INTERCEPT",
+            "XHS.PERM.OPS.AUXILIARY_SERVER",
+            "XHS.PERM.ROUTING.BYPASS_NAMESPACE",
+            "XHS.PERM.ROUTING.OVERWRITE_PROTECTED",
+            "XHS.PERM.HTTP.GLOBAL_MIDDLEWARE",
+            "XHS.PERM.SECURITY.CONFIGS",
+            "XHS.PERM.SECURITY.SENSITIVE_DATA",
+            "XHS.HOOK.HTTP.REQUEST",
+            "XHS.HOOK.HTTP.RESPONSE",
+        ];
+        // DEEP SCAN: Check all known hook and permission keys
+        for (const key of hookKeys) {
+            const hookId = PluginHookIds.HOOK_ID_MAP[key];
+            const value = plugin[key];
+            // If the key exists on the plugin instance (function, boolean, array, etc.)
+            if (value !== undefined) {
+                foundCount++;
+                const meta = PluginHookIds.HOOK_METADATA[hookId];
+                const isPrivileged = privilegedIds.includes(hookId);
+                console.log(`\n  ${c.cyan}○${c.reset} ${c.bold}Hook/Capability:${c.reset} ${c.green}${key}${c.reset}`);
+                console.log(`    ${c.bold}ID:${c.reset}   ${c.yellow}${hookId}${c.reset} ${isPrivileged ? `${c.red}${c.bold}⚠️  [PRIVILEGED]${c.reset}` : ""}`);
+                if (meta) {
+                    console.log(`    ${c.gray}Role:${c.reset} ${meta.action}`);
+                    console.log(`    ${c.gray}Info:${c.reset} ${c.dim}${meta.description}${c.reset}`);
+                }
+            }
+        }
+        if (foundCount === 0) {
+            console.log(`\n  ${c.yellow}No hooks requiring special permissions were detected in this plugin.${c.reset}`);
+        }
+        else {
+            console.log(`\n${c.bold}${c.green}Summary: Found ${foundCount} required permissions.${c.reset}`);
+            console.log(`\n${c.bold}${c.cyan}TIP:${c.reset} Copy the IDs above into your package.json's ${c.bold}"xfpm.permissions"${c.reset} array.`);
+        }
+        console.log(`\n${c.cyan}${line}${c.reset}\n`);
     }
 }
 // ─── Proxy Shield ─────────────────────────────────────────────────────────────

package/dist/cjs/src/plugins/api/PluginAPI.js.map

@@ -1 +1 @@
-{"version":3,"file":"PluginAPI.js","sources":["../../../../../src/plugins/api/PluginAPI.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"PluginAPI.js","sources":["../../../../../src/plugins/api/PluginAPI.ts"],"sourcesContent":[null],"names":["HOOK_ID_MAP","HOOK_METADATA"],"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;;;;"}