@skrr-ai/cli 0.1.123 → 0.1.125

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

@@ -50,6 +50,33 @@ export interface Ed25519PublicJwk {
 export interface Ed25519PrivateJwk extends Ed25519PublicJwk {
     readonly d: string;
 }
+/**
+ * NIST P-256 public JSON Web Key — RFC 7518 §6.2 ("Key Type 'EC'").
+ *
+ * The only curve a Secure Enclave or TPM will sign with, which is why a
+ * hardware-bound device key is a different `alg` (ES256) rather than a
+ * different storage backend for the same algorithm. `x` and `y` are the
+ * 32-byte affine coordinates in base64url-no-padding. There is deliberately
+ * no private form: a P-256 device key in this codebase is non-exportable, so
+ * nothing here ever holds its scalar.
+ */
+export interface P256PublicJwk {
+    readonly kty: 'EC';
+    readonly crv: 'P-256';
+    readonly x: string;
+    readonly y: string;
+}
+/** Any public key a device proof may be signed with. */
+export type DevicePublicJwk = Ed25519PublicJwk | P256PublicJwk;
+/**
+ * The JWS algorithms a device proof may use. `EdDSA` is the software key every
+ * install has had since L11; `ES256` is the hardware-bound key. A server pins
+ * ONE per device and never requires a client to use an algorithm it did not
+ * announce.
+ */
+export type DeviceKeyAlg = 'EdDSA' | 'ES256';
+/** Every algorithm this build can verify, in the order a client prefers them. */
+export declare const DEVICE_KEY_ALGS: readonly DeviceKeyAlg[];
 /**
  * The full keypair returned at generation time. Holding both forms here
  * is convenient for the daemon-side bridge — the public form is what we
@@ -57,6 +84,11 @@ export interface Ed25519PrivateJwk extends Ed25519PublicJwk {
  *
  * `thumbprint` is the RFC 7638 JWK thumbprint of the public key — the
  * canonical stable id we use as the device handle on the server.
+ *
+ * This is the SOFTWARE Ed25519 key only, and only the sealed-file store and
+ * key generation touch its private half. Everything that signs holds a
+ * `DeviceKeyHandle` (deviceKeyHandle.ts) instead, which cannot return the
+ * private scalar and so works unchanged for a key that has none.
  */
 export interface DeviceKeyPair {
     readonly publicJwk: Ed25519PublicJwk;
@@ -83,7 +115,23 @@ export declare function generateDeviceKeyPair(): DeviceKeyPair;
  * `kid` in JWS headers and as the registered identifier on the server's
  * `Daemon` table.
  */
-export declare function jwkThumbprint(publicJwk: Ed25519PublicJwk): string;
+export declare function jwkThumbprint(publicJwk: DevicePublicJwk): string;
+/**
+ * Structural check for a public device key: the right `kty`/`crv` pair, and
+ * coordinates that are exactly 32 bytes of base64url. It does not prove the
+ * point is on the curve (importing the key does that); it proves the value is
+ * safe to build a thumbprint from.
+ */
+export declare function isDevicePublicJwk(value: unknown): value is DevicePublicJwk;
+/** The JWS algorithm a public key signs with. */
+export declare function algForJwk(jwk: DevicePublicJwk): DeviceKeyAlg;
+/**
+ * A P-256 public JWK from the 64-byte `x || y` form a Secure Enclave reports
+ * (CryptoKit's `rawRepresentation`). Rejects any other length so a helper that
+ * returns an x9.63 point (65 bytes, leading 0x04) fails loudly instead of being
+ * mis-split into a key nothing can verify.
+ */
+export declare function p256PublicJwkFromRaw(raw: Uint8Array): P256PublicJwk;
 /**
  * Construct an `Ed25519PublicJwk` from a base64url-encoded 32-byte
  * public point. Used by the persistence layer when reading a stored
@@ -124,13 +172,13 @@ export interface DeviceProofClaims {
     ath?: string;
 }
 export interface DeviceProofHeader {
-    alg: 'EdDSA';
+    alg: DeviceKeyAlg;
     /** Custom `typ` so the server can refuse generic JWTs that happen
-     *  to be EdDSA-signed by a stolen device key. RFC 9449 uses
+     *  to be signed by a stolen device key. RFC 9449 uses
      *  `dpop+jwt`; we differentiate so OverSky proofs can't be
      *  cross-replayed into a generic DPoP resource server. */
     typ: 'oversky-dpop+jwt';
-    jwk: Ed25519PublicJwk;
+    jwk: DevicePublicJwk;
 }
 export interface BuildProofOptions {
     method: string;
@@ -172,11 +220,35 @@ export declare const DEVICE_PROOF_TYP = "oversky-dpop+jwt";
  * never verify as the other.
  */
 export declare function signEd25519Proof(privateKey: crypto.KeyObject, publicJwk: Ed25519PublicJwk, typ: string, opts: BuildProofOptions): string;
+/**
+ * The `header.payload` half of a proof: everything the key signs. Split out so
+ * a key that cannot be handed to this process (a Secure Enclave key signs
+ * inside a helper) signs the very same bytes a software key does, and nothing
+ * about the wire format depends on where the signature came from.
+ *
+ * @internal Shared by `signEd25519Proof` and `signProofWith`.
+ */
+export declare function proofSigningInput(alg: DeviceKeyAlg, publicJwk: DevicePublicJwk, typ: string, opts: BuildProofOptions): string;
+/**
+ * Anything that can sign a device proof (a `DeviceKeySigner`): a software key held in this process,
+ * or a hardware key that signs elsewhere. `sign` returns the JWS signature for
+ * `alg` (RFC 7515 §A.3 / RFC 8037: raw r||s for ES256, the 64 bytes for EdDSA),
+ * never DER.
+ */
+export interface DeviceKeySigner {
+    readonly alg: DeviceKeyAlg;
+    readonly publicJwk: DevicePublicJwk;
+    sign(signingInput: Uint8Array): Promise<Uint8Array>;
+}
+/** Sign a device-identity proof with any `DeviceKeySigner`. */
+export declare function signProofWith(signer: DeviceKeySigner, opts: BuildProofOptions, typ?: string): Promise<string>;
 export type VerifyFailureReason = 'malformed' | 'bad_alg' | 'bad_typ' | 'bad_jwk' | 'sig_invalid' | 'iat_old' | 'iat_future' | 'htm_mismatch' | 'htu_mismatch' | 'rth_mismatch' | 'ath_mismatch' | 'pin_mismatch';
 export interface VerifySuccess {
     valid: true;
     claims: DeviceProofClaims;
-    publicJwk: Ed25519PublicJwk;
+    publicJwk: DevicePublicJwk;
+    /** The algorithm the proof was signed with; always one `allowedAlgs` admitted. */
+    alg: DeviceKeyAlg;
     thumbprint: string;
 }
 export interface VerifyFailure {
@@ -199,8 +271,17 @@ export interface VerifyOptions {
     expectedAth?: string;
     /** Public JWK pinned at the server side. When provided, the proof's
      *  inlined JWK MUST equal this — defends against a stolen valid
-     *  proof signed by a different (e.g., revoked) device. */
-    pinnedPublicJwk?: Ed25519PublicJwk;
+     *  proof signed by a different (e.g., revoked) device. Compared by
+     *  thumbprint, so a pin on one algorithm never admits a key of another. */
+    pinnedPublicJwk?: DevicePublicJwk;
+    /**
+     * The algorithms this verification admits. Defaults to `['EdDSA']`: a caller
+     * that has not decided it accepts hardware-bound keys keeps exactly the
+     * behaviour it had before ES256 existed. A server that pins a device to ES256
+     * passes the algorithm of the PIN, not `DEVICE_KEY_ALGS`, so a proof cannot
+     * choose a weaker algorithm than the device enrolled with.
+     */
+    allowedAlgs?: readonly DeviceKeyAlg[];
     /** Override the wall clock — testing hook. Defaults to `Date.now()`. */
     now?: number;
 }
@@ -217,7 +298,25 @@ export declare function verifyProof(jws: string, opts?: VerifyOptions): VerifySu
 /**
  * Verify a DPoP-shaped Ed25519 proof whose header `typ` must equal `typ`.
  *
+ * Always EdDSA, whatever `opts.allowedAlgs` says: the RFC 9449 access-token
+ * proof (`dpop.ts`) is signed by the CLI's own in-memory Ed25519 key, which is a
+ * different key from the device key and deliberately stays software.
+ *
  * @internal See `signEd25519Proof`. `verifyProof` (device identity) and
  * `verifyDpopProof` (`dpop.ts`, RFC 9449) are the two public doors.
  */
 export declare function verifyEd25519Proof(jws: string, opts: VerifyOptions, typ: string): VerifySuccess | VerifyFailure;
+/**
+ * Verify a DPoP-shaped proof signed by an Ed25519 or P-256 key, whose header
+ * `typ` must equal `typ` and whose `alg` must be in `opts.allowedAlgs`.
+ *
+ * The algorithm comes from the header and is checked twice before any key is
+ * built: it must be one the caller admitted, and it must be the algorithm the
+ * header's own key type signs with. Without the second check a header could
+ * pair `alg: ES256` with an Ed25519 key (or the reverse) and steer the
+ * verifier into a code path nobody tested; with it, the only thing an attacker
+ * controls about the algorithm is a choice among the caller's own allow-list.
+ *
+ * @internal
+ */
+export declare function verifyDevicePublicKeyProof(jws: string, opts: VerifyOptions, typ: string): VerifySuccess | VerifyFailure;

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

@@ -35,6 +35,8 @@
  *   - Wire-up to the daemon's outgoing HTTP path (Phase 2 of L11).
  */
 import crypto from 'node:crypto';
+/** Every algorithm this build can verify, in the order a client prefers them. */
+export const DEVICE_KEY_ALGS = ['ES256', 'EdDSA'];
 // ---------------------------------------------------------------------------
 // Base64url helpers — same shape as `credentialEnvelope.ts` so the two
 // modules are visually consistent in the auth-core codebase.
@@ -91,9 +93,55 @@ export function jwkThumbprint(publicJwk) {
     // guarantee key order across Node versions, even though current V8
     // preserves insertion order. Build the bytes ourselves to defend
     // against a hypothetical future regression.
-    const canonical = `{"crv":"${publicJwk.crv}","kty":"${publicJwk.kty}","x":"${publicJwk.x}"}`;
+    //
+    // RFC 7638 §3.2: an EC key's required members are crv, kty, x, y; an OKP
+    // key's are crv, kty, x. The caller has validated the members as base64url
+    // (`isDevicePublicJwk`), so nothing here can inject a quote into the input.
+    const canonical = publicJwk.kty === 'EC'
+        ? `{"crv":"${publicJwk.crv}","kty":"${publicJwk.kty}","x":"${publicJwk.x}","y":"${publicJwk.y}"}`
+        : `{"crv":"${publicJwk.crv}","kty":"${publicJwk.kty}","x":"${publicJwk.x}"}`;
     return b64u(crypto.createHash('sha256').update(canonical, 'utf-8').digest());
 }
+const B64URL_32 = /^[A-Za-z0-9_-]{43}$/;
+/**
+ * Structural check for a public device key: the right `kty`/`crv` pair, and
+ * coordinates that are exactly 32 bytes of base64url. It does not prove the
+ * point is on the curve (importing the key does that); it proves the value is
+ * safe to build a thumbprint from.
+ */
+export function isDevicePublicJwk(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const jwk = value;
+    if (jwk.kty === 'OKP') {
+        return jwk.crv === 'Ed25519' && typeof jwk.x === 'string' && B64URL_32.test(jwk.x);
+    }
+    if (jwk.kty === 'EC') {
+        return (jwk.crv === 'P-256' &&
+            typeof jwk.x === 'string' &&
+            typeof jwk.y === 'string' &&
+            B64URL_32.test(jwk.x) &&
+            B64URL_32.test(jwk.y));
+    }
+    return false;
+}
+/** The JWS algorithm a public key signs with. */
+export function algForJwk(jwk) {
+    return jwk.kty === 'EC' ? 'ES256' : 'EdDSA';
+}
+/**
+ * A P-256 public JWK from the 64-byte `x || y` form a Secure Enclave reports
+ * (CryptoKit's `rawRepresentation`). Rejects any other length so a helper that
+ * returns an x9.63 point (65 bytes, leading 0x04) fails loudly instead of being
+ * mis-split into a key nothing can verify.
+ */
+export function p256PublicJwkFromRaw(raw) {
+    if (raw.length !== 64) {
+        throw new Error(`p256PublicJwkFromRaw: expected 64 bytes (x||y), got ${raw.length}`);
+    }
+    const buf = Buffer.from(raw);
+    return { kty: 'EC', crv: 'P-256', x: b64u(buf.subarray(0, 32)), y: b64u(buf.subarray(32)) };
+}
 /**
  * Construct an `Ed25519PublicJwk` from a base64url-encoded 32-byte
  * public point. Used by the persistence layer when reading a stored
@@ -180,12 +228,34 @@ export const DEVICE_PROOF_TYP = 'oversky-dpop+jwt';
  * never verify as the other.
  */
 export function signEd25519Proof(privateKey, publicJwk, typ, opts) {
+    const signingInput = proofSigningInput('EdDSA', publicJwk, typ, opts);
+    // EdDSA over Ed25519 — Node's crypto.sign expects `null` as the
+    // digest algorithm because Ed25519 hashes the message internally.
+    const signature = crypto.sign(null, Buffer.from(signingInput, 'utf-8'), privateKey);
+    return `${signingInput}.${b64u(signature)}`;
+}
+/**
+ * The `header.payload` half of a proof: everything the key signs. Split out so
+ * a key that cannot be handed to this process (a Secure Enclave key signs
+ * inside a helper) signs the very same bytes a software key does, and nothing
+ * about the wire format depends on where the signature came from.
+ *
+ * @internal Shared by `signEd25519Proof` and `signProofWith`.
+ */
+export function proofSigningInput(alg, publicJwk, typ, opts) {
     if (typeof opts.method !== 'string' || opts.method.length === 0) {
         throw new Error('buildProof: method must be a non-empty string');
     }
     if (typeof opts.url !== 'string' || opts.url.length === 0) {
         throw new Error('buildProof: url must be a non-empty string');
     }
+    // A header that claims an algorithm its own key cannot produce is a bug in the
+    // caller, and the one a verifier is built to reject (`bad_alg`). Refuse to
+    // emit it rather than ship a proof that fails on the server with a reason
+    // nobody connects to this line.
+    if (algForJwk(publicJwk) !== alg) {
+        throw new Error(`buildProof: alg ${alg} does not match a ${publicJwk.kty} key`);
+    }
     const claims = {
         htm: opts.method.toUpperCase(),
         htu: normalizeHtu(opts.url),
@@ -196,14 +266,16 @@ export function signEd25519Proof(privateKey, publicJwk, typ, opts) {
         claims.rth = tokenHash(opts.refreshToken);
     if (opts.accessToken !== undefined)
         claims.ath = tokenHash(opts.accessToken);
-    const header = { alg: 'EdDSA', typ, jwk: publicJwk };
+    const header = { alg, typ, jwk: publicJwk };
     const headerB64 = b64u(Buffer.from(JSON.stringify(header), 'utf-8'));
     const payloadB64 = b64u(Buffer.from(JSON.stringify(claims), 'utf-8'));
-    const signingInput = `${headerB64}.${payloadB64}`;
-    // EdDSA over Ed25519 — Node's crypto.sign expects `null` as the
-    // digest algorithm because Ed25519 hashes the message internally.
-    const signature = crypto.sign(null, Buffer.from(signingInput, 'utf-8'), privateKey);
-    return `${signingInput}.${b64u(signature)}`;
+    return `${headerB64}.${payloadB64}`;
+}
+/** Sign a device-identity proof with any `DeviceKeySigner`. */
+export async function signProofWith(signer, opts, typ = DEVICE_PROOF_TYP) {
+    const signingInput = proofSigningInput(signer.alg, signer.publicJwk, typ, opts);
+    const signature = await signer.sign(Buffer.from(signingInput, 'utf-8'));
+    return `${signingInput}.${b64u(Buffer.from(signature))}`;
 }
 /**
  * Verify a device-identity proof. Returns a discriminated union — the
@@ -215,15 +287,35 @@ export function signEd25519Proof(privateKey, publicJwk, typ, opts) {
  * `sig_invalid` to keep the failure surface narrow.
  */
 export function verifyProof(jws, opts = {}) {
-    return verifyEd25519Proof(jws, opts, DEVICE_PROOF_TYP);
+    return verifyDevicePublicKeyProof(jws, opts, DEVICE_PROOF_TYP);
 }
 /**
  * Verify a DPoP-shaped Ed25519 proof whose header `typ` must equal `typ`.
  *
+ * Always EdDSA, whatever `opts.allowedAlgs` says: the RFC 9449 access-token
+ * proof (`dpop.ts`) is signed by the CLI's own in-memory Ed25519 key, which is a
+ * different key from the device key and deliberately stays software.
+ *
  * @internal See `signEd25519Proof`. `verifyProof` (device identity) and
  * `verifyDpopProof` (`dpop.ts`, RFC 9449) are the two public doors.
  */
 export function verifyEd25519Proof(jws, opts, typ) {
+    return verifyDevicePublicKeyProof(jws, { ...opts, allowedAlgs: ['EdDSA'] }, typ);
+}
+/**
+ * Verify a DPoP-shaped proof signed by an Ed25519 or P-256 key, whose header
+ * `typ` must equal `typ` and whose `alg` must be in `opts.allowedAlgs`.
+ *
+ * The algorithm comes from the header and is checked twice before any key is
+ * built: it must be one the caller admitted, and it must be the algorithm the
+ * header's own key type signs with. Without the second check a header could
+ * pair `alg: ES256` with an Ed25519 key (or the reverse) and steer the
+ * verifier into a code path nobody tested; with it, the only thing an attacker
+ * controls about the algorithm is a choice among the caller's own allow-list.
+ *
+ * @internal
+ */
+export function verifyDevicePublicKeyProof(jws, opts, typ) {
     if (typeof jws !== 'string' || jws.length === 0) {
         return { valid: false, reason: 'malformed' };
     }
@@ -241,33 +333,34 @@ export function verifyEd25519Proof(jws, opts, typ) {
     catch {
         return { valid: false, reason: 'malformed' };
     }
-    if (!header || typeof header !== 'object' || header.alg !== 'EdDSA') {
+    const allowedAlgs = opts.allowedAlgs ?? ['EdDSA'];
+    const headerAlg = header && typeof header === 'object' ? header.alg : undefined;
+    if ((headerAlg !== 'EdDSA' && headerAlg !== 'ES256') ||
+        !allowedAlgs.includes(headerAlg)) {
         return { valid: false, reason: 'bad_alg' };
     }
     if (header.typ !== typ) {
         return { valid: false, reason: 'bad_typ' };
     }
+    // Take only the members a key of this type has. Whatever else the header's
+    // `jwk` carries (a stray `d`, `use`, `key_ops`) is dropped here, so nothing
+    // downstream can come to depend on a member we never validated, and the
+    // thumbprint is over exactly what was checked.
     const headerJwk = header.jwk;
-    if (!headerJwk ||
-        typeof headerJwk !== 'object' ||
-        headerJwk.kty !== 'OKP' ||
-        headerJwk.crv !== 'Ed25519' ||
-        typeof headerJwk.x !== 'string') {
+    if (!isDevicePublicJwk(headerJwk)) {
         return { valid: false, reason: 'bad_jwk' };
     }
-    const publicJwk = {
-        kty: 'OKP',
-        crv: 'Ed25519',
-        x: headerJwk.x,
-    };
-    // Validate the public point length — defends against an attacker who
-    // smuggles a non-32-byte `x` to confuse downstream consumers.
+    const publicJwk = headerJwk.kty === 'EC'
+        ? { kty: 'EC', crv: 'P-256', x: headerJwk.x, y: headerJwk.y }
+        : { kty: 'OKP', crv: 'Ed25519', x: headerJwk.x };
+    // The algorithm and the key must agree (see the function comment).
+    if (algForJwk(publicJwk) !== headerAlg) {
+        return { valid: false, reason: 'bad_alg' };
+    }
+    // Importing the key validates it: an Ed25519 point of the wrong length, or a
+    // P-256 point that is not on the curve, throws here.
     let publicKeyObj;
     try {
-        const raw = b64uDecode(publicJwk.x);
-        if (raw.length !== 32) {
-            return { valid: false, reason: 'bad_jwk' };
-        }
         publicKeyObj = crypto.createPublicKey({
             format: 'jwk',
             key: publicJwk,
@@ -276,7 +369,7 @@ export function verifyEd25519Proof(jws, opts, typ) {
     catch {
         return { valid: false, reason: 'bad_jwk' };
     }
-    if (opts.pinnedPublicJwk && opts.pinnedPublicJwk.x !== publicJwk.x) {
+    if (opts.pinnedPublicJwk && jwkThumbprint(opts.pinnedPublicJwk) !== jwkThumbprint(publicJwk)) {
         return { valid: false, reason: 'pin_mismatch' };
     }
     // Verify the signature itself before validating claims — a bad
@@ -292,7 +385,17 @@ export function verifyEd25519Proof(jws, opts, typ) {
     }
     let sigOk;
     try {
-        sigOk = crypto.verify(null, signingInput, publicKeyObj, signature);
+        sigOk =
+            headerAlg === 'ES256'
+                ? // JWS ES256 is the fixed-width r||s form, never DER (RFC 7518 §3.4).
+                    // Node's 'ieee-p1363' encoding is that form and already refuses any
+                    // other width (removing the explicit length check changes no test
+                    // result), so the check below states the requirement instead of
+                    // inheriting it: a DER or truncated signature must fail here rather
+                    // than be re-encoded into validity, even under a Node that changes.
+                    signature.length === 64 &&
+                        crypto.verify('sha256', signingInput, { key: publicKeyObj, dsaEncoding: 'ieee-p1363' }, signature)
+                : crypto.verify(null, signingInput, publicKeyObj, signature);
     }
     catch {
         sigOk = false;
@@ -334,6 +437,7 @@ export function verifyEd25519Proof(jws, opts, typ) {
         valid: true,
         claims,
         publicJwk,
+        alg: headerAlg,
         thumbprint: jwkThumbprint(publicJwk),
     };
 }

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

@@ -0,0 +1,33 @@
+import { type DeviceKeyPair, type DeviceKeySigner } from './deviceKey.js';
+/**
+ * Where the private half lives.
+ *
+ *  - `software`: an exportable scalar, sealed in a file under the credential
+ *    envelope. Anything that can read that file and the envelope key owns the
+ *    device identity.
+ *  - `hardware`: a non-exportable key inside a Secure Enclave / TPM. A copy of
+ *    every file on the disk is still not the key.
+ */
+export type DeviceKeyCustody = 'software' | 'hardware';
+export interface DeviceKeyHandle extends DeviceKeySigner {
+    readonly custody: DeviceKeyCustody;
+    /** RFC 7638 thumbprint of `publicJwk`; the id the server pins. */
+    readonly thumbprint: string;
+}
+/**
+ * A handle over a software Ed25519 key. Throws if the pair is internally
+ * inconsistent (public and private halves from different keys, or a private
+ * JWK Node cannot import) so a corrupted identity fails at load, where the
+ * caller already handles it, rather than at the first signature.
+ */
+export declare function softwareEd25519Handle(pair: DeviceKeyPair): DeviceKeyHandle;
+/**
+ * A software P-256 handle with a fresh key. NOT a device-key backend: a
+ * software P-256 key gives up exactly what P-256 is for, and nothing in the
+ * product creates one. It exists so the ES256 wire format (sign, verify, pin)
+ * can be exercised end to end without a Secure Enclave, and so a fake hardware
+ * helper in a test signs with the real algorithm instead of a stub.
+ *
+ * @internal
+ */
+export declare function generateSoftwareP256Handle(): DeviceKeyHandle;

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

@@ -0,0 +1,81 @@
+/**
+ * deviceKeyHandle.ts — the one thing the rest of the codebase holds instead of a
+ * private key.
+ *
+ * WHY THIS EXISTS. Every signing site used to be handed a `DeviceKeyPair` and
+ * call `buildProof(kp.privateJwk, kp.publicJwk, …)`. That is correct for a
+ * software key and impossible for any other kind: a Secure Enclave or TPM key
+ * has no scalar to put in a JWK, and the next kind of key would have meant
+ * editing every signing site again. A handle inverts it. The holder asks the
+ * key to sign bytes (`sign`) and to describe itself (`alg`, `publicJwk`,
+ * `custody`); how the signature is made, and whether the key could be copied
+ * out of this machine, is the key's business.
+ *
+ * The consequence that matters in practice: `privateJwk` is read in exactly two
+ * places — the sealed-file store that persists a software key and the function
+ * here that turns it into a handle. A handle holds a `KeyObject` in a closure
+ * and offers no way to get the scalar back, so no new caller can come to depend
+ * on having it. That is the property that makes "the device key is
+ * extractable" (docs/architecture/device-key-custody-2026-10-29.md §3.2) a
+ * property of ONE backend rather than of the whole design.
+ *
+ * `custody` is the honest name for that difference, and it is surfaced (status,
+ * telemetry, UI) rather than inferred: `software` means a file on this disk can
+ * be copied to another machine and used there; `hardware` means it cannot.
+ */
+import crypto from 'node:crypto';
+import { jwkThumbprint, } from './deviceKey.js';
+/**
+ * A handle over a software Ed25519 key. Throws if the pair is internally
+ * inconsistent (public and private halves from different keys, or a private
+ * JWK Node cannot import) so a corrupted identity fails at load, where the
+ * caller already handles it, rather than at the first signature.
+ */
+export function softwareEd25519Handle(pair) {
+    if (pair.publicJwk.x !== pair.privateJwk.x) {
+        // Public and private must come from the same keypair. A mismatch is a
+        // partial write, a manual edit, or one file swapped for another.
+        throw new Error('softwareEd25519Handle: public/private JWK x mismatch (corrupted keypair)');
+    }
+    // Cast through `unknown`: Node's `JsonWebKey` wants an index signature our
+    // narrow OKP type deliberately does not declare.
+    const privateKey = crypto.createPrivateKey({
+        format: 'jwk',
+        key: pair.privateJwk,
+    });
+    const publicJwk = pair.publicJwk;
+    return {
+        alg: 'EdDSA',
+        custody: 'software',
+        publicJwk,
+        thumbprint: jwkThumbprint(publicJwk),
+        // Ed25519 hashes the message itself, so Node takes `null` for the digest.
+        sign: async (signingInput) => new Uint8Array(crypto.sign(null, Buffer.from(signingInput), privateKey)),
+    };
+}
+/**
+ * A software P-256 handle with a fresh key. NOT a device-key backend: a
+ * software P-256 key gives up exactly what P-256 is for, and nothing in the
+ * product creates one. It exists so the ES256 wire format (sign, verify, pin)
+ * can be exercised end to end without a Secure Enclave, and so a fake hardware
+ * helper in a test signs with the real algorithm instead of a stub.
+ *
+ * @internal
+ */
+export function generateSoftwareP256Handle() {
+    const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
+    const jwk = publicKey.export({ format: 'jwk' });
+    const publicJwk = { kty: 'EC', crv: 'P-256', x: jwk.x, y: jwk.y };
+    return {
+        alg: 'ES256',
+        custody: 'software',
+        publicJwk,
+        thumbprint: jwkThumbprint(publicJwk),
+        sign: async (signingInput) => new Uint8Array(
+        // 'ieee-p1363' is the JWS (r||s) form; the default would be DER.
+        crypto.sign('sha256', Buffer.from(signingInput), {
+            key: privateKey,
+            dsaEncoding: 'ieee-p1363',
+        })),
+    };
+}

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

@@ -0,0 +1,68 @@
+import { type P256PublicJwk } from './deviceKey.js';
+import type { DeviceKeyHandle } from './deviceKeyHandle.js';
+/** File name of the helper next to the daemon binary and under `<machine root>/bin`. */
+export declare const HARDWARE_KEY_HELPER_NAME = "skrr-native-device-key";
+export declare const HARDWARE_KEY_PROTOCOL = 1;
+export type HardwareDeviceKeyErrorCode = 'helper_missing' | 'helper_failed' | 'timeout' | 'bad_response' | 'key_mismatch' | 'unsupported';
+export declare class HardwareDeviceKeyError extends Error {
+    readonly code: HardwareDeviceKeyErrorCode;
+    constructor(code: HardwareDeviceKeyErrorCode, message: string);
+}
+/**
+ * Tell auth-core where the helper is. The daemon calls this at boot with the
+ * path next to its own binary; a process that never does (the CLI, a test)
+ * falls back to the places the helper is installed: beside this process's
+ * executable, then `<machine root>/bin`. Pass `null` to forget a resolver.
+ */
+export declare function configureHardwareDeviceKeyHelper(resolver: (() => string | null) | null): void;
+/** Absolute path of an executable helper, or null when this machine has none. */
+export declare function resolveHardwareDeviceKeyHelper(): string | null;
+/** @internal Test seam — bound every helper call by `ms`. `null` restores the real limits. */
+export declare function __setHardwareHelperTimeoutForTest(ms: number | null): void;
+export type HardwareKeyCapability = {
+    available: true;
+} | {
+    available: false;
+    reason: 'helper_missing' | 'no_secure_hardware' | 'probe_failed';
+    message?: string;
+};
+/**
+ * Can this machine create and use a hardware-bound device key right now? Looked
+ * up, never assumed: the answer needs both a helper that runs and hardware that
+ * answers. A positive result is kept for the life of the process; a negative one
+ * is retried after a minute, so a helper installed by an update is picked up
+ * without a restart and a broken one is not spawned on every proof.
+ */
+export declare function probeHardwareDeviceKey(): Promise<HardwareKeyCapability>;
+/** @internal Test seam — forget the cached capability. */
+export declare function __resetHardwareProbeForTest(): void;
+/** Contents of `device-key.se`. The blob is opaque and machine-bound; see the file header. */
+export interface HardwareKeyRecord {
+    readonly blob: string;
+    readonly publicJwk: P256PublicJwk;
+}
+export declare function serializeHardwareKeyRecord(record: HardwareKeyRecord, createdAt?: Date): string;
+/**
+ * Parse `device-key.se`. Null for anything that is not a well-formed v1 record
+ * whose stored thumbprint matches its own public key: a record is trusted for
+ * exactly what it proves about itself, so a half-written or hand-edited file
+ * reads as unreadable (which never replaces it) and not as a different key.
+ */
+export declare function parseHardwareKeyRecord(text: string): HardwareKeyRecord | null;
+/** A handle whose `sign` asks the helper, so no scalar is ever in this process. */
+export declare function hardwareDeviceKeyHandle(record: HardwareKeyRecord): DeviceKeyHandle;
+/**
+ * Create a hardware key and PROVE it before anyone relies on it: sign random
+ * bytes and verify them with Node's own crypto against the public key the helper
+ * reported. A helper that returns a mis-encoded signature, or a public key that
+ * is not the signer's, fails here with nothing yet persisted and nothing yet sent
+ * to the server, instead of as a rejected login that leaves a pin half-moved.
+ *
+ * The returned record is NOT persisted; the caller decides when it becomes the
+ * device's identity (see `commitDeviceKeyCandidate`). Dropping it destroys the
+ * key: the Secure Enclave keeps nothing the blob does not.
+ */
+export declare function createHardwareDeviceKey(): Promise<{
+    record: HardwareKeyRecord;
+    handle: DeviceKeyHandle;
+}>;