@rmdes/indiekit-endpoint-activitypub 1.0.28 → 1.1.1

package/lib/storage/notifications.js

@@ -0,0 +1,132 @@
+/**
+ * Notification storage operations
+ * @module storage/notifications
+ */
+
+/**
+ * Add a notification (uses atomic upsert for deduplication)
+ * @param {object} collections - MongoDB collections
+ * @param {object} notification - Notification data
+ * @param {string} notification.uid - Activity ID or constructed dedup key
+ * @param {string} notification.type - "like" | "boost" | "follow" | "mention" | "reply"
+ * @param {string} notification.actorUrl - Remote actor URL
+ * @param {string} notification.actorName - Display name
+ * @param {string} notification.actorPhoto - Avatar URL
+ * @param {string} notification.actorHandle - @user@instance
+ * @param {string} [notification.targetUrl] - The post they liked/boosted/replied to
+ * @param {string} [notification.targetName] - Post title
+ * @param {object} [notification.content] - { text, html } for mentions/replies
+ * @param {Date} notification.published - Activity timestamp (kept as Date for sort)
+ * @param {string} notification.createdAt - ISO string creation timestamp
+ * @returns {Promise<object>} Created or existing notification
+ */
+export async function addNotification(collections, notification) {
+  const { ap_notifications } = collections;
+
+  const result = await ap_notifications.updateOne(
+    { uid: notification.uid },
+    {
+      $setOnInsert: {
+        ...notification,
+        read: false,
+      },
+    },
+    { upsert: true },
+  );
+
+  if (result.upsertedCount > 0) {
+    return await ap_notifications.findOne({ uid: notification.uid });
+  }
+
+  // Return existing document if it was a duplicate
+  return await ap_notifications.findOne({ uid: notification.uid });
+}
+
+/**
+ * Get notifications with cursor-based pagination
+ * @param {object} collections - MongoDB collections
+ * @param {object} options - Query options
+ * @param {string} [options.before] - Before cursor (published date)
+ * @param {number} [options.limit=20] - Items per page
+ * @param {boolean} [options.unreadOnly=false] - Show only unread notifications
+ * @returns {Promise<object>} { items, before }
+ */
+export async function getNotifications(collections, options = {}) {
+  const { ap_notifications } = collections;
+  const parsedLimit = Number.parseInt(options.limit, 10);
+  const limit = Math.min(
+    Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 20,
+    100,
+  );
+
+  const query = {};
+
+  // Unread filter
+  if (options.unreadOnly) {
+    query.read = false;
+  }
+
+  // Cursor pagination
+  if (options.before) {
+    query.published = { $lt: new Date(options.before) };
+  }
+
+  const rawItems = await ap_notifications
+    .find(query)
+    .sort({ published: -1 })
+    .limit(limit)
+    .toArray();
+
+  // Normalize published dates to ISO strings for Nunjucks | date filter
+  const items = rawItems.map((item) => ({
+    ...item,
+    published: item.published instanceof Date
+      ? item.published.toISOString()
+      : item.published,
+  }));
+
+  // Generate cursor for next page
+  const before =
+    items.length > 0
+      ? items[items.length - 1].published
+      : null;
+
+  return {
+    items,
+    before,
+  };
+}
+
+/**
+ * Get count of unread notifications
+ * @param {object} collections - MongoDB collections
+ * @returns {Promise<number>} Unread notification count
+ */
+export async function getUnreadNotificationCount(collections) {
+  const { ap_notifications } = collections;
+  return await ap_notifications.countDocuments({ read: false });
+}
+
+/**
+ * Mark notifications as read
+ * @param {object} collections - MongoDB collections
+ * @param {string[]} uids - Notification UIDs to mark read
+ * @returns {Promise<object>} Update result
+ */
+export async function markNotificationsRead(collections, uids) {
+  const { ap_notifications } = collections;
+  return await ap_notifications.updateMany(
+    { uid: { $in: uids } },
+    { $set: { read: true } },
+  );
+}
+
+/**
+ * Mark all notifications as read
+ * @param {object} collections - MongoDB collections
+ * @returns {Promise<object>} Update result
+ */
+export async function markAllNotificationsRead(collections) {
+  const { ap_notifications } = collections;
+  return await ap_notifications.updateMany({}, { $set: { read: true } });
+}

package/lib/storage/timeline.js

@@ -0,0 +1,210 @@
+/**
+ * Timeline item storage operations
+ * @module storage/timeline
+ */
+
+/**
+ * Add a timeline item (uses atomic upsert for deduplication)
+ * @param {object} collections - MongoDB collections
+ * @param {object} item - Timeline item data
+ * @param {string} item.uid - Canonical AP object URL (dedup key)
+ * @param {string} item.type - "note" | "article" | "boost"
+ * @param {string} item.url - Post URL
+ * @param {string} [item.name] - Post title (articles only)
+ * @param {object} item.content - { text, html }
+ * @param {string} [item.summary] - Content warning text
+ * @param {boolean} item.sensitive - Sensitive content flag
+ * @param {Date} item.published - Published date (kept as Date for sort queries)
+ * @param {object} item.author - { name, url, photo, handle }
+ * @param {string[]} item.category - Tags/categories
+ * @param {string[]} item.photo - Photo URLs
+ * @param {string[]} item.video - Video URLs
+ * @param {string[]} item.audio - Audio URLs
+ * @param {string} [item.inReplyTo] - Parent post URL
+ * @param {object} [item.boostedBy] - { name, url, photo, handle } for boosts
+ * @param {Date} [item.boostedAt] - Boost timestamp
+ * @param {string} [item.originalUrl] - Original post URL for boosts
+ * @param {string} item.createdAt - ISO string creation timestamp
+ * @returns {Promise<object>} Created or existing item
+ */
+export async function addTimelineItem(collections, item) {
+  const { ap_timeline } = collections;
+
+  const result = await ap_timeline.updateOne(
+    { uid: item.uid },
+    {
+      $setOnInsert: {
+        ...item,
+        readBy: [],
+      },
+    },
+    { upsert: true },
+  );
+
+  if (result.upsertedCount > 0) {
+    return await ap_timeline.findOne({ uid: item.uid });
+  }
+
+  // Return existing document if it was a duplicate
+  return await ap_timeline.findOne({ uid: item.uid });
+}
+
+/**
+ * Get timeline items with cursor-based pagination
+ * @param {object} collections - MongoDB collections
+ * @param {object} options - Query options
+ * @param {string} [options.before] - Before cursor (published date)
+ * @param {string} [options.after] - After cursor (published date)
+ * @param {number} [options.limit=20] - Items per page
+ * @param {string} [options.type] - Filter by type
+ * @param {string} [options.authorUrl] - Filter by author URL
+ * @returns {Promise<object>} { items, before, after }
+ */
+export async function getTimelineItems(collections, options = {}) {
+  const { ap_timeline } = collections;
+  const parsedLimit = Number.parseInt(options.limit, 10);
+  const limit = Math.min(
+    Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 20,
+    100,
+  );
+
+  const query = {};
+
+  // Type filter
+  if (options.type) {
+    query.type = options.type;
+  }
+
+  // Author filter (for profile view) — validate string type to prevent operator injection
+  if (options.authorUrl) {
+    if (typeof options.authorUrl !== "string") {
+      throw new Error("Invalid authorUrl");
+    }
+
+    query["author.url"] = options.authorUrl;
+  }
+
+  // Cursor pagination — validate dates
+  if (options.before) {
+    const beforeDate = new Date(options.before);
+
+    if (Number.isNaN(beforeDate.getTime())) {
+      throw new Error("Invalid before cursor");
+    }
+
+    query.published = { $lt: beforeDate };
+  } else if (options.after) {
+    const afterDate = new Date(options.after);
+
+    if (Number.isNaN(afterDate.getTime())) {
+      throw new Error("Invalid after cursor");
+    }
+
+    query.published = { $gt: afterDate };
+  }
+
+  const rawItems = await ap_timeline
+    .find(query)
+    .sort({ published: -1 })
+    .limit(limit)
+    .toArray();
+
+  // Normalize published dates to ISO strings for Nunjucks | date filter
+  const items = rawItems.map((item) => ({
+    ...item,
+    published: item.published instanceof Date
+      ? item.published.toISOString()
+      : item.published,
+  }));
+
+  // Generate cursors for pagination
+  const before =
+    items.length > 0
+      ? items[0].published
+      : null;
+  const after =
+    items.length > 0
+      ? items[items.length - 1].published
+      : null;
+
+  return {
+    items,
+    before,
+    after,
+  };
+}
+
+/**
+ * Get a single timeline item by UID
+ * @param {object} collections - MongoDB collections
+ * @param {string} uid - Item UID (canonical URL)
+ * @returns {Promise<object|null>} Timeline item or null
+ */
+export async function getTimelineItem(collections, uid) {
+  const { ap_timeline } = collections;
+  return await ap_timeline.findOne({ uid });
+}
+
+/**
+ * Delete a timeline item by UID
+ * @param {object} collections - MongoDB collections
+ * @param {string} uid - Item UID
+ * @returns {Promise<object>} Delete result
+ */
+export async function deleteTimelineItem(collections, uid) {
+  const { ap_timeline } = collections;
+  return await ap_timeline.deleteOne({ uid });
+}
+
+/**
+ * Update a timeline item's content (for Update activities)
+ * @param {object} collections - MongoDB collections
+ * @param {string} uid - Item UID
+ * @param {object} updates - Fields to update
+ * @param {object} [updates.content] - New content
+ * @param {string} [updates.name] - New title
+ * @param {string} [updates.summary] - New content warning
+ * @param {boolean} [updates.sensitive] - New sensitive flag
+ * @returns {Promise<object>} Update result
+ */
+export async function updateTimelineItem(collections, uid, updates) {
+  const { ap_timeline } = collections;
+  return await ap_timeline.updateOne({ uid }, { $set: updates });
+}
+
+/**
+ * Delete timeline items older than a cutoff date (retention cleanup)
+ * @param {object} collections - MongoDB collections
+ * @param {Date} cutoffDate - Delete items published before this date
+ * @returns {Promise<number>} Number of items deleted
+ */
+export async function deleteOldTimelineItems(collections, cutoffDate) {
+  const { ap_timeline } = collections;
+  const result = await ap_timeline.deleteMany({ published: { $lt: cutoffDate } });
+  return result.deletedCount;
+}
+
+/**
+ * Delete timeline items by count-based retention (keep N newest)
+ * @param {object} collections - MongoDB collections
+ * @param {number} keepCount - Number of items to keep
+ * @returns {Promise<number>} Number of items deleted
+ */
+export async function cleanupTimelineByCount(collections, keepCount) {
+  const { ap_timeline } = collections;
+
+  // Find the Nth newest item's published date
+  const items = await ap_timeline
+    .find({})
+    .sort({ published: -1 })
+    .skip(keepCount)
+    .limit(1)
+    .toArray();
+
+  if (items.length === 0) {
+    return 0; // Fewer than keepCount items exist
+  }
+
+  const cutoffDate = items[0].published;
+  return await deleteOldTimelineItems(collections, cutoffDate);
+}

package/lib/timeline-cleanup.js

@@ -0,0 +1,88 @@
+/**
+ * Timeline retention cleanup — removes old timeline items to prevent
+ * unbounded collection growth and cleans up stale interaction tracking.
+ */
+
+/**
+ * Remove timeline items beyond the retention limit and clean up
+ * corresponding ap_interactions entries.
+ *
+ * Uses aggregation to identify exact items to delete by UID,
+ * avoiding race conditions between finding and deleting.
+ *
+ * @param {object} collections - MongoDB collections
+ * @param {number} retentionLimit - Max number of timeline items to keep
+ * @returns {Promise<{removed: number, interactionsRemoved: number}>}
+ */
+export async function cleanupTimeline(collections, retentionLimit) {
+  if (!collections.ap_timeline || retentionLimit <= 0) {
+    return { removed: 0, interactionsRemoved: 0 };
+  }
+
+  const totalCount = await collections.ap_timeline.countDocuments();
+  if (totalCount <= retentionLimit) {
+    return { removed: 0, interactionsRemoved: 0 };
+  }
+
+  // Use aggregation to get exact UIDs beyond the retention limit.
+  // This avoids race conditions: we delete by UID, not by date.
+  const toDelete = await collections.ap_timeline
+    .aggregate([
+      { $sort: { published: -1 } },
+      { $skip: retentionLimit },
+      { $project: { uid: 1 } },
+    ])
+    .toArray();
+
+  if (!toDelete.length) {
+    return { removed: 0, interactionsRemoved: 0 };
+  }
+
+  const removedUids = toDelete.map((item) => item.uid).filter(Boolean);
+
+  // Delete old timeline items by UID
+  const deleteResult = await collections.ap_timeline.deleteMany({
+    _id: { $in: toDelete.map((item) => item._id) },
+  });
+
+  // Clean up stale interactions for removed items
+  let interactionsRemoved = 0;
+  if (removedUids.length > 0 && collections.ap_interactions) {
+    const interactionResult = await collections.ap_interactions.deleteMany({
+      objectUrl: { $in: removedUids },
+    });
+    interactionsRemoved = interactionResult.deletedCount || 0;
+  }
+
+  const removed = deleteResult.deletedCount || 0;
+
+  if (removed > 0) {
+    console.info(
+      `[ActivityPub] Timeline cleanup: removed ${removed} items, ${interactionsRemoved} stale interactions`,
+    );
+  }
+
+  return { removed, interactionsRemoved };
+}
+
+/**
+ * Schedule periodic timeline cleanup.
+ *
+ * @param {object} collections - MongoDB collections
+ * @param {number} retentionLimit - Max number of timeline items to keep
+ * @param {number} intervalMs - Cleanup interval in milliseconds (default: 24 hours)
+ * @returns {NodeJS.Timeout} The interval timer (for cleanup if needed)
+ */
+export function scheduleCleanup(collections, retentionLimit, intervalMs = 86_400_000) {
+  // Run immediately on startup
+  cleanupTimeline(collections, retentionLimit).catch((error) => {
+    console.error("[ActivityPub] Timeline cleanup failed:", error.message);
+  });
+
+  // Then run periodically
+  return setInterval(() => {
+    cleanupTimeline(collections, retentionLimit).catch((error) => {
+      console.error("[ActivityPub] Timeline cleanup failed:", error.message);
+    });
+  }, intervalMs);
+}

package/lib/timeline-store.js

@@ -0,0 +1,207 @@
+/**
+ * Timeline item extraction helpers
+ * @module timeline-store
+ */
+
+import sanitizeHtml from "sanitize-html";
+
+/**
+ * Sanitize HTML content for safe display
+ * @param {string} html - Raw HTML content
+ * @returns {string} Sanitized HTML
+ */
+export function sanitizeContent(html) {
+  if (!html) return "";
+
+  return sanitizeHtml(html, {
+    allowedTags: [
+      "p", "br", "a", "strong", "em", "ul", "ol", "li",
+      "blockquote", "code", "pre", "h1", "h2", "h3", "h4", "h5", "h6",
+      "span", "div", "img"
+    ],
+    allowedAttributes: {
+      a: ["href", "rel", "class"],
+      img: ["src", "alt", "class"],
+      span: ["class"],
+      div: ["class"]
+    },
+    allowedSchemes: ["http", "https", "mailto"],
+    allowedSchemesByTag: {
+      img: ["http", "https", "data"]
+    }
+  });
+}
+
+/**
+ * Extract actor information from Fedify Person/Application/Service object
+ * @param {object} actor - Fedify actor object
+ * @returns {object} { name, url, photo, handle }
+ */
+export async function extractActorInfo(actor) {
+  if (!actor) {
+    return {
+      name: "Unknown",
+      url: "",
+      photo: "",
+      handle: ""
+    };
+  }
+
+  const rawName = actor.name?.toString() || actor.preferredUsername?.toString() || "Unknown";
+  // Strip all HTML from actor names to prevent stored XSS
+  const name = sanitizeHtml(rawName, { allowedTags: [], allowedAttributes: {} });
+  const url = actor.id?.href || "";
+
+  // Extract photo URL from icon (Fedify uses async getters)
+  let photo = "";
+  try {
+    if (typeof actor.getIcon === "function") {
+      const iconObj = await actor.getIcon();
+      photo = iconObj?.url?.href || "";
+    } else {
+      const iconObj = await actor.icon;
+      photo = iconObj?.url?.href || "";
+    }
+  } catch {
+    // No icon available
+  }
+
+  // Extract handle from actor URL
+  let handle = "";
+  try {
+    const actorUrl = new URL(url);
+    const username = actor.preferredUsername?.toString() || "";
+    if (username) {
+      handle = `@${username}@${actorUrl.hostname}`;
+    }
+  } catch {
+    // Invalid URL, keep handle empty
+  }
+
+  return { name, url, photo, handle };
+}
+
+/**
+ * Extract timeline item data from Fedify Note/Article object
+ * @param {object} object - Fedify Note or Article object
+ * @param {object} options - Extraction options
+ * @param {object} [options.boostedBy] - Actor info for boosts
+ * @param {Date} [options.boostedAt] - Boost timestamp
+ * @returns {Promise<object>} Timeline item data
+ */
+export async function extractObjectData(object, options = {}) {
+  if (!object) {
+    throw new Error("Object is required");
+  }
+
+  const uid = object.id?.href || "";
+  const url = object.url?.href || uid;
+
+  // Determine type
+  let type = "note";
+  if (object.type?.toLowerCase() === "article") {
+    type = "article";
+  }
+  if (options.boostedBy) {
+    type = "boost";
+  }
+
+  // Extract content
+  const contentHtml = object.content?.toString() || "";
+  const contentText = object.source?.content?.toString() || contentHtml.replace(/<[^>]*>/g, "");
+
+  const content = {
+    text: contentText,
+    html: sanitizeContent(contentHtml)
+  };
+
+  // Extract name (articles only)
+  const name = type === "article" ? (object.name?.toString() || "") : "";
+
+  // Content warning / summary
+  const summary = object.summary?.toString() || "";
+  const sensitive = object.sensitive || false;
+
+  // Published date — store as ISO string per Indiekit convention
+  const published = object.published
+    ? new Date(object.published).toISOString()
+    : new Date().toISOString();
+
+  // Extract author — use async getAttributedTo() for Fedify objects
+  let authorObj = null;
+  try {
+    if (typeof object.getAttributedTo === "function") {
+      const attr = await object.getAttributedTo();
+      authorObj = Array.isArray(attr) ? attr[0] : attr;
+    }
+  } catch {
+    // Fallback: try direct property access for plain objects
+    authorObj = object.attribution || object.attributedTo || null;
+  }
+  const author = await extractActorInfo(authorObj);
+
+  // Extract tags/categories
+  const category = [];
+  if (object.tag) {
+    const tags = Array.isArray(object.tag) ? object.tag : [object.tag];
+    for (const tag of tags) {
+      if (tag.type === "Hashtag" && tag.name) {
+        category.push(tag.name.toString().replace(/^#/, ""));
+      }
+    }
+  }
+
+  // Extract media attachments
+  const photo = [];
+  const video = [];
+  const audio = [];
+
+  if (object.attachment) {
+    const attachments = Array.isArray(object.attachment) ? object.attachment : [object.attachment];
+    for (const att of attachments) {
+      const mediaUrl = att.url?.href || "";
+      if (!mediaUrl) continue;
+
+      const mediaType = att.mediaType?.toLowerCase() || "";
+
+      if (mediaType.startsWith("image/")) {
+        photo.push(mediaUrl);
+      } else if (mediaType.startsWith("video/")) {
+        video.push(mediaUrl);
+      } else if (mediaType.startsWith("audio/")) {
+        audio.push(mediaUrl);
+      }
+    }
+  }
+
+  // In-reply-to
+  const inReplyTo = object.inReplyTo?.href || "";
+
+  // Build base timeline item
+  const item = {
+    uid,
+    type,
+    url,
+    name,
+    content,
+    summary,
+    sensitive,
+    published,
+    author,
+    category,
+    photo,
+    video,
+    audio,
+    inReplyTo,
+    createdAt: new Date().toISOString()
+  };
+
+  // Add boost metadata if this is a boost
+  if (options.boostedBy) {
+    item.boostedBy = options.boostedBy;
+    item.boostedAt = options.boostedAt || new Date().toISOString();
+    item.originalUrl = url;
+  }
+
+  return item;
+}