@revenexx/integrations-node-sdk 1.1.0 → 1.3.0

package/README.md

@@ -4,9 +4,10 @@ The shared TypeScript contract library for **Revenexx integration nodes**. It
 defines the interfaces every integration node and credential must implement, and
 ships the small helper toolchain the node registry uses to build manifests.
 
-It has **no runtime dependencies** and contains no business logic beyond the
-manifest helpers — it exists purely to share one contract between the node
-packages and the workflow engine that runs them.
+It carries **one runtime dependency** — `ipaddr.js`, which the SSRF guard defers
+its address classification to (PO-183) — and no business logic beyond the manifest
+helpers: it exists purely to share one contract between the node packages and the
+workflow engine that runs them.
 
 ```
 integrations-node-sdk          ← this package (types & helpers only)
@@ -34,7 +35,7 @@ configuration or auth token needed.
 | `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). |
+| `ssrf` | `assertPublicUrl` / `isBlockedAddress` — the SSRF guard that backs `safeFetch`, exported for reuse. An address is refused unless it is public unicast — `ipaddr.js` classifies the range, and for IPv6 the address must also sit inside IANA's allocated `2000::/3`, since that classification's *default* verdict is `unicast`. So reserved and unallocated bands nobody enumerated are refused too (PO-183). These two are the pre-flight check; `safeFetch` additionally judges the address each connection lands on, so a DNS answer that changes between check and connect gets no request (PO-184). 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. |
 

package/dist/index.cjs

@@ -54,11 +54,14 @@ __export(index_exports, {
   backoffDelay: () => backoffDelay,
   buildManifest: () => buildManifest,
   clampResponseBytes: () => clampResponseBytes,
+  errorPort: () => errorPort,
+  errorResult: () => errorResult,
   evaluate: () => evaluate,
   extractCredentialManifest: () => extractCredentialManifest,
   extractCredentialManifests: () => extractCredentialManifests,
   extractManifest: () => extractManifest,
   extractManifests: () => extractManifests,
+  httpErrorResult: () => httpErrorResult,
   isBlockedAddress: () => isBlockedAddress,
   isNodeWithIteration: () => isNodeWithIteration,
   isOAuthAuthorizeCredential: () => isOAuthAuthorizeCredential,
@@ -76,6 +79,8 @@ __export(index_exports, {
   sleepWithSignal: () => sleepWithSignal,
   takesValue: () => takesValue,
   timeoutConfigField: () => timeoutConfigField,
+  toErrorOutput: () => toErrorOutput,
+  toErrorResult: () => toErrorResult,
   withRetry: () => withRetry
 });
 module.exports = __toCommonJS(index_exports);
@@ -203,6 +208,76 @@ var NodeError = class extends Error {
   }
 };
 
+// src/nodeErrors.ts
+function toErrorOutput(err) {
+  if (err instanceof NodeError) {
+    const raw = err.meta?.["status"];
+    const status = typeof raw === "number" && Number.isFinite(raw) ? raw : 0;
+    return { code: err.code, message: err.message, status };
+  }
+  if (err instanceof Error && err.name === "AbortError") {
+    return { code: "TIMEOUT", message: "Request timed out", status: 0 };
+  }
+  if (err instanceof Error) {
+    return { code: "REQUEST_FAILED", message: err.message, status: 0 };
+  }
+  return { code: "REQUEST_FAILED", message: String(err), status: 0 };
+}
+function errorResult(output, port = "error") {
+  return { outputs: { [port]: output }, branch: port };
+}
+function toErrorResult(err, port = "error") {
+  return errorResult(toErrorOutput(err), port);
+}
+function httpErrorResult(err, port = "error") {
+  const body = err instanceof NodeError ? err.meta?.["body"] ?? null : null;
+  return errorResult({ ...toErrorOutput(err), body }, port);
+}
+function errorPort(opts = {}) {
+  return {
+    name: "error",
+    kind: "error",
+    dataType: "object",
+    label: { en: "Error", de: "Fehler" },
+    description: {
+      en: "Taken when the attempt fails in a way the workflow can carry on from. A node that cannot run as configured fails the run instead of taking this path.",
+      de: "Wird genommen, wenn der Versuch auf eine Weise fehlschl\xE4gt, mit der der Workflow weiterarbeiten kann. Ein Node, der so konfiguriert nicht laufen kann, l\xE4sst den Run scheitern, statt diesen Pfad zu nehmen."
+    },
+    fields: {
+      code: {
+        dataType: "string",
+        description: {
+          en: "Machine-readable name of the failure \u2014 branch on this rather than on the message. A node that talks to a remote system shares `TIMEOUT` and `REQUEST_FAILED` with every other one; the remaining codes belong to this node alone.",
+          de: "Maschinenlesbarer Name des Fehlers \u2014 hierauf verzweigen, nicht auf die Meldung. Ein Node, der mit einem Fremdsystem spricht, teilt `TIMEOUT` und `REQUEST_FAILED` mit allen anderen; die \xFCbrigen Codes geh\xF6ren allein zu diesem Node."
+        }
+      },
+      message: {
+        dataType: "string",
+        description: {
+          en: "Wording for whoever reads the run afterwards, frequently the wording the far end used. It is not a stable value to branch on.",
+          de: "Wortlaut f\xFCr den, der den Run sp\xE4ter liest, h\xE4ufig der des Gegen\xFCbers. Kein stabiler Wert, auf den sich Verzweigungen st\xFCtzen sollten."
+        }
+      },
+      status: {
+        dataType: "number",
+        description: {
+          en: "How the far end answered, as an HTTP status code, where one answered with a status at all. `0` otherwise \u2014 a timeout, a refused connection, an input the node could not use, a node that never leaves the workflow, or a failure the far end reported in its own answer rather than in a status, as a bulk job that ends as failed does. So `0` means there is no status to read, not that nothing was reached.",
+          de: "Wie das Gegen\xFCber geantwortet hat, als HTTP-Statuscode \u2014 sofern eines \xFCberhaupt mit einem Status geantwortet hat. Sonst `0`: Timeout, abgelehnte Verbindung, eine unbrauchbare Eingabe, ein Node, der den Workflow nicht verl\xE4sst, oder ein Fehler, den das Gegen\xFCber in seiner Antwort statt im Status gemeldet hat \u2014 wie ein Bulk-Job, der als fehlgeschlagen endet. `0` hei\xDFt also: kein Status zu lesen, nicht: nichts erreicht."
+        }
+      },
+      ...opts.body ? {
+        body: {
+          dataType: "any",
+          description: {
+            en: "The answer the far end gave, where the failure got far enough to have one: the response body, or the job the platform reported as failed.",
+            de: "Die Antwort des Gegen\xFCbers, sofern der Fehler weit genug kam, um eine zu haben: der Response-Body oder der von der Plattform als fehlgeschlagen gemeldete Job."
+          }
+        }
+      } : {}
+    }
+  };
+}
+
 // src/extract.ts
 function extractManifest(node) {
   return node.description;
@@ -218,7 +293,9 @@ function extractCredentialManifests(credentials) {
 }
 
 // src/ssrf.ts
+var import_node_diagnostics_channel = require("diagnostics_channel");
 var import_node_net = require("net");
+var import_ipaddr = __toESM(require("ipaddr.js"), 1);
 var ssrfResolver = {
   lookup: async (hostname) => {
     const { lookup } = await import("dns/promises");
@@ -226,66 +303,27 @@ var ssrfResolver = {
     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 isIPv6(addr) {
+  return addr.kind() === "ipv6";
+}
+var PUBLIC_RANGE = "unicast";
+var GLOBAL_UNICAST_V6 = import_ipaddr.default.parseCIDR("2000::/3");
+var V4_EMBEDDING_RANGES = /* @__PURE__ */ new Set(["ipv4Mapped", "rfc6052"]);
+function embeddedIpv4(addr) {
+  return import_ipaddr.default.fromByteArray(addr.toByteArray().slice(12));
 }
 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;
+  let addr;
+  try {
+    addr = import_ipaddr.default.parse(ip);
+  } catch {
+    return true;
+  }
+  if (isIPv6(addr)) {
+    if (V4_EMBEDDING_RANGES.has(addr.range())) return embeddedIpv4(addr).range() !== PUBLIC_RANGE;
+    if (!addr.match(GLOBAL_UNICAST_V6)) return true;
+  }
+  return addr.range() !== PUBLIC_RANGE;
 }
 var bypassNoticeLogged = false;
 function guardRelaxedForLocalDev() {
@@ -310,6 +348,82 @@ function blockedError(host, address) {
     status: 0
   });
 }
+var guardedTargets = /* @__PURE__ */ new Map();
+var connectGuardInstalled = false;
+function normalizeHost(hostname) {
+  const host = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  return host.toLowerCase();
+}
+function targetKey(hostname, port, protocol) {
+  const host = normalizeHost(hostname);
+  const effective = port === "" ? protocol === "https:" ? "443" : "80" : port;
+  return `${host}:${effective}`;
+}
+var unreadableMessageLogged = false;
+function reportUnreadableMessage() {
+  if (unreadableMessageLogged) return;
+  unreadableMessageLogged = true;
+  console.warn(
+    "[ssrf] undici:client:connected published a message this guard cannot read: the connect-time half of the SSRF guard is not judging connections. The pre-flight check still applies."
+  );
+}
+function connectBlockedError(host, address) {
+  if (address == null) {
+    console.warn(`[ssrf] dropped connection to ${host}: the address it landed on could not be read`);
+    return new NodeError(
+      "BLOCKED_ADDRESS",
+      `Blocked request to ${host}: the address the connection landed on could not be read`,
+      { status: 0 }
+    );
+  }
+  if (host === address) {
+    return new NodeError("BLOCKED_ADDRESS", `Blocked connection to private or reserved address ${address}`, {
+      status: 0
+    });
+  }
+  console.warn(`[ssrf] dropped connection to ${host}: connected to private/reserved address ${address}`);
+  return new NodeError(
+    "BLOCKED_ADDRESS",
+    `Blocked request to ${host}: the connection landed on a private or reserved address`,
+    { status: 0 }
+  );
+}
+function judgeConnection(message) {
+  const { connectParams, socket } = message ?? {};
+  const hostname = connectParams?.hostname;
+  const port = connectParams?.port;
+  const protocol = connectParams?.protocol;
+  if (hostname == null || port == null || protocol == null || typeof socket?.destroy !== "function") {
+    reportUnreadableMessage();
+    return;
+  }
+  if (!guardedTargets.has(targetKey(hostname, port, protocol))) return;
+  if (guardRelaxedForLocalDev()) return;
+  const peer = socket.remoteAddress;
+  if (peer != null && !isBlockedAddress(peer)) return;
+  socket.destroy(connectBlockedError(normalizeHost(hostname), peer));
+}
+function guardConnectionsTo(url) {
+  if (!connectGuardInstalled) {
+    connectGuardInstalled = true;
+    (0, import_node_diagnostics_channel.subscribe)("undici:client:connected", judgeConnection);
+  }
+  const key = targetKey(url.hostname, url.port, url.protocol);
+  guardedTargets.set(key, (guardedTargets.get(key) ?? 0) + 1);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const count = (guardedTargets.get(key) ?? 1) - 1;
+    if (count > 0) guardedTargets.set(key, count);
+    else guardedTargets.delete(key);
+  };
+}
+function connectionRefusal(err) {
+  const cause = err?.cause;
+  if (cause instanceof NodeError && cause.code === "BLOCKED_ADDRESS") return cause;
+  return void 0;
+}
 async function resolveHost(lookup, host, signal) {
   if (!signal) return lookup(host);
   if (signal.aborted) throw signal.reason;
@@ -376,6 +490,8 @@ async function timedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
   try {
     return await fetch(url, { ...fetchOptions, signal });
   } catch (err) {
+    const blocked = connectionRefusal(err);
+    if (blocked) throw blocked;
     if (ctxSignal?.aborted) throw ctxSignal.reason;
     if (ac.signal.aborted) throw new NodeError("TIMEOUT", `Request timed out after ${effectiveMs}ms`);
     throw err;
@@ -402,7 +518,15 @@ async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
   let currentInit = { ...fetchOptions, redirect: "manual" };
   await guardUrl(currentUrl, ctxSignal, effectiveMs);
   for (let hop = 0; ; hop++) {
-    const res = await timedFetch(currentUrl, currentInit, ctxSignal, effectiveMs);
+    const release = guardConnectionsTo(
+      currentUrl instanceof URL ? currentUrl : new URL(currentUrl)
+    );
+    let res;
+    try {
+      res = await timedFetch(currentUrl, currentInit, ctxSignal, effectiveMs);
+    } finally {
+      release();
+    }
     const location = res.headers.get("location");
     if (!REDIRECT_STATUSES.has(res.status) || !location) return res;
     const redirectStatus = res.status;
@@ -486,6 +610,8 @@ async function readArrayBuffer(res, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
   const cap = clampResponseBytes(maxBytes);
   const declared = Number(res.headers.get("content-length"));
   if (Number.isFinite(declared) && declared > cap) {
+    await res.body?.cancel().catch(() => {
+    });
     throw tooLargeError(res.status, declared, cap);
   }
   const body = res.body;
@@ -694,6 +820,7 @@ function expiryFromExpiresIn(expiresIn) {
   }
   return new Date(Date.now() + seconds * 1e3).toISOString();
 }
+var MAX_TOKEN_RESPONSE_BYTES = 1024 * 1024;
 var BaseCredential = class {
   async test(_ctx, config) {
     for (const field of this.description.fields) {
@@ -721,6 +848,12 @@ var BaseCredential = class {
    * Note that a 301/302 answer to this POST is downgraded to a bodiless GET —
    * per the redirect rules, not a quirk of ours. Real token endpoints do not
    * redirect; one that does was never going to complete the exchange anyway.
+   *
+   * The third protection is the caller's own: safeFetch hands back a `Response`
+   * and reading it is not its job, so the answer goes through {@link readText}
+   * under {@link MAX_TOKEN_RESPONSE_BYTES} rather than a bare `res.text()`.
+   * Both branches below read that same string, so the cap covers the refusal as
+   * well as the token — an error body is the less predictable of the two.
    */
   async postForm(ctx, url, form, headers = {}) {
     const body = new URLSearchParams();
@@ -735,7 +868,7 @@ var BaseCredential = class {
       headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json", ...headers },
       body
     });
-    const text = await res.text();
+    const text = await readText(res, MAX_TOKEN_RESPONSE_BYTES);
     if (!res.ok) {
       throw new Error(`token endpoint ${url} -> ${res.status}${formatOAuthError(text)}`);
     }
@@ -922,11 +1055,14 @@ function base64Url(buf) {
   backoffDelay,
   buildManifest,
   clampResponseBytes,
+  errorPort,
+  errorResult,
   evaluate,
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
   extractManifests,
+  httpErrorResult,
   isBlockedAddress,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
@@ -944,5 +1080,7 @@ function base64Url(buf) {
   sleepWithSignal,
   takesValue,
   timeoutConfigField,
+  toErrorOutput,
+  toErrorResult,
   withRetry
 });

package/dist/index.d.cts

@@ -650,6 +650,67 @@ declare class NodeError extends Error {
     constructor(code: string, message: string, meta?: Record<string, unknown>);
 }
 
+/**
+ * Canonical error-output shape emitted on a node's `error` port. It lives here
+ * rather than in a node package because all four of them were building it
+ * separately — `integrations-nodes-core` in an internal module, `deepl` in a
+ * copy of that module, Business Central in `bc-fetch.ts` and Pipedrive in
+ * `pipedrive-client.ts` — so the workflow editor's guarantee of one
+ * `{ code, message, status }` payload rested on four files agreeing by hand
+ * (PO-442; asked for by PO-134 in June and not done then).
+ */
+interface NodeErrorOutput {
+    /** Machine-readable error code, e.g. `HTTP_ERROR`, `TIMEOUT`, `REQUEST_FAILED`. */
+    code: string;
+    message: string;
+    /** HTTP status code, or `0` for timeouts / network / non-HTTP errors. */
+    status: number;
+    /** Optional response body — HTTP-specific. */
+    body?: unknown;
+}
+/**
+ * Normalize any caught value into the canonical {@link NodeErrorOutput} shape.
+ * Use this in a node's `catch` block before routing to the `error` port.
+ */
+declare function toErrorOutput(err: unknown): NodeErrorOutput;
+/** Wrap an error output into an `INodeResult` routed to the `error` port. */
+declare function errorResult(output: NodeErrorOutput, port?: string): INodeResult;
+/**
+ * Catch-block shortcut: normalize any thrown value and route it to the failure
+ * output. The one helper every node's `catch` funnels into, so the
+ * `{ code, message, status }` mapping lives in a single place instead of being
+ * re-implemented per protocol (FTP/SFTP) or per package.
+ *
+ * `port` is the output taken, `error` unless the node declares its failure
+ * output under another name (`{ ...errorPort(), name: 'failed' }`) — pass the
+ * same name here, or the branch names a port that node does not have.
+ */
+declare function toErrorResult(err: unknown, port?: string): INodeResult;
+/**
+ * Catch-block shortcut for the HTTP-style nodes whose failure output additionally
+ * declares `body`: the canonical `{ code, message, status }` mapping plus the
+ * response body a {@link NodeError} carries in `meta.body` (`null` when the
+ * failure never reached a response). `port` names the output as above.
+ */
+declare function httpErrorResult(err: unknown, port?: string): INodeResult;
+/**
+ * Shared `error` output port — the uniform `{ code, message, status }` triple
+ * declared on every node that has an `error` branch. Pass `body: true` for
+ * HTTP-style nodes that additionally emit a response body on the port.
+ *
+ * The sentences travel with the port. The three values mean the same thing
+ * behind every node, so they are written here once instead of per node; a node
+ * whose failures are worth naming more precisely spreads the port and replaces
+ * only its `description` (`{ ...errorPort(), description: … }`).
+ *
+ * The second sentence of the description is the rule this port exists under,
+ * and it is promised in `specs/error-handling.md`: a fault in the author's own
+ * configuration ends the run, a fault met while running is offered here.
+ */
+declare function errorPort(opts?: {
+    body?: boolean;
+}): IOutputPort;
+
 declare function extractManifest(node: INode): INodeDescription;
 declare function extractManifests(nodes: INode[]): INodeDescription[];
 declare function extractCredentialManifest(credential: ICredential): ICredentialDescription;
@@ -694,7 +755,8 @@ declare function safeFetch(url: string | URL, options?: SafeFetchOptions): Promi
  * The `Content-Length` header is used as a fast-reject (bail before downloading
  * anything), but the limit is *also* enforced while streaming, since the header
  * can be absent or lie. On overrun the stream is cancelled and a
- * `NodeError('RESPONSE_TOO_LARGE', …, { status })` is thrown.
+ * `NodeError('RESPONSE_TOO_LARGE', …, { status })` is thrown. Both refusal paths
+ * cancel the body first, so neither leaves the connection held.
  */
 declare function readArrayBuffer(res: Response, maxBytes?: number): Promise<ArrayBuffer>;
 /** Read a response body as UTF-8 text, capped at `maxBytes` (see {@link readArrayBuffer}). */
@@ -738,10 +800,19 @@ interface LookupAddress {
 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
+ * loopback, link-local, carrier-grade NAT, multicast, broadcast, reserved,
+ * unallocated or otherwise non-public target that a server-side fetch must never be
+ * steered to.
+ *
+ * The verdict is an allow-list: the address is refused unless the classification
+ * calls its range public unicast and — for IPv6, where that verdict is a default
+ * rather than a determination — it also sits inside the block IANA has allocated
+ * (see {@link GLOBAL_UNICAST_V6}). The IPv6 forms that embed an IPv4 address are
+ * unwrapped and the embedded address judged in its place, so a public host stays
+ * reachable when it is written that way. An address we cannot parse is treated as
  * blocked (fail-closed).
+ *
+ * Promised behaviour: specs/ssrf-guard.md (AC-9, AC-11, AC-19).
  */
 declare function isBlockedAddress(ip: string): boolean;
 /**
@@ -752,8 +823,10 @@ declare function isBlockedAddress(ip: string): boolean;
  * 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.
+ * This is the pre-flight half of the guard: the connection that follows resolves
+ * the name again on its own, so `safeFetch` also judges the address the socket
+ * actually reached (PO-184). A caller that opens its own request after
+ * `assertPublicUrl` gets the check and not that second half.
  *
  * Pass `signal` (the per-request timeout/cancellation budget) so a hung or
  * hostile DNS resolve cannot block the guard past that budget — see
@@ -952,6 +1025,12 @@ declare abstract class BaseCredential implements ICredential {
      * Note that a 301/302 answer to this POST is downgraded to a bodiless GET —
      * per the redirect rules, not a quirk of ours. Real token endpoints do not
      * redirect; one that does was never going to complete the exchange anyway.
+     *
+     * The third protection is the caller's own: safeFetch hands back a `Response`
+     * and reading it is not its job, so the answer goes through {@link readText}
+     * under {@link MAX_TOKEN_RESPONSE_BYTES} rather than a bare `res.text()`.
+     * Both branches below read that same string, so the cap covers the refusal as
+     * well as the token — an error body is the less predictable of the two.
      */
     protected postForm(ctx: ICredentialContext, url: string, form: Record<string, string | undefined>, headers?: Record<string, string>): Promise<OAuthTokenResponse>;
 }
@@ -1028,4 +1107,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 INodeState, type INodeWithIteration, type IOutputField, type IOutputPort, type IShowIfCondition, 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, OPERATORS, type Operator, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, VALUELESS_OPERATORS, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, evaluate, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, isOperator, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, settingApplies, sleepWithSignal, takesValue, 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 INodeState, type INodeWithIteration, type IOutputField, type IOutputPort, type IShowIfCondition, 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 NodeErrorOutput, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, OPERATORS, type Operator, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, VALUELESS_OPERATORS, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, errorPort, errorResult, evaluate, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, httpErrorResult, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, isOperator, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, settingApplies, sleepWithSignal, takesValue, timeoutConfigField, toErrorOutput, toErrorResult, withRetry };

package/dist/index.d.ts

@@ -650,6 +650,67 @@ declare class NodeError extends Error {
     constructor(code: string, message: string, meta?: Record<string, unknown>);
 }
 
+/**
+ * Canonical error-output shape emitted on a node's `error` port. It lives here
+ * rather than in a node package because all four of them were building it
+ * separately — `integrations-nodes-core` in an internal module, `deepl` in a
+ * copy of that module, Business Central in `bc-fetch.ts` and Pipedrive in
+ * `pipedrive-client.ts` — so the workflow editor's guarantee of one
+ * `{ code, message, status }` payload rested on four files agreeing by hand
+ * (PO-442; asked for by PO-134 in June and not done then).
+ */
+interface NodeErrorOutput {
+    /** Machine-readable error code, e.g. `HTTP_ERROR`, `TIMEOUT`, `REQUEST_FAILED`. */
+    code: string;
+    message: string;
+    /** HTTP status code, or `0` for timeouts / network / non-HTTP errors. */
+    status: number;
+    /** Optional response body — HTTP-specific. */
+    body?: unknown;
+}
+/**
+ * Normalize any caught value into the canonical {@link NodeErrorOutput} shape.
+ * Use this in a node's `catch` block before routing to the `error` port.
+ */
+declare function toErrorOutput(err: unknown): NodeErrorOutput;
+/** Wrap an error output into an `INodeResult` routed to the `error` port. */
+declare function errorResult(output: NodeErrorOutput, port?: string): INodeResult;
+/**
+ * Catch-block shortcut: normalize any thrown value and route it to the failure
+ * output. The one helper every node's `catch` funnels into, so the
+ * `{ code, message, status }` mapping lives in a single place instead of being
+ * re-implemented per protocol (FTP/SFTP) or per package.
+ *
+ * `port` is the output taken, `error` unless the node declares its failure
+ * output under another name (`{ ...errorPort(), name: 'failed' }`) — pass the
+ * same name here, or the branch names a port that node does not have.
+ */
+declare function toErrorResult(err: unknown, port?: string): INodeResult;
+/**
+ * Catch-block shortcut for the HTTP-style nodes whose failure output additionally
+ * declares `body`: the canonical `{ code, message, status }` mapping plus the
+ * response body a {@link NodeError} carries in `meta.body` (`null` when the
+ * failure never reached a response). `port` names the output as above.
+ */
+declare function httpErrorResult(err: unknown, port?: string): INodeResult;
+/**
+ * Shared `error` output port — the uniform `{ code, message, status }` triple
+ * declared on every node that has an `error` branch. Pass `body: true` for
+ * HTTP-style nodes that additionally emit a response body on the port.
+ *
+ * The sentences travel with the port. The three values mean the same thing
+ * behind every node, so they are written here once instead of per node; a node
+ * whose failures are worth naming more precisely spreads the port and replaces
+ * only its `description` (`{ ...errorPort(), description: … }`).
+ *
+ * The second sentence of the description is the rule this port exists under,
+ * and it is promised in `specs/error-handling.md`: a fault in the author's own
+ * configuration ends the run, a fault met while running is offered here.
+ */
+declare function errorPort(opts?: {
+    body?: boolean;
+}): IOutputPort;
+
 declare function extractManifest(node: INode): INodeDescription;
 declare function extractManifests(nodes: INode[]): INodeDescription[];
 declare function extractCredentialManifest(credential: ICredential): ICredentialDescription;
@@ -694,7 +755,8 @@ declare function safeFetch(url: string | URL, options?: SafeFetchOptions): Promi
  * The `Content-Length` header is used as a fast-reject (bail before downloading
  * anything), but the limit is *also* enforced while streaming, since the header
  * can be absent or lie. On overrun the stream is cancelled and a
- * `NodeError('RESPONSE_TOO_LARGE', …, { status })` is thrown.
+ * `NodeError('RESPONSE_TOO_LARGE', …, { status })` is thrown. Both refusal paths
+ * cancel the body first, so neither leaves the connection held.
  */
 declare function readArrayBuffer(res: Response, maxBytes?: number): Promise<ArrayBuffer>;
 /** Read a response body as UTF-8 text, capped at `maxBytes` (see {@link readArrayBuffer}). */
@@ -738,10 +800,19 @@ interface LookupAddress {
 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
+ * loopback, link-local, carrier-grade NAT, multicast, broadcast, reserved,
+ * unallocated or otherwise non-public target that a server-side fetch must never be
+ * steered to.
+ *
+ * The verdict is an allow-list: the address is refused unless the classification
+ * calls its range public unicast and — for IPv6, where that verdict is a default
+ * rather than a determination — it also sits inside the block IANA has allocated
+ * (see {@link GLOBAL_UNICAST_V6}). The IPv6 forms that embed an IPv4 address are
+ * unwrapped and the embedded address judged in its place, so a public host stays
+ * reachable when it is written that way. An address we cannot parse is treated as
  * blocked (fail-closed).
+ *
+ * Promised behaviour: specs/ssrf-guard.md (AC-9, AC-11, AC-19).
  */
 declare function isBlockedAddress(ip: string): boolean;
 /**
@@ -752,8 +823,10 @@ declare function isBlockedAddress(ip: string): boolean;
  * 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.
+ * This is the pre-flight half of the guard: the connection that follows resolves
+ * the name again on its own, so `safeFetch` also judges the address the socket
+ * actually reached (PO-184). A caller that opens its own request after
+ * `assertPublicUrl` gets the check and not that second half.
  *
  * Pass `signal` (the per-request timeout/cancellation budget) so a hung or
  * hostile DNS resolve cannot block the guard past that budget — see
@@ -952,6 +1025,12 @@ declare abstract class BaseCredential implements ICredential {
      * Note that a 301/302 answer to this POST is downgraded to a bodiless GET —
      * per the redirect rules, not a quirk of ours. Real token endpoints do not
      * redirect; one that does was never going to complete the exchange anyway.
+     *
+     * The third protection is the caller's own: safeFetch hands back a `Response`
+     * and reading it is not its job, so the answer goes through {@link readText}
+     * under {@link MAX_TOKEN_RESPONSE_BYTES} rather than a bare `res.text()`.
+     * Both branches below read that same string, so the cap covers the refusal as
+     * well as the token — an error body is the less predictable of the two.
      */
     protected postForm(ctx: ICredentialContext, url: string, form: Record<string, string | undefined>, headers?: Record<string, string>): Promise<OAuthTokenResponse>;
 }
@@ -1028,4 +1107,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 INodeState, type INodeWithIteration, type IOutputField, type IOutputPort, type IShowIfCondition, 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, OPERATORS, type Operator, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, VALUELESS_OPERATORS, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, evaluate, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, isOperator, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, settingApplies, sleepWithSignal, takesValue, 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 INodeState, type INodeWithIteration, type IOutputField, type IOutputPort, type IShowIfCondition, 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 NodeErrorOutput, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, OPERATORS, type Operator, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, VALUELESS_OPERATORS, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, errorPort, errorResult, evaluate, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, httpErrorResult, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, isOperator, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, settingApplies, sleepWithSignal, takesValue, timeoutConfigField, toErrorOutput, toErrorResult, withRetry };

package/dist/index.js

@@ -131,8 +131,80 @@ var NodeError = class extends Error {
   }
 };
 
+// src/nodeErrors.ts
+function toErrorOutput(err) {
+  if (err instanceof NodeError) {
+    const raw = err.meta?.["status"];
+    const status = typeof raw === "number" && Number.isFinite(raw) ? raw : 0;
+    return { code: err.code, message: err.message, status };
+  }
+  if (err instanceof Error && err.name === "AbortError") {
+    return { code: "TIMEOUT", message: "Request timed out", status: 0 };
+  }
+  if (err instanceof Error) {
+    return { code: "REQUEST_FAILED", message: err.message, status: 0 };
+  }
+  return { code: "REQUEST_FAILED", message: String(err), status: 0 };
+}
+function errorResult(output, port = "error") {
+  return { outputs: { [port]: output }, branch: port };
+}
+function toErrorResult(err, port = "error") {
+  return errorResult(toErrorOutput(err), port);
+}
+function httpErrorResult(err, port = "error") {
+  const body = err instanceof NodeError ? err.meta?.["body"] ?? null : null;
+  return errorResult({ ...toErrorOutput(err), body }, port);
+}
+function errorPort(opts = {}) {
+  return {
+    name: "error",
+    kind: "error",
+    dataType: "object",
+    label: { en: "Error", de: "Fehler" },
+    description: {
+      en: "Taken when the attempt fails in a way the workflow can carry on from. A node that cannot run as configured fails the run instead of taking this path.",
+      de: "Wird genommen, wenn der Versuch auf eine Weise fehlschl\xE4gt, mit der der Workflow weiterarbeiten kann. Ein Node, der so konfiguriert nicht laufen kann, l\xE4sst den Run scheitern, statt diesen Pfad zu nehmen."
+    },
+    fields: {
+      code: {
+        dataType: "string",
+        description: {
+          en: "Machine-readable name of the failure \u2014 branch on this rather than on the message. A node that talks to a remote system shares `TIMEOUT` and `REQUEST_FAILED` with every other one; the remaining codes belong to this node alone.",
+          de: "Maschinenlesbarer Name des Fehlers \u2014 hierauf verzweigen, nicht auf die Meldung. Ein Node, der mit einem Fremdsystem spricht, teilt `TIMEOUT` und `REQUEST_FAILED` mit allen anderen; die \xFCbrigen Codes geh\xF6ren allein zu diesem Node."
+        }
+      },
+      message: {
+        dataType: "string",
+        description: {
+          en: "Wording for whoever reads the run afterwards, frequently the wording the far end used. It is not a stable value to branch on.",
+          de: "Wortlaut f\xFCr den, der den Run sp\xE4ter liest, h\xE4ufig der des Gegen\xFCbers. Kein stabiler Wert, auf den sich Verzweigungen st\xFCtzen sollten."
+        }
+      },
+      status: {
+        dataType: "number",
+        description: {
+          en: "How the far end answered, as an HTTP status code, where one answered with a status at all. `0` otherwise \u2014 a timeout, a refused connection, an input the node could not use, a node that never leaves the workflow, or a failure the far end reported in its own answer rather than in a status, as a bulk job that ends as failed does. So `0` means there is no status to read, not that nothing was reached.",
+          de: "Wie das Gegen\xFCber geantwortet hat, als HTTP-Statuscode \u2014 sofern eines \xFCberhaupt mit einem Status geantwortet hat. Sonst `0`: Timeout, abgelehnte Verbindung, eine unbrauchbare Eingabe, ein Node, der den Workflow nicht verl\xE4sst, oder ein Fehler, den das Gegen\xFCber in seiner Antwort statt im Status gemeldet hat \u2014 wie ein Bulk-Job, der als fehlgeschlagen endet. `0` hei\xDFt also: kein Status zu lesen, nicht: nichts erreicht."
+        }
+      },
+      ...opts.body ? {
+        body: {
+          dataType: "any",
+          description: {
+            en: "The answer the far end gave, where the failure got far enough to have one: the response body, or the job the platform reported as failed.",
+            de: "Die Antwort des Gegen\xFCbers, sofern der Fehler weit genug kam, um eine zu haben: der Response-Body oder der von der Plattform als fehlgeschlagen gemeldete Job."
+          }
+        }
+      } : {}
+    }
+  };
+}
+
 // src/ssrf.ts
+import { subscribe } from "diagnostics_channel";
 import { isIP } from "net";
+import ipaddr from "ipaddr.js";
 var ssrfResolver = {
   lookup: async (hostname) => {
     const { lookup } = await import("dns/promises");
@@ -140,66 +212,27 @@ var ssrfResolver = {
     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 isIPv6(addr) {
+  return addr.kind() === "ipv6";
+}
+var PUBLIC_RANGE = "unicast";
+var GLOBAL_UNICAST_V6 = ipaddr.parseCIDR("2000::/3");
+var V4_EMBEDDING_RANGES = /* @__PURE__ */ new Set(["ipv4Mapped", "rfc6052"]);
+function embeddedIpv4(addr) {
+  return ipaddr.fromByteArray(addr.toByteArray().slice(12));
 }
 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;
+  let addr;
+  try {
+    addr = ipaddr.parse(ip);
+  } catch {
+    return true;
+  }
+  if (isIPv6(addr)) {
+    if (V4_EMBEDDING_RANGES.has(addr.range())) return embeddedIpv4(addr).range() !== PUBLIC_RANGE;
+    if (!addr.match(GLOBAL_UNICAST_V6)) return true;
+  }
+  return addr.range() !== PUBLIC_RANGE;
 }
 var bypassNoticeLogged = false;
 function guardRelaxedForLocalDev() {
@@ -224,6 +257,82 @@ function blockedError(host, address) {
     status: 0
   });
 }
+var guardedTargets = /* @__PURE__ */ new Map();
+var connectGuardInstalled = false;
+function normalizeHost(hostname) {
+  const host = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  return host.toLowerCase();
+}
+function targetKey(hostname, port, protocol) {
+  const host = normalizeHost(hostname);
+  const effective = port === "" ? protocol === "https:" ? "443" : "80" : port;
+  return `${host}:${effective}`;
+}
+var unreadableMessageLogged = false;
+function reportUnreadableMessage() {
+  if (unreadableMessageLogged) return;
+  unreadableMessageLogged = true;
+  console.warn(
+    "[ssrf] undici:client:connected published a message this guard cannot read: the connect-time half of the SSRF guard is not judging connections. The pre-flight check still applies."
+  );
+}
+function connectBlockedError(host, address) {
+  if (address == null) {
+    console.warn(`[ssrf] dropped connection to ${host}: the address it landed on could not be read`);
+    return new NodeError(
+      "BLOCKED_ADDRESS",
+      `Blocked request to ${host}: the address the connection landed on could not be read`,
+      { status: 0 }
+    );
+  }
+  if (host === address) {
+    return new NodeError("BLOCKED_ADDRESS", `Blocked connection to private or reserved address ${address}`, {
+      status: 0
+    });
+  }
+  console.warn(`[ssrf] dropped connection to ${host}: connected to private/reserved address ${address}`);
+  return new NodeError(
+    "BLOCKED_ADDRESS",
+    `Blocked request to ${host}: the connection landed on a private or reserved address`,
+    { status: 0 }
+  );
+}
+function judgeConnection(message) {
+  const { connectParams, socket } = message ?? {};
+  const hostname = connectParams?.hostname;
+  const port = connectParams?.port;
+  const protocol = connectParams?.protocol;
+  if (hostname == null || port == null || protocol == null || typeof socket?.destroy !== "function") {
+    reportUnreadableMessage();
+    return;
+  }
+  if (!guardedTargets.has(targetKey(hostname, port, protocol))) return;
+  if (guardRelaxedForLocalDev()) return;
+  const peer = socket.remoteAddress;
+  if (peer != null && !isBlockedAddress(peer)) return;
+  socket.destroy(connectBlockedError(normalizeHost(hostname), peer));
+}
+function guardConnectionsTo(url) {
+  if (!connectGuardInstalled) {
+    connectGuardInstalled = true;
+    subscribe("undici:client:connected", judgeConnection);
+  }
+  const key = targetKey(url.hostname, url.port, url.protocol);
+  guardedTargets.set(key, (guardedTargets.get(key) ?? 0) + 1);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const count = (guardedTargets.get(key) ?? 1) - 1;
+    if (count > 0) guardedTargets.set(key, count);
+    else guardedTargets.delete(key);
+  };
+}
+function connectionRefusal(err) {
+  const cause = err?.cause;
+  if (cause instanceof NodeError && cause.code === "BLOCKED_ADDRESS") return cause;
+  return void 0;
+}
 async function resolveHost(lookup, host, signal) {
   if (!signal) return lookup(host);
   if (signal.aborted) throw signal.reason;
@@ -290,6 +399,8 @@ async function timedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
   try {
     return await fetch(url, { ...fetchOptions, signal });
   } catch (err) {
+    const blocked = connectionRefusal(err);
+    if (blocked) throw blocked;
     if (ctxSignal?.aborted) throw ctxSignal.reason;
     if (ac.signal.aborted) throw new NodeError("TIMEOUT", `Request timed out after ${effectiveMs}ms`);
     throw err;
@@ -316,7 +427,15 @@ async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
   let currentInit = { ...fetchOptions, redirect: "manual" };
   await guardUrl(currentUrl, ctxSignal, effectiveMs);
   for (let hop = 0; ; hop++) {
-    const res = await timedFetch(currentUrl, currentInit, ctxSignal, effectiveMs);
+    const release = guardConnectionsTo(
+      currentUrl instanceof URL ? currentUrl : new URL(currentUrl)
+    );
+    let res;
+    try {
+      res = await timedFetch(currentUrl, currentInit, ctxSignal, effectiveMs);
+    } finally {
+      release();
+    }
     const location = res.headers.get("location");
     if (!REDIRECT_STATUSES.has(res.status) || !location) return res;
     const redirectStatus = res.status;
@@ -400,6 +519,8 @@ async function readArrayBuffer(res, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
   const cap = clampResponseBytes(maxBytes);
   const declared = Number(res.headers.get("content-length"));
   if (Number.isFinite(declared) && declared > cap) {
+    await res.body?.cancel().catch(() => {
+    });
     throw tooLargeError(res.status, declared, cap);
   }
   const body = res.body;
@@ -581,6 +702,7 @@ function expiryFromExpiresIn(expiresIn) {
   }
   return new Date(Date.now() + seconds * 1e3).toISOString();
 }
+var MAX_TOKEN_RESPONSE_BYTES = 1024 * 1024;
 var BaseCredential = class {
   async test(_ctx, config) {
     for (const field of this.description.fields) {
@@ -608,6 +730,12 @@ var BaseCredential = class {
    * Note that a 301/302 answer to this POST is downgraded to a bodiless GET —
    * per the redirect rules, not a quirk of ours. Real token endpoints do not
    * redirect; one that does was never going to complete the exchange anyway.
+   *
+   * The third protection is the caller's own: safeFetch hands back a `Response`
+   * and reading it is not its job, so the answer goes through {@link readText}
+   * under {@link MAX_TOKEN_RESPONSE_BYTES} rather than a bare `res.text()`.
+   * Both branches below read that same string, so the cap covers the refusal as
+   * well as the token — an error body is the less predictable of the two.
    */
   async postForm(ctx, url, form, headers = {}) {
     const body = new URLSearchParams();
@@ -622,7 +750,7 @@ var BaseCredential = class {
       headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json", ...headers },
       body
     });
-    const text = await res.text();
+    const text = await readText(res, MAX_TOKEN_RESPONSE_BYTES);
     if (!res.ok) {
       throw new Error(`token endpoint ${url} -> ${res.status}${formatOAuthError(text)}`);
     }
@@ -808,11 +936,14 @@ export {
   backoffDelay,
   buildManifest,
   clampResponseBytes,
+  errorPort,
+  errorResult,
   evaluate,
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
   extractManifests,
+  httpErrorResult,
   isBlockedAddress,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
@@ -830,5 +961,7 @@ export {
   sleepWithSignal,
   takesValue,
   timeoutConfigField,
+  toErrorOutput,
+  toErrorResult,
   withRetry
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenexx/integrations-node-sdk",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "TypeScript interfaces and utilities for Revenexx integration nodes",
   "license": "MIT",
   "author": "revenexx GmbH",
@@ -61,5 +61,8 @@
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "ipaddr.js": "2.5.0"
   }
 }