Feature-flagged sudo mode for 2fa setting (#10671)

RFC: #10653

The following PRs were extracted from this one and shipped separately:
- #10780
- #10826
- #10903

## Changes

- Adds the model relationships described in
#10903 (comment)
  - Adds `logins` and `initial_login` relations to `UserSession`
  - Adds `initial_login` relation to `Login`
- Updates the logic in `Login` to only require a single factor in the
case of a reauthentication
- Adds `UserSession#sudo_mode?` to determine whether sudo mode is
enabled based on the creation times of its associated logins
- Adds `SudoModeHandler` which handles intercepting requests and
rendering the reauthentication page
- Requires sudo mode if the 2fa setting is changed and the user has the
feature flag enabled
- Extensive testing

Author: davidcornu

app/assets/stylesheets/_utilities.scss

@@ -232,3 +232,15 @@ tr.strikethrough td:before {
 .scrollbar-hidden::-webkit-scrollbar {
   display: none;
 }
+
+// https://piccalil.li/blog/link-button/
+.link-button {
+  display: inline;
+  padding: 0;
+  border: 0;
+  font: inherit;
+  text-decoration: underline;
+  cursor: pointer;
+  background: transparent;
+  color: currentColor;
+}

app/controllers/sudo_mode_handler.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+class SudoModeHandler
+  # The default rank for authentication factors (lower is better)
+  # - 0 is deliberately left available so we can use it for the user's preference
+  # - `:backup_code` is explicitly omitted as we don't want to use that for
+  #   reauthentication
+  FACTOR_PREFERENCES = {
+    webauthn: 1,
+    totp: 2,
+    sms: 3,
+    email: 4,
+  }.freeze
+
+  Params = Struct.new(
+    # When the form is submitted, `submit_method` determines which
+    # authentication method the user selected, which in turn determines whether
+    # `login_code` or webauthn_response` is relevant
+    :submit_method,
+    :login_code,
+    :webauthn_response,
+    # When the user first sees the reauthentication page we create a login for
+    # them whose ID is passed around over subsequent operations. It is required
+    # when completing the form.
+    :login_id,
+    # When the user clicks on an alternate authentication method, the form will be
+    # submitted with this param indicating which method they chose.
+    :switch_method,
+    keyword_init: true
+  )
+
+  # @param controller_instance [ApplicationController]
+  def initialize(controller_instance:)
+    @controller_instance = controller_instance
+  end
+
+  # @return [Boolean] whether sudo mode was obtained and sensitive actions can proceed
+  def call
+    unless sudo_params.submit_method.present?
+      render_reauthentication_page
+      return false
+    end
+
+    login = Login.incomplete.active.find_by_hashid(sudo_params.login_id)
+
+    # If the login doesn't exist, was completed, or has expired, treat this as a
+    # new request
+    unless login
+      flash.now[:error] = "Login has expired. Please try again."
+      render_reauthentication_page
+      return false
+    end
+
+    service = ProcessLoginService.new(login:)
+
+    ok =
+      case sudo_params.submit_method
+      when "email", "sms"
+        service.process_login_code(
+          code: sudo_params.login_code,
+          sms: sudo_params.submit_method == "sms"
+        )
+      when "totp"
+        service.process_totp(
+          code: sudo_params.login_code
+        )
+      when "webauthn"
+        service.process_webauthn(
+          raw_credential: sudo_params.webauthn_response,
+          challenge: session[:webauthn_challenge]
+        )
+      else
+        raise ActionController::ParameterMissing.new(:submit_method)
+      end
+
+    unless ok
+      flash.now[:error] = service.errors.full_messages.to_sentence
+      render_reauthentication_page(login:)
+      return false
+    end
+
+    login.update!(user_session: current_session)
+    current_session.reload
+
+    true
+  end
+
+  private
+
+  attr_reader(:controller_instance)
+
+  delegate(
+    :current_user,
+    :current_session,
+    :params,
+    :session,
+    :request,
+    :flash,
+    to: :controller_instance,
+    private: true
+  )
+
+  def sudo_params
+    @sudo_params ||= begin
+      nested = params[:_sudo]
+
+      if nested.is_a?(ActionController::Parameters)
+        Params.new(
+          **nested.permit(
+            :submit_method,
+            :switch_method,
+            :login_id,
+            :login_code,
+            :webauthn_response,
+          )
+        )
+      else
+        Params.new
+      end
+    end
+  end
+
+  def sorted_factors(login)
+    factor_preference = FACTOR_PREFERENCES
+
+    # Put the user's preference first
+    user_preference = sudo_params.switch_method.presence || session[:login_preference].presence
+    if user_preference.present? && factor_preference.key?(user_preference.to_sym)
+      factor_preference = factor_preference.merge(user_preference.to_sym => 0)
+    end
+
+    # Filter available factors down to only those present in
+    # `FACTOR_PREFERENCES` and sort based on their associated ranks.
+    (login.available_factors & FACTOR_PREFERENCES.keys)
+      .sort_by { |factor| factor_preference.fetch(factor) }
+  end
+
+  # Extracts the request parameters as a flat list of key-value pairs (instead
+  # of following Rack's nesting conventions) so that we can re-submit them along
+  # with the sudo credentials.
+  def forwarded_params
+    Rack::Utils
+      # Re-encoding params to immediately parse them may seem wasteful, but it
+      # means we don't have to re-implement Rack's nested param encoding logic
+      .parse_query(request.request_parameters.to_query)
+      .reject do |name, _value_or_values|
+        case name
+        # Both of these fields will be regenerated by `form_tag`
+        when "authenticity_token", "_method"
+          true
+        else
+          # Skip anything that is part of the sudo functionality
+          name.start_with?("_sudo")
+        end
+      end
+      .each_with_object([]) do |(name, value_or_values), array|
+        # `Rack::Utils.parse_query` returns a hash of param names to values but
+        # returns an array of values for repeated params (as is the convention
+        # params like `tags[]`)
+        if value_or_values.is_a?(Array)
+          value_or_values.each do |value|
+            array << [name, value]
+          end
+        else
+          array << [name, value_or_values]
+        end
+      end
+  end
+
+  def find_or_create_login!
+    existing =
+      if sudo_params.login_id.present?
+        Login.incomplete.active.find_by_hashid(sudo_params.login_id)
+      end
+
+    return existing if existing
+
+    raise("Session does not have an initial login") unless current_session.initial_login
+
+    Login.create!(
+      user: current_user,
+      initial_login: current_session.initial_login
+    )
+  end
+
+  def render_reauthentication_page(login: find_or_create_login!)
+    default_factor, *additional_factors = sorted_factors(login)
+
+    # In the case where we know we're going to ask for an SMS or email code,
+    # send it ahead of time so the user doesn't have to perform an additional
+    # step
+    if [:sms, :email].include?(default_factor)
+      LoginCodeService::Request.new(
+        email: current_user.email,
+        sms: default_factor == :sms,
+        ip_address: request.remote_ip,
+        user_agent: request.user_agent
+      ).run
+    end
+
+    # Remove extra content from the layout so we only have the
+    # reauthentication form on the page.
+    controller_instance.instance_variable_set(:@no_app_shell, true)
+
+    controller_instance.render(
+      template: "sudo_mode/reauthenticate",
+      layout: "application",
+      locals: {
+        login:,
+        additional_factors:,
+        default_factor:,
+        forwarded_params:
+      },
+      status: :unprocessable_entity
+    )
+  end
+
+end

app/controllers/users_controller.rb

@@ -232,6 +232,12 @@ def update
     @user = User.friendly.find(params[:id])
     authorize @user
 
+    @user.assign_attributes(user_params)
+
+    if @user.use_two_factor_authentication_changed?
+      return unless enforce_sudo_mode # rubocop:disable Style/SoleNestedConditional
+    end
+
     if admin_signed_in?
       if @user.auditor? && params[:user][:running_balance_enabled].present?
         enable_running_balance = params[:user][:running_balance_enabled] == "1"
@@ -276,7 +282,7 @@ def update
       end
     end
 
-    if @user.update(user_params)
+    if @user.save
       confetti! if !@user.seasonal_themes_enabled_before_last_save && @user.seasonal_themes_enabled? # confetti if the user enables seasonal themes
 
       if @user.full_name_before_last_save.blank?

app/helpers/sessions_helper.rb

@@ -158,4 +158,23 @@ def sign_out_of_all_sessions(user = current_user)
       &.where&.not(id: current_session.id)
       &.update_all(signed_out_at: Time.now, expiration_at: Time.now)
   end
+
+  def sudo_mode?
+    current_session&.sudo_mode?
+  end
+
+  # Intercepts the request and renders a reauthentication form if the user does
+  # not have sudo mode.
+  #
+  # It can either be used as a `before_action` callback or as part of an action
+  # implementation if you only want to require sudo mode in specific cases. In
+  # the latter scenario, you _MUST_ check the return value and only proceed if
+  # it is `true`.
+  #
+  # @return [Boolean] whether sudo mode was obtained and the controller action can proceed
+  def enforce_sudo_mode
+    return true if sudo_mode?
+
+    SudoModeHandler.new(controller_instance: self).call
+  end
 end

app/models/login.rb

@@ -31,6 +31,14 @@ class Login < ApplicationRecord
 
   belongs_to :user
   belongs_to :user_session, optional: true
+  belongs_to(
+    :initial_login,
+    optional: true,
+    class_name: "Login",
+    inverse_of: nil
+  )
+
+  scope(:initial, -> { where(initial_login_id: nil) })
   belongs_to :referral_program, class_name: "Referral::Program", optional: true
 
   has_encrypted :browser_token
@@ -66,7 +74,7 @@ class Login < ApplicationRecord
     event :mark_complete do
       transitions from: :incomplete, to: :complete do
         guard do
-          authentication_factors_count == (user.use_two_factor_authentication? ? 2 : 1)
+          authentication_factors_count == required_authentication_factors_count
         end
       end
     end
@@ -119,4 +127,23 @@ def available_factors
     factors
   end
 
+  def reauthentication?
+    initial_login_id.present?
+  end
+
+  private
+
+  # The number of authentication factors required to consider this login
+  # complete (based on the user's 2FA setting and whether this is a
+  # reauthentication)
+  #
+  # @return [Integer]
+  def required_authentication_factors_count
+    if user.use_two_factor_authentication? && !reauthentication?
+      2
+    else
+      1
+    end
+  end
+
 end

app/models/user_session.rb

@@ -43,6 +43,13 @@ class UserSession < ApplicationRecord
   belongs_to :user
   belongs_to :impersonated_by, class_name: "User", optional: true
   belongs_to :webauthn_credential, optional: true
+  has_many(:logins)
+  has_one(
+    :initial_login,
+    -> { initial },
+    class_name: "Login",
+    inverse_of: :user_session,
+  )
 
   include PublicActivity::Model
   tracked owner: proc{ |controller, record| record.impersonated_by || record.user }, recipient: proc { |controller, record| record.impersonated_by || record.user }, only: [:create]
@@ -83,6 +90,20 @@ def expired?
     expiration_at <= Time.now
   end
 
+  SUDO_MODE_TTL = 2.hours
+
+  # Determines whether the user can perform a sensitive action without
+  # reauthenticating.
+  #
+  # @return [Boolean]
+  def sudo_mode?
+    return true unless Flipper.enabled?(:sudo_mode_2015_07_21, user)
+
+    return false if last_authenticated_at.nil?
+
+    last_authenticated_at >= SUDO_MODE_TTL.ago
+  end
+
   def clear_metadata!
     update!(
       device_info: nil,
@@ -99,4 +120,12 @@ def user_is_unlocked
     end
   end
 
+  # The last time the user went through a login flow. Used to determine whether
+  # sensitive actions can be performed.
+  #
+  # @return [ActiveSupport::TimeWithZone, nil]
+  def last_authenticated_at
+    logins.complete.max_by(&:created_at)&.created_at
+  end
+
 end