Security Core

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.

Version Compatibility: XyPriss v9.14.35+
•
Status: Hardened Zero-Trust Sandbox (libXESS Active)
Zero-Leak Protection

Security Shield & Honeypot Interception

Access Attemptprocess.env or fs.read
libXESS Core
Honeypot / MaskingDecoys or Undefined
Process SandboxSecrets Secured
Prevention

Blocks third-party packages from harvesting database credentials or private keys.

Canary Decoys

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

typescript
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)

typescript
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:

typescript
// 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:

jsonc
{
    "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:

VariablePurpose
NODE_ENVActive execution environment mode
PORTConfigured listening port
PATHOperating system binary search path
USERActive operating system user
HOMECurrent user home directory
LANGSystem localization and charset
COLORTERMTerminal 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

jsonc
{
  "$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:

jsonc
{
  "$env": {
    "whitelist": ["PORT", "CUSTOM_ALLOWED_VAR"],
    "replaceDefaultWhitelist": true
  }
}

Scoped Package Environment Sandboxing ($env.packages)

Advisory ID: XSA-XESS-028
By default, $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.

jsonc
{
  "$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

OptionTypeDefaultDescription
$envObjectundefinedRoot environment security configuration block in xypriss.config.jsonc.
$env.whiteliststring[][]Explicit list of variable keys permitted for direct process.env access globally.
$env.replaceDefaultWhitelistbooleanfalseWhen true, discards all default system keys and enforces only the custom whitelist.
$env.packagesRecord<string, PackageCfg>undefinedPer-package scoped sandbox configurations (XSA-XESS-028).
$env.packages.<pkg>.whiteliststring[][]Variables whitelisted strictly for the named package.
$env.packages.<pkg>.inheritGlobalbooleanfalseWhen 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.

Explore Core Concepts

Return to the core architectural concepts of the XyPriss ecosystem.