create-walle 0.10.1 → 0.10.3

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

@@ -0,0 +1,285 @@
+'use strict';
+
+// WP-3 (docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §6.3, D-6/D-9/D-13, §9 S-15/S-16/S-23):
+// the BOX side of pairing — the two routes a joining member talks to.
+//
+//   POST /api/machine-pairing/offers  (admin + stepUp remote)
+//        -> 201 { ok, code:'XXXX-XXXX', expiresAt, pairingString, candidates }
+//        -> 409 { error:'pairing_offer_limit' }    3 unspent offers already exist
+//        -> 409 { error:'pool_member_exists' }     this box is already IN a pool with members
+//
+//   POST /api/machine-pairing/join    (PRE-AUTH — phase 'api-cloudflare')
+//        { code, token, version, members, primary:{instanceId} }
+//        -> 201 { ok, instanceId, displayName, urls }
+//        -> 400 { error:'pool_token_invalid' } / 400 { error:'invalid_json' }
+//        -> 409 { error:'pool_member_exists' }     this box is already somebody's member
+//        -> 410 { error:'pairing_code_invalid' }   wrong / expired / already-used / burned
+//        -> 429 { error:'rate_limited' }
+//
+//   GET  /api/machine-pairing/identity (PRE-AUTH — phase 'api-cloudflare')
+//        -> 200 { ok, instanceId, displayName }    a live code is showing on this box
+//        -> 404 { error:'pairing_offer_none' }     no live code — not a pairing target right now
+//        -> 429 { error:'rate_limited' }
+//
+// WHY THE JOIN IS PRE-AUTH. The joining member does not hold this box's credential YET — the join
+// request is the act that establishes it, and it carries the pool secret in the body precisely
+// because there is nothing else to authenticate with. server.js dispatches phase 'api-cloudflare'
+// BEFORE the /api auth wall (the same seam lib/api/microsoft-owner.js's public rows use), so this
+// route never reaches lib/auth-rules.js and deliberately has NO row in HTTP_AUTH_RULES: a rule the
+// dispatcher never consults is a lie in the table. Its defence is instead (a) possession of a live
+// single-use code and (b) the `machine_pair` rate-limit bucket below (5/min, burst 5), keyed by
+// REMOTE ADDRESS because there is no principal to key on.
+//
+// WHY THE IDENTITY PROBE IS PRE-AUTH TOO (D-9). Before it has paired, a member holds NO credential of
+// this box, so it cannot read `/api/sync/manifest` (`sync`-scoped in lib/auth-rules.js) to find out
+// whether it dialled the right machine — on a real LAN that 401s and the pair dies before it starts.
+// The probe answers the smallest fact that makes a wrong address visible: "this box is showing a code
+// right now", plus the name to compare against, and never a code, a token or a membership.
+//
+// WHAT IT NEVER DOES. Neither handler echoes, logs or persists a code or the token: the offer
+// response is the ONE place a code exists in wire form (it is the box's own act of showing it to the
+// operator), and the join response carries only this instance's identity and its own URLs.
+
+const os = require('node:os');
+const { registerApiRoutes } = require('../api-router');
+const { TOKEN_PREFIX } = require('../machine-pool');
+const { encodePairingString } = require('../machine-pairing');
+
+let _deps = null;
+
+function configure({
+  db,
+  pool,
+  pairing,
+  machineSelf,
+  registry,
+  selfUrls,
+  readJsonRequestBody,
+  sendJsonResponse,
+  rateLimit,
+  remoteIp,
+  logError = null,
+  ready = null,
+} = {}) {
+  _deps = {
+    db, pool, pairing, machineSelf, registry, selfUrls,
+    readJsonRequestBody, sendJsonResponse, rateLimit, remoteIp, logError, ready,
+  };
+}
+
+/** server.js injects its own (console) logger; the fallback keeps a bare harness truthful. */
+function _logError(...args) {
+  if (_deps && typeof _deps.logError === 'function') return _deps.logError(...args);
+  console.error(...args);
+}
+
+/** The boot read's promise (server.js `_machinePoolReady`); both handlers here MUTATE the pool. */
+function ready() {
+  return (_deps && _deps.ready) || Promise.resolve();
+}
+
+function _send(res, status, payload) {
+  if (_deps && typeof _deps.sendJsonResponse === 'function') return _deps.sendJsonResponse(res, status, payload);
+  const body = JSON.stringify(payload || {});
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+function _pool() {
+  return (_deps && _deps.pool) || require('../machine-pool').getMachinePool();
+}
+
+function _readJson(req) {
+  if (_deps && typeof _deps.readJsonRequestBody === 'function') return _deps.readJsonRequestBody(req);
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8');
+      if (!raw) return resolve({});
+      try { resolve(JSON.parse(raw)); } catch { reject(new Error('invalid_json')); }
+    });
+    req.on('error', reject);
+  });
+}
+
+/** This machine's own minted id — '' rather than a throw before boot has primed identity. */
+function _instanceId() {
+  try {
+    const identity = require('../instance-identity-access').getInstanceIdentity({ required: false });
+    return (identity && identity.instanceId) || '';
+  } catch {
+    return ''; // expected: instance identity is not ready yet (early boot / pre-initDb)
+  }
+}
+
+/**
+ * D-4: the operator's label for this box, read from the machine-self store (the same source the
+ * manifest publishes), falling back to the host name. A pairing string with a label is what makes the
+ * operator's "which machine am I looking at" check possible on the far side.
+ */
+function _displayName() {
+  try {
+    const store = _deps && _deps.machineSelf;
+    const current = store && typeof store.current === 'function' ? store.current() : null;
+    const name = String((current && current.displayName) || '').trim();
+    if (name) return name;
+  } catch {
+    // expected: the machine-self cache is not configured (unit harness) — fall through to the host name
+  }
+  try {
+    return String(os.hostname() || '').trim();
+  } catch {
+    return ''; // expected: no host name available — an empty label is truthful, never a failure
+  }
+}
+
+/** P-4: the dial list the pairing string advertises (injected — lib/api/machine-pool.js owns it). */
+function _selfUrls() {
+  try {
+    const urls = _deps && typeof _deps.selfUrls === 'function' ? _deps.selfUrls() : [];
+    return Array.isArray(urls) ? urls.map((url) => String(url || '')).filter(Boolean) : [];
+  } catch {
+    return []; // expected: the URL getter is optional/unready — the operator can still type a URL
+  }
+}
+
+/**
+ * The pre-auth defence both 'api-cloudflare' routes share (D-13): with no principal there is nothing
+ * to key a bucket on but the remote address, and the limiter is server.js's own singleton — the same
+ * instance every authorised route is charged to.
+ */
+function _allowed(req) {
+  const ip = _deps && typeof _deps.remoteIp === 'function' ? String(_deps.remoteIp(req) || '') : '';
+  const decision = _deps && typeof _deps.rateLimit === 'function'
+    ? _deps.rateLimit('machine_pair', ip || 'anonymous')
+    : { ok: true };
+  return !!(decision && decision.ok);
+}
+
+async function handleOffers(req, res) {
+  const pool = _pool();
+  await ready();
+  // §6.3 AC-3f: a box that already has a pool AND members is not "unpaired" — minting a code here
+  // would let a second, unrelated primary adopt a machine that is already somebody's member.
+  if (pool.hasPool() && pool.members().length > 0) {
+    return _send(res, 409, { ok: false, error: 'pool_member_exists' });
+  }
+  let result = null;
+  try {
+    result = await _deps.pairing.createOffer();
+  } catch (error) {
+    // F5: REPORT the fault to the log; never echo it to the caller. The failure path still holds the
+    // offer's code (the store mints before it inserts), so a `detail` here would be the one place a
+    // live code could be copied out of a response body.
+    _logError('[machine-pairing] offer mint failed:', (error && error.message) || error);
+    return _send(res, 500, { ok: false, error: 'pairing_offer_failed' });
+  }
+  if (!result || !result.ok) {
+    // §6.3: 409 pairing_offer_limit (3 unspent offers already exist).
+    return _send(res, 409, { ok: false, error: (result && result.code) || 'pairing_offer_limit' });
+  }
+  const candidates = _selfUrls();
+  const instanceId = _instanceId();
+  return _send(res, 201, {
+    ok: true,
+    code: result.code,
+    expiresAt: result.expiresAt,
+    pairingString: encodePairingString({ instanceId, displayName: _displayName(), urls: candidates, code: result.code }),
+    candidates,
+  });
+}
+
+/**
+ * D-9/F1: the PRE-AUTH identity probe (see the file header). A BOOLEAN, never a code: 200 while this
+ * box is showing at least one live offer, 404 the moment it is not. That is what lets a member aimed
+ * at the wrong address see "there is no pairing code here" instead of a 401 it cannot interpret.
+ */
+async function handleIdentity(req, res) {
+  if (!_allowed(req)) return _send(res, 429, { ok: false, error: 'rate_limited' });
+  await ready();
+  let live = false;
+  try {
+    live = !!(await _deps.pairing.hasLiveOffers());
+  } catch (error) {
+    _logError('[machine-pairing] identity probe failed:', (error && error.message) || error);
+    return _send(res, 500, { ok: false, error: 'pairing_identity_failed' });
+  }
+  if (!live) return _send(res, 404, { ok: false, error: 'pairing_offer_none' });
+  return _send(res, 200, { ok: true, instanceId: _instanceId(), displayName: _displayName() });
+}
+
+async function handleJoin(req, res) {
+  // PRE-AUTH: there is no principal, so the bucket is keyed by remote address (see _allowed).
+  if (!_allowed(req)) return _send(res, 429, { ok: false, error: 'rate_limited' });
+
+  let body = null;
+  try {
+    body = await _readJson(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  const token = String((body && body.token) || '').trim();
+  if (!token.startsWith(TOKEN_PREFIX)) return _send(res, 400, { ok: false, error: 'pool_token_invalid' });
+
+  await ready();
+  const pool = _pool();
+  // F4: a box that already belongs to somebody must not be adoptable by a second, unrelated primary
+  // that happens to hold a code minted earlier (or to have brute-forced one). Same predicate as
+  // handleOffers, on the join side — and checked BEFORE the redeem so the attempt cannot spend a code.
+  if (pool.hasPool() && pool.members().length > 0) {
+    return _send(res, 409, { ok: false, error: 'pool_member_exists' });
+  }
+  const identity = _instanceId();
+  // §6.3 ordering: verify the code (hash compare) and burn it BEFORE the pool is touched, so a
+  // replay of an already-consumed code can never reach adopt().
+  const redeemed = await _deps.pairing.redeem(body && body.code, { by: identity });
+  if (!redeemed || !redeemed.ok) return _send(res, 410, { ok: false, error: 'pairing_code_invalid' });
+
+  // P-8: the PREVIOUS membership set, captured before adopt() — replaceRosterMachines may only
+  // delete rows for machines that WERE pool members. A legacy env-token row is never one, so this
+  // join can never drop it (the WP-2b fix; do not reintroduce the unguarded sweep).
+  const removable = pool.members();
+  // Two shapes, two consumers, and they are NOT interchangeable:
+  //   - the POOL store holds instanceIds (P-8's per-target credential rule),
+  //   - the REGISTRY takes the roster ENTRIES (db.replaceRosterMachines writes `url`/`urls_json` from
+  //     each entry's dial list and SKIPS an entry with no URL). Handing it bare ids writes no row at
+  //     all, which is how the membership silently failed to land: the box would answer 201 and then
+  //     list nobody.
+  const entries = (Array.isArray(body && body.members) ? body.members : [])
+    .map((member) => ({
+      instanceId: String((member && (member.instanceId || member.instance_id)) || '').trim(),
+      urls: (Array.isArray(member && member.urls) ? member.urls : [])
+        .map((url) => String(url || '').trim().replace(/\/+$/, ''))
+        .filter(Boolean),
+    }))
+    .filter((member) => member.instanceId && member.instanceId !== identity);
+  const members = entries.map((member) => member.instanceId);
+  await pool.adopt({ token, roster: body && body.version, members });
+  await _deps.db.replaceRosterMachines({ members: entries, selfInstanceId: identity, removable });
+  if (_deps.registry && typeof _deps.registry.noteRegistryChanged === 'function') _deps.registry.noteRegistryChanged();
+  // F4: this box is somebody's member now, so every code that is still live dies here. Without it, a
+  // second primary holding an offer minted before this join could adopt the same box with the same
+  // code-less flow and take the pool secret with it. Best-effort after the fact: the adopt already
+  // succeeded and is what the caller was promised, so a burn failure is reported, never fatal.
+  try {
+    await _deps.pairing.burnAll();
+  } catch (error) {
+    _logError('[machine-pairing] burning the remaining offers after a join failed:', (error && error.message) || error);
+  }
+  // The token is deliberately NOT echoed — the caller already has it, and a response body is the
+  // easiest place for a secret to end up in a log or a proxy trace.
+  return _send(res, 201, { ok: true, instanceId: identity, displayName: _displayName(), urls: _selfUrls() });
+}
+
+function register() {
+  registerApiRoutes('machine-pairing', [
+    { method: 'POST', path: '/api/machine-pairing/offers', handler: (req, res) => handleOffers(req, res) },
+    // PRE-AUTH (§6.3): dispatched before server.js's auth wall, so it carries no auth-rules row.
+    { phase: 'api-cloudflare', method: 'POST', path: '/api/machine-pairing/join', handler: (req, res) => handleJoin(req, res) },
+    // PRE-AUTH (D-9/F1): same phase, same reason — an unpaired member holds no credential here.
+    { phase: 'api-cloudflare', method: 'GET', path: '/api/machine-pairing/identity', handler: (req, res) => handleIdentity(req, res) },
+  ]);
+}
+
+module.exports = { configure, register, ready, handleOffers, handleJoin, handleIdentity };

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

@@ -0,0 +1,307 @@
+'use strict';
+
+// WP-2a (docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §6.2, D-4/D-13, P-5/P-6, §9
+// S-24/S-25/S-27): the pool + machine-self routes.
+//
+//   GET  /api/pool/roster   (peerControl)   -> { ok, poolId, version, members:[{instanceId, urls}] }
+//                                              `members` INCLUDES self (P-1: the roster a member
+//                                              pushes carries itself).
+//   POST /api/pool/roster   (peerControl)   P-5 receive side: a lower-revision push replaces this
+//                                              member's membership (upsert listed, delete unlisted,
+//                                              never self) and stores the version; an equal/higher
+//                                              revision is ignored and answered `{applied:false}`.
+//   POST /api/pool/rotate   (peerControl)   P-6 receive side: acceptRotation({token}).
+//   POST /api/pool/leave    (admin+stepUp)  leave() + drop every roster row.
+//   GET  /api/machine-self  (read, peerControl)   D-4: this machine's own settings.
+//   POST /api/machine-self  (admin+stepUp, peerControl) D-4 write.
+//
+// Like lib/api/machines.js (and unlike the lib/api/*.js extraction slices) this is NEW surface: the
+// handler bodies live here, so there is no legacy handleApi branch to delete and
+// tests-integration/api-router-parity.test.js's no-dual-dispatch rule is satisfied by construction.
+//
+// AUTH. lib/auth-rules.js carries the rows (D-13). The codebase expresses no "peer-only" rule
+// mechanism — `peerControl: true` ADDS the peer bearer to a row's normal reach, it does not remove
+// anyone — so the two roster rows and POST /api/pool/rotate are declared `admin` + `peerControl`
+// and each handler REFUSES a non-peer principal itself with 403 `peer_only` (read off
+// `req.ctmAuth`, the same place lib/api/access.js reads the principal). That is the "handler
+// refuses" branch the brief names.
+
+const os = require('node:os');
+const { registerApiRoutes } = require('../api-router');
+const { PEER_CONTROL_SCOPE } = require('../auth-rules');
+const remoteMachineProxy = require('../remote-machine-proxy');
+
+let _deps = null;
+
+function configure({
+  db,
+  pool,
+  machineSelf,
+  registry,
+  readJsonRequestBody,
+  sendJsonResponse,
+  listenPort = 0,
+  publicOrigin = () => '',
+  ready = null,
+} = {}) {
+  _deps = { db, pool, machineSelf, registry, readJsonRequestBody, sendJsonResponse, listenPort, publicOrigin, ready };
+}
+
+/**
+ * The boot read's promise (`_machinePoolReady` in server.js). server.js fires the pool load
+ * fire-and-forget, so a handler that MUTATES the pool awaits this first instead of racing a load
+ * still in flight; read-only handlers never need to. WP-3's pair/remove handlers await the same
+ * promise through their own configure() call.
+ */
+function ready() {
+  return (_deps && _deps.ready) || Promise.resolve();
+}
+
+function _send(res, status, payload) {
+  if (_deps && typeof _deps.sendJsonResponse === 'function') return _deps.sendJsonResponse(res, status, payload);
+  const body = JSON.stringify(payload || {});
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+function _pool() {
+  return (_deps && _deps.pool) || require('../machine-pool').getMachinePool();
+}
+
+/** D-13: the peer-only gate. Returns true (and answers 403) for a non-peer principal. */
+function _refuseNonPeer(req, res) {
+  const scopes = req && req.ctmAuth && req.ctmAuth.scopes;
+  const isPeer = !!scopes && (scopes instanceof Set ? scopes.has(PEER_CONTROL_SCOPE) : Array.isArray(scopes) && scopes.includes(PEER_CONTROL_SCOPE));
+  if (isPeer) return false;
+  _send(res, 403, { ok: false, error: 'peer_only' });
+  return true;
+}
+
+/**
+ * P-6: a pool MUTATION (roster push, rotate) must present this machine's CURRENT pool secret. The
+ * auth wall accepts the grace (previous) secret for ordinary calls, but a machine just removed from
+ * the pool still holds it — so on these two routes it is refused, as is an env peer token (a legacy
+ * env box is never a pool member and has no business rewriting the pool). Answers 403
+ * `pool_secret_stale`.
+ */
+function _refuseStaleSecret(req, res) {
+  const header = String((req && req.headers && req.headers.authorization) || '');
+  const match = /^Bearer\s+(\S+)$/i.exec(header.trim());
+  if (match && _pool().isCurrent(match[1])) return false;
+  _send(res, 403, { ok: false, error: 'pool_secret_stale' });
+  return true;
+}
+
+/** This machine's own minted id — '' rather than a throw before boot has primed identity. */
+function _instanceId() {
+  try {
+    const identity = require('../instance-identity-access').getInstanceIdentity({ required: false });
+    return (identity && identity.instanceId) || '';
+  } catch {
+    return ''; // expected: identity is not ready yet (early boot / pre-initDb)
+  }
+}
+
+/**
+ * An IPv4 a peer can dial: not the subnet's network address (host bits all zero) and not its
+ * broadcast address (host bits all one). macOS VM/container bridges (bridge101..105 on the lead's
+ * Mac, 2026-10-25) carry the bare network address, e.g. 192.168.215.0/24 — advertising it costs the
+ * redeeming member one dead identity probe per pairing. /31 and /32 have no such addresses.
+ */
+function isDialableIPv4(address, netmask) {
+  const toInt = (dotted) => String(dotted || '').split('.').reduce((acc, part) => ((acc << 8) | (Number(part) & 255)) >>> 0, 0);
+  const parts = String(address || '').split('.');
+  if (parts.length !== 4) return false;
+  const mask = toInt(netmask || '255.255.255.255');
+  const hostBits = (~mask) >>> 0;
+  if (hostBits <= 1) return true;
+  const host = (toInt(address) & hostBits) >>> 0;
+  return host !== 0 && host !== hostBits;
+}
+
+/**
+ * P-4 self URLs: every dialable non-internal IPv4 of this host as `http://<ip>:<listen port>`, then
+ * executionHost.publicOrigin (`http://` added when the origin is bare host[:port]). De-duplicated,
+ * order preserved, empties dropped.
+ */
+function selfUrls() {
+  const port = Number(_deps && _deps.listenPort) || 0;
+  const out = [];
+  const ifaces = os.networkInterfaces();
+  for (const entries of Object.values(ifaces)) {
+    for (const entry of Array.isArray(entries) ? entries : []) {
+      if (!entry || entry.internal) continue;
+      if (String(entry.family) !== 'IPv4' && String(entry.family) !== '4') continue;
+      if (!entry.address || !isDialableIPv4(entry.address, entry.netmask)) continue;
+      out.push(`http://${entry.address}:${port}`);
+    }
+  }
+  let origin = '';
+  try {
+    origin = String((typeof _deps?.publicOrigin === 'function' ? _deps.publicOrigin() : _deps?.publicOrigin) || '').trim();
+  } catch {
+    origin = ''; // expected: the manifest origin getter is optional/unready — self URLs stay LAN-only
+  }
+  if (origin) out.push(/^https?:\/\//i.test(origin) ? origin : `http://${origin}`);
+  return [...new Set(out.filter(Boolean))];
+}
+
+/**
+ * P-1: the roster lists every OTHER pool member plus self (last), each as {instanceId, urls}. Only
+ * POOL MEMBERS: a legacy env-token row (P-8) is a registry row but never a member, and a receiver
+ * that adopted it into its member set would dial it with the pool bearer and be refused. Exported so
+ * lib/api/machines.js's pair/remove pushes speak exactly this shape.
+ */
+function rosterMembers() {
+  const db = _deps && _deps.db;
+  const pool = _pool();
+  const rows = db && typeof db.listMachineRows === 'function' ? (db.listMachineRows() || []) : [];
+  const members = rows.filter((row) => pool.isMember(String(row.instanceId || ''))).map((row) => ({
+    instanceId: String(row.instanceId || ''),
+    urls: Array.isArray(row.urls) && row.urls.length ? row.urls : [String(row.url || '')].filter(Boolean),
+  })).filter((row) => row.instanceId);
+  const self = _instanceId();
+  if (self && !members.some((row) => row.instanceId === self)) members.push({ instanceId: self, urls: selfUrls() });
+  return members;
+}
+
+function _readJson(req) {
+  if (_deps && typeof _deps.readJsonRequestBody === 'function') return _deps.readJsonRequestBody(req);
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8');
+      if (!raw) return resolve({});
+      try { resolve(JSON.parse(raw)); } catch { reject(new Error('invalid_json')); }
+    });
+    req.on('error', reject);
+  });
+}
+
+async function handleRosterGet(req, res) {
+  if (_refuseNonPeer(req, res)) return;
+  const pool = _pool();
+  return _send(res, 200, {
+    ok: true,
+    poolId: pool.poolId(),
+    version: pool.rosterVersion(),
+    members: rosterMembers(),
+  });
+}
+
+async function handleRosterPost(req, res) {
+  if (_refuseNonPeer(req, res)) return;
+  if (_refuseStaleSecret(req, res)) return;
+  let body = null;
+  try {
+    body = await _readJson(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  const pool = _pool();
+  const version = (body && body.version) || {};
+  const current = pool.rosterVersion();
+  if (!pool.isNewer(version, current)) {
+    return _send(res, 200, { ok: true, applied: false, version: current });
+  }
+  const self = _instanceId();
+  const pushed = Array.isArray(body && body.members) ? body.members : [];
+  // Only PREVIOUS pool members may be deleted (a legacy env-token row is never one, P-8).
+  const removable = typeof pool.members === 'function' ? pool.members() : [];
+  const result = await _deps.db.replaceRosterMachines({ members: pushed, selfInstanceId: self, removable });
+  await pool.setRosterVersion(version);
+  // P-8: the pushed roster IS this member's membership set, less itself — that is what makes the
+  // outbound bearer per target (a legacy env-token box is never in it and keeps getting the env one).
+  await pool.setMembers(pushed
+    .map((member) => String((member && member.instanceId) || ''))
+    .filter((id) => id && id !== self));
+  if (_deps.registry && typeof _deps.registry.noteRegistryChanged === 'function') _deps.registry.noteRegistryChanged();
+  return _send(res, 200, { ok: true, applied: true, version: pool.rosterVersion(), ...result });
+}
+
+async function handleRotate(req, res) {
+  if (_refuseNonPeer(req, res)) return;
+  if (_refuseStaleSecret(req, res)) return;
+  let body = null;
+  try {
+    body = await _readJson(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  try {
+    await _pool().acceptRotation({ token: body && body.token });
+  } catch {
+    return _send(res, 400, { ok: false, error: 'token_required' });
+  }
+  return _send(res, 200, { ok: true });
+}
+
+async function handleLeave(req, res) {
+  const pool = _pool();
+  // leave() drops the token AND (P-8) the membership set — a re-joined box must not keep dialling a
+  // stale pool with a secret it no longer holds.
+  await pool.leave();
+  const removed = await _deps.db.deleteAllMachineRows();
+  if (_deps.registry && typeof _deps.registry.noteRegistryChanged === 'function') _deps.registry.noteRegistryChanged();
+  return _send(res, 200, { ok: true, removed: Number(removed) || 0 });
+}
+
+async function handleMachineSelfGet(req, res) {
+  return _send(res, 200, { ok: true, self: _deps.machineSelf.current() });
+}
+
+async function handleMachineSelfPost(req, res) {
+  let body = null;
+  try {
+    body = await _readJson(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  const patch = {};
+  if (body && body.displayName !== undefined) {
+    const displayName = String(body.displayName || '').trim();
+    if (displayName.length > 80) return _send(res, 400, { ok: false, error: 'display_name_too_long' });
+    patch.displayName = displayName;
+  }
+  if (body && body.favorite !== undefined) patch.favorite = body.favorite ? 1 : 0;
+  if (body && body.hidden !== undefined) patch.hidden = body.hidden ? 1 : 0;
+  const self = await _deps.machineSelf.setSelf(patch, Date.now());
+  return _send(res, 200, { ok: true, self });
+}
+
+// D-4: a machine-self request that names ANOTHER machine (?machine= or X-CTM-Machine) is answered by
+// that member over the peer bearer — the same wrapper shape lib/api/misc-ops.js:41 uses, applied per
+// verb. A non-machine-routed request is the unchanged local handler.
+function _machineRouted(route, local) {
+  return (req, res, url) => (remoteMachineProxy.isMachineRouted(req, url)
+    ? remoteMachineProxy.maybeProxyMachineRequest(req, res, url, { route })
+      .then((handled) => (handled ? undefined : local(req, res, url)))
+    : local(req, res, url));
+}
+
+function register() {
+  registerApiRoutes('machine-pool', [
+    { method: 'GET', path: '/api/pool/roster', handler: (req, res) => handleRosterGet(req, res) },
+    { method: 'POST', path: '/api/pool/roster', handler: (req, res) => handleRosterPost(req, res) },
+    { method: 'POST', path: '/api/pool/rotate', handler: (req, res) => handleRotate(req, res) },
+    { method: 'POST', path: '/api/pool/leave', handler: (req, res) => handleLeave(req, res) },
+    { method: 'GET', path: '/api/machine-self', handler: _machineRouted('GET /api/machine-self', (req, res) => handleMachineSelfGet(req, res)) },
+    { method: 'POST', path: '/api/machine-self', handler: _machineRouted('POST /api/machine-self', (req, res) => handleMachineSelfPost(req, res)) },
+  ]);
+}
+
+module.exports = {
+  configure,
+  register,
+  ready,
+  handleRosterGet,
+  handleRosterPost,
+  handleRotate,
+  handleLeave,
+  handleMachineSelfGet,
+  handleMachineSelfPost,
+  selfUrls,
+  isDialableIPv4,
+  rosterMembers,
+};