@fedify/vocab 2.5.0-dev.2446 → 2.5.0-dev.2448

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab",
-  "version": "2.5.0-dev.2446+2014cb03",
+  "version": "2.5.0-dev.2448+756933d0",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts"

package/dist/mod.cjs

@@ -36,7 +36,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.5.0-dev.2446+2014cb03";
+var version = "2.5.0-dev.2448+756933d0";
 //#endregion
 //#region src/type.ts
 function getTypeId(object) {
@@ -81571,6 +81571,20 @@ const logger = (0, _logtape_logtape.getLogger)([
 	"lookup"
 ]);
 /**
+* Options for the {@link lookupObject} function.
+*
+* @since 0.2.0
+*/
+/**
+* The key of the {@link LookupObjectOptions} property that observes how
+* {@link lookupObject} selects the object it returns.
+*
+* @internal Technically exported for other Fedify packages, but not part of
+* the public API contract.  This is not considered public API for Semantic
+* Versioning decisions.
+*/
+const lookupObserver = Symbol.for("@fedify/vocab/lookupObserver");
+/**
 * The maximum number of requests to FEP-ef61 gateways that a single
 * {@link lookupObject} call makes for portable objects.  Gateways come from
 * possibly untrusted WebFinger responses and location hints, so they are
@@ -81690,8 +81704,13 @@ async function lookupObjectInternal(identifier, options = {}) {
 			remoteDoc = await documentLoader(identifier.href, { signal: options.signal });
 		} catch (error) {
 			logger.debug("Failed to fetch remote document:\n{error}", { error });
+			options[lookupObserver]?.failed?.({
+				operation: "fetch",
+				error
+			});
 		}
 	}
+	if (remoteDoc == null && options[lookupObserver]?.webFinger === false) return null;
 	if (remoteDoc == null) {
 		const jrd = await (0, _fedify_webfinger.lookupWebFinger)(identifier, {
 			userAgent: options.userAgent,
@@ -81736,7 +81755,7 @@ async function lookupObjectInternal(identifier, options = {}) {
 		}
 	}
 	if (remoteDoc == null) return null;
-	const snapshot = options.verifyPortableObject == null ? null : (0, _fedify_vocab_runtime_internal_portable_dereference.createSnapshotContextLoader)(options.contextLoader ?? (0, _fedify_vocab_runtime.getDocumentLoader)({ userAgent: options.userAgent }));
+	const snapshot = options.verifyPortableObject == null && options[lookupObserver] == null ? null : (0, _fedify_vocab_runtime_internal_portable_dereference.createSnapshotContextLoader)(options.contextLoader ?? (0, _fedify_vocab_runtime.getDocumentLoader)({ userAgent: options.userAgent }));
 	try {
 		let object;
 		let documentUrl;
@@ -81750,6 +81769,10 @@ async function lookupObjectInternal(identifier, options = {}) {
 				baseUrl: documentUrl
 			});
 		} catch (error) {
+			options[lookupObserver]?.failed?.({
+				operation: "parse",
+				error
+			});
 			if (error instanceof TypeError) {
 				logger.debug("Failed to parse JSON-LD document: {error}\n{document}", {
 					...remoteDoc,
@@ -81759,7 +81782,7 @@ async function lookupObjectInternal(identifier, options = {}) {
 			}
 			throw error;
 		}
-		if (snapshot != null) {
+		if (options.verifyPortableObject != null && snapshot != null) {
 			const claim = (0, _fedify_vocab_runtime_internal_portable_dereference.getPortableResponseClaim)(remoteDoc.documentUrl, object.id);
 			if (claim === null) {
 				logger.debug("Refusing the document {documentUrl}, as it claims to be a portable object with a malformed compatible identifier.", { documentUrl: remoteDoc.documentUrl });
@@ -81778,8 +81801,16 @@ async function lookupObjectInternal(identifier, options = {}) {
 				...remoteDoc,
 				objectId: object.id.href
 			});
+			options[lookupObserver]?.failed?.({ operation: "origin" });
 			return null;
 		}
+		if (!await (0, _fedify_vocab_runtime_internal_portable_dereference.acceptCandidate)(options[lookupObserver], {
+			document: remoteDoc.document,
+			documentUrl: remoteDoc.documentUrl,
+			baseUrl: documentUrl,
+			contextLoader: snapshot?.loader ?? options.contextLoader ?? (0, _fedify_vocab_runtime.getDocumentLoader)({ userAgent: options.userAgent }),
+			object
+		})) return null;
 		return object;
 	} finally {
 		snapshot?.release();
@@ -81893,6 +81924,7 @@ async function dereference({ options, documentLoader }, id, inferredGateways, ga
 			verifyPortableObject: options.verifyPortableObject,
 			crossOrigin: options.crossOrigin === "throw" ? "throw" : "ignore",
 			signal: options.signal,
+			observer: options[lookupObserver],
 			parse: (document, { contextLoader, baseUrl }) => Object$1.fromJsonLd(document, {
 				documentLoader,
 				contextLoader,
@@ -82043,6 +82075,7 @@ exports.isActor = isActor;
 exports.isEntityType = isEntityType;
 exports.isFediverseHandle = isFediverseHandle;
 exports.lookupObject = lookupObject;
+exports.lookupObserver = lookupObserver;
 exports.normalizeActorHandle = normalizeActorHandle;
 exports.normalizeLinkToImage = normalizeLinkToImage;
 exports.parseFediverseHandle = parseFediverseHandle;

package/dist/mod.d.cts

@@ -1,6 +1,7 @@
 /// <reference lib="esnext.temporal" />
 import { Decimal, Decimal as Decimal$1, DocumentLoader, DocumentLoader as DocumentLoader$1, DocumentLoaderOptions, GetUserAgentOptions, GetUserAgentOptions as GetUserAgentOptions$1, Json, LanguageString, LanguageString as LanguageString$1, PortableObjectReferrer, PortableObjectVerification, PortableObjectVerifier, PortableObjectVerifier as PortableObjectVerifier$1, PortableObjectVerifierOptions, PropertyPreprocessor, PropertyPreprocessor as PropertyPreprocessor$1, PropertyPreprocessorContext, RemoteDocument } from "@fedify/vocab-runtime";
 import { MeterProvider, Span, TracerProvider } from "@opentelemetry/api";
+import { DereferenceObserver } from "@fedify/vocab-runtime/internal/portable-dereference";
 
 //#region src/vocab.d.ts
 /** Describes an object of any kind. The Object type serves as the base type for
@@ -25673,6 +25674,34 @@ type ObjectLookupKind = "actor" | "object" | "other";
 *
 * @since 0.2.0
 */
+/**
+* The key of the {@link LookupObjectOptions} property that observes how
+* {@link lookupObject} selects the object it returns.
+*
+* @internal Technically exported for other Fedify packages, but not part of
+* the public API contract.  This is not considered public API for Semantic
+* Versioning decisions.
+*/
+declare const lookupObserver: unique symbol;
+/**
+* Observes how {@link lookupObject} selects the object it returns: each
+* candidate is offered to {@link DereferenceObserver.accept} at the boundary
+* that would otherwise return it, both for ordinary documents and for
+* FEP-ef61 portable objects, and each failure that does not propagate is
+* reported to {@link DereferenceObserver.failed}.  The observer is not passed
+* on to the returned object.
+*
+* @internal Technically exported for other Fedify packages, but not part of
+* the public API contract.  This is not considered public API for Semantic
+* Versioning decisions.
+*/
+interface LookupObserver extends DereferenceObserver<Object$1> {
+  /**
+  * Whether to fall back to WebFinger when an HTTP(S) URL cannot be fetched.
+  * Defaults to `true`.
+  */
+  readonly webFinger?: boolean;
+}
 interface LookupObjectOptions {
   /**
   * The document loader for loading remote JSON-LD documents.
@@ -25768,6 +25797,11 @@ interface LookupObjectOptions {
   * @since 2.4.0
   */
   verifyPortableObject?: PortableObjectVerifier$1;
+  /**
+  * See {@link LookupObserver}.
+  * @internal
+  */
+  [lookupObserver]?: LookupObserver;
 }
 /**
 * Looks up an ActivityStreams object by its URI (including `acct:` URIs)
@@ -25992,4 +26026,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, ActorDiscoveryResult, ActorTypeName, Add, Agreement, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Commitment, Create, CryptographicKey, DataIntegrityProof, type Decimal, Delete, DidService, Dislike, Document, type DocumentLoader, type DocumentLoaderOptions, Emoji, EmojiReact, Endpoints, Event, Export, FeatureAuthorization, FeatureRequest, FeaturedCollection, FeaturedItem, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, type Json, 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, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, Profile, type PropertyPreprocessor, type PropertyPreprocessorContext, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Translation, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, normalizeLinkToImage, parseFediverseHandle, toAcctUrl, traverseCollection };
+export { $EntityType, Accept, Activity, Actor, ActorDiscoveryResult, ActorTypeName, Add, Agreement, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Commitment, Create, CryptographicKey, DataIntegrityProof, type Decimal, Delete, DidService, Dislike, Document, type DocumentLoader, type DocumentLoaderOptions, Emoji, EmojiReact, Endpoints, Event, Export, FeatureAuthorization, FeatureRequest, FeaturedCollection, FeaturedItem, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, type Json, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, LookupObjectOptions, LookupObserver, Measure, Mention, Move, Multikey, NormalizeActorHandleOptions, Note, Object$1 as Object, ObjectLookupKind, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, Profile, type PropertyPreprocessor, type PropertyPreprocessorContext, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Translation, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, lookupObserver, normalizeActorHandle, normalizeLinkToImage, parseFediverseHandle, toAcctUrl, traverseCollection };

package/dist/mod.d.ts

@@ -1,6 +1,7 @@
 /// <reference lib="esnext.temporal" />
 import { Decimal, Decimal as Decimal$1, DocumentLoader, DocumentLoader as DocumentLoader$1, DocumentLoaderOptions, GetUserAgentOptions, GetUserAgentOptions as GetUserAgentOptions$1, Json, LanguageString, LanguageString as LanguageString$1, PortableObjectReferrer, PortableObjectVerification, PortableObjectVerifier, PortableObjectVerifier as PortableObjectVerifier$1, PortableObjectVerifierOptions, PropertyPreprocessor, PropertyPreprocessor as PropertyPreprocessor$1, PropertyPreprocessorContext, RemoteDocument } from "@fedify/vocab-runtime";
 import { MeterProvider, Span, TracerProvider } from "@opentelemetry/api";
+import { DereferenceObserver } from "@fedify/vocab-runtime/internal/portable-dereference";
 
 //#region src/vocab.d.ts
 /** Describes an object of any kind. The Object type serves as the base type for
@@ -25673,6 +25674,34 @@ type ObjectLookupKind = "actor" | "object" | "other";
 *
 * @since 0.2.0
 */
+/**
+* The key of the {@link LookupObjectOptions} property that observes how
+* {@link lookupObject} selects the object it returns.
+*
+* @internal Technically exported for other Fedify packages, but not part of
+* the public API contract.  This is not considered public API for Semantic
+* Versioning decisions.
+*/
+declare const lookupObserver: unique symbol;
+/**
+* Observes how {@link lookupObject} selects the object it returns: each
+* candidate is offered to {@link DereferenceObserver.accept} at the boundary
+* that would otherwise return it, both for ordinary documents and for
+* FEP-ef61 portable objects, and each failure that does not propagate is
+* reported to {@link DereferenceObserver.failed}.  The observer is not passed
+* on to the returned object.
+*
+* @internal Technically exported for other Fedify packages, but not part of
+* the public API contract.  This is not considered public API for Semantic
+* Versioning decisions.
+*/
+interface LookupObserver extends DereferenceObserver<Object$1> {
+  /**
+  * Whether to fall back to WebFinger when an HTTP(S) URL cannot be fetched.
+  * Defaults to `true`.
+  */
+  readonly webFinger?: boolean;
+}
 interface LookupObjectOptions {
   /**
   * The document loader for loading remote JSON-LD documents.
@@ -25768,6 +25797,11 @@ interface LookupObjectOptions {
   * @since 2.4.0
   */
   verifyPortableObject?: PortableObjectVerifier$1;
+  /**
+  * See {@link LookupObserver}.
+  * @internal
+  */
+  [lookupObserver]?: LookupObserver;
 }
 /**
 * Looks up an ActivityStreams object by its URI (including `acct:` URIs)
@@ -25992,4 +26026,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, ActorDiscoveryResult, ActorTypeName, Add, Agreement, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Commitment, Create, CryptographicKey, DataIntegrityProof, type Decimal, Delete, DidService, Dislike, Document, type DocumentLoader, type DocumentLoaderOptions, Emoji, EmojiReact, Endpoints, Event, Export, FeatureAuthorization, FeatureRequest, FeaturedCollection, FeaturedItem, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, type Json, 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, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, Profile, type PropertyPreprocessor, type PropertyPreprocessorContext, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Translation, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, normalizeLinkToImage, parseFediverseHandle, toAcctUrl, traverseCollection };
+export { $EntityType, Accept, Activity, Actor, ActorDiscoveryResult, ActorTypeName, Add, Agreement, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Commitment, Create, CryptographicKey, DataIntegrityProof, type Decimal, Delete, DidService, Dislike, Document, type DocumentLoader, type DocumentLoaderOptions, Emoji, EmojiReact, Endpoints, Event, Export, FeatureAuthorization, FeatureRequest, FeaturedCollection, FeaturedItem, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, type Json, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, LookupObjectOptions, LookupObserver, Measure, Mention, Move, Multikey, NormalizeActorHandleOptions, Note, Object$1 as Object, ObjectLookupKind, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, Profile, type PropertyPreprocessor, type PropertyPreprocessorContext, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Translation, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, lookupObserver, normalizeActorHandle, normalizeLinkToImage, parseFediverseHandle, toAcctUrl, traverseCollection };

package/dist/mod.js

@@ -6,13 +6,13 @@ import { domainToASCII, domainToUnicode } from "node:url";
 import jsonld from "@fedify/vocab-runtime/jsonld";
 import { getLogger } from "@logtape/logtape";
 import { compactJsonLdCache, createScopedContextLoader, getPortableActorGateways, isTrustedIriOrigin, normalizeJsonLdIris } from "@fedify/vocab-runtime/internal/jsonld-cache";
-import { PortableObjectRejectedError, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject } from "@fedify/vocab-runtime/internal/portable-dereference";
+import { PortableObjectRejectedError, acceptCandidate, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject } from "@fedify/vocab-runtime/internal/portable-dereference";
 import { enterSignedValueScope, resolveSignedValues, retainedSignedValueRef } from "@fedify/vocab-runtime/internal/signed-representation";
 import { isTemporalDuration, isTemporalInstant } from "@fedify/vocab-runtime/temporal";
 import { delay } from "es-toolkit";
 //#region deno.json
 var name = "@fedify/vocab";
-var version = "2.5.0-dev.2446+2014cb03";
+var version = "2.5.0-dev.2448+756933d0";
 //#endregion
 //#region src/type.ts
 function getTypeId(object) {
@@ -77981,6 +77981,20 @@ const logger = getLogger([
 	"lookup"
 ]);
 /**
+* Options for the {@link lookupObject} function.
+*
+* @since 0.2.0
+*/
+/**
+* The key of the {@link LookupObjectOptions} property that observes how
+* {@link lookupObject} selects the object it returns.
+*
+* @internal Technically exported for other Fedify packages, but not part of
+* the public API contract.  This is not considered public API for Semantic
+* Versioning decisions.
+*/
+const lookupObserver = Symbol.for("@fedify/vocab/lookupObserver");
+/**
 * The maximum number of requests to FEP-ef61 gateways that a single
 * {@link lookupObject} call makes for portable objects.  Gateways come from
 * possibly untrusted WebFinger responses and location hints, so they are
@@ -78100,8 +78114,13 @@ async function lookupObjectInternal(identifier, options = {}) {
 			remoteDoc = await documentLoader(identifier.href, { signal: options.signal });
 		} catch (error) {
 			logger.debug("Failed to fetch remote document:\n{error}", { error });
+			options[lookupObserver]?.failed?.({
+				operation: "fetch",
+				error
+			});
 		}
 	}
+	if (remoteDoc == null && options[lookupObserver]?.webFinger === false) return null;
 	if (remoteDoc == null) {
 		const jrd = await lookupWebFinger(identifier, {
 			userAgent: options.userAgent,
@@ -78146,7 +78165,7 @@ async function lookupObjectInternal(identifier, options = {}) {
 		}
 	}
 	if (remoteDoc == null) return null;
-	const snapshot = options.verifyPortableObject == null ? null : createSnapshotContextLoader(options.contextLoader ?? getDocumentLoader({ userAgent: options.userAgent }));
+	const snapshot = options.verifyPortableObject == null && options[lookupObserver] == null ? null : createSnapshotContextLoader(options.contextLoader ?? getDocumentLoader({ userAgent: options.userAgent }));
 	try {
 		let object;
 		let documentUrl;
@@ -78160,6 +78179,10 @@ async function lookupObjectInternal(identifier, options = {}) {
 				baseUrl: documentUrl
 			});
 		} catch (error) {
+			options[lookupObserver]?.failed?.({
+				operation: "parse",
+				error
+			});
 			if (error instanceof TypeError) {
 				logger.debug("Failed to parse JSON-LD document: {error}\n{document}", {
 					...remoteDoc,
@@ -78169,7 +78192,7 @@ async function lookupObjectInternal(identifier, options = {}) {
 			}
 			throw error;
 		}
-		if (snapshot != null) {
+		if (options.verifyPortableObject != null && snapshot != null) {
 			const claim = getPortableResponseClaim(remoteDoc.documentUrl, object.id);
 			if (claim === null) {
 				logger.debug("Refusing the document {documentUrl}, as it claims to be a portable object with a malformed compatible identifier.", { documentUrl: remoteDoc.documentUrl });
@@ -78188,8 +78211,16 @@ async function lookupObjectInternal(identifier, options = {}) {
 				...remoteDoc,
 				objectId: object.id.href
 			});
+			options[lookupObserver]?.failed?.({ operation: "origin" });
 			return null;
 		}
+		if (!await acceptCandidate(options[lookupObserver], {
+			document: remoteDoc.document,
+			documentUrl: remoteDoc.documentUrl,
+			baseUrl: documentUrl,
+			contextLoader: snapshot?.loader ?? options.contextLoader ?? getDocumentLoader({ userAgent: options.userAgent }),
+			object
+		})) return null;
 		return object;
 	} finally {
 		snapshot?.release();
@@ -78303,6 +78334,7 @@ async function dereference({ options, documentLoader }, id, inferredGateways, ga
 			verifyPortableObject: options.verifyPortableObject,
 			crossOrigin: options.crossOrigin === "throw" ? "throw" : "ignore",
 			signal: options.signal,
+			observer: options[lookupObserver],
 			parse: (document, { contextLoader, baseUrl }) => Object$1.fromJsonLd(document, {
 				documentLoader,
 				contextLoader,
@@ -78351,4 +78383,4 @@ async function* traverseCollection(collection, options = {}) {
 	}
 }
 //#endregion
-export { Accept, Activity, Add, Agreement, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Commitment, Create, CryptographicKey, DataIntegrityProof, Delete, DidService, Dislike, Document, Emoji, EmojiReact, Endpoints, Event, Export, FeatureAuthorization, FeatureRequest, FeaturedCollection, FeaturedItem, Flag, Follow, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, Measure, Mention, Move, Multikey, Note, Object$1 as Object, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, Profile, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Reject, Relationship, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Translation, Travel, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, normalizeLinkToImage, parseFediverseHandle, toAcctUrl, traverseCollection };
+export { Accept, Activity, Add, Agreement, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Commitment, Create, CryptographicKey, DataIntegrityProof, Delete, DidService, Dislike, Document, Emoji, EmojiReact, Endpoints, Event, Export, FeatureAuthorization, FeatureRequest, FeaturedCollection, FeaturedItem, Flag, Follow, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, Measure, Mention, Move, Multikey, Note, Object$1 as Object, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, Profile, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Reject, Relationship, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Translation, Travel, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, lookupObserver, normalizeActorHandle, normalizeLinkToImage, parseFediverseHandle, toAcctUrl, traverseCollection };

package/dist-tests/{actor-C89Bex4F.mjs → actor-C93GLWk5.mjs}

@@ -8,7 +8,7 @@ import { SpanStatusCode, trace } from "@opentelemetry/api";
 import { domainToASCII, domainToUnicode } from "node:url";
 //#region deno.json
 var name = "@fedify/vocab";
-var version = "2.5.0-dev.2446+2014cb03";
+var version = "2.5.0-dev.2448+756933d0";
 //#endregion
 //#region src/actor.ts
 const ACTOR_DISCOVERY_HISTOGRAM_BUCKETS = [

package/dist-tests/actor.test.mjs

@@ -2,7 +2,7 @@ import "temporal-polyfill";
 globalThis.addEventListener = () => {};
 import { $ as __exportAll, F as Person, P as Organization, U as Service, a as Application, b as Group } from "./vocab-jHKm_LJ6.mjs";
 import { t as esm_default } from "./esm-DtAfYdqR.mjs";
-import { a as normalizeActorHandle, i as isActor, n as getActorHandle, r as getActorTypeName, t as getActorClassByTypeName } from "./actor-C89Bex4F.mjs";
+import { a as normalizeActorHandle, i as isActor, n as getActorHandle, r as getActorTypeName, t as getActorClassByTypeName } from "./actor-C93GLWk5.mjs";
 import { createTestMeterProvider, test } from "@fedify/fixture";
 import { deepStrictEqual, ok, rejects, strictEqual, throws } from "node:assert/strict";
 //#region ../../node_modules/.pnpm/fast-check@3.23.2/node_modules/fast-check/lib/esm/check/precondition/PreconditionFailure.js

package/dist-tests/gateway.test.mjs

@@ -2,7 +2,7 @@ import "temporal-polyfill";
 globalThis.addEventListener = () => {};
 import { F as Person, M as OrderedCollection, S as Image, c as CollectionPage, k as Note, s as Collection, u as Create } from "./vocab-jHKm_LJ6.mjs";
 import { t as esm_default } from "./esm-DtAfYdqR.mjs";
-import { n as traverseCollection, t as lookupObject } from "./lookup-BehNGq4X.mjs";
+import { r as traverseCollection, t as lookupObject } from "./lookup-C4i0dNeY.mjs";
 import { t as assertInstanceOf } from "./utils-Df2odC27.mjs";
 import { createTestTracerProvider, mockDocumentLoader, test } from "@fedify/fixture";
 import { deepStrictEqual, ok, rejects } from "node:assert/strict";

package/dist-tests/license.test.mjs

@@ -1,7 +1,7 @@
 import "temporal-polyfill";
 globalThis.addEventListener = () => {};
 import { E as Link, F as Person, J as Video, P as Organization, S as Image, U as Service, a as Application, b as Group, k as Note, s as Collection, u as Create, z as Question } from "./vocab-jHKm_LJ6.mjs";
-import "./src-fpZm9WyF.mjs";
+import "./src-Dn87CPDV.mjs";
 import { test } from "@fedify/fixture";
 import { deepStrictEqual, ok } from "node:assert/strict";
 import { getDocumentLoader, preloadedContexts } from "@fedify/vocab-runtime";

package/dist-tests/{lookup-BehNGq4X.mjs → lookup-C4i0dNeY.mjs}

@@ -1,13 +1,13 @@
 import { Temporal } from "temporal-polyfill";
 globalThis.addEventListener = () => {};
 import { A as Object$1 } from "./vocab-jHKm_LJ6.mjs";
-import { i as isActor, o as name, s as version } from "./actor-C89Bex4F.mjs";
+import { i as isActor, o as name, s as version } from "./actor-C93GLWk5.mjs";
 import { t as getTypeId } from "./type-BMdjm4Eg.mjs";
 import { canonicalizePortableUri, formatIri, getDocumentLoader, haveSameFe34Origin, haveSameIriOrigin, parseIri } from "@fedify/vocab-runtime";
 import { lookupWebFinger } from "@fedify/webfinger";
 import { SpanStatusCode, trace } from "@opentelemetry/api";
 import { getLogger } from "@logtape/logtape";
-import { PortableObjectRejectedError, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, isPortableIri, parseCompatibleEf61Reference } from "@fedify/vocab-runtime/internal/portable-dereference";
+import { PortableObjectRejectedError, acceptCandidate, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, isPortableIri, parseCompatibleEf61Reference } from "@fedify/vocab-runtime/internal/portable-dereference";
 import { delay } from "es-toolkit";
 //#region src/handle.ts
 /**
@@ -107,6 +107,20 @@ const logger = getLogger([
 	"lookup"
 ]);
 /**
+* Options for the {@link lookupObject} function.
+*
+* @since 0.2.0
+*/
+/**
+* The key of the {@link LookupObjectOptions} property that observes how
+* {@link lookupObject} selects the object it returns.
+*
+* @internal Technically exported for other Fedify packages, but not part of
+* the public API contract.  This is not considered public API for Semantic
+* Versioning decisions.
+*/
+const lookupObserver = Symbol.for("@fedify/vocab/lookupObserver");
+/**
 * The maximum number of requests to FEP-ef61 gateways that a single
 * {@link lookupObject} call makes for portable objects.  Gateways come from
 * possibly untrusted WebFinger responses and location hints, so they are
@@ -226,8 +240,13 @@ async function lookupObjectInternal(identifier, options = {}) {
 			remoteDoc = await documentLoader(identifier.href, { signal: options.signal });
 		} catch (error) {
 			logger.debug("Failed to fetch remote document:\n{error}", { error });
+			options[lookupObserver]?.failed?.({
+				operation: "fetch",
+				error
+			});
 		}
 	}
+	if (remoteDoc == null && options[lookupObserver]?.webFinger === false) return null;
 	if (remoteDoc == null) {
 		const jrd = await lookupWebFinger(identifier, {
 			userAgent: options.userAgent,
@@ -272,7 +291,7 @@ async function lookupObjectInternal(identifier, options = {}) {
 		}
 	}
 	if (remoteDoc == null) return null;
-	const snapshot = options.verifyPortableObject == null ? null : createSnapshotContextLoader(options.contextLoader ?? getDocumentLoader({ userAgent: options.userAgent }));
+	const snapshot = options.verifyPortableObject == null && options[lookupObserver] == null ? null : createSnapshotContextLoader(options.contextLoader ?? getDocumentLoader({ userAgent: options.userAgent }));
 	try {
 		let object;
 		let documentUrl;
@@ -286,6 +305,10 @@ async function lookupObjectInternal(identifier, options = {}) {
 				baseUrl: documentUrl
 			});
 		} catch (error) {
+			options[lookupObserver]?.failed?.({
+				operation: "parse",
+				error
+			});
 			if (error instanceof TypeError) {
 				logger.debug("Failed to parse JSON-LD document: {error}\n{document}", {
 					...remoteDoc,
@@ -295,7 +318,7 @@ async function lookupObjectInternal(identifier, options = {}) {
 			}
 			throw error;
 		}
-		if (snapshot != null) {
+		if (options.verifyPortableObject != null && snapshot != null) {
 			const claim = getPortableResponseClaim(remoteDoc.documentUrl, object.id);
 			if (claim === null) {
 				logger.debug("Refusing the document {documentUrl}, as it claims to be a portable object with a malformed compatible identifier.", { documentUrl: remoteDoc.documentUrl });
@@ -314,8 +337,16 @@ async function lookupObjectInternal(identifier, options = {}) {
 				...remoteDoc,
 				objectId: object.id.href
 			});
+			options[lookupObserver]?.failed?.({ operation: "origin" });
 			return null;
 		}
+		if (!await acceptCandidate(options[lookupObserver], {
+			document: remoteDoc.document,
+			documentUrl: remoteDoc.documentUrl,
+			baseUrl: documentUrl,
+			contextLoader: snapshot?.loader ?? options.contextLoader ?? getDocumentLoader({ userAgent: options.userAgent }),
+			object
+		})) return null;
 		return object;
 	} finally {
 		snapshot?.release();
@@ -429,6 +460,7 @@ async function dereference({ options, documentLoader }, id, inferredGateways, ga
 			verifyPortableObject: options.verifyPortableObject,
 			crossOrigin: options.crossOrigin === "throw" ? "throw" : "ignore",
 			signal: options.signal,
+			observer: options[lookupObserver],
 			parse: (document, { contextLoader, baseUrl }) => Object$1.fromJsonLd(document, {
 				documentLoader,
 				contextLoader,
@@ -477,4 +509,4 @@ async function* traverseCollection(collection, options = {}) {
 	}
 }
 //#endregion
-export { traverseCollection as n, lookupObject as t };
+export { lookupObserver as n, traverseCollection as r, lookupObject as t };

package/dist-tests/lookup.test.mjs

@@ -2,7 +2,7 @@ import "temporal-polyfill";
 globalThis.addEventListener = () => {};
 import { A as Object$1, F as Person, k as Note, s as Collection } from "./vocab-jHKm_LJ6.mjs";
 import { t as esm_default } from "./esm-DtAfYdqR.mjs";
-import { n as traverseCollection, t as lookupObject } from "./lookup-BehNGq4X.mjs";
+import { n as lookupObserver, r as traverseCollection, t as lookupObject } from "./lookup-C4i0dNeY.mjs";
 import { t as assertInstanceOf } from "./utils-Df2odC27.mjs";
 import { createTestMeterProvider, createTestTracerProvider, mockDocumentLoader, test } from "@fedify/fixture";
 import { deepStrictEqual, equal, ok, rejects } from "node:assert/strict";
@@ -665,5 +665,104 @@ test("lookupObject() records activitypub.object.lookup counter", {
 		esm_default.hardReset();
 	}
 });
+const OBSERVER_DID = "did:key:z6MkhVPuyvgG1RkMv67azDqDCDERPXVrUg1i3qchXY5EACE3";
+test("lookupObject() offers each candidate to the observer", async () => {
+	const note = {
+		"@context": "https://www.w3.org/ns/activitystreams",
+		id: "https://example.com/notes/1",
+		type: "Note",
+		content: "Hello"
+	};
+	const fetched = [];
+	const documentLoader = (url) => {
+		fetched.push(url);
+		if (url === "https://example.com/notes/1") return Promise.resolve({
+			contextUrl: null,
+			document: note,
+			documentUrl: "https://example.com/notes/1?redirected"
+		});
+		return Promise.reject(/* @__PURE__ */ new Error(`Not found: ${url}`));
+	};
+	const candidates = [];
+	const failures = [];
+	const accepted = await lookupObject("https://example.com/notes/1", {
+		documentLoader,
+		contextLoader: mockDocumentLoader,
+		[lookupObserver]: {
+			accept: (candidate) => {
+				candidates.push(candidate);
+				return Promise.resolve(true);
+			},
+			failed: (failure) => failures.push(failure)
+		}
+	});
+	ok(accepted instanceof Note);
+	equal(candidates.length, 1);
+	deepStrictEqual(candidates[0].document, note);
+	equal(candidates[0].documentUrl, "https://example.com/notes/1?redirected");
+	equal(candidates[0].baseUrl.href, "https://example.com/notes/1?redirected");
+	equal(candidates[0].object, accepted);
+	deepStrictEqual(failures, []);
+	for (const accept of [() => Promise.resolve(false), () => Promise.reject(/* @__PURE__ */ new Error("Oops"))]) {
+		const refusals = [];
+		equal(await lookupObject("https://example.com/notes/1", {
+			documentLoader,
+			contextLoader: mockDocumentLoader,
+			[lookupObserver]: {
+				accept,
+				failed: (f) => refusals.push(f)
+			}
+		}), null);
+		deepStrictEqual(refusals.map((f) => f.operation), ["accept"]);
+	}
+	fetched.length = 0;
+	const missing = [];
+	equal(await lookupObject("https://example.com/notes/2", {
+		documentLoader,
+		contextLoader: mockDocumentLoader,
+		[lookupObserver]: {
+			webFinger: false,
+			failed: (f) => missing.push(f)
+		}
+	}), null);
+	deepStrictEqual(fetched, ["https://example.com/notes/2"]);
+	deepStrictEqual(missing.map((f) => f.operation), ["fetch"]);
+});
+test("lookupObject() keeps looking after the observer refuses a portable candidate", async () => {
+	const id = `ap://${OBSERVER_DID}/notes/1`;
+	const gateways = ["https://gw1.example", "https://gw2.example"];
+	const documentLoader = (url) => Promise.resolve({
+		contextUrl: null,
+		document: {
+			"@context": "https://www.w3.org/ns/activitystreams",
+			id,
+			type: "Note",
+			content: url.startsWith("https://gw1.example/") ? "first" : "second"
+		},
+		documentUrl: url
+	});
+	const verifier = () => Promise.resolve({ verified: true });
+	const offered = [];
+	const failures = [];
+	const object = await lookupObject(id, {
+		documentLoader,
+		contextLoader: mockDocumentLoader,
+		gateways,
+		verifyPortableObject: verifier,
+		[lookupObserver]: {
+			accept: (candidate) => {
+				offered.push(candidate.documentUrl);
+				return Promise.resolve(offered.length > 1);
+			},
+			failed: (failure) => failures.push(failure)
+		}
+	});
+	ok(object instanceof Note);
+	equal(object.content, "second");
+	equal(offered.length, 2);
+	ok(offered[0].startsWith("https://gw1.example/"));
+	ok(offered[1].startsWith("https://gw2.example/"));
+	deepStrictEqual(failures.map((f) => f.operation), ["accept"]);
+});
 //#endregion
 export {};

package/dist-tests/portable-lookup.test.mjs

@@ -2,8 +2,8 @@ import "temporal-polyfill";
 globalThis.addEventListener = () => {};
 import { F as Person } from "./vocab-jHKm_LJ6.mjs";
 import { t as esm_default } from "./esm-DtAfYdqR.mjs";
-import { n as getActorHandle } from "./actor-C89Bex4F.mjs";
-import { t as lookupObject } from "./lookup-BehNGq4X.mjs";
+import { n as getActorHandle } from "./actor-C93GLWk5.mjs";
+import { t as lookupObject } from "./lookup-C4i0dNeY.mjs";
 import { t as assertInstanceOf } from "./utils-Df2odC27.mjs";
 import { mockDocumentLoader, test } from "@fedify/fixture";
 import { deepStrictEqual, equal, rejects } from "node:assert/strict";

package/dist-tests/{src-fpZm9WyF.mjs → src-Dn87CPDV.mjs}

@@ -1,8 +1,8 @@
 import "temporal-polyfill";
 globalThis.addEventListener = () => {};
 import "./vocab-jHKm_LJ6.mjs";
-import "./actor-C89Bex4F.mjs";
-import "./lookup-BehNGq4X.mjs";
+import "./actor-C93GLWk5.mjs";
+import "./lookup-C4i0dNeY.mjs";
 import { LanguageString as LanguageString$1 } from "@fedify/vocab-runtime";
 new URL("https://www.w3.org/ns/activitystreams#Public");
 //#endregion

package/dist-tests/translation.test.mjs

@@ -1,7 +1,7 @@
 import "temporal-polyfill";
 globalThis.addEventListener = () => {};
 import { A as Object$1, E as Link, F as Person, K as Translation, L as PropertyValue, P as Organization, U as Service, a as Application, b as Group, k as Note, o as Article, q as Update, s as Collection, u as Create } from "./vocab-jHKm_LJ6.mjs";
-import { t as LanguageString$1 } from "./src-fpZm9WyF.mjs";
+import { t as LanguageString$1 } from "./src-Dn87CPDV.mjs";
 import { test } from "@fedify/fixture";
 import { deepStrictEqual, ok, rejects } from "node:assert/strict";
 import { getDocumentLoader, preloadedContexts } from "@fedify/vocab-runtime";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab",
-  "version": "2.5.0-dev.2446+2014cb03",
+  "version": "2.5.0-dev.2448+756933d0",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",
@@ -43,9 +43,9 @@
     "jsonld": "^9.0.0",
     "pkijs": "^3.3.3",
     "temporal-polyfill": "^1.0.1",
-    "@fedify/webfinger": "2.5.0-dev.2446+2014cb03",
-    "@fedify/vocab-tools": "2.5.0-dev.2446+2014cb03",
-    "@fedify/vocab-runtime": "2.5.0-dev.2446+2014cb03"
+    "@fedify/vocab-tools": "2.5.0-dev.2448+756933d0",
+    "@fedify/webfinger": "2.5.0-dev.2448+756933d0",
+    "@fedify/vocab-runtime": "2.5.0-dev.2448+756933d0"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",

package/src/lookup.test.ts

@@ -6,7 +6,15 @@ import {
 } from "@fedify/fixture";
 import fetchMock from "fetch-mock";
 import { deepStrictEqual, equal, ok, rejects } from "node:assert/strict";
-import { lookupObject, traverseCollection } from "./lookup.ts";
+import type {
+  DocumentLoader,
+  PortableObjectVerifier,
+} from "@fedify/vocab-runtime";
+import type {
+  DereferenceCandidate,
+  DereferenceFailure,
+} from "@fedify/vocab-runtime/internal/portable-dereference";
+import { lookupObject, lookupObserver, traverseCollection } from "./lookup.ts";
 import { assertInstanceOf } from "./utils.ts";
 import { Collection, Note, Object, Person } from "./vocab.ts";
 
@@ -1051,3 +1059,118 @@ test("lookupObject() records activitypub.object.lookup counter", {
 });
 
 // cSpell: ignore gildong
+
+const OBSERVER_DID = "did:key:z6MkhVPuyvgG1RkMv67azDqDCDERPXVrUg1i3qchXY5EACE3";
+
+test("lookupObject() offers each candidate to the observer", async () => {
+  const note = {
+    "@context": "https://www.w3.org/ns/activitystreams",
+    id: "https://example.com/notes/1",
+    type: "Note",
+    content: "Hello",
+  };
+  const fetched: string[] = [];
+  const documentLoader: DocumentLoader = (url) => {
+    fetched.push(url);
+    if (url === "https://example.com/notes/1") {
+      return Promise.resolve({
+        contextUrl: null,
+        document: note,
+        documentUrl: "https://example.com/notes/1?redirected",
+      });
+    }
+    return Promise.reject(new Error(`Not found: ${url}`));
+  };
+  const candidates: DereferenceCandidate<Object>[] = [];
+  const failures: DereferenceFailure[] = [];
+  const accepted = await lookupObject("https://example.com/notes/1", {
+    documentLoader,
+    contextLoader: mockDocumentLoader,
+    [lookupObserver]: {
+      accept: (candidate) => {
+        candidates.push(candidate);
+        return Promise.resolve(true);
+      },
+      failed: (failure) => failures.push(failure),
+    },
+  });
+  ok(accepted instanceof Note);
+  equal(candidates.length, 1);
+  deepStrictEqual(candidates[0].document, note);
+  equal(candidates[0].documentUrl, "https://example.com/notes/1?redirected");
+  equal(candidates[0].baseUrl.href, "https://example.com/notes/1?redirected");
+  equal(candidates[0].object, accepted);
+  deepStrictEqual(failures, []);
+
+  // A refused candidate is not returned, and neither is an observer error:
+  for (
+    const accept of [
+      () => Promise.resolve(false),
+      () => Promise.reject(new Error("Oops")),
+    ]
+  ) {
+    const refusals: DereferenceFailure[] = [];
+    equal(
+      await lookupObject("https://example.com/notes/1", {
+        documentLoader,
+        contextLoader: mockDocumentLoader,
+        [lookupObserver]: { accept, failed: (f) => refusals.push(f) },
+      }),
+      null,
+    );
+    deepStrictEqual(refusals.map((f) => f.operation), ["accept"]);
+  }
+
+  // Without WebFinger, a URL that cannot be fetched is not looked up further:
+  fetched.length = 0;
+  const missing: DereferenceFailure[] = [];
+  equal(
+    await lookupObject("https://example.com/notes/2", {
+      documentLoader,
+      contextLoader: mockDocumentLoader,
+      [lookupObserver]: { webFinger: false, failed: (f) => missing.push(f) },
+    }),
+    null,
+  );
+  deepStrictEqual(fetched, ["https://example.com/notes/2"]);
+  deepStrictEqual(missing.map((f) => f.operation), ["fetch"]);
+});
+
+test("lookupObject() keeps looking after the observer refuses a portable candidate", async () => {
+  const id = `ap://${OBSERVER_DID}/notes/1`;
+  const gateways = ["https://gw1.example", "https://gw2.example"];
+  const documentLoader: DocumentLoader = (url) =>
+    Promise.resolve({
+      contextUrl: null,
+      document: {
+        "@context": "https://www.w3.org/ns/activitystreams",
+        id,
+        type: "Note",
+        content: url.startsWith("https://gw1.example/") ? "first" : "second",
+      },
+      documentUrl: url,
+    });
+  const verifier: PortableObjectVerifier = () =>
+    Promise.resolve({ verified: true });
+  const offered: string[] = [];
+  const failures: DereferenceFailure[] = [];
+  const object = await lookupObject(id, {
+    documentLoader,
+    contextLoader: mockDocumentLoader,
+    gateways,
+    verifyPortableObject: verifier,
+    [lookupObserver]: {
+      accept: (candidate) => {
+        offered.push(candidate.documentUrl);
+        return Promise.resolve(offered.length > 1);
+      },
+      failed: (failure) => failures.push(failure),
+    },
+  });
+  ok(object instanceof Note);
+  equal(object.content, "second");
+  equal(offered.length, 2);
+  ok(offered[0].startsWith("https://gw1.example/"));
+  ok(offered[1].startsWith("https://gw2.example/"));
+  deepStrictEqual(failures.map((f) => f.operation), ["accept"]);
+});

package/src/lookup.ts

@@ -13,7 +13,9 @@ import {
   type RemoteDocument,
 } from "@fedify/vocab-runtime";
 import {
+  acceptCandidate,
   createSnapshotContextLoader,
+  type DereferenceObserver,
   dereferencePortableIri,
   getPortableGatewayCandidates,
   getPortableResponseClaim,
@@ -123,6 +125,38 @@ const logger = getLogger(["fedify", "vocab", "lookup"]);
  *
  * @since 0.2.0
  */
+/**
+ * The key of the {@link LookupObjectOptions} property that observes how
+ * {@link lookupObject} selects the object it returns.
+ *
+ * @internal Technically exported for other Fedify packages, but not part of
+ * the public API contract.  This is not considered public API for Semantic
+ * Versioning decisions.
+ */
+export const lookupObserver: unique symbol = Symbol.for(
+  "@fedify/vocab/lookupObserver",
+);
+
+/**
+ * Observes how {@link lookupObject} selects the object it returns: each
+ * candidate is offered to {@link DereferenceObserver.accept} at the boundary
+ * that would otherwise return it, both for ordinary documents and for
+ * FEP-ef61 portable objects, and each failure that does not propagate is
+ * reported to {@link DereferenceObserver.failed}.  The observer is not passed
+ * on to the returned object.
+ *
+ * @internal Technically exported for other Fedify packages, but not part of
+ * the public API contract.  This is not considered public API for Semantic
+ * Versioning decisions.
+ */
+export interface LookupObserver extends DereferenceObserver<Object> {
+  /**
+   * Whether to fall back to WebFinger when an HTTP(S) URL cannot be fetched.
+   * Defaults to `true`.
+   */
+  readonly webFinger?: boolean;
+}
+
 export interface LookupObjectOptions {
   /**
    * The document loader for loading remote JSON-LD documents.
@@ -226,6 +260,12 @@ export interface LookupObjectOptions {
    * @since 2.4.0
    */
   verifyPortableObject?: PortableObjectVerifier;
+
+  /**
+   * See {@link LookupObserver}.
+   * @internal
+   */
+  [lookupObserver]?: LookupObserver;
 }
 
 /**
@@ -395,8 +435,12 @@ async function lookupObjectInternal(
       });
     } catch (error) {
       logger.debug("Failed to fetch remote document:\n{error}", { error });
+      options[lookupObserver]?.failed?.({ operation: "fetch", error });
     }
   }
+  if (remoteDoc == null && options[lookupObserver]?.webFinger === false) {
+    return null;
+  }
   if (remoteDoc == null) {
     const jrd = await lookupWebFinger(identifier, {
       userAgent: options.userAgent,
@@ -467,12 +511,13 @@ async function lookupObjectInternal(
   if (remoteDoc == null) return null;
   // With verifyPortableObject, the document may turn out to be a portable
   // object, which has to be verified with the same context documents:
-  const snapshot = options.verifyPortableObject == null
-    ? null
-    : createSnapshotContextLoader(
-      options.contextLoader ??
-        getDocumentLoader({ userAgent: options.userAgent }),
-    );
+  const snapshot =
+    options.verifyPortableObject == null && options[lookupObserver] == null
+      ? null
+      : createSnapshotContextLoader(
+        options.contextLoader ??
+          getDocumentLoader({ userAgent: options.userAgent }),
+      );
   try {
     let object: Object;
     let documentUrl: URL;
@@ -486,6 +531,7 @@ async function lookupObjectInternal(
         baseUrl: documentUrl,
       });
     } catch (error) {
+      options[lookupObserver]?.failed?.({ operation: "parse", error });
       if (error instanceof TypeError) {
         logger.debug(
           "Failed to parse JSON-LD document: {error}\n{document}",
@@ -495,7 +541,7 @@ async function lookupObjectInternal(
       }
       throw error;
     }
-    if (snapshot != null) {
+    if (options.verifyPortableObject != null && snapshot != null) {
       // A document whose final URL or @id stands for a portable object is
       // verified as one instead of being trusted because of its origin:
       const claim = getPortableResponseClaim(remoteDoc.documentUrl, object.id);
@@ -540,6 +586,19 @@ async function lookupObjectInternal(
           'implications, set the crossOrigin option to "trust".',
         { ...remoteDoc, objectId: object.id.href },
       );
+      options[lookupObserver]?.failed?.({ operation: "origin" });
+      return null;
+    }
+    if (
+      !await acceptCandidate(options[lookupObserver], {
+        document: remoteDoc.document,
+        documentUrl: remoteDoc.documentUrl,
+        baseUrl: documentUrl,
+        contextLoader: snapshot?.loader ?? options.contextLoader ??
+          getDocumentLoader({ userAgent: options.userAgent }),
+        object,
+      })
+    ) {
       return null;
     }
     return object;
@@ -728,6 +787,7 @@ async function dereference(
       verifyPortableObject: options.verifyPortableObject,
       crossOrigin: options.crossOrigin === "throw" ? "throw" : "ignore",
       signal: options.signal,
+      observer: options[lookupObserver],
       parse: (document, { contextLoader, baseUrl }) =>
         Object.fromJsonLd(document, {
           documentLoader,