feat(profile-sync): add MFA step-up sessions by mathieuartu · Pull Request #10267 · MetaMask/core

mathieuartu · 2026-09-16T13:42:45Z

Explanation

Adds MFA step-up verification and a memory-only elevated AAL2 session on AuthenticationController.

beginStepUp, completeStepUp, getElevatedProfileToken, clearStepUpSession.
In-memory elevated token with TTL; AuthenticationController:stepUpSession on open/close.
Session is torn down on lock, sign-out, wallet reset, successful enrollment, and when getElevatedProfileToken observes expiry.
Completing enrollment or step-up re-asserts the wallet is still unlocked after network calls so a lock during the request cannot reopen an AAL2 session.
MFA network steps are traced with operation / credentialType tags and span attributes for outcome / mfaCode.

References

Depends on #10266. Stack: stack #10268.
Related to: https://consensyssoftware.atlassian.net/browse/MUL-2263

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

High Risk
Changes authentication and elevated-token handling for sensitive operations; incorrect session TTL or teardown logic could block legitimate actions or briefly retain AAL2 access after lock/sign-out.

Overview
Adds MFA step-up verification on AuthenticationController: beginStepUp / completeStepUp run passkey or email OTP ceremonies, exchange the MFA assertion for an AAL2 elevated profile token, and expose it via getElevatedProfileToken while a short-lived session is open. The token stays memory-only; persisted/UI state is limited to non-secret stepUpSessionExpiresAt (60s TTL clamped to JWT exp).

Session lifecycle clears elevated access on wallet lock, sign-out, wallet reset, successful credential enrollment, base-session authentication_required, and hard expiry (timer or lazy check in getElevatedProfileToken). Callers can require fresher proof with maxSessionAgeMs without tearing down the session for others.

Hardening reuses auth-session epoch checks so lock/sign-out during in-flight MFA cannot apply results; invalid exchanged tokens fail with elevated_token_invalid. MFA network tracing now sets span attributes (outcome, mfaErrorCode) via the trace callback context instead of mutating shared trace data. A 401 on credential refresh also invalidates the SRP session and drops any step-up session.

Docs/changelog and messenger action types are updated; tests cover step-up flows, TTL edge cases, and enrollment lock races.

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

cursor

Stale Bugbot comment from a previous run.

cursor

Stale Bugbot comment from a previous run.

## Explanation Wires the MFA HTTP client into the SRP JWT auth SDK on top of the validation foundation. - `mfa/services` calls `/api/v2/mfa/*` (enroll, enroll complete, verify, verify complete, credentials), validates request/response bodies, maps server codes to `MfaError` subclasses, and handles OTP cooldown / `Retry-After`. - `SRPJwtBearerAuth` exposes begin/complete enrollment and verification, credential listing, and assertion-to-token exchange. - Public `JwtBearerAuth` forwards those methods and rejects non-SRP auth types. - Nock fixtures and unit tests cover happy paths and error mapping. Clients still go through `AuthenticationController` in later PRs; this layer is not UI-facing. ## References Depends on MetaMask#10264. Follow-ups: MetaMask#10266, MetaMask#10267. Stack: [stack #10268](https://github.com/MetaMask/core/pull/10268). Related to: https://consensyssoftware.atlassian.net/browse/MUL-2261 ## Checklist - [x] I've updated the test suite for new or updated code as appropriate - [x] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate - [x] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md) - [ ] I've introduced [breaking changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md) in this PR and have prepared draft pull requests for clients and consumer packages to resolve them  --- > [!NOTE] > **High Risk** > Touches authentication, step-up tokens, and passkey/OTP handling; mistakes could weaken session elevation or mishandle credentials, though coverage is extensive. > > **Overview** > Adds **passkey and email OTP MFA** to the profile-sync JWT auth SDK: a new HTTP layer calls `/api/v2/mfa/*` (enroll, complete, verify, credentials), validates payloads, maps server codes to `MfaError` subclasses, and handles OTP cooldown plus `Retry-After`. > > **`SRPJwtBearerAuth`** and public **`JwtBearerAuth`** expose enrollment/step-up flows, credential listing, and **`exchangeMfaAssertion`** (AAL2 JWT → elevated access token via existing OIDC). MFA is **SRP-only**; email enrollment uses a separate `email` option from `entropySourceId`. > > Schemas mark challenges, OTP codes, passkey payloads, and tokens with **`sensitive()`**. Tests, nock fixtures, changelog, and SDK exports for MFA types are included. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 56b3671. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  --------- Co-authored-by: Cursor <cursoragent@cursor.com>

## Explanation Exposes UI-driven MFA enrollment on `AuthenticationController` (no ApprovalController). - In-memory `enrolledCredentials` cache (optional on the state type so partial-state selectors stay assignable) with redacted emails in state logs. - `refreshEnrolledCredentials`, `beginCredentialEnrollment`, `completeCredentialEnrollment`. - `AuthenticationController:credentialsChanged` when the cache actually changes. - Automatic credential refresh after sign-in and unlock when MFA is enabled; refresh failure does not fail sign-in. - Cache cleared (and the change event published) on lock, sign-out, and wallet reset. - Regenerated messenger action types; README and changelog updates. Enrollment is UI-orchestrated: the controller returns challenges; the client collects the passkey or OTP proof and calls complete. ## References Depends on MetaMask#10265. Follow-up: MetaMask#10267. Stack: [stack #10268](https://github.com/MetaMask/core/pull/10268). Related to: https://consensyssoftware.atlassian.net/browse/MUL-2262 ## Checklist - [x] I've updated the test suite for new or updated code as appropriate - [x] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate - [x] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md) - [ ] I've introduced [breaking changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md) in this PR and have prepared draft pull requests for clients and consumer packages to resolve them  --- > [!NOTE] > **High Risk** > Changes authentication session lifecycle and MFA enrollment, including SRP token invalidation after email enroll and race handling around lock/sign-out—security-sensitive behavior that clients must wire correctly. > > **Overview** > Adds **UI-orchestrated MFA enrollment** on `AuthenticationController`: `refreshEnrolledCredentials`, `beginCredentialEnrollment`, and `completeCredentialEnrollment`, wired to the existing JWT bearer MFA SDK and new messenger action types. > > Enrollment state lives in a **non-persisted** `enrolledCredentials` cache (UI-visible; state logs allow-list type/status/enrolledAt only). An optional **`trace`** constructor hook (`@metamask/controller-utils`) wraps MFA network steps with operation/credential tags and outcomes. > > **Session and concurrency guards** bump an auth-session epoch on lock, sign-out, and wallet reset so in-flight MFA work cannot apply after the session ends; credential refreshes are sequenced so slower responses cannot overwrite newer lists. **Email OTP completion** invalidates the primary SRP session after a post-enroll refresh (or even when the session ends mid-flow) so cached tokens are not reused without the new email claim; passkey enroll does not touch the session. Sign-out/`clearState` clear the credential cache. > > Also adds MFA nock fixtures and mock response helpers, depends on `@metamask/controller-utils`, and tightens `ElevatedTokenClaimsStruct` as a single sensitive struct. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit d70d671. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  --------- Co-authored-by: Cursor <cursoragent@cursor.com>

This reverts commit 1947dc2.

ccharly · 2026-09-22T10:19:37Z

+    expect(() =>
+      controller.getElevatedProfileToken({ maxSessionAgeMs: -1 }),
+    ).toThrow(/MFA\[invalid_request\]/u);
+  });


Nit: Should we have a test to also ensure the session is not clear when the request ends up as "invalid request"? e.g. we're never clearing the token in that case?

mathieuartu requested review from a team as code owners September 16, 2026 13:42

mathieuartu added this pull request to stack #10268 September 16, 2026 13:42

This was referenced Sep 16, 2026

feat(profile-sync): add MFA validation foundation #10264

Merged

feat(profile-sync): add MFA authentication services #10265

Merged

feat(profile-sync): add MFA credential enrollment #10266

Merged

cursor Bot reviewed Sep 16, 2026

View reviewed changes

Comment thread packages/profile-sync-controller/src/controllers/authentication/AuthenticationController.ts

mathieuartu force-pushed the mfa/controller-stepup branch from 58aa78b to 796a725 Compare September 16, 2026 14:08

mathieuartu self-assigned this Sep 16, 2026

mathieuartu added the team-accounts label Sep 16, 2026

cursor Bot reviewed Sep 16, 2026

View reviewed changes

Comment thread packages/profile-sync-controller/src/controllers/authentication/AuthenticationController.ts

mathieuartu force-pushed the mfa/controller-stepup branch from 5fe0fb9 to b6feacb Compare September 16, 2026 20:13

mathieuartu force-pushed the mfa/controller-stepup branch from b6feacb to 2c4687d Compare September 16, 2026 20:31

mathieuartu force-pushed the mfa/controller-stepup branch 4 times, most recently from 7826fcb to e84159d Compare September 16, 2026 21:03

mathieuartu force-pushed the mfa/controller-stepup branch from e84159d to ab66eab Compare September 17, 2026 06:48

mathieuartu force-pushed the mfa/controller-stepup branch from ab66eab to 15ab75a Compare September 17, 2026 06:53

mathieuartu force-pushed the mfa/controller-stepup branch 2 times, most recently from 9c60aec to 26775e8 Compare September 17, 2026 07:46

mathieuartu force-pushed the mfa/controller-stepup branch from 26775e8 to 5478a59 Compare September 17, 2026 08:12

mathieuartu force-pushed the mfa/controller-stepup branch from 98c36cc to ca7b5d0 Compare September 18, 2026 12:13

mathieuartu force-pushed the mfa/controller-stepup branch 2 times, most recently from b04a6c3 to 89d2052 Compare September 18, 2026 13:47

mathieuartu force-pushed the mfa/controller-stepup branch 2 times, most recently from ed5705e to 07823f4 Compare September 18, 2026 21:10

mathieuartu force-pushed the mfa/controller-stepup branch from 07823f4 to 1eafaf2 Compare September 21, 2026 14:07

Base automatically changed from mfa/controller-enrollment to main September 21, 2026 15:37

mathieuartu force-pushed the mfa/controller-stepup branch from 1eafaf2 to 744dee0 Compare September 21, 2026 15:37

mathieuartu added 3 commits September 22, 2026 10:05

feat(profile-sync): add MFA step-up sessions to AuthenticationController

2544d14

fix: add back cleanAllNock

bc3561b

fix: remove stepUpSessionTtlMs

716bf2e

mathieuartu force-pushed the mfa/controller-stepup branch from 744dee0 to 716bf2e Compare September 22, 2026 08:05

ccharly reviewed Sep 22, 2026

View reviewed changes

mathieuartu added 3 commits September 22, 2026 10:55

fix: address PR feedbacks

5968e4f

fix: add clearStepUpSession in invalidateSrpSession

1947dc2

Revert "fix: add clearStepUpSession in invalidateSrpSession"

b22c0c9

This reverts commit 1947dc2.

ccharly previously approved these changes Sep 22, 2026

View reviewed changes

fix: add UT

8f0582f

mathieuartu dismissed ccharly’s stale review via 8f0582f September 22, 2026 11:06

ccharly approved these changes Sep 22, 2026

View reviewed changes

mathieuartu added this pull request to the merge queue Sep 22, 2026

Merged via the queue into main with commit 5bbe76c Sep 22, 2026
136 checks passed

mathieuartu deleted the mfa/controller-stepup branch September 22, 2026 11:20

Navigation Menu

Uh oh!

feat(profile-sync): add MFA step-up sessions - #10267

feat(profile-sync): add MFA step-up sessions#10267
mathieuartu merged 7 commits into
mainfrom
mfa/controller-stepup

mathieuartu commented Sep 16, 2026 •

edited by cursor Bot

Loading

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ccharly Sep 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

mathieuartu commented Sep 16, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

References

Checklist

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ccharly Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mathieuartu commented Sep 16, 2026 •

edited by cursor Bot

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading