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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab",
-  "version": "2.5.0-dev.2446+2014cb03",
+  "version": "2.5.0-dev.2492+4648c04e",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",
@@ -37,15 +37,15 @@
   "dependencies": {
     "@multiformats/base-x": "^4.0.1",
     "@logtape/logtape": "^2.2.0",
-    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api": "~1.9.1",
     "asn1js": "^3.0.10",
     "es-toolkit": "1.46.1",
     "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.2492+4648c04e",
+    "@fedify/vocab-runtime": "2.5.0-dev.2492+4648c04e",
+    "@fedify/webfinger": "2.5.0-dev.2492+4648c04e"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",

package/src/actor.ts

@@ -394,6 +394,8 @@ async function getPortableActorHandle(
     userAgent: options.userAgent,
     tracerProvider: options.tracerProvider,
     meterProvider: options.meterProvider,
+    allowPrivateAddress: "allowPrivateAddress" in options &&
+      options.allowPrivateAddress === true,
   });
   // Unlike an ordinary actor, whose ID vouches for its host, a portable
   // actor's gateways are claimed by the actor itself, so there is no
@@ -409,6 +411,8 @@ async function getPortableActorHandle(
       userAgent: options.userAgent,
       tracerProvider: options.tracerProvider,
       meterProvider: options.meterProvider,
+      allowPrivateAddress: "allowPrivateAddress" in options &&
+        options.allowPrivateAddress === true,
     });
     if (
       subjectResult != null && linksToPortableActor(subjectResult, canonicalId)

package/src/gateway.test.ts

@@ -876,7 +876,7 @@ test("getObject() sends the ActivityStreams Accept header to gateways", {
   });
   try {
     const object = await (await createActivity()).getObject({
-      documentLoader: getDocumentLoader(),
+      documentLoader: getDocumentLoader({ allowPrivateAddress: true }),
       contextLoader: mockDocumentLoader,
       gateways: ["https://example.com"],
       verifyPortableObject: createVerifier(),

package/src/lookup.test.ts

@@ -6,14 +6,29 @@ 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";
 
+// lookupObject() accepts this option without declaring it, since Fedify's
+// Context passes it.  It makes WebFinger lookups use the global fetch()
+// (fetch-mock here) without resolving hostnames, so that the tests do not
+// depend on the real DNS:
+const allowPrivateAddress = { allowPrivateAddress: true };
+
 test("lookupObject()", {
   sanitizeResources: false,
   sanitizeOps: false,
 }, async (t) => {
+  const responseTimers: ReturnType<typeof setTimeout>[] = [];
   fetchMock.spyGlobal();
 
   fetchMock.get(
@@ -43,6 +58,7 @@ test("lookupObject()", {
   const options = {
     documentLoader: mockDocumentLoader,
     contextLoader: mockDocumentLoader,
+    ...allowPrivateAddress,
   };
 
   await t.step("actor", async () => {
@@ -106,7 +122,7 @@ test("lookupObject()", {
     "begin:https://example.com/.well-known/webfinger",
     () =>
       new Promise((resolve) => {
-        setTimeout(() => {
+        responseTimers.push(setTimeout(() => {
           resolve({
             subject: "acct:johndoe@example.com",
             links: [
@@ -117,7 +133,7 @@ test("lookupObject()", {
               },
             ],
           });
-        }, 1000);
+        }, 1000));
       }),
   );
 
@@ -162,7 +178,7 @@ test("lookupObject()", {
     "begin:https://example.com/.well-known/webfinger",
     () =>
       new Promise((resolve) => {
-        setTimeout(() => {
+        responseTimers.push(setTimeout(() => {
           resolve({
             subject: "acct:johndoe@example.com",
             links: [
@@ -173,7 +189,7 @@ test("lookupObject()", {
               },
             ],
           });
-        }, 500);
+        }, 500));
       }),
   );
 
@@ -193,7 +209,7 @@ test("lookupObject()", {
     "https://example.com/slow-object",
     () =>
       new Promise((resolve) => {
-        setTimeout(() => {
+        responseTimers.push(setTimeout(() => {
           resolve({
             status: 200,
             headers: { "Content-Type": "application/activity+json" },
@@ -203,7 +219,7 @@ test("lookupObject()", {
               content: "Slow response",
             },
           });
-        }, 1000);
+        }, 1000));
       }),
   );
 
@@ -218,6 +234,7 @@ test("lookupObject()", {
     deepStrictEqual(await promise, null);
   });
 
+  for (const timer of responseTimers) clearTimeout(timer);
   fetchMock.hardReset();
   fetchMock.removeRoutes();
 });
@@ -601,6 +618,7 @@ test("FEP-fe34: lookupObject() cross-origin security", {
 
     // Default behavior should return null
     const result1 = await lookupObject("@user@example.com", {
+      ...allowPrivateAddress,
       documentLoader: webfingerDocumentLoader,
       contextLoader: mockDocumentLoader,
     });
@@ -610,6 +628,7 @@ test("FEP-fe34: lookupObject() cross-origin security", {
     await rejects(
       () =>
         lookupObject("@user@example.com", {
+          ...allowPrivateAddress,
           documentLoader: webfingerDocumentLoader,
           contextLoader: mockDocumentLoader,
           crossOrigin: "throw",
@@ -620,6 +639,7 @@ test("FEP-fe34: lookupObject() cross-origin security", {
 
     // With crossOrigin: trust, should return the object
     const result2 = await lookupObject("@user@example.com", {
+      ...allowPrivateAddress,
       documentLoader: webfingerDocumentLoader,
       contextLoader: mockDocumentLoader,
       crossOrigin: "trust",
@@ -719,12 +739,22 @@ test("FEP-fe34: lookupObject() cross-origin security", {
       throw new Error("Network error");
     };
 
+    // The WebFinger fallback must not reach the network:
+    fetchMock.spyGlobal();
+    fetchMock.get("begin:https://example.com/.well-known/webfinger", 404);
+
     // Network errors should not be confused with cross-origin errors
-    const result = await lookupObject("https://example.com/note", {
-      documentLoader: errorDocumentLoader,
-      contextLoader: mockDocumentLoader,
-      crossOrigin: "throw",
-    });
+    let result;
+    try {
+      result = await lookupObject("https://example.com/note", {
+        ...allowPrivateAddress,
+        documentLoader: errorDocumentLoader,
+        contextLoader: mockDocumentLoader,
+        crossOrigin: "throw",
+      });
+    } finally {
+      fetchMock.hardReset();
+    }
 
     // Should return null because the document loader failed,
     // not because of cross-origin policy
@@ -842,6 +872,7 @@ test("lookupObject() records activitypub.object.lookup counter", {
     await t.step("records kind=actor for an actor result", async () => {
       const [meterProvider, recorder] = createTestMeterProvider();
       const person = await lookupObject("@johndoe@example.com", {
+        ...allowPrivateAddress,
         documentLoader: mockDocumentLoader,
         contextLoader: mockDocumentLoader,
         meterProvider,
@@ -928,6 +959,7 @@ test("lookupObject() records activitypub.object.lookup counter", {
       });
       const [meterProvider, recorder] = createTestMeterProvider();
       const result = await lookupObject("janedoe@example.com", {
+        ...allowPrivateAddress,
         documentLoader: mockDocumentLoader,
         contextLoader: mockDocumentLoader,
         meterProvider,
@@ -979,6 +1011,7 @@ test("lookupObject() records activitypub.object.lookup counter", {
         );
         const [meterProvider, recorder] = createTestMeterProvider();
         await lookupObject("@johndoe@example.com", {
+          ...allowPrivateAddress,
           documentLoader: mockDocumentLoader,
           contextLoader: mockDocumentLoader,
           meterProvider,
@@ -1012,6 +1045,7 @@ test("lookupObject() records activitypub.object.lookup counter", {
         });
         const [meterProvider, recorder] = createTestMeterProvider();
         await lookupObject(new URL("acct:johndoe@example.com"), {
+          ...allowPrivateAddress,
           documentLoader: mockDocumentLoader,
           contextLoader: mockDocumentLoader,
           meterProvider,
@@ -1051,3 +1085,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,