centralu 0.1.0-beta.43 → 0.1.0-beta.45

package/bin/centralu.mjs

@@ -48,6 +48,7 @@ import {
   parseServeArgs,
   printConnection,
   rotateToken,
+  revokeCredential,
   runAutostart,
   runDetach,
   runDetachedChild,
@@ -621,6 +622,11 @@ switch (cmd) {
       break
     }
     try {
+      // One full credential withdrawn (#1405): like --rotate-token, nothing to start or describe
+      if (args.mode === 'revoke') {
+        process.exitCode = revokeCredential({ env: process.env, home: HOME, id: args.revoke })
+        break
+      }
       if (args.mode === 'rotate') {
         process.exitCode = rotateToken({ env: process.env, home: HOME })
         break
@@ -655,7 +661,7 @@ switch (cmd) {
       if (spec) Object.assign(process.env, spec.env)
       // realpath: npm's bin is a symlink to this file, and the launcher must not depend on the link
       const opts = { env: process.env, home: HOME, entry: requireHostEntry(), version: pkg.version, cliPath: realpathSync(process.argv[1]) }
-      if (args.mode === 'connection') process.exitCode = await printConnection(opts)
+      if (args.mode === 'connection') process.exitCode = await printConnection({ ...opts, pair: args.pair ?? null })
       else if (args.mode === 'detach') process.exitCode = await runDetach({ ...opts, port: args.port, from: args.from })
       else if (args.mode === 'stop') process.exitCode = await runStop(opts)
       else if (args.mode === 'window') process.exitCode = await runWindow(opts)

package/bin/serve-args.mjs

@@ -8,10 +8,17 @@ export const SERVE_HELP = `centralu serve: run the Centralu host on this machine
   centralu serve --detach         Start it in the background, outside this session; return once it answers
   centralu serve --stop           Ask the running host to stop, and wait until it has
   centralu serve --window         What the Centralu window on Windows runs here: start the host if
-                                  none runs, print its port and token as a ready line, stay until
-                                  stdin ends, and leave the host running
-  centralu serve --connection     Print how to reach it as one JSON line, then exit
-  centralu serve --rotate-token   Replace the token (a running serve keeps the old one until restarted)
+                                  none runs, print its port and a full credential for the window as
+                                  a ready line, stay until stdin ends, and leave the host running
+  centralu serve --connection     Print how to reach it as one JSON line, then exit. It carries the
+                                  limited credential (everyday calls) and lists the full ones
+  centralu serve --connection --pair <label>
+                                  ... and a new full credential for <label>, printed once and kept
+                                  here only as its hash; it replaces <label>'s earlier one. What the
+                                  app on another computer runs at each link
+  centralu serve --revoke <id>    Withdraw one full credential (--connection lists their ids)
+  centralu serve --rotate-token   A new key, and every full credential withdrawn (a running serve
+                                  keeps its old key until restarted)
   centralu serve --from <hub>     With serve or --detach: the name of the computer whose link asks,
                                   said by a second Centralu on this data folder when it is refused
   centralu serve --autostart on|off|remove|status
@@ -32,7 +39,16 @@ from an install the app made over SSH, which has a launcher of its own.`
 
 /** The flags that each make serve a different command */
 const MODE_FLAGS = { '--connection': 'connection', '--rotate-token': 'rotate', '--detach': 'detach', '--stop': 'stop', '--window': 'window' }
-const FLAG_OF = { ...Object.fromEntries(Object.entries(MODE_FLAGS).map(([f, m]) => [m, f])), autostart: '--autostart' }
+const FLAG_OF = { ...Object.fromEntries(Object.entries(MODE_FLAGS).map(([f, m]) => [m, f])), autostart: '--autostart', revoke: '--revoke' }
+
+/**
+ * What `--pair` takes (#1405): who the full credential is for, said back in `--connection`'s `others` and on the hub's
+ * machine row. A hub sends `hub:<its machine id>`
+ */
+export const PAIR_LABEL_RE = /^[A-Za-z0-9:._-]{1,80}$/
+
+/** What `--revoke` takes: a full credential's id, as `--connection` lists it (8 hex characters) */
+export const CREDENTIAL_ID_RE = /^[0-9a-f]{8}$/
 
 /** What `--autostart` takes */
 export const AUTOSTART_ACTIONS = ['on', 'off', 'remove', 'status']
@@ -66,9 +82,21 @@ export function parseServeArgs(argv) {
   let child = null
   let autostart = null
   let from = null
+  let pair = null
+  let revoke = null
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
-    if (a === '--autostart' || a.startsWith('--autostart=')) {
+    if (a === '--pair' || a.startsWith('--pair=')) {
+      const raw = a === '--pair' ? argv[++i] : a.slice('--pair='.length)
+      if (typeof raw !== 'string' || !PAIR_LABEL_RE.test(raw)) return { error: `--pair needs a label: letters, digits, ':', '.', '_' and '-' (got ${raw === undefined ? 'nothing' : JSON.stringify(raw)})` }
+      pair = raw
+    } else if (a === '--revoke' || a.startsWith('--revoke=')) {
+      const raw = a === '--revoke' ? argv[++i] : a.slice('--revoke='.length)
+      if (typeof raw !== 'string' || !CREDENTIAL_ID_RE.test(raw)) return { error: `--revoke needs a credential's id, as --connection lists it (got ${raw === undefined ? 'nothing' : JSON.stringify(raw)})` }
+      if (mode !== 'serve' && mode !== 'revoke') return { error: `${FLAG_OF[mode]} and --revoke are separate commands; pass one` }
+      mode = 'revoke'
+      revoke = raw
+    } else if (a === '--autostart' || a.startsWith('--autostart=')) {
       const raw = a === '--autostart' ? argv[++i] : a.slice('--autostart='.length)
       if (!AUTOSTART_ACTIONS.includes(raw)) return { error: `--autostart needs on, off, remove or status (got ${raw === undefined ? 'nothing' : JSON.stringify(raw)})` }
       if (mode !== 'serve' && mode !== 'autostart') return { error: `${FLAG_OF[mode]} and --autostart are separate commands; pass one` }
@@ -76,7 +104,7 @@ export function parseServeArgs(argv) {
       autostart = raw
     } else if (Object.hasOwn(MODE_FLAGS, a)) {
       const m = MODE_FLAGS[a]
-      if (mode !== 'serve' && mode !== m) return { error: `${FLAG_OF[mode]} and ${a} are separate commands; pass one` }
+      if (mode !== 'serve' && mode !== m) return { error: `${FLAG_OF[mode] ?? mode} and ${a} are separate commands; pass one` }
       mode = m
     } else if (a === '--help' || a === '-h') help = true
     else if (a.startsWith(CHILD_FLAG)) child = a.slice(CHILD_FLAG.length)
@@ -92,6 +120,8 @@ export function parseServeArgs(argv) {
     } else return { error: `unknown option for serve: ${a}\n\n${SERVE_HELP}` }
   }
   if (help) return { mode: 'help', port }
+  if (pair !== null && mode !== 'connection') return { error: '--pair goes with --connection' }
+  if (mode === 'revoke') return port !== null ? { error: '--revoke takes no --port' } : { mode, port, revoke }
   if (from !== null && mode !== 'serve' && mode !== 'detach') return { error: `--from goes with \`centralu serve\` and --detach, which start a host; not with ${FLAG_OF[mode]}` }
   if (child !== null) {
     if (mode !== 'serve') return { error: `${CHILD_FLAG.slice(0, -1)} is how --detach starts serve, not an option of ${FLAG_OF[mode]}` }
@@ -106,7 +136,7 @@ export function parseServeArgs(argv) {
     if (port !== null) return { error: '--autostart takes no --port: the entry it writes starts serve on the port serve recorded' }
     return { mode, port, autostart }
   }
-  return { mode, port, ...(from !== null ? { from } : {}) }
+  return { mode, port, ...(from !== null ? { from } : {}), ...(pair !== null ? { pair } : {}) }
 }
 
 function parsePort(raw) {

package/bin/serve-detach.mjs

@@ -270,7 +270,8 @@ export async function runDetachedChild({ spec, ...opts }) {
  *
  * A stop that went through is remembered in the data folder (`markStopped`, #1143), so a linked hub does not start the
  * host again by itself; the next host that starts here removes the mark. Not for a hub's own stop, which starts the
- * host again itself (an update, a rollback): the hub runs it with `CENTRALU_STOP_BY=hub` (links/tunnel.ts `stopCommand`)
+ * host again itself (an update, a rollback): the hub runs it with `CENTRALU_STOP_BY=hub` (links/tunnel.ts `stopCommand`).
+ * With `CENTRALU_STOP_FOR=update` too (#1618), the host is asked to list the turns it ends, which the next host continues
  */
 export async function runStop({
   env,
@@ -283,7 +284,7 @@ export async function runStop({
   write = (line) => process.stdout.write(line),
 }) {
   const dataDir = serveDataDir(env, home)
-  const stopped = await stopServedHost({ dataDir, entry, platform, timeoutMs, graceMs, kill })
+  const stopped = await stopServedHost({ dataDir, entry, platform, forUpdate: env.CENTRALU_STOP_FOR === 'update', timeoutMs, graceMs, kill })
   if (stopped.ok && env.CENTRALU_STOP_BY !== 'hub') markStopped(dataDir, 'stop')
   return answerLine(write, 'stop', stopped)
 }

package/bin/serve-files.mjs

@@ -1,24 +1,50 @@
 /**
- * The files `centralu serve` keeps in the data folder: the token and port (serve.json, private to the
- * user), the running launcher's pid (serve.pid), and the host's own lock (host.lock), read to tell a
- * live host of this folder from a stale pid.
+ * The files `centralu serve` keeps in the data folder: the host's key, the verifiers of the full credentials and the
+ * port (serve.json, private to the user), the running launcher's pid (serve.pid), and the host's own lock (host.lock),
+ * read to tell a live host of this folder from a stale pid.
  */
 import { execFileSync } from 'node:child_process'
-import { randomBytes } from 'node:crypto'
-import { chmodSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync, closeSync } from 'node:fs'
+import { createHash, createHmac, randomBytes } from 'node:crypto'
+import { chmodSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync, closeSync } from 'node:fs'
 import { join } from 'node:path'
 import { isAlive, renameRetrying, replaceFile, sleepSync } from './serve-util.mjs'
+import { CREDENTIAL_ID_RE, PAIR_LABEL_RE } from './serve-args.mjs'
 
 /**
- * The file in the data folder that holds the token and the port, mode 0600.
+ * The file in the data folder that holds the host's key, the full credentials' verifiers and the port, mode 0600.
  *
- * The token is generated once, the first time either `serve` or `serve --connection` runs, and kept:
- * the client stores it (in the OS secret store) and has to find the same one after the host
- * restarts. The port is the one the last `serve` actually listened on, which is how
- * `--connection`, a separate process, learns a `--port` given to `serve` in a systemd unit.
+ * Since #1405 (version 2) it holds **no credential that opens the host whole**:
+ *
+ * - `key`: 32 random bytes the host derives what it hands out from (the limited credential `--connection` prints, a
+ *   Codex bridge's, the proof of a launcher's probe). With it a process of this user gets the limited credential;
+ *   it is never a full one (a hello with it is refused as full).
+ * - `full`: one entry per full credential, `{ id, label, verifier, created }`, the verifier being the SHA-256 of the
+ *   credential. The credential itself is printed once, to whoever asked for it (`--pair`: a hub at each link,
+ *   `--window` for the person's own window, which the desktop app runs on Windows and which runs on every OS), and written nowhere. The host checks a hello against these,
+ *   read again at each hello, so a pairing or a revocation applies at once.
+ * - `legacyHostToken`: only while the installed host is from before verifiers (a rollback): the one token such a
+ *   host knows, given to it and to the hub that pairs, as before #1405.
+ *
+ * The port is the one the last `serve` actually listened on, which is how `--connection`, a separate process, learns a
+ * `--port` given to `serve` in a systemd unit. A version 1 file (`{ token, port }`) is moved to version 2 on first
+ * use: its token becomes a full credential labelled `legacy` (a hub or window still holding it keeps working), which the
+ * next pairing removes.
  */
 export const SERVE_STATE_FILE = 'serve.json'
 
+/** The label of the full credential a version 1 file's token became; removed by the next pairing */
+export const LEGACY_LABEL = 'legacy'
+
+/** A full credential's verifier: the SHA-256 of it, as hex (the host's `serve-credentials.ts` compares the same) */
+export function verifierOf(credential) {
+  return createHash('sha256').update(credential).digest('hex')
+}
+
+/** The limited credential the host derives from `key` (#1405, the host's `transport/limited-token.ts`) */
+export function limitedOf(key) {
+  return `ccl1:${createHmac('sha256', key).update('centralu limited token v1').digest('base64url')}`
+}
+
 /** What a detached serve writes: its own lines, and the host's until it is ready (host.log has the rest) */
 export const SERVE_LOG_FILE = 'serve.log'
 
@@ -119,16 +145,45 @@ export function readServeState(dataDir, { tries = 5, sleep = sleepSync } = {}) {
   }
 }
 
+/**
+ * The state as the launcher uses it. `token` is the credential the launcher's own probes say hello with, and
+ * `proofKey` what the host proves with to them: the limited credential and the key for version 2, the token for a
+ * version 1 file not moved yet.
+ */
 function parseServeState(raw) {
   try {
     const v = JSON.parse(raw)
+    const port = Number.isInteger(v?.port) && v.port >= 1 && v.port <= 65535 ? v.port : null
+    if (v?.v === 2) {
+      if (typeof v.key !== 'string' || v.key.length < 32) return null
+      // Exactly what the host takes (serve-credentials.ts `isListedEntry`): an entry of another shape is dropped here, so
+      // the next write leaves it out too, and the host refuses it meanwhile
+      const full = (Array.isArray(v.full) ? v.full : []).filter((e) => isListedEntry(e)).map((e) => ({ id: e.id, label: e.label, verifier: e.verifier, created: Number.isFinite(e.created) ? e.created : 0, ...(PAIRED_VIA.includes(e.via) ? { via: e.via } : {}), ...(e.replaced === true ? { replaced: true } : {}) }))
+      const legacyHostToken = typeof v.legacyHostToken === 'string' && v.legacyHostToken.length >= 32 ? v.legacyHostToken : null
+      return { v: 2, key: v.key, port, full, legacyHostToken, token: limitedOf(v.key), proofKey: v.key }
+    }
     if (typeof v?.token !== 'string' || v.token.length < 32) return null
-    return { token: v.token, port: Number.isInteger(v.port) && v.port >= 1 && v.port <= 65535 ? v.port : null }
+    return { v: 1, token: v.token, proofKey: v.token, port, key: null, full: [], legacyHostToken: null }
   } catch {
     return null
   }
 }
 
+/** An entry the launcher lists, `--revoke` takes and the host accepts: an 8-hex id, a label `--pair` takes, a hex verifier */
+export function isListedEntry(e) {
+  return typeof e?.id === 'string' && CREDENTIAL_ID_RE.test(e.id) && typeof e.label === 'string' && PAIR_LABEL_RE.test(e.label) && typeof e.verifier === 'string' && /^[0-9a-f]{64}$/.test(e.verifier)
+}
+
+/** What version 2 writes for a state */
+function stateFile(state) {
+  return { v: 2, key: state.key, port: state.port, full: state.full, ...(state.legacyHostToken ? { legacyHostToken: state.legacyHostToken } : {}) }
+}
+
+/** A new full credential and its id */
+function mint() {
+  return { token: randomBytes(32).toString('base64url'), id: randomBytes(4).toString('hex') }
+}
+
 /**
  * The state, created on first use. Never replaces a token that is already there.
  *
@@ -137,41 +192,274 @@ function parseServeState(raw) {
  * that exists but cannot be read as state is refused rather than overwritten: it may be a token
  * the client already holds, and a silent new one would lock that client out with "bad token".
  */
-export function ensureServeState(dataDir, platform = process.platform) {
+export function ensureServeState(dataDir, platform = process.platform, now = Date.now()) {
   mkdirSync(dataDir, { recursive: true })
   const file = join(dataDir, SERVE_STATE_FILE)
   if (!existsSync(file)) {
-    const token = randomBytes(32).toString('base64url')
     try {
-      writePrivate(file, { v: 1, token, port: null }, 'wx')
+      writePrivate(file, { v: 2, key: randomBytes(32).toString('base64url'), port: null, full: [] }, 'wx')
     } catch (e) {
       if (e?.code !== 'EEXIST') throw e
     }
   }
-  const state = readServeState(dataDir)
-  if (!state) throw new Error(`${file} exists but is not a serve state file. Move it aside and run again.`)
+  let state = readServeState(dataDir)
+  if (!state) throw noState(file)
+  // A version 1 file (#1405): its token becomes a full credential no longer written down, and a new key is drawn
+  if (state.v === 1) {
+    state = changeServeState(dataDir, (s) =>
+      s.v === 1
+        ? { v: 2, key: randomBytes(32).toString('base64url'), port: s.port, full: [{ id: randomBytes(4).toString('hex'), label: LEGACY_LABEL, verifier: verifierOf(s.token), created: now }], legacyHostToken: null }
+        : s,
+      platform,
+    )
+  }
   keepPrivate(file, platform)
   return state
 }
 
-/** Writes the port `serve` listened on, keeping the token. Atomic: a temp file renamed over it */
-export function recordServePort(dataDir, port, platform = process.platform) {
+/**
+ * Why serve.json gives no state (#1405 review): a file this user may not read is said as that, with what makes it
+ * readable again. Moving it aside, the advice for a file that is not a state file, would lock out every hub and window
+ * that holds a credential it names.
+ */
+export function noState(file, read = readFileSync) {
+  try {
+    read(file)
+  } catch (e) {
+    if (e?.code === 'EACCES' || e?.code === 'EPERM') {
+      return new Error(`${file} cannot be read by this user (${e.code}). Give this user read and write access to it again (on Linux and macOS: chmod 600 ${file}) and run again; do not move it aside.`)
+    }
+    if (e?.code === 'ENOENT') return new Error(`${file} is missing`)
+  }
+  return new Error(`${file} exists but is not a serve state file. Move it aside and run again.`)
+}
+
+/** How long a held `serve.json.lock` is waited on before it counts as a crashed writer's (`changeServeState`) */
+export const STATE_LOCK_STALE_MS = 10_000
+
+/**
+ * How long before `STATE_LOCK_STALE_MS` a writer stops trying to write (#1405 review): the time it leaves itself
+ * for the rename, so that a rename it starts lands before any waiter may count its lock as stale
+ */
+export const STATE_LOCK_MARGIN_MS = 2_000
+
+/**
+ * Reads the state, changes it with `change` and writes it back, under a lock (`serve.json.lock`) so two changes at once
+ * (a hub pairing while a window starts) do not lose one another. Returns the state written.
+ *
+ * - A lock whose time is more than `STATE_LOCK_STALE_MS` from now, either way, is a crashed writer's and is taken over.
+ *   Either way (#1405 review): a lock dated ahead of now (a crashed writer, then the clock set back) blocked every
+ *   `--pair` and `--revoke` for as long as it was ahead, so a hub could not link.
+ * - The lock holds a nonce of its writer's, and the writer reads it back before each try of the rename that replaces
+ *   the file: a writer stalled past the 10 s, whose lock another took over meanwhile, writes nothing (#1405 review),
+ *   rather than a state it computed before a `--revoke` that came in between. It throws, and whoever asked tries again
+ *   (a hub at its next link attempt, a person by running it again).
+ * - A writer also writes only within `STATE_LOCK_STALE_MS - STATE_LOCK_MARGIN_MS` of taking its lock, by this
+ *   process's own clock, which a clock set back does not stretch (#1405 review): on Windows a rename is tried again
+ *   for up to 5 s while a reader holds the file, and a try seconds after the read-back could land after another writer
+ *   took the lock over and wrote. Its last try is then at least 2 s before any waiter may take the lock over.
+ * - Taking over a stale lock, and removing its own at the end, first move the lock aside under a name of this
+ *   writer's and look at what was moved: a fresh lock, or another writer's, is put back (`releaseLock`). Before, two
+ *   waiters taking over one stale lock at once could remove the other's fresh lock, and a writer's end could remove the
+ *   lock of one that took it over between its read-back and its removal.
+ *
+ * What is left: a writer suspended for over 2 s between its last read-back and the rename right after it; a
+ * system clock set forward by more than 10 s while a writer holds the lock, which makes its lock look stale to a
+ * waiter; and the moment a lock is moved aside to be looked at, during which a third writer may create one and read
+ * the state while the lock's owner, past its read-back, renames (on a file system without hard links the moved lock is
+ * not put back at all, and its owner's next read-back refuses). No lock file can close these.
+ */
+export function changeServeState(dataDir, change, platform = process.platform, { sleep = sleepSync, nowMs = Date.now, clock = () => performance.now(), read = readFileSync } = {}) {
   const file = join(dataDir, SERVE_STATE_FILE)
-  const state = readServeState(dataDir)
-  if (!state) throw new Error(`${file} is missing or unreadable`)
-  if (state.port === port) return
-  replacePrivate(file, { v: 1, token: state.token, port }, platform)
+  const lock = `${file}.lock`
+  const mine = randomBytes(8).toString('hex')
+  for (let i = 0; ; i++) {
+    try {
+      const fd = openSync(lock, 'wx', 0o600)
+      try {
+        writeSync(fd, mine)
+      } finally {
+        closeSync(fd)
+      }
+      break
+    } catch (e) {
+      if (e?.code !== 'EEXIST') throw e
+      try {
+        if (Math.abs(nowMs() - statSync(lock).mtimeMs) > STATE_LOCK_STALE_MS) takeOverStale(lock, mine, nowMs)
+      } catch {
+        // gone meanwhile: try again
+      }
+      // Past the 10 s after which a lock counts as a crashed writer's, so a waiter takes it over rather than giving up first
+      if (i >= 480) throw new Error(`${lock} is held by another serve; try again`)
+      sleep(25)
+    }
+  }
+  const took = clock()
+  const held = () => {
+    try {
+      return read(lock, 'utf8') === mine
+    } catch {
+      return false
+    }
+  }
+  // Whether this writer may still write: within its time, and the lock still its own
+  const mayWrite = () => {
+    if (clock() - took >= STATE_LOCK_STALE_MS - STATE_LOCK_MARGIN_MS) return new Error(`${lock} was held too long by this serve to write safely; nothing was written, try again`)
+    if (!held()) return new Error(`${lock} was taken over while this serve held it; nothing was written, try again`)
+    return null
+  }
+  try {
+    const before = readServeState(dataDir)
+    if (!before) throw noState(file)
+    const after = change(before)
+    if (after !== before) {
+      const refusal = mayWrite()
+      if (refusal) throw refusal
+      replacePrivate(file, stateFile(after), platform, { mayTry: mayWrite })
+    }
+    // What was written, as a reader reads it: never null once written
+    return after !== before ? parseServeState(JSON.stringify(stateFile(after))) : before
+  } finally {
+    // Only its own: a lock another writer took over is that writer's to keep
+    releaseLock(lock, mine, { read })
+  }
+}
+
+/**
+ * Removes `lock` if it is `mine` (#1405 review): moved aside under a name of this writer's first, so what is looked at
+ * is what is removed, and put back when it was another writer's. Reading it and then removing it by name could remove
+ * a lock another writer took over in between. Never throws: a lock left behind goes stale and is taken over.
+ */
+export function releaseLock(lock, mine, { read = readFileSync, rename = renameSync, link = linkSync, rm = rmSync } = {}) {
+  const aside = `${lock}.${mine}.release`
+  try {
+    renameRetrying(lock, aside, { rename, budgetMs: 1_000 })
+  } catch {
+    // not there (taken over and removed), or held open past the retries: nothing of this writer's to remove now
+    return
+  }
+  let found = null
+  try {
+    found = read(aside, 'utf8')
+  } catch {
+    // unreadable (a scanner on Windows): it may be another writer's, so it is put back; if it was this one's, it goes stale
+  }
+  if (found !== mine) putBack(aside, lock, link)
+  try {
+    rm(aside, { force: true })
+  } catch {
+    // a stray file beside the lock, nothing a writer reads
+  }
+}
+
+/**
+ * Takes over a lock that looked stale (`changeServeState`): moved aside first, and put back when what was moved is not
+ * stale after all (another waiter's fresh lock, taken over a moment before). The caller then creates its own
+ */
+function takeOverStale(lock, mine, nowMs) {
+  const aside = `${lock}.${mine}.stale`
+  renameSync(lock, aside)
+  let stale = true
+  try {
+    stale = Math.abs(nowMs() - statSync(aside).mtimeMs) > STATE_LOCK_STALE_MS
+  } catch {
+    // gone: nothing to put back
+  }
+  if (!stale) putBack(aside, lock, linkSync)
+  rmSync(aside, { force: true })
+}
+
+/** Puts a moved lock back where it was, unless another writer created one there since (a hard link never replaces) */
+function putBack(aside, lock, link) {
+  try {
+    link(aside, lock)
+  } catch {
+    // another holds the lock by now, or links are not possible here: that writer's read-back sees it is not its own
+  }
+}
+
+/**
+ * How a full credential was asked for, kept on its entry as `via` (#1405 review): `pair` (`--connection --pair`, a
+ * hub's at each link or any program's), `window` (`--window`, the person's window on Windows at each start), `handover`
+ * (the launcher's own, for one `host.handover` call and withdrawn right after)
+ */
+export const PAIRED_VIA = ['pair', 'window', 'handover']
+
+/**
+ * A new full credential for `label` (#1405): written as its verifier only, and returned once. One label holds one
+ * credential: a hub pairing again (each link does) replaces its own, and `window` the window's. The `legacy` one a
+ * version 1 file left goes with a hub's or the window's pairing: whoever held it was one of the two, which pairs now.
+ * `via` is how it was asked for (`PAIRED_VIA`). Returns `{ token, id, state }`.
+ *
+ * `replaced` (#1405 review): set on the new entry only when the one of its label it takes the place of was asked for
+ * another way, or the file does not say how. The window pairing again at each start, and a hub at each link, are the
+ * same pairer as before and are not marked: marked at every routine pairing, the flag meant nothing. A `--pair window`
+ * taking the window's place, or the window's next start taking that one's, is marked. What this cannot tell is two
+ * askers of the same way: a program's `--pair hub:<name>-<key>` against that hub's own. The hub's row tells that one
+ * by itself (`hubsName`, and its own credential gone), docs/security-boundaries.md.
+ */
+export function pairServe(dataDir, label, platform = process.platform, now = Date.now(), via = 'pair') {
+  ensureServeState(dataDir, platform, now)
+  const { token, id } = mint()
+  const state = changeServeState(dataDir, (s) => ({
+    ...s,
+    /*
+     * A hub's or the window's pairing removes the `legacy` one (#1405 review): whoever held it was a hub or the window
+     * of before #1405, each of which pairs now, so on a machine no hub links to it does not outlive the window's next
+     * start. Any other label leaves it: a program's own `--pair` does not cut off a hub that has not paired yet
+     */
+    full: [
+      ...s.full.filter((e) => e.label !== label && !(takesLegacyPlace(label) && e.label === LEGACY_LABEL)),
+      { id, label, verifier: verifierOf(token), created: now, via, ...(s.full.some((e) => e.label === label && e.via !== via) ? { replaced: true } : {}) },
+    ],
+  }), platform)
+  return { token, id, state }
+}
+
+/** The pairings that stand for whoever held a version 1 file's token: a hub's and the window's (`pairServe`) */
+function takesLegacyPlace(label) {
+  return label === 'window' || label.startsWith('hub:')
+}
+
+/** Removes the full credential `id`; true when there was one. A hello with it is refused from then on */
+export function revokeServe(dataDir, id, platform = process.platform) {
+  let found = false
+  changeServeState(dataDir, (s) => {
+    found = s.full.some((e) => e.id === id)
+    return found ? { ...s, full: s.full.filter((e) => e.id !== id) } : s
+  }, platform)
+  return found
+}
+
+/**
+ * The one token an installed host from before verifiers knows (a rollback): kept in the state while such a host is
+ * installed, given to it and to a hub that pairs. Created once; returns it.
+ */
+export function legacyHostTokenOf(dataDir, platform = process.platform) {
+  const state = ensureServeState(dataDir, platform)
+  if (state.legacyHostToken) return state.legacyHostToken
+  const token = randomBytes(32).toString('base64url')
+  return changeServeState(dataDir, (s) => (s.legacyHostToken ? s : { ...s, legacyHostToken: token }), platform).legacyHostToken
+}
+
+/** A host of today runs: the token kept for an older one is not kept any longer */
+export function dropLegacyHostToken(dataDir, platform = process.platform) {
+  changeServeState(dataDir, (s) => (s.legacyHostToken ? { ...s, legacyHostToken: null } : s), platform)
+}
+
+/** Writes the port `serve` listened on, keeping the rest. Atomic: a temp file renamed over it */
+export function recordServePort(dataDir, port, platform = process.platform) {
+  changeServeState(dataDir, (s) => (s.port === port ? s : { ...s, port }), platform)
 }
 
 /**
- * A new token, keeping the port. Only when the person asks (`--rotate-token`): every client that
- * stored the old one has to fetch the new one with `--connection`, and a serve already running
- * keeps answering to the old one until it restarts.
+ * A new key, and no full credential, keeping the port. Only when the person asks (`--rotate-token`): every hub pairs
+ * again at its next link, the window at its next start, and a serve already running keeps its old key (what it hands
+ * out) until it restarts, while the full credentials end at once.
  */
 export function rotateServeToken(dataDir, platform = process.platform) {
-  const before = ensureServeState(dataDir, platform)
-  replacePrivate(join(dataDir, SERVE_STATE_FILE), { v: 1, token: randomBytes(32).toString('base64url'), port: before.port }, platform)
-  return readServeState(dataDir)
+  ensureServeState(dataDir, platform)
+  return changeServeState(dataDir, (s) => ({ ...s, key: randomBytes(32).toString('base64url'), full: [], legacyHostToken: null }), platform)
 }
 
 /**
@@ -187,9 +475,9 @@ function writePrivate(file, value, flag) {
   }
 }
 
-/** Replaces a private file whole (`replaceFile`), created 0600 as `writePrivate` creates one */
-function replacePrivate(file, value, platform) {
-  replaceFile(file, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: 'wx' })
+/** Replaces a private file whole (`replaceFile`), created 0600 as `writePrivate` creates one; `rename` goes to `renameRetrying` */
+function replacePrivate(file, value, platform, rename = {}) {
+  replaceFile(file, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: 'wx', ...rename })
   keepPrivate(file, platform)
 }
 

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 } from './serve-files.mjs'
+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 } from './serve-host.mjs'
+import { protocolVersionOf, hostProvesOf, probeHost, askHostToStop, askHostRpc, ownCredentials, takesVerifiers } from './serve-host.mjs'
 import { ownLogon } from './serve-windows.mjs'
 import { isAlive, say, sleep, waitUntil } from './serve-util.mjs'
 
@@ -23,15 +23,19 @@ import { isAlive, say, sleep, waitUntil } from './serve-util.mjs'
  * with this folder's token: a stale pid is never signalled.
  *
  * `{ 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.
+ * when nothing runs there, and `{ ok: false, busy: true }` says it did not. `forUpdate` (#1618): a hub's update stops it, and
+ * the host writes the turns it ends for the next one (`host.stop { forUpdate }`); a host that does not take the request is
+ * ended as any is, and lists nothing.
  */
-export async function stopServedHost({ dataDir, entry, platform = process.platform, ifIdle = false, timeoutMs = 30_000, graceMs = 15_000, kill = (pid, sig) => process.kill(pid, sig) }) {
+export async function stopServedHost({ dataDir, entry, platform = process.platform, ifIdle = false, forUpdate = false, timeoutMs = 30_000, graceMs = 15_000, kill = (pid, sig) => process.kill(pid, sig) }) {
   const state = readServeState(dataDir)
   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)
-  const probe = () => probeHost({ port, token: state.token, protocolVersion: installed, prove })
+  // 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 first = await probe()
   if (!heldHere(first, dataDir)) return { ok: true, wasRunning: false, message: `centralu serve is not running for ${dataDir}` }
 
@@ -41,8 +45,8 @@ export async function stopServedHost({ dataDir, entry, platform = process.platfo
   const launcherPid = launcher && hostPid && launcher.hostPid === hostPid ? launcher.pid : null
   const down = async () => !(await probe()).running && !(hostPid && isAlive(hostPid))
 
-  let asked = await askHostToStop({ port, token: state.token, protocolVersion: first.protocolVersion ?? installed, prove, ifIdle })
-  if (!asked.ok && asked.protocolVersion !== undefined) asked = await askHostToStop({ port, token: state.token, protocolVersion: asked.protocolVersion, prove, ifIdle })
+  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'
@@ -124,13 +128,26 @@ export async function moveIntoSignIn({
   const port = state.port ?? DEFAULT_SERVE_PORT
   const prove = hostProvesOf(entry)
   const protocolVersion = existing.protocolVersion ?? protocolVersionOf(entry) ?? 0
-  const report = (handover) => (tell ?? ((h) => askHostRpc({ port, token: state.token, protocolVersion, prove, method: 'host.handover', params: { handover: h } })))(handover)
+  const own = ownCredentials(state, entry)
+  /*
+   * `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
+   */
+  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 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, token: state.token, protocolVersion, prove })).running) return true
+    if (!(await probeHost({ port, ...own, protocolVersion, prove })).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

@@ -34,17 +34,27 @@ 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, version, protocolVersion, dataDir, hostRunning, install, autostart, detach, proof, stopped }) {
+export function connectionLine({ port, token, credential, limited, others, version, protocolVersion, dataDir, hostRunning, install, autostart, detach, proof, stopped }) {
   /*
    * 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
    * desktop window on Windows uses this serve's host through `--window` only when it is listed (#1223 review)
    */
-  const takes = ['from', 'window']
+  /*
+   * `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']
   return JSON.stringify({
     v: 1,
     port,
-    token,
+    // A full credential only to `--pair` (#1405), with its id for the proof; an older serve always printed its token
+    ...(token ? { token } : {}),
+    ...(credential ? { credential } : {}),
+    // What a process of this user gets without pairing (#1405): everyday calls only
+    ...(limited ? { limited } : {}),
+    // The full credentials this folder holds besides the one just paired, as `{ id, label, created }` (#1405)
+    ...(others ? { others } : {}),
     version,
     protocolVersion,
     dataDir,
@@ -113,9 +123,14 @@ 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 }) {
+export function hostEnv(env, { dataDir, version, hostDir, legacyToken, 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', 'CENTRALU_MANAGED', 'CENTRALU_STARTED_FROM', 'CC_SERVE_FROM', 'CC_STARTED_BY']) delete out[k]
+  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`)
+   */
+  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
   if (from) out.CC_SERVE_FROM = JSON.stringify(from)
   out.CC_DATA_DIR = dataDir
@@ -146,6 +161,37 @@ 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)
+ */
+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.
  *
@@ -228,7 +274,7 @@ function proofOf(token, nonce) {
  * `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, protocolVersion, prove, WebSocketImpl, on }) {
+function helloSocket({ port, token, proofKey, protocolVersion, prove, WebSocketImpl, on }) {
   const ws = new WebSocketImpl(`ws://127.0.0.1:${port}`)
   const nonce = prove ? randomBytes(24).toString('base64url') : null
   // Proving only once the socket is open: a port where nothing listens is gone, not unproven
@@ -248,7 +294,8 @@ function helloSocket({ port, token, protocolVersion, prove, WebSocketImpl, on })
     }
     if (proving) {
       proving = false
-      if (m?.kind === 'proof' && m.nonce === nonce && m.mac === proofOf(token, nonce)) return hello()
+      // A host that takes verifiers proves with its key, which is not the credential this says hello with (#1405)
+      if (m?.kind === 'proof' && m.nonce === nonce && m.mac === proofOf(proofKey ?? token, nonce)) return hello()
       return on.unproven()
     }
     if (m) on.message(m, ws)
@@ -269,10 +316,10 @@ function helloSocket({ port, token, protocolVersion, prove, WebSocketImpl, on })
  * (`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, protocolVersion, prove = false, timeoutMs = 2000, WebSocketImpl = globalThis.WebSocket }) {
+export function probeHost({ port, token, proofKey, protocolVersion, prove = false, timeoutMs = 2000, WebSocketImpl = globalThis.WebSocket }) {
   if (typeof WebSocketImpl !== 'function') return tcpProbe(port, timeoutMs)
   return helloExchange({
-    port, token, protocolVersion, prove, WebSocketImpl, timeoutMs,
+    port, token, proofKey, protocolVersion, prove, WebSocketImpl, timeoutMs,
     timedOut: { running: false },
     failed: () => ({ running: false }),
     on: (done) => ({
@@ -344,10 +391,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, protocolVersion, prove = false, method, params = {}, timeoutMs = 5000, WebSocketImpl = globalThis.WebSocket }) {
+export function askHostRpc({ port, token, proofKey, protocolVersion, prove = false, method, params = {}, timeoutMs = 5000, WebSocketImpl = globalThis.WebSocket }) {
   if (typeof WebSocketImpl !== 'function') return Promise.resolve(null)
   return helloExchange({
-    port, token, protocolVersion, prove, WebSocketImpl, timeoutMs,
+    port, token, proofKey, protocolVersion, prove, WebSocketImpl, timeoutMs,
     timedOut: null,
     failed: () => null,
     on: (done) => ({
@@ -367,20 +414,20 @@ export function askHostRpc({ port, token, protocolVersion, prove = false, method
  * `{ ok: true }` once the host took it, `{ ok: false, message, protocolVersion? }` otherwise; the
  * last names the host's protocol when the hello was refused for it, so the caller can ask again.
  * `ifIdle` (#1224): only if nothing runs there, checked and acted on by the host in one step; `{ ok: false, busy: true }`
- * when something does.
+ * 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, protocolVersion, prove = false, ifIdle = false, timeoutMs = 5000, WebSocketImpl = globalThis.WebSocket }) {
+export function askHostToStop({ port, token, proofKey, protocolVersion, prove = false, 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, protocolVersion, prove, WebSocketImpl, timeoutMs,
+    port, token, proofKey, protocolVersion, prove, WebSocketImpl, timeoutMs,
     timedOut: { ok: false, message: 'no answer in time' },
     failed: (e) => ({ ok: false, message: e.message }),
     on: (done) => ({
       unproven: () => done({ ok: false, message: 'what answers on the port did not prove it holds the token' }),
       gone: () => done({ ok: false, message: 'the connection closed' }),
       message: (m, ws) => {
-        if (m.kind === 'hello_ok') ws.send(JSON.stringify({ kind: 'rpc', id: 'stop', method: 'host.stop', params: ifIdle ? { ifIdle: true } : {} }))
+        if (m.kind === 'hello_ok') ws.send(JSON.stringify({ kind: 'rpc', id: 'stop', method: 'host.stop', params: { ...(ifIdle ? { ifIdle: true } : {}), ...(forUpdate ? { forUpdate: true } : {}) } }))
         else if (m.kind === 'res' && m.id === 'stop' && m.ok && m.result?.ok === false) {
           // `ifIdle` and something runs there (#1224): nothing was changed
           done({ ok: false, busy: true, message: 'it has work running', activity: m.result.busy ?? null, calls: m.result.calls ?? 0 })

package/bin/serve-run.mjs

@@ -4,10 +4,10 @@ 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 } from './serve-files.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 { 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 } from './serve-host.mjs'
+import { protocolVersionOf, connectionLine, hostEnv, hostCommand, readyPort, hostProvesOf, probeHost, serveFrom, takesTokenOnStdin, tokenLine, keyLine, takesVerifiers, ownCredentials } from './serve-host.mjs'
 import { autostartInfo } from './serve-autostart.mjs'
 import { moveIntoSignIn } from './serve-handover.mjs'
 
@@ -22,22 +22,34 @@ export function serveFolder({ env, home, cliPath, platform = process.platform })
   return { dataDir, state }
 }
 
-/** What `--connection` answers, as fields: the running host's versions when one answers, else the installed ones */
-export async function describe({ env, dataDir, state, entry, version }) {
+/**
+ * What `--connection` answers, as fields: the running host's versions when one answers, else the installed ones.
+ *
+ * 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`).
+ * `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 }) {
   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 probe = await probeHost({ port, token: state.token, protocolVersion: installed, prove: proof })
+  const own = ownCredentials(state, entry)
+  const probe = await probeHost({ port, ...own, protocolVersion: installed, prove: proof })
   const protocolVersion = (probe.running ? probe.protocolVersion : undefined) ?? installed
   if (protocolVersion === null) return null
   const hostRunning = heldHere(probe, dataDir)
   // 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,
-    token: state.token,
+    ...(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 } : {}) })),
     version: (probe.running ? probe.version : undefined) ?? version,
     protocolVersion,
     dataDir,
@@ -52,9 +64,23 @@ export async function describe({ env, dataDir, state, entry, version }) {
  * `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 }) {
-  const { dataDir, state } = serveFolder({ env, home, cliPath })
-  const d = await describe({ env, dataDir, state, entry, version })
+export async function printConnection({ env, home, entry, version, cliPath, pair = null }) {
+  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`)
+    } else {
+      paired = { token: legacyHostTokenOf(dataDir), id: null }
+    }
+  }
+  const d = await describe({ env, dataDir, state, entry, version, paired })
   if (!d) {
     say(`cannot read the protocol version of the host at ${entry}`)
     return 1
@@ -82,7 +108,7 @@ 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, token: state.token, protocolVersion, prove: hostProvesOf(entry) })
+  const existing = await probeHost({ port: recorded, ...ownCredentials(state, entry), protocolVersion, prove: hostProvesOf(entry) })
   // 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 }))) {
     const pid = lockHolderPid(dataDir)
@@ -104,14 +130,28 @@ 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
+   */
+  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, { dataDir, version, hostDir: dirname(entry), from: serveFrom(env, from), ...(onStdin ? {} : { legacyToken: state.token }) }),
+    env: hostEnv(env, {
+      dataDir,
+      version,
+      hostDir: dirname(entry),
+      from: serveFrom(env, from),
+      ...(verifiers ? { serveState: join(dataDir, SERVE_STATE_FILE) } : {}),
+      ...(onStdin ? {} : { legacyToken: legacy ?? state.token }),
+    }),
     detached: plan.detached,
     windowsHide: true,
   })
-  // The token, before anything else on the pipe the host watches (#538); stdin stays open for --watch-parent
-  if (onStdin) child.stdin.write(tokenLine(state.token))
+  // 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))
 
   let ready = false
   if (logFd !== null) {
@@ -187,11 +227,26 @@ export async function runServe({ env, home, entry, version, cliPath, port: asked
   })
 }
 
-/** `centralu serve --rotate-token` */
+/** `centralu serve --rotate-token`: a new key, and every full credential withdrawn (#1405) */
 export function rotateToken({ env, home }) {
   const dataDir = serveDataDir(env, home)
   rotateServeToken(dataDir)
-  say(`replaced the token in ${join(dataDir, SERVE_STATE_FILE)}.`)
-  say('A serve that is running keeps the old one until it restarts; clients read the new one with --connection.')
+  say(`replaced the key and withdrew every full credential in ${join(dataDir, SERVE_STATE_FILE)}.`)
+  say('A linked computer pairs again at its next connection, and a window at its next start. A serve that is running keeps its old key until it restarts: the limited credential --connection prints works once it has.')
+  return 0
+}
+
+/** `centralu serve --revoke <id>`: one full credential withdrawn (#1405); its next hello is refused, and the host closes a socket already in with it */
+export function revokeCredential({ env, home, id, write = (line) => process.stdout.write(line) }) {
+  const dataDir = serveDataDir(env, home)
+  const revoked = revokeServe(dataDir, id)
+  // One JSON line on stdout, as every serve command a hub runs prints one: whether there was one to withdraw
+  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.`)
+    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.`)
   return 0
 }

package/bin/serve-util.mjs

@@ -44,10 +44,16 @@ const BUSY_CODES = new Set(['EPERM', 'EBUSY', 'EACCES'])
  * `rename`, tried again for up to `budgetMs` while the system refuses it because someone has the target open (#1041;
  * `retry`: Windows only, `renameWaitsForReaders`). With `retry` off, and for any other error, it is one try. Backs off 10, 20, 40 ... 200 ms between tries; the last
  * error is thrown when the budget is spent.
+ *
+ * `mayTry`, when given, is asked before every try, the first too, and a false answer ends it with its error (#1405
+ * review): a writer under a lock checks there that the lock is still its own, so a retry seconds later cannot land a
+ * write after another writer took the lock over.
  */
-export function renameRetrying(from, to, { retry = renameWaitsForReaders(), rename = renameSync, sleep = sleepSync, budgetMs = 5_000, now = Date.now } = {}) {
+export function renameRetrying(from, to, { retry = renameWaitsForReaders(), rename = renameSync, sleep = sleepSync, budgetMs = 5_000, now = Date.now, mayTry = null } = {}) {
   const t0 = now()
   for (let delay = 10; ; delay = Math.min(delay * 2, 200)) {
+    const refusal = mayTry?.()
+    if (refusal) throw refusal
     try {
       return rename(from, to)
     } catch (e) {

package/bin/serve-window.mjs

@@ -5,9 +5,9 @@
  * lock refuses.
  */
 import { join } from 'node:path'
-import { readServeState } from './serve-files.mjs'
+import { legacyHostTokenOf, pairServe, readServeState } from './serve-files.mjs'
 import { DEFAULT_SERVE_PORT } from './serve-port.mjs'
-import { hostProvesOf, probeHost, protocolVersionOf } from './serve-host.mjs'
+import { hostProvesOf, ownCredentials, probeHost, protocolVersionOf, takesVerifiers } from './serve-host.mjs'
 import { serveFolder } from './serve-run.mjs'
 import { runDetach } from './serve-detach.mjs'
 import { startInSignIn } from './serve-autostart.mjs'
@@ -15,7 +15,10 @@ import { say, sleep } from './serve-util.mjs'
 
 /**
  * Makes sure the folder's serve host runs, then prints the window's ready line, `{"ready":true,"port","token","db"}`
- * (the line a host the window starts prints), and stays until the window goes.
+ * (the line a host the window starts prints), and stays until the window goes. The token is a full credential made for
+ * the window at each start (#1405, `--pair window`'s, replacing the last window's): serve.json keeps only its verifier.
+ * It runs the same on Linux and macOS, though only the Windows app runs it. Residual: any process of this user, on any
+ * OS, can run `--window` too, until it checks its parent (#1417).
  *
  * - No host answers: one is started the way `--detach` starts it, in this Windows sign-in through the scheduled task,
  *   so it outlives the window and the hub's link finds it (`serve --connection`).
@@ -48,7 +51,7 @@ export async function runWindow({
   const protocolVersion = protocolVersionOf(entry) ?? 0
   const probe = () => {
     const state = readServeState(dataDir)
-    return state ? probeHost({ port: state.port ?? DEFAULT_SERVE_PORT, token: state.token, protocolVersion, prove }) : Promise.resolve({ running: false })
+    return state ? probeHost({ port: state.port ?? DEFAULT_SERVE_PORT, ...ownCredentials(state, entry), protocolVersion, prove }) : Promise.resolve({ running: false })
   }
 
   let host = await probe()
@@ -75,8 +78,10 @@ export async function runWindow({
     )
   }
 
+  // The window's own full credential (#1405); an older installed host knows only the token kept for it
+  const token = takesVerifiers(entry) ? pairServe(dataDir, 'window', platform, Date.now(), 'window').token : legacyHostTokenOf(dataDir, platform)
   const state = readServeState(dataDir)
-  write(`${JSON.stringify({ ready: true, port: state.port ?? DEFAULT_SERVE_PORT, token: state.token, db: join(dataDir, 'store.db') })}\n`)
+  write(`${JSON.stringify({ ready: true, port: state.port ?? DEFAULT_SERVE_PORT, token, db: join(dataDir, 'store.db') })}\n`)
 
   return await new Promise((resolve) => {
     let done = false

package/bin/serve.mjs

@@ -24,14 +24,14 @@
  * (`serve-autostart.mjs`), Windows, WSL and PowerShell (`serve-windows.mjs`), and small helpers
  * (`serve-util.mjs`).
  */
-export { SERVE_STATE_FILE, SERVE_LOG_FILE, SERVE_PID_FILE, serveDataDir, readServeState, ensureServeState, recordServePort, rotateServeToken, heldHere, lockHolderIsAlive, processStartTime, lockHolder, lockHolderPid, readServePid, SERVE_STOPPED_FILE, SERVE_LOGS_KEPT, markStopped, readStopped, rotateServeLog } from './serve-files.mjs'
+export { SERVE_STATE_FILE, SERVE_LOG_FILE, SERVE_PID_FILE, serveDataDir, readServeState, ensureServeState, recordServePort, rotateServeToken, pairServe, revokeServe, verifierOf, limitedOf, legacyHostTokenOf, changeServeState, heldHere, lockHolderIsAlive, processStartTime, lockHolder, lockHolderPid, readServePid, SERVE_STOPPED_FILE, SERVE_LOGS_KEPT, markStopped, readStopped, rotateServeLog } from './serve-files.mjs'
 export { detachHow, windowsArg, wmiScript, parseWmiAnswer, wmiBlockedMessage, windowsPowershell, ownLogon } from './serve-windows.mjs'
 export { DEFAULT_SERVE_PORT, SERVE_PORT_TRIES, chooseServePort, listensHere, parseNetstatListening } from './serve-port.mjs'
-export { SERVE_HELP, AUTOSTART_ACTIONS, parseServeArgs } from './serve-args.mjs'
+export { SERVE_HELP, AUTOSTART_ACTIONS, parseServeArgs, PAIR_LABEL_RE, CREDENTIAL_ID_RE } from './serve-args.mjs'
 export { launcherScript, ensureLauncher, remoteLayout, parsePointer, installInfo, managedLauncherScript } from './serve-install.mjs'
-export { protocolVersionOf, connectionLine, hostEnv, hostCommand, readyPort, mismatchServerVersion, hostProvesOf, probeHost, askHostToStop, askHostRpc, serveFrom, takesTokenOnStdin, tokenLine } from './serve-host.mjs'
+export { protocolVersionOf, connectionLine, hostEnv, hostCommand, readyPort, mismatchServerVersion, hostProvesOf, probeHost, askHostToStop, askHostRpc, serveFrom, takesTokenOnStdin, tokenLine, keyLine, takesVerifiers, ownCredentials } from './serve-host.mjs'
 export { stopServedHost, moveIntoSignIn, HANDOVER_WAIT_MS } from './serve-handover.mjs'
 export { runWindow } from './serve-window.mjs'
 export { AUTOSTART_FILE, AUTOSTART_ENV, autostartHow, autostartUnsupported, pathKey, autostartName, autostartLauncher, systemdUnit, taskActionScript, taskScript, parseTaskAnswer, readAutostartMark, autostartInfo, lingerMessage, runAutostart, startInSignIn } from './serve-autostart.mjs'
-export { printConnection, runServe, rotateToken } from './serve-run.mjs'
+export { printConnection, runServe, rotateToken, revokeCredential } from './serve-run.mjs'
 export { CARRIED_ENV, encodeChildSpec, decodeChildSpec, startDetached, runDetach, runDetachedChild, runStop } from './serve-detach.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "centralu",
-  "version": "0.1.0-beta.43",
+  "version": "0.1.0-beta.45",
   "description": "Run, watch and steer several Claude Code and Codex CLI sessions from one window",
   "license": "MIT",
   "author": "ijun17",
@@ -38,9 +38,9 @@
     "win32"
   ],
   "optionalDependencies": {
-    "@centralu/darwin-arm64": "0.1.0-beta.43",
-    "@centralu/linux-arm64": "0.1.0-beta.43",
-    "@centralu/linux-x64": "0.1.0-beta.43",
-    "@centralu/win32-x64": "0.1.0-beta.43"
+    "@centralu/darwin-arm64": "0.1.0-beta.45",
+    "@centralu/linux-arm64": "0.1.0-beta.45",
+    "@centralu/linux-x64": "0.1.0-beta.45",
+    "@centralu/win32-x64": "0.1.0-beta.45"
   }
 }