## Linear Ticket - https://linear.app/chatwoot/issue/CW-6884/nudge-users-with-a-dashboard-banner-when-2fa-backup-codes-run-low ## Description Shows a dashboard-wide banner when the signed-in user has 3 or fewer unused backup codes left (amber), turning to an alert style at 0 remaining. Clicking "Generate codes" takes the user to the MFA settings page so they can regenerate codes before they get locked out. Inspired by Google's post-backup-code-use nudges. ## How to test 1. Sign in as a user with MFA enabled. <img width="1512" height="824" alt="Screenshot 2026-08-05 at 4 52 15 PM" src="https://github.com/user-attachments/assets/08138f3e-cc15-451e-bbcc-7772dc2a875c" /> <img width="1507" height="701" alt="Screenshot 2026-08-05 at 4 54 02 PM" src="https://github.com/user-attachments/assets/580051fa-cbb5-47c1-81a3-258b7c5b5a03" /> 2. In a Rails console, simulate a low state by marking most backup codes as used: ```ruby u = User.find_by(email: '<your user>') codes = u.otp_backup_codes.dup (0...8).each { |i| codes[i] = 'XXXXXXXX' } u.otp_backup_codes = codes u.save! ``` 3. Reload any dashboard page — the amber banner should appear with a "Generate codes" CTA. 4. Click the CTA — it should route to **Profile → Two-Factor Authentication**, where you can regenerate codes. 5. Set the count to 0 (mark all 10 as `'XXXXXXXX'`) — banner should switch to the red/alert style. 6. Regenerate codes — banner should disappear on the next dashboard page load. ## 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 > Base is the [disable-with-backup-code PR branch](https://github.com/chatwoot/chatwoot/pull/14102) so CTAs around recovery are consistent; rebase onto `develop` once that merges. --------- Co-authored-by: Sivin Varghese <64252451+iamsivin@users.noreply.github.com> Co-authored-by: iamsivin <iamsivin@gmail.com> Co-authored-by: Sony Mathew <sony@chatwoot.com>
93 lines
2.0 KiB
Ruby
93 lines
2.0 KiB
Ruby
class Mfa::ManagementService
|
|
pattr_initialize [:user!]
|
|
|
|
def enable_two_factor!
|
|
user.otp_secret = User.generate_otp_secret
|
|
user.save!
|
|
end
|
|
|
|
def disable_two_factor!
|
|
user.otp_secret = nil
|
|
user.otp_required_for_login = false
|
|
user.otp_backup_codes = nil
|
|
user.save!
|
|
end
|
|
|
|
def verify_and_activate!
|
|
ActiveRecord::Base.transaction do
|
|
user.update!(otp_required_for_login: true)
|
|
backup_codes_generated? ? nil : generate_backup_codes!
|
|
end
|
|
end
|
|
|
|
def two_factor_provisioning_uri
|
|
return nil if user.otp_secret.blank?
|
|
|
|
issuer = 'Chatwoot'
|
|
label = user.email
|
|
user.otp_provisioning_uri(label, issuer: issuer)
|
|
end
|
|
|
|
def generate_backup_codes!
|
|
codes = Array.new(10) { SecureRandom.hex(4).upcase }
|
|
user.otp_backup_codes = codes
|
|
user.save!
|
|
codes
|
|
end
|
|
|
|
def validate_backup_code!(code)
|
|
return false unless valid_backup_code_input?(code)
|
|
|
|
codes = user.otp_backup_codes
|
|
found_index = find_matching_code_index(codes, code)
|
|
|
|
return false if found_index.nil?
|
|
|
|
mark_code_as_used(codes, found_index)
|
|
end
|
|
|
|
private
|
|
|
|
def valid_backup_code_input?(code)
|
|
user.otp_backup_codes.present? && code.present?
|
|
end
|
|
|
|
def find_matching_code_index(codes, code)
|
|
found_index = nil
|
|
|
|
# Constant-time comparison to prevent timing attacks
|
|
codes.each_with_index do |stored_code, idx|
|
|
is_match = ActiveSupport::SecurityUtils.secure_compare(stored_code, code)
|
|
is_unused = stored_code != 'XXXXXXXX'
|
|
found_index = idx if is_match && is_unused
|
|
end
|
|
|
|
found_index
|
|
end
|
|
|
|
def mark_code_as_used(codes, index)
|
|
codes[index] = 'XXXXXXXX'
|
|
user.otp_backup_codes = codes
|
|
user.save!
|
|
true
|
|
end
|
|
|
|
public
|
|
|
|
def backup_codes_generated?
|
|
user.otp_backup_codes.present?
|
|
end
|
|
|
|
def remaining_backup_codes_count
|
|
Array(user.otp_backup_codes).count { |code| code != 'XXXXXXXX' }
|
|
end
|
|
|
|
def mfa_enabled?
|
|
user.otp_required_for_login?
|
|
end
|
|
|
|
def two_factor_setup_pending?
|
|
user.otp_secret.present? && !user.otp_required_for_login?
|
|
end
|
|
end
|