@fedify/vocab-runtime 2.4.0-pr.936.41 → 2.5.0-dev.2271

package/src/docloader.ts

@@ -1,6 +1,12 @@
 import { getLogger } from "@logtape/logtape";
 import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import metadata from "../deno.json" with { type: "json" };
+import {
+  BodyTooLargeError,
+  MAX_BODY_SIZE,
+  readBoundedBytes,
+  readBoundedText,
+} from "./body.ts";
 import preloadedContexts from "./contexts.ts";
 import { HttpHeaderLink } from "./link.ts";
 import {
@@ -14,6 +20,11 @@ import { UrlError, validatePublicUrl } from "./url.ts";
 const logger = getLogger(["fedify", "runtime", "docloader"]);
 const DEFAULT_MAX_REDIRECTION = 20;
 const MAX_HTML_SIZE = 1024 * 1024; // 1MB
+const MAX_ERROR_BODY_SIZE = 1024 * 1024; // 1MB
+const DEFAULT_TIMEOUT = 10_000; // 10 seconds
+// The maximum delay setTimeout() accepts; larger values fire immediately
+// on some runtimes:
+const MAX_TIMEOUT = 2_147_483_647;
 
 /**
  * A remote JSON-LD document and its context fetched by
@@ -46,6 +57,14 @@ export interface DocumentLoaderOptions {
    * @since 1.8.0
    */
   signal?: AbortSignal;
+
+  /**
+   * Whether to lower error-level logs for recoverable document loading
+   * failures to warning-level logs.  The loader still throws the error.
+   * @default `false`
+   * @since 2.4.0
+   */
+  suppressError?: boolean;
 }
 
 /**
@@ -96,6 +115,29 @@ export interface DocumentLoaderFactoryOptions {
    * @since 2.2.0
    */
   maxRedirection?: number;
+
+  /**
+   * The timeout in milliseconds for each call of the created document
+   * loader.  The timeout is shared by all the steps of a call, including
+   * URL validation, every HTTP redirect and alternate document link it
+   * follows, retries, and reading the response body; it does not restart
+   * for each of them.  It does not interrupt synchronous work such as
+   * parsing a document that has already been received.
+   *
+   * When a call times out, the loader throws a {@link FetchError} without
+   * a {@link FetchError.response}, whose `cause` is a `DOMException` named
+   * `"TimeoutError"`.  An `AbortSignal` passed through
+   * {@link DocumentLoaderOptions.signal} still cancels a call; in that case
+   * the loader throws the signal's reason as before.
+   *
+   * Fractional values are rounded up.  Set it to `null` to turn off the
+   * timeout.
+   * @default `10000` (10 seconds)
+   * @throws {RangeError} If the value is not a positive finite number or is
+   *                      greater than 2,147,483,647 (about 24.8 days).
+   * @since 2.4.0
+   */
+  timeout?: number | null;
 }
 
 /**
@@ -121,49 +163,59 @@ function createResponseMetadata(response: Response): Response {
   });
 }
 
-async function cancelResponseBody(response: Response): Promise<void> {
-  if (response.body != null) {
-    await response.body.cancel();
-  }
-}
+const NULL_BODY_STATUSES: ReadonlySet<number> = new Set([204, 205, 304]);
 
-async function readBoundedText(
+/**
+ * Reads the body of an error response while the document loader is still
+ * running, so that its timeout and `AbortSignal` also bound the read, and
+ * nothing reading {@link FetchError.response} later waits on the network.
+ * The body is kept byte for byte, unless it is too large or cannot be read;
+ * then only the status and headers are kept.  A response whose status
+ * the `Response` constructor does not accept (e.g., 999) is kept as a clone
+ * whose body has been read in full; if its body is too large or cannot be
+ * read, no response is kept at all.
+ */
+async function bufferErrorResponse(
   response: Response,
-  maxBytes: number,
-): Promise<{ text: string; size: number; tooLarge: boolean }> {
-  const contentLength = response.headers.get("Content-Length");
-  if (contentLength != null) {
-    const size = Number(contentLength);
-    if (size > maxBytes) {
-      await cancelResponseBody(response);
-      return { text: "", size, tooLarge: true };
+  url: string,
+  signal?: AbortSignal,
+): Promise<Response | undefined> {
+  if (response.status < 200 || response.status > 599) {
+    // Such a response cannot be rebuilt, so keep a clone instead, and read
+    // the original to the end so that the clone's body is buffered too:
+    const clone = response.clone();
+    try {
+      await readBoundedBytes(response, MAX_ERROR_BODY_SIZE, url);
+    } catch (error) {
+      await clone.body?.cancel().catch(() => {});
+      if (signal?.aborted) throw error;
+      logger.debug(
+        "Failed to read the error response body from {url}: {error}",
+        { url, error },
+      );
+      return undefined;
     }
+    return clone;
   }
-
-  if (response.body == null) return { text: "", size: 0, tooLarge: false };
-
-  const reader = response.body.getReader();
-  const decoder = new TextDecoder();
-  let text = "";
-  let size = 0;
+  if (response.body == null || NULL_BODY_STATUSES.has(response.status)) {
+    return createResponseMetadata(response);
+  }
+  let body: Uint8Array<ArrayBuffer>;
   try {
-    while (true) {
-      const result = await reader.read();
-      if (result.done) break;
-      const chunkSize = result.value.byteLength;
-      if (size + chunkSize > maxBytes) {
-        size += chunkSize;
-        await reader.cancel();
-        return { text: "", size, tooLarge: true };
-      }
-      size += chunkSize;
-      text += decoder.decode(result.value, { stream: true });
-    }
-    text += decoder.decode();
-    return { text, size, tooLarge: false };
-  } finally {
-    reader.releaseLock();
+    body = await readBoundedBytes(response, MAX_ERROR_BODY_SIZE, url);
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    logger.debug(
+      "Failed to read the error response body from {url}: {error}",
+      { url, error },
+    );
+    return createResponseMetadata(response);
   }
+  return new Response(body, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
 }
 
 /**
@@ -171,6 +223,7 @@ async function readBoundedText(
  * @param url The URL of the document to load.
  * @param response The response to get the document from.
  * @param fetch The function to fetch the document.
+ * @param options The options for loading the document.
  * @returns The loaded remote document.
  * @throws {FetchError} If the response is not OK.
  * @internal
@@ -182,22 +235,35 @@ export async function getRemoteDocument(
     url: string,
     options?: DocumentLoaderOptions,
   ) => Promise<RemoteDocument>,
+  options?: DocumentLoaderOptions,
 ): Promise<RemoteDocument> {
   const documentUrl = response.url === "" ? url : response.url;
   const docUrl = new URL(documentUrl);
   if (!response.ok) {
-    logger.error(
-      "Failed to fetch document: {status} {url} {headers}",
-      {
-        status: response.status,
-        url: documentUrl,
-        headers: Object.fromEntries(response.headers.entries()),
-      },
-    );
+    if (options?.suppressError) {
+      logger.warn(
+        "Failed to fetch document: {status} {url} {headers}",
+        {
+          status: response.status,
+          url: documentUrl,
+          headers: Object.fromEntries(response.headers.entries()),
+        },
+      );
+    } else {
+      logger.error(
+        "Failed to fetch document: {status} {url} {headers}",
+        {
+          status: response.status,
+          url: documentUrl,
+          headers: Object.fromEntries(response.headers.entries()),
+        },
+      );
+    }
+
     throw new FetchError(
       documentUrl,
       `HTTP ${response.status}: ${documentUrl}`,
-      response.clone(),
+      await bufferErrorResponse(response, documentUrl, options?.signal),
     );
   }
   const contentType = response.headers.get("Content-Type");
@@ -242,7 +308,7 @@ export async function getRemoteDocument(
             "Found alternate document: {alternateUrl} from {url}",
             { alternateUrl: altUri.href, url: documentUrl },
           );
-          return await fetch(altUri.href);
+          return await fetch(altUri.href, options);
         }
       }
     }
@@ -255,11 +321,14 @@ export async function getRemoteDocument(
       contentType?.startsWith("application/xhtml+xml;"))
   ) {
     const errorResponse = createResponseMetadata(response);
-    const html = await readBoundedText(response, MAX_HTML_SIZE);
-    if (html.tooLarge) {
+    let html: string;
+    try {
+      html = await readBoundedText(response, MAX_HTML_SIZE, documentUrl);
+    } catch (error) {
+      if (!(error instanceof BodyTooLargeError)) throw error;
       logger.warn(
         "HTML response too large, skipping alternate link discovery: {url}",
-        { url: documentUrl, size: html.size },
+        { url: documentUrl, maxBytes: MAX_HTML_SIZE },
       );
       throw new FetchError(
         documentUrl,
@@ -267,58 +336,58 @@ export async function getRemoteDocument(
           `(Content-Type: ${contentType})`,
         errorResponse,
       );
-    } else {
-      // Safe regex patterns without nested quantifiers to prevent ReDoS
-      // (CVE-2025-68475)
-      // Step 1: Extract <a ...> or <link ...> tags
-      const tagPattern = /<(a|link)\s+([^>]*?)\s*\/?>/gi;
-      // Step 2: Parse attributes
-      const attrPattern =
-        /([a-z][a-z:_-]*)=(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi;
-
-      let tagMatch: RegExpExecArray | null;
-      while ((tagMatch = tagPattern.exec(html.text)) !== null) {
-        const tagContent = tagMatch[2];
-        let attrMatch: RegExpExecArray | null;
-        const attribs: Record<string, string> = {};
+    }
+    // Safe regex patterns without nested quantifiers to prevent ReDoS
+    // (CVE-2025-68475)
+    // Step 1: Extract <a ...> or <link ...> tags
+    const tagPattern = /<(a|link)\s+([^>]*?)\s*\/?>/gi;
+    // Step 2: Parse attributes
+    const attrPattern = /([a-z][a-z:_-]*)=(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi;
 
-        // Reset regex state for attribute parsing
-        attrPattern.lastIndex = 0;
-        while ((attrMatch = attrPattern.exec(tagContent)) !== null) {
-          const key = attrMatch[1].toLowerCase();
-          const value = attrMatch[2] ?? attrMatch[3] ?? attrMatch[4] ?? "";
-          attribs[key] = value;
-        }
+    let tagMatch: RegExpExecArray | null;
+    while ((tagMatch = tagPattern.exec(html)) !== null) {
+      const tagContent = tagMatch[2];
+      let attrMatch: RegExpExecArray | null;
+      const attribs: Record<string, string> = {};
 
-        if (
-          attribs.rel === "alternate" && "type" in attribs && (
-            attribs.type === "application/activity+json" ||
-            attribs.type === "application/ld+json" ||
-            attribs.type.startsWith("application/ld+json;")
-          ) && "href" in attribs &&
-          new URL(attribs.href, docUrl).href !== docUrl.href
-        ) {
-          logger.debug(
-            "Found alternate document: {alternateUrl} from {url}",
-            { alternateUrl: attribs.href, url: documentUrl },
-          );
-          return await fetch(new URL(attribs.href, docUrl).href);
-        }
+      // Reset regex state for attribute parsing
+      attrPattern.lastIndex = 0;
+      while ((attrMatch = attrPattern.exec(tagContent)) !== null) {
+        const key = attrMatch[1].toLowerCase();
+        const value = attrMatch[2] ?? attrMatch[3] ?? attrMatch[4] ?? "";
+        attribs[key] = value;
       }
-      try {
-        document = JSON.parse(html.text);
-      } catch (error) {
-        if (!(error instanceof SyntaxError)) throw error;
-        throw new FetchError(
-          documentUrl,
-          `HTML document has no ActivityPub alternate link ` +
-            `(Content-Type: ${contentType})`,
-          errorResponse,
+
+      if (
+        attribs.rel === "alternate" && "type" in attribs && (
+          attribs.type === "application/activity+json" ||
+          attribs.type === "application/ld+json" ||
+          attribs.type.startsWith("application/ld+json;")
+        ) && "href" in attribs &&
+        new URL(attribs.href, docUrl).href !== docUrl.href
+      ) {
+        logger.debug(
+          "Found alternate document: {alternateUrl} from {url}",
+          { alternateUrl: attribs.href, url: documentUrl },
         );
+        return await fetch(new URL(attribs.href, docUrl).href, options);
       }
     }
+    try {
+      document = JSON.parse(html);
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw error;
+      throw new FetchError(
+        documentUrl,
+        `HTML document has no ActivityPub alternate link ` +
+          `(Content-Type: ${contentType})`,
+        errorResponse,
+      );
+    }
   } else {
-    document = await response.json();
+    document = JSON.parse(
+      await readBoundedText(response, MAX_BODY_SIZE, documentUrl),
+    );
   }
   logger.debug(
     "Fetched document: {status} {url} {headers}",
@@ -331,6 +400,104 @@ export async function getRemoteDocument(
   return { contextUrl, document, documentUrl };
 }
 
+/**
+ * Resolves {@link DocumentLoaderFactoryOptions.timeout} into milliseconds.
+ * @param timeout The timeout option.  `undefined` means the default timeout,
+ *                and `null` means no timeout.
+ * @returns The timeout in milliseconds, or `null` if it is turned off.
+ * @throws {RangeError} If the timeout is invalid.
+ * @internal
+ */
+export function resolveDocumentLoaderTimeout(
+  timeout: number | null | undefined,
+): number | null {
+  if (timeout === undefined) return DEFAULT_TIMEOUT;
+  if (timeout === null) return null;
+  if (
+    typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0
+  ) {
+    throw new RangeError(
+      `The document loader timeout must be a positive finite number of ` +
+        `milliseconds, but got ${String(timeout)}.`,
+    );
+  }
+  const ms = Math.ceil(timeout);
+  if (ms > MAX_TIMEOUT) {
+    throw new RangeError(
+      `The document loader timeout must not be greater than ${MAX_TIMEOUT} ` +
+        `milliseconds, but got ${timeout}.`,
+    );
+  }
+  return ms;
+}
+
+/**
+ * Bounds each call of the given document loader by the given timeout.
+ * The timeout is combined with the caller's `signal`, and the combined
+ * signal is passed to the loader.  The call settles no later than the
+ * timeout even if the loader is stuck in a step that cannot be aborted,
+ * e.g., a DNS lookup.
+ *
+ * A timed-out call throws a {@link FetchError} without a response, whose
+ * `cause` is a `DOMException` named `"TimeoutError"`.  If the caller's
+ * signal is aborted, its reason is thrown instead.
+ * @param loader The document loader to bound.
+ * @param timeout The timeout in milliseconds, or `null` for no timeout.
+ *                It is assumed to have been resolved by
+ *                {@link resolveDocumentLoaderTimeout}.
+ * @returns The bounded document loader.
+ * @internal
+ */
+export function withDocumentLoaderTimeout(
+  loader: DocumentLoader,
+  timeout: number | null,
+): DocumentLoader {
+  if (timeout == null) return loader;
+  return async (url, options) => {
+    const callerSignal = options?.signal;
+    callerSignal?.throwIfAborted();
+    const controller = new AbortController();
+    const timeoutReason = new DOMException(
+      `The document loader timed out after ${timeout} ms.`,
+      "TimeoutError",
+    );
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort(timeoutReason);
+    }, timeout);
+    const onCallerAbort = () => controller.abort(callerSignal?.reason);
+    callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+    let onAbort: (() => void) | undefined;
+    const aborted = new Promise<never>((_, reject) => {
+      onAbort = () => reject(controller.signal.reason);
+      controller.signal.addEventListener("abort", onAbort, { once: true });
+    });
+    const loading = loader(url, { ...options, signal: controller.signal });
+    // If the abort wins the race, the loader's late rejection is ignored:
+    loading.catch(() => {});
+    try {
+      return await Promise.race([loading, aborted]);
+    } catch (error) {
+      if (callerSignal?.aborted) throw callerSignal.reason;
+      if (!timedOut) throw error;
+      logger[options?.suppressError ? "warn" : "error"](
+        "Timed out after {timeout} ms while fetching document: {url}",
+        { timeout, url },
+      );
+      const fetchError = new FetchError(url, `Timed out after ${timeout} ms`);
+      fetchError.cause = timeoutReason;
+      throw fetchError;
+    } finally {
+      clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+      if (onAbort != null) {
+        controller.signal.removeEventListener("abort", onAbort);
+      }
+    }
+  };
+}
+
 /**
  * Options for {@link getDocumentLoader}.
  * @since 1.3.0
@@ -344,6 +511,10 @@ export interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
 
 /**
  * Creates a JSON-LD document loader that utilizes the browser's `fetch` API.
+ * At most 20 HTTP redirects and alternate document links are followed in total
+ * per call.  Revisiting a URL within that chain throws a {@link FetchError}.
+ * Each call times out after 10 seconds by default; see
+ * {@link DocumentLoaderFactoryOptions.timeout}.
  *
  * The created loader preloads the below frequently used contexts by default
  * (unless `options.skipPreloadedContexts` is set to `true`):
@@ -353,8 +524,10 @@ export interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
  * - <https://w3id.org/security/data-integrity/v1>
  * - <https://w3id.org/security/data-integrity/v2>
  * - <https://www.w3.org/ns/did/v1>
+ * - <https://www.w3.org/ns/cid/v1>
  * - <https://w3id.org/security/multikey/v1>
  * - <https://w3id.org/fep/ef61>
+ * - <https://w3id.org/fep/7aa9>
  * - <https://purl.archive.org/socialweb/webfinger>
  * - <http://schema.org/>
  * @param options Options for the document loader.
@@ -362,9 +535,15 @@ export interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
  * @since 1.3.0
  */
 export function getDocumentLoader(
-  { allowPrivateAddress, maxRedirection, skipPreloadedContexts, userAgent }:
-    GetDocumentLoaderOptions = {},
+  {
+    allowPrivateAddress,
+    maxRedirection,
+    skipPreloadedContexts,
+    timeout,
+    userAgent,
+  }: GetDocumentLoaderOptions = {},
 ): DocumentLoader {
+  const resolvedTimeout = resolveDocumentLoaderTimeout(timeout);
   const tracerProvider = trace.getTracerProvider();
   const tracer = tracerProvider.getTracer(metadata.name, metadata.version);
   const maximumRedirection = maxRedirection ?? DEFAULT_MAX_REDIRECTION;
@@ -390,13 +569,26 @@ export function getDocumentLoader(
         await validatePublicUrl(currentUrl);
       } catch (error) {
         if (error instanceof UrlError) {
-          logger.error("Disallowed private URL: {url}", {
-            url: currentUrl,
-            error,
-          });
+          if (error.reason === "dns") {
+            logger.debug("DNS lookup failed for {url}", {
+              url: currentUrl,
+              error,
+            });
+          } else {
+            logger[options?.suppressError ? "warn" : "error"](
+              "Disallowed private URL: {url}",
+              {
+                url: currentUrl,
+                error,
+              },
+            );
+          }
         }
         throw error;
       }
+      // The DNS lookup cannot be aborted, so do not go on if the call was
+      // aborted or timed out in the meantime:
+      options?.signal?.throwIfAborted();
     }
     visited.add(currentUrl);
 
@@ -427,7 +619,7 @@ export function getDocumentLoader(
             response.headers.has("Location")
           ) {
             if (redirected >= maximumRedirection) {
-              logger.error(
+              logger[options?.suppressError ? "warn" : "error"](
                 "Too many redirections ({redirections}) while fetching document.",
                 { redirections: redirected + 1, url: currentUrl },
               );
@@ -442,7 +634,7 @@ export function getDocumentLoader(
             ).href;
             span.setAttribute("http.redirect.url", redirectUrl);
             if (visited.has(redirectUrl)) {
-              logger.error(
+              logger[options?.suppressError ? "warn" : "error"](
                 "Detected a redirect loop while fetching document: {url} -> " +
                   "{redirectUrl}",
                 { url: currentUrl, redirectUrl },
@@ -455,7 +647,27 @@ export function getDocumentLoader(
             return await load(redirectUrl, options, redirected + 1, visited);
           }
 
-          const result = await getRemoteDocument(currentUrl, response, load);
+          const result = await getRemoteDocument(
+            currentUrl,
+            response,
+            async (alternateUrl) => {
+              options?.signal?.throwIfAborted();
+              if (redirected >= DEFAULT_MAX_REDIRECTION) {
+                throw new FetchError(
+                  currentUrl,
+                  `Too many redirections (${redirected + 1})`,
+                );
+              }
+              if (visited.has(alternateUrl)) {
+                throw new FetchError(
+                  currentUrl,
+                  `Redirect loop detected: ${alternateUrl}`,
+                );
+              }
+              return await load(alternateUrl, options, redirected + 1, visited);
+            },
+            options,
+          );
           span.setAttribute("docloader.document_url", result.documentUrl);
           if (result.contextUrl != null) {
             span.setAttribute("docloader.context_url", result.contextUrl);
@@ -474,5 +686,8 @@ export function getDocumentLoader(
       },
     );
   }
-  return load;
+  return withDocumentLoaderTimeout(
+    (url, options) => load(url, options),
+    resolvedTimeout,
+  );
 }

package/src/internal/jsonld-cache.ts

@@ -1,9 +1,105 @@
 import type { DocumentLoader } from "../docloader.ts";
 import jsonld from "../jsonld.ts";
-import { formatIri, haveSameFe34Origin, haveSameIriOrigin } from "../url.ts";
+import {
+  formatIri,
+  fromCompatibleEf61Id,
+  getFe34Origin,
+  haveSameFe34Origin,
+  haveSameIriOrigin,
+  parseIri,
+} from "../url.ts";
+
+/**
+ * Reads expanded gateways, including an unmapped term on portable actors.
+ * The original values and their order are preserved for URL validation by
+ * the caller.  An explicitly mapped FEP-ef61 property always takes precedence.
+ * @internal Used by generated vocabulary classes and portable proof checks.
+ */
+export function getPortableActorGateways(
+  node: Record<string, unknown>,
+  allowUnmapped = true,
+): unknown[] | undefined {
+  const property = "https://w3id.org/fep/ef61/gateways";
+  if (globalThis.Object.hasOwn(node, property)) {
+    return Array.isArray(node[property]) ? node[property] : undefined;
+  }
+  if (
+    !allowUnmapped || typeof node["@id"] !== "string" ||
+    !("http://www.w3.org/ns/ldp#inbox" in node) ||
+    !("https://www.w3.org/ns/activitystreams#outbox" in node)
+  ) return undefined;
+  try {
+    const id = fromCompatibleEf61Id(node["@id"]) ?? node["@id"];
+    if (!getFe34Origin(parseIri(id)).startsWith("did:")) return undefined;
+  } catch (error) {
+    if (error instanceof TypeError) return undefined;
+    throw error;
+  }
+  return Array.isArray(node["_:gateways"]) ? node["_:gateways"] : undefined;
+}
 
 const noJsonLdContext = Symbol("noJsonLdContext");
 
+const documentLoaderWrappers = new WeakMap<
+  DocumentLoader,
+  { readonly base: DocumentLoader; released: boolean }
+>();
+
+/**
+ * Registers a loader wrapper with the shared released-wrapper registry.
+ * Both suppression and snapshot wrappers must use this registry so mixed
+ * chains can be unwrapped.  The caller updates the state on release.
+ * @internal Not a public API.
+ */
+export function registerDocumentLoaderWrapper(
+  loader: DocumentLoader,
+  state: { readonly base: DocumentLoader; released: boolean },
+): void {
+  documentLoaderWrappers.set(loader, state);
+}
+
+/**
+ * Removes released loader wrappers, stopping at the first active wrapper.
+ * Active wrappers retain their operation's suppression or snapshot cache.
+ * @internal Not a public API.
+ */
+export function unwrapReleasedDocumentLoader(
+  base: DocumentLoader,
+): DocumentLoader {
+  for (
+    let state = documentLoaderWrappers.get(base);
+    state?.released;
+    state = documentLoaderWrappers.get(base)
+  ) {
+    base = state.base;
+  }
+  return base;
+}
+
+/**
+ * Lowers context loading failure logs for one accessor operation.  Parsed
+ * objects retain the loader, so release it before returning to the caller.
+ * Released wrappers are unwrapped to avoid accumulating loader chains.
+ * @internal Used by generated vocabulary accessors; not a public API.
+ */
+export function createScopedContextLoader(
+  base: DocumentLoader,
+  suppressError?: boolean,
+): { loader: DocumentLoader; release: () => void } {
+  base = unwrapReleasedDocumentLoader(base);
+  if (!suppressError) return { loader: base, release: () => {} };
+  const state = { base, released: false };
+  const loader: DocumentLoader = (url, options) =>
+    base(url, state.released ? options : { ...options, suppressError: true });
+  registerDocumentLoaderWrapper(loader, state);
+  return {
+    loader,
+    release: () => {
+      state.released = true;
+    },
+  };
+}
+
 /**
  * Options for deciding whether two IRIs should be treated as same-origin.
  *