feat(react): MFA step-up challenge & enrolment flow

[harishsundar-okta]

Changes

Please describe both what is changing and why this is important. Include:

Implements the interactive MFA step-up flow inside Gatekeeper. When a step-up is required, users are now walked through selecting an authenticator, receiving a challenge, and submitting a verification code. If no authenticators are enrolled, an enrollment flow is presented first.

Changes

• New hook — useStepUpChallenge
• Manages LIST → CHALLENGING → VERIFY state. Uses a "frozen challenge" ref to ensure the mfaToken + oobCode pair captured at challenge time is always used for the matching verify call, regardless of parent re-renders.

New components (mfa-step-up/)

• step-up-authenticator-list — pick an authenticator to verify with
• step-up-challenge-form — OTP/OOB code input
• step-up-enrollment-setup-form — enrollment orchestrator (factor picker → per-factor sub-flow)
• step-up-contact-input-form — email/SMS enrollment
• step-up-qr-code-enrollment-form — TOTP/Push QR enrollment
• Gatekeeper — wires everything together; fetches enrollment factors (SPA only) and authenticators, dispatches to the right component via getMfaFetchState()

i18n — common.error.mfa.* expanded with ~20 new keys in en-US and ja

Types — step-up-types.ts challenge array tightened from { type: string } to { type: ChallengeType }

References

Please include relevant links supporting this change such as a:

• support ticket
• community post
• StackOverflow post
• support forum thread

Testing

Please describe how this can be tested by reviewers. Be specific about anything not tested and reasons why. If this library has unit and tests should be added for new functionality and existing tests should complete without errors.

• Trigger a step-up action against a tenant with MFA policies. Verify the authenticator list renders, OTP/OOB verification succeeds, and enrollment works for users with no registered authenticators. In proxy (RWA) mode, confirm the enrollment factor fetch is skipped.

Checklist

• I have read the Auth0 general contribution guidelines
• I have read the Auth0 Code of Conduct
• All existing and new tests complete without errors

[github-actions]

🚀 Preview deployment

Branch: refs/pull/100/merge
Commit: 0236f61

📝 Preview URL: https://auth0-universal-components-lsoqo7qjp-okta.vercel.app

---

Updated at 2026-03-09T04:47:13.185Z

[codecov-commenter]

Codecov Report

❌ Patch coverage is 70.57742% with 800 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.04%. Comparing base (eafca4d) to head (a6ee389).

Files with missing lines	Patch %	Lines
.../shared/mfa-step-up/step-up-contact-input-form.tsx	11.62%	152 Missing ⚠️
...ared/mfa-step-up/step-up-enrollment-setup-form.tsx	42.30%	150 Missing ⚠️
...ed/mfa-step-up/step-up-qr-code-enrollment-form.tsx	12.87%	115 Missing ⚠️
...src/hooks/my-organization/use-sso-provider-edit.ts	70.35%	99 Missing ⚠️
...uth0/shared/mfa-step-up/step-up-challenge-form.tsx	8.79%	83 Missing ⚠️
...eact/src/hooks/my-organization/use-domain-table.ts	81.37%	46 Missing ⚠️
...ct/src/hooks/my-organization/use-sso-domain-tab.ts	62.80%	45 Missing ⚠️
...ct/src/hooks/auth0/shared/use-step-up-challenge.ts	49.36%	40 Missing ⚠️
...rc/hooks/my-organization/use-sso-provider-table.ts	82.25%	33 Missing ⚠️
...s/react/src/components/auth0/shared/gatekeeper.tsx	92.98%	16 Missing ⚠️
... and 2 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #100      +/-   ##
==========================================
- Coverage   88.17%   83.04%   -5.13%     
==========================================
  Files         143      145       +2     
  Lines       12497    13184     +687     
  Branches     1318     1334      +16     
==========================================
- Hits        11019    10949      -70     
- Misses       1478     2235     +757     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.