@metamask-previews/keyring-controller 22.0.2-preview-13f36eb8 → 22.0.2-preview-0013a1bd

package/CHANGELOG.md

@@ -9,19 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Added optional `SupportedKeyDerivationOptions` type parameter to the `ExportableKeyEncryptor` type ([#5963](https://github.com/MetaMask/core/pull/5963))
-  - This type parameter allows specifying the key derivation options supported by the injected encryptor.
-
-### Changed
-
-- **BREAKING:** The `KeyringController` constructor now requires an encryptor supporting the `keyFromPassword`, `exportKey` and `generateSalt` methods ([#5963](https://github.com/MetaMask/core/pull/5963))
-
-### Removed
-
-- **BREAKING:** The `cacheEncryptionKey` parameter has been removed from the `KeyringController` constructor options ([#5963](https://github.com/MetaMask/core/pull/5963))
-  - This parameter was previously used to enable encryption key in-memory caching, but it is no longer needed as the controller now always uses the latest encryption key.
-- **BREAKING:** The `submitEncryptionKey` method does not accept an `encryptionSalt` argument anymore ([#5963](https://github.com/MetaMask/core/pull/5963))
-  - The encryption salt is now always taken from the vault.
+- Add support for envelope encryption ([#5940](https://github.com/MetaMask/core/pull/5940))
 
 ## [22.0.2]
 

package/dist/KeyringController.cjs

@@ -36,7 +36,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
-var _KeyringController_instances, _KeyringController_controllerOperationMutex, _KeyringController_vaultOperationMutex, _KeyringController_keyringBuilders, _KeyringController_encryptor, _KeyringController_keyrings, _KeyringController_unsupportedKeyrings, _KeyringController_encryptionKey, _KeyringController_qrKeyringStateListener, _KeyringController_registerMessageHandlers, _KeyringController_getKeyringById, _KeyringController_getKeyringByIdOrDefault, _KeyringController_getKeyringMetadata, _KeyringController_getKeyringBuilderForType, _KeyringController_addQRKeyring, _KeyringController_subscribeToQRKeyringEvents, _KeyringController_unsubscribeFromQRKeyringsEvents, _KeyringController_createNewVaultWithKeyring, _KeyringController_deriveEncryptionKey, _KeyringController_useEncryptionKey, _KeyringController_verifySeedPhrase, _KeyringController_getUpdatedKeyrings, _KeyringController_getSerializedKeyrings, _KeyringController_getSessionState, _KeyringController_restoreSerializedKeyrings, _KeyringController_unlockKeyrings, _KeyringController_updateVault, _KeyringController_isNewEncryptionAvailable, _KeyringController_getAccountsFromKeyrings, _KeyringController_createKeyringWithFirstAccount, _KeyringController_newKeyring, _KeyringController_createKeyring, _KeyringController_clearKeyrings, _KeyringController_restoreKeyring, _KeyringController_destroyKeyring, _KeyringController_removeEmptyKeyrings, _KeyringController_assertNoDuplicateAccounts, _KeyringController_setUnlocked, _KeyringController_assertIsUnlocked, _KeyringController_persistOrRollback, _KeyringController_withRollback, _KeyringController_assertControllerMutexIsLocked, _KeyringController_withControllerLock, _KeyringController_withVaultLock;
+var _KeyringController_instances, _KeyringController_controllerOperationMutex, _KeyringController_vaultOperationMutex, _KeyringController_keyringBuilders, _KeyringController_encryptor, _KeyringController_cacheEncryptionKey, _KeyringController_keyrings, _KeyringController_unsupportedKeyrings, _KeyringController_password, _KeyringController_encryptionKey, _KeyringController_qrKeyringStateListener, _KeyringController_registerMessageHandlers, _KeyringController_getKeyringById, _KeyringController_getKeyringByIdOrDefault, _KeyringController_getKeyringMetadata, _KeyringController_getKeyringBuilderForType, _KeyringController_addQRKeyring, _KeyringController_subscribeToQRKeyringEvents, _KeyringController_unsubscribeFromQRKeyringsEvents, _KeyringController_createNewVaultWithKeyring, _KeyringController_updateCachedEncryptionKey, _KeyringController_verifySeedPhrase, _KeyringController_getUpdatedKeyrings, _KeyringController_getSerializedKeyrings, _KeyringController_getSessionState, _KeyringController_restoreSerializedKeyrings, _KeyringController_unlockKeyrings, _KeyringController_updateVault, _KeyringController_isNewEncryptionAvailable, _KeyringController_isEnvelopeEncryptionEnabled, _KeyringController_getAccountsFromKeyrings, _KeyringController_createKeyringWithFirstAccount, _KeyringController_newKeyring, _KeyringController_createKeyring, _KeyringController_clearKeyrings, _KeyringController_restoreKeyring, _KeyringController_destroyKeyring, _KeyringController_removeEmptyKeyrings, _KeyringController_assertNoDuplicateAccounts, _KeyringController_setUnlocked, _KeyringController_assertIsUnlocked, _KeyringController_persistOrRollback, _KeyringController_withRollback, _KeyringController_assertControllerMutexIsLocked, _KeyringController_withControllerLock, _KeyringController_withVaultLock;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyringController = exports.getDefaultKeyringState = exports.keyringBuilderFactory = exports.SignTypedDataVersion = exports.AccountImportStrategy = exports.isCustodyKeyring = exports.KeyringTypes = void 0;
 const util_1 = require("@ethereumjs/util");
@@ -168,6 +168,17 @@ function assertIsValidPassword(password) {
         throw new Error(constants_1.KeyringControllerError.InvalidEmptyPassword);
     }
 }
+/**
+ * Assert that the provided cacheEncryptionKey is true.
+ *
+ * @param cacheEncryptionKey - The cacheEncryptionKey to check.
+ * @throws If the cacheEncryptionKey is not true.
+ */
+function assertIsCacheEncryptionKeyTrue(cacheEncryptionKey) {
+    if (!cacheEncryptionKey) {
+        throw new Error(constants_1.KeyringControllerError.CacheEncryptionKeyDisabled);
+    }
+}
 /**
  * Checks if the provided value is a serialized keyrings array.
  *
@@ -258,6 +269,7 @@ class KeyringController extends base_controller_1.BaseController {
                 keyrings: { persist: false, anonymous: false },
                 encryptionKey: { persist: false, anonymous: false },
                 encryptionSalt: { persist: false, anonymous: false },
+                encryptedEncryptionKey: { persist: true, anonymous: false },
             },
             messenger,
             state: {
@@ -270,17 +282,24 @@ class KeyringController extends base_controller_1.BaseController {
         _KeyringController_vaultOperationMutex.set(this, new async_mutex_1.Mutex());
         _KeyringController_keyringBuilders.set(this, void 0);
         _KeyringController_encryptor.set(this, void 0);
+        _KeyringController_cacheEncryptionKey.set(this, void 0);
         _KeyringController_keyrings.set(this, void 0);
         _KeyringController_unsupportedKeyrings.set(this, void 0);
+        _KeyringController_password.set(this, void 0);
         _KeyringController_encryptionKey.set(this, void 0);
         _KeyringController_qrKeyringStateListener.set(this, void 0);
         __classPrivateFieldSet(this, _KeyringController_keyringBuilders, keyringBuilders
             ? keyringBuilders.concat(defaultKeyringBuilders)
             : defaultKeyringBuilders, "f");
-        assertIsExportableKeyEncryptor(encryptor);
         __classPrivateFieldSet(this, _KeyringController_encryptor, encryptor, "f");
         __classPrivateFieldSet(this, _KeyringController_keyrings, [], "f");
         __classPrivateFieldSet(this, _KeyringController_unsupportedKeyrings, [], "f");
+        // This option allows the controller to cache an exported key
+        // for use in decrypting and encrypting data without password
+        __classPrivateFieldSet(this, _KeyringController_cacheEncryptionKey, Boolean(options.cacheEncryptionKey), "f");
+        if (__classPrivateFieldGet(this, _KeyringController_cacheEncryptionKey, "f")) {
+            assertIsExportableKeyEncryptor(encryptor);
+        }
         __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_registerMessageHandlers).call(this);
     }
     /**
@@ -350,9 +369,11 @@ class KeyringController extends base_controller_1.BaseController {
      * @param password - Password to unlock keychain.
      * @param seed - A BIP39-compliant seed phrase as Uint8Array,
      * either as a string or an array of UTF-8 bytes that represent the string.
+     * @param encryptionKey - Optional encryption key to encrypt the new vault. If
+     * set, envelope encryption will be used.
      * @returns Promise resolving when the operation ends successfully.
      */
-    async createNewVaultAndRestore(password, seed) {
+    async createNewVaultAndRestore(password, seed, encryptionKey) {
         return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_persistOrRollback).call(this, async () => {
             assertIsValidPassword(password);
             await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_createNewVaultWithKeyring).call(this, password, {
@@ -361,25 +382,28 @@ class KeyringController extends base_controller_1.BaseController {
                     mnemonic: seed,
                     numberOfAccounts: 1,
                 },
-            });
+            }, encryptionKey);
         });
     }
     /**
      * Create a new vault and primary keyring.
      *
-     * This only works if keyrings are empty. If there is a pre-existing unlocked vault, calling this will have no effect.
-     * If there is a pre-existing locked vault, it will be replaced.
+     * This only works if keyrings are empty. If there is a pre-existing unlocked
+     * vault, calling this will have no effect. If there is a pre-existing locked
+     * vault, it will be replaced.
      *
      * @param password - Password to unlock the new vault.
+     * @param encryptionKey - Optional encryption key to encrypt the new vault. If
+     * set, envelope encryption will be used.
      * @returns Promise resolving when the operation ends successfully.
      */
-    async createNewVaultAndKeychain(password) {
+    async createNewVaultAndKeychain(password, encryptionKey) {
         return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_persistOrRollback).call(this, async () => {
             const accounts = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getAccountsFromKeyrings).call(this);
             if (!accounts.length) {
                 await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_createNewVaultWithKeyring).call(this, password, {
                     type: KeyringTypes.hd,
-                });
+                }, encryptionKey);
             }
         });
     }
@@ -408,7 +432,16 @@ class KeyringController extends base_controller_1.BaseController {
         if (!this.state.vault) {
             throw new Error(constants_1.KeyringControllerError.VaultError);
         }
-        await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").decrypt(password, this.state.vault);
+        if (this.state.encryptedEncryptionKey) {
+            // Envelope encryption mode.
+            assertIsExportableKeyEncryptor(__classPrivateFieldGet(this, _KeyringController_encryptor, "f"));
+            const decryptedEncryptionKey = (await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").decrypt(password, this.state.encryptedEncryptionKey));
+            const importedKey = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").importKey(decryptedEncryptionKey);
+            await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").decryptWithKey(importedKey, this.state.vault);
+        }
+        else {
+            await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").decrypt(password, this.state.vault);
+        }
     }
     /**
      * Returns the status of the vault.
@@ -597,7 +630,7 @@ class KeyringController extends base_controller_1.BaseController {
                     try {
                         wallet = ethereumjs_wallet_1.thirdparty.fromEtherWallet(input, password);
                     }
-                    catch (e) {
+                    catch {
                         wallet = wallet || (await ethereumjs_wallet_1.default.fromV3(input, password, true));
                     }
                     privateKey = (0, utils_1.bytesToHex)(wallet.getPrivateKey());
@@ -655,6 +688,7 @@ class KeyringController extends base_controller_1.BaseController {
         __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
         return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withRollback).call(this, async () => {
             __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_unsubscribeFromQRKeyringsEvents).call(this);
+            __classPrivateFieldSet(this, _KeyringController_password, undefined, "f");
             __classPrivateFieldSet(this, _KeyringController_encryptionKey, undefined, "f");
             await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_clearKeyrings).call(this);
             this.update((state) => {
@@ -836,10 +870,33 @@ class KeyringController extends base_controller_1.BaseController {
      * @returns Promise resolving when the operation completes.
      */
     changePassword(password) {
+        return this.changePasswordAndEncryptionKey(password);
+    }
+    /**
+     * Changes the password and encryption key used to encrypt the vault.
+     *
+     * @param password - The new password.
+     * @param encryptionKey - The new encryption key. If omitted, the encryption
+     * key will not be changed.
+     * @returns Promise resolving when the operation completes.
+     */
+    changePasswordAndEncryptionKey(password, encryptionKey) {
         __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
         return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_persistOrRollback).call(this, async () => {
             assertIsValidPassword(password);
-            await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_deriveEncryptionKey).call(this, password);
+            // Update password.
+            __classPrivateFieldSet(this, _KeyringController_password, password, "f");
+            // Update encryption key.
+            __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_updateCachedEncryptionKey).call(this, encryptionKey);
+            // We need to clear encryption key and salt from state
+            // to force the controller to re-encrypt the vault using
+            // the new password.
+            if (__classPrivateFieldGet(this, _KeyringController_cacheEncryptionKey, "f")) {
+                this.update((state) => {
+                    delete state.encryptionKey;
+                    delete state.encryptionSalt;
+                });
+            }
         });
     }
     /**
@@ -847,13 +904,12 @@ class KeyringController extends base_controller_1.BaseController {
      * using the given encryption key and salt.
      *
      * @param encryptionKey - Key to unlock the keychain.
+     * @param encryptionSalt - Salt to unlock the keychain.
      * @returns Promise resolving when the operation completes.
      */
-    async submitEncryptionKey(encryptionKey) {
+    async submitEncryptionKey(encryptionKey, encryptionSalt) {
         const { newMetadata } = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withRollback).call(this, async () => {
-            const result = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_unlockKeyrings).call(this, {
-                exportedEncryptionKey: encryptionKey,
-            });
+            const result = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_unlockKeyrings).call(this, undefined, encryptionKey, encryptionSalt);
             __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_setUnlocked).call(this);
             return result;
         });
@@ -881,7 +937,7 @@ class KeyringController extends base_controller_1.BaseController {
      */
     async submitPassword(password) {
         const { newMetadata } = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withRollback).call(this, async () => {
-            const result = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_unlockKeyrings).call(this, { password });
+            const result = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_unlockKeyrings).call(this, password);
             __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_setUnlocked).call(this);
             return result;
         });
@@ -891,12 +947,6 @@ class KeyringController extends base_controller_1.BaseController {
             // can attempt to upgrade the vault.
             await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withRollback).call(this, async () => {
                 if (newMetadata || __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_isNewEncryptionAvailable).call(this)) {
-                    await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_deriveEncryptionKey).call(this, password, {
-                        // If the vault is being upgraded, we want to ignore the metadata
-                        // that is already in the vault, so we can effectively
-                        // re-encrypt the vault with the new encryption config.
-                        ignoreVaultKeyMetadata: true,
-                    });
                     await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_updateVault).call(this);
                 }
             });
@@ -1151,7 +1201,7 @@ class KeyringController extends base_controller_1.BaseController {
     }
 }
 exports.KeyringController = KeyringController;
-_KeyringController_controllerOperationMutex = new WeakMap(), _KeyringController_vaultOperationMutex = new WeakMap(), _KeyringController_keyringBuilders = new WeakMap(), _KeyringController_encryptor = new WeakMap(), _KeyringController_keyrings = new WeakMap(), _KeyringController_unsupportedKeyrings = new WeakMap(), _KeyringController_encryptionKey = new WeakMap(), _KeyringController_qrKeyringStateListener = new WeakMap(), _KeyringController_instances = new WeakSet(), _KeyringController_registerMessageHandlers = function _KeyringController_registerMessageHandlers() {
+_KeyringController_controllerOperationMutex = new WeakMap(), _KeyringController_vaultOperationMutex = new WeakMap(), _KeyringController_keyringBuilders = new WeakMap(), _KeyringController_encryptor = new WeakMap(), _KeyringController_cacheEncryptionKey = new WeakMap(), _KeyringController_keyrings = new WeakMap(), _KeyringController_unsupportedKeyrings = new WeakMap(), _KeyringController_password = new WeakMap(), _KeyringController_encryptionKey = new WeakMap(), _KeyringController_qrKeyringStateListener = new WeakMap(), _KeyringController_instances = new WeakSet(), _KeyringController_registerMessageHandlers = function _KeyringController_registerMessageHandlers() {
     this.messagingSystem.registerActionHandler(`${name}:signMessage`, this.signMessage.bind(this));
     this.messagingSystem.registerActionHandler(`${name}:signEip7702Authorization`, this.signEip7702Authorization.bind(this));
     this.messagingSystem.registerActionHandler(`${name}:signPersonalMessage`, this.signPersonalMessage.bind(this));
@@ -1220,9 +1270,10 @@ async function _KeyringController_addQRKeyring() {
  * @param keyring - A object containing the params to instantiate a new keyring.
  * @param keyring.type - The keyring type.
  * @param keyring.opts - Optional parameters required to instantiate the keyring.
+ * @param encryptionKey - Optional encryption key to encrypt the vault.
  * @returns A promise that resolves to the state.
  */
-async function _KeyringController_createNewVaultWithKeyring(password, keyring) {
+async function _KeyringController_createNewVaultWithKeyring(password, keyring, encryptionKey) {
     __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertControllerMutexIsLocked).call(this);
     if (typeof password !== 'string') {
         throw new TypeError(constants_1.KeyringControllerError.WrongPasswordType);
@@ -1231,56 +1282,21 @@ async function _KeyringController_createNewVaultWithKeyring(password, keyring) {
         delete state.encryptionKey;
         delete state.encryptionSalt;
     });
-    await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_deriveEncryptionKey).call(this, password);
+    __classPrivateFieldSet(this, _KeyringController_password, password, "f");
+    __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_updateCachedEncryptionKey).call(this, encryptionKey);
     await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_clearKeyrings).call(this);
     await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_createKeyringWithFirstAccount).call(this, keyring.type, keyring.opts);
     __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_setUnlocked).call(this);
-}, _KeyringController_deriveEncryptionKey = 
-/**
- * Derive the vault encryption key from the provided password, and
- * assign it to the class variable for later use with cryptographic
- * functions.
- *
- * When the controller has a vault in its state, the key is derived
- * using the salt from the vault. If the vault is empty, a new salt
- * is generated and used to derive the key.
- *
- * @param password - The password to use for decryption or derivation.
- * @param options - Options for the key derivation.
- * @param options.ignoreVaultKeyMetadata - Whether to ignore the vault key metadata
- */
-async function _KeyringController_deriveEncryptionKey(password, options = {
-    ignoreVaultKeyMetadata: false,
-}) {
-    __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertControllerMutexIsLocked).call(this);
-    const { vault } = this.state;
-    if (typeof password !== 'string') {
-        throw new TypeError(constants_1.KeyringControllerError.WrongPasswordType);
-    }
-    let salt, keyMetadata;
-    if (vault && !options.ignoreVaultKeyMetadata) {
-        const parsedVault = JSON.parse(vault);
-        salt = parsedVault.salt;
-        keyMetadata = parsedVault.keyMetadata;
+}, _KeyringController_updateCachedEncryptionKey = function _KeyringController_updateCachedEncryptionKey(encryptionKey) {
+    if (!encryptionKey && this.state.encryptedEncryptionKey) {
+        // If no encryption key is provided and we are in envelope encryption
+        // mode, use the cached encryption key. This case occurs when we call
+        // change password without providing a new encryption key.
+        __classPrivateFieldSet(this, _KeyringController_encryptionKey, this.state.encryptionKey, "f");
     }
     else {
-        salt = __classPrivateFieldGet(this, _KeyringController_encryptor, "f").generateSalt();
+        __classPrivateFieldSet(this, _KeyringController_encryptionKey, encryptionKey, "f");
     }
-    const exportedEncryptionKey = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").exportKey(await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").keyFromPassword(password, salt, true, keyMetadata));
-    __classPrivateFieldSet(this, _KeyringController_encryptionKey, {
-        salt,
-        exported: exportedEncryptionKey,
-    }, "f");
-}, _KeyringController_useEncryptionKey = function _KeyringController_useEncryptionKey(encryptionKey, encryptionSalt) {
-    __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertControllerMutexIsLocked).call(this);
-    if (typeof encryptionKey !== 'string' ||
-        typeof encryptionSalt !== 'string') {
-        throw new TypeError(constants_1.KeyringControllerError.WrongEncryptionKeyType);
-    }
-    __classPrivateFieldSet(this, _KeyringController_encryptionKey, {
-        salt: encryptionSalt,
-        exported: encryptionKey,
-    }, "f");
 }, _KeyringController_verifySeedPhrase = 
 /**
  * Internal non-exclusive method to verify the seed phrase.
@@ -1369,6 +1385,7 @@ async function _KeyringController_getSerializedKeyrings({ includeUnsupported } =
 async function _KeyringController_getSessionState() {
     return {
         keyrings: await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getSerializedKeyrings).call(this),
+        password: __classPrivateFieldGet(this, _KeyringController_password, "f"),
         encryptionKey: __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f"),
     };
 }, _KeyringController_restoreSerializedKeyrings = 
@@ -1398,28 +1415,63 @@ async function _KeyringController_restoreSerializedKeyrings(serializedKeyrings)
  * Unlock Keyrings, decrypting the vault and deserializing all
  * keyrings contained in it, using a password or an encryption key with salt.
  *
- * @param credentials - The credentials to unlock the keyrings.
+ * @param password - The keyring controller password.
+ * @param encryptionKey - An exported key string to unlock keyrings with.
+ * @param encryptionSalt - The salt used to encrypt the vault.
  * @returns A promise resolving to the deserialized keyrings array.
  */
-async function _KeyringController_unlockKeyrings(credentials) {
+async function _KeyringController_unlockKeyrings(password, encryptionKey, encryptionSalt) {
     return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withVaultLock).call(this, async () => {
-        if (!this.state.vault) {
+        const { vault: encryptedVault, encryptedEncryptionKey } = this.state;
+        if (!encryptedVault) {
             throw new Error(constants_1.KeyringControllerError.VaultError);
         }
-        const parsedEncryptedVault = JSON.parse(this.state.vault);
-        if ('password' in credentials) {
-            await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_deriveEncryptionKey).call(this, credentials.password);
+        let vault;
+        const updatedState = {};
+        if (__classPrivateFieldGet(this, _KeyringController_cacheEncryptionKey, "f")) {
+            assertIsExportableKeyEncryptor(__classPrivateFieldGet(this, _KeyringController_encryptor, "f"));
+            if (password) {
+                if (encryptedEncryptionKey) {
+                    const decryptedEncryptionKey = (await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").decrypt(password, encryptedEncryptionKey));
+                    const importedKey = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").importKey(decryptedEncryptionKey);
+                    vault = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").decryptWithKey(importedKey, encryptedVault);
+                    __classPrivateFieldSet(this, _KeyringController_password, password, "f");
+                    updatedState.encryptionKey = decryptedEncryptionKey;
+                }
+                else {
+                    const result = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").decryptWithDetail(password, encryptedVault);
+                    vault = result.vault;
+                    __classPrivateFieldSet(this, _KeyringController_password, password, "f");
+                    updatedState.encryptionKey = result.exportedKeyString;
+                    updatedState.encryptionSalt = result.salt;
+                }
+            }
+            else {
+                const parsedEncryptedVault = JSON.parse(encryptedVault);
+                if (encryptionSalt !== parsedEncryptedVault.salt) {
+                    throw new Error(constants_1.KeyringControllerError.ExpiredCredentials);
+                }
+                if (typeof encryptionKey !== 'string') {
+                    throw new TypeError(constants_1.KeyringControllerError.WrongPasswordType);
+                }
+                const importedKey = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").importKey(encryptionKey);
+                vault = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").decryptWithKey(importedKey, parsedEncryptedVault);
+                // This call is required on the first call because encryptionKey
+                // is not yet inside the memStore
+                updatedState.encryptionKey = encryptionKey;
+                // we can safely assume that encryptionSalt is defined here
+                // because we compare it with the salt from the vault
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                updatedState.encryptionSalt = encryptionSalt;
+            }
         }
         else {
-            const { exportedEncryptionKey } = credentials;
-            __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_useEncryptionKey).call(this, exportedEncryptionKey, parsedEncryptedVault.salt);
-        }
-        const encryptionKey = __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f")?.exported;
-        if (!encryptionKey) {
-            throw new Error(constants_1.KeyringControllerError.MissingCredentials);
+            if (typeof password !== 'string') {
+                throw new TypeError(constants_1.KeyringControllerError.WrongPasswordType);
+            }
+            vault = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").decrypt(password, encryptedVault);
+            __classPrivateFieldSet(this, _KeyringController_password, password, "f");
         }
-        const key = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").importKey(encryptionKey);
-        const vault = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").decryptWithKey(key, parsedEncryptedVault);
         if (!isSerializedKeyringsArray(vault)) {
             throw new Error(constants_1.KeyringControllerError.VaultDataError);
         }
@@ -1427,8 +1479,10 @@ async function _KeyringController_unlockKeyrings(credentials) {
         const updatedKeyrings = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getUpdatedKeyrings).call(this);
         this.update((state) => {
             state.keyrings = updatedKeyrings;
-            state.encryptionKey = encryptionKey;
-            state.encryptionSalt = parsedEncryptedVault.salt;
+            if (updatedState.encryptionKey || updatedState.encryptionSalt) {
+                state.encryptionKey = updatedState.encryptionKey;
+                state.encryptionSalt = updatedState.encryptionSalt;
+            }
         });
         return { keyrings, newMetadata };
     });
@@ -1436,41 +1490,84 @@ async function _KeyringController_unlockKeyrings(credentials) {
     return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withVaultLock).call(this, async () => {
         // Ensure no duplicate accounts are persisted.
         await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertNoDuplicateAccounts).call(this);
-        if (!__classPrivateFieldGet(this, _KeyringController_encryptionKey, "f")) {
+        const { encryptionKey, encryptionSalt, vault } = this.state;
+        // READ THIS CAREFULLY:
+        // We do check if the vault is still considered up-to-date, if not, we would not re-use the
+        // cached key and we will re-generate a new one (based on the password).
+        //
+        // This helps doing seamless updates of the vault. Useful in case we change some cryptographic
+        // parameters to the KDF.
+        const useCachedKey = encryptionKey && vault && __classPrivateFieldGet(this, _KeyringController_encryptor, "f").isVaultUpdated?.(vault);
+        if (!__classPrivateFieldGet(this, _KeyringController_password, "f") && !encryptionKey) {
             throw new Error(constants_1.KeyringControllerError.MissingCredentials);
         }
         const serializedKeyrings = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getSerializedKeyrings).call(this);
         if (!serializedKeyrings.some((keyring) => keyring.type === KeyringTypes.hd)) {
             throw new Error(constants_1.KeyringControllerError.NoHdKeyring);
         }
-        const key = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").importKey(__classPrivateFieldGet(this, _KeyringController_encryptionKey, "f").exported);
-        const encryptedVault = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").encryptWithKey(key, serializedKeyrings);
-        if (__classPrivateFieldGet(this, _KeyringController_encryptionKey, "f").salt) {
-            // We need to include the salt used to derive
-            // the encryption key, to be able to derive it
-            // from password again.
-            encryptedVault.salt = __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f").salt;
+        const updatedState = {};
+        if (__classPrivateFieldGet(this, _KeyringController_cacheEncryptionKey, "f")) {
+            assertIsExportableKeyEncryptor(__classPrivateFieldGet(this, _KeyringController_encryptor, "f"));
+            if (useCachedKey) {
+                const key = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").importKey(encryptionKey);
+                const vaultJSON = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").encryptWithKey(key, serializedKeyrings);
+                vaultJSON.salt = encryptionSalt;
+                updatedState.vault = JSON.stringify(vaultJSON);
+            }
+            else if (__classPrivateFieldGet(this, _KeyringController_password, "f")) {
+                if (__classPrivateFieldGet(this, _KeyringController_encryptionKey, "f")) {
+                    // Update cached key.
+                    updatedState.encryptionKey = __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f");
+                    // Encrypt key and update encrypted key.
+                    const encryptedEncryptionKey = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").encrypt(__classPrivateFieldGet(this, _KeyringController_password, "f"), __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f"));
+                    updatedState.encryptedEncryptionKey = encryptedEncryptionKey;
+                    // Encrypt and update vault.
+                    const importedKey = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").importKey(__classPrivateFieldGet(this, _KeyringController_encryptionKey, "f"));
+                    const vaultJSON = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").encryptWithKey(importedKey, serializedKeyrings);
+                    // Note that we don't need to explicitly append the salt to the
+                    // vault here as it's already stored as part of the encrypted
+                    // encryption key.
+                    updatedState.vault = JSON.stringify(vaultJSON);
+                }
+                else {
+                    const { vault: newVault, exportedKeyString } = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").encryptWithDetail(__classPrivateFieldGet(this, _KeyringController_password, "f"), serializedKeyrings);
+                    updatedState.vault = newVault;
+                    updatedState.encryptionKey = exportedKeyString;
+                }
+            }
+        }
+        else {
+            assertIsValidPassword(__classPrivateFieldGet(this, _KeyringController_password, "f"));
+            updatedState.vault = await __classPrivateFieldGet(this, _KeyringController_encryptor, "f").encrypt(__classPrivateFieldGet(this, _KeyringController_password, "f"), serializedKeyrings);
+        }
+        if (__classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_isEnvelopeEncryptionEnabled).call(this)) {
+            assertIsCacheEncryptionKeyTrue(__classPrivateFieldGet(this, _KeyringController_cacheEncryptionKey, "f"));
+        }
+        if (!updatedState.vault) {
+            throw new Error(constants_1.KeyringControllerError.MissingVaultData);
         }
-        const updatedState = {
-            vault: JSON.stringify(encryptedVault),
-            encryptionKey: __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f").exported,
-            encryptionSalt: __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f").salt,
-        };
         const updatedKeyrings = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getUpdatedKeyrings).call(this);
         this.update((state) => {
             state.vault = updatedState.vault;
             state.keyrings = updatedKeyrings;
-            state.encryptionKey = updatedState.encryptionKey;
-            state.encryptionSalt = updatedState.encryptionSalt;
+            if (updatedState.encryptionKey) {
+                state.encryptionKey = updatedState.encryptionKey;
+                state.encryptionSalt = JSON.parse(updatedState.vault).salt;
+            }
+            if (updatedState.encryptedEncryptionKey) {
+                state.encryptedEncryptionKey = updatedState.encryptedEncryptionKey;
+            }
         });
         return true;
     });
 }, _KeyringController_isNewEncryptionAvailable = function _KeyringController_isNewEncryptionAvailable() {
     const { vault } = this.state;
-    if (!vault || !__classPrivateFieldGet(this, _KeyringController_encryptor, "f").isVaultUpdated) {
+    if (!vault || !__classPrivateFieldGet(this, _KeyringController_password, "f") || !__classPrivateFieldGet(this, _KeyringController_encryptor, "f").isVaultUpdated) {
         return false;
     }
     return !__classPrivateFieldGet(this, _KeyringController_encryptor, "f").isVaultUpdated(vault);
+}, _KeyringController_isEnvelopeEncryptionEnabled = function _KeyringController_isEnvelopeEncryptionEnabled() {
+    return this.state.encryptedEncryptionKey || __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f");
 }, _KeyringController_getAccountsFromKeyrings = 
 /**
  * Retrieves all the accounts from keyrings instances
@@ -1555,7 +1652,8 @@ async function _KeyringController_createKeyring(type, data) {
     if (keyring.init) {
         await keyring.init();
     }
-    if (type === KeyringTypes.hd && (!(0, utils_1.isObject)(data) || !data.mnemonic)) {
+    if (type === KeyringTypes.hd &&
+        (!(0, utils_1.isObject)(data) || !data.mnemonic)) {
         if (!keyring.generateRandomMnemonic) {
             throw new Error(constants_1.KeyringControllerError.UnsupportedGenerateRandomMnemonic);
         }
@@ -1677,11 +1775,16 @@ async function _KeyringController_assertNoDuplicateAccounts(additionalKeyrings =
     }
 }, _KeyringController_persistOrRollback = 
 /**
- * Execute the given function after acquiring the controller lock
- * and save the vault to state after it (only if needed), or rollback to their
- * previous state in case of error.
+ * Execute the given function after acquiring the controller lock and save the
+ * vault to state after it (only if needed), or rollback to their previous
+ * state in case of error.
+ *
+ * ATTENTION: The callback must **not** alter `controller.state`. Any state
+ * change performed by the callback will not be rolled back on error.
  *
- * @param callback - The function to execute.
+ * @param callback - The function to execute. This callback must **not** alter
+ * `controller.state`. Any state change performed by the callback will not be
+ * rolled back on error.
  * @returns The result of the function.
  */
 async function _KeyringController_persistOrRollback(callback) {
@@ -1706,16 +1809,15 @@ async function _KeyringController_persistOrRollback(callback) {
 async function _KeyringController_withRollback(callback) {
     return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withControllerLock).call(this, async ({ releaseLock }) => {
         const currentSerializedKeyrings = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getSerializedKeyrings).call(this);
-        const currentEncryptionKey = __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f")?.exported;
-        const currentEncryptionSalt = __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f")?.salt;
+        const currentPassword = __classPrivateFieldGet(this, _KeyringController_password, "f");
+        const currentEncryptionKey = __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f");
         try {
             return await callback({ releaseLock });
         }
         catch (e) {
-            // Keyrings and encryption credentials are restored to their previous state
-            if (currentEncryptionKey && currentEncryptionSalt) {
-                __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_useEncryptionKey).call(this, currentEncryptionKey, currentEncryptionSalt);
-            }
+            // Previous state is restored.
+            __classPrivateFieldSet(this, _KeyringController_password, currentPassword, "f");
+            __classPrivateFieldSet(this, _KeyringController_encryptionKey, currentEncryptionKey, "f");
             await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_restoreSerializedKeyrings).call(this, currentSerializedKeyrings);
             throw e;
         }