From 7cc4f0e65172fd7c94478fe2d2023d9af095c419 Mon Sep 17 00:00:00 2001
From: Jennifer Li <jli@gitlab.com>
Date: Sat, 18 Oct 2025 11:57:06 -0700
Subject: [PATCH 1/8] Render email verification view as fallback for webauthn
 authentication

Add translation changes
Changelog: added
---
 .../webauthn/components/authenticate.vue      | 89 ++++++++++++++++++-
 .../authentication/webauthn/index.js          |  4 +-
 app/assets/javascripts/sessions/new/index.js  | 27 +-----
 .../concerns/verifies_with_email.rb           |  1 +
 app/controllers/sessions_controller.rb        | 35 ++++++++
 app/helpers/sessions_helper.rb                | 25 ++++++
 .../_totp_recovery_code_or_webauthn.html.haml |  8 +-
 config/routes/user.rb                         |  1 +
 locale/gitlab.pot                             | 24 +++++
 9 files changed, 183 insertions(+), 31 deletions(-)

diff --git a/app/assets/javascripts/authentication/webauthn/components/authenticate.vue b/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
index 394632d418caf3..85fd23b359d022 100644
--- a/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
+++ b/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
@@ -1,6 +1,9 @@
 <script>
-import { GlButton, GlForm } from '@gitlab/ui';
+/* global __ */
+import { GlButton, GlForm, GlLink, GlSprintf } from '@gitlab/ui';
+import Vue from 'vue';
 import csrf from '~/lib/utils/csrf';
+import EmailVerification from '~/sessions/new/components/email_verification.vue';
 import { supported, convertGetParams, convertGetResponse } from '../util';
 import { WEBAUTHN_AUTHENTICATE } from '../constants';
 import WebAuthnError from '../error';
@@ -10,6 +13,8 @@ export default {
   components: {
     GlForm,
     GlButton,
+    GlLink,
+    GlSprintf,
   },
   props: {
     webauthnParams: {
@@ -28,6 +33,16 @@ export default {
       type: String,
       required: true,
     },
+    sendEmailOtpPath: {
+      type: String,
+      required: false,
+      default: '',
+    },
+    username: {
+      type: String,
+      required: false,
+      default: '',
+    },
   },
   data() {
     return {
@@ -39,6 +54,11 @@ export default {
       fallbackMode: false,
     };
   },
+  computed: {
+    showFooter() {
+      return this.errorMessage && this.sendEmailOtpPath;
+    },
+  },
   mounted() {
     if (this.isWebauthnSupported()) {
       this.authenticate();
@@ -54,7 +74,10 @@ export default {
     },
     switchToFallbackUI() {
       this.fallbackMode = true;
-      document.querySelector('.js-2fa-form').classList.remove('hidden');
+      const form = document.querySelector('.js-2fa-form');
+      if (form) {
+        form.classList.remove('hidden');
+      }
     },
     isWebauthnSupported() {
       return supported();
@@ -62,6 +85,51 @@ export default {
     formSubmit() {
       this.$refs.loginToken2faForm.$el.submit();
     },
+    async sendEmailOtp() {
+      try {
+        const response = await fetch(this.sendEmailOtpPath, {
+          method: 'POST',
+          headers: {
+            'X-CSRF-Token': this.$options.csrf.token,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            user: { login: this.username },
+          }),
+        });
+
+        const data = await response.json();
+        if (response.ok && data.success) {
+          // Hide WebAuthn UI
+          this.fallbackMode = true;
+
+          // Hide the 2FA form
+          const twoFaForm = document.querySelector('.js-2fa-form');
+          if (twoFaForm) {
+            twoFaForm.classList.add('hidden');
+          }
+
+          // Initialize and show email verification component
+          const container = document.querySelector('.js-email-verification-container');
+          if (container && data.email_verification_data) {
+            container.classList.remove('hidden');
+
+            // eslint-disable-next-line no-new
+            new Vue({
+              el: container,
+              render: (h) =>
+                h(EmailVerification, {
+                  props: data.email_verification_data,
+                }),
+            });
+          }
+        } else {
+          throw new Error(data.message || __('Failed to send email'));
+        }
+      } catch (err) {
+        // console.error(__('Failed to send email OTP:'), err);
+      }
+    },
     async authenticate() {
       this.inProgress = true;
       try {
@@ -138,5 +206,22 @@ export default {
     >
       {{ __('Sign in via 2FA code') }}
     </gl-button>
+
+    <div v-if="showFooter" class="gl-mt-4 gl-text-sm gl-text-subtle">
+      <gl-sprintf
+        :message="__('Having trouble signing in? %{recoveryCodeLink} or %{sendCodeLink}.')"
+      >
+        <template #recoveryCodeLink>
+          <gl-link href="#" @click.prevent="switchToFallbackUI">
+            {{ __('Enter recovery code') }}
+          </gl-link>
+        </template>
+        <template #sendCodeLink>
+          <gl-link href="#" @click.prevent="sendEmailOtp">
+            {{ __('send code to email address') }}
+          </gl-link>
+        </template>
+      </gl-sprintf>
+    </div>
   </div>
 </template>
diff --git a/app/assets/javascripts/authentication/webauthn/index.js b/app/assets/javascripts/authentication/webauthn/index.js
index 02576e8dbd96df..b14d97ddaecbd0 100644
--- a/app/assets/javascripts/authentication/webauthn/index.js
+++ b/app/assets/javascripts/authentication/webauthn/index.js
@@ -9,7 +9,7 @@ export const initWebauthnAuthenticate = () => {
     return false;
   }
 
-  const { targetPath, renderRememberMe, rememberMe } = el.dataset;
+  const { targetPath, renderRememberMe, rememberMe, sendEmailOtpPath, username } = el.dataset;
 
   return new Vue({
     el,
@@ -21,6 +21,8 @@ export const initWebauthnAuthenticate = () => {
           targetPath,
           renderRememberMe: parseBoolean(renderRememberMe),
           rememberMe,
+          sendEmailOtpPath,
+          username,
         },
       });
     },
diff --git a/app/assets/javascripts/sessions/new/index.js b/app/assets/javascripts/sessions/new/index.js
index 1540dff155af48..b2996567d9bb18 100644
--- a/app/assets/javascripts/sessions/new/index.js
+++ b/app/assets/javascripts/sessions/new/index.js
@@ -1,28 +1,5 @@
-import Vue from 'vue';
-import EmailVerification from './components/email_verification.vue';
+import { initWebauthnAuthenticate } from '~/authentication/webauthn';
 
 export default () => {
-  const el = document.querySelector('.js-email-verification');
-
-  if (!el) {
-    return null;
-  }
-
-  const { username, obfuscatedEmail, verifyPath, resendPath, skipPath } = el.dataset;
-
-  return new Vue({
-    el,
-    name: 'EmailVerificationRoot',
-    render(createElement) {
-      return createElement(EmailVerification, {
-        props: {
-          username,
-          obfuscatedEmail,
-          verifyPath,
-          resendPath,
-          skipPath,
-        },
-      });
-    },
-  });
+  initWebauthnAuthenticate();
 };
diff --git a/app/controllers/concerns/verifies_with_email.rb b/app/controllers/concerns/verifies_with_email.rb
index 9b0adad4c9e7ad..d44c14f7e7938f 100644
--- a/app/controllers/concerns/verifies_with_email.rb
+++ b/app/controllers/concerns/verifies_with_email.rb
@@ -156,6 +156,7 @@ def send_otp_with_email(user, secondary_email: nil, reason: VERIFICATION_REASON_
     service = Users::EmailVerification::GenerateTokenService.new(attr: :email_otp, user: user)
     raw_token, encrypted_token = service.execute
 
+    # Rails.logger.error("JLI: email otp: #{raw_token}")
     user.email_otp = encrypted_token
     user.email_otp_last_sent_at = Time.current
     user.email_otp_last_sent_to = secondary_email || user.email
diff --git a/app/controllers/sessions_controller.rb b/app/controllers/sessions_controller.rb
index b8ee5e8a4789d4..cf26e594a9f479 100644
--- a/app/controllers/sessions_controller.rb
+++ b/app/controllers/sessions_controller.rb
@@ -106,6 +106,41 @@ def destroy
     end
   end
 
+  def fallback_to_email_otp
+    user = find_user
+
+    unless user
+      render json: { success: false, message: _('Session expired.') }, status: :unauthorized
+      return
+    end
+
+    if fallback_to_email_otp_permitted?(user)
+      clear_two_factor_attempt!
+      session[:verification_user_id] = user.id
+
+      if !treat_as_locked?(user) && Feature.enabled?(:email_based_mfa, user)
+        send_otp_with_email(user, secondary_email: nil, reason: VerifiesWithEmail::VERIFICATION_REASON_EMAIL_OTP)
+
+        # Redirect to login page - verify_with_email will show email verification form
+        render json: {
+          success: true,
+          message: _('Verification code has been sent to your email address.'),
+          email_verification_data: {
+            username: user.username,
+            obfuscatedEmail: obfuscated_email(user.email),
+            verifyPath: session_path(:user),
+            resendPath: users_resend_verification_code_path,
+            skipPath: nil
+          }
+        }, status: :ok
+      else
+        render json: { success: false, message: _('Unable to send code.') }, status: :unprocessable_entity
+      end
+    else
+      render json: { success: false, message: _('Not permitted.') }, status: :bad_request
+    end
+  end
+
   private
 
   override :after_pending_invitations_hook
diff --git a/app/helpers/sessions_helper.rb b/app/helpers/sessions_helper.rb
index 25b1d4b9b7298a..8d77e5c6c16185 100644
--- a/app/helpers/sessions_helper.rb
+++ b/app/helpers/sessions_helper.rb
@@ -33,4 +33,29 @@ def verification_data(user)
       skip_path: permitted_to_skip ? users_skip_verification_for_now_path : nil
     }
   end
+
+  def fallback_to_email_otp_permitted?(user)
+    user.email_otp_required_after && user.email_otp_required_after <= Time.zone.today
+  end
+
+  def webauthn_authentication_data(user, admin_mode: false)
+    target_path = admin_mode ? admin_session_path : user_session_path
+    render_remember_me = admin_mode ? false : remember_me_enabled?
+    user_params = params[:user].presence || params
+    remember_me_value = user_params.fetch(:remember_me, 0)
+
+    send_email_otp_path = fallback_to_email_otp_permitted?(user) ? users_fallback_to_email_otp_path : nil
+
+    data = {
+      target_path: target_path,
+      render_remember_me: render_remember_me.to_s,
+      remember_me: remember_me_value,
+      send_email_otp_path: send_email_otp_path,
+      username: user.username
+    }
+
+    data[:email_verification_data] = verification_data(user).to_json if send_email_otp_path
+
+    data
+  end
 end
diff --git a/app/views/devise/shared/_totp_recovery_code_or_webauthn.html.haml b/app/views/devise/shared/_totp_recovery_code_or_webauthn.html.haml
index 9e7c484e2cbda9..25e05b9da247bf 100644
--- a/app/views/devise/shared/_totp_recovery_code_or_webauthn.html.haml
+++ b/app/views/devise/shared/_totp_recovery_code_or_webauthn.html.haml
@@ -1,11 +1,10 @@
 - target_path = admin_mode ? admin_session_path : user_session_path
-- render_remember_me =  admin_mode ? false : remember_me_enabled?
+- render_remember_me = admin_mode ? false : remember_me_enabled?
 - user_params = params[:user].presence || params
 
 = gitlab_ui_form_for(:user, url: target_path, method: :post, html: { class: "gl-show-field-errors js-2fa-form #{'hidden' if @user.two_factor_webauthn_enabled?}", aria: { live: 'assertive' }}) do |f|
   .form-group
     = f.label :otp_attempt, _('Enter verification code')
-    -# Note: we use inputmode="numeric", because TOTP. However, recovery codes are alphanumeric.
     = f.text_field :otp_attempt, class: 'form-control gl-form-input', required: true, autofocus: true, autocomplete: 'off', inputmode: 'numeric', title: _('This field is required.'), data: { testid: 'two-fa-code-field' }
     %p.form-text.gl-text-subtle.hint
       = _("Enter the code from your two-factor authenticator app. If you've lost your device, you can enter one of your recovery codes.")
@@ -16,5 +15,8 @@
   = render Pajamas::ButtonComponent.new(type: :submit, variant: :confirm, block: true, button_options: { data: { testid: 'verify-code-button' } }) do
     = _("Verify code")
 
+-# Add email verification component container (always hidden initially)
+.js-email-verification-container.hidden
+
 - if @user.two_factor_webauthn_enabled?
-  #js-authentication-webauthn{ data: { target_path: target_path, render_remember_me: render_remember_me.to_s, remember_me: user_params.fetch(:remember_me, 0) } }
+  #js-authentication-webauthn{ data: webauthn_authentication_data(@user, admin_mode: admin_mode) }
diff --git a/config/routes/user.rb b/config/routes/user.rb
index 42fb3e02ecafe8..dc98d595e46b3a 100644
--- a/config/routes/user.rb
+++ b/config/routes/user.rb
@@ -57,6 +57,7 @@ def override_omniauth(provider, controller, path_prefix = '/users/auth')
   get '/users/successful_verification', to: 'sessions#successful_verification'
   post '/users/skip_verification_for_now', to: 'sessions#skip_verification_for_now'
   get '/users/skip_verification_confirmation', to: 'sessions#skip_verification_confirmation'
+  post '/users/fallback_to_email_otp', to: 'sessions#fallback_to_email_otp'
 
   # Redirect on GitHub authorization request errors. E.g. it could happen when user:
   # 1. cancel authorization the GitLab OAuth app via GitHub to import GitHub repos
diff --git a/locale/gitlab.pot b/locale/gitlab.pot
index 8f8f9f7b836f05..71f52c8ece26dd 100644
--- a/locale/gitlab.pot
+++ b/locale/gitlab.pot
@@ -26316,6 +26316,9 @@ msgstr ""
 msgid "Enter one or more user ID separated by commas"
 msgstr ""
 
+msgid "Enter recovery code"
+msgstr ""
+
 msgid "Enter text"
 msgstr ""
 
@@ -28212,6 +28215,9 @@ msgstr ""
 msgid "Failed to save timelog"
 msgstr ""
 
+msgid "Failed to send email"
+msgstr ""
+
 msgid "Failed to set due date because the date format is invalid."
 msgstr ""
 
@@ -33171,6 +33177,9 @@ msgstr ""
 msgid "Hashed storage can't be disabled anymore for new projects"
 msgstr ""
 
+msgid "Having trouble signing in? %{recoveryCodeLink} or %{sendCodeLink}."
+msgstr ""
+
 msgid "Header logo"
 msgstr ""
 
@@ -43899,6 +43908,9 @@ msgstr ""
 msgid "Not permitted to update requirement control"
 msgstr ""
 
+msgid "Not permitted."
+msgstr ""
+
 msgid "Not ready yet. Try again later."
 msgstr ""
 
@@ -62236,6 +62248,9 @@ msgstr ""
 msgid "Session ID"
 msgstr ""
 
+msgid "Session expired."
+msgstr ""
+
 msgid "SessionExpire|Please, sign in again. To avoid data loss, if you have unsaved edits, dismiss the modal and copy the unsaved text before sign in again."
 msgstr ""
 
@@ -69734,6 +69749,9 @@ msgstr ""
 msgid "Unable to send approval request to administrator."
 msgstr ""
 
+msgid "Unable to send code."
+msgstr ""
+
 msgid "Unable to sign in to group with SAML: \"%{reason}\""
 msgstr ""
 
@@ -72019,6 +72037,9 @@ msgstr ""
 msgid "Various settings that affect GitLab performance."
 msgstr ""
 
+msgid "Verification code has been sent to your email address."
+msgstr ""
+
 msgid "Verification status"
 msgstr ""
 
@@ -79877,6 +79898,9 @@ msgstr ""
 msgid "selective_code_owner_removals can only be enabled when retain_approvals_on_push is enabled"
 msgstr ""
 
+msgid "send code to email address"
+msgstr ""
+
 msgid "service %{service_num} doesn't exist"
 msgstr ""
 
-- 
GitLab


From 190e67356514ccce294c74c9bf5d99cb7cd4eebd Mon Sep 17 00:00:00 2001
From: Jennifer Li <jli@gitlab.com>
Date: Mon, 20 Oct 2025 11:07:33 -0700
Subject: [PATCH 2/8] Add link for recovery code docs

---
 .../webauthn/components/authenticate.vue              | 11 +++++++----
 app/controllers/sessions_controller.rb                |  4 +---
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/app/assets/javascripts/authentication/webauthn/components/authenticate.vue b/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
index 85fd23b359d022..faebde98348d35 100644
--- a/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
+++ b/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
@@ -1,8 +1,8 @@
 <script>
-/* global __ */
 import { GlButton, GlForm, GlLink, GlSprintf } from '@gitlab/ui';
 import Vue from 'vue';
 import csrf from '~/lib/utils/csrf';
+import { __ } from '~/locale';
 import EmailVerification from '~/sessions/new/components/email_verification.vue';
 import { supported, convertGetParams, convertGetResponse } from '../util';
 import { WEBAUTHN_AUTHENTICATE } from '../constants';
@@ -124,10 +124,10 @@ export default {
             });
           }
         } else {
-          throw new Error(data.message || __('Failed to send email'));
+          throw new Error(data.message || __('Failed to send email otp'));
         }
       } catch (err) {
-        // console.error(__('Failed to send email OTP:'), err);
+        throw new Error('Fallback to email otp failed during sendEmailOtp method.');
       }
     },
     async authenticate() {
@@ -212,7 +212,10 @@ export default {
         :message="__('Having trouble signing in? %{recoveryCodeLink} or %{sendCodeLink}.')"
       >
         <template #recoveryCodeLink>
-          <gl-link href="#" @click.prevent="switchToFallbackUI">
+          <gl-link
+            href="https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication/#recovery-codes"
+            target="_blank"
+          >
             {{ __('Enter recovery code') }}
           </gl-link>
         </template>
diff --git a/app/controllers/sessions_controller.rb b/app/controllers/sessions_controller.rb
index cf26e594a9f479..5f6c476822713b 100644
--- a/app/controllers/sessions_controller.rb
+++ b/app/controllers/sessions_controller.rb
@@ -121,7 +121,6 @@ def fallback_to_email_otp
       if !treat_as_locked?(user) && Feature.enabled?(:email_based_mfa, user)
         send_otp_with_email(user, secondary_email: nil, reason: VerifiesWithEmail::VERIFICATION_REASON_EMAIL_OTP)
 
-        # Redirect to login page - verify_with_email will show email verification form
         render json: {
           success: true,
           message: _('Verification code has been sent to your email address.'),
@@ -129,8 +128,7 @@ def fallback_to_email_otp
             username: user.username,
             obfuscatedEmail: obfuscated_email(user.email),
             verifyPath: session_path(:user),
-            resendPath: users_resend_verification_code_path,
-            skipPath: nil
+            resendPath: users_resend_verification_code_path
           }
         }, status: :ok
       else
-- 
GitLab


From 5da6f4f4b54dcf3b313b3a69781485898b008e30 Mon Sep 17 00:00:00 2001
From: Jennifer Li <jli@gitlab.com>
Date: Mon, 20 Oct 2025 14:01:12 -0700
Subject: [PATCH 3/8] Add sessions controller spec

---
 app/controllers/sessions_controller.rb        |  5 +-
 app/helpers/sessions_helper.rb                |  4 +-
 .../_totp_recovery_code_or_webauthn.html.haml |  1 +
 locale/gitlab.pot                             |  4 +-
 spec/controllers/sessions_controller_spec.rb  | 87 +++++++++++++++++++
 5 files changed, 96 insertions(+), 5 deletions(-)

diff --git a/app/controllers/sessions_controller.rb b/app/controllers/sessions_controller.rb
index 5f6c476822713b..b08d0ac2e0ae88 100644
--- a/app/controllers/sessions_controller.rb
+++ b/app/controllers/sessions_controller.rb
@@ -118,7 +118,7 @@ def fallback_to_email_otp
       clear_two_factor_attempt!
       session[:verification_user_id] = user.id
 
-      if !treat_as_locked?(user) && Feature.enabled?(:email_based_mfa, user)
+      if !treat_as_locked?(user)
         send_otp_with_email(user, secondary_email: nil, reason: VerifiesWithEmail::VERIFICATION_REASON_EMAIL_OTP)
 
         render json: {
@@ -132,7 +132,8 @@ def fallback_to_email_otp
           }
         }, status: :ok
       else
-        render json: { success: false, message: _('Unable to send code.') }, status: :unprocessable_entity
+        render json: { success: false, message: _('Unable to send code to locked user.') },
+          status: :unprocessable_entity
       end
     else
       render json: { success: false, message: _('Not permitted.') }, status: :bad_request
diff --git a/app/helpers/sessions_helper.rb b/app/helpers/sessions_helper.rb
index 8d77e5c6c16185..221b1a646a9046 100644
--- a/app/helpers/sessions_helper.rb
+++ b/app/helpers/sessions_helper.rb
@@ -35,7 +35,9 @@ def verification_data(user)
   end
 
   def fallback_to_email_otp_permitted?(user)
-    user.email_otp_required_after && user.email_otp_required_after <= Time.zone.today
+    Feature.enabled?(:email_based_mfa, user) &&
+      user.email_otp_required_after &&
+      user.email_otp_required_after <= Time.zone.today
   end
 
   def webauthn_authentication_data(user, admin_mode: false)
diff --git a/app/views/devise/shared/_totp_recovery_code_or_webauthn.html.haml b/app/views/devise/shared/_totp_recovery_code_or_webauthn.html.haml
index 25e05b9da247bf..c244f1f08a8107 100644
--- a/app/views/devise/shared/_totp_recovery_code_or_webauthn.html.haml
+++ b/app/views/devise/shared/_totp_recovery_code_or_webauthn.html.haml
@@ -5,6 +5,7 @@
 = gitlab_ui_form_for(:user, url: target_path, method: :post, html: { class: "gl-show-field-errors js-2fa-form #{'hidden' if @user.two_factor_webauthn_enabled?}", aria: { live: 'assertive' }}) do |f|
   .form-group
     = f.label :otp_attempt, _('Enter verification code')
+    -# Note: we use inputmode="numeric", because TOTP. However, recovery codes are alphanumeric.
     = f.text_field :otp_attempt, class: 'form-control gl-form-input', required: true, autofocus: true, autocomplete: 'off', inputmode: 'numeric', title: _('This field is required.'), data: { testid: 'two-fa-code-field' }
     %p.form-text.gl-text-subtle.hint
       = _("Enter the code from your two-factor authenticator app. If you've lost your device, you can enter one of your recovery codes.")
diff --git a/locale/gitlab.pot b/locale/gitlab.pot
index 71f52c8ece26dd..c7a6acb4f3def0 100644
--- a/locale/gitlab.pot
+++ b/locale/gitlab.pot
@@ -28215,7 +28215,7 @@ msgstr ""
 msgid "Failed to save timelog"
 msgstr ""
 
-msgid "Failed to send email"
+msgid "Failed to send email otp"
 msgstr ""
 
 msgid "Failed to set due date because the date format is invalid."
@@ -69749,7 +69749,7 @@ msgstr ""
 msgid "Unable to send approval request to administrator."
 msgstr ""
 
-msgid "Unable to send code."
+msgid "Unable to send code to locked user."
 msgstr ""
 
 msgid "Unable to sign in to group with SAML: \"%{reason}\""
diff --git a/spec/controllers/sessions_controller_spec.rb b/spec/controllers/sessions_controller_spec.rb
index 2716c9ed03eca5..21b5ea9925f5bf 100644
--- a/spec/controllers/sessions_controller_spec.rb
+++ b/spec/controllers/sessions_controller_spec.rb
@@ -825,4 +825,91 @@ def authenticate_2fa(user_params)
       end
     end
   end
+
+  describe '#fallback_to_email_otp' do
+    context 'when user has email_otp_required_after set to nil' do
+      let(:user) { create(:user, email_otp_required_after: nil) }
+
+      it 'is not permitted to fallback to email otp' do
+        post :fallback_to_email_otp, params: { user: { login: user.username } }
+
+        expect(json_response).to match({
+          'success' => false,
+          'message' => 'Not permitted.'
+        })
+      end
+    end
+
+    context 'when user has email_otp_required_after set to the future' do
+      let(:user) { create(:user, email_otp_required_after: Time.zone.now + 1.day) }
+
+      it 'is not permitted to fallback to email otp' do
+        post :fallback_to_email_otp, params: { user: { login: user.username } }
+
+        expect(json_response).to match({
+          'success' => false,
+          'message' => 'Not permitted.'
+        })
+      end
+    end
+
+    context 'when user has email_otp_required_after set to the past' do
+      let(:user) { create(:user, email: 'user1@example.org', email_otp_required_after: Time.zone.now - 1.day) }
+
+      context 'when email_based_mfa ff is disabled for the user' do
+        before do
+          Feature.disable(:email_based_mfa, user)
+        end
+
+        it 'is not permitted to fallback to email otp' do
+          post :fallback_to_email_otp, params: { user: { login: user.username } }
+          expect(json_response).to match({
+            'success' => false,
+            'message' => 'Not permitted.'
+          })
+        end
+      end
+
+      context 'when email_based_mfa ff is enabled for the user' do
+        before do
+          Feature.enable(:email_based_mfa, user)
+        end
+
+        context 'when user is locked' do
+          before do
+            user.update!(unlock_token: '1234')
+          end
+
+          it 'returns error' do
+            post :fallback_to_email_otp, params: { user: { login: user.username } }
+
+            expect(json_response).to match({
+              'success' => false,
+              'message' => 'Unable to send code to locked user.'
+            })
+          end
+        end
+
+        context 'when user is not treated as locked' do
+          it 'is permitted to fallback to email otp' do
+            post :fallback_to_email_otp, params: { user: { login: user.username } }
+
+            expect(session[:verification_user_id]).to eq(user.id)
+            expect(response).to have_gitlab_http_status(:ok)
+
+            expect(json_response).to match({
+              'success' => true,
+              'message' => 'Verification code has been sent to your email address.',
+              'email_verification_data' => {
+                'obfuscatedEmail' => 'us***@e******.org',
+                'resendPath' => '/users/resend_verification_code',
+                'username' => user.username,
+                'verifyPath' => '/users/sign_in'
+              }
+            })
+          end
+        end
+      end
+    end
+  end
 end
-- 
GitLab


From 21ba7ea7f9ba9828bfdb8aceec87e3777d2cbfc7 Mon Sep 17 00:00:00 2001
From: Jennifer Li <jli@gitlab.com>
Date: Mon, 20 Oct 2025 19:44:18 -0700
Subject: [PATCH 4/8] Add new tests in authenticate_spec

---
 .../webauthn/components/authenticate.vue      |   4 +-
 app/assets/javascripts/sessions/new/index.js  |  28 ++
 .../webauthn/components/authenticate_spec.js  | 264 +++++++++++++++++-
 3 files changed, 283 insertions(+), 13 deletions(-)

diff --git a/app/assets/javascripts/authentication/webauthn/components/authenticate.vue b/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
index faebde98348d35..bcd7185ef6643c 100644
--- a/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
+++ b/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
@@ -90,7 +90,7 @@ export default {
         const response = await fetch(this.sendEmailOtpPath, {
           method: 'POST',
           headers: {
-            'X-CSRF-Token': this.$options.csrf.token,
+            'X-CSRF-Token': csrf.token,
             'Content-Type': 'application/json',
           },
           body: JSON.stringify({
@@ -109,7 +109,7 @@ export default {
             twoFaForm.classList.add('hidden');
           }
 
-          // Initialize and show email verification component
+          // Initialize and show email verification component as backup
           const container = document.querySelector('.js-email-verification-container');
           if (container && data.email_verification_data) {
             container.classList.remove('hidden');
diff --git a/app/assets/javascripts/sessions/new/index.js b/app/assets/javascripts/sessions/new/index.js
index b2996567d9bb18..79ed21205042d4 100644
--- a/app/assets/javascripts/sessions/new/index.js
+++ b/app/assets/javascripts/sessions/new/index.js
@@ -1,5 +1,33 @@
+import Vue from 'vue';
 import { initWebauthnAuthenticate } from '~/authentication/webauthn';
+import EmailVerification from './components/email_verification.vue';
 
 export default () => {
+  // Initialize WebAuthn if present
   initWebauthnAuthenticate();
+
+  // Initialize standalone email verification if present
+  const el = document.querySelector('.js-email-verification');
+
+  if (!el) {
+    return null;
+  }
+
+  const { username, obfuscatedEmail, verifyPath, resendPath, skipPath } = el.dataset;
+
+  return new Vue({
+    el,
+    name: 'EmailVerificationRoot',
+    render(createElement) {
+      return createElement(EmailVerification, {
+        props: {
+          username,
+          obfuscatedEmail,
+          verifyPath,
+          resendPath,
+          skipPath,
+        },
+      });
+    },
+  });
 };
diff --git a/spec/frontend/authentication/webauthn/components/authenticate_spec.js b/spec/frontend/authentication/webauthn/components/authenticate_spec.js
index b087708ae96eae..ebe19b0ee7f5b8 100644
--- a/spec/frontend/authentication/webauthn/components/authenticate_spec.js
+++ b/spec/frontend/authentication/webauthn/components/authenticate_spec.js
@@ -1,3 +1,5 @@
+import { GlLink } from '@gitlab/ui';
+import { DOCS_URL_IN_EE_DIR } from 'jh_else_ce/lib/utils/url_utility';
 import htmlWebauthnAuthenticate from 'test_fixtures/webauthn/authenticate.html';
 import { setHTMLFixture, resetHTMLFixture } from 'helpers/fixtures';
 import waitForPromises from 'helpers/wait_for_promises';
@@ -6,6 +8,11 @@ import { mountExtended } from 'helpers/vue_test_utils_helper';
 import MockWebAuthnDevice from '../mock_webauthn_device';
 import { useMockNavigatorCredentials } from '../util';
 
+jest.mock('~/lib/utils/csrf', () => ({
+  token: 'mock-csrf-token',
+  headerKey: 'X-CSRF-Token',
+}));
+
 let wrapper;
 
 const mockResponse = {
@@ -16,24 +23,26 @@ const mockResponse = {
   getClientExtensionResults: () => {},
 };
 
-const createComponent = () => {
+const createComponent = (propsData = {}) => {
   wrapper = mountExtended(WebAuthnAuthenticate, {
     propsData: {
-      webauthnParams:
+      webauthnParams: {
         // we need some valid base64 for base64ToBuffer
         // so we use "YQ==" = base64("a")
-        {
-          challenge: 'YQ==',
-          timeout: 120000,
-          allowCredentials: [
-            { type: 'public-key', id: 'YQ==' },
-            { type: 'public-key', id: 'YQ==' },
-          ],
-          userVerification: 'discouraged',
-        },
+        challenge: 'YQ==',
+        timeout: 120000,
+        allowCredentials: [
+          { type: 'public-key', id: 'YQ==' },
+          { type: 'public-key', id: 'YQ==' },
+        ],
+        userVerification: 'discouraged',
+      },
       targetPath: '/webauthn',
       renderRememberMe: true,
       rememberMe: 'Remember me',
+      sendEmailOtpPath: '',
+      username: '',
+      ...propsData,
     },
   });
 };
@@ -49,6 +58,9 @@ describe('WebAuthnAuthenticate', () => {
   const findFallbackElement = () => document.querySelector('.js-2fa-form');
   const findInProgress = () => wrapper.find('p');
   const findAuthenticated = () => wrapper.find('#js-authenticate-token-2fa-authenticated p');
+  const findFooter = () => wrapper.findByText(/Having trouble signing in\?/);
+  const findRecoveryCodeLink = () => wrapper.findAllComponents(GlLink).at(0);
+  const findEmailOtpLink = () => wrapper.findAllComponents(GlLink).at(1);
 
   const expectAuthenticated = () => {
     expect(findAuthenticated().text()).toMatchInterpolatedText(
@@ -131,4 +143,234 @@ describe('WebAuthnAuthenticate', () => {
       });
     });
   });
+
+  describe('email OTP fallback', () => {
+    describe('when sendEmailOtpPath is not provided', () => {
+      beforeEach(() => {
+        createComponent({ sendEmailOtpPath: '' });
+        webAuthnDevice.rejectAuthenticateRequest(new DOMException());
+
+        return waitForPromises();
+      });
+
+      it('does not show the footer', () => {
+        expect(findFooter().exists()).toBe(false);
+      });
+    });
+
+    describe('when sendEmailOtpPath is provided', () => {
+      beforeEach(() => {
+        createComponent({
+          sendEmailOtpPath: '/users/fallback_to_email_otp',
+          username: 'testuser',
+        });
+      });
+
+      it('does not show footer when there is no error', () => {
+        expect(findFooter().exists()).toBe(false);
+      });
+
+      describe('when authentication fails', () => {
+        beforeEach(() => {
+          webAuthnDevice.rejectAuthenticateRequest(new DOMException());
+
+          return waitForPromises();
+        });
+
+        it('shows the footer with helpful links', () => {
+          expect(findFooter().exists()).toBe(true);
+          expect(wrapper.text()).toContain('Having trouble signing in?');
+          expect(wrapper.text()).toContain('Enter recovery code');
+          expect(wrapper.text()).toContain('send code to email address');
+        });
+
+        it('recovery code link points to documentation', () => {
+          const link = findRecoveryCodeLink();
+
+          expect(link.attributes('href')).toBe(
+            `${DOCS_URL_IN_EE_DIR}/user/profile/account/two_factor_authentication/#recovery-codes`,
+          );
+          expect(link.attributes('target')).toBe('_blank');
+        });
+
+        it('email OTP link triggers sendEmailOtp', async () => {
+          jest.spyOn(wrapper.vm, 'sendEmailOtp').mockResolvedValue();
+
+          const link = findEmailOtpLink();
+          await link.trigger('click');
+
+          expect(wrapper.vm.sendEmailOtp).toHaveBeenCalled();
+        });
+      });
+
+      describe('sendEmailOtp method', () => {
+        let fetchMock;
+
+        beforeEach(() => {
+          fetchMock = jest.spyOn(global, 'fetch');
+          window.gon = { csrf_token: 'test-csrf-token' };
+          setHTMLFixture(`
+            ${htmlWebauthnAuthenticate}
+            <div class="js-2fa-form"></div>
+            <div class="js-email-verification-container hidden"></div>
+          `);
+
+          createComponent({
+            sendEmailOtpPath: '/users/fallback_to_email_otp',
+            username: 'testuser',
+          });
+        });
+
+        afterEach(() => {
+          fetchMock.mockRestore();
+        });
+
+        it('sends POST request with correct parameters', async () => {
+          fetchMock.mockResolvedValue({
+            ok: true,
+            json: jest.fn().mockResolvedValue({
+              success: true,
+              email_verification_data: {
+                username: 'testuser',
+                obfuscatedEmail: 't***@example.com',
+                verifyPath: '/users/sign_in',
+                resendPath: '/users/resend_verification_code',
+              },
+            }),
+          });
+
+          await wrapper.vm.sendEmailOtp();
+
+          expect(fetchMock).toHaveBeenCalledWith('/users/fallback_to_email_otp', {
+            method: 'POST',
+            headers: {
+              'X-CSRF-Token': expect.any(String),
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+              user: { login: 'testuser' },
+            }),
+          });
+        });
+
+        it('sets fallbackMode to true on success', async () => {
+          fetchMock.mockResolvedValue({
+            ok: true,
+            json: jest.fn().mockResolvedValue({
+              success: true,
+              email_verification_data: {},
+            }),
+          });
+
+          await wrapper.vm.sendEmailOtp();
+          await waitForPromises();
+
+          expect(wrapper.vm.fallbackMode).toBe(true);
+        });
+
+        it('hides 2FA form on success', async () => {
+          const twoFaForm = document.querySelector('.js-2fa-form');
+
+          fetchMock.mockResolvedValue({
+            ok: true,
+            json: jest.fn().mockResolvedValue({
+              success: true,
+              email_verification_data: {},
+            }),
+          });
+
+          await wrapper.vm.sendEmailOtp();
+          await waitForPromises();
+
+          expect(twoFaForm.classList.contains('hidden')).toBe(true);
+        });
+
+        it('shows email verification container on success', async () => {
+          const container = document.querySelector('.js-email-verification-container');
+
+          fetchMock.mockResolvedValue({
+            ok: true,
+            json: jest.fn().mockResolvedValue({
+              success: true,
+              email_verification_data: {
+                username: 'testuser',
+                obfuscatedEmail: 't***@example.com',
+                verifyPath: '/users/sign_in',
+                resendPath: '/users/resend_verification_code',
+              },
+            }),
+          });
+
+          await wrapper.vm.sendEmailOtp();
+          await waitForPromises();
+
+          expect(container.classList.contains('hidden')).toBe(false);
+        });
+
+        it('throws error when response is not ok', async () => {
+          fetchMock.mockResolvedValue({
+            ok: false,
+            json: jest.fn().mockResolvedValue({
+              success: false,
+              message: 'Not permitted',
+            }),
+          });
+
+          await expect(wrapper.vm.sendEmailOtp()).rejects.toThrow(
+            'Fallback to email otp failed during sendEmailOtp method.',
+          );
+        });
+
+        it('throws error when success is false', async () => {
+          fetchMock.mockResolvedValue({
+            ok: true,
+            json: jest.fn().mockResolvedValue({
+              success: false,
+              message: 'Session expired',
+            }),
+          });
+
+          await expect(wrapper.vm.sendEmailOtp()).rejects.toThrow(
+            'Fallback to email otp failed during sendEmailOtp method.',
+          );
+        });
+
+        it('throws error when fetch fails', async () => {
+          fetchMock.mockRejectedValue(new Error('Network error'));
+
+          await expect(wrapper.vm.sendEmailOtp()).rejects.toThrow(
+            'Fallback to email otp failed during sendEmailOtp method.',
+          );
+        });
+      });
+    });
+  });
+
+  describe('switchToFallbackUI', () => {
+    beforeEach(() => {
+      createComponent();
+    });
+
+    it('sets fallbackMode to true', () => {
+      wrapper.vm.switchToFallbackUI();
+
+      expect(wrapper.vm.fallbackMode).toBe(true);
+    });
+
+    it('removes hidden class from 2FA form if it exists', () => {
+      const form = findFallbackElement();
+      form.classList.add('hidden');
+
+      wrapper.vm.switchToFallbackUI();
+
+      expect(form.classList.contains('hidden')).toBe(false);
+    });
+
+    it('does not throw error if 2FA form does not exist', () => {
+      const form = findFallbackElement();
+      form.remove();
+
+      expect(() => wrapper.vm.switchToFallbackUI()).not.toThrow();
+    });
+  });
 });
-- 
GitLab


From b4a5d79ce03d34c3eaaba350f08ff534213761a0 Mon Sep 17 00:00:00 2001
From: Jennifer Li <jli@gitlab.com>
Date: Tue, 21 Oct 2025 09:59:29 -0700
Subject: [PATCH 5/8] Fix broken frontend specs

---
 .../webauthn/components/authenticate_spec.js  | 25 ++++---------------
 1 file changed, 5 insertions(+), 20 deletions(-)

diff --git a/spec/frontend/authentication/webauthn/components/authenticate_spec.js b/spec/frontend/authentication/webauthn/components/authenticate_spec.js
index ebe19b0ee7f5b8..51bb5151c047f1 100644
--- a/spec/frontend/authentication/webauthn/components/authenticate_spec.js
+++ b/spec/frontend/authentication/webauthn/components/authenticate_spec.js
@@ -1,6 +1,6 @@
 import { GlLink } from '@gitlab/ui';
-import { DOCS_URL_IN_EE_DIR } from 'jh_else_ce/lib/utils/url_utility';
 import htmlWebauthnAuthenticate from 'test_fixtures/webauthn/authenticate.html';
+import { DOCS_URL_IN_EE_DIR } from 'jh_else_ce/lib/utils/url_utility';
 import { setHTMLFixture, resetHTMLFixture } from 'helpers/fixtures';
 import waitForPromises from 'helpers/wait_for_promises';
 import WebAuthnAuthenticate from '~/authentication/webauthn/components/authenticate.vue';
@@ -179,7 +179,6 @@ describe('WebAuthnAuthenticate', () => {
 
         it('shows the footer with helpful links', () => {
           expect(findFooter().exists()).toBe(true);
-          expect(wrapper.text()).toContain('Having trouble signing in?');
           expect(wrapper.text()).toContain('Enter recovery code');
           expect(wrapper.text()).toContain('send code to email address');
         });
@@ -190,7 +189,6 @@ describe('WebAuthnAuthenticate', () => {
           expect(link.attributes('href')).toBe(
             `${DOCS_URL_IN_EE_DIR}/user/profile/account/two_factor_authentication/#recovery-codes`,
           );
-          expect(link.attributes('target')).toBe('_blank');
         });
 
         it('email OTP link triggers sendEmailOtp', async () => {
@@ -203,7 +201,7 @@ describe('WebAuthnAuthenticate', () => {
         });
       });
 
-      describe('sendEmailOtp method', () => {
+      describe('sendEmailOtp', () => {
         let fetchMock;
 
         beforeEach(() => {
@@ -225,7 +223,7 @@ describe('WebAuthnAuthenticate', () => {
           fetchMock.mockRestore();
         });
 
-        it('sends POST request with correct parameters', async () => {
+        it('sends POST request with email_verification_data', async () => {
           fetchMock.mockResolvedValue({
             ok: true,
             json: jest.fn().mockResolvedValue({
@@ -351,26 +349,13 @@ describe('WebAuthnAuthenticate', () => {
       createComponent();
     });
 
-    it('sets fallbackMode to true', () => {
-      wrapper.vm.switchToFallbackUI();
-
-      expect(wrapper.vm.fallbackMode).toBe(true);
-    });
-
-    it('removes hidden class from 2FA form if it exists', () => {
+    it('removes hidden class from 2FA form if it exists, sets fallbackMode to true', () => {
       const form = findFallbackElement();
       form.classList.add('hidden');
 
       wrapper.vm.switchToFallbackUI();
 
-      expect(form.classList.contains('hidden')).toBe(false);
-    });
-
-    it('does not throw error if 2FA form does not exist', () => {
-      const form = findFallbackElement();
-      form.remove();
-
-      expect(() => wrapper.vm.switchToFallbackUI()).not.toThrow();
+      expect(wrapper.vm.fallbackMode).toBe(true);
     });
   });
 });
-- 
GitLab


From 96023a09002219374771b019c37e9582b5e0a7bf Mon Sep 17 00:00:00 2001
From: Jennifer Li <jli@gitlab.com>
Date: Tue, 21 Oct 2025 11:08:36 -0700
Subject: [PATCH 6/8] Update authenticate vue component to send request 
 through axios

---
 .../webauthn/components/authenticate.vue      |  34 +++--
 app/assets/javascripts/sessions/new/index.js  |   3 +-
 .../webauthn/components/authenticate_spec.js  | 122 ++++++++----------
 3 files changed, 70 insertions(+), 89 deletions(-)

diff --git a/app/assets/javascripts/authentication/webauthn/components/authenticate.vue b/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
index bcd7185ef6643c..a45fea4bcd8926 100644
--- a/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
+++ b/app/assets/javascripts/authentication/webauthn/components/authenticate.vue
@@ -2,6 +2,7 @@
 import { GlButton, GlForm, GlLink, GlSprintf } from '@gitlab/ui';
 import Vue from 'vue';
 import csrf from '~/lib/utils/csrf';
+import axios from '~/lib/utils/axios_utils';
 import { __ } from '~/locale';
 import EmailVerification from '~/sessions/new/components/email_verification.vue';
 import { supported, convertGetParams, convertGetResponse } from '../util';
@@ -74,10 +75,7 @@ export default {
     },
     switchToFallbackUI() {
       this.fallbackMode = true;
-      const form = document.querySelector('.js-2fa-form');
-      if (form) {
-        form.classList.remove('hidden');
-      }
+      document.querySelector('.js-2fa-form').classList.remove('hidden');
     },
     isWebauthnSupported() {
       return supported();
@@ -87,19 +85,17 @@ export default {
     },
     async sendEmailOtp() {
       try {
-        const response = await fetch(this.sendEmailOtpPath, {
-          method: 'POST',
-          headers: {
-            'X-CSRF-Token': csrf.token,
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify({
+        const response = await axios({
+          method: 'post',
+          url: this.sendEmailOtpPath,
+          data: {
             user: { login: this.username },
-          }),
+          },
         });
 
-        const data = await response.json();
-        if (response.ok && data.success) {
+        const { data } = response;
+
+        if (data.success) {
           // Hide WebAuthn UI
           this.fallbackMode = true;
 
@@ -109,7 +105,7 @@ export default {
             twoFaForm.classList.add('hidden');
           }
 
-          // Initialize and show email verification component as backup
+          // Initialize and show email verification component
           const container = document.querySelector('.js-email-verification-container');
           if (container && data.email_verification_data) {
             container.classList.remove('hidden');
@@ -124,10 +120,12 @@ export default {
             });
           }
         } else {
-          throw new Error(data.message || __('Failed to send email otp'));
+          this.errorMessage = data.message || __('Failed to send email otp');
         }
-      } catch (err) {
-        throw new Error('Fallback to email otp failed during sendEmailOtp method.');
+      } catch (error) {
+        const errorMessage =
+          error.response?.data?.message || error.message || __('Failed to send email otp');
+        this.errorMessage = errorMessage;
       }
     },
     async authenticate() {
diff --git a/app/assets/javascripts/sessions/new/index.js b/app/assets/javascripts/sessions/new/index.js
index 79ed21205042d4..08fa16831118d1 100644
--- a/app/assets/javascripts/sessions/new/index.js
+++ b/app/assets/javascripts/sessions/new/index.js
@@ -3,10 +3,9 @@ import { initWebauthnAuthenticate } from '~/authentication/webauthn';
 import EmailVerification from './components/email_verification.vue';
 
 export default () => {
-  // Initialize WebAuthn if present
   initWebauthnAuthenticate();
-
   // Initialize standalone email verification if present
+  // This ensures the regular email OTP workflow still works as expected
   const el = document.querySelector('.js-email-verification');
 
   if (!el) {
diff --git a/spec/frontend/authentication/webauthn/components/authenticate_spec.js b/spec/frontend/authentication/webauthn/components/authenticate_spec.js
index 51bb5151c047f1..85e0fdfa01eb59 100644
--- a/spec/frontend/authentication/webauthn/components/authenticate_spec.js
+++ b/spec/frontend/authentication/webauthn/components/authenticate_spec.js
@@ -5,13 +5,12 @@ import { setHTMLFixture, resetHTMLFixture } from 'helpers/fixtures';
 import waitForPromises from 'helpers/wait_for_promises';
 import WebAuthnAuthenticate from '~/authentication/webauthn/components/authenticate.vue';
 import { mountExtended } from 'helpers/vue_test_utils_helper';
+import axios from '~/lib/utils/axios_utils';
 import MockWebAuthnDevice from '../mock_webauthn_device';
 import { useMockNavigatorCredentials } from '../util';
 
-jest.mock('~/lib/utils/csrf', () => ({
-  token: 'mock-csrf-token',
-  headerKey: 'X-CSRF-Token',
-}));
+jest.mock('~/lib/utils/csrf', () => ({ token: 'mock-csrf-token' }));
+jest.mock('~/lib/utils/axios_utils', () => jest.fn());
 
 let wrapper;
 
@@ -27,8 +26,6 @@ const createComponent = (propsData = {}) => {
   wrapper = mountExtended(WebAuthnAuthenticate, {
     propsData: {
       webauthnParams: {
-        // we need some valid base64 for base64ToBuffer
-        // so we use "YQ==" = base64("a")
         challenge: 'YQ==',
         timeout: 120000,
         allowCredentials: [
@@ -78,6 +75,7 @@ describe('WebAuthnAuthenticate', () => {
 
   afterEach(() => {
     resetHTMLFixture();
+    jest.clearAllMocks();
   });
 
   describe('with webauthn unavailable', () => {
@@ -202,11 +200,7 @@ describe('WebAuthnAuthenticate', () => {
       });
 
       describe('sendEmailOtp', () => {
-        let fetchMock;
-
         beforeEach(() => {
-          fetchMock = jest.spyOn(global, 'fetch');
-          window.gon = { csrf_token: 'test-csrf-token' };
           setHTMLFixture(`
             ${htmlWebauthnAuthenticate}
             <div class="js-2fa-form"></div>
@@ -219,45 +213,36 @@ describe('WebAuthnAuthenticate', () => {
           });
         });
 
-        afterEach(() => {
-          fetchMock.mockRestore();
-        });
-
         it('sends POST request with email_verification_data', async () => {
-          fetchMock.mockResolvedValue({
-            ok: true,
-            json: jest.fn().mockResolvedValue({
-              success: true,
-              email_verification_data: {
-                username: 'testuser',
-                obfuscatedEmail: 't***@example.com',
-                verifyPath: '/users/sign_in',
-                resendPath: '/users/resend_verification_code',
-              },
-            }),
-          });
+          const mockData = {
+            success: true,
+            email_verification_data: {
+              username: 'testuser',
+              obfuscatedEmail: 't***@example.com',
+              verifyPath: '/users/sign_in',
+              resendPath: '/users/resend_verification_code',
+            },
+          };
+
+          axios.mockResolvedValue({ data: mockData });
 
           await wrapper.vm.sendEmailOtp();
 
-          expect(fetchMock).toHaveBeenCalledWith('/users/fallback_to_email_otp', {
-            method: 'POST',
-            headers: {
-              'X-CSRF-Token': expect.any(String),
-              'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({
+          expect(axios).toHaveBeenCalledWith({
+            method: 'post',
+            url: '/users/fallback_to_email_otp',
+            data: {
               user: { login: 'testuser' },
-            }),
+            },
           });
         });
 
         it('sets fallbackMode to true on success', async () => {
-          fetchMock.mockResolvedValue({
-            ok: true,
-            json: jest.fn().mockResolvedValue({
+          axios.mockResolvedValue({
+            data: {
               success: true,
               email_verification_data: {},
-            }),
+            },
           });
 
           await wrapper.vm.sendEmailOtp();
@@ -269,12 +254,11 @@ describe('WebAuthnAuthenticate', () => {
         it('hides 2FA form on success', async () => {
           const twoFaForm = document.querySelector('.js-2fa-form');
 
-          fetchMock.mockResolvedValue({
-            ok: true,
-            json: jest.fn().mockResolvedValue({
+          axios.mockResolvedValue({
+            data: {
               success: true,
               email_verification_data: {},
-            }),
+            },
           });
 
           await wrapper.vm.sendEmailOtp();
@@ -286,9 +270,8 @@ describe('WebAuthnAuthenticate', () => {
         it('shows email verification container on success', async () => {
           const container = document.querySelector('.js-email-verification-container');
 
-          fetchMock.mockResolvedValue({
-            ok: true,
-            json: jest.fn().mockResolvedValue({
+          axios.mockResolvedValue({
+            data: {
               success: true,
               email_verification_data: {
                 username: 'testuser',
@@ -296,7 +279,7 @@ describe('WebAuthnAuthenticate', () => {
                 verifyPath: '/users/sign_in',
                 resendPath: '/users/resend_verification_code',
               },
-            }),
+            },
           });
 
           await wrapper.vm.sendEmailOtp();
@@ -305,40 +288,41 @@ describe('WebAuthnAuthenticate', () => {
           expect(container.classList.contains('hidden')).toBe(false);
         });
 
-        it('throws error when response is not ok', async () => {
-          fetchMock.mockResolvedValue({
-            ok: false,
-            json: jest.fn().mockResolvedValue({
-              success: false,
-              message: 'Not permitted',
-            }),
+        it('sets errorMessage when response is not ok', async () => {
+          axios.mockRejectedValue({
+            response: {
+              status: 422,
+              data: {
+                success: false,
+                message: 'Not permitted',
+              },
+            },
           });
 
-          await expect(wrapper.vm.sendEmailOtp()).rejects.toThrow(
-            'Fallback to email otp failed during sendEmailOtp method.',
-          );
+          await wrapper.vm.sendEmailOtp();
+
+          expect(wrapper.vm.errorMessage).toBe('Not permitted');
         });
 
-        it('throws error when success is false', async () => {
-          fetchMock.mockResolvedValue({
-            ok: true,
-            json: jest.fn().mockResolvedValue({
+        it('sets errorMessage when success is false', async () => {
+          axios.mockResolvedValue({
+            data: {
               success: false,
               message: 'Session expired',
-            }),
+            },
           });
 
-          await expect(wrapper.vm.sendEmailOtp()).rejects.toThrow(
-            'Fallback to email otp failed during sendEmailOtp method.',
-          );
+          await wrapper.vm.sendEmailOtp();
+
+          expect(wrapper.vm.errorMessage).toBe('Session expired');
         });
 
-        it('throws error when fetch fails', async () => {
-          fetchMock.mockRejectedValue(new Error('Network error'));
+        it('sets errorMessage when fetch fails', async () => {
+          axios.mockRejectedValue(new Error('Network error'));
 
-          await expect(wrapper.vm.sendEmailOtp()).rejects.toThrow(
-            'Fallback to email otp failed during sendEmailOtp method.',
-          );
+          await wrapper.vm.sendEmailOtp();
+
+          expect(wrapper.vm.errorMessage).toBe('Network error');
         });
       });
     });
-- 
GitLab


From 00e2500d1d47870d12601ab022ab093d9bdcb454 Mon Sep 17 00:00:00 2001
From: Jennifer Li <jli@gitlab.com>
Date: Thu, 23 Oct 2025 14:51:47 -0700
Subject: [PATCH 7/8] Add additional test cases in sessions_helper_spec

---
 app/assets/javascripts/sessions/new/index.js  |   2 -
 .../concerns/verifies_with_email.rb           |   1 -
 app/helpers/sessions_helper.rb                |   3 +-
 .../webauthn/components/authenticate_spec.js  |   5 +-
 spec/helpers/sessions_helper_spec.rb          | 178 ++++++++++++++++++
 5 files changed, 183 insertions(+), 6 deletions(-)

diff --git a/app/assets/javascripts/sessions/new/index.js b/app/assets/javascripts/sessions/new/index.js
index 08fa16831118d1..1394886db7cc3d 100644
--- a/app/assets/javascripts/sessions/new/index.js
+++ b/app/assets/javascripts/sessions/new/index.js
@@ -4,8 +4,6 @@ import EmailVerification from './components/email_verification.vue';
 
 export default () => {
   initWebauthnAuthenticate();
-  // Initialize standalone email verification if present
-  // This ensures the regular email OTP workflow still works as expected
   const el = document.querySelector('.js-email-verification');
 
   if (!el) {
diff --git a/app/controllers/concerns/verifies_with_email.rb b/app/controllers/concerns/verifies_with_email.rb
index d44c14f7e7938f..9b0adad4c9e7ad 100644
--- a/app/controllers/concerns/verifies_with_email.rb
+++ b/app/controllers/concerns/verifies_with_email.rb
@@ -156,7 +156,6 @@ def send_otp_with_email(user, secondary_email: nil, reason: VERIFICATION_REASON_
     service = Users::EmailVerification::GenerateTokenService.new(attr: :email_otp, user: user)
     raw_token, encrypted_token = service.execute
 
-    # Rails.logger.error("JLI: email otp: #{raw_token}")
     user.email_otp = encrypted_token
     user.email_otp_last_sent_at = Time.current
     user.email_otp_last_sent_to = secondary_email || user.email
diff --git a/app/helpers/sessions_helper.rb b/app/helpers/sessions_helper.rb
index 221b1a646a9046..ab7e0a35304ef5 100644
--- a/app/helpers/sessions_helper.rb
+++ b/app/helpers/sessions_helper.rb
@@ -36,7 +36,7 @@ def verification_data(user)
 
   def fallback_to_email_otp_permitted?(user)
     Feature.enabled?(:email_based_mfa, user) &&
-      user.email_otp_required_after &&
+      user.email_otp_required_after.present? &&
       user.email_otp_required_after <= Time.zone.today
   end
 
@@ -56,6 +56,7 @@ def webauthn_authentication_data(user, admin_mode: false)
       username: user.username
     }
 
+    # This is addtional data needed to complete the the email verification workflow
     data[:email_verification_data] = verification_data(user).to_json if send_email_otp_path
 
     data
diff --git a/spec/frontend/authentication/webauthn/components/authenticate_spec.js b/spec/frontend/authentication/webauthn/components/authenticate_spec.js
index 85e0fdfa01eb59..bc85ad3db3c05c 100644
--- a/spec/frontend/authentication/webauthn/components/authenticate_spec.js
+++ b/spec/frontend/authentication/webauthn/components/authenticate_spec.js
@@ -190,12 +190,13 @@ describe('WebAuthnAuthenticate', () => {
         });
 
         it('email OTP link triggers sendEmailOtp', async () => {
-          jest.spyOn(wrapper.vm, 'sendEmailOtp').mockResolvedValue();
+          const sendEmailOtpSpy = jest.spyOn(wrapper.vm, 'sendEmailOtp').mockResolvedValue();
 
           const link = findEmailOtpLink();
           await link.trigger('click');
+          await waitForPromises();
 
-          expect(wrapper.vm.sendEmailOtp).toHaveBeenCalled();
+          expect(sendEmailOtpSpy).toHaveBeenCalled();
         });
       });
 
diff --git a/spec/helpers/sessions_helper_spec.rb b/spec/helpers/sessions_helper_spec.rb
index 40e80c2a35dda0..b5656cc6f7aa5a 100644
--- a/spec/helpers/sessions_helper_spec.rb
+++ b/spec/helpers/sessions_helper_spec.rb
@@ -105,4 +105,182 @@
       it { is_expected.to be false }
     end
   end
+
+  describe '#fallback_to_email_otp_permitted?' do
+    let(:user) { build_stubbed(:user) }
+
+    context 'when email_based_mfa feature flag is disabled' do
+      before do
+        stub_feature_flags(email_based_mfa: false)
+      end
+
+      it 'returns false' do
+        expect(helper.fallback_to_email_otp_permitted?(user)).to be false
+      end
+    end
+
+    context 'when email_based_mfa feature flag is enabled' do
+      before do
+        stub_feature_flags(email_based_mfa: user)
+      end
+
+      context 'when user has email_otp_required_after set to nil' do
+        let(:user) { build_stubbed(:user, email_otp_required_after: nil) }
+
+        it 'returns false' do
+          expect(helper.fallback_to_email_otp_permitted?(user)).to be false
+        end
+      end
+
+      context 'when user has email_otp_required_after set to future date' do
+        let(:user) do
+          build_stubbed(:user, email_otp_required_after: Time.zone.today + 1.day)
+        end
+
+        it 'returns false' do
+          expect(helper.fallback_to_email_otp_permitted?(user)).to be false
+        end
+      end
+
+      context 'when user has email_otp_required_after set to today' do
+        let(:user) { build_stubbed(:user, email_otp_required_after: Time.zone.today) }
+
+        it 'returns true' do
+          expect(helper.fallback_to_email_otp_permitted?(user)).to be true
+        end
+      end
+
+      context 'when user has email_otp_required_after set to past date' do
+        let(:user) { build_stubbed(:user, email_otp_required_after: Time.zone.today - 1.day) }
+
+        it 'returns true' do
+          expect(helper.fallback_to_email_otp_permitted?(user)).to be true
+        end
+      end
+    end
+  end
+
+  describe '#webauthn_authentication_data' do
+    let(:user) { build_stubbed(:user) }
+    let(:remember_me_enabled) { true }
+
+    before do
+      allow(helper).to receive_messages(remember_me_enabled?: remember_me_enabled,
+        params: { user: { remember_me: '1' } })
+    end
+
+    context 'when admin_mode is false' do
+      it 'returns correct target_path' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data[:target_path]).to eq(user_session_path)
+      end
+
+      it 'returns render_remember_me as true when remember_me is enabled' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data[:render_remember_me]).to eq('true')
+      end
+
+      it 'returns remember_me value from params' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data[:remember_me]).to eq('1')
+      end
+    end
+
+    context 'when admin_mode is true' do
+      it 'returns admin session path as target_path' do
+        data = helper.webauthn_authentication_data(user, admin_mode: true)
+
+        expect(data[:target_path]).to eq(admin_session_path)
+      end
+
+      it 'returns render_remember_me as false' do
+        data = helper.webauthn_authentication_data(user, admin_mode: true)
+
+        expect(data[:render_remember_me]).to eq('false')
+      end
+    end
+
+    context 'when remember_me is disabled' do
+      let(:remember_me_enabled) { false }
+
+      it 'returns render_remember_me as false' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data[:render_remember_me]).to eq('false')
+      end
+    end
+
+    context 'when user params is not present' do
+      before do
+        allow(helper).to receive(:params).and_return({})
+      end
+
+      it 'returns default remember_me value of 0' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data[:remember_me]).to eq(0)
+      end
+    end
+
+    context 'when fallback_to_email_otp is permitted' do
+      before do
+        allow(helper).to receive(:fallback_to_email_otp_permitted?).and_return(true)
+        allow(helper).to receive(:verification_data).with(user).and_return({
+          username: user.username,
+          obfuscated_email: 'u***@example.com',
+          verify_path: '/verify',
+          resend_path: '/resend',
+          skip_path: nil
+        })
+      end
+
+      it 'includes send_email_otp_path' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data[:send_email_otp_path]).to eq(users_fallback_to_email_otp_path)
+      end
+
+      it 'includes username' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data[:username]).to eq(user.username)
+      end
+
+      it 'includes email_verification_data as JSON' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data[:email_verification_data]).to be_present
+        parsed_data = Gitlab::Json.parse(data[:email_verification_data])
+        expect(parsed_data['username']).to eq(user.username)
+        expect(parsed_data['obfuscated_email']).to eq('u***@example.com')
+      end
+    end
+
+    context 'when fallback_to_email_otp is not permitted' do
+      before do
+        allow(helper).to receive(:fallback_to_email_otp_permitted?).and_return(false)
+      end
+
+      it 'does not include send_email_otp_path' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data[:send_email_otp_path]).to be_nil
+      end
+
+      it 'includes username' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data[:username]).to eq(user.username)
+      end
+
+      it 'does not include email_verification_data' do
+        data = helper.webauthn_authentication_data(user)
+
+        expect(data.key?(:email_verification_data)).to be false
+      end
+    end
+  end
 end
-- 
GitLab


From 6184f2bbcf5fbc576726cf081343ce74b9e16fa1 Mon Sep 17 00:00:00 2001
From: Jennifer Li <jli@gitlab.com>
Date: Thu, 23 Oct 2025 16:18:03 -0700
Subject: [PATCH 8/8] Add email otp fallback integration test

---
 spec/features/users/login_spec.rb | 63 +++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/spec/features/users/login_spec.rb b/spec/features/users/login_spec.rb
index 812a5ceaa01eda..7a6e9543abc1b5 100644
--- a/spec/features/users/login_spec.rb
+++ b/spec/features/users/login_spec.rb
@@ -7,6 +7,7 @@
   include UserLoginHelper
   include SessionHelpers
   include Features::TwoFactorHelpers
+  include EmailHelpers
 
   before do
     stub_authentication_activity_metrics(debug: true)
@@ -387,6 +388,68 @@ def enter_code(code, only_two_factor_webauthn_enabled: false)
       end
     end
 
+    context 'when signing in with WebAuthn' do
+      let(:user) { create(:user, :two_factor_via_webauthn) }
+      let(:current_organization) { user.organization }
+
+      before do
+        visit new_user_session_path
+        fill_in 'user_login', with: user.username
+        fill_in 'user_password', with: user.password
+        click_button 'Sign in'
+      end
+
+      context 'Fallback to email OTP' do
+        context 'when email_based_mfa feature flag is disabled' do
+          before do
+            stub_feature_flags(email_based_mfa: false)
+          end
+
+          it 'does not show the email OTP fallback footer' do
+            expect(page).not_to have_content('Having trouble signing in?')
+            expect(page).not_to have_link('send code to email address')
+          end
+        end
+
+        context 'when email_based_mfa feature flag is enabled' do
+          before do
+            stub_feature_flags(email_based_mfa: user)
+          end
+
+          # we will not be testing different email_otp_required_after values
+          # since this is covered in the unit test level
+          context 'when user has email_otp_required_after set to past date' do
+            let(:user) { create(:user, :two_factor_via_webauthn, email_otp_required_after: 1.day.ago) }
+
+            context 'when WebAuthn authentication fails' do
+              it 'shows the email OTP fallback footer with helpful links' do
+                expect(page).to have_content('Having trouble signing in?')
+
+                expect(page).to have_link(
+                  'Enter recovery code',
+                  href: "https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication/#recovery-codes"
+                )
+                expect(page).to have_link('send code to email address')
+
+                perform_enqueued_jobs do
+                  click_link 'send code to email address'
+                  expect(page).to have_content('Verification code')
+
+                  # WebAuthn UI should be hidden
+                  expect(page).not_to have_content('Trying to communicate with your device')
+
+                  mail = wait_for('mail found for user') { find_email_for(user) }
+                  mail_to = mail&.to
+                  expect(mail_to).to match_array([user.email])
+                  expect(mail.subject).to eq(s_('IdentityVerification|Verify your identity'))
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
     context 'when logging in via OAuth' do
       let(:user) { create(:omniauth_user, :two_factor, extern_uid: 'my-uid', provider: 'saml') }
       let(:mock_saml_response) do
-- 
GitLab