System Module

Environment & Security Shield

The XyPriss Environment API (__sys__.__env__) is the application's hardened Security Nervous System.

Security Restriction

Direct access to process.env is neutralized via a proxy. Third-party enumeration or unauthorized reads will return undefined and emit security warnings.

Security Mechanisms

Map-Isolated Storage

Variables are stored in a global Map identified by an unexported Symbol. Access is strictly tied to the caller's project root, preventing cross-plugin leakage.

Restrictive Proxy

Standard process.env access is intercepted. Only whitelisted system-essential keys (PATH, HOME) and internal prefixes (XY_, ENC_) are allowed.

Value Sanitization

Automatic rejection of values containing carriage returns (\r, \n) or null characters (\0), preventing log corruption and injection attacks.

Deterministic Scoping

Modules can only access the .env of their closest parent project (detected via package.json + node_modules).

Read Methods

.get(key, defaultValue?)

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

typescript

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

.getStrict(key, options?)

The gold standard for production. Throws an EnvAccessError if the key is missing or empty, ensuring application integrity at startup.

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 });

Execution Context (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"

Native Utilities

.user(): string

Synchronously queries the native 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

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 3 hours later.

Filesystem Module

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