Security Core

Environment Security Shield (XESS)

XyPriss features a military-grade Environment Security Shield (XESS) designed to eliminate secret leakage and enforce a robust application architecture.

Zero-Leak Protection

Security Shield Interception

Access Requestprocess.env.KEY

Env ShieldProxy Interception

MaskingUndefined (Safe)

SecuredAccess Blocked

Prevention

Blocks third-party libraries from reading sensitive credentials.

Privacy

Eliminates accidental logging of production secrets.

Why the Shield?

Traditional Node.js applications rely heavily on process.env. While convenient, this approach introduces critical security vulnerabilities that XyPriss aims to resolve:

Global Exposure

Any dependency can read your entire environment, potentially leaking database keys to malicious telemetry services.

Accidental Logging

Logging process.env during debugging often prints sensitive secrets to plaintext cloud logs.

Implicit Dependencies

Code becomes hard to test and maintain when it depends on global, mutable environment state.

How it Works

XyPriss uses a native System Proxy to intercept all access to process.env.

1. Project-Root Isolation

XyPriss includes a built-in, ultra-fast .env loader that operates on Project Boundaries.

01
Project Discovery
A directory is considered a project if it contains node_modules and package.json.
02
Scoped Loading
The system automatically loads the .env file belonging to the project root.
03
Strict Isolation
Sub-projects (plugins, mods) are isolated from their parents. They only access their own local .env, ensuring configuration management is deterministic and scoped.

2. Variable Masking

When code attempts to read from process.env, the shield performs a security check:

Whitelisted core variables (e.g., NODE_ENV, PATH, PORT, TERM) are returned normally.
Project-prefixed variables (starting with XYPRISS_, XY_, ENC_, or DOTENV_) are returned normally.
All other variables return undefined and trigger a security warning in the console.

3. The Official API

To access your application variables, use the system-managed environment manager:

typescript

// ❌ Discouraged
const apiKey = process.env.MY_API_KEY;

// ✅ Recommended
const apiKey = __sys__.__env__.get("MY_API_KEY");

Configuration Whitelist

The following variables are always accessible directly via process.env to ensure system and runtime stability:

Variable	Description
`NODE_ENV`	Current runtime environment
`PORT`	Standard listening port
`PATH`	System execution paths
`USER`	Current system user
`HOME`	User home directory
`LANG`	System language/locale
`COLORTERM`	Terminal color support
`XYPRISS_*`	All official framework configurations
`ENC_*`	Encryption keys and seeds

Best Practices

Use Prefixes: For environment variables that MUST be accessed by legacy libraries, prefix them with XYPRISS_.

Standardize Access: Use __sys__.__env__.get() everywhere in your business logic.

Use .env: This file is automatically loaded and is the ideal place for hardware-local secrets that should never be committed to version control.

Declarative Configuration (XESS)

To guarantee impenetrable security from the very first millisecond of application initialization, the XyPriss Environment Security Shield (XESS) is configured strictly via the $env block in your xypriss.config.jsonc file.

This declarative approach ensures that the shield is fully locked before any ES Module hoisting or routing logic is evaluated by the JavaScript engine.

Active Protection Enforced

The security shield is a core principle of the XyPriss framework. For maximum security, the shield remains active at all times and cannot be disabled.

Extending the Default Whitelist

By default, any key specified in the whitelist array will be appended to the built-in system whitelist. Add the $env block to your xypriss.config.jsonc:

jsonc

{
  "$env": {
    "whitelist": ["MY_CUSTOM_SECRET", "ANOTHER_LEGACY_VAR"]
  }
}

Now, process.env.MY_CUSTOM_SECRET will return its actual value without triggering any warning, while other non-whitelisted keys remain securely masked.

Replacing the Default Whitelist

If you need absolute control and want to restrict the environment strictly to your custom keys (excluding default variables like PATH or LANG), set replaceDefaultWhitelist: true:

jsonc

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

Configuration Options

Option	Type	Default	Description
`$env`	Object	undefined	Security shield configuration block at the root of `xypriss.config.jsonc`.
`$env.whitelist`	string[]	[]	List of custom environment variable keys to whitelist.
`$env.replaceDefaultWhitelist`	boolean	false	If `true`, completely discards the default system whitelist in favor of `whitelist`.

Explore Core Concepts

Return to the core architectural concepts of the XyPriss ecosystem.