fedipod 1.36.6 → 1.40.0

package/lib/gateway/gateway-core.mjs

@@ -63,6 +63,24 @@ function concernsUsAtEdge(activity, ident) {
   return !!inReplyTo && ident.notesPrefix && String(inReplyTo).startsWith(ident.notesPrefix);
 }
 
+// Whether a delivery becomes one of the account's notifications rather than
+// a post in its timeline: a follow, a like, boost or reaction to its own post,
+// or a post that names it — a mention, a reply to it, a direct message. Pure
+// addressing, like the check above; the drain decides for certain.
+export function notifies(activity, ident) {
+  const type = activity?.type;
+  if (type === 'Follow') return true;
+  const obj = typeof activity.object === 'object' ? activity.object : null;
+  const target = idOf(activity.object);
+  const ours = (u) => !!u && !!ident.notesPrefix && String(u).startsWith(ident.notesPrefix);
+  if (['Like', 'Announce', 'EmojiReact'].includes(type)) return ours(target);
+  if (type !== 'Create') return false;
+  const named = [].concat(activity.to || [], activity.cc || [], obj?.to || [], obj?.cc || []).map(idOf);
+  if (named.includes(ident.actorUrl)) return true;
+  if ([].concat(obj?.tag || []).some((t) => t?.type === 'Mention' && t.href === ident.actorUrl)) return true;
+  return ours(idOf(obj?.inReplyTo));
+}
+
 // Handle one inbound delivery. `request` is a WHATWG Request. `ident` is the
 // resolved identity policy: { inboxUrl, actorUrl, followersUrl, notesPrefix,
 // following, blocklist, kind, gatewayWebId, hmacSecret }. `podPut(url, body,
@@ -119,7 +137,8 @@ export async function handleDelivery(request, ident, { podPut, fetchImpl = fetch
   // holding any state.
   if (!okA) return { status: 502, reason: 'pod inbox write failed' };
   if (receipt) await inbox.writeReceiptBeside(podPut, ident.inboxUrl, hash, receipt);
-  return { status: 202, reason: v.verified ? 'verified' : 'buffered-unverified', content, bytes: Buffer.byteLength(raw) };
+  return { status: 202, reason: v.verified ? 'verified' : 'buffered-unverified', content, bytes: Buffer.byteLength(raw),
+    type: activity.type, notifies: notifies(activity, ident) };
 }
 
 // The outbox door: the owner's own post, taken on their behalf.
@@ -133,14 +152,15 @@ export async function handleDelivery(request, ident, { podPut, fetchImpl = fetch
 // client-to-server dispatcher, which publishes and delivers it — so the post
 // goes out when the agent next runs, the same way inbound mail is read.
 //
-// `slug` is the name the client asked for its new document. It rides in the
-// receipt so the dispatcher can use it, and it is what lets the door answer a
-// Location before anything exists: the object will live at notesPrefix+slug
-// unless that name is taken, in which case the agent mints another.
+// `slug` is the name of the new document — the client's, or one the door
+// chose — and `serial` and `at` name any other activity. They ride in the
+// receipt so the dispatcher uses them, and they are what let the door answer a
+// Location before anything exists. A name the client chose that is already
+// taken is the one case where the agent picks another.
 export const SLUG_OK = /^[A-Za-z0-9._-]{1,64}$/u;
 export const safeSlug = (s) => (typeof s === 'string' && SLUG_OK.test(s) && !/^\.+$/u.test(s) ? s : null);
 
-export async function handleOwnerPost(request, ident, { podPut, ownerWebId, maxBytes = DEFAULT_MAX_BYTES } = {}) {
+export async function handleOwnerPost(request, ident, { podPut, ownerWebId, maxBytes = DEFAULT_MAX_BYTES, exists = null } = {}) {
   if (!ident.hmacSecret) return { status: 409, reason: 'this account has no door secret — attach it again' };
   let raw;
   try { raw = await request.text(); } catch { return { status: 400, reason: 'unreadable body' }; }
@@ -150,16 +170,94 @@ export async function handleOwnerPost(request, ident, { podPut, ownerWebId, maxB
   if (!doc || typeof doc !== 'object' || Array.isArray(doc) || !doc.type) {
     return { status: 400, reason: 'a typed ActivityStreams object is required' };
   }
-  const slug = safeSlug(request.headers.get('slug'));
+  // A post that makes something new is named HERE, when the client did not
+  // name it, so the answer can give the address of what it made (§6: 201 with
+  // the new activity's id in Location) though nothing has been made yet.
+  // What the account would refuse is refused here, before the app is told
+  // "created" for something that will never exist.
+  const refusal = refusedAtTheDoor(doc, ident);
+  if (refusal) return { status: 422, reason: refusal };
+  const makes = doc.type === 'Create' || !ACTIVITY_TYPES.has(doc.type);
+  // A name the client asks for that is already taken is replaced here, so the
+  // address answered is the one the post gets.
+  let slug = safeSlug(request.headers.get('slug'));
+  if (slug && makes && exists && await exists(containerFor(doc, ident) + slug).catch(() => false)) slug = null;
+  if (!slug && makes) slug = mintSlug();
+  // Anything else is named the way the agent names it, from a serial and a
+  // time chosen here and handed over in the receipt.
+  // Two posts in the same millisecond still get different names.
+  const now = Date.now();
+  const serial = now * 1000 + crypto.randomInt(1000);
+  const at = new Date(now).toISOString();
+  const hash = sha256hex(raw);
+  // The receipt names the body it vouches for, so it vouches for nothing else,
+  // and the agent can tell the same body sent twice.
   const receipt = signReceipt({
     v: 1, verified: true, method: 'c2s', keyId: ownerWebId || null, actor: ident.actorUrl,
     checks: ['owner-token'], reason: 'owner', gateway: ident.gatewayWebId, ...(slug ? { slug } : {}),
+    serial, at, hash,
   }, ident.hmacSecret);
-  const hash = sha256hex(raw);
   const okA = await inbox.appendVerifiedDelivery(podPut, ident.inboxUrl, hash, raw);
   if (!okA) return { status: 502, reason: 'pod inbox write failed' };
   await inbox.writeReceiptBeside(podPut, ident.inboxUrl, hash, receipt);
-  return { status: 201, reason: 'accepted', location: slug && ident.notesPrefix ? ident.notesPrefix + slug : null };
+  if (makes) {
+    const object = slug && ident.notesPrefix ? containerFor(doc, ident) + slug : null;
+    return { status: 201, reason: 'accepted', object, location: object ? object + '-create' : null };
+  }
+  const object = typeof doc.object === 'string' ? doc.object : doc.object?.id || null;
+  return { status: 201, reason: 'accepted', object, location: activityIdFor(doc.type, object, ident, serial, at) };
+}
+
+// The id the agent gives each kind of activity (lib/core/wire.mjs): an edit by
+// its note and time, a deletion by its note, a boost and an undo as documents
+// in the posts folder, the rest by the actor and serial.
+const SERIAL_NAMED = new Set(['Like', 'Follow', 'Block', 'Add', 'Remove', 'Accept', 'Reject']);
+function activityIdFor(type, object, ident, serial, at) {
+  const actor = ident.actorUrl;
+  if ((type === 'Update' || type === 'Delete') && object && object !== actor) {
+    return type === 'Delete' ? object + '-delete' : object + '-update-' + at.replace(/[^0-9TZ]/g, '');
+  }
+  if ((type === 'Announce' || type === 'Undo') && ident.notesPrefix) return `${ident.notesPrefix}${type.toLowerCase()}-${serial}`;
+  return SERIAL_NAMED.has(type) ? `${actor}#${type.toLowerCase()}-${serial}` : null;
+}
+
+// The account's own changes are made on its manage page, and the one
+// collection a client may add to or take from is the pinned posts.
+function refusedAtTheDoor(doc, ident) {
+  const object = typeof doc.object === 'string' ? doc.object : doc.object?.id || null;
+  const target = typeof doc.target === 'string' ? doc.target : doc.target?.id || null;
+  if (doc.type === 'Move') return 'moving the account is done on its manage page';
+  if ((doc.type === 'Update' || doc.type === 'Delete') && object === ident.actorUrl) {
+    return 'the account itself is changed on its manage page';
+  }
+  if ((doc.type === 'Add' || doc.type === 'Remove') && target !== ident.actorUrl.replace(/actor$/u, 'featured')) {
+    return 'the pinned posts are the one collection an app may add to or take from';
+  }
+  return null;
+}
+
+// The activity types §6 names; anything else with a type is an object the
+// agent wraps in a Create. The same list the dispatcher keeps (lib/client/c2s.mjs).
+const ACTIVITY_TYPES = new Set([
+  'Create', 'Update', 'Delete', 'Follow', 'Like', 'Announce', 'Undo',
+  'Block', 'Add', 'Remove', 'Accept', 'Reject', 'Move',
+]);
+
+// The name the agent would have chosen itself: the day and eight hex characters.
+const mintSlug = () => new Date().toISOString().slice(0, 10) + '-' + crypto.randomBytes(4).toString('hex');
+
+// Where the agent will keep it: public and unlisted posts under notes/, posts
+// for followers or named people under private/ — decided by the addressing,
+// read the way the dispatcher reads it (nothing stated is public).
+const PUBLIC_NAMES = new Set(['https://www.w3.org/ns/activitystreams#Public', 'as:Public', 'Public']);
+function containerFor(doc, ident) {
+  const object = doc.type === 'Create' && doc.object && typeof doc.object === 'object' ? doc.object : doc;
+  const list = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]).map(x => (typeof x === 'string' ? x : x?.id));
+  const to = list(doc.to ?? object.to);
+  const cc = list(doc.cc ?? object.cc);
+  const blind = list(doc.bto ?? object.bto).length + list(doc.bcc ?? object.bcc).length;
+  const open = (!to.length && !cc.length && !blind) || [...to, ...cc].some(a => PUBLIC_NAMES.has(a));
+  return open ? ident.notesPrefix : ident.notesPrefix.replace(/ap\/notes\/$/u, 'ap/private/');
 }
 
 export const _internal = { isBlocked, concernsUsAtEdge, httpUrl, sha256hex };

package/lib/gateway/held-mail.mjs

@@ -0,0 +1,198 @@
+// held-mail.mjs — a browser account's mail, held at the gateway while its
+// owner's app is closed, and handed to the pod as one batch.
+//
+// Every delivery the door takes is two writes into the owner's pod inbox, and
+// the drain then reads and deletes both: six pod requests a piece. While the
+// app is closed nobody reads it, so the door keeps it here instead
+// (ctx.holdMail), and writes it to the pod inbox as one document when the app
+// says it is open (POST /api/here) or when the timer comes round (flushAll).
+// While the app is open, mail goes straight to the pod as it always has.
+//
+// A batch is plain JSON, `{ "batch": [ { name, body, receipt } ] }`: `name` is
+// what the item would have been called in the inbox, `body` its bytes, and
+// `receipt` the door's receipt for it, or null. The drain reads it
+// (lib/core/intake: batch documents).
+//
+// ctx, when the deploy holds mail:
+//   holdMail(handle, name, body, ct)   keep one inbox item
+//   listHeld(handle) -> [name]         what is kept for an account
+//   readHeld(handle, name) -> string   one kept item
+//   dropHeld(handle, name)             let one go
+//   heldAccounts() -> [handle]         every account with something kept
+//   markPresent(handle)                the owner's app says it is open
+//   presentAt(handle) -> ms            when it last said so
+//   noteNext(handle, at, {earliest})   when the account's keeper next has work
+
+import { copyMeta, keptNow } from './copy.mjs';
+
+// The app says it is open every five minutes; a little over that counts.
+export const PRESENT_MS = 8 * 60_000;
+// Entries per batch document, so a long backlog is a few documents, not one
+// the drain cannot read.
+export const BATCH_MAX = 100;
+const RECEIPT = '.receipt.json';
+
+const inboxOf = (rec) => rec.inboxUrl || rec.podHome + 'ap/inbox/';
+
+// Only a browser account is held: its owner signs in (so the row has
+// `openedAt`), and its app says when it is open. An account run by a DeviceAgent
+// drains whenever mail lands, and keeps its mail as it always has.
+export const holdsMail = (ctx, rec) => !!(ctx.holdMail && rec?.openedAt);
+
+// Asked on every delivery, so it is remembered a minute per running copy.
+const seen = new Map();   // handle -> { at, asked }
+export async function isPresent(ctx, handle, now = Date.now()) {
+  const had = seen.get(handle);
+  if (had && now - had.asked < 60_000) return !!had.at && now - had.at < PRESENT_MS;
+  const at = Number(await ctx.presentAt?.(handle).catch(() => 0)) || 0;
+  if (seen.size > 10_000) seen.clear();
+  seen.set(handle, { at, asked: now });
+  return !!at && now - at < PRESENT_MS;
+}
+
+// The door's put while the app is closed: the same name the pod would have
+// given the item, kept here instead.
+export const holdingPut = (ctx, handle, rec) => async (url, body, ct) => {
+  const name = url.slice(inboxOf(rec).length);
+  await ctx.holdMail(handle, name, body, ct);
+  return true;
+};
+
+/**
+ * What is held for one account, each delivery with its receipt:
+ * [{ name, body, receipt, held: [the held names it came from] }]. A receipt
+ * whose delivery is not here has nothing to vouch for, and is let go.
+ */
+export async function heldEntries(ctx, handle) {
+  const names = await ctx.listHeld(handle);
+  if (!names.length) return [];
+  const items = new Map();            // item name -> { body, receipt, held: [names] }
+  for (const name of names) {
+    const got = await ctx.readHeld(handle, name);
+    const item = name.endsWith(RECEIPT) ? name.slice(0, -RECEIPT.length) : name;
+    const e = items.get(item) || { held: [] };
+    e.held.push(name);
+    if (got != null) {
+      if (name.endsWith(RECEIPT)) { try { e.receipt = JSON.parse(got); } catch { e.receipt = null; } } else e.body = got;
+    }
+    items.set(item, e);
+  }
+  for (const [item, e] of items) {
+    if (typeof e.body !== 'string') { for (const n of e.held) await ctx.dropHeld(handle, n); items.delete(item); }
+  }
+  return [...items].map(([name, e]) => ({ name, body: e.body, receipt: e.receipt || null, held: e.held }));
+}
+
+// Everything held for one account, written to its pod inbox in batches and
+// then let go. Returns how many deliveries reached the pod. A batch the pod
+// refuses stays held for the next try.
+export async function flushHeld(ctx, handle, rec, { now = Date.now() } = {}) {
+  const all = (await heldEntries(ctx, handle)).map((e) => [e.name, e]);
+  if (!all.length) return 0;
+  let delivered = 0;
+  for (let i = 0; i < all.length; i += BATCH_MAX) {
+    const chunk = all.slice(i, i + BATCH_MAX);
+    const batch = chunk.map(([name, e]) => ({ name, body: e.body, receipt: e.receipt || null }));
+    const doc = `batch-${now}-${i / BATCH_MAX}-${Math.random().toString(36).slice(2, 8)}.json`;
+    const ok = await ctx.podPut(handle, inboxOf(rec) + doc, JSON.stringify({ batch }), 'application/json');
+    if (!ok) break;
+    for (const [, e] of chunk) for (const n of e.held) await ctx.dropHeld(handle, n);
+    delivered += chunk.length;
+  }
+  return delivered;
+}
+
+// Held mail the keeper should not leave until the owner's app opens: a
+// follow, so it is accepted while they are away. Anything else waits, in the
+// pod inbox, for the app or for the keeper's next run.
+const WAKES_KEEPER = new Set(['Follow']);
+export async function wakesKeeper(ctx, handle, rec, type) {
+  if (!keptNow(ctx, rec) || !ctx.noteNext || !WAKES_KEEPER.has(type)) return false;
+  await ctx.noteNext(handle, new Date().toISOString(), { earliest: true }).catch(() => {});
+  return true;
+}
+
+// After a delivery is held: a follow wakes the keeper, and anything that
+// becomes a notification is read in and pushed at once to the phones and
+// browsers the owner signed up for notifications (masto-gateway.mjs: pushHeld).
+export async function afterHeld(ctx, handle, rec, { type, notifies = false } = {}) {
+  await wakesKeeper(ctx, handle, rec, type);
+  if (notifies && keptNow(ctx, rec) && ctx.startPush && await ctx.pushWanted?.(handle).catch(() => false)) {
+    await ctx.startPush(handle).catch((e) => console.log(`push @${handle}: not started: ${e?.message || e}`));
+  }
+}
+
+// The timer's round: every account with mail kept, delivered. An account that
+// is gone, closed or moved has nowhere to deliver to, so its mail is let go.
+// `keep(handle, rec)` answers true when the account's keeper will take its mail
+// itself (lib/gateway/keeper.mjs), which delivers it and then reads it.
+export async function flushAll(ctx, { log = console.log, isGone = async () => false, keep = async () => false } = {}) {
+  for (const handle of await ctx.heldAccounts()) {
+    const rec = await ctx.lookup(handle);
+    if (!rec || rec.movedTo || await isGone(handle, rec)) {
+      for (const n of await ctx.listHeld(handle)) await ctx.dropHeld(handle, n);
+      log(`held mail @${handle}: let go (no account to deliver to)`);
+      continue;
+    }
+    if (await keep(handle, rec).catch(() => false)) continue;
+    const n = await flushHeld(ctx, handle, rec).catch((e) => { log(`held mail @${handle}: ${e?.message || e}`); return 0; });
+    if (n) log(`held mail @${handle}: ${n} delivered to the pod`);
+  }
+}
+
+// The owner letting the gateway act for them while the app is closed, or
+// stopping it. Their app has already named the gateway in the rules on their
+// pod (or taken it out) before it asks. Proved like /api/here.
+export async function routeKeeperApi(request, pathname, ctx, deps) {
+  if (pathname !== '/api/keeper') return null;
+  const { j } = deps;
+  if (request.method === 'OPTIONS') return deps.apiPreflight();
+  if (request.method !== 'POST') return null;
+  if (!ctx.putDirectory) return j(501, { error: 'this front keeps no directory' });
+  let body;
+  try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
+  const handle = String(body.handle || '').toLowerCase();
+  const rec = await ctx.lookup(handle);
+  if (!rec) return j(404, { error: 'no such account' });
+  const who = await deps.provedOwner(request, pathname, ctx, rec, deps);
+  if (who.error) return who.error;
+  const on = body.on === true;
+  if (on && !ctx.keeperWebId) return j(501, { error: 'this gateway cannot act for accounts' });
+  // The account's copy goes back to the pod before the gateway stops
+  // (state-api.mjs: leave); the owner's app asks for that first.
+  if (!on && ctx.copyKv && await copyMeta(ctx.copyKv, handle)) {
+    return j(409, { error: "the account's copy is still at the gateway; give it back to the pod first", copy: true });
+  }
+  const next = { ...rec };
+  if (on) next.keeper = { webId: ctx.keeperWebId, at: new Date().toISOString() };
+  else delete next.keeper;
+  await ctx.putDirectory(handle, next);
+  console.log(`keeper @${handle}: ${on ? 'on' : 'off'}, at the owner's word`);
+  return j(200, { ok: true, handle, kept: on, keeper: ctx.keeperWebId || null });
+}
+
+// The app's "I am open": marks the account present, so mail goes straight to
+// the pod, and delivers what was kept while it was closed. The owner is proved
+// the way the relay proves them. Returns a response, or null for other paths.
+export async function routeHereApi(request, pathname, ctx, deps) {
+  if (pathname !== '/api/here') return null;
+  const { j } = deps;
+  if (request.method === 'OPTIONS') return deps.apiPreflight();
+  if (request.method !== 'POST') return null;
+  if (!ctx.markPresent) return j(501, { error: 'this gateway holds no mail' });
+  let body;
+  try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
+  const handle = String(body.handle || '').toLowerCase();
+  const rec = await ctx.lookup(handle);
+  if (!rec) return j(404, { error: 'no such account' });
+  const who = await deps.provedOwner(request, pathname, ctx, rec, deps);
+  if (who.error) return who.error;
+  await ctx.markPresent(handle);
+  seen.set(handle, { at: Date.now(), asked: Date.now() });
+  // When its next scheduled post falls due, so the keeper publishes it if
+  // the app has closed by then (keeper.mjs).
+  if (body.nextAt !== undefined && ctx.noteNext) await ctx.noteNext(handle, body.nextAt || null).catch(() => {});
+  const flushed = await flushHeld(ctx, handle, rec)
+    .catch((e) => { console.log(`here @${handle}: held mail not delivered: ${e?.message || e}`); return 0; });
+  return j(200, { ok: true, handle, flushed });
+}

package/lib/gateway/keeper-due.mjs

@@ -0,0 +1,39 @@
+// keeper-due.mjs — when each kept account's keeper next has work
+// (keeper.mjs), kept per account in a small key-value store: Netlify Blobs on
+// Netlify, a Map in a test. `store` answers get(key) -> object|null,
+// set(key, object) and keys() -> [key].
+//
+// A run sets the time from what it left (nextAt). A follow held at the door
+// sets it to now, and one that arrives while a run is going is not lost when
+// the run finishes. A run that could not take the account's lease tries again
+// next round; one that failed, in an hour.
+
+const RETRY_FAILED_MS = 3_600_000;
+
+// The sooner of two times (ISO strings, either of them null).
+export const earliest = (a, b) => (!a ? b || null : !b ? a : Date.parse(a) <= Date.parse(b) ? a : b);
+
+export function keeperBook(store) {
+  return {
+    async noteKept(handle, out, started = 0, now = Date.now()) {
+      const prev = (await store.get(handle)) || {};
+      const next = out?.retry === 'soon' ? prev.nextAt
+        : out?.retry === 'later' ? new Date(now + RETRY_FAILED_MS).toISOString() : out?.nextAt;
+      const woken = prev.noted >= started ? prev.nextAt : null;
+      await store.set(handle, { at: now, waiting: out?.waiting || 0, skipped: out?.skipped || null,
+        nextAt: earliest(next || null, woken) });
+    },
+    async noteNext(handle, nextAt, { earliest: keepSooner = false } = {}) {
+      const prev = (await store.get(handle)) || {};
+      await store.set(handle, { ...prev, nextAt: keepSooner ? earliest(prev.nextAt, nextAt) : nextAt, noted: Date.now() });
+    },
+    async keeperDue(now = Date.now()) {
+      const due = [];
+      for (const key of await store.keys()) {
+        const k = (await store.get(key)) || {};
+        if (k.nextAt && Date.parse(k.nextAt) <= now) due.push(key);
+      }
+      return due;
+    },
+  };
+}

package/lib/gateway/keeper-session.mjs

@@ -0,0 +1,10 @@
+// keeper-session.mjs — the gateway's own pod identity at work: one grant per
+// running copy, shared by every account it works for, so a round is one token,
+// not one per account (keeper.mjs, state-api.mjs).
+import grant from '../../vendor/idp-grant.cjs';
+
+let shared = null;
+export function keeperSession(cred) {
+  if (!shared || shared.cred !== cred) shared = { cred, session: grant.createGrantSession(cred) };
+  return shared.session;
+}

package/lib/gateway/keeper.mjs

@@ -0,0 +1,72 @@
+// keeper.mjs — the gateway acting for a browser account while its owner's app
+// is closed: the mail it held reaches the pod, the inbox is drained, follows
+// and replies are handled, and deliveries waiting to go out are sent.
+//
+// The owner lets it (their app names the gateway's pod identity in the rules on
+// their account's folder, and the row records `keeper`). It works with that
+// identity and nothing else: it reads the signing key from the pod when it
+// needs it, keeps no copy, and never makes or changes one. It takes the
+// account's lease like any other device, and gives it back when done, so the
+// owner's app finds the lease free and takes over as usual.
+//
+// One run is one account: keepOnce(). The fifteen-minute round (flush-mail.mjs)
+// starts one only when an account whose app is closed has work due: a follow
+// held at the door, a failed delivery's next try, a scheduled post or a poll's
+// end. Other mail waits in the pod inbox for the app.
+
+import { keeperSession } from './keeper-session.mjs';
+import { flushHeld, heldEntries } from './held-mail.mjs';
+import { publishDue, nextDue } from '../core/scheduled.mjs';
+import { lockCopy } from './copy.mjs';
+import { reachAccount, stateAndLease, actingAgent } from './account-agent.mjs';
+
+export { keeperSession };
+
+/**
+ * One account's pending work, done once. `ctx` is the gateway's: keeperWebId,
+ * keeperCredential and the held-mail stores. `session` may be handed in (a
+ * test does); otherwise the keeper's grant is used. Returns what happened.
+ *
+ * An account whose copy the gateway keeps (copy.mjs) is worked on there: its
+ * held mail is read straight into the copy, and the pod is written by the
+ * round, not here. Otherwise the held mail goes to the pod inbox first, so the
+ * drain reads it, as before.
+ */
+export async function keepOnce(ctx, handle, rec, { log = console.log, session = null } = {}) {
+  const say = (m) => log(`keeper @${handle}: ${m}`);
+  const at = await reachAccount(ctx, handle, rec, { log, session });
+  if (at.skipped) return { skipped: at.skipped };
+
+  const unlock = at.inCopy ? await lockCopy(ctx.copyKv, handle) : async () => {};
+  if (!unlock) return { skipped: 'the gateway is busy with this account', retry: 'soon' };
+  try {
+    // Held mail goes in first, so this drain reads it.
+    const flushed = !at.inCopy && ctx.listHeld
+      ? await flushHeld(ctx, handle, rec).catch((e) => { say(`held mail not delivered: ${e.message}`); return 0; }) : 0;
+    const { store, lease } = stateAndLease(ctx, handle, at, { log });
+    if (!await lease.acquire()) return { skipped: 'another device is acting on this account', flushed, retry: 'soon' };
+    try {
+      await store.load();
+      const agent = await actingAgent(at, store, lease, { log });
+      if (agent.skipped) return { skipped: agent.skipped, flushed };
+      let taken = 0;
+      if (at.inCopy && ctx.listHeld) {
+        const entries = await heldEntries(ctx, handle);
+        const done = new Set(await agent.intake.takeHeld(entries));
+        for (const e of entries) if (done.has(e.name)) for (const n of e.held) await ctx.dropHeld(handle, n);
+        taken = done.size;
+      }
+      await agent.intake.drain();
+      const published = await publishDue(store, agent.publisher, say);
+      await agent.deliverer.drainQueue();
+      await store.flush?.();
+      agent.publisher.stopPolls?.();
+      const waiting = (store.getQueue?.() || []).length;
+      const nextAt = nextDue(store);
+      say(`done: ${flushed + taken} held delivered, inbox drained, ${published} scheduled post(s) published, ${waiting} delivery(ies) waiting`);
+      return { flushed: flushed + taken, drained: true, published, waiting, nextAt };
+    } finally {
+      await lease.release().catch(() => {});
+    }
+  } finally { await unlock(); }
+}