@fedify/webfinger 2.5.0-dev.2432 → 2.5.0-dev.2446

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/webfinger",
-  "version": "2.5.0-dev.2432+f56118e1",
+  "version": "2.5.0-dev.2446+2014cb03",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts"

package/dist/lookup.test.cjs

@@ -1237,7 +1237,7 @@ var esm_default = new class FetchMock {
 //#endregion
 //#region deno.json
 var name = "@fedify/webfinger";
-var version = "2.5.0-dev.2432+f56118e1";
+var version = "2.5.0-dev.2446+2014cb03";
 //#endregion
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */
@@ -1372,13 +1372,6 @@ const WEBFINGER_LOOKUP_SCHEME_WHITELIST = /* @__PURE__ */ new Set([
 function getMetricResourceScheme(scheme) {
 	return WEBFINGER_LOOKUP_SCHEME_WHITELIST.has(scheme) ? scheme : "other";
 }
-/**
-* Looks up a WebFinger resource.
-* @param resource The resource URL to look up.
-* @param options Extra options for looking up the resource.
-* @returns The resource descriptor, or `null` if not found.
-* @since 0.2.0
-*/
 async function lookupWebFinger(resource, options = {}) {
 	const tracer = (options.tracerProvider ?? _opentelemetry_api.trace.getTracerProvider()).getTracer(name, version);
 	const scheme = getResourceScheme(resource);
@@ -1398,7 +1391,7 @@ async function lookupWebFinger(resource, options = {}) {
 		try {
 			outcome = await lookupWebFingerInternal(resource, options);
 			span.setStatus({ code: outcome.resource === null ? _opentelemetry_api.SpanStatusCode.ERROR : _opentelemetry_api.SpanStatusCode.OK });
-			return outcome.resource;
+			return options.withDiagnostics ? outcome : outcome.resource;
 		} catch (error) {
 			span.setStatus({
 				code: _opentelemetry_api.SpanStatusCode.ERROR,
@@ -1545,8 +1538,15 @@ async function lookupWebFingerInternal(resource, options = {}) {
 			};
 		}
 		try {
+			const parsed = JSON.parse(await readBoundedText(response, MAX_BODY_SIZE, url));
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+				resource: null,
+				result: "invalid",
+				statusCode: response.status,
+				remoteHost
+			};
 			return {
-				resource: JSON.parse(await readBoundedText(response, MAX_BODY_SIZE, url)),
+				resource: parsed,
 				result: "found",
 				statusCode: response.status,
 				remoteHost
@@ -2040,4 +2040,93 @@ async function lookupWebFingerInternal(resource, options = {}) {
 		}
 	});
 });
+(0, _fedify_fixture.test)("lookupWebFinger() with withDiagnostics: true", {
+	sanitizeOps: false,
+	sanitizeResources: false
+}, async (t) => {
+	await t.step("network_error", async () => {
+		const outcome = await lookupWebFinger("acct:johndoe@fedify-test.internal", { withDiagnostics: true });
+		(0, node_assert_strict.deepStrictEqual)(outcome.resource, null);
+		(0, node_assert_strict.deepStrictEqual)(outcome.result, "network_error");
+		(0, node_assert_strict.deepStrictEqual)("statusCode" in outcome, false, "no HTTP response means no status code");
+	});
+	esm_default.spyGlobal();
+	try {
+		await t.step("found", async () => {
+			esm_default.removeRoutes();
+			const expected = {
+				subject: "acct:johndoe@example.com",
+				links: []
+			};
+			esm_default.get("https://example.com/.well-known/webfinger?resource=acct%3Ajohndoe%40example.com", { body: expected });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			(0, node_assert_strict.deepStrictEqual)(outcome.resource, expected);
+			(0, node_assert_strict.deepStrictEqual)(outcome.result, "found");
+			(0, node_assert_strict.deepStrictEqual)(outcome.statusCode, 200);
+			(0, node_assert_strict.deepStrictEqual)(outcome.remoteHost, "example.com");
+		});
+		await t.step("not_found", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger?", { status: 404 });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			(0, node_assert_strict.deepStrictEqual)(outcome.resource, null);
+			(0, node_assert_strict.deepStrictEqual)(outcome.result, "not_found");
+			(0, node_assert_strict.deepStrictEqual)(outcome.statusCode, 404);
+			(0, node_assert_strict.deepStrictEqual)(outcome.remoteHost, "example.com");
+		});
+		await t.step("invalid", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger?", { body: "not json" });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			(0, node_assert_strict.deepStrictEqual)(outcome.resource, null);
+			(0, node_assert_strict.deepStrictEqual)(outcome.result, "invalid");
+			(0, node_assert_strict.deepStrictEqual)(outcome.statusCode, 200);
+			(0, node_assert_strict.deepStrictEqual)(outcome.remoteHost, "example.com");
+		});
+		await t.step("invalid: a literal JSON null body is not a resource descriptor", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger?", { body: "null" });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			(0, node_assert_strict.deepStrictEqual)(outcome.resource, null);
+			(0, node_assert_strict.deepStrictEqual)(outcome.result, "invalid");
+			(0, node_assert_strict.deepStrictEqual)(outcome.statusCode, 200);
+			(0, node_assert_strict.deepStrictEqual)(outcome.remoteHost, "example.com");
+		});
+		await t.step("invalid: a JSON array body is not a resource descriptor", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger?", { body: "[]" });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			(0, node_assert_strict.deepStrictEqual)(outcome.resource, null);
+			(0, node_assert_strict.deepStrictEqual)(outcome.result, "invalid");
+			(0, node_assert_strict.deepStrictEqual)(outcome.statusCode, 200);
+			(0, node_assert_strict.deepStrictEqual)(outcome.remoteHost, "example.com");
+		});
+		await t.step("error", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger?", { status: 500 });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			(0, node_assert_strict.deepStrictEqual)(outcome.resource, null);
+			(0, node_assert_strict.deepStrictEqual)(outcome.result, "error");
+			(0, node_assert_strict.deepStrictEqual)(outcome.statusCode, 500);
+			(0, node_assert_strict.deepStrictEqual)(outcome.remoteHost, "example.com");
+		});
+	} finally {
+		esm_default.removeRoutes();
+		esm_default.hardReset();
+	}
+});
+(0, _fedify_fixture.test)("lookupWebFinger() accepts a plain LookupWebFingerOptions-typed variable", async () => {
+	esm_default.spyGlobal();
+	try {
+		const expected = {
+			subject: "acct:johndoe@example.com",
+			links: []
+		};
+		esm_default.get("https://example.com/.well-known/webfinger?resource=acct%3Ajohndoe%40example.com", { body: expected });
+		(0, node_assert_strict.deepStrictEqual)(await lookupWebFinger("acct:johndoe@example.com", { userAgent: "test-agent" }), expected);
+	} finally {
+		esm_default.removeRoutes();
+		esm_default.hardReset();
+	}
+});
 //#endregion

package/dist/lookup.test.js

@@ -1235,7 +1235,7 @@ var esm_default = new class FetchMock {
 //#endregion
 //#region deno.json
 var name = "@fedify/webfinger";
-var version = "2.5.0-dev.2432+f56118e1";
+var version = "2.5.0-dev.2446+2014cb03";
 //#endregion
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */
@@ -1370,13 +1370,6 @@ const WEBFINGER_LOOKUP_SCHEME_WHITELIST = /* @__PURE__ */ new Set([
 function getMetricResourceScheme(scheme) {
 	return WEBFINGER_LOOKUP_SCHEME_WHITELIST.has(scheme) ? scheme : "other";
 }
-/**
-* Looks up a WebFinger resource.
-* @param resource The resource URL to look up.
-* @param options Extra options for looking up the resource.
-* @returns The resource descriptor, or `null` if not found.
-* @since 0.2.0
-*/
 async function lookupWebFinger(resource, options = {}) {
 	const tracer = (options.tracerProvider ?? trace.getTracerProvider()).getTracer(name, version);
 	const scheme = getResourceScheme(resource);
@@ -1396,7 +1389,7 @@ async function lookupWebFinger(resource, options = {}) {
 		try {
 			outcome = await lookupWebFingerInternal(resource, options);
 			span.setStatus({ code: outcome.resource === null ? SpanStatusCode.ERROR : SpanStatusCode.OK });
-			return outcome.resource;
+			return options.withDiagnostics ? outcome : outcome.resource;
 		} catch (error) {
 			span.setStatus({
 				code: SpanStatusCode.ERROR,
@@ -1543,8 +1536,15 @@ async function lookupWebFingerInternal(resource, options = {}) {
 			};
 		}
 		try {
+			const parsed = JSON.parse(await readBoundedText(response, MAX_BODY_SIZE, url));
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+				resource: null,
+				result: "invalid",
+				statusCode: response.status,
+				remoteHost
+			};
 			return {
-				resource: JSON.parse(await readBoundedText(response, MAX_BODY_SIZE, url)),
+				resource: parsed,
 				result: "found",
 				statusCode: response.status,
 				remoteHost
@@ -2038,5 +2038,94 @@ test("lookupWebFinger() logs DNS failures as such", async (t) => {
 		}
 	});
 });
+test("lookupWebFinger() with withDiagnostics: true", {
+	sanitizeOps: false,
+	sanitizeResources: false
+}, async (t) => {
+	await t.step("network_error", async () => {
+		const outcome = await lookupWebFinger("acct:johndoe@fedify-test.internal", { withDiagnostics: true });
+		deepStrictEqual(outcome.resource, null);
+		deepStrictEqual(outcome.result, "network_error");
+		deepStrictEqual("statusCode" in outcome, false, "no HTTP response means no status code");
+	});
+	esm_default.spyGlobal();
+	try {
+		await t.step("found", async () => {
+			esm_default.removeRoutes();
+			const expected = {
+				subject: "acct:johndoe@example.com",
+				links: []
+			};
+			esm_default.get("https://example.com/.well-known/webfinger?resource=acct%3Ajohndoe%40example.com", { body: expected });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			deepStrictEqual(outcome.resource, expected);
+			deepStrictEqual(outcome.result, "found");
+			deepStrictEqual(outcome.statusCode, 200);
+			deepStrictEqual(outcome.remoteHost, "example.com");
+		});
+		await t.step("not_found", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger?", { status: 404 });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			deepStrictEqual(outcome.resource, null);
+			deepStrictEqual(outcome.result, "not_found");
+			deepStrictEqual(outcome.statusCode, 404);
+			deepStrictEqual(outcome.remoteHost, "example.com");
+		});
+		await t.step("invalid", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger?", { body: "not json" });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			deepStrictEqual(outcome.resource, null);
+			deepStrictEqual(outcome.result, "invalid");
+			deepStrictEqual(outcome.statusCode, 200);
+			deepStrictEqual(outcome.remoteHost, "example.com");
+		});
+		await t.step("invalid: a literal JSON null body is not a resource descriptor", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger?", { body: "null" });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			deepStrictEqual(outcome.resource, null);
+			deepStrictEqual(outcome.result, "invalid");
+			deepStrictEqual(outcome.statusCode, 200);
+			deepStrictEqual(outcome.remoteHost, "example.com");
+		});
+		await t.step("invalid: a JSON array body is not a resource descriptor", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger?", { body: "[]" });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			deepStrictEqual(outcome.resource, null);
+			deepStrictEqual(outcome.result, "invalid");
+			deepStrictEqual(outcome.statusCode, 200);
+			deepStrictEqual(outcome.remoteHost, "example.com");
+		});
+		await t.step("error", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger?", { status: 500 });
+			const outcome = await lookupWebFinger("acct:johndoe@example.com", { withDiagnostics: true });
+			deepStrictEqual(outcome.resource, null);
+			deepStrictEqual(outcome.result, "error");
+			deepStrictEqual(outcome.statusCode, 500);
+			deepStrictEqual(outcome.remoteHost, "example.com");
+		});
+	} finally {
+		esm_default.removeRoutes();
+		esm_default.hardReset();
+	}
+});
+test("lookupWebFinger() accepts a plain LookupWebFingerOptions-typed variable", async () => {
+	esm_default.spyGlobal();
+	try {
+		const expected = {
+			subject: "acct:johndoe@example.com",
+			links: []
+		};
+		esm_default.get("https://example.com/.well-known/webfinger?resource=acct%3Ajohndoe%40example.com", { body: expected });
+		deepStrictEqual(await lookupWebFinger("acct:johndoe@example.com", { userAgent: "test-agent" }), expected);
+	} finally {
+		esm_default.removeRoutes();
+		esm_default.hardReset();
+	}
+});
 //#endregion
 export {};

package/dist/mod.cjs

@@ -4,7 +4,7 @@ let _logtape_logtape = require("@logtape/logtape");
 let _opentelemetry_api = require("@opentelemetry/api");
 //#region deno.json
 var name = "@fedify/webfinger";
-var version = "2.5.0-dev.2432+f56118e1";
+var version = "2.5.0-dev.2446+2014cb03";
 //#endregion
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */
@@ -139,13 +139,6 @@ const WEBFINGER_LOOKUP_SCHEME_WHITELIST = /* @__PURE__ */ new Set([
 function getMetricResourceScheme(scheme) {
 	return WEBFINGER_LOOKUP_SCHEME_WHITELIST.has(scheme) ? scheme : "other";
 }
-/**
-* Looks up a WebFinger resource.
-* @param resource The resource URL to look up.
-* @param options Extra options for looking up the resource.
-* @returns The resource descriptor, or `null` if not found.
-* @since 0.2.0
-*/
 async function lookupWebFinger(resource, options = {}) {
 	const tracer = (options.tracerProvider ?? _opentelemetry_api.trace.getTracerProvider()).getTracer(name, version);
 	const scheme = getResourceScheme(resource);
@@ -165,7 +158,7 @@ async function lookupWebFinger(resource, options = {}) {
 		try {
 			outcome = await lookupWebFingerInternal(resource, options);
 			span.setStatus({ code: outcome.resource === null ? _opentelemetry_api.SpanStatusCode.ERROR : _opentelemetry_api.SpanStatusCode.OK });
-			return outcome.resource;
+			return options.withDiagnostics ? outcome : outcome.resource;
 		} catch (error) {
 			span.setStatus({
 				code: _opentelemetry_api.SpanStatusCode.ERROR,
@@ -312,8 +305,15 @@ async function lookupWebFingerInternal(resource, options = {}) {
 			};
 		}
 		try {
+			const parsed = JSON.parse(await readBoundedText(response, MAX_BODY_SIZE, url));
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+				resource: null,
+				result: "invalid",
+				statusCode: response.status,
+				remoteHost
+			};
 			return {
-				resource: JSON.parse(await readBoundedText(response, MAX_BODY_SIZE, url)),
+				resource: parsed,
 				result: "found",
 				statusCode: response.status,
 				remoteHost

package/dist/mod.d.cts

@@ -85,6 +85,32 @@ interface Link {
 */
 type WebFingerLookupResult = "found" | "not_found" | "invalid" | "network_error" | "error";
 /**
+* The outcome of a {@link lookupWebFinger} call, returned in place of the
+* plain {@link ResourceDescriptor} when `options.withDiagnostics` is `true`.
+* @since 2.5.0
+*/
+interface WebFingerLookupOutcome {
+  /**
+  * The resource descriptor fetched from the remote WebFinger endpoint, or
+  * `null` if the lookup did not succeed.
+  */
+  resource: ResourceDescriptor | null;
+  /**
+  * The terminal classification of the lookup.  See
+  * {@link WebFingerLookupResult} for what each value means.
+  */
+  result: WebFingerLookupResult;
+  /**
+  * The HTTP status code of the final response, if a response was received
+  * from the remote server.
+  */
+  statusCode?: number;
+  /**
+  * The host of the final URL the lookup attempted to reach.
+  */
+  remoteHost?: string;
+}
+/**
 * Options for {@link lookupWebFinger}.
 * @since 1.3.0
 */
@@ -138,6 +164,31 @@ interface LookupWebFingerOptions {
 * @returns The resource descriptor, or `null` if not found.
 * @since 0.2.0
 */
-declare function lookupWebFinger(resource: URL | string, options?: LookupWebFingerOptions): Promise<ResourceDescriptor | null>;
+declare function lookupWebFinger(resource: URL | string, options?: LookupWebFingerOptions & {
+  /**
+  * Whether to return a {@link WebFingerLookupOutcome} describing why
+  * the lookup failed, instead of collapsing every failure into `null`.
+  * Turned off by default.
+  * @since 2.5.0
+  */
+  withDiagnostics?: false;
+}): Promise<ResourceDescriptor | null>;
+/**
+* Looks up a WebFinger resource, returning diagnostics that explain why the
+* lookup failed instead of collapsing every failure into `null`.
+* @param resource The resource URL to look up.
+* @param options Extra options for looking up the resource.  Must set
+*                `withDiagnostics: true`.
+* @returns The outcome of the lookup.
+* @since 2.5.0
+*/
+declare function lookupWebFinger(resource: URL | string, options: LookupWebFingerOptions & {
+  /**
+  * Returns a {@link WebFingerLookupOutcome} instead of a plain
+  * {@link ResourceDescriptor}.
+  * @since 2.5.0
+  */
+  withDiagnostics: true;
+}): Promise<WebFingerLookupOutcome>;
 //#endregion
-export { Link, LookupWebFingerOptions, ResourceDescriptor, WebFingerLookupResult, lookupWebFinger };
+export { Link, LookupWebFingerOptions, ResourceDescriptor, WebFingerLookupOutcome, WebFingerLookupResult, lookupWebFinger };

package/dist/mod.d.ts

@@ -85,6 +85,32 @@ interface Link {
 */
 type WebFingerLookupResult = "found" | "not_found" | "invalid" | "network_error" | "error";
 /**
+* The outcome of a {@link lookupWebFinger} call, returned in place of the
+* plain {@link ResourceDescriptor} when `options.withDiagnostics` is `true`.
+* @since 2.5.0
+*/
+interface WebFingerLookupOutcome {
+  /**
+  * The resource descriptor fetched from the remote WebFinger endpoint, or
+  * `null` if the lookup did not succeed.
+  */
+  resource: ResourceDescriptor | null;
+  /**
+  * The terminal classification of the lookup.  See
+  * {@link WebFingerLookupResult} for what each value means.
+  */
+  result: WebFingerLookupResult;
+  /**
+  * The HTTP status code of the final response, if a response was received
+  * from the remote server.
+  */
+  statusCode?: number;
+  /**
+  * The host of the final URL the lookup attempted to reach.
+  */
+  remoteHost?: string;
+}
+/**
 * Options for {@link lookupWebFinger}.
 * @since 1.3.0
 */
@@ -138,6 +164,31 @@ interface LookupWebFingerOptions {
 * @returns The resource descriptor, or `null` if not found.
 * @since 0.2.0
 */
-declare function lookupWebFinger(resource: URL | string, options?: LookupWebFingerOptions): Promise<ResourceDescriptor | null>;
+declare function lookupWebFinger(resource: URL | string, options?: LookupWebFingerOptions & {
+  /**
+  * Whether to return a {@link WebFingerLookupOutcome} describing why
+  * the lookup failed, instead of collapsing every failure into `null`.
+  * Turned off by default.
+  * @since 2.5.0
+  */
+  withDiagnostics?: false;
+}): Promise<ResourceDescriptor | null>;
+/**
+* Looks up a WebFinger resource, returning diagnostics that explain why the
+* lookup failed instead of collapsing every failure into `null`.
+* @param resource The resource URL to look up.
+* @param options Extra options for looking up the resource.  Must set
+*                `withDiagnostics: true`.
+* @returns The outcome of the lookup.
+* @since 2.5.0
+*/
+declare function lookupWebFinger(resource: URL | string, options: LookupWebFingerOptions & {
+  /**
+  * Returns a {@link WebFingerLookupOutcome} instead of a plain
+  * {@link ResourceDescriptor}.
+  * @since 2.5.0
+  */
+  withDiagnostics: true;
+}): Promise<WebFingerLookupOutcome>;
 //#endregion
-export { Link, LookupWebFingerOptions, ResourceDescriptor, WebFingerLookupResult, lookupWebFinger };
+export { Link, LookupWebFingerOptions, ResourceDescriptor, WebFingerLookupOutcome, WebFingerLookupResult, lookupWebFinger };

package/dist/mod.js

@@ -3,7 +3,7 @@ import { getLogger } from "@logtape/logtape";
 import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 //#region deno.json
 var name = "@fedify/webfinger";
-var version = "2.5.0-dev.2432+f56118e1";
+var version = "2.5.0-dev.2446+2014cb03";
 //#endregion
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */
@@ -138,13 +138,6 @@ const WEBFINGER_LOOKUP_SCHEME_WHITELIST = /* @__PURE__ */ new Set([
 function getMetricResourceScheme(scheme) {
 	return WEBFINGER_LOOKUP_SCHEME_WHITELIST.has(scheme) ? scheme : "other";
 }
-/**
-* Looks up a WebFinger resource.
-* @param resource The resource URL to look up.
-* @param options Extra options for looking up the resource.
-* @returns The resource descriptor, or `null` if not found.
-* @since 0.2.0
-*/
 async function lookupWebFinger(resource, options = {}) {
 	const tracer = (options.tracerProvider ?? trace.getTracerProvider()).getTracer(name, version);
 	const scheme = getResourceScheme(resource);
@@ -164,7 +157,7 @@ async function lookupWebFinger(resource, options = {}) {
 		try {
 			outcome = await lookupWebFingerInternal(resource, options);
 			span.setStatus({ code: outcome.resource === null ? SpanStatusCode.ERROR : SpanStatusCode.OK });
-			return outcome.resource;
+			return options.withDiagnostics ? outcome : outcome.resource;
 		} catch (error) {
 			span.setStatus({
 				code: SpanStatusCode.ERROR,
@@ -311,8 +304,15 @@ async function lookupWebFingerInternal(resource, options = {}) {
 			};
 		}
 		try {
+			const parsed = JSON.parse(await readBoundedText(response, MAX_BODY_SIZE, url));
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+				resource: null,
+				result: "invalid",
+				statusCode: response.status,
+				remoteHost
+			};
 			return {
-				resource: JSON.parse(await readBoundedText(response, MAX_BODY_SIZE, url)),
+				resource: parsed,
 				result: "found",
 				statusCode: response.status,
 				remoteHost

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/webfinger",
-  "version": "2.5.0-dev.2432+f56118e1",
+  "version": "2.5.0-dev.2446+2014cb03",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",
@@ -57,7 +57,7 @@
     "@logtape/logtape": "^2.2.0",
     "@opentelemetry/api": "^1.9.1",
     "es-toolkit": "1.46.1",
-    "@fedify/vocab-runtime": "2.5.0-dev.2432+f56118e1"
+    "@fedify/vocab-runtime": "2.5.0-dev.2446+2014cb03"
   },
   "scripts": {
     "build:self": "tsdown",

package/src/lookup.test.ts

@@ -6,7 +6,7 @@ import fetchMock from "fetch-mock";
 import { deepStrictEqual, ok } from "node:assert/strict";
 import dns from "node:dns/promises";
 import type { ResourceDescriptor } from "./jrd.ts";
-import { lookupWebFinger } from "./lookup.ts";
+import { lookupWebFinger, type LookupWebFingerOptions } from "./lookup.ts";
 
 test({
   name: "lookupWebFinger()",
@@ -989,3 +989,167 @@ test("lookupWebFinger() logs DNS failures as such", async (t) => {
     });
   }
 });
+
+test("lookupWebFinger() with withDiagnostics: true", {
+  sanitizeOps: false,
+  sanitizeResources: false,
+}, async (t) => {
+  // No fetch mock is active yet, so this reaches the real (non-existent)
+  // host and fails at the network layer, the same way the "connection
+  // refused" step above does.
+  await t.step("network_error", async () => {
+    const outcome = await lookupWebFinger(
+      "acct:johndoe@fedify-test.internal",
+      { withDiagnostics: true },
+    );
+    deepStrictEqual(outcome.resource, null);
+    deepStrictEqual(outcome.result, "network_error");
+    deepStrictEqual(
+      "statusCode" in outcome,
+      false,
+      "no HTTP response means no status code",
+    );
+  });
+
+  fetchMock.spyGlobal();
+  try {
+    await t.step("found", async () => {
+      fetchMock.removeRoutes();
+      const expected: ResourceDescriptor = {
+        subject: "acct:johndoe@example.com",
+        links: [],
+      };
+      fetchMock.get(
+        "https://example.com/.well-known/webfinger?resource=acct%3Ajohndoe%40example.com",
+        { body: expected },
+      );
+      const outcome = await lookupWebFinger("acct:johndoe@example.com", {
+        withDiagnostics: true,
+      });
+      deepStrictEqual(outcome.resource, expected);
+      deepStrictEqual(outcome.result, "found");
+      deepStrictEqual(outcome.statusCode, 200);
+      deepStrictEqual(outcome.remoteHost, "example.com");
+    });
+
+    await t.step("not_found", async () => {
+      fetchMock.removeRoutes();
+      fetchMock.get(
+        "begin:https://example.com/.well-known/webfinger?",
+        { status: 404 },
+      );
+      const outcome = await lookupWebFinger("acct:johndoe@example.com", {
+        withDiagnostics: true,
+      });
+      deepStrictEqual(outcome.resource, null);
+      deepStrictEqual(outcome.result, "not_found");
+      deepStrictEqual(outcome.statusCode, 404);
+      deepStrictEqual(outcome.remoteHost, "example.com");
+    });
+
+    await t.step("invalid", async () => {
+      fetchMock.removeRoutes();
+      fetchMock.get(
+        "begin:https://example.com/.well-known/webfinger?",
+        { body: "not json" },
+      );
+      const outcome = await lookupWebFinger("acct:johndoe@example.com", {
+        withDiagnostics: true,
+      });
+      deepStrictEqual(outcome.resource, null);
+      deepStrictEqual(outcome.result, "invalid");
+      deepStrictEqual(outcome.statusCode, 200);
+      deepStrictEqual(outcome.remoteHost, "example.com");
+    });
+
+    await t.step(
+      "invalid: a literal JSON null body is not a resource descriptor",
+      async () => {
+        // JSON.parse("null") succeeds and yields the JS value `null`.
+        // Regression test for a server that returns 200 with a literal
+        // `null` body instead of an object: this must not be classified
+        // as "found" with a null resource.
+        fetchMock.removeRoutes();
+        fetchMock.get(
+          "begin:https://example.com/.well-known/webfinger?",
+          { body: "null" },
+        );
+        const outcome = await lookupWebFinger("acct:johndoe@example.com", {
+          withDiagnostics: true,
+        });
+        deepStrictEqual(outcome.resource, null);
+        deepStrictEqual(outcome.result, "invalid");
+        deepStrictEqual(outcome.statusCode, 200);
+        deepStrictEqual(outcome.remoteHost, "example.com");
+      },
+    );
+
+    await t.step(
+      "invalid: a JSON array body is not a resource descriptor",
+      async () => {
+        // typeof [] === "object" and [] !== null, so the null-only guard
+        // above does not catch an array body; it needs its own check.
+        fetchMock.removeRoutes();
+        fetchMock.get(
+          "begin:https://example.com/.well-known/webfinger?",
+          { body: "[]" },
+        );
+        const outcome = await lookupWebFinger("acct:johndoe@example.com", {
+          withDiagnostics: true,
+        });
+        deepStrictEqual(outcome.resource, null);
+        deepStrictEqual(outcome.result, "invalid");
+        deepStrictEqual(outcome.statusCode, 200);
+        deepStrictEqual(outcome.remoteHost, "example.com");
+      },
+    );
+
+    await t.step("error", async () => {
+      fetchMock.removeRoutes();
+      fetchMock.get(
+        "begin:https://example.com/.well-known/webfinger?",
+        { status: 500 },
+      );
+      const outcome = await lookupWebFinger("acct:johndoe@example.com", {
+        withDiagnostics: true,
+      });
+      deepStrictEqual(outcome.resource, null);
+      deepStrictEqual(outcome.result, "error");
+      deepStrictEqual(outcome.statusCode, 500);
+      deepStrictEqual(outcome.remoteHost, "example.com");
+    });
+  } finally {
+    fetchMock.removeRoutes();
+    fetchMock.hardReset();
+  }
+});
+
+test(
+  "lookupWebFinger() accepts a plain LookupWebFingerOptions-typed variable",
+  async () => {
+    // Regression test: a variable typed as `LookupWebFingerOptions`, built
+    // separately from the call site and never mentioning `withDiagnostics`,
+    // must still match the default overload.  This is a type-level
+    // concern; the point of this test is that the file compiles at all.
+    fetchMock.spyGlobal();
+    try {
+      const expected: ResourceDescriptor = {
+        subject: "acct:johndoe@example.com",
+        links: [],
+      };
+      fetchMock.get(
+        "https://example.com/.well-known/webfinger?resource=acct%3Ajohndoe%40example.com",
+        { body: expected },
+      );
+      const options: LookupWebFingerOptions = { userAgent: "test-agent" };
+      const result = await lookupWebFinger(
+        "acct:johndoe@example.com",
+        options,
+      );
+      deepStrictEqual(result, expected);
+    } finally {
+      fetchMock.removeRoutes();
+      fetchMock.hardReset();
+    }
+  },
+);

package/src/lookup.ts

@@ -124,10 +124,33 @@ function getMetricResourceScheme(scheme: string): string {
   return WEBFINGER_LOOKUP_SCHEME_WHITELIST.has(scheme) ? scheme : "other";
 }
 
-interface WebFingerLookupOutcome {
+/**
+ * The outcome of a {@link lookupWebFinger} call, returned in place of the
+ * plain {@link ResourceDescriptor} when `options.withDiagnostics` is `true`.
+ * @since 2.5.0
+ */
+export interface WebFingerLookupOutcome {
+  /**
+   * The resource descriptor fetched from the remote WebFinger endpoint, or
+   * `null` if the lookup did not succeed.
+   */
   resource: ResourceDescriptor | null;
+
+  /**
+   * The terminal classification of the lookup.  See
+   * {@link WebFingerLookupResult} for what each value means.
+   */
   result: WebFingerLookupResult;
+
+  /**
+   * The HTTP status code of the final response, if a response was received
+   * from the remote server.
+   */
   statusCode?: number;
+
+  /**
+   * The host of the final URL the lookup attempted to reach.
+   */
   remoteHost?: string;
 }
 
@@ -193,8 +216,42 @@ export interface LookupWebFingerOptions {
  */
 export async function lookupWebFinger(
   resource: URL | string,
-  options: LookupWebFingerOptions = {},
-): Promise<ResourceDescriptor | null> {
+  options?: LookupWebFingerOptions & {
+    /**
+     * Whether to return a {@link WebFingerLookupOutcome} describing why
+     * the lookup failed, instead of collapsing every failure into `null`.
+     * Turned off by default.
+     * @since 2.5.0
+     */
+    withDiagnostics?: false;
+  },
+): Promise<ResourceDescriptor | null>;
+
+/**
+ * Looks up a WebFinger resource, returning diagnostics that explain why the
+ * lookup failed instead of collapsing every failure into `null`.
+ * @param resource The resource URL to look up.
+ * @param options Extra options for looking up the resource.  Must set
+ *                `withDiagnostics: true`.
+ * @returns The outcome of the lookup.
+ * @since 2.5.0
+ */
+export async function lookupWebFinger(
+  resource: URL | string,
+  options: LookupWebFingerOptions & {
+    /**
+     * Returns a {@link WebFingerLookupOutcome} instead of a plain
+     * {@link ResourceDescriptor}.
+     * @since 2.5.0
+     */
+    withDiagnostics: true;
+  },
+): Promise<WebFingerLookupOutcome>;
+
+export async function lookupWebFinger(
+  resource: URL | string,
+  options: LookupWebFingerOptions & { withDiagnostics?: boolean } = {},
+): Promise<ResourceDescriptor | null | WebFingerLookupOutcome> {
   const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
   const tracer = tracerProvider.getTracer(
     metadata.name,
@@ -228,7 +285,7 @@ export async function lookupWebFinger(
             ? SpanStatusCode.ERROR
             : SpanStatusCode.OK,
         });
-        return outcome.resource;
+        return options.withDiagnostics ? outcome : outcome.resource;
       } catch (error) {
         span.setStatus({
           code: SpanStatusCode.ERROR,
@@ -438,11 +495,24 @@ async function lookupWebFingerInternal(
       };
     }
     try {
-      const parsed = JSON.parse(
+      const parsed: unknown = JSON.parse(
         await readBoundedText(response, MAX_BODY_SIZE, url),
-      ) as ResourceDescriptor;
+      );
+      // A body that parses to anything other than a JSON object—such as
+      // a literal `null`, a number, or an array—is not a resource
+      // descriptor, even though JSON.parse() accepts it without error.
+      if (
+        typeof parsed !== "object" || parsed === null || Array.isArray(parsed)
+      ) {
+        return {
+          resource: null,
+          result: "invalid",
+          statusCode: response.status,
+          remoteHost,
+        };
+      }
       return {
-        resource: parsed,
+        resource: parsed as ResourceDescriptor,
         result: "found",
         statusCode: response.status,
         remoteHost,