From 48ccd9dfd8e75c36cb0c9921ea756d01ee9ead6e Mon Sep 17 00:00:00 2001 From: Mradul Singh Date: Thu, 12 Nov 2026 23:03:48 +0530 Subject: [PATCH 1/2] fix: don't resolve local files from remote schemas A schema loaded from an http(s) URL could read any local file with $ref: "file:///...", or with a relative $ref under a file:// $id. This worked even with safeUrlResolver on. parse() now gets the URL of the document that holds the $ref and throws a ResolverError when an http(s) document points to a filesystem path. Both the default and the resolveExcludedPathMatcher resolve paths pass it. Fixes #433 --- docs/options.md | 2 + lib/parse.ts | 9 ++ lib/resolve-external.ts | 3 +- lib/resolve-external/with-matcher.ts | 1 + .../remote-local-file.spec.ts | 124 ++++++++++++++++++ 5 files changed, 138 insertions(+), 1 deletion(-) create mode 100644 test/specs/remote-local-file/remote-local-file.spec.ts diff --git a/docs/options.md b/docs/options.md index f761e0a7..1ba17673 100644 --- a/docs/options.md +++ b/docs/options.md @@ -78,6 +78,8 @@ JSON Schema $Ref Parser comes with built-in support for HTTP and HTTPS, as well | `http.withCredentials` | `boolean` | Set this to `true` if you're downloading files from a CORS-enabled server that requires authentication | | `http.maxContentLength` | `number` | The maximum size (in bytes) of a downloaded file, including its decompressed contents. With `safeUrlResolver` enabled in Node.js, the encoded body and each intermediate decoding stage are also limited. Larger responses are rejected. The default is 50 MiB. | +A schema loaded from an HTTP or HTTPS URL can't reference local files. A `$ref` in such a schema that resolves to a filesystem path (including a `file://` URL, or a relative `$ref` under a `file://` `$id`) fails with a `ResolverError`. This also applies when the root schema object is passed in with an HTTP(S) path. + The Node.js HTTP resolver supports gzip, deflate, Brotli, and Zstandard responses, with at most five compression layers. It requests `gzip, deflate, br` by default and preserves a custom `Accept-Encoding` header. Download timeouts remain active through decompression. `resolveExcludedPathMatcher(path, value)` is a top-level option that stops resolution and fetching for a root-relative occurrence and all of its descendants. It is separate from the `resolve` map because every key in that map can be a custom resolver plugin. A reference and its resolved effective value can both be evaluated at the same root-relative path; extended-reference values are merged before their descendants are inspected. Internal alias traversal uses `dereference.maxDepth` as its safety limit. diff --git a/lib/parse.ts b/lib/parse.ts index b888863f..9dca9460 100644 --- a/lib/parse.ts +++ b/lib/parse.ts @@ -16,6 +16,8 @@ interface ParseTarget { url: string; reference?: string; baseUrl?: string; + /** The URL of the document that contains the `$ref`, without the hash. */ + referrer?: string; } /** @@ -29,6 +31,7 @@ async function parse = let path = typeof target === "string" ? target : target.url; const baseUrl = typeof target === "string" ? undefined : target.baseUrl; let reference = typeof target === "string" ? undefined : target.reference; + const referrer = typeof target === "string" ? undefined : target.referrer; // Remove the URL fragment, if any const hashIndex = path.indexOf("#"); @@ -60,6 +63,12 @@ async function parse = // Read the file and then parse the data try { + // A schema loaded from an HTTP(S) URL must not pull in local files. Without this check, + // a remote schema could read any file on the host with `$ref: "file:///..."`. + if (referrer && url.isHttp(referrer) && url.isFileSystemPath(path)) { + throw new ResolverError(new Error(`Cannot resolve local file "${path}" from remote schema "${referrer}"`), path); + } + const resolver = await readFile(file, options, $refs); $ref.pathType = resolver.plugin.name; file.data = resolver.result; diff --git a/lib/resolve-external.ts b/lib/resolve-external.ts index b131407c..dfe2cecf 100644 --- a/lib/resolve-external.ts +++ b/lib/resolve-external.ts @@ -176,9 +176,10 @@ async function resolve$Ref url: resolvedPath, baseUrl: resolutionBase, reference: reference.$ref, + referrer: url.stripHash(path), }, context.$refs, context.options, diff --git a/test/specs/remote-local-file/remote-local-file.spec.ts b/test/specs/remote-local-file/remote-local-file.spec.ts new file mode 100644 index 00000000..f34eacdf --- /dev/null +++ b/test/specs/remote-local-file/remote-local-file.spec.ts @@ -0,0 +1,124 @@ +import fs from "node:fs"; +import os from "node:os"; +import nodePath from "node:path"; +import { pathToFileURL } from "node:url"; +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import $RefParser from "../../../lib/index.js"; +import { ResolverError } from "../../../lib/util/errors.js"; +import helper from "../../utils/helper.js"; + +const isBrowser = typeof window !== "undefined"; + +describe.skipIf(isBrowser)("Local files referenced from a remote schema", () => { + let dir: string; + let secretPath: string; + let secretUrl: string; + + beforeAll(() => { + dir = fs.mkdtempSync(nodePath.join(os.tmpdir(), "json-schema-ref-parser-")); + secretPath = nodePath.join(dir, "secret.json"); + fs.writeFileSync(secretPath, JSON.stringify({ secret: "SECRET-LOCAL" })); + secretUrl = pathToFileURL(secretPath).href; + }); + + afterAll(() => { + fs.rmSync(dir, { recursive: true, force: true }); + }); + + // Serves https://example.com/* from memory, so no network is used. + function remote(files: Record) { + return { + order: 1, + canRead: /^https:\/\/example\.com\//, + read: (file: { url: string }) => JSON.stringify(files[file.url]), + }; + } + + it("rejects an absolute file:// $ref in a schema whose path is an https URL", async () => { + const schema = { components: { schemas: { leak: { $ref: secretUrl } } } }; + try { + await new $RefParser().dereference("https://example.com/openapi.json", schema, {}); + helper.shouldNotGetCalled(); + } catch (err: any) { + expect(err).to.be.an.instanceOf(ResolverError); + expect(err.message).to.contain("from remote schema"); + expect(JSON.stringify(schema)).not.to.contain("SECRET-LOCAL"); + } + }); + + it("rejects a file:// $ref in a schema downloaded over https", async () => { + const options = { + resolve: { + remote: remote({ + "https://example.com/openapi.json": { leak: { $ref: secretUrl } }, + }), + }, + }; + await expect(new $RefParser().dereference("https://example.com/openapi.json", options)).rejects.toThrow( + "from remote schema", + ); + }); + + it("rejects a relative $ref resolved against a file:// $id in a remote schema", async () => { + const options = { + resolve: { + remote: remote({ + "https://example.com/openapi.json": { + $schema: "https://json-schema.org/draft/2020-12/schema", + $id: pathToFileURL(nodePath.join(dir, "root.json")).href, + properties: { leak: { $ref: "secret.json" } }, + }, + }), + }, + }; + await expect(new $RefParser().dereference("https://example.com/openapi.json", options)).rejects.toThrow( + "from remote schema", + ); + }); + + it("rejects it when following a remote $ref from a remote schema", async () => { + const options = { + resolve: { + remote: remote({ + "https://example.com/openapi.json": { a: { $ref: "https://example.com/b.json" } }, + "https://example.com/b.json": { leak: { $ref: secretUrl } }, + }), + }, + }; + await expect(new $RefParser().dereference("https://example.com/openapi.json", options)).rejects.toThrow( + "from remote schema", + ); + }); + + it("rejects it with resolveExcludedPathMatcher too", async () => { + const schema = { leak: { $ref: secretUrl } }; + await expect( + new $RefParser().dereference("https://example.com/openapi.json", schema, { + resolveExcludedPathMatcher: () => false, + }), + ).rejects.toThrow("from remote schema"); + }); + + it("reports it as a ResolverError with continueOnError", async () => { + const schema = { components: { schemas: { leak: { $ref: secretUrl } } } }; + try { + await new $RefParser().dereference("https://example.com/openapi.json", schema, { continueOnError: true }); + helper.shouldNotGetCalled(); + } catch (err: any) { + expect(err.errors).to.containSubset([ + { + name: ResolverError.name, + path: ["components", "schemas", "leak"], + message: (message: string) => message.includes("from remote schema"), + }, + ]); + } + }); + + it("still resolves local files from a local schema", async () => { + const rootPath = nodePath.join(dir, "root.json"); + fs.writeFileSync(rootPath, JSON.stringify({ data: { $ref: "secret.json" } })); + const schema = await new $RefParser().dereference(rootPath); + expect(schema).to.deep.equal({ data: { secret: "SECRET-LOCAL" } }); + }); +}); From 9a89cf407ee951dedf5b1e2d5153f5082fbbe3bc Mon Sep 17 00:00:00 2001 From: Mradul Singh Date: Thu, 12 Nov 2026 23:07:37 +0530 Subject: [PATCH 2/2] test: cover file:// $id aliases in remote schemas --- .../remote-local-file.spec.ts | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/test/specs/remote-local-file/remote-local-file.spec.ts b/test/specs/remote-local-file/remote-local-file.spec.ts index f34eacdf..baf65fbf 100644 --- a/test/specs/remote-local-file/remote-local-file.spec.ts +++ b/test/specs/remote-local-file/remote-local-file.spec.ts @@ -76,6 +76,47 @@ describe.skipIf(isBrowser)("Local files referenced from a remote schema", () => ); }); + it("rejects a relative $ref under a file:// $id with resolveExcludedPathMatcher", async () => { + const options = { + resolveExcludedPathMatcher: () => false, + resolve: { + remote: remote({ + "https://example.com/openapi.json": { + $schema: "https://json-schema.org/draft/2020-12/schema", + $id: pathToFileURL(nodePath.join(dir, "root.json")).href, + properties: { leak: { $ref: "secret.json" } }, + }, + }), + }, + }; + await expect(new $RefParser().dereference("https://example.com/openapi.json", options)).rejects.toThrow( + "from remote schema", + ); + }); + + it("rejects a $ref through a remote schema's file:// $id alias", async () => { + const idUrl = pathToFileURL(nodePath.join(dir, "alias.json")).href; + for (const extra of [{}, { resolveExcludedPathMatcher: () => false }]) { + const options = { + ...extra, + resolve: { + remote: remote({ + "https://example.com/openapi.json": { + $schema: "https://json-schema.org/draft/2020-12/schema", + $defs: { + inner: { $id: idUrl, properties: { leak: { $ref: "secret.json" } } }, + }, + properties: { a: { $ref: idUrl } }, + }, + }), + }, + }; + await expect(new $RefParser().dereference("https://example.com/openapi.json", options)).rejects.toThrow( + "from remote schema", + ); + } + }); + it("rejects it when following a remote $ref from a remote schema", async () => { const options = { resolve: {