@fgv/ts-extras 5.1.0-14 → 5.1.0-16

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

@@ -146,7 +146,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 +169,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.
@@ -605,49 +584,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.
@@ -761,5 +720,127 @@ 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) {
+            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,
+            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) {
+        var _a;
+        const keystoreFile = this._keystoreFile;
+        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)) {
+            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
+            };
+            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);
+    }
 }
 //# sourceMappingURL=keyStore.js.map

package/dist/ts-extras.d.ts

@@ -1636,6 +1636,21 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     unlock(password: string): Promise<Result<KeyStore_2>>;
+    /**
+     * 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
+     */
+    unlockWithKey(derivedKey: Uint8Array): Promise<Result<KeyStore_2>>;
     /**
      * Locks the key store, clearing all secrets from memory.
      * @param force - If true, discards unsaved changes
@@ -1777,6 +1792,20 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     save(password: string): Promise<Result<IKeyStoreFile>>;
+    /**
+     * 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
+     */
+    saveWithKey(derivedKey: Uint8Array): Promise<Result<IKeyStoreFile>>;
     /**
      * Changes the master password.
      * Re-encrypts the vault with the new password-derived key.
@@ -1801,6 +1830,16 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     getEncryptionConfig(): Result<Pick<IEncryptionConfig, 'secretProvider' | 'cryptoProvider'>>;
+    /**
+     * Encrypts the vault with a derived key and returns the key store file.
+     * Shared by `save()` and `saveWithKey()`.
+     */
+    private _encryptVault;
+    /**
+     * Decrypts the vault with a derived key and loads secrets into memory.
+     * Shared by `unlock()` and `unlockWithKey()`.
+     */
+    private _decryptVault;
 }
 
 /**

package/lib/packlets/crypto-utils/keystore/keyStore.d.ts

@@ -76,6 +76,21 @@ export declare class KeyStore implements IEncryptionProvider {
      * @public
      */
     unlock(password: string): Promise<Result<KeyStore>>;
+    /**
+     * 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
+     */
+    unlockWithKey(derivedKey: Uint8Array): Promise<Result<KeyStore>>;
     /**
      * Locks the key store, clearing all secrets from memory.
      * @param force - If true, discards unsaved changes
@@ -217,6 +232,20 @@ export declare class KeyStore implements IEncryptionProvider {
      * @public
      */
     save(password: string): Promise<Result<IKeyStoreFile>>;
+    /**
+     * 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
+     */
+    saveWithKey(derivedKey: Uint8Array): Promise<Result<IKeyStoreFile>>;
     /**
      * Changes the master password.
      * Re-encrypts the vault with the new password-derived key.
@@ -241,5 +270,15 @@ export declare class KeyStore implements IEncryptionProvider {
      * @public
      */
     getEncryptionConfig(): Result<Pick<IEncryptionConfig, 'secretProvider' | 'cryptoProvider'>>;
+    /**
+     * Encrypts the vault with a derived key and returns the key store file.
+     * Shared by `save()` and `saveWithKey()`.
+     */
+    private _encryptVault;
+    /**
+     * Decrypts the vault with a derived key and loads secrets into memory.
+     * Shared by `unlock()` and `unlockWithKey()`.
+     */
+    private _decryptVault;
 }
 //# sourceMappingURL=keyStore.d.ts.map

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

@@ -182,7 +182,6 @@ class KeyStore {
      * @public
      */
     async unlock(password) {
-        var _a;
         if (this._isNew) {
             return (0, ts_utils_1.fail)('Cannot unlock a new key store - use initialize() instead');
         }
@@ -206,57 +205,37 @@ class KeyStore {
         if (keyResult.isFailure()) {
             return (0, ts_utils_1.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 (0, ts_utils_1.fail)(`Invalid IV in key store file: ${ivResult.message}`);
-        }
-        if (authTagResult.isFailure()) {
-            return (0, ts_utils_1.fail)(`Invalid auth tag in key store file: ${authTagResult.message}`);
-        }
-        if (encryptedDataResult.isFailure()) {
-            return (0, ts_utils_1.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 (0, ts_utils_1.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 (0, ts_utils_1.fail)('Cannot unlock a new key store - use initialize() instead');
         }
-        // Parse the vault contents
-        const parseResult = (0, ts_utils_1.captureResult)(() => JSON.parse(decryptResult.value));
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (parseResult.isFailure()) {
-            return (0, ts_utils_1.fail)(`Failed to parse vault contents: ${parseResult.message}`);
+        if (this._state === 'unlocked') {
+            return (0, ts_utils_1.fail)('Key store is already unlocked');
         }
-        const vaultResult = converters_1.keystoreVaultContents.convert(parseResult.value);
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (vaultResult.isFailure()) {
-            return (0, ts_utils_1.fail)(`Invalid vault format: ${vaultResult.message}`);
+        if (derivedKey.length !== Constants.AES_256_KEY_SIZE) {
+            return (0, ts_utils_1.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 (0, ts_utils_1.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 (0, ts_utils_1.fail)('No key store file to unlock');
         }
-        this._state = 'unlocked';
-        this._dirty = false;
-        return (0, ts_utils_1.succeed)(this);
+        return this._decryptVault(derivedKey);
     }
     /**
      * Locks the key store, clearing all secrets from memory.
@@ -641,49 +620,29 @@ class KeyStore {
         if (keyResult.isFailure()) {
             return (0, ts_utils_1.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: model_1.KEYSTORE_FORMAT,
-            secrets
-        };
-        // Serialize and encrypt
-        const jsonResult = (0, ts_utils_1.captureResult)(() => JSON.stringify(vaultContents));
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (jsonResult.isFailure()) {
-            return (0, ts_utils_1.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 (0, ts_utils_1.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 (0, ts_utils_1.fail)(`Encryption failed: ${encryptResult.message}`);
+        if (derivedKey.length !== Constants.AES_256_KEY_SIZE) {
+            return (0, ts_utils_1.fail)(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${derivedKey.length}`);
         }
-        const { iv, authTag, encryptedData } = encryptResult.value;
-        const keystoreFileData = {
-            format: model_1.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 (0, ts_utils_1.succeed)(keystoreFileData);
+        return this._encryptVault(derivedKey);
     }
     /**
      * Changes the master password.
@@ -797,6 +756,128 @@ 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) {
+            secretEntries[name] = {
+                name: entry.name,
+                type: entry.type,
+                key: this._cryptoProvider.toBase64(entry.key),
+                description: entry.description,
+                createdAt: entry.createdAt
+            };
+        }
+        const vaultContents = {
+            version: model_1.KEYSTORE_FORMAT,
+            secrets: secretEntries
+        };
+        // Serialize and encrypt
+        const jsonResult = (0, ts_utils_1.captureResult)(() => JSON.stringify(vaultContents));
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (jsonResult.isFailure()) {
+            return (0, ts_utils_1.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 (0, ts_utils_1.fail)(`Encryption failed: ${encryptResult.message}`);
+        }
+        const { iv, authTag, encryptedData } = encryptResult.value;
+        const keystoreFileData = {
+            format: model_1.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 (0, ts_utils_1.succeed)(keystoreFileData);
+    }
+    /**
+     * Decrypts the vault with a derived key and loads secrets into memory.
+     * Shared by `unlock()` and `unlockWithKey()`.
+     */
+    async _decryptVault(derivedKey) {
+        var _a;
+        const keystoreFile = this._keystoreFile;
+        if (keystoreFile === undefined) {
+            return (0, ts_utils_1.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 (0, ts_utils_1.fail)(`Invalid IV in key store file: ${ivResult.message}`);
+        }
+        if (authTagResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Invalid auth tag in key store file: ${authTagResult.message}`);
+        }
+        if (encryptedDataResult.isFailure()) {
+            return (0, ts_utils_1.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 (0, ts_utils_1.fail)('Incorrect password or corrupted key store');
+        }
+        // Parse the vault contents
+        const parseResult = (0, ts_utils_1.captureResult)(() => JSON.parse(decryptResult.value));
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (parseResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to parse vault contents: ${parseResult.message}`);
+        }
+        const vaultResult = converters_1.keystoreVaultContents.convert(parseResult.value);
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (vaultResult.isFailure()) {
+            return (0, ts_utils_1.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 (0, ts_utils_1.fail)(`Invalid salt in key store file: ${saltResult.message}`);
+        }
+        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 (0, ts_utils_1.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
+            };
+            secrets.set(name, entry);
+        }
+        // All validation passed — commit state atomically
+        this._salt = saltResult.value;
+        this._secrets = secrets;
+        this._state = 'unlocked';
+        this._dirty = false;
+        return (0, ts_utils_1.succeed)(this);
+    }
 }
 exports.KeyStore = KeyStore;
 //# sourceMappingURL=keyStore.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.1.0-14",
+  "version": "5.1.0-16",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-extras.d.ts",
@@ -86,10 +86,10 @@
     "@types/js-yaml": "~4.0.9",
     "typedoc": "~0.28.16",
     "typedoc-plugin-markdown": "~4.9.0",
-    "@fgv/heft-dual-rig": "5.1.0-14",
-    "@fgv/typedoc-compact-theme": "5.1.0-14",
-    "@fgv/ts-utils-jest": "5.1.0-14",
-    "@fgv/ts-utils": "5.1.0-14"
+    "@fgv/typedoc-compact-theme": "5.1.0-16",
+    "@fgv/heft-dual-rig": "5.1.0-16",
+    "@fgv/ts-utils-jest": "5.1.0-16",
+    "@fgv/ts-utils": "5.1.0-16"
   },
   "dependencies": {
     "luxon": "^3.7.2",
@@ -97,10 +97,10 @@
     "papaparse": "^5.4.1",
     "fflate": "~0.8.2",
     "js-yaml": "~4.1.1",
-    "@fgv/ts-json-base": "5.1.0-14"
+    "@fgv/ts-json-base": "5.1.0-16"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-14"
+    "@fgv/ts-utils": "5.1.0-16"
   },
   "repository": {
     "type": "git",