xypriss 9.11.13 → 9.12.0

package/dist/src/utils/mimeUtils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MIME Utilities for XyPriss
+ */
+/**
+ * Normalizes a MIME type by stripping parameters (e.g., "text/plain; charset=utf-8" -> "text/plain").
+ * @param mime The MIME type string to normalize.
+ * @returns The base MIME type.
+ */
+export declare function normalizeMime(mime: string): string;
+//# sourceMappingURL=mimeUtils.d.ts.map

package/dist/src/utils/mimeUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mimeUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/mimeUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGlD"}

package/dist/src/utils/mimeUtils.js

@@ -0,0 +1,14 @@
+/**
+ * MIME Utilities for XyPriss
+ */
+/**
+ * Normalizes a MIME type by stripping parameters (e.g., "text/plain; charset=utf-8" -> "text/plain").
+ * @param mime The MIME type string to normalize.
+ * @returns The base MIME type.
+ */
+export function normalizeMime(mime) {
+    if (!mime)
+        return "";
+    return mime.split(";")[0].trim().toLowerCase();
+}
+//# sourceMappingURL=mimeUtils.js.map

package/dist/src/utils/mimeUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mimeUtils.js","sourceRoot":"","sources":["../../../src/utils/mimeUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACtC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACnD,CAAC"}

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

@@ -0,0 +1,310 @@
+import { EnvAllOptions, EnvGetStrictOptions, EnvSnapshot, IEnvApi } from "./api/env/env";
+import { XyPrissRunner } from "./XyPrissRunner";
+export declare class EnvApi implements IEnvApi {
+    readonly mode: string;
+    private readonly runner;
+    private readonly isDynamic;
+    /**
+     * 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.
+     */
+    private readonly defaultWhitelist;
+    private whitelistedFields;
+    /**
+     * @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: XyPrissRunner, mode?: string, isDynamic?: boolean);
+    /**
+     * 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: string, value: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * Reads a variable from the secure internal store.
+     *
+     * @param key          - Variable name to look up.
+     * @param defaultValue - Fallback when the key is absent.
+     * @returns The stored string, or `defaultValue` / `undefined`.
+     * @throws {EnvStoreError} When the store has not been initialised.
+     *
+     * @example
+     * // May return undefined — handle it explicitly
+     * const region = __sys__.__env__.get("AWS_REGION");
+     *
+     * // Always returns a string when a default is provided
+     * const timeout = __sys__.__env__.get("REQUEST_TIMEOUT_MS", "5000");
+     * const ms = parseInt(timeout, 10);
+     *
+     * // Concise fallback with nullish coalescing
+     * const logLevel = __sys__.__env__.get("LOG_LEVEL") ?? "info";
+     */
+    get(key: string): string | undefined;
+    get(key: string, defaultValue: string): string;
+    /**
+     * Reads a variable from the secure internal store for a specific root.
+     */
+    getForRoot(key: string, root: string): string | undefined;
+    /**
+     * 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: string, options?: EnvGetStrictOptions): string;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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?: EnvAllOptions): EnvSnapshot;
+    /**
+     * Returns `true` when the execution mode is `"production"`.
+     *
+     * @example
+     * const logger = createLogger({
+     *   level: __sys__.__env__.isProduction() ? "error" : "debug",
+     * });
+     */
+    isProduction(): boolean;
+    /**
+     * Returns `true` when the execution mode is `"development"`.
+     *
+     * @example
+     * if (__sys__.__env__.isDevelopment()) {
+     *   app.use(requestLogger({ colorize: true }));
+     * }
+     */
+    isDevelopment(): boolean;
+    /**
+     * Returns `true` when the execution mode is `"staging"`.
+     *
+     * @example
+     * if (__sys__.__env__.isStaging()) {
+     *   payment.useSandbox();
+     * }
+     */
+    isStaging(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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: string): boolean;
+    /**
+     * Configures the XESS (XyPriss Environment Security Shield) dynamically.
+     *
+     * @param config - XESS configuration options.
+     */
+    configureShield(config?: {
+        whitelist?: string[];
+        replaceDefaultWhitelist?: boolean;
+    }): void;
+    /**
+     * 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(): string;
+    /**
+     * 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}
+     */
+    private requireStoreMap;
+    private getStoreForCaller;
+    /**
+     * Asserts that `key` is a valid environment variable name.
+     *
+     * @internal
+     * @throws {EnvKeyError}
+     */
+    private validateKey;
+    /**
+     * 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}
+     */
+    private validateValue;
+    /**
+     * **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
+     */
+    private applyShield;
+    private isCallerProjectCode;
+}
+//# sourceMappingURL=EnvApi.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EnvApi.d.ts","sourceRoot":"","sources":["../../../src/xhsc/EnvApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,aAAa,EACb,mBAAmB,EAEnB,WAAW,EAGX,OAAO,EAEV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAMhD,qBAAa,MAAO,YAAW,OAAO;IAClC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IAEpC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CA6B9B;IAEH,OAAO,CAAC,iBAAiB,CAA+C;IAExE;;;;OAIG;gBAEC,MAAM,EAAE,aAAa,EACrB,IAAI,GAAE,MAAsB,EAC5B,SAAS,GAAE,OAAe;IAY9B;;;;;;;;;;;;;;;;;OAiBG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAiB5C;;;;;;;;;;OAUG;IACI,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAiBhC;;;;;;;;;;;;;;;;;;OAkBG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IACpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAWrD;;OAEG;IACI,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAShE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM;IAkBpE;;;;;;;;;;;;;OAaG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKhC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,GAAG,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,WAAW;IAkBhD;;;;;;;OAOG;IACI,YAAY,IAAI,OAAO;IAI9B;;;;;;;OAOG;IACI,aAAa,IAAI,OAAO;IAI/B;;;;;;;OAOG;IACI,SAAS,IAAI,OAAO;IAI3B;;;;;;;OAOG;IACI,MAAM,IAAI,OAAO;IAIxB;;;;;;;;;;OAUG;IACI,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAInC;;;;OAIG;IACI,eAAe,CAAC,MAAM,CAAC,EAAE;QAC5B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,uBAAuB,CAAC,EAAE,OAAO,CAAC;KACrC,GAAG,IAAI;IAmBR;;;;;;;;;;;;;OAaG;IACI,IAAI,IAAI,MAAM;IAerB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,iBAAiB;IA4CzB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAYnB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,aAAa;IAcrB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,WAAW;IAmFnB,OAAO,CAAC,mBAAmB;CAK9B"}