@fedify/vocab-runtime 2.4.0-dev.2193 → 2.4.0-dev.2212

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.2193+402149b5",
+  "version": "2.4.0-dev.2212+26ce9858",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts",

package/dist/mod.cjs

@@ -16,7 +16,7 @@ let _multiformats_base_x = require("@multiformats/base-x");
 _multiformats_base_x = require_rolldown_runtime.__toESM(_multiformats_base_x, 1);
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.2193+402149b5";
+var version = "2.4.0-dev.2212+26ce9858";
 //#endregion
 //#region src/request.ts
 /**
@@ -1581,6 +1581,149 @@ LanguageString.prototype[Symbol.for("nodejs.util.inspect.custom")] = function(_d
 	return `<${this.locale.baseName}> ${inspect(this.toString(), options)}`;
 };
 //#endregion
+//#region src/portable-media.ts
+function resolveTimeout(value, fallback) {
+	if (value === null) return null;
+	const result = value ?? fallback;
+	if (!Number.isFinite(result) || result <= 0 || result > 2147483647) throw new RangeError("A media timeout must be a positive finite number of milliseconds.");
+	return Math.ceil(result);
+}
+async function withTimeout(operation, parent, timeout) {
+	parent?.throwIfAborted();
+	const controller = new AbortController();
+	const onParentAbort = () => controller.abort(parent?.reason);
+	parent?.addEventListener("abort", onParentAbort, { once: true });
+	let timer;
+	if (timeout != null) timer = setTimeout(() => controller.abort(new DOMException(`Media retrieval timed out after ${timeout} ms.`, "TimeoutError")), timeout);
+	let onAbort;
+	const aborted = new Promise((_, reject) => {
+		onAbort = () => reject(controller.signal.reason);
+		controller.signal.addEventListener("abort", onAbort, { once: true });
+	});
+	try {
+		return await Promise.race([operation(controller.signal), aborted]);
+	} finally {
+		if (timer != null) clearTimeout(timer);
+		parent?.removeEventListener("abort", onParentAbort);
+		if (onAbort != null) controller.signal.removeEventListener("abort", onAbort);
+	}
+}
+function mediaTarget(media) {
+	if (typeof media === "string" || media instanceof URL) return {
+		url: media.toString(),
+		digestMultibase: void 0
+	};
+	const target = media.href ?? media.url;
+	const url = target instanceof URL ? target.href : target != null && typeof target === "object" && "href" in target ? target.href?.href : void 0;
+	if (url == null) throw new TypeError("Portable media has no URL or href.");
+	const linkDigest = target != null && !(target instanceof URL) && typeof target === "object" && "digestMultibase" in target ? target.digestMultibase : void 0;
+	if (media.digestMultibase != null && linkDigest != null) {
+		const outer = parseDigestMultibase(media.digestMultibase).digest;
+		const inner = parseDigestMultibase(linkDigest).digest;
+		if (outer.some((byte, i) => byte !== inner[i])) throw new TypeError("Media and linked resource digests disagree.");
+	}
+	return {
+		url,
+		digestMultibase: media.digestMultibase ?? linkDigest
+	};
+}
+async function fetchVerified(url, digestMultibase, options, signal, maxBytes) {
+	const visited = /* @__PURE__ */ new Set();
+	for (let redirects = 0; redirects <= 20; redirects++) {
+		signal.throwIfAborted();
+		if (url.username !== "" || url.password !== "") throw new TypeError("Media URLs must not contain credentials.");
+		if (!options.allowPrivateAddress) await require_url.validatePublicUrl(url.href);
+		else if (url.protocol !== "http:" && url.protocol !== "https:") throw new TypeError("Media URLs must use HTTP(S).");
+		if (visited.has(url.href)) throw new TypeError("Media redirect loop.");
+		visited.add(url.href);
+		const response = await fetch(url, {
+			method: "GET",
+			headers: {
+				Accept: "*/*",
+				"User-Agent": typeof options.userAgent === "string" ? options.userAgent : getUserAgent(options.userAgent)
+			},
+			redirect: "manual",
+			signal
+		});
+		if ([
+			301,
+			302,
+			303,
+			307,
+			308
+		].includes(response.status)) {
+			const location = response.headers.get("Location");
+			response.body?.cancel().catch(() => {});
+			if (location == null || redirects === 20) throw new TypeError("Invalid or excessive media redirects.");
+			url = new URL(location, url);
+			continue;
+		}
+		if (response.status !== 200) {
+			response.body?.cancel().catch(() => {});
+			throw new Error(`Media request failed with HTTP ${response.status}.`);
+		}
+		const bytes = await readBoundedBytes(response, maxBytes, url);
+		signal.throwIfAborted();
+		if (!await verifyDigestMultibase(bytes, digestMultibase)) throw new Error("Portable media digest does not match.");
+		const headers = new Headers();
+		const contentType = response.headers.get("Content-Type");
+		if (contentType != null) headers.set("Content-Type", contentType);
+		return new Response(bytes, { headers });
+	}
+	throw new TypeError("Too many media redirects.");
+}
+/**
+* Fetches a portable object's external media and returns it only after its
+* SHA-256 `digestMultibase` has been verified.  `hl:` resources are tried at
+* the supplied gateways in order.  The result contains verified body bytes;
+* its `Content-Type` is unverified metadata supplied by the server.
+*
+* @param media A Link, Image, Document, or URL with an external resource.
+* @param options Retrieval, integrity, and network policy options.
+* @returns A response containing only verified bytes.
+* @throws {TypeError} If the media reference or digest is invalid.
+* @throws {Error} If no source supplies a matching bounded resource.
+* @since 2.4.0
+*/
+async function fetchPortableMedia(media, options = {}) {
+	const { url, digestMultibase: propertyDigest } = mediaTarget(media);
+	const digestMultibase = propertyDigest ?? options.digestMultibase;
+	if (digestMultibase == null) throw new TypeError("Portable media requires digestMultibase.");
+	const expected = parseDigestMultibase(digestMultibase).digest;
+	const maxBytes = options.maxBytes ?? 16777216;
+	if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) throw new RangeError("The media size limit must be a positive safe integer.");
+	const timeout = resolveTimeout(options.timeout, 1e4);
+	const gatewayTimeout = resolveTimeout(options.gatewayTimeout, 3e3);
+	let targets;
+	let hashlink = false;
+	if (/^hl:/i.test(url)) {
+		hashlink = true;
+		const hashDigest = parseDigestMultibase(parseHashlink(url).digestMultibase).digest;
+		if (expected.some((byte, i) => byte !== hashDigest[i])) throw new TypeError("Hashlink and digestMultibase disagree.");
+		const gateways = [...new Set([...options.gateways ?? []].map((gateway) => require_url.parseGatewayUrl(gateway.toString()).origin))];
+		if (gateways.length === 0) throw new TypeError("Hashlink media requires at least one gateway.");
+		targets = gateways.map((gateway) => new URL(`/.well-known/apgateway/${url}`, gateway));
+	} else {
+		const target = new URL(url);
+		if (target.protocol !== "http:" && target.protocol !== "https:") throw new TypeError("Portable media URLs must use HTTP(S) or hl:.");
+		targets = [target];
+	}
+	return await withTimeout(async (signal) => {
+		let lastError;
+		for (const target of targets) {
+			signal.throwIfAborted();
+			try {
+				return await withTimeout((attemptSignal) => fetchVerified(target, digestMultibase, options, attemptSignal, maxBytes), signal, hashlink ? gatewayTimeout : null);
+			} catch (error) {
+				signal.throwIfAborted();
+				if (!hashlink) throw error;
+				lastError = error;
+			}
+		}
+		throw new Error("No gateway returned verified portable media.", { cause: lastError });
+	}, options.signal, timeout);
+}
+//#endregion
 exports.FetchError = FetchError;
 exports.LanguageString = LanguageString;
 exports.UrlError = require_url.UrlError;
@@ -1597,6 +1740,7 @@ exports.expandIPv6Address = require_url.expandIPv6Address;
 exports.exportDidKey = exportDidKey;
 exports.exportMultibaseKey = exportMultibaseKey;
 exports.exportSpki = exportSpki;
+exports.fetchPortableMedia = fetchPortableMedia;
 exports.formatIri = require_url.formatIri;
 exports.fromCompatibleEf61Id = require_url.fromCompatibleEf61Id;
 exports.getDocumentLoader = getDocumentLoader;

package/dist/mod.d.cts

@@ -312,6 +312,50 @@ declare class LanguageString extends String {
   constructor(value: string, language: Intl.Locale | string);
 }
 //#endregion
+//#region src/portable-media.d.ts
+/** A link or document with an external resource and its integrity digest. */
+interface PortableMedia {
+  readonly href?: URL | null;
+  readonly url?: URL | {
+    readonly href: URL | null;
+    readonly digestMultibase?: string | null;
+  } | null;
+  readonly digestMultibase?: string | null;
+}
+/** Options for {@link fetchPortableMedia}. */
+interface FetchPortableMediaOptions {
+  /** Ordered FEP-ef61 gateway origins used for `hl:` resources. */
+  readonly gateways?: Iterable<string | URL>;
+  /** Expected digest when the first argument is a URL or string. */
+  readonly digestMultibase?: string;
+  /** Maximum decoded response size in bytes.  Defaults to 16 MiB. */
+  readonly maxBytes?: number;
+  /** Whether private network addresses may be fetched.  Defaults to `false`. */
+  readonly allowPrivateAddress?: boolean;
+  /** The HTTP `User-Agent` value or its components. */
+  readonly userAgent?: string | GetUserAgentOptions;
+  /** Cancels the entire retrieval and all gateway attempts. */
+  readonly signal?: AbortSignal;
+  /** Overall timeout in milliseconds.  Defaults to 10 seconds; `null` disables it. */
+  readonly timeout?: number | null;
+  /** Timeout per gateway in milliseconds.  Defaults to 3 seconds. */
+  readonly gatewayTimeout?: number | null;
+}
+/**
+* Fetches a portable object's external media and returns it only after its
+* SHA-256 `digestMultibase` has been verified.  `hl:` resources are tried at
+* the supplied gateways in order.  The result contains verified body bytes;
+* its `Content-Type` is unverified metadata supplied by the server.
+*
+* @param media A Link, Image, Document, or URL with an external resource.
+* @param options Retrieval, integrity, and network policy options.
+* @returns A response containing only verified bytes.
+* @throws {TypeError} If the media reference or digest is invalid.
+* @throws {Error} If no source supplies a matching bounded resource.
+* @since 2.4.0
+*/
+declare function fetchPortableMedia(media: string | URL | PortableMedia, options?: FetchPortableMediaOptions): Promise<Response>;
+//#endregion
 //#region src/multibase/types.d.ts
 type BaseCode = "\x00" | "0" | "7" | "9" | "f" | "F" | "v" | "V" | "t" | "T" | "b" | "B" | "c" | "C" | "h" | "k" | "K" | "z" | "Z" | "m" | "M" | "u" | "U";
 /**
@@ -571,4 +615,4 @@ declare function isValidPublicIPv4Address(address: string): boolean;
 declare function isValidPublicIPv6Address(address: string): boolean;
 declare function expandIPv6Address(address: string): string;
 //#endregion
-export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout };
+export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type FetchPortableMediaOptions, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableMedia, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout };

package/dist/mod.d.ts

@@ -311,6 +311,50 @@ declare class LanguageString extends String {
   constructor(value: string, language: Intl.Locale | string);
 }
 //#endregion
+//#region src/portable-media.d.ts
+/** A link or document with an external resource and its integrity digest. */
+interface PortableMedia {
+  readonly href?: URL | null;
+  readonly url?: URL | {
+    readonly href: URL | null;
+    readonly digestMultibase?: string | null;
+  } | null;
+  readonly digestMultibase?: string | null;
+}
+/** Options for {@link fetchPortableMedia}. */
+interface FetchPortableMediaOptions {
+  /** Ordered FEP-ef61 gateway origins used for `hl:` resources. */
+  readonly gateways?: Iterable<string | URL>;
+  /** Expected digest when the first argument is a URL or string. */
+  readonly digestMultibase?: string;
+  /** Maximum decoded response size in bytes.  Defaults to 16 MiB. */
+  readonly maxBytes?: number;
+  /** Whether private network addresses may be fetched.  Defaults to `false`. */
+  readonly allowPrivateAddress?: boolean;
+  /** The HTTP `User-Agent` value or its components. */
+  readonly userAgent?: string | GetUserAgentOptions;
+  /** Cancels the entire retrieval and all gateway attempts. */
+  readonly signal?: AbortSignal;
+  /** Overall timeout in milliseconds.  Defaults to 10 seconds; `null` disables it. */
+  readonly timeout?: number | null;
+  /** Timeout per gateway in milliseconds.  Defaults to 3 seconds. */
+  readonly gatewayTimeout?: number | null;
+}
+/**
+* Fetches a portable object's external media and returns it only after its
+* SHA-256 `digestMultibase` has been verified.  `hl:` resources are tried at
+* the supplied gateways in order.  The result contains verified body bytes;
+* its `Content-Type` is unverified metadata supplied by the server.
+*
+* @param media A Link, Image, Document, or URL with an external resource.
+* @param options Retrieval, integrity, and network policy options.
+* @returns A response containing only verified bytes.
+* @throws {TypeError} If the media reference or digest is invalid.
+* @throws {Error} If no source supplies a matching bounded resource.
+* @since 2.4.0
+*/
+declare function fetchPortableMedia(media: string | URL | PortableMedia, options?: FetchPortableMediaOptions): Promise<Response>;
+//#endregion
 //#region src/multibase/types.d.ts
 type BaseCode = "\x00" | "0" | "7" | "9" | "f" | "F" | "v" | "V" | "t" | "T" | "b" | "B" | "c" | "C" | "h" | "k" | "K" | "z" | "Z" | "m" | "M" | "u" | "U";
 /**
@@ -570,4 +614,4 @@ declare function isValidPublicIPv4Address(address: string): boolean;
 declare function isValidPublicIPv6Address(address: string): boolean;
 declare function expandIPv6Address(address: string): string;
 //#endregion
-export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout };
+export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type FetchPortableMediaOptions, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableMedia, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout };

package/dist/mod.js

@@ -12,7 +12,7 @@ import { PublicKeyInfo } from "pkijs";
 import baseX from "@multiformats/base-x";
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.2193+402149b5";
+var version = "2.4.0-dev.2212+26ce9858";
 //#endregion
 //#region src/request.ts
 /**
@@ -1577,4 +1577,147 @@ LanguageString.prototype[Symbol.for("nodejs.util.inspect.custom")] = function(_d
 	return `<${this.locale.baseName}> ${inspect(this.toString(), options)}`;
 };
 //#endregion
-export { FetchError, LanguageString, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout };
+//#region src/portable-media.ts
+function resolveTimeout(value, fallback) {
+	if (value === null) return null;
+	const result = value ?? fallback;
+	if (!Number.isFinite(result) || result <= 0 || result > 2147483647) throw new RangeError("A media timeout must be a positive finite number of milliseconds.");
+	return Math.ceil(result);
+}
+async function withTimeout(operation, parent, timeout) {
+	parent?.throwIfAborted();
+	const controller = new AbortController();
+	const onParentAbort = () => controller.abort(parent?.reason);
+	parent?.addEventListener("abort", onParentAbort, { once: true });
+	let timer;
+	if (timeout != null) timer = setTimeout(() => controller.abort(new DOMException(`Media retrieval timed out after ${timeout} ms.`, "TimeoutError")), timeout);
+	let onAbort;
+	const aborted = new Promise((_, reject) => {
+		onAbort = () => reject(controller.signal.reason);
+		controller.signal.addEventListener("abort", onAbort, { once: true });
+	});
+	try {
+		return await Promise.race([operation(controller.signal), aborted]);
+	} finally {
+		if (timer != null) clearTimeout(timer);
+		parent?.removeEventListener("abort", onParentAbort);
+		if (onAbort != null) controller.signal.removeEventListener("abort", onAbort);
+	}
+}
+function mediaTarget(media) {
+	if (typeof media === "string" || media instanceof URL) return {
+		url: media.toString(),
+		digestMultibase: void 0
+	};
+	const target = media.href ?? media.url;
+	const url = target instanceof URL ? target.href : target != null && typeof target === "object" && "href" in target ? target.href?.href : void 0;
+	if (url == null) throw new TypeError("Portable media has no URL or href.");
+	const linkDigest = target != null && !(target instanceof URL) && typeof target === "object" && "digestMultibase" in target ? target.digestMultibase : void 0;
+	if (media.digestMultibase != null && linkDigest != null) {
+		const outer = parseDigestMultibase(media.digestMultibase).digest;
+		const inner = parseDigestMultibase(linkDigest).digest;
+		if (outer.some((byte, i) => byte !== inner[i])) throw new TypeError("Media and linked resource digests disagree.");
+	}
+	return {
+		url,
+		digestMultibase: media.digestMultibase ?? linkDigest
+	};
+}
+async function fetchVerified(url, digestMultibase, options, signal, maxBytes) {
+	const visited = /* @__PURE__ */ new Set();
+	for (let redirects = 0; redirects <= 20; redirects++) {
+		signal.throwIfAborted();
+		if (url.username !== "" || url.password !== "") throw new TypeError("Media URLs must not contain credentials.");
+		if (!options.allowPrivateAddress) await validatePublicUrl(url.href);
+		else if (url.protocol !== "http:" && url.protocol !== "https:") throw new TypeError("Media URLs must use HTTP(S).");
+		if (visited.has(url.href)) throw new TypeError("Media redirect loop.");
+		visited.add(url.href);
+		const response = await fetch(url, {
+			method: "GET",
+			headers: {
+				Accept: "*/*",
+				"User-Agent": typeof options.userAgent === "string" ? options.userAgent : getUserAgent(options.userAgent)
+			},
+			redirect: "manual",
+			signal
+		});
+		if ([
+			301,
+			302,
+			303,
+			307,
+			308
+		].includes(response.status)) {
+			const location = response.headers.get("Location");
+			response.body?.cancel().catch(() => {});
+			if (location == null || redirects === 20) throw new TypeError("Invalid or excessive media redirects.");
+			url = new URL(location, url);
+			continue;
+		}
+		if (response.status !== 200) {
+			response.body?.cancel().catch(() => {});
+			throw new Error(`Media request failed with HTTP ${response.status}.`);
+		}
+		const bytes = await readBoundedBytes(response, maxBytes, url);
+		signal.throwIfAborted();
+		if (!await verifyDigestMultibase(bytes, digestMultibase)) throw new Error("Portable media digest does not match.");
+		const headers = new Headers();
+		const contentType = response.headers.get("Content-Type");
+		if (contentType != null) headers.set("Content-Type", contentType);
+		return new Response(bytes, { headers });
+	}
+	throw new TypeError("Too many media redirects.");
+}
+/**
+* Fetches a portable object's external media and returns it only after its
+* SHA-256 `digestMultibase` has been verified.  `hl:` resources are tried at
+* the supplied gateways in order.  The result contains verified body bytes;
+* its `Content-Type` is unverified metadata supplied by the server.
+*
+* @param media A Link, Image, Document, or URL with an external resource.
+* @param options Retrieval, integrity, and network policy options.
+* @returns A response containing only verified bytes.
+* @throws {TypeError} If the media reference or digest is invalid.
+* @throws {Error} If no source supplies a matching bounded resource.
+* @since 2.4.0
+*/
+async function fetchPortableMedia(media, options = {}) {
+	const { url, digestMultibase: propertyDigest } = mediaTarget(media);
+	const digestMultibase = propertyDigest ?? options.digestMultibase;
+	if (digestMultibase == null) throw new TypeError("Portable media requires digestMultibase.");
+	const expected = parseDigestMultibase(digestMultibase).digest;
+	const maxBytes = options.maxBytes ?? 16777216;
+	if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) throw new RangeError("The media size limit must be a positive safe integer.");
+	const timeout = resolveTimeout(options.timeout, 1e4);
+	const gatewayTimeout = resolveTimeout(options.gatewayTimeout, 3e3);
+	let targets;
+	let hashlink = false;
+	if (/^hl:/i.test(url)) {
+		hashlink = true;
+		const hashDigest = parseDigestMultibase(parseHashlink(url).digestMultibase).digest;
+		if (expected.some((byte, i) => byte !== hashDigest[i])) throw new TypeError("Hashlink and digestMultibase disagree.");
+		const gateways = [...new Set([...options.gateways ?? []].map((gateway) => parseGatewayUrl(gateway.toString()).origin))];
+		if (gateways.length === 0) throw new TypeError("Hashlink media requires at least one gateway.");
+		targets = gateways.map((gateway) => new URL(`/.well-known/apgateway/${url}`, gateway));
+	} else {
+		const target = new URL(url);
+		if (target.protocol !== "http:" && target.protocol !== "https:") throw new TypeError("Portable media URLs must use HTTP(S) or hl:.");
+		targets = [target];
+	}
+	return await withTimeout(async (signal) => {
+		let lastError;
+		for (const target of targets) {
+			signal.throwIfAborted();
+			try {
+				return await withTimeout((attemptSignal) => fetchVerified(target, digestMultibase, options, attemptSignal, maxBytes), signal, hashlink ? gatewayTimeout : null);
+			} catch (error) {
+				signal.throwIfAborted();
+				if (!hashlink) throw error;
+				lastError = error;
+			}
+		}
+		throw new Error("No gateway returned verified portable media.", { cause: lastError });
+	}, options.signal, timeout);
+}
+//#endregion
+export { FetchError, LanguageString, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout };

package/dist/tests/{body-ORlui-Nx.cjs → body-BG5Ol-IR.cjs}

@@ -1,4 +1,4 @@
-const require_request = require("./request-C5_3S-un.cjs");
+const require_request = require("./request-jic6JEwl.cjs");
 let _logtape_logtape = require("@logtape/logtape");
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */

package/dist/tests/{body-D1z0X88T.mjs → body-DbGNUM07.mjs}

@@ -1,4 +1,4 @@
-import { t as FetchError } from "./request-IIntZ5kj.mjs";
+import { t as FetchError } from "./request-CfuNbRJC.mjs";
 import { getLogger } from "@logtape/logtape";
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */

package/dist/tests/body.test.cjs

@@ -1,4 +1,4 @@
-const require_body = require("./body-ORlui-Nx.cjs");
+const require_body = require("./body-BG5Ol-IR.cjs");
 let node_assert_strict = require("node:assert/strict");
 let node_test = require("node:test");
 let node_zlib = require("node:zlib");

package/dist/tests/body.test.mjs

@@ -1,4 +1,4 @@
-import { i as readBoundedText, t as BodyTooLargeError } from "./body-D1z0X88T.mjs";
+import { i as readBoundedText, t as BodyTooLargeError } from "./body-DbGNUM07.mjs";
 import { deepStrictEqual, ok, rejects } from "node:assert/strict";
 import { test } from "node:test";
 import { gunzipSync, gzipSync } from "node:zlib";

package/dist/tests/decimal.test.cjs

@@ -1,9 +1,10 @@
 require("./url-B8xyTwP-.cjs");
-require("./docloader-Vc3BC9ad.cjs");
+require("./docloader-BC9UAgDx.cjs");
 require("./key-C-AYkdJJ.cjs");
 require("./multibase-B5Mea7Ip.cjs");
 require("./digest-3FeH2Y-Q.cjs");
 require("./langstr-C4Fl80ae.cjs");
+require("./portable-media-Cn4uVXaI.cjs");
 let node_test = require("node:test");
 let node_assert = require("node:assert");
 //#region src/decimal.ts

package/dist/tests/decimal.test.mjs

@@ -1,9 +1,10 @@
 import "./url-DfS-cvwr.mjs";
-import "./docloader-CUdtpDuf.mjs";
+import "./docloader-C-c5dtFJ.mjs";
 import "./key-C2Db_TAJ.mjs";
 import "./multibase-BPnF_L4e.mjs";
 import "./digest-COC7xDiQ.mjs";
 import "./langstr-CQ26J_L7.mjs";
+import "./portable-media-nj7yXhru.mjs";
 import { test } from "node:test";
 import { deepStrictEqual, throws } from "node:assert";
 //#region src/decimal.ts

package/dist/tests/{docloader-Vc3BC9ad.cjs → docloader-BC9UAgDx.cjs}

@@ -1,5 +1,5 @@
-const require_request = require("./request-C5_3S-un.cjs");
-const require_body = require("./body-ORlui-Nx.cjs");
+const require_request = require("./request-jic6JEwl.cjs");
+const require_body = require("./body-BG5Ol-IR.cjs");
 const require_contexts = require("./contexts-DizzBjz4.cjs");
 const require_link = require("./link-DlKm8bEr.cjs");
 const require_url = require("./url-B8xyTwP-.cjs");

package/dist/tests/{docloader-CUdtpDuf.mjs → docloader-C-c5dtFJ.mjs}

@@ -1,5 +1,5 @@
-import { a as name, i as logRequest, n as createActivityPubRequest, o as version, t as FetchError } from "./request-IIntZ5kj.mjs";
-import { i as readBoundedText, n as MAX_BODY_SIZE, r as readBoundedBytes, t as BodyTooLargeError } from "./body-D1z0X88T.mjs";
+import { a as name, i as logRequest, n as createActivityPubRequest, o as version, t as FetchError } from "./request-CfuNbRJC.mjs";
+import { i as readBoundedText, n as MAX_BODY_SIZE, r as readBoundedBytes, t as BodyTooLargeError } from "./body-DbGNUM07.mjs";
 import { t as preloadedContexts } from "./contexts-CIKsin4e.mjs";
 import { t as HttpHeaderLink } from "./link-Cevmc87v.mjs";
 import { t as UrlError, v as validatePublicUrl } from "./url-DfS-cvwr.mjs";

package/dist/tests/docloader.test.cjs

@@ -1,8 +1,8 @@
 const require_rolldown_runtime = require("./rolldown-runtime-emK7D4bc.cjs");
-const require_request = require("./request-C5_3S-un.cjs");
+const require_request = require("./request-jic6JEwl.cjs");
 const require_contexts = require("./contexts-DizzBjz4.cjs");
 const require_url = require("./url-B8xyTwP-.cjs");
-const require_docloader = require("./docloader-Vc3BC9ad.cjs");
+const require_docloader = require("./docloader-BC9UAgDx.cjs");
 let node_test = require("node:test");
 let node_zlib = require("node:zlib");
 let _logtape_logtape = require("@logtape/logtape");

package/dist/tests/docloader.test.mjs

@@ -1,7 +1,7 @@
-import { t as FetchError } from "./request-IIntZ5kj.mjs";
+import { t as FetchError } from "./request-CfuNbRJC.mjs";
 import { n as cid_v1_default, t as preloadedContexts } from "./contexts-CIKsin4e.mjs";
 import { t as UrlError } from "./url-DfS-cvwr.mjs";
-import { i as withDocumentLoaderTimeout, n as getRemoteDocument, r as resolveDocumentLoaderTimeout, t as getDocumentLoader } from "./docloader-CUdtpDuf.mjs";
+import { i as withDocumentLoaderTimeout, n as getRemoteDocument, r as resolveDocumentLoaderTimeout, t as getDocumentLoader } from "./docloader-C-c5dtFJ.mjs";
 import { test } from "node:test";
 import { gzipSync } from "node:zlib";
 import { configure, reset } from "@logtape/logtape";