feat: warn on low recovery codes after MFA recovery login

CU-86ba2zp66 / sds/idp-mfa.md §4.10.3, §4.11 step 5 require a
dismissable low-code warning after a successful MFA login, but it
was only wired into the profile page - a user who burns codes at
login never saw it unless they happened to visit their profile.

verify2FARecovery now returns recovery_codes_remaining and the
configured low threshold; login.js holds the post-login redirect
and shows a dismissable banner when the count is low, before
navigating away. The sessionStorage dismissal key is shared with
the profile page's RecoveryCodesPanel via a new shared module so
dismissing in either place suppresses it everywhere for the rest
of the session.

Author: romanetar

app/Http/Controllers/UserController.php

@@ -927,7 +927,14 @@ public function verify2FARecovery()
             // See verify2FA() for rationale: return the destination as data so a real
             // top-level navigation (not this XHR) performs any cross-origin hop.
             $redirect = $this->login_strategy->postLogin();
-            return $this->ok(['redirect_url' => $redirect->getTargetUrl()]);
+            return $this->ok([
+                'redirect_url' => $redirect->getTargetUrl(),
+                // CU-86ba2zp66 / sds/idp-mfa.md §4.10.3, §4.11 step 5: the login page
+                // must be able to warn the user when they've just burned into their
+                // last few recovery codes, since it may be their only way back in.
+                'recovery_codes_remaining' => $this->recovery_code_service->countUnusedRecoveryCodes($user),
+                'recovery_codes_low_threshold' => (int) config('auth.recovery_codes.low_threshold', 3),
+            ]);
         } catch (ValidationException $ex) {
             Log::warning($ex);
             return $this->error412($ex->getMessages());

resources/js/components/recovery_codes_panel.js

@@ -10,16 +10,17 @@ import CloseIcon from "@material-ui/icons/Close";
 import {regenerateRecoveryCodes} from "../profile/actions";
 import {handleErrorResponse} from "../utils";
 import RecoveryCodeModal from "./recovery_code_modal";
+import {
+    RECOVERY_CODES_LOW_WARNING_DISMISSED_KEY,
+    DEFAULT_RECOVERY_CODES_LOW_THRESHOLD,
+} from "../shared/recovery_codes";
 
 import styles from "./recovery_codes.module.scss";
 
-const DEFAULT_LOW_CODE_THRESHOLD = 3;
-const LOW_CODE_WARNING_DISMISSED_KEY = "recovery_codes_low_warning_dismissed";
-
 const RecoveryCodesPanel = ({
                                  recoveryCodesRemaining,
                                  recoveryCodesTotal,
-                                 lowCodeThreshold = DEFAULT_LOW_CODE_THRESHOLD,
+                                 lowCodeThreshold = DEFAULT_RECOVERY_CODES_LOW_THRESHOLD,
                                  email,
                                  initialCodes = null
                              }) => {
@@ -30,7 +31,7 @@ const RecoveryCodesPanel = ({
     const [total, setTotal] = useState(recoveryCodesTotal);
     const [codes, setCodes] = useState(initialCodes);
     const [warningDismissed, setWarningDismissed] = useState(
-        sessionStorage.getItem(LOW_CODE_WARNING_DISMISSED_KEY) === "1"
+        sessionStorage.getItem(RECOVERY_CODES_LOW_WARNING_DISMISSED_KEY) === "1"
     );
 
     const handleRegenerate = () => {
@@ -53,7 +54,7 @@ const RecoveryCodesPanel = ({
     };
 
     const dismissLowCodeWarning = () => {
-        sessionStorage.setItem(LOW_CODE_WARNING_DISMISSED_KEY, "1");
+        sessionStorage.setItem(RECOVERY_CODES_LOW_WARNING_DISMISSED_KEY, "1");
         setWarningDismissed(true);
     };
 

resources/js/login/login.js

@@ -31,8 +31,13 @@ import EmailErrorActions from "./components/email_error_actions";
 import ThirdPartyIdentityProviders from "./components/third_party_identity_providers";
 import TwoFactorForm from "./components/two_factor_form";
 import RecoveryCodeForm from "./components/recovery_code_form";
+import {
+  RECOVERY_CODES_LOW_WARNING_DISMISSED_KEY,
+  DEFAULT_RECOVERY_CODES_LOW_THRESHOLD,
+} from "../shared/recovery_codes";
 
 import styles from "./login.module.scss";
+import recoveryCodesStyles from "../components/recovery_codes.module.scss";
 import "./third_party_identity_providers.scss";
 import {
   FLOW,
@@ -93,6 +98,11 @@ class LoginPage extends React.Component {
       // change writes otp_lifetime atomically with flow, so props.otpLifetime
       // is only ever missing when there's no pending OTP to show a countdown for.
       passwordlessLifetime: props.otpLifetime ?? null,
+      // Set once a recovery-code login succeeds with a low remaining count, so
+      // the redirect can be held until the user acknowledges the warning -
+      // this is the only point where the SPA still controls the page (see
+      // onVerifyRecovery()/onContinueAfterLowRecoveryCodes() below).
+      lowRecoveryCodesWarning: null,
     };
 
     if (props.authError != "" && !this.state.user_fullname) {
@@ -130,6 +140,7 @@ class LoginPage extends React.Component {
     this.onVerify2FA = this.onVerify2FA.bind(this);
     this.onResend2FA = this.onResend2FA.bind(this);
     this.onVerifyRecovery = this.onVerifyRecovery.bind(this);
+    this.onContinueAfterLowRecoveryCodes = this.onContinueAfterLowRecoveryCodes.bind(this);
     this.onUseRecovery = this.onUseRecovery.bind(this);
     this.onBackToOtp = this.onBackToOtp.bind(this);
     this.resetToPasswordFlow = this.resetToPasswordFlow.bind(this);
@@ -540,17 +551,38 @@ class LoginPage extends React.Component {
 
     verifyRecoveryCode(recoveryCode, this.props.token).then(
       (payload) => {
-        // See onVerify2FA() for rationale.
         const { response } = payload;
-        window.location.href =
+        const redirectUrl =
           (response && response.redirect_url) || window.location.href;
+        const remaining = response && response.recovery_codes_remaining;
+        const threshold =
+          (response && response.recovery_codes_low_threshold) ??
+          DEFAULT_RECOVERY_CODES_LOW_THRESHOLD;
+        const alreadyDismissed =
+          sessionStorage.getItem(RECOVERY_CODES_LOW_WARNING_DISMISSED_KEY) === "1";
+
+        if (typeof remaining === "number" && remaining < threshold && !alreadyDismissed) {
+          this.setState({
+            ...this.state,
+            lowRecoveryCodesWarning: { remaining, redirectUrl },
+          });
+          return;
+        }
+
+        // See onVerify2FA() for rationale on using a real top-level navigation.
+        window.location.href = redirectUrl;
       },
       (error) => {
         this.handleMfaError(error, "recovery");
       },
     );
   }
 
+  onContinueAfterLowRecoveryCodes() {
+    sessionStorage.setItem(RECOVERY_CODES_LOW_WARNING_DISMISSED_KEY, "1");
+    window.location.href = this.state.lowRecoveryCodesWarning.redirectUrl;
+  }
+
   onUseRecovery() {
     this.setState({
       ...this.state,
@@ -833,7 +865,7 @@ class LoginPage extends React.Component {
                 onVerify={this.onVerify2FA}
               />
             )}
-            {showRecoveryForm && (
+            {showRecoveryForm && !this.state.lowRecoveryCodesWarning && (
               <RecoveryCodeForm
                 recoveryCode={this.state.recoveryCode}
                 recoveryError={this.state.errors.recovery}
@@ -844,6 +876,27 @@ class LoginPage extends React.Component {
                 onCancel={this.resetToPasswordFlow}
               />
             )}
+            {showRecoveryForm && this.state.lowRecoveryCodesWarning && (
+              <div
+                className={recoveryCodesStyles.low_code_warning}
+                data-testid="low-recovery-codes-warning"
+              >
+                <Typography variant="body2">
+                  You have {this.state.lowRecoveryCodesWarning.remaining} recovery
+                  code{this.state.lowRecoveryCodesWarning.remaining === 1 ? "" : "s"} left.
+                  Regenerate them from your profile after signing in to avoid getting
+                  locked out.
+                </Typography>
+                <Button
+                  variant="contained"
+                  color="primary"
+                  onClick={this.onContinueAfterLowRecoveryCodes}
+                  data-testid="continue-after-low-recovery-codes"
+                >
+                  Continue
+                </Button>
+              </div>
+            )}
             {isPasswordFlow && (
               // proceed to ask for password ( 2nd step )
               <div data-testid="password-form">

resources/js/shared/recovery_codes.js

@@ -0,0 +1,5 @@
+// Shared between the profile page's RecoveryCodesPanel and the login page's
+// post-MFA-recovery-login warning, so dismissing the low-code warning in
+// either place suppresses it everywhere else for the rest of the session.
+export const RECOVERY_CODES_LOW_WARNING_DISMISSED_KEY = "recovery_codes_low_warning_dismissed";
+export const DEFAULT_RECOVERY_CODES_LOW_THRESHOLD = 3;