@fedify/cli 2.4.0-dev.2247 → 2.4.0-dev.2253

package/dist/deno.js

@@ -1,5 +1,5 @@
 import "temporal-polyfill";
 //#region deno.json
-var version = "2.4.0-dev.2247+4fe1b8c3";
+var version = "2.4.0-dev.2253+f5212c33";
 //#endregion
 export { version };

package/dist/diagnostics.js

@@ -1,40 +1,173 @@
 import "temporal-polyfill";
-import { FetchError, UrlError } from "@fedify/vocab-runtime";
-import "@fedify/vocab";
+import { createPortableObjectVerifier, getPortableLookupProblem, isPortableReference } from "./portable.js";
+import { FetchError, UrlError, formatIri } from "@fedify/vocab-runtime";
+import { lookupObject } from "@fedify/vocab";
 //#region src/diagnostics.ts
-/** Records loader failures that lookupObject would otherwise swallow or wrap. */
-function createLookupDiagnostics(documentLoader, contextLoader) {
+/**
+* Records loader failures that lookupObject would otherwise swallow or wrap,
+* and portable objects that the verifier rejects.
+* @param documentLoader The document loader to record failures of.
+* @param contextLoader The context loader to record failures of.
+* @param verifierDocumentLoader The document loader for the documents that
+*                               the [FEP-ef61] portable object verifier
+*                               discovers.  If omitted, the returned
+*                               `verifyPortableObject` is `undefined`.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*/
+function createLookupDiagnostics(documentLoader, contextLoader, verifierDocumentLoader) {
 	let objectFailure;
 	let contextFailure;
+	let portableFailure;
+	let verificationFailures;
 	const wrap = (loader, source, record) => async (url, options) => {
 		try {
 			const document = await loader(url, options);
 			record(void 0);
+			if (verificationFailures != null) verificationFailures.length = 0;
 			return document;
 		} catch (error) {
-			record({
+			const failure = {
 				error,
 				source
-			});
+			};
+			record(failure);
+			verificationFailures?.push(failure);
 			throw error;
 		}
 	};
+	const recordObjectFailure = (failure) => objectFailure = failure;
+	const wrappedContextLoader = wrap(contextLoader, "context", (e) => contextFailure = e);
+	const verifyPortableObject = verifierDocumentLoader == null ? void 0 : createPortableObjectVerifier(wrap(verifierDocumentLoader, "object", recordObjectFailure), wrappedContextLoader);
+	const verify = verifyPortableObject == null ? void 0 : async (document, options) => {
+		const id = getDocumentId(document);
+		const failures = [];
+		verificationFailures = failures;
+		try {
+			const result = await verifyPortableObject(document, options);
+			if (result.verified) portableFailure = void 0;
+			else if (result.reason.type === "collectionOwnerUnavailable" && failures.length > 0) portableFailure = failures[failures.length - 1];
+			else portableFailure = {
+				error: void 0,
+				source: "portable",
+				id,
+				reason: result.reason
+			};
+			return result;
+		} catch (error) {
+			portableFailure = {
+				error,
+				source: "portable",
+				id
+			};
+			throw error;
+		} finally {
+			verificationFailures = void 0;
+		}
+	};
 	return {
-		documentLoader: wrap(documentLoader, "object", (e) => objectFailure = e),
-		contextLoader: wrap(contextLoader, "context", (e) => contextFailure = e),
+		documentLoader: wrap(documentLoader, "object", recordObjectFailure),
+		contextLoader: wrappedContextLoader,
+		verifyPortableObject: verify,
 		clearFailures() {
 			objectFailure = void 0;
 			contextFailure = void 0;
+			portableFailure = void 0;
 		},
 		getObjectFailure: () => objectFailure,
-		getContextFailure: () => contextFailure
+		getContextFailure: () => contextFailure,
+		getPortableFailure: () => portableFailure
 	};
 }
+function getDocumentId(document) {
+	if (document == null || typeof document !== "object") return void 0;
+	const record = document;
+	const id = record.id ?? record["@id"];
+	return typeof id === "string" ? formatIdentifier(id) : void 0;
+}
+/** Returns an object and a snapshot of the evidence for a failed lookup. */
+async function lookupWithDiagnostics(identifier, options, lookup = lookupObject) {
+	const { verifierDocumentLoader, ...lookupOptions } = options;
+	if (verifierDocumentLoader != null) {
+		const problem = getPortableLookupProblem(identifier, options.gateways);
+		if (problem != null) return Object.freeze({
+			object: null,
+			failure: {
+				error: void 0,
+				source: "portable",
+				id: formatIdentifier(identifier),
+				problem
+			}
+		});
+	}
+	const diagnostics = createLookupDiagnostics(options.documentLoader, options.contextLoader, verifierDocumentLoader);
+	try {
+		const object = await lookup(identifier, {
+			...lookupOptions,
+			documentLoader: diagnostics.documentLoader,
+			contextLoader: diagnostics.contextLoader,
+			...diagnostics.verifyPortableObject == null ? {} : { verifyPortableObject: diagnostics.verifyPortableObject }
+		});
+		if (object != null) return Object.freeze({ object });
+		return Object.freeze({
+			object,
+			failure: diagnostics.getPortableFailure() ?? diagnostics.getObjectFailure() ?? diagnostics.getContextFailure() ?? (verifierDocumentLoader != null && isPortableReference(identifier) ? {
+				error: void 0,
+				source: "portable",
+				id: formatIdentifier(identifier)
+			} : void 0)
+		});
+	} catch (error) {
+		return Object.freeze({
+			object: null,
+			thrownError: error,
+			failure: diagnostics.getContextFailure() ?? diagnostics.getObjectFailure() ?? diagnostics.getPortableFailure() ?? {
+				error,
+				source: "other"
+			}
+		});
+	}
+}
+function formatIdentifier(identifier) {
+	try {
+		return formatIri(identifier);
+	} catch {
+		return typeof identifier === "string" ? identifier : identifier.href;
+	}
+}
+const PORTABLE_REJECTION_REASONS = {
+	notPortableObject: "it has neither a portable ID nor a compatible identifier",
+	unsupportedObjectType: "its type cannot be a portable object",
+	missingProof: "it has no integrity proof",
+	invalidGateways: "its gateways property is missing or invalid",
+	invalidProof: "its integrity proof is invalid",
+	unsupportedVerificationMethod: "its integrity proof has an unsupported verification method",
+	verificationMethodMismatch: "its integrity proof was not created by the DID in its ID",
+	unknownCollectionSource: "it is a collection without an integrity proof that was not served by a gateway",
+	unknownCollectionOwner: "it is a collection without an integrity proof whose owner is unknown",
+	conflictingCollectionOwners: "it is a collection without an integrity proof whose owner is ambiguous",
+	collectionPageMismatch: "it is a collection page that does not belong to its collection",
+	collectionOwnerUnavailable: "it is a collection without an integrity proof whose owner could not be retrieved",
+	collectionNotListedByOwner: "it is a collection without an integrity proof that its owner does not list",
+	untrustedGateway: "it is a collection without an integrity proof served by a gateway that its owner does not list"
+};
+function describePortableFailure(failure) {
+	const id = failure.id ?? "(unknown)";
+	if (failure.problem === "malformed") return `Invalid portable ID: ${id}.`;
+	if (failure.problem === "no-gateway") return `The portable ID ${id} has no @gateway location hints.  Use the --gateway option to look it up.`;
+	if (failure.reason != null) return `Rejected the portable object ${id}, as ${PORTABLE_REJECTION_REASONS[failure.reason.type] ?? failure.reason.type}.`;
+	if (failure.error != null) return `Failed to verify the portable object ${id}: ${failure.error instanceof Error ? failure.error.message : String(failure.error)}`;
+	return `No gateway returned a valid portable object for ${id}.`;
+}
 function escapeControlCharacters(message) {
 	return message.replace(/[\x00-\x1f\x7f-\x9f]/g, (character) => `\\x${character.charCodeAt(0).toString(16).padStart(2, "0")}`);
 }
 /** Describes a failure without recommending signing unless HTTP supports it. */
 function describeLookupFailure(failure, authorizedFetch) {
+	if (failure?.source === "portable") return {
+		message: escapeControlCharacters(describePortableFailure(failure)),
+		suggestsAuthorizedFetch: false
+	};
 	const error = failure?.error;
 	const http = error instanceof FetchError ? /^(.+): HTTP (\d{3}): \1$/s.exec(error.message) : null;
 	if (http != null) {
@@ -67,4 +200,4 @@ function describeLookupFailure(failure, authorizedFetch) {
 	};
 }
 //#endregion
-export { createLookupDiagnostics, describeLookupFailure };
+export { createLookupDiagnostics, describeLookupFailure, lookupWithDiagnostics };

package/dist/inbox/command.js

@@ -1,6 +1,7 @@
 import "temporal-polyfill";
 import { configContext } from "../config.js";
 import { createTunnelOption } from "../options.js";
+import { gatewayUrl } from "../portable.js";
 import { command, constant, group, merge, message, multiple, object, option, string } from "@optique/core";
 import { bindConfig } from "@optique/config";
 //#region src/inbox/command.ts
@@ -8,12 +9,15 @@ const DEFAULT_EPHEMERAL_INBOX_NAME = "Fedify Ephemeral Inbox";
 const DEFAULT_EPHEMERAL_INBOX_SUMMARY = "An ephemeral ActivityPub inbox for testing purposes.";
 const inboxOptions = merge(object("Inbox options", {
 	command: constant("inbox"),
-	follow: bindConfig(multiple(option("-f", "--follow", string({ metavar: "URI" }), { description: message`Follow the given actor. The argument can be either an actor URI or a handle. Can be specified multiple times.` })), {
+	follow: bindConfig(multiple(option("-f", "--follow", string({ metavar: "URI" }), { description: message`Follow the given actor. The argument can be either an actor URI (including an FEP-ef61 portable ID) or a handle. Can be specified multiple times.` })), {
 		context: configContext,
 		key: (config) => config.inbox?.follow ?? [],
 		default: []
 	}),
-	acceptFollow: bindConfig(multiple(option("-a", "--accept-follow", string({ metavar: "URI" }), { description: message`Accept follow requests from the given actor. The argument can be either an actor URI or a handle, or a wildcard (${"*"}). Can be specified multiple times. If a wildcard is specified, all follow requests will be accepted.` })), {
+	gateways: multiple(option("--gateway", gatewayUrl(), { description: message`An FEP-ef61 gateway to look up the portable \
+actors to follow from, instead of their ${"@gateway"} location hints.  Can \
+be specified multiple times.` })),
+	acceptFollow: bindConfig(multiple(option("-a", "--accept-follow", string({ metavar: "URI" }), { description: message`Accept follow requests from the given actor. The argument can be either an actor URI (including an FEP-ef61 portable ID) or a handle, or a wildcard (${"*"}). Can be specified multiple times. If a wildcard is specified, all follow requests will be accepted.` })), {
 		context: configContext,
 		key: (config) => config.inbox?.acceptFollow ?? [],
 		default: []

package/dist/inbox.js

@@ -1,16 +1,18 @@
 import { Temporal } from "temporal-polyfill";
+import { getPortableLookupProblem } from "./portable.js";
 import { colors, matchesActor } from "./utils.js";
 import { configureLogging, recordingSink } from "./log.js";
 import { version } from "./deno.js";
-import { getDocumentLoader } from "./docloader.js";
+import { getDocumentLoader as getDocumentLoader$1 } from "./docloader.js";
 import { ActivityEntryPage, ActivityListPage } from "./inbox/view.js";
 import { tableStyle } from "./table.js";
 import { spawnTemporaryServer } from "./tempserver.js";
 import process from "node:process";
+import { formatIri } from "@fedify/vocab-runtime";
 import { MemoryKvStore, createFederation, generateCryptoKeyPair } from "@fedify/fedify";
 import { getLogger } from "@logtape/logtape";
 import ora from "ora";
-import { Accept, Activity, Application, Delete, Endpoints, Follow, Image, PUBLIC_COLLECTION, isActor, lookupObject } from "@fedify/vocab";
+import { Accept, Activity, Application, Delete, Endpoints, Follow, Image, PUBLIC_COLLECTION, isActor } from "@fedify/vocab";
 import Table from "cli-table3";
 import { Hono } from "hono";
 import { jsx } from "hono/jsx/jsx-runtime";
@@ -32,7 +34,7 @@ async function runInbox(command) {
 	for (const key of Object.keys(peers)) delete peers[key];
 	for (const key of Object.keys(followers)) delete followers[key];
 	if (command.debug) await configureLogging();
-	const federationDocumentLoader = await getDocumentLoader();
+	const federationDocumentLoader = await getDocumentLoader$1();
 	const authorizedFetchEnabled = command.authorizedFetch ?? false;
 	const authorize = async (ctx) => {
 		if (!authorizedFetchEnabled) return true;
@@ -97,13 +99,13 @@ async function runInbox(command) {
 			const follower = await activity.getActor();
 			if (!isActor(follower)) return;
 			if (!await matchesActor(follower, acceptFollows) || activity.id == null) {
-				logger.debug("Does not accept follow from {actor}.", { actor: follower.id?.href });
+				logger.debug("Does not accept follow from {actor}.", { actor: follower.id == null ? null : formatIri(follower.id) });
 				return;
 			}
-			logger.debug("Accepting follow from {actor}.", { actor: follower.id?.href });
+			logger.debug("Accepting follow from {actor}.", { actor: follower.id == null ? null : formatIri(follower.id) });
 			followers[activity.id.href] = follower;
 			await ctx.sendActivity({ identifier }, follower, new Accept({
-				id: new URL(`#accepts/${follower.id?.href}`, ctx.getActorUri("i")),
+				id: new URL(`#accepts/${follower.id == null ? "" : formatIri(follower.id)}`, ctx.getActorUri("i")),
 				actor: ctx.getActorUri(identifier),
 				object: activity.id
 			}));
@@ -181,9 +183,19 @@ async function runInbox(command) {
 	if (command.follow != null && command.follow.length > 0) {
 		spinner.text = "Following actors...";
 		const documentLoader = await fedCtx.getDocumentLoader({ identifier: "i" });
+		const gateways = command.gateways.length > 0 ? { gateways: command.gateways } : {};
 		for (const uri of command.follow) {
 			spinner.text = `Following ${colors.green(uri)}...`;
-			const actor = await lookupObject(uri, { documentLoader });
+			const problem = getPortableLookupProblem(uri, command.gateways);
+			if (problem != null) {
+				spinner.fail(problem === "malformed" ? `Invalid portable ID: ${colors.red(uri)}` : `The portable ID ${colors.red(uri)} has no @gateway location hints.  Use the --gateway option to follow it.`);
+				spinner.start();
+				continue;
+			}
+			const actor = await fedCtx.lookupObject(uri, {
+				documentLoader,
+				...gateways
+			});
 			if (!isActor(actor)) {
 				spinner.fail(`Not an actor: ${colors.red(uri)}`);
 				spinner.start();
@@ -191,7 +203,7 @@ async function runInbox(command) {
 			}
 			if (actor.id != null) peers[actor.id?.href] = actor;
 			await fedCtx.sendActivity({ identifier: "i" }, actor, new Follow({
-				id: new URL(`#follows/${actor.id?.href}`, fedCtx.getActorUri("i")),
+				id: new URL(`#follows/${actor.id == null ? "" : formatIri(actor.id)}`, fedCtx.getActorUri("i")),
 				actor: fedCtx.getActorUri("i"),
 				object: actor.id
 			}));

package/dist/lookup/command.js

@@ -1,6 +1,7 @@
 import "temporal-polyfill";
 import { configContext } from "../config.js";
 import { createTunnelServiceOption, userAgentOption } from "../options.js";
+import { gatewayUrl } from "../portable.js";
 import { argument, choice, command, constant, flag, float, integer, map, merge, message, multiple, object, option, optionNames, optional, or, string, withDefault } from "@optique/core";
 import { path } from "@optique/run";
 import { bindConfig } from "@optique/config";
@@ -80,6 +81,10 @@ const lookupModeOption = withDefault(or(object("Recurse options", {
 	suppressErrors: false
 });
 const lookupOptions = merge(object({ command: constant("lookup") }), lookupModeOption, authorizedFetchOption, merge("Network options", userAgentOption, object({
+	gateways: multiple(option("--gateway", gatewayUrl(), { description: message`An FEP-ef61 gateway to look up the given \
+portable objects from, instead of their ${"@gateway"} location hints.  Also \
+used for linked portable objects without location hints.  Can be specified \
+multiple times.` })),
 	allowPrivateAddress: allowPrivateAddressOption,
 	timeout: optional(bindConfig(option("-T", "--timeout", float({
 		min: 0,

package/dist/lookup.js

@@ -1,16 +1,17 @@
 import "temporal-polyfill";
+import { getIriKey, getPortableLookupProblem } from "./portable.js";
 import { FEDIBIRD_QUOTE_IRI, IN_REPLY_TO_IRI, MISSKEY_QUOTE_IRI, QUOTE_IRI, QUOTE_URL_IRI } from "./lookup/command.js";
 import { colorEnabled, colors, describeError, formatObject } from "./utils.js";
 import { configureLogging } from "./log.js";
 import { getContextLoader, getDocumentLoader as getDocumentLoader$1 } from "./docloader.js";
 import { spawnTemporaryServer } from "./tempserver.js";
-import { createLookupDiagnostics, describeLookupFailure } from "./diagnostics.js";
+import { createLookupDiagnostics, describeLookupFailure, lookupWithDiagnostics } from "./diagnostics.js";
 import { renderImages } from "./imagerenderer.js";
 import process from "node:process";
 import { message, optionNames, text } from "@optique/core";
 import { printError } from "@optique/run";
 import { createWriteStream } from "node:fs";
-import { FetchError, UrlError, expandIPv6Address, isValidPublicIPv4Address, isValidPublicIPv6Address } from "@fedify/vocab-runtime";
+import { FetchError, UrlError, expandIPv6Address, formatIri, isValidPublicIPv4Address, isValidPublicIPv6Address } from "@fedify/vocab-runtime";
 import { generateCryptoKeyPair, getAuthenticatedDocumentLoader, respondWithObject } from "@fedify/fedify";
 import { getLogger } from "@logtape/logtape";
 import ora from "ora";
@@ -44,10 +45,13 @@ const MAX_TIMEOUT_MS = 2147483647;
 */
 var RecursiveLookupError = class extends Error {
 	target;
-	constructor(target) {
+	/** Why the target could not be fetched, if known. */
+	failure;
+	constructor(target, failure) {
 		super(`Failed to recursively fetch object: ${target}`);
 		this.name = "RecursiveLookupError";
 		this.target = target;
+		this.failure = failure;
 	}
 };
 function writeToStream(stream, chunk) {
@@ -281,12 +285,12 @@ async function collectRecursiveObjects(initialObject, recurseProperty, recurseDe
 	const visited = options.visited ?? /* @__PURE__ */ new Set();
 	const results = [];
 	let current = initialObject;
-	if (current.id != null) visited.add(current.id.href);
+	if (current.id != null) visited.add(getVisitedKey(current.id));
 	for (let depth = 0; depth < recurseDepth; depth++) {
 		const targetId = getRecursiveTargetId(current, recurseProperty);
 		if (targetId == null) break;
-		const target = targetId.href;
-		if (visited.has(target)) break;
+		const target = formatTarget(targetId);
+		if (visited.has(getVisitedKey(targetId))) break;
 		let next;
 		try {
 			next = await lookup(target);
@@ -308,42 +312,42 @@ async function collectRecursiveObjects(initialObject, recurseProperty, recurseDe
 			throw new RecursiveLookupError(target);
 		}
 		results.push(next);
-		visited.add(target);
-		if (next.id != null) visited.add(next.id.href);
+		visited.add(getVisitedKey(targetId));
+		if (next.id != null) visited.add(getVisitedKey(next.id));
 		current = next;
 	}
 	return results;
 }
+/**
+* Gets the key for recognizing an already visited object, which identifies
+* FEP-ef61 portable objects by their canonical IDs.
+* @param iri The object's ID, or the raw string given by the user.
+* @returns The key.
+*/
+function getVisitedKey(iri) {
+	return getIriKey(iri) ?? (typeof iri === "string" ? iri : iri.href);
+}
+/**
+* Formats a recursion target, printing FEP-ef61 portable IDs in their
+* canonical form rather than their percent-encoded `URL` form.
+*/
+function formatTarget(target) {
+	try {
+		return formatIri(target);
+	} catch {
+		return target.href;
+	}
+}
 async function runLookup(command, deps = {}) {
 	const effectiveDeps = {
 		lookupObject,
 		traverseCollection,
+		getDocumentLoader: getDocumentLoader$1,
 		exit: (code) => process.exit(code),
 		...deps
 	};
-	const lookupDiagnosed = async (identifier, options) => {
-		const diagnostics = createLookupDiagnostics(options.documentLoader, options.contextLoader);
-		try {
-			const object = await effectiveDeps.lookupObject(identifier, {
-				...options,
-				...diagnostics
-			});
-			return {
-				object,
-				failure: object == null ? diagnostics.getObjectFailure() ?? diagnostics.getContextFailure() : void 0,
-				thrownError: void 0
-			};
-		} catch (error) {
-			return {
-				object: null,
-				thrownError: error,
-				failure: diagnostics.getContextFailure() ?? diagnostics.getObjectFailure() ?? {
-					error,
-					source: "other"
-				}
-			};
-		}
-	};
+	const lookupDiagnosed = (identifier, options) => lookupWithDiagnostics(identifier, options, effectiveDeps.lookupObject);
+	const gatewayOptions = command.gateways.length > 0 ? { gateways: command.gateways } : {};
 	if (command.urls.length < 1) {
 		printError(message`At least one URL or actor handle must be provided.`);
 		effectiveDeps.exit(1);
@@ -354,12 +358,12 @@ async function runLookup(command, deps = {}) {
 		discardStdin: false
 	}).start();
 	let server = void 0;
-	const initialDocumentLoader = wrapDocumentLoaderWithTimeout(await getDocumentLoader$1({
+	const initialDocumentLoader = wrapDocumentLoaderWithTimeout(await effectiveDeps.getDocumentLoader({
 		userAgent: command.userAgent,
 		allowPrivateAddress: true,
 		timeout: toDocumentLoaderTimeout(command.timeout)
 	}), command.timeout);
-	const documentLoader = wrapDocumentLoaderWithTimeout(await getDocumentLoader$1({
+	const documentLoader = wrapDocumentLoaderWithTimeout(await effectiveDeps.getDocumentLoader({
 		userAgent: command.userAgent,
 		allowPrivateAddress: command.allowPrivateAddress,
 		timeout: toDocumentLoaderTimeout(command.timeout)
@@ -475,30 +479,25 @@ async function runLookup(command, deps = {}) {
 			const visited = /* @__PURE__ */ new Set();
 			const url = command.urls[urlIndex];
 			if (urlIndex > 0) spinner.text = `Looking up object chain ${urlIndex + 1}/${command.urls.length}...`;
-			let current = null;
-			try {
-				current = await effectiveDeps.lookupObject(url, {
-					documentLoader: initialLookupDocumentLoader,
-					contextLoader,
-					userAgent: command.userAgent
-				});
-			} catch (error) {
-				if (error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, url);
+			const result = await lookupDiagnosed(url, {
+				documentLoader: initialLookupDocumentLoader,
+				contextLoader,
+				verifierDocumentLoader: recursiveLookupDocumentLoader,
+				userAgent: command.userAgent,
+				...gatewayOptions
+			});
+			const current = result.object;
+			if (current == null) {
+				if (result.thrownError instanceof TimeoutError || result.failure?.error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, url);
 				else {
 					spinner.fail(`Failed to fetch object: ${colors.red(url)}.`);
-					printLookupFailureHint(authLoader, error);
+					printError(message`${text(describeLookupFailure(result.failure, authLoader != null).message)}`);
 				}
 				await finalizeAndExit(1);
 				return;
 			}
-			if (current == null) {
-				spinner.fail(`Failed to fetch object: ${colors.red(url)}.`);
-				if (authLoader == null) printError(message`It may be a private object.  Try with ${optionNames(["-a", "--authorized-fetch"])}.`);
-				await finalizeAndExit(1);
-				return;
-			}
-			visited.add(url);
-			if (current.id != null) visited.add(current.id.href);
+			visited.add(getVisitedKey(url));
+			if (current.id != null) visited.add(getVisitedKey(current.id));
 			if (!command.reverse) try {
 				if (totalObjects > 0) await writeSeparator(command.separator, getOutputStream());
 				await writeObjectToStream(current, command.output, command.format, contextLoader, getOutputStream());
@@ -511,11 +510,18 @@ async function runLookup(command, deps = {}) {
 			}
 			let chain = [];
 			try {
-				chain = await collectRecursiveObjects(current, command.recurse, recurseDepth, (target) => effectiveDeps.lookupObject(target, {
-					documentLoader: recursiveLookupDocumentLoader,
-					contextLoader: recursiveContextLoader,
-					userAgent: command.userAgent
-				}), {
+				chain = await collectRecursiveObjects(current, command.recurse, recurseDepth, async (target) => {
+					const result = await lookupDiagnosed(target, {
+						documentLoader: recursiveLookupDocumentLoader,
+						contextLoader: recursiveContextLoader,
+						verifierDocumentLoader: recursiveLookupDocumentLoader,
+						userAgent: command.userAgent,
+						...getPortableLookupProblem(target) === "no-gateway" ? gatewayOptions : {}
+					});
+					if (result.object != null) return result.object;
+					if (result.thrownError != null && !(result.failure?.error instanceof TimeoutError)) throw result.thrownError;
+					throw new RecursiveLookupError(target, result.failure);
+				}, {
 					suppressErrors: command.suppressErrors,
 					visited
 				});
@@ -532,9 +538,13 @@ async function runLookup(command, deps = {}) {
 				}
 				logger.error("Failed to recursively fetch an object in chain: {error}", { error });
 				if (error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout);
+				else if (error instanceof RecursiveLookupError && error.failure?.error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, error.target);
 				else if (error instanceof RecursiveLookupError) {
 					spinner.fail(`Failed to recursively fetch object: ${colors.red(error.target)}.`);
+					const privateContextUrl = error.failure?.source === "context" ? getPrivateContextUrl(error.failure.error) : null;
 					if (!command.allowPrivateAddress && isPrivateAddressTarget(error.target)) printRecursivePrivateAddressHint();
+					else if (privateContextUrl != null) printRecursivePrivateContextHint(privateContextUrl);
+					else if (error.failure != null) printError(message`${text(describeLookupFailure(error.failure, authLoader != null).message)}`);
 					else if (authLoader == null) printError(message`It may be a private object.  Try with ${optionNames(["-a", "--authorized-fetch"])}.`);
 				} else {
 					spinner.fail("Failed to recursively fetch object.");
@@ -604,7 +614,9 @@ async function runLookup(command, deps = {}) {
 			const result = await lookupDiagnosed(url, {
 				documentLoader: initialAuthLoader ?? initialDocumentLoader,
 				contextLoader,
-				userAgent: command.userAgent
+				verifierDocumentLoader: authLoader ?? documentLoader,
+				userAgent: command.userAgent,
+				...gatewayOptions
 			});
 			const collection = result.object;
 			if (collection == null) {
@@ -622,13 +634,15 @@ async function runLookup(command, deps = {}) {
 				return;
 			}
 			spinner.succeed(`Fetched collection: ${colors.green(url)}.`);
-			const diagnostics = createLookupDiagnostics(authLoader ?? documentLoader, contextLoader);
+			const diagnostics = createLookupDiagnostics(authLoader ?? documentLoader, contextLoader, authLoader ?? documentLoader);
 			try {
 				if (command.reverse) {
 					const { items: traversedItems, error: traversalError } = await collectAsyncItems(effectiveDeps.traverseCollection(collection, {
 						documentLoader: diagnostics.documentLoader,
 						contextLoader: diagnostics.contextLoader,
-						suppressError: command.suppressErrors
+						verifyPortableObject: diagnostics.verifyPortableObject,
+						suppressError: command.suppressErrors,
+						...gatewayOptions
 					}));
 					for (let index = traversedItems.length - 1; index >= 0; index--) {
 						const item = traversedItems[index];
@@ -657,7 +671,9 @@ async function runLookup(command, deps = {}) {
 				} else for await (const item of effectiveDeps.traverseCollection(collection, {
 					documentLoader: diagnostics.documentLoader,
 					contextLoader: diagnostics.contextLoader,
-					suppressError: command.suppressErrors
+					verifyPortableObject: diagnostics.verifyPortableObject,
+					suppressError: command.suppressErrors,
+					...gatewayOptions
 				})) {
 					try {
 						if (totalItems > 0) await writeSeparator(command.separator, getOutputStream());
@@ -686,7 +702,7 @@ async function runLookup(command, deps = {}) {
 					url,
 					error
 				});
-				const failure = diagnostics.getContextFailure() ?? diagnostics.getObjectFailure() ?? {
+				const failure = diagnostics.getContextFailure() ?? diagnostics.getObjectFailure() ?? diagnostics.getPortableFailure() ?? {
 					error,
 					source: "other"
 				};
@@ -711,7 +727,9 @@ async function runLookup(command, deps = {}) {
 	const objects = await Promise.all(command.urls.map((url) => lookupDiagnosed(url, {
 		documentLoader: initialAuthLoader ?? initialDocumentLoader,
 		contextLoader,
-		userAgent: command.userAgent
+		verifierDocumentLoader: authLoader ?? documentLoader,
+		userAgent: command.userAgent,
+		...gatewayOptions
 	})));
 	spinner.stop();
 	let success = true;
@@ -761,4 +779,4 @@ async function runLookup(command, deps = {}) {
 	if (success && command.output) spinner.succeed(`Successfully wrote output to ${colors.green(command.output)}.`);
 }
 //#endregion
-export { RecursiveLookupError, TimeoutError, collectAsyncItems, collectRecursiveObjects, getLookupFailureHint, getPrivateUrlCandidate, getRecursiveTargetId, isDocumentLoaderTimeoutError, runLookup, shouldPrintLookupFailureHint, shouldSuggestSuppressErrorsForLookupFailure, toDocumentLoaderTimeout, toPresentationOrder, wrapDocumentLoaderWithTimeout, writeObjectToStream, writeSeparator };
+export { RecursiveLookupError, TimeoutError, collectAsyncItems, collectRecursiveObjects, getLookupFailureHint, getPrivateUrlCandidate, getRecursiveTargetId, getVisitedKey, isDocumentLoaderTimeoutError, runLookup, shouldPrintLookupFailureHint, shouldSuggestSuppressErrorsForLookupFailure, toDocumentLoaderTimeout, toPresentationOrder, wrapDocumentLoaderWithTimeout, writeObjectToStream, writeSeparator };

package/dist/portable.js

@@ -0,0 +1,136 @@
+import "temporal-polyfill";
+import { message } from "@optique/core";
+import { canonicalizePortableUri, formatIri, fromCompatibleEf61Id, getGatewayHints, isGatewayUrl, parseIri } from "@fedify/vocab-runtime";
+import { verifyPortableObject } from "@fedify/fedify";
+//#region src/portable.ts
+const PORTABLE_IRI_PATTERN = /^ap(?:\+ef61)?:/i;
+/**
+* Checks whether the identifier is an [FEP-ef61] portable `ap:` or
+* `ap+ef61:` ID.  It does not check whether the ID is well-formed.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*/
+function isPortableIdentifier(identifier) {
+	return PORTABLE_IRI_PATTERN.test(typeof identifier === "string" ? identifier : identifier.protocol);
+}
+/**
+* Checks whether the identifier is an [FEP-ef61] portable ID or looks like
+* a compatible identifier, i.e., whether `lookupObject()` looks it up
+* through gateways.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*/
+function isPortableReference(identifier) {
+	if (isPortableIdentifier(identifier)) return true;
+	try {
+		return fromCompatibleEf61Id(identifier) != null;
+	} catch (error) {
+		if (error instanceof TypeError) return true;
+		throw error;
+	}
+}
+/**
+* Tells why a portable ID cannot be looked up before asking any server.
+* @param identifier The identifier to look up.
+* @param gateways The gateways given with `--gateway`, if any.
+* @returns `"malformed"` if the identifier is a malformed portable ID,
+*          `"no-gateway"` if it is a portable ID without `@gateway` location
+*          hints and no gateways are given, or `null` otherwise.
+*/
+function getPortableLookupProblem(identifier, gateways) {
+	if (!isPortableIdentifier(identifier)) return null;
+	let hints;
+	try {
+		parseIri(identifier);
+		hints = getGatewayHints(identifier);
+	} catch (error) {
+		if (error instanceof TypeError) return "malformed";
+		throw error;
+	}
+	if (hints.length > 0 || gateways != null && gateways.length > 0) return null;
+	return "no-gateway";
+}
+/**
+* Computes a key to compare IRIs with.  An [FEP-ef61] portable ID or
+* compatible identifier is turned into its canonical form, which ignores
+* the scheme spelling, the percent-encoding of the DID, the gateway of
+* a compatible identifier, and the query (e.g., `@gateway` location hints).
+* Other IRIs are compared by their normalized URLs.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+* @param iri The IRI.  Pass the raw string as given if available, since
+*            parsing it as a `URL` may change the object it identifies.
+* @returns The key, or `null` if the IRI is malformed.
+*/
+function getIriKey(iri) {
+	try {
+		const raw = typeof iri === "string" ? iri : formatIri(iri);
+		if (isPortableIdentifier(raw)) return canonicalizePortableUri(raw);
+		const portable = fromCompatibleEf61Id(iri);
+		if (portable != null) return canonicalizePortableUri(formatIri(portable));
+		return (typeof iri === "string" ? new URL(iri) : iri).href;
+	} catch (error) {
+		if (error instanceof TypeError) return null;
+		throw error;
+	}
+}
+/**
+* Creates the [FEP-ef61] portable object verifier that the CLI uses.
+*
+* The verifier always fetches documents, such as the owner of an unsecured
+* collection, with the given document loader rather than the one passed by
+* the caller, since `lookupObject()` passes its own loader, which may allow
+* private addresses for the objects explicitly given on the command line.
+* @param documentLoader The document loader for the documents that the
+*                       verifier discovers.
+* @param contextLoader The context loader to use when the caller passes
+*                      none.
+* @returns The verifier.
+*/
+function createPortableObjectVerifier(documentLoader, contextLoader) {
+	return (document, options) => verifyPortableObject(document, {
+		...options,
+		documentLoader,
+		contextLoader: options.contextLoader ?? contextLoader
+	});
+}
+/**
+* A value parser for the `--gateway` option, which accepts an [FEP-ef61]
+* gateway, i.e., an HTTP(S) origin without credentials, path, query, or
+* fragment.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*/
+function gatewayUrl() {
+	return {
+		mode: "sync",
+		metavar: "GATEWAY",
+		placeholder: new URL("https://gateway.invalid/"),
+		parse(input) {
+			let url;
+			try {
+				url = parseIri(input);
+			} catch {
+				return {
+					success: false,
+					error: message`Invalid URL: ${input}.`
+				};
+			}
+			if (!isGatewayUrl(url)) return {
+				success: false,
+				error: message`Invalid gateway: ${input}.  A gateway must be \
+an HTTP(S) origin without credentials, path, query, or fragment, \
+e.g., ${"https://example.com"}.`
+			};
+			return {
+				success: true,
+				value: url
+			};
+		},
+		format(value) {
+			return value.href;
+		}
+	};
+}
+//#endregion
+export { createPortableObjectVerifier, gatewayUrl, getIriKey, getPortableLookupProblem, isPortableIdentifier, isPortableReference };

package/dist/relay/command.js

@@ -30,12 +30,12 @@ const relayOptions = merge(object("Relay options", {
 		key: (config) => config.relay?.name ?? "Fedify Relay",
 		default: "Fedify Relay"
 	}),
-	acceptFollow: bindConfig(multiple(option("-a", "--accept-follow", string({ metavar: "URI" }), { description: message`Accept follow requests from the given actor. The argument can be either an actor URI or a handle, or a wildcard (${"*"}). Can be specified multiple times. If a wildcard is specified, all follow requests will be accepted.` })), {
+	acceptFollow: bindConfig(multiple(option("-a", "--accept-follow", string({ metavar: "URI" }), { description: message`Accept follow requests from the given actor. The argument can be either an actor URI (including an FEP-ef61 portable ID) or a handle, or a wildcard (${"*"}). Can be specified multiple times. If a wildcard is specified, all follow requests will be accepted.` })), {
 		context: configContext,
 		key: (config) => config.relay?.acceptFollow ?? [],
 		default: []
 	}),
-	rejectFollow: bindConfig(multiple(option("-r", "--reject-follow", string({ metavar: "URI" }), { description: message`Reject follow requests from the given actor. The argument can be either an actor URI or a handle, or a wildcard (${"*"}). Can be specified multiple times. If a wildcard is specified, all follow requests will be rejected.` })), {
+	rejectFollow: bindConfig(multiple(option("-r", "--reject-follow", string({ metavar: "URI" }), { description: message`Reject follow requests from the given actor. The argument can be either an actor URI (including an FEP-ef61 portable ID) or a handle, or a wildcard (${"*"}). Can be specified multiple times. If a wildcard is specified, all follow requests will be rejected.` })), {
 		context: configContext,
 		key: (config) => config.relay?.rejectFollow ?? [],
 		default: []

package/dist/utils.js

@@ -1,4 +1,5 @@
 import "temporal-polyfill";
+import { getIriKey } from "./portable.js";
 import process from "node:process";
 import { message } from "@optique/core";
 import { print, printError } from "@optique/run";
@@ -20,19 +21,43 @@ function formatObject(obj, colors, json) {
 	if (enableColors) return highlight(formatted, { language: "json" });
 	return formatted;
 }
-async function matchesActor(actor, actorList) {
+const URI_PATTERN = /^(?:https?|ap|ap\+ef61):/i;
+const HANDLE_PATTERN = /^@?[^@/\s]+@[^@/\s]+$/;
+/**
+* Checks whether the actor matches any of the given actor URIs, handles, or
+* the wildcard (`*`).  [FEP-ef61] portable actors match their `ap:` and
+* `ap+ef61:` IDs and compatible identifiers regardless of `@gateway` location
+* hints and the gateway of a compatible identifier.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+* @param actor The actor to check.
+* @param actorList The actor URIs, handles, or wildcards.
+* @param getHandle The function to get the actor's handle with.  It is called
+*                  at most once, and only if the list has a handle.
+* @returns `true` if the actor matches.
+* @throws If the list has a handle, the actor's handle cannot be determined,
+*         and the actor matches nothing else in the list.
+*/
+async function matchesActor(actor, actorList, getHandle = getActorHandle) {
 	const actorUri = actor.id;
-	let actorHandle = void 0;
 	if (actorUri == null) return false;
-	for (let uri of actorList) {
-		if (uri == "*") return true;
-		if (uri.startsWith("http:") || uri.startsWith("https:")) {
-			uri = new URL(uri).href;
-			if (uri === actorUri.href) return true;
+	const actorKey = getIriKey(actorUri);
+	let actorHandle;
+	let handleError;
+	for (const entry of actorList) {
+		if (entry == "*") return true;
+		if (URI_PATTERN.test(entry)) {
+			const key = getIriKey(entry);
+			if (key != null && key === actorKey) return true;
+			continue;
 		}
-		if (actorHandle == null) actorHandle = await getActorHandle(actor);
-		if (actorHandle === uri) return true;
+		if (!HANDLE_PATTERN.test(entry)) continue;
+		actorHandle ??= getHandle(actor).then((handle) => ({ handle }), (error) => ({ error }));
+		const result = await actorHandle;
+		if ("error" in result) handleError = result;
+		else if (result.handle === entry) return true;
 	}
+	if (handleError != null) throw handleError.error;
 	return false;
 }
 function describeError(error) {

package/dist/webfinger/action.js

@@ -1,38 +1,124 @@
 import "temporal-polyfill";
+import { createPortableObjectVerifier, getIriKey, getPortableLookupProblem, isPortableReference } from "../portable.js";
 import { formatObject } from "../utils.js";
-import { NotFoundError, getErrorMessage } from "./error.js";
+import { getContextLoader, getDocumentLoader as getDocumentLoader$1 } from "../docloader.js";
+import { NotFoundError, PortableActorError, UnlinkedPortableActorError, getErrorMessage } from "./error.js";
 import { convertUrlIfHandle } from "./lib.js";
 import { print } from "@optique/run";
+import { formatIri } from "@fedify/vocab-runtime";
 import ora from "ora";
+import { isActor, lookupObject } from "@fedify/vocab";
 import { formatMessage, message } from "@optique/core/message";
 import { lookupWebFinger } from "@fedify/webfinger";
 //#region src/webfinger/action.ts
-async function runWebFinger({ command: _, resources, ...options }) {
-	await Array.fromAsync(resources.map((resource) => ({
+async function runWebFinger({ resources, userAgent, allowPrivateAddresses, maxRedirection, gateways }) {
+	await Array.fromAsync(resources, (resource) => lookupWithSpinner({
 		resource,
-		...options
-	})), spinnerWrapper(lookupSingleWebFinger));
+		userAgent,
+		allowPrivateAddresses,
+		maxRedirection,
+		gateways
+	}));
 }
-async function lookupSingleWebFinger({ resource, ...options }) {
-	return await lookupWebFinger(convertUrlIfHandle(resource), options) ?? new NotFoundError(resource).throw();
+function getLookupWebFingerOptions(options) {
+	return {
+		userAgent: options.userAgent,
+		allowPrivateAddress: options.allowPrivateAddresses,
+		maxRedirection: options.maxRedirection
+	};
+}
+async function lookupSingleWebFinger(options) {
+	return await lookupWebFinger(convertUrlIfHandle(options.resource), getLookupWebFingerOptions(options)) ?? new NotFoundError(options.resource).throw();
+}
+/**
+* Looks up the WebFinger address of an [FEP-ef61] portable actor by its ID,
+* i.e., an `ap:` or `ap+ef61:` URI or a compatible identifier.
+*
+* As a portable actor's ID does not belong to any server, its WebFinger
+* address is `acct:` followed by its `preferredUsername`, `@`, and the host
+* of the first gateway in its `gateways`.  The actor is looked up and its
+* proof is verified first.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+* @param options The options.
+* @returns The resource descriptor, which may not link back to the actor;
+*          see {@link linksToActor}.
+* @throws {PortableActorError} If the actor cannot be looked up, or does
+*                              not have a WebFinger address.
+* @throws {NotFoundError} If the WebFinger address is not found.
+*/
+async function lookupPortableWebFinger(options) {
+	const { resource, gateways } = options;
+	const problem = getPortableLookupProblem(resource, gateways);
+	if (problem === "malformed") throw new PortableActorError(resource, "it is not a valid portable ID");
+	else if (problem === "no-gateway") throw new PortableActorError(resource, "it has no @gateway location hints; use the --gateway option");
+	const documentLoader = await getDocumentLoader$1({
+		userAgent: options.userAgent,
+		allowPrivateAddress: options.allowPrivateAddresses
+	});
+	const contextLoader = await getContextLoader({
+		userAgent: options.userAgent,
+		allowPrivateAddress: options.allowPrivateAddresses
+	});
+	const actor = await lookupObject(resource, {
+		documentLoader,
+		contextLoader,
+		verifyPortableObject: createPortableObjectVerifier(documentLoader, contextLoader),
+		userAgent: options.userAgent,
+		...gateways == null || gateways.length < 1 ? {} : { gateways }
+	});
+	if (actor == null) throw new PortableActorError(resource, "it could not be looked up or verified");
+	else if (!isActor(actor) || actor.id == null) throw new PortableActorError(resource, "it is not an actor");
+	const gateway = actor.gateway;
+	const username = actor.preferredUsername?.toString();
+	if (gateway == null || username == null) throw new PortableActorError(resource, "it has no preferredUsername or gateways");
+	const address = `acct:${username}@${gateway.host}`;
+	return {
+		descriptor: await lookupWebFinger(address, getLookupWebFingerOptions(options)) ?? new NotFoundError(address).throw(),
+		address,
+		actorId: actor.id
+	};
+}
+/**
+* Checks if the first ActivityStreams `self` link of a WebFinger response
+* identifies the given portable actor, either by its portable ID or by
+* a compatible identifier.
+* @param descriptor The WebFinger resource descriptor.
+* @param actorId The portable actor's ID.
+* @returns `true` if the descriptor links back to the actor.
+*/
+function linksToActor(descriptor, actorId) {
+	const link = descriptor.links?.find((l) => l.rel === "self" && l.href != null && (l.type === "application/activity+json" || l.type?.match(/application\/ld\+json;\s*profile="https:\/\/www.w3.org\/ns\/activitystreams"/) != null));
+	if (link?.href == null) return false;
+	const key = getIriKey(link.href);
+	return key != null && isPortableReference(link.href) && key === getIriKey(actorId);
 }
-function spinnerWrapper(func) {
-	return async (...args) => {
-		const spinner = ora({
-			text: `Looking up WebFinger for ${args[0]}`,
-			discardStdin: false
-		}).start();
-		try {
-			const result = await func(...args);
-			spinner.succeed(formatMessage(message`WebFinger found for ${args[0].resource}:`));
+async function lookupWithSpinner(options) {
+	const { resource } = options;
+	const spinner = ora({
+		text: `Looking up WebFinger for ${resource}`,
+		discardStdin: false
+	}).start();
+	try {
+		if (isPortableReference(resource)) {
+			const { descriptor, address, actorId } = await lookupPortableWebFinger(options);
+			if (linksToActor(descriptor, actorId)) spinner.succeed(formatMessage(message`WebFinger found for ${resource} (${address}):`));
+			else spinner.fail(formatMessage(getErrorMessage(resource, new UnlinkedPortableActorError(address, formatIri(actorId)))));
 			print([{
 				type: "text",
-				text: formatObject(result)
+				text: formatObject(descriptor)
 			}]);
-		} catch (error) {
-			spinner.fail(formatMessage(getErrorMessage(args[0].resource, error)));
+			return;
 		}
-	};
+		const result = await lookupSingleWebFinger(options);
+		spinner.succeed(formatMessage(message`WebFinger found for ${resource}:`));
+		print([{
+			type: "text",
+			text: formatObject(result)
+		}]);
+	} catch (error) {
+		spinner.fail(formatMessage(getErrorMessage(resource, error)));
+	}
 }
 //#endregion
-export { runWebFinger as default, lookupSingleWebFinger };
+export { runWebFinger as default, linksToActor, lookupPortableWebFinger, lookupSingleWebFinger };

package/dist/webfinger/command.js

@@ -1,6 +1,7 @@
 import "temporal-polyfill";
 import { configContext } from "../config.js";
 import { userAgentOption } from "../options.js";
+import { gatewayUrl } from "../portable.js";
 import { argument, command, constant, flag, group, integer, merge, message, multiple, object, option, string } from "@optique/core";
 import { bindConfig } from "@optique/config";
 //#region src/webfinger/command.ts
@@ -18,13 +19,18 @@ const webFingerOptions = merge("Network options", object({
 	command: constant("webfinger"),
 	resources: group("Arguments", multiple(argument(string({ metavar: "RESOURCE" }), { description: message`WebFinger resource(s) to look up.` }), { min: 1 })),
 	allowPrivateAddresses,
-	maxRedirection
+	maxRedirection,
+	gateways: multiple(option("--gateway", gatewayUrl(), { description: message`An FEP-ef61 gateway to look up the given \
+portable actors from, instead of their ${"@gateway"} location hints.  Can \
+be specified multiple times.` }))
 }), userAgentOption);
 const webFingerMetadata = {
 	brief: message`Look up WebFinger resources.`,
 	description: message`Look up WebFinger resources.
 
-The argument can be multiple.`
+The argument can be multiple.  For an FEP-ef61 portable actor ID, the actor \
+is looked up first, and the WebFinger address derived from its first gateway \
+is looked up.`
 };
 command("webfinger", webFingerOptions, webFingerMetadata);
 //#endregion

package/dist/webfinger/error.js

@@ -8,7 +8,7 @@ import { message } from "@optique/core";
 * @param {unknown} error The error encountered.
 * @returns {string} A descriptive error message.
 */
-const getErrorMessage = (resource, error) => error instanceof InvalidHandleError ? message`Invalid handle format: ${error.handle}` : error instanceof NotFoundError ? message`Resource not found: ${error.resource}` : error instanceof Error ? message`Failed to look up WebFinger for ${resource}: ${error.message}` : message`Failed to look up WebFinger for ${resource}: ${String(error)}`;
+const getErrorMessage = (resource, error) => error instanceof InvalidHandleError ? message`Invalid handle format: ${error.handle}` : error instanceof PortableActorError ? message`Failed to look up the portable actor ${error.resource}, as ${error.reason}.` : error instanceof UnlinkedPortableActorError ? message`${error.address} does not link back to the portable actor ${error.actorId}, so it is not verified to be the actor's WebFinger address:` : error instanceof NotFoundError ? message`Resource not found: ${error.resource}` : error instanceof Error ? message`Failed to look up WebFinger for ${resource}: ${error.message}` : message`Failed to look up WebFinger for ${resource}: ${String(error)}`;
 /**
 * Custom error class for invalid handle formats.
 * @param {string} handle The invalid handle that caused the error.
@@ -41,5 +41,43 @@ var NotFoundError = class extends Error {
 		throw this;
 	}
 };
+/**
+* Custom error class for [FEP-ef61] portable actors whose WebFinger address
+* cannot be determined.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+* @param resource The portable actor's ID.
+* @param reason Why the WebFinger address cannot be determined.
+* @extends {Error}
+*/
+var PortableActorError = class extends Error {
+	resource;
+	reason;
+	constructor(resource, reason) {
+		super(`Failed to look up the portable actor ${resource}, as ${reason}.`);
+		this.resource = resource;
+		this.reason = reason;
+		this.name = "PortableActorError";
+	}
+};
+/**
+* Custom error class for a WebFinger address that does not link back to
+* the [FEP-ef61] portable actor that claims it.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+* @param address The WebFinger address, e.g., `acct:alice@example.com`.
+* @param actorId The portable actor's ID.
+* @extends {Error}
+*/
+var UnlinkedPortableActorError = class extends Error {
+	address;
+	actorId;
+	constructor(address, actorId) {
+		super(`${address} does not link back to the portable actor ${actorId}.`);
+		this.address = address;
+		this.actorId = actorId;
+		this.name = "UnlinkedPortableActorError";
+	}
+};
 //#endregion
-export { InvalidHandleError, NotFoundError, getErrorMessage };
+export { InvalidHandleError, NotFoundError, PortableActorError, UnlinkedPortableActorError, getErrorMessage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/cli",
-  "version": "2.4.0-dev.2247+4fe1b8c3",
+  "version": "2.4.0-dev.2253+f5212c33",
   "type": "module",
   "files": [
     "README.md",
@@ -88,14 +88,14 @@
     "temporal-polyfill": "^1.0.1",
     "valibot": "^1.4.0",
     "yaml": "^2.9.0",
-    "@fedify/fedify": "2.4.0-dev.2247+4fe1b8c3",
-    "@fedify/init": "2.4.0-dev.2247+4fe1b8c3",
-    "@fedify/relay": "2.4.0-dev.2247+4fe1b8c3",
-    "@fedify/vocab-runtime": "2.4.0-dev.2247+4fe1b8c3",
-    "@fedify/vocab-tools": "2.4.0-dev.2247+4fe1b8c3",
-    "@fedify/webfinger": "2.4.0-dev.2247+4fe1b8c3",
-    "@fedify/vocab": "2.4.0-dev.2247+4fe1b8c3",
-    "@fedify/sqlite": "2.4.0-dev.2247+4fe1b8c3"
+    "@fedify/relay": "2.4.0-dev.2253+f5212c33",
+    "@fedify/fedify": "2.4.0-dev.2253+f5212c33",
+    "@fedify/init": "2.4.0-dev.2253+f5212c33",
+    "@fedify/sqlite": "2.4.0-dev.2253+f5212c33",
+    "@fedify/vocab": "2.4.0-dev.2253+f5212c33",
+    "@fedify/vocab-tools": "2.4.0-dev.2253+f5212c33",
+    "@fedify/vocab-runtime": "2.4.0-dev.2253+f5212c33",
+    "@fedify/webfinger": "2.4.0-dev.2253+f5212c33"
   },
   "devDependencies": {
     "@types/bun": "^1.2.23",