Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/options.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
9 changes: 9 additions & 0 deletions lib/parse.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

/**
Expand All @@ -29,6 +31,7 @@ async function parse<S extends object = JSONSchema, O extends ParserOptions<S> =
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("#");
Expand Down Expand Up @@ -60,6 +63,12 @@ async function parse<S extends object = JSONSchema, O extends ParserOptions<S> =

// 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<S, O>(file, options, $refs);
$ref.pathType = resolver.plugin.name;
file.data = resolver.result;
Expand Down
3 changes: 2 additions & 1 deletion lib/resolve-external.ts
Original file line number Diff line number Diff line change
Expand Up @@ -176,9 +176,10 @@ async function resolve$Ref<S extends object = JSONSchema, O extends ParserOption
// Parse the $referenced file/url
try {
const reference = ($ref as JSONSchema).$ref;
const parseTarget: { url: string; baseUrl: string; reference?: string } = {
const parseTarget: { url: string; baseUrl: string; reference?: string; referrer: string } = {
url: resolvedPath,
baseUrl: resolutionBase,
referrer: url.stripHash(path),
};
if (typeof reference === "string") {
parseTarget.reference = reference;
Expand Down
1 change: 1 addition & 0 deletions lib/resolve-external/with-matcher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,7 @@ async function loadExternalDocument<S extends object, O extends ParserOptions<S>
url: resolvedPath,
baseUrl: resolutionBase,
reference: reference.$ref,
referrer: url.stripHash(path),
},
context.$refs,
context.options,
Expand Down
165 changes: 165 additions & 0 deletions test/specs/remote-local-file/remote-local-file.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
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<string, unknown>) {
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 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: {
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" } });
});
});