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 a new transactional API that can create/remove keyrings and then persist/rollback state, which touches keyring lifecycle and vault persistence paths. Risk is moderate due to potential edge cases around staged mutations, keyring destruction, and primary keyring protection.

Overview
Adds KeyringController.withController (and messenger action KeyringController:withController) to run single-lock, atomic operations across multiple keyrings via a RestrictedController that exposes a live read-only view plus staged addNewKeyring/removeKeyring mutations.

On success it commits staged keyring list changes, persists via existing persist/rollback flow, and destroys removed keyrings; on error it rolls back and destroys any newly created keyrings. The PR also blocks removal of the primary HD keyring (CannotRemovePrimaryKeyring), extends KeyringEntry/callback typings, updates mocks to include destroy, and adds comprehensive unit + messenger tests for the new behavior.

^{Reviewed by Cursor Bugbot for commit 0ae24f6. 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.}