@revenexx/integrations-node-sdk 0.17.0 → 0.18.0

package/README.md

@@ -33,6 +33,8 @@ configuration or auth token needed.
 | `localized` | `normalizeLocalized` — reduce a `LocalizedString` (`string \| Record<string, string>`) to a single plain string. |
 | `credentialType` | `normalizeCredentialType` — normalise a credential-type reference (`string \| string[] \| undefined`) to `string[]`. |
 | `errors` | `NodeError` — typed error class for unexpected/system-level failures thrown inside `execute`. |
+| `fetch` | `safeFetch` and the `read*` body helpers — timeout, retry, response size-cap, unified error form, and an always-on **SSRF guard** (blocks private/loopback/link-local/metadata targets, re-checked on every redirect hop). Prefer it over raw `fetch`. See [`docs/overview.md`](docs/overview.md#safefetch). |
+| `ssrf` | `assertPublicUrl` / `isBlockedAddress` — the SSRF guard that backs `safeFetch`, exported for reuse. Best-effort (a DNS-rebinding TOCTOU gap remains); errors surface as `NodeError('BLOCKED_ADDRESS')`. Set `RVNXX_SSRF_ALLOW_PRIVATE=1` (off by default; local dev only) to reach `localhost`/internal targets while testing — see [`docs/overview.md`](docs/overview.md#ssrf-guard). |
 | `extract` | `extractManifest` / `extractManifests` (nodes) and `extractCredentialManifest` / `extractCredentialManifests` (credentials) — pull descriptions off instances without executing them. |
 | `manifest` | `buildManifest` / `MANIFEST_VERSION` — wrap node, credential and template descriptions in the `{ manifestVersion, nodes, credentials, templates }` envelope the registry expects. |
 
@@ -213,6 +215,11 @@ export class HttpRequestNode implements INode {
 }
 ```
 
+> The example calls `fetch` directly to stay focused on the error contract. In
+> real nodes use [`safeFetch`](docs/overview.md#safefetch) instead — it adds the
+> timeout, retry, size-cap and the SSRF guard (private/loopback/metadata targets
+> are rejected with `NodeError('BLOCKED_ADDRESS')`, re-checked on every redirect).
+
 **Error contract:** `throw NodeError(code, message, meta?)` for unexpected,
 system-level failures; `return { outputs, branch: '<error-port>' }` for
 expected, routable errors (a declared `kind: 'error'` port). Never mix both for

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -29,6 +39,7 @@ __export(index_exports, {
   DEFAULT_RETRY_POLICY: () => DEFAULT_RETRY_POLICY,
   DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
   MANIFEST_VERSION: () => MANIFEST_VERSION,
+  MAX_REDIRECTS: () => MAX_REDIRECTS,
   MAX_RESPONSE_BYTES: () => MAX_RESPONSE_BYTES,
   MAX_RETRY_ATTEMPTS: () => MAX_RETRY_ATTEMPTS,
   MAX_TIMEOUT_MS: () => MAX_TIMEOUT_MS,
@@ -37,6 +48,7 @@ __export(index_exports, {
   OAuth2ClientCredentialsCredential: () => OAuth2ClientCredentialsCredential,
   RetryableError: () => RetryableError,
   SimpleValueCredential: () => SimpleValueCredential,
+  assertPublicUrl: () => assertPublicUrl,
   backoffDelay: () => backoffDelay,
   buildManifest: () => buildManifest,
   clampResponseBytes: () => clampResponseBytes,
@@ -44,6 +56,7 @@ __export(index_exports, {
   extractCredentialManifests: () => extractCredentialManifests,
   extractManifest: () => extractManifest,
   extractManifests: () => extractManifests,
+  isBlockedAddress: () => isBlockedAddress,
   isNodeWithIteration: () => isNodeWithIteration,
   isOAuthAuthorizeCredential: () => isOAuthAuthorizeCredential,
   maxBytesConfigField: () => maxBytesConfigField,
@@ -129,9 +142,149 @@ function extractCredentialManifests(credentials) {
   return credentials.map(extractCredentialManifest);
 }
 
+// src/ssrf.ts
+var import_node_net = require("net");
+var ssrfResolver = {
+  lookup: async (hostname) => {
+    const { lookup } = await import("dns/promises");
+    const results = await lookup(hostname, { all: true });
+    return results.map((r) => ({ address: r.address, family: r.family }));
+  }
+};
+function parseIpv4(input) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(input);
+  if (!m) return null;
+  const octets = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+  if (octets.some((n) => n > 255)) return null;
+  return octets;
+}
+function expandIpv6(input) {
+  let s = input;
+  const zone = s.indexOf("%");
+  if (zone !== -1) s = s.slice(0, zone);
+  if (s.includes(".")) {
+    const idx = s.lastIndexOf(":");
+    if (idx === -1) return null;
+    const v4 = parseIpv4(s.slice(idx + 1));
+    if (!v4) return null;
+    const hi = (v4[0] << 8 | v4[1]).toString(16);
+    const lo = (v4[2] << 8 | v4[3]).toString(16);
+    s = `${s.slice(0, idx + 1)}${hi}:${lo}`;
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null;
+  const parseGroups = (part) => part === "" ? [] : part.split(":").map((h) => /^[0-9a-fA-F]{1,4}$/.test(h) ? parseInt(h, 16) : Number.NaN);
+  const head = parseGroups(halves[0] ?? "");
+  const back = halves.length === 2 ? parseGroups(halves[1] ?? "") : null;
+  const declared = [...head, ...back ?? []];
+  if (declared.some((h) => !Number.isInteger(h) || h < 0 || h > 65535)) return null;
+  let hextets;
+  if (back === null) {
+    hextets = head;
+  } else {
+    const zeros = 8 - (head.length + back.length);
+    if (zeros < 1) return null;
+    hextets = [...head, ...new Array(zeros).fill(0), ...back];
+  }
+  return hextets.length === 8 ? hextets : null;
+}
+function isBlockedIpv4(o) {
+  const [a, b] = o;
+  return a === 0 || // 0.0.0.0/8 "this network" (incl. 0.0.0.0)
+  a === 127 || // 127.0.0.0/8 loopback
+  a === 10 || // 10.0.0.0/8 private
+  a === 172 && b >= 16 && b <= 31 || // 172.16.0.0/12 private
+  a === 192 && b === 168 || // 192.168.0.0/16 private
+  a === 169 && b === 254;
+}
+function isBlockedAddress(ip) {
+  const v4 = parseIpv4(ip);
+  if (v4) return isBlockedIpv4(v4);
+  const h = expandIpv6(ip);
+  if (!h) return true;
+  if (h.every((x) => x === 0)) return true;
+  if (h.slice(0, 7).every((x) => x === 0) && h[7] === 1) return true;
+  const embedsV4 = h[0] === 0 && h[1] === 0 && h[2] === 0 && h[3] === 0 && h[4] === 0 && (h[5] === 65535 || h[5] === 0);
+  if (embedsV4) {
+    return isBlockedIpv4([h[6] >> 8, h[6] & 255, h[7] >> 8, h[7] & 255]);
+  }
+  if ((h[0] & 65024) === 64512) return true;
+  if ((h[0] & 65472) === 65152) return true;
+  return false;
+}
+var bypassNoticeLogged = false;
+function guardRelaxedForLocalDev() {
+  const raw = process.env["RVNXX_SSRF_ALLOW_PRIVATE"];
+  const relaxed = raw != null && ["1", "true", "yes"].includes(raw.trim().toLowerCase());
+  if (relaxed && !bypassNoticeLogged) {
+    bypassNoticeLogged = true;
+    console.warn(
+      "[ssrf] RVNXX_SSRF_ALLOW_PRIVATE is set: allowing private/loopback fetch targets. Intended for local development only."
+    );
+  }
+  return relaxed;
+}
+function blockedError(host, address) {
+  if (host === address) {
+    return new NodeError("BLOCKED_ADDRESS", `Blocked request to private or reserved address ${address}`, {
+      status: 0
+    });
+  }
+  console.warn(`[ssrf] blocked request to ${host}: resolves to private/reserved address ${address}`);
+  return new NodeError("BLOCKED_ADDRESS", `Blocked request to ${host}: resolves to a private or reserved address`, {
+    status: 0
+  });
+}
+async function resolveHost(lookup, host, signal) {
+  if (!signal) return lookup(host);
+  if (signal.aborted) throw signal.reason;
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    lookup(host).then(
+      (addresses) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(addresses);
+      },
+      (err) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(err);
+      }
+    );
+  });
+}
+async function assertPublicUrl(url, opts = {}) {
+  const u = url instanceof URL ? url : new URL(url);
+  if (u.protocol !== "http:" && u.protocol !== "https:") {
+    throw new NodeError("BLOCKED_ADDRESS", `Blocked non-HTTP(S) URL protocol: ${u.protocol}`, { status: 0 });
+  }
+  const rawHost = u.hostname;
+  const host = rawHost.startsWith("[") && rawHost.endsWith("]") ? rawHost.slice(1, -1) : rawHost;
+  if (!host) throw new NodeError("BLOCKED_ADDRESS", "Blocked URL with empty host", { status: 0 });
+  if (guardRelaxedForLocalDev()) return;
+  const lower = host.toLowerCase();
+  if (lower === "localhost" || lower.endsWith(".localhost")) {
+    throw new NodeError("BLOCKED_ADDRESS", `Blocked loopback host: ${host}`, { status: 0 });
+  }
+  if ((0, import_node_net.isIP)(host) !== 0) {
+    if (isBlockedAddress(host)) throw blockedError(host, host);
+    return;
+  }
+  const lookup = opts.lookup ?? ssrfResolver.lookup;
+  const addresses = await resolveHost(lookup, host, opts.signal);
+  if (!addresses || addresses.length === 0) {
+    throw new NodeError("BLOCKED_ADDRESS", `Could not resolve host: ${host}`, { status: 0 });
+  }
+  for (const a of addresses) {
+    if (isBlockedAddress(a.address)) throw blockedError(host, a.address);
+  }
+}
+
 // src/fetch.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var MAX_TIMEOUT_MS = 12e4;
+var MAX_REDIRECTS = 5;
+var REDIRECT_STATUSES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
 var DEFAULT_RETRY_ATTEMPTS = 0;
 var MAX_RETRY_ATTEMPTS = 5;
 var DEFAULT_RETRY_DELAY_MS = 1e3;
@@ -141,6 +294,77 @@ function clampResponseBytes(maxBytes) {
   if (!Number.isFinite(maxBytes) || maxBytes < 1) return MAX_RESPONSE_BYTES;
   return Math.min(maxBytes, MAX_RESPONSE_BYTES);
 }
+async function timedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), effectiveMs);
+  const signal = ctxSignal ? AbortSignal.any([ctxSignal, ac.signal]) : ac.signal;
+  try {
+    return await fetch(url, { ...fetchOptions, signal });
+  } catch (err) {
+    if (ctxSignal?.aborted) throw ctxSignal.reason;
+    if (ac.signal.aborted) throw new NodeError("TIMEOUT", `Request timed out after ${effectiveMs}ms`);
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function guardUrl(url, ctxSignal, effectiveMs) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), effectiveMs);
+  const signal = ctxSignal ? AbortSignal.any([ctxSignal, ac.signal]) : ac.signal;
+  try {
+    await assertPublicUrl(url, { signal });
+  } catch (err) {
+    if (ctxSignal?.aborted) throw ctxSignal.reason;
+    if (ac.signal.aborted) throw new NodeError("TIMEOUT", `DNS resolution timed out after ${effectiveMs}ms`);
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
+  let currentUrl = url;
+  let currentInit = { ...fetchOptions, redirect: "manual" };
+  await guardUrl(currentUrl, ctxSignal, effectiveMs);
+  for (let hop = 0; ; hop++) {
+    const res = await timedFetch(currentUrl, currentInit, ctxSignal, effectiveMs);
+    const location = res.headers.get("location");
+    if (!REDIRECT_STATUSES.has(res.status) || !location) return res;
+    const redirectStatus = res.status;
+    await res.body?.cancel().catch(() => {
+    });
+    if (hop >= MAX_REDIRECTS) {
+      throw new NodeError("TOO_MANY_REDIRECTS", `Exceeded ${MAX_REDIRECTS} redirects`, { status: redirectStatus });
+    }
+    const base = currentUrl instanceof URL ? currentUrl : new URL(currentUrl);
+    let nextUrl;
+    try {
+      nextUrl = new URL(location, base);
+    } catch {
+      throw new NodeError("BLOCKED_ADDRESS", "Blocked redirect with an invalid Location header", { status: 0 });
+    }
+    if (base.protocol === "https:" && nextUrl.protocol !== "https:") {
+      throw new NodeError("BLOCKED_ADDRESS", "Blocked https\u2192http downgrade on redirect", { status: 0 });
+    }
+    await guardUrl(nextUrl, ctxSignal, effectiveMs);
+    const headers = new Headers(currentInit.headers ?? void 0);
+    let method = (currentInit.method ?? "GET").toUpperCase();
+    let body = currentInit.body;
+    if (redirectStatus === 303 || (redirectStatus === 301 || redirectStatus === 302) && method === "POST") {
+      method = "GET";
+      body = void 0;
+      headers.delete("content-type");
+      headers.delete("content-length");
+    }
+    if (nextUrl.origin !== base.origin) {
+      headers.delete("authorization");
+      headers.delete("cookie");
+      headers.delete("proxy-authorization");
+    }
+    currentUrl = nextUrl;
+    currentInit = { ...currentInit, method, body, headers, redirect: "manual" };
+  }
+}
 async function safeFetch(url, options = {}) {
   const { timeoutMs = DEFAULT_TIMEOUT_MS, signal: ctxSignal, retry, ...fetchOptions } = options;
   const effectiveMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.min(timeoutMs, MAX_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
@@ -151,29 +375,27 @@ async function safeFetch(url, options = {}) {
   let lastError;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     if (ctxSignal?.aborted) throw ctxSignal.reason;
-    const ac = new AbortController();
-    const timer = setTimeout(() => ac.abort(), effectiveMs);
-    const signal = ctxSignal ? AbortSignal.any([ctxSignal, ac.signal]) : ac.signal;
     try {
-      return await fetch(url, { ...fetchOptions, signal });
+      return await guardedFetch(url, fetchOptions, ctxSignal, effectiveMs);
     } catch (err) {
       if (ctxSignal?.aborted) throw ctxSignal.reason;
-      if (ac.signal.aborted) {
-        lastError = new NodeError("TIMEOUT", `Request timed out after ${effectiveMs}ms`);
-      } else {
-        lastError = err;
+      if (err instanceof NodeError && (err.code === "BLOCKED_ADDRESS" || err.code === "TOO_MANY_REDIRECTS")) {
+        throw err;
       }
+      lastError = err;
       if (attempt < maxAttempts) {
         await new Promise((resolve) => {
-          const t = setTimeout(resolve, retryDelayMs);
-          ctxSignal?.addEventListener("abort", () => {
+          const onAbort = () => {
             clearTimeout(t);
             resolve();
-          }, { once: true });
+          };
+          const t = setTimeout(() => {
+            ctxSignal?.removeEventListener("abort", onAbort);
+            resolve();
+          }, retryDelayMs);
+          ctxSignal?.addEventListener("abort", onAbort, { once: true });
         });
       }
-    } finally {
-      clearTimeout(timer);
     }
   }
   throw lastError;
@@ -592,6 +814,7 @@ function base64Url(buf) {
   DEFAULT_RETRY_POLICY,
   DEFAULT_TIMEOUT_MS,
   MANIFEST_VERSION,
+  MAX_REDIRECTS,
   MAX_RESPONSE_BYTES,
   MAX_RETRY_ATTEMPTS,
   MAX_TIMEOUT_MS,
@@ -600,6 +823,7 @@ function base64Url(buf) {
   OAuth2ClientCredentialsCredential,
   RetryableError,
   SimpleValueCredential,
+  assertPublicUrl,
   backoffDelay,
   buildManifest,
   clampResponseBytes,
@@ -607,6 +831,7 @@ function base64Url(buf) {
   extractCredentialManifests,
   extractManifest,
   extractManifests,
+  isBlockedAddress,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
   maxBytesConfigField,

package/dist/index.d.cts

@@ -443,6 +443,8 @@ declare function extractCredentialManifests(credentials: ICredential[]): ICreden
 
 declare const DEFAULT_TIMEOUT_MS = 30000;
 declare const MAX_TIMEOUT_MS = 120000;
+/** Maximum number of redirect hops `safeFetch` follows before giving up. */
+declare const MAX_REDIRECTS = 5;
 declare const DEFAULT_RETRY_ATTEMPTS = 0;
 declare const MAX_RETRY_ATTEMPTS = 5;
 declare const DEFAULT_RETRY_DELAY_MS = 1000;
@@ -506,6 +508,48 @@ declare function retryConfigFields(opts?: {
     defaultDelayMs?: number;
 }): IConfigField[];
 
+/**
+ * A resolved DNS address, mirroring the shape of Node's `dns.LookupAddress`.
+ * `family` is `4` or `6`; only `address` is consulted by the guard.
+ */
+interface LookupAddress {
+    address: string;
+    family: number;
+}
+/**
+ * Resolves a hostname to every address it maps to. Modelled on
+ * `dns.lookup(host, { all: true })`. Injectable so tests can drive the guard
+ * deterministically without real DNS — see {@link ssrfResolver}.
+ */
+type LookupFn = (hostname: string) => Promise<LookupAddress[]>;
+/**
+ * Return `true` when `ip` (a literal IPv4/IPv6 address) points at a private,
+ * loopback, link-local or otherwise non-public target that a server-side fetch
+ * must never be steered to. IPv4-mapped/-compatible IPv6 addresses are unwrapped
+ * and re-checked against the IPv4 rules. An address we cannot parse is treated as
+ * blocked (fail-closed).
+ */
+declare function isBlockedAddress(ip: string): boolean;
+/**
+ * Assert that `url` is safe for a server-side fetch: an http(s) URL whose target
+ * resolves only to public addresses. Rejects non-http(s) protocols, empty hosts
+ * and `localhost`, checks literal-IP hosts directly, and otherwise resolves the
+ * hostname (via the injectable `lookup`, defaulting to {@link ssrfResolver}) and
+ * rejects if **any** resolved address is private/reserved. Throws
+ * `NodeError('BLOCKED_ADDRESS', …, { status: 0 })` on rejection.
+ *
+ * Best-effort by design: Node re-resolves the hostname when it actually connects,
+ * so a DNS-rebinding race (TOCTOU) remains. See the SDK README.
+ *
+ * Pass `signal` (the per-request timeout/cancellation budget) so a hung or
+ * hostile DNS resolve cannot block the guard past that budget — see
+ * {@link resolveHost}.
+ */
+declare function assertPublicUrl(url: string | URL, opts?: {
+    lookup?: LookupFn;
+    signal?: AbortSignal;
+}): Promise<void>;
+
 /**
  * Transport-agnostic retry/backoff primitive (PO-139).
  *
@@ -752,4 +796,4 @@ declare abstract class OAuth2AuthCodeCredential extends BaseCredential implement
     test(_ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
 }
 
-export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IImage, type IInputPort, type INode, type INodeAuthorContext, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, MANIFEST_VERSION, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, backoffDelay, buildManifest, clampResponseBytes, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isNodeWithIteration, isOAuthAuthorizeCredential, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, sleepWithSignal, timeoutConfigField, withRetry };
+export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IImage, type IInputPort, type INode, type INodeAuthorContext, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, type LookupAddress, type LookupFn, MANIFEST_VERSION, MAX_REDIRECTS, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, sleepWithSignal, timeoutConfigField, withRetry };

package/dist/index.d.ts

@@ -443,6 +443,8 @@ declare function extractCredentialManifests(credentials: ICredential[]): ICreden
 
 declare const DEFAULT_TIMEOUT_MS = 30000;
 declare const MAX_TIMEOUT_MS = 120000;
+/** Maximum number of redirect hops `safeFetch` follows before giving up. */
+declare const MAX_REDIRECTS = 5;
 declare const DEFAULT_RETRY_ATTEMPTS = 0;
 declare const MAX_RETRY_ATTEMPTS = 5;
 declare const DEFAULT_RETRY_DELAY_MS = 1000;
@@ -506,6 +508,48 @@ declare function retryConfigFields(opts?: {
     defaultDelayMs?: number;
 }): IConfigField[];
 
+/**
+ * A resolved DNS address, mirroring the shape of Node's `dns.LookupAddress`.
+ * `family` is `4` or `6`; only `address` is consulted by the guard.
+ */
+interface LookupAddress {
+    address: string;
+    family: number;
+}
+/**
+ * Resolves a hostname to every address it maps to. Modelled on
+ * `dns.lookup(host, { all: true })`. Injectable so tests can drive the guard
+ * deterministically without real DNS — see {@link ssrfResolver}.
+ */
+type LookupFn = (hostname: string) => Promise<LookupAddress[]>;
+/**
+ * Return `true` when `ip` (a literal IPv4/IPv6 address) points at a private,
+ * loopback, link-local or otherwise non-public target that a server-side fetch
+ * must never be steered to. IPv4-mapped/-compatible IPv6 addresses are unwrapped
+ * and re-checked against the IPv4 rules. An address we cannot parse is treated as
+ * blocked (fail-closed).
+ */
+declare function isBlockedAddress(ip: string): boolean;
+/**
+ * Assert that `url` is safe for a server-side fetch: an http(s) URL whose target
+ * resolves only to public addresses. Rejects non-http(s) protocols, empty hosts
+ * and `localhost`, checks literal-IP hosts directly, and otherwise resolves the
+ * hostname (via the injectable `lookup`, defaulting to {@link ssrfResolver}) and
+ * rejects if **any** resolved address is private/reserved. Throws
+ * `NodeError('BLOCKED_ADDRESS', …, { status: 0 })` on rejection.
+ *
+ * Best-effort by design: Node re-resolves the hostname when it actually connects,
+ * so a DNS-rebinding race (TOCTOU) remains. See the SDK README.
+ *
+ * Pass `signal` (the per-request timeout/cancellation budget) so a hung or
+ * hostile DNS resolve cannot block the guard past that budget — see
+ * {@link resolveHost}.
+ */
+declare function assertPublicUrl(url: string | URL, opts?: {
+    lookup?: LookupFn;
+    signal?: AbortSignal;
+}): Promise<void>;
+
 /**
  * Transport-agnostic retry/backoff primitive (PO-139).
  *
@@ -752,4 +796,4 @@ declare abstract class OAuth2AuthCodeCredential extends BaseCredential implement
     test(_ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
 }
 
-export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IImage, type IInputPort, type INode, type INodeAuthorContext, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, MANIFEST_VERSION, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, backoffDelay, buildManifest, clampResponseBytes, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isNodeWithIteration, isOAuthAuthorizeCredential, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, sleepWithSignal, timeoutConfigField, withRetry };
+export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IImage, type IInputPort, type INode, type INodeAuthorContext, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, type LookupAddress, type LookupFn, MANIFEST_VERSION, MAX_REDIRECTS, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, sleepWithSignal, timeoutConfigField, withRetry };

package/dist/index.js

@@ -62,9 +62,149 @@ var NodeError = class extends Error {
   }
 };
 
+// src/ssrf.ts
+import { isIP } from "net";
+var ssrfResolver = {
+  lookup: async (hostname) => {
+    const { lookup } = await import("dns/promises");
+    const results = await lookup(hostname, { all: true });
+    return results.map((r) => ({ address: r.address, family: r.family }));
+  }
+};
+function parseIpv4(input) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(input);
+  if (!m) return null;
+  const octets = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+  if (octets.some((n) => n > 255)) return null;
+  return octets;
+}
+function expandIpv6(input) {
+  let s = input;
+  const zone = s.indexOf("%");
+  if (zone !== -1) s = s.slice(0, zone);
+  if (s.includes(".")) {
+    const idx = s.lastIndexOf(":");
+    if (idx === -1) return null;
+    const v4 = parseIpv4(s.slice(idx + 1));
+    if (!v4) return null;
+    const hi = (v4[0] << 8 | v4[1]).toString(16);
+    const lo = (v4[2] << 8 | v4[3]).toString(16);
+    s = `${s.slice(0, idx + 1)}${hi}:${lo}`;
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null;
+  const parseGroups = (part) => part === "" ? [] : part.split(":").map((h) => /^[0-9a-fA-F]{1,4}$/.test(h) ? parseInt(h, 16) : Number.NaN);
+  const head = parseGroups(halves[0] ?? "");
+  const back = halves.length === 2 ? parseGroups(halves[1] ?? "") : null;
+  const declared = [...head, ...back ?? []];
+  if (declared.some((h) => !Number.isInteger(h) || h < 0 || h > 65535)) return null;
+  let hextets;
+  if (back === null) {
+    hextets = head;
+  } else {
+    const zeros = 8 - (head.length + back.length);
+    if (zeros < 1) return null;
+    hextets = [...head, ...new Array(zeros).fill(0), ...back];
+  }
+  return hextets.length === 8 ? hextets : null;
+}
+function isBlockedIpv4(o) {
+  const [a, b] = o;
+  return a === 0 || // 0.0.0.0/8 "this network" (incl. 0.0.0.0)
+  a === 127 || // 127.0.0.0/8 loopback
+  a === 10 || // 10.0.0.0/8 private
+  a === 172 && b >= 16 && b <= 31 || // 172.16.0.0/12 private
+  a === 192 && b === 168 || // 192.168.0.0/16 private
+  a === 169 && b === 254;
+}
+function isBlockedAddress(ip) {
+  const v4 = parseIpv4(ip);
+  if (v4) return isBlockedIpv4(v4);
+  const h = expandIpv6(ip);
+  if (!h) return true;
+  if (h.every((x) => x === 0)) return true;
+  if (h.slice(0, 7).every((x) => x === 0) && h[7] === 1) return true;
+  const embedsV4 = h[0] === 0 && h[1] === 0 && h[2] === 0 && h[3] === 0 && h[4] === 0 && (h[5] === 65535 || h[5] === 0);
+  if (embedsV4) {
+    return isBlockedIpv4([h[6] >> 8, h[6] & 255, h[7] >> 8, h[7] & 255]);
+  }
+  if ((h[0] & 65024) === 64512) return true;
+  if ((h[0] & 65472) === 65152) return true;
+  return false;
+}
+var bypassNoticeLogged = false;
+function guardRelaxedForLocalDev() {
+  const raw = process.env["RVNXX_SSRF_ALLOW_PRIVATE"];
+  const relaxed = raw != null && ["1", "true", "yes"].includes(raw.trim().toLowerCase());
+  if (relaxed && !bypassNoticeLogged) {
+    bypassNoticeLogged = true;
+    console.warn(
+      "[ssrf] RVNXX_SSRF_ALLOW_PRIVATE is set: allowing private/loopback fetch targets. Intended for local development only."
+    );
+  }
+  return relaxed;
+}
+function blockedError(host, address) {
+  if (host === address) {
+    return new NodeError("BLOCKED_ADDRESS", `Blocked request to private or reserved address ${address}`, {
+      status: 0
+    });
+  }
+  console.warn(`[ssrf] blocked request to ${host}: resolves to private/reserved address ${address}`);
+  return new NodeError("BLOCKED_ADDRESS", `Blocked request to ${host}: resolves to a private or reserved address`, {
+    status: 0
+  });
+}
+async function resolveHost(lookup, host, signal) {
+  if (!signal) return lookup(host);
+  if (signal.aborted) throw signal.reason;
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    lookup(host).then(
+      (addresses) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(addresses);
+      },
+      (err) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(err);
+      }
+    );
+  });
+}
+async function assertPublicUrl(url, opts = {}) {
+  const u = url instanceof URL ? url : new URL(url);
+  if (u.protocol !== "http:" && u.protocol !== "https:") {
+    throw new NodeError("BLOCKED_ADDRESS", `Blocked non-HTTP(S) URL protocol: ${u.protocol}`, { status: 0 });
+  }
+  const rawHost = u.hostname;
+  const host = rawHost.startsWith("[") && rawHost.endsWith("]") ? rawHost.slice(1, -1) : rawHost;
+  if (!host) throw new NodeError("BLOCKED_ADDRESS", "Blocked URL with empty host", { status: 0 });
+  if (guardRelaxedForLocalDev()) return;
+  const lower = host.toLowerCase();
+  if (lower === "localhost" || lower.endsWith(".localhost")) {
+    throw new NodeError("BLOCKED_ADDRESS", `Blocked loopback host: ${host}`, { status: 0 });
+  }
+  if (isIP(host) !== 0) {
+    if (isBlockedAddress(host)) throw blockedError(host, host);
+    return;
+  }
+  const lookup = opts.lookup ?? ssrfResolver.lookup;
+  const addresses = await resolveHost(lookup, host, opts.signal);
+  if (!addresses || addresses.length === 0) {
+    throw new NodeError("BLOCKED_ADDRESS", `Could not resolve host: ${host}`, { status: 0 });
+  }
+  for (const a of addresses) {
+    if (isBlockedAddress(a.address)) throw blockedError(host, a.address);
+  }
+}
+
 // src/fetch.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var MAX_TIMEOUT_MS = 12e4;
+var MAX_REDIRECTS = 5;
+var REDIRECT_STATUSES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
 var DEFAULT_RETRY_ATTEMPTS = 0;
 var MAX_RETRY_ATTEMPTS = 5;
 var DEFAULT_RETRY_DELAY_MS = 1e3;
@@ -74,6 +214,77 @@ function clampResponseBytes(maxBytes) {
   if (!Number.isFinite(maxBytes) || maxBytes < 1) return MAX_RESPONSE_BYTES;
   return Math.min(maxBytes, MAX_RESPONSE_BYTES);
 }
+async function timedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), effectiveMs);
+  const signal = ctxSignal ? AbortSignal.any([ctxSignal, ac.signal]) : ac.signal;
+  try {
+    return await fetch(url, { ...fetchOptions, signal });
+  } catch (err) {
+    if (ctxSignal?.aborted) throw ctxSignal.reason;
+    if (ac.signal.aborted) throw new NodeError("TIMEOUT", `Request timed out after ${effectiveMs}ms`);
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function guardUrl(url, ctxSignal, effectiveMs) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), effectiveMs);
+  const signal = ctxSignal ? AbortSignal.any([ctxSignal, ac.signal]) : ac.signal;
+  try {
+    await assertPublicUrl(url, { signal });
+  } catch (err) {
+    if (ctxSignal?.aborted) throw ctxSignal.reason;
+    if (ac.signal.aborted) throw new NodeError("TIMEOUT", `DNS resolution timed out after ${effectiveMs}ms`);
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
+  let currentUrl = url;
+  let currentInit = { ...fetchOptions, redirect: "manual" };
+  await guardUrl(currentUrl, ctxSignal, effectiveMs);
+  for (let hop = 0; ; hop++) {
+    const res = await timedFetch(currentUrl, currentInit, ctxSignal, effectiveMs);
+    const location = res.headers.get("location");
+    if (!REDIRECT_STATUSES.has(res.status) || !location) return res;
+    const redirectStatus = res.status;
+    await res.body?.cancel().catch(() => {
+    });
+    if (hop >= MAX_REDIRECTS) {
+      throw new NodeError("TOO_MANY_REDIRECTS", `Exceeded ${MAX_REDIRECTS} redirects`, { status: redirectStatus });
+    }
+    const base = currentUrl instanceof URL ? currentUrl : new URL(currentUrl);
+    let nextUrl;
+    try {
+      nextUrl = new URL(location, base);
+    } catch {
+      throw new NodeError("BLOCKED_ADDRESS", "Blocked redirect with an invalid Location header", { status: 0 });
+    }
+    if (base.protocol === "https:" && nextUrl.protocol !== "https:") {
+      throw new NodeError("BLOCKED_ADDRESS", "Blocked https\u2192http downgrade on redirect", { status: 0 });
+    }
+    await guardUrl(nextUrl, ctxSignal, effectiveMs);
+    const headers = new Headers(currentInit.headers ?? void 0);
+    let method = (currentInit.method ?? "GET").toUpperCase();
+    let body = currentInit.body;
+    if (redirectStatus === 303 || (redirectStatus === 301 || redirectStatus === 302) && method === "POST") {
+      method = "GET";
+      body = void 0;
+      headers.delete("content-type");
+      headers.delete("content-length");
+    }
+    if (nextUrl.origin !== base.origin) {
+      headers.delete("authorization");
+      headers.delete("cookie");
+      headers.delete("proxy-authorization");
+    }
+    currentUrl = nextUrl;
+    currentInit = { ...currentInit, method, body, headers, redirect: "manual" };
+  }
+}
 async function safeFetch(url, options = {}) {
   const { timeoutMs = DEFAULT_TIMEOUT_MS, signal: ctxSignal, retry, ...fetchOptions } = options;
   const effectiveMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.min(timeoutMs, MAX_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
@@ -84,29 +295,27 @@ async function safeFetch(url, options = {}) {
   let lastError;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     if (ctxSignal?.aborted) throw ctxSignal.reason;
-    const ac = new AbortController();
-    const timer = setTimeout(() => ac.abort(), effectiveMs);
-    const signal = ctxSignal ? AbortSignal.any([ctxSignal, ac.signal]) : ac.signal;
     try {
-      return await fetch(url, { ...fetchOptions, signal });
+      return await guardedFetch(url, fetchOptions, ctxSignal, effectiveMs);
     } catch (err) {
       if (ctxSignal?.aborted) throw ctxSignal.reason;
-      if (ac.signal.aborted) {
-        lastError = new NodeError("TIMEOUT", `Request timed out after ${effectiveMs}ms`);
-      } else {
-        lastError = err;
+      if (err instanceof NodeError && (err.code === "BLOCKED_ADDRESS" || err.code === "TOO_MANY_REDIRECTS")) {
+        throw err;
       }
+      lastError = err;
       if (attempt < maxAttempts) {
         await new Promise((resolve) => {
-          const t = setTimeout(resolve, retryDelayMs);
-          ctxSignal?.addEventListener("abort", () => {
+          const onAbort = () => {
             clearTimeout(t);
             resolve();
-          }, { once: true });
+          };
+          const t = setTimeout(() => {
+            ctxSignal?.removeEventListener("abort", onAbort);
+            resolve();
+          }, retryDelayMs);
+          ctxSignal?.addEventListener("abort", onAbort, { once: true });
         });
       }
-    } finally {
-      clearTimeout(timer);
     }
   }
   throw lastError;
@@ -497,6 +706,7 @@ export {
   DEFAULT_RETRY_POLICY,
   DEFAULT_TIMEOUT_MS,
   MANIFEST_VERSION,
+  MAX_REDIRECTS,
   MAX_RESPONSE_BYTES,
   MAX_RETRY_ATTEMPTS,
   MAX_TIMEOUT_MS,
@@ -505,6 +715,7 @@ export {
   OAuth2ClientCredentialsCredential,
   RetryableError,
   SimpleValueCredential,
+  assertPublicUrl,
   backoffDelay,
   buildManifest,
   clampResponseBytes,
@@ -512,6 +723,7 @@ export {
   extractCredentialManifests,
   extractManifest,
   extractManifests,
+  isBlockedAddress,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
   maxBytesConfigField,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenexx/integrations-node-sdk",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "TypeScript interfaces and utilities for Revenexx integration nodes",
   "license": "MIT",
   "author": "revenexx GmbH",