@fgv/ts-extras 5.1.0-17 → 5.1.0-19

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

@@ -17,9 +17,9 @@
 // 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 { Converters } from '@fgv/ts-utils';
+import { Converters, succeed, Validators } from '@fgv/ts-utils';
 import { base64String, encryptionAlgorithm, keyDerivationParams } from '../converters';
-import { allKeyStoreSecretTypes, KEYSTORE_FORMAT } from './model';
+import { allKeyPairAlgorithms, allKeyStoreSecretTypes, allKeyStoreSymmetricSecretTypes, KEYSTORE_FORMAT, allKeyStoreAsymmetricSecretTypes } from './model';
 // ============================================================================
 // Key Store Format Converter
 // ============================================================================
@@ -31,31 +31,123 @@ export const keystoreFormat = Converters.enumeratedValue([
     KEYSTORE_FORMAT
 ]);
 // ============================================================================
-// Secret Type Converter
+// Secret Type Converters
 // ============================================================================
 /**
- * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | key store secret type} discriminator.
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | any key store secret type} discriminator.
+ * Accepts both symmetric and asymmetric type values.
  * @public
  */
 export const keystoreSecretType = Converters.enumeratedValue(allKeyStoreSecretTypes);
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSymmetricSecretType | symmetric secret type} discriminator.
+ * Accepts only `'encryption-key'` and `'api-key'`.
+ * @public
+ */
+export const keystoreSymmetricSecretType = Converters.enumeratedValue(allKeyStoreSymmetricSecretTypes);
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreAsymmetricSecretType | asymmetric secret type} discriminator.
+ * Accepts only `'asymmetric-keypair'`.
+ * @public
+ */
+export const keystoreAsymmetricSecretType = Converters.enumeratedValue(allKeyStoreAsymmetricSecretTypes);
+// ============================================================================
+// Key Pair Algorithm Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyPairAlgorithm | key pair algorithm}.
+ * @public
+ */
+export const keyPairAlgorithm = Converters.enumeratedValue(allKeyPairAlgorithms);
 // ============================================================================
-// Secret Entry Converters
+// JWK Shape Validator
 // ============================================================================
 /**
- * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSecretEntryJson | key store secret entry} in JSON format.
- * The `type` field is optional for backwards compatibility — missing means `'encryption-key'`.
+ * In-place shape check for a JSON Web Key. Asserts only that the input is a
+ * non-array object whose `kty` discriminator is a string; every other JWK
+ * field passes through untouched. This is intentionally **not** a true JWK
+ * validator — per-algorithm correctness (RSA `n`/`e`, EC `crv`/`x`/`y`,
+ * key-size constraints, etc.) is delegated to `crypto.subtle.importKey` at
+ * first use, which is the authoritative checker. The "shape" suffix in the
+ * name is the warning sign for readers expecting full validation.
+ * @remarks
+ * Built with `Validators.object` (in-place, non-strict) so unknown JWK fields
+ * survive the round-trip; the cast to `FieldValidators<JsonWebKey>` is required
+ * only because TypeScript's mapped type demands an entry for every key in
+ * `JsonWebKey`. At runtime the `ObjectValidator` only inspects keys present in
+ * the field-validators map.
  * @public
  */
-export const keystoreSecretEntryJson = Converters.object({
+export const jsonWebKeyShape = Validators.object({
+    kty: Validators.string
+});
+// ============================================================================
+// Symmetric Secret Entry Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson | symmetric secret entry} in JSON form.
+ *
+ * @remarks
+ * Backwards compatibility with vaults written before asymmetric-keypair
+ * support: those entries may lack the `type` discriminator on the wire. To
+ * keep the model type honest (`type` is required on
+ * {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson}, see its docs),
+ * we declare `type` in `optionalFields` so the inner `Converters.object` will
+ * accept input without it, then `.map()` injects the default
+ * `'encryption-key'` when missing. The output therefore always carries the
+ * discriminator and downstream code never sees the legacy missing-type form.
+ *
+ * @public
+ */
+export const keystoreSymmetricEntryJson = Converters.object({
     name: Converters.string,
-    type: keystoreSecretType,
+    type: keystoreSymmetricSecretType,
     key: base64String,
     description: Converters.string,
     createdAt: Converters.string
 }, {
+    // `type` is optional at the input layer for legacy-vault compatibility;
+    // the .map() below normalizes by injecting the default.
     optionalFields: ['type', 'description']
+}).map((entry) => {
+    var _a;
+    return succeed(Object.assign(Object.assign({}, entry), { type: (_a = entry.type) !== null && _a !== void 0 ? _a : 'encryption-key' }));
 });
 // ============================================================================
+// Asymmetric Keypair Entry Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreAsymmetricEntryJson | asymmetric keypair entry} in JSON form.
+ * The `publicKeyJwk` field passes through {@link CryptoUtils.KeyStore.Converters.jsonWebKeyShape | jsonWebKeyShape}
+ * (shape check only — see its docs); cryptographic correctness is enforced by
+ * `crypto.subtle.importKey` at use.
+ * @public
+ */
+export const keystoreAsymmetricEntryJson = Converters.object({
+    name: Converters.string,
+    type: keystoreAsymmetricSecretType,
+    id: Converters.string,
+    algorithm: keyPairAlgorithm,
+    publicKeyJwk: jsonWebKeyShape,
+    description: Converters.string.optional(),
+    createdAt: Converters.string
+});
+// ============================================================================
+// Discriminated-Union Entry Converter
+// ============================================================================
+/**
+ * Discriminated-union converter for any {@link CryptoUtils.KeyStore.IKeyStoreEntryJson | key store entry} in JSON form.
+ * Routes by the `type` field: `'asymmetric-keypair'` is parsed by
+ * {@link CryptoUtils.KeyStore.Converters.keystoreAsymmetricEntryJson | keystoreAsymmetricEntryJson},
+ * anything else (including a missing `type` field for backwards compatibility) by
+ * {@link CryptoUtils.KeyStore.Converters.keystoreSymmetricEntryJson | keystoreSymmetricEntryJson}.
+ * @public
+ */
+export const keystoreSecretEntryJson = Converters.oneOf([
+    keystoreAsymmetricEntryJson,
+    keystoreSymmetricEntryJson
+]);
+// ============================================================================
 // Vault Contents Converter
 // ============================================================================
 /**

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

@@ -23,6 +23,7 @@
  */
 // Types and interfaces
 export * from './model';
+export * from './privateKeyStorage';
 // Converters namespace
 import * as Converters from './converters';
 export { Converters };

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

@@ -63,8 +63,9 @@ function getCurrentTimestamp() {
  * @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 +88,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 +104,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
@@ -217,7 +218,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;
@@ -279,7 +282,9 @@ 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.
      * @param name - Name of the secret
      * @returns Success with secret entry, Failure if not found or locked
      * @public
@@ -294,6 +299,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
@@ -320,7 +346,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 */
@@ -334,9 +359,11 @@ 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 raw 32-byte key material into the vault.
@@ -352,7 +379,7 @@ export class KeyStore {
      * @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');
@@ -363,8 +390,8 @@ 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 = {
@@ -374,9 +401,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 });
     }
     /**
      * Adds a secret derived from a password using PBKDF2.
@@ -403,8 +431,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;
@@ -427,11 +455,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),
@@ -440,12 +470,16 @@ export class KeyStore {
         });
     }
     /**
-     * Removes a secret by name.
+     * 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');
         }
@@ -453,11 +487,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.
@@ -468,7 +503,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');
         }
@@ -478,8 +513,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();
@@ -490,9 +525,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.
@@ -515,6 +551,118 @@ export class KeyStore {
         const decoder = new TextDecoder();
         return succeed(decoder.decode(entry.key));
     }
+    // ============================================================================
+    // 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.
+     *
+     * @param name - Unique name for the entry
+     * @param options - Algorithm, optional description, replace flag
+     * @returns Success with the new entry, Failure if locked, no provider, or storage write failed
+     * @public
+     */
+    async addKeyPair(name, options) {
+        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.
+        const extractable = !this._privateKeyStorage.supportsNonExtractable;
+        const keyPairResult = await this._cryptoProvider.generateKeyPair(options.algorithm, extractable);
+        /* 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}`);
+        }
+        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, privateKey);
+        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,
+            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.
+     * @param name - Name of the entry
+     * @returns Success with `{ publicKey, privateKey }`, Failure if not found,
+     * locked, wrong type, no provider, or storage load failed.
+     * @public
+     */
+    async getKeyPair(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})`);
+        }
+        if (!this._privateKeyStorage) {
+            return fail('No private key storage configured');
+        }
+        const privateResult = await this._privateKeyStorage.load(entry.id);
+        if (privateResult.isFailure()) {
+            return fail(`Failed to load private key for '${name}': ${privateResult.message}`);
+        }
+        const publicResult = await this._cryptoProvider.importPublicKeyJwk(entry.publicKeyJwk, entry.algorithm);
+        /* c8 ignore next 3 - vault JWKs that previously exported cleanly are extremely unlikely to fail re-import */
+        if (publicResult.isFailure()) {
+            return fail(`Failed to re-import public key for '${name}': ${publicResult.message}`);
+        }
+        return succeed({ publicKey: publicResult.value, privateKey: privateResult.value });
+    }
     /**
      * Lists secret names filtered by type.
      * @param type - The secret type to filter by
@@ -554,7 +702,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);
@@ -674,6 +823,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,
@@ -701,6 +853,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);
@@ -734,13 +889,26 @@ export class KeyStore {
         // Build vault contents
         const secretEntries = {};
         for (const [name, entry] of secrets) {
-            secretEntries[name] = {
-                name: entry.name,
-                type: entry.type,
-                key: this._cryptoProvider.toBase64(entry.key),
-                description: entry.description,
-                createdAt: entry.createdAt
-            };
+            if (entry.type === 'asymmetric-keypair') {
+                secretEntries[name] = {
+                    name: entry.name,
+                    type: entry.type,
+                    id: entry.id,
+                    algorithm: entry.algorithm,
+                    publicKeyJwk: entry.publicKeyJwk,
+                    description: entry.description,
+                    createdAt: entry.createdAt
+                };
+            }
+            else {
+                secretEntries[name] = {
+                    name: entry.name,
+                    type: entry.type,
+                    key: this._cryptoProvider.toBase64(entry.key),
+                    description: entry.description,
+                    createdAt: entry.createdAt
+                };
+            }
         }
         const vaultContents = {
             version: KEYSTORE_FORMAT,
@@ -780,7 +948,6 @@ export class KeyStore {
      * Shared by `unlock()` and `unlockWithKey()`.
      */
     async _decryptVault(derivedKey) {
-        var _a;
         const keystoreFile = this._keystoreFile;
         if (keystoreFile === undefined) {
             return fail('No key store file loaded');
@@ -820,20 +987,33 @@ export class KeyStore {
         }
         const 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}`);
+            if (jsonEntry.type === 'asymmetric-keypair') {
+                const entry = {
+                    name,
+                    type: jsonEntry.type,
+                    id: jsonEntry.id,
+                    algorithm: jsonEntry.algorithm,
+                    publicKeyJwk: jsonEntry.publicKeyJwk,
+                    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,
+                    createdAt: jsonEntry.createdAt
+                };
+                secrets.set(name, entry);
             }
-            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
-            };
-            secrets.set(name, entry);
         }
         // All validation passed — commit state atomically
         this._salt = saltResult.value;
@@ -842,5 +1022,50 @@ export class KeyStore {
         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;
+    }
+    /**
+     * 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