@rmdes/indiekit-endpoint-activitypub 3.12.4 → 3.13.0

package/index.js

@@ -131,6 +131,10 @@ import {
   broadcastActorUpdateController,
   lookupObjectController,
 } from "./lib/controllers/federation-mgmt.js";
+import {
+  settingsGetController,
+  settingsPostController,
+} from "./lib/controllers/settings.js";
 
 const defaults = {
   mountPath: "/activitypub",
@@ -206,6 +210,11 @@ export default class ActivityPubEndpoint {
         text: "activitypub.federationMgmt.title",
         requiresDatabase: true,
       },
+      {
+        href: `${this.options.mountPath}/admin/settings`,
+        text: "activitypub.settings.title",
+        requiresDatabase: true,
+      },
     ];
   }
 
@@ -378,6 +387,10 @@ export default class ActivityPubEndpoint {
     router.post("/admin/federation/broadcast-actor", broadcastActorUpdateController(mp, this));
     router.get("/admin/federation/lookup", lookupObjectController(mp, this));
 
+    // Settings
+    router.get("/admin/settings", settingsGetController(mp));
+    router.post("/admin/settings", settingsPostController(mp));
+
     return router;
   }
 
@@ -969,6 +982,9 @@ export default class ActivityPubEndpoint {
     Indiekit.addCollection("ap_filters");
     Indiekit.addCollection("ap_filter_keywords");
 
+    // Plugin settings (single document, admin UI at /admin/settings)
+    Indiekit.addCollection("ap_settings");
+
     // Store collection references (posts resolved lazily)
     const indiekitCollections = Indiekit.collections;
     this._collections = {

package/lib/batch-broadcast.js

@@ -4,9 +4,7 @@
  * @module batch-broadcast
  */
 import { logActivity } from "./activity-log.js";
-
-const BATCH_SIZE = 25;
-const BATCH_DELAY_MS = 5000;
+import { getSettings } from "./settings.js";
 
 /**
  * Broadcast an activity to all followers via batch delivery.
@@ -29,6 +27,10 @@ export async function batchBroadcast({
   label,
   objectUrl,
 }) {
+  const settings = await getSettings(collections);
+  const batchSize = settings.broadcastBatchSize;
+  const batchDelay = settings.broadcastBatchDelay;
+
   const ctx = federation.createContext(new URL(publicationUrl), {
     handle,
     publicationUrl,
@@ -54,11 +56,11 @@ export async function batchBroadcast({
 
   console.info(
     `[ActivityPub] Broadcasting ${label} to ${uniqueRecipients.length} ` +
-      `unique inboxes (${followers.length} followers) in batches of ${BATCH_SIZE}`,
+      `unique inboxes (${followers.length} followers) in batches of ${batchSize}`,
   );
 
-  for (let i = 0; i < uniqueRecipients.length; i += BATCH_SIZE) {
-    const batch = uniqueRecipients.slice(i, i + BATCH_SIZE);
+  for (let i = 0; i < uniqueRecipients.length; i += batchSize) {
+    const batch = uniqueRecipients.slice(i, i + batchSize);
     const recipients = batch.map((f) => ({
       id: new URL(f.actorUrl),
       inboxId: new URL(f.inbox || f.sharedInbox),
@@ -75,12 +77,12 @@ export async function batchBroadcast({
     } catch (error) {
       failed += batch.length;
       console.warn(
-        `[ActivityPub] ${label} batch ${Math.floor(i / BATCH_SIZE) + 1} failed: ${error.message}`,
+        `[ActivityPub] ${label} batch ${Math.floor(i / batchSize) + 1} failed: ${error.message}`,
       );
     }
 
-    if (i + BATCH_SIZE < uniqueRecipients.length) {
-      await new Promise((resolve) => setTimeout(resolve, BATCH_DELAY_MS));
+    if (i + batchSize < uniqueRecipients.length) {
+      await new Promise((resolve) => setTimeout(resolve, batchDelay));
     }
   }
 

package/lib/batch-refollow.js

@@ -16,10 +16,8 @@ import { lookupWithSecurity } from "./lookup-helpers.js";
 import { Follow } from "@fedify/fedify/vocab";
 import { logActivity } from "./activity-log.js";
 import { cacheGet, cacheSet } from "./redis-cache.js";
+import { getSettings } from "./settings.js";
 
-const BATCH_SIZE = 10;
-const DELAY_PER_FOLLOW = 3_000;
-const DELAY_BETWEEN_BATCHES = 30_000;
 const STARTUP_DELAY = 30_000;
 const RETRY_COOLDOWN = 60 * 60 * 1_000; // 1 hour
 const MAX_RETRIES = 3;
@@ -104,7 +102,9 @@ export async function resumeBatchRefollow(options) {
   }
 
   await setJobState("running");
-  _timer = setTimeout(() => processNextBatch(options), DELAY_BETWEEN_BATCHES);
+  const { collections: resumeCollections } = options;
+  const resumeSettings = await getSettings(resumeCollections);
+  _timer = setTimeout(() => processNextBatch(options), resumeSettings.refollowBatchDelay);
   console.info("[ActivityPub] Batch refollow: resumed");
 }
 
@@ -158,9 +158,14 @@ async function processNextBatch(options) {
   const state = await cacheGet(KV_KEY);
   if (state?.status !== "running") return;
 
+  const settings = await getSettings(collections);
+  const batchSize = settings.refollowBatchSize;
+  const delayPerFollow = settings.refollowDelay;
+  const delayBetweenBatches = settings.refollowBatchDelay;
+
   // Claim a batch atomically: set source to "refollow:pending"
   const entries = [];
-  for (let i = 0; i < BATCH_SIZE; i++) {
+  for (let i = 0; i < batchSize; i++) {
     const doc = await collections.ap_following.findOneAndUpdate(
       { source: "import" },
       { $set: { source: "refollow:pending" } },
@@ -172,7 +177,7 @@ async function processNextBatch(options) {
 
   // Also pick up retryable entries (failed but not permanently)
   const retryCutoff = new Date(Date.now() - RETRY_COOLDOWN).toISOString();
-  const retrySlots = BATCH_SIZE - entries.length;
+  const retrySlots = batchSize - entries.length;
   for (let i = 0; i < retrySlots; i++) {
     const doc = await collections.ap_following.findOneAndUpdate(
       {
@@ -211,14 +216,14 @@ async function processNextBatch(options) {
   for (const entry of entries) {
     await processOneFollow(options, entry);
     // Delay between individual follows
-    await sleep(DELAY_PER_FOLLOW);
+    await sleep(delayPerFollow);
   }
 
   // Update job state timestamp
   await setJobState("running");
 
   // Schedule next batch
-  _timer = setTimeout(() => processNextBatch(options), DELAY_BETWEEN_BATCHES);
+  _timer = setTimeout(() => processNextBatch(options), delayBetweenBatches);
 }
 
 /**

package/lib/controllers/settings.js

@@ -0,0 +1,92 @@
+/**
+ * Settings controller — admin page for ActivityPub plugin configuration.
+ *
+ * GET:  loads settings from ap_settings, renders form with defaults
+ * POST: validates, saves settings, redirects with success message
+ */
+import { getSettings, saveSettings, DEFAULTS } from "../settings.js";
+import { getToken, validateToken } from "../csrf.js";
+
+export function settingsGetController(mountPath) {
+  return async (request, response, next) => {
+    try {
+      const { application } = request.app.locals;
+      const settings = await getSettings(application.collections);
+
+      response.render("activitypub-settings", {
+        title: response.locals.__("activitypub.settings.title"),
+        settings,
+        defaults: DEFAULTS,
+        mountPath,
+        saved: request.query.saved === "true",
+        csrfToken: getToken(request.session),
+      });
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+export function settingsPostController(mountPath) {
+  return async (request, response, next) => {
+    try {
+      if (!validateToken(request)) {
+        return response.status(403).render("error", {
+          title: "Error",
+          content: "Invalid CSRF token",
+        });
+      }
+
+      const { application } = request.app.locals;
+      const body = request.body;
+
+      const settings = {
+        // Instance & Client API
+        instanceLanguages: (body.instanceLanguages || "en")
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean),
+        maxCharacters:
+          parseInt(body.maxCharacters, 10) || DEFAULTS.maxCharacters,
+        maxMediaAttachments:
+          parseInt(body.maxMediaAttachments, 10) || DEFAULTS.maxMediaAttachments,
+        defaultVisibility: body.defaultVisibility || DEFAULTS.defaultVisibility,
+        defaultLanguage: (body.defaultLanguage || DEFAULTS.defaultLanguage).trim(),
+
+        // Federation & Delivery
+        timelineRetention: parseInt(body.timelineRetention, 10) || 0,
+        notificationRetentionDays:
+          parseInt(body.notificationRetentionDays, 10) || 0,
+        activityRetentionDays:
+          parseInt(body.activityRetentionDays, 10) || 0,
+        replyChainDepth:
+          parseInt(body.replyChainDepth, 10) || DEFAULTS.replyChainDepth,
+        broadcastBatchSize:
+          parseInt(body.broadcastBatchSize, 10) || DEFAULTS.broadcastBatchSize,
+        broadcastBatchDelay:
+          parseInt(body.broadcastBatchDelay, 10) || DEFAULTS.broadcastBatchDelay,
+        parallelWorkers:
+          parseInt(body.parallelWorkers, 10) || DEFAULTS.parallelWorkers,
+        logLevel: body.logLevel || DEFAULTS.logLevel,
+
+        // Migration
+        refollowBatchSize:
+          parseInt(body.refollowBatchSize, 10) || DEFAULTS.refollowBatchSize,
+        refollowDelay:
+          parseInt(body.refollowDelay, 10) || DEFAULTS.refollowDelay,
+        refollowBatchDelay:
+          parseInt(body.refollowBatchDelay, 10) || DEFAULTS.refollowBatchDelay,
+
+        // Security
+        refreshTokenTtlDays:
+          parseInt(body.refreshTokenTtlDays, 10) || DEFAULTS.refreshTokenTtlDays,
+      };
+
+      await saveSettings(application.collections, settings);
+
+      response.redirect(`${mountPath}/admin/settings?saved=true`);
+    } catch (error) {
+      next(error);
+    }
+  };
+}

package/lib/inbox-handlers.js

@@ -38,6 +38,7 @@ import { addNotification } from "./storage/notifications.js";
 import { addMessage } from "./storage/messages.js";
 import { fetchAndStorePreviews, fetchAndStoreQuote } from "./og-unfurl.js";
 import { getFollowedTags } from "./storage/followed-tags.js";
+import { getSettings } from "./settings.js";
 
 /** @type {string} ActivityStreams Public Collection constant */
 const PUBLIC = "https://www.w3.org/ns/activitystreams#Public";
@@ -760,7 +761,8 @@ export async function handleCreate(item, collections, ctx, handle) {
   // Each ancestor is stored with isContext: true to distinguish from organic timeline items.
   if (inReplyTo) {
     try {
-      await fetchReplyChain(object, collections, authLoader, 5);
+      const settings = await getSettings(collections);
+      await fetchReplyChain(object, collections, authLoader, settings.replyChainDepth);
     } catch (error) {
       // Non-critical — incomplete context is acceptable
       console.warn("[inbox-handlers] Reply chain fetch failed:", error.message);

package/lib/mastodon/helpers/apply-filters.js

@@ -0,0 +1,158 @@
+/**
+ * Keyword filter helpers for Mastodon Client API v2.
+ *
+ * Loads active filters from MongoDB and applies them to serialized
+ * Mastodon Status objects, following the v2 filter spec:
+ * - filterAction "hide"  → status removed from results
+ * - filterAction "warn"  → status kept with `filtered` array attached
+ */
+
+/**
+ * Strip HTML tags from a string for plain-text keyword matching.
+ *
+ * @param {string} html - HTML string
+ * @returns {string} Plain text
+ */
+function stripHtml(html) {
+  if (!html) return "";
+  return html.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Compile a regex from a list of keyword documents.
+ *
+ * Keywords with `wholeWord: true` are wrapped in `\b` word boundaries.
+ * Keywords with `wholeWord: false` are matched as plain substrings.
+ * Returns null if there are no keywords.
+ *
+ * @param {Array<{keyword: string, wholeWord: boolean}>} keywords
+ * @returns {RegExp|null}
+ */
+function compileKeywordRegex(keywords) {
+  if (!keywords || keywords.length === 0) return null;
+
+  const parts = keywords.map((kw) => {
+    const escaped = kw.keyword.replace(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+    return kw.wholeWord ? `\\b${escaped}\\b` : escaped;
+  });
+
+  return new RegExp(parts.join("|"), "i");
+}
+
+/**
+ * Load active filters for a given context from MongoDB.
+ *
+ * Skips expired filters. For each filter, loads its keywords and compiles
+ * a single regex from all of them.
+ *
+ * @param {object} collections - MongoDB collections (must have ap_filters, ap_filter_keywords)
+ * @param {string} context - Filter context to match ("home", "public", "notifications", "thread")
+ * @returns {Promise<Array<{id: string, title: string, context: string[], filterAction: string, expiresAt: string|null, regex: RegExp|null, keywords: Array}>>}
+ */
+export async function loadUserFilters(collections, context) {
+  if (!collections.ap_filters) return [];
+
+  const now = new Date().toISOString();
+
+  // Load filters that include this context, skipping expired ones
+  const filterDocs = await collections.ap_filters
+    .find({ context })
+    .toArray();
+
+  const activeFilters = filterDocs.filter((f) => {
+    if (!f.expiresAt) return true;
+    return f.expiresAt > now;
+  });
+
+  if (activeFilters.length === 0) return [];
+
+  const result = [];
+
+  for (const filter of activeFilters) {
+    const keywords = collections.ap_filter_keywords
+      ? await collections.ap_filter_keywords
+          .find({ filterId: filter._id })
+          .toArray()
+      : [];
+
+    const regex = compileKeywordRegex(keywords);
+
+    result.push({
+      id: filter._id.toString(),
+      title: filter.title || "",
+      context: filter.context || [],
+      filterAction: filter.filterAction || "warn",
+      expiresAt: filter.expiresAt || null,
+      regex,
+      keywords,
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Apply compiled filters to an array of serialized Mastodon statuses.
+ *
+ * - "hide" filters: matching statuses are removed entirely
+ * - "warn" filters: matching statuses get a `filtered` array attached
+ *
+ * @param {Array<object>} statuses - Serialized Mastodon Status objects
+ * @param {Array<object>} filters - Compiled filter objects from loadUserFilters()
+ * @returns {Array<object>} Processed statuses (hide-matched ones removed)
+ */
+export function applyFilters(statuses, filters) {
+  if (!filters || filters.length === 0) return statuses;
+
+  const result = [];
+
+  for (const status of statuses) {
+    const text = stripHtml(status.content || "");
+    let hidden = false;
+
+    for (const filter of filters) {
+      if (!filter.regex) continue;
+
+      const match = text.match(filter.regex);
+      if (!match) continue;
+
+      if (filter.filterAction === "hide") {
+        hidden = true;
+        break;
+      }
+
+      // filterAction === "warn" — attach filtered metadata
+      const matchedKeywords = filter.keywords
+        .filter((kw) => {
+          const escaped = kw.keyword.replace(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+          const kwRegex = new RegExp(
+            kw.wholeWord ? `\\b${escaped}\\b` : escaped,
+            "i",
+          );
+          return kwRegex.test(text);
+        })
+        .map((kw) => kw.keyword);
+
+      if (!status.filtered) {
+        status.filtered = [];
+      }
+
+      status.filtered.push({
+        filter: {
+          id: filter.id,
+          title: filter.title,
+          context: filter.context,
+          filter_action: filter.filterAction,
+          expires_at: filter.expiresAt,
+        },
+        keyword_matches: matchedKeywords,
+      });
+    }
+
+    if (!hidden) {
+      result.push(status);
+    }
+  }
+
+  return result;
+}

package/lib/mastodon/middleware/load-settings.js

@@ -0,0 +1,35 @@
+/**
+ * Settings cache middleware for Mastodon API hot paths.
+ *
+ * Loads settings once per minute (not per request) and attaches
+ * to req.app.locals.apSettings for all downstream handlers.
+ */
+import { getSettings } from "../../settings.js";
+
+let cachedSettings = null;
+let cacheExpiry = 0;
+const CACHE_TTL = 60_000; // 1 minute
+
+export async function loadSettingsMiddleware(req, res, next) {
+  try {
+    const now = Date.now();
+    if (cachedSettings && now < cacheExpiry) {
+      req.app.locals.apSettings = cachedSettings;
+      return next();
+    }
+
+    const collections = req.app.locals.application?.collections;
+    cachedSettings = await getSettings(collections);
+    cacheExpiry = now + CACHE_TTL;
+    req.app.locals.apSettings = cachedSettings;
+    next();
+  } catch {
+    // On error, use defaults
+    if (!cachedSettings) {
+      const { DEFAULTS } = await import("../../settings.js");
+      cachedSettings = { ...DEFAULTS };
+    }
+    req.app.locals.apSettings = cachedSettings;
+    next();
+  }
+}

package/lib/mastodon/router.js

@@ -8,6 +8,7 @@
 import express from "express";
 import rateLimit from "express-rate-limit";
 import { corsMiddleware } from "./middleware/cors.js";
+import { loadSettingsMiddleware } from "./middleware/load-settings.js";
 import { tokenRequired, optionalToken } from "./middleware/token-required.js";
 import { errorHandler, notImplementedHandler } from "./middleware/error-handler.js";
 
@@ -77,6 +78,10 @@ export function createMastodonRouter({ collections, pluginOptions = {} }) {
   // ─── CORS ───────────────────────────────────────────────────────────────
   router.use("/api", corsMiddleware);
   router.use("/oauth/token", corsMiddleware);
+
+  // ─── Settings cache ────────────────────────────────────────────────────
+  // Loads plugin settings once per minute, available as req.app.locals.apSettings
+  router.use("/api", loadSettingsMiddleware);
   router.use("/oauth/revoke", corsMiddleware);
   router.use("/.well-known/oauth-authorization-server", corsMiddleware);
 

package/lib/mastodon/routes/accounts.js

@@ -60,10 +60,11 @@ router.get("/api/v1/accounts/verify_credentials", tokenRequired, scopeRequired("
 // ─── GET /api/v1/preferences ─────────────────────────────────────────────────
 
 router.get("/api/v1/preferences", tokenRequired, scopeRequired("read", "read:accounts"), (req, res) => {
+  const apSettings = req.app.locals.apSettings;
   res.json({
-    "posting:default:visibility": "public",
+    "posting:default:visibility": apSettings?.defaultVisibility || "public",
     "posting:default:sensitive": false,
-    "posting:default:language": "en",
+    "posting:default:language": apSettings?.defaultLanguage || "en",
     "reading:expand:media": "default",
     "reading:expand:spoilers": false,
   });

package/lib/mastodon/routes/instance.js

@@ -17,6 +17,7 @@ router.get("/api/v2/instance", async (req, res, next) => {
     const domain = req.get("host");
     const collections = req.app.locals.mastodonCollections;
     const pluginOptions = req.app.locals.mastodonPluginOptions || {};
+    const apSettings = req.app.locals.apSettings;
 
     const profile = await collections.ap_profile.findOne({});
     const contactAccount = profile
@@ -44,7 +45,7 @@ router.get("/api/v2/instance", async (req, res, next) => {
         versions: {},
       },
       icon: [],
-      languages: ["en"],
+      languages: apSettings?.instanceLanguages || ["en"],
       configuration: {
         urls: {
           streaming: "",
@@ -54,8 +55,8 @@ router.get("/api/v2/instance", async (req, res, next) => {
           max_pinned_statuses: 10,
         },
         statuses: {
-          max_characters: 5000,
-          max_media_attachments: 4,
+          max_characters: apSettings?.maxCharacters || 5000,
+          max_media_attachments: apSettings?.maxMediaAttachments || 4,
           characters_reserved_per_url: 23,
         },
         media_attachments: {
@@ -116,6 +117,7 @@ router.get("/api/v1/instance", async (req, res, next) => {
     const domain = req.get("host");
     const collections = req.app.locals.mastodonCollections;
     const pluginOptions = req.app.locals.mastodonPluginOptions || {};
+    const apSettings = req.app.locals.apSettings;
 
     const profile = await collections.ap_profile.findOne({});
 
@@ -160,14 +162,14 @@ router.get("/api/v1/instance", async (req, res, next) => {
         domain_count: domainCount,
       },
       thumbnail: profile?.icon || null,
-      languages: ["en"],
+      languages: apSettings?.instanceLanguages || ["en"],
       registrations: false,
       approval_required: true,
       invites_enabled: false,
       configuration: {
         statuses: {
-          max_characters: 5000,
-          max_media_attachments: 4,
+          max_characters: apSettings?.maxCharacters || 5000,
+          max_media_attachments: apSettings?.maxMediaAttachments || 4,
           characters_reserved_per_url: 23,
         },
         media_attachments: {

package/lib/mastodon/routes/oauth.js

@@ -502,13 +502,15 @@ router.post("/oauth/token", async (req, res, next) => {
       // Rotate: new access token + new refresh token
       const newAccessToken = randomHex(64);
       const newRefreshToken = randomHex(64);
+      const refreshTtlDaysRotate = req.app.locals.apSettings?.refreshTokenTtlDays || 90;
+      const refreshTtlMsRotate = refreshTtlDaysRotate * 24 * 3600 * 1000;
       await collections.ap_oauth_tokens.updateOne(
         { _id: existing._id },
         {
           $set: {
             accessToken: newAccessToken,
             refreshToken: newRefreshToken,
-            refreshExpiresAt: new Date(Date.now() + 90 * 24 * 3600 * 1000),
+            refreshExpiresAt: new Date(Date.now() + refreshTtlMsRotate),
           },
           $unset: { expiresAt: "" },
         },
@@ -589,8 +591,9 @@ router.post("/oauth/token", async (req, res, next) => {
 
     // Generate access token and refresh token.
     // Access tokens do not expire (matching Mastodon behavior — valid until revoked).
-    // Refresh tokens expire after 90 days as a safety measure.
-    const REFRESH_TOKEN_TTL = 90 * 24 * 3600 * 1000; // 90 days
+    // Refresh tokens expire after a configurable number of days (default 90).
+    const refreshTtlDays = req.app.locals.apSettings?.refreshTokenTtlDays || 90;
+    const REFRESH_TOKEN_TTL = refreshTtlDays * 24 * 3600 * 1000;
     const accessToken = randomHex(64);
     const refreshToken = randomHex(64);
     await collections.ap_oauth_tokens.updateOne(

package/lib/mastodon/routes/timelines.js

@@ -11,6 +11,7 @@ import { buildPaginationQuery, parseLimit, setPaginationHeaders } from "../helpe
 import { resolveReplyIds } from "../helpers/resolve-reply-ids.js";
 import { loadModerationData, applyModerationFilters } from "../../item-processing.js";
 import { enrichAccountStats } from "../helpers/enrich-accounts.js";
+import { loadUserFilters, applyFilters } from "../helpers/apply-filters.js";
 import { tokenRequired } from "../middleware/token-required.js";
 import { scopeRequired } from "../middleware/scope-required.js";
 
@@ -85,10 +86,17 @@ router.get("/api/v1/timelines/home", tokenRequired, scopeRequired("read", "read:
     const pluginOptions = req.app.locals.mastodonPluginOptions || {};
     await enrichAccountStats(statuses, pluginOptions, baseUrl);
 
+    // Apply keyword filters
+    let filteredStatuses = statuses;
+    if (collections.ap_filters) {
+      const filters = await loadUserFilters(collections, "home");
+      filteredStatuses = applyFilters(statuses, filters);
+    }
+
     // Set pagination Link headers
     setPaginationHeaders(res, req, items, limit);
 
-    res.json(statuses);
+    res.json(filteredStatuses);
   } catch (error) {
     next(error);
   }
@@ -102,9 +110,10 @@ router.get("/api/v1/timelines/public", async (req, res, next) => {
     const baseUrl = `${req.protocol}://${req.get("host")}`;
     const limit = parseLimit(req.query.limit);
 
-    // Public timeline: only public visibility, no context items
+    // Public timeline: only public visibility, no context items, no replies
     const baseFilter = {
       isContext: { $ne: true },
+      inReplyTo: { $exists: false },
       visibility: "public",
     };
 
@@ -186,8 +195,15 @@ router.get("/api/v1/timelines/public", async (req, res, next) => {
     const pluginOpts = req.app.locals.mastodonPluginOptions || {};
     await enrichAccountStats(statuses, pluginOpts, baseUrl);
 
+    // Apply keyword filters
+    let filteredStatuses = statuses;
+    if (collections.ap_filters) {
+      const filters = await loadUserFilters(collections, "public");
+      filteredStatuses = applyFilters(statuses, filters);
+    }
+
     setPaginationHeaders(res, req, items, limit);
-    res.json(statuses);
+    res.json(filteredStatuses);
   } catch (error) {
     next(error);
   }
@@ -204,6 +220,7 @@ router.get("/api/v1/timelines/tag/:hashtag", async (req, res, next) => {
 
     const baseFilter = {
       isContext: { $ne: true },
+      inReplyTo: { $exists: false },
       visibility: { $in: ["public", "unlisted"] },
       category: hashtag,
     };
@@ -253,8 +270,15 @@ router.get("/api/v1/timelines/tag/:hashtag", async (req, res, next) => {
     const pluginOpts = req.app.locals.mastodonPluginOptions || {};
     await enrichAccountStats(statuses, pluginOpts, baseUrl);
 
+    // Apply keyword filters
+    let filteredStatuses = statuses;
+    if (collections.ap_filters) {
+      const filters = await loadUserFilters(collections, "public");
+      filteredStatuses = applyFilters(statuses, filters);
+    }
+
     setPaginationHeaders(res, req, items, limit);
-    res.json(statuses);
+    res.json(filteredStatuses);
   } catch (error) {
     next(error);
   }

package/lib/settings.js

@@ -0,0 +1,72 @@
+/**
+ * Plugin settings — stored in ap_settings MongoDB collection.
+ *
+ * getSettings() merges DB values over hardcoded defaults.
+ * Consumers call this once per operation (or use cached middleware for hot paths).
+ */
+
+export const DEFAULTS = {
+  // Instance & Client API
+  instanceLanguages: ["en"],
+  maxCharacters: 5000,
+  maxMediaAttachments: 4,
+  defaultVisibility: "public",
+  defaultLanguage: "en",
+
+  // Federation & Delivery
+  timelineRetention: 1000,
+  notificationRetentionDays: 30,
+  activityRetentionDays: 90,
+  replyChainDepth: 5,
+  broadcastBatchSize: 25,
+  broadcastBatchDelay: 5000,
+  parallelWorkers: 5,
+  logLevel: "warning",
+
+  // Migration
+  refollowBatchSize: 10,
+  refollowDelay: 3000,
+  refollowBatchDelay: 30000,
+
+  // Security
+  refreshTokenTtlDays: 90,
+};
+
+/**
+ * Load settings from MongoDB, merged over defaults.
+ *
+ * @param {Map|object} collections - Indiekit collections map or plain object with ap_settings
+ * @returns {Promise<object>} Settings object with all keys guaranteed present
+ */
+export async function getSettings(collections) {
+  const col = collections?.get
+    ? collections.get("ap_settings")
+    : collections?.ap_settings;
+  if (!col) return { ...DEFAULTS };
+
+  try {
+    const doc = await col.findOne({});
+    return { ...DEFAULTS, ...(doc?.settings || {}) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+/**
+ * Save settings to MongoDB.
+ *
+ * @param {Map|object} collections - Indiekit collections map or plain object
+ * @param {object} settings - Settings object (all keys from DEFAULTS)
+ */
+export async function saveSettings(collections, settings) {
+  const col = collections?.get
+    ? collections.get("ap_settings")
+    : collections?.ap_settings;
+  if (!col) return;
+
+  await col.updateOne(
+    {},
+    { $set: { settings, updatedAt: new Date().toISOString() } },
+    { upsert: true },
+  );
+}

package/locales/en.json

@@ -333,6 +333,9 @@
       "deleteSuccess": "Delete activity sent to followers",
       "deleteButton": "Delete from fediverse"
     },
+    "settings": {
+      "title": "Settings"
+    },
     "federationMgmt": {
       "title": "Federation",
       "collections": "Collection health",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmdes/indiekit-endpoint-activitypub",
-  "version": "3.12.4",
+  "version": "3.13.0",
   "description": "ActivityPub federation endpoint for Indiekit via Fedify. Adds full fediverse support: actor, inbox, outbox, followers, following, syndication, and Mastodon migration.",
   "keywords": [
     "indiekit",

package/views/activitypub-settings.njk

@@ -0,0 +1,187 @@
+{% extends "document.njk" %}
+
+{% from "heading/macro.njk" import heading with context %}
+{% from "input/macro.njk" import input with context %}
+{% from "radios/macro.njk" import radios with context %}
+{% from "button/macro.njk" import button with context %}
+{% from "notification-banner/macro.njk" import notificationBanner with context %}
+
+{% block content %}
+  {% if saved %}
+    {{ notificationBanner({ type: "success", text: "Settings saved." }) }}
+  {% endif %}
+
+  {{ heading({ text: title }) }}
+
+  <form method="POST" action="{{ mountPath }}/admin/settings">
+    <input type="hidden" name="_csrf" value="{{ csrfToken }}">
+
+    {# ─── Instance & Client API ──────────────────────────────────── #}
+    <fieldset class="fieldset">
+      <legend class="fieldset__legend">Instance &amp; Client API</legend>
+      <p class="hint">Settings reported to Mastodon-compatible clients (Phanpy, Elk, Moshidon).</p>
+
+      {{ input({
+        name: "instanceLanguages",
+        label: "Instance languages",
+        hint: "Comma-separated ISO 639-1 codes (e.g. en,fr,de). Default: " + defaults.instanceLanguages | join(","),
+        value: settings.instanceLanguages | join(","),
+        type: "text"
+      }) }}
+
+      {{ input({
+        name: "maxCharacters",
+        label: "Max characters per status",
+        hint: "Character limit shown to clients. Default: " + defaults.maxCharacters,
+        value: settings.maxCharacters,
+        type: "number"
+      }) }}
+
+      {{ input({
+        name: "maxMediaAttachments",
+        label: "Max media attachments",
+        hint: "Per-status media file limit. Default: " + defaults.maxMediaAttachments,
+        value: settings.maxMediaAttachments,
+        type: "number"
+      }) }}
+
+      {{ radios({
+        name: "defaultVisibility",
+        label: "Default post visibility",
+        hint: "Default visibility for new posts. Default: " + defaults.defaultVisibility,
+        items: [
+          { value: "public", text: "Public", checked: settings.defaultVisibility == "public" },
+          { value: "unlisted", text: "Unlisted", checked: settings.defaultVisibility == "unlisted" },
+          { value: "private", text: "Followers only", checked: settings.defaultVisibility == "private" }
+        ]
+      }) }}
+
+      {{ input({
+        name: "defaultLanguage",
+        label: "Default post language",
+        hint: "ISO 639-1 code (e.g. en, fr). Default: " + defaults.defaultLanguage,
+        value: settings.defaultLanguage,
+        type: "text"
+      }) }}
+    </fieldset>
+
+    {# ─── Federation & Delivery ──────────────────────────────────── #}
+    <fieldset class="fieldset">
+      <legend class="fieldset__legend">Federation &amp; Delivery</legend>
+      <p class="hint">Controls how content is stored, retained, and delivered to followers.</p>
+
+      {{ input({
+        name: "timelineRetention",
+        label: "Timeline retention (items)",
+        hint: "Max items in the AP timeline. 0 = unlimited. Default: " + defaults.timelineRetention,
+        value: settings.timelineRetention,
+        type: "number"
+      }) }}
+
+      {{ input({
+        name: "notificationRetentionDays",
+        label: "Notification retention (days)",
+        hint: "Days to keep notifications. 0 = forever. Default: " + defaults.notificationRetentionDays,
+        value: settings.notificationRetentionDays,
+        type: "number"
+      }) }}
+
+      {{ input({
+        name: "activityRetentionDays",
+        label: "Activity log retention (days)",
+        hint: "Days to keep activity log entries. 0 = forever. Default: " + defaults.activityRetentionDays,
+        value: settings.activityRetentionDays,
+        type: "number"
+      }) }}
+
+      {{ input({
+        name: "replyChainDepth",
+        label: "Reply chain depth",
+        hint: "Max parent posts fetched for thread context. Default: " + defaults.replyChainDepth,
+        value: settings.replyChainDepth,
+        type: "number"
+      }) }}
+
+      {{ input({
+        name: "broadcastBatchSize",
+        label: "Broadcast batch size",
+        hint: "Followers per delivery batch. Default: " + defaults.broadcastBatchSize,
+        value: settings.broadcastBatchSize,
+        type: "number"
+      }) }}
+
+      {{ input({
+        name: "broadcastBatchDelay",
+        label: "Broadcast batch delay (ms)",
+        hint: "Delay between delivery batches in milliseconds. Default: " + defaults.broadcastBatchDelay,
+        value: settings.broadcastBatchDelay,
+        type: "number"
+      }) }}
+
+      {{ input({
+        name: "parallelWorkers",
+        label: "Parallel delivery workers",
+        hint: "Redis queue workers. 0 = in-process queue. Default: " + defaults.parallelWorkers,
+        value: settings.parallelWorkers,
+        type: "number"
+      }) }}
+
+      {{ radios({
+        name: "logLevel",
+        label: "Federation log level",
+        hint: "Fedify log verbosity. Default: " + defaults.logLevel,
+        items: [
+          { value: "debug", text: "Debug", checked: settings.logLevel == "debug" },
+          { value: "info", text: "Info", checked: settings.logLevel == "info" },
+          { value: "warning", text: "Warning", checked: settings.logLevel == "warning" },
+          { value: "error", text: "Error", checked: settings.logLevel == "error" }
+        ]
+      }) }}
+    </fieldset>
+
+    {# ─── Migration ──────────────────────────────────────────────── #}
+    <fieldset class="fieldset">
+      <legend class="fieldset__legend">Migration</legend>
+      <p class="hint">Controls the speed of Mastodon account re-follow processing.</p>
+
+      {{ input({
+        name: "refollowBatchSize",
+        label: "Refollow batch size",
+        hint: "Accounts per refollow batch. Default: " + defaults.refollowBatchSize,
+        value: settings.refollowBatchSize,
+        type: "number"
+      }) }}
+
+      {{ input({
+        name: "refollowDelay",
+        label: "Refollow delay per follow (ms)",
+        hint: "Delay between individual follow requests. Default: " + defaults.refollowDelay,
+        value: settings.refollowDelay,
+        type: "number"
+      }) }}
+
+      {{ input({
+        name: "refollowBatchDelay",
+        label: "Refollow batch delay (ms)",
+        hint: "Delay between refollow batches. Default: " + defaults.refollowBatchDelay,
+        value: settings.refollowBatchDelay,
+        type: "number"
+      }) }}
+    </fieldset>
+
+    {# ─── Security ───────────────────────────────────────────────── #}
+    <fieldset class="fieldset">
+      <legend class="fieldset__legend">Security</legend>
+
+      {{ input({
+        name: "refreshTokenTtlDays",
+        label: "Refresh token TTL (days)",
+        hint: "Days before OAuth refresh tokens expire. Access tokens never expire. Default: " + defaults.refreshTokenTtlDays,
+        value: settings.refreshTokenTtlDays,
+        type: "number"
+      }) }}
+    </fieldset>
+
+    {{ button({ text: "Save settings" }) }}
+  </form>
+{% endblock %}