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

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.
@@ -761,5 +740,75 @@ export class KeyStore {
             cryptoProvider: this._cryptoProvider
         });
     }
+    // ============================================================================
+    // Private: Vault Decryption
+    // ============================================================================
+    /**
+     * 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
@@ -1801,6 +1816,11 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     getEncryptionConfig(): Result<Pick<IEncryptionConfig, 'secretProvider' | 'cryptoProvider'>>;
+    /**
+     * 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
@@ -241,5 +256,10 @@ export declare class KeyStore implements IEncryptionProvider {
      * @public
      */
     getEncryptionConfig(): Result<Pick<IEncryptionConfig, 'secretProvider' | 'cryptoProvider'>>;
+    /**
+     * 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.
@@ -797,6 +776,76 @@ class KeyStore {
             cryptoProvider: this._cryptoProvider
         });
     }
+    // ============================================================================
+    // Private: Vault Decryption
+    // ============================================================================
+    /**
+     * 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-15",
   "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/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"
   },
   "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-15"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-14"
+    "@fgv/ts-utils": "5.1.0-15"
   },
   "repository": {
     "type": "git",