@bli-cockpit/cli 0.2.218 → 0.2.219

package/dist/commands/heartbeat-token-lock.js

@@ -0,0 +1,138 @@
+/**
+ * The single-flight lock around the heartbeat's token exchange (BLI-17994).
+ *
+ * The heartbeat is the one door a device token is offered a successor
+ * through, and it is called from three places: the launchd / Task Scheduler
+ * tick, a manual `cockpit sync`, and `cockpit doctor`. Two of them can fire in
+ * the same second. Without a lock both read `session.json` holding the same
+ * token, both knock with it, and the second's rotation request races the
+ * first's reply (the server answers "rotation_pending", but two writers of
+ * `session.json` still interleave). With it they take turns: the second one
+ * reads the file AFTER the first stored the pending token and knocks with that,
+ * which is exactly the "first use" that promotes it.
+ *
+ * The same code runs on macOS and Windows: an exclusive-create (`wx`) lock file
+ * in the state directory, no `flock`, no platform branch. A holder that died
+ * leaves a file that goes stale after a minute and is taken over.
+ *
+ * The lock is a courtesy, never a gate. The server is safe without it (a
+ * request can never destroy a token that is still in use), so a lock file that
+ * cannot be created at all (read-only volume, antivirus) lets the heartbeat go
+ * ahead, loudly. Only a lock that stays HELD past the wait skips this tick, and
+ * a heartbeat is not spooled: the next tick is fifteen minutes away.
+ *
+ * A new module here must also join `scripts/build-public-cli.mjs`
+ * `runtimeFiles`, or the repo tests stay green while the packed CLI breaks.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describeError } from "../health-detail.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+const LOCK_FILENAME = "token-rotation.lock";
+/** A heartbeat holds the lock for one HTTP call (5 s timeout) plus a few file reads. */
+export const TOKEN_LOCK_STALE_MS = 60_000;
+/** How long a second caller waits for the first before skipping this tick's heartbeat. */
+export const TOKEN_LOCK_WAIT_MS = 8_000;
+const POLL_MS = 150;
+export async function acquireTokenRotationLock(homeDir, options = {}) {
+    const paths = getCollectorRuntimePaths(homeDir);
+    const lockPath = path.join(paths.state_dir, LOCK_FILENAME);
+    const waitMs = options.waitMs ?? TOKEN_LOCK_WAIT_MS;
+    const staleMs = options.staleMs ?? TOKEN_LOCK_STALE_MS;
+    const pollMs = options.pollMs ?? POLL_MS;
+    const owner = crypto.randomUUID();
+    const started = Date.now();
+    try {
+        await fs.mkdir(paths.state_dir, { recursive: true, mode: 0o700 });
+    }
+    catch (error) {
+        return unlocked("state_dir_unavailable", error, started);
+    }
+    for (;;) {
+        try {
+            const handle = await fs.open(lockPath, "wx", 0o600);
+            await handle.writeFile(`${JSON.stringify({ pid: process.pid, owner, at_ms: Date.now() })}\n`);
+            await handle.close();
+            const waited = Date.now() - started;
+            if (waited > pollMs) {
+                console.error("[heartbeat] waited for another heartbeat to finish its token exchange", JSON.stringify({ reason: "token_lock_acquired_after_wait", waited_ms: waited }));
+            }
+            return {
+                acquired: true,
+                waited_ms: waited,
+                mode: "held",
+                release: async () => {
+                    // Only remove a lock that is still ours: a holder that was taken over
+                    // as stale must not delete its successor's lock.
+                    const current = await readOwner(lockPath);
+                    if (current === owner)
+                        await fs.rm(lockPath, { force: true }).catch(() => undefined);
+                },
+            };
+        }
+        catch (error) {
+            if (error?.code !== "EEXIST") {
+                return unlocked("lock_file_unwritable", error, started);
+            }
+        }
+        const heldAt = await readHeldAt(lockPath);
+        if (heldAt === "gone")
+            continue; // released between our create and our read: try again at once
+        if (Date.now() - heldAt > staleMs) {
+            // A holder that died: take the lock over.
+            console.error("[heartbeat] removing a stale token-exchange lock", JSON.stringify({ reason: "token_lock_stale_taken_over", age_ms: Date.now() - heldAt }));
+            await fs.rm(lockPath, { force: true }).catch(() => undefined);
+            continue;
+        }
+        if (Date.now() - started >= waitMs) {
+            console.error("[heartbeat] another heartbeat is still exchanging the device token; skipping this tick's check-in", JSON.stringify({ reason: "token_lock_busy", waited_ms: Date.now() - started, next_action: "the next tick checks in" }));
+            return { acquired: false, waited_ms: Date.now() - started };
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+}
+/** Run `work` under the lock; `skipped` is the answer when the lock stays held past the wait. */
+export async function withTokenRotationLock(homeDir, options, skipped, work) {
+    const lock = await acquireTokenRotationLock(homeDir, options);
+    if (!lock.acquired)
+        return skipped;
+    try {
+        return await work();
+    }
+    finally {
+        await lock.release();
+    }
+}
+function unlocked(reason, error, started) {
+    console.error("[heartbeat] could not create the token-exchange lock; checking in without it (the dashboard stays safe without it)", JSON.stringify({ reason: `token_lock_${reason}`, ...describeError(error) }));
+    return { acquired: true, waited_ms: Date.now() - started, mode: "unlocked", release: async () => undefined };
+}
+async function readOwner(lockPath) {
+    try {
+        const raw = JSON.parse(await fs.readFile(lockPath, "utf8"));
+        return typeof raw["owner"] === "string" ? raw["owner"] : null;
+    }
+    catch {
+        // Gone or unreadable: not provably ours, so release leaves it alone.
+        return null;
+    }
+}
+/** When the lock was taken (ms), `"gone"` if the file no longer exists. A half-written file is dated by its mtime. */
+async function readHeldAt(lockPath) {
+    try {
+        const raw = JSON.parse(await fs.readFile(lockPath, "utf8"));
+        if (typeof raw["at_ms"] === "number" && Number.isFinite(raw["at_ms"]))
+            return raw["at_ms"];
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return "gone";
+    }
+    try {
+        return (await fs.stat(lockPath)).mtimeMs;
+    }
+    catch {
+        return "gone";
+    }
+}

package/dist/commands/heartbeat-token.js

@@ -1,5 +1,8 @@
 import { describeError } from "../health-detail.js";
+import { writeJsonFileAtomic } from "../local-state-files.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, recordDeviceTokenExpiry, toSessionReference, } from "../local-state.js";
+/** The request header that tells the dashboard this build stores a rotated token (BLI-17994). */
+export const TOKEN_ROTATION_HEADER = "x-cockpit-token-rotation";
 /**
  * Read the session and decide whether this tick may check in.
  *
@@ -33,7 +36,7 @@ export async function readHeartbeatSession(homeDir) {
         console.error("[heartbeat] this machine's session looks expired; checking in anyway so the dashboard can renew it", JSON.stringify({
             reason: "session_expired_locally",
             expires_at: session.expires_at ?? null,
-            next_action: "the dashboard renews a token that lapsed inside its 30-day grace window on this call",
+            next_action: "a token inside its rotation window is swapped on this call; one past its date needs `cockpit doctor`",
         }));
     }
     return { usable: true, session, state: state };
@@ -66,6 +69,43 @@ export async function recordHeartbeatTokenExpiry(homeDir, response) {
         return null;
     });
 }
+/**
+ * Store the PENDING device token the heartbeat door handed back (BLI-17994).
+ *
+ * `reply` is the parsed heartbeat body. No `pending_device_token` in it is the
+ * normal case (nothing was due, or a successor is already waiting) and says
+ * nothing. When there is one, it is written to `session.json` in ONE atomic
+ * rename (write a temp file, rename over the session), so no reader (the sync,
+ * the memory hooks, the MCP servers) ever sees a half-written file. The date is
+ * deliberately NOT touched: a pending token has not been used yet, so the
+ * server has not moved the date. The first request that carries it promotes it
+ * and retires the old token; the reply to that request carries the new date,
+ * which `recordHeartbeatTokenExpiry` stores.
+ *
+ * A reply that is malformed, or a write that fails, keeps the current token,
+ * which stays valid until its own date; the server offers another pending
+ * token after ten minutes. Never throws.
+ */
+export async function recordHeartbeatPendingToken(homeDir, reply) {
+    const incoming = reply?.["pending_device_token"];
+    if (incoming === undefined)
+        return { status: "none" };
+    if (typeof incoming !== "string" || !/^bli_dev_[A-Za-z0-9_-]{16,}$/.test(incoming)) {
+        console.error("[heartbeat] the dashboard sent a device token this build does not recognise; keeping the one it has", JSON.stringify({ reason: "pending_token_malformed" }));
+        return { status: "skipped", reason: "pending_token_malformed" };
+    }
+    const paths = getCollectorRuntimePaths(homeDir);
+    try {
+        const session = await readLocalCollectorSessionFile(paths);
+        await writeJsonFileAtomic(paths.session_file, { ...session, device_token: incoming });
+        console.error("[heartbeat] stored the pending device token; the first request that uses it makes it current", JSON.stringify({ reason: "pending_token_stored", expires_at: session.expires_at ?? null }));
+        return { status: "stored" };
+    }
+    catch (error) {
+        console.error("[heartbeat] the pending device token could not be stored; keeping the one this machine has, which stays valid until its date", JSON.stringify({ reason: "pending_token_write_failed", ...describeError(error) }));
+        return { status: "skipped", reason: "pending_token_write_failed" };
+    }
+}
 async function readTokenExpiry(response) {
     try {
         const body = (await response.json());

package/dist/commands/heartbeat.js

@@ -31,7 +31,8 @@ import { readStagingInventory } from "../disk-usage.js";
 import { describeError } from "../health-detail.js";
 import { shouldSuppressFleetReceipts, } from "../dev-build.js";
 import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
-import { noteHeartbeatRefusal, readHeartbeatSession, recordHeartbeatTokenExpiry, } from "./heartbeat-token.js";
+import { noteHeartbeatRefusal, readHeartbeatSession, recordHeartbeatTokenExpiry, recordHeartbeatPendingToken, TOKEN_ROTATION_HEADER, } from "./heartbeat-token.js";
+import { withTokenRotationLock } from "./heartbeat-token-lock.js";
 import { classifySyncHealthError } from "../sync-health-class.js";
 import { readMemoryReceiptFile } from "./memory-install-receipt.js";
 import { readMemoryHookCounts } from "./memory-hook-counts.js";
@@ -220,6 +221,11 @@ export async function readHeartbeatMemoryReceipt(options) {
  * `sync.err.log` alone when the dashboard says a device is quiet.
  */
 export async function sendCollectorHeartbeatBestEffort(options) {
+    // BLI-17994. Single-flight: a launchd tick and a manual sync take turns, so
+    // the second reads `session.json` AFTER the first stored its pending token.
+    return withTokenRotationLock(options.homeDir, options.lock, false, () => sendCollectorHeartbeatLocked(options));
+}
+async function sendCollectorHeartbeatLocked(options) {
     // BLI-3554. A checkout's heartbeat would move `last_seen_at` on a real fleet
     // device row, so an agent's worktree could keep a genuinely dead machine
     // looking alive to the BLI-3550 reader.
@@ -282,6 +288,9 @@ export async function sendCollectorHeartbeatBestEffort(options) {
             headers: {
                 "Content-Type": "application/json",
                 Authorization: `Bearer ${session.device_token}`,
+                // BLI-17994. "I store a renewed token if you send one": the dashboard
+                // only rotates for a collector that says so.
+                [TOKEN_ROTATION_HEADER]: "1",
             },
             body: JSON.stringify(heartbeat),
             signal: controller.signal,
@@ -293,24 +302,33 @@ export async function sendCollectorHeartbeatBestEffort(options) {
             // that decides what a failure is — a 401/403 is `auth_failed` and
             // anything else is not, read off the observed status and never off the
             // words in a message (BLI-3551's rule).
+            // BLI-17994. The door names why it refused (`device_token_expired`,
+            // `device_token_replaced`) in a `reason` field; say it here rather than
+            // leaving a bare status.
+            const refusal = await Promise.resolve().then(() => response.clone().json()).catch(() => null);
             console.error("[heartbeat] the dashboard refused this tick's heartbeat", JSON.stringify({
                 reason: "heartbeat_rejected",
                 health_class: classifySyncHealthError({ httpStatus: response.status }),
                 http_status: response.status,
                 root_count: heartbeat.roots.length,
+                ...(typeof refusal?.["reason"] === "string" ? { server_reason: refusal["reason"] } : {}),
                 ...(response.status === 401 || response.status === 403
                     ? {
-                        next_action: "past the 30-day grace window this needs `cockpit login` on this machine",
+                        next_action: "this token expired, was replaced or was revoked: run `cockpit doctor` to pair this machine again",
                     }
                     : {}),
             }));
             return false;
         }
-        // BLI-4019. The server slides `token_expires_at` out on every call it
-        // authenticates and answers with the result; the sibling records it, so
-        // this machine's own copy follows the server rather than drifting.
+        // The reply carries `token_expires_at` (and a `pending_device_token` when
+        // the token was near its end); the sibling records both, so this machine's
+        // own copy follows the server rather than drifting.
         const reply = await response.clone().json().catch(() => null);
         noteDoctorRequest(reply?.device_action);
+        // BLI-17994. Store a pending successor if the door handed one out (the
+        // date does not move: a pending token has not been used), then the date the
+        // door reports, which moves only when this request promoted a token.
+        await recordHeartbeatPendingToken(options.homeDir, reply);
         await recordHeartbeatTokenExpiry(options.homeDir, response);
         console.error("[heartbeat] checked in", JSON.stringify({
             reason: "heartbeat_recorded",

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.218");
+    writeLine(io?.stdout ?? process.stdout, "0.2.219");
     return 0;
   }
 

package/dist/commands/setup-receipt-lines.js

@@ -28,14 +28,15 @@ const FIXES = {
  * the same gap has two different next actions (BLI-4019).
  *
  * `device` says "run `cockpit login`" for every lapse, and for an expired
- * session that is now the wrong instruction most of the time: the dashboard
- * slides a device token's expiry out on every call it authenticates and renews
- * one that lapsed inside a 30-day grace window, so the ordinary answer is to do
- * nothing and let the next tick fix it. Telling somebody to sign in again on a
- * machine that is about to heal itself is how a receipt stops being believed.
+ * session that can be the wrong instruction: a device token lives 30 days and
+ * the heartbeat swaps it for a fresh one when 7 days or fewer are left
+ * (BLI-17994), so a machine whose local copy merely lags heals on the next
+ * tick. Only a token that stays expired (the machine was offline past its date)
+ * needs `cockpit doctor`. Telling somebody to sign in again on a machine that
+ * is about to heal itself is how a receipt stops being believed.
  */
 const REASON_FIXES = {
-    session_expired: "Renews on the next sync tick while inside the 30-day grace window; past it, run `cockpit login`.",
+    session_expired: "Renews on the next sync tick; if it stays expired this machine was offline too long, so run `cockpit doctor` to pair it again.",
 };
 /** Codex hooks a person switched OFF is a decision, not a fault. */
 const UNSUPPORTED_FIX = "Switched off in your own config; nothing to do.";

package/dist/commands/sync-heal.js

@@ -93,8 +93,8 @@ async function healAgentRules(command, paths, now) {
         : { step: "agent_rules_install", status: "fail", error_code: "agent_rules_still_missing", error_detail: "before=missing; after=missing" };
 }
 /**
- * Sign-in: the heartbeat (which ran just before this) renews a lapsed token
- * inside the server's grace window without a browser. If this machine is STILL
+ * Sign-in: the heartbeat (which ran just before this) swaps a token near its
+ * end for a fresh one without a browser (BLI-17994). If this machine is STILL
  * signed out or the door refused the token (401/403), only a browser can fix
  * it, so record the one action and say it once a day instead of every fifteen
  * minutes. A lapsed local date with no refusal (offline, a checkout build)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.218",
+  "version": "0.2.219",
   "private": false,
   "type": "module",
   "bin": {