mcp-from-openapi 2.3.0 → 2.5.0

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,19 +42,25 @@ __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);
 
 // src/generator.ts
 var yaml = __toESM(require("yaml"));
-var path = __toESM(require("path"));
-var fs = __toESM(require("fs/promises"));
 
 // src/types.ts
 function isReferenceObject(obj) {
@@ -588,12 +595,12 @@ var Validator = class {
    * Validate paths
    */
   validatePaths(paths, errors, warnings) {
-    for (const [path2, pathItem] of Object.entries(paths)) {
+    for (const [path, pathItem] of Object.entries(paths)) {
       if (!pathItem) continue;
-      if (!path2.startsWith("/")) {
+      if (!path.startsWith("/")) {
         errors.push({
-          message: `Path must start with '/': ${path2}`,
-          path: `/paths/${path2}`,
+          message: `Path must start with '/': ${path}`,
+          path: `/paths/${path}`,
           code: "INVALID_PATH_FORMAT"
         });
       }
@@ -603,13 +610,13 @@ var Validator = class {
         const operation = pathItem[method];
         if (operation) {
           hasOperations = true;
-          this.validateOperation(operation, path2, method, errors, warnings);
+          this.validateOperation(operation, path, method, errors, warnings);
         }
       }
       if (!hasOperations && !pathItem.$ref) {
         warnings.push({
-          message: `Path has no operations: ${path2}`,
-          path: `/paths/${path2}`,
+          message: `Path has no operations: ${path}`,
+          path: `/paths/${path}`,
           code: "NO_OPERATIONS"
         });
       }
@@ -618,33 +625,33 @@ var Validator = class {
   /**
    * Validate an operation
    */
-  validateOperation(operation, path2, method, errors, warnings) {
-    const basePath = `/paths/${path2}/${method}`;
+  validateOperation(operation, path, method, errors, warnings) {
+    const basePath = `/paths/${path}/${method}`;
     if (!operation.operationId) {
       warnings.push({
-        message: `Operation missing operationId: ${method.toUpperCase()} ${path2}`,
+        message: `Operation missing operationId: ${method.toUpperCase()} ${path}`,
         path: `${basePath}/operationId`,
         code: "NO_OPERATION_ID"
       });
     }
     if (!operation.responses || Object.keys(operation.responses).length === 0) {
       errors.push({
-        message: `Operation missing responses: ${method.toUpperCase()} ${path2}`,
+        message: `Operation missing responses: ${method.toUpperCase()} ${path}`,
         path: `${basePath}/responses`,
         code: "NO_RESPONSES"
       });
     }
     if (operation.parameters) {
-      this.validateParameters(operation.parameters, path2, method, errors, warnings);
+      this.validateParameters(operation.parameters, path, method, errors, warnings);
     }
-    const pathParams = path2.match(/\{([^}]+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
+    const pathParams = path.match(/\{([^}]+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
     const definedPathParams = new Set(
       operation.parameters?.filter((p) => p.in === "path").map((p) => p.name) ?? []
     );
     for (const param of pathParams) {
       if (!definedPathParams.has(param)) {
         errors.push({
-          message: `Path parameter '${param}' not defined in parameters: ${method.toUpperCase()} ${path2}`,
+          message: `Path parameter '${param}' not defined in parameters: ${method.toUpperCase()} ${path}`,
           path: `${basePath}/parameters`,
           code: "MISSING_PATH_PARAMETER"
         });
@@ -654,8 +661,8 @@ var Validator = class {
   /**
    * Validate parameters
    */
-  validateParameters(parameters, path2, method, errors, warnings) {
-    const basePath = `/paths/${path2}/${method}/parameters`;
+  validateParameters(parameters, path, method, errors, warnings) {
+    const basePath = `/paths/${path}/${method}/parameters`;
     for (let i = 0; i < parameters.length; i++) {
       const param = parameters[i];
       const paramPath = `${basePath}/${i}`;
@@ -714,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);
@@ -846,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;
@@ -871,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,
@@ -910,6 +1092,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
    */
   static async fromFile(filePath, options = {}) {
     try {
+      const [path, fs] = await Promise.all([import("path"), import("fs/promises")]);
       const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
       const content = await fs.readFile(absolutePath, "utf-8");
       const ext = path.extname(filePath).toLowerCase();
@@ -968,57 +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
-  ];
-  /**
-   * 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;
-    }
-    for (const pattern of _OpenAPIToolGenerator.BLOCKED_HOSTNAME_PATTERNS) {
-      if (typeof pattern === "string") {
-        if (hostname === pattern) return true;
-      } else {
-        if (pattern.test(hostname)) 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.
@@ -1044,6 +1181,18 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       const hasHostAllowlist = refOpts.allowedHosts.length > 0;
       const hostAllowSet = new Set(refOpts.allowedHosts);
       resolveConfig["http"] = {
+        // SECURITY: never auto-follow HTTP redirects when resolving external
+        // `$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);
@@ -1054,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 {
@@ -1068,23 +1235,75 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     }
     return { resolve: resolveConfig };
   }
+  /**
+   * Does the document contain any EXTERNAL `$ref` (a ref that is not a local
+   * JSON-pointer beginning with `#`)? Only external refs require the full
+   * `$RefParser` (file/http resolvers, which pull Node builtins). A document
+   * with only internal refs can be dereferenced with the runtime-agnostic
+   * resolver below — so it works on V8 isolates (Cloudflare Workers) too.
+   */
+  static hasExternalRefs(node, seen = /* @__PURE__ */ new Set()) {
+    if (node === null || typeof node !== "object") return false;
+    if (seen.has(node)) return false;
+    seen.add(node);
+    if (Array.isArray(node)) return node.some((n) => _OpenAPIToolGenerator.hasExternalRefs(n, seen));
+    const ref = node.$ref;
+    if (typeof ref === "string" && !ref.startsWith("#")) return true;
+    return Object.values(node).some(
+      (v) => _OpenAPIToolGenerator.hasExternalRefs(v, seen)
+    );
+  }
+  /**
+   * Dereference local (`#/...`) `$ref`s without `$RefParser` — pure, dependency-
+   * free, runtime-agnostic. A pointer cache makes circular schemas resolve to a
+   * shared reference instead of recursing forever (same contract as `$RefParser`).
+   */
+  static dereferenceInternal(root) {
+    const cache = /* @__PURE__ */ new Map();
+    const resolvePointer = (ptr) => {
+      const parts = ptr.replace(/^#\/?/, "").split("/").filter((p) => p.length > 0).map((p) => p.replace(/~1/g, "/").replace(/~0/g, "~"));
+      let cur = root;
+      for (const p of parts) cur = cur?.[p];
+      return cur;
+    };
+    const walk = (node) => {
+      if (node === null || typeof node !== "object") return node;
+      if (Array.isArray(node)) return node.map(walk);
+      const ref = node.$ref;
+      if (typeof ref === "string" && ref.startsWith("#")) {
+        const cached = cache.get(ref);
+        if (cached !== void 0) return cached;
+        const placeholder = {};
+        cache.set(ref, placeholder);
+        const resolved = walk(resolvePointer(ref));
+        if (resolved && typeof resolved === "object") Object.assign(placeholder, resolved);
+        return placeholder;
+      }
+      const out = {};
+      for (const [k, v] of Object.entries(node)) out[k] = walk(v);
+      return out;
+    };
+    return walk(root);
+  }
   /**
    * Initialize the generator (dereference if needed, then validate)
    */
   async initialize() {
     if (this.options.dereference && !this.dereferencedDocument) {
-      try {
-        const { default: $RefParser } = await import("@apidevtools/json-schema-ref-parser");
-        const refParserOptions = this.buildRefParserOptions();
-        this.dereferencedDocument = await $RefParser.dereference(
-          JSON.parse(JSON.stringify(this.document)),
-          refParserOptions
-        );
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new ParseError(`Failed to dereference OpenAPI document: ${errorMessage}`, {
-          originalError: error
-        });
+      const cloned = JSON.parse(JSON.stringify(this.document));
+      if (!_OpenAPIToolGenerator.hasExternalRefs(cloned)) {
+        this.dereferencedDocument = _OpenAPIToolGenerator.dereferenceInternal(cloned);
+      } else {
+        try {
+          const { default: $RefParser } = await import("@apidevtools/json-schema-ref-parser");
+          const refParserOptions = this.buildRefParserOptions();
+          this.dereferencedDocument = await $RefParser.dereference(cloned, refParserOptions);
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          throw new ParseError(`Failed to dereference OpenAPI document: ${errorMessage}`, {
+            originalError: error
+          });
+        }
       }
     }
     if (this.options.validate) {
@@ -1182,7 +1401,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   /**
    * Check if an operation should be included
    */
-  shouldIncludeOperation(operation, path2, method, options) {
+  shouldIncludeOperation(operation, path, method, options) {
     if (operation.deprecated && !options.includeDeprecated) {
       return false;
     }
@@ -1199,7 +1418,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     if (options.filterFn) {
       return options.filterFn({
         ...operation,
-        path: path2,
+        path,
         method
       });
     }
@@ -1208,22 +1427,22 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   /**
    * Generate a tool name
    */
-  generateToolName(path2, method, operationId, options = {}) {
+  generateToolName(path, method, operationId, options = {}) {
     if (options.namingStrategy?.toolNameGenerator) {
-      return options.namingStrategy.toolNameGenerator(path2, method, operationId);
+      return options.namingStrategy.toolNameGenerator(path, method, operationId);
     }
     if (operationId) {
       return operationId;
     }
-    const sanitized = path2.replace(/\{([^}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+    const sanitized = path.replace(/\{([^}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
     return `${method}_${sanitized}`;
   }
   /**
    * Extract metadata from operation
    */
-  extractMetadata(path2, method, operation, document, outputSchema) {
+  extractMetadata(path, method, operation, document, outputSchema) {
     const metadata = {
-      path: path2,
+      path,
       method,
       operationId: operation.operationId,
       operationSummary: operation.summary,
@@ -1703,16 +1922,18 @@ var SecurityResolver = class {
   resolveDigestAuth(context) {
     const digest = context.digest;
     if (!digest) return void 0;
+    const quoted = (v) => String(v).replace(/[\r\n]/g, "").replace(/"/g, '\\"');
+    const token = (v) => String(v).replace(/[\r\n",]/g, "");
     const parts = [
-      `username="${digest.username}"`,
-      digest.realm ? `realm="${digest.realm}"` : "",
-      digest.nonce ? `nonce="${digest.nonce}"` : "",
-      digest.uri ? `uri="${digest.uri}"` : "",
-      digest.response ? `response="${digest.response}"` : "",
-      digest.opaque ? `opaque="${digest.opaque}"` : "",
-      digest.qop ? `qop=${digest.qop}` : "",
-      digest.nc ? `nc=${digest.nc}` : "",
-      digest.cnonce ? `cnonce="${digest.cnonce}"` : ""
+      `username="${quoted(digest.username)}"`,
+      digest.realm ? `realm="${quoted(digest.realm)}"` : "",
+      digest.nonce ? `nonce="${quoted(digest.nonce)}"` : "",
+      digest.uri ? `uri="${quoted(digest.uri)}"` : "",
+      digest.response ? `response="${quoted(digest.response)}"` : "",
+      digest.opaque ? `opaque="${quoted(digest.opaque)}"` : "",
+      digest.qop ? `qop=${token(digest.qop)}` : "",
+      digest.nc ? `nc=${token(digest.nc)}` : "",
+      digest.cnonce ? `cnonce="${quoted(digest.cnonce)}"` : ""
     ].filter(Boolean);
     return `Digest ${parts.join(", ")}`;
   }
@@ -1819,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,
@@ -1830,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,9 +1,10 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.3.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",
+  "packageManager": "yarn@4.14.1",
   "keywords": [
     "mcp",
     "model-context-protocol",