fedipod-server 0.8.0 → 0.10.0

package/lib/mastoapi.mjs

@@ -16,6 +16,11 @@ import { sanitizeHtml, followsNeedApproval, publicHandle } from './wire.mjs';
 import { authorOf } from './intake.mjs';
 import { profileUrl, postUrl } from './bskyfeed.mjs';
 import { Push } from './webpush.mjs';
+import { safeFetch, readCapped } from './safefetch.mjs';
+import {
+  MAX_OPTIONS as POLL_MAX_OPTIONS, MAX_OPTION_CHARS as POLL_MAX_OPTION_CHARS,
+  MIN_SECONDS as POLL_MIN_SECONDS, MAX_SECONDS as POLL_MAX_SECONDS,
+} from './polls.mjs';
 
 // What an attachment is allowed to BE. Anything else is stored as bytes, which
 // a browser downloads rather than runs.
@@ -26,6 +31,26 @@ const ATTACHMENT_KINDS = new Set(['image', 'video', 'audio']);
 const NEVER = new Set(['image/svg+xml', 'image/svg']);
 const OPAQUE = 'application/octet-stream';
 
+/**
+ * A poll out of a compose request, or null when there is none. A JSON client
+ * sends a `poll` object; a form-encoded one spells the same thing out in
+ * Rails's bracket notation, which is the shape the option list arrives in.
+ */
+export function pollParams(body) {
+  const nested = body?.poll && typeof body.poll === 'object' ? body.poll : null;
+  const options = [].concat(nested?.options ?? body?.['poll[options][]'] ?? [])
+    .map(o => String(o ?? '').trim()).filter(Boolean);
+  const rawExpiry = nested?.expires_in ?? body?.['poll[expires_in]'];
+  const rawMultiple = nested?.multiple ?? body?.['poll[multiple]'];
+  if (!options.length && rawExpiry === undefined) return null;
+  return {
+    options,
+    expiresIn: rawExpiry === undefined || rawExpiry === null || rawExpiry === ''
+      ? null : Number(rawExpiry),
+    multiple: rawMultiple === true || rawMultiple === 'true' || rawMultiple === '1',
+  };
+}
+
 export function attachmentType(claimed) {
   const t = String(claimed || '').split(';')[0].trim().toLowerCase();
   if (!/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(t) || NEVER.has(t)) return OPAQUE;
@@ -62,6 +87,8 @@ const AUTHZ_WINDOW_MS = 60_000;
 const AUTHZ_MAX_ATTEMPTS = 5;
 const CODE_TTL_MS = 5 * 60_000;                  // an authorization code is short-lived
 const MAX_APPS = 200;                            // registered third-party clients, capped
+const CLIENT_DOC_TTL_MS = 10 * 60_000;           // how long a fetched client document is trusted
+const CLIENT_DOC_MAX = 64 * 1024;                // it names a client; it is not a payload
 
 export class MastoApi {
   constructor({ agent, log = console.log, allowed = null, scheme = null, embedded = false }) {
@@ -127,7 +154,91 @@ export class MastoApi {
   // said, and only that client, presenting its secret, can exchange it for a
   // bearer. A redirect back to this agent's own origin keeps the local flow.
   apps() { return this.store.read('oauth-apps.json', []); }
+  /**
+   * What a client needs to know before it can sign in, at the address RFC 8414
+   * puts it. The actor carries the same two endpoints; a client that looks
+   * here first finds everything rather than the minimum.
+   *
+   * `none` among the authentication methods is what says a client keeping no
+   * secret is welcome, which is the whole of what a browser app needs to hear.
+   */
+  authorizationServerMetadata(origin) {
+    const at = (p) => `${origin.replace(/\/$/u, '')}${p}`;
+    return {
+      issuer: origin.replace(/\/$/u, ''),
+      authorization_endpoint: at('/oauth/authorize'),
+      token_endpoint: at('/oauth/token'),
+      revocation_endpoint: at('/oauth/revoke'),
+      registration_endpoint: at('/api/v1/apps'),
+      response_types_supported: [ 'code' ],
+      grant_types_supported: [ 'authorization_code' ],
+      code_challenge_methods_supported: [ 'S256', 'plain' ],
+      token_endpoint_auth_methods_supported: [ 'client_secret_post', 'none' ],
+      scopes_supported: [ 'read', 'write', 'follow', 'push' ],
+    };
+  }
+
   findApp(clientId) { return clientId ? this.apps().find(a => a.clientId === clientId) || null : null; }
+
+  /**
+   * A client that publishes its own metadata document is named by that
+   * document's URL and registers nothing here: the document says who it is
+   * and where it may be sent back to. Such a client keeps no secret, so it
+   * always proves itself with a challenge instead.
+   *
+   * The fetch is the guarded one — a client id is a URL a stranger chose, and
+   * an unguarded fetch of it would ask this machine to reach wherever they
+   * pointed.
+   */
+  async resolveClientDocument(clientId) {
+    if (!/^https:\/\//iu.test(String(clientId || ''))) return null;   // cleartext is refused
+    this.clientDocs = this.clientDocs || new Map();
+    const seen = this.clientDocs.get(clientId);
+    if (seen && Date.now() - seen.at < CLIENT_DOC_TTL_MS) return seen.client;
+    let doc;
+    try {
+      const res = await safeFetch(clientId, { headers: { accept: 'application/json' } });
+      if (res.status >= 400) { this.log(`client document ${clientId} → ${res.status}`); return null; }
+      doc = JSON.parse(await readCapped(res, CLIENT_DOC_MAX));
+    } catch (e) {
+      this.log(`client document ${clientId} could not be read: ${e.message}`);
+      return null;
+    }
+    // It must claim to be itself: a document naming some other id would let
+    // one client borrow another's name.
+    if (doc?.client_id !== clientId) {
+      this.log(`client document ${clientId} names ${doc?.client_id ?? 'nothing'} — refused`);
+      return null;
+    }
+    const redirectUris = [].concat(doc.redirect_uris || []).filter((u) => typeof u === 'string');
+    if (!redirectUris.length) { this.log(`client document ${clientId} names no redirect — refused`); return null; }
+    const client = {
+      clientId, redirectUris,
+      name: String(doc.client_name || clientId).slice(0, 200),
+      scopes: 'read write follow',
+    };
+    this.clientDocs.set(clientId, { at: Date.now(), client });
+    return client;
+  }
+
+  /**
+   * Whether a redirect the client asked for is one it published.
+   *
+   * A native client listens on whatever port the machine gave it, so it can
+   * only publish the loopback address without one (RFC 8252). The port is
+   * therefore not part of the match there, and nowhere else.
+   */
+  static redirectMatches(published, asked) {
+    if (published === asked) return true;
+    try {
+      const a = new URL(published);
+      const b = new URL(asked);
+      const loopback = (h) => h === '127.0.0.1' || h === '[::1]' || h === 'localhost';
+      if (!loopback(a.hostname) || a.hostname !== b.hostname) return false;
+      return a.protocol === b.protocol
+        && a.pathname.replace(/\/$/u, '') === b.pathname.replace(/\/$/u, '');
+    } catch { return false; }
+  }
   registerApp({ name, website, redirectUris, scopes }) {
     const app = {
       clientId: crypto.randomBytes(16).toString('hex'),
@@ -143,13 +254,39 @@ export class MastoApi {
   // A short-lived, single-use authorization code for a registered client, kept
   // apart from masto-tokens.json so the code is NOT a bearer until it is
   // exchanged with the client secret.
-  mintCode({ clientId, redirectUri, scope }) {
+  mintCode({ clientId, redirectUri, scope, challenge = null, challengeMethod = null }) {
     const code = crypto.randomBytes(24).toString('hex');
     const now = Date.now();
     const kept = this.store.read('oauth-codes.json', []).filter(c => now - c.createdAt < CODE_TTL_MS);
-    this.store.write('oauth-codes.json', [...kept, { code, clientId, redirectUri, scope, createdAt: now }].slice(-50));
+    this.store.write('oauth-codes.json', [ ...kept, {
+      code, clientId, redirectUri, scope, createdAt: now,
+      // What the client promised to prove when it comes back for the token.
+      // A client that cannot keep a secret — anything running in a browser —
+      // has this instead, and it is the only thing standing between a stolen
+      // code and a token.
+      ...(challenge ? { challenge, challengeMethod: challengeMethod || 'plain' } : {}),
+    } ].slice(-50));
     return code;
   }
+  /**
+   * Whether this verifier is the one the challenge was made from (RFC 7636).
+   * Length is checked because a short verifier is guessable, which is the
+   * whole thing this is here to prevent.
+   */
+  static provesCode(rec, verifier) {
+    const v = String(verifier || '');
+    if (v.length < 43 || v.length > 128) return false;
+    if ((rec.challengeMethod || 'plain') === 'S256') {
+      const made = crypto.createHash('sha256').update(v).digest('base64url');
+      const given = Buffer.from(made);
+      const known = Buffer.from(String(rec.challenge));
+      return given.length === known.length && crypto.timingSafeEqual(given, known);
+    }
+    const given = Buffer.from(v);
+    const known = Buffer.from(String(rec.challenge));
+    return given.length === known.length && crypto.timingSafeEqual(given, known);
+  }
+
   consumeCode(code) {
     const now = Date.now();
     const all = this.store.read('oauth-codes.json', []);
@@ -515,7 +652,7 @@ export class MastoApi {
       expires_at: s.poll.expiresAt || null,
       expired: !!s.poll.closed || (!!s.poll.expiresAt && Date.parse(s.poll.expiresAt) < Date.now()),
       multiple: !!s.poll.multiple,
-      votes_count: votes, voters_count: null,
+      votes_count: votes, voters_count: s.poll.votersCount ?? null,
       options: opts.map(o => ({ title: o.title, votes_count: o.votes || 0 })),
       voted: !!s.poll.voted, own_votes: s.poll.ownVotes || [],
       emojis: [],
@@ -620,19 +757,35 @@ export class MastoApi {
       if (req.method === 'POST') { body = await readBody(req); params = new URLSearchParams(body); }
       const redirect = params.get('redirect_uri') || '';
       const app = this.findApp(params.get('client_id') || '');
+      // A client that published its own metadata document needs no
+      // registration here: the document is its name and says where it may be
+      // sent back to.
+      const doc = app ? null : await this.resolveClientDocument(params.get('client_id') || '');
       // A REGISTERED client is always the third-party flow — its code is
       // bound to it and exchanged with its secret — even when its redirect
       // points back at this very agent (a web client served from our own
       // origin registers itself exactly like a phone app does). The local
       // code-is-the-token flow is only for the built-in client, which never
       // registers.
-      const external = !!app;
-      const client = { name: app?.name || null, redirect, scope: params.get('scope') || 'read' };
-      if (external) {
+      const external = !!app || !!doc;
+      const client = { name: app?.name || doc?.name || null, redirect, scope: params.get('scope') || 'read' };
+      if (app) {
         if (!app.redirectUris.includes(redirect)) {
           this.log(`authorize refused: redirect_uri "${redirect}" not registered for ${app.clientId}`);
           return send(400, { error: 'redirect_uri was not registered by this client' });
         }
+      } else if (doc) {
+        if (!doc.redirectUris.some((u) => MastoApi.redirectMatches(u, redirect))) {
+          this.log(`authorize refused: redirect_uri "${redirect}" is not one ${doc.clientId} published`);
+          return send(400, { error: 'redirect_uri is not one this client published' });
+        }
+        // It keeps no secret, so the challenge is the only thing that will
+        // stand between its code and a token. Refuse now rather than mint a
+        // code nothing can prove.
+        if (!params.get('code_challenge')) {
+          this.log(`authorize refused: ${doc.clientId} keeps no secret and offered no challenge`);
+          return send(400, { error: 'a client identified by its own document must send a code_challenge' });
+        }
       } else if (!this.redirectAllowed(redirect)) {
         this.log(`authorize refused: redirect_uri "${redirect}" is not this agent`);
         return send(400, { error: 'redirect_uri must be an address of this agent' });
@@ -640,7 +793,11 @@ export class MastoApi {
       if (req.method === 'POST') {
         if (this.rateLimited()) {
           this.log('authorize rate limited');
-          return sendLoginForm(res, params, 'too many attempts — wait a minute', client);
+          // 429, not 401: a client that reads this as a wrong password will
+          // ask the person to type it again, which is the one thing that
+          // cannot help. Retry-After says how long the wait actually is.
+          return sendLoginForm(res, params, 'too many attempts — wait a minute', client,
+            429, { 'retry-after': String(Math.ceil(AUTHZ_WINDOW_MS / 1000)) });
         }
         if (!pw || !checkPassword(pw, body.password || '')) {
           return sendLoginForm(res, params, 'wrong password — try again', client);
@@ -670,7 +827,9 @@ export class MastoApi {
       }
       // External clients get a bound code; the local flow keeps code==token.
       const code = external
-        ? this.mintCode({ clientId: app.clientId, redirectUri: redirect, scope: client.scope })
+        ? this.mintCode({ clientId: (app || doc).clientId, redirectUri: redirect, scope: client.scope,
+          challenge: params.get('code_challenge') || null,
+          challengeMethod: params.get('code_challenge_method') || null })
         : this.mintToken();
       if (!redirect || redirect === 'urn:ietf:wg:oauth:2.0:oob') return send(200, { code });
       const target = new URL(redirect);
@@ -685,6 +844,44 @@ export class MastoApi {
       // A registered third-party client exchanges its bound code, proving its
       // secret, for a real bearer — the code alone is not a token.
       const app = this.findApp(body.client_id || '');
+      // A client named by its own document keeps no secret at all, so the
+      // challenge is the whole of its proof. The code carries the document's
+      // URL as the client it was bound to.
+      if (!app && body.code_verifier && /^https:\/\//iu.test(String(body.client_id || ''))) {
+        const rec = this.consumeCode(body.code || '');
+        if (!rec || rec.clientId !== body.client_id
+          || (body.redirect_uri && rec.redirectUri !== body.redirect_uri)) {
+          this.log('token refused: code is not a live authorization for that client document');
+          return send(400, { error: 'invalid_grant' });
+        }
+        if (!rec.challenge || !MastoApi.provesCode(rec, body.code_verifier)) {
+          this.log('token refused: the verifier does not answer the challenge this code was made with');
+          return send(400, { error: 'invalid_grant' });
+        }
+        return send(200, { access_token: this.mintToken(), token_type: 'Bearer',
+          scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000),
+          ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
+      }
+      // A client that runs in a browser cannot keep a secret, so it proves it
+      // is the same caller that asked instead: it sends the verifier for the
+      // challenge it presented at authorize (RFC 7636). Sending a verifier is
+      // what says which of the two flows this is.
+      if (app && body.code_verifier) {
+        const rec = this.consumeCode(body.code || '');
+        if (!rec || rec.clientId !== app.clientId || (body.redirect_uri && rec.redirectUri !== body.redirect_uri)) {
+          this.log('token refused: code is not a live authorization for this client');
+          return send(400, { error: 'invalid_grant' });
+        }
+        // A code minted without a challenge cannot be redeemed with one: that
+        // would let anyone holding a stolen code invent the proof for it.
+        if (!rec.challenge || !MastoApi.provesCode(rec, body.code_verifier)) {
+          this.log('token refused: the verifier does not answer the challenge this code was made with');
+          return send(400, { error: 'invalid_grant' });
+        }
+        return send(200, { access_token: this.mintToken(), token_type: 'Bearer',
+          scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000),
+          ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
+      }
       if (app && body.client_secret) {
         const given = Buffer.from(String(body.client_secret));
         const known = Buffer.from(app.clientSecret);
@@ -695,8 +892,18 @@ export class MastoApi {
           this.log('token refused: code is not a live authorization for this client');
           return send(400, { error: 'invalid_grant' });
         }
+        // A challenge, once made, is not optional: without this a client could
+        // present one and then skip past it with the secret alone.
+        if (rec.challenge && !MastoApi.provesCode(rec, body.code_verifier)) {
+          this.log('token refused: this code was made with a challenge and the verifier does not answer it');
+          return send(400, { error: 'invalid_grant' });
+        }
         return send(200, { access_token: this.mintToken(), token_type: 'Bearer',
-          scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000) });
+          scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000),
+          // Which actor the token acts for. A Mastodon client ignores it; an
+          // ActivityPub API client needs it, and asking for it separately
+          // would mean a second round trip before it knows who it is.
+          ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
       }
       // Local flow: the code IS the token, minted by /oauth/authorize after the
       // password gate. Minting one here for an unrecognised code handed a
@@ -707,7 +914,9 @@ export class MastoApi {
         this.log('token refused: code is not a live authorization');
         return send(400, { error: 'invalid_grant' });
       }
-      return send(200, { access_token: body.code, token_type: 'Bearer', scope: body.scope || 'read write follow push', created_at: Math.floor(Date.now() / 1000) });
+      return send(200, { access_token: body.code, token_type: 'Bearer',
+        scope: body.scope || 'read write follow push', created_at: Math.floor(Date.now() / 1000),
+        ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
     }
     if (pathname === '/oauth/revoke' && req.method === 'POST') {
       // It used to answer 200 and keep the token, so logging out of a client
@@ -895,6 +1104,41 @@ export class MastoApi {
       const mediaIds = [].concat(body.media_ids || body['media_ids[]'] || []).filter(Boolean);
       const media = this.store.getMedia();
       const attachments = mediaIds.map(id => media[id] && { id, ...media[id] }).filter(Boolean);
+
+      const asking = pollParams(body);
+      if (asking) {
+        // Mastodon's own rules, stated here rather than discovered inside the
+        // publisher, so a client gets the reason back on the request it made.
+        if (attachments.length) return send(422, { error: 'a poll cannot carry media' });
+        if (body.scheduled_at) return send(422, { error: 'a poll cannot be scheduled' });
+        if (asking.options.length < 2) return send(422, { error: 'a poll needs at least two options' });
+        if (asking.options.length > POLL_MAX_OPTIONS) {
+          return send(422, { error: `a poll takes at most ${POLL_MAX_OPTIONS} options` });
+        }
+        if (asking.options.some(o => o.length > POLL_MAX_OPTION_CHARS)) {
+          return send(422, { error: `a poll option is at most ${POLL_MAX_OPTION_CHARS} characters` });
+        }
+        if (new Set(asking.options).size !== asking.options.length) {
+          return send(422, { error: 'a poll\u2019s options must differ from one another' });
+        }
+        const seconds = asking.expiresIn ?? POLL_MAX_SECONDS;
+        if (!Number.isFinite(seconds) || seconds < POLL_MIN_SECONDS || seconds > POLL_MAX_SECONDS) {
+          return send(422, {
+            error: `a poll runs between ${POLL_MIN_SECONDS} and ${POLL_MAX_SECONDS} seconds`,
+          });
+        }
+        try {
+          const q = await this.agent.publisher.publishQuestion(body.status, {
+            options: asking.options, multiple: asking.multiple,
+            expiresAt: new Date(Date.now() + seconds * 1000).toISOString(),
+            inReplyTo, visibility, spoilerText,
+          });
+          return send(200, this.status(this.store.getStatuses().find(x => x.noteId === q.id)));
+        } catch (e) {
+          return send(422, { error: e.message });
+        }
+      }
+
       if (body.scheduled_at) {
         const at = Date.parse(body.scheduled_at);
         if (!Number.isFinite(at) || at < Date.now() + 60_000) {
@@ -1522,7 +1766,12 @@ function instanceConfig() {
       image_size_limit: 10 * 1024 * 1024, video_size_limit: 40 * 1024 * 1024,
       image_matrix_limit: 16777216, video_matrix_limit: 2304000,
     },
-    polls: { max_options: 0 },
+    polls: {
+      max_options: POLL_MAX_OPTIONS,
+      max_characters_per_option: POLL_MAX_OPTION_CHARS,
+      min_expiration: POLL_MIN_SECONDS,
+      max_expiration: POLL_MAX_SECONDS,
+    },
     accounts: { max_featured_tags: 0 },
   };
 }
@@ -1554,7 +1803,7 @@ const escapeHtml = (s) => String(s).replace(/[&<>"']/g, c =>
 const parseRedirects = (v) => (Array.isArray(v) ? v : String(v || '').split(/\s+/))
   .map(s => s.trim()).filter(Boolean);
 
-function sendLoginForm(res, params, error = '', client = null) {
+function sendLoginForm(res, params, error = '', client = null, status = null, headers = {}) {
   const hidden = [...params.entries()].filter(([k]) => k !== 'password')
     .map(([k, v]) => `<input type="hidden" name="${escapeHtml(k)}" value="${escapeHtml(v)}">`).join('\n');
   // Name what is asking, so the owner approves a client they can see rather
@@ -1569,7 +1818,8 @@ function sendLoginForm(res, params, error = '', client = null) {
       + `${where ? `, sending the authorization to <code>${escapeHtml(where)}</code>` : ''}.</p>`
       + `<p>Scope: <code>${escapeHtml(client.scope || 'read')}</code>. Enter the agent password to allow it.</p>`;
   }
-  res.writeHead(error ? 401 : 200, { 'content-type': 'text/html; charset=utf-8' });
+  res.writeHead(status || (error ? 401 : 200),
+    { 'content-type': 'text/html; charset=utf-8', ...headers });
   res.end(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
 <title>FediPod — authorize</title>
 <style>:root{color-scheme:light dark;font-size:125%;--heading:#1a4f8a}
@@ -1679,7 +1929,17 @@ function readBody(req) {
       const ct = String(req.headers['content-type'] || '');
       try {
         if (ct.includes('application/json')) return resolve(data ? JSON.parse(data) : {});
-        resolve(Object.fromEntries(new URLSearchParams(data)));
+        // A form-encoded list is the same key repeated, spelled with a
+        // trailing `[]`. Reading it as a plain object kept only the last one,
+        // so a client sending its poll or its media that way lost all but the
+        // final value. Only the `[]` keys become lists: everything else keeps
+        // the single value the rest of this file reads.
+        const form = new URLSearchParams(data);
+        const out = {};
+        for (const key of new Set(form.keys())) {
+          out[key] = key.endsWith('[]') ? form.getAll(key) : form.get(key);
+        }
+        resolve(out);
       } catch (e) { reject(e); }
     });
     req.on('error', reject);

package/lib/polls.mjs

@@ -0,0 +1,105 @@
+// polls.mjs — the count behind a Question.
+//
+// A poll travels as a Question whose options live in `oneOf` (pick one) or
+// `anyOf` (pick several). A vote is not a special activity: it arrives as an
+// ordinary reply carrying the option's `name` and no content. So the fediverse
+// carries the votes and the author's server keeps the count — which means when
+// the poll is ours, the roster of who chose what is ours to hold.
+//
+// Everything here is pure. The roster is a plain object the caller stores and
+// hands back; the tallies are always DERIVED from it rather than kept beside
+// it, so a count cannot drift away from the votes it is meant to summarize.
+
+import crypto from 'node:crypto';
+
+/** Where the roster lives in agent state. */
+export const VOTES_DOC = 'poll-votes.json';
+
+// What a poll may be. These are Mastodon's own limits, and they are the ones
+// clients read out of the instance document to draw their poll composer, so a
+// number we chose differently would be a number the composer then lets someone
+// exceed. They live here rather than beside the client API because every way
+// in has to honour them: an option is matched BY NAME when the vote comes
+// back, so a long title is one something else in the network may truncate and
+// hand back unrecognizable.
+export const MAX_OPTIONS = 4;
+export const MAX_OPTION_CHARS = 50;
+export const MIN_SECONDS = 5 * 60;
+export const MAX_SECONDS = 2629746;          // a month, as Mastodon counts one
+
+// A voter is recorded as a hash of their actor id rather than the id itself.
+// The roster is rewritten on every vote inside a document we serialize whole,
+// and a poll that travels would otherwise grow a list of everyone who took
+// part. The hash is stable, which is all a duplicate check needs.
+export function voterKey(actor) {
+  return crypto.createHash('sha256').update(String(actor)).digest('hex').slice(0, 16);
+}
+
+/**
+ * Does this note have the shape of a vote? A name, and no content: that is the
+ * whole convention. Anything carrying prose is a reply somebody wrote, and
+ * swallowing it into a tally would lose it.
+ */
+export function isVoteShape(note) {
+  if (!note?.name || typeof note.name !== 'string') return false;
+  const text = String(note.content ?? '').replace(/<[^>]*>/gu, '').trim();
+  return text === '';
+}
+
+/** Which option is this the name of? -1 when it names none of them. */
+export function optionIndex(poll, name) {
+  const opts = poll?.options || [];
+  return opts.findIndex(o => o.title === String(name));
+}
+
+/** Closed outright, or past its end time. */
+export function pollClosed(poll, now = Date.now()) {
+  if (!poll) return false;
+  if (poll.closed) return true;
+  return !!poll.expiresAt && Date.parse(poll.expiresAt) <= now;
+}
+
+/**
+ * Record one choice. Returns the roster to store and whether anything changed
+ * — an unchanged roster must not cost a rewrite of the Question, which is the
+ * one expense a busy poll can run up on the pod.
+ *
+ * A single-choice poll takes the first answer and ignores the rest, which is
+ * how a voter changing their mind is refused rather than counted twice. A
+ * multiple-choice poll unions the answers, because each choice arrives as its
+ * own reply.
+ */
+export function addVote(roster, key, index, { multiple = false } = {}) {
+  const had = roster[key] || [];
+  if (had.length && !multiple) return { roster, changed: false };
+  if (had.includes(index)) return { roster, changed: false };
+  return { roster: { ...roster, [key]: [...had, index] }, changed: true };
+}
+
+/**
+ * The counts, derived. `votes` is answers given, `voters` is people who gave
+ * them — the same number until a poll takes several answers each.
+ */
+export function tallyOf(roster, optionCount) {
+  const counts = new Array(optionCount).fill(0);
+  let voters = 0;
+  for (const picks of Object.values(roster || {})) {
+    let counted = false;
+    for (const i of picks) {
+      if (i >= 0 && i < optionCount) { counts[i]++; counted = true; }
+    }
+    if (counted) voters++;
+  }
+  return { counts, voters, votes: counts.reduce((n, c) => n + c, 0) };
+}
+
+/** The poll record with its counts brought up to date from the roster. */
+export function withTally(poll, roster) {
+  const opts = poll?.options || [];
+  const { counts, voters } = tallyOf(roster, opts.length);
+  return {
+    ...poll,
+    options: opts.map((o, i) => ({ ...o, votes: counts[i] })),
+    votersCount: voters,
+  };
+}