Allow required 2FA setup through the migrated-user welcome modal

[neerajbachani]

Enable was blocked because the welcome-modal guard drops every navigation except Back and Dismiss. Let the same required-2FA exception used by onboarding through, and keep every other navigation blocked.

Explanation of Change

MigratedUserWelcomeModalGuard blocks every navigation except Back and Dismiss while the migrated-user welcome modal is the top route. Enable calls Navigation.navigate into the 2FA setup screen, so the guard dropped that action and the URL flipped back to /migrated-user-welcome. Sign out was unaffected because it does not take that navigation path.

This change allows that navigation only when required 2FA setup is active and the action targets a 2FA setup screen, using the same shouldShowRequire2FAPage / isForced2FAOnboardingSetup exception already used by OnboardingGuard. The welcome modal stays on the stack. Tab switches and every other navigation stay blocked until the user dismisses the modal.

Fixed Issues

$ #102577
PROPOSAL:

Tests

1. Sign in on web with a normal account (not a copilot or Supportal session), reload, and land on Home.
2. In the dev console, mark the account as a migrated user who has not dismissed the welcome modal:

   await Onyx.merge("nvp_dismissedProductTraining", { migratedUserWelcomeModal: null });
   await Onyx.merge("nvp_tryNewDot", { nudgeMigration: { timestamp: new Date().toISOString(), cohort: "local-repro" } });
   

3. Verify the migrated-user welcome modal opens and the URL ends in /migrated-user-welcome. Do not click Got it.
4. Raise the required 2FA screen over that modal:

   await Onyx.merge("account", { needsTwoFactorAuthSetup: true, requiresTwoFactorAuth: false, twoFactorAuthSetupInProgress: false });
   

5. Click Enable.
6. Verify the 2FA setup page opens, and the URL does not flip back to /migrated-user-welcome.
7. Click Sign out and verify sign-out still works.
8. Repeat steps 2-4, then try to switch tabs instead of clicking Enable. Verify that navigation stays blocked while the welcome modal is the top route.
9. Click Got it on the welcome modal and verify normal navigation works again.

• Verify that no errors appear in the JS console

Offline tests

1. With the welcome modal and the required 2FA screen already showing, turn the network off.
2. Click Enable.
3. Verify the 2FA setup page still opens. This guard decision is local and does not wait on the network.

QA Steps

Use an account migrated from Expensify Classic to New Expensify that has never dismissed Welcome to New Expensify. The Classic domain must require 2FA, and this user must not have finished 2FA setup. Sign in as that user directly, not through Copilot or Supportal. A user who already enabled 2FA in Classic will not see this screen.

1. Sign in on web.
2. Verify the screen shows Two-factor authentication required, with Enable and Sign out, and the URL ends in /migrated-user-welcome. The welcome modal is underneath this screen, so Let's go! is not visible.
3. Click Sign out and verify sign-out still works.
4. Sign in again and confirm the same screen and the same /migrated-user-welcome URL.
5. Click Enable.
6. Verify the 2FA setup page opens and the URL moves to the setup flow. It must not bounce back to /migrated-user-welcome.
7. Finish 2FA setup and close the setup screen.
8. Verify Welcome to New Expensify is now visible. Click Let's go! and verify the modal closes and the app can be used normally.

• Verify that no errors appear in the JS console

PR Author Checklist

• I linked the correct issue in the ### Fixed Issues section above
• I wrote clear testing steps that cover the changes made in this PR
  • I added steps for local testing in the Tests section
  • I added steps for the expected offline behavior in the Offline steps section
  • I added steps for Staging and/or Production testing in the QA steps section
  • I added steps to cover failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
  • I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
  • I tested this PR with a High Traffic account against the staging or production API to ensure there are no regressions (e.g. long loading states that impact usability).
• I included screenshots or videos for tests on all platforms
• I ran the tests on all platforms & verified they passed on:
  • Android: Native
  • Android: mWeb Chrome
  • iOS: Native
  • iOS: mWeb Safari
  • MacOS: Chrome / Safari
• I verified there are no console errors (if there's a console error not related to the PR, report it or open an issue for it to be fixed)
• I followed proper code patterns (see Reviewing the code)
  • I verified that comments were added to code that is not self explanatory
  • I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
  • I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
• If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
• I followed the guidelines as stated in the Review Guidelines
• I tested other components that can be impacted by my changes (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar are working as expected)
• If a new CSS style is added I verified that:
  • A similar style doesn't already exist
  • The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG))
• If new assets were added or existing ones were modified, I verified that:
  • The assets are optimized and compressed (for SVG files, run npm run compress-svg)
  • The assets load correctly across all supported platforms.
• If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
• If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
• If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
• If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
• If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
  • I verified that all the inputs inside a form are aligned with each other.
  • I added Design label and/or tagged @Expensify/design so the design team can review the changes.
• If the PR adds or modifies the UI:
  • I asked an AI agent to review the changes for accessibility issues and addressed its findings.
  • I tested with a screen reader (VoiceOver on macOS) and verified all new/changed elements are reachable with a logical focus order.
  • I verified all new/changed elements have meaningful accessible names and roles.
  • I verified state changes are announced (e.g. checked/unchecked, expanded/collapsed, selected).
• I added unit tests for any new feature or bug fix in this PR to help automatically prevent regressions in this user flow.
• If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.

Screenshots/Videos

Android: Native

Before	After
Screen.Recording.2026-10-04.at.9.38.05.PM.mov	Screen.Recording.2026-10-03.at.10.40.44.PM.mov

Android: mWeb Chrome

Before	After
WhatsApp.Video.2026-10-04.at.21.48.14.mp4	WhatsApp.Video.2026-10-03.at.23.15.14.mp4

iOS: Native

Before	After
Screen.Recording.2026-10-04.at.9.34.31.PM.online-video-cutter.com.mp4	Screen.Recording.2026-10-03.at.10.26.24.PM.mov

iOS: mWeb Safari

Before	After
Screen.Recording.2026-10-04.at.9.35.22.PM.mov	Screen.Recording.2026-10-03.at.10.30.08.PM.mov

MacOS: Chrome / Safari

Before	After
Screen.Recording.2026-10-04.at.9.18.44.PM.mov	Screen.Recording.2026-10-03.at.10.09.30.PM.mov

[melvin-bot]

@thelullabyy Please copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button]

[github-actions]

This PR adds a new Onyx.connectWithoutView call, so I've requested a review from the Onyx performance reviewers (@tgolen, @mountiny, @luacmartins, @chuckdries) — a review from any one of them is enough. Please add a link in your PR description to the Slack discussion where the @frontend-performance team approved using connectWithoutView here.

[codecov]

Codecov Report

✅ Changes either increased or maintained existing code coverage, great job!

Files with missing lines	Coverage Δ
...Navigation/guards/MigratedUserWelcomeModalGuard.ts	100.00% <100.00%> (ø)
... and 14 files with indirect coverage changes

[tgolen]

Thanks!

[neerajbachani]

working on checklist and video recordings

[thelullabyy]

@neerajbachani Let me know when the PR is ready for review, thanks

[thelullabyy]

@neerajbachani How is it?

[github-actions]

This PR adds a new Onyx.connectWithoutView call, so I've requested a review from the Onyx performance reviewers (@tgolen, @mountiny, @luacmartins, @chuckdries) — a review from any one of them is enough. Please add a link in your PR description to the Slack discussion where the @frontend-performance team approved using connectWithoutView here.

[neerajbachani]

@thelullabyy PR is ready for review, thanks!!

[thelullabyy]

Reviewer Checklist

• I have verified the author checklist is complete (all boxes are checked off).
• I verified the correct issue is linked in the ### Fixed Issues section above
• I verified testing steps are clear and they cover the changes made in this PR
  • I verified the steps for local testing are in the Tests section
  • I verified the steps for Staging and/or Production testing are in the QA steps section
  • I verified the steps cover any possible failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
  • I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
• I checked that screenshots or videos are included for tests on all platforms
• I included screenshots or videos for tests on all platforms
• I verified that the composer does not automatically focus or open the keyboard on mobile unless explicitly intended. This includes checking that returning the app from the background does not unexpectedly open the keyboard.
• I verified tests pass on all platforms & I tested again on:
  • Android: HybridApp
  • Android: mWeb Chrome
  • iOS: HybridApp
  • iOS: mWeb Safari
  • MacOS: Chrome / Safari
• If there are any errors in the console that are unrelated to this PR, I either fixed them (preferred) or linked to where I reported them in Slack
• I verified proper code patterns were followed (see Reviewing the code)
  • I verified that comments were added to code that is not self explanatory
  • I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
  • I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
• If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
• I verified that this PR follows the guidelines as stated in the Review Guidelines
• I verified other components that can be impacted by these changes have been tested, and I retested again (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar have been tested & I retested again)
• If a new component is created I verified that:
  • A similar component doesn't exist in the codebase
  • All props are defined accurately
  • The component has a clear name that is non-ambiguous and the purpose of the component can be inferred from the name alone
  • The only data being stored in the state is data necessary for rendering and nothing else
  • The component has the minimum amount of code necessary for its purpose, and it is broken down into smaller components in order to separate concerns and functions
• If a new CSS style is added I verified that:
  • A similar style doesn't already exist
  • The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG)
• If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
• If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
• If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
• If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
• If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
  • I verified that all the inputs inside a form are aligned with each other.
  • I added Design label and/or tagged @Expensify/design so the design team can review the changes.
• If the PR adds or modifies the UI:
  • I asked an AI agent to review the changes for accessibility issues and addressed its findings.
  • I tested with a screen reader (VoiceOver on macOS) and verified all new/changed elements are reachable with a logical focus order.
  • I verified all new/changed elements have meaningful accessible names and roles.
  • I verified state changes are announced (e.g. checked/unchecked, expanded/collapsed, selected).
• For any bug fix or new feature in this PR, I verified that sufficient unit tests are included to prevent regressions in this flow.
• If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.
• I have checked off every checkbox in the PR reviewer checklist, including those that don't apply to this PR.

Screenshots/Videos

Android: HybridApp

Android: mWeb Chrome

iOS: HybridApp

iOS: mWeb Safari

MacOS: Chrome / Safari

Screen.Recording.2026-10-08.at.00.39.10.mov

[thelullabyy]

@MelvinBot Review this PR

[MelvinBot]

PR Review

The fix looks correct, and it is scoped to the bug. I'd request one change before merge: move the copied 2FA helpers into one shared place.

Correctness: no issues found.

• The exception only applies when required 2FA is active and the action's deepest screen is a 2FA setup screen. Tab switches and other navigation still get blocked.
• After the 2FA RHP opens, the top route is no longer MIGRATED_USER_MODAL_NAVIGATOR, so later steps inside the 2FA flow (verify, success) are not affected by this guard. That's why the isCurrentlyOnTwoFactorSetupRoute branch from OnboardingGuard isn't needed here.
• On success from Settings > Security, DynamicSuccessPage keeps the RHP open on the Enabled page. When the user closes it, the welcome modal is back on top, which matches QA step 8.

Requested change: duplicated code (CONSISTENCY-3)

MigratedUserWelcomeModalGuard.ts:111-150 is a line-for-line copy of OnboardingGuard.ts:125-146. That includes isRequiredTwoFactorSetupExceptionActive, isObjectPayload, getActionPayloadScreenName, and the type alias. It also adds second ACCOUNT and NVP_ONBOARDING subscriptions. If the required-2FA rule changes later, both guards must change together, or they will drift.

To fix this, move these helpers and their two Onyx subscriptions into one shared module (for example, src/libs/Navigation/guards/requiredTwoFactorSetup.ts). Import that module from both guards.

Nit: test mock

The mock in MigratedUserWelcomeModalGuard.test.ts:28-62 copies SET_UP_2FA_SCREENS and getDeepestFocusedScreen from Navigation.ts. If the shared module above owns or re-exports these helpers, the test can mock less and use the real logic. That keeps the test from passing against a stale screen list.

PR body: the PROPOSAL: line in Fixed Issues is empty.

Verification notes

• CI: unit tests, ESLint, and perf tests pass. Only the PR checklist jobs fail.
• I couldn't run a live web test. The test steps need Onyx.merge from the dev console, and the web test tool doesn't support running page scripts. Rely on the author's videos and the new unit tests for runtime coverage.

---

view run · view recording

[thelullabyy]

@neerajbachani Could you please update the PR description to use latest template? Thanks

[neerajbachani]

@neerajbachani Could you please update the PR description to use latest template? Thanks

@thelullabyy Done

[OSBotify]

✋ This PR was not deployed to staging yet because QA is ongoing. It will be automatically deployed to staging after the next production release.

[github-actions]

🚧 luacmartins has triggered a test Expensify/App build. You can view the workflow run here.

[github-actions]

🧪🧪 Use the links below to test this adhoc build on Android, iOS, and Web. Happy testing! 🧪🧪
Built from App PR #102629.

Android 🤖	iOS 🍎
https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-android-Adhoc-ff03a5d-a57d040-245dd6fcadf4477f52977b9c9c7da4be5d500f51/index.html	https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-ios-device-AdHoc-ff03a5d-a57d040-ccdc075a04f7221062c0b69eb154b58fcff94ca1/index.html

Web 🕸️
https://102629.pr-testing.expensify.com

---

👀 View the workflow run that generated this build 👀

[OSBotify]

🚀 Deployed to staging by https://github.com/luacmartins in version: 9.5.6-0 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

[MelvinBot]

No help site update needed. This bug fix makes Enable on the required 2FA screen open the setup flow, as users would expect. It doesn't make any sentence in Two-Factor Authentication or other articles wrong.

---

view run

[OSBotify]

🚀 Deployed to production by https://github.com/puneetlath in version: 9.5.6-6 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

Bundle Size Analysis (Sentry):

• Android
• iOS