@revenexx/integrations-node-sdk 1.11.0 → 1.14.0

package/dist/index.js

@@ -1,5 +1,9 @@
 import {
+  CONFIG_KEY_PATTERN,
   MANIFEST_VERSION,
+  NAMESPACED_SLUG_PATTERN,
+  SEMVER_PATTERN,
+  SLUG_PATTERN,
   assertBranchNamed,
   buildManifest,
   extractCredentialManifest,
@@ -7,11 +11,12 @@ import {
   extractManifest,
   extractManifests,
   isMultiPort,
+  nodeManifestProblems,
   outputProblems,
   outputWarnings,
   packageIconProblem,
   parsePackageMeta
-} from "./chunk-XO73F62E.js";
+} from "./chunk-CA6JVLLF.js";
 
 // src/types.ts
 function isNodeWithIteration(node) {
@@ -135,6 +140,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 +219,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 +347,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;
   }
@@ -246,19 +372,25 @@ function guardRelaxedForLocalDev() {
   if (relaxed && !bypassNoticeLogged) {
     bypassNoticeLogged = true;
     console.warn(
-      "[ssrf] RVNXX_SSRF_ALLOW_PRIVATE is set: allowing private/loopback fetch targets. Intended for local development only."
+      "[ssrf] RVNXX_SSRF_ALLOW_PRIVATE is set: allowing private/loopback targets for web requests and connections. Intended for local development only."
     );
   }
   return relaxed;
 }
+function logBlocked(noun, host, address) {
+  console.warn(`[ssrf] blocked ${noun} to ${host}: resolves to private/reserved address ${address}`);
+}
 function blockedError(host, address) {
   if (host === address) {
     return new NodeError("BLOCKED_ADDRESS", `Blocked request to private or reserved address ${address}`, {
       status: 0
     });
   }
-  console.warn(`[ssrf] blocked request to ${host}: resolves to private/reserved address ${address}`);
-  return new NodeError("BLOCKED_ADDRESS", `Blocked request to ${host}: resolves to a private or reserved address`, {
+  logBlocked("request", host, address);
+  return refusedName(host);
+}
+function refusedName(host, noun = "request") {
+  return new NodeError("BLOCKED_ADDRESS", `Blocked ${noun} to ${host}: resolves to a private or reserved address`, {
     status: 0
   });
 }
@@ -315,8 +447,86 @@ 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 lookupJudgedFor(port, { noun: "request" }, (hostname) => new NodeError("BLOCKED_ADDRESS", `Could not resolve host: ${hostname}`, { status: 0 }));
+}
+function guardedLookup(port, options = {}) {
+  return lookupJudgedFor(
+    port,
+    options,
+    (hostname) => Object.assign(new Error(`getaddrinfo ENOTFOUND ${hostname}`), { code: "ENOTFOUND", hostname })
+  );
+}
+function lookupJudgedFor(port, { refusal, unroutable, noun = "connection" }, emptyAnswer) {
+  return (hostname, options, callback) => {
+    dns.lookup(hostname, { ...options, all: true }, (err, addresses) => {
+      if (err) {
+        callback(err, "");
+        return;
+      }
+      if (addresses.length === 0) {
+        callback(emptyAnswer(hostname), "");
+        return;
+      }
+      if (!guardRelaxedForLocalDev()) {
+        const host = hostname;
+        for (const a of addresses) {
+          if (!isBlockedAddress(a.address)) continue;
+          const allowed = isAllowedTarget(a.address, port);
+          if (allowed && !unroutable) continue;
+          logBlocked(noun, host, a.address);
+          callback(allowed && unroutable ? unroutable(host) : refusal ? refusal(host) : refusedName(host, noun), "");
+          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 +579,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 +591,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);
   }
 }
 
@@ -474,34 +686,84 @@ function credentialOriginRefusal(target, bound, hop) {
     { status: 0 }
   );
 }
-async function timedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
+function attemptDeadline(ctxSignal, effectiveMs) {
   const ac = new AbortController();
-  const timer = setTimeout(() => ac.abort(), effectiveMs);
-  const signal = ctxSignal ? AbortSignal.any([ctxSignal, ac.signal]) : ac.signal;
+  let timer;
+  const arm = (message) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => ac.abort(new NodeError("TIMEOUT", message)), effectiveMs);
+  };
+  arm(`Request timed out after ${effectiveMs}ms`);
+  return {
+    signal: ctxSignal ? AbortSignal.any([ctxSignal, ac.signal]) : ac.signal,
+    expired: () => ac.signal.aborted,
+    reason: () => ac.signal.reason,
+    clear: () => clearTimeout(timer),
+    awaitChunk: () => arm(`The answer sent nothing for ${effectiveMs}ms`)
+  };
+}
+function attemptFailure(err, ctxSignal, deadline) {
+  if (ctxSignal?.aborted) return ctxSignal.reason;
+  if (deadline.expired()) return deadline.reason();
+  return err;
+}
+function answerUnderDeadline(res, ctxSignal, deadline) {
+  if (!res.body) return res;
+  let reader;
+  const body = new ReadableStream(
+    {
+      async pull(controller) {
+        reader ??= res.body.getReader();
+        deadline.awaitChunk();
+        try {
+          const { done, value } = await reader.read();
+          if (done) controller.close();
+          else controller.enqueue(value);
+        } catch (err) {
+          controller.error(attemptFailure(err, ctxSignal, deadline));
+        } finally {
+          deadline.clear();
+        }
+      },
+      cancel(reason) {
+        deadline.clear();
+        return reader ? reader.cancel(reason) : res.body?.cancel(reason);
+      }
+    },
+    // Read nothing ahead of the caller: the limit times the caller's waits, not
+    // a buffer filling while nobody reads.
+    { highWaterMark: 0 }
+  );
+  let answer;
+  try {
+    answer = new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
+  } catch {
+    return res;
+  }
+  return withUrl(answer, res.url);
+}
+function withUrl(answer, url) {
+  const clone = answer.clone.bind(answer);
+  Object.defineProperty(answer, "url", { value: url });
+  Object.defineProperty(answer, "clone", { value: () => withUrl(clone(), url) });
+  return answer;
+}
+async function timedFetch(url, fetchOptions, ctxSignal, deadline) {
   try {
-    return await fetch(url, { ...fetchOptions, signal });
+    return await fetch(url, { ...fetchOptions, signal: deadline.signal, dispatcher: guardedDispatcher() });
   } 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;
-  } finally {
-    clearTimeout(timer);
+    throw attemptFailure(err, ctxSignal, deadline);
   }
 }
-async function guardUrl(url, ctxSignal, effectiveMs) {
-  const ac = new AbortController();
-  const timer = setTimeout(() => ac.abort(), effectiveMs);
-  const signal = ctxSignal ? AbortSignal.any([ctxSignal, ac.signal]) : ac.signal;
+async function guardUrl(url, ctxSignal, deadline, effectiveMs) {
   try {
-    await assertPublicUrl(url, { signal });
+    await assertPublicUrl(url, { signal: deadline.signal });
   } catch (err) {
     if (ctxSignal?.aborted) throw ctxSignal.reason;
-    if (ac.signal.aborted) throw new NodeError("TIMEOUT", `DNS resolution timed out after ${effectiveMs}ms`);
+    if (deadline.expired()) throw new NodeError("TIMEOUT", `DNS resolution timed out after ${effectiveMs}ms`);
     throw err;
-  } finally {
-    clearTimeout(timer);
   }
 }
 function hasContent(body) {
@@ -523,16 +785,27 @@ function refuseUserinfo(url, status = 0) {
   }
 }
 async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, binding) {
+  const deadline = attemptDeadline(ctxSignal, effectiveMs);
+  try {
+    const res = await followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, binding);
+    deadline.clear();
+    return answerUnderDeadline(res, ctxSignal, deadline);
+  } catch (err) {
+    deadline.clear();
+    throw err;
+  }
+}
+async function followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, binding) {
   let currentUrl = url;
   let currentInit = { ...fetchOptions, redirect: "manual" };
-  await guardUrl(currentUrl, ctxSignal, effectiveMs);
+  await guardUrl(currentUrl, ctxSignal, deadline, effectiveMs);
   for (let hop = 0; ; hop++) {
     const release = guardConnectionsTo(
       currentUrl instanceof URL ? currentUrl : new URL(currentUrl)
     );
     let res;
     try {
-      res = await timedFetch(currentUrl, currentInit, ctxSignal, effectiveMs);
+      res = await timedFetch(currentUrl, currentInit, ctxSignal, deadline);
     } finally {
       release();
     }
@@ -574,7 +847,7 @@ async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, binding)
         { status: 0 }
       );
     }
-    await guardUrl(nextUrl, ctxSignal, effectiveMs);
+    await guardUrl(nextUrl, ctxSignal, deadline, effectiveMs);
     if (binding && nextUrl.origin !== binding.origin) {
       for (const name of [...headers.keys()]) headers.delete(name);
     } else if (nextUrl.origin !== base.origin) {
@@ -722,8 +995,8 @@ function timeoutConfigField(opts) {
     key: "timeoutMs",
     label: { en: "Timeout (ms)", de: "Zeitlimit (ms)" },
     description: {
-      en: "How long one attempt may take before it fails as a timeout. Counted per attempt and per redirect hop, not across the whole call.",
-      de: "Wie lange ein einzelner Versuch dauern darf, bevor er als Zeit\xFCberschreitung fehlschl\xE4gt. Gilt je Versuch und je Weiterleitung, nicht f\xFCr den gesamten Aufruf."
+      en: "How long one attempt may wait for an answer to start, redirects included, and how long the answer may then go silent before it fails as a timeout. An answer that keeps arriving is not cut off. Each retry gets the time again.",
+      de: "Wie lange ein einzelner Versuch auf den Beginn einer Antwort warten darf, Weiterleitungen eingeschlossen, und wie lange die Antwort danach stocken darf, bevor sie als Zeit\xFCberschreitung fehlschl\xE4gt. Eine Antwort, die weiter eintrifft, wird nicht abgebrochen. Jede Wiederholung bekommt die Zeit erneut."
     },
     type: "number",
     default: opts?.default ?? DEFAULT_TIMEOUT_MS,
@@ -1094,6 +1367,7 @@ export {
   ApiKeyCredential,
   BaseCredential,
   BasicAuthCredential,
+  CONFIG_KEY_PATTERN,
   DEFAULT_MAX_RESPONSE_BYTES,
   DEFAULT_RETRY_ATTEMPTS,
   DEFAULT_RETRY_DELAY_MS,
@@ -1104,13 +1378,20 @@ export {
   MAX_RESPONSE_BYTES,
   MAX_RETRY_ATTEMPTS,
   MAX_TIMEOUT_MS,
+  NAMESPACED_SLUG_PATTERN,
   NodeError,
   OAuth2AuthCodeCredential,
   OAuth2ClientCredentialsCredential,
   OPERATORS,
   RetryableError,
+  SEMVER_PATTERN,
+  SLUG_PATTERN,
   SimpleValueCredential,
   VALUELESS_OPERATORS,
+  VPN_ERROR_CODES,
+  VPN_ROUTE_MISSING,
+  VPN_UNAVAILABLE,
+  allowedTargets,
   assertBranchNamed,
   assertPublicUrl,
   backoffDelay,
@@ -1123,14 +1404,20 @@ export {
   extractCredentialManifests,
   extractManifest,
   extractManifests,
+  guardRelaxedForLocalDev,
+  guardedLookup,
   headerCrossesOrigin,
   httpErrorResult,
+  installAllowedTargets,
+  isAllowedTarget,
   isBlockedAddress,
   isMultiPort,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
   isOperator,
+  isVpnErrorCode,
   maxBytesConfigField,
+  nodeManifestProblems,
   normalizeCredentialType,
   normalizeLocalized,
   outputProblems,

package/dist/manifest.d.ts

@@ -73,6 +73,31 @@ export declare function packageIconProblem(icon: string | undefined): string | u
  * enforces that on upload; this is a typed, lenient read for tooling.
  */
 export declare function parsePackageMeta(raw: unknown): NodePackageMeta;
+/**
+ * The name patterns the registry enforces on a node's manifest when a package is
+ * uploaded (PO-744), as written in the integrations service's node schema
+ * (`app/Support/Schema/Versions/Node/V0DraftSchema.php`, read at `973b28c2`, 27
+ * October 2026), under the same names. A copy, not a shared source: a change on
+ * either side has to be made on both. They are exported as the schema's text, so
+ * a test on the other side can compare them byte for byte.
+ */
+/** A port name, `sourceFromConfig` and `fallback.name`: lowercase kebab-case. */
+export declare const SLUG_PATTERN = "^[a-z][a-z0-9-]{0,62}$";
+/** A node's `slug`, and a credential type a setting names: `<namespace>:<slug>`. */
+export declare const NAMESPACED_SLUG_PATTERN = "^[a-z][a-z0-9-]{0,62}:[a-z][a-z0-9-]{0,62}$";
+/** A node's `version`. */
+export declare const SEMVER_PATTERN = "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?$";
+/** A setting's `key`, `dependsOn[]` and `showIf.key`: camelCase is allowed here, unlike in a port name. */
+export declare const CONFIG_KEY_PATTERN = "^[a-zA-Z][a-zA-Z0-9-]*$";
+/**
+ * Why the registry would refuse these nodes' names on upload, one line per value,
+ * or `[]` when it would accept them (PO-744). Each line names the node, the path
+ * of the field, the value and the pattern. Only values that are present are
+ * judged: a missing slug or version is the schema's other rule, and a port may
+ * leave its name out. Settings are walked into `properties` and `items` at any
+ * depth; the schema allows less, so none is missed.
+ */
+export declare function nodeManifestProblems(nodes: readonly INodeDescription[]): string[];
 /**
  * Builds the manifest envelope from a package's `NODES` (and optional
  * `CREDENTIALS` / `TEMPLATES`) exports. The result is what gets written to

package/dist/ssrf.d.ts

@@ -1,3 +1,5 @@
+import { type LookupFunction } from 'node:net';
+import { Agent } from 'undici';
 import { NodeError } from './errors.js';
 /**
  * A resolved DNS address, mirroring the shape of Node's `dns.LookupAddress`.
@@ -39,6 +41,51 @@ export declare const ssrfResolver: {
  * Promised behaviour: specs/ssrf-guard.md (AC-9, AC-11, AC-19).
  */
 export declare function isBlockedAddress(ip: string): boolean;
+export declare function guardRelaxedForLocalDev(): boolean;
+/** How a connection that `safeFetch` does not make reports what {@link guardedLookup} decides. */
+export interface GuardedLookupOptions {
+    /**
+     * The error a refused name fails with. It is handed to the caller and may reach
+     * a workflow author, so it names the host and never an address it resolved to.
+     * Default: `Blocked <noun> to <host>: resolves to a private or reserved
+     * address`, code `BLOCKED_ADDRESS` — `safeFetch`'s words with this lookup's noun.
+     */
+    refusal?: (host: string) => Error;
+    /**
+     * For a client a VPN route cannot carry: a private address on the run's
+     * allow-list is refused with this error instead of passing. Absent, the
+     * allow-list applies as it does to `safeFetch`.
+     */
+    unroutable?: (host: string) => Error;
+    /** The noun of the operator's log line, `[ssrf] blocked <noun> to …`, and of the default refusal. Default `'connection'`. */
+    noun?: 'request' | 'connection';
+}
+/**
+ * A socket lookup, shaped like `net.LookupFunction`, that judges every address a
+ * name resolves to by the rule `safeFetch` connects under (PO-698) — for a client
+ * that opens its own socket (FTP, SFTP, a plain `node:http` stream) and so never
+ * meets `safeFetch`. Pass it as the socket's `lookup` with the port it connects to.
+ *
+ * The check runs inside the socket's own name resolution, so the socket can only
+ * reach addresses that were judged, with no second lookup a changed DNS answer
+ * could slip through, and Node still tries every approved address in turn. A
+ * name is refused when any address is private or reserved and not on the run's
+ * allow-list for `port` (PO-828); the refusal is logged for the operator; the
+ * local-development switch ({@link guardRelaxedForLocalDev}) relaxes it. A name
+ * that does not resolve fails as the resolver said, not as a refusal.
+ *
+ * **Node calls no lookup for a host written as an address**, so a literal never
+ * reaches this. A caller judges a literal itself, with `isBlockedAddress` and
+ * `isAllowedTarget`, before it opens the socket.
+ */
+export declare function guardedLookup(port: number, options?: GuardedLookupOptions): LookupFunction;
+/**
+ * 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 +95,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 +125,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}.