centralu 0.1.0-beta.45 → 0.1.0-beta.46

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-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
+  }
+}

package/bin/serve-run.mjs

@@ -4,10 +4,11 @@ import { writeFileSync, writeSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { createInterface } from 'node:readline'
 import { isAlive, say } from './serve-util.mjs'
-import { SERVE_STATE_FILE, SERVE_PID_FILE, readStopped, serveDataDir, ensureServeState, recordServePort, rotateServeToken, heldHere, lockHolder, lockHolderPid, removeServePid, pairServe, revokeServe, legacyHostTokenOf, dropLegacyHostToken } from './serve-files.mjs'
+import { SERVE_STATE_FILE, SERVE_PID_FILE, readStopped, serveDataDir, ensureServeState, recordServePort, rotateServeToken, heldHere, lockHolder, lockHolderPid, holderWho, removeServePid, pairServe, pairKeyServe, dropVerifierUnder, revokeServe } from './serve-files.mjs'
 import { DEFAULT_SERVE_PORT, SERVE_PORT_TRIES, chooseServePort, listensHere, windowsListening } from './serve-port.mjs'
 import { keepLauncher, installInfo } from './serve-install.mjs'
-import { protocolVersionOf, connectionLine, hostEnv, hostCommand, readyPort, hostProvesOf, probeHost, serveFrom, takesTokenOnStdin, tokenLine, keyLine, takesVerifiers, ownCredentials } from './serve-host.mjs'
+import { protocolVersionOf, connectionLine, hostEnv, hostCommand, readyPort, probeHost, probeKeyProof, serveFrom, keyLine, takesKeyHellos } from './serve-host.mjs'
+import { hostLinkPublicKey } from './serve-keys.mjs'
 import { autostartInfo } from './serve-autostart.mjs'
 import { moveIntoSignIn } from './serve-handover.mjs'
 
@@ -27,29 +28,33 @@ export function serveFolder({ env, home, cliPath, platform = process.platform })
  *
  * The credentials (#1405): `paired` (`--pair`, `{ token, id }`) is a full credential just made for whoever asked, and
  * the only one this ever prints; without it the line carries the limited credential, which reads and does the everyday
- * things. An installed host from before verifiers knows one token: `--pair` hands out that one (`legacyHostTokenOf`).
+ * things.
  * `others` names the full credentials the folder holds besides the one just paired, never their values, each marked
  * `replaced` when its pairing took the place of an earlier one of its label.
  */
-export async function describe({ env, dataDir, state, entry, version, paired = null }) {
+export async function describe({ env, dataDir, state, entry, version, paired = null, keyPaired = null }) {
   const port = state.port ?? DEFAULT_SERVE_PORT
   const installed = protocolVersionOf(entry)
-  // Whether the installed host proves it holds the token (#838): asked of the running one before its hello, and said in the line
-  const proof = hostProvesOf(entry)
-  const own = ownCredentials(state, entry)
-  const probe = await probeHost({ port, ...own, protocolVersion: installed, prove: proof })
+  const probe = await probeHost({ port, token: state.token, proofKey: state.proofKey, protocolVersion: installed })
   const protocolVersion = (probe.running ? probe.protocolVersion : undefined) ?? installed
   if (protocolVersion === null) return null
-  const hostRunning = heldHere(probe, dataDir)
+  const hostRunning = heldHere(probe, dataDir, undefined, state.port != null)
   // The person stopped it here (#1143): said while no host runs, so a hub starts none by itself
   const stopped = hostRunning ? null : readStopped(dataDir)
-  const verifiers = takesVerifiers(entry)
   return {
-    proof,
     port,
-    ...(paired ? { token: paired.token, ...(paired.id ? { credential: paired.id } : {}) } : {}),
-    ...(verifiers ? { limited: state.token } : {}),
-    others: state.full.filter((e) => e.id !== paired?.id).map(({ id, label, created, replaced }) => ({ id, label, created, ...(replaced ? { replaced: true } : {}) })),
+    ...(paired ? { token: paired.token, credential: paired.id } : {}),
+    // A key pairing (#1711): the key the running host signs with and the entry it signs for, never a credential
+    ...(keyPaired ? { hostKey: keyPaired.hostKey, keyId: keyPaired.keyId } : {}),
+    limited: state.token,
+    /*
+     * The hubs' key entries are listed too, with their public keys (#1711, §4.4), which a hub compares with its own; the
+     * one this line pairs is left out, as the full credential just paired is
+     */
+    others: [
+      ...state.full.filter((e) => e.id !== paired?.id).map(({ id, label, created, replaced }) => ({ id, label, created, ...(replaced ? { replaced: true } : {}) })),
+      ...(state.keys ?? []).filter((k) => k.id !== keyPaired?.keyId).map(({ id, label, created, replaced, publicKey }) => ({ id, label, created, publicKey, ...(replaced ? { replaced: true } : {}) })),
+    ],
     version: (probe.running ? probe.version : undefined) ?? version,
     protocolVersion,
     dataDir,
@@ -64,23 +69,35 @@ export async function describe({ env, dataDir, state, entry, version, paired = n
  * `centralu serve --connection`. stdout carries exactly one line, the JSON; everything else goes to
  * stderr. Exit 1 when there is no host to describe.
  */
-export async function printConnection({ env, home, entry, version, cliPath, pair = null }) {
+export async function printConnection({ env, home, entry, version, cliPath, pair = null, pairKey = null, keyPaired = false, probeKey = probeKeyProof }) {
   const folder = serveFolder({ env, home, cliPath })
   const { dataDir } = folder
   let { state } = folder
   // `--pair <label>` (#1405): a full credential for whoever asked, printed once and written down as its verifier only
   let paired = null
-  if (pair !== null) {
-    if (takesVerifiers(entry)) {
-      const made = pairServe(dataDir, pair)
-      state = made.state
-      paired = { token: made.token, id: made.id }
-      say(`made a full credential for ${JSON.stringify(pair)} (${made.id}); serve --revoke ${made.id} withdraws it`)
+  // `--pair-key <label> <key>` (#1711): a key pairing when the host that will check it signs; else a verifier pairing as `--pair`
+  let keyLine = null
+  if (pairKey !== null) {
+    const made = pairKeyServe(dataDir, pairKey.label, pairKey.publicKey)
+    state = made.state
+    const hostKey = await signingHostKey({ dataDir, state, entry, keyId: made.entry.id, hubKey: pairKey.publicKey, probeKey })
+    if (hostKey) {
+      keyLine = { hostKey, keyId: made.entry.id }
+      // The hub paired by key here before (§4.2): its verifier entry under the label is no longer its own, and goes now
+      if (keyPaired) state = dropVerifierUnder(dataDir, pairKey.label)
+      say(`paired the key of ${JSON.stringify(pairKey.label)} (${made.entry.id}); serve --revoke ${made.entry.id} withdraws it`)
     } else {
-      paired = { token: legacyHostTokenOf(dataDir), id: null }
+      // The key entry stays: it is public, and a host that signs uses it once one runs here
+      pair = pairKey.label
     }
   }
-  const d = await describe({ env, dataDir, state, entry, version, paired })
+  if (pair !== null) {
+    const made = pairServe(dataDir, pair)
+    state = made.state
+    paired = { token: made.token, id: made.id }
+    say(`made a full credential for ${JSON.stringify(pair)} (${made.id}); serve --revoke ${made.id} withdraws it`)
+  }
+  const d = await describe({ env, dataDir, state, entry, version, paired, keyPaired: keyLine })
   if (!d) {
     say(`cannot read the protocol version of the host at ${entry}`)
     return 1
@@ -89,6 +106,28 @@ export async function printConnection({ env, home, entry, version, cliPath, pair
   return 0
 }
 
+/**
+ * The key the host that checks a key hello signs with (#1711, docs/plans/key-pairing.md §4.2), or null when a key
+ * pairing cannot be made now and the line pairs by verifier:
+ *
+ * - the running host signs a `prove` for the entry: the key it signs with, which after `--rotate-token` is still its old
+ *   one until it restarts;
+ * - nothing listens on the port (the connection refused), nothing holds the data folder (`host.lock`: no keeper's host,
+ *   no host starting) and the installed host takes key hellos: the key derived from serve.json's `key`, which the host
+ *   started next is handed;
+ * - otherwise (a host that does not sign, no answer in time, a proof that does not verify, a holder of the folder):
+ *   null. A slow old host never gets a key line, and no line reports a key the running host does not sign with.
+ */
+async function signingHostKey({ dataDir, state, entry, keyId, hubKey, probeKey }) {
+  const port = state.port ?? DEFAULT_SERVE_PORT
+  const probe = await probeKey({ port, keyId, hubKey })
+  if (probe.outcome === 'signed') return probe.hostKey
+  if (probe.outcome !== 'none' || !takesKeyHellos(entry)) return null
+  const holder = lockHolder(dataDir)
+  if (holder && isAlive(holder.pid)) return null
+  return hostLinkPublicKey(state.key)
+}
+
 /**
  * `centralu serve`. Resolves with the exit code once the host has exited.
  *
@@ -108,9 +147,9 @@ export async function runServe({ env, home, entry, version, cliPath, port: asked
   // A serve that is already up answers on the port it recorded; say so before starting a host that
   // would only fail on the data folder's lock with a less specific message.
   const recorded = state.port ?? DEFAULT_SERVE_PORT
-  const existing = await probeHost({ port: recorded, ...ownCredentials(state, entry), protocolVersion, prove: hostProvesOf(entry) })
+  const existing = await probeHost({ port: recorded, token: state.token, proofKey: state.proofKey, protocolVersion })
   // A host the hub's ssh started before anyone signed in moves into this sign-in, once idle (#1224, serve-handover.mjs)
-  if (heldHere(existing, dataDir) && !(await handOver({ dataDir, entry, env, existing, platform }))) {
+  if (heldHere(existing, dataDir, undefined, state.port != null) && !(await handOver({ dataDir, entry, env, existing, platform }))) {
     const pid = lockHolderPid(dataDir)
     say(`centralu serve is already running for ${dataDir} on 127.0.0.1:${recorded}${pid ? ` (pid ${pid})` : ''}. Not starting a second one.`)
     return 1
@@ -129,14 +168,10 @@ export async function runServe({ env, home, entry, version, cliPath, port: asked
   }
 
   const plan = hostCommand(execPath, entry, { port, dataDir, platform })
-  const onStdin = takesTokenOnStdin(entry)
   /*
-   * A host that takes verifiers (#1405) gets the key on stdin and the path of serve.json, whose full credentials it
-   * checks at each hello; nothing it gets opens it whole. An older host gets the one token it knows, kept for it
+   * The host gets the key on stdin and the path of serve.json, whose full credentials it checks at each hello (#1405);
+   * nothing it gets opens it whole
    */
-  const verifiers = takesVerifiers(entry)
-  if (verifiers) dropLegacyHostToken(dataDir, platform)
-  const legacy = verifiers ? null : legacyHostTokenOf(dataDir, platform)
   const child = spawn(plan.command, plan.args, {
     stdio: ['pipe', 'pipe', logFd === null ? 'inherit' : 'pipe'],
     env: hostEnv(env, {
@@ -144,14 +179,13 @@ export async function runServe({ env, home, entry, version, cliPath, port: asked
       version,
       hostDir: dirname(entry),
       from: serveFrom(env, from),
-      ...(verifiers ? { serveState: join(dataDir, SERVE_STATE_FILE) } : {}),
-      ...(onStdin ? {} : { legacyToken: legacy ?? state.token }),
+      serveState: join(dataDir, SERVE_STATE_FILE),
     }),
     detached: plan.detached,
     windowsHide: true,
   })
   // What the host holds, before anything else on the pipe it watches (#538); stdin stays open for --watch-parent
-  if (onStdin) child.stdin.write(verifiers ? keyLine(state.key) : tokenLine(legacy))
+  child.stdin.write(keyLine(state.key))
 
   let ready = false
   if (logFd !== null) {
@@ -217,8 +251,7 @@ export async function runServe({ env, home, entry, version, cliPath, port: asked
         const holder = lockHolder(dataDir)
         if (holder && holder.pid !== child.pid && isAlive(holder.pid)) {
           // Who it is, when its host.lock says (#1223)
-          const who = { app: 'the Centralu window on this machine', keeper: "Centralu's keeper on this machine", serve: 'another centralu serve' }[holder.by] ?? 'probably the Centralu app on this machine'
-          say(`the host did not start. ${dataDir} belongs to another Centralu host (pid ${holder.pid}), ${who}. Quit it, or point CC_DATA_DIR at another folder.`)
+          say(`the host did not start. ${dataDir} belongs to another Centralu host (pid ${holder.pid}), ${holderWho(holder.by)}. Quit it, or point CC_DATA_DIR at another folder.`)
         }
       }
       if (logFd !== null) say(`the host exited (${signal ?? code})`)
@@ -244,9 +277,9 @@ export function revokeCredential({ env, home, id, write = (line) => process.stdo
   write(`${JSON.stringify({ v: 1, revoked, id })}
 `)
   if (!revoked) {
-    say(`no full credential ${JSON.stringify(id)} in ${join(dataDir, SERVE_STATE_FILE)}; --connection lists them under others.`)
+    say(`no credential ${id} in ${join(dataDir, SERVE_STATE_FILE)}; --connection lists them under others.`)
     return 1
   }
-  say(`withdrew the full credential ${id}. A running host refuses its next hello and closes a connection already open with it within a second.`)
+  say(`withdrew ${id}. A running host refuses its next hello with it and closes a connection already open with it within a second.`)
   return 0
 }