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>

spec/services/mfa/authentication_service_spec.rb

@@ -0,0 +1,106 @@
+require 'rails_helper'
+
+describe Mfa::AuthenticationService do
+  before do
+    skip('Skipping since MFA is not configured in this environment') unless Chatwoot.encryption_configured?
+    user.enable_two_factor!
+    user.update!(otp_required_for_login: true)
+  end
+
+  let(:user) { create(:user) }
+
+  describe '#authenticate' do
+    context 'with OTP code' do
+      context 'when OTP is valid' do
+        it 'returns true' do
+          valid_otp = user.current_otp
+          service = described_class.new(user: user, otp_code: valid_otp)
+          expect(service.authenticate).to be_truthy
+        end
+      end
+
+      context 'when OTP is invalid' do
+        it 'returns false' do
+          service = described_class.new(user: user, otp_code: '000000')
+          expect(service.authenticate).to be_falsey
+        end
+      end
+
+      context 'when OTP is nil' do
+        it 'returns false' do
+          service = described_class.new(user: user, otp_code: nil)
+          expect(service.authenticate).to be_falsey
+        end
+      end
+    end
+
+    context 'with backup code' do
+      let(:backup_codes) { user.generate_backup_codes! }
+
+      context 'when backup code is valid' do
+        it 'returns true and invalidates the code' do
+          valid_code = backup_codes.first
+          service = described_class.new(user: user, backup_code: valid_code)
+
+          expect(service.authenticate).to be_truthy
+
+          # Code should be invalidated after use
+          user.reload
+          expect(user.otp_backup_codes).to include('XXXXXXXX')
+        end
+      end
+
+      context 'when backup code is invalid' do
+        it 'returns false' do
+          service = described_class.new(user: user, backup_code: 'invalid')
+          expect(service.authenticate).to be_falsey
+        end
+      end
+
+      context 'when backup code has already been used' do
+        it 'returns false' do
+          valid_code = backup_codes.first
+          # Use the code once
+          service = described_class.new(user: user, backup_code: valid_code)
+          service.authenticate
+
+          # Try to use it again
+          service2 = described_class.new(user: user.reload, backup_code: valid_code)
+          expect(service2.authenticate).to be_falsey
+        end
+      end
+    end
+
+    context 'with neither OTP nor backup code' do
+      it 'returns false' do
+        service = described_class.new(user: user)
+        expect(service.authenticate).to be_falsey
+      end
+    end
+
+    context 'when user is nil' do
+      it 'returns false' do
+        service = described_class.new(user: nil, otp_code: '123456')
+        expect(service.authenticate).to be_falsey
+      end
+    end
+
+    context 'when both OTP and backup code are provided' do
+      it 'uses OTP authentication first' do
+        valid_otp = user.current_otp
+        backup_codes = user.generate_backup_codes!
+
+        service = described_class.new(
+          user: user,
+          otp_code: valid_otp,
+          backup_code: backup_codes.first
+        )
+
+        expect(service.authenticate).to be_truthy
+        # Backup code should not be consumed
+        user.reload
+        expect(user.otp_backup_codes).not_to include('XXXXXXXX')
+      end
+    end
+  end
+end

spec/services/mfa/token_service_spec.rb

@@ -0,0 +1,72 @@
+require 'rails_helper'
+
+describe Mfa::TokenService do
+  before do
+    skip('Skipping since MFA is not configured in this environment') unless Chatwoot.encryption_configured?
+  end
+
+  let(:user) { create(:user) }
+  let(:token_service) { described_class.new(user: user) }
+
+  describe '#generate_token' do
+    it 'generates a JWT token with user_id' do
+      token = token_service.generate_token
+      expect(token).to be_present
+      expect(token).to be_a(String)
+    end
+
+    it 'includes user_id in the payload' do
+      token = token_service.generate_token
+      decoded = JWT.decode(token, Rails.application.secret_key_base, true, algorithm: 'HS256').first
+      expect(decoded['user_id']).to eq(user.id)
+    end
+
+    it 'sets expiration to 5 minutes from now' do
+      allow(Time).to receive(:now).and_return(Time.zone.parse('2024-01-01 12:00:00'))
+      token = token_service.generate_token
+      decoded = JWT.decode(token, Rails.application.secret_key_base, true, algorithm: 'HS256').first
+      expected_exp = Time.zone.parse('2024-01-01 12:05:00').to_i
+      expect(decoded['exp']).to eq(expected_exp)
+    end
+  end
+
+  describe '#verify_token' do
+    let(:valid_token) { token_service.generate_token }
+
+    context 'with valid token' do
+      it 'returns the user' do
+        verifier = described_class.new(token: valid_token)
+        verified_user = verifier.verify_token
+        expect(verified_user).to eq(user)
+      end
+    end
+
+    context 'with invalid token' do
+      it 'returns nil for malformed token' do
+        verifier = described_class.new(token: 'invalid_token')
+        expect(verifier.verify_token).to be_nil
+      end
+
+      it 'returns nil for expired token' do
+        expired_payload = { user_id: user.id, exp: 1.minute.ago.to_i }
+        expired_token = JWT.encode(expired_payload, Rails.application.secret_key_base, 'HS256')
+        verifier = described_class.new(token: expired_token)
+        expect(verifier.verify_token).to be_nil
+      end
+
+      it 'returns nil for non-existent user' do
+        payload = { user_id: 999_999, exp: 5.minutes.from_now.to_i }
+        token = JWT.encode(payload, Rails.application.secret_key_base, 'HS256')
+        verifier = described_class.new(token: token)
+        expect(verifier.verify_token).to be_nil
+      end
+    end
+
+    context 'with blank token' do
+      it 'returns nil' do
+        verifier = described_class.new(token: nil)
+        expect(verifier.verify_token).to be_nil
+      end
+    end
+  end
+end