feat: Implement wallet initialization library

.github/CODEOWNERS

@@ -128,6 +128,9 @@
 /packages/client-controller                     @MetaMask/core-platform @MetaMask/extension-platform @MetaMask/mobile-platform
 /packages/profile-metrics-controller            @MetaMask/mobile-platform @MetaMask/extension-platform
 
+## Initialization
+/packages/wallet/src/initialization/instances/keyring-controller.ts @MetaMask/accounts-engineers @MetaMask/core-platform
+
 ## Package Release related
 /packages/account-tree-controller/package.json  @MetaMask/accounts-engineers @MetaMask/core-platform
 /packages/account-tree-controller/CHANGELOG.md  @MetaMask/accounts-engineers @MetaMask/core-platform

README.md

@@ -565,6 +565,9 @@ linkStyle default opacity:0.5
   user_operation_controller --> polling_controller;
   user_operation_controller --> transaction_controller;
   user_operation_controller --> eth_block_tracker;
+  wallet --> base_controller;
+  wallet --> keyring_controller;
+  wallet --> messenger;
 ```
 
 <!-- end dependency graph -->

packages/wallet/CHANGELOG.md

@@ -7,4 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Initial release ([#8838](https://github.com/MetaMask/core/pull/8838))
+
 [Unreleased]: https://github.com/MetaMask/core/

packages/wallet/package.json

@@ -52,6 +52,14 @@
     "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
     "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
   },
+  "dependencies": {
+    "@metamask/base-controller": "^9.1.0",
+    "@metamask/browser-passworder": "^6.0.0",
+    "@metamask/keyring-controller": "^25.5.0",
+    "@metamask/messenger": "^1.2.0",
+    "@metamask/scure-bip39": "^2.1.1",
+    "@metamask/utils": "^11.9.0"
+  },
   "devDependencies": {
     "@metamask/auto-changelog": "^6.1.0",
     "@ts-bridge/cli": "^0.6.4",

packages/wallet/src/Wallet.test.ts

@@ -0,0 +1,228 @@
+import { Messenger } from '@metamask/messenger';
+import { Json } from '@metamask/utils';
+import { webcrypto } from 'crypto';
+
+import MockEncryptor from '../../keyring-controller/tests/mocks/mockEncryptor';
+import * as initializationModule from './initialization/initialization';
+import { importSecretRecoveryPhrase } from './utilities';
+import { Wallet } from './Wallet';
+
+const TEST_SRP = 'test test test test test test test test test test test ball';
+const TEST_PASSWORD = 'testpass';
+
+async function setupWallet(): Promise<Wallet> {
+  const wallet = new Wallet({});
+
+  await importSecretRecoveryPhrase(wallet, TEST_PASSWORD, TEST_SRP);
+
+  return wallet;
+}
+
+describe('Wallet', () => {
+  beforeAll(() => {
+    // We can remove this once we drop Node 18
+    // eslint-disable-next-line n/no-unsupported-features/node-builtins
+    globalThis.crypto ??= webcrypto as typeof globalThis.crypto;
+
+    // eslint-disable-next-line no-restricted-syntax
+    if (!('CryptoKey' in globalThis)) {
+      Object.defineProperty(globalThis, 'CryptoKey', {
+        value: webcrypto.CryptoKey,
+      });
+    }
+  });
+
+  it('exposes state', async () => {
+    const wallet = await setupWallet();
+    const { state } = wallet;
+
+    expect(state.KeyringController).toStrictEqual({
+      isUnlocked: true,
+      keyrings: expect.any(Array),
+      encryptionKey: expect.any(String),
+      encryptionSalt: expect.any(String),
+      vault: expect.any(String),
+    });
+  });
+
+  it('exposes instances', async () => {
+    const wallet = await setupWallet();
+
+    expect(wallet.getInstance('KeyringController').state).toStrictEqual({
+      isUnlocked: true,
+      keyrings: expect.any(Array),
+      encryptionKey: expect.any(String),
+      encryptionSalt: expect.any(String),
+      vault: expect.any(String),
+    });
+  });
+
+  it('supports passing instance options', async () => {
+    const wallet = new Wallet({
+      instanceOptions: {
+        keyringController: {
+          encryptor: new MockEncryptor(),
+        },
+      },
+    });
+
+    await importSecretRecoveryPhrase(wallet, TEST_PASSWORD, TEST_SRP);
+
+    const { state } = wallet;
+
+    const vault = JSON.parse(state.KeyringController.vault as string);
+
+    expect(vault).toStrictEqual({
+      data: expect.any(String),
+      iv: 'iv',
+      salt: 'salt',
+    });
+  });
+
+  it('supports passing additional initialization configurations', async () => {
+    class DummyController {
+      state = { foo: 'bar' };
+    }
+
+    class DummyService {}
+
+    const wallet = new Wallet({
+      initializationConfigurations: [
+        {
+          name: 'KeyringController',
+          getMessenger: (): Messenger<string> =>
+            new Messenger({ namespace: 'KeyringController' }),
+          init: (): DummyController => new DummyController(),
+        },
+        {
+          name: 'TestService',
+          getMessenger: (): Messenger<string> =>
+            new Messenger({ namespace: 'TestService' }),
+          init: (): DummyService => new DummyService(),
+        },
+      ],
+    });
+    const { state } = wallet;
+
+    expect(state.KeyringController).toStrictEqual({
+      foo: 'bar',
+    });
+
+    expect((state as Record<string, Json>).TestService).toBeUndefined();
+  });
+
+  it('exposes controllerMetadata for each initialized controller', async () => {
+    const wallet = await setupWallet();
+
+    const names = Object.keys(wallet.controllerMetadata);
+    expect(names).toStrictEqual(Object.keys(wallet.state));
+    for (const name of names) {
+      expect(wallet.controllerMetadata[name]).toBeDefined();
+    }
+  });
+
+  it('omits instances without a metadata property from controllerMetadata', async () => {
+    const fakeMetadata = {
+      foo: { persist: true, includeInDebugSnapshot: false },
+    };
+    jest.spyOn(initializationModule, 'initialize').mockReturnValueOnce({
+      // @ts-expect-error Mock data.
+      WithMeta: { state: {}, metadata: fakeMetadata },
+      NoMeta: { state: {} },
+    });
+
+    const wallet = new Wallet({});
+
+    expect(wallet.controllerMetadata).toStrictEqual({
+      WithMeta: fakeMetadata,
+    });
+    expect(Object.keys(wallet.state)).toStrictEqual(['WithMeta', 'NoMeta']);
+  });
+
+  it('disallows modifying the messenger', async () => {
+    const wallet = await setupWallet();
+
+    expect(() => {
+      wallet.messenger = new Messenger({ namespace: 'Root' });
+    }).toThrow('The messenger cannot be directly mutated.');
+  });
+
+  it('disallows modifying the state', async () => {
+    const wallet = await setupWallet();
+
+    expect(() => {
+      wallet.state = { KeyringController: { isUnlocked: false, keyrings: [] } };
+    }).toThrow('Wallet state cannot be directly mutated.');
+  });
+
+  it('disallows modifying the controller metadata', async () => {
+    const wallet = await setupWallet();
+
+    expect(() => {
+      wallet.controllerMetadata = {};
+    }).toThrow('The controller metadata cannot be directly mutated.');
+  });
+
+  it('calls destroy on instances exactly once', async () => {
+    const wallet = await setupWallet();
+
+    const keyringController = wallet.getInstance('KeyringController');
+
+    const spy = jest.spyOn(keyringController, 'destroy');
+
+    await wallet.destroy();
+    await wallet.destroy();
+
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  describe('KeyringController', () => {
+    it('can unlock and populate accounts', async () => {
+      const wallet = await setupWallet();
+      const { messenger } = wallet;
+
+      expect(
+        await messenger.call('KeyringController:getAccounts'),
+      ).toStrictEqual(['0xc6d5a3c98ec9073b54fa0969957bd582e8d874bf']);
+    });
+
+    it('can unlock a persisted vault', async () => {
+      const vault =
+        '{"data":"iOD5pIcPeRZYQ4WdEMsNYoZ3xBxWBafIU8Cr4nD0X4zBvrOA06tGen3sKQ/ValasXSweLnzH9Fk2frkPYmqeJWBtTNYFwdHPe7P970ThZwreSXN1Sqrx9Ad+YzmIN0y89Yg3KrUodPWaRgIZmgWbfDon6ADPgeEDkX0/GAEYET39O7Rx/gL+rcaTpxnpHPTgHiLbhRHWGsS3z+JVomSqoLAO5XVvrJWenO6R3Nzm62BaJaSPrf/pwstZqhSvxTq8hnQf7aR81hWfwYTxNBVG7TC/dniSQ8K5So6PvUN5nzAqvtzzHT2TagOuxQkX88Zi17P8os21jNmNdA90IGYroD+b/mppyRIgRYWtAUQZH9ji36atEuFupszbg8Qw1iaL3EQyUogC30Cpj9ko5bbqhYgqmFHF0J/kflhPHKuO6d4tgSmhYpTumydQRjxaPnlghIS5YI4W+7p9HVBpb+c6IPUz9y/x3Ngbp+ukJwOnXt2U/eZhXrJzi2z1x/nzPg4fzDJoM7k=","iv":"yrZsyC7dso/q7pQ48YX3vw==","keyMetadata":{"algorithm":"PBKDF2","params":{"iterations":600000}},"salt":"s7nIrMWK1lcZVjfdmES1DBML8Uz4ja2fpm8zUz1lWI0="}';
+
+      const wallet = new Wallet({
+        state: {
+          KeyringController: {
+            vault,
+          },
+        },
+      });
+
+      await wallet.messenger.call(
+        'KeyringController:submitPassword',
+        TEST_PASSWORD,
+      );
+
+      expect(wallet.state.KeyringController).toStrictEqual({
+        isUnlocked: true,
+        keyrings: expect.any(Array),
+        encryptionKey: expect.any(String),
+        encryptionSalt: expect.any(String),
+        vault: expect.any(String),
+      });
+    });
+
+    it('can lock', async () => {
+      const wallet = await setupWallet();
+      const { messenger } = wallet;
+
+      await messenger.call('KeyringController:setLocked');
+
+      expect(wallet.state.KeyringController).toStrictEqual({
+        isUnlocked: false,
+        keyrings: [],
+        vault: expect.any(String),
+      });
+    });
+  });
+});