feat: 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

[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 0b4047c. Configure here.}

[cursor]

Read auth fails closed

Medium Severity

getRecoverySecret tolerates individual getSecret failures, but #authorizeIdentifier uses Promise.all for challenges. If any escrow that reported available then fails challenge creation, the whole read fails even when another replica could return the secret.

Additional Locations (2)

• packages/mfa-recovery-controller/src/MfaRecoveryController.ts#L621-L624
• packages/mfa-recovery-controller/src/MfaRecoveryController.ts#L640-L655

 

^{Reviewed by Cursor Bugbot for commit 0b4047c. Configure here.}