[Login] Backup Codes (#10434)

## Summary of the problem
<!-- Why these changes are being made? What problem does it solve? Link
any related issues to provide more details. -->

People might get locked out of their accounts with no way to get back
in, which is bad.

## Describe your changes
<!-- Explain your thought process to the solution and provide a quick
summary of the changes. -->

Added backup codes, securely generated, SHA-512 BLT seasoned with fresh
S&P.

<!-- If there are any visual changes, please attach images, videos, or
gifs. -->

<img width="969" alt="Screenshot 2025-05-24 at 11 11 25 PM"
src="https://github.com/user-attachments/assets/bf632d3c-3999-46c0-af88-30643fb4f3b2"
/>

<img width="969" alt="Screenshot 2025-05-24 at 11 11 48 PM"
src="https://github.com/user-attachments/assets/c807d0b5-04ad-4133-b653-c396087b778d"
/>

<img width="969" alt="Screenshot 2025-05-24 at 11 07 44 PM"
src="https://github.com/user-attachments/assets/5194a9ab-18af-4c51-84c5-78e71616f3fa"
/>

<img width="460" alt="Screenshot 2025-05-24 at 11 12 30 PM"
src="https://github.com/user-attachments/assets/cf2f04c2-a36a-425a-9466-8215ad1260c8"
/>

<img width="460" alt="Screenshot 2025-05-24 at 11 12 55 PM"
src="https://github.com/user-attachments/assets/613c4f8c-73cf-4671-b369-7d87291dd723"
/>

<img width="969" alt="Screenshot 2025-05-24 at 11 10 55 PM"
src="https://github.com/user-attachments/assets/ab2112a0-237a-4371-8087-fcadf0ae8bb9"
/>

<img width="565" alt="Screenshot 2025-05-24 at 11 24 17 PM"
src="https://github.com/user-attachments/assets/bcf4e726-9e66-480d-8d50-c2d60d3de981"
/>

<img width="565" alt="Screenshot 2025-05-24 at 11 27 51 PM"
src="https://github.com/user-attachments/assets/378a523d-d127-4227-a28a-8473573c2d29"
/>

<img width="565" alt="Screenshot 2025-05-24 at 11 29 08 PM"
src="https://github.com/user-attachments/assets/0aaff1cb-d87d-439c-8ac5-fdc64bb53634"
/>

<img width="565" alt="Screenshot 2025-05-24 at 11 23 22 PM"
src="https://github.com/user-attachments/assets/1d4eca81-7326-47b4-945c-42f9dbbf83f0"
/>

<img width="565" alt="Screenshot 2025-05-24 at 11 23 48 PM"
src="https://github.com/user-attachments/assets/d96d7e8f-3aec-4c18-bd20-7496f3e1b7ae"
/>

<img width="565" alt="Screenshot 2025-05-24 at 11 25 59 PM"
src="https://github.com/user-attachments/assets/333a7e99-7f39-4342-be18-c4037d738a7c"
/>

---------

Co-authored-by: Gary Tou <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: David Cornu <[email protected]>

Author: 4 people

Gemfile

@@ -228,4 +228,6 @@ gem "irb"
 
 gem "pstore"
 
+gem "bcrypt", "~> 3.1.7"
+
 gem "prosemirror_to_html"

Gemfile.lock

@@ -173,6 +173,7 @@ GEM
       multi_json (~> 1)
       statsd-ruby (~> 1.1)
     base64 (0.3.0)
+    bcrypt (3.1.20)
     benchmark (0.4.1)
     better_html (2.1.1)
       actionview (>= 6.0)
@@ -884,6 +885,7 @@ DEPENDENCIES
   awesome_print
   aws-sdk-s3
   barnes
+  bcrypt (~> 3.1.7)
   blazer
   blind_index
   bootsnap (>= 1.4.4)

app/controllers/logins_controller.rb

@@ -142,6 +142,12 @@ def complete
       else
         return redirect_to totp_login_path(@login), flash: { error: "Invalid TOTP code, please try again." }
       end
+    when "backup_code"
+      if @user.redeem_backup_code!(params[:backup_code])
+        @login.update(authenticated_with_backup_code: true)
+      else
+        return redirect_to backup_code_login_path(@login), flash: { error: "Invalid backup code, please try again." }
+      end
     end
 
     # Clear the flash - this prevents the error message showing up after an unsuccessful -> successful login
@@ -155,6 +161,8 @@ def complete
         redirect_to program_path(@referral_program)
       elsif @user.full_name.blank? || @user.phone_number.blank?
         redirect_to edit_user_path(@user.slug, return_to: params[:return_to])
+      elsif @login.authenticated_with_backup_code && @user.backup_codes.active.size == 0
+        redirect_to security_user_path(@user), flash: { warning: "You've just used your last backup code, and we recommend generating more." }
       else
         redirect_to(params[:return_to] || root_path)
       end
@@ -214,6 +222,7 @@ def set_available_methods
     @sms_available = @user&.phone_number_verified && !@login.authenticated_with_sms
     @webauthn_available = @user&.webauthn_credentials&.any? && !@login.authenticated_with_webauthn
     @totp_available = @user&.totp.present? && !@login.authenticated_with_totp
+    @backup_code_available = @user&.backup_codes_enabled? && !@login.authenticated_with_backup_code
   end
 
   def set_return_to

app/controllers/users_controller.rb

@@ -189,6 +189,26 @@ def disable_totp
     redirect_back_or_to security_user_path(@user)
   end
 
+  def generate_backup_codes
+    @user = params[:id] ? User.friendly.find(params[:id]) : current_user
+    authorize @user
+    @previewed_backup_codes = @user.generate_backup_codes!
+  end
+
+  def activate_backup_codes
+    @user = params[:id] ? User.friendly.find(params[:id]) : current_user
+    authorize @user
+    @user.activate_backup_codes!
+    redirect_back_or_to security_user_path(@user)
+  end
+
+  def disable_backup_codes
+    @user = params[:id] ? User.friendly.find(params[:id]) : current_user
+    authorize @user
+    @user.disable_backup_codes!
+    redirect_back_or_to security_user_path(@user)
+  end
+
   def edit_admin
     @user = params[:id] ? User.friendly.find(params[:id]) : current_user
     set_onboarding

app/mailers/user/backup_code_mailer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class User
+  class BackupCodeMailer < ApplicationMailer
+    before_action :set_user
+
+    default to: -> { @user.email_address_with_name }
+
+    def new_codes_activated
+      mail subject: "You've generated new backup codes for HCB"
+    end
+
+    def code_used
+      subject = "You've used a backup code to login to HCB"
+      case @user.backup_codes.active.size
+      when 0
+        subject = "[Action Required] You've used all your backup codes for HCB"
+      when 1..3
+        subject = "[Action Requested] You've almost used all your backup codes for HCB"
+      end
+      mail subject: subject
+    end
+
+    def backup_codes_disabled
+      mail subject: "You've disabled your HCB backup codes"
+    end
+
+    private
+
+    def set_user
+      @user = User.find(params[:user_id])
+    end
+
+  end
+
+end

app/models/login.rb

@@ -36,7 +36,7 @@ class Login < ApplicationRecord
   has_encrypted :browser_token
   before_validation :ensure_browser_token
 
-  store_accessor :authentication_factors, :sms, :email, :webauthn, :totp, prefix: :authenticated_with
+  store_accessor :authentication_factors, :sms, :email, :webauthn, :totp, :backup_code, prefix: :authenticated_with
 
   EXPIRATION = 15.minutes
 

app/models/user.rb

@@ -79,6 +79,7 @@ class User < ApplicationRecord
 
   has_many :logins
   has_many :login_codes
+  has_many :backup_codes, class_name: "User::BackupCode", inverse_of: :user, dependent: :destroy
   has_many :user_sessions, dependent: :destroy
   has_many :organizer_position_invites, dependent: :destroy
   has_many :organizer_position_contracts, through: :organizer_position_invites, class_name: "OrganizerPosition::Contract"
@@ -381,6 +382,60 @@ def only_card_grant_user?
     card_grants.size >= 1 && events.size == 0
   end
 
+  def backup_codes_enabled?
+    backup_codes.active.any?
+  end
+
+  def generate_backup_codes!
+    backup_codes.previewed.destroy_all
+
+    codes = []
+    ActiveRecord::Base.transaction do
+      while codes.size < 10
+        code = SecureRandom.alphanumeric(10)
+        next if codes.include?(code)
+
+        backup_codes.create!(code: code)
+        codes << code
+      end
+    end
+
+    codes
+  end
+
+  def activate_backup_codes!
+    ActiveRecord::Base.transaction do
+      backup_codes.active.map(&:mark_discarded!)
+      backup_codes.previewed.map(&:mark_active!)
+    end
+    User::BackupCodeMailer.with(user_id: id).new_codes_activated.deliver_now
+  end
+
+  def redeem_backup_code!(code)
+    backup_codes.active.each do |backup_code|
+      next unless backup_code.authenticate_code(code)
+
+      ActiveRecord::Base.transaction do
+        backup_code = User::BackupCode
+                      .lock # performs a SELECT ... FOR UPDATE https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE
+                      .active # makes sure that it hasn't already been used
+                      .find(backup_code.id) # will raise `ActiveRecord::NotFound` and abort the transaction
+        backup_code.mark_used!
+        return true
+      end
+    end
+
+    false
+  end
+
+  def disable_backup_codes!
+    ActiveRecord::Base.transaction do
+      backup_codes.previewed.destroy_all
+      backup_codes.active.map(&:mark_discarded!)
+    end
+    BackupCodeMailer.with(user_id: id).backup_codes_disabled.deliver_now
+  end
+
   private
 
   def update_stripe_cardholder

app/models/user/backup_code.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: user_backup_codes
+#
+#  id          :bigint           not null, primary key
+#  aasm_state  :string           default("previewed"), not null
+#  code_digest :text             not null
+#  created_at  :datetime         not null
+#  updated_at  :datetime         not null
+#  user_id     :bigint           not null
+#
+# Indexes
+#
+#  index_user_backup_codes_on_user_id  (user_id)
+#
+# Foreign Keys
+#
+#  fk_rails_...  (user_id => users.id)
+#
+class User
+  class BackupCode < ApplicationRecord
+    has_paper_trail
+
+    has_secure_password :code
+
+    include AASM
+
+    belongs_to :user
+
+    validates :code_digest, presence: true
+
+    aasm do
+      state :previewed, initial: true
+      state :active
+      state :used
+      state :discarded
+
+      event :mark_active do
+        transitions from: :previewed, to: :active
+      end
+      event :mark_used do
+        transitions from: :active, to: :used
+
+        after do
+          User::BackupCodeMailer.with(user_id: user.id).code_used.deliver_now
+        end
+      end
+      event :mark_discarded do
+        transitions from: :active, to: :discarded
+      end
+    end
+
+  end
+
+end

app/policies/user_policy.rb

@@ -25,6 +25,18 @@ def disable_totp?
     user.admin? || record == user
   end
 
+  def generate_backup_codes?
+    record == user
+  end
+
+  def activate_backup_codes?
+    record == user
+  end
+
+  def disable_backup_codes?
+    user.admin? || record == user
+  end
+
   def edit_address?
     user.auditor? || record == user
   end

app/views/logins/backup_code.html.erb

@@ -0,0 +1,33 @@
+<% title "Enter backup code" %>
+<% content_for(:page_class) { "bg-snow" } %>
+
+<div class="flex flex-col flex-1 justify-center max-w-md w-full">
+  <%= render "header", label: "Sign in to HCB" do %>
+    Backup code
+  <% end %>
+  <%= render "badge", user: @login.user %>
+  <p>
+    Please enter one of the backup codes you generated previously.
+  </p>
+  <%= form_tag complete_login_path(@login) do %>
+    <%= text_field :backup_code, "", placeholder: "Enter your backup code", name: "backup_code", class: "!max-w-full w-max", required: true, autofocus: true %>
+    <%= hidden_field_tag :method, :backup_code %>
+    <%= hidden_field_tag :fingerprint %>
+    <%= hidden_field_tag :device_info %>
+    <%= hidden_field_tag :os_info %>
+    <%= hidden_field_tag :timezone %>
+    <%= hidden_field_tag :return_to, @return_to if @return_to %>
+    <div class="flex flex-row justify-between items-center mt-4 gap-2">
+      <% if @webauthn_available || @totp_available || @email_available || @sms_available %>
+        <%= link_to "Sign in another way", choose_login_preference_login_path(@login, return_to: @return_to), class: "block mt-0 no-underline" %>
+      <% end %>
+      <button data-webauthn-auth-target="continueButton" type="submit" class="gap-2 btn">
+        Continue
+      </button>
+    </div>
+  <% end %>
+  <%= javascript_include_tag "https://cdn.jsdelivr.net/npm/ua-parser-js/dist/ua-parser.min.js" %>
+  <%= javascript_include_tag "fingerprint.js" %>
+</div>
+<%= render partial: "environment_banner" %>
+<%= render partial: "footer" %>