openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/adapters/redocly-loader/ref-access.ts

@@ -0,0 +1,146 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  BaseResolver,
+  type Document,
+  type Config as RedoclyConfig,
+  type Source,
+  YamlParseError,
+} from "@redocly/openapi-core";
+import type { RefAccess } from "../../application/ports/schema-loader.js";
+import { ERROR_CODES, type OpenAPITypesafeError } from "../../domain/errors.js";
+import { aliasExpansionFailure } from "./alias-limit.js";
+import { isHostAllowed } from "./allowed-hosts.js";
+import { refForbiddenError } from "./schema-load-errors.js";
+
+/**
+ * Limits on where `$ref` documents may be loaded from (threat model R1 and R2, ADR-017). The root
+ * document is chosen by the developer and is always loaded; every other document must pass.
+ */
+
+type ResolveConfig = RedoclyConfig["resolve"];
+
+/** Redocly treats only these prefixes as remote; any other `$ref` is a local file path. */
+function isRemoteRef(absoluteRef: string): boolean {
+  return absoluteRef.startsWith("http://") || absoluteRef.startsWith("https://");
+}
+
+/** Whether `target` is `root` or below it; both are absolute paths. */
+export function isInsideDirectory(target: string, root: string): boolean {
+  const relative = path.relative(root, target);
+  // Compare the first segment: a directory named `..hidden` is inside, `../x` is not.
+  const isParent = relative === ".." || relative.startsWith(`..${path.sep}`);
+  return !isParent && !path.isAbsolute(relative);
+}
+
+/** The real path, so a link inside the root that points outside it is caught. */
+async function realPathOrSelf(file: string): Promise<string> {
+  const absolute = path.resolve(file);
+  try {
+    return await realpath(absolute);
+  } catch (error) {
+    // A missing file is never read, and Redocly reports it. Resolve its nearest existing
+    // directory instead, so it compares with the root's real path: the root may be reached
+    // through a link (macOS `/tmp` is one), and the missing file must not look outside it.
+    const parent = path.dirname(absolute);
+    if ((error as NodeJS.ErrnoException).code === "ENOENT" && parent !== absolute) {
+      return path.join(await realPathOrSelf(parent), path.basename(absolute));
+    }
+    throw error;
+  }
+}
+
+async function localRefusal(
+  absoluteRef: string,
+  localRoot: URL,
+): Promise<OpenAPITypesafeError | undefined> {
+  const root = await realPathOrSelf(fileURLToPath(localRoot));
+  if (isInsideDirectory(await realPathOrSelf(absoluteRef), root)) {
+    return undefined;
+  }
+  return refForbiddenError(absoluteRef, { reason: "outside-local-root", localRoot: root });
+}
+
+/** The refusal for one document, or undefined when the limits allow it. */
+export async function refusalOf(
+  absoluteRef: string,
+  access: RefAccess,
+): Promise<OpenAPITypesafeError | undefined> {
+  if (!isRemoteRef(absoluteRef)) {
+    return access.localRoot === undefined ? undefined : localRefusal(absoluteRef, access.localRoot);
+  }
+  if (access.remoteHosts === undefined || isHostAllowed(new URL(absoluteRef), access.remoteHosts)) {
+    return undefined;
+  }
+  return refForbiddenError(absoluteRef, {
+    reason: "host-not-allowed",
+    allowedHosts: [...access.remoteHosts],
+  });
+}
+
+/**
+ * A Redocly resolver that checks each document before it loads it. Redocly turns a failed load
+ * into an unresolved-`$ref` problem, so the refusals are also kept for the loader to report as
+ * the typed error.
+ */
+export class RefAccessResolver extends BaseResolver {
+  readonly #access: RefAccess;
+  readonly #refusals: OpenAPITypesafeError[] = [];
+  /** The root document's ref: it is chosen by the developer, so it is not limited. */
+  #rootRef: string | undefined;
+
+  constructor(config: ResolveConfig, access: RefAccess) {
+    super(config);
+    this.#access = access;
+  }
+
+  /** The first document that was refused, if any. */
+  get firstRefusal(): OpenAPITypesafeError | undefined {
+    return this.#refusals[0];
+  }
+
+  override resolveDocument(
+    base: string | null,
+    ref: string,
+    isRoot = false,
+  ): ReturnType<BaseResolver["resolveDocument"]> {
+    if (isRoot) {
+      this.#rootRef = this.resolveExternalRef(base, ref);
+    }
+    return super.resolveDocument(base, ref, isRoot);
+  }
+
+  /** Refuse a YAML alias bomb before Redocly walks it (pre-beta test plan 10.2). */
+  override parseDocument(source: Source, isRoot = false): Document {
+    const document = super.parseDocument(source, isRoot);
+    const failure = aliasExpansionFailure(document.parsed);
+    if (failure !== undefined) {
+      throw new YamlParseError(failure, source);
+    }
+    return document;
+  }
+
+  override async loadExternalRef(absoluteRef: string): Promise<Source> {
+    const refusal =
+      absoluteRef === this.#rootRef ? undefined : await refusalOf(absoluteRef, this.#access);
+    if (refusal !== undefined) {
+      this.#refusals.push(refusal);
+      throw refusal;
+    }
+    try {
+      return await super.loadExternalRef(absoluteRef);
+    } catch (error) {
+      // A refused redirect throws inside the fetch, and Redocly wraps it in a ResolveError.
+      const cause = (error as { originalError?: unknown }).originalError;
+      if (isRefusal(cause)) {
+        this.#refusals.push(cause);
+      }
+      throw error;
+    }
+  }
+}
+
+function isRefusal(value: unknown): value is OpenAPITypesafeError {
+  return (value as { code?: unknown } | null)?.code === ERROR_CODES.SCHEMA_REF_FORBIDDEN;
+}

package/src/adapters/redocly-loader/ref-holders.ts

@@ -0,0 +1,43 @@
+import { escapePointerSegment } from "../../domain/openapi/json-pointer.js";
+
+/** An object with a string `$ref`, and its JSON Pointer in the document. */
+export interface RefHolder {
+  readonly node: { $ref: string };
+  readonly pointer: string;
+}
+
+interface PendingNode {
+  readonly value: object;
+  readonly pointer: string;
+}
+
+function hasStringRef(value: object): value is { $ref: string } {
+  return !Array.isArray(value) && typeof (value as { $ref?: unknown }).$ref === "string";
+}
+
+/**
+ * Every object with a string `$ref` in a parsed document, in no particular order. The walk uses
+ * its own stack, so a deeply nested document does not run out of call stack, and a node shared by
+ * YAML aliases (or a cycle of them) is visited once.
+ */
+export function findRefHolders(document: unknown): RefHolder[] {
+  const found: RefHolder[] = [];
+  const visited = new WeakSet<object>();
+  const pending: PendingNode[] = [];
+  const enqueue = (value: unknown, pointer: string): void => {
+    if (typeof value === "object" && value !== null && !visited.has(value)) {
+      visited.add(value);
+      pending.push({ value, pointer });
+    }
+  };
+  enqueue(document, "#");
+  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+    if (hasStringRef(next.value)) {
+      found.push({ node: next.value, pointer: next.pointer });
+    }
+    for (const [key, child] of Object.entries(next.value)) {
+      enqueue(child, `${next.pointer}/${escapePointerSegment(key)}`);
+    }
+  }
+  return found;
+}

package/src/adapters/redocly-loader/remote-fetch.ts

@@ -0,0 +1,104 @@
+import type { Config as RedoclyConfig } from "@redocly/openapi-core";
+import type { RefAccess } from "../../application/ports/schema-loader.js";
+import { isHostAllowed } from "./allowed-hosts.js";
+import { refForbiddenError } from "./schema-load-errors.js";
+
+/** How the loader fetches remote documents: a time limit, and the host limit on redirects. */
+
+type ResolveConfig = RedoclyConfig["resolve"];
+
+/** The fetch Redocly calls for a remote document (`resolve.http.customFetch`). */
+export type RemoteFetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+/**
+ * Redirects followed for a remote `$ref` when hosts are limited. Each hop is checked, so fetch
+ * cannot follow them on its own; 5 covers http → https plus a moved file, and a loop stops early.
+ */
+export const MAX_CHECKED_REDIRECTS = 5;
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+/** Statuses whose responses have no body; `new Response()` refuses a body for them. */
+const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
+
+/** A response whose body is already read, so that reading it again cannot wait or fail. */
+async function bufferedResponse(response: Response): Promise<Response> {
+  const body = await response.arrayBuffer();
+  const { status, statusText, headers } = response;
+  return new Response(NULL_BODY_STATUSES.has(status) ? null : body, {
+    status,
+    statusText,
+    headers,
+  });
+}
+
+/**
+ * Fetch with a time limit for the whole response, body included: Node's own fetch waits five
+ * minutes for a server that never answers, and a server that sends its body one byte at a time
+ * never finishes. The body is read here, inside the limit; when Redocly read it, the abort
+ * surfaced as a `DOMException` whose read-only `message` Redocly tried to change, which gave
+ * "Cannot set property message of  which has only a getter" instead of the time limit.
+ */
+function fetchWithTimeout(timeoutMs: number): RemoteFetch {
+  return async (input, init = {}) => {
+    try {
+      const response = await fetch(input, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+      return await bufferedResponse(response);
+    } catch (cause) {
+      const isTimeout = cause instanceof Error && cause.name === "TimeoutError";
+      throw isTimeout ? new Error(`Timed out after ${timeoutMs} ms loading ${input}`) : cause;
+    }
+  };
+}
+
+/**
+ * Follow redirects one by one, and refuse a redirect to a host that is not listed. The first URL
+ * was checked by the resolver (or is the root document). As fetch does, the configured headers
+ * (often credentials) are not sent on to another origin.
+ */
+export function fetchWithCheckedRedirects(
+  fetchImpl: RemoteFetch,
+  hosts: readonly string[],
+): RemoteFetch {
+  return async (input, init = {}) => {
+    const firstOrigin = new URL(input).origin;
+    let url = new URL(input);
+    for (let hop = 0; hop <= MAX_CHECKED_REDIRECTS; hop += 1) {
+      if (hop > 0 && !isHostAllowed(url, hosts)) {
+        throw refForbiddenError(url.href, { reason: "host-not-allowed", allowedHosts: [...hosts] });
+      }
+      const { headers, ...rest } = init;
+      const hopInit: RequestInit =
+        url.origin === firstOrigin && headers !== undefined ? { ...rest, headers } : rest;
+      const response = await fetchImpl(url.href, { ...hopInit, redirect: "manual" });
+      const location = response.headers.get("location");
+      if (!REDIRECT_STATUSES.has(response.status) || location === null) {
+        return response;
+      }
+      url = new URL(location, url);
+    }
+    throw new Error(`More than ${MAX_CHECKED_REDIRECTS} redirects loading ${input}`);
+  };
+}
+
+export interface RemoteFetchOptions {
+  /** Time limit of one fetch and its body, unless the Redocly config has its own `customFetch`. */
+  readonly timeoutMs: number;
+  readonly access: RefAccess;
+}
+
+/**
+ * The resolve config with the fetch the loader uses. A `customFetch` of the Redocly config is
+ * kept; with a host limit, it is wrapped so that each redirect is checked.
+ */
+export function resolveConfigWithAccess(
+  resolve: ResolveConfig,
+  options: RemoteFetchOptions,
+): ResolveConfig {
+  // Redocly types `customFetch` as `Function`; it is called as fetch is.
+  const configured = resolve.http.customFetch as RemoteFetch | undefined;
+  const base = configured ?? fetchWithTimeout(options.timeoutMs);
+  const hosts = options.access.remoteHosts;
+  const customFetch = hosts === undefined ? base : fetchWithCheckedRedirects(base, hosts);
+  return { ...resolve, http: { ...resolve.http, customFetch } };
+}

package/src/adapters/redocly-loader/schema-load-errors.ts

@@ -0,0 +1,124 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+
+/**
+ * The typed errors of loading, validating and bundling a document (ADR-011). Messages are the
+ * original messages, so Node API users who match on them keep working.
+ */
+
+/** No source was given, or the source is empty. */
+export function sourceEmptyError(message: string): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({ code: ERROR_CODES.SCHEMA_SOURCE_EMPTY, message });
+}
+
+/** The source is neither a URL, text, buffer, stream nor plain object. */
+export function sourceInvalidError(source: unknown): OpenAPITypesafeError {
+  const received = Array.isArray(source) ? "Array" : typeof source;
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_SOURCE_INVALID,
+    message: `Expected string, object, or Buffer. Got ${received}`,
+    details: { received },
+  });
+}
+
+function causeMessage(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+/** Enough of a source string to recognise it in the message. */
+const SOURCE_TEXT_IN_MESSAGE = 200;
+
+/**
+ * A string source is document text, so a file path parses as a YAML string scalar, not as a
+ * document (docs/node.md). The message says how to load the file instead.
+ */
+export function pathStringError(text: string): OpenAPITypesafeError {
+  const shown =
+    text.length > SOURCE_TEXT_IN_MESSAGE ? `${text.slice(0, SOURCE_TEXT_IN_MESSAGE)}…` : text;
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_SOURCE_INVALID,
+    message:
+      `The string "${shown}" was parsed as YAML text, not loaded as a file. ` +
+      "To load a file, pass a URL: openapiTS(pathToFileURL(path)) from node:url.",
+    details: { reason: "path", received: "string" },
+  });
+}
+
+/** Reading the document from a file or URL failed; the message is the reader's message. */
+export function loadFailedError(absoluteRef: string, cause: unknown): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_LOAD_FAILED,
+    message: causeMessage(cause),
+    details: { source: absoluteRef },
+    cause,
+  });
+}
+
+/** The document text is not valid JSON or YAML; the message is the parser's message. */
+export function parseFailedError(
+  format: "json" | "yaml",
+  absoluteRef: string,
+  cause: unknown,
+): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_PARSE_FAILED,
+    message: causeMessage(cause),
+    details: { format, source: absoluteRef },
+    cause,
+  });
+}
+
+/** The document is not OpenAPI 3.x. */
+export function versionUnsupportedError(
+  message: string,
+  parsed: Readonly<Record<string, unknown>>,
+): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_VERSION_UNSUPPORTED,
+    message,
+    details: { openapi: parsed.openapi, swagger: parsed.swagger },
+  });
+}
+
+/**
+ * Linting or bundling found errors. The message is the last error, as in the original; all error
+ * messages are in `details.problems`.
+ */
+export function schemaInvalidError(problems: readonly string[]): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_INVALID,
+    message: problems.at(-1) ?? "",
+    details: { problems: [...problems] },
+  });
+}
+
+/** A `$ref` chain points back to itself with no schema in between (`A: $ref B`, `B: $ref A`). */
+export function refCycleError(cause: Error): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_REF_INVALID,
+    message: cause.message,
+    details: { reason: "cycle" },
+    cause,
+  });
+}
+
+function hostListText(hosts: readonly string[]): string {
+  return hosts.length === 0 ? "none" : hosts.join(", ");
+}
+
+/** Why a `$ref` document was refused, with the limit it broke (ADR-017). */
+export type RefRefusalDetails =
+  | { readonly reason: "outside-local-root"; readonly localRoot: string }
+  | { readonly reason: "host-not-allowed"; readonly allowedHosts: readonly string[] };
+
+/** A `$ref` is outside the local root, or its host is not allowed (threat model R1, R2). */
+export function refForbiddenError(ref: string, details: RefRefusalDetails): OpenAPITypesafeError {
+  const limit =
+    details.reason === "outside-local-root"
+      ? `it is outside the local $ref root ${details.localRoot}`
+      : `its host is not in the allowed remote $ref hosts (${hostListText(details.allowedHosts)})`;
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_REF_FORBIDDEN,
+    message: `Refused to load ${ref}: ${limit}`,
+    details: { ref, ...details },
+  });
+}

package/src/adapters/redocly-loader/schema-source.ts

@@ -0,0 +1,151 @@
+import { Readable } from "node:stream";
+import { text } from "node:stream/consumers";
+import { fileURLToPath } from "node:url";
+import {
+  type BaseResolver,
+  type Document,
+  makeDocumentFromString,
+  ResolveError,
+  Source,
+  YamlParseError,
+} from "@redocly/openapi-core";
+import parseJson from "parse-json";
+import { aliasExpansionFailure } from "./alias-limit.js";
+import {
+  loadFailedError,
+  parseFailedError,
+  pathStringError,
+  sourceEmptyError,
+  sourceInvalidError,
+} from "./schema-load-errors.js";
+
+/** Parse a schema source of any supported type into a Redocly document (ENGINEERING_PLAN 4.5). */
+
+export interface ParseSchemaOptions {
+  absoluteRef: string;
+  resolver: BaseResolver;
+}
+
+/**
+ * Read a stream to the end as UTF-8 text, trimmed. A stream that fails rejects with
+ * SCHEMA_LOAD_FAILED; listening only for `data` and `end` left the promise pending forever.
+ */
+async function readStream(stream: Readable, absoluteRef: string): Promise<string> {
+  try {
+    return (await text(stream)).trim();
+  } catch (error) {
+    throw loadFailedError(absoluteRef, error);
+  }
+}
+
+const URL_PREFIXES = ["http://", "https://", "file://"] as const;
+
+/** A string is a URL, JSON (starts with `{`) or YAML. */
+function parseSchemaText(
+  schema: string,
+  options: ParseSchemaOptions,
+): Promise<Document> | Document {
+  if (URL_PREFIXES.some((prefix) => schema.startsWith(prefix))) {
+    const url = new URL(schema);
+    const absoluteRef = url.protocol === "file:" ? fileURLToPath(url) : url.href;
+    return parseSchema(url, { absoluteRef, resolver: options.resolver });
+  }
+  return schema[0] === "{"
+    ? parseJsonText(schema, options.absoluteRef)
+    : parseYamlText(schema, options.absoluteRef);
+}
+
+function parseJsonText(text: string, absoluteRef: string): Document {
+  try {
+    return { source: new Source(absoluteRef, text, "application/json"), parsed: parseJson(text) };
+  } catch (cause) {
+    throw parseFailedError("json", absoluteRef, cause);
+  }
+}
+
+function parseYamlText(text: string, absoluteRef: string): Document {
+  let document: Document;
+  try {
+    document = makeDocumentFromString(text, absoluteRef);
+  } catch (cause) {
+    throw parseFailedError("yaml", absoluteRef, cause);
+  }
+  // Text that is only a YAML string scalar, such as "./openapi.yaml", was meant as a file path.
+  if (typeof document.parsed === "string") {
+    throw pathStringError(text);
+  }
+  const failure = aliasExpansionFailure(document.parsed);
+  if (failure !== undefined) {
+    throw parseFailedError("yaml", absoluteRef, failure);
+  }
+  return document;
+}
+
+/** The resolver throws for some failures (a missing file) and returns an error for others. */
+async function resolveSchemaURL(options: ParseSchemaOptions): Promise<Document> {
+  const result = await options.resolver
+    .resolveDocument(null, options.absoluteRef, true)
+    .catch((cause: unknown) => {
+      throw cause instanceof YamlParseError
+        ? fileParseFailedError(options.absoluteRef, cause)
+        : loadFailedError(options.absoluteRef, readerError(cause));
+    });
+  if ("parsed" in result) {
+    return result;
+  }
+  throw loadFailedError(options.absoluteRef, readerError(result));
+}
+
+/**
+ * Redocly wraps a failed read in `ResolveError`, which keeps the reader's error in
+ * `originalError`, not in `cause`. Unwrapped, the cause keeps the network reason (refused, DNS).
+ */
+function readerError(error: unknown): unknown {
+  let current = error;
+  while (current instanceof ResolveError) {
+    current = current.originalError;
+  }
+  return current;
+}
+
+/**
+ * The resolver parses JSON files with its YAML parser too, so the format comes from the file
+ * name. Some parser messages (a second YAML document) do not name the file; the error adds it.
+ */
+function fileParseFailedError(absoluteRef: string, error: YamlParseError): Error {
+  const format = absoluteRef.toLowerCase().endsWith(".json") ? "json" : "yaml";
+  const cause = error.message.includes(absoluteRef)
+    ? error
+    : new Error(`${error.message} in "${absoluteRef}"`, { cause: error });
+  return parseFailedError(format, absoluteRef, cause);
+}
+
+function parseSchemaObject(schema: unknown, absoluteRef: string): Document {
+  if (typeof schema === "object" && !Array.isArray(schema)) {
+    return {
+      source: new Source(absoluteRef, JSON.stringify(schema), "application/json"),
+      parsed: schema,
+    };
+  }
+  throw sourceInvalidError(schema);
+}
+
+/** Parse any supported source: URL, stream, buffer, URL or document text, or a plain object. */
+export async function parseSchema(schema: unknown, options: ParseSchemaOptions): Promise<Document> {
+  if (!schema) {
+    throw sourceEmptyError("Can’t parse empty schema");
+  }
+  if (schema instanceof URL) {
+    return resolveSchemaURL(options);
+  }
+  if (schema instanceof Readable) {
+    return parseSchema(await readStream(schema, options.absoluteRef), options);
+  }
+  if (schema instanceof Buffer) {
+    return parseSchema(schema.toString("utf8"), options);
+  }
+  if (typeof schema === "string") {
+    return parseSchemaText(schema, options);
+  }
+  return parseSchemaObject(schema, options.absoluteRef);
+}

package/src/adapters/redocly-loader/unsupported-keys.ts

@@ -0,0 +1,102 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+
+/**
+ * Keys Redocly 1.34 cannot walk. It looks up the type of every key with `type.properties[key]`,
+ * which also finds inherited `Object.prototype` members; it then calls a found function with no
+ * `this`, and these methods throw a `TypeError` for that. Redocly 2.x looks up own keys only
+ * (ADR-005 keeps 1.34). `toString` and `constructor` do not throw, and load as they should.
+ *
+ * Redocly does not walk every value (`default` and `const` are data), so a document with such a
+ * key is not rejected up front: the loader looks for them only after Redocly threw a `TypeError`.
+ */
+export const UNSUPPORTED_KEYS: ReadonlySet<string> = new Set([
+  "hasOwnProperty",
+  "isPrototypeOf",
+  "propertyIsEnumerable",
+  "toLocaleString",
+  "valueOf",
+  "__defineGetter__",
+  "__defineSetter__",
+  "__lookupGetter__",
+  "__lookupSetter__",
+]);
+
+/** Enough found keys in the message to act on; `details.keys` has all of them. */
+const KEYS_IN_MESSAGE = 5;
+
+/** A parsed document and where it was loaded from. */
+export interface LoadedDocument {
+  readonly source: string;
+  readonly parsed: unknown;
+}
+
+/** An unsupported key: its JSON pointer and the document that has it. */
+export interface UnsupportedKey {
+  readonly key: string;
+  readonly pointer: string;
+  readonly source: string;
+}
+
+interface PendingNode {
+  readonly value: object;
+  readonly pointer: string;
+}
+
+/** RFC 6901: `~` becomes `~0` and `/` becomes `~1`. */
+function escapePointerSegment(segment: string): string {
+  return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+/**
+ * The unsupported keys of one parsed document. The walk uses its own stack, so a deeply nested
+ * document is checked without running out of call stack; nodes shared by YAML aliases are checked
+ * once.
+ */
+function unsupportedKeysOf(document: LoadedDocument): UnsupportedKey[] {
+  const found: UnsupportedKey[] = [];
+  const visited = new WeakSet<object>();
+  const pending: PendingNode[] = [];
+  const enqueue = (value: unknown, pointer: string): void => {
+    if (typeof value === "object" && value !== null && !visited.has(value)) {
+      visited.add(value);
+      pending.push({ value, pointer });
+    }
+  };
+  enqueue(document.parsed, "#");
+  for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
+    for (const [key, child] of Object.entries(node.value)) {
+      const pointer = `${node.pointer}/${escapePointerSegment(key)}`;
+      if (UNSUPPORTED_KEYS.has(key)) {
+        found.push({ key, pointer, source: document.source });
+      }
+      enqueue(child, pointer);
+    }
+  }
+  return found;
+}
+
+/** Every unsupported key of the given documents. */
+export function findUnsupportedKeys(documents: readonly LoadedDocument[]): UnsupportedKey[] {
+  return documents.flatMap(unsupportedKeysOf);
+}
+
+function describeKey(found: UnsupportedKey): string {
+  return `"${found.key}" at ${found.pointer} in ${found.source}`;
+}
+
+/** The typed error for the keys the schema loader failed on; `cause` is Redocly's `TypeError`. */
+export function unsupportedKeysError(
+  keys: readonly UnsupportedKey[],
+  cause: unknown,
+): OpenAPITypesafeError {
+  const listed = keys.slice(0, KEYS_IN_MESSAGE).map(describeKey);
+  const more = keys.length > KEYS_IN_MESSAGE ? ` and ${keys.length - KEYS_IN_MESSAGE} more` : "";
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_KEY_UNSUPPORTED,
+    message:
+      "The schema loader (Redocly 1.x) failed on a key named like a built-in object method. " +
+      `Rename it: ${listed.join(", ")}${more}.`,
+    details: { keys: keys.map((found) => ({ ...found })) },
+    cause,
+  });
+}