fedipod-bb 0.2.0 → 0.4.0

package/README.md

@@ -21,6 +21,12 @@ node --test packages/fedipod-bb/test/*.test.mjs
 
 ## Hosting a forum
 
+A forum can be made at a FediPod Gateway's sign-up page (fedipod.net's, for
+one) with no machine of your own: choose "A forum", make a pod for it at a
+provider, name it and its categories, and the Gateway writes it on the pod
+and runs it from then on. The commands below are for running a forum from a
+machine of your own instead.
+
 ```
 npm install -g fedipod-bb
 fedipod-bb credential --home DIR --email you@example.org --pod https://forum.example/

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,17 @@
 {
   "name": "fedipod-bb",
-  "version": "0.2.0",
+  "version": "0.4.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",
+    "./setup": "./src/setup.mjs",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "fedipod-bb": "bin/fedipod-bb.mjs"
   },
@@ -20,7 +27,7 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "fedipod": "^1.42.0",
+    "fedipod": "^1.44.0",
     "fediverse-session": "^0.2.1"
   }
 }

package/site/bb.js

@@ -39,8 +39,14 @@ const place = placeOf({ origin: location.origin, pathname: location.pathname, se
 const { front, base } = place;
 const frontHost = new URL(front).host;
 // The reader asks anonymously first; where a category is members-only it
-// asks again with the pod session, if there is one.
-let read = reader();
+// asks again with the pod session, if there is one. Right after this reader
+// posts, the next read goes past the browser's own copy of each document (a
+// front lets a browser keep one for a minute): a post the forum placed as it
+// arrived is then on the page at once, not a minute later.
+let freshRead = false;
+const readerFetch = (url, init = {}) => fetch(url, freshRead ? { ...init, cache: 'reload' } : init);
+const makeReader = (session = null) => reader({ session, fetch: readerFetch });
+let read = makeReader();
 const login = new MastoLogin({ storage: localStorage, redirectUri: location.origin + location.pathname + location.search });
 // What this reader has already read. Theirs, in their own browser: a public
 // forum has nowhere to keep it and no business keeping it.
@@ -989,7 +995,7 @@ async function report(id) {
   if (why === null) return;
   try {
     const cat = replyCtx.cat;
-    const inbox = await pod.podInboxOf(cat.id, { front, handle: cat.slug || null });
+    const inbox = await pod.podInboxOf(cat.id);
     const who = podAcct?.actor || login.account()?.url;
     await pod.report({ actor: who, object: id, category: cat.id, inbox, why });
     alert('Reported. A moderator will see it in the forum\'s queue.');
@@ -1007,7 +1013,7 @@ async function asksTo(activity, forCat = null) {
   // The same reason voteOn says it.
   let step = 'finding where the forum takes mail';
   try {
-    const inbox = await pod.podInboxOf(cat.id, { front, handle: cat.slug || null });
+    const inbox = await pod.podInboxOf(cat.id);
     if (!inbox) throw new Error('the forum did not say where to send it');
     // moderate() names its own two requests, so nothing is added over the top.
     step = 'sending the request';
@@ -1049,7 +1055,7 @@ async function joinOrLeave(categoryId, on) {
     return;
   }
   try {
-    const inbox = await pod.podInboxOf(cat.id, { front, handle: cat.slug || null });
+    const inbox = await pod.podInboxOf(cat.id);
     const ok = on
       ? await pod.join({ actor: podAcct.actor, category: cat.id, inbox })
       : await pod.leave({ actor: podAcct.actor, category: cat.id, inbox });
@@ -1129,7 +1135,7 @@ async function voteOn(postId, way, was) {
   if (!cat) return;
   let step = 'finding where the forum takes mail';
   try {
-    const inbox = await pod.podInboxOf(cat.id, { front, handle: cat.slug || null });
+    const inbox = await pod.podInboxOf(cat.id);
     if (!inbox) throw new Error('the forum did not say where to send it');
     step = `sending the vote to ${new URL(inbox).host}`;
     await pod.vote({ actor: podAcct.actor, post: postId, category: cat.id, inbox, way, was });
@@ -1207,7 +1213,7 @@ async function askToJoin(categoryId) {
   const cat = cats().find(c => c.id === categoryId);
   if (!cat || !podAcct) return;
   try {
-    const inbox = await pod.podInboxOf(cat.id, { front, handle: cat.slug || null });
+    const inbox = await pod.podInboxOf(cat.id);
     await pod.join({ actor: podAcct.actor, category: cat.id, inbox });
     say('Asked. A moderator sees it in the forum\'s queue.');
     alert('Your request is with the moderators.');
@@ -1326,7 +1332,7 @@ function settingsSaid(text, bad = false) {
 
 async function settingsAsk(...activities) {
   try {
-    const inbox = await pod.podInboxOf(cats()[0]?.id || forum.id, { front, handle: cats()[0]?.slug || forum.handle });
+    const inbox = await pod.podInboxOf(cats()[0]?.id || forum.id);
     for (const activity of activities) {
       await pod.moderate({ actor: podAcct.actor, podHome: podAcct.podHome, inbox, activity });
     }
@@ -1404,7 +1410,7 @@ async function removePost(id) {
   try {
     const cat = replyCtx.cat;
     if (podAcct) {
-      const inbox = await pod.podInboxOf(cat.id, { front, handle: cat.slug || null });
+      const inbox = await pod.podInboxOf(cat.id);
       await pod.remove({ actor: podAcct.actor, podHome: podAcct.podHome, id, category: cat.id,
         categoryBase: cat.base, isPrivate: !!cat.private, inbox });
     } else {
@@ -1534,7 +1540,7 @@ $('who-act').addEventListener('click', async () => {
 async function saveEdit({ body }) {
   const cat = replyCtx.cat;
   if (podAcct) {
-    const inbox = await pod.podInboxOf(cat.id, { front, handle: cat.slug || null });
+    const inbox = await pod.podInboxOf(cat.id);
     return pod.edit({ actor: podAcct.actor, podHome: podAcct.podHome, id: editing.id, text: body, category: cat.id,
       categoryBase: cat.base, isPrivate: !!cat.private, inbox });
   }
@@ -1545,7 +1551,7 @@ async function saveEdit({ body }) {
 // category is named on its own pod, which is where a delivery is taken.
 async function postFromPod({ topic, body }) {
   const cat = replyCtx.cat;
-  const inbox = await pod.podInboxOf(cat.id, { front, handle: cat.slug || null });
+  const inbox = await pod.podInboxOf(cat.id);
   if (!inbox) throw new Error('the forum did not say where to send it');
   // Posting in an open category joins it on the way past, which is what makes
   // the post carry. A private one is joined by asking and being admitted, so
@@ -1584,7 +1590,8 @@ $('reply-send').addEventListener('click', async () => {
     $('topic-title').value = '';
     $('reply-dlg').close();
     forgetIndex();
-    await route();
+    freshRead = true;
+    try { await route(); } finally { freshRead = false; }
   } catch (e) { $('reply-err').textContent = e.message; }
   $('reply-send').disabled = false;
 });
@@ -1600,7 +1607,7 @@ $('reply-send').addEventListener('click', async () => {
   if (kept && !sessionStorage.getItem('bb:pod')) {
     try {
       const s = await pod.session();
-      if (s) { podAcct = { ...JSON.parse(kept), webId: s.webId }; read = reader({ session: s }); }
+      if (s) { podAcct = { ...JSON.parse(kept), webId: s.webId }; read = makeReader(s); }
       else localStorage.removeItem('bb:acct');
     } catch { localStorage.removeItem('bb:acct'); }
   }
@@ -1611,7 +1618,7 @@ $('reply-send').addEventListener('click', async () => {
       const s = params.get('code') ? await pod.complete(location.href) : await pod.session();
       if (s) {
         podAcct = { ...who, webId: s.webId };
-        read = reader({ session: s });
+        read = makeReader(s);
         try { localStorage.setItem('bb:acct', JSON.stringify(who)); } catch { /* blocked storage */ }
         sessionStorage.removeItem('bb:pod');
         params.delete('code'); params.delete('state'); params.delete('iss');

package/site/pod.mjs

@@ -84,18 +84,12 @@ async function placeAndAudience(s, { actor, podHome, category, categoryBase, isP
   return { where, to: [categoryBase + 'ap/followers'] };
 }
 
-// What the forum answers as, on its own pod: the page reads a category
-// through the Gateway, whose ids are the front's, but a post is delivered to
-// the pod itself.
-export async function podInboxOf(categoryActorId, { front = null, handle = null, fetch: f = globalThis.fetch.bind(globalThis) } = {}) {
-  // Through a Gateway the category's actor names the Gateway's own door, which
-  // takes signed mail between servers. A post made here is the reader's own,
-  // so it goes to the pod inbox the Gateway names when asked.
-  if (front && handle && categoryActorId.startsWith(front)) {
-    const said = await f(`${front}/api/server?host=${encodeURIComponent(new URL(front).host)}&handle=${encodeURIComponent(handle)}`,
-      { headers: { accept: 'application/json' } }).then(r => (r.ok ? r.json() : null)).catch(() => null);
-    if (said?.inbox) return said.inbox;
-  }
+// Where a category takes what is sent to it: the inbox its actor names. Through
+// a Gateway that is the Gateway's door, which writes the delivery into the
+// forum's pod inbox for whatever runs the forum, and, when the Gateway keeps
+// the forum itself, places the post before it answers. Read from the pod
+// outright, it is the pod inbox.
+export async function podInboxOf(categoryActorId, { fetch: f = globalThis.fetch.bind(globalThis) } = {}) {
   const doc = await f(categoryActorId, { headers: { accept: 'application/activity+json' } }).then(r => (r.ok ? r.json() : null)).catch(() => null);
   const inbox = doc?.endpoints?.sharedInbox || doc?.inbox;
   return typeof inbox === 'string' ? inbox : null;

package/src/forum-agent.mjs

@@ -30,6 +30,9 @@ 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 { writeForumConfig, attachRows } from './setup.mjs';
+import * as place from './place.mjs';
 
 import { ForumIntake } from './forum-intake.mjs';
 export { ForumIntake };
@@ -44,13 +47,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 +78,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 +94,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',
@@ -106,46 +132,25 @@ export class ForumAgent {
     const cred = this.readCredential();
     if (!cred) throw new Error('no credential.json — make one first');
     await this.attachRemote(cred);
-    const site = forumUrls(cred.remotePod, cred.root || ROOT);
-    await provisionForum(this.remote, site);
-    const store = new PodStore({ log: this.log });
-    store.attach(this.storageFor(site.state, (u, i) => this.remote.fetch(u, i)));
-    await store.load().catch(() => {});
-    const existing = store.getConfig() || {};
-    const cats = categories.map(c => (typeof c === 'string' ? { slug: c, name: c } : c));
-    for (const c of cats) if (!isSlug(c.slug)) throw new Error(`not a category slug: ${c.slug}`);
-    // A renamed forum has to be published again: the profile is written only
-    // when its digest changed or something asks, and a name lives in the
-    // actor document, not in the config alone.
-    // A changed name — the forum's or any category's — lives in a published
-    // actor, and the profile is only rewritten when its digest changed or
-    // something asks. So it asks.
-    const was = JSON.stringify((existing.categories || []).map(c => [c.slug, c.name]));
-    // Who may read what is written into the pod's own access rules, which are
-    // only written when something asks for a republish — so a change to them
-    // asks for one.
-    const access = JSON.stringify([existing.membersOnly || [], existing.memberWebIds || {}, existing.moderatorWebIds || []]);
-    const accessChanged = !!existing.handle && access !== JSON.stringify([membersOnly, memberWebIds, moderatorWebIds]);
-    const renamed = !!existing.handle
-      && ((name || handle) !== existing.name || was !== JSON.stringify(cats.map(c => [c.slug, c.name])));
-    store.setConfig({
-      ...existing, kind: 'application', handle, name: name || existing.name || handle,
-      ...(renamed || accessChanged ? { republish: true } : {}),
-      ...(accessChanged ? { reprovision: true } : {}),
-      remotePod: cred.remotePod, root: cred.root || ROOT,
-      categories: cats, moderators, moderatorWebIds, membersOnly, memberWebIds,
-      approveJoins, review, replyPolicy,
-    });
-    await store.flush();
-    this.log(`forum ${handle} initialised with ${cats.length} categor${cats.length === 1 ? 'y' : 'ies'}`);
-    return store.getConfig();
+    const { config } = await writeForumConfig(this.remote, this.storageFor, {
+      remotePod: cred.remotePod, root: cred.root || ROOT, handle, name, categories, moderators, moderatorWebIds,
+      membersOnly, memberWebIds, approveJoins, review, replyPolicy,
+    }, { log: this.log });
+    return config;
   }
 
   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 +167,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 +230,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 +259,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 +303,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 +354,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.
@@ -393,28 +385,14 @@ export class ForumAgent {
     const cred = this.readCredential();
     if (!cred || !this.store || !this.config) throw new Error('connect first');
     const plain = forumUrls(cred.remotePod, cred.root || ROOT);
-    const post = attachOne || (async (body) => {
-      const res = await this.remote.session.fetch(`${origin}/api/attach`, {
-        method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),
-      });
-      const d = await res.json().catch(() => ({}));
-      if (res.status !== 201 || !d.hmacSecret) throw new Error(`attach ${body.handle} at ${origin}: HTTP ${res.status}${d.error ? ' ' + d.error : ''}`);
-      return d;
-    });
-    const secrets = {};
-    const rows = [
-      { handle: this.config.handle, podHome: plain.home, actorUrl: plain.actor, kind: 'application' },
-      ...(this.config.categories || []).map(c => ({ handle: c.slug, podHome: plain.category(c.slug).home,
-        actorUrl: plain.category(c.slug).actor, kind: 'group' })),
-    ];
-    for (const row of rows) {
-      const d = await post({ ...row, fronted: true, inboxUrl: plain.inbox });
-      secrets[row.handle] = String(d.hmacSecret);
-      this.log(`attached @${row.handle}@${new URL(origin).host}`);
-    }
-    this.store.setConfig({ ...this.store.getConfig(), gateway: { front: origin, mode: 'trust', secrets }, republish: true });
+    // A test hands in the attach itself; otherwise the pod session proves the owner.
+    const f = attachOne
+      ? async (_url, init) => { const d = await attachOne(JSON.parse(init.body)); return { status: 201, json: async () => d }; }
+      : (u, i) => this.remote.session.fetch(u, i);
+    const { gateway, handles } = await attachRows({ fetch: f, front: origin, config: this.config, plain }, { log: this.log });
+    this.store.setConfig({ ...this.store.getConfig(), gateway, republish: true });
     await this.store.flush();
-    return { front: origin, handles: rows.map(r => r.handle) };
+    return { front: origin, handles };
   }
 
   // One category's handle at the Gateway, claimed when a moderator creates
@@ -464,45 +442,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 +691,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 +723,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 +770,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,215 @@
+// 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);
+      // The run wrote on the pod (what the door could not place, the queue,
+      // the heartbeat): the edge's copies of the forum's documents go.
+      if (ctx.purge) {
+        const tags = [`u-${f.forumHandle}`, ...(config.categories || []).map((c) => `u-${c.slug}`)];
+        await ctx.purge(tags).catch((e) => say(`purge: ${e.message}`));
+      }
+      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/index.mjs

@@ -6,4 +6,5 @@ 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 * as setup from './setup.mjs';
 export { ForumAgent, ForumIntake } from './forum-agent.mjs';

package/src/keep.mjs

@@ -0,0 +1,40 @@
+// 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';
+import { keepRows } from './setup.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 { keeper, handles } = await keepRows({ fetch: (u, i) => forum.remote.session.fetch(u, i), front, config: forum.config, on });
+  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));
+}
+

package/src/setup.mjs

@@ -0,0 +1,163 @@
+// setup.mjs — bringing a forum into being on its pod, from wherever its owner
+// is: a moderator's machine (`fedipod-bb init`, `attach`, `keep`) or the
+// browser at a Gateway's sign-up page. Config, containers and rules, the rows
+// at a Gateway and the keeper's name: nothing here runs the forum. Every
+// function takes the pod transport and the fetch it is handed; none reaches
+// for a file, a credential or the network on its own, so the same code runs
+// in Node and in a page.
+
+import { restateRules } from 'fedipod/pod/containers.mjs';
+import { forumUrls, ROOT, isSlug } from './urls.mjs';
+
+export { ROOT };
+import { provisionForum, provisionCategory } from './provision.mjs';
+
+/**
+ * The forum's config, from what it was and what is asked. A renamed forum or
+ * a changed reader list has to be published again — the actors and the rules
+ * are only rewritten when something asks — so the config says so.
+ */
+export function forumConfig(existing = {}, { remotePod, root = ROOT, handle, name, categories = [], moderators = [],
+  moderatorWebIds = [], membersOnly = [], memberWebIds = {}, approveJoins = false, review = false, replyPolicy = 'open' }) {
+  if (!isSlug(handle)) throw new Error(`not a forum handle: ${handle}`);
+  const cats = categories.map(c => (typeof c === 'string' ? { slug: c, name: c } : c));
+  for (const c of cats) if (!isSlug(c.slug)) throw new Error(`not a category slug: ${c.slug}`);
+  const was = JSON.stringify((existing.categories || []).map(c => [c.slug, c.name]));
+  const access = JSON.stringify([existing.membersOnly || [], existing.memberWebIds || {}, existing.moderatorWebIds || []]);
+  const accessChanged = !!existing.handle && access !== JSON.stringify([membersOnly, memberWebIds, moderatorWebIds]);
+  const renamed = !!existing.handle
+    && ((name || handle) !== existing.name || was !== JSON.stringify(cats.map(c => [c.slug, c.name])));
+  return {
+    ...existing, kind: 'application', handle, name: name || existing.name || handle,
+    ...(renamed || accessChanged ? { republish: true } : {}),
+    ...(accessChanged ? { reprovision: true } : {}),
+    remotePod, root,
+    categories: cats, moderators, moderatorWebIds, membersOnly, memberWebIds,
+    approveJoins, review, replyPolicy,
+  };
+}
+
+// The config document, written the way the state store writes it (one JSON
+// document per name in the state container), without the store itself: a
+// page that makes a forum need not carry the store's whole apparatus.
+const CONFIG = 'config.json';
+const serialise = (obj) => JSON.stringify(obj, null, 2) + '\n';
+async function writeConfig(storage, config) {
+  const w = await storage.write(CONFIG, serialise(config), 'application/json');
+  if (!w.ok) throw new Error(`the forum's config could not be written${w.why ? ` (${w.why})` : ''}`);
+}
+
+/**
+ * The first act on a pod: the forum's containers and its config, nothing
+ * else — the actors are published by the first run. `storageFor(base,
+ * fetch)` is the owner-only state storage the caller uses. Returns the
+ * storage, the config and the forum's plain urls, for whatever the caller
+ * does next.
+ */
+export async function writeForumConfig(remote, storageFor, opts, { log = () => {} } = {}) {
+  const plain = forumUrls(opts.remotePod, opts.root || ROOT);
+  await provisionForum(remote, plain);
+  const storage = storageFor(plain.state, (u, i) => remote.fetch(u, i));
+  const had = await storage.read(CONFIG).catch(() => null);
+  let existing = {};
+  if (had?.ok && had.body) { try { existing = JSON.parse(had.body) || {}; } catch { existing = {}; } }
+  const config = forumConfig(existing, opts);
+  await writeConfig(storage, config);
+  log(`forum ${config.handle} initialised with ${config.categories.length} categor${config.categories.length === 1 ? 'y' : 'ies'}`);
+  return { storage, config, plain };
+}
+
+/** The forum's rows at a Gateway: its own and one per category, all writing into its one inbox. */
+export const gatewayRows = (config, plain) => [
+  { handle: config.handle, podHome: plain.home, actorUrl: plain.actor, kind: 'application' },
+  ...(config.categories || []).map(c => ({ handle: c.slug, podHome: plain.category(c.slug).home,
+    actorUrl: plain.category(c.slug).actor, kind: 'group' })),
+];
+
+/**
+ * Attach the forum at a Gateway: each row fronted, its receipts' secret kept.
+ * `fetch` carries the owner's proof (the pod session). Returns what the config
+ * records under `gateway`, and the handles.
+ */
+export async function attachRows({ fetch: f, front, config, plain }, { log = () => {} } = {}) {
+  const origin = String(front).replace(/\/+$/u, '');
+  const secrets = {};
+  const rows = gatewayRows(config, plain);
+  for (const row of rows) {
+    const res = await f(`${origin}/api/attach`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ ...row, fronted: true, inboxUrl: plain.inbox }),
+    });
+    const d = await res.json().catch(() => ({}));
+    if (res.status !== 201 || !d.hmacSecret) throw new Error(`attach ${row.handle} at ${origin}: HTTP ${res.status}${d.error ? ' ' + d.error : ''}`);
+    secrets[row.handle] = String(d.hmacSecret);
+    log(`attached @${row.handle}@${new URL(origin).host}`);
+  }
+  return { gateway: { front: origin, mode: 'trust', secrets }, handles: rows.map(r => r.handle) };
+}
+
+/**
+ * Let a Gateway keep the forum (or stop): every row, the categories first and
+ * the forum's own row last, because turning the forum's row on is what starts
+ * its first run, and that run wants every category kept already. Returns the
+ * keeper's WebID.
+ */
+export async function keepRows({ fetch: f, front, config, on = true }) {
+  const origin = String(front).replace(/\/+$/u, '');
+  const forumHandle = config.handle;
+  const handles = [...(config.categories || []).map(c => c.slug), forumHandle];
+  let keeper = null;
+  for (const handle of handles) {
+    const res = await f(`${origin}/api/keeper`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ handle, on, ...(handle === forumHandle ? {} : { forum: forumHandle }) }),
+    });
+    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;
+  }
+  return { keeper: on ? keeper : null, handles, on };
+}
+
+/**
+ * The forum's rules stated with the keeper's name beside the owner's (or
+ * without it): the containers and what they inherit. For a forum that has
+ * members and readers already, the host's own restatement (keep.mjs) also
+ * rewrites the reader lists; a forum just made has none.
+ */
+export async function nameKeeperInRules(remote, { config, plain, keeper = null, ownerWebId = null }) {
+  remote.keepers = keeper ? [keeper] : [];
+  remote.aclOwner = ownerWebId || remote.aclOwner || null;
+  await provisionForum(remote, plain, { moderatorWebIds: config.moderatorWebIds || [] });
+  await restateRules(remote, plain);
+  for (const c of config.categories || []) {
+    const urls = plain.category(c.slug);
+    const members = (config.membersOnly || []).includes(c.slug) ? (config.memberWebIds?.[c.slug] || []) : null;
+    await provisionCategory(remote, urls, { memberWebIds: members });
+    await restateRules(remote, urls);
+  }
+}
+
+/**
+ * A forum made at a Gateway's sign-up page, start to finish: config and
+ * containers on the pod, its rows at the Gateway, the Gateway named as its
+ * keeper in every rule, and the keeper's first run started by the last
+ * switch. `remote` is the owner's pod transport, `fetch` their pod session's
+ * fetch (the Gateway proves the owner by it). Returns the forum's handle and
+ * the Gateway it lives at.
+ */
+export async function setUpForumAtGateway({ remote, storageFor, fetch: f, front, ownerWebId, ...opts }, { log = () => {}, onStep = () => {} } = {}) {
+  // `onStep(key, state)`: write, attach, keep; running then ok.
+  onStep('write', 'running');
+  const { storage, config, plain } = await writeForumConfig(remote, storageFor, opts, { log });
+  onStep('write', 'ok');
+  onStep('attach', 'running');
+  const { gateway, handles } = await attachRows({ fetch: f, front, config, plain }, { log });
+  await writeConfig(storage, { ...config, gateway, republish: true });
+  onStep('attach', 'ok');
+  onStep('keep', 'running');
+  const { keeper } = await keepRows({ fetch: f, front, config, on: true });
+  await nameKeeperInRules(remote, { config, plain, keeper, ownerWebId });
+  onStep('keep', 'ok');
+  return { handle: config.handle, front: gateway.front, handles, keeper };
+}