xypriss 9.14.17 → 9.14.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -59,7 +59,7 @@ This separation allows each layer to operate in its optimal domain: compiled nat
59
59
  - **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.
60
60
  - **File Upload Management** — Production-ready multipart/form-data handling with automatic validation, error handling, and the `getMimes()` helper for extension-to-mime mapping.
61
61
  - **Native XML/JSON Conversion Framework** — High-speed, streaming conversion layer integrated into the XHSC core. Automatically transcodes incoming XML to JSON and mirrors outgoing responses, supporting legacy XML clients with zero application-layer effort.
62
- - **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.
62
+ - **Environment Security Shield (Powered by `libXESS`)** — Kernel- and OS-level Zero-Trust secret isolation. Unlike standard runtimes that only proxy `process.env`, `libXESS` enforces OS process boundaries and serves active **decoy honeypots** on direct `.env` filesystem reads, neutralizing supply-chain exfiltration attacks.
63
63
  - **Built-in DotEnv Loader** — Zero-dependency, ultra-fast `.env` parser with automatic support for `.env`, `.env.local`.
64
64
  - **Extensible Plugin System** — Permission-based plugin architecture with lifecycle hooks and strict security controls (sandboxed restricted instances).
65
65
  - **XInS (XyPriss Intelligent Scaling)** — Native Auto-Scaling engine powered by AIMD congestion control. Dynamically adjusts Node.js concurrency based on real-time event loop latency to prevent starvation and ensure zero-downtime stability under extreme load (5000+ concurrent connections). [Read the XInS Guide](https://xypriss.nehonix.com/docs/XInS.md).
@@ -318,38 +318,52 @@ XyPriss uses a Capability-Based Security Model for plugins. Each plugin operates
318
318
 
319
319
  **[Learn more about Plugin Permissions →](https://xypriss.nehonix.com/docs/plugins/permissions)**
320
320
 
321
- ### Environment Security Shield
321
+ ### Environment Security Shield (Powered by `libXESS`)
322
322
 
323
- XyPriss implements a **Strict Environment Shield** to protect your secrets and enforce coding best practices. By default, XyPriss masks direct access to `process.env` for non-essential variables to prevent accidental exposure by third-party libraries or logging debugging artifacts.
323
+ Most Node.js security tools merely wrap `process.env` in a JavaScript Proxy. However, malicious npm dependencies or automated supply-chain scanners can effortlessly bypass JavaScript Proxies by reading the filesystem directly via `fs.readFileSync(".env")` or running shell sub-commands.
324
324
 
325
- #### 1. Zero-Dependency Loader
325
+ **XyPriss does not settle for JavaScript-level masking.** It enforces an operating system-level process boundary powered by **`libXESS`** (Bipolar Zero-Trust Confinement), embedded directly within the native `xfpm` supervisor and `XHSC` runtime:
326
+
327
+ - **OS & Kernel-Level Confinement**: Live secrets are vaulted strictly in-memory during bootstrap and never exposed in plaintext to the host filesystem.
328
+ - **Active Honeypot Canaries (Tarpits)**: When an unauthorized third-party library attempts to bypass JavaScript by reading `.env` directly from the disk, `libXESS` intercepts the I/O at the OS level and transparently serves **synthetic decoy values** (honeypot canaries). Attackers and automated harvesters exfiltrate useless tokens, alerting your monitoring systems without compromising real credentials.
329
+ - **Mandatory Supervision**: Unconfined execution (launching via standard `node` instead of `xfpm`) is blocked by design. The native `XHSC` engine refuses to bind network ports without an active `libXESS` security session.
326
330
 
327
- No need for `dotenv` or other external packages. XyPriss automatically loads variables from:
331
+ #### 1. Zero-Dependency Loader
328
332
 
333
+ No need for `dotenv` or external packages. XyPriss automatically loads variables from:
329
334
  1. `.env`
330
335
  2. `.env.local`
331
336
 
332
- #### 2. The Shield in Action
333
-
334
- Standard system variables (like `PATH`, `USER`, `NODE_ENV`) are whitelisted for system stability, but your custom application variables are protected.
337
+ #### 2. The Shield in Action: JS Masking vs. OS-Level Honeypot
335
338
 
336
339
  ```typescript
337
- // ❌ Blocked & Masked (returns undefined + Security Warning)
338
- const secret = process.env.DATABASE_PASSWORD;
339
-
340
- // ✅ Official & Secure Way
341
- const secret = __sys__.__env__.get("DATABASE_PASSWORD");
340
+ import fs from "node:fs";
341
+
342
+ // ❌ 1. Secret harvesting via process.env
343
+ console.log(process.env.DATABASE_PASSWORD);
344
+ // Output: undefined
345
+ // Status: ACCESS BLOCKED (JavaScript-level masking active)
346
+
347
+ // ❌ 2. Bypassing JS via direct filesystem read (.env)
348
+ console.log(fs.readFileSync(".env", "utf-8"));
349
+ // Output: DATABASE_PASSWORD="xy_decoy_db_pass_5c940b2874c0"
350
+ // Status: 🛡️ HONEYPOT ENGAGED (libXESS intercepts at the OS level and returns decoys!)
351
+
352
+ // ✅ 3. Official authenticated business logic in memory
353
+ console.log(__sys__.__env__.get("DATABASE_PASSWORD"));
354
+ // Output: "postgresql://admin:super_secret@db.prod.internal:5432/main"
355
+ // Status: SECURE (Authentic credentials delivered strictly in-memory to authorized code)
342
356
  ```
343
357
 
344
- #### 3. Official Configuration
358
+ #### 3. Internal Framework Configuration
345
359
 
346
- For project configuration, use the `XYPRISS_` prefix to bypass the shield for internal framework variables:
360
+ Internal framework variables using the `XYPRISS_` prefix bypass the shield for platform-level configurations:
347
361
 
348
362
  - `XYPRISS_PORT`
349
363
  - `XYPRISS_HOST`
350
364
  - `XYPRISS_REDIS_URL`
351
365
 
352
- **[Learn more about Environment Security →](https://xypriss.nehonix.com/docs/system/environment)**
366
+ 👉 **[Read the Full Environment Security Shield & libXESS Documentation →](https://xypriss.nehonix.com/docs/security/environment-shield)**
353
367
 
354
368
  ### Security Disclosure Policy
355
369
 
package/dist/cjs/index.js CHANGED
@@ -16777,12 +16777,47 @@ class ConfigLoader {
16777
16777
  __sys__$1.vars.update(config.$vars);
16778
16778
  }
16779
16779
  }
16780
+ // Apply ServerOptions sections to Configs (centralized configuration management)
16781
+ const recognizedServerOptionKeys = [
16782
+ "server",
16783
+ "multiServer",
16784
+ "security",
16785
+ "logging",
16786
+ "fileUpload",
16787
+ "performance",
16788
+ "cache",
16789
+ "requestManagement",
16790
+ "notFound",
16791
+ "send",
16792
+ "env",
16793
+ "cluster",
16794
+ "plugins",
16795
+ ];
16796
+ const serverOptionsToApply = {};
16797
+ for (const key of recognizedServerOptionKeys) {
16798
+ if (config[key] !== undefined) {
16799
+ serverOptionsToApply[key] = config[key];
16800
+ }
16801
+ }
16802
+ if (Object.keys(serverOptionsToApply).length > 0) {
16803
+ logger$2.debug("server", `ConfigLoader: Merging discovered server configuration into Configs`);
16804
+ ConfigurationManager.merge(serverOptionsToApply);
16805
+ }
16780
16806
  // Process internal configuration
16781
16807
  const internal = config?.vars?.internal || config?.internal || config?.$internal;
16782
16808
  if (internal) {
16783
16809
  this.processInternalConfig(internal, projectRoot, configDir);
16784
16810
  }
16785
16811
  }
16812
+ /**
16813
+ * Centralized application of server options provided to createServer()
16814
+ * Enriches global configuration state and reconciles mutual exclusivity
16815
+ */
16816
+ applyServerOptions(options = {}) {
16817
+ if (!options || typeof options !== "object")
16818
+ return;
16819
+ ConfigurationManager.merge(options);
16820
+ }
16786
16821
  /**
16787
16822
  * Processes the internal configuration block.
16788
16823
  * Handle specialized filesystems and meta logic defined by plugin IDs.
@@ -35379,22 +35414,23 @@ class XemsBuiltinPlugin {
35379
35414
  const app = server.app;
35380
35415
  const logger = app.logger;
35381
35416
  // 1. Configuration Extraction
35382
- // Use local app config strictly to avoid global singleton pollution in multi-server/auxiliary modes
35383
- // If not explicitly configured, fallback to global defaults only if NOT an auxiliary server
35384
- let xemsOptions = app.configs?.server?.xems || ConfigurationManager.get("server")?.xems;
35385
- if (!xemsOptions) {
35386
- if (app.configs?.isAuxiliary) {
35387
- // Auxiliary servers should NEVER auto-spawn persistence unless explicitly requested.
35388
- // We provide minimal defaults to avoid crashes but keep features disabled.
35389
- xemsOptions = { enable: false };
35390
- }
35391
- else {
35392
- // Fallback to global singleton only for primary/non-auxiliary servers
35393
- xemsOptions = ConfigurationManager.get("server")?.xems || { enable: false };
35394
- }
35417
+ // Cascade defaults from global configuration if child only specified partial options or none
35418
+ const globalXems = ConfigurationManager.get("server")?.xems;
35419
+ const localXems = app.configs?.server?.xems;
35420
+ let xemsOptions;
35421
+ if (localXems && globalXems && typeof globalXems === "object") {
35422
+ // Intelligent cascade merge: child inherits parent defaults but can override selectively
35423
+ xemsOptions = mergeWithDefaults(globalXems, localXems);
35424
+ }
35425
+ else if (localXems) {
35426
+ xemsOptions = localXems;
35427
+ }
35428
+ else if (globalXems) {
35429
+ xemsOptions = globalXems;
35430
+ }
35431
+ else {
35432
+ xemsOptions = { enable: false };
35395
35433
  }
35396
- // Expose this instance's runner on the app object for multi-server support
35397
- app.xems = this.runner;
35398
35434
  const isAuxiliary = app.configs?.isAuxiliary;
35399
35435
  if (!isAuxiliary) {
35400
35436
  logger.info("plugins", "Initializing XEMS Built-in Core Plugin...");
@@ -35404,6 +35440,7 @@ class XemsBuiltinPlugin {
35404
35440
  const rawSecret = xemsOptions.secret || xemsOptions.persistence?.secret;
35405
35441
  const rawResources = xemsOptions.resources ||
35406
35442
  xemsOptions.persistence?.resources;
35443
+ const rawCookieOpts = xemsOptions.cookieOptions || {};
35407
35444
  this.sessionOptions = {
35408
35445
  sandbox: xemsOptions.sandbox || "auth-session",
35409
35446
  cookieName: xemsOptions.cookieName || "xems_token",
@@ -35412,10 +35449,13 @@ class XemsBuiltinPlugin {
35412
35449
  autoRotation: xemsOptions.autoRotation ?? true,
35413
35450
  attachTo: xemsOptions.attachTo || "session",
35414
35451
  gracePeriod: xemsOptions.gracePeriod || 15000,
35415
- cookieOptions: xemsOptions.cookieOptions ?? {
35416
- httpOnly: true,
35417
- secure: true,
35418
- sameSite: "Strict",
35452
+ cookieOptions: {
35453
+ httpOnly: rawCookieOpts.httpOnly ?? true,
35454
+ secure: rawCookieOpts.secure ?? true,
35455
+ sameSite: rawCookieOpts.sameSite ?? "Strict",
35456
+ ...(rawCookieOpts.domain ? { domain: rawCookieOpts.domain } : {}),
35457
+ ...(rawCookieOpts.path ? { path: rawCookieOpts.path } : {}),
35458
+ ...rawCookieOpts,
35419
35459
  },
35420
35460
  };
35421
35461
  if (!isAuxiliary) {
@@ -35434,10 +35474,12 @@ class XemsBuiltinPlugin {
35434
35474
  }
35435
35475
  this.logger.debug("xems", `Server ${app.id ?? "(unknown)"} initialized XEMS. hasValidSecret: ${this.hasValidSecret}, secret: ${secret ? "PROVIDED" : "MISSING"}`);
35436
35476
  // 2. Storage & Vault Initialization
35437
- if (rawPath && secret && this.hasValidSecret) {
35438
- const pathStr = rawPath;
35477
+ if (secret && this.hasValidSecret) {
35478
+ // If path is specified, use file-based persistent runner.
35479
+ // If no path is specified, use shared volatile runner for all instances sharing this secret/cluster.
35480
+ const pathStr = rawPath || "__shared_volatile_vault__";
35439
35481
  // Use the static factory to get/create a runner for this path.
35440
- // This ensures multiple servers/plugins sharing a path also share the process.
35482
+ // This ensures multiple servers/plugins sharing a path (or cluster) also share the process.
35441
35483
  this.runner = XemsRunner.getInstance(pathStr, {
35442
35484
  secret,
35443
35485
  cacheSize: rawResources?.cacheSize,
@@ -35445,17 +35487,23 @@ class XemsBuiltinPlugin {
35445
35487
  this.logger.debug("xems", `XemsRunner instances count: ${XemsRunner.runnersByPath?.size ?? 0} for path: ${pathStr}`);
35446
35488
  // Attach the shared runner to the app
35447
35489
  app.xems = this.runner;
35448
- try {
35449
- this.runner.enablePersistence(pathStr, secret, {
35450
- cacheSize: rawResources?.cacheSize,
35451
- });
35452
- }
35453
- catch (err) {
35454
- logger.error("plugins", "Failed to enable XEMS persistence on shared runner", err);
35490
+ if (rawPath) {
35491
+ try {
35492
+ this.runner.enablePersistence(rawPath, secret, {
35493
+ cacheSize: rawResources?.cacheSize,
35494
+ });
35495
+ }
35496
+ catch (err) {
35497
+ logger.error("plugins", "Failed to enable XEMS persistence on shared runner", err);
35498
+ }
35455
35499
  }
35456
35500
  }
35457
- else if (!isAuxiliary && xemsOptions.enable !== false) {
35458
- logger.warn("plugins", "XEMS requested but mandatory 'path' or 32-byte 'secret' is missing. Please provide both.");
35501
+ else {
35502
+ // Expose fallback runner on app
35503
+ app.xems = this.runner;
35504
+ if (!isAuxiliary && xemsOptions.enable !== false) {
35505
+ logger.warn("plugins", "XEMS requested but mandatory 'path' or 32-byte 'secret' is missing. Please provide both.");
35506
+ }
35459
35507
  }
35460
35508
  // 3. Resource & Health Validation (Warmup)
35461
35509
  try {
@@ -37178,23 +37226,27 @@ class MultiServerManager {
37178
37226
  // 3. Handle port and host explicitly to ensure they are in the right place
37179
37227
  // MultiServerConfig has top-level port/host for convenience,
37180
37228
  // but ServerOptions expects them in the 'server' object.
37181
- // Hoist security from server block if it exists there (users often nest it)
37182
- if (config.server?.security) {
37183
- overrides.security = {
37184
- ...(overrides.security || {}),
37185
- ...config.server.security,
37186
- };
37187
- }
37188
- overrides.server = {
37189
- ...(this.baseConfig?.server || {}),
37190
- ...(overrides.server || {}),
37191
- ...(config.port ? { port: config.port } : {}),
37192
- ...(config.host ? { host: config.host } : {}),
37193
- };
37229
+ // Cascade and merge security options deeply
37230
+ const baseSecurity = this.baseConfig?.security || {};
37231
+ const childSecurity = config.server?.security || config.security || {};
37232
+ if (Object.keys(baseSecurity).length > 0 || Object.keys(childSecurity).length > 0) {
37233
+ overrides.security = mergeWithDefaults(baseSecurity, childSecurity);
37234
+ }
37235
+ // Cascade server options (specifically server.xems, cookieOptions, secret, etc.)
37236
+ const baseServer = this.baseConfig?.server || {};
37237
+ const childServer = config.server || {};
37238
+ const mergedServer = mergeWithDefaults(baseServer, childServer);
37239
+ if (config.port)
37240
+ mergedServer.port = config.port;
37241
+ if (config.host)
37242
+ mergedServer.host = config.host;
37243
+ overrides.server = mergedServer;
37194
37244
  // Enforce mutual exclusivity: autoKillConflict vs autoPortSwitch per server instance
37195
37245
  reconcilePortConflictResolution(overrides.server, config.server);
37246
+ const baseLogging = this.baseConfig?.logging || {};
37247
+ const childLogging = config.logging || {};
37196
37248
  overrides.logging = {
37197
- ...(overrides.logging || {}),
37249
+ ...mergeWithDefaults(baseLogging, childLogging),
37198
37250
  instanceName: config.id,
37199
37251
  };
37200
37252
  rejectInternalFlag(overrides);
@@ -38415,6 +38467,7 @@ function createServer(options = {}) {
38415
38467
  rejectInternalFlag(options);
38416
38468
  // 1. Initial setup
38417
38469
  configLoader.loadAndApplySysConfig();
38470
+ configLoader.applyServerOptions(options);
38418
38471
  Logger.getInstance(options.logging);
38419
38472
  const xms = options?.multiServer?.servers; // XMS = Xypriss MultiServer
38420
38473
  // 2. Check for Multi-Server mode