@rmdes/indiekit-endpoint-activitypub 2.0.25 → 2.0.27

package/README.md

@@ -268,11 +268,66 @@ The JF2-to-ActivityStreams converter handles these Indiekit post types:
 
 Categories are converted to `Hashtag` tags. Bookmarks include a bookmark emoji and link.
 
+## Fedify Workarounds and Implementation Notes
+
+This plugin uses [Fedify](https://fedify.dev) 2.0 but carries several workarounds for issues in Fedify or its Express integration. These are documented here so they can be revisited when Fedify upgrades.
+
+### Custom Express Bridge (instead of `@fedify/express`)
+
+**File:** `lib/federation-bridge.js`
+**Upstream issue:** `@fedify/express` uses `req.url` ([source](https://github.com/fedify-dev/fedify/blob/main/packages/express/src/index.ts), line 73), not `req.originalUrl`.
+
+Indiekit plugins mount at a sub-path (e.g. `/activitypub`). Express strips the mount prefix from `req.url`, so Fedify's URI template matching breaks — WebFinger, actor endpoints, and inbox all return 404. The custom bridge uses `req.originalUrl` to preserve the full path.
+
+The bridge also reconstructs POST bodies that Express's body parser has already consumed (`req.readable === false`). Without this, Fedify handlers like the `@fedify/debugger` login form receive empty bodies.
+
+**Revisit when:** `@fedify/express` switches to `req.originalUrl`, or provides an option to pass a custom URL builder.
+
+### JSON-LD Attachment Array Compaction
+
+**File:** `lib/federation-bridge.js` (in `sendFedifyResponse()`)
+**Upstream issue:** JSON-LD compaction collapses single-element arrays to plain objects.
+
+Mastodon's `update_account_fields` checks `attachment.is_a?(Array)` and silently skips profile links (PropertyValues) when `attachment` is a plain object instead of an array. The bridge intercepts actor JSON-LD responses and forces `attachment` to always be an array.
+
+**Revisit when:** Fedify adds an option to preserve arrays during JSON-LD serialization, or Mastodon fixes their array check.
+
+### `.authorize()` Not Chained on Actor Dispatcher
+
+**File:** `lib/federation-setup.js` (line ~254)
+**Upstream issue:** No authenticated document loading for outgoing key fetches during signature verification.
+
+Fedify's `.authorize()` predicate triggers HTTP Signature verification on every GET to the actor endpoint. When a remote server that requires Authorized Fetch (e.g. kobolds.online) requests our actor, Fedify tries to fetch *their* public key to verify the signature. Those servers return 401 on unsigned GETs, causing uncaught `FetchError` and 500 responses.
+
+This means we do **not** enforce Authorized Fetch on our actor endpoint. Any server can read our actor document without signing the request.
+
+**Revisit when:** Fedify supports using the instance actor's keys for outgoing document fetches during signature verification (i.e. authenticated document loading in the verification path, not just in inbox handlers).
+
+### `importSpkiPem()` / `importPkcs8Pem()` — Local PEM Import
+
+**File:** `lib/federation-setup.js` (lines ~784–816)
+**Upstream change:** Fedify 1.x exported `importSpki()` for loading PEM public keys. This was removed in Fedify 2.0.
+
+The plugin carries local `importSpkiPem()` and `importPkcs8Pem()` functions that use the Web Crypto API directly (`crypto.subtle.importKey`) to load legacy RSA key pairs stored in MongoDB from the Fedify 1.x era. New key pairs are generated using Fedify 2.0's `generateCryptoKeyPair()` and stored as JWK, so these functions only matter for existing installations that migrated from Fedify 1.x.
+
+**Revisit when:** All existing installations have been migrated to JWK-stored keys, or Fedify re-exports a PEM import utility.
+
+### Authenticated Document Loader for Inbox Handlers
+
+**File:** `lib/inbox-listeners.js`
+**Upstream behavior:** Fedify's personal inbox handlers do not automatically use authenticated (signed) HTTP fetches.
+
+All `.getActor()`, `.getObject()`, and `.getTarget()` calls in inbox handlers must explicitly pass an authenticated `DocumentLoader` obtained via `ctx.getDocumentLoader({ identifier: handle })`. Without this, fetches to Authorized Fetch (Secure Mode) servers like hachyderm.io fail with 401, causing timeline items to show "Unknown" authors and missing content.
+
+This is not a bug — Fedify requires explicit opt-in for signed fetches. But it's a pattern that every inbox handler must follow, and forgetting it silently degrades functionality.
+
+**Revisit when:** Fedify provides an option to default to authenticated fetches in inbox handler context, or adds a middleware layer that handles this automatically.
+
 ## Known Limitations
 
 - **No automated tests** — Manual testing against real fediverse servers
 - **Single actor** — One fediverse identity per Indiekit instance
-- **No Authorized Fetch enforcement** — Disabled due to Fedify's current limitation with authenticated outgoing fetches (causes infinite loops with servers that require it)
+- **No Authorized Fetch enforcement** — `.authorize()` disabled on actor dispatcher (see workarounds above)
 - **No image upload in reader** — Compose form is text-only
 - **In-process queue without Redis** — Activities may be lost on restart
 

package/lib/federation-bridge.js

@@ -72,11 +72,11 @@ async function sendFedifyResponse(res, response, request) {
     return;
   }
 
-  // WORKAROUND: Fedify serializes endpoints with "type": "as:Endpoints"
-  // which is not a real ActivityStreams type (fails browser.pub validation).
-  // For actor JSON responses, buffer the body and strip the invalid type.
-  // See: https://github.com/fedify-dev/fedify/issues/576
-  // TODO: Remove this workaround when Fedify fixes the upstream issue.
+  // WORKAROUND: JSON-LD compaction collapses single-element arrays to a
+  // plain object. Mastodon's update_account_fields checks
+  // `attachment.is_a?(Array)` and skips if it's not an array, so
+  // profile links/PropertyValues are silently ignored.
+  // Force `attachment` to always be an array for Mastodon compatibility.
   const contentType = response.headers.get("content-type") || "";
   const isActorJson =
     contentType.includes("activity+json") ||
@@ -86,14 +86,6 @@ async function sendFedifyResponse(res, response, request) {
     const body = await response.text();
     try {
       const json = JSON.parse(body);
-      if (json.endpoints?.type) {
-        delete json.endpoints.type;
-      }
-      // WORKAROUND: Fedify's JSON-LD compaction collapses single-element
-      // arrays to a plain object. Mastodon's update_account_fields checks
-      // `attachment.is_a?(Array)` and skips if it's not an array, so
-      // profile links/PropertyValues are silently ignored.
-      // Force `attachment` to always be an array for Mastodon compatibility.
       if (json.attachment && !Array.isArray(json.attachment)) {
         json.attachment = [json.attachment];
       }

package/lib/inbox-listeners.js

@@ -41,9 +41,20 @@ import { fetchAndStorePreviews } from "./og-unfurl.js";
 export function registerInboxListeners(inboxChain, options) {
   const { collections, handle, storeRawActivities } = options;
 
+  /**
+   * Get an authenticated DocumentLoader that signs outbound fetches with
+   * our actor's key. This allows .getActor()/.getObject() to succeed
+   * against Authorized Fetch (Secure Mode) servers like hachyderm.io.
+   *
+   * @param {import("@fedify/fedify").Context} ctx - Fedify context
+   * @returns {Promise<import("@fedify/fedify").DocumentLoader>}
+   */
+  const getAuthLoader = (ctx) => ctx.getDocumentLoader({ identifier: handle });
+
   inboxChain
     .on(Follow, async (ctx, follow) => {
-      const followerActor = await follow.getActor();
+      const authLoader = await getAuthLoader(ctx);
+      const followerActor = await follow.getActor({ documentLoader: authLoader });
       if (!followerActor?.id) return;
 
       const followerUrl = followerActor.id.href;
@@ -90,7 +101,7 @@ export function registerInboxListeners(inboxChain, options) {
       });
 
       // Store notification
-      const followerInfo = await extractActorInfo(followerActor);
+      const followerInfo = await extractActorInfo(followerActor, { documentLoader: authLoader });
       await addNotification(collections, {
         uid: follow.id?.href || `follow:${followerUrl}`,
         type: "follow",
@@ -104,9 +115,10 @@ export function registerInboxListeners(inboxChain, options) {
     })
     .on(Undo, async (ctx, undo) => {
       const actorUrl = undo.actorId?.href || "";
+      const authLoader = await getAuthLoader(ctx);
       let inner;
       try {
-        inner = await undo.getObject();
+        inner = await undo.getObject({ documentLoader: authLoader });
       } catch {
         // Inner activity not dereferenceable — can't determine what was undone
         return;
@@ -150,7 +162,8 @@ export function registerInboxListeners(inboxChain, options) {
       // it to a Person (the Follow's target) rather than the Follow itself.
       // Instead, we match directly against ap_following — if we have a
       // pending follow for this actor, any Accept from them confirms it.
-      const actorObj = await accept.getActor();
+      const authLoader = await getAuthLoader(ctx);
+      const actorObj = await accept.getActor({ documentLoader: authLoader });
       const actorUrl = actorObj?.id?.href || "";
       if (!actorUrl) return;
 
@@ -186,7 +199,8 @@ export function registerInboxListeners(inboxChain, options) {
       }
     })
     .on(Reject, async (ctx, reject) => {
-      const actorObj = await reject.getActor();
+      const authLoader = await getAuthLoader(ctx);
+      const actorObj = await reject.getActor({ documentLoader: authLoader });
       const actorUrl = actorObj?.id?.href || "";
       if (!actorUrl) return;
 
@@ -217,20 +231,19 @@ export function registerInboxListeners(inboxChain, options) {
       }
     })
     .on(Like, async (ctx, like) => {
-      // Use .objectId to get the URL without dereferencing the remote object.
-      // Calling .getObject() would trigger an HTTP fetch to the remote server,
-      // which fails with 404 when the server has Authorized Fetch (Secure Mode)
-      // enabled — causing pointless retries and log spam.
+      // Use .objectId (non-fetching) for the liked URL — we only need the
+      // URL to filter and log, not the full remote object.
       const objectId = like.objectId?.href || "";
 
       // Only log likes of our own content
       const pubUrl = collections._publicationUrl;
       if (!objectId || (pubUrl && !objectId.startsWith(pubUrl))) return;
 
+      const authLoader = await getAuthLoader(ctx);
       const actorUrl = like.actorId?.href || "";
       let actorObj;
       try {
-        actorObj = await like.getActor();
+        actorObj = await like.getActor({ documentLoader: authLoader });
       } catch {
         actorObj = null;
       }
@@ -240,17 +253,20 @@ export function registerInboxListeners(inboxChain, options) {
         actorObj?.preferredUsername?.toString() ||
         actorUrl;
 
+      // Extract actor info (including avatar) before logging so we can store it
+      const actorInfo = await extractActorInfo(actorObj, { documentLoader: authLoader });
+
       await logActivity(collections, storeRawActivities, {
         direction: "inbound",
         type: "Like",
         actorUrl,
         actorName,
+        actorAvatar: actorInfo.photo || "",
         objectUrl: objectId,
         summary: `${actorName} liked ${objectId}`,
       });
 
       // Store notification
-      const actorInfo = await extractActorInfo(actorObj);
       await addNotification(collections, {
         uid: like.id?.href || `like:${actorUrl}:${objectId}`,
         type: "like",
@@ -268,6 +284,7 @@ export function registerInboxListeners(inboxChain, options) {
       const objectId = announce.objectId?.href || "";
       if (!objectId) return;
 
+      const authLoader = await getAuthLoader(ctx);
       const actorUrl = announce.actorId?.href || "";
       const pubUrl = collections._publicationUrl;
 
@@ -277,7 +294,7 @@ export function registerInboxListeners(inboxChain, options) {
       if (pubUrl && objectId.startsWith(pubUrl)) {
         let actorObj;
         try {
-          actorObj = await announce.getActor();
+          actorObj = await announce.getActor({ documentLoader: authLoader });
         } catch {
           actorObj = null;
         }
@@ -287,18 +304,21 @@ export function registerInboxListeners(inboxChain, options) {
           actorObj?.preferredUsername?.toString() ||
           actorUrl;
 
+        // Extract actor info (including avatar) before logging so we can store it
+        const actorInfo = await extractActorInfo(actorObj, { documentLoader: authLoader });
+
         // Log the boost activity
         await logActivity(collections, storeRawActivities, {
           direction: "inbound",
           type: "Announce",
           actorUrl,
           actorName,
+          actorAvatar: actorInfo.photo || "",
           objectUrl: objectId,
           summary: `${actorName} boosted ${objectId}`,
         });
 
         // Create notification
-        const actorInfo = await extractActorInfo(actorObj);
         await addNotification(collections, {
           uid: announce.id?.href || `${actorUrl}#boost-${objectId}`,
           type: "boost",
@@ -319,8 +339,8 @@ export function registerInboxListeners(inboxChain, options) {
       const following = await collections.ap_following.findOne({ actorUrl });
       if (following) {
         try {
-          // Fetch the original object being boosted
-          const object = await announce.getObject();
+          // Fetch the original object being boosted (authenticated for Secure Mode servers)
+          const object = await announce.getObject({ documentLoader: authLoader });
           if (!object) return;
 
           // Skip non-content objects (Lemmy/PieFed like/create activities
@@ -329,13 +349,14 @@ export function registerInboxListeners(inboxChain, options) {
           if (!hasContent) return;
 
           // Get booster actor info
-          const boosterActor = await announce.getActor();
-          const boosterInfo = await extractActorInfo(boosterActor);
+          const boosterActor = await announce.getActor({ documentLoader: authLoader });
+          const boosterInfo = await extractActorInfo(boosterActor, { documentLoader: authLoader });
 
           // Extract and store with boost metadata
           const timelineItem = await extractObjectData(object, {
             boostedBy: boosterInfo,
             boostedAt: announce.published ? String(announce.published) : new Date().toISOString(),
+            documentLoader: authLoader,
           });
 
           await addTimelineItem(collections, timelineItem);
@@ -347,11 +368,12 @@ export function registerInboxListeners(inboxChain, options) {
       }
     })
     .on(Create, async (ctx, create) => {
+      const authLoader = await getAuthLoader(ctx);
       let object;
       try {
-        object = await create.getObject();
+        object = await create.getObject({ documentLoader: authLoader });
       } catch {
-        // Remote object not dereferenceable (Authorized Fetch, deleted, etc.)
+        // Remote object not dereferenceable (deleted, etc.)
         return;
       }
       if (!object) return;
@@ -359,7 +381,7 @@ export function registerInboxListeners(inboxChain, options) {
       const actorUrl = create.actorId?.href || "";
       let actorObj;
       try {
-        actorObj = await create.getActor();
+        actorObj = await create.getActor({ documentLoader: authLoader });
       } catch {
         // Actor not dereferenceable — use URL as fallback
         actorObj = null;
@@ -376,11 +398,16 @@ export function registerInboxListeners(inboxChain, options) {
       const pubUrl = collections._publicationUrl;
       if (inReplyTo) {
         const content = object.content?.toString() || "";
+
+        // Extract actor info (including avatar) before logging so we can store it
+        const actorInfo = await extractActorInfo(actorObj, { documentLoader: authLoader });
+
         await logActivity(collections, storeRawActivities, {
           direction: "inbound",
           type: "Reply",
           actorUrl,
           actorName,
+          actorAvatar: actorInfo.photo || "",
           objectUrl: object.id?.href || "",
           targetUrl: inReplyTo,
           content,
@@ -389,7 +416,6 @@ export function registerInboxListeners(inboxChain, options) {
 
         // Create notification if reply is to one of OUR posts
         if (pubUrl && inReplyTo.startsWith(pubUrl)) {
-          const actorInfo = await extractActorInfo(actorObj);
           const rawHtml = object.content?.toString() || "";
           const contentHtml = sanitizeContent(rawHtml);
           const contentText = rawHtml.replace(/<[^>]*>/g, "").substring(0, 200);
@@ -420,7 +446,7 @@ export function registerInboxListeners(inboxChain, options) {
 
         for (const tag of tags) {
           if (tag.type === "Mention" && tag.href?.href === ourActorUrl) {
-            const actorInfo = await extractActorInfo(actorObj);
+            const actorInfo = await extractActorInfo(actorObj, { documentLoader: authLoader });
             const rawMentionHtml = object.content?.toString() || "";
             const mentionHtml = sanitizeContent(rawMentionHtml);
             const contentText = rawMentionHtml.replace(/<[^>]*>/g, "").substring(0, 200);
@@ -451,6 +477,7 @@ export function registerInboxListeners(inboxChain, options) {
         try {
           const timelineItem = await extractObjectData(object, {
             actorFallback: actorObj,
+            documentLoader: authLoader,
           });
           await addTimelineItem(collections, timelineItem);
 
@@ -479,9 +506,10 @@ export function registerInboxListeners(inboxChain, options) {
       }
     })
     .on(Move, async (ctx, move) => {
-      const oldActorObj = await move.getActor();
+      const authLoader = await getAuthLoader(ctx);
+      const oldActorObj = await move.getActor({ documentLoader: authLoader });
       const oldActorUrl = oldActorObj?.id?.href || "";
-      const target = await move.getTarget();
+      const target = await move.getTarget({ documentLoader: authLoader });
       const newActorUrl = target?.id?.href || "";
 
       if (oldActorUrl && newActorUrl) {
@@ -501,11 +529,12 @@ export function registerInboxListeners(inboxChain, options) {
     })
     .on(Update, async (ctx, update) => {
       // Update can be for a profile OR for a post (edited content)
+      const authLoader = await getAuthLoader(ctx);
 
       // Try to get the object being updated
       let object;
       try {
-        object = await update.getObject();
+        object = await update.getObject({ documentLoader: authLoader });
       } catch {
         object = null;
       }
@@ -538,7 +567,7 @@ export function registerInboxListeners(inboxChain, options) {
       }
 
       // PATH 2: Otherwise, assume profile update — refresh stored follower data
-      const actorObj = await update.getActor();
+      const actorObj = await update.getActor({ documentLoader: authLoader });
       const actorUrl = actorObj?.id?.href || "";
       if (!actorUrl) return;
 
@@ -564,7 +593,8 @@ export function registerInboxListeners(inboxChain, options) {
     })
     .on(Block, async (ctx, block) => {
       // Remote actor blocked us — remove them from followers
-      const actorObj = await block.getActor();
+      const authLoader = await getAuthLoader(ctx);
+      const actorObj = await block.getActor({ documentLoader: authLoader });
       const actorUrl = actorObj?.id?.href || "";
       if (actorUrl) {
         await collections.ap_followers.deleteOne({ actorUrl });

package/lib/timeline-store.js

@@ -36,9 +36,11 @@ export function sanitizeContent(html) {
 /**
  * Extract actor information from Fedify Person/Application/Service object
  * @param {object} actor - Fedify actor object
+ * @param {object} [options] - Options
+ * @param {object} [options.documentLoader] - Authenticated DocumentLoader for Secure Mode servers
  * @returns {object} { name, url, photo, handle }
  */
-export async function extractActorInfo(actor) {
+export async function extractActorInfo(actor, options = {}) {
   if (!actor) {
     return {
       name: "Unknown",
@@ -54,10 +56,11 @@ export async function extractActorInfo(actor) {
   const url = actor.id?.href || "";
 
   // Extract photo URL from icon (Fedify uses async getters)
+  const loaderOpts = options.documentLoader ? { documentLoader: options.documentLoader } : {};
   let photo = "";
   try {
     if (typeof actor.getIcon === "function") {
-      const iconObj = await actor.getIcon();
+      const iconObj = await actor.getIcon(loaderOpts);
       photo = iconObj?.url?.href || "";
     } else {
       const iconObj = await actor.icon;
@@ -89,6 +92,7 @@ export async function extractActorInfo(actor) {
  * @param {object} [options.boostedBy] - Actor info for boosts
  * @param {Date} [options.boostedAt] - Boost timestamp
  * @param {object} [options.actorFallback] - Fedify actor to use when object.getAttributedTo() fails
+ * @param {object} [options.documentLoader] - Authenticated DocumentLoader for Secure Mode servers
  * @returns {Promise<object>} Timeline item data
  */
 export async function extractObjectData(object, options = {}) {
@@ -130,14 +134,15 @@ export async function extractObjectData(object, options = {}) {
     : new Date().toISOString();
 
   // Extract author — try multiple strategies in order of reliability
+  const loaderOpts = options.documentLoader ? { documentLoader: options.documentLoader } : {};
   let authorObj = null;
   try {
     if (typeof object.getAttributedTo === "function") {
-      const attr = await object.getAttributedTo();
+      const attr = await object.getAttributedTo(loaderOpts);
       authorObj = Array.isArray(attr) ? attr[0] : attr;
     }
   } catch {
-    // getAttributedTo() failed (Authorized Fetch, unreachable, etc.)
+    // getAttributedTo() failed (unreachable, deleted, etc.)
   }
   // If getAttributedTo() returned nothing, use the actor from the wrapping activity
   if (!authorObj && options.actorFallback) {
@@ -150,7 +155,7 @@ export async function extractObjectData(object, options = {}) {
 
   let author;
   if (authorObj) {
-    author = await extractActorInfo(authorObj);
+    author = await extractActorInfo(authorObj, loaderOpts);
   } else {
     // Last resort: use attributionIds (non-fetching) to get at least a URL
     const attrIds = object.attributionIds;
@@ -184,7 +189,7 @@ export async function extractObjectData(object, options = {}) {
   const category = [];
   try {
     if (typeof object.getTags === "function") {
-      const tags = await object.getTags();
+      const tags = await object.getTags(loaderOpts);
       for await (const tag of tags) {
         if (tag.name) {
           const tagName = tag.name.toString().replace(/^#/, "");
@@ -203,7 +208,7 @@ export async function extractObjectData(object, options = {}) {
 
   try {
     if (typeof object.getAttachments === "function") {
-      const attachments = await object.getAttachments();
+      const attachments = await object.getAttachments(loaderOpts);
       for await (const att of attachments) {
         const mediaUrl = att.url?.href || "";
         if (!mediaUrl) continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmdes/indiekit-endpoint-activitypub",
-  "version": "2.0.25",
+  "version": "2.0.27",
   "description": "ActivityPub federation endpoint for Indiekit via Fedify. Adds full fediverse support: actor, inbox, outbox, followers, following, syndication, and Mastodon migration.",
   "keywords": [
     "indiekit",