@rmdes/indiekit-endpoint-webmention-io 1.0.0

package/index.js

@@ -0,0 +1,113 @@
+import express from "express";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { dashboardController } from "./lib/controllers/dashboard.js";
+import { blocklistController } from "./lib/controllers/blocklist.js";
+import { syncController } from "./lib/controllers/sync-controller.js";
+import { apiController } from "./lib/controllers/api.js";
+import { startSync, stopSync } from "./lib/sync.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const protectedRouter = express.Router();
+const publicRouter = express.Router();
+
+const defaults = {
+  mountPath: "/webmentions",
+  syncInterval: 900_000, // 15 minutes
+  cacheTtl: 60, // seconds for public API Cache-Control
+};
+
+export default class WebmentionEndpoint {
+  name = "Webmention moderation endpoint";
+
+  constructor(options = {}) {
+    this.options = { ...defaults, ...options };
+    this.mountPath = this.options.mountPath;
+  }
+
+  get localesDirectory() {
+    return path.join(__dirname, "locales");
+  }
+
+  get viewsDirectory() {
+    return path.join(__dirname, "views");
+  }
+
+  get navigationItems() {
+    return {
+      href: this.options.mountPath,
+      text: "webmention-io.title",
+      requiresDatabase: true,
+    };
+  }
+
+  /**
+   * Protected routes (require authentication)
+   * Admin dashboard, moderation, sync controls
+   */
+  get routes() {
+    // Dashboard — paginated webmention list with moderation
+    protectedRouter.get("/", dashboardController.list);
+
+    // Blocklist management page
+    protectedRouter.get("/blocklist", blocklistController.list);
+
+    // Sync controls
+    protectedRouter.post("/sync", syncController.sync);
+    protectedRouter.post("/sync/full", syncController.fullSync);
+
+    // Moderation actions
+    protectedRouter.post("/:wmId/hide", dashboardController.hide);
+    protectedRouter.post("/:wmId/unhide", dashboardController.unhide);
+
+    // Block a domain (hides all mentions + adds to blocklist)
+    protectedRouter.post("/block", dashboardController.blockDomainHandler);
+
+    // Unblock a domain
+    protectedRouter.post(
+      "/blocklist/:domain/delete",
+      blocklistController.unblock,
+    );
+
+    // Privacy removal (permanent delete + block)
+    protectedRouter.post("/privacy-remove", dashboardController.privacyRemove);
+
+    return protectedRouter;
+  }
+
+  /**
+   * Public routes (no authentication required)
+   * JF2 JSON API — drop-in replacement for webmention.io proxy
+   */
+  get routesPublic() {
+    publicRouter.get("/api/mentions", apiController.getMentions);
+
+    return publicRouter;
+  }
+
+  init(Indiekit) {
+    Indiekit.addEndpoint(this);
+
+    // Add MongoDB collections
+    Indiekit.addCollection("webmentions");
+    Indiekit.addCollection("webmentionBlocklist");
+
+    // Store config in application for controller access
+    Indiekit.config.application.webmentionConfig = this.options;
+    Indiekit.config.application.webmentionEndpoint = this.mountPath;
+
+    // Store database getter for controller access
+    Indiekit.config.application.getWebmentionDb = () => Indiekit.database;
+
+    // Start background sync if database is available
+    if (Indiekit.config.application.mongodbUrl) {
+      startSync(Indiekit, this.options);
+    }
+  }
+
+  destroy() {
+    stopSync();
+  }
+}

package/lib/controllers/api.js

@@ -0,0 +1,51 @@
+/**
+ * Public JSON API controller
+ * Drop-in replacement for webmention.io API and the proxy plugin
+ */
+
+import { getWebmentions, documentToJf2 } from "../storage/webmentions.js";
+
+export const apiController = {
+  /**
+   * GET /api/mentions - Public JF2 webmentions API
+   */
+  async getMentions(request, response) {
+    try {
+      const { application } = request.app.locals;
+      const db = application.getWebmentionDb();
+
+      if (!db) {
+        return response.status(503).json({ error: "Database unavailable" });
+      }
+
+      const collection = db.collection("webmentions");
+
+      const target = request.query.target || null;
+      const wmProperty = request.query["wm-property"] || null;
+      const perPage = Math.min(Number(request.query["per-page"]) || 50, 10000);
+      const page = Number(request.query.page) || 0;
+
+      const { items } = await getWebmentions(collection, {
+        target,
+        wmProperty,
+        showHidden: false,
+        page,
+        perPage,
+      });
+
+      const children = items.map(documentToJf2);
+
+      const cacheTtl = application.webmentionConfig?.cacheTtl || 60;
+      response.set("Cache-Control", `public, max-age=${cacheTtl}`);
+
+      response.json({
+        type: "feed",
+        name: "Webmentions",
+        children,
+      });
+    } catch (error) {
+      console.error("[Webmentions] API error:", error);
+      response.status(500).json({ error: "Failed to fetch webmentions" });
+    }
+  },
+};

package/lib/controllers/blocklist.js

@@ -0,0 +1,64 @@
+/**
+ * Blocklist controller
+ */
+
+import { getBlocklist, unblockDomain } from "../storage/blocklist.js";
+import { unhideByDomain } from "../storage/webmentions.js";
+
+export const blocklistController = {
+  /**
+   * GET /blocklist - Blocklist management page
+   */
+  async list(request, response) {
+    const { application } = request.app.locals;
+
+    try {
+      const db = application.getWebmentionDb();
+      let entries = [];
+
+      if (db) {
+        const collection = db.collection("webmentionBlocklist");
+        entries = await getBlocklist(collection);
+      }
+
+      response.render("webmentions-blocklist", {
+        title: response.locals.__("webmention-io.blocklist.title"),
+        entries,
+        wmEndpoint: application.webmentionEndpoint,
+      });
+    } catch (error) {
+      console.error("[Webmentions] Blocklist error:", error);
+      response.status(500).render("error", {
+        title: "Error",
+        message: "Failed to load blocklist",
+        error: error.message,
+      });
+    }
+  },
+
+  /**
+   * POST /blocklist/:domain/delete - Unblock a domain
+   */
+  async unblock(request, response) {
+    const { application } = request.app.locals;
+
+    try {
+      const domain = decodeURIComponent(request.params.domain);
+      const db = application.getWebmentionDb();
+      const blockCollection = db.collection("webmentionBlocklist");
+      const wmCollection = db.collection("webmentions");
+
+      await unblockDomain(blockCollection, domain);
+
+      // Unhide mentions that were hidden by blocklist (not manual or privacy)
+      const unhidden = await unhideByDomain(wmCollection, domain);
+
+      response.redirect(
+        application.webmentionEndpoint + "/blocklist?unblocked=1&unhidden=" + unhidden,
+      );
+    } catch (error) {
+      console.error("[Webmentions] Unblock error:", error);
+      response.redirect(application.webmentionEndpoint + "/blocklist?error=unblock-failed");
+    }
+  },
+};

package/lib/controllers/dashboard.js

@@ -0,0 +1,227 @@
+/**
+ * Dashboard controller
+ * Admin UI for webmention moderation
+ */
+
+import {
+  getWebmentions,
+  getWebmentionCounts,
+  hideWebmention,
+  unhideWebmention,
+  hideByDomain,
+  deleteByDomain,
+} from "../storage/webmentions.js";
+import { blockDomain } from "../storage/blocklist.js";
+import { getSyncState } from "../sync.js";
+import { getMentionType, getMentionTitle, getAuthorName } from "../utils.js";
+
+export const dashboardController = {
+  /**
+   * GET / - Webmentions dashboard
+   */
+  async list(request, response) {
+    const { application } = request.app.locals;
+
+    try {
+      const db = application.getWebmentionDb();
+      if (!db) {
+        return response.render("webmentions", {
+          title: response.locals.__("webmention-io.title"),
+          webmentions: [],
+          counts: { total: 0, hidden: 0, visible: 0 },
+          syncState: getSyncState(),
+          cursor: {},
+          filter: "all",
+          typeFilter: "all",
+          wmEndpoint: application.webmentionEndpoint,
+        });
+      }
+
+      const collection = db.collection("webmentions");
+
+      const page = Number(request.query.page) || 0;
+      const limit = Number(request.query.limit) || 20;
+      const filter = request.query.filter || "all";
+      const typeFilter = request.query.type || "all";
+
+      // Build query options
+      const queryOptions = {
+        page,
+        perPage: limit,
+      };
+
+      if (filter === "hidden") {
+        queryOptions.showHidden = true;
+      } else if (filter === "visible") {
+        queryOptions.showHidden = false;
+      } else {
+        // "all" — show everything
+        queryOptions.showHidden = true;
+      }
+
+      if (typeFilter !== "all") {
+        queryOptions.wmProperty = typeFilter;
+      }
+
+      const { items, total } = await getWebmentions(collection, queryOptions);
+      const counts = await getWebmentionCounts(collection);
+
+      // Transform for the mention() macro
+      const webmentions = items.map((item) => {
+        let html;
+        if (item.contentHtml) {
+          html = item.contentHtml;
+        }
+
+        return {
+          id: item.wmId,
+          "wm-id": item.wmId,
+          "wm-property": item.wmProperty,
+          "wm-target": item.wmTarget,
+          icon: getMentionType(item.wmProperty),
+          locale: application.locale,
+          title: getMentionTitle({ name: item.name, "wm-property": item.wmProperty }),
+          description: html ? { html } : undefined,
+          published: item.published || item.wmReceived,
+          url: item.sourceUrl,
+          user: {
+            avatar: { src: item.authorPhoto },
+            name: item.authorName || getAuthorName({
+              author: { name: item.authorName, url: item.authorUrl },
+              url: item.sourceUrl,
+            }),
+            url: item.authorUrl,
+          },
+          // Moderation metadata
+          hidden: item.hidden,
+          hiddenReason: item.hiddenReason,
+          sourceDomain: item.sourceDomain,
+        };
+      });
+
+      // Pagination cursor
+      const cursor = {
+        next: { href: `?page=${page + 1}&filter=${filter}&type=${typeFilter}` },
+      };
+      if (page > 0) {
+        cursor.previous = { href: `?page=${page - 1}&filter=${filter}&type=${typeFilter}` };
+      }
+
+      response.render("webmentions", {
+        title: response.locals.__("webmention-io.title"),
+        webmentions,
+        counts,
+        syncState: getSyncState(),
+        cursor,
+        filter,
+        typeFilter,
+        wmEndpoint: application.webmentionEndpoint,
+      });
+    } catch (error) {
+      console.error("[Webmentions] Dashboard error:", error);
+      response.status(500).render("error", {
+        title: "Error",
+        message: "Failed to load webmentions",
+        error: error.message,
+      });
+    }
+  },
+
+  /**
+   * POST /:wmId/hide - Hide a webmention
+   */
+  async hide(request, response) {
+    const { application } = request.app.locals;
+
+    try {
+      const wmId = Number.parseInt(request.params.wmId, 10);
+      const db = application.getWebmentionDb();
+      const collection = db.collection("webmentions");
+
+      await hideWebmention(collection, wmId, "manual");
+
+      response.redirect(application.webmentionEndpoint + "?hidden=1");
+    } catch (error) {
+      console.error("[Webmentions] Hide error:", error);
+      response.redirect(application.webmentionEndpoint + "?error=hide-failed");
+    }
+  },
+
+  /**
+   * POST /:wmId/unhide - Restore a webmention
+   */
+  async unhide(request, response) {
+    const { application } = request.app.locals;
+
+    try {
+      const wmId = Number.parseInt(request.params.wmId, 10);
+      const db = application.getWebmentionDb();
+      const collection = db.collection("webmentions");
+
+      await unhideWebmention(collection, wmId);
+
+      response.redirect(application.webmentionEndpoint + "?unhidden=1");
+    } catch (error) {
+      console.error("[Webmentions] Unhide error:", error);
+      response.redirect(application.webmentionEndpoint + "?error=unhide-failed");
+    }
+  },
+
+  /**
+   * POST /block - Block a domain
+   */
+  async blockDomainHandler(request, response) {
+    const { application } = request.app.locals;
+
+    try {
+      const { domain } = request.body;
+      if (!domain) {
+        return response.redirect(application.webmentionEndpoint + "?error=no-domain");
+      }
+
+      const db = application.getWebmentionDb();
+      const wmCollection = db.collection("webmentions");
+      const blockCollection = db.collection("webmentionBlocklist");
+
+      // Hide all existing mentions from this domain
+      const hidden = await hideByDomain(wmCollection, domain, "blocklist");
+
+      // Add to blocklist
+      await blockDomain(blockCollection, domain, "spam", hidden);
+
+      response.redirect(application.webmentionEndpoint + "?blocked=1&domain=" + encodeURIComponent(domain));
+    } catch (error) {
+      console.error("[Webmentions] Block error:", error);
+      response.redirect(application.webmentionEndpoint + "?error=block-failed");
+    }
+  },
+
+  /**
+   * POST /privacy-remove - Privacy removal (delete + block)
+   */
+  async privacyRemove(request, response) {
+    const { application } = request.app.locals;
+
+    try {
+      const { domain } = request.body;
+      if (!domain) {
+        return response.redirect(application.webmentionEndpoint + "/blocklist?error=no-domain");
+      }
+
+      const db = application.getWebmentionDb();
+      const wmCollection = db.collection("webmentions");
+      const blockCollection = db.collection("webmentionBlocklist");
+
+      // Permanently delete all mentions from this domain
+      const deleted = await deleteByDomain(wmCollection, domain);
+
+      // Add to blocklist with privacy reason
+      await blockDomain(blockCollection, domain, "privacy", deleted);
+
+      response.redirect(application.webmentionEndpoint + "/blocklist?removed=1&count=" + deleted);
+    } catch (error) {
+      console.error("[Webmentions] Privacy remove error:", error);
+      response.redirect(application.webmentionEndpoint + "/blocklist?error=remove-failed");
+    }
+  },
+};

package/lib/controllers/sync-controller.js

@@ -0,0 +1,51 @@
+/**
+ * Sync controller - manual sync triggers
+ */
+
+import { runSync, runFullSync } from "../sync.js";
+
+export const syncController = {
+  /**
+   * POST /sync - Trigger incremental sync
+   */
+  async sync(request, response) {
+    const { application } = request.app.locals;
+
+    try {
+      const db = application.getWebmentionDb();
+      const options = application.webmentionConfig || {};
+      const result = await runSync(db, options);
+
+      if (result.error) {
+        response.redirect(application.webmentionEndpoint + "?error=" + encodeURIComponent(result.error));
+      } else {
+        response.redirect(application.webmentionEndpoint + "?synced=1&added=" + result.mentionsAdded);
+      }
+    } catch (error) {
+      console.error("[Webmentions] Manual sync error:", error);
+      response.redirect(application.webmentionEndpoint + "?error=sync-failed");
+    }
+  },
+
+  /**
+   * POST /sync/full - Trigger full re-sync
+   */
+  async fullSync(request, response) {
+    const { application } = request.app.locals;
+
+    try {
+      const db = application.getWebmentionDb();
+      const options = application.webmentionConfig || {};
+      const result = await runFullSync(db, options);
+
+      if (result.error) {
+        response.redirect(application.webmentionEndpoint + "?error=" + encodeURIComponent(result.error));
+      } else {
+        response.redirect(application.webmentionEndpoint + "?synced=1&added=" + result.mentionsAdded);
+      }
+    } catch (error) {
+      console.error("[Webmentions] Full sync error:", error);
+      response.redirect(application.webmentionEndpoint + "?error=sync-failed");
+    }
+  },
+};

package/lib/storage/blocklist.js

@@ -0,0 +1,84 @@
+/**
+ * Webmention blocklist MongoDB storage
+ */
+
+/**
+ * Ensure indexes exist
+ * @param {object} collection - MongoDB collection
+ */
+export async function ensureBlocklistIndexes(collection) {
+  await collection.createIndex({ domain: 1 }, { unique: true });
+}
+
+/**
+ * Add a domain to the blocklist
+ * @param {object} collection - MongoDB collection
+ * @param {string} domain - Domain to block
+ * @param {string} reason - Reason ("spam", "privacy", "manual")
+ * @param {number} mentionsHidden - Count of mentions hidden
+ * @returns {Promise<boolean>} true if inserted, false if already existed
+ */
+export async function blockDomain(collection, domain, reason = "spam", mentionsHidden = 0) {
+  try {
+    await collection.insertOne({
+      domain,
+      reason,
+      blockedAt: new Date(),
+      mentionsHidden,
+    });
+    return true;
+  } catch (error) {
+    // Duplicate key — domain already blocked
+    if (error.code === 11000) {
+      // Update reason and count
+      await collection.updateOne(
+        { domain },
+        {
+          $set: { reason },
+          $inc: { mentionsHidden },
+        },
+      );
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Remove a domain from the blocklist
+ * @param {object} collection - MongoDB collection
+ * @param {string} domain - Domain to unblock
+ */
+export async function unblockDomain(collection, domain) {
+  await collection.deleteOne({ domain });
+}
+
+/**
+ * Get all blocked domains
+ * @param {object} collection - MongoDB collection
+ * @returns {Promise<Array>}
+ */
+export async function getBlocklist(collection) {
+  return collection.find({}).sort({ blockedAt: -1 }).toArray();
+}
+
+/**
+ * Check if a domain is blocked
+ * @param {object} collection - MongoDB collection
+ * @param {string} domain - Domain to check
+ * @returns {Promise<boolean>}
+ */
+export async function isDomainBlocked(collection, domain) {
+  const entry = await collection.findOne({ domain });
+  return !!entry;
+}
+
+/**
+ * Get set of all blocked domains (for efficient sync filtering)
+ * @param {object} collection - MongoDB collection
+ * @returns {Promise<Set<string>>}
+ */
+export async function getBlockedDomainSet(collection) {
+  const entries = await collection.find({}, { projection: { domain: 1 } }).toArray();
+  return new Set(entries.map((e) => e.domain));
+}