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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab",
-  "version": "2.5.0-dev.2448+756933d0",
+  "version": "2.5.0-dev.2494+f2e9b5d3",
   "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/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"
+    "@fedify/vocab-tools": "2.5.0-dev.2494+f2e9b5d3",
+    "@fedify/webfinger": "2.5.0-dev.2494+f2e9b5d3",
+    "@fedify/vocab-runtime": "2.5.0-dev.2494+f2e9b5d3"
   },
   "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

@@ -18,10 +18,17 @@ 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(
@@ -51,6 +58,7 @@ test("lookupObject()", {
   const options = {
     documentLoader: mockDocumentLoader,
     contextLoader: mockDocumentLoader,
+    ...allowPrivateAddress,
   };
 
   await t.step("actor", async () => {
@@ -114,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: [
@@ -125,7 +133,7 @@ test("lookupObject()", {
               },
             ],
           });
-        }, 1000);
+        }, 1000));
       }),
   );
 
@@ -170,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: [
@@ -181,7 +189,7 @@ test("lookupObject()", {
               },
             ],
           });
-        }, 500);
+        }, 500));
       }),
   );
 
@@ -201,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" },
@@ -211,7 +219,7 @@ test("lookupObject()", {
               content: "Slow response",
             },
           });
-        }, 1000);
+        }, 1000));
       }),
   );
 
@@ -226,6 +234,7 @@ test("lookupObject()", {
     deepStrictEqual(await promise, null);
   });
 
+  for (const timer of responseTimers) clearTimeout(timer);
   fetchMock.hardReset();
   fetchMock.removeRoutes();
 });
@@ -609,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,
     });
@@ -618,6 +628,7 @@ test("FEP-fe34: lookupObject() cross-origin security", {
     await rejects(
       () =>
         lookupObject("@user@example.com", {
+          ...allowPrivateAddress,
           documentLoader: webfingerDocumentLoader,
           contextLoader: mockDocumentLoader,
           crossOrigin: "throw",
@@ -628,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",
@@ -727,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
@@ -850,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,
@@ -936,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,
@@ -987,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,
@@ -1020,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,

package/src/portable-lookup.test.ts

@@ -14,6 +14,9 @@ import { lookupObject } from "./lookup.ts";
 import { assertInstanceOf } from "./utils.ts";
 import { Person } from "./vocab.ts";
 
+// Runtime-only transport override for hostname-based WebFinger mocks.
+const allowPrivateAddress = { allowPrivateAddress: true };
+
 const did = "did:key:z6Mkabc";
 const actorId = `ap+ef61://${did}/actor`;
 const gatewayPath = `/.well-known/apgateway/${did}/actor`;
@@ -92,6 +95,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
       const actor = await lookupObject("@alice@example.com", {
         documentLoader,
         contextLoader: mockDocumentLoader,
+        ...allowPrivateAddress,
         verifyPortableObject,
       });
       assertInstanceOf(actor, Person);
@@ -118,6 +122,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
         const actor = await lookupObject("@alice@example.com", {
           documentLoader,
           contextLoader: mockDocumentLoader,
+          ...allowPrivateAddress,
           verifyPortableObject: createVerifier(),
         });
         assertInstanceOf(actor, Person);
@@ -138,6 +143,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
       const actor = await lookupObject("@alice@example.com", {
         documentLoader,
         contextLoader: mockDocumentLoader,
+        ...allowPrivateAddress,
         verifyPortableObject: createVerifier(),
         gateways: ["https://second.example"],
       });
@@ -153,6 +159,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
         await lookupObject("@alice@example.com", {
           documentLoader,
           contextLoader: mockDocumentLoader,
+          ...allowPrivateAddress,
           verifyPortableObject: createVerifier(),
           gateways: Array.from(
             { length: 6 },
@@ -178,6 +185,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
       const actor = await lookupObject("@alice@example.com", {
         documentLoader,
         contextLoader: mockDocumentLoader,
+        ...allowPrivateAddress,
         verifyPortableObject: createVerifier(),
       });
       assertInstanceOf(actor, Person);
@@ -197,6 +205,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
       const actor = await lookupObject("@alice@example.com", {
         documentLoader,
         contextLoader: mockDocumentLoader,
+        ...allowPrivateAddress,
         verifyPortableObject,
       });
       assertInstanceOf(actor, Person);
@@ -227,6 +236,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
           await lookupObject("@alice@example.com", {
             documentLoader,
             contextLoader: mockDocumentLoader,
+            ...allowPrivateAddress,
             verifyPortableObject,
           }),
           null,
@@ -239,6 +249,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
             lookupObject("@alice@example.com", {
               documentLoader,
               contextLoader: mockDocumentLoader,
+              ...allowPrivateAddress,
               verifyPortableObject,
               crossOrigin: "throw",
             }),
@@ -248,6 +259,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
           await lookupObject("@alice@example.com", {
             documentLoader,
             contextLoader: mockDocumentLoader,
+            ...allowPrivateAddress,
             verifyPortableObject,
             crossOrigin: "trust",
           }),
@@ -270,6 +282,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
           await lookupObject("@alice@example.com", {
             documentLoader,
             contextLoader: mockDocumentLoader,
+            ...allowPrivateAddress,
             crossOrigin,
           }),
           null,
@@ -281,6 +294,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
           lookupObject("@alice@example.com", {
             documentLoader,
             contextLoader: mockDocumentLoader,
+            ...allowPrivateAddress,
             crossOrigin: "throw",
           }),
         /has a different origin than the document URL/,
@@ -292,6 +306,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
       const actor = await lookupObject("@alice@example.com", {
         documentLoader: httpLoader,
         contextLoader: mockDocumentLoader,
+        ...allowPrivateAddress,
       });
       assertInstanceOf(actor, Person);
       deepStrictEqual(actor.id, new URL(compatibleId));
@@ -303,6 +318,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
       const ordinary = await lookupObject(malformed, {
         documentLoader: ordinaryLoader,
         contextLoader: mockDocumentLoader,
+        ...allowPrivateAddress,
       });
       assertInstanceOf(ordinary, Person);
       deepStrictEqual(ordinaryLoader.fetched, [malformed]);
@@ -321,6 +337,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
       const options = {
         documentLoader,
         contextLoader: mockDocumentLoader,
+        ...allowPrivateAddress,
         verifyPortableObject: createVerifier(),
       };
       equal(await lookupObject("@alice@example.com", options), null);
@@ -341,6 +358,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
       const options = {
         documentLoader,
         contextLoader: mockDocumentLoader,
+        ...allowPrivateAddress,
         verifyPortableObject: createVerifier(),
       };
       equal(await lookupObject(dotted, options), null);
@@ -368,6 +386,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
         await lookupObject("@alice@example.com", {
           documentLoader,
           contextLoader: mockDocumentLoader,
+          ...allowPrivateAddress,
           verifyPortableObject: createVerifier(),
         }),
         null,
@@ -397,6 +416,7 @@ test("lookupObject() with FEP-ef61 portable actors", {
         await lookupObject("@alice@example.com", {
           documentLoader,
           contextLoader: mockDocumentLoader,
+          ...allowPrivateAddress,
           verifyPortableObject,
           signal: controller.signal,
         }),
@@ -573,13 +593,25 @@ test("getActorHandle() with FEP-ef61 portable actors", {
         "https://example.com/.well-known/webfinger?resource=acct%3Aalice%40example.com",
         selfLinks(compatibleId),
       );
-      deepStrictEqual(await getActorHandle(actor), "@alice@example.com");
+      deepStrictEqual(
+        await getActorHandle(actor, {
+          ...allowPrivateAddress,
+          userAgent: undefined,
+        }),
+        "@alice@example.com",
+      );
     });
 
     await t.step("canonical self link", async () => {
       fetchMock.removeRoutes();
       fetchMock.get(webFingerPrefix, selfLinks(`ap://${did}/actor`));
-      deepStrictEqual(await getActorHandle(actor), "@alice@example.com");
+      deepStrictEqual(
+        await getActorHandle(actor, {
+          ...allowPrivateAddress,
+          userAgent: undefined,
+        }),
+        "@alice@example.com",
+      );
     });
 
     await t.step("follows a verified subject", async () => {
@@ -592,7 +624,13 @@ test("getActorHandle() with FEP-ef61 portable actors", {
         "begin:https://example.org/.well-known/webfinger",
         { ...selfLinks(compatibleId), subject: "acct:alice@example.org" },
       );
-      deepStrictEqual(await getActorHandle(actor), "@alice@example.org");
+      deepStrictEqual(
+        await getActorHandle(actor, {
+          ...allowPrivateAddress,
+          userAgent: undefined,
+        }),
+        "@alice@example.org",
+      );
 
       // An unverified subject is ignored:
       fetchMock.removeRoutes();
@@ -604,7 +642,13 @@ test("getActorHandle() with FEP-ef61 portable actors", {
         "begin:https://example.org/.well-known/webfinger",
         selfLinks(`ap://${did}/other`),
       );
-      deepStrictEqual(await getActorHandle(actor), "@alice@example.com");
+      deepStrictEqual(
+        await getActorHandle(actor, {
+          ...allowPrivateAddress,
+          userAgent: undefined,
+        }),
+        "@alice@example.com",
+      );
     });
 
     await t.step("rejects a WebFinger response for another actor", async () => {
@@ -617,14 +661,28 @@ test("getActorHandle() with FEP-ef61 portable actors", {
       ) {
         fetchMock.removeRoutes();
         fetchMock.get(webFingerPrefix, jrd);
-        await rejects(() => getActorHandle(actor), TypeError);
+        await rejects(
+          () =>
+            getActorHandle(actor, {
+              ...allowPrivateAddress,
+              userAgent: undefined,
+            }),
+          TypeError,
+        );
       }
     });
 
     await t.step("does not fall back when WebFinger fails", async () => {
       fetchMock.removeRoutes();
       fetchMock.get(webFingerPrefix, 404);
-      await rejects(() => getActorHandle(actor), TypeError);
+      await rejects(
+        () =>
+          getActorHandle(actor, {
+            ...allowPrivateAddress,
+            userAgent: undefined,
+          }),
+        TypeError,
+      );
     });
 
     await t.step("not enough information", async () => {
@@ -640,7 +698,14 @@ test("getActorHandle() with FEP-ef61 portable actors", {
           }),
         ]
       ) {
-        await rejects(() => getActorHandle(target), TypeError);
+        await rejects(
+          () =>
+            getActorHandle(target, {
+              ...allowPrivateAddress,
+              userAgent: undefined,
+            }),
+          TypeError,
+        );
       }
       deepStrictEqual(fetchMock.callHistory.calls().length, 0);
     });

package/src/vocab.test.ts

@@ -1,3 +1,5 @@
+import { createDocumentLoader } from "../../vocab-runtime/src/docloader.ts";
+import { createPublicFetch } from "../../vocab-runtime/src/public-fetch.ts";
 import { mockDocumentLoader, test } from "@fedify/fixture";
 import {
   decodeMultibase,
@@ -1996,7 +1998,14 @@ test({
     const activity2 = new Activity({
       object: new URL("https://example.com/not-found"),
     });
-    deepStrictEqual(await activity2.getObject({ suppressError: true }), null);
+    deepStrictEqual(
+      await activity2.getObject({
+        documentLoader: mockDocumentLoader,
+        contextLoader: mockDocumentLoader,
+        suppressError: true,
+      }),
+      null,
+    );
 
     const activity3 = await Activity.fromJsonLd({
       "@context": "https://www.w3.org/ns/activitystreams",
@@ -2208,7 +2217,11 @@ test({
       ],
     });
     const objects2 = await Array.fromAsync(
-      activity2.getObjects({ suppressError: true }),
+      activity2.getObjects({
+        documentLoader: mockDocumentLoader,
+        contextLoader: mockDocumentLoader,
+        suppressError: true,
+      }),
     );
     deepStrictEqual(objects2.length, 1);
     assertInstanceOf(objects2[0], Object);
@@ -6359,6 +6372,15 @@ for (const typeUri in types) {
 }
 
 test("Announce.getObject() suppresses redirect, context, and private URL logs", async () => {
+  // Validate every hop, including private redirect targets, while keeping
+  // hostname-based fetch mocks independent of runtime connection pinning.
+  const publicFetch = createPublicFetch({
+    pinner: () => Promise.resolve(null),
+    lookup: () => Promise.resolve([{ address: "93.184.215.14", family: 4 }]),
+  });
+  const documentLoader = createDocumentLoader({}, {
+    openHop: (url) => publicFetch.openPublicFetch(url),
+  });
   const records: LogRecord[] = [];
   const objectUrl = "https://example.com/suppression-object";
   const contextUrl = "https://example.com/suppression-context";
@@ -6420,7 +6442,14 @@ test("Announce.getObject() suppresses redirect, context, and private URL logs",
             ),
           });
           if (suppressError) {
-            deepStrictEqual(await announce.getObject({ suppressError }), null);
+            deepStrictEqual(
+              await announce.getObject({
+                suppressError,
+                documentLoader,
+                contextLoader: documentLoader,
+              }),
+              null,
+            );
             deepStrictEqual(
               records.filter((r) => r.level === "error"),
               [],
@@ -6428,7 +6457,13 @@ test("Announce.getObject() suppresses redirect, context, and private URL logs",
             );
             ok(records.some((r) => r.level === "warning"), scenario);
           } else {
-            await rejects(() => announce.getObject({ suppressError }));
+            await rejects(() =>
+              announce.getObject({
+                suppressError,
+                documentLoader,
+                contextLoader: documentLoader,
+              })
+            );
             ok(records.some((r) => r.level === "error"), scenario);
           }
           if (scenario === "private") deepStrictEqual(fetches, 0);
@@ -6667,7 +6702,7 @@ test("portable verifiers suppress document logs only during dereferencing", asyn
       try {
         for (const suppressError of [true, false, undefined]) {
           records.length = 0;
-          const baseLoader = getDocumentLoader();
+          const baseLoader = getDocumentLoader({ allowPrivateAddress: true });
           const calls: Parameters<DocumentLoader>[1][] = [];
           const documentLoader: DocumentLoader = (url, options) => {
             calls.push(options);