@fedify/webfinger 2.0.0-dev.0

package/dist/mod.cjs

@@ -0,0 +1,183 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __fedify_vocab_runtime = __toESM(require("@fedify/vocab-runtime"));
+const __logtape_logtape = __toESM(require("@logtape/logtape"));
+const __opentelemetry_api = __toESM(require("@opentelemetry/api"));
+
+//#region deno.json
+var name = "@fedify/webfinger";
+var version = "2.0.0";
+var license = "MIT";
+var exports$1 = { ".": "./src/mod.ts" };
+var description = "WebFinger client library for Fedify";
+var author = {
+	"name": "Hong Minhee",
+	"email": "hong@minhee.org",
+	"url": "https://hongminhee.org/"
+};
+var imports = {
+	"es-toolkit": "npm:es-toolkit@^1.42.0",
+	"fetch-mock": "npm:fetch-mock@^12.5.4"
+};
+var exclude = ["dist", "node_modules"];
+var tasks = {
+	"check": "deno fmt --check && deno lint && deno check src/*.ts",
+	"test": "deno test"
+};
+var deno_default = {
+	name,
+	version,
+	license,
+	exports: exports$1,
+	description,
+	author,
+	imports,
+	exclude,
+	tasks
+};
+
+//#endregion
+//#region src/lookup.ts
+const logger = (0, __logtape_logtape.getLogger)([
+	"fedify",
+	"webfinger",
+	"lookup"
+]);
+const DEFAULT_MAX_REDIRECTION = 5;
+/**
+* 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 tracerProvider = options.tracerProvider ?? __opentelemetry_api.trace.getTracerProvider();
+	const tracer = tracerProvider.getTracer(deno_default.name, deno_default.version);
+	return await tracer.startActiveSpan("webfinger.lookup", {
+		kind: __opentelemetry_api.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 ? __opentelemetry_api.SpanStatusCode.ERROR : __opentelemetry_api.SpanStatusCode.OK });
+			return result;
+		} catch (error) {
+			span.setStatus({
+				code: __opentelemetry_api.SpanStatusCode.ERROR,
+				message: String(error)
+			});
+			throw error;
+		} finally {
+			span.end();
+		}
+	});
+}
+async function lookupWebFingerInternal(resource, options = {}) {
+	if (typeof resource === "string") resource = new URL(resource);
+	let protocol = "https:";
+	let server;
+	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;
+		if (options.allowPrivateAddress !== true) try {
+			await (0, __fedify_vocab_runtime.validatePublicUrl)(url.href);
+		} catch (e) {
+			if (e instanceof __fedify_vocab_runtime.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 : (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 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();
+		} catch (e) {
+			if (e instanceof SyntaxError) {
+				logger.debug("Failed to parse WebFinger resource descriptor as JSON: {error}", { error: e });
+				return null;
+			}
+			throw e;
+		}
+	}
+}
+
+//#endregion
+exports.lookupWebFinger = lookupWebFinger;

package/dist/mod.d.cts

@@ -0,0 +1,113 @@
+import { GetUserAgentOptions } from "@fedify/vocab-runtime";
+import { TracerProvider } from "@opentelemetry/api";
+
+//#region src/jrd.d.ts
+/**
+ * Describes a resource.  See also
+ * [RFC 7033 section 4.4](https://datatracker.ietf.org/doc/html/rfc7033#section-4.4).
+ */
+interface ResourceDescriptor {
+  /**
+   * A URI that identifies the entity that this descriptor describes.
+   */
+  subject?: string;
+  /**
+   * URIs that identify the same entity as the `subject`.
+   */
+  aliases?: string[];
+  /**
+   * Conveys additional information about the `subject` of this descriptor.
+   */
+  properties?: Record<string, string>;
+  /**
+   * Links to other resources.
+   */
+  links?: Link[];
+}
+/**
+ * Represents a link.  See also
+ * [RFC 7033 section 4.4.4](https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4).
+ */
+interface Link {
+  /**
+   * The link's relation type, which is either a URI or a registered relation
+   * type (see [RFC 5988](https://datatracker.ietf.org/doc/html/rfc5988)).
+   */
+  rel: string;
+  /**
+   * The media type of the target resource (see
+   * [RFC 6838](https://datatracker.ietf.org/doc/html/rfc6838)).
+   */
+  type?: string;
+  /**
+   * A URI pointing to the target resource.
+   */
+  href?: string;
+  /**
+   * Human-readable titles describing the link relation.  If the language is
+   * unknown or unspecified, the key is `"und"`.
+   */
+  titles?: Record<string, string>;
+  /**
+   * Conveys additional information about the link relation.
+   */
+  properties?: Record<string, string>;
+  /**
+   * A URI Template (RFC 6570) that can be used to construct URIs by
+   * substituting variables. Used primarily for subscription endpoints
+   * where parameters like account URIs need to be dynamically inserted.
+   * @since 1.9.0
+   */
+  template?: string;
+}
+//#endregion
+//#region src/lookup.d.ts
+/**
+ * Options for {@link lookupWebFinger}.
+ * @since 1.3.0
+ */
+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
+ */
+declare function lookupWebFinger(resource: URL | string, options?: LookupWebFingerOptions): Promise<ResourceDescriptor | null>;
+//#endregion
+export { Link, LookupWebFingerOptions, ResourceDescriptor, lookupWebFinger };

package/dist/mod.d.ts

@@ -0,0 +1,113 @@
+import { GetUserAgentOptions } from "@fedify/vocab-runtime";
+import { TracerProvider } from "@opentelemetry/api";
+
+//#region src/jrd.d.ts
+/**
+ * Describes a resource.  See also
+ * [RFC 7033 section 4.4](https://datatracker.ietf.org/doc/html/rfc7033#section-4.4).
+ */
+interface ResourceDescriptor {
+  /**
+   * A URI that identifies the entity that this descriptor describes.
+   */
+  subject?: string;
+  /**
+   * URIs that identify the same entity as the `subject`.
+   */
+  aliases?: string[];
+  /**
+   * Conveys additional information about the `subject` of this descriptor.
+   */
+  properties?: Record<string, string>;
+  /**
+   * Links to other resources.
+   */
+  links?: Link[];
+}
+/**
+ * Represents a link.  See also
+ * [RFC 7033 section 4.4.4](https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4).
+ */
+interface Link {
+  /**
+   * The link's relation type, which is either a URI or a registered relation
+   * type (see [RFC 5988](https://datatracker.ietf.org/doc/html/rfc5988)).
+   */
+  rel: string;
+  /**
+   * The media type of the target resource (see
+   * [RFC 6838](https://datatracker.ietf.org/doc/html/rfc6838)).
+   */
+  type?: string;
+  /**
+   * A URI pointing to the target resource.
+   */
+  href?: string;
+  /**
+   * Human-readable titles describing the link relation.  If the language is
+   * unknown or unspecified, the key is `"und"`.
+   */
+  titles?: Record<string, string>;
+  /**
+   * Conveys additional information about the link relation.
+   */
+  properties?: Record<string, string>;
+  /**
+   * A URI Template (RFC 6570) that can be used to construct URIs by
+   * substituting variables. Used primarily for subscription endpoints
+   * where parameters like account URIs need to be dynamically inserted.
+   * @since 1.9.0
+   */
+  template?: string;
+}
+//#endregion
+//#region src/lookup.d.ts
+/**
+ * Options for {@link lookupWebFinger}.
+ * @since 1.3.0
+ */
+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
+ */
+declare function lookupWebFinger(resource: URL | string, options?: LookupWebFingerOptions): Promise<ResourceDescriptor | null>;
+//#endregion
+export { Link, LookupWebFingerOptions, ResourceDescriptor, lookupWebFinger };

package/dist/mod.js

@@ -0,0 +1,160 @@
+import { UrlError, getUserAgent, validatePublicUrl } from "@fedify/vocab-runtime";
+import { getLogger } from "@logtape/logtape";
+import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+
+//#region deno.json
+var name = "@fedify/webfinger";
+var version = "2.0.0";
+var license = "MIT";
+var exports = { ".": "./src/mod.ts" };
+var description = "WebFinger client library for Fedify";
+var author = {
+	"name": "Hong Minhee",
+	"email": "hong@minhee.org",
+	"url": "https://hongminhee.org/"
+};
+var imports = {
+	"es-toolkit": "npm:es-toolkit@^1.42.0",
+	"fetch-mock": "npm:fetch-mock@^12.5.4"
+};
+var exclude = ["dist", "node_modules"];
+var tasks = {
+	"check": "deno fmt --check && deno lint && deno check src/*.ts",
+	"test": "deno test"
+};
+var deno_default = {
+	name,
+	version,
+	license,
+	exports,
+	description,
+	author,
+	imports,
+	exclude,
+	tasks
+};
+
+//#endregion
+//#region src/lookup.ts
+const logger = getLogger([
+	"fedify",
+	"webfinger",
+	"lookup"
+]);
+const DEFAULT_MAX_REDIRECTION = 5;
+/**
+* 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 tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
+	const tracer = tracerProvider.getTracer(deno_default.name, deno_default.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, options = {}) {
+	if (typeof resource === "string") resource = new URL(resource);
+	let protocol = "https:";
+	let server;
+	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;
+		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();
+		} catch (e) {
+			if (e instanceof SyntaxError) {
+				logger.debug("Failed to parse WebFinger resource descriptor as JSON: {error}", { error: e });
+				return null;
+			}
+			throw e;
+		}
+	}
+}
+
+//#endregion
+export { lookupWebFinger };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@fedify/webfinger",
+  "version": "2.0.0-dev.0",
+  "homepage": "https://fedify.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fedify-dev/fedify.git",
+    "directory": "packages/webfinger"
+  },
+  "bugs": {
+    "url": "https://github.com/fedify-dev/fedify/issues"
+  },
+  "funding": [
+    "https://opencollective.com/fedify",
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "deno": ">=2.0.0",
+    "node": ">=22.0.0",
+    "bun": ">=1.1.0"
+  },
+  "description": "WebFinger client library for ActivityPub",
+  "type": "module",
+  "main": "./dist/mod.cjs",
+  "module": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/mod.d.ts",
+        "require": "./dist/mod.d.cts",
+        "default": "./dist/mod.d.ts"
+      },
+      "import": "./dist/mod.js",
+      "require": "./dist/mod.cjs",
+      "default": "./dist/mod.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "Fedify",
+    "WebFinger",
+    "ActivityPub",
+    "Fediverse"
+  ],
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^24.2.1",
+    "fetch-mock": "^12.5.4",
+    "tsdown": "^0.12.9",
+    "typescript": "^5.9.3",
+    "@fedify/fixture": "2.0.0"
+  },
+  "dependencies": {
+    "@logtape/logtape": "^1.3.5",
+    "@opentelemetry/api": "^1.9.0",
+    "es-toolkit": "1.43.0",
+    "@fedify/vocab-runtime": "2.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && cd dist/ && node --test"
+  }
+}

package/src/jrd.ts

@@ -0,0 +1,67 @@
+/**
+ * Describes a resource.  See also
+ * [RFC 7033 section 4.4](https://datatracker.ietf.org/doc/html/rfc7033#section-4.4).
+ */
+export interface ResourceDescriptor {
+  /**
+   * A URI that identifies the entity that this descriptor describes.
+   */
+  subject?: string;
+
+  /**
+   * URIs that identify the same entity as the `subject`.
+   */
+  aliases?: string[];
+
+  /**
+   * Conveys additional information about the `subject` of this descriptor.
+   */
+  properties?: Record<string, string>;
+
+  /**
+   * Links to other resources.
+   */
+  links?: Link[];
+}
+
+/**
+ * Represents a link.  See also
+ * [RFC 7033 section 4.4.4](https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4).
+ */
+export interface Link {
+  /**
+   * The link's relation type, which is either a URI or a registered relation
+   * type (see [RFC 5988](https://datatracker.ietf.org/doc/html/rfc5988)).
+   */
+  rel: string;
+
+  /**
+   * The media type of the target resource (see
+   * [RFC 6838](https://datatracker.ietf.org/doc/html/rfc6838)).
+   */
+  type?: string;
+
+  /**
+   * A URI pointing to the target resource.
+   */
+  href?: string;
+
+  /**
+   * Human-readable titles describing the link relation.  If the language is
+   * unknown or unspecified, the key is `"und"`.
+   */
+  titles?: Record<string, string>;
+
+  /**
+   * Conveys additional information about the link relation.
+   */
+  properties?: Record<string, string>;
+
+  /**
+   * A URI Template (RFC 6570) that can be used to construct URIs by
+   * substituting variables. Used primarily for subscription endpoints
+   * where parameters like account URIs need to be dynamically inserted.
+   * @since 1.9.0
+   */
+  template?: string;
+}