@fedify/webfinger 2.3.14 → 2.3.15

package/dist/mod.cjs

@@ -1,10 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _opentelemetry_api = require("@opentelemetry/api");
 let _fedify_vocab_runtime = require("@fedify/vocab-runtime");
+let _fedify_vocab_runtime_internal = require("@fedify/vocab-runtime/internal");
 let _logtape_logtape = require("@logtape/logtape");
-let _opentelemetry_api = require("@opentelemetry/api");
 //#region deno.json
 var name = "@fedify/webfinger";
-var version = "2.3.14";
+var version = "2.3.15";
 //#endregion
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */
@@ -80,13 +81,223 @@ async function readBoundedText(message, maxBytes, url) {
 	}
 }
 //#endregion
-//#region src/lookup.ts
+//#region src/lookup-impl.ts
 const logger = (0, _logtape_logtape.getLogger)([
 	"fedify",
 	"webfinger",
 	"lookup"
 ]);
 const DEFAULT_MAX_REDIRECTION = 5;
+/**
+* Looks up a WebFinger resource, opening a fetch session per hop.  This is
+* the implementation of {@link lookupWebFinger}, which is not exported from
+* the package entry point.
+* @param resource The resource URL to look up.
+* @param options Extra options for looking up the resource.
+* @param deps The dependencies.
+* @returns The resource descriptor and terminal lookup classification.
+* @internal
+*/
+async function lookupWebFingerInternal(resource, options = {}, deps = {}) {
+	if (typeof resource === "string") resource = new URL(resource);
+	let protocol = "https:";
+	let server;
+	if (resource.protocol === "acct:" || resource.protocol === "mailto:") {
+		const atPos = resource.pathname.lastIndexOf("@");
+		if (atPos < 0) return {
+			resource: null,
+			result: "invalid"
+		};
+		server = resource.pathname.substring(atPos + 1);
+		if (server === "" || /[/?#]/.test(server)) return {
+			resource: null,
+			result: "invalid"
+		};
+		if (resource.protocol === "acct:" && (resource.search !== "" || resource.hash !== "")) return {
+			resource: null,
+			result: "invalid"
+		};
+	} else {
+		protocol = resource.protocol;
+		server = resource.host;
+	}
+	let url = new URL(`${protocol}//${server}/.well-known/webfinger`);
+	url.searchParams.set("resource", resource.href);
+	const openHop = deps.openHop ?? ((hopUrl) => options.allowPrivateAddress === true ? (0, _fedify_vocab_runtime_internal.openDirectFetch)(hopUrl) : (0, _fedify_vocab_runtime_internal.openPublicFetch)(hopUrl, { signal: options.signal }));
+	let redirected = 0;
+	while (true) {
+		logger.debug("Fetching WebFinger resource descriptor from {url}...", { url: url.href });
+		const remoteHost = url.host;
+		const session = await openSession(url, openHop, options.signal);
+		if (session == null) return {
+			resource: null,
+			result: "network_error",
+			remoteHost
+		};
+		let hop;
+		try {
+			hop = await fetchHop(session, url, options);
+		} finally {
+			await session.close();
+		}
+		if ("outcome" in hop) return hop.outcome;
+		redirected++;
+		const maxRedirection = options.maxRedirection ?? DEFAULT_MAX_REDIRECTION;
+		if (redirected > maxRedirection) {
+			logger.error("Too many redirections ({redirections}) while fetching WebFinger resource descriptor.", { redirections: redirected });
+			return {
+				resource: null,
+				result: "invalid",
+				statusCode: hop.statusCode,
+				remoteHost
+			};
+		}
+		let redirectedUrl;
+		try {
+			redirectedUrl = new URL(hop.redirect, url);
+		} catch (error) {
+			logger.error("Invalid Location header while following WebFinger redirect: {error}", {
+				url: url.href,
+				error
+			});
+			return {
+				resource: null,
+				result: "invalid",
+				statusCode: hop.statusCode,
+				remoteHost
+			};
+		}
+		if (redirectedUrl.protocol !== url.protocol) {
+			logger.error("Redirected to a different protocol ({protocol} to {redirectedProtocol}) while fetching WebFinger resource descriptor.", {
+				protocol: url.protocol,
+				redirectedProtocol: redirectedUrl.protocol
+			});
+			return {
+				resource: null,
+				result: "invalid",
+				statusCode: hop.statusCode,
+				remoteHost
+			};
+		}
+		url = redirectedUrl;
+	}
+}
+/**
+* Opens a fetch session for a hop.  A disallowed URL, a failed DNS lookup,
+* or an aborted lookup yields `null` instead of an error.
+*/
+async function openSession(url, openHop, signal) {
+	try {
+		return await openHop(url.href);
+	} catch (e) {
+		if (e instanceof _fedify_vocab_runtime.UrlError) {
+			if (e.reason === "dns") logger.debug("DNS lookup failed for {url}", {
+				url: url.href,
+				error: e
+			});
+			else logger.error("Invalid URL for WebFinger resource descriptor: {error}", { error: e });
+			return null;
+		}
+		if (signal?.aborted) {
+			logger.debug("Failed to fetch WebFinger resource descriptor: {error}", {
+				url: url.href,
+				error: e
+			});
+			return null;
+		}
+		throw e;
+	}
+}
+/**
+* Fetches a hop with the given session, and consumes the response body or
+* starts cancelling it before returning.  The caller closes the session.
+*/
+async function fetchHop(session, url, options) {
+	let response;
+	try {
+		response = await session.fetch(url, {
+			headers: {
+				Accept: "application/jrd+json",
+				"User-Agent": typeof options.userAgent === "string" ? options.userAgent : (0, _fedify_vocab_runtime.getUserAgent)(options.userAgent)
+			},
+			redirect: "manual",
+			signal: options.signal
+		});
+	} catch (error) {
+		logger.debug("Failed to fetch WebFinger resource descriptor: {error}", {
+			url: url.href,
+			error
+		});
+		return { outcome: {
+			resource: null,
+			result: "network_error",
+			remoteHost: url.host
+		} };
+	}
+	if (response.status >= 300 && response.status < 400 && response.headers.has("Location")) {
+		cancelBody(response, url);
+		return {
+			redirect: response.headers.get("Location"),
+			statusCode: response.status
+		};
+	}
+	if (!response.ok) {
+		logger.debug("Failed to fetch WebFinger resource descriptor: {status} {statusText}.", {
+			url: url.href,
+			status: response.status,
+			statusText: response.statusText
+		});
+		cancelBody(response, url);
+		return { outcome: {
+			resource: null,
+			result: response.status === 404 || response.status === 410 ? "not_found" : "error",
+			statusCode: response.status,
+			remoteHost: url.host
+		} };
+	}
+	try {
+		return { outcome: {
+			resource: JSON.parse(await readBoundedText(response, MAX_BODY_SIZE, url)),
+			result: "found",
+			statusCode: response.status,
+			remoteHost: url.host
+		} };
+	} catch (e) {
+		if (e instanceof BodyTooLargeError) return { outcome: {
+			resource: null,
+			result: "invalid",
+			statusCode: response.status,
+			remoteHost: url.host
+		} };
+		if (e instanceof SyntaxError) {
+			logger.debug("Failed to parse WebFinger resource descriptor as JSON: {error}", { error: e });
+			return { outcome: {
+				resource: null,
+				result: "invalid",
+				statusCode: response.status,
+				remoteHost: url.host
+			} };
+		}
+		throw e;
+	}
+}
+/**
+* Starts cancelling a response body that is not read, 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.  A failure is
+* only logged.
+*/
+function cancelBody(response, url) {
+	response.body?.cancel().catch((error) => {
+		logger.debug("Failed to cancel the response body from {url}: {error}", {
+			url: url.href,
+			error
+		});
+	});
+}
+//#endregion
+//#region src/lookup.ts
 const WEBFINGER_HISTOGRAM_BUCKETS = [
 	5,
 	10,
@@ -147,6 +358,14 @@ function getMetricResourceScheme(scheme) {
 * @since 0.2.0
 */
 async function lookupWebFinger(resource, options = {}) {
+	return await lookupWebFingerWithDependencies(resource, options);
+}
+/**
+* The lookup implementation with injectable hop sessions for tests.
+* Not exported from the package entry point.
+* @internal
+*/
+async function lookupWebFingerWithDependencies(resource, options = {}, deps = {}) {
 	const tracer = (options.tracerProvider ?? _opentelemetry_api.trace.getTracerProvider()).getTracer(name, version);
 	const scheme = getResourceScheme(resource);
 	return await tracer.startActiveSpan("webfinger.lookup", {
@@ -163,7 +382,7 @@ async function lookupWebFinger(resource, options = {}) {
 			result: "error"
 		};
 		try {
-			outcome = await lookupWebFingerInternal(resource, options);
+			outcome = await lookupWebFingerInternal(resource, options, deps);
 			span.setStatus({ code: outcome.resource === null ? _opentelemetry_api.SpanStatusCode.ERROR : _opentelemetry_api.SpanStatusCode.OK });
 			return outcome.resource;
 		} catch (error) {
@@ -189,154 +408,6 @@ function recordWebFingerLookup(meterProvider, durationMs, scheme, outcome) {
 	instruments.lookup.add(1, attributes);
 	instruments.lookupDuration.record(durationMs, attributes);
 }
-async function lookupWebFingerInternal(resource, options = {}) {
-	if (typeof resource === "string") resource = new URL(resource);
-	let protocol = "https:";
-	let server;
-	if (resource.protocol === "acct:" || resource.protocol === "mailto:") {
-		const atPos = resource.pathname.lastIndexOf("@");
-		if (atPos < 0) return {
-			resource: null,
-			result: "invalid"
-		};
-		server = resource.pathname.substring(atPos + 1);
-		if (server === "" || /[/?#]/.test(server)) return {
-			resource: null,
-			result: "invalid"
-		};
-		if (resource.protocol === "acct:" && (resource.search !== "" || resource.hash !== "")) return {
-			resource: null,
-			result: "invalid"
-		};
-	} else {
-		protocol = resource.protocol;
-		server = resource.host;
-	}
-	let url = new URL(`${protocol}//${server}/.well-known/webfinger`);
-	url.searchParams.set("resource", resource.href);
-	let redirected = 0;
-	while (true) {
-		const remoteHost = url.host;
-		logger.debug("Fetching WebFinger resource descriptor from {url}...", { url: url.href });
-		let response;
-		if (options.allowPrivateAddress !== true) try {
-			await (0, _fedify_vocab_runtime.validatePublicUrl)(url.href);
-		} catch (e) {
-			if (e instanceof _fedify_vocab_runtime.UrlError) {
-				if (e.reason === "dns") logger.debug("DNS lookup failed for {url}", {
-					url: url.href,
-					error: e
-				});
-				else logger.error("Invalid URL for WebFinger resource descriptor: {error}", { error: e });
-				return {
-					resource: null,
-					result: "network_error",
-					remoteHost
-				};
-			}
-			throw e;
-		}
-		try {
-			response = await fetch(url, {
-				headers: {
-					Accept: "application/jrd+json",
-					"User-Agent": typeof options.userAgent === "string" ? options.userAgent : (0, _fedify_vocab_runtime.getUserAgent)(options.userAgent)
-				},
-				redirect: "manual",
-				signal: options.signal
-			});
-		} catch (error) {
-			logger.debug("Failed to fetch WebFinger resource descriptor: {error}", {
-				url: url.href,
-				error
-			});
-			return {
-				resource: null,
-				result: "network_error",
-				remoteHost
-			};
-		}
-		if (response.status >= 300 && response.status < 400 && response.headers.has("Location")) {
-			redirected++;
-			const maxRedirection = options.maxRedirection ?? DEFAULT_MAX_REDIRECTION;
-			if (redirected > maxRedirection) {
-				logger.error("Too many redirections ({redirections}) while fetching WebFinger resource descriptor.", { redirections: redirected });
-				return {
-					resource: null,
-					result: "invalid",
-					statusCode: response.status,
-					remoteHost
-				};
-			}
-			let redirectedUrl;
-			try {
-				redirectedUrl = new URL(response.headers.get("Location"), response.url == null || response.url === "" ? url : response.url);
-			} catch (e) {
-				logger.error("Invalid Location header while following WebFinger redirect: {error}", {
-					url: url.href,
-					error: e
-				});
-				return {
-					resource: null,
-					result: "invalid",
-					statusCode: response.status,
-					remoteHost
-				};
-			}
-			if (redirectedUrl.protocol !== url.protocol) {
-				logger.error("Redirected to a different protocol ({protocol} to {redirectedProtocol}) while fetching WebFinger resource descriptor.", {
-					protocol: url.protocol,
-					redirectedProtocol: redirectedUrl.protocol
-				});
-				return {
-					resource: null,
-					result: "invalid",
-					statusCode: response.status,
-					remoteHost
-				};
-			}
-			url = redirectedUrl;
-			continue;
-		}
-		if (!response.ok) {
-			logger.debug("Failed to fetch WebFinger resource descriptor: {status} {statusText}.", {
-				url: url.href,
-				status: response.status,
-				statusText: response.statusText
-			});
-			return {
-				resource: null,
-				result: response.status === 404 || response.status === 410 ? "not_found" : "error",
-				statusCode: response.status,
-				remoteHost
-			};
-		}
-		try {
-			return {
-				resource: JSON.parse(await readBoundedText(response, MAX_BODY_SIZE, url)),
-				result: "found",
-				statusCode: response.status,
-				remoteHost
-			};
-		} catch (e) {
-			if (e instanceof BodyTooLargeError) return {
-				resource: null,
-				result: "invalid",
-				statusCode: response.status,
-				remoteHost
-			};
-			if (e instanceof SyntaxError) {
-				logger.debug("Failed to parse WebFinger resource descriptor as JSON: {error}", { error: e });
-				return {
-					resource: null,
-					result: "invalid",
-					statusCode: response.status,
-					remoteHost
-				};
-			}
-			throw e;
-		}
-	}
-}
 //#endregion
 exports.lookupWebFinger = lookupWebFinger;
+exports.lookupWebFingerWithDependencies = lookupWebFingerWithDependencies;

package/dist/mod.d.cts

@@ -1,5 +1,6 @@
 import { GetUserAgentOptions } from "@fedify/vocab-runtime";
 import { MeterProvider, TracerProvider } from "@opentelemetry/api";
+import { PublicFetchSession } from "@fedify/vocab-runtime/internal";
 
 //#region src/jrd.d.ts
 /**
@@ -61,6 +62,19 @@ interface Link {
   readonly template?: string;
 }
 //#endregion
+//#region src/lookup-impl.d.ts
+/**
+* The dependencies of {@link lookupWebFingerInternal}.
+* @internal
+*/
+interface LookupWebFingerDependencies {
+  /**
+  * Opens a fetch session for a single hop.  Defaults to `openDirectFetch()`
+  * if `allowPrivateAddress` is turned on, or `openPublicFetch()` otherwise.
+  */
+  readonly openHop?: (url: string) => Promise<PublicFetchSession>;
+}
+//#endregion
 //#region src/lookup.d.ts
 /**
 * The terminal classification of an outgoing {@link lookupWebFinger} call,
@@ -84,6 +98,12 @@ interface Link {
 * @since 2.3.0
 */
 type WebFingerLookupResult = "found" | "not_found" | "invalid" | "network_error" | "error";
+interface WebFingerLookupOutcome {
+  resource: ResourceDescriptor | null;
+  result: WebFingerLookupResult;
+  statusCode?: number;
+  remoteHost?: string;
+}
 /**
 * Options for {@link lookupWebFinger}.
 * @since 1.3.0
@@ -139,5 +159,11 @@ interface LookupWebFingerOptions {
 * @since 0.2.0
 */
 declare function lookupWebFinger(resource: URL | string, options?: LookupWebFingerOptions): Promise<ResourceDescriptor | null>;
+/**
+* The lookup implementation with injectable hop sessions for tests.
+* Not exported from the package entry point.
+* @internal
+*/
+declare function lookupWebFingerWithDependencies(resource: URL | string, options?: LookupWebFingerOptions, deps?: LookupWebFingerDependencies): Promise<ResourceDescriptor | null>;
 //#endregion
-export { Link, LookupWebFingerOptions, ResourceDescriptor, WebFingerLookupResult, lookupWebFinger };
+export { Link, LookupWebFingerOptions, ResourceDescriptor, WebFingerLookupOutcome, WebFingerLookupResult, lookupWebFinger, lookupWebFingerWithDependencies };

package/dist/mod.d.ts

@@ -1,5 +1,6 @@
-import { GetUserAgentOptions } from "@fedify/vocab-runtime";
 import { MeterProvider, TracerProvider } from "@opentelemetry/api";
+import { GetUserAgentOptions } from "@fedify/vocab-runtime";
+import { PublicFetchSession } from "@fedify/vocab-runtime/internal";
 
 //#region src/jrd.d.ts
 /**
@@ -61,6 +62,19 @@ interface Link {
   readonly template?: string;
 }
 //#endregion
+//#region src/lookup-impl.d.ts
+/**
+* The dependencies of {@link lookupWebFingerInternal}.
+* @internal
+*/
+interface LookupWebFingerDependencies {
+  /**
+  * Opens a fetch session for a single hop.  Defaults to `openDirectFetch()`
+  * if `allowPrivateAddress` is turned on, or `openPublicFetch()` otherwise.
+  */
+  readonly openHop?: (url: string) => Promise<PublicFetchSession>;
+}
+//#endregion
 //#region src/lookup.d.ts
 /**
 * The terminal classification of an outgoing {@link lookupWebFinger} call,
@@ -84,6 +98,12 @@ interface Link {
 * @since 2.3.0
 */
 type WebFingerLookupResult = "found" | "not_found" | "invalid" | "network_error" | "error";
+interface WebFingerLookupOutcome {
+  resource: ResourceDescriptor | null;
+  result: WebFingerLookupResult;
+  statusCode?: number;
+  remoteHost?: string;
+}
 /**
 * Options for {@link lookupWebFinger}.
 * @since 1.3.0
@@ -139,5 +159,11 @@ interface LookupWebFingerOptions {
 * @since 0.2.0
 */
 declare function lookupWebFinger(resource: URL | string, options?: LookupWebFingerOptions): Promise<ResourceDescriptor | null>;
+/**
+* The lookup implementation with injectable hop sessions for tests.
+* Not exported from the package entry point.
+* @internal
+*/
+declare function lookupWebFingerWithDependencies(resource: URL | string, options?: LookupWebFingerOptions, deps?: LookupWebFingerDependencies): Promise<ResourceDescriptor | null>;
 //#endregion
-export { Link, LookupWebFingerOptions, ResourceDescriptor, WebFingerLookupResult, lookupWebFinger };
+export { Link, LookupWebFingerOptions, ResourceDescriptor, WebFingerLookupOutcome, WebFingerLookupResult, lookupWebFinger, lookupWebFingerWithDependencies };