@rmdes/indiekit-endpoint-activitypub 1.0.29 → 1.1.2

package/lib/storage/moderation.js

@@ -0,0 +1,180 @@
+/**
+ * Moderation storage operations (mute/block)
+ * @module storage/moderation
+ */
+
+/**
+ * Add a muted URL or keyword
+ * @param {object} collections - MongoDB collections
+ * @param {object} data - Mute data
+ * @param {string} [data.url] - Actor URL to mute (mutually exclusive with keyword)
+ * @param {string} [data.keyword] - Keyword to mute (mutually exclusive with url)
+ * @returns {Promise<object>} Created mute entry
+ */
+export async function addMuted(collections, { url, keyword }) {
+  const { ap_muted } = collections;
+
+  if (!url && !keyword) {
+    throw new Error("Either url or keyword must be provided");
+  }
+
+  if (url && keyword) {
+    throw new Error("Cannot mute both url and keyword in same entry");
+  }
+
+  const entry = {
+    url: url || null,
+    keyword: keyword || null,
+    mutedAt: new Date().toISOString(),
+  };
+
+  // Upsert to avoid duplicates
+  const filter = url ? { url } : { keyword };
+  await ap_muted.updateOne(filter, { $setOnInsert: entry }, { upsert: true });
+
+  return await ap_muted.findOne(filter);
+}
+
+/**
+ * Remove a muted URL or keyword
+ * @param {object} collections - MongoDB collections
+ * @param {object} data - Mute identifier
+ * @param {string} [data.url] - Actor URL to unmute
+ * @param {string} [data.keyword] - Keyword to unmute
+ * @returns {Promise<object>} Delete result
+ */
+export async function removeMuted(collections, { url, keyword }) {
+  const { ap_muted } = collections;
+
+  const filter = {};
+  if (url) {
+    filter.url = url;
+  } else if (keyword) {
+    filter.keyword = keyword;
+  } else {
+    throw new Error("Either url or keyword must be provided");
+  }
+
+  return await ap_muted.deleteOne(filter);
+}
+
+/**
+ * Get all muted URLs
+ * @param {object} collections - MongoDB collections
+ * @returns {Promise<string[]>} Array of muted URLs
+ */
+export async function getMutedUrls(collections) {
+  const { ap_muted } = collections;
+  const entries = await ap_muted.find({ url: { $ne: null } }).toArray();
+  return entries.map((entry) => entry.url);
+}
+
+/**
+ * Get all muted keywords
+ * @param {object} collections - MongoDB collections
+ * @returns {Promise<string[]>} Array of muted keywords
+ */
+export async function getMutedKeywords(collections) {
+  const { ap_muted } = collections;
+  const entries = await ap_muted.find({ keyword: { $ne: null } }).toArray();
+  return entries.map((entry) => entry.keyword);
+}
+
+/**
+ * Check if a URL is muted
+ * @param {object} collections - MongoDB collections
+ * @param {string} url - URL to check
+ * @returns {Promise<boolean>} True if muted
+ */
+export async function isUrlMuted(collections, url) {
+  const { ap_muted } = collections;
+  const entry = await ap_muted.findOne({ url });
+  return !!entry;
+}
+
+/**
+ * Check if content contains muted keywords
+ * @param {object} collections - MongoDB collections
+ * @param {string} content - Content text to check
+ * @returns {Promise<boolean>} True if contains muted keyword
+ */
+export async function containsMutedKeyword(collections, content) {
+  const keywords = await getMutedKeywords(collections);
+  const lowerContent = content.toLowerCase();
+
+  return keywords.some((keyword) => lowerContent.includes(keyword.toLowerCase()));
+}
+
+/**
+ * Add a blocked actor URL
+ * @param {object} collections - MongoDB collections
+ * @param {string} url - Actor URL to block
+ * @returns {Promise<object>} Created block entry
+ */
+export async function addBlocked(collections, url) {
+  const { ap_blocked } = collections;
+
+  const entry = {
+    url,
+    blockedAt: new Date().toISOString(),
+  };
+
+  // Upsert to avoid duplicates
+  await ap_blocked.updateOne({ url }, { $setOnInsert: entry }, { upsert: true });
+
+  return await ap_blocked.findOne({ url });
+}
+
+/**
+ * Remove a blocked actor URL
+ * @param {object} collections - MongoDB collections
+ * @param {string} url - Actor URL to unblock
+ * @returns {Promise<object>} Delete result
+ */
+export async function removeBlocked(collections, url) {
+  const { ap_blocked } = collections;
+  return await ap_blocked.deleteOne({ url });
+}
+
+/**
+ * Get all blocked URLs
+ * @param {object} collections - MongoDB collections
+ * @returns {Promise<string[]>} Array of blocked URLs
+ */
+export async function getBlockedUrls(collections) {
+  const { ap_blocked } = collections;
+  const entries = await ap_blocked.find({}).toArray();
+  return entries.map((entry) => entry.url);
+}
+
+/**
+ * Check if a URL is blocked
+ * @param {object} collections - MongoDB collections
+ * @param {string} url - URL to check
+ * @returns {Promise<boolean>} True if blocked
+ */
+export async function isUrlBlocked(collections, url) {
+  const { ap_blocked } = collections;
+  const entry = await ap_blocked.findOne({ url });
+  return !!entry;
+}
+
+/**
+ * Get list of all muted entries (URLs and keywords)
+ * @param {object} collections - MongoDB collections
+ * @returns {Promise<object[]>} Array of mute entries
+ */
+export async function getAllMuted(collections) {
+  const { ap_muted } = collections;
+  return await ap_muted.find({}).toArray();
+}
+
+/**
+ * Get list of all blocked entries
+ * @param {object} collections - MongoDB collections
+ * @returns {Promise<object[]>} Array of block entries
+ */
+export async function getAllBlocked(collections) {
+  const { ap_blocked } = collections;
+  return await ap_blocked.find({}).toArray();
+}

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);
+}