@skrr-ai/cli 0.1.123 → 0.1.125

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

@@ -32,10 +32,31 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import lockfile from 'proper-lockfile';
-import { buildProof as buildDeviceProof, generateDeviceKeyPair, jwkThumbprint, } from './deviceKey.js';
+import { generateDeviceKeyPair, isDevicePublicJwk, jwkThumbprint, signProofWith, } from './deviceKey.js';
+import { softwareEd25519Handle } from './deviceKeyHandle.js';
+import { createHardwareDeviceKey, hardwareDeviceKeyHandle, parseHardwareKeyRecord, probeHardwareDeviceKey, resolveHardwareDeviceKeyHelper, serializeHardwareKeyRecord, HardwareDeviceKeyError, } from './deviceKeyHardware.js';
 import { hasCredEnvelopePathConflict, isCredEnvelopeActive, maybeDecryptOnRead, splitKeyConvergencePolicy, wrapIfActiveOrPassthrough, } from './credentialEnvelopeBridge.js';
-import { consolidateProfileState, profileStateFilePathsToClear, profileStateDir, resolveProfileStateDir, } from './profileStateDir.js';
+import { consolidateProfileState, profileStateFilePathsToClear, profileStateDir, resolveProfileStateDir, RETIRED_COPY_SUFFIX, } from './profileStateDir.js';
+import { rethrowIfLiveStateRefusal } from './liveState.js';
 import { emitAuthTelemetry, getAuthLogger } from './runtime.js';
+import { atomicWrite0600, ensureStateDir, removeStateFile } from './stateFiles.js';
+/**
+ * The `cred_envelope.read.decrypt_failed` hint for the device PRIVATE key
+ * (OSK-20506).
+ *
+ * The envelope's default hint says "signing in again rebuilds it", which is true
+ * of a credential and false of this: `skrr login` never creates or replaces a
+ * device key, and only an interactive daemon sign-in does (it re-pins the new key
+ * on the server). `loadKeypair` hands this to `maybeDecryptOnRead` so the
+ * producer says WHAT failed; a presenter that already prints one device-key line
+ * (the CLI's `recovery_required` notice) recognises it by identity and prints
+ * nothing for the decrypt failure, instead of two lines with two remedies. A
+ * logger that prints every warning, the daemon's, shows this one as written.
+ *
+ * Compared by value by the CLI presenter: change the text and the CLI prints the
+ * credential line again, which `auth-core-init.device-key.spec.ts` catches.
+ */
+export const DEVICE_KEY_UNREADABLE_CREDENTIAL_HINT = 'stored device key is unreadable on this machine — only an interactive daemon sign-in replaces it';
 const PUBLIC_KEY_FILENAME = 'device-public-key.jwk';
 const PRIVATE_KEY_FILENAME = 'device-private-key';
 const ENROLLMENT_MARKER_FILENAME = 'device-enrollment.json';
@@ -85,12 +106,36 @@ function keyFilesStamp(profile) {
     return `${part(publicKeyPath(profile))}|${part(privateKeyPath(profile))}`;
 }
 /**
- * If a key this process could not read has been replaced on disk since, load it. Never
- * creates, replaces or deletes anything: it only picks up what another process wrote
- * under the same lock, which is not the silent replacement the `recoverUnreadable` gate
- * exists to prevent.
+ * What this process last saw of the key files while it held an ACTIVE key. A running daemon
+ * signs with the key it loaded at boot; when an interactive login in another process upgrades
+ * the device key (software to hardware), the server re-pins the machine to the new key and the
+ * old one starts being refused. Without this the daemon would keep signing with it until
+ * someone restarted it, and every refresh in between would fail as a key mismatch.
+ */
+let _activeSeen = null;
+function trackActiveKeyFiles(profile) {
+    try {
+        _activeSeen = { profile, stamp: keyFilesStamp(profile), checkedAt: Date.now() };
+    }
+    catch {
+        _activeSeen = null;
+    }
+}
+/**
+ * Pick up a key another process has written since this one loaded its own. Two cases, one
+ * rule: this only ever READS what another process wrote under the same lock, and it never
+ * creates, replaces or deletes a key, which is what keeps it clear of the silent replacement
+ * the `recoverUnreadable` gate exists to prevent.
+ *
+ *  - A key this process could not read, since replaced by a readable one (the desktop's
+ *    recovery, an interactive login elsewhere).
+ *  - An ACTIVE key, since replaced by a different one (an upgrade to hardware). A change that
+ *    does not load is ignored and not retried until the files change again: the key in
+ *    memory is the one this process was told is pinned, and a half-understood replacement is
+ *    not evidence that it still is not.
  */
 function reloadIfRecovered() {
+    reloadIfActiveKeyChanged();
     if (_state.kind !== 'disabled' || _state.reason !== 'unreadable_key')
         return;
     const seen = _unreadableSeen;
@@ -110,23 +155,69 @@ function reloadIfRecovered() {
     if (stamp === seen.stamp)
         return;
     seen.stamp = stamp;
-    let keypair = null;
+    let key = null;
     try {
-        keypair = loadKeypair(seen.profile);
+        key = loadStoredKey(seen.profile);
     }
     catch {
-        keypair = null;
+        key = null;
     }
-    if (!keypair)
+    if (!key)
         return;
     _state = {
         kind: 'active',
-        keypair,
+        key,
         profile: seen.profile,
-        envelopeProtected: isCredEnvelopeActive(),
+        envelopeProtected: key.custody === 'software' && isCredEnvelopeActive(),
     };
     _unreadableSeen = null;
-    emit('reloaded_after_recovery', true, { profile: seen.profile, thumbprint: keypair.thumbprint });
+    trackActiveKeyFiles(seen.profile);
+    emit('reloaded_after_recovery', true, {
+        profile: seen.profile,
+        thumbprint: key.thumbprint,
+        custody: key.custody,
+    });
+}
+function reloadIfActiveKeyChanged() {
+    const state = _state;
+    const seen = _activeSeen;
+    if (state.kind !== 'active' || !seen || seen.profile !== state.profile || _initializing)
+        return;
+    const now = Date.now();
+    if (now - seen.checkedAt < _unreadableReloadIntervalMs)
+        return;
+    seen.checkedAt = now;
+    let stamp;
+    try {
+        stamp = keyFilesStamp(seen.profile);
+    }
+    catch {
+        return;
+    }
+    if (stamp === seen.stamp)
+        return;
+    seen.stamp = stamp;
+    let key = null;
+    try {
+        key = loadStoredKey(seen.profile);
+    }
+    catch {
+        key = null;
+    }
+    if (!key || key.thumbprint === state.key.thumbprint)
+        return;
+    _state = {
+        kind: 'active',
+        key,
+        profile: seen.profile,
+        envelopeProtected: key.custody === 'software' && isCredEnvelopeActive(),
+    };
+    emit('reloaded_after_key_change', true, {
+        profile: seen.profile,
+        from: state.key.thumbprint,
+        thumbprint: key.thumbprint,
+        custody: key.custody,
+    });
 }
 /**
  * The CLI, daemon, and desktop's short-lived signer resolve the same canonical
@@ -141,7 +232,7 @@ function reloadIfRecovered() {
  */
 async function withDeviceIdentityLock(profile, body) {
     const dir = profileStateDir(profile);
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    ensureStateDir(dir, `take the device identity lock for profile ${profile}`);
     const release = await lockfile.lock(dir, {
         realpath: false,
         lockfilePath: path.join(dir, '.device-identity.lock'),
@@ -210,33 +301,6 @@ function enrollmentMarkerPath(profile) {
 function enrollmentBackoffPath(profile) {
     return path.join(profileConfigDir(profile), ENROLLMENT_BACKOFF_FILENAME);
 }
-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 buf = typeof value === 'string' ? Buffer.from(value, 'utf-8') : value;
-    const fd = fs.openSync(tmp, 'w', 0o600);
-    try {
-        fs.writeSync(fd, buf);
-        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; some platforms reject dir fsync */
-    }
-}
 function emit(eventName, success, metadata, opts = {}) {
     emitAuthTelemetry({
         timestamp: new Date().toISOString(),
@@ -255,17 +319,49 @@ function emit(eventName, success, metadata, opts = {}) {
         }
     }
 }
+/**
+ * The plaintext public record, written for either kind of key. `alg` and
+ * `custody` are for readers that want to know what they are looking at without
+ * opening the private slot (status, support bundles); the loader never trusts
+ * them over the key itself.
+ */
+function writePublicKeyRecord(profile, publicJwk) {
+    atomicWrite0600(publicKeyPath(profile), JSON.stringify({
+        publicJwk,
+        thumbprint: jwkThumbprint(publicJwk),
+        alg: publicJwk.kty === 'EC' ? 'ES256' : 'EdDSA',
+        custody: publicJwk.kty === 'EC' ? 'hardware' : 'software',
+        createdAt: new Date().toISOString(),
+    }), `write the device public key for profile ${profile}`);
+}
+/**
+ * Persist a hardware key. The private slot is written FIRST and is
+ * authoritative: it carries its own public key and thumbprint, so a stop
+ * between the two writes leaves a state `loadStoredKey` repairs (public file
+ * stale, private slot complete) instead of one it must call corrupt (a new
+ * public file beside an old private key). Writing in the other order would turn
+ * a crash during a key upgrade into a lost identity, which is the exact outcome
+ * the upgrade exists to make less likely.
+ *
+ * Deliberately NOT sealed under the credential envelope; see the header of
+ * `deviceKeyHardware.ts`.
+ */
+function persistHardwareKey(profile, record) {
+    atomicWrite0600(privateKeyPath(profile), serializeHardwareKeyRecord(record), `write the hardware device key record for profile ${profile}`);
+    writePublicKeyRecord(profile, record.publicJwk);
+    emit('keypair_persisted', true, {
+        profile,
+        thumbprint: jwkThumbprint(record.publicJwk),
+        custody: 'hardware',
+        envelopeProtected: false,
+    });
+}
 /**
  * Persist a freshly-generated keypair. Public goes plaintext; private
  * goes through `maybeEncryptForWrite` so L12 wraps it when active.
  */
 function persistKeypair(profile, kp) {
-    const publicPayload = JSON.stringify({
-        publicJwk: kp.publicJwk,
-        thumbprint: kp.thumbprint,
-        createdAt: new Date().toISOString(),
-    });
-    atomicWrite0600(publicKeyPath(profile), publicPayload);
+    writePublicKeyRecord(profile, kp.publicJwk);
     // Use the always-fail-open variant — device-identity wants the private
     // key persisted even when the L12 envelope path is inactive (today's
     // default on every platform). The daemon's `credEnvelopeFailClosed`
@@ -273,7 +369,7 @@ function persistKeypair(profile, kp) {
     const privatePlaintext = JSON.stringify(kp.privateJwk);
     const wireForm = wrapIfActiveOrPassthrough(privatePlaintext);
     const envelopeProtected = wireForm !== privatePlaintext;
-    atomicWrite0600(privateKeyPath(profile), wireForm);
+    atomicWrite0600(privateKeyPath(profile), wireForm, `write the device private key for profile ${profile}`);
     emit('keypair_persisted', true, {
         profile,
         thumbprint: kp.thumbprint,
@@ -326,11 +422,17 @@ function readIndependentIdentityFile(file, sealed) {
     }
 }
 /**
- * Load a previously-persisted keypair. Returns null on missing files,
- * decrypt failure, public/private mismatch (file-swap defense), or
+ * Load a previously-persisted device key as a handle. Returns null on missing
+ * files, decrypt failure, public/private mismatch (file-swap defense), or
  * malformed JSON. Throws only on unexpected fs errors; init catches.
+ *
+ * The private-key slot holds one of two things, told apart by what they are
+ * rather than by a flag anyone could forget to set: a hardware record (plain
+ * JSON that names its own algorithm and custody), or a sealed software key.
+ * A build that predates hardware keys reads a hardware record as an inconsistent
+ * keypair, so it fails closed and never replaces a key it does not understand.
  */
-function loadKeypair(profile) {
+function loadStoredKey(profile) {
     const pubPath = publicKeyPath(profile);
     const privPath = privateKeyPath(profile);
     const independent = /^desktop-bg-[a-f0-9]{32}$/i.test(profile);
@@ -344,6 +446,8 @@ function loadKeypair(profile) {
     let storedThumbprint;
     try {
         const parsed = JSON.parse(pubRaw);
+        if (!isDevicePublicJwk(parsed.publicJwk))
+            throw new Error('public key is not a device key');
         publicJwk = parsed.publicJwk;
         storedThumbprint = parsed.thumbprint;
     }
@@ -354,7 +458,32 @@ function loadKeypair(profile) {
         });
         return null;
     }
-    const decryptResult = maybeDecryptOnRead(privRaw);
+    // A reserved independent profile is software-only: its key has a server-pinned
+    // owner and is read through the strict sealed-file reader above.
+    const hardware = independent ? null : parseHardwareKeyRecord(privRaw);
+    if (hardware) {
+        // The private slot is authoritative for a hardware key: the record carries
+        // its own public key and proves its own thumbprint. A public file that
+        // disagrees is a commit that stopped between its two writes (see
+        // `persistHardwareKey`), not a swapped file, so repair it from the record.
+        if (jwkThumbprint(hardware.publicJwk) !== jwkThumbprint(publicJwk)) {
+            try {
+                writePublicKeyRecord(profile, hardware.publicJwk);
+                emit('public_key_repaired_from_hardware_record', true, { profile }, { logLevel: 'info' });
+            }
+            catch (err) {
+                emit('public_key_unreadable', false, { profile, message: err?.message ?? 'unknown' });
+                return null;
+            }
+        }
+        return hardwareDeviceKeyHandle(hardware);
+    }
+    // The device key's own hint, so a failure here is labelled as the DEVICE key and
+    // the CLI prints one device-key line instead of the generic credential one
+    // ("run `skrr login`", which cannot repair a device key).
+    const decryptResult = maybeDecryptOnRead(privRaw, {
+        unreadableHint: DEVICE_KEY_UNREADABLE_CREDENTIAL_HINT,
+    });
     if (decryptResult.plaintext === null) {
         emit('private_key_decrypt_failed', false, { profile });
         return null;
@@ -372,8 +501,10 @@ function loadKeypair(profile) {
         return null;
     }
     // public.x must match private.x — any mismatch indicates a partial
-    // write race, manual edit, or attacker swapping one of the files.
-    if (publicJwk.x !== privateJwk.x) {
+    // write race, manual edit, or attacker swapping one of the files. (A software
+    // key is Ed25519 and so has no `y`; an EC public key beside an Ed25519
+    // private one fails the `kty` test below for the same reason.)
+    if (publicJwk.kty !== 'OKP' || publicJwk.x !== privateJwk.x) {
         emit('keypair_inconsistent', false, { profile });
         return null;
     }
@@ -387,11 +518,16 @@ function loadKeypair(profile) {
             recomputed,
         });
     }
-    return {
-        publicJwk,
-        privateJwk,
-        thumbprint: recomputed,
-    };
+    try {
+        return softwareEd25519Handle({ publicJwk, privateJwk, thumbprint: recomputed });
+    }
+    catch (err) {
+        emit('private_key_malformed', false, {
+            profile,
+            message: err?.message ?? 'unknown',
+        });
+        return null;
+    }
 }
 /**
  * Identity of a device-identity directory: the thumbprint of the PLAINTEXT
@@ -405,7 +541,7 @@ function loadKeypair(profile) {
 function deviceIdentityOf(dir) {
     try {
         const parsed = JSON.parse(fs.readFileSync(path.join(dir, PUBLIC_KEY_FILENAME), 'utf-8'));
-        if (!parsed.publicJwk || typeof parsed.publicJwk.x !== 'string')
+        if (!isDevicePublicJwk(parsed.publicJwk))
             return null;
         return jwkThumbprint(parsed.publicJwk);
     }
@@ -473,6 +609,7 @@ async function consolidateDeviceIdentity(profile) {
         });
     }
     catch (err) {
+        rethrowIfLiveStateRefusal(err);
         emit('path_consolidation.failed', false, {
             profile,
             message: err?.message ?? 'unknown',
@@ -515,6 +652,7 @@ export async function initDeviceIdentity(profile, options = {}) {
         if (_state.kind === 'uninit')
             await initDeviceIdentityLocked(profile, options);
     }).catch((err) => {
+        rethrowIfLiveStateRefusal(err);
         _state = { kind: 'disabled', reason: 'init_failed' };
         emit('init_failed', false, {
             profile,
@@ -539,23 +677,25 @@ async function initDeviceIdentityLocked(profile, options = {}) {
     const independent = /^desktop-bg-[a-f0-9]{32}$/i.test(profile);
     if (!independent)
         await consolidateDeviceIdentity(profile);
-    let keypair = null;
+    let stored = null;
     try {
-        keypair = loadKeypair(profile);
+        stored = loadStoredKey(profile);
     }
     catch (err) {
         emit('load_failed', false, {
             profile,
             message: err?.message ?? 'unknown',
         });
-        keypair = null;
+        stored = null;
     }
-    if (keypair) {
-        const envelopeProtected = isCredEnvelopeActive();
-        _state = { kind: 'active', keypair, profile, envelopeProtected };
+    if (stored) {
+        const envelopeProtected = stored.custody === 'software' && isCredEnvelopeActive();
+        _state = { kind: 'active', key: stored, profile, envelopeProtected };
+        trackActiveKeyFiles(profile);
         emit('active', true, {
             profile,
-            thumbprint: keypair.thumbprint,
+            thumbprint: stored.thumbprint,
+            custody: stored.custody,
             envelopeProtected,
             regenerated: false,
         });
@@ -599,6 +739,7 @@ async function initDeviceIdentityLocked(profile, options = {}) {
         persistResult = persistKeypair(profile, fresh);
     }
     catch (err) {
+        rethrowIfLiveStateRefusal(err);
         _state = { kind: 'disabled', reason: 'persist_failed' };
         emit('persist_failed', false, {
             profile,
@@ -606,15 +747,30 @@ async function initDeviceIdentityLocked(profile, options = {}) {
         });
         return;
     }
+    let freshKey;
+    try {
+        freshKey = softwareEd25519Handle(fresh);
+    }
+    catch (err) {
+        _state = { kind: 'disabled', reason: 'init_failed' };
+        emit('init_failed', false, {
+            profile,
+            reason: 'keygen_threw',
+            message: err?.message ?? 'unknown',
+        });
+        return;
+    }
     _state = {
         kind: 'active',
-        keypair: fresh,
+        key: freshKey,
         profile,
         envelopeProtected: persistResult.envelopeProtected,
     };
+    trackActiveKeyFiles(profile);
     emit('active', true, {
         profile,
         thumbprint: fresh.thumbprint,
+        custody: 'software',
         envelopeProtected: persistResult.envelopeProtected,
         regenerated: true,
     });
@@ -631,13 +787,22 @@ export async function resetDeviceIdentity(opts) {
         // Every location, not just the resolved one. A reset that cleared only the
         // canonical copy would leave the pre-consolidation copy for the next init to
         // adopt — a deleted device key that reappears.
-        const targets = [PUBLIC_KEY_FILENAME, PRIVATE_KEY_FILENAME].flatMap((name) => profileStateFilePathsToClear(opts.profile, name));
+        //
+        // The retired copy an upgrade keeps is part of the identity: a logout that left
+        // it would leave a sealed device key behind the person asked to be rid of.
+        const targets = [
+            ...[PUBLIC_KEY_FILENAME, PRIVATE_KEY_FILENAME].flatMap((name) => profileStateFilePathsToClear(opts.profile, name)),
+            ...retiredKeyCopies(opts.profile, PUBLIC_KEY_FILENAME),
+            ...retiredKeyCopies(opts.profile, PRIVATE_KEY_FILENAME),
+            pendingHardwareKeyPath(opts.profile),
+        ];
         await withDeviceIdentityLock(opts.profile, async () => {
             for (const p of targets) {
                 try {
-                    fs.unlinkSync(p);
+                    removeStateFile(p, `delete the device key file ${path.basename(p)}`);
                 }
                 catch (err) {
+                    rethrowIfLiveStateRefusal(err);
                     if (err.code !== 'ENOENT') {
                         emit('clear_failed', false, {
                             profile: opts.profile,
@@ -651,6 +816,212 @@ export async function resetDeviceIdentity(opts) {
     }
     _state = { kind: 'uninit' };
     _unreadableSeen = null;
+    _activeSeen = null;
+}
+/**
+ * Create a hardware key candidate if this machine can hold one and does not
+ * already. Never throws and never touches disk, so an interactive sign-in can
+ * call it unconditionally and fall back to the key it has on any answer but ok.
+ */
+export async function prepareHardwareKeyCandidate(profile) {
+    if (/^desktop-bg-[a-f0-9]{32}$/i.test(profile))
+        return { ok: false, reason: 'independent_profile' };
+    if (_state.kind === 'active' && _state.key.custody === 'hardware') {
+        return { ok: false, reason: 'already_hardware' };
+    }
+    const capability = await probeHardwareDeviceKey();
+    if (!capability.available)
+        return { ok: false, reason: 'unavailable', capability };
+    try {
+        const { record, handle } = await createHardwareDeviceKey();
+        return { ok: true, candidate: { key: handle, record } };
+    }
+    catch (err) {
+        emit('hardware_key_create_failed', false, {
+            profile,
+            ...(err instanceof HardwareDeviceKeyError ? { hardwareFailure: err.code } : {}),
+            message: err?.message ?? 'unknown',
+        });
+        return { ok: false, reason: 'create_failed', message: err?.message ?? 'unknown' };
+    }
+}
+/** Sign a request with a candidate (the upgrade's sign-in proof). Null on failure, like `signServerRequest`. */
+export async function signWithCandidate(candidate, opts) {
+    try {
+        return await signProofWith(candidate.key, opts);
+    }
+    catch (err) {
+        emit('sign_failed', false, {
+            thumbprint: candidate.key.thumbprint,
+            custody: 'hardware',
+            candidate: true,
+            method: opts.method,
+            ...(err instanceof HardwareDeviceKeyError ? { hardwareFailure: err.code } : {}),
+            message: err?.message ?? 'unknown',
+        });
+        return null;
+    }
+}
+/** The retired copies of a profile's keys: `<file>.retired.<stamp>`, newest last. */
+function retiredKeyCopies(profile, filename) {
+    const dir = path.dirname(filename === PUBLIC_KEY_FILENAME ? publicKeyPath(profile) : privateKeyPath(profile));
+    const prefix = `${filename}${RETIRED_COPY_SUFFIX}.`;
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((name) => name.startsWith(prefix))
+            .sort()
+            .map((name) => path.join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Keep the software key an upgrade is about to replace, as a copy. The pin the
+ * server holds moves with the sign-in, but a bug in that move (or a server that
+ * accepted the sign-in and did not re-pin) would leave a daemon whose every
+ * refresh is refused as a key mismatch, with no way back. One retired pair is
+ * kept (the newest) and a logout deletes it with the rest of the profile's keys.
+ * Best effort: a copy that cannot be written must not block the upgrade of a
+ * key that is, at this point, already proven by the server.
+ */
+function retireSoftwareKey(profile) {
+    try {
+        const priv = privateKeyPath(profile);
+        const raw = fs.readFileSync(priv, 'utf-8');
+        if (parseHardwareKeyRecord(raw))
+            return; // already hardware: nothing software to keep
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        atomicWrite0600(`${priv}${RETIRED_COPY_SUFFIX}.${stamp}`, raw, `keep the replaced software device key for profile ${profile}`);
+        try {
+            atomicWrite0600(`${publicKeyPath(profile)}${RETIRED_COPY_SUFFIX}.${stamp}`, fs.readFileSync(publicKeyPath(profile), 'utf-8'), `keep the replaced software device public key for profile ${profile}`);
+        }
+        catch (err) {
+            rethrowIfLiveStateRefusal(err);
+            /* the private copy is the one that matters; the public key derives from it */
+        }
+        for (const filename of [PRIVATE_KEY_FILENAME, PUBLIC_KEY_FILENAME]) {
+            for (const stale of retiredKeyCopies(profile, filename).slice(0, -1)) {
+                try {
+                    removeStateFile(stale, `prune a retired device key copy for profile ${profile}`);
+                }
+                catch (err) {
+                    rethrowIfLiveStateRefusal(err);
+                    /* a stale copy that will not go costs a few hundred bytes */
+                }
+            }
+        }
+    }
+    catch (err) {
+        emit('retire_software_key_failed', false, { profile, message: err?.message ?? 'unknown' });
+    }
+}
+/**
+ * Make a candidate this profile's device identity. Call it only after the
+ * server has accepted a sign-in proven with `candidate`: until then the software
+ * key is the identity the server pins, and replacing it early is the failure
+ * this API exists to prevent.
+ *
+ * Under the identity lock, in the order that survives a crash: retire the old
+ * key, write the hardware record (authoritative), then the public file, then
+ * clear the enrollment marker (it records the OLD thumbprint and would otherwise
+ * short-circuit every later enrollment as already done).
+ */
+export async function commitDeviceKeyCandidate(profile, candidate) {
+    if (_initializing)
+        await _initializing;
+    await withDeviceIdentityLock(profile, async () => {
+        commitRecordLocked(profile, candidate.record, candidate.key);
+    });
+}
+/** The commit itself; the caller holds the identity lock. */
+function commitRecordLocked(profile, record, key) {
+    retireSoftwareKey(profile);
+    persistHardwareKey(profile, record);
+    clearEnrollmentMarker(profile);
+    removePendingHardwareKey(profile);
+    _state = { kind: 'active', key, profile, envelopeProtected: false };
+    _unreadableSeen = null;
+    trackActiveKeyFiles(profile);
+    emit('upgraded_to_hardware', true, {
+        profile,
+        thumbprint: key.thumbprint,
+        custody: 'hardware',
+    });
+}
+// ---------------------------------------------------------------------------
+// A candidate that has to outlive its process
+// ---------------------------------------------------------------------------
+//
+// The desktop signs the sign-in's proof in `skrrd device-proof` (one process),
+// POSTs it from the app (another), and only then knows whether the server
+// accepted it. The candidate therefore has to be settled by a LATER invocation,
+// so it is parked in a pending file until then. That costs nothing in safety:
+// the pending file holds a Secure Enclave blob, which is useless anywhere but
+// this machine, and an abandoned one is never read as an identity (only the two
+// anchor files are), expires on its own, and is deleted by the next attempt and
+// by a logout.
+const PENDING_HARDWARE_FILENAME = 'device-key.pending';
+/** A sign-in that takes longer than this has been abandoned; its pending key is not committed. */
+export const PENDING_HARDWARE_KEY_MAX_AGE_MS = 10 * 60 * 1000;
+function pendingHardwareKeyPath(profile) {
+    return path.join(profileConfigDir(profile), PENDING_HARDWARE_FILENAME);
+}
+function removePendingHardwareKey(profile) {
+    try {
+        removeStateFile(pendingHardwareKeyPath(profile), `remove the pending hardware key for profile ${profile}`);
+    }
+    catch (err) {
+        rethrowIfLiveStateRefusal(err);
+        if (err.code !== 'ENOENT') {
+            emit('pending_hardware_key_clear_failed', false, { profile, message: err?.message ?? 'unknown' });
+        }
+    }
+}
+/** Park a candidate so a later process can commit or discard it. Replaces any earlier one. */
+export async function persistPendingHardwareKey(profile, candidate) {
+    await withDeviceIdentityLock(profile, async () => {
+        atomicWrite0600(pendingHardwareKeyPath(profile), serializeHardwareKeyRecord(candidate.record), `park a pending hardware key for profile ${profile}`);
+    });
+}
+/**
+ * Make the parked candidate this profile's identity, if it is the one the caller
+ * proved the sign-in with (`thumbprint`) and it is not stale. Anything else
+ * commits nothing: the software key stays the identity, and the answer says why.
+ */
+export async function commitPendingHardwareKey(profile, thumbprint) {
+    if (_initializing)
+        await _initializing;
+    return withDeviceIdentityLock(profile, async () => {
+        const file = pendingHardwareKeyPath(profile);
+        let raw;
+        let modifiedAt;
+        try {
+            raw = fs.readFileSync(file, 'utf-8');
+            modifiedAt = fs.statSync(file).mtimeMs;
+        }
+        catch {
+            return 'no_pending';
+        }
+        const record = parseHardwareKeyRecord(raw);
+        if (!record)
+            return 'unreadable';
+        if (Date.now() - modifiedAt > PENDING_HARDWARE_KEY_MAX_AGE_MS) {
+            removePendingHardwareKey(profile);
+            return 'expired';
+        }
+        if (jwkThumbprint(record.publicJwk) !== thumbprint)
+            return 'mismatch';
+        commitRecordLocked(profile, record, hardwareDeviceKeyHandle(record));
+        return 'committed';
+    });
+}
+/** Drop the parked candidate (the sign-in failed or was refused). Idempotent. */
+export async function discardPendingHardwareKey(profile) {
+    await withDeviceIdentityLock(profile, async () => {
+        removePendingHardwareKey(profile);
+    });
 }
 /** True iff init has completed and a keypair is in memory. */
 export function isDeviceIdentityActive() {
@@ -666,7 +1037,12 @@ export function getDevicePublicKey() {
     reloadIfRecovered();
     if (_state.kind !== 'active')
         return null;
-    return { jwk: _state.keypair.publicJwk, thumbprint: _state.keypair.thumbprint };
+    return {
+        jwk: _state.key.publicJwk,
+        thumbprint: _state.key.thumbprint,
+        alg: _state.key.alg,
+        custody: _state.key.custody,
+    };
 }
 /**
  * Operator-readable summary of device-identity state. Used by
@@ -680,28 +1056,63 @@ export function describeDeviceIdentityState() {
     if (_state.kind === 'active') {
         return {
             kind: 'active',
-            thumbprint: _state.keypair.thumbprint,
+            thumbprint: _state.key.thumbprint,
             profile: _state.profile,
             envelopeProtected: _state.envelopeProtected,
+            alg: _state.key.alg,
+            custody: _state.key.custody,
+            canSign: _state.key.custody === 'software' ? true : resolveHardwareDeviceKeyHelper() !== null,
         };
     }
     return { kind: 'uninit' };
 }
+/**
+ * What a profile's device key IS, read from its plaintext public record alone. For
+ * `status`, which is a different process from the daemon and may run while the
+ * daemon is stopped: it opens nothing, needs no envelope key and writes nothing, so
+ * it answers even when the private half is unreadable. Not evidence the key can be
+ * used (only `describeDeviceIdentityState` in the process that loaded it says that);
+ * evidence of what kind of key the profile has, which nothing else showed.
+ */
+export function describeStoredDeviceKey(profile) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(publicKeyPath(profile), 'utf-8'));
+        if (!isDevicePublicJwk(parsed.publicJwk))
+            return { stored: false };
+        const alg = parsed.publicJwk.kty === 'EC' ? 'ES256' : 'EdDSA';
+        const custody = alg === 'ES256' ? 'hardware' : 'software';
+        return {
+            stored: true,
+            alg,
+            custody,
+            thumbprint: jwkThumbprint(parsed.publicJwk),
+            canSign: custody === 'software' ? true : resolveHardwareDeviceKeyHelper() !== null,
+        };
+    }
+    catch {
+        return { stored: false };
+    }
+}
 /**
  * Sign an outgoing request with the device key. Returns the JWS Compact
  * Serialization, or null when device identity is not active. NEVER
  * throws — a failed sign returns null and emits a telemetry event so
  * the caller can fall back to bearer-only auth without an outage.
  *
+ * Asynchronous because a hardware key signs in a helper process. A software key
+ * resolves on the next microtask, so a caller that awaits pays nothing it can
+ * measure; a caller that could not await could not have a hardware key.
+ *
  * Shape matches `DeviceProofSigner` from `./refresh.ts` so the function
  * passes directly into `refreshDaemonToken`'s `signRequestProof` slot.
  */
-export function signServerRequest(opts) {
+export async function signServerRequest(opts) {
     reloadIfRecovered();
-    if (_state.kind !== 'active')
+    const state = _state;
+    if (state.kind !== 'active')
         return null;
     try {
-        return buildDeviceProof(_state.keypair.privateJwk, _state.keypair.publicJwk, {
+        return await signProofWith(state.key, {
             method: opts.method,
             url: opts.url,
             refreshToken: opts.refreshToken,
@@ -710,9 +1121,13 @@ export function signServerRequest(opts) {
     }
     catch (err) {
         emit('sign_failed', false, {
-            profile: _state.profile,
-            thumbprint: _state.keypair.thumbprint,
+            profile: state.profile,
+            thumbprint: state.key.thumbprint,
+            custody: state.key.custody,
             method: opts.method,
+            // A hardware failure names its cause (helper missing, timed out, key
+            // mismatch) so a status line can say what to do about it.
+            ...(err instanceof HardwareDeviceKeyError ? { hardwareFailure: err.code } : {}),
             message: err?.message ?? 'unknown',
         });
         return null;
@@ -735,9 +1150,10 @@ export function __enrollmentBackoffPathForTest(profile) {
 export function clearEnrollmentMarker(profile) {
     for (const markerPath of [enrollmentMarkerPath(profile), enrollmentBackoffPath(profile)]) {
         try {
-            fs.unlinkSync(markerPath);
+            removeStateFile(markerPath, `delete the enrollment file ${path.basename(markerPath)}`);
         }
         catch (err) {
+            rethrowIfLiveStateRefusal(err);
             if (err.code !== 'ENOENT') {
                 emit('enrollment_marker_clear_failed', false, {
                     profile,
@@ -769,7 +1185,7 @@ export async function enrollWithServer(opts) {
         return { enrolled: false, reason: 'not_active' };
     }
     const profile = _state.profile;
-    const keypair = _state.keypair;
+    const key = _state.key;
     const markerPath = enrollmentMarkerPath(profile);
     const backoffPath = enrollmentBackoffPath(profile);
     try {
@@ -785,33 +1201,48 @@ export async function enrollWithServer(opts) {
         const retryAfter = Date.parse(raw.retryAfter || '');
         if (raw.serverUrl === serverUrl &&
             raw.machineUuid === machineUuid &&
-            raw.thumbprint === keypair.thumbprint &&
+            raw.thumbprint === key.thumbprint &&
             Number.isFinite(retryAfter) &&
             retryAfter > Date.now()) {
             return { enrolled: false, reason: 'backoff_active' };
         }
-        fs.unlinkSync(backoffPath);
+        removeStateFile(backoffPath, 'delete the stale enrollment backoff');
     }
     catch (err) {
         if (err.code !== 'ENOENT') {
-            // A corrupt/stale marker must never suppress enrollment indefinitely.
+            // A corrupt/stale marker must never suppress enrollment indefinitely. A refusal from the
+            // first delete above lands here too, and is asked again by this one, so this is the
+            // single place it is rethrown.
             try {
-                fs.unlinkSync(backoffPath);
+                removeStateFile(backoffPath, 'delete the corrupt enrollment backoff');
             }
-            catch {
+            catch (clearErr) {
+                rethrowIfLiveStateRefusal(clearErr);
                 /* best-effort */
             }
         }
     }
     const base = serverUrl.replace(/\/+$/, '');
     const htu = `${base}/api/daemon-resources/enroll-device-key`;
-    const proofJws = buildDeviceProof(keypair.privateJwk, keypair.publicJwk, {
-        method: 'POST',
-        url: htu,
-    });
+    let proofJws;
+    try {
+        proofJws = await signProofWith(key, { method: 'POST', url: htu });
+    }
+    catch (err) {
+        // A key that cannot sign (a hardware key whose helper is missing) is not a
+        // network failure and not the server's to hear about.
+        const message = err?.message ?? 'unknown';
+        emit('enrollment_sign_failed', false, { profile, thumbprint: key.thumbprint, custody: key.custody, message });
+        return { enrolled: false, reason: 'not_active', message };
+    }
+    // `publicJwkX` is the original wire field and only ever described an Ed25519
+    // point, so an ES256 key leaves it out rather than send a coordinate an older
+    // server would read as the wrong curve. `publicJwk` is the whole key; a server
+    // that understands it prefers it, and the proof's own header carries it too.
     const body = JSON.stringify({
         machineUuid,
-        publicJwkX: keypair.publicJwk.x,
+        ...(key.publicJwk.kty === 'OKP' ? { publicJwkX: key.publicJwk.x } : {}),
+        publicJwk: key.publicJwk,
         proofJws,
     });
     // 10-second bound — enrollment is best-effort at startup.
@@ -834,7 +1265,7 @@ export async function enrollWithServer(opts) {
         const message = err?.message ?? 'unknown';
         emit('enrollment_network_error', false, {
             profile,
-            thumbprint: keypair.thumbprint,
+            thumbprint: key.thumbprint,
             serverUrl,
             message,
         });
@@ -885,7 +1316,7 @@ export async function enrollWithServer(opts) {
         }
         const pinnedToOtherKey = response.status === 409 &&
             enrolledThumbprint !== null &&
-            enrolledThumbprint !== keypair.thumbprint;
+            enrolledThumbprint !== key.thumbprint;
         const keyPinnedElsewhere = response.status === 409 && conflictCode === 'ENROLLMENT_DUPLICATE_KEY';
         const isBenignRejection = (response.status === 404 && responseText.includes('DAEMON_NOT_FOUND')) ||
             (response.status === 403 && responseText.includes('OPAQUE_AUTH_REFUSED')) ||
@@ -893,7 +1324,7 @@ export async function enrollWithServer(opts) {
         if (pinnedToOtherKey) {
             emit('enrollment_key_mismatch', false, {
                 profile,
-                thumbprint: keypair.thumbprint,
+                thumbprint: key.thumbprint,
                 enrolledThumbprint,
                 serverUrl,
                 message: 'this machine is registered with a different device key than this profile signs ' +
@@ -906,11 +1337,12 @@ export async function enrollWithServer(opts) {
                 atomicWrite0600(backoffPath, JSON.stringify({
                     serverUrl,
                     machineUuid,
-                    thumbprint: keypair.thumbprint,
+                    thumbprint: key.thumbprint,
                     retryAfter: new Date(Date.now() + DAEMON_NOT_FOUND_BACKOFF_MS).toISOString(),
-                }));
+                }), 'write the enrollment backoff');
             }
             catch (err) {
+                rethrowIfLiveStateRefusal(err);
                 emit('enrollment_backoff_write_failed', false, {
                     profile,
                     message: err?.message ?? 'unknown',
@@ -919,7 +1351,7 @@ export async function enrollWithServer(opts) {
         }
         emit('enrollment_rejected', false, {
             profile,
-            thumbprint: keypair.thumbprint,
+            thumbprint: key.thumbprint,
             serverUrl,
             status: response.status,
             body: responseText,
@@ -934,25 +1366,28 @@ export async function enrollWithServer(opts) {
     const marker = JSON.stringify({
         enrolledAt: new Date().toISOString(),
         serverUrl,
-        thumbprint: keypair.thumbprint,
+        thumbprint: key.thumbprint,
         machineUuid,
     });
     try {
-        atomicWrite0600(markerPath, marker);
+        atomicWrite0600(markerPath, marker, 'write the enrollment marker');
     }
     catch (err) {
+        rethrowIfLiveStateRefusal(err);
         // Non-fatal — server enrolled us; we may re-POST next run, which
         // the server handles idempotently.
         emit('enrollment_marker_write_failed', false, {
             profile,
-            thumbprint: keypair.thumbprint,
+            thumbprint: key.thumbprint,
             message: err?.message ?? 'unknown',
         });
     }
     try {
-        fs.unlinkSync(backoffPath);
+        removeStateFile(backoffPath, 'delete the enrollment backoff');
     }
     catch (err) {
+        // Not a place a refusal can arise: the marker written just above lives in the same
+        // directory, and a refusal there has already ended this function.
         if (err.code !== 'ENOENT') {
             emit('enrollment_backoff_clear_failed', false, {
                 profile,
@@ -962,8 +1397,8 @@ export async function enrollWithServer(opts) {
     }
     emit('enrolled_with_server', true, {
         profile,
-        thumbprint: keypair.thumbprint,
+        thumbprint: key.thumbprint,
         serverUrl,
     });
-    return { enrolled: true, thumbprint: keypair.thumbprint };
+    return { enrolled: true, thumbprint: key.thumbprint };
 }