@skrr-ai/cli 0.1.123 → 0.1.124

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/liveState.js

@@ -0,0 +1,386 @@
+/**
+ * liveState.ts — a test process does not mutate the state of the product installed on the
+ * machine running it.
+ *
+ * The party that owns the credential files is this package, so the refusal lives at ITS write
+ * boundary. A runner-level setup (a jest global setup, a node:test `--import` loader) is
+ * necessary and insufficient: it cannot cover a child process spawned without `env`, a read of
+ * `os.userInfo().homedir`, a runner nobody wired, or a test file run directly with `node`. This
+ * module is the one place that answers the two questions every one of those cases comes down to,
+ * and `stateFiles.ts` asks them before every mutation.
+ *
+ * It exists because the same accident happened under three different runners. On 2026-10-29 a
+ * desktop jest spec assigned `process.env.HOME`, which moves nothing under jest (a worker gets a
+ * COPY of the environment, and `os.homedir()` reads the real one), ran the real credential
+ * envelope against the real `~/.skrr`, and replaced the `default` profile's wrapped DEK. The
+ * Keychain was faked, so the real KEK could not open it. The guard had been rebuilt per runner
+ * (daemon, cli, desktop) and each rebuild left the next runner uncovered.
+ *
+ *   1. "Is this a test process?"  `testProcessSignal` / `isTestProcess`.
+ *   2. "What is the real home?"   `accountHomeDir` — the account's home from the OS user
+ *      database, NOT `os.homedir()` or `$HOME`, which a test can move. Node's
+ *      `os.userInfo().homedir` reads the user database; Bun's returns `$HOME`, so there it is
+ *      read from the database directly.
+ *
+ * Then `assertMayMutateLiveState(target, what)` for a path and `assertMayMutateLiveKeychain`
+ * for a Keychain service. Both are no-ops outside a test process: they read a handful of
+ * environment variables and return, so production behaviour is unchanged.
+ *
+ * Fails CLOSED. When the real home cannot be determined, a test process may mutate only what
+ * lies under the sandbox home a hermetic runner created (`SKRR_TEST_HERMETIC_HOME`); everything
+ * else is refused, because "unknown" is not "safe".
+ *
+ * Deliberately dependency-free (node builtins and two leaf constants): the daemon imports this
+ * at module load, before anything else in it exists.
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { MASTER_KEK_KEYCHAIN_SERVICE } from './kek/masterKekService.js';
+import { CONFIG_DIR_NAME, LEGACY_NATIVE_ID_PREFIXES, NATIVE_ID_PREFIX } from './localIdentity.js';
+/** Directory name of the state root inside a home directory. */
+export { CONFIG_DIR_NAME };
+/** Opt-in for a deliberate check against the machine's real state. */
+export const ALLOW_LIVE_STATE_ENV = 'SKRR_TEST_ALLOW_LIVE_STATE';
+/** Set by every hermetic runner to the throwaway home it gave the process. */
+export const HERMETIC_HOME_ENV = 'SKRR_TEST_HERMETIC_HOME';
+/** `LiveStateRefusedError.code`. Kept at its pre-consolidation value: scripts match on it. */
+export const LIVE_STATE_REFUSED_CODE = 'SKRR_TEST_LIVE_STATE';
+// ---------------------------------------------------------------------------
+// 1. Is this a test process?
+// ---------------------------------------------------------------------------
+/** A test file's name, as an entry script: `node --import tsx src/foo.test.ts`. */
+const TEST_FILE_RE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+/**
+ * Which signal says this is a test process, or `null`. The text names the signal so a false
+ * positive (a shell that exports `NODE_ENV=test`) diagnoses itself.
+ *
+ * `NODE_TEST_CONTEXT` is set by `node --test` in every file's child process and inherited by
+ * anything a test spawns. `--test` in `execArgv` covers `--test-isolation=none`, where tests run
+ * in the runner itself. A test file run DIRECTLY (`node file.test.ts`) has neither: node:test
+ * sets no marker for it, so the entry script's name is the only evidence. `JEST_WORKER_ID` is
+ * set in the real environment of every jest worker (and by `--runInBand`), so a child a spec
+ * spawns without `env` still carries it. `NODE_ENV=test` is what jest, vitest and `bun test`
+ * default to, and what custom scripts set by hand.
+ *
+ * `argv` is the process's own only when `env` is: a caller describing a hypothetical process
+ * (`{}`) describes all of it.
+ */
+export function testProcessSignal(env = process.env, execArgv = process.execArgv, argv = env === process.env ? process.argv : []) {
+    if (env.NODE_TEST_CONTEXT)
+        return 'NODE_TEST_CONTEXT is set (node --test)';
+    if (env.JEST_WORKER_ID)
+        return 'JEST_WORKER_ID is set (jest)';
+    if (env.VITEST || env.VITEST_WORKER_ID)
+        return 'VITEST is set (vitest)';
+    if (env[HERMETIC_HOME_ENV])
+        return `${HERMETIC_HOME_ENV} is set (a hermetic test runner)`;
+    if (env.NODE_ENV === 'test')
+        return 'NODE_ENV=test';
+    if (execArgv.includes('--test'))
+        return 'node was started with --test';
+    const entry = argv[1];
+    if (typeof entry === 'string' && TEST_FILE_RE.test(entry)) {
+        return `the entry script ${path.basename(entry)} is a test file`;
+    }
+    return null;
+}
+/** Is this a test process? See `testProcessSignal` for what counts. */
+export function isTestProcess(env = process.env, execArgv = process.execArgv, argv) {
+    return testProcessSignal(env, execArgv, argv) !== null;
+}
+/** Should a test process be refused access to the machine's real state? */
+export function refusesLiveStateInTest(env = process.env, execArgv = process.execArgv, argv) {
+    return isTestProcess(env, execArgv, argv) && env[ALLOW_LIVE_STATE_ENV] !== '1';
+}
+// ---------------------------------------------------------------------------
+// 2. What is the real home?
+// ---------------------------------------------------------------------------
+let cachedAccountHome;
+function userDatabaseHome() {
+    const probe = (command, args) => execFileSync(command, args, {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 5_000,
+    });
+    try {
+        if (process.platform === 'darwin') {
+            const out = probe('dscl', [
+                '.',
+                '-read',
+                `/Users/${os.userInfo().username}`,
+                'NFSHomeDirectory',
+            ]);
+            const home = out.replace(/^NFSHomeDirectory:\s*/, '').trim();
+            return home || null;
+        }
+        if (process.platform === 'linux' && typeof process.getuid === 'function') {
+            const home = probe('getent', ['passwd', String(process.getuid())])
+                .trim()
+                .split(':')[5];
+            return home || null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * The account's home directory from the user database. A test that points `HOME` somewhere else
+ * cannot move it, which is the point: it names where the INSTALLED product keeps its state,
+ * whatever this process believes.
+ *
+ * Node's `os.userInfo().homedir` reads the user database. Bun's returns `$HOME`, which is
+ * exactly what a test moves, so the compiled daemon asks the database itself — without that, a
+ * compiled binary spawned by a test with its own `HOME` saw that home as the live one and
+ * refused to start. `null` when it cannot be determined.
+ */
+export function accountHomeDir() {
+    if (cachedAccountHome !== undefined)
+        return cachedAccountHome;
+    if (typeof process.versions.bun === 'string') {
+        cachedAccountHome = userDatabaseHome();
+    }
+    else {
+        try {
+            cachedAccountHome = os.userInfo().homedir || null;
+        }
+        catch {
+            cachedAccountHome = null;
+        }
+    }
+    return cachedAccountHome;
+}
+/**
+ * @internal Test seam — make `accountHomeDir()` answer `home` (`null`: "cannot be determined"),
+ * or restore the user-database lookup with `undefined`. It lets a spec stand a THROWAWAY
+ * directory in for the account's real home, so the guard can be exercised end to end — and its
+ * refusal removed, to prove the spec notices — without any path ever touching the real one.
+ * Never called from production code; `stateFileBoundary.spec.ts` fails if it is.
+ */
+export function __setAccountHomeForTest(home) {
+    cachedAccountHome = home;
+}
+/** The state root of the product installed for this account, when it can be known. */
+export function liveStateRoot(home = accountHomeDir()) {
+    return home ? path.resolve(home, CONFIG_DIR_NAME) : null;
+}
+function probeHome(probe) {
+    const home = probe.realHome === undefined ? accountHomeDir() : probe.realHome;
+    // A filesystem root as "the home" (a service account with HOME=/) would make every path live
+    // and the guard useless; it cannot tell the product's state from anything else.
+    if (!home || path.parse(path.resolve(home)).root === path.resolve(home))
+        return null;
+    return home;
+}
+// ---------------------------------------------------------------------------
+// Path containment, robust to symlinks and case-insensitive volumes.
+// ---------------------------------------------------------------------------
+/**
+ * `target` with every symlink resolved on its longest EXISTING prefix, the rest appended. A
+ * state directory that does not exist yet still lands where it will be created, and a symlink
+ * inside a sandbox that points back at the real home does not hide it.
+ */
+function canonicalise(target) {
+    const absolute = path.resolve(target);
+    let head = absolute;
+    const tail = [];
+    for (;;) {
+        try {
+            const real = fs.realpathSync.native(head);
+            return tail.length === 0 ? real : path.join(real, ...tail.reverse());
+        }
+        catch {
+            const parent = path.dirname(head);
+            if (parent === head)
+                return absolute;
+            tail.push(path.basename(head));
+            head = parent;
+        }
+    }
+}
+function isWithin(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+// ---------------------------------------------------------------------------
+// The refusal.
+// ---------------------------------------------------------------------------
+export class LiveStateRefusedError extends Error {
+    code = LIVE_STATE_REFUSED_CODE;
+    /** What the mutation was aimed at: a path, or a Keychain service. */
+    target;
+    /** Why this process was taken for a test. */
+    signal;
+    constructor(what, target, signal, why, hint) {
+        super(`Refusing to ${what}: ${why}. This process looks like a test (${signal}), and the target ` +
+            `belongs to the Skrr daemon, CLI and desktop app installed on this machine. ` +
+            (hint ??
+                'Run the suite through its own test script (`npm test`, or `npm run test:file -- ' +
+                    '<path>` in daemon/), which gives every test process a home of its own, or point ' +
+                    'HOME at a throwaway directory for the run (HOME=$(mktemp -d) …). ') +
+            `Set ${ALLOW_LIVE_STATE_ENV}=1 only for a deliberate check against the real state.`);
+        this.name = 'LiveStateRefusedError';
+        this.target = target;
+        this.signal = signal;
+    }
+}
+/**
+ * Is `err` a live-state refusal? By name and code as well as by class: auth-core ships as both
+ * ESM and CJS, and two copies of it in one process (a farmed worktree) have two classes.
+ */
+export function isLiveStateRefusal(err) {
+    return (err instanceof LiveStateRefusedError ||
+        (err?.name === 'LiveStateRefusedError' &&
+            err.code === LIVE_STATE_REFUSED_CODE));
+}
+/**
+ * First line of any `catch` that wraps a guarded mutation. A refusal swallowed into a telemetry
+ * event is a write that silently did not happen under a test that reports green, which is the
+ * "everything reads healthy" shape this repo has paid for before. A no-op outside a test
+ * process, where no refusal is ever constructed.
+ */
+export function rethrowIfLiveStateRefusal(err) {
+    if (isLiveStateRefusal(err))
+        throw err;
+}
+/**
+ * Why `target` may not be mutated by a test process, or `null` when it may. The caller has
+ * already established that this is a test process and that the opt-in is not set.
+ */
+function pathRefusal(target, probe, env) {
+    const resolved = canonicalise(target);
+    const home = probeHome(probe);
+    if (home === null) {
+        // Fail closed: the only place a test may write when the real home is unknown is the sandbox
+        // a hermetic runner created.
+        const sandbox = env[HERMETIC_HOME_ENV];
+        if (sandbox && isWithin(resolved, canonicalise(sandbox)))
+            return null;
+        return (`${target} cannot be shown to be outside the real home, because the account's home ` +
+            `directory could not be determined`);
+    }
+    return isWithin(resolved, canonicalise(home))
+        ? `${target} is inside the real home ${home}`
+        : null;
+}
+/**
+ * Throw `LiveStateRefusedError` when a test process is about to mutate `target`, a path under
+ * the account's real home. Returns without reading anything else outside a test process.
+ *
+ * `what` completes "Refusing to …" (`replace the wrapped DEK`). `hint` replaces the default
+ * advice about how to run the test safely.
+ */
+export function assertMayMutateLiveState(target, what, probe = {}, hint) {
+    const env = probe.env ?? process.env;
+    const signal = testProcessSignal(env, probe.execArgv ?? process.execArgv, probe.argv);
+    if (signal === null || env[ALLOW_LIVE_STATE_ENV] === '1')
+        return;
+    const why = pathRefusal(target, probe, env);
+    if (why !== null)
+        throw new LiveStateRefusedError(what, target, signal, why, hint);
+}
+// ---------------------------------------------------------------------------
+// The Keychain's live service set.
+// ---------------------------------------------------------------------------
+/** Service name prefix of the daemon's credential slots; always followed by `.<profile>`. */
+export const DAEMON_KEYCHAIN_SERVICE_BASE = `${NATIVE_ID_PREFIX}.daemon`;
+/**
+ * Separate Keychain service for local BYOK secrets.
+ *
+ * Keeping provider keys out of the daemon-auth service prevents a broad "export daemon
+ * credentials" operation from accidentally including them and lets the user remove a provider
+ * key without disturbing their login.
+ */
+export const DAEMON_BYOK_KEYCHAIN_SERVICE_BASE = `${NATIVE_ID_PREFIX}.daemon.byok`;
+/**
+ * The PRE-RENAME, pre-Phase-K service name. Read ONLY by the daemon's migration helper.
+ *
+ * It must NOT equal `DAEMON_KEYCHAIN_SERVICE_BASE`, and it held that value until a fix: the
+ * skrr rename swept the string like any other, and the two became identical. Nothing failed,
+ * because the failure is an absence — `migrateLegacyServiceToProfile` read a service nothing had
+ * ever written, found no slots, and reported success. Pre-rename credentials stayed where they
+ * were and the user silently re-authenticated. Written as a literal on purpose.
+ */
+export const LEGACY_DAEMON_KEYCHAIN_SERVICE = 'ai.oversky.daemon';
+/** The profile the installed daemon runs when nothing selects another. */
+export const LIVE_DEFAULT_PROFILE = 'default';
+/**
+ * `-<sha256(dir)[0:8]>`, the suffix of every per-profile Keychain service name. The input is the
+ * absolute, trailing-slash-stripped config directory, so two OS users running the daemon under
+ * their own `~/.skrr/` get distinct names and cannot read each other's tokens.
+ */
+export function keychainSuffixForDir(dir) {
+    const resolved = path.resolve(dir.replace(/\/+$/, ''));
+    return `-${createHash('sha256').update(resolved).digest('hex').toLowerCase().slice(0, 8)}`;
+}
+/** A per-profile default-profile service whose hash we cannot verify without the real home. */
+const UNVERIFIABLE_DEFAULT_SLOT_RE = new RegExp(`^(?:${DAEMON_KEYCHAIN_SERVICE_BASE.replace(/\./g, '\\.')}|` +
+    `${DAEMON_BYOK_KEYCHAIN_SERVICE_BASE.replace(/\./g, '\\.')})\\.` +
+    `${LIVE_DEFAULT_PROFILE}-[0-9a-f]{8}$`);
+/**
+ * Keychain services that belong to the product installed on this machine: the master KEK
+ * (current brand and the ones before it), the default profile's credential and BYOK slots under
+ * the account's real home, and the legacy names the daemon migrates from on start — a write to
+ * one of those is adopted by the next restart instead of the next read.
+ *
+ * The per-profile names are derived from the ACCOUNT's home, which no `HOME` override can reach.
+ * When the home is unknown only the names that need no home are returned; see
+ * `isLiveKeychainService` for what is done about the rest.
+ */
+export function liveKeychainServices(probe = {}) {
+    const services = new Set([
+        MASTER_KEK_KEYCHAIN_SERVICE,
+        ...LEGACY_NATIVE_ID_PREFIXES.map((prefix) => `${prefix}.daemon.kek`),
+        `${DAEMON_KEYCHAIN_SERVICE_BASE}.${LIVE_DEFAULT_PROFILE}`,
+        DAEMON_KEYCHAIN_SERVICE_BASE,
+        LEGACY_DAEMON_KEYCHAIN_SERVICE,
+    ]);
+    const root = liveStateRoot(probeHome(probe));
+    if (root) {
+        const suffix = keychainSuffixForDir(path.resolve(root, 'profiles', LIVE_DEFAULT_PROFILE));
+        services.add(`${DAEMON_KEYCHAIN_SERVICE_BASE}.${LIVE_DEFAULT_PROFILE}${suffix}`);
+        services.add(`${DAEMON_BYOK_KEYCHAIN_SERVICE_BASE}.${LIVE_DEFAULT_PROFILE}${suffix}`);
+    }
+    return services;
+}
+/**
+ * Does `service` name an item of the installed product? When the real home is unknown, a
+ * default-profile slot with a hash suffix is assumed live: its hash cannot be checked, and the
+ * guard fails closed.
+ */
+export function isLiveKeychainService(service, probe = {}) {
+    if (liveKeychainServices(probe).has(service))
+        return true;
+    return probeHome(probe) === null && UNVERIFIABLE_DEFAULT_SLOT_RE.test(service);
+}
+/** Would a mutation of Keychain `service` be refused in a process with this shape? */
+export function refusesLiveKeychainMutation(service, probe = {}) {
+    const env = probe.env ?? process.env;
+    return (refusesLiveStateInTest(env, probe.execArgv ?? process.execArgv, probe.argv) &&
+        isLiveKeychainService(service, probe));
+}
+/**
+ * Throw `LiveStateRefusedError` when a test process is about to write or delete an item in a
+ * Keychain service the installed product reads. Callers that can be handed a fake `security`
+ * binary call this only when the real one would run: a mocked write touches nothing.
+ */
+export function assertMayMutateLiveKeychain(service, what, probe = {}, hint) {
+    const env = probe.env ?? process.env;
+    const signal = testProcessSignal(env, probe.execArgv ?? process.execArgv, probe.argv);
+    if (signal === null || env[ALLOW_LIVE_STATE_ENV] === '1')
+        return;
+    if (!isLiveKeychainService(service, probe))
+        return;
+    let where = '';
+    if (probe.keychainFile !== undefined) {
+        const why = pathRefusal(probe.keychainFile, probe, env);
+        if (why === null)
+            return;
+        where = `, in a keychain that is not shown to be anyone else's (${why})`;
+    }
+    throw new LiveStateRefusedError(what, service, signal, `the Keychain service ${service} is one the installed product reads${where}`, hint);
+}

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/machineId.js

@@ -27,7 +27,9 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { rethrowIfLiveStateRefusal } from './liveState.js';
 import { getAuthMachineConfigDir, getAuthLogger } from './runtime.js';
+import { ensureStateDir, renameStateFile, writeStateFile } from './stateFiles.js';
 /** File name for the stable machine daemon id. Never changes. */
 const DAEMON_ID_FILENAME = 'daemon.id';
 /** Profile subdirectory — scanned for legacy per-profile identity files. */
@@ -86,16 +88,16 @@ function isUuidLike(raw) {
  */
 function writeDaemonIdFile(target, id) {
     const dir = path.dirname(target);
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    ensureStateDir(dir, 'create the machine id directory');
     const tmp = `${target}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
-    fs.writeFileSync(tmp, id + '\n', { encoding: 'utf-8', mode: 0o600 });
+    writeStateFile(tmp, id + '\n', { encoding: 'utf-8', mode: 0o600 }, 'write the machine id');
     try {
         fs.chmodSync(tmp, 0o600);
     }
     catch {
         /* best-effort — writeFileSync already set mode */
     }
-    fs.renameSync(tmp, target);
+    renameStateFile(tmp, target, 'write the machine id');
 }
 /**
  * Default fallback when a consumer doesn't supply one. Synthesizes a
@@ -179,6 +181,7 @@ export function ensureMachineDaemonId(machineUuidFallback) {
         return fresh;
     }
     catch (err) {
+        rethrowIfLiveStateRefusal(err);
         log.warn(`[machineIdentity] persist ${target} failed: ${err.message} — using fallback`);
         const fallback = `fallback-${fallbackFn()}`;
         cachedStableDaemonId = fallback;

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/machineUuid.js

@@ -12,7 +12,8 @@
  * identity can only agree by being edited together; this file is the one
  * implementation, and `daemon/src/registry-lite.ts` re-exports it.
  *
- * Deliberately dependency-free (node builtins only) and exposed as the
+ * Deliberately dependency-free (node builtins, plus the leaf `liveState` / `stateFiles`
+ * modules that guard its one write, which import nothing else) and exposed as the
  * `@skrr-ai/auth-core/machine-uuid` subpath: the packaged desktop imports the
  * daemon's `registry-lite.js` directly, and loading the full auth-core index
  * there would drag in the credential stack for a one-function need.
@@ -28,6 +29,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { resolveConfigRoot } from './configRoot.js';
+import { rethrowIfLiveStateRefusal } from './liveState.js';
+import { ensureStateDir, renameStateFile, writeStateFile } from './stateFiles.js';
 /**
  * Daemon sources whose identity is ISSUED by the control plane rather than
  * derived from the host: the provisioner mints the daemon id and machine uuid
@@ -220,7 +223,7 @@ function readPersistedChoice(file, hardware, profile, requireProfile = false) {
 }
 function persistChoice(dir, file, hardware, machineUuid, reason, profile, evidence) {
     try {
-        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        ensureStateDir(dir, 'create the machine identity directory');
         const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
         const body = {
             version: 1,
@@ -236,10 +239,13 @@ function persistChoice(dir, file, hardware, machineUuid, reason, profile, eviden
             ...(evidence && evidence.length > 0 ? { evidence: [...evidence] } : {}),
             decidedAt: new Date().toISOString(),
         };
-        fs.writeFileSync(tmp, `${JSON.stringify(body)}\n`, { mode: 0o600 });
-        fs.renameSync(tmp, file);
+        writeStateFile(tmp, `${JSON.stringify(body)}\n`, { mode: 0o600 }, 'write the machine identity');
+        renameStateFile(tmp, file, 'write the machine identity');
     }
-    catch {
+    catch (err) {
+        // A refusal is the one failure that is not "not persisted": a test aimed at the real home
+        // must hear about it.
+        rethrowIfLiveStateRefusal(err);
         // Not persisted: the in-process cache keeps this process consistent, and the
         // next process decides again from the same evidence.
     }

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/profileStateDir.js

@@ -73,6 +73,7 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getAuthConfigDir, getAuthMachineConfigDir } from './runtime.js';
+import { atomicWrite0600, renameStateFile } from './stateFiles.js';
 /** Directory segment that separates per-profile state from machine-scoped state. */
 export const PROFILES_SEGMENT = 'profiles';
 /**
@@ -286,37 +287,6 @@ function sha256OfFile(target) {
         return null;
     }
 }
-/**
- * tmp + fsync + rename + dir-fsync, 0600. The same shape the two bridges
- * already use, so a crash mid-migration leaves either the old file or the new
- * one and never a half-written key.
- */
-function atomicWrite0600(target, value) {
-    const dir = path.dirname(target);
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    const tmp = `${target}.tmp.${process.pid}.${Date.now()}`;
-    const fd = fs.openSync(tmp, 'w', 0o600);
-    try {
-        fs.writeSync(fd, value);
-        fs.fsyncSync(fd);
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-    fs.renameSync(tmp, target);
-    try {
-        const dirFd = fs.openSync(dir, 'r');
-        try {
-            fs.fsyncSync(dirFd);
-        }
-        finally {
-            fs.closeSync(dirFd);
-        }
-    }
-    catch {
-        /* best-effort — Windows / some BSDs reject dir fsync */
-    }
-}
 function adopt(fromDir, toDir, files, dryRun) {
     const written = [];
     for (const name of files) {
@@ -324,8 +294,9 @@ function adopt(fromDir, toDir, files, dryRun) {
         if (!existsFile(source))
             continue;
         const target = path.join(toDir, name);
-        if (!dryRun)
-            atomicWrite0600(target, fs.readFileSync(source));
+        if (!dryRun) {
+            atomicWrite0600(target, fs.readFileSync(source), `adopt ${name} into ${toDir}`);
+        }
         written.push(target);
     }
     return { written, supersededAside: [] };
@@ -337,7 +308,7 @@ function moveAside(dir, files, suffix = SUPERSEDED_COPY_SUFFIX) {
         const target = path.join(dir, name);
         if (!existsFile(target))
             continue;
-        fs.renameSync(target, `${target}${suffix}.${stamp}`);
+        renameStateFile(target, `${target}${suffix}.${stamp}`, `set aside ${target}`);
         aside.push(target);
     }
     return aside;
@@ -355,7 +326,7 @@ function writeMarker(markerPath, supersededBy, reason) {
             'older binaries read it and it is the only rollback that needs no operator step. ' +
             'Remove it only through logout.',
     };
-    atomicWrite0600(markerPath, Buffer.from(`${JSON.stringify(payload, null, 2)}\n`, 'utf-8'));
+    atomicWrite0600(markerPath, Buffer.from(`${JSON.stringify(payload, null, 2)}\n`, 'utf-8'), `write the consolidation marker ${markerPath}`);
 }
 function emitOutcome(spec, status, meta) {
     spec.onEvent?.(`path_consolidation.${status}`, status !== 'conflict', {

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/refresh.d.ts

@@ -231,7 +231,7 @@ export type DeviceProofSigner = (params: {
     method: string;
     url: string;
     refreshToken: string;
-}) => string | null | undefined;
+}) => string | null | undefined | Promise<string | null | undefined>;
 export declare function refreshDaemonToken(serverUrl: string, currentRefreshToken: string, daemonId: string, options?: {
     machineUuid?: string;
     origin?: string;

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/refresh.js

@@ -25,7 +25,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import lockfile from 'proper-lockfile';
 import { getAuthLogger, getAuthConfigDir, emitAuthTelemetry, notifyResponseObserver, } from './runtime.js';
+import { rethrowIfLiveStateRefusal } from './liveState.js';
 import { permanentReasonForRefreshCode } from './refreshClassification.js';
+import { ensureStateDir, removeStateFile, writeStateFile } from './stateFiles.js';
 import { PermanentAuthFailure, TransientAuthFailure, } from './types.js';
 /**
  * P1-6: Reduced from 30 s to 5 s.
@@ -254,9 +256,9 @@ export async function withAuthLock(body, daemonId) {
     const lockPath = authLockPath();
     const dir = path.dirname(lockPath);
     if (!fs.existsSync(dir))
-        fs.mkdirSync(dir, { recursive: true });
+        ensureStateDir(dir, 'create the auth lock directory', null);
     if (!fs.existsSync(lockPath)) {
-        fs.writeFileSync(lockPath, '', { mode: 0o600 });
+        writeStateFile(lockPath, '', { mode: 0o600 }, 'create the auth lock');
     }
     const acquireStart = Date.now();
     emitAuthTelemetry({
@@ -615,7 +617,7 @@ async function doRefresh(serverUrl, currentRefreshToken, daemonId, options = {})
     // `DEVICE_PROOF_MISSING` is only a LOCAL fact (no key to sign with) when we
     // know none went out; if one did, something between us stripped it.
     let proofAttached = false;
-    function buildRequestInit() {
+    async function buildRequestInit() {
         proofAttached = false;
         // Phase 3-R5: the stable `X-Oversky-Origin` header is the server's
         // preferred identity signal on the benign-grace rotation match. Newer
@@ -638,7 +640,9 @@ async function doRefresh(serverUrl, currentRefreshToken, daemonId, options = {})
         __refreshDiagnostics.requestAttemptCount += 1;
         if (options.signRequestProof) {
             try {
-                const proof = options.signRequestProof({
+                // Awaited: a hardware key signs in a helper process. A synchronous
+                // signer (a test double, an older caller) still works unchanged.
+                const proof = await options.signRequestProof({
                     method: 'POST',
                     url,
                     refreshToken: currentRefreshToken,
@@ -675,7 +679,7 @@ async function doRefresh(serverUrl, currentRefreshToken, daemonId, options = {})
         // Single attempt today. The builder structure is the load-bearing
         // bit: any future retry must call `buildRequestInit()` again so
         // the per-attempt invariant — fresh jti per request — holds.
-        response = await fetch(url, buildRequestInit());
+        response = await fetch(url, await buildRequestInit());
         notifyResponseObserver(response);
     }
     catch (err) {
@@ -972,12 +976,11 @@ export function persistReauthState(state) {
     try {
         const dir = path.dirname(flagPath);
         if (!fs.existsSync(dir))
-            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-        fs.writeFileSync(flagPath, JSON.stringify(state, null, 2) + '\n', {
-            mode: 0o600,
-        });
+            ensureStateDir(dir, 'create the re-auth latch directory');
+        writeStateFile(flagPath, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 }, 'write the re-auth latch');
     }
     catch (err) {
+        rethrowIfLiveStateRefusal(err);
         log.debug(`[auth/refresh] failed to persist reauth flag: ${err?.message}`);
     }
 }
@@ -1009,9 +1012,10 @@ export function clearReauthState() {
     try {
         const flagPath = reauthFlagPath();
         if (fs.existsSync(flagPath))
-            fs.unlinkSync(flagPath);
+            removeStateFile(flagPath, 'clear the re-auth latch');
     }
     catch (err) {
+        rethrowIfLiveStateRefusal(err);
         log.debug(`[auth/refresh] clearReauthState: ${err?.message}`);
     }
 }

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/stateFiles.d.ts

@@ -0,0 +1,31 @@
+/**
+ * stateFiles.ts — the ONE place auth-core mutates credential state on disk.
+ *
+ * Every write, delete, rename and mkdir of a wrapped DEK, a device key, an enrollment marker, a
+ * lock sentinel, a re-auth latch or a machine identity goes through a function here, and each
+ * asks `assertMayMutateLiveState` first: a test process aimed at the account's real home is
+ * refused with a named error before a byte changes (`liveState.ts` says why that cannot be left
+ * to each runner).
+ *
+ * This is the "own a control surface, or do not touch it" rule applied to the real home. The
+ * atomic writer used to exist three times (device identity, credential envelope, profile
+ * consolidation), so a guard added to one left two doors open. `stateFileBoundary.spec.ts`
+ * fails when a file other than this one starts calling a raw `fs` mutator, so a fourth copy
+ * cannot appear unguarded.
+ *
+ * Outside a test process every function here is exactly the `fs` call it wraps.
+ */
+import fs from 'node:fs';
+/** `mkdir -p` for a state directory, 0700 unless `mode` says otherwise. */
+export declare function ensureStateDir(dir: string, what: string, mode?: number | null): void;
+/**
+ * Atomic 0600 write — tmp+fsync+rename+dir-fsync. The same shape the daemon and CLI always used,
+ * so a partial-write race between `skrr` and `skrrd` produces the same on-disk transitions.
+ */
+export declare function atomicWrite0600(target: string, value: Buffer | string, what: string): void;
+/** `fs.writeFileSync` for a state file: lock sentinels, a re-auth latch, a machine identity. */
+export declare function writeStateFile(target: string, data: string | NodeJS.ArrayBufferView, options: fs.WriteFileOptions, what: string): void;
+/** `fs.unlinkSync` for a state file. Throws what `unlinkSync` throws, ENOENT included. */
+export declare function removeStateFile(target: string, what: string): void;
+/** `fs.renameSync` between state paths; both ends are checked. */
+export declare function renameStateFile(from: string, to: string, what: string): void;