feat(keyring-controller): add withController for atomic operations over multiple keyrings

[ccharly]

Explanation

Today there's no way to make multiple operations in an "atomic" (read transactional) way.

A good example of this is if you want to use a keyring using withKeyring that's not existing yet (I'm omitting the createIfMissing variants, as we wanted to move away from this pattern).

To do this in a safe way, you usually have to use your own lock to make sure you can get-or-create the keyring and prevent concurrent keyring creations.

This new withController is based on the withKeyring but with an access to a "restricted" state and methods of the controller. This way, you can interact with multiple keyring at once while being guarded (to prevent race-conditions) by the controller's global lock.

The former problem can then be written that way now:

const account = await keyringController.withController(async (controller) => {
  // Here, `controller.keyrings` is a "view" on the existing keyrings (instances), only valid
  // for this block.
  let keyring: MyKeyring | undefined = controller.keyrings.find(isMyKeyring);
  if (!keyring) {
    const { keyring: myKeyring } = await controller.addNewKeyring({ type: 'My Keyring', data: { ... }});
    keyring = myKeyring;
  }
  
  const [account] = await keyring.createAccounts(...);
  return account;
});

This will also be used to write the migration from the existing SnapKeyring (1 for ALL Snaps) to multiple SnapKeyring (1 PER Snap) in a safe way like:

await keyringController.withController(async (controller) => {
  const accounts: Map<SnapId, KeyringAccount[]> = new Map();

  // Get existing Snap accounts from the single Snap keyring instance we have today.
  const keyring: SnapKeyring | undefined = controller.keyrings.find(isSnapKeyring);
  if (keyring) {
    for (const account of keyring.listAccounts()) {
      accounts[account.metadata.snap.id] ??= [];
      accounts[account.metadata.snap.id].push(account);
    }
  }
  
  // Re-create all new Snap keyrings, 1 per Snap.
  for (const [snapId, snapAccounts] of accounts.entries()) {
    await controller.addNewKeyring({ type: 'Snap keyring', data: snapAccounts });
  }
  
  // We can safely remove the existing Snap keyring now.
  await controller.removeKeyring(...);
});

References

N/A

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them