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

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

@@ -584,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.
@@ -741,8 +721,60 @@ export class KeyStore {
         });
     }
     // ============================================================================
-    // Private: Vault Decryption
+    // 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()`.

package/dist/ts-extras.d.ts

@@ -1792,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.
@@ -1816,6 +1830,11 @@ 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()`.

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

@@ -232,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.
@@ -256,6 +270,11 @@ 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()`.

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

@@ -620,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.
@@ -777,8 +757,60 @@ class KeyStore {
         });
     }
     // ============================================================================
-    // Private: Vault Decryption
+    // 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()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.1.0-15",
+  "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-15",
-    "@fgv/typedoc-compact-theme": "5.1.0-15",
-    "@fgv/ts-utils-jest": "5.1.0-15",
-    "@fgv/ts-utils": "5.1.0-15"
+    "@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-15"
+    "@fgv/ts-json-base": "5.1.0-16"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-15"
+    "@fgv/ts-utils": "5.1.0-16"
   },
   "repository": {
     "type": "git",