Keyring Controller: Add method to export vault key

packages/keyring-controller/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add method `exportEncryptionKey` ([#5984](https://github.com/MetaMask/core/pull/5984))
+
+### Changed
+
+- Make salt optional with method `submitEncryptionKey` ([#5984](https://github.com/MetaMask/core/pull/5984))
+
 ## [22.0.2]
 
 ### Fixed

packages/keyring-controller/src/KeyringController.test.ts

@@ -3277,6 +3277,58 @@ describe('KeyringController', () => {
     });
   });
 
+  describe('exportEncryptionKey', () => {
+    it('should export encryption key and unlock', async () => {
+      await withController(
+        { cacheEncryptionKey: true },
+        async ({ controller }) => {
+          const encryptionKey = await controller.exportEncryptionKey();
+          expect(encryptionKey).toBeDefined();
+
+          await controller.setLocked();
+
+          await controller.submitEncryptionKey(encryptionKey);
+
+          expect(controller.isUnlocked()).toBe(true);
+        },
+      );
+    });
+
+    it('should throw error if controller is locked', async () => {
+      await withController(
+        { cacheEncryptionKey: true },
+        async ({ controller }) => {
+          await controller.setLocked();
+          await expect(controller.exportEncryptionKey()).rejects.toThrow(
+            KeyringControllerError.ControllerLocked,
+          );
+        },
+      );
+    });
+
+    it('should export key after password change', async () => {
+      await withController(
+        { cacheEncryptionKey: true },
+        async ({ controller }) => {
+          await controller.changePassword('new password');
+          const encryptionKey = await controller.exportEncryptionKey();
+          expect(encryptionKey).toBeDefined();
+        },
+      );
+    });
+
+    it('should export key after password change to the same password', async () => {
+      await withController(
+        { cacheEncryptionKey: true },
+        async ({ controller }) => {
+          await controller.changePassword(password);
+          const encryptionKey = await controller.exportEncryptionKey();
+          expect(encryptionKey).toBeDefined();
+        },
+      );
+    });
+  });
+
   describe('verifySeedPhrase', () => {
     it('should return current seedphrase', async () => {
       await withController(async ({ controller }) => {

packages/keyring-controller/src/KeyringController.ts

@@ -1434,16 +1434,17 @@ export class KeyringController extends BaseController<
   }
 
   /**
-   * Attempts to decrypt the current vault and load its keyrings,
-   * using the given encryption key and salt.
+   * Attempts to decrypt the current vault and load its keyrings, using the
+   * given encryption key and salt. The optional salt can be used to check for
+   * consistency with the vault salt.
    *
    * @param encryptionKey - Key to unlock the keychain.
-   * @param encryptionSalt - Salt to unlock the keychain.
+   * @param encryptionSalt - Optional salt to unlock the keychain.
    * @returns Promise resolving when the operation completes.
    */
   async submitEncryptionKey(
     encryptionKey: string,
-    encryptionSalt: string,
+    encryptionSalt?: string,
   ): Promise<void> {
     const { newMetadata } = await this.#withRollback(async () => {
       const result = await this.#unlockKeyrings(
@@ -1470,6 +1471,44 @@ export class KeyringController extends BaseController<
     }
   }
 
+  /**
+   * Exports the vault encryption key.
+   *
+   * @returns The vault encryption key.
+   */
+  async exportEncryptionKey(): Promise<string> {
+    this.#assertIsUnlocked();
+
+    return await this.#withControllerLock(async () => {
+      // There is a case where the controller is unlocked but the encryption key
+      // is not set, even when #cacheEncryptionKey is true. This happens when
+      // calling changePassword with the existing password. In this case, the
+      // encryption key is deleted, but the state is not recreated, because the
+      // session state does not change in this case, and #updateVault is not
+      // called in #persistOrRollback.
+      if (!this.state.encryptionKey) {
+        return await this.#withVaultLock(async () => {
+          assertIsExportableKeyEncryptor(this.#encryptor);
+          assertIsValidPassword(this.#password);
+          const result = await this.#encryptor.decryptWithDetail(
+            this.#password,
+            // Ignoring undefined. Assuming vault is set when unlocked.
+            this.state.vault as string,
+          );
+          if (this.#cacheEncryptionKey) {
+            this.update((state) => {
+              state.encryptionKey = result.exportedKeyString;
+              state.encryptionSalt = result.salt;
+            });
+          }
+          return result.exportedKeyString;
+        });
+      }
+
+      return this.state.encryptionKey;
+    });
+  }
+
   /**
    * Attempts to decrypt the current vault and load its keyrings,
    * using the given password.
@@ -2279,8 +2318,10 @@ export class KeyringController extends BaseController<
         } else {
           const parsedEncryptedVault = JSON.parse(encryptedVault);
 
-          if (encryptionSalt !== parsedEncryptedVault.salt) {
+          if (encryptionSalt && encryptionSalt !== parsedEncryptedVault.salt) {
             throw new Error(KeyringControllerError.ExpiredCredentials);
+          } else {
+            encryptionSalt = parsedEncryptedVault.salt as string;
           }
 
           if (typeof encryptionKey !== 'string') {
@@ -2296,10 +2337,7 @@ export class KeyringController extends BaseController<
           // 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!;
+          updatedState.encryptionSalt = encryptionSalt;
         }
       } else {
         if (typeof password !== 'string') {