xypriss 9.10.19 → 9.10.21

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

@@ -1,296 +0,0 @@
-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 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 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;
-    /**
-     * 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

@@ -1 +0,0 @@
-{"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,iBAAiB,CA6B/B;IAEH;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;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;IAQnC;;;;;;;;;;;;;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"}