mcp-from-openapi 2.4.0 → 2.5.0

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,178 @@ 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 defaultLookup = async (hostname) => {
+  const dns = await import("node:dns");
+  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)) {
+    let addresses;
+    try {
+      addresses = await lookup(hostname);
+    } catch {
+      return;
+    }
+    for (const { address } of addresses) {
+      if (isBlockedAddress(address)) {
+        throw new SsrfError(`Host "${hostname}" resolves to blocked address ${address}`, { url });
+      }
+    }
+  }
+}
+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") {
+    throw new SsrfError("No fetch implementation available to load OpenAPI spec from URL", { url });
+  }
+  let current = url;
+  for (let hop = 0; hop <= maxRedirects; hop++) {
+    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"
+      });
+    } 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 +994,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 +1090,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 +1121,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 +1142,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 +1978,7 @@ function createSecurityContext(auth) {
   };
 }
 export {
+  BLOCKED_HOSTNAMES,
   BUILTIN_FORMAT_RESOLVERS,
   GenerationError,
   LoadError,
@@ -1868,10 +1990,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.0",
   "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,178 @@ 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 defaultLookup = async (hostname) => {
+  const dns = await import("node:dns");
+  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)) {
+    let addresses;
+    try {
+      addresses = await lookup(hostname);
+    } catch {
+      return;
+    }
+    for (const { address } of addresses) {
+      if (isBlockedAddress(address)) {
+        throw new SsrfError(`Host "${hostname}" resolves to blocked address ${address}`, { url });
+      }
+    }
+  }
+}
+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") {
+    throw new SsrfError("No fetch implementation available to load OpenAPI spec from URL", { url });
+  }
+  let current = url;
+  for (let hop = 0; hop <= maxRedirects; hop++) {
+    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"
+      });
+    } 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 +1055,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 +1151,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 +1182,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 +1203,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 +2040,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 +2052,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.0",
   "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,108 @@
+/**
+ * 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;
+ *   - 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.
+ *
+ * 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.
+ */
+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;
+/** Default DNS resolver: lazily loads `node:dns`; rejects on non-Node runtimes. */
+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.
+ */
+export declare function assertUrlSafe(url: string, ssrf: ResolvedSsrfOptions, lookup?: SsrfHostLookup): Promise<void>;
+/** 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;
+    ssrf: ResolvedSsrfOptions;
+    /** Injectable DNS resolver (tests). */
+    lookup?: SsrfHostLookup;
+    /** Injectable fetch implementation (tests / custom runtimes). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * 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).
+ */
+export declare function safeFetch(url: string, opts: SafeFetchOptions): Promise<Response>;

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;