openapi-typesafe 1.0.0-rc.0 → 1.0.0-rc.2

package/src/adapters/redocly-loader/ref-resolution-check.ts

@@ -0,0 +1,257 @@
+import {
+  type BaseResolver,
+  type Document,
+  detectSpec,
+  getTypes,
+  isRef,
+  normalizeTypes,
+  type Config as RedoclyConfig,
+} from "@redocly/openapi-core";
+import {
+  ANCHOR_REF,
+  escapePointer,
+  hasRef,
+  isExternalValue,
+  isNamedType,
+  joinPointer,
+  nextTick,
+  parseRef,
+  propertyType,
+  REF_CYCLE_MESSAGE,
+  type Ref,
+  type RefStack,
+  type ResolvedRef,
+  UNKNOWN_TYPE,
+  type WalkType,
+} from "./ref-resolution-steps.js";
+
+/**
+ * Redocly 1.34 resolves `$ref`s with `Promise.all` over the lookups it has started and stops at
+ * the first one that fails. Lookups it starts after that (the walk of a document that was still
+ * loading) are never awaited: when one of them fails too, its rejection is unhandled, and Node.js
+ * ends the process on an unhandled rejection (ADR-031). Redocly 2.x has the same loop.
+ *
+ * This is a port of Redocly's `resolveDocument` (`lib/resolve.js`, 1.34.22, MIT) that waits for
+ * every lookup and then throws the first failure. The loader runs it before Redocly lints or
+ * bundles, so Redocly only resolves documents in which no lookup fails. It walks the same nodes
+ * with the same types and throws the same errors: the "Self-referencing circular pointer" Error,
+ * the URIError of a malformed percent escape, and the TypeError of a key such as `valueOf`.
+ */
+
+/** One walk of the documents a root reaches, with every `$ref` lookup it starts. */
+class RefResolutionWalk {
+  readonly #resolver: BaseResolver;
+  /** Redocly's `SpecExtension` type: its values are walked like values of no known type. */
+  readonly specExtension: WalkType;
+  /** Walked nodes per type name; a node walked again with the same type starts the same lookups. */
+  readonly #seenNodes = new Map<string, WeakSet<object>>();
+  readonly #lookups: Promise<void>[] = [];
+
+  constructor(resolver: BaseResolver, specExtension: WalkType) {
+    this.#resolver = resolver;
+    this.specExtension = specExtension;
+  }
+
+  isWalkedLikeUnknown(type: WalkType): boolean {
+    return type === UNKNOWN_TYPE || type === this.specExtension;
+  }
+
+  /** Wait for every lookup, including those started while waiting; return the first failure. */
+  async settle(): Promise<PromiseRejectedResult | undefined> {
+    let settled: PromiseSettledResult<void>[];
+    do {
+      settled = await Promise.allSettled(this.#lookups);
+    } while (settled.length !== this.#lookups.length);
+    return settled.find((result) => result.status === "rejected");
+  }
+
+  walkFrom(node: unknown, document: Document, pointer: string, type: WalkType): void {
+    new DocumentWalk(this, document).walk(node, type, document.source.absoluteRef + pointer);
+  }
+
+  /** Whether the node was walked with this type before; marks it walked. */
+  isSeen(type: WalkType, node: object): boolean {
+    let seen = this.#seenNodes.get(type.name);
+    if (seen === undefined) {
+      seen = new WeakSet();
+      this.#seenNodes.set(type.name, seen);
+    }
+    if (seen.has(node)) {
+      return true;
+    }
+    seen.add(node);
+    return false;
+  }
+
+  track(lookup: Promise<ResolvedRef>, type: WalkType): void {
+    this.#lookups.push(
+      lookup.then((resolved) => {
+        if (resolved.resolved && resolved.document !== undefined) {
+          this.walkFrom(resolved.node, resolved.document, resolved.nodePointer ?? "#/", type);
+        }
+      }),
+    );
+  }
+
+  async loadDocument(base: Document, uri: string): Promise<Document | undefined> {
+    try {
+      return (await this.#resolver.resolveDocument(base.source.absoluteRef, uri)) as Document;
+    } catch {
+      // Redocly records the failed lookup as an unresolved `$ref`; the lint reports it.
+      return undefined;
+    }
+  }
+}
+
+/** The walk of one document from one node, with the anchors it collects (as in Redocly). */
+class DocumentWalk {
+  readonly #walk: RefResolutionWalk;
+  readonly #document: Document;
+  readonly #anchors = new Map<string, unknown>();
+
+  constructor(walk: RefResolutionWalk, document: Document) {
+    this.#walk = walk;
+    this.#document = document;
+  }
+
+  walk(node: unknown, type: WalkType, absoluteRef: string): void {
+    if (typeof node !== "object" || node === null || this.#walk.isSeen(type, node)) {
+      return;
+    }
+    const anchor = (node as { $anchor?: unknown }).$anchor;
+    if (Object.hasOwn(node, "$anchor") && anchor) {
+      this.#anchors.set(`#${String(anchor)}`, node);
+    }
+    if (Array.isArray(node)) {
+      this.#walkItems(node, type, absoluteRef);
+      return;
+    }
+    for (const name of Object.keys(node)) {
+      const value = (node as Record<string, unknown>)[name];
+      const [propType, walked] = propertyType(type, name, value, this.#walk.specExtension);
+      if (isNamedType(propType) && typeof walked === "object") {
+        this.walk(walked, propType, joinPointer(absoluteRef, escapePointer(name)));
+      }
+    }
+    if (isRef(node)) {
+      this.#walk.track(this.#follow(this.#document, node, { prev: null, node }), type);
+    }
+    if (isExternalValue(node)) {
+      const ref = { $ref: node.externalValue };
+      this.#walk.track(this.#follow(this.#document, ref, { prev: null, node }), type);
+    }
+  }
+
+  #walkItems(items: readonly unknown[], type: WalkType, absoluteRef: string): void {
+    const itemsType = type.items;
+    if (itemsType === undefined && !this.#walk.isWalkedLikeUnknown(type)) {
+      return;
+    }
+    items.forEach((item, index) => {
+      const pointer = joinPointer(absoluteRef, index);
+      const itemType = typeof itemsType === "function" ? itemsType(item, pointer) : itemsType;
+      if (itemType === undefined && !this.#walk.isWalkedLikeUnknown(type)) {
+        return;
+      }
+      this.walk(item, isNamedType(itemType) ? itemType : UNKNOWN_TYPE, pointer);
+    });
+  }
+
+  async #follow(document: Document, ref: Ref, refStack: RefStack): Promise<ResolvedRef> {
+    if (hasRef(refStack.prev, ref)) {
+      throw new Error(REF_CYCLE_MESSAGE);
+    }
+    if (ANCHOR_REF.test(ref.$ref)) {
+      await nextTick();
+      return { resolved: true, node: this.#anchors.get(ref.$ref), document, nodePointer: ref.$ref };
+    }
+    const { uri, pointer } = parseRef(ref.$ref);
+    const targetDocument = uri === null ? document : await this.#walk.loadDocument(document, uri);
+    if (targetDocument === undefined) {
+      return { resolved: false };
+    }
+    const found = await this.#followSegments(targetDocument, pointer, refStack);
+    if (found.document !== undefined && isRef(found.node)) {
+      return this.#follow(found.document, found.node, pushRef(refStack, found.node));
+    }
+    return found;
+  }
+
+  /** Follow the pointer segments; a `$ref` met on the way is resolved first. */
+  async #followSegments(
+    targetDocument: Document,
+    segments: readonly string[],
+    refStack: RefStack,
+  ): Promise<ResolvedRef> {
+    let document = targetDocument;
+    let nodePointer = "#/";
+    let target: unknown = targetDocument.parsed;
+    for (const segment of segments) {
+      if (typeof target !== "object") {
+        return { resolved: true, node: undefined, document, nodePointer };
+      }
+      // A `null` target throws a TypeError here, as it does in Redocly.
+      const step = (target as Record<string, unknown>)[segment];
+      if (step !== undefined) {
+        target = step;
+      } else if (isRef(target)) {
+        const resolved = await this.#follow(document, target, pushRef(refStack, target));
+        document = resolved.document ?? document;
+        if (typeof resolved.node !== "object") {
+          return {
+            resolved: true,
+            node: undefined,
+            document,
+            nodePointer: resolved.nodePointer ?? nodePointer,
+          };
+        }
+        target = (resolved.node as Record<string, unknown>)[segment];
+        nodePointer = resolved.nodePointer ?? nodePointer;
+      } else {
+        return { resolved: true, node: undefined, document, nodePointer };
+      }
+      nodePointer = joinPointer(nodePointer, escapePointer(segment));
+    }
+    return { resolved: true, node: target, document, nodePointer };
+  }
+}
+
+function pushRef(head: RefStack, node: unknown): RefStack {
+  return { prev: head, node };
+}
+
+/**
+ * Resolve every `$ref` the document reaches, as Redocly's lint and bundle do, and throw the first
+ * failure only after all lookups have finished. Documents are loaded through the given resolver,
+ * whose cache Redocly then reuses.
+ */
+export async function checkRefsResolve(
+  document: Document,
+  resolver: BaseResolver,
+  styleguide: RedoclyConfig["styleguide"],
+): Promise<void> {
+  const specVersion = detectSpec(document.parsed);
+  const types = normalizeTypes(
+    styleguide.extendTypes(getTypes(specVersion), specVersion),
+    styleguide,
+  );
+  const rootType = types.Root;
+  const specExtension = types.SpecExtension;
+  if (rootType === undefined || specExtension === undefined) {
+    // Redocly gives every spec version both types; a missing one is a Redocly change to port.
+    throw new Error(`Redocly has no Root or SpecExtension type for ${specVersion}`);
+  }
+  const walk = new RefResolutionWalk(resolver, specExtension);
+  let rootFailure: PromiseRejectedResult | undefined;
+  try {
+    walk.walkFrom(document.parsed, document, "#/", rootType);
+  } catch (error) {
+    // The walk of the root can fail after it started lookups; they are awaited all the same.
+    rootFailure = { status: "rejected", reason: error };
+  }
+  const lookupFailure = await walk.settle();
+  const failure = rootFailure ?? lookupFailure;
+  if (failure !== undefined) {
+    throw failure.reason;
+  }
+}

package/src/adapters/redocly-loader/ref-resolution-steps.ts

@@ -0,0 +1,113 @@
+import type { Document, normalizeTypes } from "@redocly/openapi-core";
+import { parseRefPointer } from "../../domain/openapi/json-pointer.js";
+
+/**
+ * The pieces of Redocly 1.34's `$ref` resolution (`lib/resolve.js`, `lib/ref-utils.js`, MIT) that
+ * the resolution check (`ref-resolution-check.ts`, ADR-031) walks with, kept as Redocly has them.
+ */
+
+type RedoclyTypes = ReturnType<typeof normalizeTypes>;
+export type WalkType = RedoclyTypes[string];
+type PropTypeOrFunction = WalkType["properties"][string] | WalkType["additionalProperties"];
+/** The type of a property or array item, after Redocly called a type function. */
+export type PropType = Exclude<PropTypeOrFunction, (...args: never[]) => unknown>;
+
+/** Redocly's own placeholders: a node of no known type, and a scalar that is a `$ref`. */
+export const UNKNOWN_TYPE: WalkType = { name: "unknown", properties: {} };
+export const RESOLVABLE_SCALAR_TYPE: WalkType = { name: "scalar", properties: {} };
+
+/** Redocly's test for an anchor reference (`#name`), which waits for the whole document walk. */
+export const ANCHOR_REF = /^#[A-Za-z][A-Za-z0-9\-_:.]*$/;
+
+/** Redocly throws a plain Error with this message for a `$ref` chain that points back to itself. */
+export const REF_CYCLE_MESSAGE = "Self-referencing circular pointer";
+
+export interface RefStack {
+  readonly prev: RefStack | null;
+  readonly node: unknown;
+}
+
+export interface ResolvedRef {
+  readonly resolved: boolean;
+  readonly node?: unknown;
+  readonly document?: Document;
+  readonly nodePointer?: string;
+}
+
+export type Ref = { readonly $ref: string };
+
+export function isNamedType(type: PropType): type is WalkType {
+  return typeof (type as { name?: unknown } | null | undefined)?.name === "string";
+}
+
+export function joinPointer(base: string, key: string | number): string {
+  const start = base === "" ? "#/" : base;
+  return start.endsWith("/") ? `${start}${key}` : `${start}/${key}`;
+}
+
+export function escapePointer(fragment: string): string {
+  return fragment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+/** Redocly's `parseRef`: the document part (null for a local ref) and the unescaped segments. */
+export function parseRef(ref: string): { uri: string | null; pointer: string[] } {
+  const [uri = ""] = ref.split("#/");
+  return {
+    uri: (uri.endsWith("#") ? uri.slice(0, -1) : uri) || null,
+    pointer: parseRefPointer(ref),
+  };
+}
+
+export function hasRef(head: RefStack | null, node: unknown): boolean {
+  for (let entry = head; entry !== null; entry = entry.prev) {
+    if (entry.node === node) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function isExternalValue(node: object): node is { externalValue: string } {
+  return typeof (node as { externalValue?: unknown }).externalValue === "string";
+}
+
+/** Wait one macrotask, as Redocly does before it reads the anchors of a document. */
+export function nextTick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve));
+}
+
+/**
+ * The type Redocly gives one property value, and the value to walk (a `directResolveAs` string
+ * becomes a `$ref`). A value whose type has no name is not walked.
+ */
+export function propertyType(
+  type: WalkType,
+  name: string,
+  value: unknown,
+  specExtension: WalkType,
+): [PropType, unknown] {
+  // `properties[name]` also finds `Object.prototype` members, as in Redocly; for `valueOf` and the
+  // like the call below throws the TypeError that the loader turns into SCHEMA_KEY_UNSUPPORTED.
+  let declared: PropTypeOrFunction = type.properties[name];
+  if (declared === undefined) {
+    declared = type.additionalProperties;
+  }
+  let propType: PropType = typeof declared === "function" ? declared(value, name) : declared;
+  if (propType === undefined) {
+    propType = UNKNOWN_TYPE;
+  }
+  if (
+    type.extensionsPrefix &&
+    name.startsWith(type.extensionsPrefix) &&
+    propType === UNKNOWN_TYPE
+  ) {
+    return [specExtension, value];
+  }
+  if (!isNamedType(propType) && propType?.directResolveAs) {
+    return [propType.directResolveAs, { $ref: value }];
+  }
+  if (propType && !isNamedType(propType) && propType.resolvable !== false) {
+    return [RESOLVABLE_SCALAR_TYPE, value];
+  }
+  return [propType, value];
+}

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

@@ -1,9 +1,13 @@
 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 { refForbiddenError } from "./schema-load-errors.js";
 
-/** How the loader fetches remote documents: a time limit, and the host limit on redirects. */
+/**
+ * How the loader fetches remote documents: a time limit, the host limit and the configured headers
+ * checked on every redirect.
+ */
 
 type ResolveConfig = RedoclyConfig["resolve"];
 
@@ -11,10 +15,10 @@ type ResolveConfig = RedoclyConfig["resolve"];
 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.
+ * Redirects followed for one remote document. The loader follows them itself, so that each hop is
+ * checked; 20 is the limit of the Fetch standard, which fetch applied before.
  */
-export const MAX_CHECKED_REDIRECTS = 5;
+export const MAX_REDIRECTS = 20;
 
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 
@@ -51,33 +55,78 @@ function fetchWithTimeout(timeoutMs: number): RemoteFetch {
   };
 }
 
+/** 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;
+}
+
 /**
- * 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.
+ * Follow redirects one by one. Fetch drops only `Authorization`, `Cookie` and
+ * `Proxy-Authorization` on a redirect to another origin and keeps every other header (an
+ * `X-Api-Key`), so the configured headers are chosen for each hop's own URL instead, and a hop to
+ * a host that is not listed is refused before it is fetched. The first URL was checked by the
+ * resolver (or is the root document). Redocly passes only the configured headers in `init`, and
+ * it gets an empty list of them (`resolveConfigWithAccess`), so `init.headers` is replaced.
  */
 export function fetchWithCheckedRedirects(
   fetchImpl: RemoteFetch,
-  hosts: readonly string[],
+  policy: RedirectPolicy,
 ): 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] });
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+      if (hop > 0 && policy.hosts !== undefined && !isHostAllowed(url, policy.hosts)) {
+        throw refForbiddenError(url.href, {
+          reason: "host-not-allowed",
+          allowedHosts: [...policy.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 headers = await headersFor(url, policy.headers);
+      const response = await fetchImpl(url.href, { ...init, headers, 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}`);
+    throw new Error(`More than ${MAX_REDIRECTS} redirects loading ${input}`);
+  };
+}
+
+/** Bounds on the remote documents of one load (threat model T2, ADR-033). */
+export interface RemoteDocumentLimits {
+  /** 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;
+}
+
+/**
+ * At most `limit` calls of the fetch run at once; the others wait in order. A finished call hands
+ * its slot to the next waiting one.
+ */
+export function fetchWithConcurrencyLimit(fetchImpl: RemoteFetch, limit: number): RemoteFetch {
+  let running = 0;
+  const waiting: (() => void)[] = [];
+  return async (input, init) => {
+    if (running < limit) {
+      running += 1;
+    } else {
+      await new Promise<void>((resolve) => waiting.push(resolve));
+    }
+    try {
+      return await fetchImpl(input, init);
+    } finally {
+      const next = waiting.shift();
+      if (next === undefined) {
+        running -= 1;
+      } else {
+        next();
+      }
+    }
   };
 }
 
@@ -85,11 +134,14 @@ 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;
+  readonly maxParallelFetches: number;
 }
 
 /**
  * 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.
+ * kept and wrapped, so that each redirect is checked 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.
  */
 export function resolveConfigWithAccess(
   resolve: ResolveConfig,
@@ -98,7 +150,11 @@ export function resolveConfigWithAccess(
   // 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 } };
+  const checked = fetchWithCheckedRedirects(base, {
+    headers: resolve.http.headers,
+    hosts: options.access.remoteHosts,
+  });
+  // The limit is outside the redirects, so all hops of one document share one slot.
+  const customFetch = fetchWithConcurrencyLimit(checked, options.maxParallelFetches);
+  return { ...resolve, http: { ...resolve.http, headers: [], customFetch } };
 }

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

@@ -1,8 +1,11 @@
+import { assertNever } from "../../domain/assert-never.js";
 import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+import { redactUrlCredentials } from "../../domain/url-credentials.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.
+ * original messages, so Node API users who match on them keep working; URLs in them and in the
+ * details never show user info.
  */
 
 /** No source was given, or the source is empty. */
@@ -48,7 +51,7 @@ export function loadFailedError(absoluteRef: string, cause: unknown): OpenAPITyp
   return new OpenAPITypesafeError({
     code: ERROR_CODES.SCHEMA_LOAD_FAILED,
     message: causeMessage(cause),
-    details: { source: absoluteRef },
+    details: { source: redactUrlCredentials(absoluteRef) },
     cause,
   });
 }
@@ -62,7 +65,7 @@ export function parseFailedError(
   return new OpenAPITypesafeError({
     code: ERROR_CODES.SCHEMA_PARSE_FAILED,
     message: causeMessage(cause),
-    details: { format, source: absoluteRef },
+    details: { format, source: redactUrlCredentials(absoluteRef) },
     cause,
   });
 }
@@ -87,7 +90,7 @@ export function schemaInvalidError(problems: readonly string[]): OpenAPITypesafe
   return new OpenAPITypesafeError({
     code: ERROR_CODES.SCHEMA_INVALID,
     message: problems.at(-1) ?? "",
-    details: { problems: [...problems] },
+    details: { problems: problems.map(redactUrlCredentials) },
   });
 }
 
@@ -108,17 +111,36 @@ function hostListText(hosts: readonly string[]): string {
 /** 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[] };
+  | { 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 };
 
-/** A `$ref` is outside the local root, or its host is not allowed (threat model R1, R2). */
+function limitText(details: RefRefusalDetails): string {
+  switch (details.reason) {
+    case "outside-local-root":
+      return `it is outside the local $ref root ${details.localRoot}`;
+    case "host-not-allowed": {
+      const hosts = hostListText(details.allowedHosts);
+      return `its host is not in the allowed remote $ref hosts (${hosts})`;
+    }
+    case "local-ref-from-remote":
+      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`;
+    default:
+      return assertNever(details);
+  }
+}
+
+/**
+ * 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).
+ */
 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)})`;
+  const limit = limitText(details);
   return new OpenAPITypesafeError({
     code: ERROR_CODES.SCHEMA_REF_FORBIDDEN,
     message: `Refused to load ${ref}: ${limit}`,
-    details: { ref, ...details },
+    details: { ref: redactUrlCredentials(ref), ...details },
   });
 }

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

@@ -4,7 +4,7 @@ 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.
+ * (ADR-005 keeps 1.34). `toString` does not throw, and loads as it 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`.
@@ -21,6 +21,21 @@ export const UNSUPPORTED_KEYS: ReadonlySet<string> = new Set([
   "__lookupSetter__",
 ]);
 
+/**
+ * `constructor` finds `Object`, which returns the value it is called with. Redocly then takes the
+ * value for a node type when it has a string `name` (a security scheme, a header with a `name`),
+ * and fails reading the type's fields. Any other `constructor` key loads.
+ */
+const CONSTRUCTOR_KEY = "constructor";
+
+function isUnsupportedEntry(key: string, value: unknown): boolean {
+  if (UNSUPPORTED_KEYS.has(key)) {
+    return true;
+  }
+  const name = (value as { name?: unknown } | null | undefined)?.name;
+  return key === CONSTRUCTOR_KEY && typeof value === "object" && typeof name === "string";
+}
+
 /** Enough found keys in the message to act on; `details.keys` has all of them. */
 const KEYS_IN_MESSAGE = 5;
 
@@ -66,7 +81,7 @@ function unsupportedKeysOf(document: LoadedDocument): UnsupportedKey[] {
   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)) {
+      if (isUnsupportedEntry(key, child)) {
         found.push({ key, pointer, source: document.source });
       }
       enqueue(child, pointer);

package/src/adapters/terminal-logger/terminal-logger.ts

@@ -1,9 +1,11 @@
 import colors from "ansi-colors";
 import type { DebugGroup, Logger } from "../../application/ports/logger.js";
+import { redactUrlCredentials } from "../../domain/url-credentials.js";
 
 /**
  * The Logger port on a terminal, with the original output format: ` ⚠  ` warnings, ` ✘  `
- * errors, and `openapi-ts:<group>` debug lines filtered by `DEBUG` (ENGINEERING_PLAN 4.5).
+ * errors, and `openapi-ts:<group>` debug lines filtered by `DEBUG` (ENGINEERING_PLAN 4.5). No
+ * line shows the user info of a URL.
  */
 
 /** Where the lines go: `console` in production, a recording sink in tests. */
@@ -76,19 +78,21 @@ class TerminalLogger implements Logger {
       return;
     }
     const name = groupColor(this.#palette, group)(`openapi-ts:${group ?? "info"}`);
+    // The original wrote no space without a duration (`openapi-ts:lintIgnored …`).
     const time =
-      durationMs === undefined ? "" : this.#palette.green(` ${formatDuration(durationMs)} `);
-    this.#options.sink.debug(`  ${this.#palette.bold(name)}${time}${message}`);
+      durationMs === undefined ? " " : this.#palette.green(` ${formatDuration(durationMs)} `);
+    const text = redactUrlCredentials(message);
+    this.#options.sink.debug(`  ${this.#palette.bold(name)}${time}${text}`);
   }
 
   warn(message: string): void {
     if (!this.#options.silent) {
-      this.#options.sink.warn(this.#palette.yellow(` ⚠  ${message}`));
+      this.#options.sink.warn(this.#palette.yellow(` ⚠  ${redactUrlCredentials(message)}`));
     }
   }
 
   error(message: string): void {
-    this.#options.sink.error(this.#palette.red(` ✘  ${message}`));
+    this.#options.sink.error(this.#palette.red(` ✘  ${redactUrlCredentials(message)}`));
   }
 }