@revenexx/integrations-node-sdk 1.0.0 → 1.2.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

@@ -218,7 +218,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 +228,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 +273,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 +415,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 +443,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 +535,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 +745,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 +773,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 +793,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)}`);
     }

package/dist/index.d.cts

@@ -178,8 +178,28 @@ interface IConfigFieldBase {
     stateRole?: 'mapping' | 'cursor' | 'dedupe' | 'digest';
 }
 interface IConfigField extends IConfigFieldBase {
-    properties?: IConfigFieldBase[];
-    items?: IConfigFieldBase;
+    /**
+     * The sub-settings of a field that holds a group of them (`type: 'object'`).
+     *
+     * A full `IConfigField`, not the base. `IConfigFieldBase` already carries
+     * `options`, `default`, `required`, `description` and `showIf`, so those were
+     * never what a nested setting was missing — `properties` and `items` were: the
+     * base has neither, so a sub-setting could not itself group or repeat without
+     * a cast. The manifest schema permits that nesting and the engine's config
+     * walker reads nested fields as first-class; the type was the only place
+     * stopping at one level (PO-436).
+     */
+    properties?: IConfigField[];
+    /**
+     * What one entry of a list field (`type: 'array'`) looks like.
+     *
+     * Full `IConfigField` for the same reason as `properties`, and this is the one
+     * that bit: `items.type: 'object'` plus `items.properties` is the repeating row
+     * every mapping-style setting is built from, and `items` typed as the base had
+     * no `properties` to give it. `SwitchNode` in integrations-nodes-core ends its
+     * items block with `as IConfigField` for exactly that reason.
+     */
+    items?: IConfigField;
 }
 interface INodeDescription {
     slug: string;
@@ -674,7 +694,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}). */
@@ -718,10 +739,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;
 /**
@@ -732,8 +762,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
@@ -932,6 +964,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>;
 }

package/dist/index.d.ts

@@ -178,8 +178,28 @@ interface IConfigFieldBase {
     stateRole?: 'mapping' | 'cursor' | 'dedupe' | 'digest';
 }
 interface IConfigField extends IConfigFieldBase {
-    properties?: IConfigFieldBase[];
-    items?: IConfigFieldBase;
+    /**
+     * The sub-settings of a field that holds a group of them (`type: 'object'`).
+     *
+     * A full `IConfigField`, not the base. `IConfigFieldBase` already carries
+     * `options`, `default`, `required`, `description` and `showIf`, so those were
+     * never what a nested setting was missing — `properties` and `items` were: the
+     * base has neither, so a sub-setting could not itself group or repeat without
+     * a cast. The manifest schema permits that nesting and the engine's config
+     * walker reads nested fields as first-class; the type was the only place
+     * stopping at one level (PO-436).
+     */
+    properties?: IConfigField[];
+    /**
+     * What one entry of a list field (`type: 'array'`) looks like.
+     *
+     * Full `IConfigField` for the same reason as `properties`, and this is the one
+     * that bit: `items.type: 'object'` plus `items.properties` is the repeating row
+     * every mapping-style setting is built from, and `items` typed as the base had
+     * no `properties` to give it. `SwitchNode` in integrations-nodes-core ends its
+     * items block with `as IConfigField` for exactly that reason.
+     */
+    items?: IConfigField;
 }
 interface INodeDescription {
     slug: string;
@@ -674,7 +694,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}). */
@@ -718,10 +739,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;
 /**
@@ -732,8 +762,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
@@ -932,6 +964,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>;
 }

package/dist/index.js

@@ -132,7 +132,9 @@ var NodeError = class extends Error {
 };
 
 // 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 +142,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 +187,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 +329,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 +357,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 +449,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 +632,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 +660,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 +680,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)}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenexx/integrations-node-sdk",
-  "version": "1.0.0",
+  "version": "1.2.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"
   }
 }