fedipod-server 0.28.1 → 0.30.0

package/lib/core/lease.mjs

@@ -1,206 +0,0 @@
-// lease.mjs — single-active-agent coordination. The inbox drain is a
-// destructive read and the state store is write-through-cached, so exactly
-// one agent may ACT on a pod at a time; later arrivals run as read-only
-// viewers. The lease is one JSON doc in ap-state, always read and written
-// with FRESH fetches (never through the cached store), renewed while held.
-// Best-effort by design: a lost renewal just means the other agent takes
-// over at the next expiry.
-
-import crypto from 'node:crypto';
-
-// Renewal is the one thing that writes even when nothing is happening: at 30s
-// it was 120 PUTs an hour per agent, each taking a write lock on the pod; at
-// 90s, 40. Five minutes against a 15-minute TTL leaves two missed renewals of
-// headroom and makes it 12. The cost is automatic promotion after a crash
-// waiting up to the TTL — a user acting on a second device does not wait,
-// since takeover() claims the lease outright.
-const TTL_MS = 900_000;
-const RENEW_MS = 300_000;
-const JITTER = () => 0.85 + Math.random() * 0.3;
-// Distinct from null: null is "nobody holds it", this is "we could not ask".
-const UNREADABLE = Symbol('lease-unreadable');
-
-export class Lease {
-  // `id` names the HOLDER, and acquire() lets a holder reclaim its own lease
-  // without waiting for the TTL — so whether it is stable decides whether a
-  // restart is the same agent coming back or a second one arriving. A process
-  // that is gone for good wants a new one each time; a browser does not, since
-  // its agent lives in a service worker the browser is free to kill and restart
-  // whenever it likes. Left to the default, every one of those restarts looked
-  // like another device and asked the owner to take over their own account —
-  // which is what switching between the two clients did, because that is a
-  // navigation and a navigation can take the worker with it. The browser build
-  // passes one it keeps.
-  constructor({ url, fetchImpl, log = console.log, id = null }) {
-    this.url = url;
-    this.fetchImpl = fetchImpl;
-    this.log = log;
-    this.id = id || crypto.randomUUID();
-    this.stopped = false;
-    this.timer = null;
-    this.heldUntil = 0;   // wall-clock end of the lease we last wrote
-    this.denied = null;   // why the last acquire() said no: 'unreadable' | 'held'
-  }
-
-  // null means the lease document is NOT THERE — nobody holds it. UNREADABLE
-  // means we could not ask, which is a different answer and must not be read as
-  // "free": acquire() treated both as free, so a pod hiccup during acquire
-  // could hand a second agent a lease the first still holds, and both would
-  // drain the same inbox destructively.
-  async readFresh() {
-    let res, body;
-    try {
-      res = await this.fetchImpl(this.url, { headers: { accept: 'application/json' } });
-      if (res.status === 404 || res.status === 410) return null;
-      if (res.status >= 400) return UNREADABLE;
-      body = await res.text();
-    } catch { return UNREADABLE; }
-    this.etag = res.headers?.get?.('etag') || null;
-    // A 200 carrying garbage — a half-written PUT, a proxy error page served
-    // as 200 — is not a lease anybody holds, and overwriting it is the repair.
-    // Calling that UNREADABLE would leave the agent a viewer forever, because
-    // acquire() refuses to write over what it could not read.
-    try { return JSON.parse(body); }
-    catch { this.log('lease document is unparsable — treating it as unheld'); return null; }
-  }
-
-  // Returns false only for a refused If-Match — that is not an error, it is the
-  // answer. Anything else throws.
-  async write(doc, { ifMatch = null } = {}) {
-    const res = await this.fetchImpl(this.url, {
-      method: 'PUT',
-      headers: { 'content-type': 'application/json', ...(ifMatch ? { 'if-match': ifMatch } : {}) },
-      body: JSON.stringify(doc),
-    });
-    if (ifMatch && res.status === 412) return false;
-    if (res.status >= 400) throw new Error(`lease PUT → ${res.status}`);
-    this.etag = res.headers?.get?.('etag') || null;
-    return true;
-  }
-
-  // True when this agent now holds the lease. Write-then-confirm narrows the
-  // last-writer-wins race to a small window — acceptable for a human-scale
-  // "laptop vs phone" situation.
-  async acquire() {
-    const cur = await this.readFresh();
-    // Cannot read it: stay a viewer. A viewer that should have been active is
-    // an inconvenience; two agents both draining is the destructive one.
-    if (cur === UNREADABLE) {
-      this.denied = 'unreadable';
-      this.log('lease unreadable — staying a viewer'); return false;
-    }
-    if (cur && cur.holder !== this.id && Date.now() < cur.expiresAt) { this.denied = 'held'; return false; }
-    const doc = { holder: this.id, expiresAt: Date.now() + TTL_MS };
-    if (!await this.write(doc)) { this.denied = 'held'; return false; }
-    const confirm = await this.readFresh();
-    if (confirm === UNREADABLE) { this.denied = 'unreadable'; return false; }
-    if (confirm?.holder !== this.id) { this.denied = 'held'; return false; }
-    // From the document we WROTE, and only once the confirm agrees. Recomputing
-    // it here would claim a lease that outlives what the pod's copy grants, by
-    // however long the PUT and the confirming GET took.
-    this.heldUntil = doc.expiresAt;
-    this.denied = null;
-    return true;
-  }
-
-  // Renewal checks ownership first: a takeover by another agent must win,
-  // not be clobbered by a blind rewrite. Losing the lease fires onLost once
-  // and stops renewing.
-  async renewOnce() {
-    // The lease we hold has a wall-clock end. If renewals keep failing — the
-    // pod unreachable, refusing, or slow — the TTL passes, another agent is
-    // entitled to take over, and this one went on draining as though nothing
-    // had happened. Two agents on one destructive inbox read is exactly what
-    // the lease exists to prevent, so an expiry we could not extend is a loss.
-    if (this.heldUntil && Date.now() > this.heldUntil) {
-      this.stopRenewal();
-      this.etag = null;
-      this.log('lease expired and could not be renewed — standing down');
-      this.onLost?.();
-      return false;
-    }
-    const doc = { holder: this.id, expiresAt: Date.now() + TTL_MS };
-    // The steady path is a single conditional PUT. A 412 means somebody else
-    // wrote the lease — the only thing the preceding GET was ever there to
-    // detect — so the read is paid for exactly when it matters instead of every
-    // 90 seconds forever. No etag (a server that does not return one) falls
-    // back to read-then-write.
-    if (this.etag && await this.write(doc, { ifMatch: this.etag })) { this.heldUntil = doc.expiresAt; return true; }
-    const cur = await this.readFresh();
-    // Before the ownership test, or the sentinel answers it: a Symbol is truthy
-    // and its .holder is undefined, so "could not ask" read as "somebody else
-    // holds it" and stood a perfectly healthy agent down on one 500.
-    if (cur === UNREADABLE) return true;              // keep it; the next tick retries
-    if (cur && cur.holder !== this.id) {
-      // clearTimeout alone was a no-op here — the timer being cleared is the one
-      // whose own callback is running, and the chain re-armed in `finally`
-      // regardless. Stopping has to outlive this call, so it is a flag.
-      this.stopRenewal();
-      // readFresh just cached the NEW holder's ETag. Keeping it would let the
-      // next conditional PUT succeed and take the lease back, silently, from an
-      // agent that has already stood down.
-      this.etag = null;
-      this.log('lease taken over by another agent');
-      this.onLost?.();
-      return false;
-    }
-    await this.write(doc);
-    this.heldUntil = doc.expiresAt;
-    return true;
-  }
-
-  // Self-scheduling rather than setInterval, so each agent's renewals drift
-  // apart instead of several beating in lockstep against one pod.
-  // Idempotent, like Deliverer.startQueue: startActive reaches this twice on the
-  // parked path, and two chains against one pod is the doubling this whole file
-  // is written to avoid.
-  startRenewal() {
-    if (this.timer) return;
-    this.stopped = false;                    // restartable across demote/takeover
-    const tick = () => {
-      if (this.stopped) return;
-      this.timer = setTimeout(() => {
-        this.renewOnce()
-          .catch(e => this.log(`lease renewal: ${e.message}`))
-          .finally(() => { if (!this.stopped) tick(); });
-      }, Math.round(RENEW_MS * JITTER()));
-      this.timer.unref?.();
-    };
-    tick();
-  }
-
-  // Stop renewing WITHOUT giving the lease up — a demoted agent stands down, it
-  // does not release. Unstopped, the chain outlives demotion for the life of the
-  // process: ~80 requests an hour from an agent that is no longer acting.
-  stopRenewal() {
-    this.stopped = true;
-    clearTimeout(this.timer);
-    this.timer = null;
-  }
-
-  // Forcibly claim the lease (a user acting on a viewer device outranks the
-  // idle active agent). Write-then-confirm with one retry against the small
-  // window where the current holder's renewal lands in between.
-  async takeover() {
-    for (let attempt = 0; attempt < 2; attempt++) {
-      const doc = { holder: this.id, expiresAt: Date.now() + TTL_MS };
-      await this.write(doc);
-      const confirm = await this.readFresh();
-      if (confirm !== UNREADABLE && confirm?.holder === this.id) {
-        this.heldUntil = doc.expiresAt;
-        return true;
-      }
-    }
-    return false;
-  }
-
-  // Asked by the destructive path before it acts. The stand-down otherwise
-  // waits for the next renewal tick, which is up to ~117s away, and the whole
-  // point of the TTL is that after it another agent may start draining.
-  stillHeld() { return !this.stopped && (!this.heldUntil || Date.now() < this.heldUntil); }
-
-  async release() {
-    this.stopRenewal();
-    await this.write({ holder: this.id, expiresAt: 0 }).catch(() => {});
-  }
-}

package/lib/core/polls.mjs

@@ -1,105 +0,0 @@
-// 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,
-  };
-}

package/lib/core/profile-page.mjs

@@ -1,104 +0,0 @@
-// profile-page.mjs — the human page a browser opens for an actor: who the
-// account is, its fields, when it joined, what it pinned, and a remote-follow
-// control. The actor document is for servers; this is the address you hand
-// to a person. The agent writes it beside the actor (publisher
-// publishProfilePage) only when its content changed.
-
-const HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;' };
-
-// `fields` are the profile's name/value rows, `joined` an ISO date, `pinned`
-// the pinned posts as { content (sanitized HTML), published, url }.
-export function profilePageHtml({ name, address, summary = null, icon = null, image = null,
-  fields = [], joined = null, pinned = [], kind = 'person' }) {
-  const esc = (s) => String(s ?? '').replace(/[&<>"]/g, c => ({ ...HTML_ESCAPES, '"': '&quot;' }[c]));
-  const what = kind === 'group' ? 'a group' : 'an account';
-  const month = (iso) => {
-    const d = new Date(iso);
-    return Number.isNaN(d.getTime()) ? null
-      : d.toLocaleDateString('en', { month: 'long', year: 'numeric', timeZone: 'UTC' });
-  };
-  const day = (iso) => {
-    const d = new Date(iso);
-    return Number.isNaN(d.getTime()) ? '' : d.toISOString().slice(0, 10);
-  };
-  const fieldRows = fields.filter(f => f?.name && f?.value !== undefined && f?.value !== null && String(f.value) !== '');
-  const joinedText = joined ? month(joined) : null;
-  const pins = pinned.filter(x => x && typeof x.content === 'string');
-  return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${esc(name)} (${esc(address)})</title>
-<style>
-:root { color-scheme: light dark; }
-body { font: 112.5%/1.5 system-ui, sans-serif; max-width: 34rem; margin: 3rem auto; padding: 0 1rem; }
-img.header { width: 100%; max-height: 12rem; object-fit: cover; border-radius: 1rem; }
-img.avatar { width: 6rem; height: 6rem; border-radius: 1rem; object-fit: cover; margin-top: 1rem; }
-h1 { margin: .5rem 0 0; }
-.address { font-size: 1.1rem; user-select: all; }
-dl.fields { display: grid; grid-template-columns: max-content 1fr; gap: .4rem 1rem; margin: 1.5rem 0; }
-dl.fields dt { font-weight: 600; }
-dl.fields dd { margin: 0; overflow-wrap: anywhere; }
-.joined { margin: 1rem 0; }
-section.pinned h2 { font-size: 1.1rem; margin: 2rem 0 .5rem; }
-article.pin { border: 1px solid #8884; border-radius: 1rem; padding: 1rem 1.2rem; margin: 1rem 0; }
-article.pin p:last-child { margin-bottom: 0; }
-article.pin .when { font-size: 1rem; }
-form { margin-top: 2rem; }
-label { display: block; margin-bottom: .3rem; }
-input { font: inherit; padding: .5rem; width: 14rem; max-width: 100%; }
-button { font: inherit; padding: .5rem 1rem; }
-.hint { color: #666; font-size: 1rem; }
-.err { color: #b00020; }
-.err:empty { display: none; }
-@media (prefers-color-scheme: dark) {
-  .hint { color: #aaa; }
-  .err { color: #ff8a80; }
-}
-</style>
-</head>
-<body>
-<main>
-${image ? `<img class="header" src="${esc(image)}" alt="">` : ''}
-${icon ? `<img class="avatar" src="${esc(icon)}" alt="">` : ''}
-<h1>${esc(name)}</h1>
-<p class="address">${esc(address)}</p>
-${summary ? `<div>${summary}</div>` : ''}
-${fieldRows.length ? `<dl class="fields">
-${fieldRows.map(f => `<dt>${esc(f.name)}</dt><dd>${esc(f.value)}</dd>`).join('\n')}
-</dl>` : ''}
-${joinedText ? `<p class="joined">Joined ${esc(joinedText)}</p>` : ''}
-${pins.length ? `<section class="pinned">
-<h2>Pinned</h2>
-${pins.map(x => `<article class="pin">
-${x.content}
-<p class="when">${x.url ? `<a href="${esc(x.url)}">${esc(day(x.published))}</a>` : esc(day(x.published))}</p>
-</article>`).join('\n')}
-</section>` : ''}
-<p>This is ${what} on the Fediverse. To follow it, paste the address above
-into the search box of Mastodon or any Fediverse app — or use the form.</p>
-<form id="follow">
-  <label for="server">your server</label>
-  <input id="server" type="text" placeholder="mastodon.social" autocomplete="off"
-    required aria-describedby="follow-err">
-  <button type="submit">Follow</button>
-  <p class="err" id="follow-err" role="alert"></p>
-</form>
-<p class="hint">The form sends you to your own server's follow screen.</p>
-</main>
-<script>
-document.getElementById('follow').addEventListener('submit', (ev) => {
-  ev.preventDefault();
-  const s = document.getElementById('server').value.trim().replace(/^https?:\\/\\//, '').replace(/\\/.*$/, '');
-  const err = document.getElementById('follow-err');
-  const addr = document.querySelector('.address').textContent.trim();
-  if (!s) { err.textContent = 'Enter your server, e.g. mastodon.social'; return; }
-  err.textContent = '';
-  location.href = 'https://' + s + '/authorize_interaction?uri=' + encodeURIComponent(addr);
-});
-</script>
-</body>
-</html>
-`;
-}

package/lib/core/proof.mjs

@@ -1,79 +0,0 @@
-// proof.mjs — FEP-8b32 object integrity proofs (Data Integrity, eddsa-jcs-2022).
-//
-// An HTTP signature covers one delivery and says nothing about who wrote what
-// was inside it. A proof travels with the activity, so a server that receives
-// one of ours second-hand — carried by a group, or forwarded by a follower's
-// server — can tell it is ours without asking us.
-//
-// The RSA `#main-key` and its HTTP signatures are untouched; this is a second
-// key alongside, which is what the Data Integrity suites require.
-
-import crypto from 'node:crypto';
-import serialize from 'json-canon';
-
-// multicodec: an Ed25519 public key is its 32 raw bytes behind 0xed 0x01.
-const ED25519_PREFIX = Buffer.from([0xed, 0x01]);
-const B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
-
-export function base58btc(bytes) {
-  const b = Buffer.from(bytes);
-  let n = 0n;
-  for (const byte of b) n = (n << 8n) + BigInt(byte);
-  let out = '';
-  while (n > 0n) { out = B58[Number(n % 58n)] + out; n /= 58n; }
-  for (const byte of b) { if (byte !== 0) break; out = B58[0] + out; }
-  return out;
-}
-
-/** The `publicKeyMultibase` form of an Ed25519 public key in PEM. */
-export function multibaseEd25519(publicPem) {
-  const raw = Buffer.from(crypto.createPublicKey(publicPem).export({ format: 'jwk' }).x, 'base64url');
-  return 'z' + base58btc(Buffer.concat([ED25519_PREFIX, raw]));
-}
-
-/** The signing key, as WebCrypto wants it. */
-export function edPrivateKey(privatePem) {
-  const jwk = crypto.createPrivateKey(privatePem).export({ format: 'jwk' });
-  return crypto.subtle.importKey('jwk', { ...jwk, key_ops: ['sign'] }, { name: 'Ed25519' }, true, ['sign']);
-}
-
-const sha256 = (s) => crypto.createHash('sha256').update(s).digest();
-
-// The proof's own terms have to be declared in the document that carries it,
-// or a receiver that processes JSON-LD expands the proof away before it ever
-// looks at it. Declared BEFORE signing, because the proof covers the document
-// exactly as sent, `@context` included.
-export const DI_CTX = 'https://w3id.org/security/data-integrity/v1';
-
-function withProofContext(doc) {
-  const ctx = doc['@context'];
-  const list = Array.isArray(ctx) ? ctx : ctx ? [ctx] : [];
-  if (list.includes(DI_CTX)) return doc;
-  return { ...doc, '@context': [...list, DI_CTX] };
-}
-
-/**
- * Return the activity with a `proof` attached. The proof covers the activity
- * exactly as it goes on the wire, minus the proof itself — so it must be the
- * last thing added, and nothing may edit the activity afterwards.
- *
- * Whole seconds on `created`: a verifier re-serializes the timestamp it was
- * given, and a fractional one has more than one spelling.
- */
-export async function attachProof(activity, { privateKey, verificationMethod, created = new Date() } = {}) {
-  if (!privateKey || !verificationMethod || !activity || typeof activity !== 'object') return activity;
-  const { proof: _existing, ...bare } = activity;
-  const doc = withProofContext(bare);
-  const config = {
-    '@context': doc['@context'],
-    type: 'DataIntegrityProof',
-    cryptosuite: 'eddsa-jcs-2022',
-    verificationMethod,
-    proofPurpose: 'assertionMethod',
-    created: new Date(created).toISOString().replace(/\.\d+Z$/, 'Z'),
-  };
-  const digest = Buffer.concat([sha256(serialize(config)), sha256(serialize(doc))]);
-  const sig = await crypto.subtle.sign('Ed25519', privateKey, digest);
-  const { '@context': _ctx, ...emitted } = config;
-  return { ...doc, proof: { ...emitted, proofValue: 'z' + base58btc(Buffer.from(sig)) } };
-}