fedipod 0.8.0

package/lib/keys.mjs

@@ -0,0 +1,139 @@
+// keys.mjs — actor signing keys. RSA (Mastodon's draft-cavage HTTP Signatures
+// require RSA-SHA256) + Ed25519 (stored for future FEP-8b32 use, not yet in
+// the actor doc). PEM at rest (0600), CryptoKey in memory for Fedify's
+// signRequest.
+//
+// The key lives on THIS MACHINE by default (AP_HOME/keys.json): the pod host
+// then never holds it. `setup --keys pod` puts it in pod state instead,
+// which is what lets several devices sign as the same actor without copying
+// anything — see resolveKeys() for the guard that keeps the two modes from
+// silently breaking each other.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomic } from './home.mjs';
+
+const RSA_ALG = { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' };
+
+const localPath = (dir) => path.join(dir, 'keys.json');
+const readLocal = (dir) => {
+  try { return JSON.parse(fs.readFileSync(localPath(dir), 'utf8')); } catch { return null; }
+};
+// Atomic: this is the private key remote servers have cached, and a truncated
+// one cannot be recovered from anywhere — the pod does not hold it.
+const writeLocal = (dir, rec) => {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeJsonAtomic(localPath(dir), rec);
+};
+
+function generate() {
+  const rsa = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 });
+  const ed = crypto.generateKeyPairSync('ed25519');
+  return {
+    rsa: {
+      publicPem: rsa.publicKey.export({ type: 'spki', format: 'pem' }),
+      privatePem: rsa.privateKey.export({ type: 'pkcs8', format: 'pem' }),
+    },
+    ed25519: {
+      publicPem: ed.publicKey.export({ type: 'spki', format: 'pem' }),
+      privatePem: ed.privateKey.export({ type: 'pkcs8', format: 'pem' }),
+    },
+  };
+}
+
+/**
+ * Find or create the key record.
+ *
+ * The dangerous case is minting a NEW key when the actor already advertises
+ * one: remote servers cache the public key, so a fresh keypair silently
+ * invalidates every signature until the actor document is republished — and
+ * then breaks whichever other device holds the old key. So when key material
+ * is missing but the actor doc already has a key, we refuse and explain,
+ * unless the caller passes rotate:true deliberately.
+ *
+ * @param {object} store            pod-backed state store
+ * @param {object} o
+ * @param {string|null} o.localDir  AP_HOME when keys are local (the default)
+ * @param {boolean} o.rotate        mint a replacement on purpose
+ * @param {function} [o.actorHasKey] async () => boolean, consulted only when
+ *                                  no key material exists anywhere
+ * @param {function} [o.log]
+ */
+export async function resolveKeys(store, { localDir = null, rotate = false, actorHasKey = null, actorId = null, log = () => {} } = {}) {
+  let rec = localDir ? readLocal(localDir) : null;
+
+  // A key belongs to ONE actor. Adopting whatever keys.json happens to be in
+  // the directory is right within an identity and wrong across two: it is how
+  // a second setup in the same AP_HOME ended up signing as a different actor
+  // with the first one's key, which links the two publicly for anyone who
+  // compares the actor documents. A stamped key that names another actor is
+  // treated as absent, so the mint path (and its actorHasKey guard) applies.
+  if (rec && actorId && rec.mintedFor && rec.mintedFor !== actorId) {
+    log(`local keys.json belongs to ${rec.mintedFor} — not reusing it for ${actorId}`);
+    rec = null;
+  } else if (rec && actorId && !rec.mintedFor) {
+    // Written before keys were stamped: keep working, but say so, because it
+    // may be another actor's key.
+    log('keys.json predates per-identity stamping — if this actor was set up in a '
+      + 'home that already held a key, `setup --rotate-key` mints one of its own');
+  }
+
+  if (!rec) {
+    const podRec = store.read('keys.json', null);
+    if (podRec && localDir) {
+      // Migrating an existing actor to local keys: adopt the pod's key so
+      // the identity is preserved, then remove the pod's copy — leaving it
+      // would defeat the point of going local.
+      writeLocal(localDir, podRec);
+      rec = podRec;
+      const gone = await store.remove('keys.json');
+      log(gone
+        ? `signing key moved to ${localPath(localDir)} and deleted from pod state`
+        : `signing key copied to ${localPath(localDir)} — could NOT delete the pod copy, remove it by hand`);
+    } else {
+      rec = podRec;
+    }
+  }
+
+  if (!rec && !rotate && actorHasKey && await actorHasKey()) {
+    throw new Error(
+      'this actor already publishes a signing key, but no key material is present here.\n'
+      + `  Copy keys.json from your other device into ${localDir || 'pod state'}, or\n`
+      + '  re-run setup with --keys pod to share the key through the pod, or\n'
+      // --force, because rotate-key connects before it rotates and would meet
+      // this same refusal: advice has to name a command that can actually run.
+      + '  run `fedipod rotate-key --force` to replace the published key (breaks other devices).');
+  }
+
+  if (!rec || rotate) {
+    rec = { ...generate(), ...(actorId ? { mintedFor: actorId } : {}) };
+    if (localDir) writeLocal(localDir, rec); else store.write('keys.json', rec);
+    log(rotate ? 'minted a REPLACEMENT signing key — republish the profile' : 'minted a signing key');
+  }
+
+  const der = crypto.createPrivateKey(rec.rsa.privatePem).export({ type: 'pkcs8', format: 'der' });
+  const rsaPrivate = await crypto.subtle.importKey('pkcs8', der, RSA_ALG, true, ['sign']);
+  return { rsaPrivate, rsaPublicPem: rec.rsa.publicPem };
+}
+
+// Move a local key into pod state — the arrangement that lets several
+// devices sign as one actor once the state store is a pod they all reach.
+// The pod write is forced and checked BEFORE the local file goes: a key
+// remote servers have cached cannot be recovered from anywhere else.
+export async function moveKeysToPod(store, { localDir, actorId = null, log = () => {} }) {
+  const rec = readLocal(localDir);
+  if (!rec) throw new Error(`no local key at ${localPath(localDir)} — nothing to move`);
+  if (actorId && rec.mintedFor && rec.mintedFor !== actorId) {
+    throw new Error(`local keys.json belongs to ${rec.mintedFor}, not ${actorId} — refusing to move it`);
+  }
+  store.write('keys.json', rec);
+  const landed = store.commit ? await store.commit() : await store.flush?.();
+  if (landed === false) throw new Error('the pod write did not land — the local key is untouched');
+  fs.rmSync(localPath(localDir), { force: true });
+  log('signing key moved to pod state and removed from this machine');
+  return true;
+}
+
+// Back-compat alias for callers that just want "the keys, wherever they are".
+export const ensureKeys = (store, opts) => resolveKeys(store, opts);

package/lib/lease.mjs

@@ -0,0 +1,190 @@
+// 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. 90s
+// against a 5-minute TTL leaves three missed renewals of headroom and cuts that
+// load by two thirds. 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 = 300_000;
+const RENEW_MS = 90_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 {
+  constructor({ url, fetchImpl, log = console.log }) {
+    this.url = url;
+    this.fetchImpl = fetchImpl;
+    this.log = log;
+    this.id = crypto.randomUUID();
+    this.stopped = false;
+    this.timer = null;
+    this.heldUntil = 0;   // wall-clock end of the lease we last wrote
+  }
+
+  // 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.log('lease unreadable — staying a viewer'); return false; }
+    if (cur && cur.holder !== this.id && Date.now() < cur.expiresAt) return false;
+    const doc = { holder: this.id, expiresAt: Date.now() + TTL_MS };
+    if (!await this.write(doc)) return false;
+    const confirm = await this.readFresh();
+    if (confirm === UNREADABLE || confirm?.holder !== this.id) 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;
+    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/localapi.mjs

@@ -0,0 +1,87 @@
+// localapi.mjs — talking to an agent on this machine.
+//
+// The agent serves https and nothing else, on the one port it was given. Its
+// certificate is signed by this install's own certificate authority, which no
+// public trust store knows about, so a plain fetch() would refuse it. Every
+// caller here is on loopback reaching a listener this install started, so the
+// answer is to trust that one authority — never to skip verification.
+//
+// Returns a small fetch-shaped result ({ status, ok, text(), json() }) so call
+// sites read the way they did when this was cleartext http.
+
+import https from 'node:https';
+import fs from 'node:fs';
+import path from 'node:path';
+import { rootOf, apRoot } from './home.mjs';
+import { certPaths } from './certs.mjs';
+
+/**
+ * The authorities worth offering for a loopback call: this install's, and the
+ * machine's default install's. The well-known door on 8030 is held by
+ * whichever agent got there first, which may belong to a different root than
+ * the one this command is acting in — so both are candidates. An empty list
+ * means no certificate has been minted anywhere, and the call will fail the
+ * way any unreachable agent does.
+ */
+export function localCa(home) {
+  const read = (root) => {
+    try { return fs.readFileSync(certPaths(path.join(root, 'certs')).caCert); } catch { return null; }
+  };
+  // This install's own authority decides, and alone: every install names its
+  // authority the same thing, so offering two lets the verifier match by name
+  // and then fail on the signature. Only an install with no authority of its
+  // own falls back to the machine's default — that is the case of a command
+  // run outside any install reaching the well-known door.
+  const mine = home ? read(rootOf(home)) : null;
+  if (mine) return [mine];
+  try { const fallback = read(apRoot()); if (fallback) return [fallback]; } catch { /* no home dir */ }
+  return null;
+}
+
+/**
+ * One request to an agent on this machine. `home` names any identity under the
+ * install, which is how the CA is found; `port` is the agent's own port.
+ */
+export async function localFetch(home, port, pathname, opts = {}) {
+  const res = await once(home, port, pathname, opts);
+  // The well-known door answers with a redirect to whichever agent holds it,
+  // so a probe that lands there has to follow it the way fetch() would.
+  if (opts.redirect === 'manual' || res.status < 300 || res.status >= 400) return res;
+  const to = res.headers?.location;
+  if (!to) return res;
+  const target = new URL(to, `https://localhost:${port}`);
+  return once(home, Number(target.port) || 443, target.pathname + target.search, opts);
+}
+
+function once(home, port, pathname, { method = 'GET', headers = {}, body, timeout = 0 } = {}) {
+  const ca = localCa(home);
+  return new Promise((resolve, reject) => {
+    const req = https.request({
+      host: 'localhost', port, path: pathname, method,
+      // One-shot calls: a kept-alive socket holds the agent's listener open, so
+      // a shutdown asked for over this channel would never finish.
+      headers: { connection: 'close', ...headers },
+      ...(ca ? { ca } : {}),
+      // The certificate carries localhost and *.localhost; on some systems
+      // "localhost" resolves to ::1 first, which the name check still covers.
+      servername: 'localhost',
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        resolve({
+          status: res.statusCode,
+          ok: res.statusCode >= 200 && res.statusCode < 300,
+          headers: res.headers,
+          text: async () => text,
+          json: async () => JSON.parse(text),
+        });
+      });
+    });
+    req.on('error', reject);
+    if (timeout) req.setTimeout(timeout, () => req.destroy(new Error('timed out')));
+    if (body !== undefined && body !== null) req.write(body);
+    req.end();
+  });
+}