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

---

Note

Medium Risk
Adds new transactional mutation surface that can create/remove keyrings and update vault persistence/rollback semantics, so bugs could affect keyring lifecycle and vault state integrity.

Overview
Adds KeyringController.withController (and messenger action KeyringController:withController) to run single-lock, transaction-like operations across multiple keyrings via a RestrictedController view that supports staged addNewKeyring/removeKeyring, auto-persist on success, and rollback (including destroying newly created keyrings) on error.

Updates types to export KeyringEntry/RestrictedController, wires withController into the exposed messenger methods and action union, and expands tests to cover lock checks, immediate visibility of staged changes, commit/rollback behavior, and preventing returning raw keyring instances; test mocks add a destroy() method to support lifecycle assertions.

^{Reviewed by Cursor Bugbot for commit 21276f6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 02a9fac. Configure here.}