create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/lib/machine-pairing.js

@@ -0,0 +1,238 @@
+'use strict';
+
+// WP-3 (docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §6.3, D-6/D-9, §9 S-15/S-16/S-23):
+// the pairing code — the BOX side.
+//
+// A machine that wants to join a pool shows an 8-character code. The joining member posts the code
+// plus the pool token to the box's PRE-AUTH `POST /api/machine-pairing/join`; the box verifies the
+// code, burns it, and adopts the token. Rules that shape this module:
+//
+//   * §6.3 verbatim — alphabet, length, TTL, the 3-live-offer ceiling and the 5-wrong-redeem burn.
+//   * The code is a BEARER secret for one redemption. It is NEVER stored and NEVER logged: the only
+//     thing that reaches the database is `sha256(normalizeCode(code))` hex (D-6, §11 anti-goals).
+//   * `redeem` compares hashes with crypto.timingSafeEqual over EQUAL-LENGTH buffers — the digest is
+//     fixed-width, so a length mismatch is a malformed row, never a timing oracle.
+//   * Expired and already-used offers answer the SAME `pairing_code_invalid` code: a wrong code, a
+//     stale offer and a burned one must be indistinguishable to the caller, or the endpoint becomes
+//     an oracle for "was there ever an offer here".
+//
+// LEAF module: node built-ins only. Everything is injectable (`now`, `randomBytes`, `db`) so the
+// unit test never touches the real clock, the real CSPRNG or a real database (clock-free rule).
+
+const crypto = require('node:crypto');
+
+const CODE_ALPHABET = 'BCDFGHJKLMNPQRSTVWXZ'; // RFC 8628 §6.1 — no vowels, no 0/1/I/O look-alikes
+const CODE_LENGTH = 8;                        // shown (and typed) as XXXX-XXXX
+const OFFER_TTL_MS = 600_000;
+const MAX_LIVE_OFFERS = 3;
+const MAX_FAILED_REDEEMS = 5;
+
+// The container the box prints/paints once: `ctmpair1:` + base64url(JSON).
+const PAIRING_STRING_PREFIX = 'ctmpair1:';
+
+// |CODE_ALPHABET| = 20 and 256 is NOT a multiple of 20, so `byte % 20` would favour the first four
+// letters roughly 13% of the time. 240 = floor(256/20)*20 is the largest multiple of 20 that fits in
+// a byte: every byte >= 240 is discarded and re-drawn (RFC 8628 §6.1 rejection sampling).
+const REJECT_AT = Math.floor(256 / CODE_ALPHABET.length) * CODE_ALPHABET.length; // 240
+// A batch per draw, and a hard ceiling on batches so a broken/scripted `randomBytes` cannot spin
+// this loop forever — 32 batches of 16 bytes is a 1-in-10^22 tail, never a real event.
+const DRAW_BATCH = CODE_LENGTH * 2;
+const MAX_DRAW_BATCHES = 32;
+
+/**
+ * §6.3 verbatim: uppercase, then drop every character outside the alphabet. Hyphens and spaces are
+ * therefore formatting, not content — `wdjb-mjht`, `WDJB MJHT` and `WDJBMJHT` are one code.
+ */
+function normalizeCode(value) {
+  return String(value || '').toUpperCase().replace(/[^BCDFGHJKLMNPQRSTVWXZ]/g, '');
+}
+
+/** The display form the offer response carries: XXXX-XXXX (empty in => empty out). */
+function formatCode(value) {
+  const code = normalizeCode(value);
+  if (code.length !== CODE_LENGTH) return code;
+  return `${code.slice(0, 4)}-${code.slice(4)}`;
+}
+
+/** D-6: the ONLY representation of a code that is ever persisted. */
+function hashCode(value) {
+  return crypto.createHash('sha256').update(normalizeCode(value), 'utf8').digest('hex');
+}
+
+/**
+ * Constant-time hash compare over equal-length buffers. Two sha256 digests are always 64 chars, so
+ * a mismatch in length means a malformed stored row — false, never a throw and never a compare.
+ */
+function codeHashEquals(left, right) {
+  const a = Buffer.from(String(left == null ? '' : left), 'utf8');
+  const b = Buffer.from(String(right == null ? '' : right), 'utf8');
+  if (!a.length || a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+/** `XXXX-XXXX` -> a batch of random letters, rejection-sampled (no modulo bias). */
+function mintCode(randomBytes) {
+  const out = [];
+  for (let batch = 0; batch < MAX_DRAW_BATCHES && out.length < CODE_LENGTH; batch += 1) {
+    const bytes = randomBytes(DRAW_BATCH);
+    for (const byte of bytes) {
+      if (byte >= REJECT_AT) continue; // biased tail — re-draw, never fold
+      out.push(CODE_ALPHABET[byte % CODE_ALPHABET.length]);
+      if (out.length >= CODE_LENGTH) break;
+    }
+  }
+  if (out.length < CODE_LENGTH) throw new Error('machine-pairing: randomBytes did not yield an unbiased code');
+  return out.join('');
+}
+
+/**
+ * §6.3: `'ctmpair1:' + base64url(JSON{v:1,i:instanceId,n:displayName,u:candidates,c:code})`.
+ * `c` is the DISPLAY form (XXXX-XXXX); `normalizeCode` strips the hyphen on the way back in.
+ */
+function encodePairingString({ instanceId, displayName, urls, code } = {}) {
+  const payload = JSON.stringify({
+    v: 1,
+    i: String(instanceId || ''),
+    n: String(displayName || ''),
+    u: (Array.isArray(urls) ? urls : []).map((url) => String(url || '')).filter(Boolean),
+    c: String(code || ''),
+  });
+  return `${PAIRING_STRING_PREFIX}${Buffer.from(payload, 'utf8').toString('base64url')}`;
+}
+
+/**
+ * The member side of the container. Returns null for anything that is not a v1 pairing string —
+ * a hand-edited or truncated string is a 400 (`pairing_string_invalid`), never a throw.
+ */
+function decodePairingString(value) {
+  const raw = String(value == null ? '' : value).trim();
+  if (!raw.startsWith(PAIRING_STRING_PREFIX)) return null;
+  let parsed = null;
+  try {
+    parsed = JSON.parse(Buffer.from(raw.slice(PAIRING_STRING_PREFIX.length), 'base64url').toString('utf8'));
+  } catch {
+    return null; // expected: a corrupted container is a client error, not a server fault
+  }
+  if (!parsed || typeof parsed !== 'object' || parsed.v !== 1) return null;
+  const code = normalizeCode(parsed.c);
+  if (code.length !== CODE_LENGTH) return null;
+  const urls = (Array.isArray(parsed.u) ? parsed.u : [])
+    .map((url) => String(url || '').trim().replace(/\/+$/, ''))
+    .filter(Boolean);
+  const instanceId = String(parsed.i || '').trim();
+  if (!instanceId && !urls.length) return null;
+  return { version: 1, instanceId, displayName: String(parsed.n || ''), urls, code };
+}
+
+/**
+ * The box's pairing store.
+ *
+ * @param {{db: object, now?: () => number, randomBytes?: (n: number) => Buffer}} deps
+ *   `db` must expose the four DB-owner ops: listLivePairingOffers, insertPairingOffer,
+ *   markPairingOfferRedeemed, burnLivePairingOffers.
+ * @returns {{createOffer: () => Promise<object>, redeem: (code: string, options?: object) => Promise<object>,
+ *   hasLiveOffers: () => Promise<boolean>, burnAll: () => Promise<object>}}
+ */
+function createMachinePairing({ db, now = () => Date.now(), randomBytes = (n) => crypto.randomBytes(n) } = {}) {
+  if (!db || typeof db.listLivePairingOffers !== 'function') {
+    throw new TypeError('machine-pairing: db.listLivePairingOffers is required');
+  }
+  // §6.3: in memory on purpose — a restart clearing the counter is fine (the offers themselves are
+  // single-use and TTL-bounded), while persisting it would put an attacker-controlled number in the
+  // DB. Five CONSECUTIVE failures burn everything live; one success resets it.
+  let failedRedeems = 0;
+
+  function _now() {
+    return Math.trunc(Number(now()) || 0);
+  }
+
+  /**
+   * §6.3 `POST /api/machine-pairing/offers`. At most MAX_LIVE_OFFERS unspent offers exist at any
+   * moment, so a walked-away browser cannot leave an unbounded set of valid codes behind.
+   */
+  async function createOffer() {
+    const at = _now();
+    const live = await db.listLivePairingOffers({ at });
+    if (Array.isArray(live) && live.length >= MAX_LIVE_OFFERS) {
+      return { ok: false, code: 'pairing_offer_limit' };
+    }
+    const code = mintCode(randomBytes);
+    const expiresAt = at + OFFER_TTL_MS;
+    await db.insertPairingOffer({ id: crypto.randomUUID(), codeHash: hashCode(code), createdAt: at, expiresAt });
+    return { ok: true, code: formatCode(code), expiresAt };
+  }
+
+  /**
+   * §6.3 ordering: hash-compare against the live set, then burn the one that matched. `by` is the
+   * redeeming machine's instance id and is the only thing recorded — never the code.
+   *
+   * SINGLE USE IS THE UPDATE, NOT THE READ (F3). The candidate was found by reading the live set, but
+   * that read is not a claim: two joins holding the same code would both find the row and both return
+   * ok from a read-then-trust redeem. `markPairingOfferRedeemed` carries the `redeemed_at IS NULL`
+   * predicate in its WHERE clause and reports how many rows it changed, so exactly one of the two
+   * callers sees `changes === 1` and the loser is told `pairing_code_invalid` — the same answer an
+   * already-used code gets, which is what keeps the endpoint from being an oracle. A lost claim is NOT
+   * a failed guess (the caller was holding a real code), so it must not count toward the burn.
+   */
+  async function redeem(code, { by = '' } = {}) {
+    const at = _now();
+    const live = await db.listLivePairingOffers({ at });
+    const wanted = hashCode(code);
+    const offer = (Array.isArray(live) ? live : []).find((row) => codeHashEquals(row && row.codeHash, wanted));
+    if (!offer) {
+      failedRedeems += 1;
+      if (failedRedeems >= MAX_FAILED_REDEEMS) {
+        failedRedeems = 0;
+        // §6.3 AC-3c: the 5th consecutive miss burns EVERY live offer, so an attacker who is
+        // brute-forcing the 20^8 space loses the offers they were guessing against.
+        await db.burnLivePairingOffers({ at });
+      }
+      return { ok: false, code: 'pairing_code_invalid' };
+    }
+    const id = String(offer.id || '');
+    const changed = Number(await db.markPairingOfferRedeemed({
+      id,
+      at,
+      redeemedBy: String(by || '').slice(0, 200),
+    })) || 0;
+    if (changed !== 1) return { ok: false, code: 'pairing_code_invalid' };
+    // Only a claimed offer is a success, and only a success resets the consecutive-miss counter.
+    failedRedeems = 0;
+    return { ok: true, offer: { id, expiresAt: Number(offer.expiresAt) || 0 } };
+  }
+
+  /** §6.3/D-9: is this box showing a live code right now? (the identity probe's yes/no, never a code) */
+  async function hasLiveOffers() {
+    const live = await db.listLivePairingOffers({ at: _now() });
+    return Array.isArray(live) && live.length > 0;
+  }
+
+  /**
+   * F4: after a successful adopt this box belongs to somebody, so every OTHER live code must die —
+   * otherwise a second primary holding a code minted before the join could re-adopt the box and walk
+   * away with the pool secret. Also clears the failure counter: the box is no longer "unpaired".
+   */
+  async function burnAll() {
+    failedRedeems = 0;
+    return db.burnLivePairingOffers({ at: _now() });
+  }
+
+  return { createOffer, redeem, hasLiveOffers, burnAll };
+}
+
+module.exports = {
+  CODE_ALPHABET,
+  CODE_LENGTH,
+  OFFER_TTL_MS,
+  MAX_LIVE_OFFERS,
+  MAX_FAILED_REDEEMS,
+  PAIRING_STRING_PREFIX,
+  normalizeCode,
+  formatCode,
+  hashCode,
+  codeHashEquals,
+  mintCode,
+  encodePairingString,
+  decodePairingString,
+  createMachinePairing,
+};

package/template/coding-task-manager/lib/machine-pool.js

@@ -0,0 +1,409 @@
+'use strict';
+
+// WP-2a (docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §6.2, D-7/D-8, P-1..P-6): the
+// pool core. This is the ONLY module that reads or writes the pool secret.
+//
+// Rev 2 D-7: one shared pool secret per pool, shaped `ctmpool1_<poolId>.<secret>`, stored in
+// getDataDir()/machine-pool.json (mode 0600, atomic write). It is deliberately NOT stored in the
+// DB — every member also sends the token OUTBOUND, so it cannot be hash-at-rest, and DB backups
+// exist. The poolId half is public (it names the pool in logs and errors); the secret half is the
+// 32 random bytes that authenticate.
+//
+// LEAF module: it requires only node built-ins and ./data-dir. It must NOT require
+// hosted-sync-worker / machine-registry / remote-machine-create — lib/** dependency-cycle lint is
+// at ceiling 0, and lib/auth-context.js (which does the inbound verification) is on that cycle's
+// critical path. Everything is injectable so the unit test never touches the real data dir or the
+// real clock (clock-free rule).
+
+const path = require('node:path');
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const { getDataDir } = require('./data-dir');
+
+const TOKEN_PREFIX = 'ctmpool1_';
+// P-6: a rotation keeps the OLD secret accepted inbound for ten minutes, so a member that was
+// offline during the rotate call is not locked out before the next sweep can reach it.
+const ROTATION_GRACE_MS = 600_000;
+// D-7: poolId = 12 lowercase base32 chars (RFC 4648 lowercase alphabet, 32 symbols = 5 bits each).
+const POOL_ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+const POOL_ID_LENGTH = 12;
+const SECRET_BYTES = 32;
+
+function _poolFile() {
+  return path.join(getDataDir(), 'machine-pool.json');
+}
+
+/** Constant-time compare over equal-length buffers; a length mismatch (or an empty side) is false. */
+function _constantTimeEqual(a, b) {
+  const left = Buffer.from(String(a == null ? '' : a), 'utf8');
+  const right = Buffer.from(String(b == null ? '' : b), 'utf8');
+  if (!left.length || left.length !== right.length) return false;
+  return crypto.timingSafeEqual(left, right);
+}
+
+/** 12 lowercase base32 chars from `randomBytes` — the public pool id (D-7). */
+function _mintPoolId(randomBytes) {
+  const bytes = randomBytes(POOL_ID_LENGTH);
+  let out = '';
+  for (let i = 0; i < POOL_ID_LENGTH; i += 1) {
+    out += POOL_ID_ALPHABET[bytes[i] % POOL_ID_ALPHABET.length];
+  }
+  return out;
+}
+
+/** ctmpool1_<poolId>.<secret>; the secret is 32 random bytes, base64url (D-7). */
+function _mintToken(randomBytes) {
+  const poolId = _mintPoolId(randomBytes);
+  const secret = Buffer.from(randomBytes(SECRET_BYTES)).toString('base64url');
+  return `${TOKEN_PREFIX}${poolId}.${secret}`;
+}
+
+/** The public half of a token, or '' when the shape is not a pool token. */
+function poolIdOf(token) {
+  const raw = String(token == null ? '' : token);
+  if (!raw.startsWith(TOKEN_PREFIX)) return '';
+  const rest = raw.slice(TOKEN_PREFIX.length);
+  const dot = rest.indexOf('.');
+  if (dot <= 0) return '';
+  return rest.slice(0, dot);
+}
+
+/** Atomic write with mode 0600: temp file in the same dir, fsync, rename (the house pattern). */
+async function _defaultWriteAtomic(file, data) {
+  const dir = path.dirname(file);
+  await fs.promises.mkdir(dir, { recursive: true });
+  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  let handle = null;
+  try {
+    handle = await fs.promises.open(tmp, 'w', 0o600);
+    await handle.writeFile(String(data), 'utf8');
+    await handle.sync();
+  } finally {
+    if (handle) await handle.close();
+  }
+  await fs.promises.rename(tmp, file);
+}
+
+function _defaultReadFile(file) {
+  return fs.promises.readFile(file, 'utf8');
+}
+
+/**
+ * @param {{now?: () => number, readFile?: (p: string) => Promise<string>, writeFileAtomic?: (p: string, d: string) => Promise<void>, randomBytes?: (n: number) => Buffer}} [deps]
+ */
+function createMachinePool(deps = {}) {
+  const now = typeof deps.now === 'function' ? deps.now : () => Date.now();
+  const readFile = typeof deps.readFile === 'function' ? deps.readFile : _defaultReadFile;
+  const writeFileAtomic = typeof deps.writeFileAtomic === 'function' ? deps.writeFileAtomic : _defaultWriteAtomic;
+  const randomBytes = typeof deps.randomBytes === 'function' ? deps.randomBytes : (n) => crypto.randomBytes(n);
+
+  // { version, token, previous: {token, until} | null, roster: {revision, updatedAt, by},
+  //   members: string[] }
+  let state = null;
+
+  function _snapshot() {
+    return state
+      ? {
+        version: 1,
+        token: state.token,
+        previous: state.previous ? { token: state.previous.token, until: state.previous.until } : null,
+        roster: { ...state.roster },
+        members: [...state.members],
+      }
+      : null;
+  }
+
+  function _normalizeRoster(value) {
+    const roster = value && typeof value === 'object' ? value : {};
+    return {
+      revision: Number(roster.revision) || 0,
+      updatedAt: Number(roster.updatedAt) || 0,
+      by: String(roster.by || ''),
+    };
+  }
+
+  /**
+   * P-8: the persisted membership set — the instanceIds of the OTHER machines in this pool. It is
+   * what makes the outbound credential a PER-TARGET decision: an env-token box that never joined
+   * must be dialled with the env bearer, not the pool secret it has never seen. Empty/duplicate
+   * entries are dropped; a non-array reads as "no members".
+   */
+  function _normalizeMembers(value) {
+    if (!Array.isArray(value)) return [];
+    return [...new Set(value.map((id) => String(id == null ? '' : id).trim()).filter(Boolean))];
+  }
+
+  async function _persist() {
+    await writeFileAtomic(_poolFile(), JSON.stringify(_snapshot(), null, 2));
+  }
+
+  /** Boot read. ENOENT (or any unreadable file) means "this machine has no pool" — never throws. */
+  async function load() {
+    let raw = '';
+    try {
+      raw = await readFile(_poolFile());
+    } catch {
+      state = null; // expected: no pool file yet — a pool-less member is the normal first state
+      return;
+    }
+    try {
+      const parsed = JSON.parse(String(raw || ''));
+      const token = String((parsed && parsed.token) || '');
+      if (!token.startsWith(TOKEN_PREFIX)) {
+        state = null;
+        return;
+      }
+      const previous = parsed && parsed.previous && typeof parsed.previous === 'object'
+        ? { token: String(parsed.previous.token || ''), until: Number(parsed.previous.until) || 0 }
+        : null;
+      state = {
+        version: 1,
+        token,
+        previous: previous && previous.token ? previous : null,
+        roster: _normalizeRoster(parsed && parsed.roster),
+        members: _normalizeMembers(parsed && parsed.members),
+      };
+    } catch {
+      state = null; // expected: a garbled file is treated as "no pool", never a boot failure
+    }
+  }
+
+  function hasPool() {
+    return !!(state && state.token);
+  }
+
+  function poolId() {
+    return state ? poolIdOf(state.token) : '';
+  }
+
+  function token() {
+    return state ? state.token : '';
+  }
+
+  /**
+   * D-7 inbound check. Synchronous over in-memory state (no I/O on the auth path) and constant
+   * time on equal-length buffers. The previous secret is accepted only inside its grace window
+   * (P-6); an expired one is refused even though it is still on disk.
+   */
+  function verify(bearer) {
+    const raw = String(bearer == null ? '' : bearer);
+    if (!raw.startsWith(TOKEN_PREFIX) || !state || !state.token) return false;
+    if (_constantTimeEqual(raw, state.token)) return true;
+    if (state.previous && now() < state.previous.until && _constantTimeEqual(raw, state.previous.token)) return true;
+    return false;
+  }
+
+  /**
+   * P-6: the CURRENT secret only, never the grace one. A machine removed from the pool still holds
+   * the previous secret for ROTATION_GRACE_MS, so a pool MUTATION (roster push, rotate) accepted on
+   * the grace secret would let it rotate a remaining member to a token of its own choosing. The
+   * legitimate remover dials with the secret that is still the receiver's current one, so it passes.
+   */
+  function isCurrent(bearer) {
+    const raw = String(bearer == null ? '' : bearer);
+    if (!raw.startsWith(TOKEN_PREFIX) || !state || !state.token) return false;
+    return _constantTimeEqual(raw, state.token);
+  }
+
+  /** D-7: the first pairing on a pool-less member mints the pool (id + secret) at that moment. */
+  async function ensurePool() {
+    if (hasPool()) return state.token;
+    state = {
+      version: 1,
+      token: _mintToken(randomBytes),
+      previous: null,
+      roster: _normalizeRoster(state && state.roster),
+      members: _normalizeMembers(state && state.members),
+    };
+    await _persist();
+    return state.token;
+  }
+
+  /**
+   * D-9 join: the box stores the token the redeeming member handed it, plus the roster version and
+   * (P-8) the membership set — without it this box would send the pool secret to every target,
+   * including the legacy env-token boxes that never joined and would 401 it.
+   */
+  async function adopt({ token: adoptedToken, roster, members } = {}) {
+    const next = String(adoptedToken || '');
+    if (!next.startsWith(TOKEN_PREFIX)) throw new TypeError('machine-pool: adopt requires a ctmpool1_ token');
+    state = {
+      version: 1,
+      token: next,
+      previous: null,
+      roster: _normalizeRoster(roster),
+      members: _normalizeMembers(members),
+    };
+    await _persist();
+  }
+
+  /** P-6: mint a new secret and keep the old one accepted inbound for the grace window. */
+  async function rotate() {
+    const old = state && state.token;
+    const next = _mintToken(randomBytes);
+    state = {
+      version: 1,
+      token: next,
+      previous: old ? { token: old, until: now() + ROTATION_GRACE_MS } : null,
+      roster: _normalizeRoster(state && state.roster),
+      members: _normalizeMembers(state && state.members),
+    };
+    await _persist();
+    return next;
+  }
+
+  /** P-6 receiver side: the sender's new token becomes current; the old one gets the grace. */
+  async function acceptRotation({ token: rotated } = {}) {
+    const next = String(rotated || '');
+    if (!next.startsWith(TOKEN_PREFIX)) throw new TypeError('machine-pool: acceptRotation requires a ctmpool1_ token');
+    const old = state && state.token;
+    if (old === next) return;
+    state = {
+      version: 1,
+      token: next,
+      previous: old ? { token: old, until: now() + ROTATION_GRACE_MS } : null,
+      roster: _normalizeRoster(state && state.roster),
+      members: _normalizeMembers(state && state.members),
+    };
+    await _persist();
+  }
+
+  function members() {
+    return state ? [...state.members] : [];
+  }
+
+  /** P-8: is `id` a machine of this pool (and therefore dialled with the pool secret)? */
+  function isMember(id) {
+    const wanted = String(id == null ? '' : id).trim();
+    if (!wanted || !state) return false;
+    return state.members.includes(wanted);
+  }
+
+  /** P-5 receive side: the pushed membership IS this member's set (self already excluded). */
+  async function setMembers(ids) {
+    state = {
+      version: 1,
+      token: state ? state.token : '',
+      previous: state ? state.previous : null,
+      roster: _normalizeRoster(state && state.roster),
+      members: _normalizeMembers(ids),
+    };
+    if (state.token) await _persist();
+    return members();
+  }
+
+  async function addMember(id) {
+    const wanted = String(id == null ? '' : id).trim();
+    if (!wanted) return members();
+    return setMembers([...members(), wanted]);
+  }
+
+  async function removeMember(id) {
+    const unwanted = String(id == null ? '' : id).trim();
+    if (!unwanted) return members();
+    return setMembers(members().filter((member) => member !== unwanted));
+  }
+
+  function rosterVersion() {
+    return _normalizeRoster(state && state.roster);
+  }
+
+  /**
+   * P-5 receive side (beyond §6.2's literal list, which has no store-the-pushed-version call): the
+   * receiver stores the version it just applied verbatim, so its next GET/pull answers with the set
+   * the sender pushed instead of re-bumping and re-propagating. Returns the stored version.
+   */
+  async function setRosterVersion(version) {
+    state = {
+      version: 1,
+      token: state ? state.token : '',
+      previous: state ? state.previous : null,
+      roster: _normalizeRoster(version),
+      members: _normalizeMembers(state && state.members),
+    };
+    if (state.token) await _persist();
+    return rosterVersion();
+  }
+
+  /** P-5: revision+1, updatedAt = now(), by = self. A pool-less member starts at revision 1. */
+  async function bumpRoster(selfId) {
+    const current = _normalizeRoster(state && state.roster);
+    state = {
+      version: 1,
+      token: state ? state.token : '',
+      previous: state ? state.previous : null,
+      roster: { revision: current.revision + 1, updatedAt: now(), by: String(selfId || '') },
+      members: _normalizeMembers(state && state.members),
+    };
+    if (state.token) await _persist();
+    return rosterVersion();
+  }
+
+  /**
+   * P-5 ordering: revision first, then updatedAt, then `by` as a string compare. `isNewer(a, b)`
+   * answers "does a outrank b" — an equal triple is not newer.
+   */
+  function isNewer(a, b) {
+    const left = _normalizeRoster(a);
+    const right = _normalizeRoster(b);
+    if (left.revision !== right.revision) return left.revision > right.revision;
+    if (left.updatedAt !== right.updatedAt) return left.updatedAt > right.updatedAt;
+    return left.by > right.by;
+  }
+
+  /**
+   * D-7: leave deletes the file — the token AND (P-8) the membership set go with it, so a
+   * re-joined box never dials a stale pool with a secret it no longer holds. The caller deletes the
+   * roster rows (deleteAllMachineRows).
+   */
+  async function leave() {
+    state = null;
+    try {
+      await fs.promises.unlink(_poolFile());
+    } catch (error) {
+      // expected: no file to delete (a pool-less member leaving) is not a failure
+      if (error && error.code !== 'ENOENT') throw error;
+    }
+  }
+
+  return {
+    load,
+    hasPool,
+    poolId,
+    token,
+    verify,
+    isCurrent,
+    ensurePool,
+    adopt,
+    rotate,
+    acceptRotation,
+    rosterVersion,
+    setRosterVersion,
+    bumpRoster,
+    isNewer,
+    members,
+    isMember,
+    setMembers,
+    addMember,
+    removeMember,
+    leave,
+  };
+}
+
+// The process singleton lib/auth-context.js verifies against. auth-context's branch is
+// SYNCHRONOUS (no I/O on the auth path), so it reads this instance's in-memory state; server.js
+// awaits load() once at boot (before routes are served) to populate it.
+let _singleton = null;
+
+function getMachinePool() {
+  if (!_singleton) _singleton = createMachinePool();
+  return _singleton;
+}
+
+module.exports = {
+  TOKEN_PREFIX,
+  ROTATION_GRACE_MS,
+  createMachinePool,
+  getMachinePool,
+  poolIdOf,
+};