@fedify/vocab 2.3.0-dev.1119 → 2.3.0-dev.1131

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab",
-  "version": "2.3.0-dev.1119+6cc02662",
+  "version": "2.3.0-dev.1131+553b59b8",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts"

package/dist/mod.cjs

@@ -33,7 +33,7 @@ let _fedify_vocab_runtime_temporal = require("@fedify/vocab-runtime/temporal");
 let es_toolkit = require("es-toolkit");
 //#region deno.json
 var name = "@fedify/vocab";
-var version = "2.3.0-dev.1119+6cc02662";
+var version = "2.3.0-dev.1131+553b59b8";
 //#endregion
 //#region src/type.ts
 function getTypeId(object) {
@@ -47552,6 +47552,40 @@ function toAcctUrl(handle) {
 }
 //#endregion
 //#region src/lookup.ts
+const objectLookupCounters = /* @__PURE__ */ new WeakMap();
+function getObjectLookupCounter(meterProvider) {
+	let counter = objectLookupCounters.get(meterProvider);
+	if (counter == null) {
+		counter = meterProvider.getMeter(name, version).createCounter("activitypub.object.lookup", {
+			description: "ActivityStreams object lookups via lookupObject(), classified by whether the resolved value is an Actor.",
+			unit: "{lookup}"
+		});
+		objectLookupCounters.set(meterProvider, counter);
+	}
+	return counter;
+}
+function getLookupRemoteHost(identifier) {
+	let url;
+	if (identifier instanceof URL) url = identifier;
+	else try {
+		url = new URL(identifier);
+	} catch {
+		return extractHandleHost(identifier.startsWith("@") ? identifier.slice(1) : identifier);
+	}
+	if (url.hostname !== "") return url.hostname;
+	if (url.protocol === "acct:") return extractHandleHost(url.pathname);
+}
+function extractHandleHost(handle) {
+	const at = handle.lastIndexOf("@");
+	if (at < 0 || at >= handle.length - 1) return void 0;
+	const candidate = handle.slice(at + 1);
+	if (/[/?#\s]/.test(candidate)) return void 0;
+	try {
+		return new URL(`https://${candidate}`).hostname || void 0;
+	} catch {
+		return;
+	}
+}
 const logger = (0, _logtape_logtape.getLogger)([
 	"fedify",
 	"vocab",
@@ -47591,8 +47625,10 @@ const logger = (0, _logtape_logtape.getLogger)([
 */
 async function lookupObject(identifier, options = {}) {
 	return await (options.tracerProvider ?? _opentelemetry_api.trace.getTracerProvider()).getTracer(name, version).startActiveSpan("activitypub.lookup_object", async (span) => {
+		let kind = "other";
 		try {
 			const result = await lookupObjectInternal(identifier, options);
+			if (result != null) kind = isActor(result) ? "actor" : "object";
 			if (result == null) span.setStatus({ code: _opentelemetry_api.SpanStatusCode.ERROR });
 			else {
 				if (result.id != null) span.setAttribute("activitypub.object.id", result.id.href);
@@ -47612,6 +47648,12 @@ async function lookupObject(identifier, options = {}) {
 			});
 			throw error;
 		} finally {
+			if (options.meterProvider != null) {
+				const attributes = { "activitypub.lookup.kind": kind };
+				const host = getLookupRemoteHost(identifier);
+				if (host != null) attributes["activitypub.remote.host"] = host;
+				getObjectLookupCounter(options.meterProvider).add(1, attributes);
+			}
 			span.end();
 		}
 	});

package/dist/mod.d.cts

@@ -1,6 +1,6 @@
 /// <reference lib="esnext.temporal" />
 import { Decimal, DocumentLoader, DocumentLoader as DocumentLoader$1, GetUserAgentOptions, GetUserAgentOptions as GetUserAgentOptions$1, LanguageString, LanguageString as LanguageString$1, RemoteDocument } from "@fedify/vocab-runtime";
-import { Span, TracerProvider } from "@opentelemetry/api";
+import { MeterProvider, Span, TracerProvider } from "@opentelemetry/api";
 
 //#region src/vocab.d.ts
 /** Describes an object of any kind. The Object type serves as the base type for
@@ -18296,6 +18296,18 @@ declare function toAcctUrl(handle: string): URL | null;
 //#endregion
 //#region src/lookup.d.ts
 /**
+* The classification of an ActivityStreams lookup performed by
+* {@link lookupObject}, recorded as `activitypub.lookup.kind` on the
+* `activitypub.object.lookup` counter.
+*
+*  -  `actor`: the resolved object is an {@link import("./actor.ts").Actor}.
+*  -  `object`: the resolved object is a non-actor ActivityStreams object.
+*  -  `other`: the lookup did not resolve to an object (not found, network
+*     failure, parse failure).
+* @since 2.3.0
+*/
+type ObjectLookupKind = "actor" | "object" | "other";
+/**
 * Options for the {@link lookupObject} function.
 *
 * @since 0.2.0
@@ -18343,6 +18355,14 @@ interface LookupObjectOptions {
   */
   tracerProvider?: TracerProvider;
   /**
+  * The OpenTelemetry meter provider used to record the
+  * `activitypub.object.lookup` counter.  If omitted, the counter is not
+  * emitted at all (the helper is opt-in to avoid touching the global
+  * meter provider for callers that do not use OpenTelemetry).
+  * @since 2.3.0
+  */
+  meterProvider?: MeterProvider;
+  /**
   * AbortSignal for cancelling the request.
   * @since 1.8.0
   */
@@ -18511,4 +18531,4 @@ declare function getTypeId(object: Object$1 | Link | null): URL | null;
 */
 declare function getTypeId(object: Object$1 | Link | null | undefined): URL | null | undefined;
 //#endregion
-export { $EntityType, Accept, Activity, Actor, ActorTypeName, Add, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Create, CryptographicKey, DataIntegrityProof, Delete, DidService, Dislike, Document, type DocumentLoader, Emoji, EmojiReact, Endpoints, Event, Export, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, LookupObjectOptions, Measure, Mention, Move, Multikey, NormalizeActorHandleOptions, Note, Object$1 as Object, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, Profile, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, parseFediverseHandle, toAcctUrl, traverseCollection };
+export { $EntityType, Accept, Activity, Actor, ActorTypeName, Add, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Create, CryptographicKey, DataIntegrityProof, Delete, DidService, Dislike, Document, type DocumentLoader, Emoji, EmojiReact, Endpoints, Event, Export, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, LookupObjectOptions, Measure, Mention, Move, Multikey, NormalizeActorHandleOptions, Note, Object$1 as Object, ObjectLookupKind, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, Profile, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, parseFediverseHandle, toAcctUrl, traverseCollection };

package/dist/mod.d.ts

@@ -1,5 +1,5 @@
 /// <reference lib="esnext.temporal" />
-import { Span, TracerProvider } from "@opentelemetry/api";
+import { MeterProvider, Span, TracerProvider } from "@opentelemetry/api";
 import { Decimal, DocumentLoader, DocumentLoader as DocumentLoader$1, GetUserAgentOptions, GetUserAgentOptions as GetUserAgentOptions$1, LanguageString, LanguageString as LanguageString$1, RemoteDocument } from "@fedify/vocab-runtime";
 
 //#region src/vocab.d.ts
@@ -18296,6 +18296,18 @@ declare function toAcctUrl(handle: string): URL | null;
 //#endregion
 //#region src/lookup.d.ts
 /**
+* The classification of an ActivityStreams lookup performed by
+* {@link lookupObject}, recorded as `activitypub.lookup.kind` on the
+* `activitypub.object.lookup` counter.
+*
+*  -  `actor`: the resolved object is an {@link import("./actor.ts").Actor}.
+*  -  `object`: the resolved object is a non-actor ActivityStreams object.
+*  -  `other`: the lookup did not resolve to an object (not found, network
+*     failure, parse failure).
+* @since 2.3.0
+*/
+type ObjectLookupKind = "actor" | "object" | "other";
+/**
 * Options for the {@link lookupObject} function.
 *
 * @since 0.2.0
@@ -18343,6 +18355,14 @@ interface LookupObjectOptions {
   */
   tracerProvider?: TracerProvider;
   /**
+  * The OpenTelemetry meter provider used to record the
+  * `activitypub.object.lookup` counter.  If omitted, the counter is not
+  * emitted at all (the helper is opt-in to avoid touching the global
+  * meter provider for callers that do not use OpenTelemetry).
+  * @since 2.3.0
+  */
+  meterProvider?: MeterProvider;
+  /**
   * AbortSignal for cancelling the request.
   * @since 1.8.0
   */
@@ -18511,4 +18531,4 @@ declare function getTypeId(object: Object$1 | Link | null): URL | null;
 */
 declare function getTypeId(object: Object$1 | Link | null | undefined): URL | null | undefined;
 //#endregion
-export { $EntityType, Accept, Activity, Actor, ActorTypeName, Add, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Create, CryptographicKey, DataIntegrityProof, Delete, DidService, Dislike, Document, type DocumentLoader, Emoji, EmojiReact, Endpoints, Event, Export, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, LookupObjectOptions, Measure, Mention, Move, Multikey, NormalizeActorHandleOptions, Note, Object$1 as Object, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, Profile, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, parseFediverseHandle, toAcctUrl, traverseCollection };
+export { $EntityType, Accept, Activity, Actor, ActorTypeName, Add, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Create, CryptographicKey, DataIntegrityProof, Delete, DidService, Dislike, Document, type DocumentLoader, Emoji, EmojiReact, Endpoints, Event, Export, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, LookupObjectOptions, Measure, Mention, Move, Multikey, NormalizeActorHandleOptions, Note, Object$1 as Object, ObjectLookupKind, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, Profile, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, parseFediverseHandle, toAcctUrl, traverseCollection };

package/dist/mod.js

@@ -9,7 +9,7 @@ import { isTemporalDuration, isTemporalInstant } from "@fedify/vocab-runtime/tem
 import { delay } from "es-toolkit";
 //#region deno.json
 var name = "@fedify/vocab";
-var version = "2.3.0-dev.1119+6cc02662";
+var version = "2.3.0-dev.1131+553b59b8";
 //#endregion
 //#region src/type.ts
 function getTypeId(object) {
@@ -47528,6 +47528,40 @@ function toAcctUrl(handle) {
 }
 //#endregion
 //#region src/lookup.ts
+const objectLookupCounters = /* @__PURE__ */ new WeakMap();
+function getObjectLookupCounter(meterProvider) {
+	let counter = objectLookupCounters.get(meterProvider);
+	if (counter == null) {
+		counter = meterProvider.getMeter(name, version).createCounter("activitypub.object.lookup", {
+			description: "ActivityStreams object lookups via lookupObject(), classified by whether the resolved value is an Actor.",
+			unit: "{lookup}"
+		});
+		objectLookupCounters.set(meterProvider, counter);
+	}
+	return counter;
+}
+function getLookupRemoteHost(identifier) {
+	let url;
+	if (identifier instanceof URL) url = identifier;
+	else try {
+		url = new URL(identifier);
+	} catch {
+		return extractHandleHost(identifier.startsWith("@") ? identifier.slice(1) : identifier);
+	}
+	if (url.hostname !== "") return url.hostname;
+	if (url.protocol === "acct:") return extractHandleHost(url.pathname);
+}
+function extractHandleHost(handle) {
+	const at = handle.lastIndexOf("@");
+	if (at < 0 || at >= handle.length - 1) return void 0;
+	const candidate = handle.slice(at + 1);
+	if (/[/?#\s]/.test(candidate)) return void 0;
+	try {
+		return new URL(`https://${candidate}`).hostname || void 0;
+	} catch {
+		return;
+	}
+}
 const logger = getLogger([
 	"fedify",
 	"vocab",
@@ -47567,8 +47601,10 @@ const logger = getLogger([
 */
 async function lookupObject(identifier, options = {}) {
 	return await (options.tracerProvider ?? trace.getTracerProvider()).getTracer(name, version).startActiveSpan("activitypub.lookup_object", async (span) => {
+		let kind = "other";
 		try {
 			const result = await lookupObjectInternal(identifier, options);
+			if (result != null) kind = isActor(result) ? "actor" : "object";
 			if (result == null) span.setStatus({ code: SpanStatusCode.ERROR });
 			else {
 				if (result.id != null) span.setAttribute("activitypub.object.id", result.id.href);
@@ -47588,6 +47624,12 @@ async function lookupObject(identifier, options = {}) {
 			});
 			throw error;
 		} finally {
+			if (options.meterProvider != null) {
+				const attributes = { "activitypub.lookup.kind": kind };
+				const host = getLookupRemoteHost(identifier);
+				if (host != null) attributes["activitypub.remote.host"] = host;
+				getObjectLookupCounter(options.meterProvider).add(1, attributes);
+			}
 			span.end();
 		}
 	});

package/dist-tests/{deno-C05d783V.mjs → actor-DBM2eKvJ.mjs}

@@ -1,6 +1,10 @@
 import "@js-temporal/polyfill";
 globalThis.addEventListener = () => {};
-import { A as __commonJSMin, M as __toESM } from "./vocab-B0Z-tH4q.mjs";
+import { A as __commonJSMin, M as __toESM, r as Application, u as Group, v as Organization, w as Service, y as Person } from "./vocab-B0Z-tH4q.mjs";
+import { t as getTypeId } from "./type-Cf-vxmre.mjs";
+import { lookupWebFinger } from "@fedify/webfinger";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { domainToASCII, domainToUnicode } from "node:url";
 //#endregion
 //#region ../../node_modules/.pnpm/regexparam@3.0.0/node_modules/regexparam/dist/index.mjs
 var import_glob_to_regexp = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
@@ -1202,6 +1206,138 @@ var esm_default = new class FetchMock {
 //#endregion
 //#region deno.json
 var name = "@fedify/vocab";
-var version = "2.3.0-dev.1119+6cc02662";
+var version = "2.3.0-dev.1131+553b59b8";
 //#endregion
-export { version as n, esm_default as r, name as t };
+//#region src/actor.ts
+/**
+* Checks if the given object is an {@link Actor}.
+* @param object The object to check.
+* @returns `true` if the given object is an {@link Actor}.
+*/
+function isActor(object) {
+	return object instanceof Application || object instanceof Group || object instanceof Organization || object instanceof Person || object instanceof Service;
+}
+/**
+* Gets the type name of the given actor.
+* @param actor The actor to get the type name of.
+* @returns The type name of the given actor.
+*/
+function getActorTypeName(actor) {
+	if (actor instanceof Application) return "Application";
+	else if (actor instanceof Group) return "Group";
+	else if (actor instanceof Organization) return "Organization";
+	else if (actor instanceof Person) return "Person";
+	else if (actor instanceof Service) return "Service";
+	throw new Error("Unknown actor type.");
+}
+/**
+* Gets the actor class by the given type name.
+* @param typeName The type name to get the actor class by.
+* @returns The actor class by the given type name.
+*/
+function getActorClassByTypeName(typeName) {
+	switch (typeName) {
+		case "Application": return Application;
+		case "Group": return Group;
+		case "Organization": return Organization;
+		case "Person": return Person;
+		case "Service": return Service;
+	}
+	throw new Error("Unknown actor type name.");
+}
+/**
+* Gets the actor handle, of the form `@username@domain`, from the given actor
+* or an actor URI.
+*
+* @example
+* ``` typescript
+* // Get the handle of an actor object:
+* await getActorHandle(
+*   new Person({ id: new URL("https://fosstodon.org/users/hongminhee") })
+* );
+*
+* // Get the handle of an actor URI:
+* await getActorHandle(new URL("https://fosstodon.org/users/hongminhee"));
+* ```
+*
+* @param actor The actor or actor URI to get the handle from.
+* @param options The extra options for getting the actor handle.
+* @returns The actor handle.  It starts with `@` and is followed by the
+*          username and domain, separated by `@` by default (it can be
+*          customized with the options).
+* @throws {TypeError} If the actor does not have enough information to get the
+*                     handle.
+* @since 0.4.0
+*/
+async function getActorHandle(actor, options = {}) {
+	return await (options.tracerProvider ?? trace.getTracerProvider()).getTracer(name, version).startActiveSpan("activitypub.get_actor_handle", async (span) => {
+		if (isActor(actor)) {
+			if (actor.id != null) span.setAttribute("activitypub.actor.id", actor.id.href);
+			span.setAttribute("activitypub.actor.type", getTypeId(actor).href);
+		}
+		try {
+			return await getActorHandleInternal(actor, options);
+		} catch (error) {
+			span.setStatus({
+				code: SpanStatusCode.ERROR,
+				message: String(error)
+			});
+			throw error;
+		} finally {
+			span.end();
+		}
+	});
+}
+async function getActorHandleInternal(actor, options = {}) {
+	const actorId = actor instanceof URL ? actor : actor.id;
+	if (actorId != null) {
+		const result = await lookupWebFinger(actorId, {
+			userAgent: options.userAgent,
+			tracerProvider: options.tracerProvider
+		});
+		if (result != null) {
+			const aliases = [...result.aliases ?? []];
+			if (result.subject != null) aliases.unshift(result.subject);
+			for (const alias of aliases) {
+				const match = alias.match(/^acct:([^@]+)@([^@]+)$/);
+				if (match != null) {
+					if (new URL(`https://${match[2]}/`).hostname !== actorId.hostname && !await verifyCrossOriginActorHandle(actorId.href, alias, options.userAgent, options.tracerProvider)) continue;
+					return normalizeActorHandle(`@${match[1]}@${match[2]}`, options);
+				}
+			}
+		}
+	}
+	if (!(actor instanceof URL) && actor.preferredUsername != null && actor.id != null) return normalizeActorHandle(`@${actor.preferredUsername}@${actor.id.host}`, options);
+	throw new TypeError("Actor does not have enough information to get the handle.");
+}
+async function verifyCrossOriginActorHandle(actorId, alias, userAgent, tracerProvider) {
+	const response = await lookupWebFinger(alias, {
+		userAgent,
+		tracerProvider
+	});
+	if (response == null) return false;
+	for (const alias of response.aliases ?? []) if (new URL(alias).href === actorId) return true;
+	return false;
+}
+/**
+* Normalizes the given actor handle.
+* @param handle The full handle of the actor to normalize.
+* @param options The options for normalizing the actor handle.
+* @returns The normalized actor handle.
+* @throws {TypeError} If the actor handle is invalid.
+* @since 0.9.0
+*/
+function normalizeActorHandle(handle, options = {}) {
+	handle = handle.replace(/^@/, "");
+	const atPos = handle.indexOf("@");
+	if (atPos < 1) throw new TypeError("Invalid actor handle.");
+	let domain = handle.substring(atPos + 1);
+	if (domain.length < 1 || domain.includes("@")) throw new TypeError("Invalid actor handle.");
+	domain = domain.toLowerCase();
+	domain = options.punycode ? domainToASCII(domain) : domainToUnicode(domain);
+	domain = domain.toLowerCase();
+	const user = handle.substring(0, atPos);
+	return options.trimLeadingAt ? `${user}@${domain}` : `@${user}@${domain}`;
+}
+//#endregion
+export { normalizeActorHandle as a, esm_default as c, isActor as i, getActorHandle as n, name as o, getActorTypeName as r, version as s, getActorClassByTypeName as t };

package/dist-tests/actor.test.mjs

@@ -1,13 +1,9 @@
 import "@js-temporal/polyfill";
 globalThis.addEventListener = () => {};
 import { j as __exportAll, r as Application, u as Group, v as Organization, w as Service, y as Person } from "./vocab-B0Z-tH4q.mjs";
-import { n as version, r as esm_default, t as name } from "./deno-C05d783V.mjs";
-import { t as getTypeId } from "./type-Cf-vxmre.mjs";
+import { a as normalizeActorHandle, c as esm_default, i as isActor, n as getActorHandle, r as getActorTypeName, t as getActorClassByTypeName } from "./actor-DBM2eKvJ.mjs";
 import { test } from "@fedify/fixture";
 import { deepStrictEqual, ok, rejects, strictEqual, throws } from "node:assert/strict";
-import { lookupWebFinger } from "@fedify/webfinger";
-import { SpanStatusCode, trace } from "@opentelemetry/api";
-import { domainToASCII, domainToUnicode } from "node:url";
 //#region ../../node_modules/.pnpm/fast-check@3.23.2/node_modules/fast-check/lib/esm/check/precondition/PreconditionFailure.js
 var PreconditionFailure = class PreconditionFailure extends Error {
 	constructor(interruptExecution = false) {
@@ -5609,138 +5605,6 @@ function anything(constraints) {
 	return anyArbitraryBuilder(toQualifiedObjectConstraints(constraints));
 }
 //#endregion
-//#region src/actor.ts
-/**
-* Checks if the given object is an {@link Actor}.
-* @param object The object to check.
-* @returns `true` if the given object is an {@link Actor}.
-*/
-function isActor(object) {
-	return object instanceof Application || object instanceof Group || object instanceof Organization || object instanceof Person || object instanceof Service;
-}
-/**
-* Gets the type name of the given actor.
-* @param actor The actor to get the type name of.
-* @returns The type name of the given actor.
-*/
-function getActorTypeName(actor) {
-	if (actor instanceof Application) return "Application";
-	else if (actor instanceof Group) return "Group";
-	else if (actor instanceof Organization) return "Organization";
-	else if (actor instanceof Person) return "Person";
-	else if (actor instanceof Service) return "Service";
-	throw new Error("Unknown actor type.");
-}
-/**
-* Gets the actor class by the given type name.
-* @param typeName The type name to get the actor class by.
-* @returns The actor class by the given type name.
-*/
-function getActorClassByTypeName(typeName) {
-	switch (typeName) {
-		case "Application": return Application;
-		case "Group": return Group;
-		case "Organization": return Organization;
-		case "Person": return Person;
-		case "Service": return Service;
-	}
-	throw new Error("Unknown actor type name.");
-}
-/**
-* Gets the actor handle, of the form `@username@domain`, from the given actor
-* or an actor URI.
-*
-* @example
-* ``` typescript
-* // Get the handle of an actor object:
-* await getActorHandle(
-*   new Person({ id: new URL("https://fosstodon.org/users/hongminhee") })
-* );
-*
-* // Get the handle of an actor URI:
-* await getActorHandle(new URL("https://fosstodon.org/users/hongminhee"));
-* ```
-*
-* @param actor The actor or actor URI to get the handle from.
-* @param options The extra options for getting the actor handle.
-* @returns The actor handle.  It starts with `@` and is followed by the
-*          username and domain, separated by `@` by default (it can be
-*          customized with the options).
-* @throws {TypeError} If the actor does not have enough information to get the
-*                     handle.
-* @since 0.4.0
-*/
-async function getActorHandle(actor, options = {}) {
-	return await (options.tracerProvider ?? trace.getTracerProvider()).getTracer(name, version).startActiveSpan("activitypub.get_actor_handle", async (span) => {
-		if (isActor(actor)) {
-			if (actor.id != null) span.setAttribute("activitypub.actor.id", actor.id.href);
-			span.setAttribute("activitypub.actor.type", getTypeId(actor).href);
-		}
-		try {
-			return await getActorHandleInternal(actor, options);
-		} catch (error) {
-			span.setStatus({
-				code: SpanStatusCode.ERROR,
-				message: String(error)
-			});
-			throw error;
-		} finally {
-			span.end();
-		}
-	});
-}
-async function getActorHandleInternal(actor, options = {}) {
-	const actorId = actor instanceof URL ? actor : actor.id;
-	if (actorId != null) {
-		const result = await lookupWebFinger(actorId, {
-			userAgent: options.userAgent,
-			tracerProvider: options.tracerProvider
-		});
-		if (result != null) {
-			const aliases = [...result.aliases ?? []];
-			if (result.subject != null) aliases.unshift(result.subject);
-			for (const alias of aliases) {
-				const match = alias.match(/^acct:([^@]+)@([^@]+)$/);
-				if (match != null) {
-					if (new URL(`https://${match[2]}/`).hostname !== actorId.hostname && !await verifyCrossOriginActorHandle(actorId.href, alias, options.userAgent, options.tracerProvider)) continue;
-					return normalizeActorHandle(`@${match[1]}@${match[2]}`, options);
-				}
-			}
-		}
-	}
-	if (!(actor instanceof URL) && actor.preferredUsername != null && actor.id != null) return normalizeActorHandle(`@${actor.preferredUsername}@${actor.id.host}`, options);
-	throw new TypeError("Actor does not have enough information to get the handle.");
-}
-async function verifyCrossOriginActorHandle(actorId, alias, userAgent, tracerProvider) {
-	const response = await lookupWebFinger(alias, {
-		userAgent,
-		tracerProvider
-	});
-	if (response == null) return false;
-	for (const alias of response.aliases ?? []) if (new URL(alias).href === actorId) return true;
-	return false;
-}
-/**
-* Normalizes the given actor handle.
-* @param handle The full handle of the actor to normalize.
-* @param options The options for normalizing the actor handle.
-* @returns The normalized actor handle.
-* @throws {TypeError} If the actor handle is invalid.
-* @since 0.9.0
-*/
-function normalizeActorHandle(handle, options = {}) {
-	handle = handle.replace(/^@/, "");
-	const atPos = handle.indexOf("@");
-	if (atPos < 1) throw new TypeError("Invalid actor handle.");
-	let domain = handle.substring(atPos + 1);
-	if (domain.length < 1 || domain.includes("@")) throw new TypeError("Invalid actor handle.");
-	domain = domain.toLowerCase();
-	domain = options.punycode ? domainToASCII(domain) : domainToUnicode(domain);
-	domain = domain.toLowerCase();
-	const user = handle.substring(0, atPos);
-	return options.trimLeadingAt ? `${user}@${domain}` : `@${user}@${domain}`;
-}
-//#endregion
 //#region src/actor.test.ts
 function actorClass() {
 	return constantFrom(Application, Group, Organization, Person, Service);

package/dist-tests/lookup.test.mjs

@@ -1,10 +1,10 @@
 import { Temporal } from "@js-temporal/polyfill";
 globalThis.addEventListener = () => {};
 import { g as Object$1, h as Note, i as Collection, y as Person } from "./vocab-B0Z-tH4q.mjs";
-import { n as version, r as esm_default, t as name } from "./deno-C05d783V.mjs";
+import { c as esm_default, i as isActor, o as name, s as version } from "./actor-DBM2eKvJ.mjs";
 import { t as getTypeId } from "./type-Cf-vxmre.mjs";
 import { t as assertInstanceOf } from "./utils-CE8Dk5hm.mjs";
-import { createTestTracerProvider, mockDocumentLoader, test } from "@fedify/fixture";
+import { createTestMeterProvider, createTestTracerProvider, mockDocumentLoader, test } from "@fedify/fixture";
 import { deepStrictEqual, equal, ok, rejects } from "node:assert/strict";
 import { lookupWebFinger } from "@fedify/webfinger";
 import { SpanStatusCode, trace } from "@opentelemetry/api";
@@ -67,6 +67,40 @@ function toAcctUrl(handle) {
 }
 //#endregion
 //#region src/lookup.ts
+const objectLookupCounters = /* @__PURE__ */ new WeakMap();
+function getObjectLookupCounter(meterProvider) {
+	let counter = objectLookupCounters.get(meterProvider);
+	if (counter == null) {
+		counter = meterProvider.getMeter(name, version).createCounter("activitypub.object.lookup", {
+			description: "ActivityStreams object lookups via lookupObject(), classified by whether the resolved value is an Actor.",
+			unit: "{lookup}"
+		});
+		objectLookupCounters.set(meterProvider, counter);
+	}
+	return counter;
+}
+function getLookupRemoteHost(identifier) {
+	let url;
+	if (identifier instanceof URL) url = identifier;
+	else try {
+		url = new URL(identifier);
+	} catch {
+		return extractHandleHost(identifier.startsWith("@") ? identifier.slice(1) : identifier);
+	}
+	if (url.hostname !== "") return url.hostname;
+	if (url.protocol === "acct:") return extractHandleHost(url.pathname);
+}
+function extractHandleHost(handle) {
+	const at = handle.lastIndexOf("@");
+	if (at < 0 || at >= handle.length - 1) return void 0;
+	const candidate = handle.slice(at + 1);
+	if (/[/?#\s]/.test(candidate)) return void 0;
+	try {
+		return new URL(`https://${candidate}`).hostname || void 0;
+	} catch {
+		return;
+	}
+}
 const logger = getLogger([
 	"fedify",
 	"vocab",
@@ -106,8 +140,10 @@ const logger = getLogger([
 */
 async function lookupObject(identifier, options = {}) {
 	return await (options.tracerProvider ?? trace.getTracerProvider()).getTracer(name, version).startActiveSpan("activitypub.lookup_object", async (span) => {
+		let kind = "other";
 		try {
 			const result = await lookupObjectInternal(identifier, options);
+			if (result != null) kind = isActor(result) ? "actor" : "object";
 			if (result == null) span.setStatus({ code: SpanStatusCode.ERROR });
 			else {
 				if (result.id != null) span.setAttribute("activitypub.object.id", result.id.href);
@@ -127,6 +163,12 @@ async function lookupObject(identifier, options = {}) {
 			});
 			throw error;
 		} finally {
+			if (options.meterProvider != null) {
+				const attributes = { "activitypub.lookup.kind": kind };
+				const host = getLookupRemoteHost(identifier);
+				if (host != null) attributes["activitypub.remote.host"] = host;
+				getObjectLookupCounter(options.meterProvider).add(1, attributes);
+			}
 			span.end();
 		}
 	});
@@ -668,5 +710,110 @@ test("lookupObject() records OpenTelemetry span events", async () => {
 	ok(typeof event.attributes["activitypub.object.json"] === "string");
 	deepStrictEqual(JSON.parse(event.attributes["activitypub.object.json"]).id, "https://example.com/object");
 });
+test("lookupObject() records activitypub.object.lookup counter", {
+	sanitizeResources: false,
+	sanitizeOps: false
+}, async (t) => {
+	esm_default.spyGlobal();
+	try {
+		esm_default.removeRoutes();
+		esm_default.get("begin:https://example.com/.well-known/webfinger", {
+			subject: "acct:johndoe@example.com",
+			links: [{
+				rel: "self",
+				href: "https://example.com/person",
+				type: "application/activity+json"
+			}]
+		});
+		await t.step("records kind=actor for an actor result", async () => {
+			const [meterProvider, recorder] = createTestMeterProvider();
+			assertInstanceOf(await lookupObject("@johndoe@example.com", {
+				documentLoader: mockDocumentLoader,
+				contextLoader: mockDocumentLoader,
+				meterProvider
+			}), Person);
+			const counters = recorder.getMeasurements("activitypub.object.lookup");
+			deepStrictEqual(counters.length, 1);
+			deepStrictEqual(counters[0].type, "counter");
+			deepStrictEqual(counters[0].value, 1);
+			deepStrictEqual(counters[0].attributes["activitypub.lookup.kind"], "actor");
+			deepStrictEqual(counters[0].attributes["activitypub.remote.host"], "example.com");
+			deepStrictEqual(recorder.getMeasurements("activitypub.document.fetch").length, 0);
+		});
+		await t.step("records kind=object for a non-actor object", async () => {
+			const [meterProvider, recorder] = createTestMeterProvider();
+			assertInstanceOf(await lookupObject("https://example.com/object", {
+				documentLoader: mockDocumentLoader,
+				contextLoader: mockDocumentLoader,
+				meterProvider
+			}), Object$1);
+			const counters = recorder.getMeasurements("activitypub.object.lookup");
+			deepStrictEqual(counters.length, 1);
+			deepStrictEqual(counters[0].attributes["activitypub.lookup.kind"], "object");
+			deepStrictEqual(counters[0].attributes["activitypub.remote.host"], "example.com");
+		});
+		await t.step("records kind=other on null result", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger", {
+				subject: "acct:janedoe@example.com",
+				links: [{
+					rel: "self",
+					href: "https://example.com/404",
+					type: "application/activity+json"
+				}]
+			});
+			const [meterProvider, recorder] = createTestMeterProvider();
+			deepStrictEqual(await lookupObject("janedoe@example.com", {
+				documentLoader: mockDocumentLoader,
+				contextLoader: mockDocumentLoader,
+				meterProvider
+			}), null);
+			const counters = recorder.getMeasurements("activitypub.object.lookup");
+			deepStrictEqual(counters.length, 1);
+			deepStrictEqual(counters[0].attributes["activitypub.lookup.kind"], "other");
+			deepStrictEqual(counters[0].attributes["activitypub.remote.host"], "example.com");
+		});
+		await t.step("omits counter when no meterProvider is provided", async () => {
+			const [_unused, recorder] = createTestMeterProvider();
+			await lookupObject("https://example.com/object", {
+				documentLoader: mockDocumentLoader,
+				contextLoader: mockDocumentLoader
+			});
+			deepStrictEqual(recorder.getMeasurements("activitypub.object.lookup").length, 0);
+		});
+		await t.step("extracts host from a URL acct: instance", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger", {
+				subject: "acct:johndoe@example.com",
+				links: [{
+					rel: "self",
+					href: "https://example.com/person",
+					type: "application/activity+json"
+				}]
+			});
+			const [meterProvider, recorder] = createTestMeterProvider();
+			await lookupObject(new URL("acct:johndoe@example.com"), {
+				documentLoader: mockDocumentLoader,
+				contextLoader: mockDocumentLoader,
+				meterProvider
+			});
+			deepStrictEqual(recorder.getMeasurement("activitypub.object.lookup")?.attributes["activitypub.remote.host"], "example.com");
+		});
+		await t.step("omits host when the identifier carries path/query characters", async () => {
+			const [meterProvider, recorder] = createTestMeterProvider();
+			await lookupObject("johndoe@example.com/leak", {
+				documentLoader: mockDocumentLoader,
+				contextLoader: mockDocumentLoader,
+				meterProvider
+			});
+			const counter = recorder.getMeasurement("activitypub.object.lookup");
+			ok(counter != null);
+			deepStrictEqual("activitypub.remote.host" in counter.attributes, false, "high-cardinality handle suffixes must not be recorded as remote.host");
+		});
+	} finally {
+		esm_default.removeRoutes();
+		esm_default.hardReset();
+	}
+});
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab",
-  "version": "2.3.0-dev.1119+6cc02662",
+  "version": "2.3.0-dev.1131+553b59b8",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",
@@ -46,9 +46,9 @@
     "es-toolkit": "1.46.1",
     "jsonld": "^9.0.0",
     "pkijs": "^3.3.3",
-    "@fedify/webfinger": "2.3.0-dev.1119+6cc02662",
-    "@fedify/vocab-tools": "2.3.0-dev.1119+6cc02662",
-    "@fedify/vocab-runtime": "2.3.0-dev.1119+6cc02662"
+    "@fedify/vocab-tools": "2.3.0-dev.1131+553b59b8",
+    "@fedify/webfinger": "2.3.0-dev.1131+553b59b8",
+    "@fedify/vocab-runtime": "2.3.0-dev.1131+553b59b8"
   },
   "devDependencies": {
     "@types/node": "^22.17.0",

package/src/lookup.test.ts

@@ -1,4 +1,5 @@
 import {
+  createTestMeterProvider,
   createTestTracerProvider,
   mockDocumentLoader,
   test,
@@ -693,4 +694,175 @@ test("lookupObject() records OpenTelemetry span events", async () => {
   deepStrictEqual(recordedObject.id, "https://example.com/object");
 });
 
+test("lookupObject() records activitypub.object.lookup counter", {
+  sanitizeResources: false,
+  sanitizeOps: false,
+}, async (t) => {
+  fetchMock.spyGlobal();
+  // Cleanup must run even if a test step throws so the global `fetch`
+  // spy does not leak into subsequent tests.
+  try {
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://example.com/.well-known/webfinger",
+      {
+        subject: "acct:johndoe@example.com",
+        links: [
+          {
+            rel: "self",
+            href: "https://example.com/person",
+            type: "application/activity+json",
+          },
+        ],
+      },
+    );
+
+    await t.step("records kind=actor for an actor result", async () => {
+      const [meterProvider, recorder] = createTestMeterProvider();
+      const person = await lookupObject("@johndoe@example.com", {
+        documentLoader: mockDocumentLoader,
+        contextLoader: mockDocumentLoader,
+        meterProvider,
+      });
+      assertInstanceOf(person, Person);
+      const counters = recorder.getMeasurements("activitypub.object.lookup");
+      deepStrictEqual(counters.length, 1);
+      deepStrictEqual(counters[0].type, "counter");
+      deepStrictEqual(counters[0].value, 1);
+      deepStrictEqual(
+        counters[0].attributes["activitypub.lookup.kind"],
+        "actor",
+      );
+      deepStrictEqual(
+        counters[0].attributes["activitypub.remote.host"],
+        "example.com",
+      );
+      // No `activitypub.document.fetch` measurement should be recorded by
+      // lookupObject itself; that lives on the document-loader path.
+      deepStrictEqual(
+        recorder.getMeasurements("activitypub.document.fetch").length,
+        0,
+      );
+    });
+
+    await t.step("records kind=object for a non-actor object", async () => {
+      const [meterProvider, recorder] = createTestMeterProvider();
+      const object = await lookupObject("https://example.com/object", {
+        documentLoader: mockDocumentLoader,
+        contextLoader: mockDocumentLoader,
+        meterProvider,
+      });
+      assertInstanceOf(object, Object);
+      const counters = recorder.getMeasurements("activitypub.object.lookup");
+      deepStrictEqual(counters.length, 1);
+      deepStrictEqual(
+        counters[0].attributes["activitypub.lookup.kind"],
+        "object",
+      );
+      deepStrictEqual(
+        counters[0].attributes["activitypub.remote.host"],
+        "example.com",
+      );
+    });
+
+    await t.step("records kind=other on null result", async () => {
+      fetchMock.removeRoutes();
+      fetchMock.get("begin:https://example.com/.well-known/webfinger", {
+        subject: "acct:janedoe@example.com",
+        links: [
+          {
+            rel: "self",
+            href: "https://example.com/404",
+            type: "application/activity+json",
+          },
+        ],
+      });
+      const [meterProvider, recorder] = createTestMeterProvider();
+      const result = await lookupObject("janedoe@example.com", {
+        documentLoader: mockDocumentLoader,
+        contextLoader: mockDocumentLoader,
+        meterProvider,
+      });
+      deepStrictEqual(result, null);
+      const counters = recorder.getMeasurements("activitypub.object.lookup");
+      deepStrictEqual(counters.length, 1);
+      deepStrictEqual(
+        counters[0].attributes["activitypub.lookup.kind"],
+        "other",
+      );
+      deepStrictEqual(
+        counters[0].attributes["activitypub.remote.host"],
+        "example.com",
+      );
+    });
+
+    await t.step(
+      "omits counter when no meterProvider is provided",
+      async () => {
+        const [_unused, recorder] = createTestMeterProvider();
+        await lookupObject("https://example.com/object", {
+          documentLoader: mockDocumentLoader,
+          contextLoader: mockDocumentLoader,
+        });
+        deepStrictEqual(
+          recorder.getMeasurements("activitypub.object.lookup").length,
+          0,
+        );
+      },
+    );
+
+    await t.step(
+      "extracts host from a URL acct: instance",
+      async () => {
+        fetchMock.removeRoutes();
+        fetchMock.get("begin:https://example.com/.well-known/webfinger", {
+          subject: "acct:johndoe@example.com",
+          links: [
+            {
+              rel: "self",
+              href: "https://example.com/person",
+              type: "application/activity+json",
+            },
+          ],
+        });
+        const [meterProvider, recorder] = createTestMeterProvider();
+        await lookupObject(new URL("acct:johndoe@example.com"), {
+          documentLoader: mockDocumentLoader,
+          contextLoader: mockDocumentLoader,
+          meterProvider,
+        });
+        const counter = recorder.getMeasurement("activitypub.object.lookup");
+        deepStrictEqual(
+          counter?.attributes["activitypub.remote.host"],
+          "example.com",
+        );
+      },
+    );
+
+    await t.step(
+      "omits host when the identifier carries path/query characters",
+      async () => {
+        const [meterProvider, recorder] = createTestMeterProvider();
+        // The bare-handle parser must refuse to put a path-bearing string
+        // like "example.com/leak" into the metric attribute.
+        await lookupObject("johndoe@example.com/leak", {
+          documentLoader: mockDocumentLoader,
+          contextLoader: mockDocumentLoader,
+          meterProvider,
+        });
+        const counter = recorder.getMeasurement("activitypub.object.lookup");
+        ok(counter != null);
+        deepStrictEqual(
+          "activitypub.remote.host" in counter.attributes,
+          false,
+          "high-cardinality handle suffixes must not be recorded as remote.host",
+        );
+      },
+    );
+  } finally {
+    fetchMock.removeRoutes();
+    fetchMock.hardReset();
+  }
+});
+
 // cSpell: ignore gildong

package/src/lookup.ts

@@ -6,13 +6,95 @@ import {
 } from "@fedify/vocab-runtime";
 import { lookupWebFinger } from "@fedify/webfinger";
 import { getLogger } from "@logtape/logtape";
-import { SpanStatusCode, trace, type TracerProvider } from "@opentelemetry/api";
+import {
+  type Attributes,
+  type Counter,
+  type MeterProvider,
+  SpanStatusCode,
+  trace,
+  type TracerProvider,
+} from "@opentelemetry/api";
 import { delay } from "es-toolkit";
 import metadata from "../deno.json" with { type: "json" };
+import { isActor } from "./actor.ts";
 import { toAcctUrl } from "./handle.ts";
 import { getTypeId } from "./type.ts";
 import { type Collection, type Link, Object } from "./vocab.ts";
 
+/**
+ * The classification of an ActivityStreams lookup performed by
+ * {@link lookupObject}, recorded as `activitypub.lookup.kind` on the
+ * `activitypub.object.lookup` counter.
+ *
+ *  -  `actor`: the resolved object is an {@link import("./actor.ts").Actor}.
+ *  -  `object`: the resolved object is a non-actor ActivityStreams object.
+ *  -  `other`: the lookup did not resolve to an object (not found, network
+ *     failure, parse failure).
+ * @since 2.3.0
+ */
+export type ObjectLookupKind = "actor" | "object" | "other";
+
+const objectLookupCounters = new WeakMap<MeterProvider, Counter>();
+
+function getObjectLookupCounter(meterProvider: MeterProvider): Counter {
+  let counter = objectLookupCounters.get(meterProvider);
+  if (counter == null) {
+    counter = meterProvider
+      .getMeter(metadata.name, metadata.version)
+      .createCounter("activitypub.object.lookup", {
+        description:
+          "ActivityStreams object lookups via lookupObject(), classified " +
+          "by whether the resolved value is an Actor.",
+        unit: "{lookup}",
+      });
+    objectLookupCounters.set(meterProvider, counter);
+  }
+  return counter;
+}
+
+function getLookupRemoteHost(identifier: string | URL): string | undefined {
+  let url: URL | undefined;
+  if (identifier instanceof URL) {
+    url = identifier;
+  } else {
+    try {
+      url = new URL(identifier);
+    } catch {
+      // Not a URL — try to interpret as a bare fediverse handle below.
+      const stripped = identifier.startsWith("@")
+        ? identifier.slice(1)
+        : identifier;
+      return extractHandleHost(stripped);
+    }
+  }
+  if (url.hostname !== "") return url.hostname;
+  // `acct:` URIs are opaque (no `//host` form), so the URL hostname is
+  // empty.  The user and authority live in `url.pathname` as
+  // `user@host`; reuse the same handle-extraction logic, which both
+  // takes only the substring after the last `@` and refuses to record
+  // anything that looks like a path / query / fragment rather than a
+  // bare hostname.
+  if (url.protocol === "acct:") return extractHandleHost(url.pathname);
+  return undefined;
+}
+
+function extractHandleHost(handle: string): string | undefined {
+  const at = handle.lastIndexOf("@");
+  if (at < 0 || at >= handle.length - 1) return undefined;
+  const candidate = handle.slice(at + 1);
+  // Reject anything that is not just an authority — paths, queries,
+  // fragments, and spaces would all leak high-cardinality metadata into
+  // the metric attribute, so we drop the host entirely in those cases.
+  if (/[/?#\s]/.test(candidate)) return undefined;
+  // Round-trip through `URL` so the parser validates the authority and
+  // strips any port/userinfo before we record it.
+  try {
+    return new URL(`https://${candidate}`).hostname || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 const logger = getLogger(["fedify", "vocab", "lookup"]);
 
 /**
@@ -67,6 +149,15 @@ export interface LookupObjectOptions {
    */
   tracerProvider?: TracerProvider;
 
+  /**
+   * The OpenTelemetry meter provider used to record the
+   * `activitypub.object.lookup` counter.  If omitted, the counter is not
+   * emitted at all (the helper is opt-in to avoid touching the global
+   * meter provider for callers that do not use OpenTelemetry).
+   * @since 2.3.0
+   */
+  meterProvider?: MeterProvider;
+
   /**
    * AbortSignal for cancelling the request.
    * @since 1.8.0
@@ -118,8 +209,16 @@ export async function lookupObject(
   return await tracer.startActiveSpan(
     "activitypub.lookup_object",
     async (span) => {
+      let kind: ObjectLookupKind = "other";
       try {
         const result = await lookupObjectInternal(identifier, options);
+        // Classify the result as soon as `lookupObjectInternal` returns,
+        // so that any subsequent throw (for example from
+        // `result.toJsonLd(options)` while building the span event) does
+        // not roll `kind` back to `"other"` in the `finally` block.
+        if (result != null) {
+          kind = isActor(result) ? "actor" : "object";
+        }
         if (result == null) span.setStatus({ code: SpanStatusCode.ERROR });
         else {
           if (result.id != null) {
@@ -150,6 +249,14 @@ export async function lookupObject(
         });
         throw error;
       } finally {
+        if (options.meterProvider != null) {
+          const attributes: Attributes = {
+            "activitypub.lookup.kind": kind,
+          };
+          const host = getLookupRemoteHost(identifier);
+          if (host != null) attributes["activitypub.remote.host"] = host;
+          getObjectLookupCounter(options.meterProvider).add(1, attributes);
+        }
         span.end();
       }
     },