fedipod-bb 0.2.0

package/src/forum-intake.mjs

@@ -0,0 +1,112 @@
+// forum-intake.mjs — the forum's inbox, drained by one loop and handed out by
+// address. Every mechanism of a drain — listing, reading, receipts, dead
+// letters, the commit-before-delete rule — is the Intake's; only handle()
+// differs.
+
+import { Intake } from 'fedipod/core/intake/index.mjs';
+import * as podInbox from 'fedipod/pod/inbox.mjs';
+import * as settings from './settings.mjs';
+
+const idOf = (v) => (typeof v === 'string' ? v : v?.id);
+
+// A vote, as Lemmy federates one: a Like for up, a Dislike for down, and the
+// Undo of either to take it back. Both are ordinary ActivityStreams. Anything
+// else is not a vote.
+export function voteIn(activity) {
+  const t = activity?.type;
+  const inner = activity?.object && typeof activity.object === 'object' ? activity.object : null;
+  if (t === 'Like') return { post: idOf(activity.object), actor: idOf(activity.actor), way: 'up' };
+  if (t === 'Dislike') return { post: idOf(activity.object), actor: idOf(activity.actor), way: 'down' };
+  if (t === 'Undo' && (inner?.type === 'Like' || inner?.type === 'Dislike')) {
+    return { post: idOf(inner.object), actor: idOf(activity.actor), way: 'none' };
+  }
+  return null;
+}
+
+export class ForumIntake extends Intake {
+  constructor(opts, forum) {
+    super(opts);
+    this.forum = forum;
+  }
+
+  async handle(activity, receipt = null) {
+    const vote = voteIn(activity);
+    if (vote) {
+      const done = await this.forum.countVote(vote);
+      if (done) return undefined;
+    }
+    // A moderator ask is the forum's whichever list it names: moderators are
+    // forum-wide. Asked before the categories, or a category took an ask
+    // naming its own list as a roster change and the forum never heard.
+    if ((activity?.type === 'Add' || activity?.type === 'Remove') && settings.isSettingsAsk(this.forum, activity)) {
+      const who = idOf(activity?.actor);
+      if (!(this.forum.config.moderators || []).includes(who)) return 'only a moderator may change this forum';
+      this.queueModeration(activity, who, { trusted: false });
+      return undefined;
+    }
+    const cats = this.forum.route(activity);
+    if (cats.length) {
+      const results = [];
+      for (const cat of cats) results.push(await cat.intake.handle(activity, receipt));
+      // Accepted by any category is accepted; refused by all is the first reason.
+      return results.every(r => r) ? results[0] : undefined;
+    }
+    if (settings.isSettingsAsk(this.forum, activity)) {
+      const who = idOf(activity?.actor);
+      if (!(this.forum.config.moderators || []).includes(who)) return 'only a moderator may change this forum';
+      this.queueModeration(activity, who, { trusted: false });
+      return undefined;
+    }
+    if (this.forum.namesSite(activity)) return super.handle(activity, receipt);
+    return 'names no category of this forum';
+  }
+
+  // One commit boundary for every category too. The base drain holds only
+  // the forum's own store, so a category's topic, index and people documents
+  // went to the pod once per item instead of once per batch.
+  async drain() {
+    for (const cat of this.forum.categories) cat.store.hold?.();
+    try { return await super.drain(); }
+    finally { for (const cat of this.forum.categories) cat.store.release?.(); }
+  }
+
+  // Every category's state has to be on the pod before an item leaves the
+  // inbox, not only the forum's own.
+  async _persisted() {
+    let ok = await this.store.commit();
+    for (const cat of this.forum.categories) ok = (await cat.store.commit()) && ok;
+    return ok;
+  }
+
+  // Categories carry (FEP-1b12); the forum's own inbox forwards nothing.
+  async _maybeForward() {}
+
+  // A receipt beside an item was signed by the door it came through, and each
+  // category's door has its own secret: the receipt is ours if any of them
+  // verifies it.
+  async _readReceipt(itemUrl) {
+    const secrets = [this.config.gateway?.hmacSecret, ...this.forum.categories.map(c => c.config.gateway?.hmacSecret)]
+      .filter(Boolean);
+    if (!secrets.length) return null;
+    try {
+      const { readCapped } = await import('fedipod/shared/safefetch.mjs');
+      const { verifyReceipt } = await import('fedipod/gateway/httpsig.mjs');
+      const receipt = await podInbox.readDeliveryReceipt(this.remote, itemUrl, { maxBytes: 64 * 1024, readCapped });
+      if (!receipt) return null;
+      return secrets.some(s => verifyReceipt(receipt, s)) ? receipt : null;
+    } catch { return null; }
+  }
+
+  gatewaySecret() {
+    return this.config.gateway?.hmacSecret || this.forum.categories.find(c => c.config.gateway?.hmacSecret)?.config.gateway.hmacSecret || null;
+  }
+
+  // The forum owner's own post, taken at an outbox door: written by the
+  // category it addresses.
+  async ownerPostFrom(activity, raw, receipt) {
+    const [cat] = this.forum.route(activity);
+    if (!cat) return 'an owner post names no category';
+    const r = await cat.c2s.dispatch(activity, { raw, slug: receipt?.slug || null });
+    return r.status < 300 ? undefined : `owner post refused (${r.status}: ${r.body?.error || ''})`;
+  }
+}

package/src/index.mjs

@@ -0,0 +1,9 @@
+// index.mjs — what FediPod-BB exports.
+
+export { ROOT, forumUrls, categoryUrls, cacheKey, isSlug, isTid } from './urls.mjs';
+export * as wire from './wire.mjs';
+export * as topics from './topics.mjs';
+export * as publish from './publish.mjs';
+export * as moderation from './moderation.mjs';
+export { provisionForum, provisionCategory } from './provision.mjs';
+export { ForumAgent, ForumIntake } from './forum-agent.mjs';

package/src/moderation.mjs

@@ -0,0 +1,303 @@
+// moderation.mjs — what a moderator does to a topic, and what it says on the
+// wire: a post removed (Delete with the topic as its origin), a topic deleted
+// (Remove from the category, FEP-f15d), a topic moved (Move between
+// categories), a topic pinned (the category's featured collection) or locked
+// (local). Every activity is announced to the category's members the way a
+// group's bans are (FEP-1b12). And the other direction: which arriving
+// activities are a moderator's ask, held for the operator, and how one is
+// applied.
+//
+// A category here is the object the host builds: { urls, store, remote,
+// publisher, deliverer, intake, log }.
+
+import { AS_CTX, LEMMY_CTX, PUBLIC, orderedCollection, updateActorActivity } from 'fedipod/core/wire.mjs';
+import { announceModeration, applyModeration } from 'fedipod/core/social.mjs';
+import * as collection from 'fedipod/pod/collection.mjs';
+import * as podNotes from 'fedipod/pod/notes.mjs';
+import * as topics from './topics.mjs';
+import * as publish from './publish.mjs';
+import { applySettings } from './settings.mjs';
+
+const idOf = (v) => (typeof v === 'string' ? v : v?.id);
+
+// ── on the wire ────────────────────────────────────────────────────────
+export function removeTopicActivity({ urls, topic, serial }) {
+  return { '@context': AS_CTX, id: `${urls.actor}#remove-${serial}`, type: 'Remove', actor: urls.actor,
+    object: topic, target: urls.actor, to: [PUBLIC], cc: [urls.followers] };
+}
+
+export function moveTopicActivity({ urls, topic, origin, target, serial }) {
+  return { '@context': AS_CTX, id: `${urls.actor}#move-${serial}`, type: 'Move', actor: urls.actor,
+    object: topic, origin, target, to: [PUBLIC], cc: [urls.followers] };
+}
+
+// The category is not the post's author; what it deletes is the post's place
+// in the topic, which `origin` names.
+export function deletePostActivity({ urls, post, origin, serial }) {
+  return { '@context': AS_CTX, id: `${urls.actor}#delete-${serial}`, type: 'Delete', actor: urls.actor,
+    object: post, origin, to: [PUBLIC], cc: [urls.followers] };
+}
+
+export function flagActivity({ urls, objects, content, serial }) {
+  return { '@context': AS_CTX, id: `${urls.actor}#flag-${serial}`, type: 'Flag', actor: urls.actor,
+    object: [].concat(objects), ...(content ? { content: String(content).slice(0, 2000) } : {}) };
+}
+
+const tidOf = (cat, id) => {
+  if (typeof id !== 'string' || !id.startsWith(cat.urls.topicContainer)) return null;
+  const tail = id.slice(cat.urls.topicContainer.length);
+  return topics.get(cat.store, tail) ? tail : (topics.get(cat.store, tail.replace(/-\d+$/u, '')) ? tail.replace(/-\d+$/u, '') : null);
+};
+
+// ── the moderator's acts ───────────────────────────────────────────────
+// A post out of its topic: the copy becomes a tombstone, the page it was on
+// goes one short, the carry is unsaid, and members are told.
+export async function removePost(cat, postId, { announce = true } = {}) {
+  const tid = topics.topicOf(cat.store, postId);
+  if (!tid) throw new Error(`no topic holds ${postId}`);
+  const copy = await cat.remote.getJson(cat.urls.cached(postId)).catch(() => null);
+  topics.remove(cat.store, tid, postId);
+  await publish.tombstoneCached(cat, postId, { formerType: copy?.type && copy.type !== 'Tombstone' ? copy.type : 'Note' });
+  await publish.publishTopic(cat, tid);
+  await publish.publishTopicIndex(cat);
+  const s = cat.store.getStatuses().find(x => x.noteId === postId);
+  if (s?.announceActivity) await cat.intake.retract(postId).catch(e => cat.log?.(`retract ${postId}: ${e.message}`));
+  if (announce) {
+    await announceModeration(cat, deletePostActivity({ urls: cat.urls, post: postId, origin: cat.urls.topic(tid), serial: Date.now() }));
+  }
+  return { tid };
+}
+
+// A whole topic: announced first as a Remove of the topic from the category,
+// then each post as above, then the topic's documents become a tombstone.
+export async function deleteTopic(cat, tid) {
+  const doc = topics.get(cat.store, tid);
+  if (!doc) throw new Error(`no such topic: ${tid}`);
+  await announceModeration(cat, removeTopicActivity({ urls: cat.urls, topic: cat.urls.topic(tid), serial: Date.now() }));
+  for (const p of [...doc.posts]) {
+    await publish.tombstoneCached(cat, p.id);
+    const s = cat.store.getStatuses().find(x => x.noteId === p.id);
+    if (s?.announceActivity) await cat.intake.retract(p.id).catch(e => cat.log?.(`retract ${p.id}: ${e.message}`));
+  }
+  await dropTopicDocuments(cat, tid, doc);
+  topics.drop(cat.store, tid);
+  await publish.publishTopicIndex(cat);
+  return { removed: doc.posts.length };
+}
+
+async function dropTopicDocuments(cat, tid, doc) {
+  for (const n of Object.keys(doc.pages || {})) await collection.dropPage(cat.remote, cat.urls.topicPage(tid, Number(n)));
+  await podNotes.writeTombstone(cat.remote, cat.urls.topic(tid),
+    { '@context': AS_CTX, id: cat.urls.topic(tid), type: 'Tombstone', formerType: 'OrderedCollection', deleted: new Date().toISOString() });
+}
+
+// A topic from one category to another: opened afresh there with the same
+// posts and copies, announced as a Move by both, and left as a tombstone here.
+export async function moveTopic(from, to, tid) {
+  const doc = topics.get(from.store, tid);
+  const entry = topics.list(from.store).find(t => t.tid === tid);
+  if (!doc || !entry) throw new Error(`no such topic: ${tid}`);
+  const [first, ...rest] = doc.posts;
+  const newTid = topics.open(to.store, { title: doc.title, post: first, tid: topics.get(to.store, tid) ? null : tid });
+  for (const p of rest) topics.append(to.store, newTid, { ...p, cached: to.urls.cached(p.id) });
+  topics.setFlags(to.store, newTid, { pinned: entry.pinned, locked: entry.locked });
+  const authors = new Set();
+  for (const p of doc.posts) {
+    const copy = await from.remote.getJson(from.urls.cached(p.id)).catch(() => null);
+    if (copy) await podNotes.write(to.remote, to.urls.cached(p.id), copy);
+    if (p.author) authors.add(p.author);
+  }
+  for (const a of authors) {
+    const card = await from.remote.getJson(from.urls.cached(a)).catch(() => null);
+    if (card) await podNotes.write(to.remote, to.urls.cached(a), card);
+  }
+  await publish.publishTopic(to, newTid);
+  await publish.publishTopicIndex(to);
+  const move = { topic: from.urls.topic(tid), origin: from.urls.actor, target: to.urls.actor, serial: Date.now() };
+  await announceModeration(from, moveTopicActivity({ urls: from.urls, ...move }));
+  await announceModeration(to, moveTopicActivity({ urls: to.urls, ...move }));
+  await dropTopicDocuments(from, tid, doc);
+  topics.drop(from.store, tid);
+  await publish.publishTopicIndex(from);
+  return { tid: newTid, topic: to.urls.topic(newTid) };
+}
+
+// Pinned topics are the category's featured collection; members' servers
+// learn of the change through an Update of the category, and Lemmy through
+// an Update of the opening post (below).
+export async function pinTopic(cat, tid, pinned) {
+  if (!topics.get(cat.store, tid)) throw new Error(`no such topic: ${tid}`);
+  topics.setFlags(cat.store, tid, { pinned });
+  const ids = await publish.publishPinnedTopics(cat);
+  const actor = await cat.remote.getJson(cat.urls.actor).catch(() => null);
+  const inboxes = memberInboxes(cat);
+  if (actor && inboxes.length) {
+    await cat.deliverer.deliverToAll(inboxes, updateActorActivity({ urls: cat.urls, actor, serial: Date.now() }));
+  }
+  await announcePageFlags(cat, tid);
+  return { pinned: ids };
+}
+
+const memberInboxes = (cat) => [...new Set(cat.store.getContacts().followers.map(f => f.sharedInbox || f.inbox).filter(Boolean))];
+
+// What Lemmy reads a pin and a lock from: the opening post itself, carrying
+// `stickied` and `commentsEnabled` in Lemmy's terms, sent as an Update from
+// the category — the moderator's edit of a post in its community, which is
+// how a Lemmy community tells its subscribers a post was featured or locked.
+// The copy sent is the forum's cached copy of the post, so the object is the
+// whole post and not a fragment. Mastodon drops an Update from anyone but
+// the author, which is the right answer for it.
+export async function announcePageFlags(cat, tid) {
+  const entry = topics.list(cat.store).find(t => t.tid === tid);
+  const opening = topics.get(cat.store, tid)?.posts?.[0];
+  if (!entry || !opening?.id) return null;
+  const copy = await cat.remote.getJson(cat.urls.cached(opening.id)).catch(() => null);
+  if (!copy?.id) return null;
+  const inboxes = memberInboxes(cat);
+  if (!inboxes.length) return null;
+  const page = { ...copy, '@context': [AS_CTX, LEMMY_CTX], stickied: !!entry.pinned, commentsEnabled: !entry.locked };
+  const activity = {
+    '@context': [AS_CTX, LEMMY_CTX],
+    id: `${cat.urls.actor}#page-${Date.now()}`,
+    type: 'Update', actor: cat.urls.actor, to: [PUBLIC], cc: [cat.urls.followers],
+    object: page,
+  };
+  await cat.deliverer.deliverToAll(inboxes, activity);
+  return activity;
+}
+
+// A topic's name, changed: the record and the published head follow, and
+// nothing about the posts inside it moves.
+export async function renameTopic(cat, tid, name) {
+  if (!topics.get(cat.store, tid)) throw new Error(`no such topic: ${tid}`);
+  const title = String(name).trim().slice(0, 200);
+  if (!title) throw new Error('a topic needs a name');
+  topics.setTitle(cat.store, tid, title);
+  await publish.publishTopic(cat, tid, { force: true });
+  await publish.publishTopicIndex(cat, { force: true });
+  return { tid, name: title };
+}
+
+// Locked: the record says so, and the host places nothing more in it.
+export async function lockTopic(cat, tid, locked) {
+  if (!topics.get(cat.store, tid)) throw new Error(`no such topic: ${tid}`);
+  topics.setFlags(cat.store, tid, { locked });
+  // The topic says so itself, so a reader and any other server can see it:
+  // `closed` is what AS2 gives for a collection that takes no more. Lemmy
+  // reads it off the opening post instead (announcePageFlags).
+  await publish.publishTopic(cat, tid, { force: true });
+  await announcePageFlags(cat, tid);
+  return { locked: !!locked };
+}
+
+export const isLocked = (cat, tid) => !!topics.list(cat.store).find(t => t.tid === tid)?.locked;
+
+// ── the other direction: a moderator's ask, arriving ──────────────────
+// Beyond what every group already holds (Block, Undo, Delete of a carried
+// post, roster changes): a Remove or Move of one of our topics, a Delete
+// naming one of our topics as its origin, and a Flag.
+export function isForumAsk(cat, activity) {
+  const t = activity?.type;
+  if (t === 'Flag') return true;
+  // A held post let through, or turned away: both name a post the forum is
+  // holding rather than one it has carried.
+  if (t === 'Accept' || t === 'Reject') return !!idOf(activity.object);
+  // Somebody let into the category: named by their actor, which is what a
+  // moderator has in front of them.
+  if (t === 'Join') return !!idOf(activity.object);
+  if (t === 'Add' || t === 'Remove' || t === 'Move') return !!tidOf(cat, idOf(activity.object));
+  // A topic renamed, or closed to further replies: the name and the closing
+  // are the topic's own, and only the forum can write them, so a moderator
+  // asks for both the way they ask for anything else.
+  if (t === 'Update') return !!tidOf(cat, idOf(activity.object));
+  if (t === 'Delete') return !!tidOf(cat, idOf(activity.origin));
+  return false;
+}
+
+// Apply one queued ask. `forum` resolves a Move's target to a category.
+export async function applyForumModeration(forum, cat, entry) {
+  const object = idOf(entry.activity?.object);
+  switch (entry.type) {
+    case 'Update': {
+      const tid = tidOf(cat, object);
+      const asked = typeof entry.activity?.object === 'object' ? entry.activity.object : null;
+      if (!tid || !asked) break;
+      // `closed` present and truthy: no more replies are placed in it. The
+      // STRING "false" is false — a boolean that has been through a form, a
+      // template or an RDF round trip arrives as text, and `!!"false"` is true,
+      // which turns every reopen into another close.
+      if ('closed' in asked) {
+        const shut = asked.closed !== false && asked.closed !== 'false' && !!asked.closed;
+        cat.log?.(`topic ${tid}: ${shut ? 'closing' : 'reopening'} (asked closed=${JSON.stringify(asked.closed)})`);
+        return lockTopic(cat, tid, shut);
+      }
+      if (asked.name) return renameTopic(cat, tid, asked.name);
+      break;
+    }
+    // Somebody admitted to a category: their follow is accepted, and for a
+    // private one their pod is granted the reading their membership means.
+    case 'Join': {
+      if (!object) break;
+      // In a private category, membership means reading, and reading is
+      // granted to a WebID. Somebody whose server has none cannot be admitted
+      // at all — admitting them would carry them posts they may not read.
+      const closed = (forum.config?.membersOnly || []).includes(cat.slug);
+      if (closed) {
+        const webid = await forum.webIdOf(object).catch(() => null);
+        if (!webid) throw new Error(`${object} has no WebID this forum can grant reading to`);
+        await applySettings(forum, { type: 'Add', object: webid, target: cat.urls.members });
+      }
+      const { admitRequest } = await import('fedipod/core/social.mjs');
+      await admitRequest(cat, object);
+      return { admitted: object };
+    }
+    // A held post let through: the category carries it after all.
+    case 'Accept': {
+      if (!object) break;
+      await cat.intake.amplify(object, { approved: true });
+      return { approved: object };
+    }
+    // Turned away: nothing is carried and the holding ends.
+    case 'Reject': {
+      if (!object) break;
+      cat.store.write('modqueue.json', cat.store.read('modqueue.json', [])
+        .filter(e => (typeof e.activity?.object === 'string' ? e.activity.object : e.activity?.object?.id) !== object));
+      return { refused: object };
+    }
+    case 'Add': {
+      const tid = tidOf(cat, object);
+      if (!tid) break;
+      const target = idOf(entry.activity?.target);
+      // The forum's own featured collection: pinned for the whole site.
+      if (forum.site?.featured && target === forum.site.featured) return forum.sitePin(object, true);
+      if (target !== cat.urls.featured) break;
+      return pinTopic(cat, tid, true);
+    }
+    case 'Remove': {
+      const tid = tidOf(cat, object);
+      if (!tid) break;
+      // From the featured collection: unpinned. From the category itself:
+      // gone (FEP-f15d).
+      const target = idOf(entry.activity?.target);
+      if (forum.site?.featured && target === forum.site.featured) return forum.sitePin(object, false);
+      if (target === cat.urls.featured) return pinTopic(cat, tid, false);
+      return deleteTopic(cat, tid);
+    }
+    case 'Move': {
+      const tid = tidOf(cat, object);
+      const to = forum.categories.find(c => c.urls.actor === idOf(entry.activity?.target));
+      if (!tid || !to) break;
+      return moveTopic(cat, to, tid);
+    }
+    case 'Delete': {
+      if (object && topics.topicOf(cat.store, object)) return removePost(cat, object);
+      break;
+    }
+    case 'Flag': {
+      cat.store.addNotification({ type: 'flag', actor: entry.moderator, noteId: object || null });
+      return { flagged: object || null };
+    }
+    default:
+  }
+  return applyModeration(cat, entry);
+}

package/src/provision.mjs

@@ -0,0 +1,37 @@
+// provision.mjs — bringing a forum's containers into being with their access
+// rules, the way FediPod provisions an identity: a canary document and the
+// rule as one operation, idempotent, so running it on every start is safe.
+
+import * as containers from 'fedipod/pod/containers.mjs';
+
+// The forum level: the site actor's home and state, owner-only; its notes
+// and media, public.
+export async function provisionForum(remote, site, { moderatorWebIds = [] } = {}) {
+  await containers.provisionPrivate(remote, site);
+  await containers.provisionPublic(remote, site.notes);
+  await containers.provisionPublic(remote, site.media);
+  // What only the moderators may see: reports name people, and held posts
+  // are somebody's words that the forum has not carried. Not public, not
+  // owner-only either — each moderator's WebID may read it.
+  await remote.putJson(site.mod + '.keep', { '@context': 'https://www.w3.org/ns/activitystreams', type: 'Object' }, 'application/activity+json');
+  await remote.setAcl(site.mod, [], { readAgents: moderatorWebIds });
+}
+
+// A category: a group's home and state, owner-only; its public trees, plus
+// the topic container and the cache, public. The topic container's rule is
+// what every topic head and page inherits.
+export async function provisionCategory(remote, cat, { memberWebIds = null } = {}) {
+  await containers.provisionPrivate(remote, cat);
+  for (const base of [cat.notes, cat.media, cat.topicContainer, cat.cache]) {
+    // A members-only category: the same containers, readable by the people
+    // named rather than by the world. The actor itself stays public — a
+    // server that cannot read the actor cannot deliver to the category at
+    // all, and members join from outside.
+    if (memberWebIds) {
+      await remote.putJson(base + '.keep', { '@context': 'https://www.w3.org/ns/activitystreams', type: 'Object' }, 'application/activity+json');
+      await remote.setAcl(base, [], { readAgents: memberWebIds });
+    } else {
+      await containers.provisionPublic(remote, base);
+    }
+  }
+}