openapi-typesafe 1.0.0-rc.3 → 1.0.0-rc.4

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

@@ -8,11 +8,17 @@ import {
   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 type {
+  LoadedSchema,
+  SchemaLoader,
+  SchemaLoadRequest,
+} from "../../application/ports/schema-loader.js";
 import { withStackOverflowReportedAsync } from "../../application/stack-overflow.js";
 import { WARNING_CODES, warningText } from "../../domain/warnings.js";
 import type { OpenAPI3 } from "../../types.js";
+import { removeBundledMappingCopies, schemaKeysOf } from "./bundled-mapping-copies.js";
 import { repairBundledRefs } from "./bundled-ref-repair.js";
+import { loadedDocuments, localFilesRead } from "./loaded-documents.js";
 import { findMalformedRefs, malformedRefsError } from "./malformed-refs.js";
 import { RefAccessResolver } from "./ref-access.js";
 import { checkRefsResolve } from "./ref-resolution-check.js";
@@ -25,11 +31,7 @@ import {
   versionUnsupportedError,
 } from "./schema-load-errors.js";
 import { parseSchema } from "./schema-source.js";
-import {
-  findUnsupportedKeys,
-  type LoadedDocument,
-  unsupportedKeysError,
-} from "./unsupported-keys.js";
+import { findUnsupportedKeys, unsupportedKeysError } from "./unsupported-keys.js";
 
 /**
  * The SchemaLoader port on Redocly 1.34 (ADR-005): parse any inherited source type, then lint and
@@ -107,21 +109,6 @@ function sourceFilePath(source: URL): string {
   }
 }
 
-/**
- * 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,
@@ -148,7 +135,7 @@ class RedoclySchemaLoader implements SchemaLoader {
     this.#options = options;
   }
 
-  async load(request: SchemaLoadRequest): Promise<OpenAPI3> {
+  async load(request: SchemaLoadRequest): Promise<LoadedSchema> {
     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.
@@ -164,7 +151,7 @@ class RedoclySchemaLoader implements SchemaLoader {
     return bundled;
   }
 
-  async #parseAndBundle(request: SchemaLoadRequest, resolver: BaseResolver): Promise<OpenAPI3> {
+  async #parseAndBundle(request: SchemaLoadRequest, resolver: BaseResolver): Promise<LoadedSchema> {
     const { logger, now } = this.#options;
     const configLoadedAt = now();
     logger.debug("Loaded Redoc config", "redoc", now() - configLoadedAt);
@@ -173,7 +160,10 @@ class RedoclySchemaLoader implements SchemaLoader {
     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);
+    const bundled = await this.#lintAndBundle(document, resolver, request.shouldLint);
+    const isRootAFile = request.source instanceof URL && request.source.protocol === "file:";
+    const localFiles = await localFilesRead(document, resolver, isRootAFile);
+    return { document: bundled, localFiles };
   }
 
   #resolver(request: SchemaLoadRequest): RefAccessResolver {
@@ -182,10 +172,12 @@ class RedoclySchemaLoader implements SchemaLoader {
       timeoutMs: remoteRefTimeoutMs,
       access: request.refAccess,
       maxParallelFetches: remoteDocumentLimits.maxParallelFetches,
+      bodyLimits: remoteDocumentLimits,
     });
     return new RefAccessResolver(config, {
       access: request.refAccess,
       maxRemoteDocuments: remoteDocumentLimits.maxDocuments,
+      maxRemoteNodes: remoteDocumentLimits.maxNodes,
     });
   }
 
@@ -216,6 +208,7 @@ class RedoclySchemaLoader implements SchemaLoader {
 
   async #bundle(document: Document, resolver: BaseResolver): Promise<OpenAPI3> {
     const startedAt = this.#options.now();
+    const schemaKeys = schemaKeysOf(document.parsed);
     // The lint resolver: documents it already loaded are not fetched again.
     const bundled = await bundle({
       config: this.#options.redoc,
@@ -224,6 +217,7 @@ class RedoclySchemaLoader implements SchemaLoader {
       externalRefResolver: resolver,
     });
     this.#report(bundled.problems);
+    removeBundledMappingCopies(bundled.bundle.parsed, schemaKeys);
     repairBundledRefs(bundled.bundle.parsed);
     this.#options.logger.debug("Bundled schema", "bundle", this.#options.now() - startedAt);
     return bundled.bundle.parsed;

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

@@ -10,9 +10,10 @@ import {
 } from "@redocly/openapi-core";
 import type { RefAccess } from "../../application/ports/schema-loader.js";
 import { ERROR_CODES, type OpenAPITypesafeError } from "../../domain/errors.js";
-import { redactUrlCredentials } from "../../domain/url-credentials.js";
+import { redactUrlSecrets } from "../../domain/url-secrets.js";
 import { aliasExpansionFailure } from "./alias-limit.js";
 import { isHostAllowed } from "./allowed-hosts.js";
+import { isParsedSource, RemoteNodeLimit } from "./remote-node-limit.js";
 import { refForbiddenError } from "./schema-load-errors.js";
 
 /**
@@ -92,15 +93,20 @@ function localFromRemoteRefusal(
   if (!isRemoteRef(base) || isRemoteRef(absoluteRef)) {
     return undefined;
   }
-  const shownBase = redactUrlCredentials(base);
+  const shownBase = redactUrlSecrets(base);
   return refForbiddenError(absoluteRef, { reason: "local-ref-from-remote", base: shownBase });
 }
 
+/** The scheme of an `http(s)` URL, in any case. */
+const REMOTE_SCHEME_RE = /^https?:(?=\/\/)/i;
+
 /** The limits one resolver checks; each load gets its own resolver. */
 export interface RefAccessLimits {
   readonly access: RefAccess;
   /** Remote documents one load may fetch, the root included (threat model T2). */
   readonly maxRemoteDocuments: number;
+  /** Nodes the remote documents of one load may parse into together (threat model T2). */
+  readonly maxRemoteNodes: number;
 }
 
 /**
@@ -110,6 +116,7 @@ export interface RefAccessLimits {
  */
 export class RefAccessResolver extends BaseResolver {
   readonly #limits: RefAccessLimits;
+  readonly #nodeLimit: RemoteNodeLimit;
   readonly #refusals: OpenAPITypesafeError[] = [];
   /** The root document's ref: it is chosen by the developer, so it is not limited. */
   #rootRef: string | undefined;
@@ -119,6 +126,7 @@ export class RefAccessResolver extends BaseResolver {
   constructor(config: ResolveConfig, limits: RefAccessLimits) {
     super(config);
     this.#limits = limits;
+    this.#nodeLimit = new RemoteNodeLimit(limits.maxRemoteNodes);
   }
 
   /** The first document that was refused, if any. */
@@ -126,6 +134,17 @@ export class RefAccessResolver extends BaseResolver {
     return this.#refusals[0];
   }
 
+  /**
+   * A scheme is the same in any case (RFC 3986, section 3.1), but Redocly takes only `http://` and
+   * `https://` as URLs: it read `HTTP://host/x.yaml` as a file path, and its "not found" message
+   * showed the user info and the query of the URL, which no longer looked like one. The scheme
+   * is written in lowercase first, so the `$ref` loads as the URL it is, within the same limits.
+   */
+  override resolveExternalRef(base: string | null, ref: string): string {
+    const normalized = ref.replace(REMOTE_SCHEME_RE, (scheme) => scheme.toLowerCase());
+    return super.resolveExternalRef(base, normalized);
+  }
+
   override resolveDocument(
     base: string | null,
     ref: string,
@@ -145,7 +164,7 @@ export class RefAccessResolver extends BaseResolver {
 
   /** 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 document = this.#parsed(source, isRoot);
     const failure = aliasExpansionFailure(document.parsed);
     if (failure !== undefined) {
       throw new YamlParseError(failure, source);
@@ -153,6 +172,21 @@ export class RefAccessResolver extends BaseResolver {
     return document;
   }
 
+  /** A remote document is parsed within the node limit; any other one as Redocly parses it. */
+  #parsed(source: Source, isRoot: boolean): Document {
+    if (!isRemoteRef(source.absoluteRef) || !isParsedSource(source, isRoot)) {
+      return super.parseDocument(source, isRoot);
+    }
+    try {
+      return this.#nodeLimit.parse(source);
+    } catch (error) {
+      if (isRefusal(error)) {
+        this.#refusals.push(error);
+      }
+      throw new YamlParseError(error as Error, source);
+    }
+  }
+
   override async loadExternalRef(absoluteRef: string): Promise<Source> {
     const refusal = this.#countRefusal(absoluteRef) ?? (await this.#accessRefusal(absoluteRef));
     if (refusal !== undefined) {

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

@@ -1,4 +1,4 @@
-import { escapePointerSegment } from "../../domain/openapi/json-pointer.js";
+import { childPointer, ROOT_POINTER } from "../../domain/openapi/json-pointer.js";
 
 /** An object with a string `$ref`, and its JSON Pointer in the document. */
 export interface RefHolder {
@@ -30,13 +30,13 @@ export function findRefHolders(document: unknown): RefHolder[] {
       pending.push({ value, pointer });
     }
   };
-  enqueue(document, "#");
+  enqueue(document, ROOT_POINTER);
   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)}`);
+      enqueue(child, childPointer(next.pointer, key));
     }
   }
   return found;

package/src/adapters/redocly-loader/remote-body-limit.ts

@@ -0,0 +1,66 @@
+import type { OpenAPITypesafeError } from "../../domain/errors.js";
+import { refForbiddenError } from "./schema-load-errors.js";
+
+/** The decoded size limits of the remote documents of one load (threat model T2). */
+export interface RemoteBodyLimits {
+  /** Bytes of one remote document's body after `Content-Encoding` is decoded. */
+  readonly maxDocumentBytes: number;
+  /** Bytes of the bodies of every remote document of one load together, decoded. */
+  readonly maxTotalBytes: number;
+}
+
+/**
+ * Reads remote bodies as a stream and stops at the limits. Fetch decodes `gzip`, `deflate` and
+ * `br` before the body reaches the loader, so a body of a few megabytes on the wire can become
+ * gigabytes in memory (a "gzip bomb"); counting the decoded bytes while they arrive stops it before
+ * the memory is taken. One instance per load: the total covers every document of that load.
+ */
+export class RemoteBodyLimit {
+  readonly #limits: RemoteBodyLimits;
+  #totalBytes = 0;
+
+  constructor(limits: RemoteBodyLimits) {
+    this.#limits = limits;
+  }
+
+  /** The whole body of `response` from `url`; fails with `SCHEMA_REF_FORBIDDEN` past a limit. */
+  async read(response: Response, url: string): Promise<ArrayBuffer> {
+    const reader = response.body?.getReader();
+    if (reader === undefined) {
+      return new ArrayBuffer(0);
+    }
+    const chunks: Uint8Array[] = [];
+    let documentBytes = 0;
+    for (let next = await reader.read(); !next.done; next = await reader.read()) {
+      documentBytes += next.value.byteLength;
+      this.#totalBytes += next.value.byteLength;
+      const refusal = this.#refusal(url, documentBytes);
+      if (refusal !== undefined) {
+        await reader.cancel();
+        throw refusal;
+      }
+      chunks.push(next.value);
+    }
+    return joined(chunks, documentBytes);
+  }
+
+  #refusal(url: string, documentBytes: number): OpenAPITypesafeError | undefined {
+    const { maxDocumentBytes, maxTotalBytes } = this.#limits;
+    if (documentBytes > maxDocumentBytes) {
+      return refForbiddenError(url, { reason: "remote-document-too-large", maxDocumentBytes });
+    }
+    return this.#totalBytes > maxTotalBytes
+      ? refForbiddenError(url, { reason: "remote-documents-too-large", maxTotalBytes })
+      : undefined;
+  }
+}
+
+function joined(chunks: readonly Uint8Array[], byteLength: number): ArrayBuffer {
+  const body = new Uint8Array(byteLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body.buffer;
+}

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

@@ -2,11 +2,12 @@ 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 { type ConfiguredHeader, headersFor } from "./configured-headers.js";
+import { RemoteBodyLimit, type RemoteBodyLimits } from "./remote-body-limit.js";
 import { refForbiddenError } from "./schema-load-errors.js";
 
 /**
- * How the loader fetches remote documents: a time limit, the host limit and the configured headers
- * checked on every redirect.
+ * How the loader fetches remote documents: a time limit, size limits, the host limit and the
+ * configured headers checked on every redirect.
  */
 
 type ResolveConfig = RedoclyConfig["resolve"];
@@ -25,9 +26,16 @@ 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();
+/**
+ * A response whose body is already read within the size limits, so that reading it again cannot
+ * wait, fail or take more memory.
+ */
+async function bufferedResponse(
+  response: Response,
+  url: string,
+  bodyLimit: RemoteBodyLimit,
+): Promise<Response> {
+  const body = await bodyLimit.read(response, url);
   const { status, statusText, headers } = response;
   return new Response(NULL_BODY_STATUSES.has(status) ? null : body, {
     status,
@@ -36,6 +44,45 @@ async function bufferedResponse(response: Response): Promise<Response> {
   });
 }
 
+/**
+ * Codes of a connection that closed before any response came. The server can close a kept-alive
+ * connection while the process is busy (parsing a large document, generating another API) and
+ * has not read the close yet; the next request on that connection then fails with one of these.
+ */
+const CLOSED_CONNECTION_CODES: ReadonlySet<string> = new Set([
+  "ECONNRESET",
+  "EPIPE",
+  "UND_ERR_SOCKET",
+]);
+
+/** Methods that may be sent again without a second effect (RFC 9110 §9.2.2). */
+const IDEMPOTENT_METHODS: ReadonlySet<string> = new Set(["GET", "HEAD"]);
+const DEFAULT_METHOD = "GET";
+
+/** Whether fetch failed because its connection closed before any response came. */
+function isClosedConnection(error: unknown): boolean {
+  const cause = error instanceof TypeError ? error.cause : undefined;
+  const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
+  return typeof code === "string" && CLOSED_CONNECTION_CODES.has(code);
+}
+
+/**
+ * Fetch, and send the request once more when its connection closed before any response came, as
+ * RFC 9112 §9.3.1 allows for an idempotent request. Fetch drops a connection that failed, so the
+ * second attempt goes out on another one; a second failure is the server's answer and is thrown.
+ */
+async function fetchOnOpenConnection(input: string, init: RequestInit): Promise<Response> {
+  try {
+    return await fetch(input, init);
+  } catch (error) {
+    const method = (init.method ?? DEFAULT_METHOD).toUpperCase();
+    if (!(IDEMPOTENT_METHODS.has(method) && isClosedConnection(error))) {
+      throw error;
+    }
+    return fetch(input, init);
+  }
+}
+
 /**
  * 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
@@ -43,11 +90,13 @@ async function bufferedResponse(response: Response): Promise<Response> {
  * 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 {
+function fetchWithTimeout(timeoutMs: number, bodyLimit: RemoteBodyLimit): RemoteFetch {
   return async (input, init = {}) => {
     try {
-      const response = await fetch(input, { ...init, signal: AbortSignal.timeout(timeoutMs) });
-      return await bufferedResponse(response);
+      // One signal for both attempts, so that a request sent again stays within the same limit.
+      const signal = AbortSignal.timeout(timeoutMs);
+      const response = await fetchOnOpenConnection(input, { ...init, signal });
+      return await bufferedResponse(response, input, bodyLimit);
     } catch (cause) {
       const isTimeout = cause instanceof Error && cause.name === "TimeoutError";
       throw isTimeout ? new Error(`Timed out after ${timeoutMs} ms loading ${input}`) : cause;
@@ -55,6 +104,11 @@ function fetchWithTimeout(timeoutMs: number): RemoteFetch {
   };
 }
 
+/** A configured `customFetch` with its bodies read within the size limits. */
+function fetchWithBodyLimit(fetchImpl: RemoteFetch, bodyLimit: RemoteBodyLimit): RemoteFetch {
+  return async (input, init) => bufferedResponse(await fetchImpl(input, init), input, bodyLimit);
+}
+
 /** What every hop of a remote fetch is checked against. */
 export interface RedirectPolicy {
   /** `resolve.http.headers` of the Redocly config; chosen again for the URL of every hop. */
@@ -97,11 +151,13 @@ export function fetchWithCheckedRedirects(
 }
 
 /** Bounds on the remote documents of one load (threat model T2, ADR-033). */
-export interface RemoteDocumentLimits {
+export interface RemoteDocumentLimits extends RemoteBodyLimits {
   /** Remote documents one load may fetch, the root included; one more is refused. */
   readonly maxDocuments: number;
   /** Remote documents fetched at the same time; the others wait for a free slot. */
   readonly maxParallelFetches: number;
+  /** Nodes (keys and values) the remote documents of one load may parse into together. */
+  readonly maxNodes: number;
 }
 
 /**
@@ -135,11 +191,13 @@ export interface RemoteFetchOptions {
   readonly timeoutMs: number;
   readonly access: RefAccess;
   readonly maxParallelFetches: number;
+  readonly bodyLimits: RemoteBodyLimits;
 }
 
 /**
  * The resolve config with the fetch the loader uses. A `customFetch` of the Redocly config is
- * kept and wrapped, so that each redirect is checked and only a few documents load at once. The
+ * kept and wrapped, so that each redirect is checked, each body is read within the size limits
+ * and only a few documents load at once. The
  * configured headers move into that wrapper: Redocly would match them against the raw URL and
  * send them on through redirects.
  */
@@ -149,7 +207,12 @@ export function resolveConfigWithAccess(
 ): 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);
+  // One limit per load, so that the total covers every document this resolver fetches.
+  const bodyLimit = new RemoteBodyLimit(options.bodyLimits);
+  const base =
+    configured === undefined
+      ? fetchWithTimeout(options.timeoutMs, bodyLimit)
+      : fetchWithBodyLimit(configured, bodyLimit);
   const checked = fetchWithCheckedRedirects(base, {
     headers: resolve.http.headers,
     hosts: options.access.remoteHosts,

package/src/adapters/redocly-loader/remote-node-limit.ts

@@ -0,0 +1,62 @@
+import { type Document, parseYaml, type Source } from "@redocly/openapi-core";
+import type { OpenAPITypesafeError } from "../../domain/errors.js";
+import { refForbiddenError } from "./schema-load-errors.js";
+
+/**
+ * Bounds the parsed size of the remote documents of one load (threat model T2). The byte limits
+ * do not bound memory: parsing multiplies it by the density of the text, and 250 MiB of `{},`
+ * (87 million empty objects, under a quarter of a megabyte as gzip) took the process past its
+ * 4 GB heap. The parser reports every node it builds, keys included, and the parse stops when
+ * the nodes of all remote documents of the load pass the limit, before their memory is taken.
+ */
+
+/** The extensions that Redocly 1.34's `BaseResolver.parseDocument` parses as YAML or JSON. */
+const PARSED_EXTENSIONS: ReadonlySet<string> = new Set([".json", ".yml", ".yaml"]);
+const PARSED_MIME_TYPE = /(json|yaml|openapi)/;
+
+/** Whether Redocly parses this source, or keeps its text: the same rule as its own resolver. */
+export function isParsedSource(source: Source, isRoot: boolean): boolean {
+  const { absoluteRef, mimeType } = source;
+  const extension = absoluteRef.slice(absoluteRef.lastIndexOf("."));
+  return isRoot || PARSED_EXTENSIONS.has(extension) || PARSED_MIME_TYPE.test(mimeType ?? "");
+}
+
+/** The parser's event for a node it starts to build. */
+const NODE_OPENED = "open";
+
+/** One instance per load: the count covers every remote document of that load. */
+export class RemoteNodeLimit {
+  readonly #maxNodes: number;
+  #nodes = 0;
+
+  constructor(maxNodes: number) {
+    this.#maxNodes = maxNodes;
+  }
+
+  /**
+   * The parsed document of `source`, as Redocly parses it. Fails with `SCHEMA_REF_FORBIDDEN`
+   * (`remote-documents-too-many-nodes`) once the nodes of the load pass the limit.
+   */
+  parse(source: Source): Document {
+    const listener = (event: string): void => {
+      if (event !== NODE_OPENED) {
+        return;
+      }
+      this.#nodes += 1;
+      const refusal = this.#refusal(source.absoluteRef);
+      if (refusal !== undefined) {
+        throw refusal;
+      }
+    };
+    return { source, parsed: parseYaml(source.body, { filename: source.absoluteRef, listener }) };
+  }
+
+  #refusal(url: string): OpenAPITypesafeError | undefined {
+    return this.#nodes > this.#maxNodes
+      ? refForbiddenError(url, {
+          reason: "remote-documents-too-many-nodes",
+          maxNodes: this.#maxNodes,
+        })
+      : undefined;
+  }
+}

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

@@ -1,6 +1,6 @@
 import { assertNever } from "../../domain/assert-never.js";
 import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
-import { redactUrlCredentials } from "../../domain/url-credentials.js";
+import { redactUnparsedUrl, redactUrlSecrets } from "../../domain/url-secrets.js";
 
 /**
  * The typed errors of loading, validating and bundling a document (ADR-011). Messages are the
@@ -23,6 +23,15 @@ export function sourceInvalidError(source: unknown): OpenAPITypesafeError {
   });
 }
 
+/** A source string starts with a URL scheme but does not parse as a URL. */
+export function urlInvalidError(text: string): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_SOURCE_INVALID,
+    message: `The string ${redactUnparsedUrl(text)} starts like a URL but is not a valid URL`,
+    details: { reason: "url", received: "string" },
+  });
+}
+
 function causeMessage(cause: unknown): string {
   return cause instanceof Error ? cause.message : String(cause);
 }
@@ -30,19 +39,29 @@ function causeMessage(cause: unknown): string {
 /** Enough of a source string to recognise it in the message. */
 const SOURCE_TEXT_IN_MESSAGE = 200;
 
+/** Where document text that is only a YAML string came from. */
+export type TextOrigin = "string" | "stream";
+
+const LOAD_FILE_ADVICE =
+  "To load a file, pass a URL: openapiTS(pathToFileURL(path)) from node:url.";
+
 /**
  * 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.
+ * document (docs/node.md). The message says how to load the file instead. Text read from a
+ * stream (stdin in the CLI) is named as such; `details.text` lets the CLI give its own advice.
  */
-export function pathStringError(text: string): OpenAPITypesafeError {
+export function pathStringError(text: string, origin: TextOrigin): OpenAPITypesafeError {
   const shown =
     text.length > SOURCE_TEXT_IN_MESSAGE ? `${text.slice(0, SOURCE_TEXT_IN_MESSAGE)}…` : text;
+  const message =
+    origin === "string"
+      ? `The string "${shown}" was parsed as YAML text, not loaded as a file. ${LOAD_FILE_ADVICE}`
+      : `The stream held only the YAML string "${shown}", not an OpenAPI document. ` +
+        LOAD_FILE_ADVICE;
   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" },
+    message,
+    details: { reason: "path", received: origin, text: shown },
   });
 }
 
@@ -51,7 +70,7 @@ export function loadFailedError(absoluteRef: string, cause: unknown): OpenAPITyp
   return new OpenAPITypesafeError({
     code: ERROR_CODES.SCHEMA_LOAD_FAILED,
     message: causeMessage(cause),
-    details: { source: redactUrlCredentials(absoluteRef) },
+    details: { source: redactUrlSecrets(absoluteRef) },
     cause,
   });
 }
@@ -65,7 +84,7 @@ export function parseFailedError(
   return new OpenAPITypesafeError({
     code: ERROR_CODES.SCHEMA_PARSE_FAILED,
     message: causeMessage(cause),
-    details: { format, source: redactUrlCredentials(absoluteRef) },
+    details: { format, source: redactUrlSecrets(absoluteRef) },
     cause,
   });
 }
@@ -90,7 +109,7 @@ export function schemaInvalidError(problems: readonly string[]): OpenAPITypesafe
   return new OpenAPITypesafeError({
     code: ERROR_CODES.SCHEMA_INVALID,
     message: problems.at(-1) ?? "",
-    details: { problems: problems.map(redactUrlCredentials) },
+    details: { problems: problems.map(redactUrlSecrets) },
   });
 }
 
@@ -113,7 +132,17 @@ export type RefRefusalDetails =
   | { readonly reason: "outside-local-root"; readonly localRoot: string }
   | { readonly reason: "host-not-allowed"; readonly allowedHosts: readonly string[] }
   | { readonly reason: "local-ref-from-remote"; readonly base: string }
-  | { readonly reason: "too-many-remote-documents"; readonly maxDocuments: number };
+  | { readonly reason: "too-many-remote-documents"; readonly maxDocuments: number }
+  | { readonly reason: "remote-document-too-large"; readonly maxDocumentBytes: number }
+  | { readonly reason: "remote-documents-too-large"; readonly maxTotalBytes: number }
+  | { readonly reason: "remote-documents-too-many-nodes"; readonly maxNodes: number };
+
+const BYTES_PER_MEBIBYTE = 1024 * 1024;
+
+/** A byte count in MiB, as the limits are chosen: `256 MiB`; a smaller limit in bytes. */
+function sizeText(bytes: number): string {
+  return bytes % BYTES_PER_MEBIBYTE === 0 ? `${bytes / BYTES_PER_MEBIBYTE} MiB` : `${bytes} bytes`;
+}
 
 function limitText(details: RefRefusalDetails): string {
   switch (details.reason) {
@@ -127,6 +156,16 @@ function limitText(details: RefRefusalDetails): string {
       return `it is not an http(s) URL, and the $ref is in the remote document ${details.base}`;
     case "too-many-remote-documents":
       return `the document refers to more than ${details.maxDocuments} remote documents`;
+    case "remote-document-too-large":
+      return `its body is larger than ${sizeText(details.maxDocumentBytes)} once decoded`;
+    case "remote-documents-too-large": {
+      const limit = sizeText(details.maxTotalBytes);
+      return `the remote documents of this run are larger than ${limit} together once decoded`;
+    }
+    case "remote-documents-too-many-nodes": {
+      const limit = details.maxNodes;
+      return `the remote documents of this run parse into more than ${limit} nodes together`;
+    }
     default:
       return assertNever(details);
   }
@@ -134,13 +173,13 @@ function limitText(details: RefRefusalDetails): string {
 
 /**
  * A `$ref` is outside the local root, its host is not allowed (threat model R1, R2), a remote
- * document refers to a local file (T3), or there are too many remote documents (T2).
+ * document refers to a local file (T3), or there are too many or too large remote documents (T2).
  */
 export function refForbiddenError(ref: string, details: RefRefusalDetails): OpenAPITypesafeError {
   const limit = limitText(details);
   return new OpenAPITypesafeError({
     code: ERROR_CODES.SCHEMA_REF_FORBIDDEN,
     message: `Refused to load ${ref}: ${limit}`,
-    details: { ref: redactUrlCredentials(ref), ...details },
+    details: { ref: redactUrlSecrets(ref), ...details },
   });
 }