nattermatic 0.0.1 → 0.2.1

package/src/roster.js

@@ -0,0 +1,517 @@
+// Network membership: a set of signed records that members exchange and merge.
+//
+//   add    {host, fp, cert}  signed by a current member ("by"); the founding machine signs its own
+//   remove {fp, seen}        signed by a member that joined before the one removed; carries the
+//                            next discovery key, and lists the removed machine's records the
+//                            remover had (`seen`)
+//
+// Every member computes the same membership from the same set of records by replaying them in
+// (at, sig) order: a record counts only if its signer is a member at that point.
+//
+// Seniority: machines are ranked in the order they joined (the founder first), and a machine can
+// remove only machines ranked after it. So two machines can never remove each other.
+//
+// A removal is final. Timestamps are chosen by the signer, so a removed machine could sign records
+// dated before its removal; instead, a removed machine's records count only if its remover listed
+// them in `seen`. Anything else it signs is void, whatever its date. Between snapshots, a removed key
+// stays removed (re-adding a machine means a new key) and the set of records only grows, so merging
+// converges in any order and offline machines catch up on their next hello. A snapshot replaces all
+// of that with one record: see replay.
+import fs from 'node:fs'
+import crypto from 'node:crypto'
+import { signRecord, verifyRecord, newDiscoveryKey, recId, recKey } from './crypto.js'
+import { fingerprint, certDer } from './cert.js'
+import { normHost, machineName, writeAtomic } from './config.js'
+
+// New records stop being taken in at this size, so that a roster always fits in one hello (8 MB):
+// if it didn't, this node's removals would never reach anyone. The limit doesn't apply to loading our
+// own file, so nothing already held is lost, or to a removal that must get in (see mustTake), so a
+// full roster can always be cleaned up. There is at most one of those per machine, of at most
+// MAX_TAKEN, plus a list entry for each machine its target added, plus what it clears. A machine's add
+// takes at least about 400 bytes, so that's some 2600 machines at the very most, each with one adder,
+// and what's cleared is at most what was held: 1 MB + 2600 * 2 KB + 2600 * 25 B + 1 MB is about
+// 7 MB, whatever a member signs.
+export const MAX_ROSTER_BYTES = 1 << 20
+const MAX_TAKEN = 2 << 10              // a removal listing no one, with room for some 70 adds not held here
+const SEEN_ENTRY = 25                  // what listing one record in `seen` takes
+const MAX_FORGED = 20_000              // bad signatures remembered, so a resent one costs nothing
+const MAX_FUTURE_MS = 3600_000     // a record stamped further ahead than this is refused (bad clock)
+const MAX_SEEN = 4000                  // more than a full roster's adds, so no machine can make itself impossible to remove
+const MAX_KEYS = 4000                  // discovery keys a snapshot carries: every one still in its grace period, if it can
+const MAX_DROPPED = 50                 // adds that didn't count, kept per removed machine (so their keys stay known as dropped)
+// a replaced discovery key still opens other members' gates for this long, so a machine that was
+// offline during a removal can catch up; after that it needs a new invite
+export const DK_GRACE_MS = 14 * 86400_000
+
+/** @typedef {import('./types.js').RosterRecord} RosterRecord */
+/** @typedef {import('./types.js').Member} Member */
+
+const ASCII_KEY = /^[\w+/=-]+$/        // fingerprints and signatures: base64, in either alphabet
+
+/** @param {any} r @returns {r is RosterRecord} */
+function wellFormed(r) {
+  if (!r || typeof r !== 'object') return false
+  if (r.type !== 'add' && r.type !== 'remove' && r.type !== 'snapshot') return false
+  if (typeof r.fp !== 'string' || !ASCII_KEY.test(r.fp) || r.fp.length > 64 || typeof r.by !== 'string' || !ASCII_KEY.test(r.by) || r.by.length > 64) return false
+  if (typeof r.sig !== 'string' || !ASCII_KEY.test(r.sig) || r.sig.length > 200 || !Number.isSafeInteger(r.at) || r.at < 0) return false
+  if (r.dk !== undefined && (typeof r.dk !== 'string' || r.dk.length !== 44 || Buffer.from(r.dk, 'base64').length !== 32)) return false
+  if (r.type !== 'add' && (r.host !== undefined || r.cert !== undefined)) return false
+  if (r.type === 'snapshot' ? !snapshotShape(r) : r.list !== undefined || r.keys !== undefined) return false
+  if (r.seen !== undefined && (r.type !== 'remove' || !Array.isArray(r.seen) || r.seen.length > MAX_SEEN || !r.seen.every((/** @type {unknown} */ x) => typeof x === 'string' && /^[\w-]{22}$/.test(x)))) return false
+  // strict base64: the decoder skips anything else, so a good certificate could carry padding
+  if (r.type === 'add' && (typeof r.host !== 'string' || r.host.length > 253 || typeof r.cert !== 'string' || r.cert.length > 1024 || !/^[A-Za-z0-9+/]+={0,2}$/.test(r.cert))) return false
+  return true
+}
+
+/** @param {RosterRecord} r */
+function snapshotShape(r) {
+  const key = (/** @type {unknown} */ s) => typeof s === 'string' && s.length <= 64 && ASCII_KEY.test(s)
+  return r.fp === r.by && r.dk === undefined && r.seen === undefined &&
+    Array.isArray(r.list) && r.list.length > 0 && r.list.length <= MAX_SEEN &&
+    r.list.every(m => Array.isArray(m) && m.length === 5 && typeof m[0] === 'string' && m[0].length <= 253 && key(m[1]) &&
+      typeof m[2] === 'string' && m[2].length <= 1024 && /^[A-Za-z0-9+/]+={0,2}$/.test(m[2]) && Number.isSafeInteger(m[3]) && m[3] >= 0 && key(m[4])) &&
+    Array.isArray(r.keys) && r.keys.length > 0 && r.keys.length <= MAX_KEYS &&
+    r.keys.every(k => Array.isArray(k) && k.length === 2 && typeof k[0] === 'string' && k[0].length === 44 && Buffer.from(k[0], 'base64').length === 32 && Number.isSafeInteger(k[1]) && k[1] >= 0)
+}
+
+/** What a snapshot says about each member, in the shape of the add that made it. @param {RosterRecord} r */
+const snapshotAdds = r => (r.list ?? []).map(([host, fp, cert, at, by]) => /** @type {RosterRecord} */ ({ type: 'add', host, fp, cert, at, by, sig: '' }))
+
+export class Roster {
+  /**
+   * @param {{ net: string, records: RosterRecord[] }} data
+   * @param {string | null} [file] where save() writes
+   */
+  constructor(data, file = null) {
+    this.net = data.net
+    this.file = file
+    /** @type {RosterRecord[]} */
+    this.records = []
+    /** @type {Set<string>} ids of the records held (see recId) */
+    this.ids = new Set()
+    /** @type {Set<string>} records whose signature checked out (see recKey) */
+    this.verified = new Set()
+    /** @type {Set<string>} records whose signature didn't: that can't change, so they aren't checked twice */
+    this.forged = new Set()
+    /** @type {Map<string, Member>} fp -> member */
+    this.members = new Map()
+    /** @type {Map<string, Member>} host -> member */
+    this.byHost = new Map()
+    /** @type {Map<string, Member>} every machine that joined, removed or not */
+    this.ranked = new Map()
+    /** @type {Map<string, { at: number, by: string }>} */
+    this.removed = new Map()
+    /** @type {string[]} discovery keys, oldest first */
+    this.dks = []
+    /** @type {number[]} when each discovery key was introduced */
+    this.dkAt = []
+    /** @type {Set<string>} keys added by a machine that was removed before the add was seen: never members */
+    this.dropped = new Set()
+    /** @type {RosterRecord | null} the founder's newest snapshot, which everything now starts from */
+    this.snapshot = null
+    /** @type {Map<string, { host: string, pem: string, publicKey: crypto.KeyObject } | null>} parsed add records (see recKey) */
+    this.parsed = new Map()
+    this.merge(data.records, { trustClock: true })
+  }
+
+  /** @param {string} file */
+  static load(file) {
+    const d = JSON.parse(fs.readFileSync(file, 'utf8'))
+    if (!d || typeof d.net !== 'string' || !Array.isArray(d.records)) throw new Error(`bad roster ${file}`)
+    return new Roster(d, file)
+  }
+
+  save() {
+    if (!this.file) return
+    writeAtomic(this.file, JSON.stringify({ net: this.net, records: this.records }, null, 1) + '\n', 0o600)
+  }
+
+  /** The current discovery key. */
+  get dk() { return this.dks[this.dks.length - 1] }
+
+  /** Discovery keys that open this node's gate: the current one, and ones replaced recently. */
+  gateDks(now = Date.now()) {
+    return this.dks.filter((_, i) => i === this.dks.length - 1 || this.dkAt[i + 1] > now - DK_GRACE_MS)
+  }
+
+  /** May member `by` remove member `fp`? (only machines that joined after it) @param {string} by @param {string} fp */
+  canRemove(by, fp) {
+    const a = this.members.get(by), b = this.members.get(fp)
+    return !!a && !!b && a.rank < b.rank
+  }
+
+  /**
+   * Must this removal get in even when the roster is full? It takes a current member off the network,
+   * by a machine that joined before it, so refusing it would leave the machine on here and off
+   * elsewhere, and a flooder could keep itself on. It may be as big as a removal has any reason to be:
+   * a list entry for each machine its target really added, and otherwise no bigger than what it clears
+   * (the target's adds it doesn't list stop counting). So a list padded with made-up ids gets nothing
+   * for them, and a member can't stop its own removal by filling one node with adds no one else has.
+   * @param {RosterRecord} r @param {number} size its size in bytes
+   * @param {() => Map<string, { id: string, size: number, made: boolean }[]>} adds what each machine has signed that its removal would list or clear
+   */
+  mustTake(r, size, adds) {
+    const s = this.ranked.get(r.by), t = this.ranked.get(r.fp)
+    if (r.type !== 'remove' || !s || !t || s.rank >= t.rank || !this.members.has(r.fp)) return false
+    const listed = new Set(r.seen ?? [])
+    let room = MAX_TAKEN
+    for (const a of adds().get(r.fp) ?? []) room += !listed.has(a.id) ? a.size : a.made ? SEEN_ENTRY : 0
+    return size <= room
+  }
+
+  /** @param {string} key */
+  noteForged(key) {
+    if (this.forged.size >= MAX_FORGED) this.forged.clear()
+    this.forged.add(key)
+  }
+
+  /** Did the founder sign this snapshot? It carries the founder's own certificate. @param {RosterRecord} r */
+  signedSnapshot(r) {
+    try {
+      const x509 = new crypto.X509Certificate(Buffer.from(String(r.list?.[0]?.[2]), 'base64'))
+      return r.by === this.net && fingerprint(x509) === this.net && r.list?.[0]?.[1] === this.net && verifyRecord(x509.publicKey, r)
+    } catch { return false }
+  }
+
+  /** What a machine's removal would list or clear, by who signed it. */
+  addsBySigner() {
+    /** @type {Map<string, { id: string, size: number, made: boolean }[]>} */
+    const out = new Map()
+    for (const r of this.records) {
+      // a removal of a key no one has heard of goes when its signer does, so it counts as much as an add
+      if (r.type !== 'add' && this.ranked.has(r.fp)) continue
+      if (!out.has(r.by)) out.set(r.by, [])
+      out.get(r.by)?.push({ id: recId(r), size: Buffer.byteLength(JSON.stringify(r)), made: this.ranked.get(r.fp)?.by === r.by })
+    }
+    return out
+  }
+
+  /**
+   * Add records we were sent (or made). Returns true if the set of records changed.
+   * @param {unknown} list @param {{ trustClock?: boolean }} [opts]
+   * @returns {boolean}
+   */
+  merge(list, { trustClock = false } = {}) {
+    // a snapshot first: what it clears makes room for what came with it
+    const isSnapshot = (/** @type {any} */ r) => r?.type === 'snapshot'
+    if (Array.isArray(list) && list.some(isSnapshot) && !list.every(isSnapshot)) {
+      const a = this.merge(list.filter(isSnapshot), { trustClock })
+      return this.merge(list.filter(r => !isSnapshot(r)), { trustClock }) || a
+    }
+    let added = false
+    const before = this.ids
+    let bytes = trustClock ? 0 : Buffer.byteLength(JSON.stringify(this.records))
+    /** @type {Set<string>} machines taken off past the limit in this batch: once is enough */
+    const over = new Set()
+    /** @type {ReturnType<Roster['addsBySigner']> | undefined} */
+    let adds
+    for (const r of Array.isArray(list) ? list : []) {
+      if (!wellFormed(r) || this.ids.has(recId(r)) || this.forged.has(recKey(r))) continue
+      if (!trustClock && r.at > Date.now() + MAX_FUTURE_MS) continue
+      // what a snapshot has already settled, sent by a machine that hasn't heard of it yet
+      const held = this.snapshot
+      if (held && r.type === 'add' && r.at <= held.at) continue
+      if (held && r.type === 'snapshot' && (r.at < held.at || (r.at === held.at && recId(r) < recId(held)))) continue
+      const o = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (r))
+      const clean = /** @type {RosterRecord} */ (/** @type {unknown} */ (Object.fromEntries(['type', 'host', 'fp', 'cert', 'at', 'by', 'dk', 'seen', 'list', 'keys', 'sig'].filter(k => o[k] !== undefined).map(k => [k, o[k]]))))
+      const size = Buffer.byteLength(JSON.stringify(clean))
+      if (clean.type === 'snapshot') {
+        // it's what makes room, so it always gets in, and only the founder's can
+        if (!this.signedSnapshot(clean)) { this.noteForged(recKey(clean)); continue }
+      } else if (!trustClock && bytes + size > MAX_ROSTER_BYTES) {
+        if (over.has(clean.fp) || !this.mustTake(clean, size, () => adds ??= this.addsBySigner())) continue
+        over.add(clean.fp)
+      }
+      bytes += size
+      this.records.push(clean)
+      added = true
+    }
+    if (!added) return false
+    this.replay()
+    return this.ids.size !== before.size || [...this.ids].some(s => !before.has(s))
+  }
+
+  /**
+   * Recompute membership: a pure function of the set of records, so every node that holds the same
+   * records agrees, whatever order they arrived in.
+   *
+   * Machines are settled in joining order. Whether a machine is removed depends only on records
+   * signed by machines that joined before it (only they can remove it), and those are settled
+   * first. So nothing is ever decided twice, and a single pass suffices.
+   *
+   * - A removal by an earlier machine always stands, even if its signer is removed too: a removal
+   *   can't be undone by removing the remover (concurrent removals all stand).
+   * - Any other record signed by a removed machine (an add) counts only if every removal of that
+   *   machine lists it in `seen`. So a removed machine can't add machines, backdated or not.
+   * - The discovery key is the newest one introduced by a machine that is still a member, so a
+   *   key made by a removed machine is never current.
+   *
+   * Records are kept if they could ever count: everything signed by current members, and what
+   * counts of what removed machines signed. Anything else can never count, whatever arrives later
+   * (since the last snapshot, removals only accumulate), so every node reaches the same result.
+   *
+   * A snapshot replaces all of that history. The founder's newest one is where replay starts: its
+   * members hold their places in joining order, and its keys are the discovery keys so far. After it:
+   * - An add counts only if it's dated later. So a removed machine can't come back on an old add,
+   *   and an add the founder hadn't heard of needs a new invite.
+   * - A removal of a machine in the snapshot counts whatever its date, if its signer is in it too and
+   *   joined first, and it's dated after that machine's add. So a removal made at the same moment
+   *   as the snapshot isn't lost, and one from before a forgotten key was let back in says nothing
+   *   about the machine there now, at this snapshot or any later one.
+   * - Nothing else from before it counts, so it's dropped, and the roster shrinks.
+   */
+  replay() {
+    // ties go by content: which encoding of a signature a node happened to get must not decide anything
+    /** @type {Map<RosterRecord, string>} */
+    const idOf = new Map(this.records.map(r => [r, recId(r)]))
+    const tie = (/** @type {RosterRecord} */ a, /** @type {RosterRecord} */ b) => { const x = /** @type {string} */ (idOf.get(a)), y = /** @type {string} */ (idOf.get(b)); return x < y ? -1 : x > y ? 1 : 0 }
+    this.records.sort((a, b) => a.at - b.at || tie(a, b))
+    /** @param {crypto.KeyObject} pub @param {RosterRecord} r */
+    const ok = (pub, r) => {
+      const k = recKey(r)
+      if (this.verified.has(k)) return true
+      if (!verifyRecord(pub, r)) { this.noteForged(k); return false }
+      this.verified.add(k)
+      return true
+    }
+    /** @param {RosterRecord} r */
+    const parse = r => {
+      const k = recKey(r)
+      let c = this.parsed.get(k)
+      if (c === undefined) {
+        c = null
+        try {
+          const x509 = new crypto.X509Certificate(Buffer.from(String(r.cert), 'base64'))
+          const host = normHost(String(r.host))
+          if (host === r.host && machineName(host) && fingerprint(x509) === r.fp) c = { host, pem: x509.toString(), publicKey: x509.publicKey }
+        } catch {}
+        this.parsed.set(k, c)
+      }
+      return c
+    }
+
+    // (signatures were checked on the way in)
+    const snapshot = [...this.records].reverse().find(r => r.type === 'snapshot' && snapshotAdds(r).every(parse)) ?? null
+    const since = snapshot?.at ?? -1
+    const base = snapshot ? snapshotAdds(snapshot) : []
+    const addedAt = new Map(base.map(r => [r.fp, r.at]))
+    /**
+     * Is this removal about a key a snapshot forgot, rather than the machine there now? An honest
+     * removal is dated after the add it answers, as its signer held that add.
+     * @param {RosterRecord} r
+     */
+    const stale = r => {
+      if (r.type !== 'remove' || r.at > since) return false
+      const added = addedAt.get(r.fp)
+      return added === undefined || r.at < added
+    }
+
+    /** @type {Map<string, RosterRecord[]>} target fp -> remove records naming it */
+    const removesOf = new Map()
+    for (const r of this.records) if (r.type === 'remove') { if (!removesOf.has(r.fp)) removesOf.set(r.fp, []); removesOf.get(r.fp)?.push(r) }
+
+    /** @type {Map<string, Member>} every machine that joined (ranked), removed or not */
+    const ranked = new Map()
+    /** @type {Map<string, { removed: false } | { removed: true, at: number, by: string, seen: Set<string>[] }>} */
+    const statusMemo = new Map()
+    /** The removals that stand against `fp` (by machines ranked before it). @param {string} fp */
+    const status = fp => {
+      const known = statusMemo.get(fp)
+      if (known) return known
+      const m = ranked.get(fp)
+      /** @type {RosterRecord[]} */
+      const stand = []
+      /** @type {Set<string>} */
+      const signers = new Set()
+      // one removal per signer counts: its earliest (so signing more can't change the outcome)
+      if (m) for (const r of removesOf.get(fp) || []) {
+        const s = ranked.get(r.by)
+        if (s && s.rank < m.rank && !stale(r) && !signers.has(r.by) && ok(s.publicKey, r)) { stand.push(r); signers.add(r.by) }
+      }
+      const st = stand.length
+        ? { removed: /** @type {const} */ (true), at: stand[0].at, by: stand[0].by, seen: stand.map(r => new Set(r.seen ?? [])) }
+        : { removed: /** @type {const} */ (false) }
+      statusMemo.set(fp, st)
+      return st
+    }
+    /** Does `r`, signed by ranked machine `by`, count? @param {string} by @param {RosterRecord} r */
+    const counts = (by, r) => {
+      const st = status(by)
+      return !st.removed || st.seen.every(seen => seen.has(recId(r)))
+    }
+
+    /** @type {Map<string, Member>} host -> the machine holding that name */
+    const nameHolder = new Map()
+    /** @type {Set<string>} keys whose add didn't count because their adder was removed first */
+    const dropped = new Set()
+    let rank = 0
+    for (const r of base) {
+      const c = parse(r)
+      if (!c || ranked.has(r.fp)) continue
+      const m = { host: c.host, fp: r.fp, pem: c.pem, publicKey: c.publicKey, at: r.at, by: r.by, rank: rank++ }
+      ranked.set(r.fp, m)
+      nameHolder.set(c.host, m)
+    }
+    for (const r of this.records) {
+      if (r.type !== 'add' || r.at <= since) continue
+      const c = parse(r)
+      if (!c) continue
+      const genesis = r.by === r.fp
+      if (genesis) {
+        if (r.fp !== this.net || ranked.size || !ok(c.publicKey, r)) continue
+      } else {
+        const s = ranked.get(r.by)
+        if (!s || !ok(s.publicKey, r)) continue
+      }
+      if (ranked.has(r.fp)) continue
+      if (!genesis && !counts(r.by, r)) { dropped.add(r.fp); continue }
+      const holder = nameHolder.get(c.host)
+      if (holder && !status(holder.fp).removed) continue            // the name is taken
+      const m = { host: c.host, fp: r.fp, pem: c.pem, publicKey: c.publicKey, at: r.at, by: r.by, rank: rank++ }
+      ranked.set(r.fp, m)
+      nameHolder.set(c.host, m)
+    }
+
+    /** @type {Map<string, Member>} */
+    const members = new Map()
+    /** @type {Map<string, Member>} */
+    const byHost = new Map()
+    /** @type {Map<string, { at: number, by: string }>} */
+    const removed = new Map()
+    for (const m of ranked.values()) {
+      const st = status(m.fp)
+      if (st.removed) removed.set(m.fp, { at: st.at, by: st.by })
+      else { members.set(m.fp, m); byHost.set(m.host, m) }
+    }
+    for (const fp of ranked.keys()) dropped.delete(fp)
+
+    // Only records whose signature checks out are kept, whoever they claim to be from. Of those: what
+    // current members signed, and of what removed machines signed only what counts (adds every
+    // remover had seen). Copies of a record (the same content, signed differently) are kept once. A removal is kept if it is the first by its signer for a
+    // target it can remove. Nothing else from a removed or dropped key can ever count, whatever
+    // arrives later, so dropping it keeps every node's result the same, and a removed machine can't
+    // fill the roster. Adds that didn't count are kept too (at most MAX_DROPPED per removed machine),
+    // so their keys stay known as dropped: messages from them are refused instead of retried.
+    /** @type {Set<string>} */
+    const firstRemove = new Set()
+    /** @type {Map<string, number>} */
+    const droppedKept = new Map()
+    /** @type {Set<string>} */
+    const copies = new Set()
+    const once = (/** @type {RosterRecord} */ r) => { const id = recId(r); if (copies.has(id)) return false; copies.add(id); return true }
+    const kept = this.records.filter(r => {
+      if (r.type === 'snapshot') return r === snapshot && once(r)
+      if ((r.type === 'add' && r.at <= since) || stale(r)) return false
+      const s = ranked.get(r.by)
+      if (!s || !ok(s.publicKey, r) || !once(r)) return false
+      if (r.type === 'add') {
+        if (!parse(r)) return false                                             // can never count
+        if (members.has(r.by)) return true
+        if (ranked.get(r.fp)?.by === r.by && counts(r.by, r)) return true
+        if (!dropped.has(r.fp)) return false
+        const n = (droppedKept.get(r.by) || 0) + 1
+        droppedKept.set(r.by, n)
+        return n <= MAX_DROPPED
+      }
+      // the removal that counts for this signer and target (the only one status() looks at)
+      const t = ranked.get(r.fp)
+      if (t && s.rank < t.rank) {
+        if (firstRemove.has(`${r.by} ${r.fp}`)) return false
+        firstRemove.add(`${r.by} ${r.fp}`)
+        return true
+      }
+      // a machine it can't remove stays that way; one we haven't heard of yet may turn out otherwise
+      return !t && members.has(r.by)
+    })
+
+    /** @type {string[]} */
+    const dks = (snapshot?.keys ?? []).map(k => k[0])
+    /** @type {number[]} */
+    const dkAt = (snapshot?.keys ?? []).map(k => k[1])
+    for (const r of kept) {
+      const signer = members.get(r.by)
+      if (!r.dk || !signer) continue                               // never a key made by a removed machine
+      const target = ranked.get(r.fp)
+      // the founder's first key, and the keys in removals that stand: no other record brings one in.
+      // (This is the only check of which removals may bring in a key, whatever the checks above imply.)
+      if (r.type === 'add' ? r.by === r.fp && r.fp === this.net : !!target && status(r.fp).removed && signer.rank < target.rank) {
+        dks.push(r.dk)
+        dkAt.push(Math.max(r.at, since))         // it replaced the snapshot's key no earlier than the snapshot
+      }
+    }
+    this.parsed = new Map([...base, ...kept.filter(r => r.type === 'add')].map(r => [recKey(r), this.parsed.get(recKey(r)) ?? null]))
+    if (this.verified.size > MAX_FORGED) this.verified = new Set(kept.map(recKey).filter(k => this.verified.has(k)))
+    Object.assign(this, { members, byHost, ranked, removed, dropped, dks, dkAt, snapshot, records: kept, ids: new Set(kept.map(recId)) })
+  }
+
+  /** A timestamp later than every record we hold, so our records sort after what we've seen
+   * even if our clock is behind the machine that added us. */
+  nextAt() {
+    return Math.max(Date.now(), ...this.records.map(r => r.at + 1))
+  }
+
+  /**
+   * Sign and merge a record adding `host` (whose certificate is `pem`).
+   * @param {import('./types.js').Identity} me @param {string} host @param {string} pem
+   */
+  add(me, host, pem) {
+    /** @type {Omit<RosterRecord, 'sig'>} */
+    const r = { type: 'add', host, fp: fingerprint(pem), cert: certDer(pem), at: this.nextAt(), by: me.fp }
+    const rec = { ...r, sig: signRecord(me.key, r) }
+    this.merge([rec])
+    if (!this.ids.has(recId(rec))) throw new Error('the network has reached its size limit: remove any machine that is flooding it, then run `natter compact` on the founding machine')
+    return rec
+  }
+
+  /**
+   * Sign and merge a record removing `fp` (which must have joined after us); rotates the discovery
+   * key, and lists the removed machine's records we have: nothing else it signs will count.
+   * @param {import('./types.js').Identity} me @param {string} fp
+   */
+  remove(me, fp) {
+    if (!this.canRemove(me.fp, fp)) throw new Error('only a machine that joined earlier can remove this one')
+    // the adds that made machines, once each (records are in replay order, so the first is the one that counted)
+    /** @type {Map<string, string>} */
+    const made = new Map()
+    for (const x of this.records) {
+      if (x.by === fp && x.type === 'add' && !made.has(x.fp) && this.ranked.get(x.fp)?.by === fp) made.set(x.fp, recId(x))
+    }
+    /** @type {Omit<RosterRecord, 'sig'>} */
+    const r = { type: 'remove', fp, at: this.nextAt(), by: me.fp, dk: newDiscoveryKey(), seen: [...made.values()] }
+    const rec = { ...r, sig: signRecord(me.key, r) }
+    this.merge([rec])
+    if (!this.ids.has(recId(rec)) || this.members.has(fp)) throw new Error('its removal could not be recorded')
+    return rec
+  }
+
+  /**
+   * Sign and merge a snapshot of the current members, which replaces everything before it. Only the
+   * founder's counts: it's the one machine every member trusts and no one can remove. Removed
+   * machines are forgotten, and a new discovery key comes in, so whatever a removed machine still
+   * held stops being current.
+   * @param {import('./types.js').Identity} me
+   */
+  compact(me) {
+    if (me.fp !== this.net) throw new Error('only the founding machine can do this')
+    const at = this.nextAt()
+    const live = this.gateDks()
+    const keys = this.dks.flatMap((dk, i) => live.includes(dk) ? [/** @type {[string, number]} */ ([dk, this.dkAt[i]])] : []).slice(1 - MAX_KEYS)
+    /** @type {Omit<RosterRecord, 'sig'>} */
+    const r = {
+      type: 'snapshot', fp: me.fp, by: me.fp, at,
+      list: [...this.members.values()].sort((a, b) => a.rank - b.rank).map(m => [m.host, m.fp, certDer(m.pem), m.at, m.by]),
+      keys: [...keys, [newDiscoveryKey(), at]],
+    }
+    const rec = { ...r, sig: signRecord(me.key, r) }
+    this.merge([rec])
+    if (this.snapshot === null || recId(this.snapshot) !== recId(rec)) throw new Error('the snapshot could not be recorded')
+    return rec
+  }
+
+  /** A new network whose only member is `me`, called `host`. @param {import('./types.js').Identity} me @param {string} host */
+  static genesis(me, host, /** @type {string | null} */ file = null) {
+    /** @type {Omit<RosterRecord, 'sig'>} */
+    const r = { type: 'add', host, fp: me.fp, cert: certDer(me.cert), at: Date.now(), by: me.fp, dk: newDiscoveryKey() }
+    return new Roster({ net: me.fp, records: [{ ...r, sig: signRecord(me.key, r) }] }, file)
+  }
+}

package/src/self.js

@@ -0,0 +1,41 @@
+// How nattermatic runs itself and finds the files it ships with. Two forms:
+// - an npm install: `node bin/natter.js`, with the package directory beside it;
+// - a single executable (the macOS app): Node's single-executable feature, where the executable is
+//   the whole program and the files it ships with (install.sh, the npm package it hands to
+//   machines that join through it) are embedded in it.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import sea from 'node:sea'
+
+/** Running as a single executable? */
+export const SEA = (() => { try { return sea.isSea() } catch { return false } })()
+
+// A single executable can't be given Node's --no-warnings flag; node:sqlite's experimental warning
+// would otherwise be printed on every command.
+if (SEA) process.removeAllListeners('warning')
+
+/** The package directory (npm installs only). */
+export const PKG_ROOT = SEA ? '' : path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+/** The program's entry point: bin/natter.js, or the executable itself. */
+export const BIN = SEA ? process.execPath : path.join(PKG_ROOT, 'bin', 'natter.js')
+
+/**
+ * The app bundle this executable runs from (the macOS app on Apple silicon), or null. A machine
+ * running the app hands it to Macs that join through its invites.
+ * @returns {string | null}
+ */
+export function appBundle() {
+  if (!SEA || process.platform !== 'darwin' || process.arch !== 'arm64') return null
+  const dir = path.resolve(process.execPath, '..', '..', '..')
+  return dir.endsWith('.app') && fs.existsSync(path.join(dir, 'Contents', 'Info.plist')) ? dir : null
+}
+
+/**
+ * A file nattermatic ships with (install.sh, the npm package). For an npm install, `name` is
+ * relative to the package directory; a single executable has it embedded under the same name.
+ * @param {string} name @returns {Buffer}
+ */
+export function readAsset(name) {
+  return SEA ? Buffer.from(sea.getAsset(name)) : fs.readFileSync(path.join(PKG_ROOT, name))
+}