mcp-from-openapi 2.4.0 → 2.5.1

package/errors.d.ts

@@ -11,6 +11,19 @@ export declare class OpenAPIToolError extends Error {
 export declare class LoadError extends OpenAPIToolError {
     constructor(message: string, context?: Record<string, any>);
 }
+/**
+ * Error thrown when a spec URL or external `$ref` target is refused by the
+ * SSRF guard: it targets — or resolves to — a loopback / private / link-local /
+ * cloud-metadata address, uses a disallowed protocol, or is outside the
+ * configured allow-list.
+ *
+ * Subclasses {@link LoadError} so it propagates cleanly out of `fromURL` (whose
+ * catch re-throws `LoadError`) and so existing `instanceof LoadError` handling
+ * keeps working, while still being independently catchable.
+ */
+export declare class SsrfError extends LoadError {
+    constructor(message: string, context?: Record<string, any>);
+}
 /**
  * Error thrown when parsing an OpenAPI specification fails
  */

package/esm/index.mjs

@@ -660,6 +660,11 @@ var LoadError = class extends OpenAPIToolError {
     super(message, context);
   }
 };
+var SsrfError = class extends LoadError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
 var ParseError = class extends OpenAPIToolError {
   constructor(message, context) {
     super(message, context);
@@ -792,6 +797,275 @@ function resolveSchemaFormats(schema, resolvers) {
   return result;
 }
 
+// src/ssrf.ts
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
+  "localhost",
+  "localhost.localdomain",
+  "ip6-localhost",
+  "ip6-loopback",
+  "metadata",
+  "metadata.google.internal",
+  "metadata.goog"
+]);
+function normalizeSsrfOptions(refResolution) {
+  return {
+    allowedHosts: refResolution?.allowedHosts ?? [],
+    blockedHosts: refResolution?.blockedHosts ?? [],
+    allowInternalIPs: refResolution?.allowInternalIPs ?? false
+  };
+}
+function decodeIpv4MappedIpv6(hostname) {
+  let h = hostname;
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  const lower = h.toLowerCase();
+  const marker = lower.lastIndexOf("::ffff:");
+  if (marker === -1) return null;
+  const tail = lower.slice(marker + "::ffff:".length);
+  if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(tail)) return tail;
+  const hex = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hex) {
+    const hi = parseInt(hex[1], 16);
+    const lo = parseInt(hex[2], 16);
+    if (Number.isNaN(hi) || Number.isNaN(lo)) return null;
+    return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
+  }
+  return null;
+}
+function parseIpv4(host) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (!m) return null;
+  const octets = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+  if (octets.some((n) => n > 255)) return null;
+  return octets;
+}
+function isBlockedIpv4(octets) {
+  const [a, b, c] = octets;
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 0 && c === 0) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  if (a >= 224) return true;
+  return false;
+}
+function isBlockedIpv6(host) {
+  let h = host;
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  const zone = h.indexOf("%");
+  if (zone !== -1) h = h.slice(0, zone);
+  const lower = h.toLowerCase();
+  if (lower === "::" || lower === "::0") return true;
+  if (lower === "::1") return true;
+  if (/^f[cd]/.test(lower)) return true;
+  if (/^fe[89a-f]/.test(lower)) return true;
+  if (/^ff/.test(lower)) return true;
+  return false;
+}
+function isBlockedAddress(host) {
+  let h = host;
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  const mapped = decodeIpv4MappedIpv6(host);
+  if (mapped) {
+    const o = parseIpv4(mapped);
+    if (o) return isBlockedIpv4(o);
+  }
+  const v4 = parseIpv4(h);
+  if (v4) return isBlockedIpv4(v4);
+  if (h.includes(":")) return isBlockedIpv6(h);
+  return false;
+}
+function isIpLiteral(hostname) {
+  if (hostname.startsWith("[") && hostname.endsWith("]")) return true;
+  return parseIpv4(hostname) !== null;
+}
+function isBlockedHostname(hostname, ssrf) {
+  if (ssrf.allowInternalIPs) {
+    return ssrf.blockedHosts.includes(hostname);
+  }
+  if (ssrf.blockedHosts.includes(hostname)) return true;
+  const lower = hostname.toLowerCase();
+  const stripped = lower.startsWith("[") && lower.endsWith("]") ? lower.slice(1, -1) : lower;
+  if (BLOCKED_HOSTNAMES.has(lower) || BLOCKED_HOSTNAMES.has(stripped)) return true;
+  return isBlockedAddress(hostname);
+}
+var SsrfResolverUnavailableError = class extends Error {
+};
+var defaultLookup = async (hostname) => {
+  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) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new SsrfError(`Invalid spec URL: ${url}`, { url });
+  }
+  const protocol = parsed.protocol.replace(/:$/, "");
+  if (protocol !== "http" && protocol !== "https") {
+    throw new SsrfError(`Protocol "${protocol}" is not allowed for network spec loading (only http/https)`, { url });
+  }
+  const hostname = parsed.hostname;
+  if (ssrf.allowedHosts.length > 0 && !ssrf.allowedHosts.includes(hostname)) {
+    throw new SsrfError(`Host "${hostname}" is not in the allowed-hosts list`, { url });
+  }
+  if (ssrf.allowInternalIPs) {
+    if (ssrf.blockedHosts.includes(hostname)) {
+      throw new SsrfError(`Host "${hostname}" is blocked`, { url });
+    }
+    return [];
+  }
+  if (isBlockedHostname(hostname, ssrf)) {
+    throw new SsrfError(`Host "${hostname}" maps to a blocked internal address`, { url });
+  }
+  if (isIpLiteral(hostname)) {
+    return [];
+  }
+  let addresses;
+  try {
+    addresses = await lookup(hostname);
+  } catch (error) {
+    if (error instanceof SsrfResolverUnavailableError) {
+      return [];
+    }
+    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;
+}
+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++) {
+    const pinned = await assertUrlSafe(current, ssrf, lookup);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await transport(current, { headers, signal: controller.signal, pinned, maxBytes: opts.maxResponseBytes });
+    } finally {
+      clearTimeout(timer);
+    }
+    const status = typeof response.status === "number" ? response.status : 0;
+    const isRedirect = status >= 300 && status < 400 && status !== 304;
+    if (!isRedirect || !followRedirects) {
+      return response;
+    }
+    const location = response.headers?.get?.("location") ?? void 0;
+    if (!location) {
+      return response;
+    }
+    current = new URL(location, current).toString();
+  }
+  throw new SsrfError(`Too many redirects while loading OpenAPI spec (max ${maxRedirects})`, { url });
+}
+
 // src/generator.ts
 var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   document;
@@ -817,14 +1091,12 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
    */
   static async fromURL(url, options = {}) {
     try {
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), options.timeout ?? 3e4);
-      const response = await fetch(url, {
+      const response = await safeFetch(url, {
         headers: options.headers,
-        signal: controller.signal,
-        redirect: options.followRedirects ?? true ? "follow" : "manual"
+        timeoutMs: options.timeout ?? 3e4,
+        followRedirects: options.followRedirects ?? true,
+        ssrf: normalizeSsrfOptions(options.refResolution)
       });
-      clearTimeout(timeout);
       if (!response.ok) {
         throw new LoadError(`Failed to fetch OpenAPI spec from URL: ${response.status} ${response.statusText}`, {
           url,
@@ -915,87 +1187,11 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     const validator = new Validator();
     return validator.validate(this.document);
   }
-  /**
-   * Hostnames and IP patterns that are blocked by default to prevent SSRF.
-   * Covers RFC 1918/6598 private ranges, link-local, loopback, and cloud metadata endpoints.
-   */
-  static BLOCKED_HOSTNAME_PATTERNS = [
-    "localhost",
-    "metadata.google.internal",
-    /^127\.\d+\.\d+\.\d+$/,
-    // 127.0.0.0/8 loopback
-    /^10\.\d+\.\d+\.\d+$/,
-    // 10.0.0.0/8 private
-    /^172\.(1[6-9]|2\d|3[01])\.\d+\.\d+$/,
-    // 172.16.0.0/12 private
-    /^192\.168\.\d+\.\d+$/,
-    // 192.168.0.0/16 private
-    /^169\.254\.\d+\.\d+$/,
-    // 169.254.0.0/16 link-local / cloud metadata
-    /^0\.0\.0\.0$/,
-    // unspecified
-    "::1",
-    // IPv6 loopback
-    /^fd[0-9a-f]{2}:/i,
-    // fd00::/8 IPv6 ULA
-    /^fe80:/i,
-    // fe80::/10 IPv6 link-local
-    /^\[::1\]$/,
-    // bracketed IPv6 loopback
-    /^\[fd[0-9a-f]{2}:/i,
-    // bracketed IPv6 ULA
-    /^\[fe80:/i
-    // bracketed IPv6 link-local
-  ];
-  /**
-   * Decode an IPv4-mapped IPv6 host (`::ffff:169.254.169.254` or its hex form
-   * `::ffff:a9fe:a9fe`, optionally bracketed) to its embedded dotted-quad IPv4,
-   * or `null` if the host isn't IPv4-mapped. `new URL().hostname` normalizes
-   * `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, which the plain
-   * dotted-quad blocklist patterns miss — letting an attacker reach a private /
-   * metadata IPv4 through the v6 mapping. We re-check the decoded v4.
-   */
-  static mappedIPv4FromIPv6(hostname) {
-    let h = hostname;
-    if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
-    const lower = h.toLowerCase();
-    const marker = lower.lastIndexOf("::ffff:");
-    if (marker === -1) return null;
-    const tail = lower.slice(marker + "::ffff:".length);
-    if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(tail)) return tail;
-    const hex = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-    if (hex) {
-      const hi = parseInt(hex[1], 16);
-      const lo = parseInt(hex[2], 16);
-      if (Number.isNaN(hi) || Number.isNaN(lo)) return null;
-      return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
-    }
-    return null;
-  }
-  /**
-   * Check whether a hostname is blocked (internal/private IP or explicit blocklist).
-   */
-  isBlockedHost(hostname, refOpts) {
-    if (refOpts.allowInternalIPs) {
-      return refOpts.blockedHosts.includes(hostname);
-    }
-    if (refOpts.blockedHosts.includes(hostname)) {
-      return true;
-    }
-    const candidates = [hostname];
-    const mapped = _OpenAPIToolGenerator.mappedIPv4FromIPv6(hostname);
-    if (mapped) candidates.push(mapped);
-    for (const candidate of candidates) {
-      for (const pattern of _OpenAPIToolGenerator.BLOCKED_HOSTNAME_PATTERNS) {
-        if (typeof pattern === "string") {
-          if (candidate === pattern) return true;
-        } else {
-          if (pattern.test(candidate)) return true;
-        }
-      }
-    }
-    return false;
-  }
+  // NOTE: internal/private-address blocking + IPv4-mapped-IPv6 decoding now live
+  // in `ssrf.ts` (`isBlockedHostname` / `isBlockedAddress` / `decodeIpv4MappedIpv6`),
+  // shared by the spec-URL fetch (`fromURL`) and the `$ref` resolver below, and
+  // augmented there with DNS resolution (closing the DNS-name-to-internal bypass)
+  // and per-hop redirect re-validation (`safeFetch`).
   /**
    * Build $RefParser options based on refResolution configuration.
    * Defaults: allow http/https, block file://, block internal IPs.
@@ -1022,13 +1218,17 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       const hostAllowSet = new Set(refOpts.allowedHosts);
       resolveConfig["http"] = {
         // SECURITY: never auto-follow HTTP redirects when resolving external
-        // `$ref`s. `canRead` (below) validates only the INITIAL URL; the
-        // resolver's default redirect-following (up to 5 hops) re-fetches the
-        // `Location` target WITHOUT re-invoking `canRead`, so an allowlisted host
-        // could 302 → `http://169.254.169.254/...` and smuggle a blocked target
-        // past the allowlist/blocklist. Setting `redirects: 0` refuses the first
-        // redirect; legitimate refs resolve in one hop.
+        // `$ref`s. `canRead` validates only the INITIAL URL; the resolver's
+        // default redirect-following (up to 5 hops) re-fetches the `Location`
+        // target WITHOUT re-invoking `canRead`, so an allowlisted host could
+        // 302 → `http://169.254.169.254/...` and smuggle a blocked target past
+        // the allow/deny lists. `redirects: 0` refuses the first redirect, and
+        // our custom `read` (below) additionally refuses redirects itself.
         redirects: 0,
+        // Synchronous gate: protocol, host allow-list, and literal/known
+        // internal hosts. DNS names that *resolve* to internal addresses pass
+        // here (canRead cannot be async) and are caught in `read` via DNS
+        // resolution — closing the `127.0.0.1.nip.io` bypass for `$ref`s too.
         canRead: (file) => {
           try {
             const parsed = new URL(file.url);
@@ -1039,13 +1239,31 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
             if (hasHostAllowlist && !hostAllowSet.has(parsed.hostname)) {
               return false;
             }
-            if (this.isBlockedHost(parsed.hostname, refOpts)) {
+            if (isBlockedHostname(parsed.hostname, refOpts)) {
               return false;
             }
             return true;
           } catch {
             return false;
           }
+        },
+        // SSRF-safe fetch: resolves DNS and rejects names that map to internal
+        // addresses, and refuses redirects. NOTE: deliberately does NOT forward
+        // `this.options.headers` (the spec-load credentials) to third-party
+        // `$ref` hosts — that would leak the spec's auth token cross-origin.
+        read: async (file) => {
+          const response = await safeFetch(file.url, {
+            timeoutMs: this.options.timeout,
+            followRedirects: false,
+            ssrf: refOpts
+          });
+          if (!response.ok) {
+            throw new LoadError(
+              `Failed to resolve external $ref "${file.url}": ${response.status} ${response.statusText}`,
+              { url: file.url, status: response.status }
+            );
+          }
+          return response.text();
         }
       };
     } else {
@@ -1857,6 +2075,7 @@ function createSecurityContext(auth) {
   };
 }
 export {
+  BLOCKED_HOSTNAMES,
   BUILTIN_FORMAT_RESOLVERS,
   GenerationError,
   LoadError,
@@ -1868,10 +2087,18 @@ export {
   SchemaBuilder,
   SchemaError,
   SecurityResolver,
+  SsrfError,
   ValidationError,
   Validator,
+  assertUrlSafe,
   createSecurityContext,
+  decodeIpv4MappedIpv6,
+  defaultLookup,
+  isBlockedAddress,
+  isBlockedHostname,
   isReferenceObject,
+  normalizeSsrfOptions,
   resolveSchemaFormats,
+  safeFetch,
   toJsonSchema
 };

package/esm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.4.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/generator.d.ts

@@ -34,24 +34,6 @@ export declare class OpenAPIToolGenerator {
      * Validate the OpenAPI document
      */
     validate(): Promise<ValidationResult>;
-    /**
-     * Hostnames and IP patterns that are blocked by default to prevent SSRF.
-     * Covers RFC 1918/6598 private ranges, link-local, loopback, and cloud metadata endpoints.
-     */
-    private static readonly BLOCKED_HOSTNAME_PATTERNS;
-    /**
-     * Decode an IPv4-mapped IPv6 host (`::ffff:169.254.169.254` or its hex form
-     * `::ffff:a9fe:a9fe`, optionally bracketed) to its embedded dotted-quad IPv4,
-     * or `null` if the host isn't IPv4-mapped. `new URL().hostname` normalizes
-     * `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, which the plain
-     * dotted-quad blocklist patterns miss — letting an attacker reach a private /
-     * metadata IPv4 through the v6 mapping. We re-check the decoded v4.
-     */
-    private static mappedIPv4FromIPv6;
-    /**
-     * Check whether a hostname is blocked (internal/private IP or explicit blocklist).
-     */
-    private isBlockedHost;
     /**
      * Build $RefParser options based on refResolution configuration.
      * Defaults: allow http/https, block file://, block internal IPs.

package/index.d.ts

@@ -5,7 +5,9 @@ export { ResponseBuilder } from './response-builder';
 export { Validator } from './validator';
 export { SecurityResolver, createSecurityContext } from './security-resolver';
 export { BUILTIN_FORMAT_RESOLVERS, resolveSchemaFormats } from './format-resolver';
-export { OpenAPIToolError, LoadError, ParseError, ValidationError, GenerationError, SchemaError } from './errors';
+export { OpenAPIToolError, LoadError, SsrfError, ParseError, ValidationError, GenerationError, SchemaError } from './errors';
+export { assertUrlSafe, safeFetch, isBlockedAddress, isBlockedHostname, decodeIpv4MappedIpv6, normalizeSsrfOptions, defaultLookup, BLOCKED_HOSTNAMES, } from './ssrf';
+export type { ResolvedSsrfOptions, ResolvedAddress, SsrfHostLookup, SafeFetchOptions } from './ssrf';
 export type { McpOpenAPITool, ParameterMapper, ToolMetadata, FrontMcpExtensionData, SerializationInfo, SecurityRequirement, SecurityParameterInfo, ServerInfo, RefResolutionOptions, LoadOptions, GenerateOptions, FormatResolver, JsonSchema, NamingStrategy, OperationWithContext, OpenAPIDocument, OpenAPIVersion, HTTPMethod, ParameterLocation, AuthType, OperationObject, ParameterObject, RequestBodyObject, ResponseObject, ResponsesObject, MediaTypeObject, HeaderObject, ExampleObject, PathItemObject, PathsObject, ServerObject, SecuritySchemeObject, ReferenceObject, TagObject, ExternalDocumentationObject, ServerVariableObject, EncodingObject, SecurityRequirementObject, SchemaObject, ValidationResult, ValidationErrorDetail, ValidationWarning, } from './types';
 export type { SecurityContext, ResolvedSecurity, DigestAuthCredentials, ClientCertificate, AWSCredentials, SignatureData, } from './security-resolver';
 export { isReferenceObject, toJsonSchema } from './types';

package/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BLOCKED_HOSTNAMES: () => BLOCKED_HOSTNAMES,
   BUILTIN_FORMAT_RESOLVERS: () => BUILTIN_FORMAT_RESOLVERS,
   GenerationError: () => GenerationError,
   LoadError: () => LoadError,
@@ -41,11 +42,19 @@ __export(index_exports, {
   SchemaBuilder: () => SchemaBuilder,
   SchemaError: () => SchemaError,
   SecurityResolver: () => SecurityResolver,
+  SsrfError: () => SsrfError,
   ValidationError: () => ValidationError,
   Validator: () => Validator,
+  assertUrlSafe: () => assertUrlSafe,
   createSecurityContext: () => createSecurityContext,
+  decodeIpv4MappedIpv6: () => decodeIpv4MappedIpv6,
+  defaultLookup: () => defaultLookup,
+  isBlockedAddress: () => isBlockedAddress,
+  isBlockedHostname: () => isBlockedHostname,
   isReferenceObject: () => isReferenceObject,
+  normalizeSsrfOptions: () => normalizeSsrfOptions,
   resolveSchemaFormats: () => resolveSchemaFormats,
+  safeFetch: () => safeFetch,
   toJsonSchema: () => toJsonSchema
 });
 module.exports = __toCommonJS(index_exports);
@@ -712,6 +721,11 @@ var LoadError = class extends OpenAPIToolError {
     super(message, context);
   }
 };
+var SsrfError = class extends LoadError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
 var ParseError = class extends OpenAPIToolError {
   constructor(message, context) {
     super(message, context);
@@ -844,6 +858,275 @@ function resolveSchemaFormats(schema, resolvers) {
   return result;
 }
 
+// src/ssrf.ts
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
+  "localhost",
+  "localhost.localdomain",
+  "ip6-localhost",
+  "ip6-loopback",
+  "metadata",
+  "metadata.google.internal",
+  "metadata.goog"
+]);
+function normalizeSsrfOptions(refResolution) {
+  return {
+    allowedHosts: refResolution?.allowedHosts ?? [],
+    blockedHosts: refResolution?.blockedHosts ?? [],
+    allowInternalIPs: refResolution?.allowInternalIPs ?? false
+  };
+}
+function decodeIpv4MappedIpv6(hostname) {
+  let h = hostname;
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  const lower = h.toLowerCase();
+  const marker = lower.lastIndexOf("::ffff:");
+  if (marker === -1) return null;
+  const tail = lower.slice(marker + "::ffff:".length);
+  if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(tail)) return tail;
+  const hex = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hex) {
+    const hi = parseInt(hex[1], 16);
+    const lo = parseInt(hex[2], 16);
+    if (Number.isNaN(hi) || Number.isNaN(lo)) return null;
+    return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
+  }
+  return null;
+}
+function parseIpv4(host) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (!m) return null;
+  const octets = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+  if (octets.some((n) => n > 255)) return null;
+  return octets;
+}
+function isBlockedIpv4(octets) {
+  const [a, b, c] = octets;
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 0 && c === 0) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  if (a >= 224) return true;
+  return false;
+}
+function isBlockedIpv6(host) {
+  let h = host;
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  const zone = h.indexOf("%");
+  if (zone !== -1) h = h.slice(0, zone);
+  const lower = h.toLowerCase();
+  if (lower === "::" || lower === "::0") return true;
+  if (lower === "::1") return true;
+  if (/^f[cd]/.test(lower)) return true;
+  if (/^fe[89a-f]/.test(lower)) return true;
+  if (/^ff/.test(lower)) return true;
+  return false;
+}
+function isBlockedAddress(host) {
+  let h = host;
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  const mapped = decodeIpv4MappedIpv6(host);
+  if (mapped) {
+    const o = parseIpv4(mapped);
+    if (o) return isBlockedIpv4(o);
+  }
+  const v4 = parseIpv4(h);
+  if (v4) return isBlockedIpv4(v4);
+  if (h.includes(":")) return isBlockedIpv6(h);
+  return false;
+}
+function isIpLiteral(hostname) {
+  if (hostname.startsWith("[") && hostname.endsWith("]")) return true;
+  return parseIpv4(hostname) !== null;
+}
+function isBlockedHostname(hostname, ssrf) {
+  if (ssrf.allowInternalIPs) {
+    return ssrf.blockedHosts.includes(hostname);
+  }
+  if (ssrf.blockedHosts.includes(hostname)) return true;
+  const lower = hostname.toLowerCase();
+  const stripped = lower.startsWith("[") && lower.endsWith("]") ? lower.slice(1, -1) : lower;
+  if (BLOCKED_HOSTNAMES.has(lower) || BLOCKED_HOSTNAMES.has(stripped)) return true;
+  return isBlockedAddress(hostname);
+}
+var SsrfResolverUnavailableError = class extends Error {
+};
+var defaultLookup = async (hostname) => {
+  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) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new SsrfError(`Invalid spec URL: ${url}`, { url });
+  }
+  const protocol = parsed.protocol.replace(/:$/, "");
+  if (protocol !== "http" && protocol !== "https") {
+    throw new SsrfError(`Protocol "${protocol}" is not allowed for network spec loading (only http/https)`, { url });
+  }
+  const hostname = parsed.hostname;
+  if (ssrf.allowedHosts.length > 0 && !ssrf.allowedHosts.includes(hostname)) {
+    throw new SsrfError(`Host "${hostname}" is not in the allowed-hosts list`, { url });
+  }
+  if (ssrf.allowInternalIPs) {
+    if (ssrf.blockedHosts.includes(hostname)) {
+      throw new SsrfError(`Host "${hostname}" is blocked`, { url });
+    }
+    return [];
+  }
+  if (isBlockedHostname(hostname, ssrf)) {
+    throw new SsrfError(`Host "${hostname}" maps to a blocked internal address`, { url });
+  }
+  if (isIpLiteral(hostname)) {
+    return [];
+  }
+  let addresses;
+  try {
+    addresses = await lookup(hostname);
+  } catch (error) {
+    if (error instanceof SsrfResolverUnavailableError) {
+      return [];
+    }
+    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;
+}
+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++) {
+    const pinned = await assertUrlSafe(current, ssrf, lookup);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await transport(current, { headers, signal: controller.signal, pinned, maxBytes: opts.maxResponseBytes });
+    } finally {
+      clearTimeout(timer);
+    }
+    const status = typeof response.status === "number" ? response.status : 0;
+    const isRedirect = status >= 300 && status < 400 && status !== 304;
+    if (!isRedirect || !followRedirects) {
+      return response;
+    }
+    const location = response.headers?.get?.("location") ?? void 0;
+    if (!location) {
+      return response;
+    }
+    current = new URL(location, current).toString();
+  }
+  throw new SsrfError(`Too many redirects while loading OpenAPI spec (max ${maxRedirects})`, { url });
+}
+
 // src/generator.ts
 var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   document;
@@ -869,14 +1152,12 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
    */
   static async fromURL(url, options = {}) {
     try {
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), options.timeout ?? 3e4);
-      const response = await fetch(url, {
+      const response = await safeFetch(url, {
         headers: options.headers,
-        signal: controller.signal,
-        redirect: options.followRedirects ?? true ? "follow" : "manual"
+        timeoutMs: options.timeout ?? 3e4,
+        followRedirects: options.followRedirects ?? true,
+        ssrf: normalizeSsrfOptions(options.refResolution)
       });
-      clearTimeout(timeout);
       if (!response.ok) {
         throw new LoadError(`Failed to fetch OpenAPI spec from URL: ${response.status} ${response.statusText}`, {
           url,
@@ -967,87 +1248,11 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     const validator = new Validator();
     return validator.validate(this.document);
   }
-  /**
-   * Hostnames and IP patterns that are blocked by default to prevent SSRF.
-   * Covers RFC 1918/6598 private ranges, link-local, loopback, and cloud metadata endpoints.
-   */
-  static BLOCKED_HOSTNAME_PATTERNS = [
-    "localhost",
-    "metadata.google.internal",
-    /^127\.\d+\.\d+\.\d+$/,
-    // 127.0.0.0/8 loopback
-    /^10\.\d+\.\d+\.\d+$/,
-    // 10.0.0.0/8 private
-    /^172\.(1[6-9]|2\d|3[01])\.\d+\.\d+$/,
-    // 172.16.0.0/12 private
-    /^192\.168\.\d+\.\d+$/,
-    // 192.168.0.0/16 private
-    /^169\.254\.\d+\.\d+$/,
-    // 169.254.0.0/16 link-local / cloud metadata
-    /^0\.0\.0\.0$/,
-    // unspecified
-    "::1",
-    // IPv6 loopback
-    /^fd[0-9a-f]{2}:/i,
-    // fd00::/8 IPv6 ULA
-    /^fe80:/i,
-    // fe80::/10 IPv6 link-local
-    /^\[::1\]$/,
-    // bracketed IPv6 loopback
-    /^\[fd[0-9a-f]{2}:/i,
-    // bracketed IPv6 ULA
-    /^\[fe80:/i
-    // bracketed IPv6 link-local
-  ];
-  /**
-   * Decode an IPv4-mapped IPv6 host (`::ffff:169.254.169.254` or its hex form
-   * `::ffff:a9fe:a9fe`, optionally bracketed) to its embedded dotted-quad IPv4,
-   * or `null` if the host isn't IPv4-mapped. `new URL().hostname` normalizes
-   * `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, which the plain
-   * dotted-quad blocklist patterns miss — letting an attacker reach a private /
-   * metadata IPv4 through the v6 mapping. We re-check the decoded v4.
-   */
-  static mappedIPv4FromIPv6(hostname) {
-    let h = hostname;
-    if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
-    const lower = h.toLowerCase();
-    const marker = lower.lastIndexOf("::ffff:");
-    if (marker === -1) return null;
-    const tail = lower.slice(marker + "::ffff:".length);
-    if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(tail)) return tail;
-    const hex = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-    if (hex) {
-      const hi = parseInt(hex[1], 16);
-      const lo = parseInt(hex[2], 16);
-      if (Number.isNaN(hi) || Number.isNaN(lo)) return null;
-      return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
-    }
-    return null;
-  }
-  /**
-   * Check whether a hostname is blocked (internal/private IP or explicit blocklist).
-   */
-  isBlockedHost(hostname, refOpts) {
-    if (refOpts.allowInternalIPs) {
-      return refOpts.blockedHosts.includes(hostname);
-    }
-    if (refOpts.blockedHosts.includes(hostname)) {
-      return true;
-    }
-    const candidates = [hostname];
-    const mapped = _OpenAPIToolGenerator.mappedIPv4FromIPv6(hostname);
-    if (mapped) candidates.push(mapped);
-    for (const candidate of candidates) {
-      for (const pattern of _OpenAPIToolGenerator.BLOCKED_HOSTNAME_PATTERNS) {
-        if (typeof pattern === "string") {
-          if (candidate === pattern) return true;
-        } else {
-          if (pattern.test(candidate)) return true;
-        }
-      }
-    }
-    return false;
-  }
+  // NOTE: internal/private-address blocking + IPv4-mapped-IPv6 decoding now live
+  // in `ssrf.ts` (`isBlockedHostname` / `isBlockedAddress` / `decodeIpv4MappedIpv6`),
+  // shared by the spec-URL fetch (`fromURL`) and the `$ref` resolver below, and
+  // augmented there with DNS resolution (closing the DNS-name-to-internal bypass)
+  // and per-hop redirect re-validation (`safeFetch`).
   /**
    * Build $RefParser options based on refResolution configuration.
    * Defaults: allow http/https, block file://, block internal IPs.
@@ -1074,13 +1279,17 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       const hostAllowSet = new Set(refOpts.allowedHosts);
       resolveConfig["http"] = {
         // SECURITY: never auto-follow HTTP redirects when resolving external
-        // `$ref`s. `canRead` (below) validates only the INITIAL URL; the
-        // resolver's default redirect-following (up to 5 hops) re-fetches the
-        // `Location` target WITHOUT re-invoking `canRead`, so an allowlisted host
-        // could 302 → `http://169.254.169.254/...` and smuggle a blocked target
-        // past the allowlist/blocklist. Setting `redirects: 0` refuses the first
-        // redirect; legitimate refs resolve in one hop.
+        // `$ref`s. `canRead` validates only the INITIAL URL; the resolver's
+        // default redirect-following (up to 5 hops) re-fetches the `Location`
+        // target WITHOUT re-invoking `canRead`, so an allowlisted host could
+        // 302 → `http://169.254.169.254/...` and smuggle a blocked target past
+        // the allow/deny lists. `redirects: 0` refuses the first redirect, and
+        // our custom `read` (below) additionally refuses redirects itself.
         redirects: 0,
+        // Synchronous gate: protocol, host allow-list, and literal/known
+        // internal hosts. DNS names that *resolve* to internal addresses pass
+        // here (canRead cannot be async) and are caught in `read` via DNS
+        // resolution — closing the `127.0.0.1.nip.io` bypass for `$ref`s too.
         canRead: (file) => {
           try {
             const parsed = new URL(file.url);
@@ -1091,13 +1300,31 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
             if (hasHostAllowlist && !hostAllowSet.has(parsed.hostname)) {
               return false;
             }
-            if (this.isBlockedHost(parsed.hostname, refOpts)) {
+            if (isBlockedHostname(parsed.hostname, refOpts)) {
               return false;
             }
             return true;
           } catch {
             return false;
           }
+        },
+        // SSRF-safe fetch: resolves DNS and rejects names that map to internal
+        // addresses, and refuses redirects. NOTE: deliberately does NOT forward
+        // `this.options.headers` (the spec-load credentials) to third-party
+        // `$ref` hosts — that would leak the spec's auth token cross-origin.
+        read: async (file) => {
+          const response = await safeFetch(file.url, {
+            timeoutMs: this.options.timeout,
+            followRedirects: false,
+            ssrf: refOpts
+          });
+          if (!response.ok) {
+            throw new LoadError(
+              `Failed to resolve external $ref "${file.url}": ${response.status} ${response.statusText}`,
+              { url: file.url, status: response.status }
+            );
+          }
+          return response.text();
         }
       };
     } else {
@@ -1910,6 +2137,7 @@ function createSecurityContext(auth) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BLOCKED_HOSTNAMES,
   BUILTIN_FORMAT_RESOLVERS,
   GenerationError,
   LoadError,
@@ -1921,10 +2149,18 @@ function createSecurityContext(auth) {
   SchemaBuilder,
   SchemaError,
   SecurityResolver,
+  SsrfError,
   ValidationError,
   Validator,
+  assertUrlSafe,
   createSecurityContext,
+  decodeIpv4MappedIpv6,
+  defaultLookup,
+  isBlockedAddress,
+  isBlockedHostname,
   isReferenceObject,
+  normalizeSsrfOptions,
   resolveSchemaFormats,
+  safeFetch,
   toJsonSchema
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.4.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

@@ -0,0 +1,170 @@
+/**
+ * SSRF protection for spec loading and external `$ref` resolution.
+ *
+ * The generator fetches two kinds of attacker-influenceable URLs:
+ *   1. the OpenAPI spec itself (`fromURL`), and
+ *   2. external `$ref` targets during dereferencing.
+ *
+ * A hostname-string denylist (the pre-2.5 approach) is bypassable, as reported
+ * in GHSA-65h7-9wrw-629c:
+ *   - DNS names that resolve to internal IPs, e.g. `http://127.0.0.1.nip.io/`
+ *     — the literal-string `127.0.0.1` patterns never match, yet the name
+ *     resolves to loopback;
+ *   - IPv4-mapped IPv6 forms (handled since 2.4 via {@link decodeIpv4MappedIpv6});
+ *   - redirects from an allowed host to an internal one.
+ *
+ * This module validates the **resolved IP**, not just the hostname string:
+ *   - parses/normalizes IPv4 (incl. numeric/hex/octal forms canonicalized by
+ *     `new URL()`) and IPv4-mapped IPv6 before range checks;
+ *   - blocks loopback / private (RFC 1918) / CGNAT (RFC 6598) / link-local /
+ *     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 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.
+ *
+ * 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. */
+export interface ResolvedSsrfOptions {
+    allowedHosts: string[];
+    blockedHosts: string[];
+    allowInternalIPs: boolean;
+}
+/** Resolved DNS address shape (subset of Node's `dns.LookupAddress`). */
+export interface ResolvedAddress {
+    address: string;
+    family: number;
+}
+/** Hostname → resolved addresses. Injectable for testing. */
+export type SsrfHostLookup = (hostname: string) => Promise<ResolvedAddress[]>;
+/**
+ * Non-IP hostnames that map to internal targets, so the IP-range checks alone
+ * would miss them when DNS resolution is unavailable. DNS resolution (when
+ * available) also catches these; this set is defense-in-depth.
+ */
+export declare const BLOCKED_HOSTNAMES: ReadonlySet<string>;
+/** Normalize a (possibly undefined) {@link RefResolutionOptions} to the SSRF subset. */
+export declare function normalizeSsrfOptions(refResolution?: RefResolutionOptions): ResolvedSsrfOptions;
+/**
+ * Decode an IPv4-mapped IPv6 host (`::ffff:169.254.169.254` or its hex form
+ * `::ffff:a9fe:a9fe`, optionally bracketed) to its embedded dotted-quad IPv4, or
+ * `null` if the host isn't IPv4-mapped. `new URL().hostname` normalizes
+ * `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, which the plain
+ * dotted-quad range checks would otherwise miss.
+ */
+export declare function decodeIpv4MappedIpv6(hostname: string): string | null;
+/**
+ * Predicate: is `host` (an IP literal — dotted-quad IPv4, bracketed/zoned IPv6,
+ * or IPv4-mapped IPv6) in a blocked, non-public range? Returns `false` for
+ * non-IP-literal hostnames (use DNS resolution for those).
+ */
+export declare function isBlockedAddress(host: string): boolean;
+/**
+ * Synchronous host check used by the `$RefParser` `canRead` filter (which cannot
+ * be async). Blocks known internal hostnames, explicit `blockedHosts`, and
+ * literal internal IPs (incl. IPv4-mapped IPv6). DNS names that *resolve* to
+ * internal addresses are caught later, asynchronously, in {@link safeFetch}.
+ */
+export declare function isBlockedHostname(hostname: string, ssrf: ResolvedSsrfOptions): boolean;
+/**
+ * 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<ResolvedAddress[]>;
+/** Options for {@link safeFetch}. */
+export interface SafeFetchOptions {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    /** Follow 3xx redirects (re-validating each hop). @default true */
+    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). 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, 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 {};

package/types.d.ts

@@ -327,9 +327,15 @@ export interface ServerInfo {
     variables?: Record<string, ServerVariableObject>;
 }
 /**
- * Controls how external $ref pointers are resolved during dereferencing.
- * By default, only http/https protocols are allowed and internal/private
- * IP addresses are blocked to prevent SSRF attacks.
+ * Controls how external `$ref` pointers are resolved during dereferencing, and
+ * the host policy applied to the initial spec-URL fetch in `fromURL`.
+ *
+ * By default only http/https protocols are allowed and internal/private targets
+ * are blocked to prevent SSRF. As of 2.5.0 the guard validates the **resolved
+ * IP** (it resolves DNS and rejects hostnames that map to internal addresses —
+ * e.g. `127.0.0.1.nip.io`), normalizes IPv4-mapped IPv6, and re-validates every
+ * HTTP redirect hop. `allowedHosts` / `blockedHosts` / `allowInternalIPs` apply
+ * to both the spec URL and external `$ref`s.
  */
 export interface RefResolutionOptions {
     /**
@@ -386,13 +392,17 @@ export interface LoadOptions {
      */
     validate?: boolean;
     /**
-     * Whether to follow HTTP redirects
+     * Whether to follow HTTP redirects when fetching the spec URL. Each redirect
+     * hop is re-validated against the SSRF guard before being followed (a 3xx to
+     * an internal target is refused), so following is safe by default.
      * @default true
      */
     followRedirects?: boolean;
     /**
-     * Controls external $ref resolution security.
-     * By default, file:// is blocked and internal IPs are blocked.
+     * Controls spec-loading security: external `$ref` resolution AND the host
+     * policy for the initial spec-URL fetch. By default `file://` is blocked,
+     * internal/private targets are blocked, and hostnames are DNS-resolved and
+     * re-checked against the internal-address ranges.
      * @see RefResolutionOptions
      */
     refResolution?: RefResolutionOptions;