[BT-128] Migrate forwardTo Routes - 2FA Flow by collectioneur · Pull Request #89608 · Expensify/App

collectioneur · 2026-05-05T14:46:19Z

Explanation of Change

Migrate 2FA routes (SETTINGS_2FA_ROOT, SETTINGS_2FA_VERIFY, SETTINGS_2FA_SUCCESS, SETTINGS_2FA_VERIFY_ACCOUNT) and the contact-method verify-account route from static backTo/forwardTo query params to the dynamic route system. Introduces useTwoFactorAuthRoute hook for resolving the correct 2FA entry point and useDynamicForwardPath hook for forward navigation after dynamic pages. Splits the old TwoFactorAuthPage into dedicated dynamic pages, extracts SuccessPageBase, and updates all consumers.

Fixed Issues

$ #83360

Tests

Verify that no errors appear in the JS console

Test 1

Navigate to Settings > Security
Tap Two-factor authentication
If the account is not validated, verify you are redirected to the /verify-account page, and after validating you proceed to the /two-factor-auth page
If the account is validated, verify the /two-factor-auth page loads, copy the recovery codes, proceed to the verify step, enter a valid code, and verify the success page appears
On the success page, tap Confirm and verify you are returned to the Security settings page

Test 2

Navigate to Settings > Profile > Contact methods
Tap New contact method while the account is not validated
Verify you are redirected to the /verify-account page (URL uses the dynamic route pattern, e.g. settings/profile/contact-methods/verify-account)
After validating, verify you are forwarded to the new contact method magic code confirmation page

Test 3

Navigate to Workspaces > Workspace > Accounting for a workspace that requires Xero connection
Trigger the Xero connection flow that requires 2FA
Verify the 2FA setup flow starts correctly and upon completion the Xero setup link opens

Test 4

Have an account without 2FA.
Create a mock USD bank account.
Create a new workspace.
Go to Workflows → Payments → Add bank account.
Choose this USD account.
Then click "Secure your account".
Complete the 2FA setup flow.
On the success page, after enabling 2FA, verify that clicking 'Got it' takes you back to the bank account modal (where you were before clicking 'Secure your account').

Offline tests

N/A

QA Steps

Same as tests

Verify that no errors appear in the JS console

PR Author Checklist

Screenshots/Videos

Android: Native

Android: mWeb Chrome

iOS: Native

iOS: mWeb Safari

MacOS: Chrome / Safari

Test 1:

1_test.mov

Test 2:

2_test.mov

Test 3:

3_test.mov

Test 4:

Screen.Recording.2026-05-21.at.11.33.17.mov

codecov · 2026-05-13T12:38:27Z

Codecov Report

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

Files with missing lines	Coverage Δ
src/ROUTES.ts	`18.87% <ø> (+1.34%)`	⬆️
src/SCREENS.ts	`100.00% <ø> (ø)`
src/hooks/useTwoFactorAuthRoute.ts	`100.00% <100.00%> (ø)`
src/libs/Navigation/Navigation.ts	`51.55% <ø> (ø)`
src/libs/Navigation/linkingConfig/OldRoutes.ts	`100.00% <ø> (ø)`
...igation/linkingConfig/RELATIONS/SETTINGS_TO_RHP.ts	`100.00% <ø> (ø)`
src/libs/Navigation/linkingConfig/config.ts	`76.92% <ø> (ø)`
src/libs/PaymentUtils.ts	`81.03% <ø> (+0.50%)`	⬆️
...nkAccount/components/BankAccountValidationForm.tsx	`0.00% <ø> (ø)`
...rc/pages/RequireTwoFactorAuthenticationOverlay.tsx	`51.42% <100.00%> (+2.77%)`	⬆️
... and 21 more
... and 151 files with indirect coverage changes

jmusial · 2026-05-14T07:55:17Z

+    },
+    TWO_FACTOR_AUTH_VERIFY_ACCOUNT: {
+        path: 'two-factor-auth/verify-account',
+        entryScreens: ['*'],


Curious, why do you use entryScreens: ['*'] here while the top one has a list ?

We have a RequireTwoFactorAuthenticationOverlay modal component that can appear on top of any screen in the app. It triggers when the backend signals that the user is required to have 2FA (for example, if the user is made an admin of a workspace that already has Xero set up). Since the entire 2FA flow can overlay any screen, we have to specify all screens as entryScreens here

jmusial · 2026-05-14T08:59:20Z

-    [SCREENS.SETTINGS.DYNAMIC_VERIFY_ACCOUNT]: undefined;
+    [SCREENS.SETTINGS.DYNAMIC_VERIFY_ACCOUNT]: {
+        // eslint-disable-next-line no-restricted-syntax -- `backTo` usages in this file are legacy. Do not add new `backTo` params to screens. See contributingGuides/NAVIGATION.md
+        backTo?: Routes;


Do we have to add backTo here ?

Previously, verify-account was used in flows that didn't have a backTo parameter. In this batch, I added a case where the basePath for verify-account can actually have a backTo, so we are propagating backTo into verify-account. This ensures that the previous flow path isn't lost, even on a dynamic screen. Once all routes with backTo that served as a basePath for this case are migrated, this won't be needed anymore and can be removed 🙂

jmusial · 2026-05-14T09:59:13Z


-    let forwardPath = backPath;
-    if (backPath === ROUTES.SETTINGS_WALLET) {
+    if (forwardPath === ROUTES.SETTINGS_NEW_CONTACT_METHOD_CONFIRM_MAGIC_CODE.route) {


now that we have useDynamicForwardPath would be nice to move all the logic for calculating forwardPath there

I love the idea of consolidating, but it might be quite tricky to fit everything into useDynamicForwardPath. It was built more as a test for dynamic screens with forwardTo: if the screen follows the standard forward route, the function returns nothing; if it takes a non-standard route, it returns a specific path. We have some weird edge cases that would be hard to fit inside useDynamicForwardPath (like adding a backTo parameter to a route, or navigating to Xero after a goBack)

jmusial · 2026-05-14T10:00:12Z

+ * - entryScreen: The screen that the dynamic suffix is appended to (e.g. 'Settings_Wallet').
+ * - forwardRoute: The destination route to navigate forward to from the dynamic route page.
+ */
+const FORWARD_TO_MAPPINGS: Record<string, Record<string, Route>> = {


I could see this in ROUTES same as entryScreens. wdyt ?

Since forwardTo hasn't been heavily used so far (just in about 5 routes, plus a couple we'll add after the verify-account refactoring), adding it to ROUTES.ts might be a bit much right now. It feels a bit more like a local utility rather than a global one. I could instead extract it into a separate file to keep things tidy, but I'd love to avoid cluttering ROUTES.ts 🙂

Ok, let's maybe revisit this after couple routes w/ forward to are migrated

jmusial

LGTM 👍

melvin-bot · 2026-05-14T13:46:22Z

@huult 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]

collectioneur · 2026-05-19T12:41:57Z

@huult I noticed a few bugs while checking these two flows, but don't worry, I'll have them fixed by tomorrow.
Did you come across any other issues related to this migrated flow?

huult · 2026-05-20T02:23:06Z

@collectioneur I checked the other flows and they are working well.

collectioneur · 2026-05-20T11:02:16Z

Hey @huult, I’ve fixed all the bugs. I added one more test for the USD flow. For the non-USD flow, I couldn’t get through it manually (since, as far as I know, we don’t have a mock bank account for non-USD flows). So, I just navigated directly to the finish page link and tested it that way. Everything works perfectly 👍

Screen.Recording.2026-05-20.at.12.45.11.mov

huult · 2026-05-21T08:52:01Z

Screen.Recording.2026-05-21.at.15.46.26.mov

@collectioneur Before the migration, after completing the 2FA setup, the app would return to the bank account verification flow. After your migration, once 2FA setup is completed, it no longer returns to the bank account verification screen.

Could you check this? You can compare the behavior with staging to see what changed.

huult · 2026-05-21T09:00:05Z

Screen.Recording.2026-05-21.at.15.58.10.mov

On the BANK_ACCOUNT_NON_USD_SETUP_FINISH page, when I go back, it redirects to the Security page, which is incorrect.

In staging, it correctly goes back to the BANK_ACCOUNT_NON_USD_SETUP_FINISH flow instead. Could you check this issue?

collectioneur · 2026-05-21T09:27:33Z

On the BANK_ACCOUNT_NON_USD_SETUP_FINISH page, when I go back, it redirects to the Security page, which is incorrect.

In staging, it correctly goes back to the BANK_ACCOUNT_NON_USD_SETUP_FINISH flow instead. Could you check this issue?

It happens due to #89710, where fullscreen screens aren't updating when navigating to certain modals. As soon as that issue is resolved, this bug will also be fixed because we'll route to a static enabled page and the fullscreen will instantly update to settings/security. Previously on staging, the enabled page was part of the 2fa root page and had a backTo param. Now, after the refactoring, it is static and will route directly to settings/security

collectioneur · 2026-05-21T09:38:55Z

@collectioneur Before the migration, after completing the 2FA setup, the app would return to the bank account verification flow. After your migration, once 2FA setup is completed, it no longer returns to the bank account verification screen.

Could you check this? You can compare the behavior with staging to see what changed.

Screen.Recording.2026-05-21.at.11.33.17.mov

Resolved, thanks!

huult · 2026-05-21T09:40:15Z

Too quick, haha. I’ll re-check this PR in the next 4 hours

huult

LGTM.

github-actions · 2026-05-22T07:34:18Z

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

OSBotify · 2026-05-22T07:38:54Z

✋ 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 · 2026-05-22T07:39:41Z

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

Android 🤖	iOS 🍎
https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-android-Adhoc-49c5907-d1139c3-f2062af7eed3f05362d1e13c74b25042887e33d9/index.html	https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-ios-device-AdHoc-49c5907-d1139c3-6c49afbd1e8a9ed1fb01f1863829e2e328f4c726/index.html

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

👀 View the workflow run that generated this build 👀

OSBotify · 2026-05-22T22:43:40Z

🚀 Deployed to staging by https://github.com/mjasikowski in version: 9.3.80-0 🚀

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

Bundle Size Analysis (Sentry):

Android
iOS

MelvinBot · 2026-05-22T22:45:50Z

No help site changes are required for this PR.

This PR is a purely internal code refactoring — it migrates 2FA routes from static backTo/forwardTo query params to a dynamic route system, introduces new hooks (useTwoFactorAuthRoute, useDynamicForwardPath), and splits internal page components. None of these changes affect user-facing behavior, UI labels, navigation steps, or feature names.

The existing help article at docs/articles/new-expensify/settings/Two-Factor-Authentication.md remains accurate — the user-visible flow for enabling and using 2FA is unchanged.

OSBotify · 2026-05-25T22:35:25Z

🚀 Deployed to production by https://github.com/luacmartins in version: 9.3.81-2 🚀

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

parasharrajat · 2026-06-05T11:57:27Z

                                return setError(translate('twoFactorAuth.errorStepCodes'));
                            }
-                            Navigation.navigate(ROUTES.SETTINGS_2FA_VERIFY.getRoute(route.params?.backTo, route.params?.forwardTo));
+                            Navigation.navigate(createDynamicRoute(DYNAMIC_ROUTES.TWO_FACTOR_AUTH_VERIFY.path, backPath), {forceReplace: true});


Why are we using forceReplace here @collectioneur @huult ?

@parasharrajat What issue does this cause? We need forceReplace to fix an issue where users can't navigate back

Do you have steps for that issue or any comments? We are solving this #92544

melvin-bot Bot assigned collectioneur May 5, 2026

squash commits

edca12f

collectioneur force-pushed the collectioneur/dynamic-routes-remove-forward-to branch from ced339c to edca12f Compare May 8, 2026 14:42

This was referenced May 11, 2026

[HOLD] Refactor payment util to use dynamic verify account #90171

Open

[Due for payment 2026-07-02] [Due for payment 2026-06-29] Providing magic code during verification navigates back instead of continuing forward in flow #72980

Open

collectioneur added 10 commits May 12, 2026 12:59

cleanup

9d230cc

rename pages

97f6610

cleanup

3fdc6d6

add static success page

a5040fc

small navi fix in 2fa

f25e215

split 2fa between two pages (static and dynamic)

276419d

update useDynamicForwardPath

e087530

refactor static and dynamic success page

57d8727

add tests

7d7784b

Merge branch 'main' into collectioneur/dynamic-routes-remove-forward-to

0dae1c8

collectioneur changed the title ~~migrate forwardTo~~ [BT-128] Migrate forwardTo Routes - 2FA Flow May 13, 2026

fix eslint and tests

a73d0ae

fix prettier

25b6efa

jmusial reviewed May 14, 2026

View reviewed changes

collectioneur added 2 commits May 14, 2026 13:26

cleanup

320ea9d

fix lint

357c501

jmusial approved these changes May 14, 2026

View reviewed changes

collectioneur marked this pull request as ready for review May 14, 2026 13:46

collectioneur requested review from a team as code owners May 14, 2026 13:46

melvin-bot Bot requested review from huult and joekaufmanexpensify and removed request for a team May 14, 2026 13:46

collectioneur mentioned this pull request May 19, 2026

BT - Migrate Transaction Duplicates #89572

Closed

52 tasks

fix USD bank account 2fa flow and small cleanup

8ead1d2

Merge branch 'main' into collectioneur/dynamic-routes-remove-forward-to

766cd52

fix going back to reimbursement account page

89e6fce

huult approved these changes May 22, 2026

View reviewed changes

melvin-bot Bot requested a review from mjasikowski May 22, 2026 02:58

mjasikowski approved these changes May 22, 2026

View reviewed changes

mjasikowski merged commit 49c5907 into Expensify:main May 22, 2026
41 checks passed

OSBotify mentioned this pull request May 22, 2026

Deploy Checklist: New Expensify 2026-05-22 #91472

Closed

71 tasks

melvin-bot Bot mentioned this pull request May 25, 2026

[BT-128] Migrate forwardTo Routes - 2FA Flow #83360

Closed

5 tasks

This was referenced May 28, 2026

[$250] Required 2FA setup screen is unresponsive, blocking new-domain login and account merge #91985

Open

[Due for payment 2026-06-16] [$250] Web -2FA - After clicking Got it, the Two-factor authentication RHP is closed #92544

Closed

parasharrajat reviewed Jun 5, 2026

View reviewed changes

parasharrajat mentioned this pull request Jun 5, 2026

[$250] Chrome - 2FA - Clicking Download codes, closes the 2FA page #92564

Open

7 tasks

aimane-chnaif mentioned this pull request Jun 23, 2026

Refactor useSelectionMode report actions to use dynamic verify account #93715

Merged

49 tasks

MobileMage mentioned this pull request Jun 27, 2026

Use PUSH instead of REPLACE for 2FA Download codes navigation on web #94761

Open

44 tasks

Uh oh!

Conversation

collectioneur commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation of Change

Fixed Issues

Tests

Offline tests

QA Steps

PR Author Checklist

Screenshots/Videos

Uh oh!

codecov Bot commented May 13, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

collectioneur May 14, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmusial left a comment

Choose a reason for hiding this comment

Uh oh!

melvin-bot Bot commented May 14, 2026

Uh oh!

collectioneur commented May 19, 2026

Uh oh!

huult commented May 20, 2026

Uh oh!

collectioneur commented May 20, 2026

Uh oh!

huult commented May 21, 2026

Uh oh!

huult commented May 21, 2026

Uh oh!

collectioneur commented May 21, 2026

Uh oh!

collectioneur commented May 21, 2026

Uh oh!

huult commented May 21, 2026

Uh oh!

huult left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented May 22, 2026

Uh oh!

OSBotify commented May 22, 2026

Uh oh!

github-actions Bot commented May 22, 2026

Uh oh!

OSBotify commented May 22, 2026

Uh oh!

MelvinBot commented May 22, 2026

Uh oh!

OSBotify commented May 25, 2026

Uh oh!

Choose a reason for hiding this comment

collectioneur commented May 5, 2026 •

edited

Loading

codecov Bot commented May 13, 2026 •

edited by github-actions Bot

Loading

collectioneur May 14, 2026 •

edited

Loading