Security Core

Environment Security Shield

XyPriss features a military-grade Environment Security Shield designed to eliminate secret leakage and enforce a zero-trust architecture for application variables.

Zero-Leak Protection

Security Shield Interception

Access Requestprocess.env.KEY

Env ShieldProxy Validation

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 State

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

Mechanism of Action

XyPriss uses a native System Proxy to intercept all access to process.env, implementing two primary security layers.

1. Project-Root Isolation

The framework includes a built-in, ultra-fast .env loader that operates on strictly defined Project Boundaries.

01
Project Discovery
A directory is considered a project boundary if it contains node_modules and package.json.
02
Strict Isolation
Sub-projects (plugins, mods) are isolated from parents. They only access their local .env file, ensuring deterministic config.

2. Variable Masking

When code attempts to read from process.env, the shield performs a real-time security check against the official whitelist:

Category	Variable Pattern	Action
System Core	`NODE_ENV`, `PATH`, `PORT`	Pass Through
Framework	`XYPRISS_`, `XY_`	Pass Through
Security	`ENC_`, `DOTENV_`	Pass Through
Third Party	All others (DB_URL, API_KEY, etc.)	Mask (undefined)

The Official API

To access your application secrets safely, use the system-managed environment manager. This ensures the access is logged and verified by the security layer.

typescript

// ❌ Discouraged: Will return undefined for custom secrets
const apiKey = process.env.MY_API_KEY;

// ✅ Recommended: Official and secure access
const apiKey = __sys__.__env__.get("MY_API_KEY");

Security Warning

Variables not in the whitelist will return undefined via process.env and will trigger a security warning in the console. This is intended behavior to prevent silent leaks.

Best Practices

Use XYPRISS_ prefix for variables that MUST be accessed by legacy libraries.

Standardize on __sys__.__env__.get() for all business logic.

Never commit .env files to version control; they are hardware-local.

Explore Core Concepts

Return to the core architectural concepts of the XyPriss ecosystem.