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 +30 -16
- package/dist/cjs/index.js +98 -45
- package/dist/cjs/index.js.map +1 -1
- package/dist/esm/index.js +98 -45
- package/dist/esm/index.js.map +1 -1
- package/package.json +1 -1
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** —
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
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.
|
|
358
|
+
#### 3. Internal Framework Configuration
|
|
345
359
|
|
|
346
|
-
|
|
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
|
-
**[
|
|
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
|
-
//
|
|
35383
|
-
|
|
35384
|
-
|
|
35385
|
-
|
|
35386
|
-
|
|
35387
|
-
|
|
35388
|
-
|
|
35389
|
-
|
|
35390
|
-
|
|
35391
|
-
|
|
35392
|
-
|
|
35393
|
-
|
|
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:
|
|
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 (
|
|
35438
|
-
|
|
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
|
-
|
|
35449
|
-
|
|
35450
|
-
|
|
35451
|
-
|
|
35452
|
-
|
|
35453
|
-
|
|
35454
|
-
|
|
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
|
|
35458
|
-
|
|
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
|
-
//
|
|
37182
|
-
|
|
37183
|
-
|
|
37184
|
-
|
|
37185
|
-
|
|
37186
|
-
|
|
37187
|
-
|
|
37188
|
-
|
|
37189
|
-
|
|
37190
|
-
|
|
37191
|
-
|
|
37192
|
-
|
|
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
|
-
...(
|
|
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
|