@revenexx/integrations-node-sdk 1.11.0 → 1.13.0

package/dist/allowedTargets.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The per-run allow-list of the SSRF guard (PO-828): the exact `ip:port` pairs a
+ * run may reach although the address is private — its own tenant's VPN routes,
+ * served by the relay at a private overlay address (an RFC 1918 or IPv6
+ * unique-local one — no other address may be listed).
+ *
+ * **The global symbol is the contract, not this module.** Every node bundle carries
+ * its own copy of this package, so a module-level setter would reach only the copy
+ * that happened to be imported by the host. The trusted host instead defines one
+ * property on `globalThis`, before any node bundle is imported, and every copy reads
+ * that same property:
+ *
+ * ```ts
+ * Object.defineProperty(globalThis, Symbol.for('revenexx.ssrf.allowedTargets'), {
+ *   value: Object.freeze([...targets]),
+ *   writable: false, configurable: false, enumerable: false,
+ * });
+ * ```
+ *
+ * The host may do that itself (the runtimes do, without depending on this package)
+ * or call {@link installAllowedTargets}, which does exactly that.
+ *
+ * A property that is not shaped that way is read as no list at all. Non-writable and
+ * non-configurable is what makes the list impossible to widen after the host set it;
+ * a property that lacks either was not set by a host following the contract, and a
+ * guard that honoured it would let whoever set it decide what is private.
+ */
+export declare const ALLOWED_TARGETS_SYMBOL: unique symbol;
+/** Test seam: how many times a list has been validated. Not re-exported from the package. */
+export declare const allowListStats: {
+    validations: number;
+};
+/**
+ * Read the list off `holder` — `globalThis` in production, a fresh object in the
+ * tests that need a shape the one-shot global cannot be given twice. Anything but a
+ * frozen array of valid entries on a non-writable, non-configurable data property
+ * reads as the empty list: fail closed, never partly.
+ */
+export declare function readAllowedTargets(holder: object): readonly string[];
+/** {@link isAllowedTarget} against the list on `holder`. */
+export declare function isAllowedTargetOn(holder: object, ip: string, port: number): boolean;
+/** {@link installAllowedTargets} onto `holder`. */
+export declare function installAllowedTargetsOn(holder: object, targets: readonly string[]): void;
+/**
+ * Install the per-run allow-list on `globalThis`. For the trusted host, before any
+ * node bundle is imported; one-shot — a second call throws, as does an entry that is
+ * not `"<ip>:<port>"` (IPv4 dotted) or `"[v6]:<port>"`, or whose address is not an
+ * RFC 1918 or IPv6 unique-local one.
+ *
+ * Install it even when the list is empty. A process that never installs one leaves
+ * the property free for the first code that runs to define it — node code included.
+ *
+ * Promised behaviour: specs/ssrf-guard.md (AC-26 to AC-31).
+ */
+export declare function installAllowedTargets(targets: readonly string[]): void;
+/**
+ * The per-run allow-list as the host installed it, or an empty list when none is
+ * installed or the property is malformed (see {@link ALLOWED_TARGETS_SYMBOL}).
+ */
+export declare function allowedTargets(): readonly string[];
+/**
+ * Whether the run may reach `ip` on `port` although the address is private: `true`
+ * only when exactly that pair is on the allow-list. The port is part of the target —
+ * `10.31.0.7:8080` on the list does not allow `10.31.0.7:22`. For a caller that opens
+ * its own socket; `safeFetch` and `assertPublicUrl` already consult it.
+ */
+export declare function isAllowedTarget(ip: string, port: number): boolean;

package/dist/errors.d.ts

@@ -3,3 +3,24 @@ export declare class NodeError extends Error {
     readonly meta?: Record<string, unknown>;
     constructor(code: string, message: string, meta?: Record<string, unknown>);
 }
+/**
+ * The two codes a step fails with when the VPN route it was configured with
+ * cannot be used (PO-825). Both are failures of the world around the run, not of
+ * the data a record carried, and neither is retried by the platform.
+ *
+ * - `VPN_UNAVAILABLE` — the connection exists but is not `active`;
+ *   message `VPN connection <name> is <status>`.
+ * - `VPN_ROUTE_MISSING` — the connection or the route no longer exists;
+ *   message `VPN route <connection>/<route> no longer exists`.
+ */
+export declare const VPN_UNAVAILABLE: 'VPN_UNAVAILABLE';
+export declare const VPN_ROUTE_MISSING: 'VPN_ROUTE_MISSING';
+/** Every VPN failure code, for a reader that has to recognise one. */
+export declare const VPN_ERROR_CODES: readonly ["VPN_UNAVAILABLE", "VPN_ROUTE_MISSING"];
+/** One of {@link VPN_ERROR_CODES}. */
+export type VpnErrorCode = (typeof VPN_ERROR_CODES)[number];
+/**
+ * Whether `code` is a VPN failure code, narrowing it. `VPN_ERROR_CODES.includes`
+ * does not accept a plain `string`, which is what `NodeError.code` is.
+ */
+export declare function isVpnErrorCode(code: string): code is VpnErrorCode;

package/dist/index.cjs

@@ -50,6 +50,10 @@ __export(index_exports, {
   RetryableError: () => RetryableError,
   SimpleValueCredential: () => SimpleValueCredential,
   VALUELESS_OPERATORS: () => VALUELESS_OPERATORS,
+  VPN_ERROR_CODES: () => VPN_ERROR_CODES,
+  VPN_ROUTE_MISSING: () => VPN_ROUTE_MISSING,
+  VPN_UNAVAILABLE: () => VPN_UNAVAILABLE,
+  allowedTargets: () => allowedTargets,
   assertBranchNamed: () => assertBranchNamed,
   assertPublicUrl: () => assertPublicUrl,
   backoffDelay: () => backoffDelay,
@@ -64,11 +68,14 @@ __export(index_exports, {
   extractManifests: () => extractManifests,
   headerCrossesOrigin: () => headerCrossesOrigin,
   httpErrorResult: () => httpErrorResult,
+  installAllowedTargets: () => installAllowedTargets,
+  isAllowedTarget: () => isAllowedTarget,
   isBlockedAddress: () => isBlockedAddress,
   isMultiPort: () => isMultiPort,
   isNodeWithIteration: () => isNodeWithIteration,
   isOAuthAuthorizeCredential: () => isOAuthAuthorizeCredential,
   isOperator: () => isOperator,
+  isVpnErrorCode: () => isVpnErrorCode,
   maxBytesConfigField: () => maxBytesConfigField,
   normalizeCredentialType: () => normalizeCredentialType,
   normalizeLocalized: () => normalizeLocalized,
@@ -213,6 +220,12 @@ var NodeError = class extends Error {
     this.meta = meta;
   }
 };
+var VPN_UNAVAILABLE = "VPN_UNAVAILABLE";
+var VPN_ROUTE_MISSING = "VPN_ROUTE_MISSING";
+var VPN_ERROR_CODES = Object.freeze([VPN_UNAVAILABLE, VPN_ROUTE_MISSING]);
+function isVpnErrorCode(code) {
+  return VPN_ERROR_CODES.includes(code);
+}
 
 // src/nodeErrors.ts
 function toErrorOutput(err) {
@@ -359,8 +372,123 @@ function assertBranchNamed(node, result, config) {
 
 // src/ssrf.ts
 var import_node_diagnostics_channel = require("diagnostics_channel");
+var import_node_dns = __toESM(require("dns"), 1);
+var import_node_net2 = require("net");
+var import_ipaddr2 = __toESM(require("ipaddr.js"), 1);
+var import_undici = require("undici");
+
+// src/allowedTargets.ts
 var import_node_net = require("net");
 var import_ipaddr = __toESM(require("ipaddr.js"), 1);
+var ALLOWED_TARGETS_SYMBOL = /* @__PURE__ */ Symbol.for("revenexx.ssrf.allowedTargets");
+var EMPTY = Object.freeze([]);
+var V4_ENTRY = /^(\d{1,3}(?:\.\d{1,3}){3}):(\d{1,5})$/;
+var V6_ENTRY = /^\[([0-9A-Fa-f:.]+)\]:(\d{1,5})$/;
+function canonicalAddress(ip) {
+  const bare = ip.startsWith("[") && ip.endsWith("]") ? ip.slice(1, -1) : ip;
+  if ((0, import_node_net.isIP)(bare) === 0) return void 0;
+  try {
+    return import_ipaddr.default.process(bare).toString();
+  } catch {
+    return void 0;
+  }
+}
+function validPort(port) {
+  return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+var TARGET_RANGES = /* @__PURE__ */ new Set(["private", "uniqueLocal"]);
+function loopbackTargetsAllowed() {
+  const raw = process.env["RVNXX_SSRF_TARGETS_ALLOW_LOOPBACK"];
+  return raw != null && ["1", "true", "yes"].includes(raw.trim().toLowerCase());
+}
+function parseTarget(entry, allowLoopback) {
+  if (typeof entry !== "string") return void 0;
+  const v4 = V4_ENTRY.exec(entry);
+  const m = v4 ?? V6_ENTRY.exec(entry);
+  if (!m) return void 0;
+  const host = m[1];
+  const port = Number(m[2]);
+  if (v4 && !import_ipaddr.default.IPv4.isValidFourPartDecimal(host)) return void 0;
+  if (!validPort(port)) return void 0;
+  const address = canonicalAddress(host);
+  if (address === void 0) return void 0;
+  const range = import_ipaddr.default.parse(address).range();
+  if (!TARGET_RANGES.has(range) && !(allowLoopback && range === "loopback")) return void 0;
+  return `${address}:${port}`;
+}
+var allowListStats = { validations: 0 };
+var keysByList = /* @__PURE__ */ new WeakMap();
+function keysOf(list) {
+  const allowLoopback = loopbackTargetsAllowed();
+  let byMode = keysByList.get(list);
+  if (byMode === void 0) {
+    byMode = /* @__PURE__ */ new Map();
+    keysByList.set(list, byMode);
+  }
+  const cached = byMode.get(allowLoopback);
+  if (cached !== void 0) return cached;
+  allowListStats.validations++;
+  const keys = /* @__PURE__ */ new Set();
+  let result = keys;
+  for (const entry of list) {
+    const key = parseTarget(entry, allowLoopback);
+    if (key === void 0) {
+      result = null;
+      break;
+    }
+    keys.add(key);
+  }
+  byMode.set(allowLoopback, result);
+  return result;
+}
+function installedList(holder) {
+  const descriptor = Object.getOwnPropertyDescriptor(holder, ALLOWED_TARGETS_SYMBOL);
+  if (descriptor === void 0 || !("value" in descriptor)) return null;
+  if (descriptor.writable || descriptor.configurable) return null;
+  const value = descriptor.value;
+  if (!Array.isArray(value) || !Object.isFrozen(value)) return null;
+  const keys = keysOf(value);
+  return keys === null ? null : { list: value, keys };
+}
+function readAllowedTargets(holder) {
+  return installedList(holder)?.list ?? EMPTY;
+}
+function isAllowedTargetOn(holder, ip, port) {
+  const installed = installedList(holder);
+  if (installed === null || !validPort(port)) return false;
+  const address = canonicalAddress(ip);
+  return address !== void 0 && installed.keys.has(`${address}:${port}`);
+}
+function installAllowedTargetsOn(holder, targets) {
+  if (Object.getOwnPropertyDescriptor(holder, ALLOWED_TARGETS_SYMBOL) !== void 0) {
+    throw new Error("The SSRF allow-list is already installed, and is installed once per process");
+  }
+  if (!Array.isArray(targets)) throw new TypeError('The SSRF allow-list must be an array of "<ip>:<port>" strings');
+  for (const entry of targets) {
+    if (parseTarget(entry, loopbackTargetsAllowed()) === void 0) {
+      throw new TypeError(
+        `Not an allowed target: ${JSON.stringify(entry)} (expected "<ip>:<port>" or "[v6]:<port>" at an RFC 1918 or unique-local address)`
+      );
+    }
+  }
+  Object.defineProperty(holder, ALLOWED_TARGETS_SYMBOL, {
+    value: Object.freeze([...targets]),
+    writable: false,
+    configurable: false,
+    enumerable: false
+  });
+}
+function installAllowedTargets(targets) {
+  installAllowedTargetsOn(globalThis, targets);
+}
+function allowedTargets() {
+  return readAllowedTargets(globalThis);
+}
+function isAllowedTarget(ip, port) {
+  return isAllowedTargetOn(globalThis, ip, port);
+}
+
+// src/ssrf.ts
 var ssrfResolver = {
   lookup: async (hostname) => {
     const { lookup } = await import("dns/promises");
@@ -372,15 +500,15 @@ function isIPv6(addr) {
   return addr.kind() === "ipv6";
 }
 var PUBLIC_RANGE = "unicast";
-var GLOBAL_UNICAST_V6 = import_ipaddr.default.parseCIDR("2000::/3");
+var GLOBAL_UNICAST_V6 = import_ipaddr2.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));
+  return import_ipaddr2.default.fromByteArray(addr.toByteArray().slice(12));
 }
 function isBlockedAddress(ip) {
   let addr;
   try {
-    addr = import_ipaddr.default.parse(ip);
+    addr = import_ipaddr2.default.parse(ip);
   } catch {
     return true;
   }
@@ -466,8 +594,73 @@ function judgeConnection(message) {
   if (guardRelaxedForLocalDev()) return;
   const peer = socket.remoteAddress;
   if (peer != null && !isBlockedAddress(peer)) return;
+  const remotePort = socket.remotePort;
+  if (peer != null && allowedTargets().length > 0 && !Number.isInteger(remotePort)) {
+    reportUnreadablePeerPort();
+    socket.destroy(unreadablePortError(normalizeHost(hostname)));
+    return;
+  }
+  if (peer != null && isAllowedTarget(peer, remotePort)) return;
   socket.destroy(connectBlockedError(normalizeHost(hostname), peer));
 }
+var unreadablePeerPortLogged = false;
+function reportUnreadablePeerPort() {
+  if (unreadablePeerPortLogged) return;
+  unreadablePeerPortLogged = true;
+  console.warn(
+    "[ssrf] a connection reported no remote port: the SSRF allow-list cannot be consulted, so private peers are refused."
+  );
+}
+function unreadablePortError(host) {
+  return new NodeError(
+    "BLOCKED_ADDRESS",
+    `Blocked request to ${host}: the port the connection landed on could not be read, so the allow-list could not be consulted`,
+    { status: 0 }
+  );
+}
+function judgingLookup(port) {
+  return (hostname, options, callback) => {
+    import_node_dns.default.lookup(hostname, { ...options, all: true }, (err, addresses) => {
+      if (err) {
+        callback(err, "");
+        return;
+      }
+      if (addresses.length === 0) {
+        callback(new NodeError("BLOCKED_ADDRESS", `Could not resolve host: ${hostname}`, { status: 0 }), "");
+        return;
+      }
+      if (!guardRelaxedForLocalDev()) {
+        for (const a of addresses) {
+          if (isBlockedAddress(a.address) && !isAllowedTarget(a.address, port)) {
+            callback(blockedError(normalizeHost(hostname), a.address), "");
+            return;
+          }
+        }
+      }
+      if (options.all) callback(null, addresses);
+      else callback(null, addresses[0].address, addresses[0].family);
+    });
+  };
+}
+var connectors = /* @__PURE__ */ new Map();
+function connectorFor(port) {
+  let connector = connectors.get(port);
+  if (connector === void 0) {
+    connector = (0, import_undici.buildConnector)({ lookup: judgingLookup(port) });
+    connectors.set(port, connector);
+  }
+  return connector;
+}
+var dispatcher;
+function guardedDispatcher() {
+  dispatcher ??= new import_undici.Agent({
+    connect: (opts, callback) => {
+      const port = opts.port === "" ? opts.protocol === "https:" ? 443 : 80 : Number(opts.port);
+      return connectorFor(port)(opts, callback);
+    }
+  });
+  return dispatcher;
+}
 function guardConnectionsTo(url) {
   if (!connectGuardInstalled) {
     connectGuardInstalled = true;
@@ -520,8 +713,10 @@ async function assertPublicUrl(url, opts = {}) {
   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);
+  const port = u.port === "" ? u.protocol === "https:" ? 443 : 80 : Number(u.port);
+  const refused = (address) => isBlockedAddress(address) && !isAllowedTarget(address, port);
+  if ((0, import_node_net2.isIP)(host) !== 0) {
+    if (refused(host)) throw blockedError(host, host);
     return;
   }
   const lookup = opts.lookup ?? ssrfResolver.lookup;
@@ -530,7 +725,7 @@ async function assertPublicUrl(url, opts = {}) {
     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);
+    if (refused(a.address)) throw blockedError(host, a.address);
   }
 }
 
@@ -630,7 +825,7 @@ async function timedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
   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 fetch(url, { ...fetchOptions, signal, dispatcher: guardedDispatcher() });
   } catch (err) {
     const blocked = connectionRefusal(err);
     if (blocked) throw blocked;
@@ -1298,6 +1493,10 @@ function base64Url(buf) {
   RetryableError,
   SimpleValueCredential,
   VALUELESS_OPERATORS,
+  VPN_ERROR_CODES,
+  VPN_ROUTE_MISSING,
+  VPN_UNAVAILABLE,
+  allowedTargets,
   assertBranchNamed,
   assertPublicUrl,
   backoffDelay,
@@ -1312,11 +1511,14 @@ function base64Url(buf) {
   extractManifests,
   headerCrossesOrigin,
   httpErrorResult,
+  installAllowedTargets,
+  isAllowedTarget,
   isBlockedAddress,
   isMultiPort,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
   isOperator,
+  isVpnErrorCode,
   maxBytesConfigField,
   normalizeCredentialType,
   normalizeLocalized,

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './branches.js';
 export * from './fetch.js';
 export { assertPublicUrl, isBlockedAddress } from './ssrf.js';
 export type { LookupAddress, LookupFn } from './ssrf.js';
+export { allowedTargets, installAllowedTargets, isAllowedTarget } from './allowedTargets.js';
 export * from './retry.js';
 export * from './manifest.js';
 export * from './credentials.js';

package/dist/index.js

@@ -135,6 +135,12 @@ var NodeError = class extends Error {
     this.meta = meta;
   }
 };
+var VPN_UNAVAILABLE = "VPN_UNAVAILABLE";
+var VPN_ROUTE_MISSING = "VPN_ROUTE_MISSING";
+var VPN_ERROR_CODES = Object.freeze([VPN_UNAVAILABLE, VPN_ROUTE_MISSING]);
+function isVpnErrorCode(code) {
+  return VPN_ERROR_CODES.includes(code);
+}
 
 // src/nodeErrors.ts
 function toErrorOutput(err) {
@@ -208,8 +214,123 @@ function errorPort(opts = {}) {
 
 // src/ssrf.ts
 import { subscribe } from "diagnostics_channel";
+import dns from "dns";
+import { isIP as isIP2 } from "net";
+import ipaddr2 from "ipaddr.js";
+import { Agent, buildConnector } from "undici";
+
+// src/allowedTargets.ts
 import { isIP } from "net";
 import ipaddr from "ipaddr.js";
+var ALLOWED_TARGETS_SYMBOL = /* @__PURE__ */ Symbol.for("revenexx.ssrf.allowedTargets");
+var EMPTY = Object.freeze([]);
+var V4_ENTRY = /^(\d{1,3}(?:\.\d{1,3}){3}):(\d{1,5})$/;
+var V6_ENTRY = /^\[([0-9A-Fa-f:.]+)\]:(\d{1,5})$/;
+function canonicalAddress(ip) {
+  const bare = ip.startsWith("[") && ip.endsWith("]") ? ip.slice(1, -1) : ip;
+  if (isIP(bare) === 0) return void 0;
+  try {
+    return ipaddr.process(bare).toString();
+  } catch {
+    return void 0;
+  }
+}
+function validPort(port) {
+  return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+var TARGET_RANGES = /* @__PURE__ */ new Set(["private", "uniqueLocal"]);
+function loopbackTargetsAllowed() {
+  const raw = process.env["RVNXX_SSRF_TARGETS_ALLOW_LOOPBACK"];
+  return raw != null && ["1", "true", "yes"].includes(raw.trim().toLowerCase());
+}
+function parseTarget(entry, allowLoopback) {
+  if (typeof entry !== "string") return void 0;
+  const v4 = V4_ENTRY.exec(entry);
+  const m = v4 ?? V6_ENTRY.exec(entry);
+  if (!m) return void 0;
+  const host = m[1];
+  const port = Number(m[2]);
+  if (v4 && !ipaddr.IPv4.isValidFourPartDecimal(host)) return void 0;
+  if (!validPort(port)) return void 0;
+  const address = canonicalAddress(host);
+  if (address === void 0) return void 0;
+  const range = ipaddr.parse(address).range();
+  if (!TARGET_RANGES.has(range) && !(allowLoopback && range === "loopback")) return void 0;
+  return `${address}:${port}`;
+}
+var allowListStats = { validations: 0 };
+var keysByList = /* @__PURE__ */ new WeakMap();
+function keysOf(list) {
+  const allowLoopback = loopbackTargetsAllowed();
+  let byMode = keysByList.get(list);
+  if (byMode === void 0) {
+    byMode = /* @__PURE__ */ new Map();
+    keysByList.set(list, byMode);
+  }
+  const cached = byMode.get(allowLoopback);
+  if (cached !== void 0) return cached;
+  allowListStats.validations++;
+  const keys = /* @__PURE__ */ new Set();
+  let result = keys;
+  for (const entry of list) {
+    const key = parseTarget(entry, allowLoopback);
+    if (key === void 0) {
+      result = null;
+      break;
+    }
+    keys.add(key);
+  }
+  byMode.set(allowLoopback, result);
+  return result;
+}
+function installedList(holder) {
+  const descriptor = Object.getOwnPropertyDescriptor(holder, ALLOWED_TARGETS_SYMBOL);
+  if (descriptor === void 0 || !("value" in descriptor)) return null;
+  if (descriptor.writable || descriptor.configurable) return null;
+  const value = descriptor.value;
+  if (!Array.isArray(value) || !Object.isFrozen(value)) return null;
+  const keys = keysOf(value);
+  return keys === null ? null : { list: value, keys };
+}
+function readAllowedTargets(holder) {
+  return installedList(holder)?.list ?? EMPTY;
+}
+function isAllowedTargetOn(holder, ip, port) {
+  const installed = installedList(holder);
+  if (installed === null || !validPort(port)) return false;
+  const address = canonicalAddress(ip);
+  return address !== void 0 && installed.keys.has(`${address}:${port}`);
+}
+function installAllowedTargetsOn(holder, targets) {
+  if (Object.getOwnPropertyDescriptor(holder, ALLOWED_TARGETS_SYMBOL) !== void 0) {
+    throw new Error("The SSRF allow-list is already installed, and is installed once per process");
+  }
+  if (!Array.isArray(targets)) throw new TypeError('The SSRF allow-list must be an array of "<ip>:<port>" strings');
+  for (const entry of targets) {
+    if (parseTarget(entry, loopbackTargetsAllowed()) === void 0) {
+      throw new TypeError(
+        `Not an allowed target: ${JSON.stringify(entry)} (expected "<ip>:<port>" or "[v6]:<port>" at an RFC 1918 or unique-local address)`
+      );
+    }
+  }
+  Object.defineProperty(holder, ALLOWED_TARGETS_SYMBOL, {
+    value: Object.freeze([...targets]),
+    writable: false,
+    configurable: false,
+    enumerable: false
+  });
+}
+function installAllowedTargets(targets) {
+  installAllowedTargetsOn(globalThis, targets);
+}
+function allowedTargets() {
+  return readAllowedTargets(globalThis);
+}
+function isAllowedTarget(ip, port) {
+  return isAllowedTargetOn(globalThis, ip, port);
+}
+
+// src/ssrf.ts
 var ssrfResolver = {
   lookup: async (hostname) => {
     const { lookup } = await import("dns/promises");
@@ -221,15 +342,15 @@ function isIPv6(addr) {
   return addr.kind() === "ipv6";
 }
 var PUBLIC_RANGE = "unicast";
-var GLOBAL_UNICAST_V6 = ipaddr.parseCIDR("2000::/3");
+var GLOBAL_UNICAST_V6 = ipaddr2.parseCIDR("2000::/3");
 var V4_EMBEDDING_RANGES = /* @__PURE__ */ new Set(["ipv4Mapped", "rfc6052"]);
 function embeddedIpv4(addr) {
-  return ipaddr.fromByteArray(addr.toByteArray().slice(12));
+  return ipaddr2.fromByteArray(addr.toByteArray().slice(12));
 }
 function isBlockedAddress(ip) {
   let addr;
   try {
-    addr = ipaddr.parse(ip);
+    addr = ipaddr2.parse(ip);
   } catch {
     return true;
   }
@@ -315,8 +436,73 @@ function judgeConnection(message) {
   if (guardRelaxedForLocalDev()) return;
   const peer = socket.remoteAddress;
   if (peer != null && !isBlockedAddress(peer)) return;
+  const remotePort = socket.remotePort;
+  if (peer != null && allowedTargets().length > 0 && !Number.isInteger(remotePort)) {
+    reportUnreadablePeerPort();
+    socket.destroy(unreadablePortError(normalizeHost(hostname)));
+    return;
+  }
+  if (peer != null && isAllowedTarget(peer, remotePort)) return;
   socket.destroy(connectBlockedError(normalizeHost(hostname), peer));
 }
+var unreadablePeerPortLogged = false;
+function reportUnreadablePeerPort() {
+  if (unreadablePeerPortLogged) return;
+  unreadablePeerPortLogged = true;
+  console.warn(
+    "[ssrf] a connection reported no remote port: the SSRF allow-list cannot be consulted, so private peers are refused."
+  );
+}
+function unreadablePortError(host) {
+  return new NodeError(
+    "BLOCKED_ADDRESS",
+    `Blocked request to ${host}: the port the connection landed on could not be read, so the allow-list could not be consulted`,
+    { status: 0 }
+  );
+}
+function judgingLookup(port) {
+  return (hostname, options, callback) => {
+    dns.lookup(hostname, { ...options, all: true }, (err, addresses) => {
+      if (err) {
+        callback(err, "");
+        return;
+      }
+      if (addresses.length === 0) {
+        callback(new NodeError("BLOCKED_ADDRESS", `Could not resolve host: ${hostname}`, { status: 0 }), "");
+        return;
+      }
+      if (!guardRelaxedForLocalDev()) {
+        for (const a of addresses) {
+          if (isBlockedAddress(a.address) && !isAllowedTarget(a.address, port)) {
+            callback(blockedError(normalizeHost(hostname), a.address), "");
+            return;
+          }
+        }
+      }
+      if (options.all) callback(null, addresses);
+      else callback(null, addresses[0].address, addresses[0].family);
+    });
+  };
+}
+var connectors = /* @__PURE__ */ new Map();
+function connectorFor(port) {
+  let connector = connectors.get(port);
+  if (connector === void 0) {
+    connector = buildConnector({ lookup: judgingLookup(port) });
+    connectors.set(port, connector);
+  }
+  return connector;
+}
+var dispatcher;
+function guardedDispatcher() {
+  dispatcher ??= new Agent({
+    connect: (opts, callback) => {
+      const port = opts.port === "" ? opts.protocol === "https:" ? 443 : 80 : Number(opts.port);
+      return connectorFor(port)(opts, callback);
+    }
+  });
+  return dispatcher;
+}
 function guardConnectionsTo(url) {
   if (!connectGuardInstalled) {
     connectGuardInstalled = true;
@@ -369,8 +555,10 @@ async function assertPublicUrl(url, opts = {}) {
   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);
+  const port = u.port === "" ? u.protocol === "https:" ? 443 : 80 : Number(u.port);
+  const refused = (address) => isBlockedAddress(address) && !isAllowedTarget(address, port);
+  if (isIP2(host) !== 0) {
+    if (refused(host)) throw blockedError(host, host);
     return;
   }
   const lookup = opts.lookup ?? ssrfResolver.lookup;
@@ -379,7 +567,7 @@ async function assertPublicUrl(url, opts = {}) {
     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);
+    if (refused(a.address)) throw blockedError(host, a.address);
   }
 }
 
@@ -479,7 +667,7 @@ async function timedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
   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 fetch(url, { ...fetchOptions, signal, dispatcher: guardedDispatcher() });
   } catch (err) {
     const blocked = connectionRefusal(err);
     if (blocked) throw blocked;
@@ -1111,6 +1299,10 @@ export {
   RetryableError,
   SimpleValueCredential,
   VALUELESS_OPERATORS,
+  VPN_ERROR_CODES,
+  VPN_ROUTE_MISSING,
+  VPN_UNAVAILABLE,
+  allowedTargets,
   assertBranchNamed,
   assertPublicUrl,
   backoffDelay,
@@ -1125,11 +1317,14 @@ export {
   extractManifests,
   headerCrossesOrigin,
   httpErrorResult,
+  installAllowedTargets,
+  isAllowedTarget,
   isBlockedAddress,
   isMultiPort,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
   isOperator,
+  isVpnErrorCode,
   maxBytesConfigField,
   normalizeCredentialType,
   normalizeLocalized,

package/dist/ssrf.d.ts

@@ -1,3 +1,4 @@
+import { Agent } from 'undici';
 import { NodeError } from './errors.js';
 /**
  * A resolved DNS address, mirroring the shape of Node's `dns.LookupAddress`.
@@ -39,6 +40,13 @@ export declare const ssrfResolver: {
  * Promised behaviour: specs/ssrf-guard.md (AC-9, AC-11, AC-19).
  */
 export declare function isBlockedAddress(ip: string): boolean;
+/**
+ * The dispatcher `safeFetch` hands every request to. One per process, so
+ * keep-alive survives across calls; its pool holds only connections a `safeFetch`
+ * call opened. Deliberately **not** re-exported from `index.ts`, for the reason
+ * {@link guardConnectionsTo} is not.
+ */
+export declare function guardedDispatcher(): Agent;
 /**
  * Put `url`'s host **and port** under the connect-time guard and return the
  * release for it. Ref-counted, so concurrent calls to one target do not release
@@ -48,8 +56,8 @@ export declare function isBlockedAddress(ip: string): boolean;
  *
  * The window is the call, not the connection. A connect that completes after the
  * release — the fetch it belonged to having already timed out or aborted — finds
- * its target unregistered and is not judged; see the gap in
- * `specs/ssrf-guard.md`.
+ * its target unregistered and is not judged here; the address it connected to was
+ * judged before the socket opened, by {@link guardedDispatcher}.
  *
  * Deliberately **not** re-exported from `index.ts`. The guard is engaged by
  * `safeFetch`, which is the one sanctioned way out to the network (PO-185); an
@@ -78,6 +86,11 @@ export declare function connectionRefusal(err: unknown): NodeError | undefined;
  * actually reached (PO-184). A caller that opens its own request after
  * `assertPublicUrl` gets the check and not that second half.
  *
+ * A private address passes only where exactly that address **and** the URL's
+ * effective port are on the run's allow-list (PO-828, see `isAllowedTarget`) —
+ * every other answer still decides as before, so one allowed address among
+ * private ones does not carry the rest.
+ *
  * 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}.

package/dist/types.d.ts

@@ -3,7 +3,31 @@ export type LocalizedString = string | Record<string, string>;
 export type DataType = 'any' | 'object' | 'array' | 'string' | 'number' | 'boolean';
 export type OutputKind = 'default' | 'branch' | 'error';
 export type NodeCategory = 'trigger' | 'action' | 'transform' | 'control' | 'io';
-export type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'state-ref' | 'dynamic-schema';
+export type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'state-ref' | 'dynamic-schema' | 'vpn-route';
+/**
+ * What a node receives at run time for a `vpn-route` setting (PO-831).
+ *
+ * The editor stores `{ connection: string; route: string }`, or `null` (or no
+ * value) for the public internet. Before `execute`, the worker replaces a stored
+ * reference with the route as it stands now, so the node never resolves it
+ * itself; a connection that is not active fails the step as `VPN_UNAVAILABLE`,
+ * one that is gone as `VPN_ROUTE_MISSING` (see `VPN_ERROR_CODES`). A setting left
+ * on the public internet stays `null` or absent.
+ */
+export interface ResolvedVpnRoute {
+    /** The VPN connection's name. */
+    connection: string;
+    /** The route's name within that connection. */
+    route: string;
+    kind: 'http' | 'tcp';
+    /**
+     * Where the run reaches the route: for `http` a base URL
+     * (`http://10.31.0.7:8080/sap-odata/`), for `tcp` a `host:port`
+     * (`10.31.0.7:20001`). The address is on the run's allow-list, so
+     * `safeFetch` reaches it although it is private.
+     */
+    endpoint: string;
+}
 /**
  * Semantic category of an image, driving how the registry/CDN organises and
  * displays it.
@@ -186,6 +210,15 @@ export interface IConfigFieldBase {
      * the node whose config names it.
      */
     stateRole?: 'mapping' | 'cursor' | 'dedupe' | 'digest';
+    /**
+     * Only meaningful when `type === 'vpn-route'`: which kind of route the picker
+     * offers (PO-831) — `http` for a node that sends HTTP requests through the
+     * relay's proxy, `tcp` for one that opens a socket. Defaults to `'http'`.
+     *
+     * **Accepted by the registry only once integrations#406 is deployed** — until
+     * then a package declaring it is refused on upload.
+     */
+    routeKind?: 'http' | 'tcp';
 }
 export interface IConfigField extends IConfigFieldBase {
     /**
@@ -504,6 +537,29 @@ export interface ICredentialDescription {
     images?: IImage[];
     authKind: CredentialAuthKind;
     fields: ICredentialField[];
+    /**
+     * Which of this type's fields a VPN route replaces (PO-829). A type without it
+     * cannot be routed through a VPN, and the studio offers no choice.
+     *
+     * - `tcp` — the route's relay address and port replace the `hostField` and
+     *   `portField` values (both keys of `fields`).
+     * - `http` — the route's endpoint replaces the base of the `urlField` value,
+     *   keeping any path the author typed after it.
+     *
+     * The stored configuration is never rewritten; the platform substitutes the
+     * route's current endpoint each time the credential is tested or resolved.
+     *
+     * **Accepted by the registry only once integrations#406 is deployed** — until
+     * then a package declaring it is refused on upload.
+     */
+    network?: {
+        kind: 'tcp';
+        hostField: string;
+        portField: string;
+    } | {
+        kind: 'http';
+        urlField: string;
+    };
 }
 /**
  * Runtime context handed to a credential's `test`/`resolve`. Runs in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenexx/integrations-node-sdk",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "TypeScript interfaces and utilities for Revenexx integration nodes",
   "license": "MIT",
   "author": "revenexx GmbH",
@@ -63,6 +63,7 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "ipaddr.js": "2.5.0"
+    "ipaddr.js": "2.5.0",
+    "undici": "6.29.1"
   }
 }