xypriss 9.11.13 → 9.12.0

package/dist/src/xhsc/EnvApi.js

@@ -0,0 +1,556 @@
+import { EnvAccessError, EnvKeyError, EnvStoreError, FORBIDDEN_VALUE_PATTERN, XY_ENV_STORE_KEY, } from "./api/env/env";
+import { getCallerProjectRoot } from "../utils/ProjectDiscovery";
+import path from "path";
+import fs from "fs";
+import { DotEnvLoader } from "../utils/DotEnvLoader";
+export class EnvApi {
+    /**
+     * @param runner - The XyPrissRunner used to invoke native Go binaries.
+     * @param mode   - The execution mode. Defaults to `"development"`.
+     * @param isDynamic - Whether this EnvApi should use dynamic project discovery (Sandboxing).
+     */
+    constructor(runner, mode = "development", isDynamic = false) {
+        /**
+         * Keys that may pass through the Shield to the real `process.env` without
+         * restriction. Stored as a `Set` for O(1) lookup inside the Proxy trap.
+         *
+         * This list covers OS and Node.js internals required for system stability.
+         * Application secrets must never be added here.
+         */
+        this.defaultWhitelist = new Set([
+            "PORT",
+            "TERM",
+            "PATH",
+            "PWD",
+            "HOME",
+            "USER",
+            "LANG",
+            "COLORTERM",
+            "FORCE_COLOR",
+            "TERM_PROGRAM",
+            "EDITOR",
+            "SHELL",
+            "SHLVL",
+            "NO_DEPRECATION",
+            "DEBUG_FD",
+            "DEBUG",
+            "NODE_DEBUG",
+            "NODE_OPTIONS",
+            "NODE_ENV",
+            "ENC_SECRET_KEY",
+            "ENC_SECRET_SEED",
+            "ENC_SECRET_SALT",
+            "TRACE_DEPRECATION",
+            "APPEND_DEPRECATION",
+            "READABLE_STREAM",
+            "BUN_CONFIG_VERBOSE_FETCH",
+            "XYPRISS_ENV_SHIELD",
+            "BUN_DISABLE_DYNAMIC_CHUNK_SIZE",
+        ]);
+        this.whitelistedFields = new Set(this.defaultWhitelist);
+        this.runner = runner;
+        this.mode = mode;
+        this.isDynamic = isDynamic;
+        this.applyShield();
+    }
+    // -------------------------------------------------------------------------
+    // Write
+    // -------------------------------------------------------------------------
+    /**
+     * Writes a variable to the secure internal store.
+     *
+     * The key must be non-empty and must not consist solely of whitespace.
+     * The value must not contain CR (`\r`), LF (`\n`), or NUL (`\0`) — these
+     * characters can corrupt downstream parsers and log sinks.
+     *
+     * @param key   - Variable name.
+     * @param value - Value to store.
+     * @throws {EnvKeyError}   When the key or value fails validation.
+     * @throws {EnvStoreError} When the store has not been initialised.
+     *
+     * @example
+     * __sys__.__env__.set("MAINTENANCE_MODE", "true");
+     *
+     * const resolvedBase = resolveBaseUrl(config);
+     * __sys__.__env__.set("APP_BASE_URL", resolvedBase);
+     */
+    set(key, value) {
+        this.validateKey(key);
+        this.validateValue(key, value);
+        const store = this.getStoreForCaller();
+        store[key] = value;
+        // Keep process.env in sync for whitelisted keys only to maintain system stability
+        if (this.whitelistedFields.has(key)) {
+            try {
+                process.env[key] = value;
+            }
+            catch {
+                // Shield is locked
+            }
+        }
+    }
+    /**
+     * Removes a variable from the secure internal store and from `process.env`.
+     * Deleting a key that does not exist is a no-op; no error is thrown.
+     *
+     * @param key - Variable name to remove.
+     * @throws {EnvStoreError} When the store has not been initialised.
+     *
+     * @example
+     * // Revoke a short-lived deployment credential immediately after use
+     * __sys__.__env__.delete("CI_DEPLOY_TOKEN");
+     */
+    delete(key) {
+        const store = this.getStoreForCaller();
+        delete store[key];
+        if (this.whitelistedFields.has(key)) {
+            try {
+                delete process.env[key];
+            }
+            catch {
+                // Shield may block deletion
+            }
+        }
+    }
+    get(key, defaultValue) {
+        if (key === "__root__") {
+            return this.runner.getRoot();
+        }
+        const store = this.getStoreForCaller();
+        const value = store[key];
+        return value !== undefined ? value : defaultValue;
+    }
+    /**
+     * Reads a variable from the secure internal store for a specific root.
+     */
+    getForRoot(key, root) {
+        if (key === "__root__") {
+            return root;
+        }
+        const store = this.getStoreForCaller(root);
+        return store[key];
+    }
+    /**
+     * Reads a required variable from the secure internal store and throws if
+     * it cannot be resolved.
+     *
+     * Use this method for every variable that is mandatory for application
+     * correctness. It surfaces configuration errors at startup rather than
+     * silently producing `undefined` at the point of use.
+     *
+     * @param key     - Variable name to look up.
+     * @param options - Optional validation settings.
+     * @returns The stored value, guaranteed non-undefined.
+     * @throws {EnvAccessError} When the variable is missing or empty.
+     * @throws {EnvStoreError}  When the store has not been initialised.
+     *
+     * @example
+     * // Fail fast at boot if a critical variable is absent
+     * const databaseUrl = __sys__.__env__.getStrict("DATABASE_URL");
+     * const jwtSecret   = __sys__.__env__.getStrict("JWT_SECRET", { rejectEmpty: true });
+     * const smtpHost    = __sys__.__env__.getStrict("SMTP_HOST");
+     *
+     * // Collect all required variables once at module initialisation
+     * const config = {
+     *   db:   __sys__.__env__.getStrict("DATABASE_URL"),
+     *   jwt:  __sys__.__env__.getStrict("JWT_SECRET", { rejectEmpty: true }),
+     *   smtp: __sys__.__env__.getStrict("SMTP_HOST"),
+     * };
+     */
+    getStrict(key, options) {
+        if (key === "__root__") {
+            return this.runner.getRoot();
+        }
+        const store = this.getStoreForCaller();
+        const value = store[key];
+        if (value === undefined) {
+            throw new EnvAccessError(key, "missing");
+        }
+        if (options?.rejectEmpty && value === "") {
+            throw new EnvAccessError(key, "empty");
+        }
+        return value;
+    }
+    /**
+     * Returns `true` when the given key is present in the secure internal
+     * store, regardless of its value (including empty strings).
+     *
+     * @param key - Variable name to test.
+     * @throws {EnvStoreError} When the store has not been initialised.
+     *
+     * @example
+     * if (__sys__.__env__.has("SENTRY_DSN")) {
+     *   Sentry.init({ dsn: __sys__.__env__.get("SENTRY_DSN") });
+     * }
+     *
+     * const betaEnabled = __sys__.__env__.has("ENABLE_BETA_UI");
+     */
+    has(key) {
+        const store = this.getStoreForCaller();
+        return store[key] !== undefined;
+    }
+    /**
+     * Returns a frozen, point-in-time snapshot of stored variables.
+     *
+     * The object is frozen at the moment of the call; subsequent `set` or
+     * `delete` calls do not affect it.
+     *
+     * Providing `options.keys` is strongly recommended in production code.
+     * Returning the full store risks inadvertently capturing secrets in log
+     * statements or JSON serialisations.
+     *
+     * @param options - Optional filter configuration.
+     * @returns A frozen {@link EnvSnapshot}.
+     * @throws {EnvStoreError} When the store has not been initialised.
+     *
+     * @example
+     * // Filtered snapshot — preferred in all production code paths
+     * const dbConfig = __sys__.__env__.all({
+     *   keys: ["DATABASE_URL", "DATABASE_POOL_SIZE", "DATABASE_TIMEOUT_MS"],
+     * });
+     *
+     * // Full snapshot — use only for diagnostics / startup validation
+     * const full = __sys__.__env__.all();
+     * logger.debug("Env snapshot", { count: Object.keys(full).length });
+     */
+    all(options) {
+        const store = this.getStoreForCaller();
+        if (options?.keys && options.keys.length > 0) {
+            const subset = {};
+            for (const key of options.keys) {
+                subset[key] = store[key];
+            }
+            return Object.freeze(subset);
+        }
+        return Object.freeze({ ...store });
+    }
+    // -------------------------------------------------------------------------
+    // Mode helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Returns `true` when the execution mode is `"production"`.
+     *
+     * @example
+     * const logger = createLogger({
+     *   level: __sys__.__env__.isProduction() ? "error" : "debug",
+     * });
+     */
+    isProduction() {
+        return this.mode === "production";
+    }
+    /**
+     * Returns `true` when the execution mode is `"development"`.
+     *
+     * @example
+     * if (__sys__.__env__.isDevelopment()) {
+     *   app.use(requestLogger({ colorize: true }));
+     * }
+     */
+    isDevelopment() {
+        return this.mode === "development";
+    }
+    /**
+     * Returns `true` when the execution mode is `"staging"`.
+     *
+     * @example
+     * if (__sys__.__env__.isStaging()) {
+     *   payment.useSandbox();
+     * }
+     */
+    isStaging() {
+        return this.mode === "staging";
+    }
+    /**
+     * Returns `true` when the execution mode is `"test"`.
+     *
+     * @example
+     * const dbUrl = __sys__.__env__.isTest()
+     *   ? __sys__.__env__.getStrict("TEST_DATABASE_URL")
+     *   : __sys__.__env__.getStrict("DATABASE_URL");
+     */
+    isTest() {
+        return this.mode === "test";
+    }
+    /**
+     * Returns `true` when the execution mode exactly matches `envName`
+     * (case-sensitive).
+     *
+     * @param envName - Mode name to compare against.
+     *
+     * @example
+     * if (__sys__.__env__.is("canary")) {
+     *   featureFlags.enableAll();
+     * }
+     */
+    is(envName) {
+        return this.mode === envName;
+    }
+    /**
+     * Configures the XESS (XyPriss Environment Security Shield) dynamically.
+     *
+     * @param config - XESS configuration options.
+     */
+    configureShield(config) {
+        if (!config)
+            return;
+        if (config.whitelist !== undefined) {
+            if (config.replaceDefaultWhitelist) {
+                this.whitelistedFields = new Set(config.whitelist);
+            }
+            else {
+                this.whitelistedFields = new Set([
+                    ...this.defaultWhitelist,
+                    ...config.whitelist,
+                ]);
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Native / system
+    // -------------------------------------------------------------------------
+    /**
+     * Retrieves the OS-level username of the current process owner by invoking
+     * the XHSC native Go binary.
+     *
+     * This method is synchronous and blocks until the native call completes.
+     * Do not call it in request hot paths. Returns `""` on failure so callers
+     * can safely use the result without null checks.
+     *
+     * @returns The current OS username, or `""` on failure.
+     *
+     * @example
+     * const actor = __sys__.__env__.user() || "<unknown>";
+     * auditLog.write({ actor, action: "deploy" });
+     */
+    user() {
+        try {
+            const result = this.runner.runSync("sys", "user");
+            return result?.username ?? "";
+        }
+        catch {
+            return "";
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private — store access
+    // -------------------------------------------------------------------------
+    /**
+     * Returns the internal store, throwing {@link EnvStoreError} if it has not
+     * yet been initialised.
+     *
+     * SECURITY: This is the single point of store access. Every read and write
+     * method must go through here — never access `globalThis[XY_ENV_STORE_KEY]`
+     * directly outside this method.
+     *
+     * Eliminating the `?? process.env` fallback is intentional. A silent
+     * fallback to `process.env` during the bootstrap race window would bypass
+     * the Shield and leak values without any warning. A thrown error is
+     * immediately visible during development and integration testing.
+     *
+     * @internal
+     * @throws {EnvStoreError}
+     */
+    requireStoreMap() {
+        const storeMap = globalThis[XY_ENV_STORE_KEY];
+        if (!storeMap) {
+            throw new EnvStoreError();
+        }
+        return storeMap;
+    }
+    getStoreForCaller(callerRoot) {
+        const storeMap = this.requireStoreMap();
+        // 🛡️ Security & Scope Policy (Sandboxing):
+        // 1. If an explicit root is provided, use it.
+        // 2. Fallback to dynamic project discovery based on the caller's stack (Restricted Context) if enabled.
+        // 3. Fallback to this EnvApi instance's pinned runner root (System Baseline/Forced root).
+        const root = callerRoot ||
+            (this.isDynamic ? getCallerProjectRoot() : null) ||
+            this.runner.getRoot() ||
+            getCallerProjectRoot();
+        if (!root)
+            return {};
+        let store = storeMap.get(root);
+        if (!store) {
+            // Dynamic loading for projects not encountered during bootstrap (like plugins/mods)
+            const envPath = path.resolve(root, ".env");
+            const envData = {};
+            if (fs.existsSync(envPath)) {
+                const loaded = DotEnvLoader.load({
+                    path: [envPath],
+                    override: true,
+                });
+                for (const key in loaded) {
+                    envData[key] = loaded[key];
+                }
+            }
+            // Cache the loaded env for this project
+            storeMap.set(root, envData);
+            store = envData;
+        }
+        return store;
+    }
+    // -------------------------------------------------------------------------
+    // Private — validation
+    // -------------------------------------------------------------------------
+    /**
+     * Asserts that `key` is a valid environment variable name.
+     *
+     * @internal
+     * @throws {EnvKeyError}
+     */
+    validateKey(key) {
+        if (key.length === 0) {
+            throw new EnvKeyError(key, "key must not be empty");
+        }
+        if (key.trim().length === 0) {
+            throw new EnvKeyError(key, "key must not consist solely of whitespace");
+        }
+    }
+    /**
+     * Asserts that `value` does not contain characters that can corrupt
+     * downstream parsers, log sinks, or HTTP serialisers.
+     *
+     * Rejected characters:
+     * - CR (`\r`) and LF (`\n`) — break line-oriented `.env` parsers and
+     *   enable log injection attacks.
+     * - NUL (`\0`) — truncates strings in C-based runtimes and can bypass
+     *   suffix-based extension checks in some file path handling code.
+     *
+     * @internal
+     * @throws {EnvKeyError}
+     */
+    validateValue(key, value) {
+        if (FORBIDDEN_VALUE_PATTERN.test(value)) {
+            throw new EnvKeyError(key, "value must not contain carriage return (\\r), line feed (\\n), " +
+                "or NUL (\\0) characters — these can corrupt parsers and enable log injection");
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private — Shield
+    // -------------------------------------------------------------------------
+    /**
+     * **Environment Security Shield**
+     *
+     * Replaces the `process.env` object with a hardened Proxy that enforces
+     * the following policies on every property access:
+     *
+     * **Read trap**
+     * - Whitelisted keys (see {@link EnvApi.whitelistedFields}) and keys
+     *   matching the prefixes `XY_`, `XYPRISS_`, `ENC_`, `DOTENV_`, or `__`
+     *   pass through to the real value.
+     * - All other reads return `undefined`. A one-time per-key warning is
+     *   written to `process.stderr` (suppressed when
+     *   `XYPRISS_ENV_SHIELD=silent`).
+     *
+     * **`ownKeys` and `has` traps**
+     * - Restrict the apparent key set to the whitelist. This prevents
+     *   third-party code from enumerating the real store through
+     *   `Object.keys(process.env)`, `JSON.stringify(process.env)`, or spread
+     *   operators — all of which bypass the `get` trap.
+     *
+     * The descriptor is applied with `writable: false` to prevent replacement
+     * by application code, and `configurable: true` to allow test teardown.
+     *
+     * @internal
+     */
+    /**
+     * **Environment Security Shield**
+     *
+     * Replaces the `process.env` object with a hardened Proxy that enforces
+     * the following policies on every property access:
+     *
+     * **Read trap**
+     * - Whitelisted keys (see {@link EnvApi.whitelistedFields}) and keys
+     *   matching the prefixes `XY_`, `XYPRISS_`, `ENC_`, `DOTENV_`, or `__`
+     *   pass through to the real value.
+     * - All other reads return `undefined`. A one-time per-key warning is
+     *   written to `process.stderr` (suppressed when
+     *   `XYPRISS_ENV_SHIELD=silent`).
+     *
+     * **`ownKeys` and `has` traps**
+     * - Restrict the apparent key set to the whitelist. This prevents
+     *   third-party code from enumerating the real store through
+     *   `Object.keys(process.env)`, `JSON.stringify(process.env)`, or spread
+     *   operators — all of which bypass the `get` trap.
+     *
+     * The descriptor is applied with `writable: false` to prevent replacement
+     * by application code, and `configurable: true` to allow test teardown.
+     *
+     * @internal
+     */
+    applyShield() {
+        // Per-key deduplication: every distinct blocked key gets exactly one
+        // warning, preserving actionable signal without log flooding.
+        const warnedKeys = new Set();
+        const self = this;
+        const envShield = new Proxy(process.env, {
+            get(target, prop, receiver) {
+                if (typeof prop !== "string") {
+                    return Reflect.get(target, prop, receiver);
+                }
+                // Pass through whitelisted keys and framework-reserved prefixes.
+                if (self.whitelistedFields.has(prop) ||
+                    prop.startsWith("XY_") ||
+                    prop.startsWith("XYPRISS_") ||
+                    prop.startsWith("ENC_") ||
+                    prop.startsWith("DOTENV_") ||
+                    prop.startsWith("__")) {
+                    return Reflect.get(target, prop, receiver);
+                }
+                // Emit one warning per unique blocked key.
+                if (!warnedKeys.has(prop)) {
+                    const storeMap = globalThis[XY_ENV_STORE_KEY];
+                    let isSilent = target["XYPRISS_ENV_SHIELD"] === "silent";
+                    if (storeMap) {
+                        for (const env of storeMap.values()) {
+                            if (env["XYPRISS_ENV_SHIELD"] === "silent") {
+                                isSilent = true;
+                                break;
+                            }
+                        }
+                    }
+                    if (!isSilent) {
+                        process.stderr.write(`\x1b[33m[SECURITY]\x1b[0m ` +
+                            `Direct access to process.env["${prop}"] is blocked. ` +
+                            `Use \x1b[36m__sys__.__env__.get("${prop}")\x1b[0m ` +
+                            `or \x1b[36m__sys__.__env__.getStrict("${prop}")\x1b[0m instead.\n`);
+                    }
+                    warnedKeys.add(prop);
+                }
+                return undefined;
+            },
+            // Harden enumeration: restrict what callers see when they iterate
+            // or spread process.env. Without this trap, spread operators and
+            // Object.keys() bypass the get trap entirely.
+            ownKeys(_target) {
+                return [...self.whitelistedFields];
+            },
+            // Align `in` operator behaviour with the restricted key set.
+            has(_target, prop) {
+                if (typeof prop !== "string")
+                    return false;
+                return self.whitelistedFields.has(prop);
+            },
+        });
+        try {
+            Object.defineProperty(process, "env", {
+                value: envShield,
+                writable: false,
+                configurable: true,
+                enumerable: true,
+            });
+        }
+        catch {
+            // Silently degrade — the Shield could not be applied (e.g., inside
+            // certain container or VM environments with locked descriptors).
+            // The Symbol-keyed internal store remains the authoritative and
+            // isolated source for all EnvApi reads.
+        }
+    }
+    isCallerProjectCode() {
+        const callerRoot = getCallerProjectRoot();
+        const sysRoot = globalThis.__sys__?.__root__;
+        return !!callerRoot && callerRoot === sysRoot;
+    }
+}
+//# sourceMappingURL=EnvApi.js.map

package/dist/src/xhsc/EnvApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvApi.js","sourceRoot":"","sources":["../../../src/xhsc/EnvApi.ts"],"names":[],"mappings":"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"}

package/dist/src/xhsc/FSApi.d.ts

@@ -0,0 +1,21 @@
+import { FSExtended } from "./fs/FSExtended";
+/**
+ * **Professional Filesystem API (High Performance)**
+ *
+ * The `FSApi` class provides a unified, high-performance interface for all filesystem operations.
+ * It is modularized into several specialized layers while maintaining a single cohesive API.
+ *
+ * **Modular Structure:**
+ * - `FSCore`: Fundamental operations (ls, read, write, move, rm)
+ * - `FSHelpers`: Convenience methods (JSON patterns, type checks)
+ * - `FSSearch`: Regex-based discovery and grep
+ * - `FSArchive`: Compression and TAR handling
+ * - `FSWatch`: Real-time monitoring and streaming
+ * - `FSExtended`: Advanced security and atomic operations
+ *
+ * @class FSApi
+ * @extends FSExtended
+ */
+export declare class FSApi extends FSExtended {
+}
+//# sourceMappingURL=FSApi.d.ts.map

package/dist/src/xhsc/FSApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FSApi.d.ts","sourceRoot":"","sources":["../../../src/xhsc/FSApi.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,KAAM,SAAQ,UAAU;CAAG"}

package/dist/src/xhsc/FSApi.js

@@ -0,0 +1,49 @@
+/* *****************************************************************************
+ * Nehonix XyPriss System
+ *
+ * ACCESS RESTRICTIONS:
+ * - This software is exclusively for use by Authorized Personnel of NEHONIX
+ * - Intended for Internal Use only within NEHONIX operations
+ * - No rights granted to unauthorized individuals or entities
+ * - All modifications are works made for hire assigned to NEHONIX
+ *
+ * PROHIBITED ACTIVITIES:
+ * - Copying, distributing, or sublicensing without written permission
+ * - Reverse engineering, decompiling, or disassembling
+ * - Creating derivative works without explicit authorization
+ * - External use or commercial distribution outside NEHONIX
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * For questions or permissions, contact:
+ * NEHONIX Legal Department
+ * Email: legal@nehonix.com
+ * Website: www.nehonix.com
+ * ***************************************************************************** */
+import { FSExtended } from "./fs/FSExtended";
+/**
+ * **Professional Filesystem API (High Performance)**
+ *
+ * The `FSApi` class provides a unified, high-performance interface for all filesystem operations.
+ * It is modularized into several specialized layers while maintaining a single cohesive API.
+ *
+ * **Modular Structure:**
+ * - `FSCore`: Fundamental operations (ls, read, write, move, rm)
+ * - `FSHelpers`: Convenience methods (JSON patterns, type checks)
+ * - `FSSearch`: Regex-based discovery and grep
+ * - `FSArchive`: Compression and TAR handling
+ * - `FSWatch`: Real-time monitoring and streaming
+ * - `FSExtended`: Advanced security and atomic operations
+ *
+ * @class FSApi
+ * @extends FSExtended
+ */
+export class FSApi extends FSExtended {
+}
+//# sourceMappingURL=FSApi.js.map

package/dist/src/xhsc/FSApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FSApi.js","sourceRoot":"","sources":["../../../src/xhsc/FSApi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;mFA2BmF;AAEnF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,KAAM,SAAQ,UAAU;CAAG"}