@revenexx/integrations-node-sdk 1.10.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/branches.d.ts

@@ -0,0 +1,47 @@
+import type { INode, INodeDescription, INodeResult, IOutputPort } from './types.js';
+/**
+ * A node's output ports are alternatives: exactly one fires. A node with a
+ * single port has nothing to choose between, so its result may leave `branch`
+ * out; a node with several must say which one it took, because the worker
+ * otherwise activates every outgoing connection (PO-751).
+ *
+ * A node counts as multi-port when EITHER holds:
+ *  - more than one port is declared (an `error` port counts: `out` + `error` is two);
+ *  - a port is marked `resolveOutputs`, because that set is only known while the
+ *    author edits and may hold several.
+ *
+ * A single port is one way out however it is declared — of kind `branch`, or named
+ * from a setting by `sourceFromConfig` (one name, with its `fallback`).
+ */
+export declare function isMultiPort(outputs: readonly IOutputPort[] | undefined): boolean;
+/** A result that names its branch — what every multi-port node returns. */
+export interface IBranchedNodeResult extends INodeResult {
+    branch: string;
+}
+/**
+ * Declaration problems of a node's output ports that the manifest build can see.
+ * Returns one sentence per problem, empty when there is none.
+ *
+ * A node with several ports must give each fixed port a unique `name`, since `branch`
+ * names one of them, and a generated port's `fallback` name must not repeat a fixed
+ * one. (Whether `execute` really returns a `branch` cannot be read from a declaration
+ * — see {@link assertBranchNamed}.)
+ */
+export declare function outputProblems(description: INodeDescription): string[];
+/**
+ * The warnings `rvnxx-nodes manifest` prints for a package's nodes: every
+ * {@link outputProblems} finding, worded for the log. In 1.x they are warnings and the
+ * build continues; the next major turns them into errors.
+ */
+export declare function outputWarnings(nodes: readonly INode[]): string[];
+/**
+ * Check a result against the node's declaration. For a node's own tests:
+ * `assertBranchNamed(node, await node.execute(ctx, inputs), config)`.
+ *
+ * Throws when a multi-port node returned no `branch`, and when the branch is none of
+ * the names the node can produce: a fixed name is always accepted; beyond that, a
+ * `resolveOutputs` port accepts any name (it is unknown here), and a `sourceFromConfig`
+ * port accepts its fallback name and — when `config` is passed — the value it holds
+ * (with no `config`, any name). A single-port node may leave `branch` out.
+ */
+export declare function assertBranchNamed(node: INode | INodeDescription, result: INodeResult, config?: Record<string, unknown>): void;

package/dist/chunk-XO73F62E.js

@@ -0,0 +1,122 @@
+// src/branches.ts
+function isMultiPort(outputs) {
+  if (!outputs) return false;
+  return outputs.length > 1 || outputs.some((p) => p.resolveOutputs === true);
+}
+var isGenerated = (p) => p.sourceFromConfig !== void 0 || p.resolveOutputs === true;
+function outputProblems(description) {
+  const outputs = description.outputs ?? [];
+  if (!isMultiPort(outputs)) return [];
+  const problems = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [i, port] of outputs.entries()) {
+    if (isGenerated(port)) continue;
+    if (port.name === void 0 || port.name === "") {
+      problems.push(
+        `${description.slug}: output ${i + 1} has no name, so a branch cannot choose it \u2014 a node with several outputs must name each one.`
+      );
+    } else if (seen.has(port.name)) {
+      problems.push(`${description.slug}: output name "${port.name}" is declared twice.`);
+    } else {
+      seen.add(port.name);
+    }
+  }
+  for (const port of outputs) {
+    const fb = port.fallback?.name;
+    if (isGenerated(port) && fb !== void 0 && seen.has(fb)) {
+      problems.push(`${description.slug}: the fallback name "${fb}" is also the name of a fixed output, so a branch "${fb}" is ambiguous.`);
+    }
+  }
+  return problems;
+}
+function outputWarnings(nodes) {
+  return nodes.flatMap((n) => outputProblems(n.description));
+}
+function assertBranchNamed(node, result, config) {
+  const description = "execute" in node ? node.description : node;
+  const outputs = description.outputs ?? [];
+  if (!isMultiPort(outputs)) return;
+  const branch = result.branch;
+  if (typeof branch !== "string" || branch === "") {
+    throw new Error(
+      `${description.slug} has several outputs, so its result must name the branch it took; without it every output fires.`
+    );
+  }
+  if (outputs.some((p) => !isGenerated(p) && p.name === branch)) return;
+  const producible = outputs.some((p) => {
+    if (p.resolveOutputs === true) return true;
+    if (p.sourceFromConfig === void 0) return false;
+    if (p.fallback?.name === branch) return true;
+    return config === void 0 || config[p.sourceFromConfig] === branch;
+  });
+  if (!producible) {
+    const names = outputs.map((p) => p.name ?? p.fallback?.name).filter((n) => n);
+    throw new Error(
+      `${description.slug} returned branch "${branch}", which none of its outputs can produce (${names.join(", ")}).`
+    );
+  }
+}
+
+// src/extract.ts
+function extractManifest(node) {
+  return node.description;
+}
+function extractManifests(nodes) {
+  return nodes.map(extractManifest);
+}
+function extractCredentialManifest(credential) {
+  return credential.description;
+}
+function extractCredentialManifests(credentials) {
+  return credentials.map(extractCredentialManifest);
+}
+
+// src/manifest.ts
+var MANIFEST_VERSION = "v0-draft";
+var PACKAGE_ICON = /^lucide:[a-z0-9]+(-[a-z0-9]+)*$/;
+var PHP_TRIM = /^[ \t\n\r\0\v]+|[ \t\n\r\0\v]+$/g;
+function packageIconProblem(icon) {
+  if (icon === void 0 || PACKAGE_ICON.test(icon)) return void 0;
+  return `package.json "revenexx.icon" must be a Lucide icon name such as "lucide:bell", got "${icon}".`;
+}
+function parsePackageMeta(raw) {
+  const obj = raw && typeof raw === "object" ? raw : {};
+  const str = (v) => typeof v === "string" ? v.trim() : "";
+  const revenexx = obj.revenexx && typeof obj.revenexx === "object" ? obj.revenexx : {};
+  const displayName = str(revenexx.displayName);
+  const icon = typeof revenexx.icon === "string" ? revenexx.icon.replace(PHP_TRIM, "") : "";
+  return {
+    name: str(obj.name),
+    version: str(obj.version),
+    displayName: displayName !== "" ? displayName : void 0,
+    icon: icon !== "" ? icon : void 0
+  };
+}
+function buildManifest(nodes, credentials = [], templates = []) {
+  const manifest = {
+    manifestVersion: MANIFEST_VERSION,
+    nodes: extractManifests(nodes)
+  };
+  if (credentials.length > 0) {
+    manifest.credentials = extractCredentialManifests(credentials);
+  }
+  if (templates.length > 0) {
+    manifest.templates = templates;
+  }
+  return manifest;
+}
+
+export {
+  isMultiPort,
+  outputProblems,
+  outputWarnings,
+  assertBranchNamed,
+  extractManifest,
+  extractManifests,
+  extractCredentialManifest,
+  extractCredentialManifests,
+  MANIFEST_VERSION,
+  packageIconProblem,
+  parsePackageMeta,
+  buildManifest
+};

package/dist/cli.cjs

@@ -28,6 +28,41 @@ var fs2 = __toESM(require("fs"), 1);
 var import_node_path2 = require("path");
 var import_node_url = require("url");
 
+// src/branches.ts
+function isMultiPort(outputs) {
+  if (!outputs) return false;
+  return outputs.length > 1 || outputs.some((p) => p.resolveOutputs === true);
+}
+var isGenerated = (p) => p.sourceFromConfig !== void 0 || p.resolveOutputs === true;
+function outputProblems(description) {
+  const outputs = description.outputs ?? [];
+  if (!isMultiPort(outputs)) return [];
+  const problems = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [i, port] of outputs.entries()) {
+    if (isGenerated(port)) continue;
+    if (port.name === void 0 || port.name === "") {
+      problems.push(
+        `${description.slug}: output ${i + 1} has no name, so a branch cannot choose it \u2014 a node with several outputs must name each one.`
+      );
+    } else if (seen.has(port.name)) {
+      problems.push(`${description.slug}: output name "${port.name}" is declared twice.`);
+    } else {
+      seen.add(port.name);
+    }
+  }
+  for (const port of outputs) {
+    const fb = port.fallback?.name;
+    if (isGenerated(port) && fb !== void 0 && seen.has(fb)) {
+      problems.push(`${description.slug}: the fallback name "${fb}" is also the name of a fixed output, so a branch "${fb}" is ambiguous.`);
+    }
+  }
+  return problems;
+}
+function outputWarnings(nodes) {
+  return nodes.flatMap((n) => outputProblems(n.description));
+}
+
 // src/images.ts
 var fs = __toESM(require("fs"), 1);
 var import_node_path = require("path");
@@ -174,6 +209,9 @@ async function runManifest() {
       '\u26A0 package.json has no "revenexx.displayName" \u2014 the node palette will fall back to the raw package name.'
     );
   }
+  for (const w of outputWarnings(mod.NODES)) {
+    console.warn(`\u26A0 ${w} This will be an error in the next major version.`);
+  }
   const manifest = buildManifest(mod.NODES, credentials, templates);
   const outDir = (0, import_node_path2.resolve)(projectRoot, "dist");
   const outFile = (0, import_node_path2.resolve)(outDir, "manifest.json");

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import {
   buildManifest,
+  outputWarnings,
   packageIconProblem,
   parsePackageMeta
-} from "./chunk-5BCAXRU3.js";
+} from "./chunk-XO73F62E.js";
 
 // src/cli.ts
 import * as fs2 from "fs";
@@ -107,6 +108,9 @@ async function runManifest() {
       '\u26A0 package.json has no "revenexx.displayName" \u2014 the node palette will fall back to the raw package name.'
     );
   }
+  for (const w of outputWarnings(mod.NODES)) {
+    console.warn(`\u26A0 ${w} This will be an error in the next major version.`);
+  }
   const manifest = buildManifest(mod.NODES, credentials, templates);
   const outDir = resolve2(projectRoot, "dist");
   const outFile = resolve2(outDir, "manifest.json");

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,11 @@ __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,
   buildManifest: () => buildManifest,
@@ -63,13 +68,19 @@ __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,
+  outputProblems: () => outputProblems,
+  outputWarnings: () => outputWarnings,
   packageIconProblem: () => packageIconProblem,
   parsePackageMeta: () => parsePackageMeta,
   readArrayBuffer: () => readArrayBuffer,
@@ -209,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) {
@@ -294,10 +311,184 @@ function extractCredentialManifests(credentials) {
   return credentials.map(extractCredentialManifest);
 }
 
+// src/branches.ts
+function isMultiPort(outputs) {
+  if (!outputs) return false;
+  return outputs.length > 1 || outputs.some((p) => p.resolveOutputs === true);
+}
+var isGenerated = (p) => p.sourceFromConfig !== void 0 || p.resolveOutputs === true;
+function outputProblems(description) {
+  const outputs = description.outputs ?? [];
+  if (!isMultiPort(outputs)) return [];
+  const problems = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [i, port] of outputs.entries()) {
+    if (isGenerated(port)) continue;
+    if (port.name === void 0 || port.name === "") {
+      problems.push(
+        `${description.slug}: output ${i + 1} has no name, so a branch cannot choose it \u2014 a node with several outputs must name each one.`
+      );
+    } else if (seen.has(port.name)) {
+      problems.push(`${description.slug}: output name "${port.name}" is declared twice.`);
+    } else {
+      seen.add(port.name);
+    }
+  }
+  for (const port of outputs) {
+    const fb = port.fallback?.name;
+    if (isGenerated(port) && fb !== void 0 && seen.has(fb)) {
+      problems.push(`${description.slug}: the fallback name "${fb}" is also the name of a fixed output, so a branch "${fb}" is ambiguous.`);
+    }
+  }
+  return problems;
+}
+function outputWarnings(nodes) {
+  return nodes.flatMap((n) => outputProblems(n.description));
+}
+function assertBranchNamed(node, result, config) {
+  const description = "execute" in node ? node.description : node;
+  const outputs = description.outputs ?? [];
+  if (!isMultiPort(outputs)) return;
+  const branch = result.branch;
+  if (typeof branch !== "string" || branch === "") {
+    throw new Error(
+      `${description.slug} has several outputs, so its result must name the branch it took; without it every output fires.`
+    );
+  }
+  if (outputs.some((p) => !isGenerated(p) && p.name === branch)) return;
+  const producible = outputs.some((p) => {
+    if (p.resolveOutputs === true) return true;
+    if (p.sourceFromConfig === void 0) return false;
+    if (p.fallback?.name === branch) return true;
+    return config === void 0 || config[p.sourceFromConfig] === branch;
+  });
+  if (!producible) {
+    const names = outputs.map((p) => p.name ?? p.fallback?.name).filter((n) => n);
+    throw new Error(
+      `${description.slug} returned branch "${branch}", which none of its outputs can produce (${names.join(", ")}).`
+    );
+  }
+}
+
 // 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");
@@ -309,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;
   }
@@ -403,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;
@@ -457,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;
@@ -467,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);
   }
 }
 
@@ -567,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;
@@ -1235,6 +1493,11 @@ function base64Url(buf) {
   RetryableError,
   SimpleValueCredential,
   VALUELESS_OPERATORS,
+  VPN_ERROR_CODES,
+  VPN_ROUTE_MISSING,
+  VPN_UNAVAILABLE,
+  allowedTargets,
+  assertBranchNamed,
   assertPublicUrl,
   backoffDelay,
   buildManifest,
@@ -1248,13 +1511,19 @@ function base64Url(buf) {
   extractManifests,
   headerCrossesOrigin,
   httpErrorResult,
+  installAllowedTargets,
+  isAllowedTarget,
   isBlockedAddress,
+  isMultiPort,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
   isOperator,
+  isVpnErrorCode,
   maxBytesConfigField,
   normalizeCredentialType,
   normalizeLocalized,
+  outputProblems,
+  outputWarnings,
   packageIconProblem,
   parsePackageMeta,
   readArrayBuffer,

package/dist/index.d.ts

@@ -6,9 +6,11 @@ export * from './credentialType.js';
 export * from './errors.js';
 export * from './nodeErrors.js';
 export * from './extract.js';
+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

@@ -1,13 +1,17 @@
 import {
   MANIFEST_VERSION,
+  assertBranchNamed,
   buildManifest,
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
   extractManifests,
+  isMultiPort,
+  outputProblems,
+  outputWarnings,
   packageIconProblem,
   parsePackageMeta
-} from "./chunk-5BCAXRU3.js";
+} from "./chunk-XO73F62E.js";
 
 // src/types.ts
 function isNodeWithIteration(node) {
@@ -131,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) {
@@ -204,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");
@@ -217,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;
   }
@@ -311,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;
@@ -365,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;
@@ -375,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);
   }
 }
 
@@ -475,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;
@@ -1107,6 +1299,11 @@ export {
   RetryableError,
   SimpleValueCredential,
   VALUELESS_OPERATORS,
+  VPN_ERROR_CODES,
+  VPN_ROUTE_MISSING,
+  VPN_UNAVAILABLE,
+  allowedTargets,
+  assertBranchNamed,
   assertPublicUrl,
   backoffDelay,
   buildManifest,
@@ -1120,13 +1317,19 @@ export {
   extractManifests,
   headerCrossesOrigin,
   httpErrorResult,
+  installAllowedTargets,
+  isAllowedTarget,
   isBlockedAddress,
+  isMultiPort,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
   isOperator,
+  isVpnErrorCode,
   maxBytesConfigField,
   normalizeCredentialType,
   normalizeLocalized,
+  outputProblems,
+  outputWarnings,
   packageIconProblem,
   parsePackageMeta,
   readArrayBuffer,

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 {
     /**
@@ -368,6 +401,14 @@ export interface INodeState {
 }
 export interface INodeResult {
     outputs: Record<string, unknown>;
+    /**
+     * The output port the node took. Output ports are alternatives — exactly one
+     * fires — so a node with more than one output (an `error` port counts) must
+     * name it; only a node with a single output may omit it. The worker fails such
+     * a step from the integrations release that carries PO-751; until then a result
+     * without `branch` fires every output. See `isMultiPort` for what counts as
+     * several, and `assertBranchNamed` to check a result in the node's own tests.
+     */
     branch?: string;
 }
 /**
@@ -496,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.10.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"
   }
 }

package/dist/chunk-5BCAXRU3.js

@@ -1,59 +0,0 @@
-// src/extract.ts
-function extractManifest(node) {
-  return node.description;
-}
-function extractManifests(nodes) {
-  return nodes.map(extractManifest);
-}
-function extractCredentialManifest(credential) {
-  return credential.description;
-}
-function extractCredentialManifests(credentials) {
-  return credentials.map(extractCredentialManifest);
-}
-
-// src/manifest.ts
-var MANIFEST_VERSION = "v0-draft";
-var PACKAGE_ICON = /^lucide:[a-z0-9]+(-[a-z0-9]+)*$/;
-var PHP_TRIM = /^[ \t\n\r\0\v]+|[ \t\n\r\0\v]+$/g;
-function packageIconProblem(icon) {
-  if (icon === void 0 || PACKAGE_ICON.test(icon)) return void 0;
-  return `package.json "revenexx.icon" must be a Lucide icon name such as "lucide:bell", got "${icon}".`;
-}
-function parsePackageMeta(raw) {
-  const obj = raw && typeof raw === "object" ? raw : {};
-  const str = (v) => typeof v === "string" ? v.trim() : "";
-  const revenexx = obj.revenexx && typeof obj.revenexx === "object" ? obj.revenexx : {};
-  const displayName = str(revenexx.displayName);
-  const icon = typeof revenexx.icon === "string" ? revenexx.icon.replace(PHP_TRIM, "") : "";
-  return {
-    name: str(obj.name),
-    version: str(obj.version),
-    displayName: displayName !== "" ? displayName : void 0,
-    icon: icon !== "" ? icon : void 0
-  };
-}
-function buildManifest(nodes, credentials = [], templates = []) {
-  const manifest = {
-    manifestVersion: MANIFEST_VERSION,
-    nodes: extractManifests(nodes)
-  };
-  if (credentials.length > 0) {
-    manifest.credentials = extractCredentialManifests(credentials);
-  }
-  if (templates.length > 0) {
-    manifest.templates = templates;
-  }
-  return manifest;
-}
-
-export {
-  extractManifest,
-  extractManifests,
-  extractCredentialManifest,
-  extractCredentialManifests,
-  MANIFEST_VERSION,
-  packageIconProblem,
-  parsePackageMeta,
-  buildManifest
-};