Logo
System Module

Environment API (__sys__.__env__)

The __sys__.__env__ API is the application's hardened Security Nervous System. Operating on a Zero-Trust architecture, it ensures strict project-level isolation, proxy-shielded secret protection, and deterministic environment management.

Version Compatibility: XyPriss v9.12.67+
•
Status: Hardened Zero-Trust Sandbox
Security Shield Active
Direct access to process.env is neutralized via a restrictive Proxy. Third-party enumeration or non-whitelisted reads will return undefined and emit security warnings to stderr.
Configurable Shield (XESS)
You can declaratively configure the Environment Security Shield (XESS) via xypriss.config.jsonc to whitelist custom keys. See the XESS Configuration Guide for details.

Zero-Trust Security Architecture (5-Layer Shield)

The environment subsystem enforces a Zero-Trust Sandboxing model built on five independent security layers:

1. Map-Isolated Storage

Variables reside in a global store keyed by an unexported module-scoped Symbol (XY_ENV_STORE_KEY). Access is strictly tied to the caller's project root via stack inspection (getCallerProjectRoot()).

2. Initialization Guard

Any read or write attempt prior to formal initialization of EnvApi is immediately blocked, preventing startup race condition leaks.

3. Value Sanitization

Automatic rejection of values containing carriage returns (\r, \n) or null bytes (\0), preventing log corruption, CRLF injection, and HTTP header manipulation.

4. Deterministic Project Scoping

Modules and plugins can only access the .env of their own project folder (node_modules + package.json). Plugins running in separate workspaces cannot access host secrets.

5. Restrictive Proxy Shield (process.env)

Standard process.env access is intercepted by a hardened Proxy. Non-whitelisted keys return undefined. Enumeration via Object.keys(), JSON.stringify(), or spread operators is restricted to a tight whitelist of system essentials.

Read Methods

.get(key: string, defaultValue?: string): string | undefined

Retrieves a variable safely. When a defaultValue is provided, TypeScript correctly infers the return type as string.

typescript
// Infers 'string'
const port = __sys__.__env__.get("PORT", "3000");

// Infers 'string | undefined'
const apiKey = __sys__.__env__.get("API_KEY");

.getStrict(key: string, options?: { rejectEmpty?: boolean }): string

The gold standard for production entry points. Throws an EnvAccessError if the key is missing or empty, failing fast during boot.

typescript
// Throws if JWT_SECRET is missing
const secret = __sys__.__env__.getStrict("JWT_SECRET");

// Throws if DB_PASS is missing OR is an empty string ""
const pass = __sys__.__env__.getStrict("DB_PASS", { rejectEmpty: true });

.has(key: string): boolean

Returns true if the key exists in the store, regardless of its value (including empty strings).

typescript
if (__sys__.__env__.has("MAINTENANCE_MODE")) {
    handleMaintenance();
}

.all(options?: { keys?: string[] }): EnvSnapshot

Generates a frozen point-in-time snapshot of current variables. Use key filtering to avoid logging secrets.

typescript
const publicConfig = __sys__.__env__.all({
    keys: ["PUBLIC_API_URL", "FEATURE_FLAG_X"],
});

Write Methods

.set(key: string, value: string): void

Registers or modifies a variable. Automatically sanitizes values against CRLF and null characters.

typescript
__sys__.__env__.set("TEMPORARY_ACCESS_TOKEN", "xy-token-123");

.delete(key: string): void

Securely removes a variable from the in-memory store and from process.env if applicable.

typescript
__sys__.__env__.delete("TEMPORARY_ACCESS_TOKEN");

Execution Context (Readonly Modes)

The environment mode is set once during initialization and is readonly to prevent runtime tampering.

.isProduction()True if mode is 'production'
.isDevelopment()True if mode is 'development'
.isStaging()True if mode is 'staging'
.isTest()True if mode is 'test'
.is(envName)Checks custom environment string
.modeReturns raw mode string
typescript
if (__sys__.__env__.isDevelopment()) {
    enableVerboseLogging();
}

Native XHSC Utilities

.user(): string

Synchronously queries the native Go XHSC process to retrieve the operating system username of the instance owner.

typescript
const actor = __sys__.__env__.user() || "anonymous";
auditLog.write({ actor, action: "initialization" });
Best Practice: Fail Fast at Startup
Use getStrict() in your main entry point. Catching a missing variable at boot is infinitely better than encountering a null error in a background worker hours later.
Filesystem Module

Explore the high-performance filesystem API powered by the XHSC engine.