Skip to content

Required 2FA setup screen is unresponsive, blocking new-domain login and account merge - #94486

Merged
iwiznia merged 30 commits into
Expensify:mainfrom
neerajbachani:91985-fix-required-2fa-overlay-onboarding
Aug 18, 2026
Merged

iwiznia merged 30 commits into
Expensify:mainfrom
neerajbachani:91985-fix-required-2fa-overlay-onboarding

Conversation

@neerajbachani

@neerajbachani neerajbachani commented Jun 24, 2026 •

Copy link
Copy Markdown
Contributor

Explanation of Change

Fixes the required-2FA overlay blocking domain-migration / incomplete-onboarding users from completing 2FA setup.

When twoFactorAuthSetupInProgress is true during incomplete guided setup, the overlay CTA could not reliably open the 2FA wizard: the dynamic route was anchored to the onboarding screen behind the overlay, requiresTwoFactorAuth: true routed to the enabled page (which does not dismiss the overlay), the wizard bounced back to the enabled page, OnboardingGuard and useOnboardingFlow fought the 2FA modal, and submitting the authenticator code called openApp() before the success page could restart onboarding.

This PR:

  • Anchors the overlay CTA to ROUTES.SETTINGS_SECURITY with forceSetup: true
  • Pauses onboarding auto-redirect while required 2FA is active
  • Allows required 2FA navigation through OnboardingGuard
  • Prevents wizard bounce and completes onboarding handoff from DynamicSuccessPage
  • Skips openApp() on validateTwoFactorAuth during forced onboarding 2FA setup so the verify → success → onboarding path works

Fixed Issues

$ #91985
PROPOSAL: #91985 (comment)

Tests

  1. Log in to dev.new.expensify.com:8082 with a new account (incomplete onboarding)
  2. Open DevTools console and run:
Onyx.merge("nvp_onboarding", { hasCompletedGuidedSetupFlow: false });
Onyx.merge("account", {
  needsTwoFactorAuthSetup: true,
  requiresTwoFactorAuth: false,
  twoFactorAuthSetupInProgress: false,
  isFromPublicDomain: true,
});
  1. Confirm the "Two-factor authentication required" overlay appears
  2. Click Enable two-factor authentication and confirm the overlay dismisses and the 2FA setup wizard opens
  3. Complete the wizard (copy/download recovery codes → verify authenticator → submit 6-digit code if prompted)
  4. Click Got it on the success screen
  5. Confirm you land on Home with the onboarding modal — not stuck on the require-2FA overlay or a leftover 2FA modal
  6. Confirm no errors in the JS console during the flow
  • Verify that no errors appear in the JS console

Offline tests

Same as Tests — this flow is routing/UI state driven and does not require additional offline-specific steps beyond verifying no console errors while offline after setup completes.

QA Steps

  1. Log in to a new account on staging with incomplete guided setup
  2. If domain-enforced 2FA state is not naturally available, use the same Onyx fixture from Tests (step 2) in DevTools
  3. Tap Enable two-factor authentication on the required-2FA overlay
  4. Complete the full 2FA setup wizard
  5. Confirm after setup the user is returned to complete onboarding (per product: finish 2FA → complete onboarding)
  6. Verify normal Settings > Security 2FA enable/disable still works on a regular account (no regression)
  7. Confirm no errors in the JS console
  • 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 any callback methods that were added or modified are named for what the method does and never what callback they handle (i.e. toggleReport and not onIconClick)
    • 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 any new file was added I verified that:
    • The file has a description of what it does and/or why is needed at the top of the file if the code is not self explanatory
  • 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.
  • 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
android-2fa.online-video-cutter.com.mp4
Android: mWeb Chrome
androi-web-2fa.online-video-cutter.com.mp4
iOS: Native
Simulator.Screen.Recording.-.iPhone.17.Pro.-.2026-07-27.at.00.online-video-cutter.com.1.mp4
iOS: mWeb Safari
Simulator.Screen.Recording.-.iPhone.17.Pro.-.2026-07-27.at.00.online-video-cutter.com.mp4
MacOS: Chrome / Safari
Screen.Recording.2026-07-06.at.2.06.43.PM.online-video-cutter.com.1.mp4

Unblock the Enable 2FA button for domain-migration users who must finish
2FA before guided setup by anchoring setup routes to Settings/Security,
forcing the wizard path, pausing competing onboarding redirects, and
cleanly handing off to onboarding after success.
Skip openApp() during validateTwoFactorAuth when setup runs during
incomplete onboarding, so DynamicSuccessPage can complete the
onboarding handoff after the user submits their authenticator code.
@neerajbachani
neerajbachani requested review from a team as code owners June 24, 2026 17:06
@melvin-bot
melvin-bot Bot requested review from cretadn22 and joekaufmanexpensify and removed request for a team June 24, 2026 17:06
@melvin-bot

melvin-bot Bot commented Jun 24, 2026

Copy link
Copy Markdown

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

clearTwoFactorAuthData(true);
Navigation.revealRouteBeforeDismissingModal(ROUTES.HOME, {
afterTransition: () => {
startOnboardingFlow({

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❌ CONSISTENCY-3 (docs)

This startOnboardingFlow({...}) invocation builds the exact same 8-field params object (onboardingValuesParam, isUserFromPublicDomain, hasAccessiblePolicies, currentOnboardingCompanySize, currentOnboardingPurposeSelected, onboardingInitialPath, onboardingValues, isAccountValidated) from the same account/onboarding Onyx values that already exists in src/hooks/useOnboardingFlow.ts (lines 96-105). Duplicating this params-construction logic means any future change to how onboarding is started (new field, changed source value) must be made in two places, raising bug risk.

Extract the params construction into a shared helper (e.g. in @userActions/Welcome/OnboardingFlow) that derives the startOnboardingFlow params from account + onboarding values, and call it from both sites:

// OnboardingFlow.ts
function buildOnboardingFlowParams(account, onboardingValues, onboardingCompanySize, onboardingPurposeSelected, onboardingInitialPath) {
    return {
        onboardingValuesParam: onboardingValues ?? undefined,
        isUserFromPublicDomain: !!account?.isFromPublicDomain,
        hasAccessiblePolicies: !!account?.hasAccessibleDomainPolicies,
        currentOnboardingCompanySize: onboardingCompanySize,
        currentOnboardingPurposeSelected: onboardingPurposeSelected,
        onboardingInitialPath,
        onboardingValues,
        isAccountValidated: !!account?.validated,
    };
}

// Both call sites
startOnboardingFlow(buildOnboardingFlowParams(account, onboardingValues, onboardingCompanySize, onboardingPurposeSelected, onboardingInitialPath));

Reviewed at: 121dfb7 | Please rate this suggestion with 👍 or 👎 to help us improve! Reactions are used to monitor reviewer efficiency.

@codecov

codecov Bot commented Jun 24, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Looks like you've decreased code coverage for some files. Please write tests to increase, or at least maintain, the existing level of code coverage. See our documentation here for how to interpret this table.

Files with missing lines Coverage Δ
src/hooks/useShouldShowRequire2FAPage.ts 100.00% <100.00%> (ø)
src/hooks/useTwoFactorAuthRoute.ts 100.00% <100.00%> (ø)
src/libs/AccountUtils.ts 78.94% <100.00%> (+9.71%) ⬆️
src/libs/Navigation/Navigation.ts 49.01% <ø> (+1.18%) ⬆️
...es/OnboardingWorkEmail/BaseOnboardingWorkEmail.tsx 85.00% <100.00%> (-0.37%) ⬇️
...Security/TwoFactorAuth/ToggleTwoFactorAuthForm.tsx 93.33% <100.00%> (+1.02%) ⬆️
src/hooks/useOnboardingFlow.ts 81.13% <50.00%> (-0.69%) ⬇️
src/libs/Navigation/guards/OnboardingGuard.ts 98.98% <93.33%> (-1.02%) ⬇️
src/libs/actions/Session/index.ts 59.17% <77.77%> (+5.82%) ⬆️
...tings/Security/TwoFactorAuth/DynamicVerifyPage.tsx 0.00% <0.00%> (ø)
... and 4 more
... and 586 files with indirect coverage changes

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 121dfb76f8

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread src/libs/AccountUtils.ts Outdated
* (domain-migration / required-2FA-before-onboarding scenario).
*/
function isForced2FAOnboardingSetup(account: OnyxEntry<Account>, hasCompletedGuidedSetupFlow: boolean): boolean {
return !!account?.twoFactorAuthSetupInProgress && !hasCompletedGuidedSetupFlow;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Gate forced 2FA detection on required setup state

When a user can access the app without completing guided setup (for example invited/group-member accounts are explicitly skipped by useOnboardingFlow) and then enables 2FA from Settings, setCodesAreCopied() sets twoFactorAuthSetupInProgress to true. This helper will then classify that normal Settings flow as the forced domain-setup flow, causing ToggleTwoFactorAuthForm to skip the usual openApp/clear path and DynamicSuccessPage to send the user into onboarding instead of the enabled 2FA page. Please include the required-2FA condition in this predicate so ordinary unfinished-onboarding accounts are not redirected incorrectly.

Useful? React with 👍 / 👎.

Coerce hasCompletedGuidedSetupFlow to boolean in ToggleTwoFactorAuthForm
and require requiresTwoFactorAuth in isForced2FAOnboardingSetup so voluntary
Settings 2FA setup does not incorrectly trigger the onboarding handoff.

Co-authored-by: Cursor <cursoragent@cursor.com>

@joekaufmanexpensify joekaufmanexpensify left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good for product

Comment thread src/hooks/useOnboardingFlow.ts Outdated
// corrupts its dynamic base route, and flashes the overlay. Once 2FA finishes, the success page clears
// twoFactorAuthSetupInProgress and explicitly starts onboarding.
if (AccountUtils.shouldShowRequire2FAPage(account, !!isOnboardingCompleted)) {
Log.info('[Require2FA] Pausing onboarding redirect during required 2FA setup', false, {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can leave out the log to keep things cleaner

Comment thread src/hooks/useTwoFactorAuthRoute.ts Outdated
if (is2FAEnabled) {
const getTwoFactorAuthRoute = (backTo?: Route, options?: TwoFactorAuthRouteOptions): Route => {
if (is2FAEnabled && !options?.forceSetup) {
Log.info('[Require2FA] Resolved route to SETTINGS_2FA_ENABLED', false, {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should get rid of all these new logs

@cretadn22

Copy link
Copy Markdown
Contributor

Bug 1: When logging in, the onboarding flow initially starts with the "What's your work mail" screen. However, after completing the 2FA setup, the flow incorrectly skips ahead and displays the purpose selection screen.

Bug 2: Upon completing the 2FA flow, the 2FA modal briefly flashes/appears for a moment before the onboarding flow is displayed.

Screen.Recording.2026-06-30.at.22.10.15.mov

@cretadn22

Copy link
Copy Markdown
Contributor

@neerajbachani Please upload testing evidence for all platforms

@neerajbachani

Copy link
Copy Markdown
Contributor Author

@cretadn22 Thanks for the review - addressed the bugs and cleaned up the branch.

Bug 1 (resume wrong step → purpose instead of work-email)

Root cause: onboardingLastVisitedPath was often empty when the required-2FA overlay appeared, and validated users were auto-navigated off work-email during incomplete guided setup. getOnboardingInitialPath also skips work-email for validated accounts.

Verified locally: work-email → required 2FA overlay → complete setup → resumes work-email (recording attached).

Bug 2 (2FA modal flash before onboarding)

Addressed by the existing handoff flow: pausing useOnboardingFlow during required 2FA, then DynamicSuccessPage clears 2FA state and explicitly restarts onboarding via revealRouteBeforeDismissingModal → startOnboardingFlow. No flash observed in re-test.

Testing evidence

Screen.Recording.2026-07-06.at.2.06.43.PM.online-video-cutter.com.1.mp4

Merge / commit history

Merged latest main and resolved conflicts in the 2FA/onboarding files. Extra commits after that were only to remove accidental local WIP/debug files that got swept into the merge commit the PR diff is now 16 files / ~400 lines. should i force push to remove unnecessary commit or its just oka to proceed?

Drop debug Log.info calls requested in review and update WorkEmailOnboarding
tests for Fix C validated auto-nav guard during incomplete guided setup.
@neerajbachani

Copy link
Copy Markdown
Contributor Author

@codex review

Empty commit to kick off a fresh CI run after self-hosted runner
communication failures on the previous workflow run.
Empty commit to rerun workflows after self-hosted runner communication
errors and cancelled Jest jobs on the previous CI run.
@neerajbachani
neerajbachani requested a review from iwiznia August 14, 2026 07:04
@neerajbachani

Copy link
Copy Markdown
Contributor Author

@iwiznia gentle bump, thanks

@iwiznia
iwiznia merged commit 917d120 into Expensify:main Aug 18, 2026
35 of 36 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

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

@OSBotify OSBotify mentioned this pull request Aug 18, 2026
66 tasks done
@OSBotify

Copy link
Copy Markdown
Contributor

🚀 Deployed to staging by https://github.com/iwiznia in version: 9.4.56-0 🚀

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

@MelvinBot

Copy link
Copy Markdown
Contributor

No help site changes required 📝

I reviewed the changes in this PR and no updates to the help site (App/docs/articles) are needed, so I did not create a draft docs PR.

Why: This PR is a bug fix that restores the intended behavior of the required‑2FA overlay for onboarding / domain‑migration users. It's entirely internal routing and navigation‑guard logic — no new user‑facing feature, setting, tab, button, or copy was introduced. Every change is in hooks, navigation guards, session/onboarding actions, and their tests; there are no new translation strings or labels.

The existing article Two-Factor Authentication (2FA) already documents enabling 2FA and Domain Admins requiring it, and it remains accurate after this change — the documented steps (enable 2FA, save recovery codes, verify with an authenticator code) are unchanged. This PR just makes the "Two-factor authentication required" overlay's Enable two-factor authentication CTA reliably open the wizard again, which is the behavior the docs already assume.

What changed in this PR
  • Anchors the overlay CTA to Settings > Security with forceSetup: true
  • Pauses onboarding auto-redirect while required 2FA is active
  • Allows required‑2FA navigation through OnboardingGuard
  • Prevents the wizard bounce and completes the onboarding handoff from the success page
  • Skips openApp() on validateTwoFactorAuth during forced onboarding 2FA setup

All are internal state/routing fixes with no accompanying UI copy or feature additions.


@neerajbachani, since no user-facing behavior or copy changed, there's no help site PR to review here. If you believe a specific article should still be updated (e.g. to document the domain‑required 2FA onboarding flow in more detail), let me know which behavior you'd like documented and I'll draft it.

@mitarachim

Copy link
Copy Markdown

Deploy Blocker #98938 was identified to be related to this PR.

@OSBotify

Copy link
Copy Markdown
Contributor

🚀 Deployed to production by https://github.com/Beamanator in version: 9.4.56-3 🚀

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

Bundle Size Analysis (Sentry):

@neerajbachani

Copy link
Copy Markdown
Contributor Author

Yep, this looks much better to me. I feel like "Enable 2FA" would work well. Let's see what design thinks on the second PR too 👍

@joekaufmanexpensify Following up on our agreement to split the Sign out escape hatch into a follow-up PR (#94486 thread): the core #91985 fix is merged and the deploy blockers are resolved, so I’m ready to pick this back up.

Could you please open a separate GitHub issue for the require-2FA overlay Sign out button and assign it to me? I already have the implementation prototyped locally (horizontal layout with Enable 2FA + Sign out, confirm modal same as Settings), once the issue is up I’ll open a small PR and loop in Design on placement if needed.

@joekaufmanexpensify

Copy link
Copy Markdown
Contributor

Can we just use the existing issue? I would say it was intended to be fixed there. We just de-scoped it to get this PR done faster.

@abzokhattab

Copy link
Copy Markdown
Contributor

This PR narrowed the early return in BaseOnboardingWorkEmail's navigation effect from:

if (account?.validated) {
    navigateToNextStep(account?.isFromPublicDomain);
    return;
}

to:

if (account?.validated && hasCompletedGuidedSetupFlow) {
    navigateToNextStep(account?.isFromPublicDomain);
    return;
}

This allowed the effect to fall through to the navigation at line ~108-111, which was the only navigate call in the effect that omitted {forceReplace: true} (the three sibling calls at L85, L89, L92 all used it). Without forceReplace, the work email screen stayed mounted underneath. When the post-merge OpenApp updated account, the effect re-ran and pushed the validation screen again, creating a duplicate "Join a workspace" screen.

Fixed in #101393.


const handleOnPress = () => {
snapshotOnboardingResumePathIfNeeded();
Navigation.navigate(getTwoFactorAuthRoute(ROUTES.SETTINGS_SECURITY, {forceSetup: true}));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Coming from #101848.

This line gave the require-2FA overlay the same ROUTES.SETTINGS_SECURITY base as voluntary setup from Settings > Security.

The onboarding handoff in DynamicSuccessPage only runs for users who haven't finished onboarding. An invited admin who has finished onboarding went down the voluntary branch from #92637 instead.

After Got it, they stayed on Account > Security rather than landing on Home. Before this PR, setup ran on top of the active route, so those admins went back to Home.

Fixed in #102482.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.