fedipod-bb 0.3.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fedipod-bb",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "FediPod-BB: a forum website whose record lives on a Solid pod.",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,7 @@
   "exports": {
     ".": "./src/index.mjs",
     "./gateway": "./src/gateway.mjs",
+    "./setup": "./src/setup.mjs",
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
@@ -26,7 +27,7 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "fedipod": "^1.43.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

@@ -31,6 +31,7 @@ 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';
@@ -131,39 +132,11 @@ 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) {
@@ -412,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

package/src/gateway.mjs

@@ -167,6 +167,12 @@ export async function keepOnce(ctx, handle, rec, { log = console.log, session =
       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(() => {}); }

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

@@ -6,23 +6,13 @@ 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 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;
-  }
+  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;

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 };
+}