openapi-typesafe 0.0.0 → 1.0.0-rc.1

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

@@ -0,0 +1,262 @@
+import { fileURLToPath } from "node:url";
+import {
+  type BaseResolver,
+  bundle,
+  type Document,
+  lintDocument,
+  type NormalizedProblem,
+  type Config as RedoclyConfig,
+} from "@redocly/openapi-core";
+import type { Logger } from "../../application/ports/logger.js";
+import type { SchemaLoader, SchemaLoadRequest } from "../../application/ports/schema-loader.js";
+import { withStackOverflowReportedAsync } from "../../application/stack-overflow.js";
+import type { OpenAPI3 } from "../../types.js";
+import { repairBundledRefs } from "./bundled-ref-repair.js";
+import { findMalformedRefs, malformedRefsError } from "./malformed-refs.js";
+import { RefAccessResolver } from "./ref-access.js";
+import { resolveConfigWithAccess } from "./remote-fetch.js";
+import {
+  loadFailedError,
+  refCycleError,
+  schemaInvalidError,
+  versionUnsupportedError,
+} from "./schema-load-errors.js";
+import { parseSchema } from "./schema-source.js";
+import {
+  findUnsupportedKeys,
+  type LoadedDocument,
+  unsupportedKeysError,
+} from "./unsupported-keys.js";
+
+/**
+ * The SchemaLoader port on Redocly 1.34 (ADR-005): parse any inherited source type, then lint and
+ * bundle with the given Redocly config. Problems go to the logger; errors fail the load.
+ */
+export interface RedoclySchemaLoaderOptions {
+  readonly redoc: RedoclyConfig;
+  readonly logger: Logger;
+  /** A monotonic time in milliseconds, for the debug durations. */
+  readonly now: () => number;
+  /** Time limit of one remote fetch, unless the Redocly config brings its own `customFetch`. */
+  readonly remoteRefTimeoutMs: number;
+}
+
+const UNSUPPORTED_FORMAT_MESSAGE = "Unsupported schema format, expected `openapi: 3.x`";
+
+/**
+ * Accept OpenAPI 3.x only; Swagger 2 and other formats get their own message. An empty file or a
+ * `null` root parses to nothing, so it is checked before any field is read.
+ */
+function assertOpenAPI3(document: unknown): void {
+  if (typeof document !== "object" || document === null) {
+    throw versionUnsupportedError(UNSUPPORTED_FORMAT_MESSAGE, {});
+  }
+  const parsed = document as Record<string, unknown>;
+  const openapiVersion = Number.parseFloat(parsed.openapi as string);
+  const isOpenAPI3 =
+    !parsed.swagger &&
+    Boolean(parsed.openapi) &&
+    !Number.isNaN(openapiVersion) &&
+    openapiVersion >= 3 &&
+    openapiVersion < 4;
+  if (isOpenAPI3) {
+    return;
+  }
+  if (parsed.swagger) {
+    throw versionUnsupportedError(
+      "Unsupported Swagger version: 2.x. Use OpenAPI 3.x instead.",
+      parsed,
+    );
+  }
+  if (parsed.openapi || openapiVersion < 3 || openapiVersion >= 4) {
+    throw versionUnsupportedError(`Unsupported OpenAPI version: ${parsed.openapi}`, parsed);
+  }
+  throw versionUnsupportedError(UNSUPPORTED_FORMAT_MESSAGE, parsed);
+}
+
+/**
+ * The name an inline source (a string, object, buffer or stream) gets inside the working
+ * directory. Redocly resolves relative `$ref`s against the directory of the document, so the
+ * document must be named as a file in the working directory, not as the directory itself.
+ */
+const INLINE_SOURCE_NAME = "inline-source";
+
+/** The base for relative `$ref`s: the source file or URL itself, else a file in the cwd. */
+function sourceAbsoluteRef(source: unknown, cwd: URL): string {
+  const document = source instanceof URL ? source : new URL(INLINE_SOURCE_NAME, cwd);
+  return document.protocol === "file:" ? sourceFilePath(document) : document.href;
+}
+
+/**
+ * The path of a `file:` source. A URL that names no path on this platform (an encoded slash, a
+ * host on POSIX, no drive letter on Windows) cannot be read, so it fails as a read would.
+ */
+function sourceFilePath(source: URL): string {
+  try {
+    return fileURLToPath(source);
+  } catch (error) {
+    // Node.js reports these as TypeErrors (ERR_INVALID_FILE_URL_PATH, ERR_INVALID_FILE_URL_HOST).
+    if (!(error instanceof TypeError)) {
+      throw error;
+    }
+    throw loadFailedError(source.href, error);
+  }
+}
+
+/** Redocly throws a plain Error for a `$ref` chain that points back to itself. */
+const REF_CYCLE_MESSAGE = "Self-referencing circular pointer";
+
+/**
+ * The root document and every other document the resolver loaded, as far as they parsed. A root
+ * read from a file or URL is in the resolver cache too, and is listed once.
+ */
+async function loadedDocuments(root: Document, resolver: BaseResolver): Promise<LoadedDocument[]> {
+  const cached = await Promise.all(resolver.cache.values());
+  const bySource = new Map<string, unknown>([[root.source.absoluteRef, root.parsed]]);
+  for (const document of cached) {
+    if ("parsed" in document && !bySource.has(document.source.absoluteRef)) {
+      bySource.set(document.source.absoluteRef, document.parsed);
+    }
+  }
+  return [...bySource].map(([source, parsed]) => ({ source, parsed }));
+}
+
+/** Report the document problems Redocly throws as typed errors; anything else passes through. */
+async function rethrowDocumentError(
+  error: unknown,
+  root: Document,
+  resolver: BaseResolver,
+): Promise<never> {
+  if (error instanceof Error && error.message === REF_CYCLE_MESSAGE) {
+    throw refCycleError(error);
+  }
+  if (error instanceof URIError) {
+    throw malformedRefsError(findMalformedRefs(await loadedDocuments(root, resolver)), error);
+  }
+  if (error instanceof TypeError) {
+    const keys = findUnsupportedKeys(await loadedDocuments(root, resolver));
+    throw keys.length === 0 ? error : unsupportedKeysError(keys, error);
+  }
+  throw error;
+}
+
+class RedoclySchemaLoader implements SchemaLoader {
+  readonly #options: RedoclySchemaLoaderOptions;
+
+  constructor(options: RedoclySchemaLoaderOptions) {
+    this.#options = options;
+  }
+
+  async load(request: SchemaLoadRequest): Promise<OpenAPI3> {
+    const resolver = this.#resolver(request);
+    // Parsing is guarded too: `JSON.stringify` of a deep object source overflows the stack on
+    // Node.js 22 and 24, before linting starts.
+    const bundled = await withStackOverflowReportedAsync("load", () =>
+      this.#parseAndBundle(request, resolver),
+    ).catch((error: unknown) => {
+      throw resolver.firstRefusal ?? error;
+    });
+    // A refused `$ref` is an unresolved-`$ref` problem, which a Redocly config can turn off.
+    if (resolver.firstRefusal !== undefined) {
+      throw resolver.firstRefusal;
+    }
+    return bundled;
+  }
+
+  async #parseAndBundle(request: SchemaLoadRequest, resolver: BaseResolver): Promise<OpenAPI3> {
+    const { logger, now } = this.#options;
+    const configLoadedAt = now();
+    logger.debug("Loaded Redoc config", "redoc", now() - configLoadedAt);
+    const parseStartedAt = now();
+    const absoluteRef = sourceAbsoluteRef(request.source, request.cwd);
+    const document = await parseSchema(request.source, { absoluteRef, resolver });
+    logger.debug("Parsed schema", "redoc", now() - parseStartedAt);
+    assertOpenAPI3(document.parsed);
+    return this.#lintAndBundle(document, resolver, request.shouldLint);
+  }
+
+  #resolver(request: SchemaLoadRequest): RefAccessResolver {
+    const { redoc, remoteRefTimeoutMs } = this.#options;
+    const config = resolveConfigWithAccess(redoc.resolve, {
+      timeoutMs: remoteRefTimeoutMs,
+      access: request.refAccess,
+    });
+    return new RefAccessResolver(config, request.refAccess);
+  }
+
+  async #lintAndBundle(
+    document: Document,
+    resolver: BaseResolver,
+    shouldLint: boolean,
+  ): Promise<OpenAPI3> {
+    const rethrow = (error: unknown) => rethrowDocumentError(error, document, resolver);
+    if (shouldLint) {
+      await this.#lint(document, resolver).catch(rethrow);
+    }
+    return this.#bundle(document, resolver).catch(rethrow);
+  }
+
+  async #lint(document: Document, resolver: BaseResolver): Promise<void> {
+    const startedAt = this.#options.now();
+    const problems = await lintDocument({
+      document,
+      config: this.#options.redoc.styleguide,
+      externalRefResolver: resolver,
+    });
+    this.#report(problems);
+    this.#options.logger.debug("Linted schema", "lint", this.#options.now() - startedAt);
+  }
+
+  async #bundle(document: Document, resolver: BaseResolver): Promise<OpenAPI3> {
+    const startedAt = this.#options.now();
+    // The lint resolver: documents it already loaded are not fetched again.
+    const bundled = await bundle({
+      config: this.#options.redoc,
+      dereference: false,
+      doc: document,
+      externalRefResolver: resolver,
+    });
+    this.#report(bundled.problems);
+    repairBundledRefs(bundled.bundle.parsed);
+    this.#options.logger.debug("Bundled schema", "bundle", this.#options.now() - startedAt);
+    return bundled.bundle.parsed;
+  }
+
+  /**
+   * Report every problem; then throw if any of them is an error. A problem that the Redocly
+   * config's `.redocly.lint-ignore.yaml` lists is left out, as `redocly lint` leaves it out
+   * (upstream #2189).
+   */
+  #report(problems: readonly NormalizedProblem[]): void {
+    const errorMessages: string[] = [];
+    for (const problem of problems) {
+      if (problem.ignored === true) {
+        this.#options.logger.debug(
+          `Ignored by the lint ignore file: ${problemMessage(problem)}`,
+          "lint",
+        );
+        continue;
+      }
+      const message = problemMessage(problem);
+      if (problem.severity === "error") {
+        errorMessages.push(message);
+        this.#options.logger.error(message);
+      } else {
+        this.#options.logger.warn(message);
+      }
+    }
+    if (errorMessages.length > 0) {
+      throw schemaInvalidError(errorMessages);
+    }
+  }
+}
+
+function problemMessage(problem: NormalizedProblem): string {
+  const location = problem.location?.[0]?.pointer;
+  return location ? `${problem.message} at ${location}` : problem.message;
+}
+
+/** A schema loader with one Redocly config and logger, for one or more loads. */
+export function createRedoclySchemaLoader(options: RedoclySchemaLoaderOptions): SchemaLoader {
+  return new RedoclySchemaLoader(options);
+}

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 },
+  });
+}