@skrr-ai/cli 0.1.123 → 0.1.125

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

@@ -49,7 +49,9 @@ var import_node_fs = __toESM(require("node:fs"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var import_proper_lockfile = __toESM(require("proper-lockfile"), 1);
 var import_runtime = require("./runtime.js");
+var import_liveState = require("./liveState.js");
 var import_refreshClassification = require("./refreshClassification.js");
+var import_stateFiles = require("./stateFiles.js");
 var import_types = require("./types.js");
 const LOCK_STALE_MS = 5e3;
 const LOCK_RETRY_MS = 100;
@@ -125,9 +127,9 @@ async function withAuthLock(body, daemonId) {
   const lockPath = authLockPath();
   const dir = import_node_path.default.dirname(lockPath);
   if (!import_node_fs.default.existsSync(dir))
-    import_node_fs.default.mkdirSync(dir, { recursive: true });
+    (0, import_stateFiles.ensureStateDir)(dir, "create the auth lock directory", null);
   if (!import_node_fs.default.existsSync(lockPath)) {
-    import_node_fs.default.writeFileSync(lockPath, "", { mode: 384 });
+    (0, import_stateFiles.writeStateFile)(lockPath, "", { mode: 384 }, "create the auth lock");
   }
   const acquireStart = Date.now();
   (0, import_runtime.emitAuthTelemetry)({
@@ -283,7 +285,7 @@ async function doRefresh(serverUrl, currentRefreshToken, daemonId, options = {})
     body.machineUuid = options.machineUuid;
   }
   let proofAttached = false;
-  function buildRequestInit() {
+  async function buildRequestInit() {
     proofAttached = false;
     const headers = { "Content-Type": "application/json" };
     if (options.origin) {
@@ -292,7 +294,7 @@ async function doRefresh(serverUrl, currentRefreshToken, daemonId, options = {})
     __refreshDiagnostics.requestAttemptCount += 1;
     if (options.signRequestProof) {
       try {
-        const proof = options.signRequestProof({
+        const proof = await options.signRequestProof({
           method: "POST",
           url,
           refreshToken: currentRefreshToken
@@ -315,7 +317,7 @@ async function doRefresh(serverUrl, currentRefreshToken, daemonId, options = {})
   }
   let response;
   try {
-    response = await fetch(url, buildRequestInit());
+    response = await fetch(url, await buildRequestInit());
     (0, import_runtime.notifyResponseObserver)(response);
   } catch (err) {
     log.warn(`[auth/refresh] network error: ${err?.message}`);
@@ -501,11 +503,10 @@ function persistReauthState(state) {
   try {
     const dir = import_node_path.default.dirname(flagPath);
     if (!import_node_fs.default.existsSync(dir))
-      import_node_fs.default.mkdirSync(dir, { recursive: true, mode: 448 });
-    import_node_fs.default.writeFileSync(flagPath, JSON.stringify(state, null, 2) + "\n", {
-      mode: 384
-    });
+      (0, import_stateFiles.ensureStateDir)(dir, "create the re-auth latch directory");
+    (0, import_stateFiles.writeStateFile)(flagPath, JSON.stringify(state, null, 2) + "\n", { mode: 384 }, "write the re-auth latch");
   } catch (err) {
+    (0, import_liveState.rethrowIfLiveStateRefusal)(err);
     log.debug(`[auth/refresh] failed to persist reauth flag: ${err?.message}`);
   }
 }
@@ -532,8 +533,9 @@ function clearReauthState() {
   try {
     const flagPath = reauthFlagPath();
     if (import_node_fs.default.existsSync(flagPath))
-      import_node_fs.default.unlinkSync(flagPath);
+      (0, import_stateFiles.removeStateFile)(flagPath, "clear the re-auth latch");
   } catch (err) {
+    (0, import_liveState.rethrowIfLiveStateRefusal)(err);
     log.debug(`[auth/refresh] clearReauthState: ${err?.message}`);
   }
 }

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/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;

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/stateFiles.js

@@ -0,0 +1,89 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var stateFiles_exports = {};
+__export(stateFiles_exports, {
+  atomicWrite0600: () => atomicWrite0600,
+  ensureStateDir: () => ensureStateDir,
+  removeStateFile: () => removeStateFile,
+  renameStateFile: () => renameStateFile,
+  writeStateFile: () => writeStateFile
+});
+module.exports = __toCommonJS(stateFiles_exports);
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+var import_liveState = require("./liveState.js");
+function ensureStateDir(dir, what, mode = 448) {
+  (0, import_liveState.assertMayMutateLiveState)(dir, what);
+  import_node_fs.default.mkdirSync(dir, mode === null ? { recursive: true } : { recursive: true, mode });
+}
+function atomicWrite0600(target, value, what) {
+  (0, import_liveState.assertMayMutateLiveState)(target, what);
+  const dir = import_node_path.default.dirname(target);
+  import_node_fs.default.mkdirSync(dir, { recursive: true, mode: 448 });
+  const tmp = `${target}.tmp.${process.pid}.${Date.now()}`;
+  const buf = typeof value === "string" ? Buffer.from(value, "utf-8") : value;
+  const fd = import_node_fs.default.openSync(tmp, "w", 384);
+  try {
+    import_node_fs.default.writeSync(fd, buf);
+    import_node_fs.default.fsyncSync(fd);
+  } finally {
+    import_node_fs.default.closeSync(fd);
+  }
+  import_node_fs.default.renameSync(tmp, target);
+  try {
+    const dirFd = import_node_fs.default.openSync(dir, "r");
+    try {
+      import_node_fs.default.fsyncSync(dirFd);
+    } finally {
+      import_node_fs.default.closeSync(dirFd);
+    }
+  } catch {
+  }
+}
+function writeStateFile(target, data, options, what) {
+  (0, import_liveState.assertMayMutateLiveState)(target, what);
+  import_node_fs.default.writeFileSync(target, data, options);
+}
+function removeStateFile(target, what) {
+  (0, import_liveState.assertMayMutateLiveState)(target, what);
+  import_node_fs.default.unlinkSync(target);
+}
+function renameStateFile(from, to, what) {
+  (0, import_liveState.assertMayMutateLiveState)(from, what);
+  (0, import_liveState.assertMayMutateLiveState)(to, what);
+  import_node_fs.default.renameSync(from, to);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  atomicWrite0600,
+  ensureStateDir,
+  removeStateFile,
+  renameStateFile,
+  writeStateFile
+});

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

@@ -161,7 +161,11 @@ export type DaemonSupervisor = 'desktop' | 'service';
 export declare function daemonSignInRemedy(opts?: {
     /** How the daemon is run; absent when the caller cannot tell. */
     supervisor?: DaemonSupervisor;
-    /** The exact `skrrd … login` for this profile, when the daemon knows it. */
+    /**
+     * The exact login command for this profile (`skrrd … login`, or
+     * `skrr daemon login --profile …`), when the caller knows it. Used when the
+     * supervisor is `service` or unknown; a desktop-hosted daemon is never told one.
+     */
     loginCommand?: string;
     /** The refusal was DEVICE_PROOF_PIN_MISMATCH: say that a sign-in re-pins. */
     repinsDeviceKey?: boolean;

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

@@ -167,7 +167,10 @@ export function daemonSignInRemedy(opts = {}) {
         const login = opts.loginCommand ? `\`${opts.loginCommand}\`` : '`skrr daemon login`';
         return `run ${login}${repin ? ' — an interactive login re-pins the device key' : ''}`;
     }
+    // A caller that cannot tell who runs the daemon may still know which profile it
+    // is on: `skrr daemon login` with no `--profile` signs the DEFAULT daemon in
+    // (OSK-16435), so the command it names is the one it was given.
     return ('sign the daemon in again on the machine running it: if the Skrr desktop app runs it, quit ' +
-        'and reopen the app; otherwise run `skrr daemon login`' +
+        `and reopen the app; otherwise run \`${opts.loginCommand ?? 'skrr daemon login'}\`` +
         (repin ? ' (either one re-pins the device key)' : ''));
 }

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

@@ -47,8 +47,10 @@ import lockfile from 'proper-lockfile';
 import { buildCredentialAad, decrypt as credEnvelopeDecrypt, deserialize as credEnvelopeDeserialize, encrypt as credEnvelopeEncrypt, isEnvelopeString as isCredEnvelopeString, generateDek, serialize as credEnvelopeSerialize, } from './credentialEnvelope.js';
 import { getKekStrategy, KekUnavailableError, zeroizeKekCaches, } from './kek/index.js';
 import { consolidateProfileState, profileStateDir, profileStateFilePathsToClear, resolveProfileStateFile, RETIRED_COPY_SUFFIX, } from './profileStateDir.js';
+import { assertMayMutateLiveState, rethrowIfLiveStateRefusal } from './liveState.js';
 import { needsReauthState } from './refresh.js';
 import { emitAuthTelemetry, getAuthLogger, getCredEnvelopeFailClosed } from './runtime.js';
+import { atomicWrite0600, ensureStateDir, removeStateFile, writeStateFile } from './stateFiles.js';
 /**
  * Account name the wrapped DEK lives under (file fallback). Keeping the
  * literal here so a future rename surfaces as a single grep target.
@@ -84,37 +86,6 @@ export function __getStateForTest() {
 function wrappedDekFilePath(profile) {
     return resolveProfileStateFile(profile, ACCOUNT_CRED_DEK_WRAPPED).path;
 }
-/**
- * Atomic 0600 write — tmp+fsync+rename+dir-fsync. Same shape as the
- * original daemon/CLI implementations so partial-write races between
- * `sky` and `oversky` produce the same on-disk transitions.
- */
-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 */
-    }
-}
 /**
  * Telemetry shim. Routes through the consumer-supplied logEvent sink
  * (daemon: structured event log; CLI: typically no-op or stderr at DEBUG).
@@ -195,9 +166,9 @@ function credEnvelopeLockPath(profile) {
 async function withCredEnvelopeLock(profile, body) {
     const lockPath = credEnvelopeLockPath(profile);
     const dir = path.dirname(lockPath);
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    ensureStateDir(dir, `take the credential envelope lock for profile ${profile}`);
     if (!fs.existsSync(lockPath)) {
-        fs.writeFileSync(lockPath, '', { mode: 0o600 });
+        writeStateFile(lockPath, '', { mode: 0o600 }, 'create the credential envelope lock');
     }
     const acquireStart = Date.now();
     const release = await lockfile.lock(lockPath, {
@@ -338,6 +309,7 @@ async function consolidateWrappedDek(profile, kek, aad) {
         }));
     }
     catch (err) {
+        rethrowIfLiveStateRefusal(err);
         emit('cred_envelope.path_consolidation.failed', false, {
             profile,
             message: err?.message ?? 'unknown',
@@ -473,11 +445,11 @@ function keepUnreadableWrappedDek(profile, wrapped) {
             }
         }
         const name = `${UNREADABLE_DEK_COPY_PREFIX}${new Date().toISOString().replace(/[:.]/g, '-')}`;
-        atomicWrite0600(path.join(dir, name), wrapped);
+        atomicWrite0600(path.join(dir, name), wrapped, 'keep the unreadable wrapped DEK');
         const kept = [...existing, name].sort();
         for (const stale of kept.slice(0, Math.max(0, kept.length - MAX_UNREADABLE_DEK_COPIES))) {
             try {
-                fs.unlinkSync(path.join(dir, stale));
+                removeStateFile(path.join(dir, stale), 'prune a kept wrapped DEK');
             }
             catch {
                 /* a copy that will not go costs 92 bytes */
@@ -486,6 +458,7 @@ function keepUnreadableWrappedDek(profile, wrapped) {
         return name;
     }
     catch (err) {
+        rethrowIfLiveStateRefusal(err);
         emit('cred_envelope.unreadable_dek_copy_failed', false, {
             profile,
             message: err?.message ?? 'unknown',
@@ -626,6 +599,9 @@ export async function initNewIndependentCredEnvelope(profile) {
     const dek = generateDek();
     let temp;
     try {
+        // Everything below creates, links and deletes inside `dir`, with raw flags
+        // (O_EXCL, link) the shared writers do not offer, so the refusal is asked once here.
+        assertMayMutateLiveState(dir, `enroll the wrapped DEK for background profile ${profile}`);
         const wrapped = await kek.wrap(dek, buildCredentialAad(profile));
         // Another enrollment may have won while the platform store was busy.
         // Its file is opened read-only; this process never overwrites it.
@@ -869,7 +845,7 @@ export async function initCredEnvelope(profile) {
             try {
                 dek = generateDek();
                 const wrapped = await kek.wrap(dek, aad);
-                atomicWrite0600(targetPath, wrapped);
+                atomicWrite0600(targetPath, wrapped, `write the wrapped DEK for profile ${profile}`);
                 emit('cred_envelope.dek_enrolled', true, {
                     kekId: kek.id,
                     kekKind: captureKind(),
@@ -878,6 +854,7 @@ export async function initCredEnvelope(profile) {
                 });
             }
             catch (err) {
+                rethrowIfLiveStateRefusal(err);
                 _state = { kind: 'disabled', reason: 'init_failed' };
                 emit('cred_envelope.init_failed', false, {
                     reason: 'enrollment_failed',
@@ -926,9 +903,10 @@ export async function resetCredEnvelope(opts) {
             ...retiredDekFiles(opts.profile),
         ]) {
             try {
-                fs.unlinkSync(target);
+                removeStateFile(target, `delete the wrapped DEK file ${path.basename(target)}`);
             }
             catch (err) {
+                rethrowIfLiveStateRefusal(err);
                 if (err.code !== 'ENOENT') {
                     emit('cred_envelope.clear_failed', false, {
                         profile: opts.profile,

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

@@ -1,4 +1,34 @@
-import { type DeviceKeyPair, type Ed25519PublicJwk } from './deviceKey.js';
+import { type DeviceKeyAlg, type DevicePublicJwk } from './deviceKey.js';
+import { type DeviceKeyCustody, type DeviceKeyHandle } from './deviceKeyHandle.js';
+import { type HardwareKeyCapability, type HardwareKeyRecord } from './deviceKeyHardware.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 declare const DEVICE_KEY_UNREADABLE_CREDENTIAL_HINT = "stored device key is unreadable on this machine \u2014 only an interactive daemon sign-in replaces it";
+/**
+ * `key` is a handle, never a keypair: nothing in this module (or any caller of
+ * it) can read a private scalar once a key is active, which is what lets a
+ * hardware key stand in for a software one without a second code path.
+ *
+ * `envelopeProtected` is about the PRIVATE KEY FILE being sealed under the
+ * credential envelope. A hardware record is deliberately not sealed (it is
+ * useless off this machine, and sealing it would tie the device identity's life
+ * to the envelope key again), so it is always `false` for hardware and says
+ * nothing about how well that key is protected: read `key.custody` for that.
+ */
 type DeviceIdentityState = {
     kind: 'uninit';
 } | {
@@ -6,7 +36,7 @@ type DeviceIdentityState = {
     reason: DisabledReason;
 } | {
     kind: 'active';
-    keypair: DeviceKeyPair;
+    key: DeviceKeyHandle;
     profile: string;
     envelopeProtected: boolean;
 };
@@ -69,6 +99,69 @@ export declare function resetDeviceIdentity(opts?: {
     profile?: string;
     clearOnDisk?: boolean;
 }): Promise<void>;
+/**
+ * A hardware key that exists only in memory. It is not this machine's identity
+ * until `commitDeviceKeyCandidate`, and it leaves nothing behind if it is
+ * dropped: a Secure Enclave key lives in the blob and nowhere else.
+ *
+ * That is the whole safety argument for an upgrade. The server learns the new key
+ * from a proof signed with it (an interactive sign-in re-pins the row), so the
+ * order has to be: create the candidate, sign the sign-in with it, and only after
+ * the server has accepted that sign-in make it the identity. The software key
+ * stays on disk, untouched and active, through every step before the last one.
+ */
+export interface DeviceKeyCandidate {
+    readonly key: DeviceKeyHandle;
+    /** @internal what `commitDeviceKeyCandidate` persists. */
+    readonly record: HardwareKeyRecord;
+}
+export type DeviceKeyCandidateResult = {
+    ok: true;
+    candidate: DeviceKeyCandidate;
+} | {
+    ok: false;
+    reason: 'already_hardware' | 'independent_profile' | 'unavailable' | 'create_failed';
+    capability?: HardwareKeyCapability;
+    message?: string;
+};
+/**
+ * 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 declare function prepareHardwareKeyCandidate(profile: string): Promise<DeviceKeyCandidateResult>;
+/** Sign a request with a candidate (the upgrade's sign-in proof). Null on failure, like `signServerRequest`. */
+export declare function signWithCandidate(candidate: DeviceKeyCandidate, opts: {
+    method: string;
+    url: string;
+    refreshToken?: string;
+    accessToken?: string;
+}): Promise<string | null>;
+/**
+ * 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 declare function commitDeviceKeyCandidate(profile: string, candidate: DeviceKeyCandidate): Promise<void>;
+/** A sign-in that takes longer than this has been abandoned; its pending key is not committed. */
+export declare const PENDING_HARDWARE_KEY_MAX_AGE_MS: number;
+/** Park a candidate so a later process can commit or discard it. Replaces any earlier one. */
+export declare function persistPendingHardwareKey(profile: string, candidate: DeviceKeyCandidate): Promise<void>;
+export type PendingHardwareKeyOutcome = 'committed' | 'no_pending' | 'mismatch' | 'expired' | 'unreadable';
+/**
+ * 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 declare function commitPendingHardwareKey(profile: string, thumbprint: string): Promise<PendingHardwareKeyOutcome>;
+/** Drop the parked candidate (the sign-in failed or was refused). Idempotent. */
+export declare function discardPendingHardwareKey(profile: string): Promise<void>;
 /** True iff init has completed and a keypair is in memory. */
 export declare function isDeviceIdentityActive(): boolean;
 /**
@@ -77,8 +170,10 @@ export declare function isDeviceIdentityActive(): boolean;
  * on the in-flight request.
  */
 export declare function getDevicePublicKey(): {
-    jwk: Ed25519PublicJwk;
+    jwk: DevicePublicJwk;
     thumbprint: string;
+    alg: DeviceKeyAlg;
+    custody: DeviceKeyCustody;
 } | null;
 /**
  * Operator-readable summary of device-identity state. Used by
@@ -90,13 +185,47 @@ export declare function describeDeviceIdentityState(): {
     thumbprint?: string;
     profile?: string;
     envelopeProtected?: boolean;
+    alg?: DeviceKeyAlg;
+    /** Whether the private half can be copied off this machine. Absent unless active. */
+    custody?: DeviceKeyCustody;
+    /**
+     * For a hardware key: can THIS process sign with it right now? False means the
+     * key exists and is intact but the helper that signs with it is not installed
+     * where this process can find it (a CLI without the desktop app's helper, an
+     * app update that has not landed). It is a different fact from an unreadable
+     * key, and it must never lead to replacing the key.
+     */
+    canSign?: boolean;
+};
+export type StoredDeviceKeyDescription = {
+    stored: false;
+} | {
+    stored: true;
+    alg: DeviceKeyAlg;
+    custody: DeviceKeyCustody;
+    thumbprint: string;
+    /** A hardware key needs the helper to sign; a software key never does. */
+    canSign: boolean;
 };
+/**
+ * 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 declare function describeStoredDeviceKey(profile: string): StoredDeviceKeyDescription;
 /**
  * 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.
  */
@@ -105,7 +234,7 @@ export declare function signServerRequest(opts: {
     url: string;
     refreshToken?: string;
     accessToken?: string;
-}): string | null;
+}): Promise<string | null>;
 /** @internal Test seams — file path resolvers. */
 export declare function __publicKeyPathForTest(profile: string): string;
 export declare function __privateKeyPathForTest(profile: string): string;