@scalar/json-magic 0.13.3 → 0.13.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalar/json-magic
 
+## 0.13.4
+
+### Patch Changes
+
+- [#10079](https://github.com/scalar/scalar/pull/10079): Harden the mock server against SSRF and local file disclosure through OpenAPI `$ref`s. External `$ref` resolution now refuses to fetch private, loopback, link-local, and metadata addresses, and confines local file reads to the document's directory. The `fetchUrls` and `readFiles` bundling plugins gain opt-in `blockPrivateNetworks` and `basePath` options, so other callers keep their current behavior unless they opt in.
+
 ## 0.13.3
 
 ## 0.13.2

package/dist/bundle/plugins/browser.d.ts

@@ -1,4 +1,4 @@
-export { fetchUrls } from './fetch-urls/index.js';
+export { fetchUrls } from './fetch-urls/browser.js';
 export { parseJson } from './parse-json/index.js';
 export { parseYaml } from './parse-yaml/index.js';
 //# sourceMappingURL=browser.d.ts.map

package/dist/bundle/plugins/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/bundle/plugins/browser.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/bundle/plugins/browser.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA"}

package/dist/bundle/plugins/browser.js

@@ -1,4 +1,4 @@
 // biome-ignore lint/performance/noBarrelFile: entrypoint
-export { fetchUrls } from './fetch-urls/index.js';
+export { fetchUrls } from './fetch-urls/browser.js';
 export { parseJson } from './parse-json/index.js';
 export { parseYaml } from './parse-yaml/index.js';

package/dist/bundle/plugins/fetch-urls/browser.d.ts

@@ -0,0 +1,16 @@
+import type { LoaderPlugin } from '../../../bundle/index.js';
+type FetchConfig = Partial<{
+    headers: {
+        headers: HeadersInit;
+        domains: string[];
+    }[];
+    fetch: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+}>;
+/**
+ * Creates a browser-safe plugin for handling remote URL references.
+ */
+export declare const fetchUrls: (config?: FetchConfig & Partial<{
+    limit: number | null;
+}>) => LoaderPlugin;
+export {};
+//# sourceMappingURL=browser.d.ts.map

package/dist/bundle/plugins/fetch-urls/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/browser.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,UAAU,CAAA;AAI3D,KAAK,WAAW,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAA;IACtD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC3F,CAAC,CAAA;AA+CF;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,WAAW,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,KAAG,YAQpF,CAAA"}

package/dist/bundle/plugins/fetch-urls/browser.js

@@ -0,0 +1,51 @@
+import { createLimiter } from '@scalar/helpers/general/create-limiter';
+import { isHttpUrl } from '../../../helpers/is-http-url.js';
+import { normalize } from '../../../helpers/normalize.js';
+/**
+ * Safely checks for host from a URL.
+ * Needed because we cannot create a URL from a relative remote URL such as examples/openapi.json.
+ */
+const getHost = (url) => {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Fetches and normalizes data from a remote URL in a browser environment.
+ */
+const fetchUrl = async (url, limiter, config) => {
+    try {
+        const host = getHost(url);
+        const headers = config?.headers?.find((a) => a.domains.find((d) => d === host) !== undefined)?.headers;
+        const exec = config?.fetch ?? fetch;
+        const result = await limiter(() => exec(url, { headers }));
+        if (result.ok) {
+            const body = await result.text();
+            return { ok: true, data: normalize(body), raw: body };
+        }
+        const contentType = result.headers.get('Content-Type') ?? '';
+        if (['text/html', 'application/xml'].includes(contentType)) {
+            console.warn(`[WARN] We only support JSON/YAML formats, received ${contentType}`);
+        }
+        console.warn(`[WARN] Fetch failed with status ${result.status} ${result.statusText} for URL: ${url}`);
+        return { ok: false };
+    }
+    catch {
+        console.warn(`[WARN] Failed to parse JSON/YAML from URL: ${url}`);
+        return { ok: false };
+    }
+};
+/**
+ * Creates a browser-safe plugin for handling remote URL references.
+ */
+export const fetchUrls = (config) => {
+    const limiter = config?.limit ? createLimiter(config.limit) : (fn) => fn();
+    return {
+        type: 'loader',
+        validate: isHttpUrl,
+        exec: (value) => fetchUrl(value, limiter, config),
+    };
+};

package/dist/bundle/plugins/fetch-urls/index.d.ts

@@ -5,6 +5,12 @@ type FetchConfig = Partial<{
         domains: string[];
     }[];
     fetch: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+    /**
+     * When true, refuse to fetch URLs that resolve to a private, loopback, link-local, or otherwise
+     * internal address. Only enforced in Node, where DNS resolution is available. Off by default so
+     * existing callers keep working unchanged.
+     */
+    blockPrivateNetworks: boolean;
 }>;
 /**
  * Fetches and normalizes data from a remote URL

package/dist/bundle/plugins/fetch-urls/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAI3D,KAAK,WAAW,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAA;IACtD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC3F,CAAC,CAAA;AAcF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CA0CxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,GAAG,YAAY,CAShG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAI3D,KAAK,WAAW,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAA;IACtD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC1F;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAA;CAC9B,CAAC,CAAA;AAyBF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAkExB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,GAAG,YAAY,CAShG"}

package/dist/bundle/plugins/fetch-urls/index.js

@@ -13,6 +13,17 @@ const getHost = (url) => {
         return null;
     }
 };
+/**
+ * Safely reads the hostname (without port) from a URL, for the private-address check.
+ */
+const getHostname = (url) => {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return null;
+    }
+};
 /**
  * Fetches and normalizes data from a remote URL
  * @param url - The URL to fetch data from
@@ -29,12 +40,31 @@ const getHost = (url) => {
  */
 export async function fetchUrl(url, limiter, config) {
     try {
+        // SSRF guard: optionally refuse to fetch internal or private targets before making the request.
+        // Only runs in Node, since the browser build has no DNS access and its own network isolation.
+        if (config?.blockPrivateNetworks && typeof window === 'undefined') {
+            const hostname = getHostname(url);
+            if (hostname) {
+                const { isBlockedHost } = await import('./is-blocked-host.js');
+                if (await isBlockedHost(hostname)) {
+                    console.warn(`[WARN] Refused to fetch a private or internal address: ${url}`);
+                    return {
+                        ok: false,
+                    };
+                }
+            }
+        }
         const host = getHost(url);
         // Get the headers that match the domain
         const headers = config?.headers?.find((a) => a.domains.find((d) => d === host) !== undefined)?.headers;
         const exec = config?.fetch ?? fetch;
+        // Under the SSRF guard, do not follow redirects. Otherwise a public URL that passes the host
+        // check above could redirect to an internal target (for example the metadata endpoint) that
+        // the redirect would reach without being re-validated.
+        const redirect = config?.blockPrivateNetworks && typeof window === 'undefined' ? 'error' : undefined;
         const result = await limiter(() => exec(url, {
             headers,
+            redirect,
         }));
         if (result.ok) {
             const body = await result.text();

package/dist/bundle/plugins/fetch-urls/is-blocked-host.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reports whether a hostname resolves to a private, loopback, link-local, or otherwise internal
+ * address that a bundled `$ref` should not be allowed to reach.
+ *
+ * Literal IPs are checked directly. Hostnames are resolved via DNS and every returned address is
+ * checked, so a name that points at an internal IP is rejected. A host that cannot be resolved is
+ * treated as blocked.
+ *
+ * This lives in a Node-only module because it depends on `node:dns` and `node:net`. Load it with a
+ * dynamic import so the browser build of the fetch plugin stays free of Node built-ins.
+ *
+ * @param hostname - The hostname or IP (brackets around an IPv6 literal are tolerated).
+ */
+export declare const isBlockedHost: (hostname: string) => Promise<boolean>;
+//# sourceMappingURL=is-blocked-host.d.ts.map

package/dist/bundle/plugins/fetch-urls/is-blocked-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-blocked-host.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/is-blocked-host.ts"],"names":[],"mappings":"AAmEA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,OAAO,CAerE,CAAA"}

package/dist/bundle/plugins/fetch-urls/is-blocked-host.js

@@ -0,0 +1,81 @@
+import { lookup } from 'node:dns/promises';
+import { BlockList, isIP, isIPv4 } from 'node:net';
+/**
+ * Address ranges that must never be reachable through a bundled `$ref`.
+ *
+ * Covers loopback, private, link-local (including the cloud metadata endpoint 169.254.169.254),
+ * carrier-grade NAT, and their IPv6 equivalents. The IPv6 transition ranges (6to4, NAT64, Teredo,
+ * IPv4-compatible) are blocked wholesale so an address like 64:ff9b::a9fe:a9fe cannot smuggle a
+ * private IPv4 destination past the checks. Those ranges are deprecated or rarely used for real API
+ * hosting, so blocking them outright is a safe trade.
+ */
+const blockList = new BlockList();
+blockList.addAddress('0.0.0.0', 'ipv4');
+blockList.addSubnet('127.0.0.0', 8, 'ipv4');
+blockList.addSubnet('10.0.0.0', 8, 'ipv4');
+blockList.addSubnet('172.16.0.0', 12, 'ipv4');
+blockList.addSubnet('192.168.0.0', 16, 'ipv4');
+blockList.addSubnet('169.254.0.0', 16, 'ipv4');
+blockList.addSubnet('100.64.0.0', 10, 'ipv4');
+blockList.addSubnet('::', 96, 'ipv6'); // unspecified, loopback (::1), and deprecated IPv4-compatible
+blockList.addSubnet('fe80::', 10, 'ipv6'); // link-local
+blockList.addSubnet('fc00::', 7, 'ipv6'); // unique local
+blockList.addSubnet('2002::', 16, 'ipv6'); // 6to4
+blockList.addSubnet('64:ff9b::', 96, 'ipv6'); // NAT64
+blockList.addSubnet('2001::', 32, 'ipv6'); // Teredo
+/**
+ * Checks whether a single IP address falls inside a blocked range.
+ */
+const ipIsBlocked = (ip) => {
+    const family = isIP(ip);
+    if (family === 0) {
+        // Not a valid IP, block to be safe
+        return true;
+    }
+    if (blockList.check(ip, family === 4 ? 'ipv4' : 'ipv6')) {
+        return true;
+    }
+    // Normalize an IPv4-mapped IPv6 address (::ffff:x.x.x.x, in dotted or hex form) and re-check it
+    // against the IPv4 rules, since it targets the embedded IPv4 destination.
+    const dotted = ip.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+    if (dotted && isIPv4(dotted[1]) && blockList.check(dotted[1], 'ipv4')) {
+        return true;
+    }
+    const hex = ip.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (hex) {
+        const high = Number.parseInt(hex[1], 16);
+        const low = Number.parseInt(hex[2], 16);
+        const mapped = `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
+        if (blockList.check(mapped, 'ipv4')) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * Reports whether a hostname resolves to a private, loopback, link-local, or otherwise internal
+ * address that a bundled `$ref` should not be allowed to reach.
+ *
+ * Literal IPs are checked directly. Hostnames are resolved via DNS and every returned address is
+ * checked, so a name that points at an internal IP is rejected. A host that cannot be resolved is
+ * treated as blocked.
+ *
+ * This lives in a Node-only module because it depends on `node:dns` and `node:net`. Load it with a
+ * dynamic import so the browser build of the fetch plugin stays free of Node built-ins.
+ *
+ * @param hostname - The hostname or IP (brackets around an IPv6 literal are tolerated).
+ */
+export const isBlockedHost = async (hostname) => {
+    const host = hostname.replace(/^\[/, '').replace(/\]$/, '');
+    if (isIP(host)) {
+        return ipIsBlocked(host);
+    }
+    try {
+        const addresses = await lookup(host, { all: true });
+        return addresses.some(({ address }) => ipIsBlocked(address));
+    }
+    catch {
+        // Block when the host cannot be resolved
+        return true;
+    }
+};

package/dist/bundle/plugins/read-files/index.d.ts

@@ -1,7 +1,8 @@
 import type { LoaderPlugin, ResolveResult } from '../../../bundle/index.js';
 /**
  * Reads and normalizes data from a local file
- * @param path - The file path to read from
+ * @param filePath - The file path to read from
+ * @param basePath - When set, reads are confined to this directory so a `$ref` cannot escape it
  * @returns A promise that resolves to either the normalized data or an error result
  * @example
  * ```ts
@@ -13,17 +14,20 @@ import type { LoaderPlugin, ResolveResult } from '../../../bundle/index.js';
  * }
  * ```
  */
-export declare function readFile(path: string): Promise<ResolveResult>;
+export declare function readFile(filePath: string, basePath?: string): Promise<ResolveResult>;
 /**
  * Creates a plugin for handling local file references.
  * This plugin validates and reads data from local filesystem paths.
  *
  * @returns A plugin object with validate and exec functions
+ * @param config - Optional settings. `basePath` confines reads to a directory.
  * @example
  * const filePlugin = readFiles()
  * if (filePlugin.validate('./local-schema.json')) {
  *   const result = await filePlugin.exec('./local-schema.json')
  * }
  */
-export declare function readFiles(): LoaderPlugin;
+export declare function readFiles(config?: {
+    basePath?: string;
+}): LoaderPlugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/bundle/plugins/read-files/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/read-files/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAI3D;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAoBnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAMxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/read-files/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AA8B3D;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6B1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAMtE"}

package/dist/bundle/plugins/read-files/index.js

@@ -1,8 +1,32 @@
+import path from 'pathe';
 import { isFilePath } from '../../../helpers/is-file-path.js';
 import { normalize } from '../../../helpers/normalize.js';
+/**
+ * Resolves a path to its real location, following symlinks. Falls back to a lexical resolve when the
+ * path does not exist yet, so a missing file is still confined (the read fails afterwards anyway).
+ */
+const realpathOrResolve = async (fs, target) => {
+    try {
+        return await fs.realpath(path.resolve(target));
+    }
+    catch {
+        return path.resolve(target);
+    }
+};
+/**
+ * Reports whether a file escapes the allowed base directory. Symlinks are dereferenced first, so a
+ * link inside the base directory cannot point at a file outside it.
+ */
+const isOutsideBasePath = async (fs, filePath, basePath) => {
+    const realBase = await realpathOrResolve(fs, basePath);
+    const realTarget = await realpathOrResolve(fs, filePath);
+    const relative = path.relative(realBase, realTarget);
+    return relative === '..' || relative.startsWith('../') || path.isAbsolute(relative);
+};
 /**
  * Reads and normalizes data from a local file
- * @param path - The file path to read from
+ * @param filePath - The file path to read from
+ * @param basePath - When set, reads are confined to this directory so a `$ref` cannot escape it
  * @returns A promise that resolves to either the normalized data or an error result
  * @example
  * ```ts
@@ -14,13 +38,21 @@ import { normalize } from '../../../helpers/normalize.js';
  * }
  * ```
  */
-export async function readFile(path) {
+export async function readFile(filePath, basePath) {
     const fs = typeof window === 'undefined' ? await import('node:fs/promises') : undefined;
     if (fs === undefined) {
         throw 'Can not use readFiles plugin outside of a node environment';
     }
+    // Confine reads to basePath when provided, so a `$ref` like `../../../../etc/passwd` (or a symlink
+    // pointing outside the directory) cannot read files outside the document's directory.
+    if (basePath !== undefined && (await isOutsideBasePath(fs, filePath, basePath))) {
+        console.warn(`[WARN] Refused to read a file outside the allowed directory: ${filePath}`);
+        return {
+            ok: false,
+        };
+    }
     try {
-        const fileContents = await fs.readFile(path, { encoding: 'utf-8' });
+        const fileContents = await fs.readFile(filePath, { encoding: 'utf-8' });
         return {
             ok: true,
             data: normalize(fileContents),
@@ -38,16 +70,17 @@ export async function readFile(path) {
  * This plugin validates and reads data from local filesystem paths.
  *
  * @returns A plugin object with validate and exec functions
+ * @param config - Optional settings. `basePath` confines reads to a directory.
  * @example
  * const filePlugin = readFiles()
  * if (filePlugin.validate('./local-schema.json')) {
  *   const result = await filePlugin.exec('./local-schema.json')
  * }
  */
-export function readFiles() {
+export function readFiles(config) {
     return {
         type: 'loader',
         validate: isFilePath,
-        exec: readFile,
+        exec: (value) => readFile(value, config?.basePath),
     };
 }

package/package.json

@@ -10,7 +10,7 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "packages/json-magic"
   },
-  "version": "0.13.3",
+  "version": "0.13.4",
   "engines": {
     "node": ">=22"
   },
@@ -109,7 +109,7 @@
   "dependencies": {
     "pathe": "^2.0.3",
     "yaml": "^2.9.0",
-    "@scalar/helpers": "0.11.2"
+    "@scalar/helpers": "0.11.3"
   },
   "devDependencies": {
     "fastify": "^5.11.2",