@skrr-ai/cli 0.1.123 → 0.1.124

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