feat: [MFA-581] mfa recovery controller

[ieow]

Explanation

Current state

MFA recovery needs to keep a recovery secret consistent across multiple escrow
replicas. A mutation can succeed at one escrow and fail at another, so the
controller needs durable progress tracking, request binding, and a safe way to
resume incomplete writes.

The original implementation also combined mutation orchestration, pending-state
validation, receipt handling, and read consistency logic in one large
controller file.

Solution

This PR introduces @metamask/mfa-recovery-controller, which coordinates
profile authentication, identifier authentication, recovery-secret reads, and
replication across build-configured escrow providers.

The mutation protocol now:

• Creates one request-bound mutation containing the profile, operation,
  expected/new versions, payload hash, and escrow audiences.
• Persists encrypted authorizing state before authorization.
• Persists encrypted writing state with the auth token and acknowledged
  escrow receipts before starting writes.
• Applies the same mutation to every configured escrow and validates each
  receipt against its expected escrow.
• Persists successful receipts even when another escrow fails.
• Allows resume() to retry only missing acknowledgements.
• Requires escrow-side idempotency by mutation id so a crash after a write but
  before receipt persistence is safe to retry.
• Clears pending state only after every configured escrow is acknowledged.

The controller now rejects malformed persisted operations before authorization
or escrow calls. Fully acknowledged pending mutations can be cleared without
checking availability of already-acknowledged escrows.

The large controller has been split into focused internal modules:

• pending-operation-validation.ts handles runtime validation of decrypted
  pending state.
• escrow-utils.ts handles receipt validation, settled-result narrowing, and
  highest-consistent-version selection.

The public exports remain unchanged by this refactor. The
RecoveryEscrowProvider.verifyReceipt contract intentionally requires the
expected escrow id, which is a breaking provider-interface change documented
in the changelog.

Security and trust model

Mutation authorization uses one request-bound AuthControllerToken for the
configured escrow audience set. Each escrow implementation must independently
verify the token signature, issuer, expiry, profile, exact mutation hash, and
that its own id is included in the mutation audiences.

Key-bound identifier authentication creates a separate challenge and proof for
each escrow. Escrow-challenge identifiers also complete a separate challenge
for each escrow.

The current design treats configured escrows as trusted equivalent replicas:
the recovery secret is replicated in full to each escrow. This is not an
M-of-N threshold-recovery design. A future independent-trust model would need
escrow-specific authorization scopes and escrow-specific or threshold-encrypted
secret material.

References

Related work is contained in this pull request.

Validation

• yarn workspace @metamask/mfa-recovery-controller run test
  • 57 tests passing
  • 100% statements, branches, functions, and lines
• Focused ESLint passes for the changed controller, utility, type, test, and
  stub files
• yarn workspace @metamask/mfa-recovery-controller run build
• yarn workspace @metamask/mfa-recovery-controller run changelog:validate
• git diff --check

Checklist

• Updated the test suite for the updated code
• Updated documentation and JSDoc
• Updated the package changelog
• Prepared consumer follow-up pull requests for the breaking
  verifyReceipt signature change

---

Note

High Risk
Introduces new recovery-secret replication, auth, and escrow mutation logic with durable encrypted state—security-sensitive account recovery behavior and a breaking escrow provider interface.

Overview
Adds @metamask/mfa-recovery-controller, a new BaseController that orchestrates MFA recovery by replicating a recovery secret across build-configured escrow replicas with injectable RecoveryAuthProvider and RecoveryEscrowProvider implementations.

Mutations run through persisted authorizing → writing phases (encrypted pending state), exposing register, updateRecoverySecret, updateIdentifiers, getRecoverySecret, resume, and abort. resume retries only escrows missing receipts; abort is limited to pre-write authorizing state. Receipt verification is bound to the expected escrow id via a breaking RecoveryEscrowProvider.verifyReceipt(receipt, mutation, expectedEscrowId) contract.

Monorepo wiring registers the package under Web3Auth / team-onboarding (CODEOWNERS, codeowners.ts, teams.json, root README/tsconfig, yarn.lock).

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

[ieow]

https://consensyssoftware.atlassian.net/browse/MFA-581

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ 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 2a3b74e. Configure here.}

[cursor]

Auth token persisted without mutation checks

Medium Severity

The controller persists a writing token from #authorizeMutation without checking profileId or requestHash against the mutation. A mismatched token later fails pending validation, so resume and abort cannot load the record they just wrote.

Additional Locations (2)

• packages/mfa-recovery-controller/src/MfaRecoveryController.ts#L480-L492
• packages/mfa-recovery-controller/src/MfaRecoveryController.ts#L545-L554

 

^{Reviewed by Cursor Bugbot for commit 2a3b74e. Configure here.}