@apidevtools/json-schema-ref-parser 13.0.5 → 14.0.0

package/dist/lib/index.d.ts

@@ -5,6 +5,7 @@ import { JSONParserError, InvalidPointerError, MissingPointerError, ResolverErro
 import type { ParserOptions } from "./options.js";
 import { getJsonSchemaRefParserDefaultOptions } from "./options.js";
 import type { $RefsCallback, JSONSchema, SchemaCallback, FileInfo, Plugin, ResolverOptions, HTTPResolverOptions } from "./types/index.js";
+import { isUnsafeUrl } from "./util/url.js";
 export type RefParserSchema = string | JSONSchema;
 /**
  * This class parses a JSON schema, builds a map of its JSON references and their resolved values,
@@ -159,4 +160,4 @@ export declare const parse: typeof $RefParser.parse;
 export declare const resolve: typeof $RefParser.resolve;
 export declare const bundle: typeof $RefParser.bundle;
 export declare const dereference: typeof $RefParser.dereference;
-export { UnmatchedResolverError, JSONParserError, JSONSchema, InvalidPointerError, MissingPointerError, ResolverError, ParserError, UnmatchedParserError, ParserOptions, $RefsCallback, isHandledError, JSONParserErrorGroup, SchemaCallback, FileInfo, Plugin, ResolverOptions, HTTPResolverOptions, _dereference as dereferenceInternal, normalizeArgs as jsonSchemaParserNormalizeArgs, getJsonSchemaRefParserDefaultOptions, $Refs, };
+export { UnmatchedResolverError, JSONParserError, JSONSchema, InvalidPointerError, MissingPointerError, ResolverError, ParserError, UnmatchedParserError, ParserOptions, $RefsCallback, isHandledError, JSONParserErrorGroup, SchemaCallback, FileInfo, Plugin, ResolverOptions, HTTPResolverOptions, _dereference as dereferenceInternal, normalizeArgs as jsonSchemaParserNormalizeArgs, getJsonSchemaRefParserDefaultOptions, $Refs, isUnsafeUrl, };

package/dist/lib/index.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.$Refs = exports.getJsonSchemaRefParserDefaultOptions = exports.jsonSchemaParserNormalizeArgs = exports.dereferenceInternal = exports.JSONParserErrorGroup = exports.isHandledError = exports.UnmatchedParserError = exports.ParserError = exports.ResolverError = exports.MissingPointerError = exports.InvalidPointerError = exports.JSONParserError = exports.UnmatchedResolverError = exports.dereference = exports.bundle = exports.resolve = exports.parse = exports.$RefParser = void 0;
+exports.isUnsafeUrl = exports.$Refs = exports.getJsonSchemaRefParserDefaultOptions = exports.jsonSchemaParserNormalizeArgs = exports.dereferenceInternal = exports.JSONParserErrorGroup = exports.isHandledError = exports.UnmatchedParserError = exports.ParserError = exports.ResolverError = exports.MissingPointerError = exports.InvalidPointerError = exports.JSONParserError = exports.UnmatchedResolverError = exports.dereference = exports.bundle = exports.resolve = exports.parse = exports.$RefParser = void 0;
 const refs_js_1 = __importDefault(require("./refs.js"));
 exports.$Refs = refs_js_1.default;
 const parse_js_1 = __importDefault(require("./parse.js"));
@@ -60,6 +60,8 @@ Object.defineProperty(exports, "JSONParserErrorGroup", { enumerable: true, get:
 const maybe_js_1 = __importDefault(require("./util/maybe.js"));
 const options_js_1 = require("./options.js");
 Object.defineProperty(exports, "getJsonSchemaRefParserDefaultOptions", { enumerable: true, get: function () { return options_js_1.getJsonSchemaRefParserDefaultOptions; } });
+const url_js_1 = require("./util/url.js");
+Object.defineProperty(exports, "isUnsafeUrl", { enumerable: true, get: function () { return url_js_1.isUnsafeUrl; } });
 /**
  * This class parses a JSON schema, builds a map of its JSON references and their resolved values,
  * and provides methods for traversing, manipulating, and dereferencing those references.

package/dist/lib/resolvers/http.js

@@ -64,13 +64,17 @@ exports.default = {
      * Set this to `true` if you're downloading files from a CORS-enabled server that requires authentication
      */
     withCredentials: false,
+    /**
+     * Set this to `false` if you want to allow unsafe URLs (e.g., `127.0.0.1`, localhost, and other internal URLs).
+     */
+    safeUrlResolver: true,
     /**
      * Determines whether this resolver can read a given file reference.
      * Resolvers that return true will be tried in order, until one successfully resolves the file.
      * Resolvers that return false will not be given a chance to resolve the file.
      */
     canRead(file) {
-        return url.isHttp(file.url);
+        return url.isHttp(file.url) && (!this.safeUrlResolver || !url.isUnsafeUrl(file.url));
     },
     /**
      * Reads the given URL and returns its raw contents as a Buffer.

package/dist/lib/types/index.d.ts

@@ -25,6 +25,10 @@ export interface HTTPResolverOptions<S extends object = JSONSchema> extends Part
      * Set this to `true` if you're downloading files from a CORS-enabled server that requires authentication
      */
     withCredentials?: boolean;
+    /**
+     * Set this to `false` if you want to allow unsafe URLs (e.g., `127.0.0.1`, localhost, and other internal URLs).
+     */
+    safeUrlResolver: true;
 }
 /**
  * JSON Schema `$Ref` Parser comes with built-in resolvers for HTTP and HTTPS URLs, as well as local filesystem paths (when running in Node.js). You can add your own custom resolvers to support additional protocols, or even replace any of the built-in resolvers with your own custom implementation.

package/dist/lib/util/url.d.ts

@@ -55,6 +55,13 @@ export declare function stripHash(path?: string | undefined): string;
  * @returns
  */
 export declare function isHttp(path: string): boolean;
+/**
+ * Determines whether the given url is an unsafe or internal url.
+ *
+ * @param path - The URL or path to check
+ * @returns true if the URL is unsafe/internal, false otherwise
+ */
+export declare function isUnsafeUrl(path: string): boolean;
 /**
  * Determines whether the given path is a filesystem path.
  * This includes "file://" URLs.

package/dist/lib/util/url.js

@@ -45,6 +45,7 @@ exports.stripQuery = stripQuery;
 exports.getHash = getHash;
 exports.stripHash = stripHash;
 exports.isHttp = isHttp;
+exports.isUnsafeUrl = isUnsafeUrl;
 exports.isFileSystemPath = isFileSystemPath;
 exports.fromFileSystemPath = fromFileSystemPath;
 exports.toFileSystemPath = toFileSystemPath;
@@ -209,6 +210,152 @@ function isHttp(path) {
         return false;
     }
 }
+/**
+ * Determines whether the given url is an unsafe or internal url.
+ *
+ * @param path - The URL or path to check
+ * @returns true if the URL is unsafe/internal, false otherwise
+ */
+function isUnsafeUrl(path) {
+    if (!path || typeof path !== "string") {
+        return true;
+    }
+    // Trim whitespace and convert to lowercase for comparison
+    const normalizedPath = path.trim().toLowerCase();
+    // Empty or just whitespace
+    if (!normalizedPath) {
+        return true;
+    }
+    // JavaScript protocols
+    if (normalizedPath.startsWith("javascript:") ||
+        normalizedPath.startsWith("vbscript:") ||
+        normalizedPath.startsWith("data:")) {
+        return true;
+    }
+    // File protocol
+    if (normalizedPath.startsWith("file:")) {
+        return true;
+    }
+    // if we're in the browser, we assume that it is safe
+    if (typeof window !== "undefined" && window.location && window.location.href) {
+        return false;
+    }
+    // Local/internal network addresses
+    const localPatterns = [
+        // Localhost variations
+        "localhost",
+        "127.0.0.1",
+        "::1",
+        // Private IP ranges (RFC 1918)
+        "10.",
+        "172.16.",
+        "172.17.",
+        "172.18.",
+        "172.19.",
+        "172.20.",
+        "172.21.",
+        "172.22.",
+        "172.23.",
+        "172.24.",
+        "172.25.",
+        "172.26.",
+        "172.27.",
+        "172.28.",
+        "172.29.",
+        "172.30.",
+        "172.31.",
+        "192.168.",
+        // Link-local addresses
+        "169.254.",
+        // Internal domains
+        ".local",
+        ".internal",
+        ".intranet",
+        ".corp",
+        ".home",
+        ".lan",
+    ];
+    try {
+        // Try to parse as URL
+        const url = new URL(normalizedPath.startsWith("//") ? "http:" + normalizedPath : normalizedPath);
+        const hostname = url.hostname.toLowerCase();
+        // Check against local patterns
+        for (const pattern of localPatterns) {
+            if (hostname === pattern || hostname.startsWith(pattern) || hostname.endsWith(pattern)) {
+                return true;
+            }
+        }
+        // Check for IP addresses in private ranges
+        if (isPrivateIP(hostname)) {
+            return true;
+        }
+        // Check for non-standard ports that might indicate internal services
+        const port = url.port;
+        if (port && isInternalPort(parseInt(port))) {
+            return true;
+        }
+    }
+    catch (e) {
+        // If URL parsing fails, check if it's a relative path or contains suspicious patterns
+        // Relative paths starting with / are generally safe for same-origin
+        if (normalizedPath.startsWith("/") && !normalizedPath.startsWith("//")) {
+            return false;
+        }
+        // Check for localhost patterns in non-URL strings
+        for (const pattern of localPatterns) {
+            if (normalizedPath.includes(pattern)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Helper function to check if an IP address is in a private range
+ */
+function isPrivateIP(ip) {
+    const ipRegex = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+    const match = ip.match(ipRegex);
+    if (!match) {
+        return false;
+    }
+    const [, a, b, c, d] = match.map(Number);
+    // Validate IP format
+    if (a > 255 || b > 255 || c > 255 || d > 255) {
+        return false;
+    }
+    // Private IP ranges
+    return (a === 10 || a === 127 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254) // Link-local
+    );
+}
+/**
+ * Helper function to check if a port is typically used for internal services
+ */
+function isInternalPort(port) {
+    const internalPorts = [
+        22, // SSH
+        23, // Telnet
+        25, // SMTP
+        53, // DNS
+        135, // RPC
+        139, // NetBIOS
+        445, // SMB
+        993, // IMAPS
+        995, // POP3S
+        1433, // SQL Server
+        1521, // Oracle
+        3306, // MySQL
+        3389, // RDP
+        5432, // PostgreSQL
+        5900, // VNC
+        6379, // Redis
+        8080, // Common internal web
+        8443, // Common internal HTTPS
+        9200, // Elasticsearch
+        27017, // MongoDB
+    ];
+    return internalPorts.includes(port);
+}
 /**
  * Determines whether the given path is a filesystem path.
  * This includes "file://" URLs.

package/lib/index.ts

@@ -28,6 +28,7 @@ import type {
   ResolverOptions,
   HTTPResolverOptions,
 } from "./types/index.js";
+import { isUnsafeUrl } from "./util/url.js";
 
 export type RefParserSchema = string | JSONSchema;
 
@@ -439,4 +440,5 @@ export {
   normalizeArgs as jsonSchemaParserNormalizeArgs,
   getJsonSchemaRefParserDefaultOptions,
   $Refs,
+  isUnsafeUrl,
 };

package/lib/resolvers/http.ts

@@ -36,13 +36,18 @@ export default {
    */
   withCredentials: false,
 
+  /**
+   * Set this to `false` if you want to allow unsafe URLs (e.g., `127.0.0.1`, localhost, and other internal URLs).
+   */
+  safeUrlResolver: true,
+
   /**
    * Determines whether this resolver can read a given file reference.
    * Resolvers that return true will be tried in order, until one successfully resolves the file.
    * Resolvers that return false will not be given a chance to resolve the file.
    */
   canRead(file: FileInfo) {
-    return url.isHttp(file.url);
+    return url.isHttp(file.url) && (!this.safeUrlResolver || !url.isUnsafeUrl(file.url));
   },
 
   /**

package/lib/types/index.ts

@@ -41,6 +41,11 @@ export interface HTTPResolverOptions<S extends object = JSONSchema> extends Part
    * Set this to `true` if you're downloading files from a CORS-enabled server that requires authentication
    */
   withCredentials?: boolean;
+
+  /**
+   * Set this to `false` if you want to allow unsafe URLs (e.g., `127.0.0.1`, localhost, and other internal URLs).
+   */
+  safeUrlResolver: true;
 }
 
 /**

package/lib/util/url.ts

@@ -167,7 +167,178 @@ export function isHttp(path: string) {
     return false;
   }
 }
+/**
+ * Determines whether the given url is an unsafe or internal url.
+ *
+ * @param path - The URL or path to check
+ * @returns true if the URL is unsafe/internal, false otherwise
+ */
+export function isUnsafeUrl(path: string): boolean {
+  if (!path || typeof path !== "string") {
+    return true;
+  }
+
+  // Trim whitespace and convert to lowercase for comparison
+  const normalizedPath = path.trim().toLowerCase();
 
+  // Empty or just whitespace
+  if (!normalizedPath) {
+    return true;
+  }
+
+  // JavaScript protocols
+  if (
+    normalizedPath.startsWith("javascript:") ||
+    normalizedPath.startsWith("vbscript:") ||
+    normalizedPath.startsWith("data:")
+  ) {
+    return true;
+  }
+
+  // File protocol
+  if (normalizedPath.startsWith("file:")) {
+    return true;
+  }
+
+  // if we're in the browser, we assume that it is safe
+  if (typeof window !== "undefined" && window.location && window.location.href) {
+    return false;
+  }
+
+  // Local/internal network addresses
+  const localPatterns = [
+    // Localhost variations
+    "localhost",
+    "127.0.0.1",
+    "::1",
+
+    // Private IP ranges (RFC 1918)
+    "10.",
+    "172.16.",
+    "172.17.",
+    "172.18.",
+    "172.19.",
+    "172.20.",
+    "172.21.",
+    "172.22.",
+    "172.23.",
+    "172.24.",
+    "172.25.",
+    "172.26.",
+    "172.27.",
+    "172.28.",
+    "172.29.",
+    "172.30.",
+    "172.31.",
+    "192.168.",
+
+    // Link-local addresses
+    "169.254.",
+
+    // Internal domains
+    ".local",
+    ".internal",
+    ".intranet",
+    ".corp",
+    ".home",
+    ".lan",
+  ];
+
+  try {
+    // Try to parse as URL
+    const url = new URL(normalizedPath.startsWith("//") ? "http:" + normalizedPath : normalizedPath);
+
+    const hostname = url.hostname.toLowerCase();
+
+    // Check against local patterns
+    for (const pattern of localPatterns) {
+      if (hostname === pattern || hostname.startsWith(pattern) || hostname.endsWith(pattern)) {
+        return true;
+      }
+    }
+
+    // Check for IP addresses in private ranges
+    if (isPrivateIP(hostname)) {
+      return true;
+    }
+
+    // Check for non-standard ports that might indicate internal services
+    const port = url.port;
+    if (port && isInternalPort(parseInt(port))) {
+      return true;
+    }
+  } catch (e) {
+    // If URL parsing fails, check if it's a relative path or contains suspicious patterns
+
+    // Relative paths starting with / are generally safe for same-origin
+    if (normalizedPath.startsWith("/") && !normalizedPath.startsWith("//")) {
+      return false;
+    }
+
+    // Check for localhost patterns in non-URL strings
+    for (const pattern of localPatterns) {
+      if (normalizedPath.includes(pattern)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Helper function to check if an IP address is in a private range
+ */
+function isPrivateIP(ip: string): boolean {
+  const ipRegex = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+  const match = ip.match(ipRegex);
+
+  if (!match) {
+    return false;
+  }
+
+  const [, a, b, c, d] = match.map(Number);
+
+  // Validate IP format
+  if (a > 255 || b > 255 || c > 255 || d > 255) {
+    return false;
+  }
+
+  // Private IP ranges
+  return (
+    a === 10 || a === 127 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254) // Link-local
+  );
+}
+
+/**
+ * Helper function to check if a port is typically used for internal services
+ */
+function isInternalPort(port: number): boolean {
+  const internalPorts = [
+    22, // SSH
+    23, // Telnet
+    25, // SMTP
+    53, // DNS
+    135, // RPC
+    139, // NetBIOS
+    445, // SMB
+    993, // IMAPS
+    995, // POP3S
+    1433, // SQL Server
+    1521, // Oracle
+    3306, // MySQL
+    3389, // RDP
+    5432, // PostgreSQL
+    5900, // VNC
+    6379, // Redis
+    8080, // Common internal web
+    8443, // Common internal HTTPS
+    9200, // Elasticsearch
+    27017, // MongoDB
+  ];
+
+  return internalPorts.includes(port);
+}
 /**
  * Determines whether the given path is a filesystem path.
  * This includes "file://" URLs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apidevtools/json-schema-ref-parser",
-  "version": "13.0.5",
+  "version": "14.0.0",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "scripts": {
     "prepublishOnly": "yarn build",
@@ -67,16 +67,16 @@
     "cjs"
   ],
   "devDependencies": {
-    "@eslint/compat": "^1.2.9",
-    "@eslint/js": "^9.28.0",
+    "@eslint/compat": "^1.3.0",
+    "@eslint/js": "^9.29.0",
     "@types/eslint": "^9.6.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^24",
-    "@typescript-eslint/eslint-plugin": "^8.34.0",
-    "@typescript-eslint/parser": "^8.34.0",
+    "@typescript-eslint/eslint-plugin": "^8.34.1",
+    "@typescript-eslint/parser": "^8.34.1",
     "@vitest/coverage-v8": "^3.2.3",
     "cross-env": "^7.0.3",
-    "eslint": "^9.28.0",
+    "eslint": "^9.29.0",
     "eslint-config-prettier": "^10.1.5",
     "eslint-config-standard": "^17.1.0",
     "eslint-plugin-import": "^2.31.0",
@@ -88,7 +88,7 @@
     "prettier": "^3.5.3",
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.34.0",
+    "typescript-eslint": "^8.34.1",
     "vitest": "^3.2.3"
   },
   "dependencies": {