@growconnect/growtickets-nest 0.1.0 → 0.3.0

package/dist/env/settings.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EXIT_CODE = exports.DEFAULT_ENV_PATH = void 0;
+exports.readEnvSettings = readEnvSettings;
+exports.DEFAULT_ENV_PATH = 'growtickets/env';
+/** 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`). */
+exports.DEFAULT_EXIT_CODE = 75;
+const DEFAULT_MAX_STALE_HOURS = 168;
+const PATH_SHAPE = /^[A-Za-z0-9][A-Za-z0-9/_-]{0,118}$/;
+/**
+ * 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.
+ */
+function readEnvSettings(env) {
+    const horas = Number.parseInt((env.GROWTICKETS_ENV_MAX_STALE_HOURS ?? '').trim(), 10);
+    const dir = (env.GROWTICKETS_ENV_DIR ?? '').trim();
+    return {
+        path: cleanPath(env.GROWTICKETS_ENV_PATH),
+        onFailure: (env.GROWTICKETS_ENV_ON_FAILURE ?? '').trim().toLowerCase() === 'fail' ? 'fail' : 'keep',
+        maxStaleHours: Number.isFinite(horas) && horas >= 1 ? horas : DEFAULT_MAX_STALE_HOURS,
+        onChange: (env.GROWTICKETS_ENV_ON_CHANGE ?? '').trim().toLowerCase() === 'reload' ? 'reload' : 'restart',
+        dir: dir === '' ? null : dir,
+        exitCode: cleanExitCode(env.GROWTICKETS_ENV_EXIT_CODE),
+    };
+}
+/** Un entero de 0 a 255 (lo que cabe en un código de salida); cualquier otra cosa vuelve al de serie. */
+function cleanExitCode(value) {
+    const texto = (value ?? '').trim();
+    return /^\d{1,3}$/.test(texto) && Number(texto) <= 255 ? Number(texto) : exports.DEFAULT_EXIT_CODE;
+}
+/**
+ * Por dónde avisa la central. Esta cadena acaba comparada con la ruta de cada petición, así que sólo letras, números, `/`, `_` y `-`: lo
+ * que no tenga esa forma vuelve a la de serie.
+ */
+function cleanPath(value) {
+    const ruta = (value ?? exports.DEFAULT_ENV_PATH).trim().replace(/^[/\s]+|[/\s]+$/g, '');
+    return PATH_SHAPE.test(ruta) && !ruta.includes('//') ? ruta : exports.DEFAULT_ENV_PATH;
+}

package/dist/env/snapshot.d.ts

@@ -0,0 +1,32 @@
+import { type EnvPayload } from './policy';
+import type { EnvStorage } from './storage';
+export declare const SNAPSHOT_FILE = "env.snapshot";
+export interface SnapshotCopy {
+    payload: EnvPayload;
+    /** Cuándo se bajó o se confirmó por última vez (segundos Unix). */
+    fetchedAt: number;
+}
+/**
+ * La COPIA LOCAL de la última versión bajada, CIFRADA, en `env.snapshot` con permisos 0600. Sirve para tres cosas: preguntar a la central
+ * con `If-None-Match` (si nada cambió contesta 304 y se reconstruye con esto), saber desde qué versión no se puede retroceder, y arrancar
+ * si la central no contesta (`GROWTICKETS_ENV_ON_FAILURE=keep`, hasta `max_stale_hours`).
+ *
+ * AES-256-GCM con una llave que le da el transporte (`snapshotKey()`; el transporte decide de qué semilla sale y la deriva aparte de lo que
+ * firma los avisos): sin la llave el archivo no dice nada, y con otra (se rotó) no se lee —la etiqueta de GCM no casa— y se baja de nuevo. El formato es `gtenv1:` y base64 de
+ * `iv(12) | etiqueta(16) | cifrado`; el nombre de la librería viaja como dato autenticado, así que el archivo no vale para otro uso.
+ */
+export declare class EnvSnapshot {
+    private readonly storage;
+    private readonly key;
+    private readonly now;
+    constructor(storage: EnvStorage, key: () => Buffer | null, now: () => number);
+    /** La copia, o `null` si no hay, no se puede leer o es de otra clave. */
+    read(): SnapshotCopy | null;
+    /** Guarda la versión bajada. Nunca lanza: sin copia se sigue funcionando. */
+    write(payload: EnvPayload, fetchedAt?: number): boolean;
+    /** Marca la copia como recién confirmada (la central contestó 304: sigue valiendo). */
+    touch(payload: EnvPayload): boolean;
+    forget(): void;
+    /** Horas desde que se bajó, o `null` sin copia. */
+    ageHours(copia: SnapshotCopy | null): number | null;
+}

package/dist/env/snapshot.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvSnapshot = exports.SNAPSHOT_FILE = void 0;
+const node_crypto_1 = require("node:crypto");
+const policy_1 = require("./policy");
+exports.SNAPSHOT_FILE = 'env.snapshot';
+const FORMAT = 'gtenv1:';
+const AAD = Buffer.from('growtickets-env-snapshot', 'utf8');
+const IV_END = 12;
+const TAG_END = 28;
+/**
+ * La COPIA LOCAL de la última versión bajada, CIFRADA, en `env.snapshot` con permisos 0600. Sirve para tres cosas: preguntar a la central
+ * con `If-None-Match` (si nada cambió contesta 304 y se reconstruye con esto), saber desde qué versión no se puede retroceder, y arrancar
+ * si la central no contesta (`GROWTICKETS_ENV_ON_FAILURE=keep`, hasta `max_stale_hours`).
+ *
+ * AES-256-GCM con una llave que le da el transporte (`snapshotKey()`; el transporte decide de qué semilla sale y la deriva aparte de lo que
+ * firma los avisos): sin la llave el archivo no dice nada, y con otra (se rotó) no se lee —la etiqueta de GCM no casa— y se baja de nuevo. El formato es `gtenv1:` y base64 de
+ * `iv(12) | etiqueta(16) | cifrado`; el nombre de la librería viaja como dato autenticado, así que el archivo no vale para otro uso.
+ */
+class EnvSnapshot {
+    constructor(storage, key, now) {
+        this.storage = storage;
+        this.key = key;
+        this.now = now;
+    }
+    /** La copia, o `null` si no hay, no se puede leer o es de otra clave. */
+    read() {
+        const crudo = this.storage.read(exports.SNAPSHOT_FILE);
+        const llave = this.key();
+        if (crudo === null || llave === null || !crudo.startsWith(FORMAT))
+            return null;
+        try {
+            const bytes = Buffer.from(crudo.slice(FORMAT.length).trim(), 'base64');
+            if (bytes.length <= TAG_END)
+                return null;
+            const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', llave, bytes.subarray(0, IV_END), { authTagLength: TAG_END - IV_END });
+            decipher.setAAD(AAD);
+            decipher.setAuthTag(bytes.subarray(IV_END, TAG_END));
+            const texto = Buffer.concat([decipher.update(bytes.subarray(TAG_END)), decipher.final()]).toString('utf8');
+            const datos = JSON.parse(texto);
+            const payload = (0, policy_1.parseEnvPayload)({ schema: 1, ...datos.payload }, typeof datos.payload?.etag === 'string' ? datos.payload.etag : null);
+            return { payload, fetchedAt: Number.isFinite(Number(datos.fetched_at)) ? Number(datos.fetched_at) : 0 };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Guarda la versión bajada. Nunca lanza: sin copia se sigue funcionando. */
+    write(payload, fetchedAt = this.now()) {
+        const llave = this.key();
+        if (llave === null)
+            return false;
+        try {
+            const iv = (0, node_crypto_1.randomBytes)(IV_END);
+            const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', llave, iv, { authTagLength: TAG_END - IV_END });
+            cipher.setAAD(AAD);
+            const contenido = JSON.stringify({
+                payload: {
+                    version: payload.version,
+                    environment: { id: payload.environmentId, name: payload.environmentName, kind: payload.environmentKind },
+                    variables: payload.variables,
+                    etag: payload.etag,
+                },
+                fetched_at: fetchedAt,
+            });
+            const cifrado = Buffer.concat([cipher.update(contenido, 'utf8'), cipher.final()]);
+            return this.storage.write(exports.SNAPSHOT_FILE, FORMAT + Buffer.concat([iv, cipher.getAuthTag(), cifrado]).toString('base64'));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Marca la copia como recién confirmada (la central contestó 304: sigue valiendo). */
+    touch(payload) {
+        return this.write(payload);
+    }
+    forget() {
+        this.storage.remove(exports.SNAPSHOT_FILE);
+    }
+    /** Horas desde que se bajó, o `null` sin copia. */
+    ageHours(copia) {
+        return copia === null ? null : Math.max(0, this.now() - copia.fetchedAt) / 3600;
+    }
+}
+exports.EnvSnapshot = EnvSnapshot;

package/dist/env/state.d.ts

@@ -0,0 +1,27 @@
+import type { EnvPayload } from './policy';
+import type { EnvStorage } from './storage';
+export declare const STATE_FILE = "env.state";
+export interface EnvStateData {
+    /** «entorno:versión» de lo último aplicado, o `null` si nunca. */
+    applied: string | null;
+    version: number;
+    environment: number;
+    /** Segundos Unix. */
+    appliedAt: number;
+    /** Cuántas variables se pusieron en la última aplicación. Nunca sus nombres. */
+    count: number;
+    /** Los nombres que la política descartó la última vez (sólo nombres, hasta 20). */
+    discarded: string[];
+}
+/**
+ * Qué tiene aplicado este servidor, en disco (`env.state`): el entorno y la versión de lo último que se puso, y cuándo. No lleva ningún valor
+ * ni ningún nombre de variable aplicada. Es lo que deja a `growtickets-nest env status`, que es OTRO proceso, decir qué versión corre, y lo
+ * que sostiene el «no se retrocede» entre un arranque y el siguiente.
+ */
+export declare class EnvState {
+    private readonly storage;
+    private readonly now;
+    constructor(storage: EnvStorage, now: () => number);
+    read(): EnvStateData;
+    applied(payload: EnvPayload): void;
+}

package/dist/env/state.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvState = exports.STATE_FILE = void 0;
+const policy_1 = require("./policy");
+exports.STATE_FILE = 'env.state';
+/**
+ * Qué tiene aplicado este servidor, en disco (`env.state`): el entorno y la versión de lo último que se puso, y cuándo. No lleva ningún valor
+ * ni ningún nombre de variable aplicada. Es lo que deja a `growtickets-nest env status`, que es OTRO proceso, decir qué versión corre, y lo
+ * que sostiene el «no se retrocede» entre un arranque y el siguiente.
+ */
+class EnvState {
+    constructor(storage, now) {
+        this.storage = storage;
+        this.now = now;
+    }
+    read() {
+        const vacio = { applied: null, version: 0, environment: 0, appliedAt: 0, count: 0, discarded: [] };
+        const crudo = this.storage.read(exports.STATE_FILE);
+        if (crudo === null)
+            return vacio;
+        try {
+            const datos = JSON.parse(crudo);
+            return {
+                applied: typeof datos.applied === 'string' ? datos.applied : null,
+                version: int(datos.version),
+                environment: int(datos.environment),
+                appliedAt: int(datos.applied_at),
+                count: int(datos.count),
+                discarded: Array.isArray(datos.discarded) ? datos.discarded.filter((n) => typeof n === 'string').slice(0, 20) : [],
+            };
+        }
+        catch {
+            return vacio;
+        }
+    }
+    applied(payload) {
+        this.storage.write(exports.STATE_FILE, JSON.stringify({
+            applied: (0, policy_1.markerOf)(payload),
+            version: payload.version,
+            environment: payload.environmentId,
+            applied_at: this.now(),
+            count: Object.keys(payload.variables).length,
+            discarded: payload.discarded.slice(0, 20),
+        }));
+    }
+}
+exports.EnvState = EnvState;
+function int(value) {
+    const n = Number(value);
+    return Number.isSafeInteger(n) && n > 0 ? n : 0;
+}

package/dist/env/storage.d.ts

@@ -0,0 +1,33 @@
+export interface StorageOptions {
+    /** `GROWTICKETS_ENV_DIR`: si se fija, es la única carpeta que se usa. Se pregunta en cada uso: el entorno puede cambiar. */
+    dir: () => string | null;
+    cwd: () => string;
+}
+/**
+ * Dónde guarda la pieza lo suyo (la copia cifrada y el estado): una carpeta propia con permisos 0700 y archivos 0600.
+ *
+ * De serie es `.growtickets/` junto al proceso. Si no se puede escribir ahí (un contenedor con el sistema de archivos de sólo lectura), cae
+ * a una carpeta del directorio temporal con el usuario en el nombre, y sólo la usa si ya es un directorio de verdad (no un enlace), del
+ * mismo usuario y sin permisos para los demás: en un `/tmp` compartido cualquiera pudo crear antes ese nombre. Una carpeta fijada con
+ * `GROWTICKETS_ENV_DIR` no tiene alternativa: es decisión de quien administra el servidor.
+ *
+ * Escribir nunca lanza: sin copia el servidor sigue funcionando, sólo pregunta más a la central. Se escribe en un temporal y se
+ * renombra, así que un corte a medias deja el archivo anterior entero, nunca la mitad.
+ */
+export declare class EnvStorage {
+    private readonly options;
+    private resolved;
+    constructor(options: StorageOptions);
+    /** La carpeta de trabajo, creada. `null` si ninguna sirve. */
+    directory(): string | null;
+    /** Todas las carpetas donde pudo quedar algo, la preferida primero: la lectura mira en las dos. */
+    readCandidates(): string[];
+    read(name: string): string | null;
+    /** Escribe `contenido` en `name` con permisos 0600, de forma atómica. `false` si no se pudo. */
+    write(name: string, contenido: string): boolean;
+    /** Borra el archivo de TODAS las carpetas posibles (una clave revocada no deja copias). */
+    remove(name: string): void;
+    private candidates;
+    private prepare;
+    private writable;
+}

package/dist/env/storage.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvStorage = void 0;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const MAX_FILE_BYTES = 16 * 1024 * 1024;
+/**
+ * Dónde guarda la pieza lo suyo (la copia cifrada y el estado): una carpeta propia con permisos 0700 y archivos 0600.
+ *
+ * De serie es `.growtickets/` junto al proceso. Si no se puede escribir ahí (un contenedor con el sistema de archivos de sólo lectura), cae
+ * a una carpeta del directorio temporal con el usuario en el nombre, y sólo la usa si ya es un directorio de verdad (no un enlace), del
+ * mismo usuario y sin permisos para los demás: en un `/tmp` compartido cualquiera pudo crear antes ese nombre. Una carpeta fijada con
+ * `GROWTICKETS_ENV_DIR` no tiene alternativa: es decisión de quien administra el servidor.
+ *
+ * Escribir nunca lanza: sin copia el servidor sigue funcionando, sólo pregunta más a la central. Se escribe en un temporal y se
+ * renombra, así que un corte a medias deja el archivo anterior entero, nunca la mitad.
+ */
+class EnvStorage {
+    constructor(options) {
+        this.options = options;
+        this.resolved = null;
+    }
+    /** La carpeta de trabajo, creada. `null` si ninguna sirve. */
+    directory() {
+        if (this.resolved !== null && (0, node_fs_1.existsSync)(this.resolved))
+            return this.resolved;
+        for (const candidata of this.candidates()) {
+            if (this.prepare(candidata.path, candidata.strict)) {
+                this.resolved = candidata.path;
+                return candidata.path;
+            }
+        }
+        return null;
+    }
+    /** Todas las carpetas donde pudo quedar algo, la preferida primero: la lectura mira en las dos. */
+    readCandidates() {
+        return this.candidates().map((c) => c.path);
+    }
+    read(name) {
+        for (const dir of this.readCandidates()) {
+            const ruta = (0, node_path_1.join)(dir, name);
+            try {
+                if ((0, node_fs_1.existsSync)(ruta) && (0, node_fs_1.statSync)(ruta).size <= MAX_FILE_BYTES)
+                    return (0, node_fs_1.readFileSync)(ruta, 'utf8');
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    }
+    /** Escribe `contenido` en `name` con permisos 0600, de forma atómica. `false` si no se pudo. */
+    write(name, contenido) {
+        const dir = this.directory();
+        if (dir === null)
+            return false;
+        const destino = (0, node_path_1.join)(dir, name);
+        const temporal = `${destino}.${(0, node_crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+        try {
+            const fd = (0, node_fs_1.openSync)(temporal, 'wx', 0o600);
+            try {
+                (0, node_fs_1.writeSync)(fd, contenido);
+            }
+            finally {
+                (0, node_fs_1.closeSync)(fd);
+            }
+            (0, node_fs_1.chmodSync)(temporal, 0o600);
+            (0, node_fs_1.renameSync)(temporal, destino);
+            return true;
+        }
+        catch {
+            try {
+                (0, node_fs_1.unlinkSync)(temporal);
+            }
+            catch {
+                return false;
+            }
+            return false;
+        }
+    }
+    /** Borra el archivo de TODAS las carpetas posibles (una clave revocada no deja copias). */
+    remove(name) {
+        for (const dir of this.readCandidates()) {
+            try {
+                (0, node_fs_1.unlinkSync)((0, node_path_1.join)(dir, name));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    candidates() {
+        const fijada = this.options.dir();
+        if (fijada !== null)
+            return [{ path: fijada, strict: false }];
+        const uid = typeof process.getuid === 'function' ? String(process.getuid()) : 'user';
+        return [
+            { path: (0, node_path_1.join)(this.options.cwd(), '.growtickets'), strict: false },
+            { path: (0, node_path_1.join)((0, node_os_1.tmpdir)(), `growtickets-${uid}`), strict: true },
+        ];
+    }
+    prepare(path, strict) {
+        try {
+            (0, node_fs_1.mkdirSync)(path, { recursive: true, mode: 0o700 });
+            const info = (0, node_fs_1.lstatSync)(path);
+            if (!info.isDirectory())
+                return false;
+            if (strict) {
+                const mio = typeof process.getuid !== 'function' || info.uid === process.getuid();
+                if (!mio || (info.mode & 0o077) !== 0)
+                    return false;
+            }
+            return this.writable(path);
+        }
+        catch {
+            return false;
+        }
+    }
+    writable(path) {
+        const prueba = (0, node_path_1.join)(path, `.write-test-${(0, node_crypto_1.randomBytes)(4).toString('hex')}`);
+        try {
+            (0, node_fs_1.closeSync)((0, node_fs_1.openSync)(prueba, 'wx', 0o600));
+            (0, node_fs_1.unlinkSync)(prueba);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.EnvStorage = EnvStorage;

package/dist/env/transport/client.d.ts

@@ -0,0 +1,58 @@
+import { type EnvPayload } from '../policy';
+import type { EnvCredential } from './credential';
+import { type TransportConfig } from './config';
+export interface EnvClientDeps {
+    /** La credencial del servidor; lanza `EnvError` `invalid_key` si falta o no tiene la forma. */
+    credential: () => EnvCredential;
+    config: () => TransportConfig;
+    env: () => Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+    /** La última dirección pública que vio la seguridad, para cuando `GROWTICKETS_ORIGIN` no la fija. */
+    learnedOrigin?: () => string | null;
+    /** Para las pruebas: la espera entre intentos. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Segundos, época Unix. Para las pruebas: el reloj que firma. */
+    now?: () => number;
+    /** Para las pruebas: el azar de los nonce y las efímeras, que el vector común fija byte a byte. */
+    random?: (bytes: number) => Buffer;
+}
+/**
+ * Lo que habla con la central (protocolo GT-ENV2): bajar las variables de ESTE servidor (`GET api/ingest/env`) y confirmar que se aplicaron
+ * (`POST api/ingest/env/ack`). Ninguna clave viaja: cada petición va FIRMADA con la llave del servidor (`EnvCredential`) y cada respuesta se
+ * cree sólo si la firmó la central FIJADA en la credencial.
+ *
+ * - **Cifrado de punta a punta**: al bajar se manda una efímera X25519 nueva (firmada dentro de la petición) y la central cifra para ella. Sólo
+ *   este proceso puede abrir la respuesta, y la efímera se borra al salir: capturar el tráfico —o robar luego la credencial— no descifra nada.
+ * - **Sólo lo firmado cambia el estado**: un 304, un «revocada» o un error sin la firma de la central son `unsigned_response` (un fallo
+ *   pasajero: se sigue con la copia), y un 200 sin cifrar no se acepta aunque venga firmado.
+ * - **Sólo https** (salvo `localhost`, `127.0.0.1` y nombres `.test`/`.localhost`), **sin redirecciones** (`redirect: 'error'`), **tiempos y
+ *   tamaño con tope** (3 s hasta la respuesta, 10 s en total, 8 MB) y hasta tres intentos si la central no contestó o dio 5xx: cada uno con su
+ *   hora, su nonce y su efímera, porque repetir la misma petición sería un `replayed`.
+ * - **Errores con CÓDIGO** (`invalid_key`, `revoked_key`, `expired_key`, `no_environment`, `not_published`, `clock_skew`, `replayed`,
+ *   `network_not_allowed`, `unsigned_response`, `unreachable`, `timeout`, `malformed`, `incompatible_schema`), nunca con un valor ni con la
+ *   credencial.
+ *
+ * Cada petición dice quién pregunta —la réplica, la dirección del producto, la ruta por la que escucha avisos, la librería y el runtime— y
+ * esas cabeceras van DENTRO de la firma: la central las guarda y las usa.
+ */
+export declare class EnvClient {
+    private readonly deps;
+    constructor(deps: EnvClientDeps);
+    /** La versión vigente, o `null` si la central dice (firmado) que no cambió: 304 con el `etag` de la copia. */
+    fetch(etag?: string | null): Promise<EnvPayload | null>;
+    /** Confirma a la central que esta réplica aplicó (o por qué no). Nunca lanza: un acuse perdido sólo deja el panel atrás. */
+    ack(version: number, ok: boolean, errorCode?: string | null): Promise<boolean>;
+    /**
+     * Lo que entregó la central, si lo FIRMÓ ella para esta petición.
+     *
+     * @throws EnvError
+     */
+    private delivered;
+    /** ¿La firmó la central fijada, para ESTA petición (su hash), con este estado, este cuerpo y este ETag? */
+    private signed;
+    private call;
+    /** Las cabeceras de UNA petición firmada y el hash de su cadena. Cada intento llama otra vez: hora, nonce y efímera nuevos. */
+    private sign;
+    private once;
+    private random;
+}