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

package/dist/tests/portable-media-C4LEXJk4.mjs

@@ -0,0 +1,148 @@
+import { r as getUserAgent } from "./request-Cf-A3DU-.mjs";
+import { r as readBoundedBytes } from "./body-CVR1bABr.mjs";
+import { g as parseGatewayUrl, x as validatePublicUrl } from "./url-DMxmp7ZG.mjs";
+import { a as verifyDigestMultibase, i as parseHashlink, r as parseDigestMultibase } from "./digest-COC7xDiQ.mjs";
+//#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 { fetchPortableMedia as t };

package/dist/tests/portable-media-D05JJIJg.cjs

@@ -0,0 +1,153 @@
+const require_request = require("./request-C-VZ9TLj.cjs");
+const require_body = require("./body-T_yQWql3.cjs");
+const require_url = require("./url-BNakuZ8k.cjs");
+const require_digest = require("./digest-3FeH2Y-Q.cjs");
+//#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 = require_digest.parseDigestMultibase(media.digestMultibase).digest;
+		const inner = require_digest.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 : require_request.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 require_body.readBoundedBytes(response, maxBytes, url);
+		signal.throwIfAborted();
+		if (!await require_digest.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 = require_digest.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 = require_digest.parseDigestMultibase(require_digest.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
+Object.defineProperty(exports, "fetchPortableMedia", {
+	enumerable: true,
+	get: function() {
+		return fetchPortableMedia;
+	}
+});

package/dist/tests/portable-media.test.cjs

@@ -0,0 +1,222 @@
+const require_digest = require("./digest-3FeH2Y-Q.cjs");
+const require_portable_media = require("./portable-media-D05JJIJg.cjs");
+let node_assert_strict = require("node:assert/strict");
+let node_test = require("node:test");
+let node_http = require("node:http");
+//#region src/portable-media.test.ts
+const bytes = new TextEncoder().encode("portable image");
+const digest = "zQmU2Jds4B2J83K7CrYC34CEJdB6vCLyqkM2cgBxYeaNWTA";
+const hashlink = require_digest.createHashlink(digest);
+const networkTest = (name, run) => (0, node_test.test)(name, async (t) => {
+	if ("Deno" in globalThis && (await Deno.permissions.query({ name: "net" })).state !== "granted") {
+		t.skip("Requires network permission for a local test server.");
+		return;
+	}
+	await run();
+});
+async function withServers(handlers, run) {
+	const servers = handlers.map((handler) => (0, node_http.createServer)(async (request, reply) => {
+		const result = handler(request.url ?? "/");
+		if (result == null) return;
+		reply.writeHead(result.status, Object.fromEntries(result.headers));
+		reply.end(new Uint8Array(await result.arrayBuffer()));
+	}));
+	try {
+		const origins = [];
+		for (const server of servers) {
+			await new Promise((resolve, reject) => {
+				server.once("error", reject);
+				server.listen(0, "127.0.0.1", resolve);
+			});
+			const address = server.address();
+			if (address == null || typeof address === "string") throw new Error("Server did not bind a TCP port.");
+			origins.push(`http://127.0.0.1:${address.port}`);
+		}
+		await run(origins);
+	} finally {
+		await Promise.all(servers.map(async (server) => {
+			server.closeAllConnections();
+			await new Promise((resolve) => server.close(() => resolve()));
+		}));
+	}
+}
+networkTest("fetchPortableMedia() accepts Link, Image, and Document", async () => {
+	const link = {
+		href: new URL(hashlink),
+		digestMultibase: digest
+	};
+	const image = {
+		url: new URL(hashlink),
+		digestMultibase: digest
+	};
+	const document = { url: {
+		href: new URL(hashlink),
+		digestMultibase: digest
+	} };
+	const requested = [];
+	await withServers([(path) => {
+		requested.push(path);
+		return new Response(bytes);
+	}], async ([gateway]) => {
+		for (const media of [
+			link,
+			image,
+			document
+		]) (0, node_assert_strict.equal)(await (await require_portable_media.fetchPortableMedia(media, {
+			gateways: [gateway],
+			allowPrivateAddress: true
+		})).text(), "portable image");
+	});
+	(0, node_assert_strict.deepStrictEqual)(requested, Array(3).fill(`/.well-known/apgateway/${hashlink}`));
+});
+networkTest("fetchPortableMedia() falls back on status and digest mismatch", async () => {
+	const requested = [];
+	await withServers([
+		(path) => {
+			requested.push(`first:${path}`);
+			return new Response(null, { status: 503 });
+		},
+		(path) => {
+			requested.push(`second:${path}`);
+			return new Response("wrong bytes");
+		},
+		(path) => {
+			requested.push(`third:${path}`);
+			return new Response(bytes, { headers: {
+				"Content-Type": "image/png",
+				"Set-Cookie": "secret=1"
+			} });
+		}
+	], async (gateways) => {
+		const result = await require_portable_media.fetchPortableMedia({
+			url: new URL(hashlink),
+			digestMultibase: digest
+		}, {
+			gateways,
+			allowPrivateAddress: true
+		});
+		(0, node_assert_strict.equal)(await result.text(), "portable image");
+		(0, node_assert_strict.equal)(result.headers.get("Content-Type"), "image/png");
+		(0, node_assert_strict.equal)(result.headers.get("Set-Cookie"), null);
+	});
+	(0, node_assert_strict.deepStrictEqual)(requested.map((r) => r.split(":")[0]), [
+		"first",
+		"second",
+		"third"
+	]);
+});
+networkTest("fetchPortableMedia() verifies direct HTTP media", async () => {
+	const wrongDigest = await require_digest.computeDigestMultibase(/* @__PURE__ */ new Uint8Array());
+	await withServers([() => new Response(bytes)], async ([origin]) => {
+		(0, node_assert_strict.equal)(await (await require_portable_media.fetchPortableMedia(`${origin}/a`, {
+			digestMultibase: digest,
+			allowPrivateAddress: true
+		})).text(), "portable image");
+		await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia(`${origin}/a`, {
+			digestMultibase: wrongDigest,
+			allowPrivateAddress: true
+		}), /digest does not match/);
+	});
+});
+(0, node_test.test)("fetchPortableMedia() rejects invalid references before fetching", async () => {
+	const wrongDigest = await require_digest.computeDigestMultibase(/* @__PURE__ */ new Uint8Array());
+	await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia({ url: new URL(hashlink) }), /requires digestMultibase/);
+	await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia({
+		url: new URL(hashlink),
+		digestMultibase: digest
+	}), /requires at least one gateway/);
+	await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia({
+		url: new URL(hashlink),
+		digestMultibase: wrongDigest
+	}, { gateways: ["https://example.com"] }), /disagree/);
+	await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia({
+		url: new URL("hl:invalid"),
+		digestMultibase: digest
+	}, { gateways: ["https://example.com"] }), TypeError);
+	await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia({
+		url: {
+			href: new URL(hashlink),
+			digestMultibase: wrongDigest
+		},
+		digestMultibase: digest
+	}, { gateways: ["https://example.com"] }), /digests disagree/);
+	await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia("file:///tmp/media", { digestMultibase: digest }), TypeError);
+});
+networkTest("fetchPortableMedia() bounds response bytes", async () => {
+	await withServers([() => new Response(bytes)], async ([origin]) => {
+		await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia(`${origin}/media`, {
+			digestMultibase: digest,
+			maxBytes: bytes.length - 1,
+			allowPrivateAddress: true
+		}), /exceeds the limit/);
+	});
+	await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia("https://example.com/media", {
+		digestMultibase: digest,
+		maxBytes: 0
+	}), RangeError);
+});
+(0, node_test.test)("fetchPortableMedia() rejects private media and gateways", async () => {
+	await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia("http://127.0.0.1/media", { digestMultibase: digest }), /private address/);
+	await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia({
+		url: new URL(hashlink),
+		digestMultibase: digest
+	}, { gateways: ["http://127.0.0.1"] }), /No gateway returned verified portable media/);
+});
+(0, node_test.test)("fetchPortableMedia() propagates cancellation", async () => {
+	const controller = new AbortController();
+	const reason = /* @__PURE__ */ new Error("cancelled");
+	controller.abort(reason);
+	await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia({
+		url: new URL(hashlink),
+		digestMultibase: digest
+	}, {
+		gateways: ["https://example.com"],
+		signal: controller.signal
+	}), (error) => error === reason);
+});
+networkTest("fetchPortableMedia() falls back after a gateway timeout", async () => {
+	await withServers([() => void 0, () => new Response(bytes)], async (gateways) => {
+		(0, node_assert_strict.equal)(await (await require_portable_media.fetchPortableMedia({
+			url: new URL(hashlink),
+			digestMultibase: digest
+		}, {
+			gateways,
+			allowPrivateAddress: true,
+			gatewayTimeout: 500,
+			timeout: 5e3
+		})).text(), "portable image");
+	});
+});
+networkTest("fetchPortableMedia() applies one overall timeout", async () => {
+	await withServers([() => void 0, () => new Response(bytes)], async (gateways) => {
+		await (0, node_assert_strict.rejects)(() => require_portable_media.fetchPortableMedia({
+			url: new URL(hashlink),
+			digestMultibase: digest
+		}, {
+			gateways,
+			allowPrivateAddress: true,
+			gatewayTimeout: 100,
+			timeout: 20
+		}), (error) => error instanceof DOMException && error.name === "TimeoutError");
+	});
+});
+networkTest("fetchPortableMedia() follows a safe redirect", async () => {
+	const requested = [];
+	await withServers([(path) => {
+		requested.push(path);
+		return path === "/media" ? new Response(bytes) : new Response(null, {
+			status: 302,
+			headers: { Location: "/media" }
+		});
+	}], async ([gateway]) => {
+		(0, node_assert_strict.equal)(await (await require_portable_media.fetchPortableMedia({
+			url: new URL(hashlink),
+			digestMultibase: digest
+		}, {
+			gateways: [gateway],
+			allowPrivateAddress: true
+		})).text(), "portable image");
+	});
+	(0, node_assert_strict.deepStrictEqual)(requested, [`/.well-known/apgateway/${hashlink}`, "/media"]);
+});
+//#endregion

package/dist/tests/portable-media.test.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/tests/portable-media.test.d.mts

@@ -0,0 +1 @@
+export { };