@rmdes/indiekit-endpoint-microsub 1.0.0-beta.1

package/lib/webmention/processor.js

@@ -0,0 +1,214 @@
+/**
+ * Webmention processor
+ * @module webmention/processor
+ */
+
+import { getRedisClient, publishEvent } from "../cache/redis.js";
+import { ensureNotificationsChannel } from "../storage/channels.js";
+
+import { verifyWebmention } from "./verifier.js";
+
+/**
+ * Get notifications collection
+ * @param {object} application - Indiekit application
+ * @returns {object} MongoDB collection
+ */
+function getCollection(application) {
+  return application.collections.get("microsub_notifications");
+}
+
+/**
+ * Process a webmention
+ * @param {object} application - Indiekit application
+ * @param {string} source - Source URL
+ * @param {string} target - Target URL
+ * @param {string} [userId] - User ID (for user-specific notifications)
+ * @returns {Promise<object>} Processing result
+ */
+export async function processWebmention(application, source, target, userId) {
+  // Verify the webmention
+  const verification = await verifyWebmention(source, target);
+
+  if (!verification.verified) {
+    console.log(
+      `[Microsub] Webmention verification failed: ${verification.error}`,
+    );
+    return {
+      success: false,
+      error: verification.error,
+    };
+  }
+
+  // Ensure notifications channel exists
+  const channel = await ensureNotificationsChannel(application, userId);
+
+  // Check for existing notification (update if exists)
+  const collection = getCollection(application);
+  const existing = await collection.findOne({
+    source,
+    target,
+    ...(userId && { userId }),
+  });
+
+  const notification = {
+    source,
+    target,
+    userId,
+    channelId: channel._id,
+    type: verification.type,
+    author: verification.author,
+    content: verification.content,
+    url: verification.url,
+    published: verification.published
+      ? new Date(verification.published)
+      : new Date(),
+    verified: true,
+    readBy: [],
+    updatedAt: new Date(),
+  };
+
+  if (existing) {
+    // Update existing notification
+    await collection.updateOne({ _id: existing._id }, { $set: notification });
+    notification._id = existing._id;
+  } else {
+    // Insert new notification
+    notification.createdAt = new Date();
+    await collection.insertOne(notification);
+  }
+
+  // Publish real-time event
+  const redis = getRedisClient(application);
+  if (redis && userId) {
+    await publishEvent(redis, `microsub:user:${userId}`, {
+      type: "new-notification",
+      channelId: channel._id.toString(),
+      notification: transformNotification(notification),
+    });
+  }
+
+  console.log(
+    `[Microsub] Webmention processed: ${verification.type} from ${source}`,
+  );
+
+  return {
+    success: true,
+    type: verification.type,
+    id: notification._id?.toString(),
+  };
+}
+
+/**
+ * Delete a webmention (when source no longer links to target)
+ * @param {object} application - Indiekit application
+ * @param {string} source - Source URL
+ * @param {string} target - Target URL
+ * @returns {Promise<boolean>} Whether deletion was successful
+ */
+export async function deleteWebmention(application, source, target) {
+  const collection = getCollection(application);
+  const result = await collection.deleteOne({ source, target });
+  return result.deletedCount > 0;
+}
+
+/**
+ * Get notifications for a user
+ * @param {object} application - Indiekit application
+ * @param {string} userId - User ID
+ * @param {object} options - Query options
+ * @returns {Promise<Array>} Array of notifications
+ */
+export async function getNotifications(application, userId, options = {}) {
+  const collection = getCollection(application);
+  const { limit = 20, unreadOnly = false } = options;
+
+  const query = { userId };
+  if (unreadOnly) {
+    query.readBy = { $ne: userId };
+  }
+
+  /* eslint-disable unicorn/no-array-callback-reference -- query is MongoDB query object */
+  const notifications = await collection
+    .find(query)
+    .toSorted({ published: -1 })
+    .limit(limit)
+    .toArray();
+  /* eslint-enable unicorn/no-array-callback-reference */
+
+  return notifications.map((n) => transformNotification(n, userId));
+}
+
+/**
+ * Mark notifications as read
+ * @param {object} application - Indiekit application
+ * @param {string} userId - User ID
+ * @param {Array} ids - Notification IDs to mark as read
+ * @returns {Promise<number>} Number of notifications updated
+ */
+export async function markNotificationsRead(application, userId, ids) {
+  const collection = getCollection(application);
+  const { ObjectId } = await import("mongodb");
+
+  const objectIds = ids.map((id) => {
+    try {
+      return new ObjectId(id);
+    } catch {
+      return id;
+    }
+  });
+
+  const result = await collection.updateMany(
+    { _id: { $in: objectIds } },
+    { $addToSet: { readBy: userId } },
+  );
+
+  return result.modifiedCount;
+}
+
+/**
+ * Get unread notification count
+ * @param {object} application - Indiekit application
+ * @param {string} userId - User ID
+ * @returns {Promise<number>} Unread count
+ */
+export async function getUnreadNotificationCount(application, userId) {
+  const collection = getCollection(application);
+  return collection.countDocuments({
+    userId,
+    readBy: { $ne: userId },
+  });
+}
+
+/**
+ * Transform notification to API format
+ * @param {object} notification - Database notification
+ * @param {string} [userId] - User ID for read state
+ * @returns {object} Transformed notification
+ */
+function transformNotification(notification, userId) {
+  return {
+    type: "entry",
+    uid: notification._id?.toString(),
+    url: notification.url || notification.source,
+    published: notification.published?.toISOString(),
+    author: notification.author,
+    content: notification.content,
+    _source: notification.source,
+    _target: notification.target,
+    _type: notification.type, // like, reply, repost, bookmark, mention
+    _is_read: userId ? notification.readBy?.includes(userId) : false,
+  };
+}
+
+/**
+ * Create indexes for notifications
+ * @param {object} application - Indiekit application
+ * @returns {Promise<void>}
+ */
+export async function createNotificationIndexes(application) {
+  const collection = getCollection(application);
+
+  await collection.createIndex({ userId: 1, published: -1 });
+  await collection.createIndex({ source: 1, target: 1 });
+  await collection.createIndex({ userId: 1, readBy: 1 });
+}

package/lib/webmention/receiver.js

@@ -0,0 +1,54 @@
+/**
+ * Webmention receiver
+ * @module webmention/receiver
+ */
+
+import { processWebmention } from "./processor.js";
+
+/**
+ * Receive a webmention
+ * POST /microsub/webmention
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function receive(request, response) {
+  const { source, target } = request.body;
+
+  if (!source || !target) {
+    return response.status(400).json({
+      error: "invalid_request",
+      error_description: "Missing source or target parameter",
+    });
+  }
+
+  // Validate URLs
+  try {
+    new URL(source);
+    new URL(target);
+  } catch {
+    return response.status(400).json({
+      error: "invalid_request",
+      error_description: "Invalid source or target URL",
+    });
+  }
+
+  const { application } = request.app.locals;
+  const userId = request.session?.userId;
+
+  // Return 202 Accepted immediately (processing asynchronously)
+  response.status(202).json({
+    status: "accepted",
+    message: "Webmention queued for processing",
+  });
+
+  // Process webmention in background
+  setImmediate(async () => {
+    try {
+      await processWebmention(application, source, target, userId);
+    } catch (error) {
+      console.error(`[Microsub] Error processing webmention: ${error.message}`);
+    }
+  });
+}
+
+export const webmentionReceiver = { receive };

package/lib/webmention/verifier.js

@@ -0,0 +1,308 @@
+/**
+ * Webmention verification
+ * @module webmention/verifier
+ */
+
+import { mf2 } from "microformats-parser";
+
+/**
+ * Verify a webmention
+ * @param {string} source - Source URL
+ * @param {string} target - Target URL
+ * @returns {Promise<object>} Verification result
+ */
+export async function verifyWebmention(source, target) {
+  try {
+    // Fetch the source URL
+    const response = await fetch(source, {
+      headers: {
+        Accept: "text/html, application/xhtml+xml",
+        "User-Agent": "Indiekit Microsub/1.0 (+https://getindiekit.com)",
+      },
+      redirect: "follow",
+    });
+
+    if (!response.ok) {
+      return {
+        verified: false,
+        error: `Source returned ${response.status}`,
+      };
+    }
+
+    const content = await response.text();
+    const finalUrl = response.url;
+
+    // Check if source links to target
+    if (!containsLink(content, target)) {
+      return {
+        verified: false,
+        error: "Source does not link to target",
+      };
+    }
+
+    // Parse microformats
+    const parsed = mf2(content, { baseUrl: finalUrl });
+    const entry = findEntry(parsed, target);
+
+    if (!entry) {
+      // Still valid, just no h-entry context
+      return {
+        verified: true,
+        type: "mention",
+        author: undefined,
+        content: undefined,
+      };
+    }
+
+    // Determine webmention type
+    const mentionType = detectMentionType(entry, target);
+
+    // Extract author
+    const author = extractAuthor(entry, parsed);
+
+    // Extract content
+    const webmentionContent = extractContent(entry);
+
+    return {
+      verified: true,
+      type: mentionType,
+      author,
+      content: webmentionContent,
+      url: getFirst(entry.properties.url) || source,
+      published: getFirst(entry.properties.published),
+    };
+  } catch (error) {
+    return {
+      verified: false,
+      error: `Verification failed: ${error.message}`,
+    };
+  }
+}
+
+/**
+ * Check if content contains a link to target
+ * @param {string} content - HTML content
+ * @param {string} target - Target URL to find
+ * @returns {boolean} Whether the link exists
+ */
+function containsLink(content, target) {
+  // Normalize target URL for matching
+  const normalizedTarget = target.replace(/\/$/, "");
+
+  // Check for href attribute containing target
+  const hrefPattern = new RegExp(
+    `href=["']${escapeRegex(normalizedTarget)}/?["']`,
+    "i",
+  );
+  if (hrefPattern.test(content)) {
+    return true;
+  }
+
+  // Also check without quotes (some edge cases)
+  return content.includes(target) || content.includes(normalizedTarget);
+}
+
+/**
+ * Find the h-entry that references the target
+ * @param {object} parsed - Parsed microformats
+ * @param {string} target - Target URL
+ * @returns {object|undefined} The h-entry or undefined
+ */
+function findEntry(parsed, target) {
+  const normalizedTarget = target.replace(/\/$/, "");
+
+  for (const item of parsed.items) {
+    // Check if this entry references the target
+    if (
+      item.type?.includes("h-entry") &&
+      entryReferencesTarget(item, normalizedTarget)
+    ) {
+      return item;
+    }
+
+    // Check children
+    if (item.children) {
+      for (const child of item.children) {
+        if (
+          child.type?.includes("h-entry") &&
+          entryReferencesTarget(child, normalizedTarget)
+        ) {
+          return child;
+        }
+      }
+    }
+  }
+
+  // Return first h-entry as fallback
+  for (const item of parsed.items) {
+    if (item.type?.includes("h-entry")) {
+      return item;
+    }
+  }
+
+  return;
+}
+
+/**
+ * Check if an entry references the target URL
+ * @param {object} entry - h-entry object
+ * @param {string} target - Normalized target URL
+ * @returns {boolean} Whether the entry references the target
+ */
+function entryReferencesTarget(entry, target) {
+  const properties = entry.properties || {};
+
+  // Check interaction properties
+  const interactionProperties = [
+    "in-reply-to",
+    "like-of",
+    "repost-of",
+    "bookmark-of",
+  ];
+
+  for (const property of interactionProperties) {
+    const values = properties[property] || [];
+    for (const value of values) {
+      const url =
+        typeof value === "string" ? value : value?.properties?.url?.[0];
+      if (url && normalizeUrl(url) === target) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Detect the type of webmention
+ * @param {object} entry - h-entry object
+ * @param {string} target - Target URL
+ * @returns {string} Mention type
+ */
+function detectMentionType(entry, target) {
+  const properties = entry.properties || {};
+  const normalizedTarget = target.replace(/\/$/, "");
+
+  // Check for specific interaction types
+  if (matchesTarget(properties["like-of"], normalizedTarget)) {
+    return "like";
+  }
+  if (matchesTarget(properties["repost-of"], normalizedTarget)) {
+    return "repost";
+  }
+  if (matchesTarget(properties["bookmark-of"], normalizedTarget)) {
+    return "bookmark";
+  }
+  if (matchesTarget(properties["in-reply-to"], normalizedTarget)) {
+    return "reply";
+  }
+
+  return "mention";
+}
+
+/**
+ * Check if any value in array matches target
+ * @param {Array} values - Array of values
+ * @param {string} target - Target URL to match
+ * @returns {boolean} Whether any value matches
+ */
+function matchesTarget(values, target) {
+  if (!values || values.length === 0) return false;
+
+  for (const value of values) {
+    const url = typeof value === "string" ? value : value?.properties?.url?.[0];
+    if (url && normalizeUrl(url) === target) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Extract author from entry or page
+ * @param {object} entry - h-entry object
+ * @param {object} parsed - Full parsed microformats
+ * @returns {object|undefined} Author object
+ */
+function extractAuthor(entry, parsed) {
+  const author = getFirst(entry.properties?.author);
+
+  if (typeof author === "string") {
+    return { name: author };
+  }
+
+  if (author?.type?.includes("h-card")) {
+    return {
+      type: "card",
+      name: getFirst(author.properties?.name),
+      url: getFirst(author.properties?.url),
+      photo: getFirst(author.properties?.photo),
+    };
+  }
+
+  // Try to find author from page's h-card
+  const hcard = parsed.items.find((item) => item.type?.includes("h-card"));
+  if (hcard) {
+    return {
+      type: "card",
+      name: getFirst(hcard.properties?.name),
+      url: getFirst(hcard.properties?.url),
+      photo: getFirst(hcard.properties?.photo),
+    };
+  }
+
+  return;
+}
+
+/**
+ * Extract content from entry
+ * @param {object} entry - h-entry object
+ * @returns {object|undefined} Content object
+ */
+function extractContent(entry) {
+  const content = getFirst(entry.properties?.content);
+
+  if (!content) {
+    const summary = getFirst(entry.properties?.summary);
+    const name = getFirst(entry.properties?.name);
+    return summary || name ? { text: summary || name } : undefined;
+  }
+
+  if (typeof content === "string") {
+    return { text: content };
+  }
+
+  return {
+    text: content.value,
+    html: content.html,
+  };
+}
+
+/**
+ * Get first item from array
+ * @param {Array|*} value - Value or array
+ * @returns {*} First value
+ */
+function getFirst(value) {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+/**
+ * Normalize URL for comparison
+ * @param {string} url - URL to normalize
+ * @returns {string} Normalized URL
+ */
+function normalizeUrl(url) {
+  return url.replace(/\/$/, "");
+}
+
+/**
+ * Escape special regex characters
+ * @param {string} string - String to escape
+ * @returns {string} Escaped string
+ */
+function escapeRegex(string) {
+  return string.replaceAll(/[$()*+.?[\\\]^{|}]/g, String.raw`\$&`);
+}

package/lib/websub/discovery.js

@@ -0,0 +1,129 @@
+/**
+ * WebSub hub discovery
+ * @module websub/discovery
+ */
+
+/**
+ * Discover WebSub hub from HTTP response headers and content
+ * @param {object} response - Fetch response object
+ * @param {string} content - Response body content
+ * @returns {object|undefined} WebSub info { hub, self }
+ */
+export function discoverWebsub(response, content) {
+  // Try to find hub and self URLs from Link headers first
+  const linkHeader = response.headers.get("link");
+  const fromHeaders = linkHeader ? parseLinkHeader(linkHeader) : {};
+
+  // Fall back to content parsing
+  const fromContent = parseContentForLinks(content);
+
+  const hub = fromHeaders.hub || fromContent.hub;
+  const self = fromHeaders.self || fromContent.self;
+
+  if (hub) {
+    return { hub, self };
+  }
+
+  return;
+}
+
+/**
+ * Parse Link header for hub and self URLs
+ * @param {string} linkHeader - Link header value
+ * @returns {object} { hub, self }
+ */
+function parseLinkHeader(linkHeader) {
+  const result = {};
+  const links = linkHeader.split(",");
+
+  for (const link of links) {
+    const parts = link.trim().split(";");
+    if (parts.length < 2) continue;
+
+    const urlMatch = parts[0].match(/<([^>]+)>/);
+    if (!urlMatch) continue;
+
+    const url = urlMatch[1];
+    const relationship = parts
+      .slice(1)
+      .find((p) => p.trim().startsWith("rel="))
+      ?.match(/rel=["']?([^"'\s;]+)["']?/)?.[1];
+
+    if (relationship === "hub") {
+      result.hub = url;
+    } else if (relationship === "self") {
+      result.self = url;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse content for hub and self URLs (Atom, RSS, HTML)
+ * @param {string} content - Response body
+ * @returns {object} { hub, self }
+ */
+function parseContentForLinks(content) {
+  const result = {};
+
+  // Try HTML <link> elements
+  const htmlHubMatch = content.match(
+    /<link[^>]+rel=["']?hub["']?[^>]+href=["']([^"']+)["']/i,
+  );
+  if (htmlHubMatch) {
+    result.hub = htmlHubMatch[1];
+  }
+
+  const htmlSelfMatch = content.match(
+    /<link[^>]+rel=["']?self["']?[^>]+href=["']([^"']+)["']/i,
+  );
+  if (htmlSelfMatch) {
+    result.self = htmlSelfMatch[1];
+  }
+
+  // Also try the reverse order (href before rel)
+  if (!result.hub) {
+    const htmlHubMatch2 = content.match(
+      /<link[^>]+href=["']([^"']+)["'][^>]+rel=["']?hub["']?/i,
+    );
+    if (htmlHubMatch2) {
+      result.hub = htmlHubMatch2[1];
+    }
+  }
+
+  if (!result.self) {
+    const htmlSelfMatch2 = content.match(
+      /<link[^>]+href=["']([^"']+)["'][^>]+rel=["']?self["']?/i,
+    );
+    if (htmlSelfMatch2) {
+      result.self = htmlSelfMatch2[1];
+    }
+  }
+
+  // Try Atom <link> elements
+  if (!result.hub) {
+    const atomHubMatch = content.match(
+      /<atom:link[^>]+rel=["']?hub["']?[^>]+href=["']([^"']+)["']/i,
+    );
+    if (atomHubMatch) {
+      result.hub = atomHubMatch[1];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Check if a hub URL is valid
+ * @param {string} hubUrl - Hub URL to validate
+ * @returns {boolean} Whether the URL is valid
+ */
+export function isValidHubUrl(hubUrl) {
+  try {
+    const url = new URL(hubUrl);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}