@hostwebhook/node-sdk 0.1.0

package/dist/pre-request-runner-source.js

@@ -0,0 +1,411 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRE_REQUEST_RUNNER_SOURCE = void 0;
+/**
+ * Source of the child process that runs tenant code.
+ *
+ * Dos clases de trabajo, un solo hijo: el script pre-request de siempre
+ * (`kind: 'pre-request'`, el de por defecto) y el nodo de código
+ * (`kind: 'code'`). Comparten proceso porque comparten exactamente el motivo
+ * de estar aquí — son JS que escribe un inquilino — y porque el pool caliente
+ * ya montado es lo que hace que sacarlos del proceso no se note.
+ *
+ * Kept as a string, not a file, on purpose: the child is started with
+ * `node -e <this>`, so there is no path to resolve and the same code works
+ * under ts-node, jest and `dist/` alike. A file would have to exist at three
+ * different paths depending on how the API was started.
+ *
+ * The globals below are seeded from the child's own realm, and they are the
+ * same list, in the same order, that the in-process sandbox seeded before —
+ * including the cross-realm quirks that come with it (`[] instanceof Array` is
+ * false in here, because the literal's prototype is the vm context's while
+ * `Array` is the child's). Keeping the list identical is what makes a tenant
+ * script compute exactly what it computed before.
+ *
+ * These are real Node intrinsics, not shims. That is only safe because the
+ * realm they come from is worth nothing: the child is started with an empty
+ * environment and, where the runtime supports it, with the filesystem and
+ * process spawning denied. A script that breaks out of the vm — which is easy,
+ * vm was never a boundary — lands in a process that holds no secret.
+ */
+exports.PRE_REQUEST_RUNNER_SOURCE = `
+'use strict';
+
+/* La red se cierra ANTES que nada, y por eso está en la primera línea.
+ *
+ * El modelo de permisos de Node —\`--permission\`— cubre ficheros, spawn,
+ * worker_threads y addons. NO cubre la red: está medido, y un escape del vm
+ * dentro de este hijo encontraba \`require('http')\` y \`fetch\` disponibles.
+ * Y este hijo corre DENTRO de la red privada, así que desde ahí se alcanza
+ * Mongo, Redis, el servicio de metadatos de la nube y la propia API.
+ *
+ * El escape no es hipotético ni difícil: \`payload\` es un objeto del realm
+ * del hijo que entra al sandbox, así que
+ * \`payload.constructor.constructor('return process')()\` sale de golpe. El
+ * comentario de abajo ya lo decía —«vm nunca fue una frontera»—; lo que
+ * faltaba era que el realm al que se sale tampoco tuviera red.
+ *
+ * Esto NO convierte al hijo en un sandbox. La respuesta de verdad es la
+ * POSICIÓN —el worker de Cloudflare, donde no hay red privada que alcanzar—,
+ * y sigue siendo el camino preferido; ver \`code-runner.ts\`. Esto es la capa
+ * que queda puesta mientras tanto y el día que el worker no responda y se
+ * caiga al hijo, que es justo cuando hace falta.
+ *
+ * Se quitan también \`child_process\` y \`worker_threads\`, que el modelo de
+ * permisos ya niega, porque el escalón degradado —cuando el runtime no
+ * soporta el flag— se queda sin esa negación y con éstas no.
+ */
+(function cerrarLaRed() {
+  const Module = require('module');
+
+  /* LISTA BLANCA, no lista negra — y el cambio importa más que su contenido.
+   *
+   * La primera versión enumeraba lo peligroso: http, https, net, tls, dns…
+   * Se rodeaba sin esfuerzo, porque Node expone los mismos transportes con
+   * otros nombres: \`_http_client\`, \`_tls_wrap\`, \`_http_common\` y
+   * \`_stream_wrap\` cargan los cuatro, y ninguno estaba en la lista.
+   *
+   * Enumerar lo prohibido es apostar a conocer TODOS los nombres, hoy y en la
+   * versión de Node de dentro de un año. Enumerar lo permitido es apostar a
+   * conocer lo que este hijo usa, que son tres módulos y están cinco líneas
+   * más abajo. La segunda apuesta se puede ganar.
+   */
+  const PERMITIDOS = new Set(['vm', 'crypto', 'module']);
+
+  const cargar = Module._load;
+  Module._load = function (peticion, padre, esPrincipal) {
+    const nombre = String(peticion).replace(/^node:/, '');
+    if (!PERMITIDOS.has(nombre)) {
+      throw new Error('module "' + peticion + '" is not available to node code');
+    }
+    return cargar.call(this, peticion, padre, esPrincipal);
+  };
+
+  /* \`process.binding\` devuelve los bindings nativos SIN pasar por el cargador
+     de módulos, así que la lista blanca de arriba no lo ve. Es una API vieja y
+     desaconsejada, y este hijo no la usa para nada. \`_linkedBinding\` es su
+     hermana.
+
+     \`getBuiltinModule\` es la misma idea con ropa nueva —Node 20.16 / 22.3—:
+     devuelve el builtin ya resuelto sin tocar \`Module._load\`, así que la
+     lista blanca tampoco lo veía. Está medido en este hijo:
+     \`getBuiltinModule('net')\` daba un socket de verdad, y los bytes llegaban
+     al otro extremo. \`dlopen\` carga un addon nativo, que trae red y todo lo
+     demás; el modelo de permisos ya lo niega, pero el escalón degradado —el
+     que se queda sin esa negación— no. Ninguna de las cuatro la usa este
+     hijo. */
+  for (const nombre of ['binding', '_linkedBinding', 'getBuiltinModule', 'dlopen']) {
+    if (typeof process[nombre] === 'function') {
+      process[nombre] = function () {
+        throw new Error('process.' + nombre + '() is not available to node code');
+      };
+    }
+  }
+
+  /* Registrar hooks de ESM abre un realm nuevo —otro hilo— donde
+     \`Module._load\` NO está parcheado, y el módulo de hooks importa lo que
+     quiera: basta una \`data:\` URL. También está medido, y también en el
+     escalón degradado, que es donde el modelo de permisos no lo niega por su
+     cuenta. \`registerHooks\` es la variante síncrona, que no existe en todas
+     las versiones; de ahí el \`typeof\`. */
+  for (const nombre of ['register', 'registerHooks']) {
+    if (typeof Module[nombre] === 'function') {
+      Module[nombre] = function () {
+        throw new Error('module.' + nombre + '() is not available to node code');
+      };
+    }
+  }
+
+  /* El último cargador que no pasa por \`Module._load\` es el \`import()\`
+     dinámico del contexto principal, y la llave la regala \`vm\`, que sí está
+     permitido porque este hijo lo necesita: pasando
+     \`vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER\` como
+     \`importModuleDynamically\` a \`Script\`, \`compileFunction\`,
+     \`runInThisContext\` o \`runInNewContext\`, \`import('net')\` resuelve —
+     medido igual que las de arriba, con bytes al otro lado. Sin esa llave no
+     queda camino: una callback propia exige \`--experimental-vm-modules\`, que
+     este hijo no lleva.
+
+     El objeto \`constants\` viene congelado, así que el símbolo no se puede
+     borrar de ahí; lo que sí se puede es dejar en \`vm.constants\` una copia
+     sin la llave. La copia conserva el resto de constantes y el prototipo
+     nulo que traía el original, para que lo que un script vea ahí sea lo
+     mismo de antes menos la llave. Si un día ninguna de las dos formas
+     funcionara no habría dónde avisar —este hijo corre con stdio cerrado—: lo
+     que cubre ese caso es el test de este fichero. */
+  const vmParaCerrar = require('vm');
+  const constantes = vmParaCerrar.constants;
+  if (constantes && constantes.USE_MAIN_CONTEXT_DEFAULT_LOADER) {
+    const copia = Object.create(null);
+    for (const clave of Object.getOwnPropertyNames(constantes)) {
+      if (clave !== 'USE_MAIN_CONTEXT_DEFAULT_LOADER') copia[clave] = constantes[clave];
+    }
+    Object.freeze(copia);
+    if (!Reflect.defineProperty(vmParaCerrar, 'constants', {
+      value: copia,
+      configurable: false,
+      writable: false,
+      enumerable: true,
+    })) {
+      Reflect.set(vmParaCerrar, 'constants', copia);
+    }
+  }
+
+  /* Los globales de red no pasan por \`require\`, así que hay que quitarlos
+     aparte. Con \`Reflect\` en vez de \`delete\` + asignación porque estos
+     globales son accesores perezosos: en modo estricto la asignación LANZA, y
+     \`Reflect\` devuelve \`false\` en vez de lanzar. Si las dos formas fallaran
+     —una versión de Node que los clave— no hay dónde avisar: este hijo corre
+     con stdio cerrado. Lo que cubre ese caso es el test de este fichero. */
+  for (const nombre of ['fetch', 'WebSocket', 'EventSource', 'XMLHttpRequest']) {
+    if (!Reflect.deleteProperty(globalThis, nombre)) {
+      Reflect.defineProperty(globalThis, nombre, {
+        value: undefined,
+        configurable: false,
+        writable: false,
+      });
+    }
+  }
+})();
+
+const vm = require('vm');
+const crypto = require('crypto');
+
+/* Una promesa rechazada que el inquilino deja suelta NO puede matar al hijo.
+ *
+ * Desde Node 15, el comportamiento por defecto de \`unhandledRejection\` es
+ * matar el proceso con código 1. Aquí eso es una carrera: el script termina,
+ * mandamos el resultado por IPC y, si Node recoge el rechazo antes de que el
+ * mensaje salga, el padre no ve respuesta — ve morir al hijo y contesta
+ * "Pre-request script worker stopped unexpectedly (1)". El mismo script, la
+ * misma petición, funciona o no según lo cargada que esté la máquina. En una
+ * portátil gana el envío casi siempre; en el runner del CI, no.
+ *
+ * Y basta con \`import('fs')\` —bloqueado, así que la promesa se rechaza— para
+ * dejar una suelta sin querer.
+ *
+ * El manejador está vacío a propósito. Lo tentador es recogerlo en los
+ * \`logs\` que el usuario ve, pero el rechazo aflora DESPUÉS de que el
+ * resultado ya salió: el script corre y se contesta dentro del mismo turno del
+ * bucle, y el evento llega en uno posterior. Un log escrito ahí no viajaría en
+ * esta ejecución, y como el pool reutiliza el proceso, acabaría contado en la
+ * siguiente — un mensaje falso sobre el script de otra persona. Se queda en lo
+ * que sí se puede prometer: el rechazo no mata al hijo.
+ */
+process.on('unhandledRejection', function () {});
+
+// A header value the structured clone cannot carry is replaced by the text the
+// caller would have put on the wire anyway, so the send cannot fail on it.
+function cloneable(headers) {
+  if (!headers || typeof headers !== 'object') return headers;
+  const out = Array.isArray(headers) ? [] : {};
+  for (const key of Object.keys(headers)) {
+    const value = headers[key];
+    const type = typeof value;
+    out[key] = type === 'function' || type === 'symbol' ? String(value) : value;
+  }
+  return out;
+}
+
+/**
+ * El sandbox del nodo de código.
+ *
+ * Misma lista de globales, en el mismo orden, que sembraba \`buildSandbox\` en
+ * proceso — incluidos los recortes deliberados: \`JSON\`, \`Array\` y \`Object\`
+ * entran con sólo unos métodos, no enteros. Mantenerla idéntica es lo que hace
+ * que el código de un inquilino calcule exactamente lo que calculaba antes.
+ *
+ * Aquí sí son los intrínsecos de verdad del hijo, y da igual: el realm del que
+ * salen no vale nada.
+ */
+function buildCodeSandbox(ctx, logs) {
+  function stringify(v) {
+    if (v === undefined) return 'undefined';
+    if (v === null) return 'null';
+    if (typeof v === 'object') {
+      try { return JSON.stringify(v, null, 2); } catch (e) { return String(v); }
+    }
+    return String(v);
+  }
+
+  // \`$("nombre")\` — la salida de otro nodo del lienzo. Misma forma que en
+  // proceso: un iterable devuelve su campo, y \`_meta\` no se ve.
+  function nodeLookup(workspacePayloads) {
+    return function (nodeName) {
+      if (!workspacePayloads) throw new Error('$() requires workspace context');
+      const p = workspacePayloads[nodeName];
+      if (!p) throw new Error('Node "' + nodeName + '" not found');
+      const cloned = JSON.parse(JSON.stringify(p));
+      const m = cloned._meta;
+      if (m && m.iterable && m.iterateField) return cloned[m.iterateField] || [];
+      delete cloned._meta;
+      return cloned;
+    };
+  }
+
+  const sandbox = {
+    payload: ctx.payload,
+    $: nodeLookup(ctx.workspacePayloads),
+    headers: Object.assign({}, ctx.headers || {}),
+    meta: Object.assign({}, ctx.meta || {}),
+    JSON: { parse: JSON.parse, stringify: JSON.stringify },
+    Math: Math,
+    Date: Date,
+    Array: { isArray: Array.isArray, from: Array.from, of: Array.of },
+    Object: {
+      keys: Object.keys, values: Object.values, entries: Object.entries,
+      assign: Object.assign, freeze: Object.freeze,
+    },
+    String: String,
+    Number: Number,
+    Boolean: Boolean,
+    RegExp: RegExp,
+    parseInt: parseInt,
+    parseFloat: parseFloat,
+    isNaN: isNaN,
+    isFinite: isFinite,
+    encodeURIComponent: encodeURIComponent,
+    decodeURIComponent: decodeURIComponent,
+    Map: Map,
+    Set: Set,
+    undefined: undefined,
+    console: {
+      log: function () { logs.push(Array.prototype.map.call(arguments, stringify).join(' ')); },
+      warn: function () { logs.push('[warn] ' + Array.prototype.map.call(arguments, stringify).join(' ')); },
+      error: function () { logs.push('[error] ' + Array.prototype.map.call(arguments, stringify).join(' ')); },
+    },
+  };
+
+  return vm.createContext(sandbox);
+}
+
+function runCodeNode(msg) {
+  const logs = [];
+  let output;
+  try {
+    const sandbox = buildCodeSandbox(msg.ctx, logs);
+    // El envoltorio en función es lo que hace que \`return\` funcione, igual
+    // que en proceso.
+    output = new vm.Script('(function() {\\n' + msg.code + '\\n})()', {
+      filename: 'code-node.js',
+    }).runInContext(sandbox, { timeout: msg.timeoutMs });
+  } catch (err) {
+    process.send({
+      ok: false,
+      logs: logs,
+      name: err && err.name ? String(err.name) : 'Error',
+      message: err && err.message ? String(err.message) : String(err),
+    });
+    return;
+  }
+
+  // Lo que devuelva el inquilino cruza por structured clone. Lo que el clon no
+  // pueda llevar —una función, un símbolo— habría reventado el envío y matado
+  // la ejecución entera; el round-trip por JSON deja pasar lo que sí es
+  // representable y descarta el resto, que es lo que el llamante iba a
+  // serializar de todas formas.
+  try {
+    process.send({ ok: true, output: output === undefined ? null : output, logs: logs });
+  } catch (err) {
+    try {
+      process.send({
+        ok: true,
+        output: output === undefined || output === null
+          ? null
+          : JSON.parse(JSON.stringify(output)),
+        logs: logs,
+      });
+    } catch (again) {
+      process.send({
+        ok: false,
+        logs: logs,
+        name: 'TypeError',
+        message: 'Code node returned a value that cannot be returned: ' +
+          (again && again.message ? again.message : String(again)),
+      });
+    }
+  }
+}
+
+process.on('message', function (msg) {
+  if (msg && msg.kind === 'code') {
+    runCodeNode(msg);
+    return;
+  }
+
+  const ctx = msg.ctx;
+  const req = {
+    url: ctx.url,
+    method: ctx.method,
+    headers: Object.assign({}, ctx.headers),
+    body: ctx.body,
+  };
+
+  const sandbox = vm.createContext({
+    req,
+    payload: Object.freeze(ctx.payload),
+    // Crypto — needed for HMAC-SHA256 (S3, custom signatures)
+    crypto: {
+      createHmac: crypto.createHmac.bind(crypto),
+      createHash: crypto.createHash.bind(crypto),
+      randomUUID: crypto.randomUUID.bind(crypto),
+    },
+    // Standard globals
+    URL: URL,
+    URLSearchParams: URLSearchParams,
+    Buffer: Buffer,
+    Date: Date,
+    JSON: JSON,
+    Math: Math,
+    parseInt: parseInt,
+    parseFloat: parseFloat,
+    encodeURIComponent: encodeURIComponent,
+    decodeURIComponent: decodeURIComponent,
+    encodeURI: encodeURI,
+    decodeURI: decodeURI,
+    atob: globalThis.atob,
+    btoa: globalThis.btoa,
+    console: { log: function () {}, warn: function () {}, error: function () {} },
+    // String/Array/Object utilities
+    String: String,
+    Number: Number,
+    Boolean: Boolean,
+    Array: Array,
+    Object: Object,
+    RegExp: RegExp,
+    Map: Map,
+    Set: Set,
+  });
+
+  try {
+    new vm.Script(msg.code, { filename: 'pre-request-script.js' })
+      .runInContext(sandbox, { timeout: msg.timeoutMs });
+  } catch (err) {
+    process.send({
+      ok: false,
+      name: err && err.name ? String(err.name) : 'Error',
+      message: err && err.message ? String(err.message) : String(err),
+    });
+    return;
+  }
+
+  const result = { ok: true, url: req.url, headers: req.headers, body: req.body };
+  try {
+    process.send(result);
+  } catch (err) {
+    try {
+      result.headers = cloneable(req.headers);
+      process.send(result);
+    } catch (again) {
+      process.send({
+        ok: false,
+        name: 'TypeError',
+        message: 'Pre-request script produced a result that cannot be returned: ' +
+          (again && again.message ? again.message : String(again)),
+      });
+    }
+  }
+});
+
+process.send({ ready: true });
+`;

package/dist/regex-de-inquilino.d.ts

@@ -0,0 +1,15 @@
+import RE2 from 're2';
+/**
+ * Compila el patrón con RE2, o devuelve `null` si no se puede.
+ *
+ * `null` cubre las dos formas de no poder, que desde fuera se tratan igual:
+ * el patrón está mal escrito, o usa algo que RE2 no implementa.
+ */
+export declare function compilarRegexDeInquilino(patron: string, donde: string, 
+/** Los mismos de `RegExp`. El filtro de RSS usa `i`. */
+flags?: string): RE2 | null;
+/**
+ * `patron.test(cadena)` con el motor seguro. `false` cuando el patrón no
+ * compila, que es lo que estos dos sitios ya devolvían.
+ */
+export declare function casaRegexDeInquilino(patron: string, cadena: unknown, donde: string): boolean;

package/dist/regex-de-inquilino.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compilarRegexDeInquilino = compilarRegexDeInquilino;
+exports.casaRegexDeInquilino = casaRegexDeInquilino;
+const common_1 = require("@nestjs/common");
+const re2_1 = __importDefault(require("re2"));
+/**
+ * Las expresiones regulares que escribe un inquilino corren en RE2, no en el
+ * motor de JavaScript.
+ *
+ * ## El fallo
+ *
+ * Había dos sitios donde un patrón del inquilino se compilaba y se corría
+ * contra cadenas del payload, en el hilo de la petición:
+ *
+ *   - `filter-utils.ts`, operador `matches_regex`;
+ *   - `schema-validator-utils.ts`, la restricción `pattern`.
+ *
+ * El motor de JavaScript resuelve por retroceso, así que un patrón como
+ * `(a+)+$` contra una cadena de treinta letras tarda más que la vida útil del
+ * servidor. Y no hace falta ser el dueño del patrón para dispararlo: la cadena
+ * contra la que se prueba viene del payload, y el payload entra por
+ * `/api/in/:token`, que es público. Un solo evento deja un worker girando.
+ *
+ * Un `setTimeout` no lo corta: una expresión regular de JavaScript es
+ * síncrona, no cede el hilo, y no hay forma de interrumpirla desde dentro del
+ * proceso. Por eso el arreglo no puede ser «ponerle un límite de tiempo».
+ *
+ * ## Por qué RE2
+ *
+ * RE2 no retrocede: recorre el autómata en tiempo lineal sobre la longitud de
+ * la cadena, pase lo que pase con el patrón. No es un límite ni una heurística
+ * — es que la clase de fallo no existe en ese motor.
+ *
+ * ## Lo que RE2 NO acepta, que es el precio
+ *
+ * Precisamente porque no retrocede, RE2 no implementa lo que sólo se puede
+ * resolver retrocediendo: las referencias hacia atrás (`\1`) y las miradas
+ * adelante/atrás (`(?=…)`, `(?!…)`, `(?<=…)`). Un patrón que las use deja de
+ * compilar.
+ *
+ * Eso es un cambio de comportamiento y no se esconde: `compilar` devuelve
+ * `null` y deja que cada sitio decida cómo contarlo — el validador de esquema
+ * ya tenía un mensaje para «patrón inválido» y lo reutiliza; el filtro no
+ * casa, como ya hacía con cualquier patrón que no compilara, pero además lo
+ * registra, porque «este filtro dejó de casar en silencio» es un mal día para
+ * quien lo escribió.
+ *
+ * ## Sin caché, a propósito
+ *
+ * Tentaba guardar los compilados en un Map. La clave sería el patrón, y el
+ * patrón lo elige el inquilino: eso es exactamente un Map sin tope con clave
+ * que controla otro, que es otro de los hallazgos de este mismo informe. Los
+ * dos sitios ya compilaban en cada llamada antes de esto, así que no se pierde
+ * nada.
+ */
+const logger = new common_1.Logger('RegexDeInquilino');
+/** Máximo del patrón. Uno más largo que esto no es un filtro, es otra cosa. */
+const MAX_PATRON = 1_000;
+/**
+ * Compila el patrón con RE2, o devuelve `null` si no se puede.
+ *
+ * `null` cubre las dos formas de no poder, que desde fuera se tratan igual:
+ * el patrón está mal escrito, o usa algo que RE2 no implementa.
+ */
+function compilarRegexDeInquilino(patron, donde, 
+/** Los mismos de `RegExp`. El filtro de RSS usa `i`. */
+flags) {
+    if (typeof patron !== 'string' || patron.length === 0)
+        return null;
+    if (patron.length > MAX_PATRON) {
+        logger.warn(`[${donde}] patrón de ${patron.length} caracteres ignorado (máximo ${MAX_PATRON})`);
+        return null;
+    }
+    try {
+        return flags ? new re2_1.default(patron, flags) : new re2_1.default(patron);
+    }
+    catch (err) {
+        /* Se registra en vez de tragárselo porque el motivo casi siempre es
+           «RE2 no soporta esto», y sin la línea el patrón simplemente deja de
+           casar y nadie sabe por qué. */
+        logger.warn(`[${donde}] patrón rechazado: ${patron.slice(0, 120)} — ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * `patron.test(cadena)` con el motor seguro. `false` cuando el patrón no
+ * compila, que es lo que estos dos sitios ya devolvían.
+ */
+function casaRegexDeInquilino(patron, cadena, donde) {
+    if (typeof cadena !== 'string')
+        return false;
+    const re = compilarRegexDeInquilino(patron, donde);
+    return re ? re.test(cadena) : false;
+}

package/dist/request-context.d.ts

@@ -0,0 +1,18 @@
+import type { Request } from 'express';
+import type { IdentidadDePeticion as UserDocument } from './contratos';
+export declare function getUser(req: Request): UserDocument;
+export declare function getUserId(req: Request): string;
+export declare function getOrganizationId(req: Request): string;
+/**
+ * ¿Tiene quien llama este permiso?
+ *
+ * Una sesión del panel actúa por la cuenta entera, así que los tiene todos —
+ * es la misma distinción que lee `ScopesGuard`, y la que marca la estrategia
+ * de API key con `__isApiKey`. Una llave sólo tiene lo que se le acuñó.
+ *
+ * Existe porque un `@RequiredScopes(...)` en la ruta es todo o nada, y hay
+ * respuestas donde un CAMPO concreto vale más que el resto: el token de
+ * ingress de un webhook deja publicar eventos en él, así que no puede viajar
+ * en una respuesta que sólo pide permiso de lectura de eventos.
+ */
+export declare function tienePermiso(req: Request, scope: string): boolean;

package/dist/request-context.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUser = getUser;
+exports.getUserId = getUserId;
+exports.getOrganizationId = getOrganizationId;
+exports.tienePermiso = tienePermiso;
+function getUser(req) {
+    return req.user;
+}
+function getUserId(req) {
+    return getUser(req)._id.toString();
+}
+function getOrganizationId(req) {
+    const user = getUser(req);
+    return (user.organizationId ?? user._id).toString();
+}
+/**
+ * ¿Tiene quien llama este permiso?
+ *
+ * Una sesión del panel actúa por la cuenta entera, así que los tiene todos —
+ * es la misma distinción que lee `ScopesGuard`, y la que marca la estrategia
+ * de API key con `__isApiKey`. Una llave sólo tiene lo que se le acuñó.
+ *
+ * Existe porque un `@RequiredScopes(...)` en la ruta es todo o nada, y hay
+ * respuestas donde un CAMPO concreto vale más que el resto: el token de
+ * ingress de un webhook deja publicar eventos en él, así que no puede viajar
+ * en una respuesta que sólo pide permiso de lectura de eventos.
+ */
+function tienePermiso(req, scope) {
+    const user = getUser(req);
+    if (!user?.__isApiKey)
+        return true;
+    return (user.__apiKeyScopes ?? []).includes(scope);
+}

package/dist/retry-transient.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Retry helper for pipeline nodes that make external HTTP requests.
+ * Retries on transient status codes (429, 502, 503, 504), waiting as long as
+ * the server asked when it said (`NodeResult.retryAfterMs`) and falling back
+ * to linear backoff when it didn't, plus jitter either way.
+ * Fire-and-forget safe — no state, no side effects.
+ *
+ * IMPORTANT: 500 is NOT retryable by default — a 500 from our own
+ * catch block (import error, parse failure, etc.) is NOT transient.
+ * Only external gateway errors (502/503/504) and rate limits (429) are.
+ *
+ * If fn() throws an exception (instead of returning a result),
+ * the error is caught and returned as statusCode 520 (internal error)
+ * WITHOUT retrying — thrown errors are bugs, not transient failures.
+ */
+export interface NodeResult {
+    statusCode: number;
+    responseBody: string;
+    latencyMs: number;
+    /** Set to true when retryOnTransientError retried at least once */
+    _retriedTransient?: boolean;
+    /**
+     * How long the *server* said to wait before trying again, in ms — Discord's
+     * `retry_after`, a `Retry-After` header, anything of that shape. When set it
+     * replaces the computed backoff, because a guess that lands before the
+     * window reopens just burns an attempt. Control-plane only: it rides
+     * alongside the result like `_retriedTransient` and never reaches the
+     * downstream payload, which is built from `responseBody`.
+     */
+    retryAfterMs?: number;
+}
+export interface RetryOptions {
+    /** Max retries after first attempt (default 2 → 3 total attempts) */
+    maxRetries?: number;
+    /** Status codes to retry on (default: 429, 502, 503, 504) */
+    retryableStatuses?: Set<number>;
+    /** Base backoff delay in ms, multiplied by attempt (default 3000) */
+    backoffMs?: number;
+    /**
+     * Ceiling for a single wait, in ms (default 15000). Applies to a
+     * server-stated `retryAfterMs` too: a node that blocks for the four minutes
+     * a global rate limit can ask for is worse than a node that gives up.
+     */
+    maxBackoffMs?: number;
+    /** Logger for retry warnings */
+    logger?: {
+        warn: (msg: string) => void;
+        log: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+    /** Label for log messages (e.g. 'Firecrawl "Get Udemy"') */
+    label?: string;
+}
+export declare function retryOnTransientError(fn: () => Promise<NodeResult>, opts?: RetryOptions): Promise<NodeResult>;