fedipod-bb 0.2.0 → 0.3.0

package/bin/fedipod-bb.mjs

@@ -20,6 +20,10 @@
 //     per category. Deliveries arrive verified at the front and are written
 //     into the forum's inbox; every actor is republished with its front ids
 //     on the next start.
+//   fedipod-bb keep --home DIR --front https://fedipod.net
+//     Let that Gateway run the forum when nothing else does: the pod's rules
+//     name its keeper from here on, and it places posts as they land. `unkeep`
+//     takes the name out again.
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -102,12 +106,22 @@ if (cmd === 'credential') {
   const r = await agent.attach({ front });
   console.log(`attached at ${r.front}: ${r.handles.map(h => '@' + h).join(', ')} — start the forum to publish its new addresses`);
   process.exit(0);
+} else if (cmd === 'keep' || cmd === 'unkeep') {
+  const front = flag('front');
+  if (!front) { console.error('--front <https://gateway-origin> is required'); process.exit(2); }
+  const agent = new ForumAgent({ home, log });
+  if (!await agent.connect({ act: false })) { console.error('nothing to keep — run init first'); process.exit(1); }
+  const r = await agent.keep({ front, on: cmd === 'keep' });
+  console.log(cmd === 'keep'
+    ? `${front} keeps this forum (${r.handles.map(h => '@' + h).join(', ')}) as ${r.keeper}`
+    : `${front} no longer keeps this forum`);
+  process.exit(0);
 } else if (cmd === 'status') {
   const agent = new ForumAgent({ home, log: () => {} });
   const up = await agent.connect({ act: false });
   console.log(JSON.stringify(up ? agent.status() : { mode: 'unconfigured' }, null, 2));
   process.exit(0);
 } else {
-  console.log('usage: fedipod-bb <credential|init|start|status|attach> --home DIR [--email E --pod URL | --handle H --name N --category slug:Name … --reply-policy open|review | --front URL]');
+  console.log('usage: fedipod-bb <credential|init|start|status|attach|keep|unkeep> --home DIR [--email E --pod URL | --handle H --name N --category slug:Name … --reply-policy open|review | --front URL]');
   process.exit(2);
 }

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "fedipod-bb",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "FediPod-BB: a forum website whose record lives on a Solid pod.",
   "license": "MIT",
   "type": "module",
   "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./gateway": "./src/gateway.mjs",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "fedipod-bb": "bin/fedipod-bb.mjs"
   },
@@ -20,7 +26,7 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "fedipod": "^1.42.0",
+    "fedipod": "^1.43.0",
     "fediverse-session": "^0.2.1"
   }
 }

package/src/forum-agent.mjs

@@ -30,6 +30,8 @@ import * as moderation from './moderation.mjs';
 import * as access from './access.mjs';
 import { provisionForum, provisionCategory } from './provision.mjs';
 import * as settings from './settings.mjs';
+import { keepForum, restateForumRules } from './keep.mjs';
+import * as place from './place.mjs';
 
 import { ForumIntake } from './forum-intake.mjs';
 export { ForumIntake };
@@ -44,13 +46,24 @@ const VIEWER_REFRESH_MS = 5 * 60_000;
 
 export class ForumAgent {
   // `remote` and `storageFor` are injectable so a test can stand a pod in.
-  constructor({ home, log = () => {}, remote = null, storageFor = defaultStorageFor, push = true, pollSeconds = null }) {
+  // A host with no directory of its own — fedipod.net's door or its keeper —
+  // hands in the credential, the lease and its holder id instead of files,
+  // names the keeper the pod's rules must carry, reads keys and never mints
+  // them, and defers every send to the run that follows.
+  constructor({ home = null, log = () => {}, remote = null, storageFor = defaultStorageFor, push = true, pollSeconds = null,
+    credential = null, lease = null, holderId = null, keepers = [], mintKeys = true, defer = false }) {
     this.home = home;
     this.log = log;
     this.remote = remote;
     this.storageFor = storageFor;
     this.push = push;
     this.pollSeconds = pollSeconds;
+    this.credential = credential;
+    this.givenLease = lease;
+    this.holderId = holderId;
+    this.keepers = keepers;
+    this.mintKeys = mintKeys;
+    this.defer = defer;
     this.categories = [];
     this.viewer = true;
   }
@@ -64,6 +77,8 @@ export class ForumAgent {
   // a moderator's ask — until it expired. Which is what a restart to pick up a
   // fix looked like from the outside: the fix changing nothing.
   hostId() {
+    if (this.holderId) return this.holderId;
+    if (!this.home) return null;
     const at = path.join(this.home, 'host-id');
     try { return fs.readFileSync(at, 'utf8').trim() || null; } catch { /* not yet */ }
     try {
@@ -78,10 +93,20 @@ export class ForumAgent {
   }
 
   readCredential() {
+    if (this.credential) return this.credential;
+    if (!this.home) return null;
     try { return JSON.parse(fs.readFileSync(path.join(this.home, 'credential.json'), 'utf8')); }
     catch { return null; }
   }
 
+  // The signing key of one actor, from its pod state. A host that may not
+  // mint — the door, which must never invent an identity's key — refuses a
+  // missing one instead.
+  async keysFor(store, actorId) {
+    if (!this.mintKeys && !store.read('keys.json', null)) throw new Error(`no signing key on the pod for ${actorId}`);
+    return resolveKeys(store, { localDir: null, actorId, log: this.log });
+  }
+
   status() {
     return {
       mode: !this.store ? 'unconfigured' : this.viewer ? 'viewer' : 'active',
@@ -142,10 +167,17 @@ export class ForumAgent {
   }
 
   async attachRemote(cred) {
-    if (this.remote) return;
-    const { RemotePod } = await import('fedipod/remote');
-    this.remote = new RemotePod(cred, { log: this.log, home: this.home });
-    await this.remote.warmup();
+    if (!this.remote) {
+      const { RemotePod } = await import('fedipod/remote');
+      this.remote = new RemotePod(cred, { log: this.log, home: this.home });
+      await this.remote.warmup();
+    }
+    // Every rule this host writes names the keeper beside the owner, and the
+    // owner is the forum's, whoever holds the pen.
+    if (this.keepers.length) {
+      this.remote.keepers = [...this.keepers];
+      this.remote.aclOwner = cred.webId || this.remote.aclOwner || null;
+    }
   }
 
   async connect({ act = true } = {}) {
@@ -162,7 +194,7 @@ export class ForumAgent {
     if (!this.config) { this.log('credential present but the forum has no config — run init'); return false; }
     const front = this.config.gateway?.front || null;
     this.site = forumUrls(cred.remotePod, cred.root || ROOT, front ? { front, handle: this.config.handle } : {});
-    this.lease = new Lease({ url: this.site.state + 'lease.json', fetchImpl: (u, i) => this.remote.fetch(u, i), log: this.log,
+    this.lease = this.givenLease || new Lease({ url: this.site.state + 'lease.json', fetchImpl: (u, i) => this.remote.fetch(u, i), log: this.log,
       id: this.hostId() });
     this.viewer = act ? !(await this.lease.acquire()) : true;
     this.categories = [];
@@ -225,11 +257,11 @@ export class ForumAgent {
       } } : {}),
     };
     store.setConfig(config);
-    const keys = await resolveKeys(store, { localDir: null, actorId: urls.actor, log: this.log });
+    const keys = await this.keysFor(store, urls.actor);
     const cat = { slug, urls, store, config, remote: this.remote };
     cat.deliverer = new Deliverer({
       store, rsaPrivate: keys.rsaPrivate, keyId: urls.actor + '#main-key', actorId: urls.actor,
-      edPrivate: keys.edPrivate, proofKeyId: assertionKeyId(urls), log: this.log, passive: true,
+      edPrivate: keys.edPrivate, proofKeyId: assertionKeyId(urls), log: this.log, passive: true, defer: this.defer,
       onGone: () => cat.publisher.publishCollections({ followers: true }),
     });
     cat.publisher = new Publisher({
@@ -254,7 +286,7 @@ export class ForumAgent {
       if (doc || !(this.config.membersOnly || []).includes(slug)) return doc;
       return this.podFetchAP(url);
     };
-    cat.intake.onCarried = (ev) => this.onCarried(cat, ev);
+    cat.intake.onCarry = (ev) => this.onCarry(cat, ev);
     cat.intake.onReport = (activity, actor, opts) => cat.intake.queueModeration(activity, actor, opts);
     // What happens to a post from somebody who has not joined: dropped, or
     // held where a moderator will see it (the category's `replyPolicy`).
@@ -298,11 +330,11 @@ export class ForumAgent {
         mode: gw.mode || 'trust', hmacSecret: gw.secrets?.[this.config.handle] || null,
       } } : {}),
     };
-    const keys = await resolveKeys(store, { localDir: null, actorId: site.actor, log: this.log });
+    const keys = await this.keysFor(store, site.actor);
     const agent = { urls: site, store, config, remote: this.remote, log: this.log, configured: () => true };
     agent.deliverer = new Deliverer({
       store, rsaPrivate: keys.rsaPrivate, keyId: site.actor + '#main-key', actorId: site.actor,
-      edPrivate: keys.edPrivate, proofKeyId: assertionKeyId(site), log: this.log, passive: true,
+      edPrivate: keys.edPrivate, proofKeyId: assertionKeyId(site), log: this.log, passive: true, defer: this.defer,
     });
     agent.publisher = new Publisher({
       config, remote: this.remote, store, deliverer: agent.deliverer,
@@ -349,40 +381,27 @@ export class ForumAgent {
     return ids.some(id => id === s.actor || id === s.followers);
   }
 
-  // After a category carried a post: place it in its topic, keep a copy for
-  // readers, and publish what changed.
-  async onCarried(cat, { noteId, sent }) {
-    let note = cat.intake.recentNotes.get(noteId) || null;
-    cat.intake.recentNotes.delete(noteId);
-    if (!note) note = await cat.intake.fetchAP(noteId);
-    if (!note) { this.log(`carried ${noteId} but could not read it for the topic`); return; }
-    const tid = await topics.assign({ store: cat.store, urls: cat.urls, fetchAP: (u) => cat.intake.fetchAP(u) }, note, sent);
-    // A locked topic takes no more: the post leaves it again and the carry is
-    // unsaid, so members' servers do not keep what the forum does not.
-    if (moderation.isLocked(cat, tid) && !topics.list(cat.store).find(t => t.tid === tid && t.op === noteId)) {
-      topics.remove(cat.store, tid, noteId);
-      await cat.intake.retract(noteId).catch(e => this.log(`retract ${noteId}: ${e.message}`));
-      this.log(`${cat.slug}: ${noteId} not placed — topic ${tid} is locked`);
-      return;
-    }
-    await publish.cachePost(cat, note, { topic: cat.urls.topic(tid), replies: 0 });
-    this.noteLatest(cat, note);
-    const answered = idOf(note.inReplyTo);
-    if (answered) await this.countReplies(cat, tid, answered).catch(e => this.log(`replies of ${answered}: ${e.message}`));
-    // The author's card, from the actor the intake already holds; fetched
-    // once when it does not, so the website can name them.
-    const author = idOf([].concat(note.attributedTo || [])[0]);
-    if (author) {
-      const held = cat.store.getActors?.()[author];
-      const doc = held ? { id: author, ...held } : await cat.intake.fetchAP(author).catch(() => null);
-      if (doc) await publish.cacheAuthor(cat, doc).catch(e => this.log(`author card for ${author}: ${e.message}`));
-    }
-    await publish.publishTopic(cat, tid);
-    await publish.publishTopicIndex(cat);
-    await publish.publishLatest(this.siteAgent);
-    this.log(`${cat.slug}: ${noteId} in topic ${tid}`);
+  // Placing a post in its topic, and what an edit or a deletion does to the
+  // place: place.mjs.
+  onCarry(cat, ev) { return place.placePost(this, cat, ev); }
+  onCarriedEdit(cat, ev) { return place.editPlaced(this, cat, ev); }
+  onCarriedGone(cat, ev) { return place.dropPlaced(this, cat, ev); }
+  countReplies(cat, tid, postId) { return place.countReplies(this, cat, tid, postId); }
+  noteLatest(cat, note) { return place.noteLatest(this, cat, note); }
+  dropLatest(cat, noteId) { return place.dropLatest(this, cat, noteId); }
+
+  // One delivery, handed in by whoever took it at the forum's door, done the
+  // way the drain does one item: handled, every store committed, and only
+  // then reported done — so the caller may remove it from the inbox.
+  async placeOne(name, body, receipt = null) {
+    const done = await this.intake.takeHeld([{ name, body, receipt }]);
+    return done.includes(name);
   }
 
+  // Letting a Gateway keep this forum, and taking that back: keep.mjs.
+  keep(o) { return keepForum(this, o); }
+  restateRules() { return restateForumRules(this); }
+
   // Take addresses at a Gateway: one row for the forum and one per category,
   // each a handle at the front, all writing their mail into the forum's one
   // inbox. The pod session proves the pod; no password leaves this machine.
@@ -464,45 +483,6 @@ export class ForumAgent {
     await cat.store.flush().catch(() => {});
   }
 
-  // An author edited a post of theirs that we hold: the copy the website
-  // reads is rewritten from the note as verified at its origin, and a changed
-  // title is the topic's title when that post opened it.
-  async onCarriedEdit(cat, { noteId, note }) {
-    // The copy is rewritten from the note as verified at its origin; the
-    // counts the forum keeps on it are put back from what the forum knows.
-    const v = cat.store.read('votes.json', {})[noteId];
-    const held = topics.topicOf(cat.store, noteId);
-    const replies = held ? (topics.get(cat.store, held)?.posts || []).filter(p => p.inReplyTo === noteId).length : null;
-    await publish.cachePost(cat, note, { topic: held ? cat.urls.topic(held) : null, replies,
-      likes: (Array.isArray(v) ? v : v?.up || []).length, dislikes: (Array.isArray(v) ? [] : v?.down || []).length });
-    await publish.publishLatest(this.siteAgent);
-    const tid = topics.topicOf(cat.store, noteId);
-    if (!tid) return;
-    await publish.publishTopic(cat, tid, { force: true });
-  }
-
-  // An author deleted one: it leaves the topic, its copy becomes a tombstone
-  // (FEP-4f05), and a topic with nothing left in it goes too. The carry has
-  // already been taken back by the group itself.
-  async onCarriedGone(cat, { noteId }) {
-    const tid = topics.topicOf(cat.store, noteId);
-    // Whatever it answered has one fewer answer now.
-    const answered = tid ? idOf(topics.get(cat.store, tid)?.posts?.find(p => p.id === noteId)?.inReplyTo) : null;
-    this.dropLatest(cat, noteId);
-    await publish.tombstoneCached(cat, noteId);
-    await publish.publishLatest(this.siteAgent);
-    if (!tid) return;
-    topics.remove(cat.store, tid, noteId);
-    const left = topics.get(cat.store, tid);
-    if (!left?.posts?.length) {
-      await moderation.deleteTopic(cat, tid).catch(e => this.log(`empty topic ${tid}: ${e.message}`));
-      return;
-    }
-    await publish.publishTopic(cat, tid, { force: true });
-    await publish.publishTopicIndex(cat, { force: true });
-    if (answered) await this.countReplies(cat, tid, answered).catch(e => this.log(`replies of ${answered}: ${e.message}`));
-  }
-
   // Queued asks from listed moderators that can be verified at their own
   // origin are applied; everything else waits for a person.
   async applyVerifiedAsks() {
@@ -752,28 +732,6 @@ export class ForumAgent {
     return true;
   }
 
-  // Answers to one post, counted in the topic that holds it, and written
-  // into the copy the website reads.
-  async countReplies(cat, tid, postId) {
-    const doc = topics.get(cat.store, tid);
-    if (!doc) return;
-    const n = (doc.posts || []).filter(p => p.inReplyTo === postId).length;
-    const copy = await this.remote.getJson(cat.urls.cached(postId)).catch(() => null);
-    if (!copy || copy.type === 'Tombstone') return;
-    if (Number(copy.replies?.totalItems) === n) return;
-    await publish.cachePost(cat, copy, { replies: n });
-  }
-
-  // The forum's own index of its newest posts, across every category.
-  noteLatest(cat, note) {
-    const copy = cat.urls.cached(note.id);
-    const at = note.published || new Date().toISOString();
-    const rows = this.store.read('latest.json', []).filter(e => e.copy !== copy);
-    rows.push({ copy, at });
-    rows.sort((a, b) => String(b.at).localeCompare(String(a.at)));
-    this.store.write('latest.json', rows.slice(0, publish.LATEST_MAX));
-  }
-
   // Everything the forum already holds, read back out of the topics, for an
   // index that did not exist when those posts arrived.
   // Copies kept before the forum recorded which topic they were in: the
@@ -806,11 +764,6 @@ export class ForumAgent {
     return rows.length;
   }
 
-  dropLatest(cat, noteId) {
-    const copy = cat.urls.cached(noteId);
-    this.store.write('latest.json', this.store.read('latest.json', []).filter(e => e.copy !== copy));
-  }
-
   async applyModeration(slug, entryId) {
     const cat = this.categories.find(c => c.slug === slug);
     if (!cat) throw new Error(`no such category: ${slug}`);
@@ -858,8 +811,20 @@ export class ForumAgent {
         .catch(e => this.log(`the reader list for ${cat.slug}: ${e.message}`));
       await this.dropUnreadableFollowers(cat)
         .catch(e => this.log(`letting go of ${cat.slug}'s strangers: ${e.message}`));
-      await this.carryOldTopics(cat);
-      await this.stampOldCopies(cat).catch(e => this.log(`stamping ${cat.slug}: ${e.message}`));
+      // Two passes over what older versions wrote, made once and recorded
+      // (upkeep.json): each reads every topic or every copy, which is no way
+      // to begin every start.
+      const upkeep = cat.store.read('upkeep.json', {});
+      if (!upkeep.oldTopicsCarried) {
+        await this.carryOldTopics(cat);
+        cat.store.write('upkeep.json', { ...cat.store.read('upkeep.json', {}), oldTopicsCarried: new Date().toISOString() });
+      }
+      if (!upkeep.copiesStamped) {
+        try {
+          await this.stampOldCopies(cat);
+          cat.store.write('upkeep.json', { ...cat.store.read('upkeep.json', {}), copiesStamped: new Date().toISOString() });
+        } catch (e) { this.log(`stamping ${cat.slug}: ${e.message}`); }
+      }
       const seen = cat.store.read('published.json', {});
       if (force || !seen.actorDigest) {
         await cat.publisher.publishProfile({ force });

package/src/forum-intake.mjs

@@ -78,6 +78,20 @@ export class ForumIntake extends Intake {
     return ok;
   }
 
+  // Deliveries handed in rather than listed — one placed at the door, a batch
+  // the door held — are done only when every category's state is on the pod
+  // too, the same rule the drain keeps.
+  async takeHeld(entries) {
+    for (const cat of this.forum.categories) cat.store.hold?.();
+    let done;
+    try { done = await super.takeHeld(entries); }
+    finally { for (const cat of this.forum.categories) cat.store.release?.(); }
+    if (!done.length) return done;
+    let ok = true;
+    for (const cat of this.forum.categories) ok = (await cat.store.commit()) && ok;
+    return ok ? done : [];
+  }
+
   // Categories carry (FEP-1b12); the forum's own inbox forwards nothing.
   async _maybeForward() {}
 
@@ -97,6 +111,16 @@ export class ForumIntake extends Intake {
     } catch { return null; }
   }
 
+  // A receipt handed in with a delivery, the same way: any of the forum's
+  // secrets may have signed it.
+  async _checkReceipt(receipt) {
+    if (!receipt || typeof receipt !== 'object') return null;
+    const secrets = [this.config.gateway?.hmacSecret, ...this.forum.categories.map(c => c.config.gateway?.hmacSecret)].filter(Boolean);
+    if (!secrets.length) return null;
+    const { verifyReceipt } = await import('fedipod/gateway/httpsig.mjs');
+    return secrets.some(s => verifyReceipt(receipt, s)) ? receipt : null;
+  }
+
   gatewaySecret() {
     return this.config.gateway?.hmacSecret || this.forum.categories.find(c => c.config.gateway?.hmacSecret)?.config.gateway.hmacSecret || null;
   }

package/src/gateway.mjs

@@ -0,0 +1,209 @@
+// gateway.mjs — the forum as fedipod.net runs it, with nothing running
+// anywhere else. Two entries: placeAtDoor(), called by the door with the
+// delivery it just wrote into the forum's inbox, places it in the same
+// request; keepOnce(), the forum's run, carries what the door placed, drains
+// what it left, applies moderators' asks and writes the heartbeat. Both work
+// as the gateway's keeper identity, from the copies the gateway holds of the
+// forum's and each category's state, under the forum's one copy lease.
+
+import { PodTransport } from 'fedipod/pod/transport.mjs';
+import { podBaseOfWebId } from 'fedipod/pod/urls.mjs';
+import * as podInbox from 'fedipod/pod/inbox.mjs';
+import { HttpStorage } from 'fedipod/core/storage.mjs';
+import { Lease } from 'fedipod/core/lease.mjs';
+import { CopyStorage, copyMeta, copyLease, lockCopy, GATEWAY_HOLDER } from 'fedipod/gateway/copy.mjs';
+import { ensureCopy } from 'fedipod/gateway/state-api.mjs';
+import { keeperSession } from 'fedipod/gateway/keeper-session.mjs';
+import { ForumAgent } from './forum-agent.mjs';
+import * as publish from './publish.mjs';
+
+// How soon a run comes back for an ask that could not be applied yet.
+const ASK_RETRY_MS = 60_000;
+
+/** A forum's own row, or one of its categories': both write into one inbox. */
+export const isForumRow = (rec) => !!rec?.inboxUrl && (rec.kind === 'group' || rec.kind === 'application');
+
+/** The forum a row belongs to: its handle and row, and where it is on the pod. */
+export async function forumFor(ctx, handle, rec) {
+  const forumHandle = rec.kind === 'application' ? handle : rec.forum;
+  if (!forumHandle) return { skipped: 'the category names no forum; run `fedipod-bb keep` again' };
+  const forumRec = forumHandle === handle ? rec : await ctx.lookup(forumHandle);
+  if (!forumRec || !isForumRow(forumRec) || !forumRec.keeper) return { skipped: `@${forumHandle} is not a forum this gateway keeps` };
+  if (!forumRec.webId || !forumRec.podHome) return { skipped: 'the forum row names no owner or pod' };
+  const home = forumRec.podHome.replace(/\/?$/u, '/');
+  const pod = podBaseOfWebId(forumRec.webId);
+  if (!home.startsWith(pod)) return { skipped: "the forum's folder is not on its owner's pod" };
+  return { forumHandle, forumRec, home, pod, root: home.slice(pod.length) };
+}
+
+// The gateway's pod fetch, as the keeper: a session handed in, the keeper's
+// credential, or the front's own keeperFetch.
+async function keeperFetchFor(ctx, session) {
+  if (session) return (u, i) => session.fetch(u, i);
+  if (ctx.keeperCredential) { const s = keeperSession(ctx.keeperCredential); return (u, i) => s.fetch(u, i); }
+  return ctx.keeperFetch ? ctx.keeperFetch() : null;
+}
+
+function transportFor(ctx, f, podFetch, log) {
+  const remote = new PodTransport({ fetch: podFetch }, { webId: ctx.keeperWebId, log, role: 'keeper', runtime: 'node', cooldownMode: 'refuse' });
+  // Any rule it writes names the forum's owner, and the keeper beside them.
+  remote.aclOwner = f.forumRec.webId;
+  remote.keepers = [ctx.keeperWebId];
+  remote.aclIfChanged = true;
+  return remote;
+}
+
+// Which copy holds a state container: the forum's own, or a category's. The
+// inbox archive and anything else stays the pod's.
+function copyHandleOf(base, f) {
+  if (base === f.home + 'ap-state/') return f.forumHandle;
+  const m = base.startsWith(f.home + 'c/') ? /^c\/([^/]+)\/ap-state\/$/u.exec(base.slice(f.home.length)) : null;
+  return m ? m[1] : null;
+}
+
+/** State storage for the forum: the copy where one exists, fenced by the forum's lease; the pod otherwise. */
+export function storageFactory(ctx, f, podFetch, copies) {
+  return (base) => {
+    const pod = new HttpStorage(base, podFetch);
+    const h = copyHandleOf(base, f);
+    if (!h || !copies.has(h)) return pod;
+    return new CopyStorage(ctx.copyKv, h, { holder: GATEWAY_HOLDER, pod, podNames: ['keys.json'], fence: f.forumHandle });
+  };
+}
+
+async function readConfig(ctx, f, podFetch) {
+  const storage = await copyMeta(ctx.copyKv, f.forumHandle)
+    ? new CopyStorage(ctx.copyKv, f.forumHandle, { holder: GATEWAY_HOLDER })
+    : new HttpStorage(f.home + 'ap-state/', podFetch);
+  const r = await storage.read('config.json', { accept: 'application/json' }).catch(() => null);
+  if (!r?.ok || !r.body) return null;
+  try { return JSON.parse(r.body); } catch { return null; }
+}
+
+/**
+ * The copies the forum works from, the forum's and each category's, made
+ * from the pod where missing. A copy cannot be made while another host
+ * holds the pod's lease, which is how a forum still run elsewhere is left
+ * alone until that host stops.
+ */
+export async function ensureForumCopies(ctx, f, config, log) {
+  const rows = [[f.forumHandle, f.forumRec]];
+  for (const c of config?.categories || []) {
+    const r = await ctx.lookup(c.slug);
+    if (r && isForumRow(r)) rows.push([c.slug, r]);
+  }
+  const have = new Set();
+  for (const [h, r] of rows) {
+    if (await copyMeta(ctx.copyKv, h)) { have.add(h); continue; }
+    const made = await ensureCopy(ctx, h, r, log);
+    if (made.ok) have.add(h); else log(`copy @${h}: ${made.why}`);
+  }
+  return have;
+}
+
+/** Which copies exist now, without making any. */
+async function copiesOf(ctx, f, config) {
+  const have = new Set();
+  if (await copyMeta(ctx.copyKv, f.forumHandle)) have.add(f.forumHandle);
+  for (const c of config?.categories || []) if (await copyMeta(ctx.copyKv, c.slug)) have.add(c.slug);
+  return have;
+}
+
+function agentFor(ctx, f, { remote, podFetch, copies, log, mode }) {
+  const lease = copies.has(f.forumHandle)
+    ? copyLease(ctx.copyKv, f.forumHandle, { id: GATEWAY_HOLDER, log })
+    : new Lease({ url: f.home + 'ap-state/lease.json', fetchImpl: podFetch, log, id: `keeper:${ctx.keeperWebId}` });
+  return new ForumAgent({
+    log, remote, storageFor: storageFactory(ctx, f, podFetch, copies), push: false,
+    credential: { remotePod: f.pod, root: f.root, webId: f.forumRec.webId },
+    lease, holderId: GATEWAY_HOLDER, keepers: [ctx.keeperWebId],
+    // The run may mint a new forum's first keys; the door never mints.
+    mintKeys: mode === 'run', defer: mode === 'door',
+  });
+}
+
+// When the run should come back on its own: a delivery's next try, or an ask
+// that could not be applied yet.
+function nextRun(forum, asksPending) {
+  const times = [];
+  for (const s of [forum.store, ...forum.categories.map((c) => c.store)]) {
+    for (const item of s.getQueue?.() || []) if (item.nextAt) times.push(item.nextAt);
+  }
+  if (asksPending) times.push(Date.now() + ASK_RETRY_MS);
+  return times.length ? Math.min(...times) : null;
+}
+
+/**
+ * One run of the forum: what the door left in the inbox is drained, what it
+ * placed is carried, moderators' asks are applied, the heartbeat is written.
+ * Returns what the keeper's bookkeeping expects: { drained, waiting, nextAt }
+ * or { skipped, retry }.
+ */
+export async function keepOnce(ctx, handle, rec, { log = console.log, session = null, remote: given = null, prepare = null } = {}) {
+  const f = await forumFor(ctx, handle, rec);
+  if (f.skipped) return { skipped: f.skipped };
+  const say = (m) => log(`forum @${f.forumHandle}: ${m}`);
+  const podFetch = given ? (u, i) => given.fetch(u, i) : await keeperFetchFor(ctx, session);
+  if (!podFetch) return { skipped: 'this gateway cannot reach pods for accounts' };
+  const remote = given || transportFor(ctx, f, podFetch, say);
+  const config = await readConfig(ctx, f, podFetch);
+  if (!config) return { skipped: 'no forum on the pod' };
+  const copies = await ensureForumCopies(ctx, f, config, say);
+  const unlock = await lockCopy(ctx.copyKv, f.forumHandle);
+  if (!unlock) return { skipped: 'the gateway is busy with this forum', retry: 'soon' };
+  try {
+    const forum = agentFor(ctx, f, { remote, podFetch, copies, log: say, mode: 'run' });
+    if (!await forum.connect({ act: false })) return { skipped: 'no forum on the pod' };
+    prepare?.(forum);   // a test's origins, in place of the network
+    if (!await forum.lease.acquire()) return { skipped: 'another host has the forum', retry: 'soon' };
+    try {
+      await forum.publishAll();
+      await forum.intake.drain();
+      await forum.applyVerifiedAsks().catch((e) => say(`asks: ${e.message}`));
+      await forum.publishModQueue().catch((e) => say(`queue: ${e.message}`));
+      for (const cat of forum.categories) await cat.deliverer.drainQueue();
+      await forum.siteAgent.deliverer.drainQueue();
+      await publish.publishHeartbeat(forum.siteAgent).catch((e) => say(`heartbeat: ${e.message}`));
+      await Promise.allSettled([forum.store.flush(), ...forum.categories.map((c) => c.store.flush())]);
+      const waiting = [forum.store, ...forum.categories.map((c) => c.store)].reduce((n, s) => n + (s.getQueue?.() || []).length, 0);
+      const asks = [forum.store, ...forum.categories.map((c) => c.store)].reduce((n, s) => n + s.read('modqueue.json', []).length, 0);
+      say(`done: inbox drained, ${waiting} delivery(ies) waiting, ${asks} ask(s) pending`);
+      return { drained: true, waiting, nextAt: nextRun(forum, asks) };
+    } finally { await forum.lease.release().catch(() => {}); }
+  } finally { await unlock(); }
+}
+
+/**
+ * The delivery the door just wrote into the forum's inbox, placed now: the
+ * forum handles it with every send deferred, and when it is done the item
+ * and its receipt leave the inbox. Returns { placed, forum, why }. Whatever
+ * is not placed here stays in the inbox for the run the caller starts.
+ */
+export async function placeAtDoor(ctx, handle, rec, { name, raw, receipt = null, log = console.log, waitMs = 3000, remote: given = null, prepare = null } = {}) {
+  const f = await forumFor(ctx, handle, rec);
+  if (f.skipped) return { placed: false, why: f.skipped };
+  const out = { placed: false, forum: f.forumHandle };
+  if (!await copyMeta(ctx.copyKv, f.forumHandle)) return { ...out, why: 'the forum has no copy yet' };
+  const podFetch = given ? (u, i) => given.fetch(u, i) : await keeperFetchFor(ctx, null);
+  if (!podFetch) return { ...out, why: 'this gateway cannot reach pods for accounts' };
+  const say = (m) => log(`door @${f.forumHandle}: ${m}`);
+  const remote = given || transportFor(ctx, f, podFetch, say);
+  const config = await readConfig(ctx, f, podFetch);
+  if (!config) return { ...out, why: 'no forum on the pod' };
+  const copies = await copiesOf(ctx, f, config);
+  const unlock = await lockCopy(ctx.copyKv, f.forumHandle, { waitMs });
+  if (!unlock) return { ...out, why: 'the forum is busy' };
+  try {
+    const forum = agentFor(ctx, f, { remote, podFetch, copies, log: say, mode: 'door' });
+    if (!await forum.connect({ act: false })) return { ...out, why: 'no forum on the pod' };
+    prepare?.(forum);   // a test's origins, in place of the network
+    if (!await forum.lease.acquire()) return { ...out, why: 'another host has the forum' };
+    try {
+      if (!await forum.placeOne(name, raw, receipt)) return { ...out, why: 'not done here; left for the run' };
+      const item = f.home + 'ap/inbox/' + name;
+      await podInbox.dropHandledItem(remote, item).catch(() => false);
+      await podInbox.dropReceiptBeside(remote, item);
+      return { ...out, placed: true };
+    } finally { await forum.lease.release().catch(() => {}); }
+  } finally { await unlock(); }
+}

package/src/keep.mjs

@@ -0,0 +1,50 @@
+// keep.mjs — letting a Gateway keep this forum: it acts for the forum when
+// nothing else does, from the pod's own rules, which name its keeper beside
+// the owner from then on. Taking the name out again is the same in reverse.
+
+import { restateRules } from 'fedipod/pod/containers.mjs';
+import * as podInbox from 'fedipod/pod/inbox.mjs';
+import * as publish from './publish.mjs';
+import { provisionForum, provisionCategory } from './provision.mjs';
+
+// Let a Gateway keep this forum: it acts for the forum when nothing else
+// does, from the pod's own rules, which name it beside the owner from here
+// on. `on: false` takes the name out again.
+export async function keepForum(forum, { front, on = true }) {
+  const origin = String(front).replace(/\/+$/u, '');
+  const handles = [forum.config.handle, ...forum.categories.map(c => c.slug)];
+  let keeper = null;
+  for (const handle of handles) {
+    const res = await forum.remote.session.fetch(`${origin}/api/keeper`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ handle, on, ...(handle === forum.config.handle ? {} : { forum: forum.config.handle }) }),
+    });
+    const d = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(`${origin} would not ${on ? 'keep' : 'let go of'} @${handle}: ${d.error || res.status}`);
+    keeper = d.keeper || keeper;
+  }
+  forum.keepers = on && keeper ? [keeper] : [];
+  forum.remote.keepers = [...forum.keepers];
+  forum.remote.aclOwner = forum.readCredential()?.webId || forum.remote.aclOwner || null;
+  await forum.restateRules();
+  return { keeper: on ? keeper : null, handles, on };
+}
+
+// Every rule on the forum's tree, stated again with the names this host
+// carries: the containers, the inboxes, the reader lists, and the documents
+// that state a rule of their own.
+export async function restateForumRules(forum) {
+    await provisionForum(forum.remote, forum.site, { moderatorWebIds: forum.config.moderatorWebIds || [] });
+  await restateRules(forum.remote, forum.site).catch(e => forum.log(`restating the forum's rules: ${e.message}`));
+  await podInbox.setPosture(forum.remote, forum.site, 'open');
+  for (const cat of forum.categories) {
+    await provisionCategory(forum.remote, cat.urls, { memberWebIds: forum.membersOf(cat) });
+    await restateRules(forum.remote, cat.urls).catch(e => forum.log(`restating ${cat.slug}'s rules: ${e.message}`));
+    await publish.publishMembers(cat, forum.readersOf(cat), { force: true }).catch(e => forum.log(`the reader list for ${cat.slug}: ${e.message}`));
+    await podInbox.setPosture(forum.remote, cat.urls, 'closed');
+    for (const base of [cat.urls.topicContainer, cat.urls.cache]) {
+      const children = await forum.remote.listContainer?.(base).catch(() => []) || [];
+      for (const child of children) if (!child.url.endsWith('/')) await forum.remote.restateAcl?.(child.url).catch(() => null);
+    }
+  }
+}

package/src/place.mjs

@@ -0,0 +1,110 @@
+// place.mjs — placing a post in its topic, keeping the copy readers see, and
+// what an edit or a deletion does to that place. Called by a category's
+// intake before it carries a post, and by the door that takes one as it
+// lands.
+
+import * as topics from './topics.mjs';
+import * as publish from './publish.mjs';
+import * as moderation from './moderation.mjs';
+
+const idOf = (v) => (typeof v === 'string' ? v : v?.id);
+
+// Before a category carries a post: place it in its topic, keep a copy for
+// readers, and publish what changed. A locked topic takes no more: the post
+// is not placed and, answered with false, not carried either.
+export async function placePost(forum, cat, { noteId, sent }) {
+  let note = cat.intake.recentNotes.get(noteId) || null;
+  cat.intake.recentNotes.delete(noteId);
+  if (!note) note = await cat.intake.fetchAP(noteId);
+  if (!note) throw new Error(`${noteId} could not be read for its topic`);
+  const tid = await topics.assign({ store: cat.store, urls: cat.urls, fetchAP: (u) => cat.intake.fetchAP(u) }, note, sent);
+  if (moderation.isLocked(cat, tid) && !topics.list(cat.store).find(t => t.tid === tid && t.op === noteId)) {
+    topics.remove(cat.store, tid, noteId);
+    forum.log(`${cat.slug}: ${noteId} not placed — topic ${tid} is locked`);
+    return false;
+  }
+  await publish.cachePost(cat, note, { topic: cat.urls.topic(tid), replies: 0 });
+  noteLatest(forum, cat, note);
+  const answered = idOf(note.inReplyTo);
+  if (answered) await countReplies(forum, cat, tid, answered).catch(e => forum.log(`replies of ${answered}: ${e.message}`));
+  // The author's card, from the actor the intake already holds; fetched
+  // once when it does not, so the website can name them.
+  const author = idOf([].concat(note.attributedTo || [])[0]);
+  if (author) {
+    const held = cat.store.getActors?.()[author];
+    const doc = held ? { id: author, ...held } : await cat.intake.fetchAP(author).catch(() => null);
+    if (doc) await publish.cacheAuthor(cat, doc).catch(e => forum.log(`author card for ${author}: ${e.message}`));
+  }
+  await publish.publishTopic(cat, tid);
+  await publish.publishTopicIndex(cat);
+  await publish.publishLatest(forum.siteAgent);
+  forum.log(`${cat.slug}: ${noteId} in topic ${tid}`);
+  return true;
+}
+
+// An author edited a post of theirs that we hold: the copy the website
+// reads is rewritten from the note as verified at its origin, and a changed
+// title is the topic's title when that post opened it.
+export async function editPlaced(forum, cat, { noteId, note }) {
+  // The copy is rewritten from the note as verified at its origin; the
+  // counts the forum keeps on it are put back from what the forum knows.
+  const v = cat.store.read('votes.json', {})[noteId];
+  const held = topics.topicOf(cat.store, noteId);
+  const replies = held ? (topics.get(cat.store, held)?.posts || []).filter(p => p.inReplyTo === noteId).length : null;
+  await publish.cachePost(cat, note, { topic: held ? cat.urls.topic(held) : null, replies,
+    likes: (Array.isArray(v) ? v : v?.up || []).length, dislikes: (Array.isArray(v) ? [] : v?.down || []).length });
+  await publish.publishLatest(forum.siteAgent);
+  const tid = topics.topicOf(cat.store, noteId);
+  if (!tid) return;
+  await publish.publishTopic(cat, tid, { force: true });
+}
+
+// An author deleted one: it leaves the topic, its copy becomes a tombstone
+// (FEP-4f05), and a topic with nothing left in it goes too. The carry has
+// already been taken back by the group itself.
+export async function dropPlaced(forum, cat, { noteId }) {
+  const tid = topics.topicOf(cat.store, noteId);
+  // Whatever it answered has one fewer answer now.
+  const answered = tid ? idOf(topics.get(cat.store, tid)?.posts?.find(p => p.id === noteId)?.inReplyTo) : null;
+  dropLatest(forum, cat, noteId);
+  await publish.tombstoneCached(cat, noteId);
+  await publish.publishLatest(forum.siteAgent);
+  if (!tid) return;
+  topics.remove(cat.store, tid, noteId);
+  const left = topics.get(cat.store, tid);
+  if (!left?.posts?.length) {
+    await moderation.deleteTopic(cat, tid).catch(e => forum.log(`empty topic ${tid}: ${e.message}`));
+    return;
+  }
+  await publish.publishTopic(cat, tid, { force: true });
+  await publish.publishTopicIndex(cat, { force: true });
+  if (answered) await countReplies(forum, cat, tid, answered).catch(e => forum.log(`replies of ${answered}: ${e.message}`));
+}
+
+// Answers to one post, counted in the topic that holds it, and written
+// into the copy the website reads.
+export async function countReplies(forum, cat, tid, postId) {
+  const doc = topics.get(cat.store, tid);
+  if (!doc) return;
+  const n = (doc.posts || []).filter(p => p.inReplyTo === postId).length;
+  const copy = await forum.remote.getJson(cat.urls.cached(postId)).catch(() => null);
+  if (!copy || copy.type === 'Tombstone') return;
+  if (Number(copy.replies?.totalItems) === n) return;
+  await publish.cachePost(cat, copy, { replies: n });
+}
+
+// The forum's own index of its newest posts, across every category.
+export function noteLatest(forum, cat, note) {
+  const copy = cat.urls.cached(note.id);
+  const at = note.published || new Date().toISOString();
+  const rows = forum.store.read('latest.json', []).filter(e => e.copy !== copy);
+  rows.push({ copy, at });
+  rows.sort((a, b) => String(b.at).localeCompare(String(a.at)));
+  forum.store.write('latest.json', rows.slice(0, publish.LATEST_MAX));
+}
+
+export function dropLatest(forum, cat, noteId) {
+  const copy = cat.urls.cached(noteId);
+  forum.store.write('latest.json', forum.store.read('latest.json', []).filter(e => e.copy !== copy));
+}
+