centralu 0.1.0-beta.44 → 0.1.0-beta.46

package/bin/serve-files.mjs

@@ -1,24 +1,54 @@
 /**
- * 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'
+import { parseLinkPublicKey } from './serve-keys.mjs'
+import { windowsPowershell } from './serve-windows.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.
+ * - `keys` (#1711, docs/plans/key-pairing.md §4.2, additive: still version 2): one entry per hub that paired by key,
+ *   `{ id, label, publicKey, created, via: 'pair-key' }`, the hub's Ed25519 public key. Public: nothing in it opens the
+ *   host. A host from before key pairing ignores it, and a launcher from before drops it at its next write.
+ *
+ * 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. This is the update path for a machine below `MIN_SUPPORTED_VERSION` (#1143): version 2 first
+ * shipped in 0.1.0-beta.45, so the hub's update of an older machine (`serve --detach`) and `npm i -g` run on a version 1 file.
  */
 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 +149,52 @@ 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)
-    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 }
+    const port = Number.isInteger(v?.port) && v.port >= 1 && v.port <= 65535 ? v.port : null
+    if (v?.v !== 2) {
+      // A version 1 file, moved by `ensureServeState`: the update path from below the minimum (#1143)
+      if (typeof v?.token !== 'string' || v.token.length < 32) return null
+      return { v: 1, token: v.token, proofKey: v.token, port, key: null, full: [], keys: [] }
+    }
+    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 } : {}) }))
+    // The same for the hubs' key entries (#1711): one with a key the host refuses (§4.1) is dropped at the next write
+    const keys = (Array.isArray(v.keys) ? v.keys : []).filter((e) => isKeyEntry(e)).map((e) => ({ id: e.id, label: e.label, publicKey: e.publicKey, created: Number.isFinite(e.created) ? e.created : 0, via: 'pair-key', ...(e.replaced === true ? { replaced: true } : {}) }))
+    return { v: 2, key: v.key, port, full, keys, token: limitedOf(v.key), proofKey: v.key }
   } 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)
+}
+
+/** A hub's key entry the launcher lists, `--revoke` takes and the host accepts (#1711): an 8-hex id, a label `--pair` takes, a public key the host takes (§4.1) */
+export function isKeyEntry(e) {
+  return typeof e?.id === 'string' && CREDENTIAL_ID_RE.test(e.id) && typeof e.label === 'string' && PAIR_LABEL_RE.test(e.label) && parseLinkPublicKey(e.publicKey) !== null
+}
+
+/** What version 2 writes for a state; `keys` only when there are any, so a folder no hub paired by key keeps today's file */
+function stateFile(state) {
+  return { v: 2, key: state.key, port: state.port, full: state.full, ...(state.keys?.length ? { keys: state.keys } : {}) }
+}
+
+/** 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 +203,303 @@ 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. Kept as
+  // the update path for a machine below `MIN_SUPPORTED_VERSION` (#1143), whose launcher wrote version 1
+  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 }], keys: [] }
+        : 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:')
+}
+
+/**
+ * The key entry for `label` with `publicKey` (#1711, docs/plans/key-pairing.md §4.2): `--pair-key`'s write. At most one
+ * key entry per label. The same key under the same label keeps its entry and id; another key under it is a new entry
+ * with a new id, marked `replaced`, and the old key entry goes, so a socket in under the old key is closed by the sweep
+ * (which compares id and key). The label's verifier entry is never touched here. Returns `{ entry, state }`.
+ */
+export function pairKeyServe(dataDir, label, publicKey, platform = process.platform, now = Date.now()) {
+  if (!parseLinkPublicKey(publicKey)) throw new Error('A refused public key is never written')
+  ensureServeState(dataDir, platform)
+  let entry = null
+  const state = changeServeState(dataDir, (s) => {
+    const before = s.keys.find((k) => k.label === label)
+    /*
+     * The host takes the first key entry of an id (#1717 review, L2), so one written by hand ahead of the hub's, with its id
+     * and another key, keeps the hub from linking. Such an id is not kept: the entry gets a fresh one, which the line reports.
+     * The same for an id a verifier entry has (#1717 recheck, F1): the host takes no key entry of such an id
+     */
+    const shared = before !== undefined && (s.keys.some((k) => k !== before && k.id === before.id) || s.full.some((e) => e.id === before.id))
+    if (before && before.publicKey === publicKey && !shared) {
+      entry = before
+      return s
+    }
+    entry = { id: freshId(s), label, publicKey, created: now, via: 'pair-key', ...(before ? { replaced: true } : {}) }
+    return { ...s, keys: [...s.keys.filter((k) => k.label !== label), entry] }
+  }, platform)
+  return { entry, state }
+}
+
+/** An entry id no full credential and no key entry of `state` has: a `--revoke <id>` names one entry */
+function freshId(state) {
+  for (;;) {
+    const id = randomBytes(4).toString('hex')
+    if (!state.full.some((e) => e.id === id) && !state.keys.some((k) => k.id === id)) return id
+  }
 }
 
 /**
- * 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.
+ * Removes the verifier entry under `label` (#1711, `--key-paired`): the hub paired by key with this machine before and
+ * now has a key line, so the verifier entry it made under its label is no longer its own. Returns the state written.
+ */
+export function dropVerifierUnder(dataDir, label, platform = process.platform) {
+  return changeServeState(dataDir, (s) => (s.full.some((e) => e.label === label) ? { ...s, full: s.full.filter((e) => e.label !== label) } : s), platform)
+}
+
+/** Removes the full credential or the key entry `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) || s.keys.some((k) => k.id === id)
+    return found ? { ...s, full: s.full.filter((e) => e.id !== id), keys: s.keys.filter((k) => k.id !== id) } : s
+  }, platform)
+  return found
+}
+
+/** 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 key, and no full credential and no key entry, 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, and what it signs with, #1711 §7) 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: [], keys: [] }), platform)
 }
 
 /**
@@ -187,9 +515,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)
 }
 
@@ -223,45 +551,78 @@ export function removeServePid(dataDir, pid) {
 }
 
 /**
- * A probe that did not prove the token, while this data folder's host is alive (`host.lock`): a host from before #838
- * still running after an update. It is running, and is not sent the token; a hub asking it for a proof is refused
- * until it restarts. Without a live lock holder, what answered is not ours.
+ * A probe that did not prove the token, while this data folder's `serve` is alive (`host.lock`): a host still on its old
+ * key after `--rotate-token`. It is running, and is not sent the token; a hub asking it for a proof is refused until it
+ * restarts. Without a live lock holder that `serve` started (`startedByServe`), what answered is not ours: a live holder
+ * the app or the keeper started owns the folder, and whatever sits on the recorded port (a hub's ssh forward, #1722) is
+ * not that holder.
+ *
+ * `portRecorded`: serve.json names the port the probe went to (`state.port != null`). A folder that has none was probed
+ * on the default port, where whatever listens is as likely another host's (a hub's ssh forward to a linked machine's serve
+ * lands there): an unproven answer from it says nothing about this folder, whoever holds the lock.
  */
-export function heldHere(probe, dataDir, startOf = processStartTime) {
+export function heldHere(probe, dataDir, startOf = processStartTime, portRecorded = true) {
   if (probe.running) return true
-  if (!probe.unproven) return false
-  return lockHolderIsAlive(dataDir, startOf)
+  if (!probe.unproven || !portRecorded) return false
+  return lockHolderIsAlive(dataDir, startOf) && startedByServe(dataDir)
+}
+
+/**
+ * Whether the process `host.lock` names is a host `centralu serve` started (#1722): what lets the launcher signal it.
+ * The lock says so itself (`by: 'serve'`, #1223); a lock that names another starter (`app`, `keeper`), or none (a host
+ * started by hand), is not serve's.
+ */
+export function startedByServe(dataDir) {
+  return lockHolder(dataDir)?.by === 'serve'
+}
+
+/** Who `by` in host.lock says started the host, as a phrase (#1223); an absent `by` is most likely the app */
+export function holderWho(by) {
+  return { app: 'the Centralu window on this machine', keeper: "Centralu's keeper on this machine", serve: 'another centralu serve' }[by] ?? 'probably the Centralu app on this machine'
+}
+
+/**
+ * The live process that holds this folder's lock and that `centralu serve` did not start, `{ pid, started, by? }`, or
+ * null (#1722): `--stop` names it rather than signal it. Only named, so a pid that is alive is enough (no start time:
+ * Windows has none), as for the message `serve` itself prints when the lock stops its host.
+ */
+export function foreignHolder(dataDir) {
+  const holder = lockHolder(dataDir)
+  return holder && isAlive(holder.pid) && !startedByServe(dataDir) ? holder : null
 }
 
 /**
  * Whether the process `host.lock` names is the one that wrote it (#838 review): alive, and started when the lock says
  * (`ps -o lstart`, as the host writes it, `instance-lock.ts`). A lock left by a host that died, whose pid another
  * process of the same user now has, names a stranger: counted as running, `--stop` would signal it. A lock without a
- * start time (a host from before #184) or a system without `ps` (Windows) cannot be told apart, so it does not count.
+ * start time and no `at` (its host found no `ps`) cannot be told apart, so it does not count. Windows has no `ps` and its
+ * host records no start time (#1723), only `at`, when it took the folder: the process that wrote the lock was created by
+ * then, and one given its number afterwards was created later. Both times come from one clock and the host writes `at`
+ * 17 ms or more after its process was created, so the slack is one clock tick, for the two readings of it. An `at` in the
+ * future (a clock set back since) proves nothing.
  */
-export function lockHolderIsAlive(dataDir, startOf = processStartTime) {
-  let holder
-  try {
-    holder = parseLockHolder(readFileSync(join(dataDir, 'host.lock'), 'utf8'))
-  } catch {
-    return false
-  }
-  if (!holder || !holder.started || !isAlive(holder.pid)) return false
-  return startOf(holder.pid) === holder.started
+export function lockHolderIsAlive(dataDir, startOf = processStartTime, createdAt = processCreatedAt) {
+  const holder = lockHolder(dataDir)
+  if (!holder || !isAlive(holder.pid)) return false
+  if (holder.started) return startOf(holder.pid) === holder.started
+  if (holder.at === undefined || holder.at > Date.now()) return false
+  const created = createdAt(holder.pid)
+  return created !== null && created <= holder.at + CLOCK_TICK_MS
 }
 
+/** One tick of the Windows clock */
+const CLOCK_TICK_MS = 16
+
 /**
- * host.lock's `{ pid, started, by? }`; a bare pid (an older host) has no start time. `by` (#1223, additive) is who
- * started the host: `app`, `keeper` or `serve` (`instance-lock.ts`), absent when the host did not say
+ * host.lock's `{ pid, started, by? }`. `by` (#1223, additive) is who started the host: `app`, `keeper` or `serve`
+ * (`instance-lock.ts`), absent when the host did not say
  */
 function parseLockHolder(text) {
-  const t = text.trim()
-  if (/^\d+$/.test(t)) return Number(t) > 0 ? { pid: Number(t), started: null } : null
   try {
-    const v = JSON.parse(t)
+    const v = JSON.parse(text)
     if (!Number.isInteger(v?.pid) || v.pid <= 0) return null
     const by = v.by === 'app' || v.by === 'keeper' || v.by === 'serve' ? v.by : null
-    return { pid: v.pid, started: typeof v.started === 'string' ? v.started : null, ...(by ? { by } : {}) }
+    return { pid: v.pid, started: typeof v.started === 'string' ? v.started : null, ...(Number.isFinite(v.at) ? { at: v.at } : {}), ...(by ? { by } : {}) }
   } catch {
     return null
   }
@@ -280,7 +641,24 @@ export function processStartTime(pid) {
   }
 }
 
-/** Who `host.lock` names as the data folder's owner, `{ pid, started, by? }`, or null */
+/**
+ * When a pid's process was created, as milliseconds since the epoch, on Windows (PowerShell); null elsewhere, or when
+ * it cannot be told (a process of another account). Asked of .NET, not `Get-Process`: that one loads a module, which
+ * under PowerShell 7's module path (a CI runner's, a pwsh terminal's) fails, and every lock held on Windows read as a
+ * dead one's (#1906)
+ */
+export function processCreatedAt(pid) {
+  if (process.platform !== 'win32') return null
+  try {
+    const out = execFileSync(windowsPowershell('wmi', process.env), ['-NoProfile', '-NonInteractive', '-Command', `([DateTimeOffset][Diagnostics.Process]::GetProcessById(${pid}).StartTime).ToUnixTimeMilliseconds()`], { encoding: 'utf8', timeout: 10_000, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] })
+    const ms = Number(out.trim())
+    return Number.isFinite(ms) && ms > 0 ? ms : null
+  } catch {
+    return null
+  }
+}
+
+/** Who `host.lock` names as the data folder's owner, `{ pid, started, by?, at? }`, or null */
 export function lockHolder(dataDir) {
   try {
     return parseLockHolder(readFileSync(join(dataDir, 'host.lock'), 'utf8'))