@fgv/ts-extras 5.1.0-5 → 5.1.0-50

package/dist/packlets/crypto-utils/keystore/keyStore.js

@@ -17,9 +17,11 @@
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
-import { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { captureAsyncResult, captureResult, fail, succeed } from '@fgv/ts-utils';
 import * as Constants from '../constants';
 import { createEncryptedFile } from '../encryptedFile';
+import { keyPairAlgorithmParams } from '../keyPairAlgorithmParams';
+import { ARGON2ID_OWASP_MIN } from '../model';
 import { DEFAULT_KEYSTORE_ITERATIONS, DEFAULT_SECRET_ITERATIONS, KEYSTORE_FORMAT, MIN_SALT_LENGTH } from './model';
 import { keystoreFile, keystoreVaultContents } from './converters';
 /**
@@ -28,6 +30,11 @@ import { keystoreFile, keystoreVaultContents } from './converters';
 function getCurrentTimestamp() {
     return new Date().toISOString();
 }
+// WebCrypto key usages that only ever apply to a public key. Filtering these
+// out of the keypair usages yields the usages valid for the private half, which
+// `crypto.subtle.importKey` requires when re-importing a private JWK. Mirrors
+// the same list in `EncryptedFilePrivateKeyStorage`.
+const PUBLIC_ONLY_USAGES = ['verify', 'encrypt', 'wrapKey'];
 // ============================================================================
 // KeyStore Class
 // ============================================================================
@@ -60,11 +67,26 @@ function getCurrentTimestamp() {
  * const encryptionConfig = keystore2.getEncryptionConfig().orThrow();
  * ```
  *
+ * @remarks
+ * SECURITY — private-key escrow. By default an asymmetric keypair's private
+ * key lives only in the per-device {@link CryptoUtils.KeyStore.IPrivateKeyStorage}
+ * backend; the vault carries only the public JWK, so a vault recovered on a new
+ * device reconstitutes with no private keys (a lost device is a lost identity).
+ * `addKeyPair(name, { escrow: true })` opts into carrying an encrypted private-key
+ * copy inside the vault ciphertext, so the vault file plus the master password can
+ * recover the identity on a fresh device via `getKeyPair(name, { rehydrate: true })`.
+ *
+ * When escrow is used, **the master password becomes the sole gate** protecting a
+ * private signing/decryption key that was previously unrecoverable from the vault.
+ * Configure escrow-bearing stores with a strong KDF — an Argon2id-derived master
+ * key or a high-iteration PBKDF2 count — and treat the vault file accordingly.
+ *
  * @public
  */
 export class KeyStore {
-    constructor(cryptoProvider, iterations, keystoreFile, isNew = true) {
+    constructor(cryptoProvider, iterations, keystoreFile, isNew, privateKeyStorage) {
         this._cryptoProvider = cryptoProvider;
+        this._privateKeyStorage = privateKeyStorage;
         this._iterations = iterations;
         this._keystoreFile = keystoreFile;
         this._state = 'locked';
@@ -87,7 +109,7 @@ export class KeyStore {
         if (iterations < 1) {
             return fail('Iterations must be at least 1');
         }
-        return succeed(new KeyStore(params.cryptoProvider, iterations, undefined, true));
+        return succeed(new KeyStore(params.cryptoProvider, iterations, undefined, true, params.privateKeyStorage));
     }
     /**
      * Opens an existing encrypted key store.
@@ -103,7 +125,7 @@ export class KeyStore {
             return fail(`Invalid key store file: ${fileResult.message}`);
         }
         const iterations = fileResult.value.keyDerivation.iterations;
-        return succeed(new KeyStore(params.cryptoProvider, iterations, fileResult.value, false));
+        return succeed(new KeyStore(params.cryptoProvider, iterations, fileResult.value, false, params.privateKeyStorage));
     }
     // ============================================================================
     // Lifecycle Methods
@@ -146,7 +168,6 @@ export class KeyStore {
      * @public
      */
     async unlock(password) {
-        var _a;
         if (this._isNew) {
             return fail('Cannot unlock a new key store - use initialize() instead');
         }
@@ -170,57 +191,37 @@ export class KeyStore {
         if (keyResult.isFailure()) {
             return fail(`Key derivation failed: ${keyResult.message}`);
         }
-        // Decrypt the vault
-        const ivResult = this._cryptoProvider.fromBase64(this._keystoreFile.iv);
-        const authTagResult = this._cryptoProvider.fromBase64(this._keystoreFile.authTag);
-        const encryptedDataResult = this._cryptoProvider.fromBase64(this._keystoreFile.encryptedData);
-        /* c8 ignore next 9 - base64 decode errors tested but coverage intermittently missed */
-        if (ivResult.isFailure()) {
-            return fail(`Invalid IV in key store file: ${ivResult.message}`);
-        }
-        if (authTagResult.isFailure()) {
-            return fail(`Invalid auth tag in key store file: ${authTagResult.message}`);
-        }
-        if (encryptedDataResult.isFailure()) {
-            return fail(`Invalid encrypted data in key store file: ${encryptedDataResult.message}`);
-        }
-        const decryptResult = await this._cryptoProvider.decrypt(encryptedDataResult.value, keyResult.value, ivResult.value, authTagResult.value);
-        if (decryptResult.isFailure()) {
-            return fail('Incorrect password or corrupted key store');
+        return this._decryptVault(keyResult.value);
+    }
+    /**
+     * Unlocks an existing key store with a pre-derived key, bypassing
+     * PBKDF2 key derivation. Use this when the derived key has been
+     * stored externally (e.g., in another key store) and the original
+     * password is no longer available.
+     *
+     * The supplied key must have been derived from the correct password
+     * using the key store file's own PBKDF2 parameters (salt and
+     * iteration count).
+     *
+     * @param derivedKey - The pre-derived master key (32 bytes for AES-256)
+     * @returns Success with this instance when unlocked, Failure if key is incorrect
+     * @public
+     */
+    async unlockWithKey(derivedKey) {
+        if (this._isNew) {
+            return fail('Cannot unlock a new key store - use initialize() instead');
         }
-        // Parse the vault contents
-        const parseResult = captureResult(() => JSON.parse(decryptResult.value));
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (parseResult.isFailure()) {
-            return fail(`Failed to parse vault contents: ${parseResult.message}`);
+        if (this._state === 'unlocked') {
+            return fail('Key store is already unlocked');
         }
-        const vaultResult = keystoreVaultContents.convert(parseResult.value);
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (vaultResult.isFailure()) {
-            return fail(`Invalid vault format: ${vaultResult.message}`);
+        if (derivedKey.length !== Constants.AES_256_KEY_SIZE) {
+            return fail(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${derivedKey.length}`);
         }
-        // Load secrets into memory
-        this._salt = salt;
-        this._secrets = new Map();
-        for (const [name, jsonEntry] of Object.entries(vaultResult.value.secrets)) {
-            const keyBytesResult = this._cryptoProvider.fromBase64(jsonEntry.key);
-            /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-            if (keyBytesResult.isFailure()) {
-                return fail(`Invalid key for secret '${name}': ${keyBytesResult.message}`);
-            }
-            const entry = {
-                name,
-                /* c8 ignore next 1 - backwards compatibility: old vaults may lack type field */
-                type: (_a = jsonEntry.type) !== null && _a !== void 0 ? _a : 'encryption-key',
-                key: keyBytesResult.value,
-                description: jsonEntry.description,
-                createdAt: jsonEntry.createdAt
-            };
-            this._secrets.set(name, entry);
+        /* c8 ignore next 3 - defensive coding: unreachable via public API (open sets file, create sets isNew) */
+        if (!this._keystoreFile) {
+            return fail('No key store file to unlock');
         }
-        this._state = 'unlocked';
-        this._dirty = false;
-        return succeed(this);
+        return this._decryptVault(derivedKey);
     }
     /**
      * Locks the key store, clearing all secrets from memory.
@@ -238,7 +239,9 @@ export class KeyStore {
         // Clear secrets from memory (overwrite for security)
         if (this._secrets) {
             for (const entry of this._secrets.values()) {
-                entry.key.fill(0);
+                if (entry.type !== 'asymmetric-keypair') {
+                    entry.key.fill(0);
+                }
             }
             this._secrets.clear();
             this._secrets = undefined;
@@ -300,7 +303,15 @@ export class KeyStore {
         return succeed(Array.from(this._secrets.keys()));
     }
     /**
-     * Gets a secret by name.
+     * Gets a secret by name. Returns the {@link CryptoUtils.KeyStore.IKeyStoreEntry | discriminated union}
+     * — callers must check `entry.type` before accessing `key`/`id` since asymmetric
+     * entries carry no raw key material.
+     *
+     * SECURITY: for an escrow-enabled asymmetric-keypair entry the returned object
+     * carries `escrowedPrivateKeyJwk` in cleartext (same custody class as
+     * `publicKeyJwk`, gated by the same unlock) — do not log or serialize a
+     * `getSecret()` result casually.
+     *
      * @param name - Name of the secret
      * @returns Success with secret entry, Failure if not found or locked
      * @public
@@ -315,6 +326,27 @@ export class KeyStore {
         }
         return succeed(entry);
     }
+    /**
+     * Returns the public-key JWK for an asymmetric-keypair entry.
+     * Available without {@link CryptoUtils.KeyStore.IPrivateKeyStorage} since the
+     * public key lives in the vault metadata directly.
+     * @param name - Name of the entry
+     * @returns Success with the JWK, Failure if not found, locked, or wrong type
+     * @public
+     */
+    getPublicKeyJwk(name) {
+        if (!this._secrets) {
+            return fail('Key store is locked');
+        }
+        const entry = this._secrets.get(name);
+        if (!entry) {
+            return fail(`Secret '${name}' not found`);
+        }
+        if (entry.type !== 'asymmetric-keypair') {
+            return fail(`Secret '${name}' is not an asymmetric keypair (type: ${entry.type})`);
+        }
+        return succeed(entry.publicKeyJwk);
+    }
     /**
      * Checks if a secret exists.
      * @param name - Name of the secret
@@ -341,7 +373,6 @@ export class KeyStore {
         if (!name || name.length === 0) {
             return fail('Secret name cannot be empty');
         }
-        const replaced = this._secrets.has(name);
         // Generate a new random key
         const keyResult = await this._cryptoProvider.generateKey();
         /* c8 ignore next 3 - crypto provider errors tested but coverage intermittently missed */
@@ -355,19 +386,28 @@ export class KeyStore {
             description: options === null || options === void 0 ? void 0 : options.description,
             createdAt: getCurrentTimestamp()
         };
+        const existing = this._secrets.get(name);
+        const warning = existing ? await this._releaseEntryResources(existing) : undefined;
         this._secrets.set(name, entry);
         this._dirty = true;
-        return succeed({ entry, replaced });
+        return succeed({ entry, replaced: existing !== undefined, warning });
     }
     /**
-     * Imports an existing secret key.
+     * Imports raw 32-byte key material into the vault.
+     *
+     * Always validates that the key is exactly 32 bytes (AES-256). The optional
+     * `type` field is a classification label stored with the entry; it does not
+     * change the validation rules.  For importing UTF-8 API key strings (variable
+     * length), use {@link KeyStore.importApiKey} instead.
+     *
      * @param name - Unique name for the secret
-     * @param key - The 32-byte AES-256 key
-     * @param options - Optional description, whether to replace existing
+     * @param key - The 32-byte AES-256 key material
+     * @param options - Optional type classification, description, whether to replace existing
      * @returns Success with entry, Failure if locked, key invalid, or exists and !replace
      * @public
      */
-    importSecret(name, key, options) {
+    async importSecret(name, key, options) {
+        var _a;
         if (!this._secrets) {
             return fail('Key store is locked');
         }
@@ -377,20 +417,21 @@ export class KeyStore {
         if (key.length !== Constants.AES_256_KEY_SIZE) {
             return fail(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
         }
-        const exists = this._secrets.has(name);
-        if (exists && !(options === null || options === void 0 ? void 0 : options.replace)) {
+        const existing = this._secrets.get(name);
+        if (existing && !(options === null || options === void 0 ? void 0 : options.replace)) {
             return fail(`Secret '${name}' already exists - use replace=true to overwrite`);
         }
         const entry = {
             name,
-            type: 'encryption-key',
+            type: (_a = options === null || options === void 0 ? void 0 : options.type) !== null && _a !== void 0 ? _a : 'encryption-key',
             key: new Uint8Array(key), // Copy to prevent external modification
             description: options === null || options === void 0 ? void 0 : options.description,
             createdAt: getCurrentTimestamp()
         };
+        const warning = existing ? await this._releaseEntryResources(existing) : undefined;
         this._secrets.set(name, entry);
         this._dirty = true;
-        return succeed({ entry, replaced: exists });
+        return succeed({ entry, replaced: existing !== undefined, warning });
     }
     /**
      * Adds a secret derived from a password using PBKDF2.
@@ -417,8 +458,8 @@ export class KeyStore {
         if (!password || password.length === 0) {
             return fail('Password cannot be empty');
         }
-        const exists = this._secrets.has(name);
-        if (exists && !(options === null || options === void 0 ? void 0 : options.replace)) {
+        const existing = this._secrets.get(name);
+        if (existing && !(options === null || options === void 0 ? void 0 : options.replace)) {
             return fail(`Secret '${name}' already exists - use replace=true to overwrite`);
         }
         const iterations = (_a = options === null || options === void 0 ? void 0 : options.iterations) !== null && _a !== void 0 ? _a : DEFAULT_SECRET_ITERATIONS;
@@ -441,11 +482,13 @@ export class KeyStore {
             description: options === null || options === void 0 ? void 0 : options.description,
             createdAt: getCurrentTimestamp()
         };
+        const warning = existing ? await this._releaseEntryResources(existing) : undefined;
         this._secrets.set(name, entry);
         this._dirty = true;
         return succeed({
             entry,
-            replaced: exists,
+            replaced: existing !== undefined,
+            warning,
             keyDerivation: {
                 kdf: 'pbkdf2',
                 salt: this._cryptoProvider.toBase64(saltResult.value),
@@ -454,12 +497,183 @@ export class KeyStore {
         });
     }
     /**
-     * Removes a secret by name.
+     * Verifies that a candidate password derives the same key material currently
+     * stored under `name`, using the supplied
+     * {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+     *
+     * The keystore does not persist per-slot key derivation parameters with the
+     * entry — callers receive them from `addSecretFromPassword` and store them
+     * alongside the encrypted artifact (or wherever else makes sense). Pass
+     * those same parameters here for verification.
+     *
+     * Re-derives a key from `password` + `keyDerivation`, then compares it to
+     * the stored key material in constant time. Restricted to entries of type
+     * `'encryption-key'` — the type produced by `addSecretFromPassword`. Other
+     * symmetric types (`'api-key'`) and asymmetric entries are rejected so
+     * the boolean result reflects "this slot accepts this password" rather
+     * than an incidental byte-equality match against unrelated material.
+     *
+     * Note: the keystore does not currently flag whether an `'encryption-key'`
+     * entry was actually password-derived (vs. random via `addSecret` or raw
+     * via `importSecret`). A `true` result therefore means "the candidate
+     * password produces the same 32 bytes currently stored", which is what
+     * the equivalent consumer-side helper (`verifyGatePassword`) already
+     * implies for entries it manages.
+     *
+     * @param name - Name of the secret to verify against
+     * @param password - Candidate password to test
+     * @param keyDerivation - The key derivation parameters returned by
+     * `addSecretFromPassword` when the secret was created. Only
+     * `kdf: 'pbkdf2'` is supported.
+     * @returns Success(true) when the candidate matches the stored key,
+     * Success(false) when it does not, Failure if locked, secret missing,
+     * wrong type, unsupported `kdf`, or key derivation fails
+     * @public
+     */
+    async verifySecretFromPassword(name, password, keyDerivation) {
+        if (!this._secrets) {
+            return fail('Key store is locked');
+        }
+        if (!password || password.length === 0) {
+            return fail('Password cannot be empty');
+        }
+        if (keyDerivation.kdf !== 'pbkdf2') {
+            return fail(`Unsupported kdf '${keyDerivation.kdf}' (expected 'pbkdf2')`);
+        }
+        const entry = this._secrets.get(name);
+        if (!entry) {
+            return fail(`Secret '${name}' not found`);
+        }
+        if (entry.type !== 'encryption-key') {
+            return fail(`Secret '${name}' is not a password-verifiable encryption key (type: ${entry.type})`);
+        }
+        const saltResult = this._cryptoProvider.fromBase64(keyDerivation.salt);
+        if (saltResult.isFailure()) {
+            return fail(`Invalid salt: ${saltResult.message}`);
+        }
+        const derivedResult = await this._cryptoProvider.deriveKey(password, saltResult.value, keyDerivation.iterations);
+        /* c8 ignore next 3 - crypto provider errors covered in nodeCryptoProvider tests */
+        if (derivedResult.isFailure()) {
+            return fail(`Key derivation failed: ${derivedResult.message}`);
+        }
+        return succeed(KeyStore._timingSafeEqual(derivedResult.value, entry.key));
+    }
+    /**
+     * Adds a secret derived from a password using Argon2id (RFC 9106).
+     *
+     * The Argon2id provider must be supplied explicitly; the KeyStore does not
+     * hold one by default (consumers opt in by depending on the argon2 package).
+     *
+     * Returns the key derivation parameters so callers can store them alongside
+     * encrypted artifacts, enabling future re-derivation and verification.
+     *
+     * @param name - Unique name for the secret
+     * @param password - Password or passphrase
+     * @param argon2idProvider - Argon2id provider (Node or Browser implementation)
+     * @param options - Optional: Argon2id params (defaults to ARGON2ID_OWASP_MIN), description, replace flag
+     * @returns Success with entry and keyDerivation params, Failure if locked or invalid
+     * @public
+     */
+    async addSecretFromPasswordArgon2id(name, password, argon2idProvider, options) {
+        var _a;
+        if (!this._secrets) {
+            return fail('Key store is locked');
+        }
+        if (!name || name.length === 0) {
+            return fail('Secret name cannot be empty');
+        }
+        if (!password || password.length === 0) {
+            return fail('Password cannot be empty');
+        }
+        const existing = this._secrets.get(name);
+        if (existing && !(options === null || options === void 0 ? void 0 : options.replace)) {
+            return fail(`Secret '${name}' already exists - use replace=true to overwrite`);
+        }
+        const params = (_a = options === null || options === void 0 ? void 0 : options.params) !== null && _a !== void 0 ? _a : ARGON2ID_OWASP_MIN;
+        const saltResult = this._cryptoProvider.generateRandomBytes(MIN_SALT_LENGTH);
+        /* c8 ignore next 3 - crypto provider errors tested but coverage intermittently missed */
+        if (saltResult.isFailure()) {
+            return fail(`Failed to generate salt: ${saltResult.message}`);
+        }
+        const keyResult = await argon2idProvider.argon2id(password, saltResult.value, params);
+        if (keyResult.isFailure()) {
+            return fail(`Argon2id key derivation failed: ${keyResult.message}`);
+        }
+        if (keyResult.value.length !== Constants.AES_256_KEY_SIZE) {
+            return fail(`Argon2id outputBytes must be ${Constants.AES_256_KEY_SIZE} for KeyStore secrets, got ${keyResult.value.length}`);
+        }
+        const entry = {
+            name,
+            type: 'encryption-key',
+            key: keyResult.value,
+            description: options === null || options === void 0 ? void 0 : options.description,
+            createdAt: getCurrentTimestamp()
+        };
+        const warning = existing ? await this._releaseEntryResources(existing) : undefined;
+        this._secrets.set(name, entry);
+        this._dirty = true;
+        const keyDerivation = {
+            kdf: 'argon2id',
+            salt: this._cryptoProvider.toBase64(saltResult.value),
+            memoryKiB: params.memoryKiB,
+            iterations: params.iterations,
+            parallelism: params.parallelism
+        };
+        return succeed({ entry, replaced: existing !== undefined, warning, keyDerivation });
+    }
+    /**
+     * Verifies a candidate password against an Argon2id-derived entry using the
+     * supplied key derivation parameters. Constant-time comparison.
+     *
+     * @param name - Name of the secret to verify against
+     * @param password - Candidate password to test
+     * @param argon2idProvider - Argon2id provider (must produce bit-identical output for identical inputs)
+     * @param keyDerivation - The Argon2id key derivation parameters returned by `addSecretFromPasswordArgon2id`
+     * @returns Success(true) if candidate matches stored key, Success(false) if not,
+     * Failure if locked, secret missing, wrong type, or derivation fails
+     * @public
+     */
+    async verifySecretFromPasswordArgon2id(name, password, argon2idProvider, keyDerivation) {
+        if (!this._secrets) {
+            return fail('Key store is locked');
+        }
+        if (!password || password.length === 0) {
+            return fail('Password cannot be empty');
+        }
+        const entry = this._secrets.get(name);
+        if (!entry) {
+            return fail(`Secret '${name}' not found`);
+        }
+        if (entry.type !== 'encryption-key') {
+            return fail(`Secret '${name}' is not a password-verifiable encryption key (type: ${entry.type})`);
+        }
+        const saltResult = this._cryptoProvider.fromBase64(keyDerivation.salt);
+        if (saltResult.isFailure()) {
+            return fail(`Invalid salt: ${saltResult.message}`);
+        }
+        const params = {
+            memoryKiB: keyDerivation.memoryKiB,
+            iterations: keyDerivation.iterations,
+            parallelism: keyDerivation.parallelism,
+            outputBytes: entry.key.length
+        };
+        const derivedResult = await argon2idProvider.argon2id(password, saltResult.value, params);
+        if (derivedResult.isFailure()) {
+            return fail(`Argon2id key derivation failed: ${derivedResult.message}`);
+        }
+        return succeed(KeyStore._timingSafeEqual(derivedResult.value, entry.key));
+    }
+    /**
+     * Removes a secret by name. Vault-first: the in-memory vault entry is dropped
+     * before any storage cleanup runs. For asymmetric-keypair entries, best-effort
+     * calls {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete on the entry's
+     * `id`; a failure is reported via `warning` on the result but does not roll
+     * back the vault removal.
      * @param name - Name of the secret to remove
-     * @returns Success with removed entry, Failure if not found or locked
+     * @returns Success with removed entry (and optional warning), Failure if not found or locked
      * @public
      */
-    removeSecret(name) {
+    async removeSecret(name) {
         if (!this._secrets) {
             return fail('Key store is locked');
         }
@@ -467,11 +681,12 @@ export class KeyStore {
         if (!entry) {
             return fail(`Secret '${name}' not found`);
         }
-        // Clear the key before removing (security)
-        entry.key.fill(0);
+        // Vault-first: drop the in-memory entry before touching storage so a
+        // storage failure cannot block removal.
         this._secrets.delete(name);
         this._dirty = true;
-        return succeed(entry);
+        const warning = await this._releaseEntryResources(entry);
+        return succeed({ entry, warning });
     }
     /**
      * Imports an API key string into the vault.
@@ -482,7 +697,7 @@ export class KeyStore {
      * @returns Success with entry, Failure if locked, empty, or exists and !replace
      * @public
      */
-    importApiKey(name, apiKey, options) {
+    async importApiKey(name, apiKey, options) {
         if (!this._secrets) {
             return fail('Key store is locked');
         }
@@ -492,8 +707,8 @@ export class KeyStore {
         if (!apiKey || apiKey.length === 0) {
             return fail('API key cannot be empty');
         }
-        const exists = this._secrets.has(name);
-        if (exists && !(options === null || options === void 0 ? void 0 : options.replace)) {
+        const existing = this._secrets.get(name);
+        if (existing && !(options === null || options === void 0 ? void 0 : options.replace)) {
             return fail(`Secret '${name}' already exists - use replace=true to overwrite`);
         }
         const encoder = new TextEncoder();
@@ -504,9 +719,10 @@ export class KeyStore {
             description: options === null || options === void 0 ? void 0 : options.description,
             createdAt: getCurrentTimestamp()
         };
+        const warning = existing ? await this._releaseEntryResources(existing) : undefined;
         this._secrets.set(name, entry);
         this._dirty = true;
-        return succeed({ entry, replaced: exists });
+        return succeed({ entry, replaced: existing !== undefined, warning });
     }
     /**
      * Retrieves an API key string by name.
@@ -529,6 +745,269 @@ export class KeyStore {
         const decoder = new TextDecoder();
         return succeed(decoder.decode(entry.key));
     }
+    /**
+     * Imports arbitrary raw bytes into the vault with type `'opaque'`.
+     *
+     * Unlike {@link KeyStore.importSecret} (which enforces a 32-byte AES-256 key)
+     * and {@link KeyStore.importApiKey} (which UTF-8 encodes a string), this
+     * accepts a byte buffer of any length and stores it verbatim — including
+     * embedded NUL bytes. Use it for byte blobs that are neither a fixed-size key
+     * nor a UTF-8 string (e.g. a serialized credential bundle), so they are not
+     * mistyped as `'api-key'`.
+     *
+     * @param name - Unique name for the secret
+     * @param bytes - The raw bytes to store
+     * @param options - Optional description, initial metadata, whether to replace existing
+     * @returns Success with entry, Failure if locked, empty, or exists and !replace
+     * @public
+     */
+    async importSecretBytes(name, bytes, options) {
+        if (!this._secrets) {
+            return fail('Key store is locked');
+        }
+        if (!name || name.length === 0) {
+            return fail('Secret name cannot be empty');
+        }
+        const existing = this._secrets.get(name);
+        if (existing && !(options === null || options === void 0 ? void 0 : options.replace)) {
+            return fail(`Secret '${name}' already exists - use replace=true to overwrite`);
+        }
+        const entry = {
+            name,
+            type: 'opaque',
+            key: new Uint8Array(bytes), // Copy to prevent external modification
+            description: options === null || options === void 0 ? void 0 : options.description,
+            metadata: options === null || options === void 0 ? void 0 : options.metadata,
+            createdAt: getCurrentTimestamp()
+        };
+        const warning = existing ? await this._releaseEntryResources(existing) : undefined;
+        this._secrets.set(name, entry);
+        this._dirty = true;
+        return succeed({ entry, replaced: existing !== undefined, warning });
+    }
+    /**
+     * Retrieves the raw stored bytes for a symmetric entry, returned verbatim
+     * (never UTF-8 decoded). Intended for `'opaque'` entries but works for any
+     * symmetric type; asymmetric-keypair entries carry no raw key material and
+     * are rejected.
+     *
+     * @param name - Name of the secret
+     * @returns Success with a copy of the stored bytes, Failure if not found,
+     * locked, or the entry is asymmetric
+     * @public
+     */
+    getSecretBytes(name) {
+        if (!this._secrets) {
+            return fail('Key store is locked');
+        }
+        const entry = this._secrets.get(name);
+        if (!entry) {
+            return fail(`Secret '${name}' not found`);
+        }
+        if (entry.type === 'asymmetric-keypair') {
+            return fail(`Secret '${name}' is an asymmetric keypair, not raw byte material (type: ${entry.type})`);
+        }
+        // Copy so callers cannot mutate the in-memory vault buffer.
+        return succeed(new Uint8Array(entry.key));
+    }
+    /**
+     * Replaces the mutable metadata on a symmetric entry and stamps `updatedAt`
+     * with the current timestamp. Does NOT touch the secret `key` bytes — the
+     * material reads back identically afterward.
+     *
+     * Metadata is non-secret by contract but physically lives inside the vault
+     * ciphertext (see {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntry.metadata}).
+     *
+     * @param name - Name of the secret to update
+     * @param value - New metadata value (replaces any prior metadata)
+     * @returns Success with the updated entry, Failure if not found, locked, or
+     * the entry is asymmetric
+     * @public
+     */
+    setSecretMetadata(name, value) {
+        if (!this._secrets) {
+            return fail('Key store is locked');
+        }
+        const entry = this._secrets.get(name);
+        if (!entry) {
+            return fail(`Secret '${name}' not found`);
+        }
+        if (entry.type === 'asymmetric-keypair') {
+            return fail(`Secret '${name}' is an asymmetric keypair; metadata is only supported on symmetric entries (type: ${entry.type})`);
+        }
+        const updated = Object.assign(Object.assign({}, entry), { metadata: value, updatedAt: getCurrentTimestamp() });
+        this._secrets.set(name, updated);
+        this._dirty = true;
+        return succeed(updated);
+    }
+    // ============================================================================
+    // Asymmetric Keypair Management
+    // ============================================================================
+    /**
+     * Adds a new asymmetric keypair to the vault. Storage-first: the private key
+     * is stored under a freshly-minted `id` before the public-key vault entry is
+     * committed. If the storage call fails, no vault entry is written and the
+     * operation returns Failure.
+     *
+     * When `replace: true` displaces an existing entry (asymmetric or symmetric),
+     * a fresh `id` is minted; the displaced entry's resources are released
+     * best-effort. Failure of the storage delete is reported via `warning` on the
+     * result but does not roll back the replacement.
+     *
+     * Requires a {@link CryptoUtils.KeyStore.IPrivateKeyStorage} backend
+     * supplied at construction.
+     *
+     * Extractability of the generated private key defaults to the storage
+     * backend's {@link CryptoUtils.KeyStore.IPrivateKeyStorage.supportsNonExtractable}.
+     * `options.extractable` overrides that default for this key only; requesting
+     * `extractable: false` against a backend that cannot store non-extractable
+     * keys fails loudly rather than silently generating an extractable key.
+     *
+     * @param name - Unique name for the entry
+     * @param options - Algorithm, optional description, replace flag, extractable override
+     * @returns Success with the new entry, Failure if locked, no provider, storage write failed,
+     * or the requested extractability cannot be honored by the backend
+     * @public
+     */
+    async addKeyPair(name, options) {
+        var _a;
+        if (!this._secrets) {
+            return fail('Key store is locked');
+        }
+        if (!name || name.length === 0) {
+            return fail('Entry name cannot be empty');
+        }
+        if (!this._privateKeyStorage) {
+            return fail('No private key storage configured');
+        }
+        const existing = this._secrets.get(name);
+        if (existing && !options.replace) {
+            return fail(`Secret '${name}' already exists - use replace=true to overwrite`);
+        }
+        // Generate the keypair before touching storage. extractable=true on backends
+        // that round-trip via JWK; extractable=false on backends that hold CryptoKey
+        // refs directly. `options.extractable` overrides the backend-derived default
+        // for this key only; a caller-requested non-extractable key against a
+        // backend that cannot store one fails loudly rather than silently
+        // upgrading to extractable.
+        const backendExtractable = !this._privateKeyStorage.supportsNonExtractable;
+        if (options.extractable === false && backendExtractable) {
+            return fail(`Cannot create non-extractable keypair for '${name}': storage backend does not support non-extractable keys`);
+        }
+        // Extractability of the LIVE stored key. Escrow is orthogonal — it never
+        // changes this; the escrow copy is captured separately from a transient
+        // extractable key.
+        const liveExtractable = (_a = options.extractable) !== null && _a !== void 0 ? _a : backendExtractable;
+        // For escrow we must be able to export the private key to JWK, which only
+        // works on an extractable key, so the transient keypair is generated
+        // extractable regardless of `liveExtractable`. Without escrow it is
+        // generated directly at the live setting.
+        const generateExtractable = options.escrow === true ? true : liveExtractable;
+        const keyPairResult = await this._cryptoProvider.generateKeyPair(options.algorithm, generateExtractable);
+        /* c8 ignore next 3 - crypto provider errors covered in nodeCryptoProvider tests; cannot be triggered here without mocking */
+        if (keyPairResult.isFailure()) {
+            return fail(`Failed to generate keypair for '${name}': ${keyPairResult.message}`);
+        }
+        const { publicKey, privateKey } = keyPairResult.value;
+        const jwkResult = await this._cryptoProvider.exportPublicKeyJwk(publicKey);
+        /* c8 ignore next 3 - export of an extractable freshly-generated public key is hard to fail */
+        if (jwkResult.isFailure()) {
+            return fail(`Failed to export public key for '${name}': ${jwkResult.message}`);
+        }
+        // Escrow (opt-in). The bare private key exists only as three local
+        // artifacts, none of which is returned or logged: (1) the transient
+        // extractable `privateKey` above; (2) the exported `escrowedPrivateKeyJwk`,
+        // which is carried in the vault entry (same custody class as the public
+        // JWK); (3) a freshly re-imported non-extractable key handed to `store()`
+        // when the live copy must be non-extractable. When the live copy is
+        // extractable the transient key IS the live copy and is stored directly.
+        let escrowedPrivateKeyJwk;
+        let keyToStore = privateKey;
+        if (options.escrow === true) {
+            // Chain the export → (conditional) non-extractable re-import so the
+            // failure dispatch lives in ts-utils rather than in local branch nodes.
+            // When the live copy is extractable the transient key IS the live copy;
+            // otherwise a freshly re-imported non-extractable key is stored instead.
+            const escrowPrepResult = await (await this._exportPrivateKeyJwk(privateKey, name)).thenOnSuccess(async (jwk) => {
+                if (liveExtractable) {
+                    return succeed({ jwk, keyToStore: privateKey });
+                }
+                return (await this._importEscrowedPrivateKey(jwk, options.algorithm, false))
+                    .withErrorFormat((msg) => `Failed to prepare non-extractable key for '${name}': ${msg}`)
+                    .onSuccess((reimported) => succeed({ jwk, keyToStore: reimported }));
+            });
+            /* c8 ignore next 3 - escrowPrepResult only fails if exporting or re-importing a freshly-generated valid key fails, which a healthy provider cannot do (same untestable class as the keyPairResult/jwkResult/idResult guards); the import-failure path itself is covered via getKeyPair rehydration of a malformed escrow JWK */
+            if (escrowPrepResult.isFailure()) {
+                return fail(escrowPrepResult.message);
+            }
+            ({ jwk: escrowedPrivateKeyJwk, keyToStore } = escrowPrepResult.value);
+        }
+        const idResult = this._generateId();
+        /* c8 ignore next 3 - random-bytes failure is hard to trigger with a healthy provider */
+        if (idResult.isFailure()) {
+            return fail(`Failed to mint storage id for '${name}': ${idResult.message}`);
+        }
+        const id = idResult.value;
+        // Storage-first: write the private key before committing the vault entry.
+        const storeResult = await this._privateKeyStorage.store(id, keyToStore);
+        if (storeResult.isFailure()) {
+            return fail(`Failed to persist private key for '${name}': ${storeResult.message}`);
+        }
+        const entry = {
+            name,
+            type: 'asymmetric-keypair',
+            id,
+            algorithm: options.algorithm,
+            publicKeyJwk: jwkResult.value,
+            escrowedPrivateKeyJwk,
+            description: options.description,
+            createdAt: getCurrentTimestamp()
+        };
+        const warning = existing ? await this._releaseEntryResources(existing) : undefined;
+        this._secrets.set(name, entry);
+        this._dirty = true;
+        return succeed({ entry, replaced: existing !== undefined, warning });
+    }
+    /**
+     * Retrieves the keypair for an asymmetric-keypair entry. The private key is
+     * loaded from {@link CryptoUtils.KeyStore.IPrivateKeyStorage} on every call —
+     * the keystore never caches private `CryptoKey` references between calls.
+     * The public key is re-imported from the vault's JWK so callers always
+     * receive a `CryptoKey` rather than the JWK form.
+     *
+     * With `options.rehydrate: true`, if the storage backend holds no blob for
+     * the entry's `id` and the entry carries an `escrowedPrivateKeyJwk` (see
+     * `addKeyPair(name, { escrow: true })`), the escrowed JWK is imported and
+     * stored under the entry's `id` before being returned — recovering the
+     * private key on a fresh device from the vault plus master password. This is
+     * fill-a-gap only: an existing storage blob is never overwritten.
+     *
+     * @param name - Name of the entry
+     * @param options - Optional {@link CryptoUtils.KeyStore.IGetKeyPairOptions}
+     * (currently the `rehydrate` escrow-recovery flag).
+     * @returns Success with `{ publicKey, privateKey }`, Failure if not found,
+     * locked, wrong type, no provider, or storage load (and any escrow
+     * rehydration) failed.
+     * @public
+     */
+    async getKeyPair(name, options) {
+        if (!this._secrets) {
+            return fail('Key store is locked');
+        }
+        const entry = this._secrets.get(name);
+        if (!entry) {
+            return fail(`Secret '${name}' not found`);
+        }
+        if (entry.type !== 'asymmetric-keypair') {
+            return fail(`Secret '${name}' is not an asymmetric keypair (type: ${entry.type})`);
+        }
+        if (!this._privateKeyStorage) {
+            return fail('No private key storage configured');
+        }
+        return (await this._loadOrRehydratePrivateKey(name, entry, options)).thenOnSuccess(async (privateKey) => (await this._cryptoProvider.importPublicKeyJwk(entry.publicKeyJwk, entry.algorithm))
+            .withErrorFormat((msg) => `Failed to re-import public key for '${name}': ${msg}`)
+            .onSuccess((publicKey) => succeed({ publicKey, privateKey })));
+    }
     /**
      * Lists secret names filtered by type.
      * @param type - The secret type to filter by
@@ -568,7 +1047,8 @@ export class KeyStore {
         if (oldName !== newName && this._secrets.has(newName)) {
             return fail(`Secret '${newName}' already exists`);
         }
-        // Create new entry with new name (preserve type)
+        // Create new entry with new name. For asymmetric entries the spread
+        // preserves `id` so the storage handle survives the rename.
         const newEntry = Object.assign(Object.assign({}, entry), { name: newName });
         this._secrets.delete(oldName);
         this._secrets.set(newName, newEntry);
@@ -598,49 +1078,29 @@ export class KeyStore {
         if (keyResult.isFailure()) {
             return fail(`Key derivation failed: ${keyResult.message}`);
         }
-        // Build vault contents
-        const secrets = {};
-        for (const [name, entry] of this._secrets) {
-            secrets[name] = {
-                name: entry.name,
-                type: entry.type,
-                key: this._cryptoProvider.toBase64(entry.key),
-                description: entry.description,
-                createdAt: entry.createdAt
-            };
-        }
-        const vaultContents = {
-            version: KEYSTORE_FORMAT,
-            secrets
-        };
-        // Serialize and encrypt
-        const jsonResult = captureResult(() => JSON.stringify(vaultContents));
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (jsonResult.isFailure()) {
-            return fail(`Failed to serialize vault: ${jsonResult.message}`);
+        return this._encryptVault(keyResult.value);
+    }
+    /**
+     * Saves the key store using a pre-derived key, bypassing PBKDF2 key
+     * derivation. Use this when the derived key has been stored externally
+     * (e.g., in another key store) and the original password is no longer
+     * available.
+     *
+     * The supplied key must be the same key that was (or would be) derived
+     * from the master password using the key store's PBKDF2 parameters.
+     *
+     * @param derivedKey - The pre-derived master key (32 bytes for AES-256)
+     * @returns Success with IKeyStoreFile, Failure if locked or key invalid
+     * @public
+     */
+    async saveWithKey(derivedKey) {
+        if (!this._secrets || !this._salt) {
+            return fail('Key store is locked');
         }
-        const encryptResult = await this._cryptoProvider.encrypt(jsonResult.value, keyResult.value);
-        /* c8 ignore next 3 - crypto provider errors tested but coverage intermittently missed */
-        if (encryptResult.isFailure()) {
-            return fail(`Encryption failed: ${encryptResult.message}`);
+        if (derivedKey.length !== Constants.AES_256_KEY_SIZE) {
+            return fail(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${derivedKey.length}`);
         }
-        const { iv, authTag, encryptedData } = encryptResult.value;
-        const keystoreFileData = {
-            format: KEYSTORE_FORMAT,
-            algorithm: Constants.DEFAULT_ALGORITHM,
-            iv: this._cryptoProvider.toBase64(iv),
-            authTag: this._cryptoProvider.toBase64(authTag),
-            encryptedData: this._cryptoProvider.toBase64(encryptedData),
-            keyDerivation: {
-                kdf: 'pbkdf2',
-                salt: this._cryptoProvider.toBase64(this._salt),
-                iterations: this._iterations
-            }
-        };
-        this._keystoreFile = keystoreFileData;
-        this._dirty = false;
-        this._isNew = false;
-        return succeed(keystoreFileData);
+        return this._encryptVault(derivedKey);
     }
     /**
      * Changes the master password.
@@ -708,6 +1168,9 @@ export class KeyStore {
         if (secretResult.isFailure()) {
             return fail(`encryptByName: ${secretResult.message}`);
         }
+        if (secretResult.value.type === 'asymmetric-keypair') {
+            return fail(`encryptByName: secret '${secretName}' is an asymmetric keypair, not symmetric key material`);
+        }
         return createEncryptedFile({
             content,
             secretName,
@@ -735,6 +1198,9 @@ export class KeyStore {
             if (!entry) {
                 return fail(`Secret '${secretName}' not found in key store`);
             }
+            if (entry.type === 'asymmetric-keypair') {
+                return fail(`Secret '${secretName}' is an asymmetric keypair, not symmetric key material`);
+            }
             return succeed(entry.key);
         };
         return succeed(provider);
@@ -754,5 +1220,292 @@ export class KeyStore {
             cryptoProvider: this._cryptoProvider
         });
     }
+    // ============================================================================
+    // Private: Vault Encryption / Decryption
+    // ============================================================================
+    /**
+     * Encrypts the vault with a derived key and returns the key store file.
+     * Shared by `save()` and `saveWithKey()`.
+     */
+    async _encryptVault(derivedKey) {
+        // _secrets and _salt are guaranteed non-undefined by callers
+        const secrets = this._secrets;
+        const salt = this._salt;
+        // Build vault contents
+        const secretEntries = {};
+        for (const [name, entry] of secrets) {
+            if (entry.type === 'asymmetric-keypair') {
+                secretEntries[name] = {
+                    name: entry.name,
+                    type: entry.type,
+                    id: entry.id,
+                    algorithm: entry.algorithm,
+                    publicKeyJwk: entry.publicKeyJwk,
+                    escrowedPrivateKeyJwk: entry.escrowedPrivateKeyJwk,
+                    description: entry.description,
+                    createdAt: entry.createdAt
+                };
+            }
+            else {
+                secretEntries[name] = {
+                    name: entry.name,
+                    type: entry.type,
+                    key: this._cryptoProvider.toBase64(entry.key),
+                    description: entry.description,
+                    metadata: entry.metadata,
+                    createdAt: entry.createdAt,
+                    updatedAt: entry.updatedAt
+                };
+            }
+        }
+        const vaultContents = {
+            version: KEYSTORE_FORMAT,
+            secrets: secretEntries
+        };
+        // Serialize and encrypt
+        const jsonResult = captureResult(() => JSON.stringify(vaultContents));
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (jsonResult.isFailure()) {
+            return fail(`Failed to serialize vault: ${jsonResult.message}`);
+        }
+        const encryptResult = await this._cryptoProvider.encrypt(jsonResult.value, derivedKey);
+        /* c8 ignore next 3 - crypto provider errors tested but coverage intermittently missed */
+        if (encryptResult.isFailure()) {
+            return fail(`Encryption failed: ${encryptResult.message}`);
+        }
+        const { iv, authTag, encryptedData } = encryptResult.value;
+        const keystoreFileData = {
+            format: KEYSTORE_FORMAT,
+            algorithm: Constants.DEFAULT_ALGORITHM,
+            iv: this._cryptoProvider.toBase64(iv),
+            authTag: this._cryptoProvider.toBase64(authTag),
+            encryptedData: this._cryptoProvider.toBase64(encryptedData),
+            keyDerivation: {
+                kdf: 'pbkdf2',
+                salt: this._cryptoProvider.toBase64(salt),
+                iterations: this._iterations
+            }
+        };
+        this._keystoreFile = keystoreFileData;
+        this._dirty = false;
+        this._isNew = false;
+        return succeed(keystoreFileData);
+    }
+    /**
+     * Decrypts the vault with a derived key and loads secrets into memory.
+     * Shared by `unlock()` and `unlockWithKey()`.
+     */
+    async _decryptVault(derivedKey) {
+        const keystoreFile = this._keystoreFile;
+        /* c8 ignore next 3 - defensive: _decryptVault is only called after a successful open() or create() */
+        if (keystoreFile === undefined) {
+            return fail('No key store file loaded');
+        }
+        const ivResult = this._cryptoProvider.fromBase64(keystoreFile.iv);
+        const authTagResult = this._cryptoProvider.fromBase64(keystoreFile.authTag);
+        const encryptedDataResult = this._cryptoProvider.fromBase64(keystoreFile.encryptedData);
+        /* c8 ignore next 9 - base64 decode errors tested but coverage intermittently missed */
+        if (ivResult.isFailure()) {
+            return fail(`Invalid IV in key store file: ${ivResult.message}`);
+        }
+        if (authTagResult.isFailure()) {
+            return fail(`Invalid auth tag in key store file: ${authTagResult.message}`);
+        }
+        if (encryptedDataResult.isFailure()) {
+            return fail(`Invalid encrypted data in key store file: ${encryptedDataResult.message}`);
+        }
+        const decryptResult = await this._cryptoProvider.decrypt(encryptedDataResult.value, derivedKey, ivResult.value, authTagResult.value);
+        if (decryptResult.isFailure()) {
+            return fail('Incorrect password or corrupted key store');
+        }
+        // Parse the vault contents
+        const parseResult = captureResult(() => JSON.parse(decryptResult.value));
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (parseResult.isFailure()) {
+            return fail(`Failed to parse vault contents: ${parseResult.message}`);
+        }
+        const vaultResult = keystoreVaultContents.convert(parseResult.value);
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (vaultResult.isFailure()) {
+            return fail(`Invalid vault format: ${vaultResult.message}`);
+        }
+        // Build secrets into local variables to avoid partial state on failure
+        const saltResult = this._cryptoProvider.fromBase64(keystoreFile.keyDerivation.salt);
+        if (saltResult.isFailure()) {
+            return fail(`Invalid salt in key store file: ${saltResult.message}`);
+        }
+        const secrets = new Map();
+        for (const [name, jsonEntry] of Object.entries(vaultResult.value.secrets)) {
+            if (jsonEntry.type === 'asymmetric-keypair') {
+                const entry = {
+                    name,
+                    type: jsonEntry.type,
+                    id: jsonEntry.id,
+                    algorithm: jsonEntry.algorithm,
+                    publicKeyJwk: jsonEntry.publicKeyJwk,
+                    escrowedPrivateKeyJwk: jsonEntry.escrowedPrivateKeyJwk,
+                    description: jsonEntry.description,
+                    createdAt: jsonEntry.createdAt
+                };
+                secrets.set(name, entry);
+            }
+            else {
+                const keyBytesResult = this._cryptoProvider.fromBase64(jsonEntry.key);
+                /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+                if (keyBytesResult.isFailure()) {
+                    return fail(`Invalid key for secret '${name}': ${keyBytesResult.message}`);
+                }
+                const entry = {
+                    name,
+                    type: jsonEntry.type,
+                    key: keyBytesResult.value,
+                    description: jsonEntry.description,
+                    metadata: jsonEntry.metadata,
+                    createdAt: jsonEntry.createdAt,
+                    updatedAt: jsonEntry.updatedAt
+                };
+                secrets.set(name, entry);
+            }
+        }
+        // All validation passed — commit state atomically
+        this._salt = saltResult.value;
+        this._secrets = secrets;
+        this._state = 'unlocked';
+        this._dirty = false;
+        return succeed(this);
+    }
+    // ============================================================================
+    // Private: Helpers for asymmetric flows
+    // ============================================================================
+    /**
+     * Releases the resources held by an entry being displaced from the vault.
+     * Symmetric entries get their key buffer zeroed in place. Asymmetric entries
+     * have their private-key blob best-effort deleted from
+     * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}; if the storage call fails,
+     * a warning string is returned but the displacement still proceeds — the
+     * orphaned blob is left for consumer-side GC. Without a configured provider,
+     * asymmetric cleanup is silently skipped.
+     * @returns A warning string if storage cleanup failed, otherwise undefined.
+     */
+    async _releaseEntryResources(entry) {
+        if (entry.type === 'asymmetric-keypair') {
+            if (!this._privateKeyStorage) {
+                return undefined;
+            }
+            const deleteResult = await this._privateKeyStorage.delete(entry.id);
+            if (deleteResult.isFailure()) {
+                return `Failed to delete prior storage blob for '${entry.name}' (id ${entry.id}): ${deleteResult.message}`;
+            }
+            return undefined;
+        }
+        entry.key.fill(0);
+        return undefined;
+    }
+    /**
+     * Exports the transient extractable private `CryptoKey` to a JWK for escrow,
+     * via WebCrypto's `exportKey('jwk', ...)` (cross-runtime through
+     * `globalThis.crypto.subtle`). The result is carried in the vault entry — the
+     * same custody class as the public JWK — and is never returned from a public
+     * method nor logged.
+     */
+    async _exportPrivateKeyJwk(privateKey, name) {
+        return captureAsyncResult(() => globalThis.crypto.subtle.exportKey('jwk', privateKey)).withErrorFormat((msg) => `Failed to export private key for escrow of '${name}': ${msg}`);
+    }
+    /**
+     * Re-imports an escrowed private-key JWK as a `CryptoKey` for `algorithm`
+     * with the requested extractability. The WebCrypto JWK-import descriptor is
+     * shared between the public and private halves for every supported algorithm,
+     * so `IKeyPairAlgorithmParams.importPublicKey` is reused; the private/public
+     * distinction is carried by the requested usages (see
+     * {@link KeyStore._privateKeyUsagesFor}). Cross-runtime through
+     * `globalThis.crypto.subtle`.
+     */
+    async _importEscrowedPrivateKey(jwk, algorithm, extractable) {
+        const params = keyPairAlgorithmParams[algorithm];
+        const usages = KeyStore._privateKeyUsagesFor(jwk, params);
+        return captureAsyncResult(() => globalThis.crypto.subtle.importKey('jwk', jwk, params.importPublicKey, extractable, usages)).withErrorFormat((msg) => `Failed to import escrowed private key: ${msg}`);
+    }
+    /**
+     * Loads the private key for `entry` from storage, or — when
+     * `options.rehydrate` is set, storage holds no blob, and the entry carries an
+     * escrowed JWK — imports the escrowed key, persists it under the entry's `id`
+     * (fill-a-gap; never overwrites an existing blob), and returns it.
+     */
+    async _loadOrRehydratePrivateKey(name, entry, options) {
+        // Non-undefined by getKeyPair's precondition check.
+        const storage = this._privateKeyStorage;
+        const loadResult = await storage.load(entry.id);
+        if (loadResult.isSuccess()) {
+            return succeed(loadResult.value);
+        }
+        if ((options === null || options === void 0 ? void 0 : options.rehydrate) !== true || entry.escrowedPrivateKeyJwk === undefined) {
+            return fail(`Failed to load private key for '${name}': ${loadResult.message}`);
+        }
+        // Fill-a-gap recovery: import the escrowed key non-extractable where the
+        // backend supports it (extractable otherwise, since a JWK-round-tripping
+        // backend cannot store a non-extractable key), then persist it.
+        const backendExtractable = !storage.supportsNonExtractable;
+        const importResult = await this._importEscrowedPrivateKey(entry.escrowedPrivateKeyJwk, entry.algorithm, backendExtractable);
+        if (importResult.isFailure()) {
+            return fail(`Failed to rehydrate private key for '${name}' from escrow: ${importResult.message}`);
+        }
+        const storeResult = await storage.store(entry.id, importResult.value);
+        if (storeResult.isFailure()) {
+            return fail(`Failed to persist rehydrated private key for '${name}': ${storeResult.message}`);
+        }
+        return succeed(importResult.value);
+    }
+    /**
+     * Computes the key usages to request when importing an escrowed private JWK.
+     * Mirrors `EncryptedFilePrivateKeyStorage`: intersect the algorithm's private
+     * usages (its keypair usages minus the public-only ones) with the JWK's
+     * recorded `key_ops` so we request exactly the operations the stored key
+     * supports; fall back to the algorithm's private usages when `key_ops` is
+     * absent.
+     */
+    static _privateKeyUsagesFor(jwk, params) {
+        const privateUsages = params.keyPairUsages.filter((usage) => !PUBLIC_ONLY_USAGES.includes(usage));
+        const keyOps = jwk.key_ops;
+        if (keyOps === undefined) {
+            return [...privateUsages];
+        }
+        return privateUsages.filter((usage) => keyOps.includes(usage));
+    }
+    /**
+     * Constant-time byte comparison. Returns false immediately for length
+     * mismatch (length is not secret); for equal-length inputs, walks the full
+     * buffer accumulating differences via XOR so the running time does not leak
+     * the position of the first differing byte.
+     */
+    static _timingSafeEqual(a, b) {
+        /* c8 ignore next 3 - defensive: callers compare equal-length 32-byte PBKDF2 keys */
+        if (a.length !== b.length) {
+            return false;
+        }
+        let diff = 0;
+        for (let i = 0; i < a.length; i++) {
+            // eslint-disable-next-line no-bitwise
+            diff |= a[i] ^ b[i];
+        }
+        return diff === 0;
+    }
+    /**
+     * Mints a fresh UUID v4 storage handle using the crypto provider's
+     * {@link CryptoUtils.ICryptoProvider.generateRandomBytes | generateRandomBytes}.
+     * Random-bytes failures propagate as Failure.
+     */
+    _generateId() {
+        return this._cryptoProvider.generateRandomBytes(16).onSuccess((bytes) => {
+            // Per RFC 4122 §4.4: set version (4) and variant (10xx) bits.
+            // eslint-disable-next-line no-bitwise
+            bytes[6] = (bytes[6] & 0x0f) | 0x40;
+            // eslint-disable-next-line no-bitwise
+            bytes[8] = (bytes[8] & 0x3f) | 0x80;
+            const hex = Array.from(bytes)
+                .map((b) => b.toString(16).padStart(2, '0'))
+                .join('');
+            return succeed(`${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`);
+        });
+    }
 }
 //# sourceMappingURL=keyStore.js.map