Environment Security Shield (XESS / libXESS)
XyPriss features a military-grade Environment Security Shield (XESS) powered by a Go-native libXESS engine designed to eliminate secret leakage, honeypot unauthorized filesystem reads, and enforce Zero-Trust process confinement.
Security Shield & Honeypot Interception
Blocks third-party packages from harvesting database credentials or private keys.
Injects deceptive fake values into unauthorized filesystem reads.
The libXESS Engine Core
Built as a low-level Go core embedded directly into the XHSC network engine, libXESS operates at the process supervision and runtime boundary layer before application code evaluation begins. It acts as a hardened runtime shield and filesystem honeypot — not a substitute for OS-level MAC policies or hardware HSM enclaves.
Go-Native libXESS Core
Operates directly inside the native XHSC engine prior to runtime initialization, placing process memory and environment state inside a cryptographically verified boundary.
Active Honeypot Canaries
If rogue dependencies or automated scanners attempt direct filesystem reads on configuration files (fs.readFileSync('.env')), libXESS intercepts reads and serves dynamically generated decoys instead of actual secrets.
Deterministic Subproject Scoping
In monorepos or multi-service setups, libXESS enforces strict boundaries between plugins and parent projects, preventing cross-tenant secret leakage.
Native Dual-Interlock Enforcement
Both the xfpm supervisor and native XHSC network core actively verify active libXESS confinement; unshielded processes are blocked before binding ports.
Comparison: Traditional Backends vs. XyPriss (libXESS)
Consider a scenario where an untrusted third-party npm package executes unauthorized file reading or variable inspection:
Traditional Node.js / Bun Backends
import fs from "fs";
// 1. Secret harvesting via process.env
console.log(process.env.DATABASE_URL);
// Output: "postgresql://admin:super_secret@db.prod:5432/db"
// Status: CRITICAL LEAK (All secrets globally exposed)
// 2. Direct filesystem read of .env file
console.log(fs.readFileSync(".env", "utf-8"));
// Output: Real plaintext secrets from disk
// Status: CRITICAL LEAK (Disk contents stolen)XyPriss (Powered by libXESS)
import fs from "fs";
// 1. Secret harvesting attempt via process.env
console.log(process.env.DATABASE_URL);
// Output: undefined (ACCESS BLOCKED)
// 2. Direct filesystem read attempt on .env
console.log(fs.readFileSync(".env", "utf-8"));
// Output: DATABASE_URL="xy_decoy_database_url_5c940b28"
// Status: HONEYPOT ENGAGED (Deceptive decoy values)
// 3. Authorized application code via official API
console.log(__sys__.__env__.get("DATABASE_URL"));
// Output: "postgresql://admin:super_secret@db.prod:5432/db"
// Status: SECURE (Authentic credentials in memory)Architectural Principles
1. Mandatory Supervised Execution via XFPM
All XyPriss applications must be launched through the official XFPM CLI (xfpm dev, xfpm run, xfpm start), which initializes libXESS. Direct unconfined execution (node index.js or bun index.js) is blocked by design.
2. Variable Masking & Access Control
By default, global process.env is shielded. System variables essential for OS stability pass through, while unwhitelisted access attempts return undefined (or trigger security audit logging in development profiles) and unauthorized file reads receive honeypot decoys.
3. Unified Developer API
All application configurations must be retrieved through the native system accessor:
// Discouraged: returns undefined for shielded variables
const apiKey = process.env.DATABASE_URL;
// Recommended: secure, authenticated access via libXESS
const dbUrl = __sys__.__env__.get("DATABASE_URL");
// Enforces existence (throws if missing or empty)
const secretKey = __sys__.__env__.getStrict("JWT_SECRET");
// Ephemeral buffer retrieval with deterministic zeroization (no JS string materialized)
const signatureValid = __sys__.__env__.withSecret("WEBHOOK_HMAC_KEY", (keyBytes) => {
return verifyHmac(payload, keyBytes);
});Declarative Configuration References (&(env).KEY)
Configuration files (xypriss.config.jsonc) support declarative environment variable interpolation via the &(env).KEY syntax:
{
"server": {
"port": "&(env).PORT || 3000",
"host": "&(env).HOST || '127.0.0.1'"
},
"security": {
"csrf": {
"secret": "&(env).CSRF_SECRET"
}
},
"$vars": {
"__port__": "&(env).PORT || 3000",
"__db_url__": "&(env).DATABASE_URL"
}
}Memory & Heap Retention Boundaries
Understanding what libXESS guarantees in memory is essential for designing secure production services:
At Rest (Before Retrieval)
Secrets are held exclusively in the libXESS supervisor vault. Before get(), getStrict(), or withSecret() is called, 0 secret bytes appear in process.env, /proc/<PID>/environ, or the V8/JavaScriptCore heap.
After get() / getStrict()
JavaScript strings are immutable and managed by the runtime garbage collector (V8 / JSC). Once retrieved via get() or getStrict(), the value exists as a standard JS string in the heap until reclaimed by GC. libXESS cannot retroactively zeroize an immutable JS string.
Zeroizable Ephemeral Buffers (withSecret)
For cryptographic operations, signing, or native calls that do not require a JS string, use __sys__.__env__.withSecret(key, (buf) => ...). It transfers the secret as raw bytes into a mutable Uint8Array and deterministically wipes it (buf.fill(0)) in a finally block as soon as the callback finishes (sync or async). Avoid decoding buf into a JS string inside the callback. Note that while withSecret wipes the application Uint8Array and avoids JS heap strings, it cannot retroactively wipe internal native buffers allocated by third-party primitives (such as OpenSSL contexts during crypto.createHmac).
Standard Whitelisted Variables
The following system variables remain directly accessible via process.env to ensure operating system and runtime interoperability:
| Variable | Purpose |
|---|---|
| NODE_ENV | Active execution environment mode |
| PORT | Configured listening port |
| PATH | Operating system binary search path |
| USER | Active operating system user |
| HOME | Current user home directory |
| LANG | System localization and charset |
| COLORTERM | Terminal color capabilities |
| XYPRISS_* | Official framework runtime parameters |
Declarative Configuration ($env)
For third-party dependencies that strictly require access to specific environment variables via process.env, configure explicit exceptions using the declarative $env block in xypriss.config.jsonc.
Extending the Default Whitelist
{
"$env": {
"whitelist": ["STRIPE_PUBLIC_KEY", "LEGACY_CLIENT_ID"]
}
}Strict Whitelist Replacement
For zero-tolerance production deployments requiring complete exclusion of default system variables, set replaceDefaultWhitelist: true:
{
"$env": {
"whitelist": ["PORT", "CUSTOM_ALLOWED_VAR"],
"replaceDefaultWhitelist": true
}
}Scoped Package Environment Sandboxing ($env.packages)
$env.whitelist grants global access to whitelisted variables for both the host application and any unconfigured dependency in node_modules. To prevent sensitive secrets from being accessible across the entire dependency graph, configure Scoped Package Sandboxes using $env.packages.When a package is declared under $env.packages, its access to process.env is restricted to its own scoped whitelist. It cannot see the global $env.whitelist or default system keys unless inheritGlobal: true is explicitly enabled.
{
"$env": {
// Global whitelist: accessible by host app and packages without a dedicated sandbox
"whitelist": ["APP_PUBLIC_URL"],
"packages": {
// Dedicated sandbox for xypriss-security:
// Only 'xypriss-security' can read these secrets from process.env.
// Other packages (e.g. lodash, express) will receive undefined + [SECURITY] warning.
"xypriss-security": {
"whitelist": ["ENC_SECRET_KEY", "ENC_SECRET_SEED", "XYPRISS_SEC_WARNINGS"],
"inheritGlobal": false // Default: does NOT inherit global whitelist
},
// Scoped access with global inheritance:
"@stripe/stripe-node": {
"whitelist": ["STRIPE_API_KEY"],
"inheritGlobal": true // Can access STRIPE_API_KEY + global whitelist (APP_PUBLIC_URL, PORT, etc.)
}
}
}
}Package Sandboxing Rules
1. Scoped Isolation: A variable defined solely in packages[pkg].whitelist can only be read by that specific package. All other callers (including other dependencies and undeclared packages) receive undefined.
2. Selective Inheritance (inheritGlobal): false (default) restricts the package exclusively to its explicit whitelist; true grants access to its scoped whitelist plus all global whitelist and default system keys.
3. Undeclared Packages: Packages not listed in packages retain standard access to the global $env.whitelist and default system keys.
Configuration Reference
| Option | Type | Default | Description |
|---|---|---|---|
| $env | Object | undefined | Root environment security configuration block in xypriss.config.jsonc. |
| $env.whitelist | string[] | [] | Explicit list of variable keys permitted for direct process.env access globally. |
| $env.replaceDefaultWhitelist | boolean | false | When true, discards all default system keys and enforces only the custom whitelist. |
| $env.packages | Record<string, PackageCfg> | undefined | Per-package scoped sandbox configurations (XSA-XESS-028). |
| $env.packages.<pkg>.whitelist | string[] | [] | Variables whitelisted strictly for the named package. |
| $env.packages.<pkg>.inheritGlobal | boolean | false | When true, merges the global whitelist and default keys into this package's scope. |
Best Practices
Adopt __sys__.__env__
Treat process.env as obsolete for application business logic.
Use getStrict() for Critical Secrets
Fail fast during startup if database connection strings, encryption keys, or external tokens are missing.
Avoid Broad Whitelists
Keep $env.whitelist minimal. Only expose keys strictly required by third-party packages.
Always Launch via XFPM
Use xfpm run, xfpm dev, xfpm start, or xfpm exec to engage libXESS confinement. Direct execution outside xfpm triggers XessShieldRequiredError.
Minimize JS Heap Retention
Prefer __sys__.__env__.withSecret() for binary/crypto secrets. When a string is required by a third-party SDK, call get() / getStrict() at the latest possible moment in a short local scope rather than storing secrets in long-lived globals.
Verify Production Profile
Setting NODE_ENV=production alone does not switch __sys__.__env__.mode. Explicitly configure the production profile and verify __sys__.__env__.mode === "production" at startup.
Disable Heap Introspection
Strictly disable --inspect, v8.writeHeapSnapshot(), and profiling endpoints in production so attackers cannot inspect JS strings already retrieved into the heap.
Return to the core architectural concepts of the XyPriss ecosystem.
