agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/credentials.js

@@ -0,0 +1,374 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, chmodSync, unlinkSync, writeFileSync, writeSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * A server-minted org address: `org_` followed by a canonical uuid.
+ *
+ * Exported because the shape is a contract between the two places that care —
+ * the caller that receives one over the wire and the key that is built from it.
+ * Stating it in a comment next to the key was not enough: the comment justified
+ * a delimiter by a property nothing enforced.
+ */
+export function isOrgAddress(value) {
+    return /^org_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value);
+}
+/**
+ * The storage key: one slot per (host, org).
+ *
+ * Both halves are derived rather than taken as typed — `https://x.test/` and
+ * `https://x.test` are one host and must not become two slots holding two
+ * secrets. The separator is a space because neither half can contain one: an
+ * origin has no spaces by construction, and an org address is `org_<uuid>`.
+ *
+ * That second half is now checked here rather than assumed. A malformed org —
+ * `x`, or anything carrying a space or a newline — would not be caught by a
+ * non-empty test upstream, and it does not fail loudly either: it writes a slot
+ * under a key nothing will ever look up again, which is worse than the
+ * `undefined` key this guarded against in the first place. The invariant is
+ * enforced where it is relied upon, so a future caller cannot skip it.
+ */
+function keyFor(endpoint, org) {
+    if (!isOrgAddress(org)) {
+        throw new Error(`refusing to store a credential under a malformed org address`);
+    }
+    return `${originOf(endpoint)} ${org}`;
+}
+const EMPTY = { version: 1, active: null, credentials: {} };
+export function credentialsPath(env = process.env) {
+    const base = env.AGMSG_CLOUD_HOME ?? join(homedir(), '.agmsg-cloud');
+    return join(base, 'credentials.json');
+}
+// An origin is the credential's key, so it must be derived — never taken as the
+// caller typed it. `https://x.test/` and `https://x.test` are one host and must
+// not become two slots holding two secrets.
+export function originOf(endpoint) {
+    return new URL(endpoint).origin;
+}
+function readFile(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (err) {
+        const code = err.code;
+        // ELOOP: the path is a symlink. That is not "no credentials yet" — it is a
+        // credential file that someone else controls the destination of, so it
+        // fails loudly rather than being treated as absent and overwritten.
+        if (code === 'ELOOP')
+            throw new Error(`${path} is a symlink; refusing to read a credential through it`);
+        if (code === 'ENOENT')
+            return { ...EMPTY, credentials: {} };
+        throw err;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(fd, 'utf8'));
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            parsed.version !== 1 ||
+            typeof parsed.credentials !== 'object') {
+            throw new Error(`${path} is not a v1 credential file`);
+        }
+        return parsed;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * The credential for a host, or for whatever the last login wrote.
+ *
+ * Callers ask by ORIGIN, because that is all they know: `connect` and `pull`
+ * have an endpoint, not an org. One host can now hold several credentials, so
+ * this has to choose, and there is exactly one honest way to choose between
+ * two secrets that both fit: don't.
+ *
+ * - one credential for the host — return it
+ * - several, and `active` is one of them — return that, the last login
+ * - several, and `active` is elsewhere — THROW, naming the orgs
+ *
+ * The last case is the one worth being careful about. Returning `null` there
+ * would say "no credential for this host", which is false and sends the caller
+ * down the sign-in path — the same collapse of "ambiguous" into "absent" that
+ * hid the original defect. It throws instead, and the message names the orgs so
+ * the person can say which one they meant.
+ */
+export function readCredential(origin, env = process.env) {
+    const file = readFile(credentialsPath(env));
+    if (origin === null) {
+        return file.active ? (file.credentials[file.active] ?? null) : null;
+    }
+    const matches = Object.entries(file.credentials).filter(([key]) => key.startsWith(`${origin} `));
+    if (matches.length === 0)
+        return null;
+    if (matches.length === 1)
+        return matches[0][1];
+    if (file.active && file.credentials[file.active] && file.active.startsWith(`${origin} `)) {
+        return file.credentials[file.active];
+    }
+    const orgs = matches
+        .map(([, c]) => c.org)
+        .sort()
+        .join(', ');
+    throw new Error(`${origin} has credentials for more than one org (${orgs}) and none of them is the active one. ` +
+        `Run agmsg-cloud login again for the org you want, which makes it active.`);
+}
+// An atomic rename prevents a half-written FILE. It does not serialize an
+// update: two logins to different origins both read the same old JSON, both
+// rename, and the last one silently drops the other's entry — while both have
+// already been told to activate. The loser is then in exactly the state the
+// write-before-activate ordering exists to prevent (the server holds a live
+// credential this machine no longer has). So the read-modify-write runs under a
+// cross-process lock, not just an atomic replace.
+// `mkdirSync({ mode })` only applies to a directory it creates, and a file
+// rewritten in place keeps the mode it already had. So the 0700/0600 claim is
+// enforced on every write rather than assumed from the first one — an
+// `~/.agmsg-cloud` left group-readable by an older build, or by a user, would
+// otherwise keep that mode forever while the comment claimed otherwise.
+function enforceDirMode(dir) {
+    const mode = statSync(dir).mode & 0o777;
+    if (mode !== 0o700)
+        chmodSync(dir, 0o700);
+}
+function enforceFileMode(path) {
+    try {
+        const mode = statSync(path).mode & 0o777;
+        if (mode !== 0o600)
+            chmodSync(path, 0o600);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_MS = 25;
+const LOCK_TIMEOUT_MS = 10_000;
+// The holder's pid goes IN the lock. Without it, "make sure no login is
+// running" is advice the operator cannot act on; with it, the check is a
+// concrete one they can perform.
+function tryCreateExclusive(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return false;
+        throw err;
+    }
+    // Past a successful O_EXCL open, this call created the file and no one else
+    // can be holding it — which is what makes removing it here safe, and why the
+    // cleanup belongs on this side of the open and nowhere else.
+    //
+    // Without it a failed write (ENOSPC, EIO) leaves a lock with no owner and no
+    // release callback. Since this file stopped reclaiming abandoned locks, the
+    // next login would wait the full stale window and then ask a person to delete
+    // it by hand. The pid is written to help diagnose an abandoned lock; it must
+    // not be able to manufacture one.
+    try {
+        try {
+            writeSync(fd, `${process.pid}\n`);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (err) {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            // Best effort. If the lock cannot be removed the original write error is
+            // still the one worth reporting, and a second failure here would bury it.
+        }
+        throw err;
+    }
+    return true;
+}
+function holderPid(path) {
+    try {
+        const text = readFileSync(path, 'utf8').trim();
+        return /^\d+$/.test(text) ? text : null;
+    }
+    catch {
+        // Best effort only: a lock we cannot read still gets the safety wording.
+        return null;
+    }
+}
+// ENOENT means the lock is gone, which is a real and expected answer. Any other
+// stat error means something is wrong with the path, and rounding that to "gone"
+// would spin the retry loop past its own deadline, silently. Broken is not absent.
+function ageMs(path) {
+    try {
+        return Date.now() - statSync(path).mtimeMs;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+function spin(ms) {
+    // Deliberate: the lock is held for one small file rewrite, and sleeping would
+    // need an async signature the synchronous callers do not have.
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        /* spin */
+    }
+}
+// Serializes the read-modify-write across PROCESSES, which is what two
+// concurrent `agmsg-cloud login` runs are.
+//
+// An abandoned lock is NOT reclaimed automatically. An earlier version did
+// that, correctly as far as anyone could argue — the right to break a stale
+// lock was claimed with O_EXCL and held until the replacement was taken — but
+// no test could tell it apart from the naive "stat it, then unlink it" version
+// that races. Measured at 6 and at 24 concurrent writers, both implementations
+// passed. A protection nothing can distinguish from its absence is one that
+// stops protecting the moment somebody edits it, without anything going red.
+//
+// So the reclaim is gone. A lock older than the stale window stops the run and
+// names the file to delete: one manual step after a crash, in exchange for
+// behaviour a test can pin. (The same conclusion was reached independently on
+// the OSS side for its mkdir lock.)
+function acquireLock(path) {
+    const lockPath = `${path}.lock`;
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        if (tryCreateExclusive(lockPath)) {
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    // Already gone; nothing to undo.
+                }
+            };
+        }
+        const age = ageMs(lockPath);
+        if (age === null)
+            continue; // vanished while being inspected
+        if (age > LOCK_STALE_MS) {
+            // A held lock is a stale CANDIDATE, never a proof that its owner died: a
+            // paused process, a sleeping machine, a scheduler stall or a slow fsync
+            // all pass this age. Saying otherwise would hand the operator the very
+            // act this code stopped doing automatically — deleting a live holder's
+            // lock, which puts two read-modify-writes back in flight by hand.
+            const pid = holderPid(lockPath);
+            throw new Error(`${lockPath} has been held for ${Math.round(age / 1000)}s. That usually means the process that took it ` +
+                `exited without cleaning up, but a suspended or very slow process looks identical from here` +
+                (pid === null ? '' : ` (it was taken by pid ${pid})`) +
+                `. Delete it ONLY if you can confirm no agmsg-cloud login is running or stopped on this machine; ` +
+                `otherwise leave it and try again.`);
+        }
+        if (Date.now() > deadline) {
+            throw new Error(`timed out waiting for ${lockPath}; another login is writing. Try again.`);
+        }
+        spin(LOCK_RETRY_MS);
+    }
+}
+export function writeCredential(credential, env = process.env) {
+    const path = credentialsPath(env);
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // `mkdirSync` mode applies only when it creates the directory; an existing one
+    // keeps whatever mode it has.
+    enforceDirMode(dir);
+    const release = acquireLock(path);
+    try {
+        writeLocked(path, dir, credential);
+    }
+    finally {
+        release();
+    }
+}
+function writeLocked(path, dir, credential) {
+    const key = keyFor(credential.endpoint, credential.org);
+    // Read INSIDE the lock: a copy read before acquiring it is exactly the stale
+    // base that loses another entry.
+    const file = readFile(path);
+    const next = {
+        version: 1,
+        active: key,
+        credentials: { ...file.credentials, [key]: credential },
+    };
+    commit(path, dir, next);
+}
+/**
+ * Remove every credential this origin holds, and say which they were.
+ *
+ * Same lock and same durable write as a login, for the same reason: two
+ * processes that read before locking both write a stale base, and the loser's
+ * entry comes back from the dead. Removal has to be as careful as writing —
+ * a sign-out that half-worked leaves a secret on disk that its owner believes
+ * is gone.
+ *
+ * Returns what it removed rather than a count. The caller names the machine on
+ * screen, and the person signing out is entitled to know which identity just
+ * left this machine.
+ */
+export function removeCredentials(origin, env = process.env) {
+    const path = credentialsPath(env);
+    if (!existsSync(path))
+        return [];
+    const dir = dirname(path);
+    const release = acquireLock(path);
+    try {
+        const file = readFile(path);
+        const doomed = Object.entries(file.credentials).filter(([key]) => key.startsWith(`${origin} `));
+        if (doomed.length === 0)
+            return [];
+        const kept = Object.fromEntries(Object.entries(file.credentials).filter(([key]) => !key.startsWith(`${origin} `)));
+        // `active` is a KEY, and the key it names may be one of the ones going. A
+        // stale pointer would make `readCredential(null)` answer with a credential
+        // that is no longer in the file — null, not the first survivor: which org
+        // becomes current is the person's to say, and guessing it here would sign
+        // them into an account they did not choose.
+        const active = file.active && file.active in kept ? file.active : null;
+        commit(path, dir, { version: 1, active, credentials: kept });
+        return doomed.map(([, credential]) => credential);
+    }
+    finally {
+        release();
+    }
+}
+/** The atomic, durable write both paths share. Caller holds the lock. */
+function commit(path, dir, next) {
+    // Unpredictable temp name: a name an attacker can guess is a name they can
+    // pre-create as a symlink pointing somewhere else.
+    const tmp = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+    const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        writeSync(fd, `${JSON.stringify(next, null, 2)}\n`);
+        fsyncSync(fd);
+    }
+    catch (err) {
+        closeSync(fd);
+        unlinkSync(tmp);
+        throw err;
+    }
+    closeSync(fd);
+    renameSync(tmp, path);
+    enforceFileMode(path);
+    // Rename is atomic but not durable until the DIRECTORY entry is flushed. The
+    // whole point of writing before activating is that a crash here still leaves
+    // the credential on disk, so this fsync is load-bearing, not hygiene.
+    const dirFd = openSync(dir, constants.O_RDONLY);
+    try {
+        fsyncSync(dirFd);
+    }
+    finally {
+        closeSync(dirFd);
+    }
+}
+// Used only by the tests that need a file on disk without going through a
+// login; kept here so the 0600/0700 rules live in exactly one place.
+export function writeRawForTest(path, contents) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, contents, { mode: 0o600 });
+}

package/dist/src/device-slot.js

@@ -0,0 +1,148 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { newVdk, unwrapVdk, wrapVdk, } from './vault-crypto.js';
+import { deleteSecret, readSecret, secureStoreStatus, storeSecret, } from './secure-store.js';
+export const DEVICE_WRAP_PROFILE = 'aes256gcm-v1';
+// One account name per (deployment, account, vault, generation). The
+// generation is in the name on purpose: after a re-issuance the old slot does
+// not answer for the new vault, and the design requires exactly that — an
+// old-generation slot must not open the current vault. Making it part of the
+// address means the wrong slot is not found rather than found and refused.
+function accountFor(address) {
+    // Length-prefixed, not delimiter-joined. These are strings at runtime
+    // whatever the upstream types promise, and a value containing the separator
+    // could otherwise make two different addresses produce one account name —
+    // which would hand one vault's slot to another. Length prefixes cannot be
+    // spelled around.
+    return [
+        'vault-slot',
+        address.vaultServiceId,
+        address.accountId,
+        address.vaultId,
+        String(address.recoveryGeneration),
+    ]
+        .map((part) => `${part.length}:${part}`)
+        .join('');
+}
+function contextFor(address, slotId) {
+    return {
+        vaultId: address.vaultId,
+        recoveryGeneration: address.recoveryGeneration,
+        slotId,
+        slotType: 'device',
+        wrapProfile: DEVICE_WRAP_PROFILE,
+        vaultServiceId: address.vaultServiceId,
+        accountId: address.accountId,
+    };
+}
+/**
+ * Mint a device KEK, wrap this vault's VDK under it, and keep both.
+ *
+ * Returns rather than throws when there is no store: a machine without one is
+ * a machine that keeps typing its recovery key, which is the behaviour that
+ * exists today. What it must never become is a machine that writes the VDK to
+ * a file — the design forbids that in the same sentence that asks for the
+ * store, and there is no code path here that could.
+ */
+export async function saveDeviceSlot(address, vdk) {
+    const status = await secureStoreStatus();
+    if (status.kind !== 'available')
+        return { ok: false, reason: describe(status) };
+    const slotId = randomUUID();
+    const kek = randomBytes(32);
+    const wrapped = wrapVdk(kek, vdk, contextFor(address, slotId));
+    const slot = {
+        slotId,
+        kek: kek.toString('base64'),
+        wrappedVdk: wrapped.toString('base64'),
+        wrapProfile: DEVICE_WRAP_PROFILE,
+    };
+    try {
+        await storeSecret(accountFor(address), JSON.stringify(slot));
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+    return { ok: true, slotId };
+}
+/**
+ * Recover the VDK from this machine's slot, or say there is none.
+ *
+ * "None" is a normal answer: it is what a machine looks like before setup, and
+ * what every machine looks like after a re-issuance moves the generation. The
+ * caller falls back to asking for the recovery key — it never guesses.
+ */
+export async function openDeviceSlot(address) {
+    // The store's own state is reported as itself. Collapsing "this platform has
+    // none" into the same answer as "the slot is corrupt" would make every
+    // command on Windows print the warning that is supposed to mean something has
+    // gone wrong (raised in review).
+    const status = await secureStoreStatus();
+    if (status.kind === 'unsupported')
+        return { ok: false, reason: 'no-store', detail: status.reason };
+    if (status.kind === 'locked')
+        return { ok: false, reason: 'store-locked', detail: status.reason };
+    let raw;
+    try {
+        raw = await readSecret(accountFor(address));
+    }
+    catch (err) {
+        // The store was available a moment ago and the read still failed, so this
+        // is the store refusing rather than a bad slot.
+        return { ok: false, reason: 'store-locked', detail: err instanceof Error ? err.message : String(err) };
+    }
+    if (raw === null)
+        return { ok: false, reason: 'no-slot' };
+    let slot;
+    try {
+        slot = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: 'unusable', detail: 'the stored slot is not readable' };
+    }
+    if (typeof slot.slotId !== 'string' ||
+        typeof slot.kek !== 'string' ||
+        typeof slot.wrappedVdk !== 'string' ||
+        slot.wrapProfile !== DEVICE_WRAP_PROFILE) {
+        // A slot written by a version that wrapped differently is refused, not
+        // guessed at. Opening it under today's assumptions would produce bytes
+        // that are not the VDK and fail much later, somewhere less obvious.
+        return { ok: false, reason: 'unusable', detail: 'the stored slot is not a shape this version wraps' };
+    }
+    try {
+        const vdk = unwrapVdk(Buffer.from(slot.kek, 'base64'), Buffer.from(slot.wrappedVdk, 'base64'), contextFor(address, slot.slotId));
+        return { ok: true, vdk };
+    }
+    catch (err) {
+        // The AAD did not match — a slot for another account, deployment, vault or
+        // generation, or a tampered store. Either way this machine cannot open
+        // this vault without the recovery key.
+        return { ok: false, reason: 'unusable', detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Forget this machine's slot, used when a re-issuance retires a generation.
+ *
+ * Returns a result rather than void, and never reports success for a store it
+ * could not reach. Deleting is the one operation where "no store" cannot mean
+ * "nothing to do": a locked keychain still holds the item, and a caller told
+ * the old KEK is gone would carry on believing the old generation can no
+ * longer be opened on this machine. Read can treat absence as an answer;
+ * delete cannot.
+ */
+export async function forgetDeviceSlot(address) {
+    const status = await secureStoreStatus();
+    if (status.kind !== 'available')
+        return { ok: false, reason: describe(status) };
+    try {
+        await deleteSecret(accountFor(address));
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+function describe(status) {
+    return status.kind === 'available' ? 'available' : `${status.kind}: ${status.reason}`;
+}
+/** Exposed for tests that need a VDK without reaching into vault-crypto. */
+export { newVdk };

package/dist/src/filelock.js

@@ -0,0 +1,167 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+// A cross-process lock for the local security files.
+//
+// The attempt ledger and the pending-nonce records are read, decided on, and
+// written back. Inside one process that is a single synchronous stretch; across
+// two it is not. Two CLI invocations started together both read a ledger with
+// budget left, both decide they may proceed, and both send a commitment — so the
+// rule that bounds an attacker's guesses is broken by running the command twice.
+//
+// mkdir is the primitive because it is atomic on every platform this runs on and
+// needs no dependency: it either creates the directory or fails because someone
+// else holds it. A file opened with 'wx' would do as well; a lock built out of
+// "check then create" would not, since that is the very race being closed.
+const RETRY_MS = 15;
+const DEFAULT_TIMEOUT_MS = 5_000;
+// A lock older than this is assumed to belong to a process that died holding it.
+// Long enough that no honest holder is still working, short enough that a crash
+// does not lock a user out of enrolling for the rest of the day.
+const STALE_MS = 30_000;
+export class StaleLock extends Error {
+    path;
+    constructor(path, ageMs) {
+        super(`a lock left behind ${Math.round(ageMs / 1000)}s ago is blocking this command.\n` +
+            `  Another copy may still be running. If none is, remove:\n    ${path}\n` +
+            '  Nothing has been changed; no enrollment attempt was spent.');
+        this.path = path;
+        this.name = 'StaleLock';
+    }
+}
+export class LockTimeout extends Error {
+    constructor(path) {
+        super(`timed out waiting for the lock at ${path}`);
+        this.name = 'LockTimeout';
+    }
+}
+function ownerFile(lockDir) {
+    return join(lockDir, 'owner');
+}
+function heldFor(lockDir, now) {
+    try {
+        return now - statSync(ownerFile(lockDir)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+// A value no other holder will produce. Written into the lock and read back
+// after acquiring, so a holder can tell whether the lock it created is still the
+// lock that exists.
+let tokenCounter = 0;
+function mintToken() {
+    tokenCounter += 1;
+    return `${process.pid}-${tokenCounter}-${randomBytes(8).toString('hex')}`;
+}
+function tryAcquire(lockDir, token) {
+    try {
+        // Without `recursive`, this fails when the directory exists. That failure IS
+        // the mutual exclusion; there is no check-then-create step to lose a race in.
+        mkdirSync(lockDir, { mode: 0o700 });
+    }
+    catch {
+        return false;
+    }
+    // Identifies the holder and carries the mtime that decides staleness.
+    writeFileSync(ownerFile(lockDir), token, { mode: 0o600 });
+    return true;
+}
+function currentToken(lockDir) {
+    try {
+        return readFileSync(ownerFile(lockDir), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run `fn` with exclusive access to `key`, across processes.
+ *
+ * The callback must do the whole read-decide-write, not just the write: holding
+ * the lock only for the write leaves the decision based on a value another
+ * holder has already changed.
+ */
+export function withFileLock(key, fn, options = {}) {
+    const lockDir = `${key}.lock`;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const now = options.now ?? Date.now;
+    mkdirSync(dirname(lockDir), { recursive: true, mode: 0o700 });
+    const deadline = now() + timeoutMs;
+    const token = mintToken();
+    for (;;) {
+        if (tryAcquire(lockDir, token))
+            break;
+        // A lock this old belongs to a process that died holding it. It is NOT
+        // taken over automatically.
+        //
+        // Automatic takeover went wrong twice here, and an earlier version of this
+        // comment claimed it could not be done at all. That was wrong: serialising
+        // the RIGHT TO BREAK with a second O_EXCL marker, and holding that marker
+        // until the main lock has been acquired, closes the window. Dropping the
+        // marker any earlier reopens it.
+        //
+        // It is not used, for a different and smaller reason: by measurement, that
+        // design cannot be told apart from the broken one by any test we can write
+        // without a hook inside the production path — the break-and-create is too
+        // fast to interleave from outside. Failing closed is the version whose
+        // behaviour a test can actually pin.
+        //
+        // So a dead lock stops the command and says what to delete. The section it
+        // guards is a few small file writes, so the window in which a crash can
+        // leave one behind is milliseconds wide; trading a rare manual step for a
+        // race in the mechanism that bounds an attacker's guesses is the wrong way
+        // round.
+        const age = heldFor(lockDir, now());
+        if (age !== null && age > STALE_MS)
+            throw new StaleLock(lockDir, age);
+        if (now() >= deadline)
+            throw new LockTimeout(lockDir);
+        sleepSync(RETRY_MS);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        // Safe to remove unconditionally: nothing takes a lock away from its holder,
+        // so the directory here is the one this call created. An earlier draft
+        // re-checked the token, which only mattered while automatic takeover
+        // existed — a guard that cannot fire reads as protection and is not.
+        rmSync(lockDir, { recursive: true, force: true });
+    }
+}
+// The callers are synchronous CLI paths, so this blocks rather than yielding.
+// Atomics.wait on a private buffer is the portable way to sleep without a busy
+// loop that would burn a core while two invocations contend.
+function sleepSync(ms) {
+    const shared = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(shared, 0, 0, ms);
+}
+// A temp name no other holder can collide with. A fixed `${path}.tmp` is shared
+// by every process writing the same file, so two writers rename over each other
+// and one update is lost — the failure mode being defended against here.
+let counter = 0;
+export function uniqueTempPath(path) {
+    counter += 1;
+    return `${path}.${process.pid}.${counter}.tmp`;
+}
+/**
+ * Read a file, distinguishing "not there" from "could not be read".
+ *
+ * Only ENOENT is absence. Every other error — a permission denied, a directory
+ * where the file should be, an I/O failure, a symlink loop — used to come back
+ * as null, which the ledger reads as an empty budget and the pending store
+ * reads as no reserved nonce. So the rule that a damaged record must never be
+ * mistaken for a missing one, which the parsing layer enforces carefully, was
+ * being broken one layer below it by the read itself.
+ */
+export function readIfPresent(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}