feat: MFA (#12290)

## Linear:
- https://github.com/chatwoot/chatwoot/issues/486

## Description
This PR implements Multi-Factor Authentication (MFA) support for user
accounts, enhancing security by requiring a second form of verification
during login. The feature adds TOTP (Time-based One-Time Password)
authentication with QR code generation and backup codes for account
recovery.

## Type of change

- [ ] New feature (non-breaking change which adds functionality)

## How Has This Been Tested?

- Added comprehensive RSpec tests for MFA controller functionality
- Tested MFA setup flow with QR code generation
- Verified OTP validation and backup code generation
- Tested login flow with MFA enabled/disabled

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented on my code, particularly in hard-to-understand
areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream
modules

---------

Co-authored-by: Pranav <pranav@chatwoot.com>
Co-authored-by: Sojan Jose <sojan@pepalo.com>
Co-authored-by: Muhsin Keloth <muhsinkeramam@gmail.com>

app/controllers/api/v1/profile/mfa_controller.rb

@@ -0,0 +1,68 @@
+class Api::V1::Profile::MfaController < Api::BaseController
+  before_action :check_mfa_feature_available
+  before_action :check_mfa_enabled, only: [:destroy, :backup_codes]
+  before_action :check_mfa_disabled, only: [:create, :verify]
+  before_action :validate_otp, only: [:verify, :backup_codes, :destroy]
+  before_action :validate_password, only: [:destroy]
+
+  def show; end
+
+  def create
+    mfa_service.enable_two_factor!
+  end
+
+  def verify
+    @backup_codes = mfa_service.verify_and_activate!
+  end
+
+  def destroy
+    mfa_service.disable_two_factor!
+  end
+
+  def backup_codes
+    @backup_codes = mfa_service.generate_backup_codes!
+  end
+
+  private
+
+  def mfa_service
+    @mfa_service ||= Mfa::ManagementService.new(user: current_user)
+  end
+
+  def check_mfa_enabled
+    render_could_not_create_error(I18n.t('errors.mfa.not_enabled')) unless current_user.mfa_enabled?
+  end
+
+  def check_mfa_feature_available
+    return if Chatwoot.mfa_enabled?
+
+    render json: {
+      error: I18n.t('errors.mfa.feature_unavailable')
+    }, status: :forbidden
+  end
+
+  def check_mfa_disabled
+    render_could_not_create_error(I18n.t('errors.mfa.already_enabled')) if current_user.mfa_enabled?
+  end
+
+  def validate_otp
+    authenticated = Mfa::AuthenticationService.new(
+      user: current_user,
+      otp_code: mfa_params[:otp_code]
+    ).authenticate
+
+    return if authenticated
+
+    render_could_not_create_error(I18n.t('errors.mfa.invalid_code'))
+  end
+
+  def validate_password
+    return if current_user.valid_password?(mfa_params[:password])
+
+    render_could_not_create_error(I18n.t('errors.mfa.invalid_credentials'))
+  end
+
+  def mfa_params
+    params.permit(:otp_code, :password)
+  end
+end

app/controllers/devise_overrides/sessions_controller.rb

@@ -9,13 +9,11 @@ class DeviseOverrides::SessionsController < DeviseTokenAuth::SessionsController
   end
 
   def create
-    # Authenticate user via the temporary sso auth token
-    if params[:sso_auth_token].present? && @resource.present?
-      authenticate_resource_with_sso_token
-      yield @resource if block_given?
-      render_create_success
-    else
-      super
+    return handle_mfa_verification if mfa_verification_request?
+    return handle_sso_authentication if sso_authentication_request?
+
+    super do |resource|
+      return handle_mfa_required(resource) if resource&.mfa_enabled?
     end
   end
 
@@ -25,6 +23,20 @@ class DeviseOverrides::SessionsController < DeviseTokenAuth::SessionsController
 
   private
 
+  def mfa_verification_request?
+    params[:mfa_token].present?
+  end
+
+  def sso_authentication_request?
+    params[:sso_auth_token].present? && @resource.present?
+  end
+
+  def handle_sso_authentication
+    authenticate_resource_with_sso_token
+    yield @resource if block_given?
+    render_create_success
+  end
+
   def login_page_url(error: nil)
     frontend_url = ENV.fetch('FRONTEND_URL', nil)
 
@@ -46,6 +58,41 @@ class DeviseOverrides::SessionsController < DeviseTokenAuth::SessionsController
     user = User.from_email(params[:email])
     @resource = user if user&.valid_sso_auth_token?(params[:sso_auth_token])
   end
+
+  def handle_mfa_required(resource)
+    render json: {
+      mfa_required: true,
+      mfa_token: Mfa::TokenService.new(user: resource).generate_token
+    }, status: :partial_content
+  end
+
+  def handle_mfa_verification
+    user = Mfa::TokenService.new(token: params[:mfa_token]).verify_token
+    return render_mfa_error('errors.mfa.invalid_token', :unauthorized) unless user
+
+    authenticated = Mfa::AuthenticationService.new(
+      user: user,
+      otp_code: params[:otp_code],
+      backup_code: params[:backup_code]
+    ).authenticate
+
+    return render_mfa_error('errors.mfa.invalid_code') unless authenticated
+
+    sign_in_mfa_user(user)
+  end
+
+  def sign_in_mfa_user(user)
+    @resource = user
+    @token = @resource.create_token
+    @resource.save!
+
+    sign_in(:user, @resource, store: false, bypass: false)
+    render_create_success
+  end
+
+  def render_mfa_error(message_key, status = :bad_request)
+    render json: { error: I18n.t(message_key) }, status: status
+  end
 end
 
 DeviseOverrides::SessionsController.prepend_mod_with('DeviseOverrides::SessionsController')