@fedify/vocab 2.4.0-dev.2233 → 2.4.0-dev.2240

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

@@ -2,8 +2,8 @@ import "temporal-polyfill";
 globalThis.addEventListener = () => {};
 import { F as Person } from "./vocab-D3C791xF.mjs";
 import { t as esm_default } from "./esm-2_Uqq_my.mjs";
-import { n as getActorHandle } from "./actor-C8V9Eu9k.mjs";
-import { t as lookupObject } from "./lookup-2QrSuQR0.mjs";
+import { n as getActorHandle } from "./actor-C-Bvqy6v.mjs";
+import { t as lookupObject } from "./lookup-DiU8zIYx.mjs";
 import { t as assertInstanceOf } from "./utils-Df2odC27.mjs";
 import { mockDocumentLoader, test } from "@fedify/fixture";
 import { deepStrictEqual, equal, rejects } from "node:assert/strict";
@@ -98,6 +98,36 @@ test("lookupObject() with FEP-ef61 portable actors", {
 			}), Person);
 			deepStrictEqual(documentLoader.fetched, [compatibleId, hinted]);
 		});
+		await t.step("explicit gateways replace WebFinger hints", async () => {
+			esm_default.removeRoutes();
+			esm_default.get(webFingerPrefix, selfLinks(`ap://${did}/actor?@gateway=https%3A%2F%2Fhint.example`));
+			const second = `https://second.example${gatewayPath}`;
+			const documentLoader = createLoader({ [second]: person() });
+			assertInstanceOf(await lookupObject("@alice@example.com", {
+				documentLoader,
+				contextLoader: mockDocumentLoader,
+				verifyPortableObject: createVerifier(),
+				gateways: ["https://second.example"]
+			}), Person);
+			deepStrictEqual(documentLoader.fetched, [compatibleId, second]);
+		});
+		await t.step("WebFinger host counts toward the five attempts", async () => {
+			esm_default.removeRoutes();
+			esm_default.get(webFingerPrefix, selfLinks(`ap://${did}/actor`));
+			const documentLoader = createLoader({});
+			equal(await lookupObject("@alice@example.com", {
+				documentLoader,
+				contextLoader: mockDocumentLoader,
+				verifyPortableObject: createVerifier(),
+				gateways: Array.from({ length: 6 }, (_, i) => `https://g${i}.example`)
+			}), null);
+			deepStrictEqual(documentLoader.fetched, [compatibleId, ...[
+				0,
+				1,
+				2,
+				3
+			].map((i) => `https://g${i}.example${gatewayPath}`)]);
+		});
 		await t.step("tries the next self link after a failure", async () => {
 			esm_default.removeRoutes();
 			const other = `https://other.example${gatewayPath}`;
@@ -177,6 +207,13 @@ test("lookupObject() with FEP-ef61 portable actors", {
 			});
 			assertInstanceOf(actor, Person);
 			deepStrictEqual(actor.id, new URL(compatibleId));
+			const malformed = `${compatibleId}?gateways=x`;
+			const ordinaryLoader = createLoader({ [malformed]: person(malformed) });
+			assertInstanceOf(await lookupObject(malformed, {
+				documentLoader: ordinaryLoader,
+				contextLoader: mockDocumentLoader
+			}), Person);
+			deepStrictEqual(ordinaryLoader.fetched, [malformed]);
 		});
 		await t.step("refuses portable IRIs changed by URL parsing", async () => {
 			esm_default.removeRoutes();
@@ -191,6 +228,20 @@ test("lookupObject() with FEP-ef61 portable actors", {
 			equal(await lookupObject(`ap://${did}/x/../actor?@gateway=https%3A%2F%2Fexample.com`, options), null);
 			deepStrictEqual(documentLoader.fetched, []);
 		});
+		await t.step("refuses compatible IDs changed by URL parsing", async () => {
+			esm_default.removeRoutes();
+			const dotted = compatibleId.replace("/actor", "/x/../actor");
+			const documentLoader = createLoader({ [compatibleId]: person() });
+			const options = {
+				documentLoader,
+				contextLoader: mockDocumentLoader,
+				verifyPortableObject: createVerifier()
+			};
+			equal(await lookupObject(dotted, options), null);
+			esm_default.get(webFingerPrefix, selfLinks(dotted));
+			equal(await lookupObject("@alice@example.com", options), null);
+			deepStrictEqual(documentLoader.fetched, []);
+		});
 		await t.step("bounds gateway requests", async () => {
 			esm_default.removeRoutes();
 			const hints = Array.from({ length: 5 }, (_, i) => `@gateway=https%3A%2F%2Fg${i}.example`).join("&");
@@ -267,6 +318,79 @@ test("lookupObject() looks up portable identifiers directly", async () => {
 	}), null);
 	deepStrictEqual(documentLoader.fetched.length, 5);
 });
+test("lookupObject() uses explicit gateways for portable IDs", async (t) => {
+	const first = `https://first.example${gatewayPath}`;
+	const second = `https://second.example${gatewayPath}`;
+	const hint = `https://hint.example${gatewayPath}`;
+	const options = {
+		contextLoader: mockDocumentLoader,
+		verifyPortableObject: createVerifier()
+	};
+	await t.step("bare ap: ID and one gateway", async () => {
+		const documentLoader = createLoader({ [first]: person() });
+		assertInstanceOf(await lookupObject(`ap://${did}/actor`, {
+			...options,
+			documentLoader,
+			gateways: ["https://first.example"]
+		}), Person);
+		deepStrictEqual(documentLoader.fetched, [first]);
+	});
+	await t.step("tries several gateways in order", async () => {
+		const documentLoader = createLoader({ [second]: person() });
+		assertInstanceOf(await lookupObject(actorId, {
+			...options,
+			documentLoader,
+			gateways: ["https://first.example", new URL("https://second.example")]
+		}), Person);
+		deepStrictEqual(documentLoader.fetched, [first, second]);
+	});
+	await t.step("explicit gateways replace location hints", async () => {
+		const documentLoader = createLoader({
+			[second]: person(),
+			[hint]: person()
+		});
+		assertInstanceOf(await lookupObject(`ap://${did}/actor?@gateway=https%3A%2F%2Fhint.example`, {
+			...options,
+			documentLoader,
+			gateways: ["https://first.example", "https://second.example"]
+		}), Person);
+		deepStrictEqual(documentLoader.fetched, [first, second]);
+	});
+	await t.step("empty list uses a custom document loader", async () => {
+		const hintedId = `ap://${did}/actor?@gateway=https%3A%2F%2Fhint.example`;
+		const canonicalHintedId = `${actorId}?@gateway=https%3A%2F%2Fhint.example`;
+		const documentLoader = createLoader({
+			[canonicalHintedId]: person(),
+			[hint]: person()
+		});
+		const actor = await lookupObject(hintedId, {
+			...options,
+			documentLoader,
+			gateways: []
+		});
+		deepStrictEqual(documentLoader.fetched, [canonicalHintedId]);
+		assertInstanceOf(actor, Person);
+	});
+	await t.step("invalid gateway throws before fetching", async () => {
+		const documentLoader = createLoader({});
+		for (const verifyPortableObject of [void 0, createVerifier()]) await rejects(() => lookupObject(actorId, {
+			documentLoader,
+			contextLoader: mockDocumentLoader,
+			verifyPortableObject,
+			gateways: ["https://bad.example/path"]
+		}), TypeError);
+		deepStrictEqual(documentLoader.fetched, []);
+	});
+	await t.step("a malformed portable ID is refused first", async () => {
+		const documentLoader = createLoader({});
+		equal(await lookupObject(`ap://${did}/x/../actor`, {
+			...options,
+			documentLoader,
+			gateways: ["https://bad.example/path"]
+		}), null);
+		deepStrictEqual(documentLoader.fetched, []);
+	});
+});
 test("getActorHandle() with FEP-ef61 portable actors", {
 	sanitizeResources: false,
 	sanitizeOps: false
@@ -362,6 +486,62 @@ test("lookupObject() reports inferred gateways as hints", async () => {
 	deepStrictEqual(calls[0].gateways, void 0);
 	deepStrictEqual(calls[0].gatewayHints, [new URL("https://example.com")]);
 });
+test("lookupObject() reports explicit gateways to the verifier", async (t) => {
+	const calls = [];
+	const verifyPortableObject = async (_, options) => {
+		calls.push(options);
+		return { verified: true };
+	};
+	await t.step("bare ID with a limited explicit list", async () => {
+		const documentLoader = createLoader({ [`https://g4.example${gatewayPath}`]: person() });
+		assertInstanceOf(await lookupObject(actorId, {
+			documentLoader,
+			contextLoader: mockDocumentLoader,
+			verifyPortableObject,
+			gateways: Array.from({ length: 6 }, (_, i) => `https://g${i}.example`)
+		}), Person);
+		deepStrictEqual(documentLoader.fetched, [
+			0,
+			1,
+			2,
+			3,
+			4
+		].map((i) => `https://g${i}.example${gatewayPath}`));
+		deepStrictEqual(calls.at(-1)?.gateways, [
+			0,
+			1,
+			2,
+			3,
+			4
+		].map((i) => new URL(`https://g${i}.example`)));
+		equal(calls.at(-1)?.gatewayHints, void 0);
+	});
+	await t.step("compatible origin stays first and is deduplicated", async () => {
+		const second = `https://second.example${gatewayPath}`;
+		const documentLoader = createLoader({ [second]: person() });
+		assertInstanceOf(await lookupObject(compatibleId, {
+			documentLoader,
+			contextLoader: mockDocumentLoader,
+			verifyPortableObject,
+			gateways: ["https://example.com", "https://second.example"]
+		}), Person);
+		deepStrictEqual(documentLoader.fetched, [compatibleId, second]);
+		deepStrictEqual(calls.at(-1)?.gateways, [new URL("https://example.com"), new URL("https://second.example")]);
+		equal(calls.at(-1)?.gatewayHints, void 0);
+	});
+	await t.step("empty list keeps the compatible origin", async () => {
+		const documentLoader = createLoader({ [compatibleId]: person() });
+		assertInstanceOf(await lookupObject(compatibleId, {
+			documentLoader,
+			contextLoader: mockDocumentLoader,
+			verifyPortableObject,
+			gateways: []
+		}), Person);
+		deepStrictEqual(documentLoader.fetched, [compatibleId]);
+		deepStrictEqual(calls.at(-1)?.gateways, []);
+		equal(calls.at(-1)?.gatewayHints, void 0);
+	});
+});
 test("lookupObject() verifies fetched documents that stand for portable objects", async (t) => {
 	const plainUrl = "https://example.com/users/alice";
 	const redirectingLoader = (documentUrl, document) => {
@@ -394,6 +574,24 @@ test("lookupObject() verifies fetched documents that stand for portable objects"
 		deepStrictEqual(calls.length, 1);
 		deepStrictEqual(calls[0].documentUrl, new URL(compatibleId));
 		deepStrictEqual(calls[0].gatewayHints, [new URL("https://example.com")]);
+		const explicitCalls = [];
+		assertInstanceOf(await lookupObject(plainUrl, {
+			documentLoader,
+			contextLoader: mockDocumentLoader,
+			gateways: ["https://other.example"],
+			verifyPortableObject: async (_, options) => {
+				explicitCalls.push(options);
+				return { verified: true };
+			}
+		}), Person);
+		deepStrictEqual(explicitCalls[0].gateways, [new URL("https://other.example")]);
+		equal(explicitCalls[0].gatewayHints, void 0);
+		await rejects(() => lookupObject(plainUrl, {
+			documentLoader,
+			contextLoader: mockDocumentLoader,
+			verifyPortableObject: createVerifier(),
+			gateways: ["https://bad.example/path"]
+		}), TypeError);
 		equal(await lookupObject(plainUrl, {
 			documentLoader,
 			contextLoader: mockDocumentLoader,

package/dist-tests/translation.test.mjs

@@ -1,8 +1,8 @@
 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-D3C791xF.mjs";
-import "./actor-C8V9Eu9k.mjs";
-import "./lookup-2QrSuQR0.mjs";
+import "./actor-C-Bvqy6v.mjs";
+import "./lookup-DiU8zIYx.mjs";
 import { test } from "@fedify/fixture";
 import { deepStrictEqual, ok, rejects } from "node:assert/strict";
 import { LanguageString as LanguageString$1, getDocumentLoader, preloadedContexts } from "@fedify/vocab-runtime";

package/dist-tests/vocab.test.mjs

@@ -411,6 +411,22 @@ test("fromJsonLd() handles portable ActivityPub IRIs", async () => {
 	deepStrictEqual(pageJson.next, "ap+ef61://did:key:z6Mkabc/actor/outbox?page=2");
 	deepStrictEqual(pageJson.prev, "ap+ef61://did:key:z6Mkabc/actor/outbox?page=1");
 });
+test("fromJsonLd() refuses portable IDs changed by URL parsing", async () => {
+	const base = "ap://did:key:z6Mkabc";
+	for (const id of [
+		`${base}/a/../b`,
+		`${base}/a/%2e%2E/b`,
+		"https://gw.example/.well-known/apgateway/did:key:z6Mkabc/a/../b",
+		"https:/gw.example/.well-known/apgateway/did:key:z6Mkabc/a/../b"
+	]) await rejects(() => Note.fromJsonLd({
+		"@context": "https://www.w3.org/ns/activitystreams",
+		type: "Note",
+		id
+	}, {
+		documentLoader: mockDocumentLoader,
+		contextLoader: mockDocumentLoader
+	}), TypeError);
+});
 test("FEP-ef61: actor gateways round-trip as an ordered URI list", async () => {
 	const actorClasses = [
 		Application,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab",
-  "version": "2.4.0-dev.2233+abb4a6b2",
+  "version": "2.4.0-dev.2240+79613fa6",
   "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/vocab-tools": "2.4.0-dev.2233+abb4a6b2",
-    "@fedify/vocab-runtime": "2.4.0-dev.2233+abb4a6b2",
-    "@fedify/webfinger": "2.4.0-dev.2233+abb4a6b2"
+    "@fedify/vocab-tools": "2.4.0-dev.2240+79613fa6",
+    "@fedify/vocab-runtime": "2.4.0-dev.2240+79613fa6",
+    "@fedify/webfinger": "2.4.0-dev.2240+79613fa6"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",

package/src/gateway.test.ts

@@ -1633,18 +1633,21 @@ test("accessors verify fetched documents that stand for portable objects", async
       deepStrictEqual(object instanceof Note, expected);
     }
     // A final URL that URL parsing would turn into another ID is refused:
-    deepStrictEqual(
-      await (await createHttpActivity(plainUrl)).getObject({
-        documentLoader: createRedirectingLoader({
-          [plainUrl]: {
-            documentUrl: `ap://${did}/objects/x/../1`,
-            document: note(),
-          },
-        }),
-        contextLoader: mockDocumentLoader,
-        verifyPortableObject: createVerifier(),
-      }),
-      null,
+    await rejects(
+      () =>
+        createHttpActivity(plainUrl).then((activity) =>
+          activity.getObject({
+            documentLoader: createRedirectingLoader({
+              [plainUrl]: {
+                documentUrl: `ap://${did}/objects/x/../1`,
+                document: note(),
+              },
+            }),
+            contextLoader: mockDocumentLoader,
+            verifyPortableObject: createVerifier(),
+          })
+        ),
+      TypeError,
     );
   });
 

package/src/lookup.ts

@@ -185,6 +185,19 @@ export interface LookupObjectOptions {
    */
   signal?: AbortSignal;
 
+  /**
+   * The [FEP-ef61] gateways to try when looking up a portable
+   * (`ap:`/`ap+ef61:`) object, in order.  Each must be an HTTP(S) origin.
+   * An explicit list replaces `@gateway` location hints, including when
+   * it is empty.  The gateway named by a compatible identifier or the
+   * WebFinger server is still tried first.  At most five gateways are
+   * requested per lookup, including those given here.
+   *
+   * [FEP-ef61]: https://w3id.org/fep/ef61
+   * @since 2.4.0
+   */
+  gateways?: readonly (string | URL)[];
+
   /**
    * The [FEP-ef61] policy to apply to portable objects, typically
    * `verifyPortableObject()` from `@fedify/fedify`, which
@@ -252,7 +265,9 @@ const MAX_PORTABLE_ATTEMPTS = 5;
  *
  * [FEP-ef61] portable objects, including portable actors found through
  * WebFinger, are looked up only if the `verifyPortableObject` option is
- * given; see {@link LookupObjectOptions.verifyPortableObject}.
+ * given; see {@link LookupObjectOptions.verifyPortableObject}.  Pass
+ * {@link LookupObjectOptions.gateways} to look up a portable ID without
+ * `@gateway` location hints.
  *
  * [FEP-ef61]: https://w3id.org/fep/ef61
  *
@@ -345,7 +360,13 @@ async function lookupObjectInternal(
       if (candidate == null) return null;
       return await lookupPortableObject(portable, candidate, undefined);
     }
-    identifier = toAcctUrl(identifier) ?? new URL(identifier);
+    // Check the raw spelling before WHATWG URL can erase dot segments from a
+    // compatible identifier.  It cannot be recovered from the parsed URL.
+    if (
+      options.verifyPortableObject != null &&
+      parseCompatibleEf61Reference(identifier) === null
+    ) return null;
+    identifier = toAcctUrl(identifier) ?? parseIri(identifier);
   }
   if (isPortableIri(identifier)) {
     let candidate: URL;
@@ -408,7 +429,9 @@ async function lookupObjectInternal(
         const candidate = parsePortableCandidate(l.href);
         if (candidate == null) continue;
         const gateways = webFingerGateway == null ? [] : [webFingerGateway];
-        gateways.push(...getPortableGatewayCandidates(candidate));
+        if (options.gateways == null) {
+          gateways.push(...getPortableGatewayCandidates(candidate));
+        }
         const object = await lookupPortableObject(
           portable,
           candidate,
@@ -484,10 +507,14 @@ async function lookupObjectInternal(
         );
         return null;
       } else if (claim != null) {
-        return await dereference(portable, claim.id, claim.inferredGateways, {
-          response: remoteDoc,
-          contextLoader: snapshot.loader,
-        });
+        const explicit = getExplicitGateways(portable, claim.id);
+        return await dereference(
+          portable,
+          claim.id,
+          claim.inferredGateways,
+          explicit,
+          { response: remoteDoc, contextLoader: snapshot.loader },
+        );
       }
     }
     if (
@@ -530,6 +557,19 @@ interface PortableLookup {
   readonly attempted: Set<string>;
   /** The number of gateway requests left for this lookup. */
   remaining: number;
+  /** Validated only when the lookup reaches a portable object. */
+  explicitGateways?: URL[];
+}
+
+function getExplicitGateways(
+  lookup: PortableLookup,
+  id: URL,
+): URL[] | undefined {
+  if (lookup.options.gateways == null) return undefined;
+  return lookup.explicitGateways ??= getPortableGatewayCandidates(
+    id,
+    lookup.options.gateways,
+  );
 }
 
 /**
@@ -600,17 +640,18 @@ function getWebFingerGateway(identifier: URL): URL | undefined {
 
 /**
  * Looks up a portable object through FEP-ef61 gateways.
- * @param gateways The gateways to ask in order.  If omitted, the location
- *                 hints in the IRI are used, and if there are none, the
- *                 portable IRI itself is passed to the document loader.
+ * @param inferredGateways Gateways inferred from a compatible identifier or
+ *                         WebFinger.  If omitted, location hints in the IRI
+ *                         are used unless explicit gateways were given.
  */
 async function lookupPortableObject(
   lookup: PortableLookup,
   id: URL,
-  gateways: readonly URL[] | undefined,
+  inferredGateways: readonly URL[] | undefined,
 ): Promise<Object | null> {
   const { options } = lookup;
   const iri = formatIri(id);
+  const explicitGateways = getExplicitGateways(lookup, id);
   if (options.verifyPortableObject == null) {
     logger.debug(
       "Cannot look up the portable object {iri}, as the " +
@@ -620,20 +661,27 @@ async function lookupPortableObject(
     return null;
   }
   const canonicalId = canonicalizePortableUri(iri);
-  let candidates: URL[];
-  if (gateways == null) {
-    candidates = getPortableGatewayCandidates(id);
-    if (candidates.length < 1) {
-      // No gateway to ask; a custom document loader may know how to
-      // retrieve the portable IRI itself:
-      const key = `${canonicalId} `;
-      if (lookup.remaining < 1 || lookup.attempted.has(key)) return null;
-      lookup.attempted.add(key);
-      lookup.remaining--;
-      return await dereference(lookup, id, []);
+  const inferred = inferredGateways ??
+    (explicitGateways == null ? getPortableGatewayCandidates(id) : []);
+  const candidates = [...inferred];
+  for (const gateway of explicitGateways ?? []) {
+    if (!candidates.some((candidate) => candidate.href === gateway.href)) {
+      candidates.push(gateway);
     }
-  } else {
-    candidates = [...gateways];
+  }
+  if (candidates.length < 1 && inferredGateways == null) {
+    // No gateway to ask; a custom document loader may know how to
+    // retrieve the portable IRI itself:
+    const key = `${canonicalId} `;
+    if (lookup.remaining < 1 || lookup.attempted.has(key)) return null;
+    lookup.attempted.add(key);
+    lookup.remaining--;
+    return await dereference(
+      lookup,
+      id,
+      [],
+      explicitGateways == null ? undefined : [],
+    );
   }
   const selected: URL[] = [];
   for (const gateway of candidates) {
@@ -645,13 +693,25 @@ async function lookupPortableObject(
   }
   if (selected.length < 1) return null;
   lookup.remaining -= selected.length;
-  return await dereference(lookup, id, selected);
+  const selectedInferred = selected.filter((candidate) =>
+    inferred.some((gateway) => gateway.href === candidate.href)
+  );
+  const selectedExplicit = explicitGateways?.filter((gateway) =>
+    selected.some((candidate) => candidate.href === gateway.href)
+  );
+  return await dereference(
+    lookup,
+    id,
+    selectedInferred,
+    selectedExplicit,
+  );
 }
 
 async function dereference(
   { options, documentLoader }: PortableLookup,
   id: URL,
-  gateways: readonly URL[],
+  inferredGateways: readonly URL[],
+  gateways?: readonly URL[],
   extra: { response?: RemoteDocument; contextLoader?: DocumentLoader } = {},
 ): Promise<Object | null> {
   const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
@@ -661,10 +721,9 @@ async function dereference(
       contextLoader: extra.contextLoader ?? options.contextLoader ??
         getDocumentLoader({ userAgent: options.userAgent }),
       tracerProvider,
-      // Gateways are inferred from the identifier, WebFinger, or location
-      // hints, rather than given by the caller, so they are reported to the
-      // verifier as hints:
-      inferredGateways: gateways,
+      // Preserve where the gateways came from for the verifier:
+      inferredGateways,
+      ...(gateways == null ? {} : { gateways }),
       response: extra.response,
       verifyPortableObject: options.verifyPortableObject,
       crossOrigin: options.crossOrigin === "throw" ? "throw" : "ignore",