@rmdes/indiekit-endpoint-activitypub 2.15.4 → 3.2.0

package/lib/mastodon/helpers/pagination.js

@@ -0,0 +1,130 @@
+/**
+ * Mastodon-compatible cursor pagination helpers.
+ *
+ * Uses MongoDB ObjectId as cursor (chronologically ordered).
+ * Emits RFC 8288 Link headers that masto.js / Phanpy parse.
+ */
+import { ObjectId } from "mongodb";
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 40;
+
+/**
+ * Parse and clamp the limit parameter.
+ *
+ * @param {string|number} raw - Raw limit value from query string
+ * @returns {number}
+ */
+export function parseLimit(raw) {
+  const n = Number.parseInt(String(raw), 10);
+  if (!Number.isFinite(n) || n < 1) return DEFAULT_LIMIT;
+  return Math.min(n, MAX_LIMIT);
+}
+
+/**
+ * Build a MongoDB filter object for cursor-based pagination.
+ *
+ * Mastodon cursor params (all optional, applied to `_id`):
+ *   max_id   — return items older than this ID (exclusive)
+ *   min_id   — return items newer than this ID (exclusive), closest first
+ *   since_id — return items newer than this ID (exclusive), most recent first
+ *
+ * @param {object} baseFilter - Existing MongoDB filter to extend
+ * @param {object} cursors
+ * @param {string} [cursors.max_id]
+ * @param {string} [cursors.min_id]
+ * @param {string} [cursors.since_id]
+ * @returns {{ filter: object, sort: object, reverse: boolean }}
+ */
+export function buildPaginationQuery(baseFilter, { max_id, min_id, since_id } = {}) {
+  const filter = { ...baseFilter };
+  let sort = { _id: -1 }; // newest first (default)
+  let reverse = false;
+
+  if (max_id) {
+    try {
+      filter._id = { ...filter._id, $lt: new ObjectId(max_id) };
+    } catch {
+      // Invalid ObjectId — ignore
+    }
+  }
+
+  if (since_id) {
+    try {
+      filter._id = { ...filter._id, $gt: new ObjectId(since_id) };
+    } catch {
+      // Invalid ObjectId — ignore
+    }
+  }
+
+  if (min_id) {
+    try {
+      filter._id = { ...filter._id, $gt: new ObjectId(min_id) };
+      // min_id returns results closest to the cursor, so sort ascending
+      // then reverse the results before returning
+      sort = { _id: 1 };
+      reverse = true;
+    } catch {
+      // Invalid ObjectId — ignore
+    }
+  }
+
+  return { filter, sort, reverse };
+}
+
+/**
+ * Set the Link pagination header on an Express response.
+ *
+ * @param {object} res - Express response object
+ * @param {object} req - Express request object (for building URLs)
+ * @param {Array} items - Result items (must have `_id` or `id`)
+ * @param {number} limit - The limit used for the query
+ */
+export function setPaginationHeaders(res, req, items, limit) {
+  if (!items?.length) return;
+
+  // Only emit Link if we got a full page (may have more)
+  if (items.length < limit) return;
+
+  const firstId = itemId(items[0]);
+  const lastId = itemId(items[items.length - 1]);
+
+  if (!firstId || !lastId) return;
+
+  const baseUrl = `${req.protocol}://${req.get("host")}${req.path}`;
+
+  // Preserve existing query params (like types[] for notifications)
+  const existingParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(req.query)) {
+    if (key === "max_id" || key === "min_id" || key === "since_id") continue;
+    if (Array.isArray(value)) {
+      for (const v of value) existingParams.append(key, v);
+    } else {
+      existingParams.set(key, String(value));
+    }
+  }
+
+  const links = [];
+
+  // rel="next" — older items (max_id = last item's ID)
+  const nextParams = new URLSearchParams(existingParams);
+  nextParams.set("max_id", lastId);
+  links.push(`<${baseUrl}?${nextParams.toString()}>; rel="next"`);
+
+  // rel="prev" — newer items (min_id = first item's ID)
+  const prevParams = new URLSearchParams(existingParams);
+  prevParams.set("min_id", firstId);
+  links.push(`<${baseUrl}?${prevParams.toString()}>; rel="prev"`);
+
+  res.set("Link", links.join(", "));
+}
+
+/**
+ * Extract the string ID from an item.
+ */
+function itemId(item) {
+  if (!item) return null;
+  if (item._id) return item._id.toString();
+  if (item.id) return String(item.id);
+  return null;
+}

package/lib/mastodon/middleware/cors.js

@@ -0,0 +1,25 @@
+/**
+ * CORS middleware for Mastodon Client API routes.
+ *
+ * Mandatory for browser-based SPA clients like Phanpy that make
+ * cross-origin requests. Without this, the browser's Same-Origin
+ * Policy blocks all API calls.
+ */
+
+const ALLOWED_METHODS = "GET, HEAD, POST, PUT, DELETE, PATCH";
+const ALLOWED_HEADERS = "Authorization, Content-Type, Idempotency-Key";
+const EXPOSED_HEADERS = "Link";
+
+export function corsMiddleware(req, res, next) {
+  res.set("Access-Control-Allow-Origin", "*");
+  res.set("Access-Control-Allow-Methods", ALLOWED_METHODS);
+  res.set("Access-Control-Allow-Headers", ALLOWED_HEADERS);
+  res.set("Access-Control-Expose-Headers", EXPOSED_HEADERS);
+
+  // Handle preflight requests
+  if (req.method === "OPTIONS") {
+    return res.status(204).end();
+  }
+
+  next();
+}

package/lib/mastodon/middleware/error-handler.js

@@ -0,0 +1,37 @@
+/**
+ * Error handling middleware for Mastodon Client API routes.
+ *
+ * Ensures all errors return JSON in Mastodon's expected format
+ * instead of HTML error pages that masto.js cannot parse.
+ *
+ * Standard format: { "error": "description" }
+ * OAuth format:    { "error": "error_type", "error_description": "..." }
+ */
+
+// eslint-disable-next-line no-unused-vars
+export function errorHandler(err, req, res, _next) {
+  const status = err.status || err.statusCode || 500;
+
+  // OAuth errors use RFC 6749 format
+  if (err.oauthError) {
+    return res.status(status).json({
+      error: err.oauthError,
+      error_description: err.message || "An error occurred",
+    });
+  }
+
+  // Standard Mastodon error format
+  res.status(status).json({
+    error: err.message || "An unexpected error occurred",
+  });
+}
+
+/**
+ * 501 catch-all for unimplemented API endpoints.
+ * Must be mounted AFTER all implemented routes.
+ */
+export function notImplementedHandler(req, res) {
+  res.status(501).json({
+    error: "Not implemented",
+  });
+}

package/lib/mastodon/middleware/scope-required.js

@@ -0,0 +1,86 @@
+/**
+ * Scope enforcement middleware for Mastodon Client API.
+ *
+ * Supports scope hierarchy: parent scope covers all children.
+ *   "read" grants "read:accounts", "read:statuses", etc.
+ *   "write" grants "write:statuses", "write:favourites", etc.
+ *
+ * Legacy "follow" scope maps to read/write for blocks, follows, and mutes.
+ */
+
+/**
+ * Scopes that the legacy "follow" scope grants access to.
+ */
+const FOLLOW_SCOPE_EXPANSION = [
+  "read:blocks",
+  "write:blocks",
+  "read:follows",
+  "write:follows",
+  "read:mutes",
+  "write:mutes",
+];
+
+/**
+ * Create middleware that checks if the token has the required scope.
+ *
+ * @param {...string} requiredScopes - One or more scopes (any match = pass)
+ * @returns {Function} Express middleware
+ */
+export function scopeRequired(...requiredScopes) {
+  return (req, res, next) => {
+    const token = req.mastodonToken;
+    if (!token) {
+      return res.status(401).json({
+        error: "The access token is invalid",
+      });
+    }
+
+    const grantedScopes = token.scopes || [];
+
+    const hasScope = requiredScopes.some((required) =>
+      checkScope(grantedScopes, required),
+    );
+
+    if (!hasScope) {
+      return res.status(403).json({
+        error: `This action is outside the authorized scopes. Required: ${requiredScopes.join(" or ")}`,
+      });
+    }
+
+    next();
+  };
+}
+
+/**
+ * Check if granted scopes satisfy a required scope.
+ *
+ * Rules:
+ * - Exact match: "read:accounts" satisfies "read:accounts"
+ * - Parent match: "read" satisfies "read:accounts"
+ * - "follow" expands to read/write for blocks, follows, mutes
+ * - "profile" satisfies "read:accounts" (for verify_credentials)
+ *
+ * @param {string[]} granted - Scopes on the token
+ * @param {string} required - Scope being checked
+ * @returns {boolean}
+ */
+function checkScope(granted, required) {
+  // Exact match
+  if (granted.includes(required)) return true;
+
+  // Parent scope: "read" covers "read:*", "write" covers "write:*"
+  const [parent] = required.split(":");
+  if (parent && granted.includes(parent)) return true;
+
+  // Legacy "follow" scope expansion
+  if (granted.includes("follow") && FOLLOW_SCOPE_EXPANSION.includes(required)) {
+    return true;
+  }
+
+  // "profile" scope can satisfy "read:accounts"
+  if (required === "read:accounts" && granted.includes("profile")) {
+    return true;
+  }
+
+  return false;
+}

package/lib/mastodon/middleware/token-required.js

@@ -0,0 +1,57 @@
+/**
+ * Bearer token validation middleware for Mastodon Client API.
+ *
+ * Extracts the Bearer token from the Authorization header,
+ * validates it against the ap_oauth_tokens collection,
+ * and attaches token data to `req.mastodonToken`.
+ */
+
+/**
+ * Require a valid Bearer token. Returns 401 if invalid/missing.
+ */
+export async function tokenRequired(req, res, next) {
+  const token = await resolveToken(req);
+
+  if (!token) {
+    return res.status(401).json({
+      error: "The access token is invalid",
+    });
+  }
+
+  req.mastodonToken = token;
+  next();
+}
+
+/**
+ * Optional token — sets req.mastodonToken to null if absent.
+ * For public endpoints that personalize when authenticated.
+ */
+export async function optionalToken(req, res, next) {
+  req.mastodonToken = await resolveToken(req);
+  next();
+}
+
+/**
+ * Extract and validate Bearer token from request.
+ * @returns {object|null} Token document or null
+ */
+async function resolveToken(req) {
+  const authHeader = req.get("authorization");
+  if (!authHeader?.startsWith("Bearer ")) return null;
+
+  const accessToken = authHeader.slice(7);
+  if (!accessToken) return null;
+
+  const collections = req.app.locals.mastodonCollections;
+  const token = await collections.ap_oauth_tokens.findOne({
+    accessToken,
+    revokedAt: null,
+  });
+
+  if (!token) return null;
+
+  // Check expiry if set
+  if (token.expiresAt && token.expiresAt < new Date()) return null;
+
+  return token;
+}

package/lib/mastodon/router.js

@@ -0,0 +1,96 @@
+/**
+ * Mastodon Client API — main router.
+ *
+ * Combines all sub-routers, applies CORS and error handling middleware.
+ * Mounted at "/" via Indiekit.addEndpoint() so Mastodon clients can access
+ * /api/v1/*, /api/v2/*, /oauth/* at the domain root.
+ */
+import express from "express";
+import { corsMiddleware } from "./middleware/cors.js";
+import { tokenRequired, optionalToken } from "./middleware/token-required.js";
+import { errorHandler, notImplementedHandler } from "./middleware/error-handler.js";
+
+// Route modules
+import oauthRouter from "./routes/oauth.js";
+import instanceRouter from "./routes/instance.js";
+import accountsRouter from "./routes/accounts.js";
+import statusesRouter from "./routes/statuses.js";
+import timelinesRouter from "./routes/timelines.js";
+import notificationsRouter from "./routes/notifications.js";
+import searchRouter from "./routes/search.js";
+import mediaRouter from "./routes/media.js";
+import stubsRouter from "./routes/stubs.js";
+
+/**
+ * Create the combined Mastodon API router.
+ *
+ * @param {object} options
+ * @param {object} options.collections - MongoDB collections object
+ * @param {object} [options.pluginOptions] - Plugin options (handle, etc.)
+ * @returns {import("express").Router} Express router
+ */
+export function createMastodonRouter({ collections, pluginOptions = {} }) {
+  const router = express.Router(); // eslint-disable-line new-cap
+
+  // ─── Body parsers ───────────────────────────────────────────────────────
+  // Mastodon clients send JSON, form-urlencoded, and occasionally text/plain.
+  // These must be applied before route handlers.
+  router.use("/api", express.json());
+  router.use("/api", express.urlencoded({ extended: true }));
+  router.use("/oauth", express.json());
+  router.use("/oauth", express.urlencoded({ extended: true }));
+
+  // ─── CORS ───────────────────────────────────────────────────────────────
+  router.use("/api", corsMiddleware);
+  router.use("/oauth/token", corsMiddleware);
+  router.use("/oauth/revoke", corsMiddleware);
+  router.use("/.well-known/oauth-authorization-server", corsMiddleware);
+
+  // ─── Inject collections + plugin options into req ───────────────────────
+  router.use("/api", (req, res, next) => {
+    req.app.locals.mastodonCollections = collections;
+    req.app.locals.mastodonPluginOptions = pluginOptions;
+    next();
+  });
+  router.use("/oauth", (req, res, next) => {
+    req.app.locals.mastodonCollections = collections;
+    req.app.locals.mastodonPluginOptions = pluginOptions;
+    next();
+  });
+  router.use("/.well-known/oauth-authorization-server", (req, res, next) => {
+    req.app.locals.mastodonCollections = collections;
+    req.app.locals.mastodonPluginOptions = pluginOptions;
+    next();
+  });
+
+  // ─── Token resolution ───────────────────────────────────────────────────
+  // Apply optional token resolution to all API routes so handlers can check
+  // req.mastodonToken. Specific routes that require auth use tokenRequired.
+  router.use("/api", optionalToken);
+
+  // ─── OAuth routes (no token required for most) ──────────────────────────
+  router.use(oauthRouter);
+
+  // ─── Public API routes (no auth required) ───────────────────────────────
+  router.use(instanceRouter);
+
+  // ─── Authenticated API routes ───────────────────────────────────────────
+  router.use(accountsRouter);
+  router.use(statusesRouter);
+  router.use(timelinesRouter);
+  router.use(notificationsRouter);
+  router.use(searchRouter);
+  router.use(mediaRouter);
+  router.use(stubsRouter);
+
+  // ─── Catch-all for unimplemented endpoints ──────────────────────────────
+  // Express 5 path-to-regexp v8: use {*name} for wildcard
+  router.all("/api/v1/{*rest}", notImplementedHandler);
+  router.all("/api/v2/{*rest}", notImplementedHandler);
+
+  // ─── Error handler ──────────────────────────────────────────────────────
+  router.use("/api", errorHandler);
+  router.use("/oauth", errorHandler);
+
+  return router;
+}