Feature | Add Login UI MFA Flow

[matiasperrone-exo]

Task:

Ref: https://app.clickup.com/t/9014802374/86ba2zp3q

Changes

Preview

Overview

Adds a multi-factor authentication (MFA) flow to the React login UI, plus the backend response-contract changes needed to support it as an AJAX step instead of a full-page redirect. The monolithic login.js was refactored — inline form components were extracted into dedicated files, and two new MFA screens (verification code + recovery code) were added.

Highlights

• New MFA flow: after a successful password step, the backend can signal mfa_required, which transitions the UI into a two-factor email-OTP challenge instead of completing login.
• AJAX-completable verify/recovery: UserController::verify2FA() / verify2FARecovery() now return 200 + { redirect_url } (previously a raw redirect) so the client's XHR can read the destination and perform a real top-level navigation itself — postLogin() can chain into a cross-origin hop (OAuth2 authorization code delivery) that no XHR/fetch could follow. JsonResponses::unauthorized() was added to keep the 401 paths consistent with the rest of the trait's helpers.
• Countdown correctness on refresh: the MFA challenge payload now carries otp_issued_at (taken from the OTP entity's created_at — the same source isAlive() uses server-side), and the blade seeds the countdown with the REMAINING lifetime. Previously a mid-challenge page refresh restarted the countdown at the full TTL, overstating how long the code was valid and letting the user burn rate-limited verify attempts on a server-expired code. Expired codes can no longer be submitted (VERIFY disables + submit guard). The new payload field is additive for native-client JSON consumers.
• Passwordless OTP countdown: the passwordless OTP form now shows the same expiry countdown and expired-submit gating (its OTP expires identically; emitOTP already returned otp_lifetime — the client just ignored it). The countdown only renders when a fresh code was emitted in the current page view. The shared code-entry UI (subtitle + boxes + error + countdown) and the ticking logic were extracted into otp_code_input.js / use_otp_countdown.js, consumed by both forms.
• Component extraction: all inline form definitions in login.js were moved into resources/js/login/components/, slimming and reorganizing the main file.

New Files

Actions & constants

• resources/js/login/constants.js — HTTP_CODES, MFA_METHODS, FLOW, MFA_ERROR_CODE, and defaults (OTP length 6, TTL 300, default method email_otp).

Login form components (resources/js/login/components/)

• two_factor_form.js — MFA email-OTP entry with expiry countdown, 30s resend cooldown, "Trust this device for 30 days", links to recovery code / cancel.
• recovery_code_form.js — recovery code entry screen with back-to-OTP and cancel.
• email_input_form.js — extracted email entry form.
• password_input_form.js — extracted password form (incl. failed-attempt / account-lock messaging).
• otp_input_form.js — extracted single-use code form.
• email_error_actions.js, existing_account_actions.js, help_links.js, otp_help_links.js, third_party_identity_providers.js — extracted helper/link components.
• otp_code_input.js — shared code-entry block (subtitle + OTP boxes + error + optional expiry countdown) used by both two_factor_form.js and otp_input_form.js.
• use_otp_countdown.js — shared 1s expiry-countdown hook (resets on otpLifetime / codeVersion change).
• resources/js/shared/HTMLRender.js — DOMPurify-sanitized dangerouslySetInnerHTML wrapper, replacing raw unsanitized HTML injection for server-supplied error strings.

Modified Files

• app/Http/Controllers/UserController.php — postLogin()'s mfa_required branch now also flashes identity/display fields (username, user_fullname, user_pic, user_verified, user_is_active) so the React app can rehydrate the identity chip after the password step's page reload; verify2FA() / verify2FARecovery() return { redirect_url } instead of redirecting directly; resend2FA() keeps otp_issued_at in sync; clearMFAUISessionState() clears the identity keys and otp_issued_at.
• app/Strategies/MFA/EmailOTPMFAChallengeStrategy.php — issueChallenge()'s payload now includes otp_issued_at from the OTP entity's created_at (additive field, also visible to native-client JSON consumers).
• app/Http/Controllers/Traits/JsonResponses.php — added unauthorized(); switched raw status ints to HttpResponse::HTTP_* constants.
• routes/web.php — cancel route changed from GET to POST with CSRF middleware.
• resources/js/login/actions.js — added verify2FA, resend2FA, verifyRecoveryCode, cancelLogin.
• resources/js/login/login.js — major refactor:
  • Imports extracted components instead of defining them inline.
  • Added MFA state (mfaMethod, trustDevice, twoFactorCode, recoveryCode, otpLength, otpLifetime, codeVersion, passwordlessLifetime) and handlers (onVerify2FA, onResend2FA, onVerifyRecovery, onUseRecovery, onBackToOtp, resetToPasswordFlow, handleMfaError, cancelPendingLogin).
  • Password and passwordless-OTP auth are unchanged (native form POST); on mfa_required the page reload rehydrates the 2fa flow from session instead.
  • Render logic gated by derived flow flags (showTwoFactorForm, showRecoveryForm, isPasswordFlow, isOtpFlow, showDefaultFlow).
  • Both cancel paths (Cancel link and identity-chip delete) invalidate the pending server-side challenge via cancelPendingLogin(), which warns through the snackbar if the server-side invalidation fails.
• resources/js/login/login.module.scss — new styles: .info_message, .countdown, .trust_device_row, .disabled_link.
• resources/views/auth/login.blade.php — wired new endpoints/config: verify2faAction, resend2faAction, cancelLogin, recovery2faAction, mfaMethod, plus session-driven otpLength / otpLifetime; seeds config.otpLifetime with the REMAINING lifetime (lifetime − (now − otp_issued_at)); exposes VERIFY_2FA_ENDPOINT, RESEND_2FA_ENDPOINT, CANCEL_LOGIN_ENDPOINT, RECOVERY_2FA_ENDPOINT on window.
• tests/TwoFactorLoginFlowTest.php — assertions updated for the 200 + redirect_url response contract; added coverage for identity-field cleanup on cancel/verify-success, otp_issued_at persistence/cleanup, and a reproducer asserting a mid-challenge refresh seeds the countdown with the remaining (not full) lifetime.
• package.json — updated serve script flag (--https → --server-type https) for the newer webpack-dev-server; added dompurify, prop-types dependencies.

---

User's GOAL

Current state

The login React component supports password and passwordless OTP flows. It has no MFA verification screen after password authentication.

Target state

The login UI supports a third flow state, '2fa'. When the backend returns mfa_required, the UI renders an MFA verification step with OTP input, trust-device checkbox, resend action, recovery-code link, and relevant error handling.

TASKS

• refactor all reactjs components from resources/js/login/login.js and move then to a new folder under resources/js/login/components
  ( each component should have its own file )
• Add '2fa' flow state to login component.
• Detect error_code=mfa_required in login response.
• Store username, otp_length, otp_lifetime, and method from response.
• Render informational message: "A verification code has been sent to your email".
• Reuse existing OTP input component.
• Render "Trust this device for 30 days" checkbox, unchecked by default.
• Implement OTP submit to POST /auth/login/2fa/verify with:
  • otp_value
  • method='email_otp'
  • trust_device
• Implement resend to POST /auth/login/2fa/resend with method='email_otp'.
• Handle resend success with user feedback and cooldown/countdown.
• Handle 429 response with rate-limit message.
• Implement Cancel action to return to password screen and clear client-side MFA state.
• Add "Use a recovery code instead" link that transitions to the recovery-code login mode implemented in Ticket 12A.
• Add countdown timer based on otp_lifetime.
• Hide "Use a different method" in Phase I.
• Ensure CSRF token is included in all POST requests.

ACCEPTANCE CRITERIA

• mfa_required response transitions UI to 2FA screen.
• OTP input length follows otp_length from server.
• Valid OTP completes login and follows normal redirect/OIDC flow.
• Invalid OTP shows inline error and remains on 2FA screen.
• mfa_session_expired shows message and returns user to password flow.
• mfa_rate_limit shows "Too many attempts" or approved product copy.
• Resend calls correct endpoint and shows feedback.
• Cancel returns to password flow.
• Existing password and passwordless OTP flows are unaffected. (Amended during review: the passwordless OTP form deliberately gained the same expiry countdown and expired-submit gating as the 2FA screen — see Highlights. Its submission mechanics are otherwise untouched.)

DEVELOPMENT NOTES

Key files:

• Modified: resources/js/login/login.js
• Possibly modified: resources/views/auth/login.blade.php
• Existing: react-otp-input or equivalent OTP component

Gotchas:

• The backend may return mfa_required through login_strategy->errorLogin(), which may be represented as flash data or JSON depending on flow. Follow existing login error handling.
• Keep this as a state in the existing login component, not a separate page.
• Trust-device checkbox must default to unchecked.

Risks:

• Risk: React flow does not receive enough data from backend. Mitigation: verify mfa_required response includes username, method, otp_length, otp_lifetime.

Out of scope:

Recovery-code profile management, device-management UI, method selector for future MFA methods.

Summary by CodeRabbit

• New Features

  • Added two-factor authentication (2FA) with one-time password (OTP) verification.
  • Added recovery code verification option.
  • Added "trust this device" functionality to streamline future logins.
  • Added support for third-party identity providers for social login.
  • Added CAPTCHA integration for enhanced security.
  • Improved login flow with better error messaging and code expiry countdowns.

• Bug Fixes

  • Improved session expiration handling during authentication.

• Chores

  • Updated HTTPS server configuration.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fb0d7e9c-c83c-44bf-861c-6f771bb2430f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding an MFA flow to the login UI.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/mfa---login-ui-flow

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[coderabbitai]

Actionable comments posted: 16

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@resources/js/base_actions.js`:
- Around line 102-106: The issue is that params are unconditionally being added
to the URL query string via the url.query(params) call, which exposes sensitive
POST data like passwords, OTPs, and captchas in URLs and logs. Modify the code
to only add params to the query string for non-POST requests. Check the HTTP
method of the request before calling url.query(params) and only apply it when
the method is not POST, ensuring sensitive data in POST requests stays in the
request body and is never exposed in the URL.

In `@resources/js/login/components/email_error_actions.js`:
- Around line 22-42: The two Button components in this block are not respecting
the disableInput state, allowing users to trigger actions even when the UI
should be locked. Add the disabled prop set to disableInput on both buttons: the
button with onClick={emitOtpAction} and the button with
href={createAccountAction}. This will prevent users from clicking these recovery
action buttons when the input is disabled.

In `@resources/js/login/components/email_input_form.js`:
- Around line 51-55: Remove the use of dangerouslySetInnerHTML on the error
message element in the email error rendering section. Instead of using
dangerouslySetInnerHTML with the emailError property, render the emailError text
directly as a child of the paragraph element to prevent potential XSS
vulnerabilities. This applies to the conditional block where emailError is not
empty and the error paragraph is being displayed.

In `@resources/js/login/components/existing_account_actions.js`:
- Around line 34-37: The `Link` component with `disabled={disableInput}` prop
does not actually prevent navigation in MUI v4 when using the default anchor
element. To fix this, add an onClick handler to the Link component that prevents
the default navigation behavior when disableInput is true. The onClick handler
should call preventDefault() on the event whenever disableInput is true,
effectively blocking the navigation while the input is locked.

In `@resources/js/login/components/help_links.js`:
- Around line 18-21: The URL construction for forgotPasswordActionHref does not
account for existing query parameters in the forgotPasswordAction base URL. When
appending the email parameter, the code always uses `?email=...`, which will
create invalid URLs if forgotPasswordAction already contains a query string.
Modify the conditional block where forgotPasswordActionHref is assigned (when
userName exists) to check if forgotPasswordAction already contains a `?`
character. If it does, use `&` to append the email parameter; otherwise use `?`.
This ensures proper URL formatting regardless of whether the base URL already
has query parameters.

In `@resources/js/login/components/otp_input_form.js`:
- Around line 55-58: The error label paragraph element in the OTP input form is
using dangerouslySetInnerHTML to render the otpError variable, which creates an
XSS security vulnerability. Remove the dangerouslySetInnerHTML prop and instead
render the otpError directly as text content of the paragraph element so that
any HTML-like characters in the error message are displayed as plain text rather
than being interpreted as executable HTML.
- Line 1: Remove the useMemo hook to prevent stale captcha visibility state.
First, remove useMemo from the import statement at the top of the
otp_input_form.js file. Then, locate where useMemo is being used in the
component (likely wrapping captcha visibility logic) and unwrap it by removing
the useMemo function call while keeping the code it was wrapping. This ensures
the captcha visibility logic runs on every render and properly reflects the
current state of dependencies like loginAttempts, rather than relying on a stale
memoized result based only on the function reference.
- Line 49: The `hasErrored` prop being passed to the OtpInput component is not
supported in react-otp-input v3.1.1 and was removed in v3.0.0+. Remove the
`hasErrored={!otpError}` prop from the OtpInput component and instead use the
`renderInput` prop to handle error state styling. Pass the otpError state to the
custom input component through the `renderInput` prop so that the error styling
can be conditionally applied within the input component based on the parent
component's otpError state.

In `@resources/js/login/components/password_input_form.js`:
- Around line 85-88: The paragraph element with className styles.error_label is
rendering passwordError as HTML using dangerouslySetInnerHTML, which creates an
XSS vulnerability. Remove the dangerouslySetInnerHTML prop and instead render
passwordError directly as text content within the paragraph element to safely
display the error message without executing any embedded HTML or scripts.

In `@resources/js/login/components/recovery_code_form.js`:
- Around line 22-25: The handleBack function defined in the recovery_code_form
component is not connected to any UI element, so users cannot interact with it
to go back to the OTP screen. Add a button element in the form's JSX render that
calls the handleBack function on click. This button should be placed in a
logical location in the recovery form UI, likely near the form submission or as
a navigation element. Note that the same issue applies to the code around lines
65-72, so ensure both instances have the corresponding UI elements added to
enable the back navigation functionality.
- Around line 53-55: The recoveryError is being rendered as raw HTML using
dangerouslySetInnerHTML, which creates an XSS vulnerability if the error content
contains user-controlled or backend text. Replace the dangerouslySetInnerHTML
prop with direct text rendering by removing the
dangerouslySetInnerHTML={{__html: recoveryError}} attribute and instead render
recoveryError directly as plain text inside the paragraph element with the
error_label className. This will automatically escape any HTML special
characters and prevent potential XSS attacks.

In `@resources/js/login/components/two_factor_form.js`:
- Around line 91-93: The otpError variable is being rendered with
dangerouslySetInnerHTML which creates an XSS vulnerability since the value comes
from server responses. Remove the dangerouslySetInnerHTML attribute from the
error message paragraph element in the two_factor_form component and instead
render otpError as plain text content. If HTML formatting is required for the
error message, sanitize otpError using a proper HTML sanitization library before
using dangerouslySetInnerHTML.

In `@resources/js/login/login.js`:
- Around line 435-463: Add an early guard clause at the beginning of the
onVerify2FA method to prevent duplicate verification requests. Before processing
any validation logic or making the verify2FA API call, check if
this.state.disableInput is already true, and if so, return early from the
method. This will prevent rapid successive clicks or Enter key events from
triggering multiple concurrent API calls. Apply the same guard pattern to the
other verify handler mentioned in the comment (around lines 524-547).
- Around line 183-202: In the handleAuthenticateValidation method, the password
validation block that checks if user_password is empty is being executed
unconditionally for all auth flows. This causes the OTP flow validation to fail
even when a valid OTP code is provided, because the password check comes after
the OTP check and always requires a password. Wrap the password validation block
in a conditional statement that only executes when the auth flow is NOT
FLOW.OTP, so that OTP flow validation can complete successfully without
requiring a password field.
- Around line 220-241: The `default` case in the switch statement declares
`const redirect` without block scope, creating scope and TDZ issues. Wrap the
entire contents of the `default` case (from the `const redirect` declaration
through the closing of the if-else block that checks the redirect condition)
with curly braces to create proper block scope and isolate the variable
declaration from other switch cases.

In `@resources/views/auth/login.blade.php`:
- Around line 102-107: The line setting window.RESET_2FA_ENDPOINT is referencing
config.reset2faAction which is not defined in the template's configuration
object, causing the window variable to become undefined. Verify the template's
PHP configuration section where the config object is initialized and either add
the missing reset2faAction property with the appropriate endpoint URL, or
correct the reference to use the correct existing config key name that
corresponds to the reset 2FA endpoint.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dd2029b0-3aab-49c1-b3e1-2abdc066795e

📥 Commits

Reviewing files that changed from the base of the PR and between 5fc47a4 and 3481ac9.

📒 Files selected for processing (17)

• package.json
• resources/js/base_actions.js
• resources/js/login/actions.js
• resources/js/login/components/email_error_actions.js
• resources/js/login/components/email_input_form.js
• resources/js/login/components/existing_account_actions.js
• resources/js/login/components/help_links.js
• resources/js/login/components/otp_help_links.js
• resources/js/login/components/otp_input_form.js
• resources/js/login/components/password_input_form.js
• resources/js/login/components/recovery_code_form.js
• resources/js/login/components/third_party_identity_providers.js
• resources/js/login/components/two_factor_form.js
• resources/js/login/constants.js
• resources/js/login/login.js
• resources/js/login/login.module.scss
• resources/views/auth/login.blade.php

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[smarcet]

UX regression: password flow loses native password-manager integration.

Converting the password submission to AJAX (handleAuthenticatePasswordFlow via authenticateWithPassword/postRawRequestFull) means the browser never fires a native submit event on the <form>, which is what Chrome/1Password/etc. key their "save/update this password" prompt off of. Users who type or paste a password here won't be offered a save/update prompt, unlike every other flow in this same file (OTP, recovery, cancel), which still submit natively.

This wasn't flagged in the ticket (CU-86ba2zp3q) or any existing review comment - it's a usability downgrade, not a functional bug, but worth a deliberate call: was the AJAX conversion here intentional (e.g. to support the live in-SPA MFA transition), or just a side effect of refactoring the form components? If intentional, consider whether the live-transition benefit is worth losing autofill/save-password integration on the one flow where it matters most.

Suggested fix: let the password flow fall through to the native submit like the sibling flows already do (line 271's onAuthenticate), and drive the follow-up MFA screen via a redirect + session-flashed state instead - same mechanism this form already uses for every other flow and every other error.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-142/

This page is automatically updated on each push to this PR.