@rmdes/indiekit-endpoint-activitypub 0.1.0

package/lib/inbox.js

@@ -0,0 +1,291 @@
+/**
+ * Inbox activity processors.
+ *
+ * Each handler receives a parsed ActivityStreams activity, the MongoDB
+ * collections, and a context object with delivery capabilities.
+ * Activities are auto-accepted (Follow) and logged for the admin UI.
+ */
+
+/**
+ * Dispatch an incoming activity to the appropriate handler.
+ *
+ * @param {object} activity - Parsed ActivityStreams activity
+ * @param {object} collections - MongoDB collections (ap_followers, ap_following, ap_activities)
+ * @param {object} context - { actorUrl, deliverActivity(activity, inboxUrl), storeRawActivities }
+ */
+export async function processInboxActivity(activity, collections, context) {
+  const type = activity.type;
+
+  switch (type) {
+    case "Follow":
+      return handleFollow(activity, collections, context);
+    case "Undo":
+      return handleUndo(activity, collections, context);
+    case "Like":
+      return handleLike(activity, collections, context);
+    case "Announce":
+      return handleAnnounce(activity, collections, context);
+    case "Create":
+      return handleCreate(activity, collections, context);
+    case "Delete":
+      return handleDelete(activity, collections);
+    case "Move":
+      return handleMove(activity, collections, context);
+    default:
+      await logActivity(collections, context, {
+        direction: "inbound",
+        type,
+        actorUrl: resolveActorUrl(activity.actor),
+        summary: `Received unhandled activity: ${type}`,
+        raw: activity,
+      });
+  }
+}
+
+/**
+ * Handle Follow — store follower, send Accept back.
+ */
+async function handleFollow(activity, collections, context) {
+  const followerActorUrl = resolveActorUrl(activity.actor);
+
+  // Fetch remote actor profile for display info
+  const profile = await fetchActorProfile(followerActorUrl);
+
+  // Upsert follower record
+  await collections.ap_followers.updateOne(
+    { actorUrl: followerActorUrl },
+    {
+      $set: {
+        actorUrl: followerActorUrl,
+        handle: profile.preferredUsername || "",
+        name:
+          profile.name || profile.preferredUsername || followerActorUrl,
+        avatar: profile.icon?.url || "",
+        inbox: profile.inbox || "",
+        sharedInbox: profile.endpoints?.sharedInbox || "",
+        followedAt: new Date(),
+      },
+    },
+    { upsert: true },
+  );
+
+  // Send Accept(Follow) back to the follower's inbox
+  const acceptActivity = {
+    "@context": "https://www.w3.org/ns/activitystreams",
+    type: "Accept",
+    actor: context.actorUrl,
+    object: activity,
+  };
+
+  const targetInbox = profile.inbox || `${followerActorUrl}inbox`;
+  await context.deliverActivity(acceptActivity, targetInbox);
+
+  await logActivity(collections, context, {
+    direction: "inbound",
+    type: "Follow",
+    actorUrl: followerActorUrl,
+    actorName:
+      profile.name || profile.preferredUsername || followerActorUrl,
+    summary: `${profile.name || followerActorUrl} followed you`,
+    raw: activity,
+  });
+}
+
+/**
+ * Handle Undo — dispatch based on the inner activity type.
+ */
+async function handleUndo(activity, collections, context) {
+  const inner =
+    typeof activity.object === "string" ? { type: "unknown" } : activity.object;
+  const actorUrl = resolveActorUrl(activity.actor);
+
+  switch (inner.type) {
+    case "Follow":
+      await collections.ap_followers.deleteOne({ actorUrl });
+      await logActivity(collections, context, {
+        direction: "inbound",
+        type: "Undo(Follow)",
+        actorUrl,
+        summary: `${actorUrl} unfollowed you`,
+        raw: activity,
+      });
+      break;
+
+    case "Like":
+      await collections.ap_activities.deleteOne({
+        type: "Like",
+        actorUrl,
+        objectUrl: resolveObjectUrl(inner.object),
+      });
+      break;
+
+    case "Announce":
+      await collections.ap_activities.deleteOne({
+        type: "Announce",
+        actorUrl,
+        objectUrl: resolveObjectUrl(inner.object),
+      });
+      break;
+
+    default:
+      await logActivity(collections, context, {
+        direction: "inbound",
+        type: `Undo(${inner.type})`,
+        actorUrl,
+        summary: `${actorUrl} undid ${inner.type}`,
+        raw: activity,
+      });
+  }
+}
+
+/**
+ * Handle Like — log for admin display.
+ */
+async function handleLike(activity, collections, context) {
+  const actorUrl = resolveActorUrl(activity.actor);
+  const objectUrl = resolveObjectUrl(activity.object);
+  const profile = await fetchActorProfile(actorUrl);
+
+  await logActivity(collections, context, {
+    direction: "inbound",
+    type: "Like",
+    actorUrl,
+    actorName: profile.name || profile.preferredUsername || actorUrl,
+    objectUrl,
+    summary: `${profile.name || actorUrl} liked ${objectUrl}`,
+    raw: activity,
+  });
+}
+
+/**
+ * Handle Announce (boost) — log for admin display.
+ */
+async function handleAnnounce(activity, collections, context) {
+  const actorUrl = resolveActorUrl(activity.actor);
+  const objectUrl = resolveObjectUrl(activity.object);
+  const profile = await fetchActorProfile(actorUrl);
+
+  await logActivity(collections, context, {
+    direction: "inbound",
+    type: "Announce",
+    actorUrl,
+    actorName: profile.name || profile.preferredUsername || actorUrl,
+    objectUrl,
+    summary: `${profile.name || actorUrl} boosted ${objectUrl}`,
+    raw: activity,
+  });
+}
+
+/**
+ * Handle Create — if it's a reply to one of our posts, log it.
+ */
+async function handleCreate(activity, collections, context) {
+  const object =
+    typeof activity.object === "string" ? { id: activity.object } : activity.object;
+  const inReplyTo = object.inReplyTo;
+
+  // Only log replies to our posts (inReplyTo is set)
+  if (!inReplyTo) return;
+
+  const actorUrl = resolveActorUrl(activity.actor);
+  const profile = await fetchActorProfile(actorUrl);
+
+  await logActivity(collections, context, {
+    direction: "inbound",
+    type: "Reply",
+    actorUrl,
+    actorName: profile.name || profile.preferredUsername || actorUrl,
+    objectUrl: object.id || object.url || "",
+    summary: `${profile.name || actorUrl} replied to ${inReplyTo}`,
+    raw: activity,
+  });
+}
+
+/**
+ * Handle Delete — remove activity records for deleted objects.
+ */
+async function handleDelete(activity, collections) {
+  const objectUrl = resolveObjectUrl(activity.object);
+  if (objectUrl) {
+    await collections.ap_activities.deleteMany({ objectUrl });
+  }
+}
+
+/**
+ * Handle Move — update follower record if actor moved to a new account.
+ * This is part of the Mastodon migration flow: after a Move, followers
+ * are expected to re-follow the new account.
+ */
+async function handleMove(activity, collections, context) {
+  const oldActorUrl = resolveActorUrl(activity.actor);
+  const newActorUrl = resolveObjectUrl(activity.target || activity.object);
+
+  if (oldActorUrl && newActorUrl) {
+    await collections.ap_followers.updateOne(
+      { actorUrl: oldActorUrl },
+      { $set: { actorUrl: newActorUrl, movedFrom: oldActorUrl } },
+    );
+  }
+
+  await logActivity(collections, context, {
+    direction: "inbound",
+    type: "Move",
+    actorUrl: oldActorUrl,
+    objectUrl: newActorUrl,
+    summary: `${oldActorUrl} moved to ${newActorUrl}`,
+    raw: activity,
+  });
+}
+
+// --- Helpers ---
+
+/**
+ * Extract actor URL from an activity's actor field.
+ * The actor can be a string URL or an object with an id field.
+ */
+function resolveActorUrl(actor) {
+  if (typeof actor === "string") return actor;
+  return actor?.id || "";
+}
+
+/**
+ * Extract object URL from an activity's object field.
+ */
+function resolveObjectUrl(object) {
+  if (typeof object === "string") return object;
+  return object?.id || object?.url || "";
+}
+
+/**
+ * Fetch a remote actor's profile document for display info.
+ * Returns an empty object on failure — federation should be resilient
+ * to unreachable remote servers.
+ */
+async function fetchActorProfile(actorUrl) {
+  try {
+    const response = await fetch(actorUrl, {
+      headers: { Accept: "application/activity+json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (response.ok) {
+      return await response.json();
+    }
+  } catch {
+    // Remote server unreachable — proceed without profile
+  }
+  return {};
+}
+
+/**
+ * Write an activity record to the ap_activities collection.
+ * Strips the raw JSON field unless storeRawActivities is enabled,
+ * keeping the activity log lightweight for backups.
+ */
+async function logActivity(collections, context, record) {
+  const { raw, ...rest } = record;
+  await collections.ap_activities.insertOne({
+    ...rest,
+    ...(context.storeRawActivities ? { raw } : {}),
+    receivedAt: new Date(),
+  });
+}

package/lib/jf2-to-as2.js

@@ -0,0 +1,191 @@
+/**
+ * Convert Indiekit JF2 post properties to ActivityStreams 2.0 objects.
+ *
+ * JF2 is the simplified Microformats2 JSON format used by Indiekit internally.
+ * ActivityStreams 2.0 (AS2) is the JSON-LD format used by ActivityPub for federation.
+ *
+ * @param {object} properties - JF2 post properties from Indiekit's posts collection
+ * @param {string} actorUrl - This actor's URL (e.g. "https://rmendes.net/")
+ * @param {string} publicationUrl - Publication base URL with trailing slash
+ * @returns {object} ActivityStreams activity (Create, Like, or Announce)
+ */
+export function jf2ToActivityStreams(properties, actorUrl, publicationUrl) {
+  const postType = properties["post-type"];
+
+  // Like — not wrapped in Create, stands alone
+  if (postType === "like") {
+    return {
+      "@context": "https://www.w3.org/ns/activitystreams",
+      type: "Like",
+      actor: actorUrl,
+      object: properties["like-of"],
+    };
+  }
+
+  // Repost/boost — Announce activity
+  if (postType === "repost") {
+    return {
+      "@context": "https://www.w3.org/ns/activitystreams",
+      type: "Announce",
+      actor: actorUrl,
+      object: properties["repost-of"],
+    };
+  }
+
+  // Everything else is wrapped in a Create activity
+  const isArticle = postType === "article" && properties.name;
+  const postUrl = resolvePostUrl(properties.url, publicationUrl);
+
+  const object = {
+    type: isArticle ? "Article" : "Note",
+    id: postUrl,
+    attributedTo: actorUrl,
+    published: properties.published,
+    url: postUrl,
+    to: ["https://www.w3.org/ns/activitystreams#Public"],
+    cc: [`${actorUrl.replace(/\/$/, "")}/activitypub/followers`],
+  };
+
+  // Content — bookmarks get special treatment
+  if (postType === "bookmark") {
+    const bookmarkUrl = properties["bookmark-of"];
+    const commentary = properties.content?.html || properties.content || "";
+    object.content = commentary
+      ? `${commentary}<br><br>\u{1F516} <a href="${bookmarkUrl}">${bookmarkUrl}</a>`
+      : `\u{1F516} <a href="${bookmarkUrl}">${bookmarkUrl}</a>`;
+    object.tag = [
+      {
+        type: "Hashtag",
+        name: "#bookmark",
+        href: `${publicationUrl}categories/bookmark`,
+      },
+    ];
+  } else {
+    object.content = properties.content?.html || properties.content || "";
+  }
+
+  if (isArticle) {
+    object.name = properties.name;
+    if (properties.summary) {
+      object.summary = properties.summary;
+    }
+  }
+
+  // Reply
+  if (properties["in-reply-to"]) {
+    object.inReplyTo = properties["in-reply-to"];
+  }
+
+  // Media attachments
+  const attachments = [];
+
+  if (properties.photo) {
+    const photos = Array.isArray(properties.photo)
+      ? properties.photo
+      : [properties.photo];
+    for (const photo of photos) {
+      const url = typeof photo === "string" ? photo : photo.url;
+      const alt = typeof photo === "string" ? "" : photo.alt || "";
+      attachments.push({
+        type: "Image",
+        mediaType: guessMediaType(url),
+        url: resolveMediaUrl(url, publicationUrl),
+        name: alt,
+      });
+    }
+  }
+
+  if (properties.video) {
+    const videos = Array.isArray(properties.video)
+      ? properties.video
+      : [properties.video];
+    for (const video of videos) {
+      const url = typeof video === "string" ? video : video.url;
+      attachments.push({
+        type: "Video",
+        url: resolveMediaUrl(url, publicationUrl),
+        name: "",
+      });
+    }
+  }
+
+  if (properties.audio) {
+    const audios = Array.isArray(properties.audio)
+      ? properties.audio
+      : [properties.audio];
+    for (const audio of audios) {
+      const url = typeof audio === "string" ? audio : audio.url;
+      attachments.push({
+        type: "Audio",
+        url: resolveMediaUrl(url, publicationUrl),
+        name: "",
+      });
+    }
+  }
+
+  if (attachments.length > 0) {
+    object.attachment = attachments;
+  }
+
+  // Categories → hashtags
+  if (properties.category) {
+    const categories = Array.isArray(properties.category)
+      ? properties.category
+      : [properties.category];
+    object.tag = [
+      ...(object.tag || []),
+      ...categories.map((cat) => ({
+        type: "Hashtag",
+        name: `#${cat.replace(/\s+/g, "")}`,
+        href: `${publicationUrl}categories/${encodeURIComponent(cat)}`,
+      })),
+    ];
+  }
+
+  return {
+    "@context": "https://www.w3.org/ns/activitystreams",
+    type: "Create",
+    actor: actorUrl,
+    object,
+  };
+}
+
+/**
+ * Resolve a post URL, ensuring it's absolute.
+ * @param {string} url - Post URL (may be relative or absolute)
+ * @param {string} publicationUrl - Base publication URL
+ * @returns {string} Absolute URL
+ */
+export function resolvePostUrl(url, publicationUrl) {
+  if (!url) return "";
+  if (url.startsWith("http")) return url;
+  const base = publicationUrl.replace(/\/$/, "");
+  return `${base}/${url.replace(/^\//, "")}`;
+}
+
+/**
+ * Resolve a media URL, ensuring it's absolute.
+ */
+function resolveMediaUrl(url, publicationUrl) {
+  if (!url) return "";
+  if (url.startsWith("http")) return url;
+  const base = publicationUrl.replace(/\/$/, "");
+  return `${base}/${url.replace(/^\//, "")}`;
+}
+
+/**
+ * Guess MIME type from file extension.
+ */
+function guessMediaType(url) {
+  const ext = url.split(".").pop()?.toLowerCase();
+  const types = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    avif: "image/avif",
+  };
+  return types[ext] || "image/jpeg";
+}

package/lib/keys.js

@@ -0,0 +1,39 @@
+import { generateKeyPair } from "node:crypto";
+import { promisify } from "node:util";
+
+const generateKeyPairAsync = promisify(generateKeyPair);
+
+/**
+ * Get or create an RSA 2048-bit key pair for the ActivityPub actor.
+ * Keys are stored in the ap_keys MongoDB collection so they persist
+ * across server restarts — a stable key pair is essential for federation
+ * since remote servers cache the public key for signature verification.
+ *
+ * @param {Collection} collection - MongoDB ap_keys collection
+ * @param {string} actorUrl - Actor URL (used as the key document identifier)
+ * @returns {Promise<{publicKeyPem: string, privateKeyPem: string}>}
+ */
+export async function getOrCreateKeyPair(collection, actorUrl) {
+  const existing = await collection.findOne({ actorUrl });
+  if (existing) {
+    return {
+      publicKeyPem: existing.publicKeyPem,
+      privateKeyPem: existing.privateKeyPem,
+    };
+  }
+
+  const { publicKey, privateKey } = await generateKeyPairAsync("rsa", {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: "spki", format: "pem" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  });
+
+  await collection.insertOne({
+    actorUrl,
+    publicKeyPem: publicKey,
+    privateKeyPem: privateKey,
+    createdAt: new Date(),
+  });
+
+  return { publicKeyPem: publicKey, privateKeyPem: privateKey };
+}

package/lib/migration.js

@@ -0,0 +1,184 @@
+/**
+ * Mastodon migration utilities.
+ *
+ * Parses Mastodon data export CSVs and resolves handles via WebFinger
+ * to import followers/following into the ActivityPub collections.
+ */
+
+/**
+ * Parse Mastodon's following_accounts.csv export.
+ * Format: "Account address,Show boosts,Notify on new posts,Languages"
+ * First row is the header.
+ *
+ * @param {string} csvText - Raw CSV text
+ * @returns {string[]} Array of handles (e.g. ["user@instance.social"])
+ */
+export function parseMastodonFollowingCsv(csvText) {
+  const lines = csvText.trim().split("\n");
+  // Skip header row
+  return lines
+    .slice(1)
+    .map((line) => line.split(",")[0].trim())
+    .filter((handle) => handle.length > 0 && handle.includes("@"));
+}
+
+/**
+ * Parse Mastodon's followers CSV or JSON export.
+ * Accepts the same CSV format as following, or a JSON array of actor URLs.
+ *
+ * @param {string} text - Raw CSV or JSON text
+ * @returns {string[]} Array of handles or actor URLs
+ */
+export function parseMastodonFollowersList(text) {
+  const trimmed = text.trim();
+
+  // Try JSON first (array of actor URLs)
+  if (trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      return Array.isArray(parsed) ? parsed.filter(Boolean) : [];
+    } catch {
+      // Fall through to CSV parsing
+    }
+  }
+
+  // CSV format — same as following
+  return parseMastodonFollowingCsv(trimmed);
+}
+
+/**
+ * Resolve a fediverse handle (user@instance) to an actor URL via WebFinger.
+ *
+ * @param {string} handle - Handle like "user@instance.social"
+ * @returns {Promise<{actorUrl: string, inbox: string, sharedInbox: string, name: string, handle: string} | null>}
+ */
+export async function resolveHandleViaWebFinger(handle) {
+  const [user, domain] = handle.split("@");
+  if (!user || !domain) return null;
+
+  try {
+    // WebFinger lookup
+    const wfUrl = `https://${domain}/.well-known/webfinger?resource=acct:${encodeURIComponent(handle)}`;
+    const wfResponse = await fetch(wfUrl, {
+      headers: { Accept: "application/jrd+json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!wfResponse.ok) return null;
+
+    const jrd = await wfResponse.json();
+    const selfLink = jrd.links?.find(
+      (l) => l.rel === "self" && l.type === "application/activity+json",
+    );
+
+    if (!selfLink?.href) return null;
+
+    // Fetch actor document for inbox and profile
+    const actorResponse = await fetch(selfLink.href, {
+      headers: { Accept: "application/activity+json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!actorResponse.ok) return null;
+
+    const actor = await actorResponse.json();
+    return {
+      actorUrl: actor.id || selfLink.href,
+      inbox: actor.inbox || "",
+      sharedInbox: actor.endpoints?.sharedInbox || "",
+      name: actor.name || actor.preferredUsername || handle,
+      handle: actor.preferredUsername || user,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Import a list of handles into the ap_following collection.
+ *
+ * @param {string[]} handles - Array of handles to import
+ * @param {Collection} collection - MongoDB ap_following collection
+ * @returns {Promise<{imported: number, failed: number}>}
+ */
+export async function bulkImportFollowing(handles, collection) {
+  let imported = 0;
+  let failed = 0;
+
+  for (const handle of handles) {
+    const resolved = await resolveHandleViaWebFinger(handle);
+    if (!resolved) {
+      failed++;
+      continue;
+    }
+
+    await collection.updateOne(
+      { actorUrl: resolved.actorUrl },
+      {
+        $set: {
+          actorUrl: resolved.actorUrl,
+          handle: resolved.handle,
+          name: resolved.name,
+          inbox: resolved.inbox,
+          sharedInbox: resolved.sharedInbox,
+          followedAt: new Date(),
+          source: "import",
+        },
+      },
+      { upsert: true },
+    );
+    imported++;
+  }
+
+  return { imported, failed };
+}
+
+/**
+ * Import a list of handles/URLs into the ap_followers collection.
+ * These are "pending" followers — they'll become real when they
+ * re-follow after the Mastodon Move activity.
+ *
+ * @param {string[]} entries - Array of handles or actor URLs
+ * @param {Collection} collection - MongoDB ap_followers collection
+ * @returns {Promise<{imported: number, failed: number}>}
+ */
+export async function bulkImportFollowers(entries, collection) {
+  let imported = 0;
+  let failed = 0;
+
+  for (const entry of entries) {
+    // If it's a URL, store directly; if it's a handle, resolve via WebFinger
+    const isUrl = entry.startsWith("http");
+    let actorData;
+
+    if (isUrl) {
+      actorData = { actorUrl: entry, handle: "", name: entry, inbox: "", sharedInbox: "" };
+    } else {
+      actorData = await resolveHandleViaWebFinger(entry);
+    }
+
+    if (!actorData) {
+      failed++;
+      continue;
+    }
+
+    await collection.updateOne(
+      { actorUrl: actorData.actorUrl },
+      {
+        $set: {
+          actorUrl: actorData.actorUrl,
+          handle: actorData.handle,
+          name: actorData.name,
+          inbox: actorData.inbox,
+          sharedInbox: actorData.sharedInbox,
+          followedAt: new Date(),
+          pending: true, // Will be confirmed when they re-follow after Move
+        },
+      },
+      { upsert: true },
+    );
+    imported++;
+  }
+
+  return { imported, failed };
+}