@growconnect/growtickets-nest 0.1.0 → 0.3.0

package/dist/env/overlay.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvOverlay = void 0;
+/**
+ * Pone las variables de la central ENCIMA del entorno del proceso y recuerda qué había debajo. La central gana sobre la plataforma
+ * (Docker, Railway) y sobre un `.env` que lea el producto después, porque `dotenv` no pisa lo que ya está en `process.env`.
+ *
+ * Al recibir una versión nueva en caliente (`reload`) lo que la central dejó de mandar NO se queda: vuelve al valor que tenía la
+ * plataforma, o se borra si no tenía ninguno. Sin esto, quitar una variable de la bóveda no la quitaría hasta el siguiente reinicio.
+ */
+class EnvOverlay {
+    constructor(target) {
+        this.target = target;
+        this.baseline = new Map();
+        this.current = new Set();
+    }
+    apply(variables) {
+        const removed = [];
+        const changed = [];
+        for (const nombre of [...this.current]) {
+            if (nombre in variables)
+                continue;
+            this.restore(nombre);
+            removed.push(nombre);
+        }
+        for (const [nombre, valor] of Object.entries(variables)) {
+            if (!this.current.has(nombre)) {
+                this.baseline.set(nombre, this.target[nombre]);
+                this.current.add(nombre);
+            }
+            if (this.target[nombre] !== valor) {
+                this.target[nombre] = valor;
+                changed.push(nombre);
+            }
+        }
+        return { changed: changed.sort(), removed: removed.sort() };
+    }
+    restore(nombre) {
+        const antes = this.baseline.get(nombre);
+        if (antes === undefined)
+            delete this.target[nombre];
+        else
+            this.target[nombre] = antes;
+        this.baseline.delete(nombre);
+        this.current.delete(nombre);
+    }
+}
+exports.EnvOverlay = EnvOverlay;

package/dist/env/policy.d.ts

@@ -0,0 +1,30 @@
+export declare const ENV_SCHEMA = 1;
+export declare const MAX_VARIABLES = 1000;
+export declare const MAX_VALUE_BYTES = 32768;
+/** Lo que la central dio por bueno para este servidor: la versión, de qué entorno, y las variables ya validadas. */
+export interface EnvPayload {
+    version: number;
+    environmentId: number;
+    environmentName: string;
+    environmentKind: string;
+    variables: Record<string, string>;
+    /** El `ETag` de la respuesta: la siguiente pregunta lo manda y, si nada cambió, la central contesta 304 sin cuerpo. */
+    etag: string | null;
+    /** Los NOMBRES (nunca los valores) que la política descartó. No se guardan en la copia: se calculan al validar. */
+    discarded: string[];
+}
+/** «7:12»: el entorno y la versión. Lo que se compara para saber si algo ya está aplicado. */
+export declare function markerOf(payload: Pick<EnvPayload, 'environmentId' | 'version'>): string;
+/** ¿El nombre se puede poner en el entorno del proceso? */
+export declare function isAllowedName(name: string): boolean;
+/**
+ * La respuesta de `GET api/ingest/env` ya decodificada, convertida en una carga útil en la que se puede confiar. La central ya valida al
+ * guardar; aquí se vuelve a validar porque lo recibido acaba en `process.env`, y eso es más que configuración.
+ *
+ * - **Esquema**: `schema` 1; la versión y el entorno son enteros positivos. Otro esquema es `incompatible_schema`: la librería es vieja.
+ * - **Nombres**: los no permitidos se DESCARTAN —sólo su nombre queda en `discarded`— en vez de tumbar la versión entera: el resto de la
+ *   configuración sigue llegando.
+ * - **Valores**: texto, sin NUL, hasta 32 KB; como mucho 1000 variables. Un valor que no cumple es `malformed` aunque su nombre se
+ *   fuera a descartar, para no aceptar una respuesta a medias.
+ */
+export declare function parseEnvPayload(json: unknown, etag?: string | null): EnvPayload;

package/dist/env/policy.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_VALUE_BYTES = exports.MAX_VARIABLES = exports.ENV_SCHEMA = void 0;
+exports.markerOf = markerOf;
+exports.isAllowedName = isAllowedName;
+exports.parseEnvPayload = parseEnvPayload;
+const errors_1 = require("./errors");
+exports.ENV_SCHEMA = 1;
+exports.MAX_VARIABLES = 1000;
+exports.MAX_VALUE_BYTES = 32768;
+/** Sin la bandera `m` y con `$` al final: en JavaScript `$` no acepta un salto de línea final, así que `"PATH\n"` no pasa por nombre válido. */
+const NAME_SHAPE = /^[A-Z_][A-Z0-9_]{0,127}$/;
+/** Todo `GROWTICKETS_*` es de la librería: la bóveda no puede tocar sus claves, sus logs remotos ni su seguridad. */
+const RESERVED_PREFIX = 'GROWTICKETS_';
+const SYSTEM_PREFIXES = ['LD_', 'DYLD_', 'GIT_'];
+/**
+ * Las que gobiernan el PROCESO y no la aplicación, o cargan código o certificados por otra puerta. Es la lista de la central
+ * (`EnvVariableRules::SYSTEM`, espejo de `EnvPolicy` de growtickets-laravel) entera: aquí lo recibido acaba en `process.env`, así que
+ * `NODE_OPTIONS`, `NODE_PATH` y `NODE_EXTRA_CA_CERTS` cambian qué código y qué certificados cargan los procesos hijos,
+ * `NODE_TLS_REJECT_UNAUTHORIZED=0` apagaría la verificación de TLS de todo el proceso —la de la propia llamada a la central incluida—,
+ * `OPENSSL_CONF`/`SSL_CERT_FILE`/`SSLKEYLOGFILE` tocan el TLS de lo que el producto lanza, y `PYTHONWARNINGS`, `BROWSER`, `PAGER`, `EDITOR`,
+ * `PS4`, `SHELLOPTS`, `JAVA_TOOL_OPTIONS`… ejecutan código al arrancar un intérprete o una herramienta.
+ */
+const SYSTEM = new Set([
+    'GROWTICKETS_ENV_VERSION', 'GROWTICKETS_ENV_BUILDING', 'GROWTICKETS_ENV_PATH',
+    'APP_CONFIG_CACHE', 'APP_SERVICES_CACHE', 'APP_PACKAGES_CACHE', 'APP_EVENTS_CACHE', 'APP_ROUTES_CACHE', 'APP_BASE_PATH',
+    'PATH', 'HOME', 'SHELL', 'IFS', 'PHPRC', 'PHP_INI_SCAN_DIR', 'PHP_BINARY', 'BASH_ENV', 'ENV', 'PERL5OPT', 'PERL5LIB',
+    'NODE_OPTIONS', 'PYTHONPATH', 'PYTHONSTARTUP', 'GCONV_PATH', 'TESTBENCH_WORKING_PATH',
+    'PYTHONHOME', 'PYTHONBREAKPOINT', 'PYTHONINSPECT', 'PYTHONUSERBASE', 'PYTHONEXECUTABLE',
+    'NODE_PATH', 'NODE_TLS_REJECT_UNAUTHORIZED', 'NODE_EXTRA_CA_CERTS', 'NEXT_RUNTIME',
+    'OPENSSL_CONF', 'OPENSSL_MODULES', 'OPENSSL_ENGINES', 'SSLKEYLOGFILE', 'SSL_CERT_FILE', 'SSL_CERT_DIR',
+    'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'PYTHONWARNINGS', 'PYTHONPLATLIBDIR', 'BROWSER', 'PAGER', 'EDITOR', 'VISUAL',
+    'PS4', 'SHELLOPTS', 'BASHOPTS', 'PROMPT_COMMAND', 'JAVA_TOOL_OPTIONS', '_JAVA_OPTIONS', 'JDK_JAVA_OPTIONS',
+    'RUBYOPT', 'RUBYLIB', 'PERLLIB', 'PERL5DB', 'GLIBC_TUNABLES', 'HOSTALIASES', 'LOCALDOMAIN', 'RES_OPTIONS',
+    'NLSPATH', 'LOCPATH', 'NODE_REPL_EXTERNAL_MODULE',
+]);
+/** «7:12»: el entorno y la versión. Lo que se compara para saber si algo ya está aplicado. */
+function markerOf(payload) {
+    return `${payload.environmentId}:${payload.version}`;
+}
+/** ¿El nombre se puede poner en el entorno del proceso? */
+function isAllowedName(name) {
+    if (!NAME_SHAPE.test(name) || name.startsWith(RESERVED_PREFIX) || SYSTEM.has(name))
+        return false;
+    return !SYSTEM_PREFIXES.some((prefijo) => name.startsWith(prefijo));
+}
+/**
+ * La respuesta de `GET api/ingest/env` ya decodificada, convertida en una carga útil en la que se puede confiar. La central ya valida al
+ * guardar; aquí se vuelve a validar porque lo recibido acaba en `process.env`, y eso es más que configuración.
+ *
+ * - **Esquema**: `schema` 1; la versión y el entorno son enteros positivos. Otro esquema es `incompatible_schema`: la librería es vieja.
+ * - **Nombres**: los no permitidos se DESCARTAN —sólo su nombre queda en `discarded`— en vez de tumbar la versión entera: el resto de la
+ *   configuración sigue llegando.
+ * - **Valores**: texto, sin NUL, hasta 32 KB; como mucho 1000 variables. Un valor que no cumple es `malformed` aunque su nombre se
+ *   fuera a descartar, para no aceptar una respuesta a medias.
+ */
+function parseEnvPayload(json, etag = null) {
+    if (!isRecord(json) || !('schema' in json))
+        throw new errors_1.EnvError('malformed', 'La central contestó algo que no son variables de entorno.');
+    if (positiveInt(json.schema) !== exports.ENV_SCHEMA) {
+        throw new errors_1.EnvError('incompatible_schema', 'La central manda un formato que esta versión de la librería no conoce: actualízala.');
+    }
+    const entorno = isRecord(json.environment) ? json.environment : {};
+    const version = positiveInt(json.version);
+    const environmentId = positiveInt(entorno.id);
+    const variables = json.variables;
+    if (version === null || environmentId === null || !isRecord(variables) || Object.keys(variables).length > exports.MAX_VARIABLES) {
+        throw new errors_1.EnvError('malformed', 'La respuesta de la central no tiene la forma esperada.');
+    }
+    const limpias = {};
+    const descartadas = [];
+    for (const [nombre, valor] of Object.entries(variables)) {
+        if (typeof valor !== 'string' || valor.includes('\0') || Buffer.byteLength(valor, 'utf8') > exports.MAX_VALUE_BYTES) {
+            throw new errors_1.EnvError('malformed', `La variable ${printable(nombre)} no tiene un valor válido.`);
+        }
+        if (isAllowedName(nombre))
+            limpias[nombre] = valor;
+        else
+            descartadas.push(printable(nombre));
+    }
+    return {
+        version,
+        environmentId,
+        environmentName: String(entorno.name ?? '').slice(0, 80),
+        environmentKind: /^[a-z]{1,20}$/.test(String(entorno.kind ?? '')) ? String(entorno.kind) : 'other',
+        variables: Object.fromEntries(Object.entries(limpias).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+        etag,
+        discarded: descartadas,
+    };
+}
+/** Un nombre recibido de la red, listo para ir a un mensaje: sin caracteres de control y acotado. */
+function printable(name) {
+    return name.replace(/[^\x20-\x7E]/g, '?').slice(0, 130);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function positiveInt(value) {
+    const n = typeof value === 'string' && /^\d{1,15}$/.test(value) ? Number(value) : value;
+    return typeof n === 'number' && Number.isSafeInteger(n) && n >= 1 ? n : null;
+}

package/dist/env/poller.d.ts

@@ -0,0 +1,27 @@
+/** Lo que el temporizador hace tras cada revisión: seguir al ritmo de siempre, espaciarla (la central pidió esperar) o no volver a revisar. */
+export type PollHint = 'continue' | 'slow' | 'stop';
+export interface PollerOptions {
+    tick: () => Promise<PollHint>;
+    intervalMs: number;
+    jitterMs: number;
+    slowMs: number;
+    random?: () => number;
+}
+/**
+ * La revisión periódica que hace cada PROCESO: el aviso de «Vincular» le llega a UNA réplica, y las demás (y la propia, si el aviso se
+ * perdió) se enteran preguntando a la central con `If-None-Match` cada minuto, con algo de jitter para que varias réplicas arrancadas a la
+ * vez no pregunten a la vez. Un temporizador por vez (no un `setInterval`): la siguiente espera se decide cuando termina la anterior, así dos
+ * revisiones nunca se pisan, y el temporizador no retiene el proceso (`unref`).
+ */
+export declare class EnvPoller {
+    private readonly options;
+    private timer;
+    private stopped;
+    constructor(options: PollerOptions);
+    running(): boolean;
+    start(): void;
+    stop(): void;
+    private schedule;
+    private run;
+    private delay;
+}

package/dist/env/poller.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvPoller = void 0;
+/**
+ * La revisión periódica que hace cada PROCESO: el aviso de «Vincular» le llega a UNA réplica, y las demás (y la propia, si el aviso se
+ * perdió) se enteran preguntando a la central con `If-None-Match` cada minuto, con algo de jitter para que varias réplicas arrancadas a la
+ * vez no pregunten a la vez. Un temporizador por vez (no un `setInterval`): la siguiente espera se decide cuando termina la anterior, así dos
+ * revisiones nunca se pisan, y el temporizador no retiene el proceso (`unref`).
+ */
+class EnvPoller {
+    constructor(options) {
+        this.options = options;
+        this.timer = null;
+        this.stopped = false;
+    }
+    running() {
+        return this.timer !== null;
+    }
+    start() {
+        if (this.timer !== null || this.stopped)
+            return;
+        this.schedule(this.delay(this.options.intervalMs));
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer !== null)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    schedule(ms) {
+        const timer = setTimeout(() => void this.run(), ms);
+        timer.unref?.();
+        this.timer = timer;
+    }
+    async run() {
+        this.timer = null;
+        let pista = 'continue';
+        try {
+            pista = await this.options.tick();
+        }
+        catch {
+            pista = 'continue';
+        }
+        if (pista === 'stop' || this.stopped) {
+            this.stopped = true;
+            return;
+        }
+        this.schedule(this.delay(pista === 'slow' ? this.options.slowMs : this.options.intervalMs));
+    }
+    delay(base) {
+        return base + Math.floor((this.options.random ?? Math.random)() * this.options.jitterMs);
+    }
+}
+exports.EnvPoller = EnvPoller;

package/dist/env/runtime.d.ts

@@ -0,0 +1,122 @@
+import { EnvApplier, type EnvChange } from './applier';
+import { type PollHint } from './poller';
+import { type EnvSettings } from './settings';
+import { EnvSnapshot } from './snapshot';
+import { EnvState } from './state';
+import { EnvStorage } from './storage';
+import { type EnvTransport } from './transport';
+type Env = Record<string, string | undefined>;
+export type EnvChangeListener = (change: EnvChange) => void | Promise<void>;
+/** Lo único que el reinicio necesita de la app de Nest: cerrarla en orden (`app.close()`). */
+export interface EnvAppHandle {
+    close?: () => Promise<void>;
+}
+export interface EnvRuntimeDeps {
+    env: () => Env;
+    fetchImpl?: typeof fetch;
+    /** Segundos, época Unix. */
+    now: () => number;
+    cwd: () => string;
+    /** Dónde se escribe un aviso de la propia librería: el error estándar y nunca la consola, que otros adaptadores capturan. */
+    warn: (message: string) => void;
+    /** La revisión de cada minuto. Las pruebas la apagan para mover el reloj a mano. */
+    timer: boolean;
+    random?: () => number;
+    exit?: (code: number) => void;
+    sleep?: (ms: number) => Promise<void>;
+    learnedOrigin?: () => string | null;
+    /** Otro protocolo con la central. De serie, `createEnvTransport`. */
+    transport?: EnvTransport;
+}
+export interface LoadEnvOptions {
+    /** Con `GROWTICKETS_ENV_ON_CHANGE=reload`: se llama tras poner en `process.env` una versión nueva. Sólo recibe NOMBRES, nunca valores. */
+    onEnvChange?: EnvChangeListener;
+    /**
+     * Con `GROWTICKETS_ENV_ON_CHANGE=restart` (de serie): el código de salida del cierre ordenado. Si no se pasa, el de `GROWTICKETS_ENV_EXIT_CODE`
+     * y, sin él, 75 (`EX_TEMPFAIL`): con 0 una política «sólo si falla» no reinicia el proceso y el producto se queda caído.
+     */
+    exitCode?: number;
+    /** `false` no arranca la revisión de cada minuto: sólo el arranque y los avisos. */
+    poll?: boolean;
+}
+export type LoadEnvStatus = 'off' | 'applied' | 'current' | 'offline' | 'empty';
+export interface LoadEnvResult {
+    status: LoadEnvStatus;
+    version: number;
+    environment: string | null;
+    /** Cuántas variables se pusieron. Nunca sus nombres: este resultado acaba en el registro de arranque de alguien. */
+    count: number;
+    /** Los nombres (sólo nombres) que la política descartó. */
+    discarded: string[];
+}
+/**
+ * Todo el estado de las variables desde la central de UN proceso: lo que dice el entorno, la copia cifrada, lo aplicado, la revisión de cada
+ * minuto, los nonce de los avisos y los oyentes de `reload`. El arranque (`loadGrowTicketsEnv`), el middleware (la ruta del aviso) y la CLI
+ * hablan con esta clase y no entre ellos.
+ *
+ * ## Por qué hay UNA instancia y vive en `globalThis`
+ *
+ * El arranque corre en `main.ts`, fuera del contenedor de Nest, y la ruta del aviso en el middleware: tienen que compartir lo aplicado y el
+ * candado. `globalThis[Symbol.for(…)]` también resiste a que el producto acabe con dos copias de esta librería en `node_modules`.
+ *
+ * ## Apagada, no hace nada
+ *
+ * Sin credencial para la central (`transport.configured()`) no pregunta, no escucha avisos y no arranca ningún temporizador.
+ */
+export declare class EnvRuntime {
+    private readonly deps;
+    readonly storage: EnvStorage;
+    readonly snapshot: EnvSnapshot;
+    readonly state: EnvState;
+    readonly transport: EnvTransport;
+    readonly applier: EnvApplier;
+    private readonly listeners;
+    private readonly poller;
+    private readonly warned;
+    private app;
+    private exitCode;
+    private booted;
+    constructor(deps: EnvRuntimeDeps);
+    settings(): EnvSettings;
+    enabled(): boolean;
+    now(): number;
+    warn(message: string): void;
+    /** La app de Nest, para cerrarla en orden al reiniciar. La deja el middleware de `main.ts`, que es quien la recibe. */
+    attachApp(app: EnvAppHandle | undefined | null): void;
+    /** Suscribe un oyente de `reload`. Devuelve la función que lo quita. */
+    onChange(listener: EnvChangeListener): () => void;
+    /**
+     * El arranque: baja las variables, las pone en `process.env` y deja en marcha la revisión de cada minuto. Si no se puede (la central no
+     * contesta y no hay una copia que sirva, o la clave está revocada) LANZA `EnvError` y el producto no arranca: es lo que `fail` y una
+     * clave muerta piden, y arrancar sin su configuración es peor que no arrancar. Sin credencial no hace nada.
+     */
+    load(options?: LoadEnvOptions): Promise<LoadEnvResult>;
+    /**
+     * Un aviso firmado de la central ya contestado: baja lo último y lo aplica. Nunca lanza. Si el producto no llamó a `loadGrowTicketsEnv()` en el
+     * arranque este proceso no tiene las variables de la central puestas, y reiniciarlo (o ponerlas ahora) no arreglaría nada: se ignora el aviso, se
+     * dice una vez por hora y la central ve que esta réplica no confirma.
+     */
+    pushed(): Promise<void>;
+    stopPolling(): void;
+    pollingActive(): boolean;
+    /** Una revisión: la misma que hace el temporizador cada minuto. Pública para las pruebas. */
+    poll(): Promise<PollHint>;
+    private emit;
+    /**
+     * El cierre ordenado de `restart`: con la app a mano, `app.close()` (que termina lo pendiente y manda los logs); sin ella, manda lo último
+     * de los logs y espera un instante a que se vacíen las respuestas. Después sale con el código pedido —`loadGrowTicketsEnv({ exitCode })`, o
+     * `GROWTICKETS_ENV_EXIT_CODE`, o 75 de serie—, y un tope de diez segundos impide que una conexión colgada deje al proceso vivo con las variables
+     * viejas. ⚠️ Es 75 y no 0 a propósito: Railway (política «On Failure» de serie), Docker `restart: on-failure` y systemd `Restart=on-failure` no
+     * reinician una salida con 0, y el producto se quedaría caído tras cada «Vincular». Con `restart: always`, PM2 o Kubernetes da igual; con un
+     * gestor al que un código distinto de 0 le parezca un fallo que alerta, se pone `GROWTICKETS_ENV_EXIT_CODE=0`.
+     */
+    private restart;
+    private warnOnce;
+}
+/** La instancia de este proceso, creada al primer uso. */
+export declare function envRuntime(): EnvRuntime;
+/** Sólo pruebas: instala (o quita, con `null`) la instancia del proceso. */
+export declare function installEnvRuntime(runtime: EnvRuntime | null): void;
+/** ¿Hay ya una instancia? El middleware lo pregunta antes de crear una: sin clave en el entorno no hay nada que crear. */
+export declare function envRuntimeExists(): boolean;
+export {};

package/dist/env/runtime.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvRuntime = void 0;
+exports.envRuntime = envRuntime;
+exports.installEnvRuntime = installEnvRuntime;
+exports.envRuntimeExists = envRuntimeExists;
+const monitor_1 = require("../logs/monitor");
+const runtime_1 = require("../security/runtime");
+const applier_1 = require("./applier");
+const errors_1 = require("./errors");
+const overlay_1 = require("./overlay");
+const poller_1 = require("./poller");
+const settings_1 = require("./settings");
+const snapshot_1 = require("./snapshot");
+const state_1 = require("./state");
+const storage_1 = require("./storage");
+const transport_1 = require("./transport");
+const POLL_INTERVAL_MS = 60_000;
+const POLL_JITTER_MS = 15_000;
+const POLL_SLOW_MS = 5 * 60_000;
+const WARN_EVERY_SECONDS = 3600;
+const RESTART_GRACE_MS = 250;
+const RESTART_LIMIT_MS = 10_000;
+const STOP_POLLING = new Set(['invalid_key', 'revoked_key', 'expired_key']);
+/**
+ * Todo el estado de las variables desde la central de UN proceso: lo que dice el entorno, la copia cifrada, lo aplicado, la revisión de cada
+ * minuto, los nonce de los avisos y los oyentes de `reload`. El arranque (`loadGrowTicketsEnv`), el middleware (la ruta del aviso) y la CLI
+ * hablan con esta clase y no entre ellos.
+ *
+ * ## Por qué hay UNA instancia y vive en `globalThis`
+ *
+ * El arranque corre en `main.ts`, fuera del contenedor de Nest, y la ruta del aviso en el middleware: tienen que compartir lo aplicado y el
+ * candado. `globalThis[Symbol.for(…)]` también resiste a que el producto acabe con dos copias de esta librería en `node_modules`.
+ *
+ * ## Apagada, no hace nada
+ *
+ * Sin credencial para la central (`transport.configured()`) no pregunta, no escucha avisos y no arranca ningún temporizador.
+ */
+class EnvRuntime {
+    constructor(deps) {
+        this.deps = deps;
+        this.listeners = new Set();
+        this.warned = new Map();
+        this.app = null;
+        this.exitCode = null;
+        this.booted = false;
+        this.transport = deps.transport ?? (0, transport_1.createEnvTransport)({ env: deps.env, fetchImpl: deps.fetchImpl, learnedOrigin: deps.learnedOrigin, sleep: deps.sleep, now: deps.now });
+        this.storage = new storage_1.EnvStorage({ dir: () => this.settings().dir, cwd: deps.cwd });
+        this.snapshot = new snapshot_1.EnvSnapshot(this.storage, () => this.transport.snapshotKey(), deps.now);
+        this.state = new state_1.EnvState(this.storage, deps.now);
+        this.applier = new applier_1.EnvApplier({
+            settings: () => this.settings(),
+            transport: this.transport,
+            snapshot: this.snapshot,
+            state: this.state,
+            overlay: new overlay_1.EnvOverlay(deps.env()),
+            now: deps.now,
+            onReload: (change) => this.emit(change),
+            onRestart: () => this.restart(),
+            warn: deps.warn,
+        });
+        this.poller = new poller_1.EnvPoller({ tick: () => this.poll(), intervalMs: POLL_INTERVAL_MS, jitterMs: POLL_JITTER_MS, slowMs: POLL_SLOW_MS, random: deps.random });
+    }
+    settings() {
+        return (0, settings_1.readEnvSettings)(this.deps.env());
+    }
+    enabled() {
+        return this.transport.configured();
+    }
+    now() {
+        return this.deps.now();
+    }
+    warn(message) {
+        this.deps.warn(message);
+    }
+    /** La app de Nest, para cerrarla en orden al reiniciar. La deja el middleware de `main.ts`, que es quien la recibe. */
+    attachApp(app) {
+        if (app && typeof app.close === 'function')
+            this.app = app;
+    }
+    /** Suscribe un oyente de `reload`. Devuelve la función que lo quita. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * El arranque: baja las variables, las pone en `process.env` y deja en marcha la revisión de cada minuto. Si no se puede (la central no
+     * contesta y no hay una copia que sirva, o la clave está revocada) LANZA `EnvError` y el producto no arranca: es lo que `fail` y una
+     * clave muerta piden, y arrancar sin su configuración es peor que no arrancar. Sin credencial no hace nada.
+     */
+    async load(options = {}) {
+        if (!this.enabled())
+            return { status: 'off', version: 0, environment: null, count: 0, discarded: [] };
+        this.booted = true;
+        if (options.onEnvChange)
+            this.onChange(options.onEnvChange);
+        if (Number.isInteger(options.exitCode))
+            this.exitCode = options.exitCode;
+        for (const comprobacion of this.transport.diagnose())
+            if (comprobacion.level === 'fail')
+                this.deps.warn(`GrowTickets: ${comprobacion.text}`);
+        const resultado = await this.applier.apply({ phase: 'boot', network: true, wait: true, ackCurrent: true });
+        if (resultado.status === 'failed') {
+            throw new errors_1.EnvError(resultado.reason ?? 'apply_failed', `GrowTickets no pudo cargar las variables de entorno (${resultado.reason ?? 'apply_failed'}): ${resultado.message}`);
+        }
+        if (options.poll !== false && this.deps.timer)
+            this.poller.start();
+        const payload = resultado.payload;
+        const estado = resultado.status === 'applied' || resultado.status === 'offline' || resultado.status === 'empty' ? resultado.status : 'current';
+        return {
+            status: estado,
+            version: payload?.version ?? 0,
+            environment: payload?.environmentName ?? null,
+            count: payload ? Object.keys(payload.variables).length : 0,
+            discarded: payload?.discarded ?? [],
+        };
+    }
+    /**
+     * Un aviso firmado de la central ya contestado: baja lo último y lo aplica. Nunca lanza. Si el producto no llamó a `loadGrowTicketsEnv()` en el
+     * arranque este proceso no tiene las variables de la central puestas, y reiniciarlo (o ponerlas ahora) no arreglaría nada: se ignora el aviso, se
+     * dice una vez por hora y la central ve que esta réplica no confirma.
+     */
+    async pushed() {
+        if (!this.booted) {
+            this.warnOnce('push:not-booted', 'GrowTickets: llegó un aviso de variables de entorno pero loadGrowTicketsEnv() no se llamó en main.ts: se ignora.');
+            return;
+        }
+        try {
+            const resultado = await this.applier.apply({ phase: 'live', network: true, wait: true, ackCurrent: true });
+            if (resultado.status === 'failed')
+                this.warnOnce(`push:${resultado.reason}`, `GrowTickets: no se pudo aplicar el aviso de variables de entorno (${resultado.reason}): ${resultado.message}`);
+        }
+        catch {
+            this.warnOnce('push:crash', 'GrowTickets: falló la aplicación de un aviso de variables de entorno.');
+        }
+    }
+    stopPolling() {
+        this.poller.stop();
+    }
+    pollingActive() {
+        return this.poller.running();
+    }
+    /** Una revisión: la misma que hace el temporizador cada minuto. Pública para las pruebas. */
+    async poll() {
+        if (!this.enabled())
+            return 'stop';
+        try {
+            const resultado = await this.applier.apply({ phase: 'live', network: true, wait: false, ackCurrent: false });
+            if (resultado.reason && resultado.status !== 'empty') {
+                this.warnOnce(`poll:${resultado.reason}`, `GrowTickets: la revisión de variables de entorno falló (${resultado.reason}): ${resultado.message}`);
+            }
+            if (resultado.reason === 'rate_limited')
+                return 'slow';
+            if (resultado.status !== 'failed')
+                return 'continue';
+            return resultado.reason !== null && STOP_POLLING.has(resultado.reason) ? 'stop' : 'continue';
+        }
+        catch {
+            return 'continue';
+        }
+    }
+    async emit(change) {
+        for (const oyente of [...this.listeners]) {
+            try {
+                await oyente(change);
+            }
+            catch {
+                this.deps.warn('GrowTickets: un oyente de onEnvChange lanzó una excepción; las variables ya están puestas.');
+            }
+        }
+    }
+    /**
+     * El cierre ordenado de `restart`: con la app a mano, `app.close()` (que termina lo pendiente y manda los logs); sin ella, manda lo último
+     * de los logs y espera un instante a que se vacíen las respuestas. Después sale con el código pedido —`loadGrowTicketsEnv({ exitCode })`, o
+     * `GROWTICKETS_ENV_EXIT_CODE`, o 75 de serie—, y un tope de diez segundos impide que una conexión colgada deje al proceso vivo con las variables
+     * viejas. ⚠️ Es 75 y no 0 a propósito: Railway (política «On Failure» de serie), Docker `restart: on-failure` y systemd `Restart=on-failure` no
+     * reinician una salida con 0, y el producto se quedaría caído tras cada «Vincular». Con `restart: always`, PM2 o Kubernetes da igual; con un
+     * gestor al que un código distinto de 0 le parezca un fallo que alerta, se pone `GROWTICKETS_ENV_EXIT_CODE=0`.
+     */
+    async restart() {
+        const salir = this.deps.exit ?? ((code) => process.exit(code));
+        const codigo = this.exitCode ?? this.settings().exitCode;
+        const tope = setTimeout(() => salir(codigo), RESTART_LIMIT_MS);
+        try {
+            if (this.app?.close) {
+                await this.app.close();
+            }
+            else {
+                await (0, monitor_1.logMonitor)()?.shutdown();
+                await (this.deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))))(RESTART_GRACE_MS);
+            }
+        }
+        catch {
+            this.deps.warn('GrowTickets: el cierre ordenado falló; se sale igualmente para tomar las variables nuevas.');
+        }
+        salir(codigo);
+        clearTimeout(tope);
+    }
+    warnOnce(clave, mensaje) {
+        const ahora = this.deps.now();
+        const ultimo = this.warned.get(clave);
+        if (ultimo !== undefined && ahora - ultimo < WARN_EVERY_SECONDS)
+            return;
+        this.warned.set(clave, ahora);
+        this.deps.warn(mensaje);
+    }
+}
+exports.EnvRuntime = EnvRuntime;
+const KEY = Symbol.for('growtickets.nest.env');
+/** La instancia de este proceso, creada al primer uso. */
+function envRuntime() {
+    const global = globalThis;
+    global[KEY] ??= new EnvRuntime({
+        env: () => process.env,
+        now: () => Math.floor(Date.now() / 1000),
+        cwd: () => process.cwd(),
+        warn: (message) => {
+            process.stderr.write(`${message}\n`);
+        },
+        timer: true,
+        learnedOrigin: () => (0, runtime_1.securityRuntime)().origin(),
+    });
+    return global[KEY];
+}
+/** Sólo pruebas: instala (o quita, con `null`) la instancia del proceso. */
+function installEnvRuntime(runtime) {
+    const global = globalThis;
+    if (runtime)
+        global[KEY] = runtime;
+    else
+        delete global[KEY];
+}
+/** ¿Hay ya una instancia? El middleware lo pregunta antes de crear una: sin clave en el entorno no hay nada que crear. */
+function envRuntimeExists() {
+    return globalThis[KEY] !== undefined;
+}

package/dist/env/settings.d.ts

@@ -0,0 +1,26 @@
+type Env = Record<string, string | undefined>;
+export declare const DEFAULT_ENV_PATH = "growtickets/env";
+export type EnvOnFailure = 'keep' | 'fail';
+export type EnvOnChange = 'restart' | 'reload';
+export interface EnvSettings {
+    /** `GROWTICKETS_ENV_PATH`: por dónde avisa la central (`POST {path}/{operación}`), sin barras en los extremos. */
+    path: string;
+    onFailure: EnvOnFailure;
+    maxStaleHours: number;
+    onChange: EnvOnChange;
+    /** `GROWTICKETS_ENV_DIR`: dónde guarda lo suyo (copia cifrada y estado); `null` = la carpeta de serie. */
+    dir: string | null;
+    /** `GROWTICKETS_ENV_EXIT_CODE`: el código con que sale el proceso al reiniciar para tomar una versión nueva (`restart`). */
+    exitCode: number;
+}
+/** 75 = `EX_TEMPFAIL` de `sysexits.h`: «vuelve a intentarlo». Una salida con 0 no la reinicia una política «sólo si falla» (Railway de serie, Docker `on-failure`). */
+export declare const DEFAULT_EXIT_CODE = 75;
+/**
+ * Lo que el entorno dice de CÓMO se comporta la pieza, con los valores de serie en un solo sitio. NUNCA lanza: una variable mal escrita cae a
+ * su valor por defecto. Se lee en cada llamada (es un objeto en memoria) para que un cambio de entorno —y las pruebas— se noten.
+ *
+ * Nada de aquí dice cómo se autentica ni se cifra la conversación con la central: la credencial, la dirección y la firma son del transporte
+ * (`env/transport`), que es la única pieza que cambiaría con otra versión del protocolo.
+ */
+export declare function readEnvSettings(env: Env): EnvSettings;
+export {};