@fedify/webfinger 2.0.0-dev.0

package/src/lookup.test.ts

@@ -0,0 +1,331 @@
+import { test } from "@fedify/fixture";
+import { withTimeout } from "es-toolkit";
+import fetchMock from "fetch-mock";
+import { deepStrictEqual } from "node:assert/strict";
+import type { ResourceDescriptor } from "./jrd.ts";
+import { lookupWebFinger } from "./lookup.ts";
+
+test({
+  name: "lookupWebFinger()",
+  sanitizeOps: false,
+  sanitizeResources: false,
+  async fn(t) {
+    await t.step("invalid resource", async () => {
+      deepStrictEqual(await lookupWebFinger("acct:johndoe"), null);
+      deepStrictEqual(await lookupWebFinger(new URL("acct:johndoe")), null);
+      deepStrictEqual(await lookupWebFinger("acct:johndoe@"), null);
+      deepStrictEqual(await lookupWebFinger(new URL("acct:johndoe@")), null);
+    });
+
+    await t.step("connection refused", async () => {
+      deepStrictEqual(
+        await lookupWebFinger("acct:johndoe@fedify-test.internal"),
+        null,
+      );
+      deepStrictEqual(
+        await lookupWebFinger("https://fedify-test.internal/foo"),
+        null,
+      );
+    });
+
+    fetchMock.spyGlobal();
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger?",
+      { status: 404 },
+    );
+
+    await t.step("not found", async () => {
+      deepStrictEqual(await lookupWebFinger("acct:johndoe@example.com"), null);
+      deepStrictEqual(await lookupWebFinger("https://example.com/foo"), null);
+    });
+
+    const expected: ResourceDescriptor = {
+      subject: "acct:johndoe@example.com",
+      links: [],
+    };
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "https://example.com/.well-known/webfinger?resource=acct%3Ajohndoe%40example.com",
+      { body: expected },
+    );
+
+    await t.step("acct", async () => {
+      deepStrictEqual(
+        await lookupWebFinger("acct:johndoe@example.com"),
+        expected,
+      );
+    });
+
+    const expected2: ResourceDescriptor = {
+      subject: "https://example.com/foo",
+      links: [],
+    };
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "https://example.com/.well-known/webfinger?resource=https%3A%2F%2Fexample.com%2Ffoo",
+      { body: expected2 },
+    );
+
+    await t.step("https", async () => {
+      deepStrictEqual(
+        await lookupWebFinger("https://example.com/foo"),
+        expected2,
+      );
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger?",
+      { body: "not json" },
+    );
+
+    await t.step("invalid response", async () => {
+      deepStrictEqual(await lookupWebFinger("acct:johndoe@example.com"), null);
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://localhost/.well-known/webfinger?",
+      {
+        subject: "acct:test@localhost",
+        links: [
+          {
+            rel: "self",
+            type: "application/activity+json",
+            href: "https://localhost/actor",
+          },
+        ],
+      },
+    );
+
+    await t.step("private address", async () => {
+      deepStrictEqual(await lookupWebFinger("acct:test@localhost"), null);
+      deepStrictEqual(
+        await lookupWebFinger("acct:test@localhost", {
+          allowPrivateAddress: true,
+        }),
+        {
+          subject: "acct:test@localhost",
+          links: [
+            {
+              rel: "self",
+              type: "application/activity+json",
+              href: "https://localhost/actor",
+            },
+          ],
+        },
+      );
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger?",
+      {
+        status: 302,
+        headers: { Location: "/.well-known/webfinger2" },
+      },
+    );
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger2",
+      { body: expected },
+    );
+
+    await t.step("redirection", async () => {
+      deepStrictEqual(
+        await lookupWebFinger("acct:johndoe@example.com"),
+        expected,
+      );
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger?",
+      {
+        status: 302,
+        headers: { Location: "/.well-known/webfinger" },
+      },
+    );
+
+    await t.step("infinite redirection", async () => {
+      const result = await withTimeout(
+        () => lookupWebFinger("acct:johndoe@example.com"),
+        2000,
+      );
+      deepStrictEqual(result, null);
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger?",
+      {
+        status: 302,
+        headers: { Location: "ftp://example.com/" },
+      },
+    );
+
+    await t.step("redirection to different protocol", async () => {
+      deepStrictEqual(await lookupWebFinger("acct:johndoe@example.com"), null);
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger?",
+      {
+        status: 302,
+        headers: { Location: "https://localhost/" },
+      },
+    );
+
+    await t.step("redirection to private address", async () => {
+      deepStrictEqual(await lookupWebFinger("acct:johndoe@example.com"), null);
+    });
+
+    fetchMock.removeRoutes();
+    let redirectCount = 0;
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger",
+      () => {
+        redirectCount++;
+        if (redirectCount < 3) {
+          return {
+            status: 302,
+            headers: {
+              Location: `/.well-known/webfinger?redirect=${redirectCount}`,
+            },
+          };
+        }
+        return { body: expected };
+      },
+    );
+
+    await t.step("custom maxRedirection", async () => {
+      // Test with maxRedirection: 2 (should fail)
+      redirectCount = 0;
+      deepStrictEqual(
+        await lookupWebFinger("acct:johndoe@example.com", {
+          maxRedirection: 2,
+        }),
+        null,
+      );
+
+      // Test with maxRedirection: 3 (should succeed)
+      redirectCount = 0;
+      deepStrictEqual(
+        await lookupWebFinger("acct:johndoe@example.com", {
+          maxRedirection: 3,
+        }),
+        expected,
+      );
+
+      // Test with default maxRedirection: 5 (should succeed)
+      redirectCount = 0;
+      deepStrictEqual(
+        await lookupWebFinger("acct:johndoe@example.com"),
+        expected,
+      );
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger?",
+      () =>
+        new Promise((resolve) => {
+          const timeoutId = setTimeout(() => {
+            resolve({ body: expected });
+          }, 1000);
+
+          return () => clearTimeout(timeoutId);
+        }),
+    );
+
+    await t.step("request cancellation", async () => {
+      // Test cancelling a request immediately using AbortController
+      const controller = new AbortController();
+      const promise = lookupWebFinger("acct:johndoe@example.com", {
+        signal: controller.signal,
+      });
+
+      // Abort the request right after starting it
+      controller.abort();
+      deepStrictEqual(await promise, null);
+    });
+
+    fetchMock.removeRoutes();
+    let redirectCount2 = 0;
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger",
+      () => {
+        redirectCount2++;
+        if (redirectCount2 === 1) {
+          return {
+            status: 302,
+            headers: { Location: "/.well-known/webfinger2" },
+          };
+        }
+        return new Promise((resolve) => {
+          const timeoutId = setTimeout(() => {
+            resolve({ body: expected });
+          }, 1000);
+
+          return () => clearTimeout(timeoutId);
+        });
+      },
+    );
+
+    await t.step("cancellation during redirection", async () => {
+      // Test cancelling a request during redirection process
+      const controller = new AbortController();
+      const promise = lookupWebFinger("acct:johndoe@example.com", {
+        signal: controller.signal,
+      });
+
+      // Cancel during the delayed second request after redirection
+      setTimeout(() => controller.abort(), 100);
+      deepStrictEqual(await promise, null);
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger?",
+      () =>
+        new Promise((resolve) => {
+          const timeoutId = setTimeout(() => {
+            resolve({ body: expected });
+          }, 500);
+
+          return () => clearTimeout(timeoutId);
+        }),
+    );
+
+    await t.step("cancellation with immediate abort", async () => {
+      // Test starting a request with an already aborted AbortController
+      const controller = new AbortController();
+      controller.abort();
+
+      // Use a signal that was already aborted before starting the request
+      const result = await lookupWebFinger("acct:johndoe@example.com", {
+        signal: controller.signal,
+      });
+      deepStrictEqual(result, null);
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger?",
+      { body: expected },
+    );
+
+    await t.step("successful request with signal", async () => {
+      // Test successful request with a normal AbortController signal
+      const controller = new AbortController();
+      const result = await lookupWebFinger("acct:johndoe@example.com", {
+        signal: controller.signal,
+      });
+      deepStrictEqual(result, expected);
+    });
+
+    fetchMock.hardReset();
+  },
+});
+
+// cSpell: ignore johndoe

package/src/lookup.ts

@@ -0,0 +1,226 @@
+import {
+  getUserAgent,
+  type GetUserAgentOptions,
+  UrlError,
+  validatePublicUrl,
+} from "@fedify/vocab-runtime";
+import { getLogger } from "@logtape/logtape";
+import {
+  SpanKind,
+  SpanStatusCode,
+  trace,
+  type TracerProvider,
+} from "@opentelemetry/api";
+import metadata from "../deno.json" with { type: "json" };
+import type { ResourceDescriptor } from "./jrd.ts";
+
+const logger = getLogger(["fedify", "webfinger", "lookup"]);
+
+const DEFAULT_MAX_REDIRECTION = 5;
+
+/**
+ * Options for {@link lookupWebFinger}.
+ * @since 1.3.0
+ */
+export interface LookupWebFingerOptions {
+  /**
+   * The options for making `User-Agent` header.
+   * If a string is given, it is used as the `User-Agent` header value.
+   * If an object is given, it is passed to {@link getUserAgent} to generate
+   * the `User-Agent` header value.
+   */
+  userAgent?: GetUserAgentOptions | string;
+
+  /**
+   * Whether to allow private IP addresses in the URL.
+   *
+   * Mostly useful for testing purposes.  *Do not use this in production.*
+   *
+   * Turned off by default.
+   * @since 1.4.0
+   */
+  allowPrivateAddress?: boolean;
+
+  /**
+   * The maximum number of redirections to follow.
+   * @default `5`
+   * @since 1.8.0
+   */
+  maxRedirection?: number;
+
+  /**
+   * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+   * is used.
+   */
+  tracerProvider?: TracerProvider;
+
+  /**
+   * AbortSignal for cancelling the request.
+   * @since 1.8.0
+   * @
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * 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
+ */
+export async function lookupWebFinger(
+  resource: URL | string,
+  options: LookupWebFingerOptions = {},
+): Promise<ResourceDescriptor | null> {
+  const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
+  const tracer = tracerProvider.getTracer(
+    metadata.name,
+    metadata.version,
+  );
+  return await tracer.startActiveSpan(
+    "webfinger.lookup",
+    {
+      kind: SpanKind.CLIENT,
+      attributes: {
+        "webfinger.resource": resource.toString(),
+        "webfinger.resource.scheme": typeof resource === "string"
+          ? resource.replace(/:.*$/, "")
+          : resource.protocol.replace(/:$/, ""),
+      },
+    },
+    async (span) => {
+      try {
+        const result = await lookupWebFingerInternal(resource, options);
+        span.setStatus({
+          code: result === null ? SpanStatusCode.ERROR : SpanStatusCode.OK,
+        });
+        return result;
+      } catch (error) {
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: String(error),
+        });
+        throw error;
+      } finally {
+        span.end();
+      }
+    },
+  );
+}
+
+async function lookupWebFingerInternal(
+  resource: URL | string,
+  options: LookupWebFingerOptions = {},
+): Promise<ResourceDescriptor | null> {
+  if (typeof resource === "string") resource = new URL(resource);
+  let protocol = "https:";
+  let server: string;
+  if (resource.protocol === "acct:") {
+    const atPos = resource.pathname.lastIndexOf("@");
+    if (atPos < 0) return null;
+    server = resource.pathname.substring(atPos + 1);
+    if (server === "") return null;
+  } 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) {
+    logger.debug(
+      "Fetching WebFinger resource descriptor from {url}...",
+      { url: url.href },
+    );
+    let response: Response;
+    if (options.allowPrivateAddress !== true) {
+      try {
+        await validatePublicUrl(url.href);
+      } catch (e) {
+        if (e instanceof UrlError) {
+          logger.error(
+            "Invalid URL for WebFinger resource descriptor: {error}",
+            { error: e },
+          );
+          return null;
+        }
+        throw e;
+      }
+    }
+    try {
+      response = await fetch(url, {
+        headers: {
+          Accept: "application/jrd+json",
+          "User-Agent": typeof options.userAgent === "string"
+            ? options.userAgent
+            : getUserAgent(options.userAgent),
+        },
+        redirect: "manual",
+        signal: options.signal,
+      });
+    } catch (error) {
+      logger.debug(
+        "Failed to fetch WebFinger resource descriptor: {error}",
+        { url: url.href, error },
+      );
+      return null;
+    }
+    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 null;
+      }
+      const redirectedUrl = new URL(
+        response.headers.get("Location")!,
+        response.url == null || response.url === "" ? url : response.url,
+      );
+      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 null;
+      }
+      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 null;
+    }
+    try {
+      return await response.json() as ResourceDescriptor;
+    } catch (e) {
+      if (e instanceof SyntaxError) {
+        logger.debug(
+          "Failed to parse WebFinger resource descriptor as JSON: {error}",
+          { error: e },
+        );
+        return null;
+      }
+      throw e;
+    }
+  }
+}

package/src/mod.ts

@@ -0,0 +1,7 @@
+/**
+ * Exports WebFinger-related types and functions.
+ *
+ * @module
+ */
+export * from "./jrd.ts";
+export * from "./lookup.ts";

package/tsdown.config.ts

@@ -0,0 +1,20 @@
+import { glob } from "node:fs/promises";
+import { sep } from "node:path";
+import { defineConfig } from "tsdown";
+
+export default [
+  defineConfig({
+    entry: ["src/mod.ts"],
+    dts: true,
+    format: ["esm", "cjs"],
+    platform: "node",
+    external: [/^node:/],
+  }),
+  defineConfig({
+    entry: (await Array.fromAsync(glob(`src/**/*.test.ts`)))
+      .map((f) => f.replace(sep, "/")),
+    format: ["esm", "cjs"],
+    platform: "node",
+    external: [/^node:/],
+  }),
+];