@rmdes/indiekit-endpoint-activitypub 2.15.4 → 3.0.0

package/index.js

@@ -1,6 +1,7 @@
 import express from "express";
 
 import { setupFederation, buildPersonActor } from "./lib/federation-setup.js";
+import { createMastodonRouter } from "./lib/mastodon/router.js";
 import { initRedisCache } from "./lib/redis-cache.js";
 import { lookupWithSecurity } from "./lib/lookup-helpers.js";
 import {
@@ -1137,6 +1138,10 @@ export default class ActivityPubEndpoint {
     Indiekit.addCollection("ap_key_freshness");
     // Async inbox processing queue
     Indiekit.addCollection("ap_inbox_queue");
+    // Mastodon Client API collections
+    Indiekit.addCollection("ap_oauth_apps");
+    Indiekit.addCollection("ap_oauth_tokens");
+    Indiekit.addCollection("ap_markers");
 
     // Store collection references (posts resolved lazily)
     const indiekitCollections = Indiekit.collections;
@@ -1170,6 +1175,10 @@ export default class ActivityPubEndpoint {
       ap_key_freshness: indiekitCollections.get("ap_key_freshness"),
       // Async inbox processing queue
       ap_inbox_queue: indiekitCollections.get("ap_inbox_queue"),
+      // Mastodon Client API collections
+      ap_oauth_apps: indiekitCollections.get("ap_oauth_apps"),
+      ap_oauth_tokens: indiekitCollections.get("ap_oauth_tokens"),
+      ap_markers: indiekitCollections.get("ap_markers"),
       get posts() {
         return indiekitCollections.get("posts");
       },
@@ -1391,6 +1400,24 @@ export default class ActivityPubEndpoint {
         { processedAt: 1 },
         { expireAfterSeconds: 86_400, background: true },
       );
+
+      // Mastodon Client API indexes
+      this._collections.ap_oauth_apps.createIndex(
+        { clientId: 1 },
+        { unique: true, background: true },
+      );
+      this._collections.ap_oauth_tokens.createIndex(
+        { accessToken: 1 },
+        { unique: true, background: true },
+      );
+      this._collections.ap_oauth_tokens.createIndex(
+        { code: 1 },
+        { unique: true, sparse: true, background: true },
+      );
+      this._collections.ap_markers.createIndex(
+        { userId: 1, timeline: 1 },
+        { unique: true, background: true },
+      );
     } catch {
       // Index creation failed — collections not yet available.
       // Indexes already exist from previous startups; non-fatal.
@@ -1457,6 +1484,26 @@ export default class ActivityPubEndpoint {
       routesPublic: this.contentNegotiationRoutes,
     });
 
+    // Mastodon Client API — virtual endpoint at root
+    // Mastodon-compatible clients (Phanpy, Elk, etc.) expect /api/v1/*,
+    // /api/v2/*, /oauth/* at the domain root, not under /activitypub.
+    const pluginRef = this;
+    const mastodonRouter = createMastodonRouter({
+      collections: this._collections,
+      pluginOptions: {
+        handle: this.options.actor?.handle || "user",
+        publicationUrl: this._publicationUrl,
+        federation: this._federation,
+        followActor: (url, info) => pluginRef.followActor(url, info),
+        unfollowActor: (url) => pluginRef.unfollowActor(url),
+      },
+    });
+    Indiekit.addEndpoint({
+      name: "Mastodon Client API",
+      mountPath: "/",
+      routesPublic: mastodonRouter,
+    });
+
     // Register syndicator (appears in post editing UI)
     Indiekit.addSyndicator(this.syndicator);
 

package/lib/mastodon/entities/account.js

@@ -0,0 +1,200 @@
+/**
+ * Account entity serializer for Mastodon Client API.
+ *
+ * Converts local profile (ap_profile) and remote actor objects
+ * (from timeline author, follower/following docs) into the
+ * Mastodon Account JSON shape that masto.js expects.
+ */
+import { accountId } from "../helpers/id-mapping.js";
+import { sanitizeHtml, stripHtml } from "./sanitize.js";
+
+/**
+ * Serialize an actor as a Mastodon Account entity.
+ *
+ * Handles two shapes:
+ * - Local profile: { _id, name, summary, url, icon, image, actorType,
+ *     manuallyApprovesFollowers, attachments, createdAt, ... }
+ * - Remote author (from timeline): { name, url, photo, handle, emojis, bot }
+ * - Follower/following doc: { actorUrl, name, handle, avatar, ... }
+ *
+ * @param {object} actor - Actor document (profile, author, or follower)
+ * @param {object} options
+ * @param {string} options.baseUrl - Server base URL
+ * @param {boolean} [options.isLocal=false] - Whether this is the local user
+ * @param {string} [options.handle] - Local actor handle (for local accounts)
+ * @returns {object} Mastodon Account entity
+ */
+export function serializeAccount(actor, { baseUrl, isLocal = false, handle = "" }) {
+  if (!actor) {
+    return null;
+  }
+
+  const id = accountId(actor, isLocal);
+
+  // Resolve username and acct
+  let username;
+  let acct;
+  if (isLocal) {
+    username = handle || extractUsername(actor.url) || "user";
+    acct = username; // local accounts use bare username
+  } else {
+    // Remote: extract from handle (@user@domain) or URL
+    const remoteHandle = actor.handle || "";
+    if (remoteHandle.startsWith("@")) {
+      username = remoteHandle.split("@")[1] || "";
+      acct = remoteHandle.slice(1); // strip leading @
+    } else if (remoteHandle.includes("@")) {
+      username = remoteHandle.split("@")[0];
+      acct = remoteHandle;
+    } else {
+      username = extractUsername(actor.url || actor.actorUrl) || "unknown";
+      const domain = extractDomain(actor.url || actor.actorUrl);
+      acct = domain ? `${username}@${domain}` : username;
+    }
+  }
+
+  // Resolve display name
+  const displayName = actor.name || actor.displayName || username || "";
+
+  // Resolve URLs for avatar and header
+  const avatarUrl =
+    actor.icon || actor.avatarUrl || actor.photo || actor.avatar || "";
+  const headerUrl = actor.image || actor.bannerUrl || "";
+
+  // Resolve URL
+  const url = actor.url || actor.actorUrl || "";
+
+  // Resolve note/summary
+  const note = actor.summary || "";
+
+  // Bot detection
+  const bot =
+    actor.bot === true ||
+    actor.actorType === "Service" ||
+    actor.actorType === "Application";
+
+  // Profile fields from attachments
+  const fields = (actor.attachments || actor.fields || []).map((f) => ({
+    name: f.name || "",
+    value: sanitizeHtml(f.value || ""),
+    verified_at: null,
+  }));
+
+  // Custom emojis
+  const emojis = (actor.emojis || []).map((e) => ({
+    shortcode: e.shortcode || "",
+    url: e.url || "",
+    static_url: e.url || "",
+    visible_in_picker: true,
+  }));
+
+  return {
+    id,
+    username,
+    acct,
+    url,
+    display_name: displayName,
+    note: sanitizeHtml(note),
+    avatar: avatarUrl || `${baseUrl}/placeholder-avatar.png`,
+    avatar_static: avatarUrl || `${baseUrl}/placeholder-avatar.png`,
+    header: headerUrl || "",
+    header_static: headerUrl || "",
+    locked: actor.manuallyApprovesFollowers || false,
+    fields,
+    emojis,
+    bot,
+    group: actor.actorType === "Group" || false,
+    discoverable: true,
+    noindex: false,
+    created_at: actor.createdAt || new Date().toISOString(),
+    last_status_at: actor.lastStatusAt || null,
+    statuses_count: actor.statusesCount || 0,
+    followers_count: actor.followersCount || 0,
+    following_count: actor.followingCount || 0,
+    moved: actor.movedTo || null,
+    suspended: false,
+    limited: false,
+    memorial: false,
+    roles: [],
+    hide_collections: false,
+  };
+}
+
+/**
+ * Serialize the local profile as a CredentialAccount (includes source + role).
+ *
+ * @param {object} profile - ap_profile document
+ * @param {object} options
+ * @param {string} options.baseUrl - Server base URL
+ * @param {string} options.handle - Local actor handle
+ * @param {object} [options.counts] - { statuses, followers, following }
+ * @returns {object} Mastodon CredentialAccount entity
+ */
+export function serializeCredentialAccount(profile, { baseUrl, handle, counts = {} }) {
+  const account = serializeAccount(profile, {
+    baseUrl,
+    isLocal: true,
+    handle,
+  });
+
+  // Add counts if provided
+  account.statuses_count = counts.statuses || 0;
+  account.followers_count = counts.followers || 0;
+  account.following_count = counts.following || 0;
+
+  // CredentialAccount extensions
+  account.source = {
+    privacy: "public",
+    sensitive: false,
+    language: "",
+    note: stripHtml(profile.summary || ""),
+    fields: (profile.attachments || []).map((f) => ({
+      name: f.name || "",
+      value: f.value || "",
+      verified_at: null,
+    })),
+    follow_requests_count: 0,
+  };
+
+  account.role = {
+    id: "-99",
+    name: "",
+    permissions: "0",
+    color: "",
+    highlighted: false,
+  };
+
+  return account;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Extract username from a URL path.
+ * Handles /@username, /users/username patterns.
+ */
+function extractUsername(url) {
+  if (!url) return "";
+  try {
+    const { pathname } = new URL(url);
+    const atMatch = pathname.match(/\/@([^/]+)/);
+    if (atMatch) return atMatch[1];
+    const usersMatch = pathname.match(/\/users\/([^/]+)/);
+    if (usersMatch) return usersMatch[1];
+    return "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Extract domain from a URL.
+ */
+function extractDomain(url) {
+  if (!url) return "";
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return "";
+  }
+}

package/lib/mastodon/entities/instance.js

@@ -0,0 +1 @@
+// Instance v1/v2 serializer — implemented in Task 8

package/lib/mastodon/entities/media.js

@@ -0,0 +1,38 @@
+/**
+ * MediaAttachment entity serializer for Mastodon Client API.
+ *
+ * Converts stored media metadata to Mastodon MediaAttachment shape.
+ */
+
+/**
+ * Serialize a MediaAttachment entity.
+ *
+ * @param {object} media - Media document from ap_media collection
+ * @returns {object} Mastodon MediaAttachment entity
+ */
+export function serializeMediaAttachment(media) {
+  const type = detectMediaType(media.contentType || media.type || "");
+
+  return {
+    id: media._id ? media._id.toString() : media.id || "",
+    type,
+    url: media.url || "",
+    preview_url: media.thumbnailUrl || media.url || "",
+    remote_url: null,
+    text_url: media.url || "",
+    meta: media.meta || {},
+    description: media.description || media.alt || null,
+    blurhash: media.blurhash || null,
+  };
+}
+
+/**
+ * Map MIME type or simple type string to Mastodon media type.
+ */
+function detectMediaType(contentType) {
+  if (contentType.startsWith("image/") || contentType === "image") return "image";
+  if (contentType.startsWith("video/") || contentType === "video") return "video";
+  if (contentType.startsWith("audio/") || contentType === "audio") return "audio";
+  if (contentType.startsWith("image/gif")) return "gifv";
+  return "unknown";
+}

package/lib/mastodon/entities/notification.js

@@ -0,0 +1,118 @@
+/**
+ * Notification entity serializer for Mastodon Client API.
+ *
+ * Converts ap_notifications documents into the Mastodon Notification JSON shape.
+ *
+ * Internal type -> Mastodon type mapping:
+ *   like    -> favourite
+ *   boost   -> reblog
+ *   follow  -> follow
+ *   reply   -> mention
+ *   mention -> mention
+ *   dm      -> mention (status will have visibility: "direct")
+ */
+import { serializeAccount } from "./account.js";
+import { serializeStatus } from "./status.js";
+
+/**
+ * Map internal notification types to Mastodon API types.
+ */
+const TYPE_MAP = {
+  like: "favourite",
+  boost: "reblog",
+  follow: "follow",
+  follow_request: "follow_request",
+  reply: "mention",
+  mention: "mention",
+  dm: "mention",
+  report: "admin.report",
+};
+
+/**
+ * Serialize a notification document as a Mastodon Notification entity.
+ *
+ * @param {object} notif - ap_notifications document
+ * @param {object} options
+ * @param {string} options.baseUrl - Server base URL
+ * @param {Map<string, object>} [options.statusMap] - Pre-fetched statuses keyed by targetUrl
+ * @param {object} [options.interactionState] - { favouritedIds, rebloggedIds, bookmarkedIds }
+ * @returns {object|null} Mastodon Notification entity
+ */
+export function serializeNotification(notif, { baseUrl, statusMap, interactionState }) {
+  if (!notif) return null;
+
+  const mastodonType = TYPE_MAP[notif.type] || notif.type;
+
+  // Build the actor account from notification fields
+  const account = serializeAccount(
+    {
+      name: notif.actorName,
+      url: notif.actorUrl,
+      photo: notif.actorPhoto,
+      handle: notif.actorHandle,
+    },
+    { baseUrl },
+  );
+
+  // Resolve the associated status (for favourite, reblog, mention types)
+  let status = null;
+  if (notif.targetUrl && statusMap) {
+    const timelineItem = statusMap.get(notif.targetUrl);
+    if (timelineItem) {
+      status = serializeStatus(timelineItem, {
+        baseUrl,
+        favouritedIds: interactionState?.favouritedIds || new Set(),
+        rebloggedIds: interactionState?.rebloggedIds || new Set(),
+        bookmarkedIds: interactionState?.bookmarkedIds || new Set(),
+        pinnedIds: new Set(),
+      });
+    }
+  }
+
+  // For mentions/replies that don't have a matching timeline item,
+  // construct a minimal status from the notification content
+  if (!status && notif.content && (mastodonType === "mention")) {
+    status = {
+      id: notif._id.toString(),
+      created_at: notif.published || notif.createdAt || new Date().toISOString(),
+      in_reply_to_id: null,
+      in_reply_to_account_id: null,
+      sensitive: false,
+      spoiler_text: "",
+      visibility: notif.type === "dm" ? "direct" : "public",
+      language: null,
+      uri: notif.uid || "",
+      url: notif.targetUrl || notif.uid || "",
+      replies_count: 0,
+      reblogs_count: 0,
+      favourites_count: 0,
+      edited_at: null,
+      favourited: false,
+      reblogged: false,
+      muted: false,
+      bookmarked: false,
+      pinned: false,
+      content: notif.content?.html || notif.content?.text || "",
+      filtered: null,
+      reblog: null,
+      application: null,
+      account,
+      media_attachments: [],
+      mentions: [],
+      tags: [],
+      emojis: [],
+      card: null,
+      poll: null,
+    };
+  }
+
+  return {
+    id: notif._id.toString(),
+    type: mastodonType,
+    created_at: notif.published instanceof Date
+      ? notif.published.toISOString()
+      : notif.published || notif.createdAt || new Date().toISOString(),
+    account,
+    status,
+  };
+}

package/lib/mastodon/entities/relationship.js

@@ -0,0 +1,38 @@
+/**
+ * Relationship entity serializer for Mastodon Client API.
+ *
+ * Represents the relationship between the authenticated user
+ * and another account.
+ */
+
+/**
+ * Serialize a Relationship entity.
+ *
+ * @param {string} id - Account ID
+ * @param {object} state - Relationship state
+ * @param {boolean} [state.following=false]
+ * @param {boolean} [state.followed_by=false]
+ * @param {boolean} [state.blocking=false]
+ * @param {boolean} [state.muting=false]
+ * @param {boolean} [state.requested=false]
+ * @returns {object} Mastodon Relationship entity
+ */
+export function serializeRelationship(id, state = {}) {
+  return {
+    id,
+    following: state.following || false,
+    showing_reblogs: state.following || false,
+    notifying: false,
+    languages: [],
+    followed_by: state.followed_by || false,
+    blocking: state.blocking || false,
+    blocked_by: false,
+    muting: state.muting || false,
+    muting_notifications: state.muting || false,
+    requested: state.requested || false,
+    requested_by: false,
+    domain_blocking: false,
+    endorsed: false,
+    note: "",
+  };
+}

package/lib/mastodon/entities/sanitize.js

@@ -0,0 +1,111 @@
+/**
+ * XSS HTML sanitizer for Mastodon Client API responses.
+ *
+ * Strips dangerous HTML while preserving safe markup that
+ * Mastodon clients expect (links, paragraphs, line breaks,
+ * inline formatting, mentions, hashtags).
+ */
+
+/**
+ * Allowed HTML tags in Mastodon API content fields.
+ * Matches what Mastodon itself permits in status content.
+ */
+const ALLOWED_TAGS = new Set([
+  "a",
+  "br",
+  "p",
+  "span",
+  "strong",
+  "em",
+  "b",
+  "i",
+  "u",
+  "s",
+  "del",
+  "pre",
+  "code",
+  "blockquote",
+  "ul",
+  "ol",
+  "li",
+]);
+
+/**
+ * Allowed attributes per tag.
+ */
+const ALLOWED_ATTRS = {
+  a: new Set(["href", "rel", "class", "target"]),
+  span: new Set(["class"]),
+};
+
+/**
+ * Sanitize HTML content for safe inclusion in API responses.
+ *
+ * Strips all tags not in the allowlist and removes disallowed attributes.
+ * This is a lightweight sanitizer — for production, consider a
+ * battle-tested library like DOMPurify or sanitize-html.
+ *
+ * @param {string} html - Raw HTML string
+ * @returns {string} Sanitized HTML
+ */
+export function sanitizeHtml(html) {
+  if (!html || typeof html !== "string") return "";
+
+  return html.replace(/<\/?([a-z][a-z0-9]*)\b[^>]*>/gi, (match, tagName) => {
+    const tag = tagName.toLowerCase();
+
+    // Closing tag
+    if (match.startsWith("</")) {
+      return ALLOWED_TAGS.has(tag) ? `</${tag}>` : "";
+    }
+
+    // Opening tag — check if allowed
+    if (!ALLOWED_TAGS.has(tag)) return "";
+
+    // Self-closing br
+    if (tag === "br") return "<br>";
+
+    // Strip disallowed attributes
+    const allowedAttrs = ALLOWED_ATTRS[tag];
+    if (!allowedAttrs) return `<${tag}>`;
+
+    const attrs = [];
+    const attrRegex = /([a-z][a-z0-9-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+)))?/gi;
+    let attrMatch;
+    while ((attrMatch = attrRegex.exec(match)) !== null) {
+      const attrName = attrMatch[1].toLowerCase();
+      if (attrName === tag) continue; // skip tag name itself
+      const attrValue = attrMatch[2] ?? attrMatch[3] ?? attrMatch[4] ?? "";
+      if (allowedAttrs.has(attrName)) {
+        // Block javascript: URIs in href
+        if (attrName === "href" && /^\s*javascript:/i.test(attrValue)) continue;
+        attrs.push(`${attrName}="${escapeAttr(attrValue)}"`);
+      }
+    }
+
+    return attrs.length > 0 ? `<${tag} ${attrs.join(" ")}>` : `<${tag}>`;
+  });
+}
+
+/**
+ * Escape HTML attribute value.
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeAttr(value) {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Strip all HTML tags, returning plain text.
+ * @param {string} html
+ * @returns {string}
+ */
+export function stripHtml(html) {
+  if (!html || typeof html !== "string") return "";
+  return html.replace(/<[^>]*>/g, "").trim();
+}