mcp-from-openapi 2.3.0 → 2.4.0

package/esm/index.mjs

@@ -1,7 +1,5 @@
 // src/generator.ts
 import * as yaml from "yaml";
-import * as path from "path";
-import * as fs from "fs/promises";
 
 // src/types.ts
 function isReferenceObject(obj) {
@@ -536,12 +534,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"
         });
       }
@@ -551,13 +549,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"
         });
       }
@@ -566,33 +564,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"
         });
@@ -602,8 +600,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}`;
@@ -858,6 +856,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();
@@ -948,6 +947,31 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     /^\[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).
    */
@@ -958,11 +982,16 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     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;
+    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;
@@ -992,6 +1021,14 @@ 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` (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.
+        redirects: 0,
         canRead: (file) => {
           try {
             const parsed = new URL(file.url);
@@ -1016,23 +1053,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) {
@@ -1130,7 +1219,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;
     }
@@ -1147,7 +1236,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     if (options.filterFn) {
       return options.filterFn({
         ...operation,
-        path: path2,
+        path,
         method
       });
     }
@@ -1156,22 +1245,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,
@@ -1651,16 +1740,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(", ")}`;
   }

package/esm/package.json

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

package/generator.d.ts

@@ -39,6 +39,15 @@ export declare class OpenAPIToolGenerator {
      * 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).
      */
@@ -48,6 +57,20 @@ export declare class OpenAPIToolGenerator {
      * Defaults: allow http/https, block file://, block internal IPs.
      */
     private buildRefParserOptions;
+    /**
+     * 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.
+     */
+    private static hasExternalRefs;
+    /**
+     * 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`).
+     */
+    private static dereferenceInternal;
     /**
      * Initialize the generator (dereference if needed, then validate)
      */

package/index.js

@@ -52,8 +52,6 @@ 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 +586,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 +601,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 +616,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 +652,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}`;
@@ -910,6 +908,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();
@@ -1000,6 +999,31 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     /^\[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).
    */
@@ -1010,11 +1034,16 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     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;
+    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;
@@ -1044,6 +1073,14 @@ 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` (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.
+        redirects: 0,
         canRead: (file) => {
           try {
             const parsed = new URL(file.url);
@@ -1068,23 +1105,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 +1271,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 +1288,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     if (options.filterFn) {
       return options.filterFn({
         ...operation,
-        path: path2,
+        path,
         method
       });
     }
@@ -1208,22 +1297,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 +1792,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(", ")}`;
   }

package/package.json

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