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

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,12 +104,22 @@ 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. */
   readonly headers: readonly ConfiguredHeader[];
   /** `--remote-ref-hosts`; undefined allows every host. */
   readonly hosts: readonly string[] | undefined;
+  /**
+   * The URL of the root document, if it is remote. The developer chose it, so neither it nor its
+   * redirects are limited to the hosts (ADR-017): a spec URL that redirects to a CDN loads.
+   */
+  readonly rootUrl: string | undefined;
 }
 
 /**
@@ -76,12 +135,13 @@ export function fetchWithCheckedRedirects(
   policy: RedirectPolicy,
 ): RemoteFetch {
   return async (input, init = {}) => {
+    const hosts = input === policy.rootUrl ? undefined : policy.hosts;
     let url = new URL(input);
     for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
-      if (hop > 0 && policy.hosts !== undefined && !isHostAllowed(url, policy.hosts)) {
+      if (hop > 0 && hosts !== undefined && !isHostAllowed(url, hosts)) {
         throw refForbiddenError(url.href, {
           reason: "host-not-allowed",
-          allowedHosts: [...policy.hosts],
+          allowedHosts: [...hosts],
         });
       }
       const headers = await headersFor(url, policy.headers);
@@ -97,11 +157,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;
 }
 
 /**
@@ -134,12 +196,16 @@ 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 root document's URL, whose redirects are not limited to the hosts. */
+  readonly rootUrl: string | undefined;
   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,10 +215,16 @@ 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,
+    rootUrl: options.rootUrl,
   });
   // The limit is outside the redirects, so all hops of one document share one slot.
   const customFetch = fetchWithConcurrencyLimit(checked, options.maxParallelFetches);

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

@@ -0,0 +1,102 @@
+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)/;
+/**
+ * The text formats that a `$ref` loads as text, as a `description` from a Markdown file. A URL
+ * keeps its document as text only when its extension or type names one of them: the last segment
+ * of an API's path often has a dot that is no file type (`/schemas/v1.0`, `/schemas/pet.v2`).
+ */
+const TEXT_EXTENSIONS: ReadonlySet<string> = new Set([".md", ".markdown", ".txt", ".html", ".htm"]);
+const TEXT_MIME_TYPE = /^text\/(markdown|x-markdown|html)\b/;
+const REMOTE_URL_RE = /^https?:\/\//;
+const PATH_SEPARATOR_RE = /[/\\]/;
+const EXTENSION_START = ".";
+
+/** The extension of the last segment of a path, with its dot; empty when it has none. */
+function extensionOf(path: string): string {
+  const name = path.split(PATH_SEPARATOR_RE).at(-1) ?? "";
+  const start = name.lastIndexOf(EXTENSION_START);
+  return start === -1 ? "" : name.slice(start);
+}
+
+/**
+ * The path of a document: the path of a URL, without its query and fragment, or the file path.
+ * Redocly took the extension of the whole URL, so `pet.yaml?token=…` had none it knew.
+ */
+function documentPath(absoluteRef: string): string {
+  return REMOTE_URL_RE.test(absoluteRef) && URL.canParse(absoluteRef)
+    ? new URL(absoluteRef).pathname
+    : absoluteRef;
+}
+
+/**
+ * Whether a source is parsed as YAML or JSON, or kept as text (a Markdown `description`, say).
+ * It is parsed when it is the root, when its type or the extension of its path says JSON or YAML,
+ * and when it is a URL whose path and type name no text format: an API serves its documents at
+ * paths like `/schemas/pet` or `/schemas/v1.0`, often as `text/plain`, and Redocly kept those as
+ * text, which failed as a schema. A local file is kept as text unless its name says JSON or YAML,
+ * as Redocly keeps it.
+ */
+export function isParsedSource(source: Source, isRoot: boolean): boolean {
+  const { absoluteRef, mimeType = "" } = source;
+  const extension = extensionOf(documentPath(absoluteRef));
+  const isTextUrl = TEXT_EXTENSIONS.has(extension) || TEXT_MIME_TYPE.test(mimeType);
+  return (
+    isRoot ||
+    PARSED_EXTENSIONS.has(extension) ||
+    PARSED_MIME_TYPE.test(mimeType) ||
+    (REMOTE_URL_RE.test(absoluteRef) && !isTextUrl)
+  );
+}
+
+/** 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 },
   });
 }

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

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import {
   type BaseResolver,
   type Document,
-  makeDocumentFromString,
+  parseYaml,
   ResolveError,
   Source,
   YamlParseError,
@@ -17,6 +17,8 @@ import {
   pathStringError,
   sourceEmptyError,
   sourceInvalidError,
+  type TextOrigin,
+  urlInvalidError,
 } from "./schema-load-errors.js";
 
 /** Parse a schema source of any supported type into a Redocly document (ENGINEERING_PLAN 4.5). */
@@ -24,6 +26,8 @@ import {
 export interface ParseSchemaOptions {
   absoluteRef: string;
   resolver: BaseResolver;
+  /** Where document text came from, for the message of text that is only a string. */
+  textOrigin?: TextOrigin;
 }
 
 /**
@@ -38,21 +42,28 @@ async function readStream(stream: Readable, absoluteRef: string): Promise<string
   }
 }
 
-const URL_PREFIXES = ["http://", "https://", "file://"] as const;
+/** A URL source string; a scheme is the same in any case (RFC 3986, section 3.1). */
+const URL_PREFIX_RE = /^(?:https?|file):\/\//i;
 
-/** A string is a URL, JSON (starts with `{`) or YAML. */
+/**
+ * A string is a URL, JSON (starts with `{`) or YAML. A string that starts like a URL but does not
+ * parse as one fails with `SCHEMA_SOURCE_INVALID`, not the parser's `TypeError`.
+ */
 function parseSchemaText(
   schema: string,
   options: ParseSchemaOptions,
 ): Promise<Document> | Document {
-  if (URL_PREFIXES.some((prefix) => schema.startsWith(prefix))) {
-    const url = new URL(schema);
+  if (URL_PREFIX_RE.test(schema)) {
+    const url = URL.parse(schema);
+    if (url === null) {
+      throw urlInvalidError(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);
+    : parseYamlText(schema, options.absoluteRef, options.textOrigin ?? "string");
 }
 
 function parseJsonText(text: string, absoluteRef: string): Document {
@@ -63,16 +74,28 @@ function parseJsonText(text: string, absoluteRef: string): Document {
   }
 }
 
-function parseYamlText(text: string, absoluteRef: string): Document {
+/**
+ * How a parser message names document text that is no file. The document itself is named as a
+ * file in the working directory, so that its relative `$ref`s resolve there, but no such file
+ * exists, and a message that named it sent the user looking for it.
+ */
+const TEXT_ORIGIN_NAMES: Readonly<Record<TextOrigin, string>> = {
+  string: "the schema string",
+  stream: "the schema stream",
+};
+
+function parseYamlText(text: string, absoluteRef: string, origin: TextOrigin): Document {
+  const source = new Source(absoluteRef, text);
   let document: Document;
   try {
-    document = makeDocumentFromString(text, absoluteRef);
+    document = { source, parsed: parseYaml(text, { filename: TEXT_ORIGIN_NAMES[origin] }) };
   } catch (cause) {
-    throw parseFailedError("yaml", absoluteRef, cause);
+    // As Redocly's own parse: the error keeps the first line, not the parser's code excerpt.
+    throw parseFailedError("yaml", absoluteRef, new YamlParseError(cause as Error, source));
   }
   // 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);
+    throw pathStringError(text, origin);
   }
   const failure = aliasExpansionFailure(document.parsed);
   if (failure !== undefined) {
@@ -139,7 +162,8 @@ export async function parseSchema(schema: unknown, options: ParseSchemaOptions):
     return resolveSchemaURL(options);
   }
   if (schema instanceof Readable) {
-    return parseSchema(await readStream(schema, options.absoluteRef), options);
+    const text = await readStream(schema, options.absoluteRef);
+    return parseSchema(text, { ...options, textOrigin: "stream" });
   }
   if (schema instanceof Buffer) {
     return parseSchema(schema.toString("utf8"), options);

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

@@ -1,4 +1,5 @@
 import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+import { childPointer, ROOT_POINTER } from "../../domain/openapi/json-pointer.js";
 
 /**
  * Keys Redocly 1.34 cannot walk. It looks up the type of every key with `type.properties[key]`,
@@ -57,11 +58,6 @@ interface PendingNode {
   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
@@ -77,10 +73,10 @@ function unsupportedKeysOf(document: LoadedDocument): UnsupportedKey[] {
       pending.push({ value, pointer });
     }
   };
-  enqueue(document.parsed, "#");
+  enqueue(document.parsed, ROOT_POINTER);
   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)}`;
+      const pointer = childPointer(node.pointer, key);
       if (isUnsupportedEntry(key, child)) {
         found.push({ key, pointer, source: document.source });
       }