fedipod-server 0.9.0 → 0.11.0

package/lib/publisher.mjs

@@ -1,14 +1,27 @@
-// publisher.mjs — builds/maintains the actor's public face on the remote pod
-// (webfinger, actor doc, collections, notes) and mirrors truth into the local
-// pod. The remote /ap/ tree is disposable: publishProfile() rebuilds it.
+// publisher.mjs — builds/maintains the actor's public face on the remote pod:
+// webfinger, actor doc, collections, notes. The /ap/ tree is disposable:
+// publishProfile() rebuilds it.
 
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as wire from './wire.mjs';
+import * as polls from './polls.mjs';
 import { USER_AGENT } from './ua.mjs';
 import { HTTP_TIMEOUT_MS } from './safefetch.mjs';
+import * as containers from './pod/containers.mjs';
+import * as discovery from './pod/discovery.mjs';
+import * as podActor from './pod/actor.mjs';
+import * as podInbox from './pod/inbox.mjs';
+import * as podOutbox from './pod/outbox.mjs';
+import * as podFollowers from './pod/followers.mjs';
+import * as podFollowing from './pod/following.mjs';
+import * as podFeatured from './pod/featured.mjs';
+import * as podPrivate from './pod/private.mjs';
+import * as podPolicy from './pod/policy.mjs';
+import * as podNotes from './pod/notes.mjs';
+import * as podMedia from './pod/media.mjs';
 
 const ACCEPT_AP = 'application/activity+json, application/ld+json; profile="https://www.w3.org/ns/activitystreams"';
 // The default for publishCollections: the whole public surface, ACLs included.
@@ -16,18 +29,22 @@ const ACCEPT_AP = 'application/activity+json, application/ld+json; profile="http
 // still gets everything, so a missed call site degrades to the old cost rather
 // than silently publishing nothing.
 const REBUILD_MAX_PER_RUN = 200;
+// How long a poll gathers votes before its Question is rewritten. Every vote
+// changes a number other servers re-read, and rewriting per vote would make a
+// busy poll a steady write stream against the pod. A burst costs one rewrite
+// and one Update instead.
+const POLL_REWRITE_MS = 10_000;
 const ALL_COLLECTIONS = { followers: true, following: true, outbox: true, acls: true,
   pending: true, blocked: true };
 const AGENT_VERSION = JSON.parse(fs.readFileSync(
   path.join(path.dirname(fileURLToPath(import.meta.url)), '../package.json'), 'utf8')).version;
 
 export class Publisher {
-  constructor({ config, remote, local, store, deliverer, publicKeyPem, assertionKey = null, log = console.log,
-    probeFetch = null, resolveMention = null, privateOnPod = true, clientOrigin = null,
+  constructor({ config, remote, store, deliverer, publicKeyPem, assertionKey = null, log = console.log,
+    probeFetch = null, resolveMention = null, clientOrigin = null,
   }) {
     this.config = config;
     this.remote = remote;
-    this.local = local;
     this.store = store;
     this.deliverer = deliverer;
     this.publicKeyPem = publicKeyPem;
@@ -47,7 +64,8 @@ export class Publisher {
     // socket opened to that pod. Tests inject their own.
     this.probeFetch = probeFetch || ((u, i) => this.remote.probe(u, i));
     this.resolveMention = resolveMention;
-    this.privateOnPod = privateOnPod;
+    // Per-poll rewrite windows, keyed by question id. See POLL_REWRITE_MS.
+    this.pollTimers = new Map();
     this.log = log;
   }
 
@@ -110,34 +128,25 @@ export class Publisher {
       return { unreachable: [], updated: 0, skipped: true };
     }
 
-    await this.remote.putJson(urls.webfinger,
-      wire.jrd({ handle: this.config.handle, host, actor: urls.actor }), 'application/jrd+json');
-    await this.remote.setAcl(urls.webfinger, ['Read']);
+    await discovery.writeWebfinger(this.remote, urls,
+      wire.jrd({ handle: this.config.handle, host, actor: urls.actor }));
+    await discovery.writeHostMeta(this.remote, urls, wire.hostMeta(urls.base));
 
-    const hostMetaUrl = urls.base + '.well-known/host-meta';
-    await this.remote.put(hostMetaUrl, wire.hostMeta(urls.base), 'application/xrd+xml');
-    await this.remote.setAcl(hostMetaUrl, ['Read']);
-
-    // NodeInfo: pointer at the protocol-required root, document in our tree.
     const nodeinfoDocUrl = urls.home + 'ap/nodeinfo-2.0';
     const localPosts = this.store.getStatuses().filter(s => s.kind === 'post').length;
-    await this.remote.putJson(urls.base + '.well-known/nodeinfo',
-      wire.nodeinfoPointer(nodeinfoDocUrl), 'application/json');
-    await this.remote.setAcl(urls.base + '.well-known/nodeinfo', ['Read']);
-    await this.remote.putJson(nodeinfoDocUrl,
-      wire.nodeinfoDoc({ version: AGENT_VERSION, localPosts }), 'application/json');
-    await this.remote.setAcl(nodeinfoDocUrl, ['Read']);
+    await discovery.writeNodeinfo(this.remote, urls, {
+      pointer: wire.nodeinfoPointer(nodeinfoDocUrl),
+      doc: wire.nodeinfoDoc({ version: AGENT_VERSION, localPosts }),
+    });
 
     const actor = actorDoc;                 // built above, for the digest
-    await this.remote.putJson(urls.actor, actor);
-    await this.remote.setAcl(urls.actor, ['Read']);
+    await podActor.write(this.remote, urls, actor);
 
     // FEP-1b12: the moderator roster, public — it is what a recipient
     // validates a group's announced moderation against.
     if (moderators) {
-      await this.remote.putJson(urls.moderators,
+      await podFeatured.writeModerators(this.remote, urls,
         wire.orderedCollection(urls.moderators, this.config.moderators));
-      await this.remote.setAcl(urls.moderators, ['Read']);
     }
     // The gateway policy doc: the PUBLIC data a keyless gateway reads to decide
     // what concerns this identity. Written only while a gateway is advertised.
@@ -145,20 +154,19 @@ export class Publisher {
 
     // The human half: a page a browser can open and follow from. The actor
     // document is for servers; this is the address you hand to a person.
-    await this.remote.put(urls.profileHtml, wire.profilePageHtml({
+    await podActor.writeProfilePage(this.remote, urls, wire.profilePageHtml({
       name: this.config.name || this.config.handle,
       address: wire.webfingerHost(urls.base) ? `@${this.config.handle}@${host}` : urls.actor,
       summary: this.config.summary ? wire.contentHtml(this.config.summary) : null,
       icon: this.config.icon || null,
       kind: this.config.kind,
-    }), 'text/html');
-    await this.remote.setAcl(urls.profileHtml, ['Read']);
+    }));
 
     // WebID → actor: the profile card lists the actor as a foaf:account.
     // Best-effort — a profile that cannot be read or edited does not stop the
     // publish, it is logged and the rest of the surface still goes up.
     try {
-      const wrote = await this.remote.linkAccountInProfile({
+      const wrote = await podActor.linkInWebIdProfile(this.remote, {
         actorUrl: urls.actor,
         accountName: `@${this.config.handle}@${host}`,
         kind: this.config.kind,
@@ -171,21 +179,15 @@ export class Publisher {
     // inbox: public may only Append; owner (the agent) reads + drains. A
     // quiesced actor keeps its name resolving but takes no more mail, so a
     // republish must not re-open the door.
-    await this.remote.putJson(urls.inbox + '.keep', { keep: true }, 'application/json');
-    if (this.config.quiescedAt) {
-      await this.remote.setAcl(urls.inbox, []);
-      this.log('inbox left closed — this actor is quiesced');
-    } else {
-      await this.remote.setAcl(urls.inbox, ['Append']);
-    }
+    await podInbox.writeKeep(this.remote, urls);
+    await podInbox.setPosture(this.remote, urls, this.config.quiescedAt ? 'closed' : 'open');
+    if (this.config.quiescedAt) this.log('inbox left closed — this actor is quiesced');
 
     // notes live under a public-Read container (acl:default covers new notes).
-    await this.remote.putJson(urls.notes + '.keep', { keep: true }, 'application/json');
-    await this.remote.setAcl(urls.notes, ['Read']);
+    await podNotes.provisionContainer(this.remote, urls);
 
     await this.publishCollections({ ...ALL_COLLECTIONS, force });
     const updated = await this.announceProfileChange(actor, { force });
-    await this.local.writeSettings({ handle: this.config.handle, actorUrl: urls.actor });
     await this.ensurePrivateAcls();
     const unreachable = await this.verifyPublicSurface();
     // Last, and merged: announceProfileChange writes this document too.
@@ -272,23 +274,14 @@ export class Publisher {
   // this runs on every connect: probe UNauthenticated, rewrite whatever
   // answers, and say so loudly if the rewrite does not take.
   async ensurePrivateAcls() {
-    // Only trees that are actually ON the pod. With the default local
-    // privateRoot the fediverse tree lives on disk, so probing it was a request
-    // that could only ever 404, on every start.
-    const onPod = [this.urls.home, this.urls.state,
-      ...(this.privateOnPod === false ? [] : [this.urls.fediverse])];
-    for (const url of onPod) {
-      if (!await this.publiclyReadable(url)) continue;
-      this.log(`${url} was readable without credentials — rewriting its ACL`);
-      try {
-        await this.remote.setAcl(url, []);
-      } catch (e) {
-        this.log(`SECURITY: ${url} is public and its ACL could not be rewritten: ${e.message}`);
-        continue;
-      }
-      if (await this.publiclyReadable(url)) {
-        this.log(`SECURITY: ${url} is STILL readable without credentials — check the pod's ACLs`);
-      }
+    const findings = await containers.repairPrivateAcls(this.remote,
+      [this.urls.home, this.urls.state],
+      { isPublic: (u) => this.publiclyReadable(u) });
+    // What a finding MEANS is ours to say; the library just reports.
+    for (const f of findings) {
+      this.log(`${f.url} was readable without credentials — rewriting its ACL`);
+      if (f.error) { this.log(`SECURITY: ${f.url} is public and its ACL could not be rewritten: ${f.error}`); continue; }
+      if (f.stillPublic) this.log(`SECURITY: ${f.url} is STILL readable without credentials — check the pod's ACLs`);
     }
   }
 
@@ -296,14 +289,9 @@ export class Publisher {
   // accept: */* matters — asking for turtle makes the server answer 501 on the
   // JSON documents (webfinger, actor), which reads as "unreachable" when the
   // world can in fact see them perfectly well.
-  async publiclyReadable(url) {
-    try {
-      const res = await this.probeFetch(url, {
-        headers: { accept: '*/*', 'user-agent': USER_AGENT },
-        signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
-      });
-      return res.status < 400;
-    } catch { return false; }     // unreachable is not a finding here
+  publiclyReadable(url) {
+    return containers.probePublicReadability(this.probeFetch, url,
+      { headers: { 'user-agent': USER_AGENT }, timeoutMs: HTTP_TIMEOUT_MS });
   }
 
   // Retire this identity for good: tell everyone who follows us to drop the
@@ -318,8 +306,7 @@ export class Publisher {
     const inboxes = [...new Set(contacts.followers.map(f => f.sharedInbox || f.inbox).filter(Boolean))];
     const deletedAt = new Date().toISOString();
     await this.deliverer.deliverToAll(inboxes, wire.deleteActorActivity(urls, Date.parse(deletedAt)));
-    await this.remote.putJson(urls.actor, wire.tombstoneDoc(urls, deletedAt, this.config.kind));
-    await this.remote.setAcl(urls.actor, ['Read']);      // a Tombstone must stay fetchable
+    await podActor.writeTombstone(this.remote, urls, wire.tombstoneDoc(urls, deletedAt, this.config.kind));
     this.store.setConfig({ ...this.store.getConfig(), retiredAt: deletedAt });
     await this.store.flush();
     this.log(`retired: Delete sent to ${inboxes.length} inbox(es), actor replaced with a Tombstone`);
@@ -330,7 +317,7 @@ export class Publisher {
   // 401 rather than a 201 into storage nobody will ever drain. WebFinger,
   // host-meta and the actor stay published, so the handle still resolves.
   async closeInbox() {
-    await this.remote.setAcl(this.urls.inbox, []);
+    await podInbox.setPosture(this.remote, this.urls, 'closed');
     const at = new Date().toISOString();
     this.store.setConfig({ ...this.store.getConfig(), quiescedAt: at });
     await this.store.flush();
@@ -340,7 +327,7 @@ export class Publisher {
 
   // Undo closeInbox: mail flows again and the actor is no longer quiesced.
   async openInbox() {
-    await this.remote.setAcl(this.urls.inbox, ['Append']);
+    await podInbox.setPosture(this.remote, this.urls, 'open');
     const { quiescedAt, ...rest } = this.store.getConfig() || {};
     this.store.setConfig(rest);
     this.config.quiescedAt = undefined;
@@ -352,7 +339,7 @@ export class Publisher {
   // the pod except through the gateway's verify-at-the-door. Reversible with
   // openInbox (public-Append) — the one-call rollback.
   async lockInboxToGateway(gatewayWebId) {
-    await this.remote.setAcl(this.urls.inbox, [], { appendAgents: [gatewayWebId] });
+    await podInbox.setPosture(this.remote, this.urls, { gatewayWebId });
     this.log(`inbox locked to gateway ${gatewayWebId} — public delivery is refused`);
   }
 
@@ -366,7 +353,7 @@ export class Publisher {
     await this.deliverer.deliverToAll(inboxes, wire.moveActivity(urls, target, Date.parse(at)));
     this.config.movedTo = target;                       // so the republish below carries it
     this.store.setConfig({ ...this.store.getConfig(), movedTo: target, movedAt: at });
-    await this.remote.putJson(urls.actor, wire.actorDoc({
+    await podActor.writeMoved(this.remote, urls, wire.actorDoc({
       urls, handle: wire.publicHandle(this.config), name: this.config.name,
       publicKeyPem: this.publicKeyPem, movedTo: target, kind: this.config.kind,
       approveJoins: wire.followsNeedApproval(this.config),
@@ -376,7 +363,6 @@ export class Publisher {
       webId: this.remote.webId || null,
       aliases: this.config.aliases || [],
     }));
-    await this.remote.setAcl(urls.actor, ['Read']);
     await this.store.flush();
     this.log(`moved to ${target}: Move sent to ${inboxes.length} inbox(es), actor now advertises movedTo`);
     return { inboxes: inboxes.length, target, movedAt: at };
@@ -500,8 +486,7 @@ export class Publisher {
       // `-replies` — plus a `.keep`. Which is which is settled by reading the
       // document below, not by its name: a slug is a date and eight hex
       // characters and says nothing about what it holds.
-      for (const child of await this.remote.listContainer(urls.notes).catch(() => [])) {
-        if (/(-create|-replies|\/\.keep)$/.test(child.url)) continue;
+      for (const child of await podNotes.list(this.remote, urls).catch(() => [])) {
         ids.add(child.url);
       }
       indexed = true;
@@ -520,7 +505,7 @@ export class Publisher {
       if (budget <= 0) { this.log(`rebuild: stopping at ${REBUILD_MAX_PER_RUN} this run — run it again for the rest`); break; }
       if (have.has(id) || removed.has(id)) continue;
       budget--;
-      const note = await this.remote.getJson(id).catch(() => null);
+      const note = await podNotes.read(this.remote, id).catch(() => null);
       if (note?.type !== 'Note' || note.id !== id || note.attributedTo !== urls.actor) continue;
       const attachments = wire.attachmentsOf(note);
       const mentions = (Array.isArray(note.tag) ? note.tag : [])
@@ -552,31 +537,18 @@ export class Publisher {
     }
     if (!recovered.length && !reblogs) return { indexed: ids.size, recovered: 0, reblogs: 0, landed: true };
 
-    // Written whole and sorted, the way backfillStatuses does it: addStatus
-    // unshifts and fires the streaming event, so a loop of it would arrive
-    // backwards and push every recovered post at connected clients as new.
+    // Written whole and sorted: addStatus unshifts and fires the streaming
+    // event, so a loop of it would arrive backwards and push every recovered
+    // post at connected clients as new.
     merged.sort((a, b) => String(b.published || '').localeCompare(String(a.published || '')));
     const kept = merged.slice(0, 1000);
     this.store.write('statuses.json', kept);
     const landed = await this.store.commit();
 
-    // The RDF mirror is the other thing a lost machine took with it, and it is
-    // what backfillStatuses reads on a fresh state. Best effort: a post in
-    // statuses.json is already the recovery that matters.
-    let rdf = 0;
-    for (const s of recovered) {
-      try {
-        await this.local.writeNote('posts', s.slug, {
-          noteId: s.noteId, actor: s.actor, published: s.published,
-          content: s.content, inReplyTo: s.inReplyTo, attachments: s.attachments,
-        });
-        rdf++;
-      } catch (e) { this.log(`rebuild: RDF for ${s.slug} not written (${e.message})`); }
-    }
     this.log(`rebuilt ${recovered.length} post(s) and ${reblogs} boost(s) from the pod`
       + `${landed ? '' : ' — THE STATE WRITE DID NOT LAND'}`);
     return {
-      indexed: ids.size, recovered: recovered.length, reblogs, rdf, landed,
+      indexed: ids.size, recovered: recovered.length, reblogs, landed,
       dropped: Math.max(0, merged.length - kept.length),
     };
   }
@@ -624,8 +596,8 @@ export class Publisher {
       const digest = crypto.createHash('sha256').update(JSON.stringify(doc)).digest('hex').slice(0, 16);
       after[n] = digest;
       if (before[n] === digest) continue;                // sealed and unchanged
-      await this.remote.putJson(wire.outboxPageId(urls.outbox, n), doc);
-      if (!before[n] || acls) await this.remote.setAcl(wire.outboxPageId(urls.outbox, n), ['Read']);
+      await podOutbox.writePage(this.remote, wire.outboxPageId(urls.outbox, n), doc,
+        { publicRead: !before[n] || acls });
       wrote++;
     }
     // Pages above the new count are orphans: the outbox shrank past them, and
@@ -635,13 +607,12 @@ export class Publisher {
     const stale = Object.keys(seen.outboxPages || {}).map(Number)
       .filter(n => Number.isFinite(n) && n > pages.length);
     for (const n of stale) {
-      await this.remote.delete(wire.outboxPageId(urls.outbox, n)).catch(() => {});
+      await podOutbox.dropPage(this.remote, wire.outboxPageId(urls.outbox, n));
     }
     // The head carries totalItems, so it moves whenever the outbox does. Four
     // lines, and constant however much you have posted.
-    await this.remote.putJson(urls.outbox,
-      wire.outboxHead(urls.outbox, outbox.length, pages.length));
-    if (acls) await this.remote.setAcl(urls.outbox, ['Read']);
+    await podOutbox.writeHead(this.remote, urls,
+      wire.outboxHead(urls.outbox, outbox.length, pages.length), { publicRead: acls });
     this.store.write('published.json',
       { ...this.store.read('published.json', {}), outboxPages: after, outboxIndex: index });
     return wrote;
@@ -651,22 +622,7 @@ export class Publisher {
   // the flat collection this used to write, so an actor published before paging
   // is still readable — which matters because rebuild reads this to recover
   // posts a lost machine no longer has.
-  async readPublishedOutbox() {
-    const head = await this.remote.getJson(this.urls.outbox).catch(() => null);
-    if (!head) return null;
-    if (Array.isArray(head.orderedItems) && head.orderedItems.length) return head.orderedItems;
-    const items = [];
-    let next = head.first;
-    const seen = new Set();
-    while (next && !seen.has(next) && items.length < 10_000) {
-      seen.add(next);
-      const page = await this.remote.getJson(next).catch(() => null);
-      if (!page) break;
-      items.push(...(page.orderedItems || []));
-      next = page.next;
-    }
-    return items;
-  }
+  readPublishedOutbox() { return podOutbox.readPublished(this.remote, this.urls); }
 
   // The followers collection, paged like the outbox: a head that carries only
   // the count and the page bounds, and page documents holding the actor IRIs —
@@ -687,19 +643,18 @@ export class Publisher {
       const digest = crypto.createHash('sha256').update(JSON.stringify(doc)).digest('hex').slice(0, 16);
       after[n] = digest;
       if (before[n] === digest) continue;                // unchanged page
-      await this.remote.putJson(wire.followersPageId(urls.followers, n), doc);
-      if (!before[n] || acls) await this.remote.setAcl(wire.followersPageId(urls.followers, n), ['Read']);
+      await podFollowers.writePage(this.remote, wire.followersPageId(urls.followers, n), doc,
+        { publicRead: !before[n] || acls });
     }
     // Pages the collection shrank past would keep serving names that no longer
     // follow; the head stops pointing at them but the URL is guessable.
     const stale = Object.keys(seen.followersPages || {}).map(Number)
       .filter(n => Number.isFinite(n) && n > pages.length);
     for (const n of stale) {
-      await this.remote.delete(wire.followersPageId(urls.followers, n)).catch(() => {});
+      await podFollowers.dropPage(this.remote, wire.followersPageId(urls.followers, n));
     }
-    await this.remote.putJson(urls.followers,
-      wire.followersHead(urls.followers, actors.length, pages.length));
-    if (acls) await this.remote.setAcl(urls.followers, ['Read']);
+    await podFollowers.writeHead(this.remote, urls,
+      wire.followersHead(urls.followers, actors.length, pages.length), { publicRead: acls });
     this.store.write('published.json',
       { ...this.store.read('published.json', {}), followersPages: after, followersIndex: index });
   }
@@ -707,23 +662,7 @@ export class Publisher {
   // Every actor in the published followers collection, walking pages. Also reads
   // the flat collection this used to write, so an actor published before paging
   // still reconciles.
-  async readPublishedFollowers() {
-    const head = await this.remote.getJson(this.urls.followers).catch(() => null);
-    if (!head) return null;
-    if (Array.isArray(head.orderedItems) && head.orderedItems.length) return head.orderedItems;
-    if (Array.isArray(head.items) && head.items.length) return head.items;
-    const items = [];
-    let next = head.first;
-    const seen = new Set();
-    while (next && !seen.has(next) && items.length < 100_000) {
-      seen.add(next);
-      const page = await this.remote.getJson(next).catch(() => null);
-      if (!page) break;
-      items.push(...(page.orderedItems || []));
-      next = page.next;
-    }
-    return items;
-  }
+  readPublishedFollowers() { return podFollowers.readPublished(this.remote, this.urls); }
 
   async publishCollections(which = ALL_COLLECTIONS) {
     const { urls } = this;
@@ -740,9 +679,9 @@ export class Publisher {
       await this.publishFollowers(actors, { acls: which.acls, force: which.force });
     }
     if (which.following) {
-      await this.remote.putJson(urls.following,
-        wire.orderedCollection(urls.following, contacts.following.filter(f => f.accepted).map(f => f.actor)));
-      if (which.acls) await this.remote.setAcl(urls.following, ['Read']);
+      await podFollowing.write(this.remote, urls,
+        wire.orderedCollection(urls.following, contacts.following.filter(f => f.accepted).map(f => f.actor)),
+        { publicRead: which.acls });
     }
     if (which.pending) await this.publishPending();
     if (which.blocked) await this.publishBlocked();
@@ -758,7 +697,6 @@ export class Publisher {
       if (which.force || !Array.isArray(known)) await this.reconcileOutbox(outbox);
       await this.publishOutbox(outbox, { acls: which.acls, force: which.force });
     }
-    if (which.followers || which.following) await this.local.writeContacts(contacts);
   }
 
   // FEP-4ccd: the follows in limbo, as owner-only collections of the Follow
@@ -770,13 +708,13 @@ export class Publisher {
     if (await this.privateReady() !== true) return;
     const { urls } = this;
     const contacts = this.store.getContacts();
-    await this.remote.putJson(urls.pendingFollowers, wire.orderedCollection(
-      urls.pendingFollowers,
-      this.store.getRequests().filter(r => r.activity && !r.bsky).map(r => r.activity)));
-    await this.remote.putJson(urls.pendingFollowing, wire.orderedCollection(
-      urls.pendingFollowing,
-      contacts.following.filter(f => !f.accepted && f.followActivity)
-        .map(f => f.followActivity).reverse()));
+    await podPrivate.writePending(this.remote, urls, {
+      followers: wire.orderedCollection(urls.pendingFollowers,
+        this.store.getRequests().filter(r => r.activity && !r.bsky).map(r => r.activity)),
+      following: wire.orderedCollection(urls.pendingFollowing,
+        contacts.following.filter(f => !f.accepted && f.followActivity)
+          .map(f => f.followActivity).reverse()),
+    });
   }
 
   // The gateway policy: a small PUBLIC document a keyless inbox gateway reads
@@ -789,7 +727,7 @@ export class Publisher {
     const { urls } = this;
     const contacts = this.store.getContacts();
     const bl = this.store.getBlocklist();
-    await this.remote.putJson(urls.home + 'ap/gateway-policy.json', {
+    await podPolicy.write(this.remote, urls, {
       v: 1,
       actorUrl: urls.actor,
       followersUrl: urls.followers,
@@ -799,8 +737,7 @@ export class Publisher {
       kind: this.config.kind || 'person',
       following: contacts.following.filter(f => f.accepted && !f.bsky).map(f => f.actor),
       blocklist: { domains: bl.domains || [], actors: bl.actors || [] },
-    }, 'application/json');
-    await this.remote.setAcl(urls.home + 'ap/gateway-policy.json', ['Read']);
+    });
   }
 
   // FEP-c648: the blocked actors, as an owner-only collection. Actors only —
@@ -809,7 +746,7 @@ export class Publisher {
     if (await this.privateReady() !== true) return;
     const { urls } = this;
     const actors = [...(this.store.getBlocklist().actors || [])].reverse();
-    await this.remote.putJson(urls.blocked, wire.orderedCollection(urls.blocked, actors));
+    await podPrivate.writeBlocked(this.remote, urls, wire.orderedCollection(urls.blocked, actors));
   }
 
   // The outbox is the public record of everything this actor has said, boosts
@@ -844,19 +781,32 @@ export class Publisher {
 
   // Media container on the remote pod — public-Read like notes, created lazily
   // at first upload (idempotent; the flag only saves round-trips).
+  // Ask before writing. `_mediaReady` is per PROCESS, and a service worker is
+  // restarted whenever the browser feels like it — so on the browser build this
+  // re-created a container that has existed since sign-up, and rewrote its ACL,
+  // on every restart. A HEAD is one request and usually the only one.
   async ensureMediaContainer() {
     if (this._mediaReady) return;
-    await this.remote.putJson(this.urls.media + '.keep', { keep: true }, 'application/json');
-    await this.remote.setAcl(this.urls.media, ['Read']);
+    if (await containers.exists(this.remote, this.urls.media)) { this._mediaReady = true; return; }
+    await containers.provisionPublic(this.remote, this.urls.media);
     this._mediaReady = true;
   }
 
+  // Whether the canary this class writes is already there. Only a definite
+  // "yes" counts: anything else falls through to the write, which is
+  // idempotent anyway, so a failed probe costs a request and never correctness.
+  _containerExists(base) { return containers.exists(this.remote, base); }
+
   // The owner-only container that followers-only and direct posts live in.
   // Its ACL is set once; every note under it inherits.
   async ensurePrivateContainer() {
     if (this._privateContainer) return;
-    await this.remote.putJson(this.urls.privateNotes + '.keep', { keep: true }, 'application/json');
-    await this.remote.setAcl(this.urls.privateNotes, []);
+    // Same reasoning as ensureMediaContainer: probe before provisioning, so a
+    // worker restart is not a re-provision. The ACL is NOT skipped on the
+    // strength of the container existing alone — ensurePrivateAcls re-checks
+    // that separately on every connect, which is the control that matters here.
+    if (await containers.exists(this.remote, this.urls.privateNotes)) { this._privateContainer = true; return; }
+    await containers.provisionOwnerOnly(this.remote, this.urls.privateNotes);
     this._privateContainer = true;
   }
 
@@ -873,9 +823,8 @@ export class Publisher {
       // fronted identity must map the advertised private container back to the
       // pod itself — the ACL we are testing is the pod's.
       const pn = this.urls.toPod ? this.urls.toPod(this.urls.privateNotes) : this.urls.privateNotes;
-      const r = await (this.probeFetch || fetch)(pn + '.keep', { redirect: 'manual' });
-      this._privateVerdict = (r.status === 401 || r.status === 403) ? true
-        : `this pod serves private documents to strangers (HTTP ${r.status}) — private posts stay off it`;
+      const verdict = await containers.probePrivateEnforcement(this.probeFetch || fetch, pn + '.keep');
+      this._privateVerdict = verdict === true ? true : `${verdict} — private posts stay off it`;
       return this._privateVerdict;
     } catch (e) {
       return `could not verify that the pod protects private posts (${e.message})`;
@@ -883,20 +832,13 @@ export class Publisher {
   }
 
   // Compose → wire note on remote pod + RDF truth locally + deliver Create.
-  async publishNote(content, { inReplyTo, attachments, visibility = 'public', spoilerText = null } = {}) {
-    const { urls } = this;
-    const priv = visibility === 'private' || visibility === 'direct';
-    if (priv) {
-      const ready = await this.privateReady();
-      if (ready !== true) throw new Error(ready);
-    }
-    const published = new Date().toISOString();
-    const slug = published.slice(0, 10) + '-' + crypto.randomBytes(4).toString('hex');
-    // A mention nobody can resolve stays plain text rather than failing the post.
-    // The reply's own text decides who is mentioned: trim a handle out and that
-    // person is not notified, which is what every fediverse client leads people
-    // to expect. A Group named in the parent is the one thing carried forward
-    // regardless — drop it and the group stops carrying the thread.
+  // Who this text mentions, resolved. A mention nobody can resolve stays plain
+  // text rather than failing the post. The text itself decides: trim a handle
+  // out and that person is not notified, which is what every fediverse client
+  // leads people to expect. A Group named in the parent is the one thing
+  // carried forward regardless — drop it and the group stops carrying the
+  // thread.
+  async _mentionsFor(content, inReplyTo) {
     const inText = new Set(wire.mentionsIn(content));
     const carried = inReplyTo
       ? (this.store.getStatuses().find(s => s.noteId === inReplyTo)?.mentions || [])
@@ -910,18 +852,29 @@ export class Publisher {
       if (!inText.has(handle) && doc.type !== 'Group') continue;   // author trimmed them out
       mentions.push({ handle, actor: doc.id, page: doc.url || null, inbox: doc.endpoints?.sharedInbox || doc.inbox });
     }
+    return mentions;
+  }
+
+  async publishNote(content, { inReplyTo, attachments, visibility = 'public', spoilerText = null } = {}) {
+    const { urls } = this;
+    const priv = visibility === 'private' || visibility === 'direct';
+    if (priv) {
+      const ready = await this.privateReady();
+      if (ready !== true) throw new Error(ready);
+    }
+    const published = new Date().toISOString();
+    const slug = published.slice(0, 10) + '-' + crypto.randomBytes(4).toString('hex');
+    const mentions = await this._mentionsFor(content, inReplyTo);
     const note = wire.noteDoc({ urls, slug, content, published, inReplyTo, attachments, mentions,
       visibility, summary: spoilerText, container: priv ? urls.privateNotes : urls.notes });
 
-    await this.remote.putJson(note.id, note);
+    await podNotes.write(this.remote, note.id, note);
     // Empty, but present: a dangling `replies` that 404s is worse than none.
-    await this.remote.putJson(wire.repliesId(note.id), wire.collection(wire.repliesId(note.id), []));
+    await podNotes.writeEmptyReplies(this.remote, wire.repliesId(note.id),
+      wire.collection(wire.repliesId(note.id), []));
     // The outbox is the PUBLIC index; a private or direct post is not in it.
     if (!priv) await this.recordOutbox(note.id);
 
-    await this.local.writeNote('posts', slug, {
-      noteId: note.id, actor: urls.actor, published, content: note.content, inReplyTo, attachments,
-    });
     this.store.addStatus({
       noteId: note.id, actor: urls.actor, content: note.content, published, inReplyTo,
       kind: 'post', slug, text: content, visibility,
@@ -934,7 +887,7 @@ export class Publisher {
     // Published as its own document: a group that carries this post wraps the
     // whole activity, and the receiving server resolves it by fetching this id.
     // It inherits the notes container's public-Read acl:default.
-    await this.remote.putJson(create.id, create);
+    await podNotes.writeCreate(this.remote, create.id, create);
     const contacts = this.store.getContacts();
     // A direct post goes to the people it names and to nobody else.
     const inboxes = [...new Set([
@@ -962,12 +915,234 @@ export class Publisher {
     return note;
   }
 
+  // --- polls ---------------------------------------------------------------
+  //
+  // A poll is published as a Question and answered by ordinary replies naming
+  // an option, so the count is ours to keep and ours to republish. The roster
+  // of who chose what lives in agent state (polls.VOTES_DOC); the tallies on
+  // the status row and in the pod document are always derived from it.
+
+  /**
+   * Publish a poll. `options` is a list of choice titles, `multiple` lets a
+   * voter pick more than one, and `expiresAt` is when voting stops.
+   */
+  async publishQuestion(content, { options = [], multiple = false, expiresAt = null,
+    inReplyTo = undefined, visibility = 'public', spoilerText = null } = {}) {
+    const { urls } = this;
+    const priv = visibility === 'private' || visibility === 'direct';
+    if (priv) {
+      const ready = await this.privateReady();
+      if (ready !== true) throw new Error(ready);
+    }
+    const titles = [].concat(options).map(o => String(o ?? '').trim()).filter(Boolean);
+    if (titles.length < 2) throw new Error('a poll needs at least two options');
+    // Options are matched BY NAME when a vote arrives — that is the whole of
+    // the convention — so two options reading the same are one option that
+    // cannot be told apart.
+    if (new Set(titles).size !== titles.length) throw new Error('a poll’s options must differ from one another');
+    // Bounded here as well as at the client API, because the outbox is a
+    // second way in and an unbounded poll is a document a stranger sizes.
+    if (titles.length > polls.MAX_OPTIONS) throw new Error(`a poll takes at most ${polls.MAX_OPTIONS} options`);
+    if (titles.some(t => t.length > polls.MAX_OPTION_CHARS)) {
+      throw new Error(`a poll option is at most ${polls.MAX_OPTION_CHARS} characters`);
+    }
+    if (expiresAt) {
+      const ends = Date.parse(expiresAt);
+      if (!Number.isFinite(ends)) throw new Error('the closing time is not a date');
+      const seconds = (ends - Date.now()) / 1000;
+      if (seconds < polls.MIN_SECONDS || seconds > polls.MAX_SECONDS) {
+        throw new Error(`a poll runs between ${polls.MIN_SECONDS} and ${polls.MAX_SECONDS} seconds`);
+      }
+    }
+
+    const published = new Date().toISOString();
+    const slug = published.slice(0, 10) + '-' + crypto.randomBytes(4).toString('hex');
+    const mentions = await this._mentionsFor(content, inReplyTo);
+    const poll = {
+      multiple: !!multiple,
+      expiresAt: expiresAt || null,
+      closed: null,
+      options: titles.map(title => ({ title, votes: 0 })),
+      votersCount: 0,
+      // Resolved once, here: a tally rewrite must not cost a webfinger lookup
+      // per vote for people the poll named.
+      mentionInboxes: [...new Set(mentions.map(m => m.inbox).filter(Boolean))],
+    };
+    const question = wire.questionDoc({
+      urls, slug, content, published, inReplyTo, attachments: [], mentions,
+      visibility, summary: spoilerText,
+      container: priv ? urls.privateNotes : urls.notes,
+      options: poll.options, multiple: poll.multiple, endTime: poll.expiresAt, votersCount: 0,
+    });
+
+    await podNotes.write(this.remote, question.id, question);
+    // Empty, but present: a dangling `replies` that 404s is worse than none.
+    await podNotes.writeEmptyReplies(this.remote, wire.repliesId(question.id),
+      wire.collection(wire.repliesId(question.id), []));
+    if (!priv) await this.recordOutbox(question.id);
+    this.store.addStatus({
+      noteId: question.id, actor: urls.actor, content: question.content, published,
+      kind: 'post', slug, text: content, visibility, poll, inReplyTo,
+      ...(spoilerText ? { spoiler: spoilerText } : {}),
+      ...(question.tag?.length ? { mentions: question.tag.map(t => ({ href: t.href, name: t.name })) } : {}),
+    });
+
+    const create = this._pollActivity('Create', question, wire.createActivityId(question.id));
+    await podNotes.writeCreate(this.remote, create.id, create);
+    const contacts = this.store.getContacts();
+    const inboxes = [...new Set([
+      ...(visibility === 'direct' ? [] : contacts.followers.map(f => f.sharedInbox || f.inbox)),
+      ...poll.mentionInboxes,
+    ].filter(Boolean))];
+    await this.deliverer.deliverToAll(inboxes, create);
+    this.log(`poll published: ${question.id} (${titles.length} options) → ${inboxes.length} inbox(es)`);
+    return question;
+  }
+
+  // The Create or Update carrying a Question. The context is hoisted onto the
+  // activity and the embedded object keeps none: a nested @context is legal
+  // JSON-LD but not every server reads one, and votersCount is declared there.
+  _pollActivity(type, question, id) {
+    const { '@context': ctx, ...object } = question;
+    return {
+      '@context': ctx, id, type,
+      actor: this.urls.actor,
+      published: question.published,
+      to: question.to, cc: question.cc,
+      object,
+    };
+  }
+
+  /**
+   * One vote on one of OUR polls, named by the option's title. Returns true
+   * when it counted — a second answer to a single-choice poll, an option we do
+   * not offer, or a poll that has closed all count for nothing.
+   */
+  async recordVote(questionId, actor, optionName) {
+    const s = this.store.getStatuses().find(x => x.noteId === questionId);
+    if (!s?.poll || s.kind !== 'post' || s.actor !== this.urls.actor) return false;
+    if (polls.pollClosed(s.poll)) return false;
+    const index = polls.optionIndex(s.poll, optionName);
+    if (index < 0) return false;
+    const all = this.store.read(polls.VOTES_DOC, {});
+    const { roster, changed } = polls.addVote(all[questionId] || {}, polls.voterKey(actor), index,
+      { multiple: !!s.poll.multiple });
+    if (!changed) return false;
+    this.store.write(polls.VOTES_DOC, { ...all, [questionId]: roster });
+    this.store.updateStatus(questionId, { poll: polls.withTally(s.poll, roster) });
+    this._pollDirty(questionId);
+    return true;
+  }
+
+  // Open the rewrite window for a poll whose count moved. Already open is
+  // already enough: the whole point is that a burst costs one rewrite.
+  _pollDirty(questionId) {
+    if (this.pollTimers.has(questionId)) return;
+    const t = setTimeout(() => {
+      this.pollTimers.delete(questionId);
+      this.republishPoll(questionId).catch(e => this.log(`poll rewrite: ${e.message}`));
+    }, POLL_REWRITE_MS);
+    t.unref?.();
+    this.pollTimers.set(questionId, t);
+  }
+
+  /**
+   * Write the poll's current count back to the pod and tell everyone who has
+   * it. `closing` stamps it shut, which is a one-way door.
+   */
+  async republishPoll(questionId, { closing = null } = {}) {
+    const s = this.store.getStatuses().find(x => x.noteId === questionId);
+    if (!s?.poll) return null;
+    const { urls } = this;
+    const roster = this.store.read(polls.VOTES_DOC, {})[questionId] || {};
+    // A shut poll whose roster has been retired keeps the counts on its row:
+    // deriving them from an empty roster would publish a poll nobody voted in.
+    const shut = closing || s.poll.closed;
+    const counted = shut && !Object.keys(roster).length ? s.poll : polls.withTally(s.poll, roster);
+    const poll = { ...counted, ...(closing ? { closed: closing } : {}) };
+    const container = String(s.noteId).startsWith(urls.privateNotes) ? urls.privateNotes : urls.notes;
+    const slug = s.slug || String(s.noteId).slice(container.length);
+    const mentions = (s.mentions || []).map(m => ({
+      handle: String(m.name || '').replace(/^@/, ''), actor: m.href, page: null, inbox: null,
+    }));
+    const question = wire.questionDoc({
+      urls, slug, content: s.text ?? '', published: s.published, inReplyTo: s.inReplyTo,
+      attachments: [], mentions,
+      visibility: s.visibility || 'public', summary: s.spoiler || null, container,
+      options: poll.options, multiple: !!poll.multiple, endTime: poll.expiresAt,
+      closed: poll.closed, votersCount: poll.votersCount || 0,
+    });
+    await podNotes.write(this.remote, question.id, question);
+    // The Create is overwritten too, so a group's Announce resolves to the
+    // current count rather than to the one the poll opened with.
+    await podNotes.writeCreate(this.remote, wire.createActivityId(question.id),
+      this._pollActivity('Create', question, wire.createActivityId(question.id)));
+    this.store.updateStatus(questionId, { poll });
+
+    // Not `updated`: a changed count is not an edit, and stamping one would
+    // have every client show the poll as edited each time somebody voted.
+    //
+    // The Update is named after the STATE it carries rather than the moment it
+    // was sent. A clock only tells two rewrites apart when they fall in
+    // different milliseconds, and a receiving server that has seen an activity
+    // id drops the next one wearing it — which would quietly freeze the count.
+    // Naming the state means an id changes exactly when there is something new
+    // to say, and two sends of the same numbers are the duplicate they look
+    // like.
+    const stamp = crypto.createHash('sha256').update(JSON.stringify([
+      poll.options.map(o => o.votes || 0), poll.votersCount || 0, poll.closed || '',
+    ])).digest('hex').slice(0, 12);
+    const update = this._pollActivity('Update', question, `${question.id}#poll-${stamp}`);
+    const contacts = this.store.getContacts();
+    const inboxes = [...new Set([
+      ...(s.visibility === 'direct' ? [] : contacts.followers.map(f => f.sharedInbox || f.inbox)),
+      ...(s.poll.mentionInboxes || []),
+    ].filter(Boolean))];
+    await this.deliverer.deliverToAll(inboxes, update);
+    this.log(`poll ${closing ? 'closed' : 'count published'}: ${question.id} → ${inboxes.length} inbox(es)`);
+    return poll;
+  }
+
+  /**
+   * Shut any poll whose time is up. Called from the agent's sweep. Closing is
+   * recorded BEFORE the republish, so a failed republish cannot leave a poll
+   * open and collecting votes it has already refused.
+   */
+  async closeDuePolls(now = Date.now()) {
+    const due = this.store.getStatuses().filter(s => s.kind === 'post' && s.poll
+      && !s.poll.closed && s.poll.expiresAt && Date.parse(s.poll.expiresAt) <= now);
+    for (const s of due) {
+      const closed = new Date(Math.min(now, Date.parse(s.poll.expiresAt) || now)).toISOString();
+      clearTimeout(this.pollTimers.get(s.noteId));
+      this.pollTimers.delete(s.noteId);
+      this.store.updateStatus(s.noteId, { poll: { ...s.poll, closed } });
+      const done = await this.republishPoll(s.noteId, { closing: closed })
+        .catch(e => { this.log(`poll close ${s.noteId}: ${e.message}`); return null; });
+      // The roster only ever answered one question — has this person already
+      // voted — and a shut poll has stopped asking it. Dropping it keeps a
+      // document we serialize whole from carrying every poll's voters forever.
+      if (done) {
+        const all = this.store.read(polls.VOTES_DOC, {});
+        if (all[s.noteId]) {
+          delete all[s.noteId];
+          this.store.write(polls.VOTES_DOC, all);
+        }
+      }
+    }
+    return due.length;
+  }
+
+  /** Stop the pending rewrite windows. Called at shutdown. */
+  stopPolls() {
+    for (const t of this.pollTimers.values()) clearTimeout(t);
+    this.pollTimers.clear();
+  }
+
   // The pinned posts, as the actor's featured collection — the one document a
   // remote server reads when it shows this profile's pins.
   async publishFeatured() {
     const ids = this.store.getStatuses().filter(s => s.kind === 'post' && s.pinned).map(s => s.noteId);
-    await this.remote.putJson(this.urls.featured, wire.orderedCollection(this.urls.featured, ids));
-    await this.remote.setAcl(this.urls.featured, ['Read']);
+    await podFeatured.write(this.remote, this.urls, wire.orderedCollection(this.urls.featured, ids));
     return ids.length;
   }
 
@@ -996,14 +1171,8 @@ export class Publisher {
       attachments: atts, mentions, visibility: s.visibility || 'public',
       summary: spoilerText, updated, container,
     });
-    await this.remote.putJson(note.id, note);
-    await this.remote.putJson(wire.createActivityId(note.id), wire.createActivity(note, urls));
-    if (s.slug) {
-      await this.local.writeNote('posts', s.slug, {
-        noteId: note.id, actor: urls.actor, published: s.published, content: note.content,
-        inReplyTo: s.inReplyTo, attachments: atts,
-      });
-    }
+    await podNotes.write(this.remote, note.id, note);
+    await podNotes.writeCreate(this.remote, wire.createActivityId(note.id), wire.createActivity(note, urls));
     const patched = this.store.updateStatus(s.noteId, {
       content: note.content, text: content, editedAt: updated,
       spoiler: spoilerText || undefined,