centralu 0.1.0-beta.45 → 0.1.0-beta.47

package/bin/serve-handover.mjs

@@ -3,9 +3,9 @@
  * Windows sign-in (#1224). One module so the foreground `serve` (serve-run.mjs) and `--stop` (serve-detach.mjs) share
  * the stop without importing each other.
  */
-import { readServeState, heldHere, lockHolderPid, readServePid, pairServe, revokeServe } from './serve-files.mjs'
-import { DEFAULT_SERVE_PORT } from './serve-port.mjs'
-import { protocolVersionOf, hostProvesOf, probeHost, askHostToStop, askHostRpc, ownCredentials, takesVerifiers } from './serve-host.mjs'
+import { readServeState, heldHere, startedByServe, foreignHolder, holderWho, lockHolderIsAlive, lockHolderPid, readServePid } from './serve-files.mjs'
+import { DEFAULT_SERVE_PORT, listensHere } from './serve-port.mjs'
+import { protocolVersionOf, probeHost, askHostToStop, askHostRpc } from './serve-host.mjs'
 import { ownLogon } from './serve-windows.mjs'
 import { isAlive, say, sleep, waitUntil } from './serve-util.mjs'
 
@@ -20,7 +20,11 @@ import { isAlive, say, sleep, waitUntil } from './serve-util.mjs'
  * one still there afterwards is ended.
  *
  * Only the processes serve.pid and host.lock name, and only while they agree with each other and the host answered
- * with this folder's token: a stale pid is never signalled.
+ * with this folder's token, or nothing listens on the port while the process host.lock names is the one that wrote it
+ * (`heldSilently`, #1903: a host that took the lock and hung before it listened; never under `ifIdle`): a stale pid is
+ * never signalled.
+ * And only a host `serve` started (`startedByServe`, #1722): a lock held by the app's or the keeper's host is theirs,
+ * whatever answers on the port, so `--stop` says whose it is and leaves it.
  *
  * `{ ok, wasRunning, how?, message? }`, the `--stop` line's `stop`. With `ifIdle` (#1224, the hand-over) the host stops only
  * when nothing runs there, and `{ ok: false, busy: true }` says it did not. `forUpdate` (#1618): a hub's update stops it, and
@@ -32,28 +36,42 @@ export async function stopServedHost({ dataDir, entry, platform = process.platfo
   if (!state) return { ok: true, wasRunning: false, message: `no centralu serve has run for ${dataDir}` }
   const port = state.port ?? DEFAULT_SERVE_PORT
   const installed = protocolVersionOf(entry) ?? 0
-  const prove = hostProvesOf(entry)
   // The limited credential is enough to probe and to stop it (#1405, `host.stop` is everyday)
-  const own = ownCredentials(state, entry)
-  const probe = () => probeHost({ port, ...own, protocolVersion: installed, prove })
+  const own = { token: state.token, proofKey: state.proofKey }
+  const probe = () => probeHost({ port, ...own, protocolVersion: installed })
   const first = await probe()
-  if (!heldHere(first, dataDir)) return { ok: true, wasRunning: false, message: `centralu serve is not running for ${dataDir}` }
+  const silent = !first.running && !first.unproven && (await heldSilently(dataDir, port))
+  if (!silent && !heldHere(first, dataDir, undefined, state.port != null)) {
+    // The folder is held, but not by a serve (#1722): the app's or the keeper's host, whatever answered on the port
+    const other = foreignHolder(dataDir)
+    const whose = other ? `. It belongs to another Centralu host (pid ${other.pid}), ${holderWho(other.by)}; not stopping it` : ''
+    return { ok: true, wasRunning: false, message: `centralu serve is not running for ${dataDir}${whose}` }
+  }
 
   const hostPid = lockHolderPid(dataDir)
+  // Only a host `serve` started is ever signalled, whoever answered with this folder's token
+  const mayKill = startedByServe(dataDir)
   const launcher = readServePid(dataDir)
   // serve.pid is only believed when it names the host that holds the folder now
-  const launcherPid = launcher && hostPid && launcher.hostPid === hostPid ? launcher.pid : null
+  const launcherPid = mayKill && launcher && hostPid && launcher.hostPid === hostPid ? launcher.pid : null
   const down = async () => !(await probe()).running && !(hostPid && isAlive(hostPid))
 
-  let asked = await askHostToStop({ port, ...own, protocolVersion: first.protocolVersion ?? installed, prove, ifIdle, forUpdate })
-  if (!asked.ok && asked.protocolVersion !== undefined) asked = await askHostToStop({ port, ...own, protocolVersion: asked.protocolVersion, prove, ifIdle, forUpdate })
-  // `ifIdle` and it has work running (#1224): it was left as it is
-  if (asked.busy) return { ok: false, wasRunning: true, busy: true, message: asked.message }
   let how = 'asked'
-  let stopped = asked.ok && (await waitUntil(down, timeoutMs))
-  let note = asked.ok ? null : `the host did not take the request to stop (${asked.message})`
+  let stopped = false
+  let note = silent ? 'nothing listens on its port' : null
+  // The hand-over stops only a host that said it is idle: one that cannot say so is left
+  if (silent && ifIdle) return { ok: false, wasRunning: true, message: `the host holds the folder but ${note}` }
+  if (!silent) {
+    let asked = await askHostToStop({ port, ...own, protocolVersion: first.protocolVersion ?? installed, ifIdle, forUpdate })
+    if (!asked.ok && asked.protocolVersion !== undefined) asked = await askHostToStop({ port, ...own, protocolVersion: asked.protocolVersion, ifIdle, forUpdate })
+    // `ifIdle` and it has work running (#1224): it was left as it is
+    if (asked.busy) return { ok: false, wasRunning: true, busy: true, message: asked.message }
+    stopped = asked.ok && (await waitUntil(down, timeoutMs))
+    if (!asked.ok) note = `the host did not take the request to stop (${asked.message})`
+  }
   if (!stopped) {
-    const target = platform !== 'win32' && launcherPid ? launcherPid : hostPid
+    const target = platform !== 'win32' && launcherPid ? launcherPid : mayKill ? hostPid : null
+    if (hostPid && !mayKill) note = `${note ? `${note}; ` : ''}the lock names pid ${hostPid}, which centralu serve did not start, so it was not signalled`
     if (target) {
       how = platform === 'win32' ? 'ended' : 'signal'
       try {
@@ -85,6 +103,16 @@ export async function stopServedHost({ dataDir, entry, platform = process.platfo
   return { ok: true, wasRunning: true, how, ...(note ? { message: note } : {}) }
 }
 
+/**
+ * A host `serve` started that holds the folder's lock while nothing listens on its port (#1903): it took the lock and hung
+ * before it listened, or is still starting. Told by a listen on the port, not by the probe: a host that listens but whose
+ * event loop is stalled answers no probe in time either, and is running (#1906 review). Not part of `heldHere`, which
+ * `--connection` and `--detach`'s wait read: there a host still starting must not count as one that answers
+ */
+async function heldSilently(dataDir, port) {
+  return startedByServe(dataDir) && lockHolderIsAlive(dataDir) && !(await listensHere(port))
+}
+
 /** How long the hand-over waits for the host's work to end before it gives up and says so (#1224 review) */
 export const HANDOVER_WAIT_MS = 30 * 60_000
 
@@ -126,28 +154,22 @@ export async function moveIntoSignIn({
   const state = readServeState(dataDir)
   if (!state) return false
   const port = state.port ?? DEFAULT_SERVE_PORT
-  const prove = hostProvesOf(entry)
   const protocolVersion = existing.protocolVersion ?? protocolVersionOf(entry) ?? 0
-  const own = ownCredentials(state, entry)
+  const own = { token: state.token, proofKey: state.proofKey }
   /*
-   * `host.handover` is a hub's call (#1405, `link`): said with a full credential made for this one call and withdrawn
-   * right after, never kept. An older installed host knows only the token kept for it
+   * `host.handover` takes everyday rights (#1711, docs/plans/key-pairing.md §4.4): said with the credentials this
+   * launcher holds for its own host (the limited credential, after a proof under the key), and no credential is made for
+   * it. Before, a full one made for this call went to whatever answered that proof, which a reader of serve.json can. A
+   * host from #1405 to key pairing refuses it (`link`): no note on the row while this waits, and the move goes on
    */
-  const sayHandover = async (h) => {
-    const made = takesVerifiers(entry) ? pairServe(dataDir, 'handover', platform, Date.now(), 'handover') : null
-    try {
-      return await askHostRpc({ port, token: made?.token ?? own.token, proofKey: own.proofKey, protocolVersion, prove, method: 'host.handover', params: { handover: h } })
-    } finally {
-      if (made) revokeServe(dataDir, made.id, platform)
-    }
-  }
+  const sayHandover = (h) => askHostRpc({ port, ...own, protocolVersion, method: 'host.handover', params: { handover: h } })
   const report = (handover) => (tell ?? sayHandover)(handover)
   const pid = lockHolderPid(dataDir)
   say(`the host running for ${dataDir}${pid ? ` (pid ${pid})` : ''} runs in a network logon (started over ssh), where Git cannot use the credentials saved in Windows; moving it into this Windows sign-in once nothing runs there`)
   const t0 = now()
   let waiting = false
   for (;;) {
-    if (!(await probeHost({ port, ...own, protocolVersion, prove })).running) return true
+    if (!(await probeHost({ port, ...own, protocolVersion })).running) return true
     const r = await stop()
     if (r.ok) {
       say(`stopped it${r.how && r.how !== 'asked' ? ` (${r.how})` : ''}; starting the host in this sign-in`)

package/bin/serve-host.mjs

@@ -1,11 +1,12 @@
 /**
  * The host `centralu serve` runs: how it is started, and talking to a running one over its own socket
- * (a hello with the token, a proof first where the host gives one, `host.stop`).
+ * (a proof, then a hello with the token, `host.stop`).
  */
 import { createHmac, randomBytes } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
 import { connect } from 'node:net'
 import { dirname, join } from 'node:path'
+import { LINK_NONCE_BYTES, signedHostKey } from './serve-keys.mjs'
 
 /**
  * The protocol a host folder speaks, from the `bundle-info.json` the bundler writes next to
@@ -34,20 +35,26 @@ export function protocolVersionOf(entry) {
  * `install` (additive, the line stays `v: 1`) says what runs this command (`installInfo`); `detach`
  * is added by `--detach` only.
  */
-export function connectionLine({ port, token, credential, limited, others, version, protocolVersion, dataDir, hostRunning, install, autostart, detach, proof, stopped }) {
+export function connectionLine({ port, token, credential, limited, others, version, protocolVersion, dataDir, hostRunning, install, autostart, detach, stopped, hostKey, keyId }) {
   /*
-   * The options this serve takes that an older one refuses (#1223): a hub adds `--from <its name>` to `--detach` only
-   * when the line says so, since an older serve answers an option it does not know with an error. `window`: the
+   * The options this serve takes that an older one refuses (#1223): a hub up to 0.1.0-beta.45's adds `--from <its name>`
+   * to `--detach` only when the line says so, since an older serve answers an option it does not know with an error. `window`: the
    * desktop window on Windows uses this serve's host through `--window` only when it is listed (#1223 review)
    */
   /*
    * `pair` (#1405): `--connection --pair <label>` hands out a full credential of its own; without it the line carries the
    * limited credential only
    */
-  const takes = ['from', 'window', 'pair']
+  /*
+   * `pairKey` (#1711, docs/plans/key-pairing.md §4.2): `--pair-key` made a key pairing, said only on a line that is one
+   * (`hostKey` and `keyId`, and no `token`). A line from `--pair-key` without it is a verifier pairing
+   */
+  const takes = ['from', 'window', 'pair', ...(hostKey && keyId ? ['pairKey'] : [])]
   return JSON.stringify({
     v: 1,
     port,
+    // The key the running host signs with, and the hub's key entry it signs for (#1711); never with a credential
+    ...(hostKey && keyId ? { hostKey, keyId } : {}),
     // A full credential only to `--pair` (#1405), with its id for the proof; an older serve always printed its token
     ...(token ? { token } : {}),
     ...(credential ? { credential } : {}),
@@ -62,8 +69,8 @@ export function connectionLine({ port, token, credential, limited, others, versi
     ...(install ? { install } : {}),
     ...(autostart ? { autostart } : {}),
     ...(detach ? { detach } : {}),
-    // The running host proves it holds the token before the hub sends it (#838); absent: the hub sends hello as before
-    ...(proof ? { proof: true } : {}),
+    // The running host proves it holds the token before the hub sends it (#838): every host from 0.1.0-beta.45 on does
+    proof: true,
     // The person stopped the host here, and when (#1143, `readStopped`); absent: an older serve, or no such stop
     ...(stopped ? { stopped } : {}),
     takes,
@@ -108,12 +115,10 @@ function parseStartedFrom(raw) {
 /**
  * The host's environment.
  *
- * - The token is in neither: arguments are readable by every user on the machine (`ps`), and a
+ * - The key is in neither: arguments are readable by every user on the machine (`ps`), and a
  *   process's start environment by every process of its user for as long as it runs (`ps eww`,
- *   #502). `CC_HOST_TOKEN_ON_STDIN=1` tells the host it comes as the first line on its stdin
- *   (`tokenLine`, #538), which is a pipe to this launcher anyway (`--watch-parent`). A host bundle
- *   from before #538 reads only `CC_HOST_TOKEN`: given `legacyToken` (`takesTokenOnStdin` said no),
- *   it gets the token there, as before.
+ *   #502). `CC_HOST_TOKEN_ON_STDIN=1` tells the host its key comes as the first line on its stdin
+ *   (`keyLine`, #538), which is a pipe to this launcher anyway (`--watch-parent`).
  * - `CC_HOST_SOURCE` is the record `hello_ok.build` is made from (keeper-link.ts); without it a
  *   client could not see which version the host it reached is.
  * - Headless: no `DISPLAY` / `WAYLAND_DISPLAY`. Nothing the host or an agent starts gets a screen
@@ -123,12 +128,12 @@ function parseStartedFrom(raw) {
  *   `CENTRALU_MANAGED`, which is the launcher's business and would otherwise reach every agent.
  * - `CC_SERVE=1` lets the host take `host.stop` (`--stop`); a host the app runs refuses it.
  */
-export function hostEnv(env, { dataDir, version, hostDir, legacyToken, from = null, serveState = null }) {
+export function hostEnv(env, { dataDir, version, hostDir, from = null, serveState = null }) {
   const out = { ...env }
   for (const k of ['DISPLAY', 'WAYLAND_DISPLAY', 'CC_KEEPER', 'CC_FRONT_DOOR', 'CC_DEV', 'CC_HOST_TOKEN', 'CC_HOST_TOKEN_ON_STDIN', 'CC_HOST_SOURCE', 'CC_SERVE_STATE', 'CENTRALU_MANAGED', 'CENTRALU_STARTED_FROM', 'CC_SERVE_FROM', 'CC_STARTED_BY']) delete out[k]
   /*
-   * A host that checks full credentials against serve.json's verifiers (#1405, `takesVerifiers`): the file it reads at
-   * each hello. A path, not a secret: the file is the user's own, 0600. Its key comes on stdin (`keyLine`)
+   * The host checks full credentials against serve.json's verifiers (#1405): the file it reads at each hello. A path,
+   * not a secret: the file is the user's own, 0600. Its key comes on stdin (`keyLine`)
    */
   if (serveState) out.CC_SERVE_STATE = serveState
   // Who asked for this host, for its host.lock (#1223): a second host on the folder names it when refused
@@ -136,62 +141,19 @@ export function hostEnv(env, { dataDir, version, hostDir, legacyToken, from = nu
   out.CC_DATA_DIR = dataDir
   // The host `host.stop` may end (`centralu serve --stop`): nothing else stops it in order on Windows
   out.CC_SERVE = '1'
-  if (legacyToken === undefined) out.CC_HOST_TOKEN_ON_STDIN = '1'
-  else out.CC_HOST_TOKEN = legacyToken
+  out.CC_HOST_TOKEN_ON_STDIN = '1'
   out.CC_HOST_SOURCE = JSON.stringify({ version, bundlePath: hostDir })
   return out
 }
 
 /**
- * Whether the host at `entry` reads its token from stdin (#538): a bundle says so in `bundle-info.json`
- * (`tokenOnStdin`), as the keeper reads it; a host run from source always does. `CENTRALU_HOST_ENTRY` can point at an
- * older bundle, which would otherwise get no token and refuse every hello.
- */
-export function takesTokenOnStdin(entry) {
-  try {
-    return JSON.parse(readFileSync(join(dirname(entry), 'bundle-info.json'), 'utf8')).tokenOnStdin === 1
-  } catch {
-    // not a bundle: the source, which reads it
-  }
-  return !existsSync(join(dirname(entry), 'bundle-info.json'))
-}
-
-/** The first line on the host's stdin: the token (#538, the host's `readHandedToken`) */
-export function tokenLine(token) {
-  return `${JSON.stringify({ token })}\n`
-}
-
-/**
- * The first line on the stdin of a host that takes verifiers (#1405): its key, from which it derives what it hands out.
- * Not a full credential: the host never takes it as one (`CC_SERVE_STATE` says where the full ones' verifiers are)
+ * The first line on the host's stdin (#538, #1405; the host's `readHandedToken`): its key, from which it derives what it
+ * hands out. Not a full credential: the host never takes it as one (`CC_SERVE_STATE` says where the full ones' verifiers are)
  */
 export function keyLine(key) {
   return `${JSON.stringify({ key })}\n`
 }
 
-/**
- * Whether the host at `entry` checks full credentials against serve.json's verifiers (#1405): a bundle says so in
- * `bundle-info.json` (`verifiers`), a host run from source has `lifecycle/serve-credentials.ts`. An older one knows a
- * single token, which this launcher then keeps for it (`legacyHostTokenOf`).
- */
-export function takesVerifiers(entry) {
-  try {
-    return JSON.parse(readFileSync(join(dirname(entry), 'bundle-info.json'), 'utf8')).verifiers === 1
-  } catch {
-    // not a bundle; try the source below
-  }
-  return existsSync(join(dirname(entry), 'lifecycle', 'serve-credentials.ts'))
-}
-
-/**
- * What this launcher says hello with to its own host, and what that host proves with to it: the limited credential
- * and the key for a host that takes verifiers, the one token an older host knows otherwise (#1405).
- */
-export function ownCredentials(state, entry) {
-  if (takesVerifiers(entry) || !state.legacyHostToken) return { token: state.token, proofKey: state.proofKey }
-  return { token: state.legacyHostToken, proofKey: state.legacyHostToken }
-}
-
 /**
  * How to start the host.
  *
@@ -249,17 +211,82 @@ function mismatchProtocolOf(error) {
 }
 
 /**
- * Whether the installed host answers a `prove` (#838): a bundle says so in `bundle-info.json` (`hostProof`), a host run
- * from source has `transport/host-proof.ts`. The connection line's `proof` is this, not a live answer: a program another
- * account put on the port could otherwise answer the probe so as to make the line say no, and the hub send the token.
+ * Whether the host at `entry` takes a hub's key hello (#1711): a bundle says so in `bundle-info.json` (`keyPairing`), a
+ * host run from source has `transport/link-proof.ts`. `--pair-key` reports a key derived from serve.json only for a host
+ * started next that will sign with it (docs/plans/key-pairing.md §4.2)
  */
-export function hostProvesOf(entry) {
+export function takesKeyHellos(entry) {
   try {
-    return JSON.parse(readFileSync(join(dirname(entry), 'bundle-info.json'), 'utf8')).hostProof === 1
+    return JSON.parse(readFileSync(join(dirname(entry), 'bundle-info.json'), 'utf8')).keyPairing === 1
   } catch {
     // not a bundle; try the source below
   }
-  return existsSync(join(dirname(entry), 'transport', 'host-proof.ts'))
+  return existsSync(join(dirname(entry), 'transport', 'link-proof.ts'))
+}
+
+/**
+ * Asks the host on `port` to sign for the key entry `keyId` (#1711, docs/plans/key-pairing.md §4.2 step 3), as a hub
+ * would: a `prove` naming it, with a nonce of this launcher's, and the answer's signature checked against the key it
+ * carries, the hub's key `hubKey` and the address `127.0.0.1:<port>`. No hello follows. One of:
+ *
+ * - `{ outcome: 'signed', hostKey }`: the running host signs, with `hostKey` (after `--rotate-token`, still its old one);
+ * - `{ outcome: 'unsigned' }`: a proof with no signature at all, from a host from before key pairing still running;
+ * - `{ outcome: 'none' }`: the connection was refused, so nothing listens there;
+ * - `{ outcome: 'unknown' }`: anything else (no answer within `timeoutMs`, a socket closed before a proof, a proof that is
+ *   malformed or does not verify, no WebSocket in this Node), which pairs as a host that does not sign does.
+ */
+export async function probeKeyProof({ port, keyId, hubKey, timeoutMs = 2000, WebSocketImpl = globalThis.WebSocket, connectTo = connect }) {
+  // Refused at once: nothing listens. Told apart from a socket that opens and says nothing, which is not known to be nothing
+  const reach = await new Promise((resolve) => {
+    const s = connectTo({ host: '127.0.0.1', port })
+    const done = (r) => {
+      s.destroy()
+      resolve(r)
+    }
+    s.setTimeout(timeoutMs, () => done('unknown'))
+    s.once('connect', () => done('open'))
+    s.once('error', (e) => done(e?.code === 'ECONNREFUSED' ? 'none' : 'unknown'))
+  })
+  if (reach !== 'open') return { outcome: reach }
+  if (typeof WebSocketImpl !== 'function') return { outcome: 'unknown' }
+  const nonce = randomBytes(LINK_NONCE_BYTES).toString('base64url')
+  return new Promise((resolve) => {
+    let ws = null
+    let settled = false
+    const done = (r) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try {
+        ws?.close()
+      } catch {
+        // already closed
+      }
+      resolve(r)
+    }
+    const timer = setTimeout(() => done({ outcome: 'unknown' }), timeoutMs)
+    try {
+      ws = new WebSocketImpl(`ws://127.0.0.1:${port}`)
+    } catch {
+      return done({ outcome: 'unknown' })
+    }
+    ws.onopen = () => ws.send(JSON.stringify({ kind: 'prove', nonce, key: keyId }))
+    ws.onmessage = (ev) => {
+      let m = null
+      try {
+        m = JSON.parse(String(ev.data))
+      } catch {
+        // not a frame
+      }
+      const hostKey = signedHostKey(m, { hubNonce: nonce, hubKey, keyId, port })
+      if (hostKey) return done({ outcome: 'signed', hostKey })
+      // A proof without any of the three fields: a host that does not sign. One with some of them and no valid signature is not known
+      const unsigned = m?.kind === 'proof' && m.nonce === nonce && m.hostNonce === undefined && m.hostKey === undefined && m.sig === undefined
+      done({ outcome: unsigned ? 'unsigned' : 'unknown' })
+    }
+    ws.onerror = () => done({ outcome: 'unknown' })
+    ws.onclose = () => done({ outcome: 'unknown' })
+  })
 }
 
 /** The answer a host holding `token` gives to a `prove` of `nonce` (the host's `hostProof`) */
@@ -268,20 +295,19 @@ function proofOf(token, nonce) {
 }
 
 /**
- * Opens a socket to the host and says hello with the token, the way `probeHost` and `askHostToStop` do. With `prove`
- * (the installed host can, `hostProvesOf`), the host first proves it holds the token (#838), and the token goes out only
- * then: whatever else listens on the port (another account's program, while the host is down) never sees it.
+ * Opens a socket to the host and says hello with the token, the way `probeHost` and `askHostToStop` do. The host first
+ * proves it holds the token (#838), and the token goes out only then: whatever else listens on the port (another
+ * account's program, while the host is down) never sees it.
  * `on.message(m, ws)` gets every frame after the hello; `on.unproven()` runs when the proof did not come, `on.gone()`
  * when the socket failed or closed.
  */
-function helloSocket({ port, token, proofKey, protocolVersion, prove, WebSocketImpl, on }) {
+function helloSocket({ port, token, proofKey, protocolVersion, WebSocketImpl, on }) {
   const ws = new WebSocketImpl(`ws://127.0.0.1:${port}`)
-  const nonce = prove ? randomBytes(24).toString('base64url') : null
+  const nonce = randomBytes(24).toString('base64url')
   // Proving only once the socket is open: a port where nothing listens is gone, not unproven
   let proving = false
   const hello = () => ws.send(JSON.stringify({ kind: 'hello', token, protocolVersion: protocolVersion ?? 0 }))
   ws.onopen = () => {
-    if (!prove) return hello()
     proving = true
     ws.send(JSON.stringify({ kind: 'prove', nonce }))
   }
@@ -309,17 +335,17 @@ function helloSocket({ port, token, proofKey, protocolVersion, prove, WebSocketI
  * Whether a host that holds this token answers on the port: a real hello, not a TCP connect, so a
  * stranger's program on the same port does not count, and the answer carries the running host's
  * own protocol and version (which differ from the installed package's after an `npm i -g` the
- * host was not restarted for). With `prove` the host proves it holds the token first (#838).
+ * host was not restarted for). The host proves it holds the token first (#838).
  *
  * `{ running, protocolVersion?, version?, unproven? }`. `unproven`: something answered on the port but did not prove
- * it holds the token, so it was not sent: another program, or a host from before #838 still running after an update
+ * it holds the token, so it was not sent: another program, or a host still on its old key after `--rotate-token`
  * (`heldHere` tells those apart by the data folder's lock). Node 22.4+ has a global WebSocket; on an older 22 this falls
  * back to a TCP connect and reports only `running`.
  */
-export function probeHost({ port, token, proofKey, protocolVersion, prove = false, timeoutMs = 2000, WebSocketImpl = globalThis.WebSocket }) {
+export function probeHost({ port, token, proofKey, protocolVersion, timeoutMs = 2000, WebSocketImpl = globalThis.WebSocket }) {
   if (typeof WebSocketImpl !== 'function') return tcpProbe(port, timeoutMs)
   return helloExchange({
-    port, token, proofKey, protocolVersion, prove, WebSocketImpl, timeoutMs,
+    port, token, proofKey, protocolVersion, WebSocketImpl, timeoutMs,
     timedOut: { running: false },
     failed: () => ({ running: false }),
     on: (done) => ({
@@ -391,10 +417,10 @@ const HOST_LOGONS = ['interactive', 'network', 'batch', 'service']
  * One call to a running host (`method` with `params`), as `askHostToStop` makes it: a hello with the token, then the
  * call. Its result, or null when it did not answer or refused. For `host.handover` (#1224)
  */
-export function askHostRpc({ port, token, proofKey, protocolVersion, prove = false, method, params = {}, timeoutMs = 5000, WebSocketImpl = globalThis.WebSocket }) {
+export function askHostRpc({ port, token, proofKey, protocolVersion, method, params = {}, timeoutMs = 5000, WebSocketImpl = globalThis.WebSocket }) {
   if (typeof WebSocketImpl !== 'function') return Promise.resolve(null)
   return helloExchange({
-    port, token, proofKey, protocolVersion, prove, WebSocketImpl, timeoutMs,
+    port, token, proofKey, protocolVersion, WebSocketImpl, timeoutMs,
     timedOut: null,
     failed: () => null,
     on: (done) => ({
@@ -416,11 +442,10 @@ export function askHostRpc({ port, token, proofKey, protocolVersion, prove = fal
  * `ifIdle` (#1224): only if nothing runs there, checked and acted on by the host in one step; `{ ok: false, busy: true }`
  * when something does. `forUpdate` (#1618): a hub's update stops it, and the host lists the turns it ends for the next one.
  */
-export function askHostToStop({ port, token, proofKey, protocolVersion, prove = false, ifIdle = false, forUpdate = false, timeoutMs = 5000, WebSocketImpl = globalThis.WebSocket }) {
+export function askHostToStop({ port, token, proofKey, protocolVersion, ifIdle = false, forUpdate = false, timeoutMs = 5000, WebSocketImpl = globalThis.WebSocket }) {
   if (typeof WebSocketImpl !== 'function') return Promise.resolve({ ok: false, message: `Node ${process.version} has no WebSocket to ask with` })
-  // With `prove`, the token goes out only to a host that proved it holds it (#838)
   return helloExchange({
-    port, token, proofKey, protocolVersion, prove, WebSocketImpl, timeoutMs,
+    port, token, proofKey, protocolVersion, WebSocketImpl, timeoutMs,
     timedOut: { ok: false, message: 'no answer in time' },
     failed: (e) => ({ ok: false, message: e.message }),
     on: (done) => ({

package/bin/serve-install.mjs

@@ -105,7 +105,7 @@ export function remoteLayout(dataDir) {
 }
 
 /** A word a pointer file may hold: a folder name, nothing a path could escape with */
-const POINTER_WORD = /^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/
+export const POINTER_WORD = /^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/
 
 /** `current` / `previous`: one line, "<centralu version> <node version>". null for anything else */
 export function parsePointer(text) {
@@ -146,7 +146,21 @@ export function installInfo(dataDir, env, nodeVersion = process.versions.node) {
     const source = p && installSource(join(l.versions, p.version))
     return p && source ? { ...p, source } : p
   }
-  return { managed: env.CENTRALU_MANAGED === '1', current: read(l.current), previous: read(l.previous), node: nodeVersion }
+  return { managed: env.CENTRALU_MANAGED === '1', current: read(l.current), previous: read(l.previous), node: nodeVersion, lastSwitch: lastSwitchOf(l.root) }
+}
+
+/**
+ * The last switch there (`switch.json`, serve-switch.mjs), as much as a hub needs to know whether to read it: its id,
+ * whether it ended, and whether its outcome was reported (`--seen`). A hub that was away for the whole of it, or
+ * restarted since, learns from this at its next open that there is an outcome to say (#1907). Null when none ran
+ */
+function lastSwitchOf(root) {
+  try {
+    const s = JSON.parse(readFileSync(join(root, 'switch.json'), 'utf8'))
+    return typeof s?.id === 'string' ? { id: s.id, ended: typeof s.outcome === 'string', seen: s.seen === true } : null
+  } catch {
+    return null
+  }
 }
 
 /**

package/bin/serve-keys.mjs

@@ -0,0 +1,126 @@
+/**
+ * The launcher's side of a hub's key pairing (#1711, docs/plans/key-pairing.md §4.1 to §4.3): the check of a hub's
+ * public key at `--pair-key`, the public key of the host's signing key derived from serve.json's `key`, and the check of
+ * the running host's signed proof. The same rules as the host's `transport/link-keys.ts`, which this standalone launcher
+ * cannot import; `tooling/launcher-keys.test.ts` holds the two to the same answers and to the pinned vector.
+ */
+import { createHmac, createPrivateKey, createPublicKey, verify } from 'node:crypto'
+
+/** Bytes of a nonce, a public key and a signature (`@cc/protocol` `link-wire.ts`) */
+export const LINK_NONCE_BYTES = 24
+export const LINK_PUBLIC_KEY_BYTES = 32
+export const LINK_SIGNATURE_BYTES = 64
+
+const CONTEXT_LABEL = 'centralu link v1'
+const HOST_ROLE_LABEL = 'centralu link host v1'
+const HOST_KEY_LABEL = 'centralu host key v1'
+const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex')
+const PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex')
+const P = 2n ** 255n - 19n
+
+/** The bytes of `text` when it is exactly the base64url (no padding) of `bytes` bytes: encoding them again gives the same string */
+export function decodeBase64url(text, bytes) {
+  if (typeof text !== 'string') return null
+  const raw = Buffer.from(text, 'base64url')
+  if (raw.length !== bytes || raw.toString('base64url') !== text) return null
+  return raw
+}
+
+/** The 32 bytes as a little-endian number with the top bit (the sign of x) cleared */
+function yOf(raw) {
+  let y = 0n
+  for (let i = raw.length - 1; i >= 0; i--) y = (y << 8n) | BigInt(i === raw.length - 1 ? raw[i] & 0x7f : raw[i])
+  return y
+}
+
+/** The y of the eight small-order points: 0, 1, p − 1 and the two of order 8 (libsodium's `ge25519_has_small_order`) */
+const SMALL_ORDER_Y = [
+  0n,
+  1n,
+  P - 1n,
+  yOf(Buffer.from('26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05', 'hex')),
+  yOf(Buffer.from('c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a', 'hex')),
+]
+
+/**
+ * `{ text, raw, key }` for a public key the host takes (§4.1), or null: exactly 43 canonical base64url characters, a y
+ * below p, not the y of a small-order point (either sign bit), and an Ed25519 key `node:crypto` imports. Unchecked, on
+ * Node 22 a small-order key verifies a forged signature over every message.
+ */
+export function parseLinkPublicKey(text) {
+  const raw = decodeBase64url(text, LINK_PUBLIC_KEY_BYTES)
+  if (!raw) return null
+  const y = yOf(raw)
+  if (y >= P || SMALL_ORDER_Y.includes(y)) return null
+  let key
+  try {
+    key = createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: 'der', type: 'spki' })
+  } catch {
+    return null
+  }
+  return key.asymmetricKeyType === 'ed25519' ? { text, raw, key } : null
+}
+
+/**
+ * The public key a host started with `key` signs with (§4.1): `seed = HMAC-SHA256(key, "centralu host key v1")`, as
+ * PKCS#8. What `--pair-key` reports when no host runs and none of a keeper's may run with another key (§4.2).
+ */
+export function hostLinkPublicKey(key) {
+  if (typeof key !== 'string' || key.length === 0) throw new Error('The host key is empty')
+  const seed = createHmac('sha256', key).update(HOST_KEY_LABEL).digest()
+  const priv = createPrivateKey({ key: Buffer.concat([PKCS8_PREFIX, seed]), format: 'der', type: 'pkcs8' })
+  const der = createPublicKey(priv).export({ format: 'der', type: 'spki' })
+  const text = der.subarray(SPKI_PREFIX.length).toString('base64url')
+  if (!parseLinkPublicKey(text)) throw new Error('The derived host key was refused')
+  return text
+}
+
+/** `u32be(len) ‖ bytes` for each part; a string as ASCII, and one with another character throws */
+export function encodeFields(parts) {
+  const out = []
+  for (const part of parts) {
+    if (typeof part === 'string' && Array.from(part).some((c) => c.codePointAt(0) > 0x7f)) throw new Error('A field string is ASCII')
+    const b = typeof part === 'string' ? Buffer.from(part, 'ascii') : Buffer.from(part)
+    const len = Buffer.alloc(4)
+    len.writeUInt32BE(b.length)
+    out.push(len, b)
+  }
+  return Buffer.concat(out)
+}
+
+/** `127.0.0.1:<port>` for a port 1 to 65535, null otherwise (the host's `linkAddress`) */
+export function linkAddress(port) {
+  return Number.isInteger(port) && port >= 1 && port <= 65535 ? `127.0.0.1:${port}` : null
+}
+
+/** The transcript `T` (§4.3), or null when a value is refused */
+export function linkTranscript({ hubNonce, hostNonce, hostKey, hubKey, keyId, address }) {
+  const nh = decodeBase64url(hubNonce, LINK_NONCE_BYTES)
+  const ns = decodeBase64url(hostNonce, LINK_NONCE_BYTES)
+  const pm = parseLinkPublicKey(hostKey)
+  const ph = parseLinkPublicKey(hubKey)
+  if (!nh || !ns || !pm || !ph) return null
+  if (typeof keyId !== 'string' || !/^[0-9a-f]{8}$/.test(keyId)) return null
+  if (typeof address !== 'string' || !/^127\.0\.0\.1:[1-9][0-9]{0,4}$/.test(address) || linkAddress(Number(address.slice(10))) !== address) return null
+  return encodeFields([CONTEXT_LABEL, nh, ns, pm.raw, ph.raw, keyId, address])
+}
+
+/**
+ * The key a running host signs with, when `proof` is its signed answer to a key `prove` of `hubNonce` (§4.2 step 3):
+ * `hostNonce`, `hostKey` and `sig` all present, strict, and the host's signature verifying over the transcript built
+ * here from the hub's key, the entry's id and the address the hub forwards to. Null for anything else: an answer
+ * without a signature (a host from before key pairing), or one that does not verify.
+ */
+export function signedHostKey(proof, { hubNonce, hubKey, keyId, port }) {
+  if (proof?.kind !== 'proof' || proof.nonce !== hubNonce) return null
+  const pm = parseLinkPublicKey(proof.hostKey)
+  const sig = decodeBase64url(proof.sig, LINK_SIGNATURE_BYTES)
+  if (!pm || !sig) return null
+  const t = linkTranscript({ hubNonce, hostNonce: proof.hostNonce, hostKey: proof.hostKey, hubKey, keyId, address: linkAddress(port) })
+  if (!t) return null
+  try {
+    return verify(null, Buffer.concat([encodeFields([HOST_ROLE_LABEL]), t]), pm.key, sig) ? pm.text : null
+  } catch {
+    return null
+  }
+}