[Login] Backup Codes

Gemfile

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

Gemfile.lock

@@ -177,6 +177,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)
@@ -889,6 +890,7 @@ DEPENDENCIES
   awesome_print
   aws-sdk-s3
   barnes
+  bcrypt (~> 3.1.7)
   blazer
   blind_index
   bootsnap (>= 1.4.4)

app/controllers/logins_controller.rb

@@ -138,6 +138,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
@@ -149,6 +155,8 @@ def complete
       @login.update(user_session: sign_in(user: @login.user, fingerprint_info:))
       if @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
@@ -207,6 +215,7 @@ def set_available_methods
     @sms_available = @user&.phone_number_verified && [email protected]_with_sms
     @webauthn_available = @user&.webauthn_credentials&.any? && [email protected]_with_webauthn
     @totp_available = @user&.totp.present? && [email protected]_with_totp
+    @backup_code_available = @user&.backup_codes_enabled? && [email protected]_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

@@ -33,7 +33,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" %>

app/views/logins/choose_login_preference.html.erb

@@ -18,7 +18,8 @@
          @email_available.presence,
          @sms_available.presence,
          @totp_available.presence,
-         @webauthn_available.presence
+         @webauthn_available.presence,
+         @backup_code_available.presence
        ].compact %>
 
     <div class="field field--options max-w-full w-full mt-3 <%= "trio" if methods.length == 3 %>">
@@ -57,10 +58,13 @@
     </div>
     <%= form.hidden_field :email, value: @email, data: { "webauthn-auth-target" => "loginEmailInput" } %>
     <%= form.hidden_field :return_to, value: @return_to if @return_to %>
-    <div class="flex flex-row justify-between items-center mt-4">
+    <div class="flex flex-row justify-between items-center my-4">
       <%= link_to "Cancel", logout_users_path, method: :delete, class: "no-underline block" %>
       <%= form.submit "Continue", data: { "webauthn-auth-target" => "continueButton", "form-disable-target" => "submitButton" } %>
     </div>
+    <% if @backup_code_available %>
+      <%= link_to "Don't have access to any of these? Use a Backup Code", backup_code_login_path(@login) %>
+    <% end %>
   <% end %>
 </div>
 <%= render partial: "environment_banner" %>

app/views/logins/login_code.html.erb

@@ -52,7 +52,7 @@
       <p class="h5 muted"><em>Make sure to check your spam folder</em></p>
     <% end %>
     <div class="flex flex-row justify-between items-center mt-4 gap-2">
-      <% if @webauthn_available || @totp_available %>
+      <% if @webauthn_available || @totp_available || @backup_code_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">

app/views/user/backup_code_mailer/backup_codes_disabled.html.erb

@@ -0,0 +1,16 @@
+<p>
+  Hey <%= @user.first_name %>,
+</p>
+
+<p>
+  You've just disabled backup codes for HCB. If you had any unused backup codes, they were invalidated.
+</p>
+
+<p>
+  If this was you, great! If you didn't do this, please <%= mail_to "[email protected]", "contact us", subject: "My backup codes were disabled and it was not me" %> immediately.
+</p>
+
+<p>
+  Thanks,<br>
+  The HCB Team
+</p>

app/views/user/backup_code_mailer/code_used.html.erb

@@ -0,0 +1,23 @@
+<p>
+  Hey <%= @user.first_name %>,
+</p>
+
+<p>
+  You've just used one of your backup codes to login to
+  <% if @user.backup_codes.active.size == 0 %>
+    HCB and have none left. We strongly urge you to regenerate more codes at your earliest convenience in your <%= link_to "user settings", security_user_url(@user) %> to ensure you can always access your account.
+  <% elsif @user.backup_codes.active.size <= 3 %>
+    HCB and only have <%= @user.backup_codes.active.size %> left. We strongly urge you to regenerate more codes at your earliest convenience in your <%= link_to "user settings", security_user_url(@user) %> to ensure you can always access your account.
+  <% else %>
+    HCB.
+  <% end %>
+</p>
+
+<p>
+  If this was you, great! If you didn't do this, please <%= mail_to "[email protected]", "contact us", subject: "Unauthorized access with backup code" %> immediately.
+</p>
+
+<p>
+  Thanks,<br>
+  The HCB Team
+</p>

app/views/user/backup_code_mailer/new_codes_activated.html.erb

@@ -0,0 +1,16 @@
+<p>
+  Hey <%= @user.first_name %>,
+</p>
+
+<p>
+  You've just generated backup codes for HCB and have 10 codes available. Please make sure to save the codes in a safe place in case you lose access to your account. HCB staff will never ask for your backup codes.
+</p>
+
+<p>
+  If this was you, great! If you didn't do this, please <%= mail_to "[email protected]", "contact us", subject: "Unauthorized backup codes generated" %> immediately.
+</p>
+
+<p>
+  Thanks,<br>
+  The HCB Team
+</p>