@hostwebhook/node-sdk 0.1.0

package/dist/retry-transient.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryOnTransientError = retryOnTransientError;
+const DEFAULT_RETRYABLE = new Set([429, 502, 503, 504]);
+async function retryOnTransientError(fn, opts) {
+    const maxRetries = opts?.maxRetries ?? 2;
+    const retryable = opts?.retryableStatuses ?? DEFAULT_RETRYABLE;
+    const backoffMs = opts?.backoffMs ?? 3000;
+    const label = opts?.label ?? 'Node';
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        let result;
+        try {
+            result = await fn();
+        }
+        catch (err) {
+            // Thrown errors are internal bugs — never retry
+            const msg = err instanceof Error ? err.message : String(err);
+            opts?.logger?.error?.(`${label} threw an exception (not retrying): ${msg}`);
+            return {
+                statusCode: 520,
+                responseBody: JSON.stringify({ error: msg, _internalError: true }),
+                latencyMs: 0,
+            };
+        }
+        if (!retryable.has(result.statusCode) || attempt === maxRetries) {
+            if (attempt > 0 && result.statusCode < 400) {
+                opts?.logger?.log?.(`${label} succeeded on retry ${attempt}`);
+            }
+            // Mark that retries were attempted (for loop error policy decisions)
+            if (attempt > 0)
+                return { ...result, _retriedTransient: true };
+            return result;
+        }
+        // Prefer the server's own number over our linear guess, then spread the
+        // wake-ups. Without the spread this makes bursts worse, not better: a
+        // fan-out of N items hits the same rate limit at the same instant, reads
+        // the same `retry_after`, and every one of them wakes at that same instant
+        // to collide again. The jitter is what turns a wall into a queue.
+        const stated = result.retryAfterMs;
+        const base = stated && stated > 0 ? stated : backoffMs * (attempt + 1);
+        const capped = Math.min(base, opts?.maxBackoffMs ?? 15_000);
+        const wait = capped + Math.round(Math.random() * Math.max(250, capped * 0.25));
+        opts?.logger?.warn?.(`${label} got ${result.statusCode}, retrying in ${wait}ms ` +
+            `(${attempt + 1}/${maxRetries})${stated ? ' — server asked' : ''}...`);
+        await new Promise((r) => setTimeout(r, wait));
+    }
+    return {
+        statusCode: 500,
+        responseBody: '{"error":"Max retries exceeded"}',
+        latencyMs: 0,
+    };
+}

package/dist/retry-utils.d.ts

@@ -0,0 +1,17 @@
+export interface RetryOptions {
+    /** Max number of attempts (default 3) */
+    maxAttempts?: number;
+    /** Initial delay in ms before first retry (default 1000) */
+    initialDelayMs?: number;
+    /** Max delay cap in ms (default 60000) */
+    maxDelayMs?: number;
+}
+/**
+ * Retry a function that returns { statusCode } on 429 (rate limit) or 5xx errors.
+ * Uses exponential backoff with 20% jitter.
+ *
+ * Does NOT use try/catch — our executors return statusCode, they don't throw.
+ */
+export declare function retryOnRateLimit<T extends {
+    statusCode: number;
+}>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;

package/dist/retry-utils.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryOnRateLimit = retryOnRateLimit;
+/**
+ * Retry a function that returns { statusCode } on 429 (rate limit) or 5xx errors.
+ * Uses exponential backoff with 20% jitter.
+ *
+ * Does NOT use try/catch — our executors return statusCode, they don't throw.
+ */
+async function retryOnRateLimit(fn, opts) {
+    const { maxAttempts = 5, initialDelayMs = 2000, maxDelayMs = 60000, } = opts ?? {};
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const result = await fn();
+        const shouldRetry = result.statusCode === 429 || result.statusCode >= 500;
+        if (!shouldRetry || attempt === maxAttempts - 1)
+            return result;
+        const delay = Math.min(initialDelayMs * Math.pow(2, attempt), maxDelayMs);
+        const jitter = Math.random() * 0.2 * delay;
+        await new Promise((r) => setTimeout(r, delay + jitter));
+    }
+    // Unreachable — loop always returns on last attempt
+    throw new Error('retryOnRateLimit: unexpected exit');
+}

package/dist/schema-validator-utils.d.ts

@@ -0,0 +1,9 @@
+import type { SchemaField } from './contratos';
+export interface SchemaValidationResult {
+    valid: boolean;
+    errors: {
+        path: string;
+        message: string;
+    }[];
+}
+export declare function validateSchema(fields: SchemaField[], payload: unknown, strictMode: boolean): SchemaValidationResult;

package/dist/schema-validator-utils.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSchema = validateSchema;
+const regex_de_inquilino_1 = require("./regex-de-inquilino");
+function getNestedValue(obj, path) {
+    // Split by . but also handle [N] bracket notation: "documents[0].size" → ["documents", "0", "size"]
+    const segments = path
+        .split(/\.|\[(\d+)\]/)
+        .filter((s) => s !== '' && s !== undefined);
+    return segments.reduce((curr, key) => {
+        if (curr === null || curr === undefined)
+            return undefined;
+        if (Array.isArray(curr) && /^\d+$/.test(key))
+            return curr[Number(key)];
+        if (typeof curr === 'object')
+            return curr[key];
+        return undefined;
+    }, obj);
+}
+function checkType(value, type) {
+    if (type === 'any')
+        return true;
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number' && !isNaN(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'array':
+            return Array.isArray(value);
+        case 'object':
+            return (value !== null && typeof value === 'object' && !Array.isArray(value));
+        default:
+            return true;
+    }
+}
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const URL_RE = /^https?:\/\/.+/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+function checkFormat(value, format) {
+    switch (format) {
+        case 'email':
+            return EMAIL_RE.test(value);
+        case 'url':
+            return URL_RE.test(value);
+        case 'uuid':
+            return UUID_RE.test(value);
+        case 'iso-date':
+            return ISO_DATE_RE.test(value);
+        default:
+            return true;
+    }
+}
+function checkConstraints(value, type, c) {
+    if (type === 'string' && typeof value === 'string') {
+        if (c.minLength !== undefined && value.length < c.minLength)
+            return `must be at least ${c.minLength} characters`;
+        if (c.maxLength !== undefined && value.length > c.maxLength)
+            return `must be at most ${c.maxLength} characters`;
+        if (c.pattern) {
+            /* Mismo motivo que en `filter-utils`: el patron es del inquilino y el
+               valor viene del payload publico. Ver `regex-de-inquilino.ts`. */
+            const re = (0, regex_de_inquilino_1.compilarRegexDeInquilino)(c.pattern, 'schema.pattern');
+            if (!re)
+                return `invalid regex pattern: ${c.pattern}`;
+            if (!re.test(value))
+                return `must match pattern /${c.pattern}/`;
+        }
+        if (c.format && !checkFormat(value, c.format))
+            return `must be a valid ${c.format}`;
+        if (c.enum && c.enum.length > 0 && !c.enum.includes(value))
+            return `must be one of: ${c.enum.join(', ')}`;
+    }
+    if (type === 'number' && typeof value === 'number') {
+        if (c.min !== undefined && value < c.min)
+            return `must be >= ${c.min}`;
+        if (c.max !== undefined && value > c.max)
+            return `must be <= ${c.max}`;
+        if (c.enum && c.enum.length > 0 && !c.enum.includes(String(value)))
+            return `must be one of: ${c.enum.join(', ')}`;
+    }
+    if (type === 'array' && Array.isArray(value)) {
+        if (c.minItems !== undefined && value.length < c.minItems)
+            return `must have at least ${c.minItems} items`;
+        if (c.maxItems !== undefined && value.length > c.maxItems)
+            return `must have at most ${c.maxItems} items`;
+    }
+    return null;
+}
+function validateSchema(fields, payload, strictMode) {
+    const errors = [];
+    if (!fields || fields.length === 0)
+        return { valid: true, errors: [] };
+    for (const field of fields) {
+        // Normalize path: strip {{payload.xxx}} or {{xxx}} template syntax → xxx
+        let path = field.path;
+        const tplMatch = path.match(/^\{\{\s*(?:payload\.)?(.+?)\s*\}\}$/);
+        if (tplMatch)
+            path = tplMatch[1];
+        const value = getNestedValue(payload, path);
+        // Check required
+        if (field.required && (value === undefined || value === null)) {
+            errors.push({ path, message: 'is required' });
+            continue;
+        }
+        // Skip further checks if value is missing and not required
+        if (value === undefined || value === null)
+            continue;
+        // Check type
+        if (field.type !== 'any' && !checkType(value, field.type)) {
+            errors.push({
+                path,
+                message: `expected ${field.type}, got ${Array.isArray(value) ? 'array' : typeof value}`,
+            });
+            continue;
+        }
+        // Check constraints
+        if (field.constraints) {
+            const constraintError = checkConstraints(value, field.type, field.constraints);
+            if (constraintError) {
+                errors.push({ path, message: constraintError });
+            }
+        }
+    }
+    // Strict mode: reject unknown top-level keys
+    if (strictMode &&
+        payload &&
+        typeof payload === 'object' &&
+        !Array.isArray(payload)) {
+        const definedPaths = new Set(fields.map((f) => f.path.split('.')[0]));
+        for (const key of Object.keys(payload)) {
+            if (!definedPaths.has(key)) {
+                errors.push({ path: key, message: 'unknown field (strict mode)' });
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/ssrf-guard.d.ts

@@ -0,0 +1,202 @@
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { Agent } from 'undici';
+/**
+ * Throw if the URI's host(s) point at private / loopback / link-local
+ * addresses, OR if their DNS resolves there. mongodb+srv URIs are
+ * handled via SRV record lookup (the `<host>.mongodb.net` pattern
+ * Atlas uses doesn't have A/AAAA records — only the SRV at
+ * `_mongodb._tcp.<host>` does).
+ */
+export declare function assertSafeMongoUri(uri: string): Promise<void>;
+/** Mask the credentials portion of a Mongo URI for logs / UI. */
+export declare function maskMongoUri(uri: string): string;
+/**
+ * Tunnel-aware variant: when `tunnelId` is set, the connection is going to
+ * route through a customer-installed agent (`hostwh expose-tcp`), so the
+ * URI's host is the customer's local network — `localhost` / `127.0.0.1` /
+ * `192.168.x.x` are all expected and safe (they're THEIR localhost, not
+ * ours). Skip the SSRF check entirely.
+ *
+ * Without a tunnel, behave exactly like assertSafeMongoUri.
+ */
+export declare function assertSafeMongoUriUnlessTunneled(uri: string, tunnelId: string | null | undefined): Promise<void>;
+/**
+ * Throw if the postgres URI's host points at private / loopback /
+ * link-local addresses, OR if its DNS resolves there. Mirrors
+ * assertSafeMongoUri but with the simpler postgres URI grammar.
+ */
+export declare function assertSafePostgresUri(uri: string): Promise<void>;
+/**
+ * Tunnel-aware variant for postgres — same semantics as the mongo one.
+ * When tunnelId is set, the URI describes the customer's own network
+ * reachable through their `hostwh expose --tcp` agent, so private IPs
+ * are intentional and we skip the SSRF check.
+ */
+export declare function assertSafePostgresUriUnlessTunneled(uri: string, tunnelId: string | null | undefined): Promise<void>;
+/**
+ * Which URI grammar each credential type's connection string uses, and so
+ * which guard applies to it.
+ *
+ * This exists because the mapping used to be inferred from the type slug by
+ * string transform, which silently produced nonsense for a snake_case type:
+ * `memory_mongodb` implied a helper named `assertSafeMemory_mongodbUri` that
+ * nobody would ever write, so the invariant test failed for a naming reason
+ * and the genuine gap behind it — memory_mongodb never being SSRF-checked at
+ * create time — sat unnoticed underneath the red test.
+ *
+ * Every credential type flagged `ssrfValidated` or `tunnelable` in
+ * CREDENTIAL_TYPES must appear here. `architecture.spec.ts` enforces that, so
+ * a new connection-string credential type cannot ship without someone
+ * deciding how its URI gets validated.
+ */
+export type UriGuardFamily = 'mongo' | 'postgres';
+export declare const URI_GUARD_FAMILY: Readonly<Record<string, UriGuardFamily>>;
+/** True when this credential type carries a connection string we must guard. */
+export declare function isGuardedUriCredential(type: string): boolean;
+/**
+ * Los esquemas que puede llevar la URI de cada familia.
+ *
+ * Va aquí, junto a `URI_GUARD_FAMILY`, y no en un `if` suelto dentro del
+ * servicio: el tipo `Record<UriGuardFamily, …>` obliga a que una familia
+ * nueva declare los suyos o no compila, que es la misma disciplina que ya
+ * aplica el registro de guardias.
+ */
+export declare const URI_SCHEMES: Readonly<Record<UriGuardFamily, readonly string[]>>;
+/**
+ * Que la cadena de conexión sea del producto que dice el tipo de credencial.
+ *
+ * Faltaba, y no se notaba porque los dos sitios que miraban la URI se
+ * rinden antes en el caso más común:
+ *
+ *  - el guardia SSRF vuelve en cuanto la credencial lleva `tunnelId`, porque
+ *    entonces la URI describe la red del propio cliente;
+ *  - la comprobación de la base de Mongo vuelve si no se tecleó ninguna.
+ *
+ * Con las dos condiciones a la vez —una credencial con túnel y sin base, que
+ * es justo lo que sale del flujo de túneles— NADIE llegaba a mirar la cadena.
+ * Una `postgres://` se guardaba como MongoDB sin una palabra, y el error
+ * aparecía mucho después dentro de un nodo, en boca del driver:
+ * «Connection string is not a valid mongodb:// URI», que no nombra lo único
+ * que hacía falta saber: que eso era de Postgres.
+ *
+ * Por eso esto NO mira el túnel ni la base: corre siempre.
+ */
+export declare function assertUriSchemeMatchesType(type: string, uri: string): void;
+/** Apply the right guard for a credential type. No-op for unguarded types. */
+export declare function assertSafeCredentialUri(type: string, uri: string): Promise<void>;
+/** As above, but a tunnelled credential describes the customer's own network. */
+export declare function assertSafeCredentialUriUnlessTunneled(type: string, uri: string, tunnelId: string | null | undefined): Promise<void>;
+/** Mask the password portion of a postgres URI for logs / UI. */
+export declare function maskPostgresUri(uri: string): string;
+/**
+ * Parse the first host:port pair out of a `mongodb://` or
+ * `mongodb+srv://` URI. Used by the TCP forwarder + URI rewriter to
+ * know what target to register and what host:port to substitute with
+ * the local forwarder address.
+ *
+ * Returns the bare host (no port) plus the explicit port — defaulting
+ * to 27017 for `mongodb://` and to a synthetic 27017 for `mongodb+srv://`
+ * (SRV resolution is bypassed entirely when tunnelled, the agent talks
+ * to its target directly).
+ */
+export declare function parseFirstMongoHost(uri: string): {
+    host: string;
+    port: number;
+};
+/**
+ * Replace the host(s) section of a Mongo URI with a single host:port.
+ * Preserves user:pass, path (database), and querystring. Forces the
+ * scheme to `mongodb://` (drops `+srv`) because the rewritten URI
+ * points at our local forwarder, not an SRV-resolvable hostname.
+ *
+ * Also drops the `tls`, `ssl`, and `replicaSet` query params — they
+ * would cause the driver to negotiate TLS with our local plaintext
+ * forwarder. The agent talks to its real Atlas with TLS on its end.
+ */
+export declare function rewriteMongoUriHost(uri: string, host: string, port: number): string;
+/**
+ * Parse the first host:port pair out of a `postgres://` /
+ * `postgresql://` URI. Same role as `parseFirstMongoHost` — the TCP
+ * forwarder needs to know what host:port to register against the
+ * tunnel, and the URI rewriter needs to know what to swap out.
+ *
+ * Postgres URIs only ever name one host (no comma list, no `+srv`
+ * sibling), but we still parse the userinfo correctly so passwords
+ * containing `@` (URL-encoded as `%40`) don't get treated as host
+ * delimiters.
+ */
+export declare function parseFirstPostgresHost(uri: string): {
+    host: string;
+    port: number;
+};
+/**
+ * Replace the host:port of a Postgres URI with the local forwarder
+ * address. Same idea as `rewriteMongoUriHost`: the local forwarder is
+ * plaintext (the agent restores TLS on its end of the wire), so any
+ * SSL-related query params would cause the driver to negotiate TLS
+ * against the wrong webhook and fail. Drop them.
+ *
+ * Preserves userinfo + path (the database name lives in the path) +
+ * remaining querystring. Also forces scheme to `postgres://` (drops
+ * `postgresql://` to one canonical form).
+ */
+/**
+ * Qué base declara una URI de Postgres en su ruta, o `null` si no declara
+ * ninguna —en ese caso el driver cae a la base con el nombre del usuario—.
+ *
+ * Se decodifica porque `rewritePostgresUriDatabase` codifica al escribir: sin
+ * esto, comparar «lo que había» con «lo que se pide» diría que `mi base` y
+ * `mi%20base` son distintas y registraría un cambio que no existe.
+ */
+export declare function baseDeLaUri(uri: string): string | null;
+/**
+ * Cambiar la base de datos de una URI de Postgres — la que va en la ruta.
+ *
+ * En Mongo la base se elige con `client.db(nombre)` sobre una conexión ya
+ * abierta. En Postgres **no existe eso**: la base se decide al conectarse y
+ * viene en la URI, así que respetar el `databaseName` de un nodo obliga a
+ * reescribirla aquí. Ésa es la razón de que `databaseName` estuviera muerto en
+ * `postgres-actions.service.ts` — se calculaba y no se podía aplicar sin esto.
+ *
+ * Se conserva el esquema tal cual llegó (`postgres://` o `postgresql://`), el
+ * userinfo, el host y el querystring; sólo cambia la ruta. El nombre se
+ * codifica porque una base puede llevar caracteres que en una URI significan
+ * otra cosa, y sin codificar `mi base` o `a/b` producirían una URI distinta de
+ * la que se pidió.
+ *
+ * Con `database` vacío devuelve la URI intacta: quien llama decide si hay algo
+ * que aplicar.
+ */
+export declare function rewritePostgresUriDatabase(uri: string, database: string): string;
+export declare function rewritePostgresUriHost(uri: string, host: string, port: number): string;
+/** Igual que `isPrivateIp`, expuesto para quien tenga ya la IP resuelta. */
+export declare function isPrivateAddress(ip: string): boolean;
+/**
+ * Rechaza una URL de entrega que apunte adentro.
+ *
+ * Comprueba esquema, nombres bloqueados, IP literal y —cuando es un nombre— lo
+ * que resuelve AHORA. Esa resolución es la foto previa; lo que de verdad ata la
+ * dirección comprobada a la dirección marcada es el hook de `agentesDeEntrega`,
+ * porque entre esta consulta y el socket cabe un cambio de DNS.
+ */
+export declare function assertSafeHttpUrl(rawUrl: string): Promise<void>;
+/** Los agentes de salida de la entrega. Se crean una vez: llevan pool de
+ *  conexiones y uno por petición lo tiraría.
+ *
+ *  Llevan las DOS capas: el `lookup` para los nombres y el conector para todo
+ *  lo demás. Ninguna sobra — ver `conConectorQueRechazaPrivadas`. */
+export declare function agentesDeEntrega(): {
+    httpAgent: http.Agent;
+    httpsAgent: https.Agent;
+};
+export declare function despachadorDeSalida(): Agent;
+/**
+ * `fetch` con el guardia puesto: comprueba la URL antes de salir y resuelve
+ * por el despachador que rechaza direcciones privadas, así que un DNS que
+ * cambie entre la comprobación y el socket tampoco entra.
+ *
+ * Es el reemplazo de una palabra para cualquier `fetch` que salga a una URL
+ * que haya elegido un inquilino.
+ */
+export declare function fetchSeguro(url: string, init?: RequestInit): Promise<Response>;