@fedify/vocab-runtime 2.2.18 → 2.2.20

package/dist/mod.js

@@ -1,9 +1,8 @@
 
+import { a as expandIPv6Address, c as validatePublicUrl, i as UrlError, n as openPublicFetch, o as isValidPublicIPv4Address, s as isValidPublicIPv6Address, t as openDirectFetch } from "./public-fetch-Dfmc_Kfy.js";
 import { getLogger } from "@logtape/logtape";
 import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import process from "node:process";
-import dns from "node:dns/promises";
-import { isIP } from "node:net";
 import { Integer, Sequence } from "asn1js";
 import { decodeBase64, encodeBase64 } from "byte-encodings/base64";
 import { decodeBase64Url } from "byte-encodings/base64url";
@@ -4588,7 +4587,7 @@ const preloadedContexts = {
 //#endregion
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.2.18";
+var version = "2.2.20";
 //#endregion
 //#region src/request.ts
 /**
@@ -4915,216 +4914,6 @@ var HttpHeaderLink = class HttpHeaderLink {
 	}
 };
 //#endregion
-//#region src/url.ts
-var UrlError = class extends Error {
-	/**
-	* The failure category. Defaults to `"disallowed"`.
-	* `"dns"` includes lookup errors and results with no usable IP addresses.
-	* @since 2.0.29
-	*/
-	reason;
-	constructor(message, options) {
-		super(message, options);
-		this.name = "UrlError";
-		this.reason = options?.reason ?? "disallowed";
-	}
-};
-/**
-* Validates a URL to prevent SSRF attacks.
-*/
-async function validatePublicUrl(url) {
-	const parsed = new URL(url);
-	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new UrlError(`Unsupported protocol: ${parsed.protocol}`);
-	let hostname = parsed.hostname;
-	if (hostname.startsWith("[") && hostname.endsWith("]")) hostname = hostname.slice(1, -1);
-	if (hostname === "localhost") throw new UrlError("Localhost is not allowed");
-	const hostnameFamily = isIP(hostname);
-	if (hostnameFamily !== 0) {
-		validatePublicIpAddress(hostname, hostnameFamily);
-		return;
-	}
-	if ("Deno" in globalThis && !isIP(hostname)) {
-		if ((await Deno.permissions.query({ name: "net" })).state !== "granted") return;
-	}
-	if ("Bun" in globalThis) {
-		if (hostname === "example.com" || hostname.endsWith(".example.com")) return;
-		else if (hostname === "fedify-test.internal") throw new UrlError("Invalid or private address: fedify-test.internal");
-	}
-	let addresses;
-	try {
-		addresses = await dns.lookup(hostname, { all: true });
-	} catch (error) {
-		throw new UrlError("DNS lookup failed", {
-			cause: error,
-			reason: "dns"
-		});
-	}
-	validateLookupAddresses(addresses);
-}
-/**
-* Validates the IP addresses returned by `node:dns.lookup()`.
-*
-* Cloudflare Workers' `node:dns` implementation currently maps every record
-* in a DNS-over-HTTPS `Answer` array—including CNAME records—to a
-* `LookupAddress`, even though Node.js specifies that the `address` field must
-* contain an IPv4 or IPv6 literal.  See:
-* https://github.com/cloudflare/workerd/issues/6886
-*
-* Work around that bug by ignoring non-IP entries only when the lookup also
-* returns at least one actual IP address.  This remains fail-closed: a result
-* containing no IP addresses is rejected, and every returned IP address is
-* still validated and must be public.  This workaround can be revisited once
-* the Workerd issue is fixed in supported Cloudflare Workers runtimes.
-*
-* @internal
-*/
-function validateLookupAddresses(addresses) {
-	let ipAddressCount = 0;
-	for (const { address } of addresses) {
-		const family = isIP(address);
-		if (family === 0) continue;
-		ipAddressCount++;
-		validatePublicIpAddress(address, family);
-	}
-	if (ipAddressCount === 0) throw new UrlError("DNS lookup did not return any IP address", { reason: "dns" });
-}
-function validatePublicIpAddress(address, family) {
-	if (family === 4 && isValidPublicIPv4Address(address) || family === 6 && isValidPublicIPv6Address(address)) return;
-	throw new UrlError(`Invalid or private address: ${address}`);
-}
-function isValidPublicIPv4Address(address) {
-	const parts = parseIPv4Address(address);
-	if (parts == null) return false;
-	const value = ipv4PartsToNumber(parts);
-	return !nonPublicIPv4Prefixes.some(({ base, prefix }) => matchesIPv4Prefix(value, base, prefix));
-}
-function isValidPublicIPv6Address(address) {
-	const words = parseIPv6Address(address);
-	if (words == null) return false;
-	if (nonPublicIPv6Prefixes.some(({ words: prefixWords, prefix }) => matchesIPv6Prefix(words, prefixWords, prefix))) return false;
-	for (const { extractIPv4, prefix, words: prefixWords } of ipv6WithIPv4Prefixes) {
-		if (!matchesIPv6Prefix(words, prefixWords, prefix)) continue;
-		const ipv4Address = extractIPv4(words);
-		if (ipv4Address != null && !isValidPublicIPv4Address(ipv4Address)) return false;
-	}
-	return true;
-}
-function expandIPv6Address(address) {
-	address = address.toLowerCase();
-	const ipv4Delimiter = address.lastIndexOf(":");
-	if (address.includes(".") && ipv4Delimiter >= 0) {
-		const ipv4Parts = parseIPv4Address(address.substring(ipv4Delimiter + 1));
-		if (ipv4Parts == null) return address;
-		const high = (ipv4Parts[0] << 8) + ipv4Parts[1];
-		const low = (ipv4Parts[2] << 8) + ipv4Parts[3];
-		address = address.substring(0, ipv4Delimiter + 1) + high.toString(16) + ":" + low.toString(16);
-	}
-	if (address === "::") return "0000:0000:0000:0000:0000:0000:0000:0000";
-	if (address.startsWith("::")) address = "0000" + address;
-	if (address.endsWith("::")) address = address + "0000";
-	address = address.replace("::", ":0000".repeat(8 - (address.match(/:/g) || []).length) + ":");
-	return address.split(":").map((part) => part.padStart(4, "0")).join(":");
-}
-const nonPublicIPv4Prefixes = [
-	ipv4Prefix("0.0.0.0/8", "RFC 6890"),
-	ipv4Prefix("10.0.0.0/8", "RFC 1918"),
-	ipv4Prefix("100.64.0.0/10", "RFC 6598"),
-	ipv4Prefix("127.0.0.0/8", "RFC 1122"),
-	ipv4Prefix("169.254.0.0/16", "RFC 3927"),
-	ipv4Prefix("172.16.0.0/12", "RFC 1918"),
-	ipv4Prefix("192.0.0.0/24", "RFC 6890"),
-	ipv4Prefix("192.0.2.0/24", "RFC 5737"),
-	ipv4Prefix("192.88.99.0/24", "RFC 7526"),
-	ipv4Prefix("192.168.0.0/16", "RFC 1918"),
-	ipv4Prefix("198.18.0.0/15", "RFC 2544"),
-	ipv4Prefix("198.51.100.0/24", "RFC 5737"),
-	ipv4Prefix("203.0.113.0/24", "RFC 5737"),
-	ipv4Prefix("224.0.0.0/4", "RFC 5771"),
-	ipv4Prefix("240.0.0.0/4", "RFC 1112")
-];
-const nonPublicIPv6Prefixes = [
-	ipv6Prefix("::/16", "RFC 4291"),
-	ipv6Prefix("2001::/32", "RFC 4380"),
-	ipv6Prefix("2002::/16", "RFC 3056"),
-	ipv6Prefix("64:ff9b:1::/48", "RFC 8215"),
-	ipv6Prefix("fc00::/7", "RFC 4193"),
-	ipv6Prefix("fe80::/10", "RFC 4291"),
-	ipv6Prefix("ff00::/8", "RFC 4291")
-];
-const ipv6WithIPv4Prefixes = [{
-	...ipv6Prefix("64:ff9b::/96", "RFC 6052"),
-	extractIPv4: (words) => ipv4FromWords(words[6], words[7])
-}];
-function ipv4Prefix(cidr, rfc) {
-	const [address, prefixText] = cidr.split("/");
-	const prefix = parseInt(prefixText, 10);
-	const parts = parseIPv4Address(address);
-	if (parts == null || !Number.isInteger(prefix) || prefix < 0 || prefix > 32) throw new Error(`Invalid IPv4 prefix: ${cidr}`);
-	return {
-		cidr,
-		base: ipv4PartsToNumber(parts),
-		prefix,
-		rfc
-	};
-}
-function ipv6Prefix(cidr, rfc) {
-	const [address, prefixText] = cidr.split("/");
-	const prefix = parseInt(prefixText, 10);
-	const words = parseIPv6Address(address);
-	if (words == null || !Number.isInteger(prefix) || prefix < 0 || prefix > 128) throw new Error(`Invalid IPv6 prefix: ${cidr}`);
-	return {
-		cidr,
-		words,
-		prefix,
-		rfc
-	};
-}
-function parseIPv4Address(address) {
-	const parts = address.split(".").map((part) => {
-		if (!/^\d+$/.test(part)) return NaN;
-		return parseInt(part, 10);
-	});
-	if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return null;
-	return parts;
-}
-function parseIPv6Address(address) {
-	const parts = expandIPv6Address(address).split(":");
-	if (parts.length !== 8) return null;
-	const words = parts.map((part) => {
-		if (!/^[0-9a-f]{1,4}$/i.test(part)) return NaN;
-		return parseInt(part, 16);
-	});
-	if (words.some((word) => !Number.isInteger(word) || word < 0 || word > 65535)) return null;
-	return words;
-}
-function ipv4PartsToNumber(parts) {
-	return parts[0] * 2 ** 24 + parts[1] * 2 ** 16 + parts[2] * 2 ** 8 + parts[3];
-}
-function ipv4FromWords(highWord, lowWord) {
-	return [
-		highWord >> 8,
-		highWord & 255,
-		lowWord >> 8,
-		lowWord & 255
-	].join(".");
-}
-function matchesIPv4Prefix(address, prefixBase, prefixLength) {
-	const blockSize = 2 ** (32 - prefixLength);
-	return Math.floor(address / blockSize) === Math.floor(prefixBase / blockSize);
-}
-function matchesIPv6Prefix(address, prefixWords, prefixLength) {
-	let remaining = prefixLength;
-	for (let i = 0; i < 8 && remaining > 0; i++) if (remaining >= 16) {
-		if (address[i] !== prefixWords[i]) return false;
-		remaining -= 16;
-	} else {
-		const mask = 65535 << 16 - remaining & 65535;
-		if ((address[i] & mask) !== (prefixWords[i] & mask)) return false;
-		remaining = 0;
-	}
-	return true;
-}
-//#endregion
 //#region src/docloader.ts
 const logger = getLogger([
 	"fedify",
@@ -5136,13 +4925,47 @@ const DEFAULT_MAX_REDIRECTION = 20;
 * Gets a {@link RemoteDocument} from the given response.
 * @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 fetch The function to fetch the document.  It is called with the URL
+*              of an alternate document, if any, after the response body has
+*              been either read or its cancellation has been started.
 * @returns The loaded remote document.
 * @throws {FetchError} If the response is not OK.
 * @internal
 */
 async function getRemoteDocument(url, response, fetch) {
-	const documentUrl = response.url === "" ? url : response.url;
+	const result = await parseRemoteDocument(url, response);
+	if ("alternate" in result) return await fetch(result.alternate);
+	return result.document;
+}
+/**
+* Starts cancelling the body of a response without waiting for it to settle.
+* The cancellation of a branch of a tee (e.g., a body cloned by a fetch mock)
+* settles only after the other branch is cancelled too, per the Streams
+* standard, so awaiting it could block forever.  Failures are only logged.
+* @param response The response whose body is cancelled.
+* @param url The URL of the response, for logging.
+*/
+function cancelResponseBody(response, url) {
+	response.body?.cancel().catch((error) => {
+		logger.debug("Failed to cancel the response body from {url}: {error}", {
+			url,
+			error
+		});
+	});
+}
+/**
+* Gets a {@link RemoteDocument} from the given response, or the URL of an
+* alternate document to load instead.  When an alternate document is found,
+* the response body has been either read or its cancellation has been started
+* (without waiting for it), so that the alternate document can be loaded after
+* the response's session is closed.
+* @param url The URL of the document to load.
+* @param response The response to get the document from.
+* @returns The loaded remote document, or the alternate document URL.
+* @throws {FetchError} If the response is not OK.
+*/
+async function parseRemoteDocument(url, response) {
+	const documentUrl = url;
 	const docUrl = new URL(documentUrl);
 	if (!response.ok) {
 		logger.error("Failed to fetch document: {status} {url} {headers}", {
@@ -5179,7 +5002,8 @@ async function getRemoteDocument(url, response, fetch) {
 						alternateUrl: altUri.href,
 						url: documentUrl
 					});
-					return await fetch(altUri.href);
+					cancelResponseBody(response, documentUrl);
+					return { alternate: altUri.href };
 				}
 			}
 		}
@@ -5204,7 +5028,7 @@ async function getRemoteDocument(url, response, fetch) {
 					alternateUrl: attribs.href,
 					url: documentUrl
 				});
-				return await fetch(new URL(attribs.href, docUrl).href);
+				return { alternate: new URL(attribs.href, docUrl).href };
 			}
 		}
 		document = JSON.parse(html);
@@ -5214,11 +5038,11 @@ async function getRemoteDocument(url, response, fetch) {
 		url: documentUrl,
 		headers: Object.fromEntries(response.headers.entries())
 	});
-	return {
+	return { document: {
 		contextUrl,
 		document,
 		documentUrl
-	};
+	} };
 }
 /**
 * Creates a JSON-LD document loader that utilizes the browser's `fetch` API.
@@ -5244,13 +5068,59 @@ async function getRemoteDocument(url, response, fetch) {
 * @returns The document loader.
 * @since 1.3.0
 */
-function getDocumentLoader({ allowPrivateAddress, maxRedirection, skipPreloadedContexts, userAgent } = {}) {
+function getDocumentLoader(options = {}) {
+	return createDocumentLoader(options);
+}
+/**
+* The implementation of {@link getDocumentLoader}, with injectable
+* dependencies.  This is not exported from any entry point.
+* @param options Options for the document loader.
+* @param deps The dependencies.
+* @returns The document loader.
+*/
+function createDocumentLoader({ allowPrivateAddress, maxRedirection, skipPreloadedContexts, userAgent } = {}, deps = {}) {
 	const tracer = trace.getTracerProvider().getTracer(name, version);
 	const maximumRedirection = maxRedirection ?? DEFAULT_MAX_REDIRECTION;
+	async function openHop(url, signal) {
+		try {
+			if (deps.openHop != null) return await deps.openHop(url);
+			return allowPrivateAddress ? await openDirectFetch(url) : await openPublicFetch(url, { signal });
+		} catch (error) {
+			if (error instanceof UrlError) if (error.reason === "dns") logger.debug("DNS lookup failed for {url}", {
+				url,
+				error
+			});
+			else logger.error("Disallowed private URL: {url}", {
+				url,
+				error
+			});
+			throw error;
+		}
+	}
+	async function fetchHop(session, url, span, options) {
+		try {
+			const request = createActivityPubRequest(url, { userAgent });
+			logRequest(logger, request);
+			const response = await session.fetch(request, {
+				redirect: "manual",
+				signal: options?.signal
+			});
+			span.setAttribute("http.response.status_code", response.status);
+			if (response.status >= 300 && response.status < 400 && response.headers.has("Location")) {
+				const location = response.headers.get("Location");
+				cancelResponseBody(response, url);
+				return { location };
+			}
+			return await parseRemoteDocument(url, response);
+		} finally {
+			await session.close();
+		}
+	}
 	async function load(url, options, redirected = 0, visited = /* @__PURE__ */ new Set()) {
 		options?.signal?.throwIfAborted();
 		const parsedUrl = new URL(url);
 		if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") throw new UrlError(`Unsupported protocol: ${parsedUrl.protocol}`);
+		if (parsedUrl.username !== "" || parsedUrl.password !== "") throw new UrlError("URLs with credentials are not allowed");
 		const currentUrl = parsedUrl.href;
 		if (!skipPreloadedContexts && currentUrl in preloadedContexts) {
 			logger.debug("Using preloaded context: {url}.", { url: currentUrl });
@@ -5260,33 +5130,15 @@ function getDocumentLoader({ allowPrivateAddress, maxRedirection, skipPreloadedC
 				documentUrl: currentUrl
 			};
 		}
-		if (!allowPrivateAddress) try {
-			await validatePublicUrl(currentUrl);
-		} catch (error) {
-			if (error instanceof UrlError) if (error.reason === "dns") logger.debug("DNS lookup failed for {url}", {
-				url: currentUrl,
-				error
-			});
-			else logger.error("Disallowed private URL: {url}", {
-				url: currentUrl,
-				error
-			});
-			throw error;
-		}
+		const session = await openHop(currentUrl, options?.signal);
 		visited.add(currentUrl);
 		return await tracer.startActiveSpan("activitypub.fetch_document", {
 			kind: SpanKind.CLIENT,
 			attributes: { "url.full": currentUrl }
 		}, async (span) => {
 			try {
-				const request = createActivityPubRequest(currentUrl, { userAgent });
-				logRequest(logger, request);
-				const response = await fetch(request, {
-					redirect: "manual",
-					signal: options?.signal
-				});
-				span.setAttribute("http.response.status_code", response.status);
-				if (response.status >= 300 && response.status < 400 && response.headers.has("Location")) {
+				const outcome = await fetchHop(session, currentUrl, span, options);
+				if ("location" in outcome) {
 					if (redirected >= maximumRedirection) {
 						logger.error("Too many redirections ({redirections}) while fetching document.", {
 							redirections: redirected + 1,
@@ -5294,7 +5146,7 @@ function getDocumentLoader({ allowPrivateAddress, maxRedirection, skipPreloadedC
 						});
 						throw new FetchError(currentUrl, `Too many redirections (${redirected + 1})`);
 					}
-					const redirectUrl = new URL(response.headers.get("Location"), response.url === "" ? currentUrl : response.url).href;
+					const redirectUrl = new URL(outcome.location, currentUrl).href;
 					span.setAttribute("http.redirect.url", redirectUrl);
 					if (visited.has(redirectUrl)) {
 						logger.error("Detected a redirect loop while fetching document: {url} -> {redirectUrl}", {
@@ -5305,12 +5157,14 @@ function getDocumentLoader({ allowPrivateAddress, maxRedirection, skipPreloadedC
 					}
 					return await load(redirectUrl, options, redirected + 1, visited);
 				}
-				const result = await getRemoteDocument(currentUrl, response, async (alternateUrl) => {
+				let result;
+				if ("alternate" in outcome) {
+					const alternateUrl = outcome.alternate;
 					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);
-				});
+					result = await load(alternateUrl, options, redirected + 1, visited);
+				} else result = outcome.document;
 				span.setAttribute("docloader.document_url", result.documentUrl);
 				if (result.contextUrl != null) span.setAttribute("docloader.context_url", result.contextUrl);
 				return result;

package/dist/public-fetch-BC-nWJNM.d.ts

@@ -0,0 +1,143 @@
+/// <reference lib="esnext.temporal" />
+//#region src/url.d.ts
+/**
+* An address returned by a DNS lookup.  It has the same shape as
+* `ResolvedAddress` of `node:dns`, without depending on its type declarations.
+* @internal
+*/
+interface ResolvedAddress {
+  /** An IPv4 or IPv6 address. */
+  readonly address: string;
+  /** The IP family of the address: `4` or `6`. */
+  readonly family: number;
+}
+declare class UrlError extends Error {
+  /**
+  * The failure category. Defaults to `"disallowed"`.
+  * `"dns"` includes lookup errors and results with no usable IP addresses.
+  * @since 2.0.29
+  */
+  readonly reason: "dns" | "disallowed";
+  constructor(message: string, options?: {
+    cause?: unknown;
+    reason?: "dns" | "disallowed";
+  });
+}
+/**
+* Validates a URL to prevent SSRF attacks.
+*
+* This function only checks the addresses that the hostname currently
+* resolves to; it does not pin the connection to those addresses.  A request
+* made after this check resolves the hostname again, so this function alone
+* does not prevent DNS rebinding.
+*/
+declare function validatePublicUrl(url: string): Promise<void>;
+declare function isValidPublicIPv4Address(address: string): boolean;
+declare function isValidPublicIPv6Address(address: string): boolean;
+declare function expandIPv6Address(address: string): string;
+//#endregion
+//#region src/public-fetch.d.ts
+/**
+* Options for {@link openPublicFetch} and {@link withPublicFetch}.
+*/
+interface PublicFetchOptions {
+  /**
+  * An `AbortSignal` for cancelling the DNS lookup.
+  */
+  readonly signal?: AbortSignal;
+  /**
+  * A function that resolves all addresses of a hostname, used instead of
+  * `node:dns.lookup()`.  The addresses it returns are validated in the same
+  * way as the default lookup's.
+  */
+  readonly lookup?: (hostname: string) => Promise<readonly ResolvedAddress[]>;
+}
+/**
+* A session for fetching resources from a single origin.  Its `fetch()`
+* connects only to the addresses validated when the session was opened, on
+* runtimes that support it.
+*/
+interface PublicFetchSession {
+  /**
+  * A copy of the URL the session was opened for.
+  */
+  readonly url: URL;
+  /**
+  * Fetches a resource from the session's origin.  Redirects are never
+  * followed; the redirect mode is always `"manual"`.
+  * @throws {TypeError} If the input's origin differs from the session's, or
+  *                     if the session is closed.
+  */
+  fetch(input: Request | URL | string, init?: RequestInit): Promise<Response>;
+  /**
+  * Closes the session.  The cancellation of response bodies that have been
+  * neither consumed nor cancelled is started (without waiting for it), and
+  * the session can no longer fetch.  Calling this more than once has no
+  * effect.
+  */
+  close(): Promise<void>;
+}
+/**
+* The functions created by {@link createPublicFetch}.
+*/
+interface PublicFetch {
+  /**
+  * Validates the URL, resolves its hostname, checks that every resolved
+  * address is public, and opens a session that connects only to those
+  * addresses.
+  * @param url The URL to open a session for.
+  * @param options The options.
+  * @returns The session.  It must be closed.
+  * @throws {UrlError} If the URL is not allowed, or its hostname cannot be
+  *                    resolved (with `reason: "dns"`).
+  */
+  openPublicFetch(url: URL | string, options?: PublicFetchOptions): Promise<PublicFetchSession>;
+  /**
+  * Opens a session with {@link PublicFetch.openPublicFetch}, runs the given
+  * function with its `fetch()`, and closes the session afterwards.
+  * @param url The URL to open a session for.
+  * @param fn The function to run.  It must not return a `Response`, since
+  *           the response bodies are cancelled when the session is closed.
+  * @param options The options.
+  * @returns The value returned by `fn`.
+  * @throws {UrlError} If the URL is not allowed.
+  * @throws {TypeError} If `fn` returns a `Response`.
+  */
+  withPublicFetch<T>(url: URL | string, fn: (fetch: PublicFetchSession["fetch"]) => Promise<T>, options?: PublicFetchOptions): Promise<T>;
+}
+/**
+* Validates the URL, resolves its hostname, checks that every resolved
+* address is public, and opens a session that connects only to those
+* addresses.  Connections are pinned on Node.js and Bun.  On other runtimes,
+* the session uses the global `fetch()` after the check.
+* @param url The URL to open a session for.
+* @param options The options.
+* @returns The session.  It must be closed.
+* @throws {UrlError} If the URL is not allowed, or its hostname cannot be
+*                    resolved (with `reason: "dns"`).
+*/
+declare const openPublicFetch: PublicFetch["openPublicFetch"];
+/**
+* Opens a session with {@link openPublicFetch}, runs the given function with
+* its `fetch()`, and closes the session afterwards.
+* @param url The URL to open a session for.
+* @param fn The function to run.  It must not return a `Response`, since
+*           the response bodies are cancelled when the session is closed.
+* @param options The options.
+* @returns The value returned by `fn`.
+* @throws {UrlError} If the URL is not allowed.
+* @throws {TypeError} If `fn` returns a `Response`.
+*/
+declare const withPublicFetch: PublicFetch["withPublicFetch"];
+/**
+* Opens a session that neither validates nor pins addresses, for callers that
+* allow private addresses.  It has the same rules as {@link openPublicFetch}
+* sessions otherwise: requests are limited to the URL's origin, redirects are
+* never followed, and unconsumed response bodies are cancelled on close.
+* It grants nothing beyond calling the global `fetch()` directly.
+* @param url The URL to open a session for.
+* @returns The session.  It must be closed.
+*/
+declare function openDirectFetch(url: URL | string): Promise<PublicFetchSession>;
+//#endregion
+export { withPublicFetch as a, isValidPublicIPv4Address as c, openPublicFetch as i, isValidPublicIPv6Address as l, PublicFetchSession as n, UrlError as o, openDirectFetch as r, expandIPv6Address as s, PublicFetchOptions as t, validatePublicUrl as u };