mcp-from-openapi 2.5.0 → 2.5.1

package/esm/index.mjs

@@ -892,8 +892,15 @@ function isBlockedHostname(hostname, ssrf) {
   if (BLOCKED_HOSTNAMES.has(lower) || BLOCKED_HOSTNAMES.has(stripped)) return true;
   return isBlockedAddress(hostname);
 }
+var SsrfResolverUnavailableError = class extends Error {
+};
 var defaultLookup = async (hostname) => {
-  const dns = await import("node:dns");
+  let dns;
+  try {
+    dns = await import("node:dns");
+  } catch {
+    throw new SsrfResolverUnavailableError("DNS resolution is unavailable on this runtime");
+  }
   return dns.promises.lookup(hostname, { all: true });
 };
 async function assertUrlSafe(url, ssrf, lookup = defaultLookup) {
@@ -915,43 +922,133 @@ async function assertUrlSafe(url, ssrf, lookup = defaultLookup) {
     if (ssrf.blockedHosts.includes(hostname)) {
       throw new SsrfError(`Host "${hostname}" is blocked`, { url });
     }
-    return;
+    return [];
   }
   if (isBlockedHostname(hostname, ssrf)) {
     throw new SsrfError(`Host "${hostname}" maps to a blocked internal address`, { url });
   }
-  if (!isIpLiteral(hostname)) {
-    let addresses;
-    try {
-      addresses = await lookup(hostname);
-    } catch {
-      return;
+  if (isIpLiteral(hostname)) {
+    return [];
+  }
+  let addresses;
+  try {
+    addresses = await lookup(hostname);
+  } catch (error) {
+    if (error instanceof SsrfResolverUnavailableError) {
+      return [];
     }
-    for (const { address } of addresses) {
-      if (isBlockedAddress(address)) {
-        throw new SsrfError(`Host "${hostname}" resolves to blocked address ${address}`, { url });
-      }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new SsrfError(`Host "${hostname}" could not be resolved for SSRF validation: ${message}`, { url });
+  }
+  if (addresses.length === 0) {
+    throw new SsrfError(`Host "${hostname}" did not resolve to any address`, { url });
+  }
+  for (const { address } of addresses) {
+    if (isBlockedAddress(address)) {
+      throw new SsrfError(`Host "${hostname}" resolves to blocked address ${address}`, { url });
     }
   }
+  return addresses;
 }
-async function safeFetch(url, opts) {
-  const { headers, timeoutMs = 3e4, followRedirects = true, maxRedirects = 5, ssrf, lookup } = opts;
-  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
-  if (typeof fetchImpl !== "function") {
+var DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+async function loadNodeHttpModules() {
+  try {
+    const [http, https] = await Promise.all([import("node:http"), import("node:https")]);
+    return { http, https };
+  } catch {
+    return null;
+  }
+}
+function pickHttpModule(protocol, modules) {
+  return protocol === "https:" ? modules.https : modules.http;
+}
+function makePinnedLookup(pinned) {
+  return (_hostname, options, callback) => {
+    const done = typeof options === "function" ? options : callback;
+    const wantsAll = typeof options === "object" && options !== null && options.all === true;
+    if (wantsAll) {
+      done(
+        null,
+        pinned.map(({ address, family }) => ({ address, family }))
+      );
+    } else {
+      done(null, pinned[0].address, pinned[0].family);
+    }
+  };
+}
+var NULL_BODY_STATUS = /* @__PURE__ */ new Set([101, 103, 204, 205, 304]);
+function nodePinnedTransport(modules) {
+  return (url, { headers, signal, pinned, maxBytes }) => new Promise((resolve, reject) => {
+    const limit = maxBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    const lib = pickHttpModule(new URL(url).protocol, modules);
+    const requestOptions = {
+      method: "GET",
+      signal,
+      headers: { ...headers, "accept-encoding": "identity" }
+    };
+    if (pinned.length > 0) {
+      requestOptions["lookup"] = makePinnedLookup(pinned);
+    }
+    const request = lib.request(url, requestOptions, (response) => {
+      const chunks = [];
+      let received = 0;
+      response.on("data", (chunk) => {
+        received += chunk.length;
+        if (received > limit) {
+          request.destroy();
+          reject(new SsrfError(`Response body exceeds ${limit} bytes`, { url }));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => {
+        const status = response.statusCode;
+        const responseHeaders = new Headers();
+        const entries = Object.entries(response.headers);
+        for (const [key, value] of entries) {
+          if (Array.isArray(value)) {
+            for (const item of value) responseHeaders.append(key, item);
+          } else {
+            responseHeaders.append(key, value);
+          }
+        }
+        const body = NULL_BODY_STATUS.has(status) ? null : Buffer.concat(chunks);
+        resolve(new Response(body, { status, statusText: response.statusMessage, headers: responseHeaders }));
+      });
+      response.on("error", reject);
+    });
+    request.on("error", reject);
+    request.end();
+  });
+}
+function fetchTransport(fetchImpl) {
+  return (url, { headers, signal }) => fetchImpl(url, { headers, signal, redirect: "manual" });
+}
+async function selectTransport(opts, url) {
+  if (opts.fetchImpl) {
+    return fetchTransport(opts.fetchImpl);
+  }
+  const modules = await loadNodeHttpModules();
+  if (!modules) {
+    const platformFetch = globalThis.fetch;
+    if (typeof platformFetch === "function") {
+      return fetchTransport(platformFetch);
+    }
     throw new SsrfError("No fetch implementation available to load OpenAPI spec from URL", { url });
   }
+  return nodePinnedTransport(modules);
+}
+async function safeFetch(url, opts) {
+  const { headers, timeoutMs = 3e4, followRedirects = true, maxRedirects = 5, ssrf, lookup } = opts;
+  const transport = await selectTransport(opts, url);
   let current = url;
   for (let hop = 0; hop <= maxRedirects; hop++) {
-    await assertUrlSafe(current, ssrf, lookup);
+    const pinned = await assertUrlSafe(current, ssrf, lookup);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     let response;
     try {
-      response = await fetchImpl(current, {
-        headers,
-        signal: controller.signal,
-        redirect: "manual"
-      });
+      response = await transport(current, { headers, signal: controller.signal, pinned, maxBytes: opts.maxResponseBytes });
     } finally {
       clearTimeout(timer);
     }

package/esm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Production-ready library for converting OpenAPI specifications into MCP tool definitions",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",

package/index.js

@@ -953,8 +953,15 @@ function isBlockedHostname(hostname, ssrf) {
   if (BLOCKED_HOSTNAMES.has(lower) || BLOCKED_HOSTNAMES.has(stripped)) return true;
   return isBlockedAddress(hostname);
 }
+var SsrfResolverUnavailableError = class extends Error {
+};
 var defaultLookup = async (hostname) => {
-  const dns = await import("node:dns");
+  let dns;
+  try {
+    dns = await import("node:dns");
+  } catch {
+    throw new SsrfResolverUnavailableError("DNS resolution is unavailable on this runtime");
+  }
   return dns.promises.lookup(hostname, { all: true });
 };
 async function assertUrlSafe(url, ssrf, lookup = defaultLookup) {
@@ -976,43 +983,133 @@ async function assertUrlSafe(url, ssrf, lookup = defaultLookup) {
     if (ssrf.blockedHosts.includes(hostname)) {
       throw new SsrfError(`Host "${hostname}" is blocked`, { url });
     }
-    return;
+    return [];
   }
   if (isBlockedHostname(hostname, ssrf)) {
     throw new SsrfError(`Host "${hostname}" maps to a blocked internal address`, { url });
   }
-  if (!isIpLiteral(hostname)) {
-    let addresses;
-    try {
-      addresses = await lookup(hostname);
-    } catch {
-      return;
+  if (isIpLiteral(hostname)) {
+    return [];
+  }
+  let addresses;
+  try {
+    addresses = await lookup(hostname);
+  } catch (error) {
+    if (error instanceof SsrfResolverUnavailableError) {
+      return [];
     }
-    for (const { address } of addresses) {
-      if (isBlockedAddress(address)) {
-        throw new SsrfError(`Host "${hostname}" resolves to blocked address ${address}`, { url });
-      }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new SsrfError(`Host "${hostname}" could not be resolved for SSRF validation: ${message}`, { url });
+  }
+  if (addresses.length === 0) {
+    throw new SsrfError(`Host "${hostname}" did not resolve to any address`, { url });
+  }
+  for (const { address } of addresses) {
+    if (isBlockedAddress(address)) {
+      throw new SsrfError(`Host "${hostname}" resolves to blocked address ${address}`, { url });
     }
   }
+  return addresses;
 }
-async function safeFetch(url, opts) {
-  const { headers, timeoutMs = 3e4, followRedirects = true, maxRedirects = 5, ssrf, lookup } = opts;
-  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
-  if (typeof fetchImpl !== "function") {
+var DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+async function loadNodeHttpModules() {
+  try {
+    const [http, https] = await Promise.all([import("node:http"), import("node:https")]);
+    return { http, https };
+  } catch {
+    return null;
+  }
+}
+function pickHttpModule(protocol, modules) {
+  return protocol === "https:" ? modules.https : modules.http;
+}
+function makePinnedLookup(pinned) {
+  return (_hostname, options, callback) => {
+    const done = typeof options === "function" ? options : callback;
+    const wantsAll = typeof options === "object" && options !== null && options.all === true;
+    if (wantsAll) {
+      done(
+        null,
+        pinned.map(({ address, family }) => ({ address, family }))
+      );
+    } else {
+      done(null, pinned[0].address, pinned[0].family);
+    }
+  };
+}
+var NULL_BODY_STATUS = /* @__PURE__ */ new Set([101, 103, 204, 205, 304]);
+function nodePinnedTransport(modules) {
+  return (url, { headers, signal, pinned, maxBytes }) => new Promise((resolve, reject) => {
+    const limit = maxBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    const lib = pickHttpModule(new URL(url).protocol, modules);
+    const requestOptions = {
+      method: "GET",
+      signal,
+      headers: { ...headers, "accept-encoding": "identity" }
+    };
+    if (pinned.length > 0) {
+      requestOptions["lookup"] = makePinnedLookup(pinned);
+    }
+    const request = lib.request(url, requestOptions, (response) => {
+      const chunks = [];
+      let received = 0;
+      response.on("data", (chunk) => {
+        received += chunk.length;
+        if (received > limit) {
+          request.destroy();
+          reject(new SsrfError(`Response body exceeds ${limit} bytes`, { url }));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => {
+        const status = response.statusCode;
+        const responseHeaders = new Headers();
+        const entries = Object.entries(response.headers);
+        for (const [key, value] of entries) {
+          if (Array.isArray(value)) {
+            for (const item of value) responseHeaders.append(key, item);
+          } else {
+            responseHeaders.append(key, value);
+          }
+        }
+        const body = NULL_BODY_STATUS.has(status) ? null : Buffer.concat(chunks);
+        resolve(new Response(body, { status, statusText: response.statusMessage, headers: responseHeaders }));
+      });
+      response.on("error", reject);
+    });
+    request.on("error", reject);
+    request.end();
+  });
+}
+function fetchTransport(fetchImpl) {
+  return (url, { headers, signal }) => fetchImpl(url, { headers, signal, redirect: "manual" });
+}
+async function selectTransport(opts, url) {
+  if (opts.fetchImpl) {
+    return fetchTransport(opts.fetchImpl);
+  }
+  const modules = await loadNodeHttpModules();
+  if (!modules) {
+    const platformFetch = globalThis.fetch;
+    if (typeof platformFetch === "function") {
+      return fetchTransport(platformFetch);
+    }
     throw new SsrfError("No fetch implementation available to load OpenAPI spec from URL", { url });
   }
+  return nodePinnedTransport(modules);
+}
+async function safeFetch(url, opts) {
+  const { headers, timeoutMs = 3e4, followRedirects = true, maxRedirects = 5, ssrf, lookup } = opts;
+  const transport = await selectTransport(opts, url);
   let current = url;
   for (let hop = 0; hop <= maxRedirects; hop++) {
-    await assertUrlSafe(current, ssrf, lookup);
+    const pinned = await assertUrlSafe(current, ssrf, lookup);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     let response;
     try {
-      response = await fetchImpl(current, {
-        headers,
-        signal: controller.signal,
-        redirect: "manual"
-      });
+      response = await transport(current, { headers, signal: controller.signal, pinned, maxBytes: opts.maxResponseBytes });
     } finally {
       clearTimeout(timer);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Production-ready library for converting OpenAPI specifications into MCP tool definitions",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",

package/ssrf.d.ts

@@ -20,17 +20,25 @@
  *     multicast / unspecified / reserved ranges and cloud-metadata endpoints;
  *   - resolves the hostname (Node, via `node:dns`) and rejects if **any**
  *     resolved address is internal — closing the DNS-name-to-internal bypass;
+ *   - **pins the connection to the validated IP**: on Node, {@link safeFetch}
+ *     connects through `node:http`/`node:https` with a custom `lookup` that
+ *     returns the exact address {@link assertUrlSafe} just validated, so the
+ *     guard and the socket share one DNS resolution. This closes the
+ *     DNS-rebinding TOCTOU where the client would otherwise re-resolve the
+ *     hostname at connect time and reach a different (internal) address. The
+ *     original hostname is preserved for the `Host` header and TLS SNI;
  *   - re-validates every redirect hop ({@link safeFetch}) instead of letting the
  *     HTTP client follow 3xx blindly.
  *
- * Node-aware: DNS resolution lazily imports `node:dns` and is a no-op on
- * runtimes without it (Web/edge), where the literal-address checks still apply.
+ * Node-aware: DNS resolution lazily imports `node:dns` and IP pinning lazily
+ * imports `node:http`/`node:https`. On runtimes without them (Web/edge) the
+ * literal-address checks still apply and the fetch falls back to the platform
+ * `fetch` (best-effort, without connection pinning) — combine with an
+ * `allowedHosts` allow-list and network egress controls there.
  *
- * Residual: this does DNS resolve-then-fetch without connection-level IP
- * pinning, so a sub-second DNS-rebinding race (flip the record between the
- * validating resolve and the client's connect-time resolve) is not fully
- * eliminated. For fully-untrusted inputs, combine with an `allowedHosts`
- * allow-list and network egress controls.
+ * Fails closed: a genuine resolver error rejects the URL rather than proceeding
+ * unvalidated; only a runtime that has no resolver at all (edge) skips the DNS
+ * step ({@link SsrfResolverUnavailableError}).
  */
 import type { RefResolutionOptions } from './types';
 /** The subset of {@link RefResolutionOptions} relevant to address blocking. */
@@ -75,15 +83,33 @@ export declare function isBlockedAddress(host: string): boolean;
  * internal addresses are caught later, asynchronously, in {@link safeFetch}.
  */
 export declare function isBlockedHostname(hostname: string, ssrf: ResolvedSsrfOptions): boolean;
-/** Default DNS resolver: lazily loads `node:dns`; rejects on non-Node runtimes. */
+/**
+ * Signals that no DNS resolver is available on the current runtime (e.g. a
+ * Web/edge isolate without `node:dns`). {@link assertUrlSafe} treats this as
+ * "cannot resolve, cannot pin" and proceeds on literal-address checks only,
+ * whereas a genuine resolver failure fails closed.
+ */
+export declare class SsrfResolverUnavailableError extends Error {
+}
+/** Default DNS resolver: lazily loads `node:dns`; signals unavailability off-Node. */
 export declare const defaultLookup: SsrfHostLookup;
 /**
  * Validate that `url` is safe to fetch (spec URL or `$ref` target), throwing
  * {@link SsrfError} if not. Enforces http/https, the `allowedHosts` allow-list,
  * the internal-address denylist, and — for DNS names — resolves and rejects if
  * any resolved address is internal.
+ *
+ * Returns the validated resolved addresses so the caller can **pin** the
+ * connection to them ({@link safeFetch}), guaranteeing the socket connects to
+ * the exact IP that was validated rather than re-resolving the hostname. An
+ * empty array means "no pinning needed" (a literal IP, `allowInternalIPs`, or a
+ * runtime without a resolver).
+ *
+ * Fails closed: a genuine resolver error (or a name that resolves to no
+ * address) rejects the URL. Only {@link SsrfResolverUnavailableError} — no
+ * resolver on this runtime — is treated as best-effort and returns `[]`.
  */
-export declare function assertUrlSafe(url: string, ssrf: ResolvedSsrfOptions, lookup?: SsrfHostLookup): Promise<void>;
+export declare function assertUrlSafe(url: string, ssrf: ResolvedSsrfOptions, lookup?: SsrfHostLookup): Promise<ResolvedAddress[]>;
 /** Options for {@link safeFetch}. */
 export interface SafeFetchOptions {
     headers?: Record<string, string>;
@@ -92,17 +118,53 @@ export interface SafeFetchOptions {
     followRedirects?: boolean;
     /** Max redirect hops before failing. @default 5 */
     maxRedirects?: number;
+    /** Max response body bytes before the request is aborted (Node transport). @default 10 MiB */
+    maxResponseBytes?: number;
     ssrf: ResolvedSsrfOptions;
     /** Injectable DNS resolver (tests). */
     lookup?: SsrfHostLookup;
-    /** Injectable fetch implementation (tests / custom runtimes). */
+    /**
+     * Injectable fetch implementation (tests / custom runtimes). Providing this
+     * bypasses the Node connection-pinning transport, so the implementation is
+     * responsible for connecting to the validated address itself.
+     */
     fetchImpl?: typeof fetch;
 }
+/** Lazily-loaded `node:http`/`node:https` modules. */
+export interface NodeHttpModules {
+    http: typeof import('node:http');
+    https: typeof import('node:https');
+}
+/** A transport that issues one GET and returns the raw (unfollowed) response. */
+type SsrfTransport = (url: string, request: {
+    headers?: Record<string, string>;
+    signal: AbortSignal;
+    pinned: ResolvedAddress[];
+    maxBytes?: number;
+}) => Promise<Response>;
+/** Select the Node transport module for a URL protocol. Exported for tests. */
+export declare function pickHttpModule(protocol: string, modules: NodeHttpModules): NodeHttpModules['http'] | NodeHttpModules['https'];
+/**
+ * A `node:net` lookup that always returns the pre-validated addresses, ignoring
+ * the queried hostname — pinning the socket to the exact IP {@link assertUrlSafe}
+ * validated so the connection cannot be re-resolved to a different (internal)
+ * address. Exported for tests.
+ */
+export declare function makePinnedLookup(pinned: ResolvedAddress[]): (_hostname: string, options: unknown, callback?: unknown) => void;
+/**
+ * Node transport that pins the connection to the validated address(es) via a
+ * custom `lookup`, preserving the original hostname for the `Host` header and
+ * TLS SNI. Manual redirects only (no `lookup` re-resolution between hops).
+ * Exported for tests.
+ */
+export declare function nodePinnedTransport(modules: NodeHttpModules): SsrfTransport;
 /**
  * SSRF-safe `fetch`: validates the initial URL and **every redirect hop** with
- * {@link assertUrlSafe} before issuing the request, using manual redirect
- * handling so a 3xx to an internal target can't be followed without
- * re-validation. Returns the final {@link Response} (the caller checks
- * `response.ok` / reads the body).
+ * {@link assertUrlSafe} before issuing the request, then **pins** the connection
+ * to the validated IP (on Node) so the socket can't be rebound to an internal
+ * address. Uses manual redirect handling so a 3xx to an internal target can't be
+ * followed without re-validation. Returns the final {@link Response} (the caller
+ * checks `response.ok` / reads the body).
  */
 export declare function safeFetch(url: string, opts: SafeFetchOptions): Promise<Response>;
+export {};