feat: add two-factor method registration and base model module

Add Devise.register_two_factor_method API for extensions to register
2FA methods (analogous to config.omniauth). Register a single
:two_factor_authenticatable module in modules.rb. Extend mapping
strategies to include 2FA methods for Warden scope defaults.

Provide TwoFactorAuthenticatable base model module with per-model
two_factor_methods config, enabled_two_factors discovery, and
automatic inclusion of extension model concerns.

Author: santiagorodriguez96

lib/devise.rb

@@ -18,6 +18,7 @@ module Devise
   autoload :ParameterSanitizer, 'devise/parameter_sanitizer'
   autoload :TimeInflector,      'devise/time_inflector'
   autoload :TokenGenerator,     'devise/token_generator'
+  autoload :TwoFactor,          'devise/two_factor'
 
   module Controllers
     autoload :Helpers,        'devise/controllers/helpers'
@@ -40,6 +41,7 @@ module Mailers
   module Strategies
     autoload :Base,            'devise/strategies/base'
     autoload :Authenticatable, 'devise/strategies/authenticatable'
+    autoload :TwoFactor,       'devise/strategies/two_factor'
   end
 
   module Test
@@ -58,6 +60,13 @@ module Test
   # Strategies that do not require user input.
   NO_INPUT = []
 
+  # Global default for two_factor_methods per-model config.
+  mattr_accessor :two_factor_methods
+  @@two_factor_methods = []
+
+  # Registry of two-factor method configs set via register_two_factor_method.
+  mattr_reader :two_factor_method_configs, default: {}
+
   # True values used to check params
   TRUE_VALUES = [true, 1, '1', 'on', 'ON', 't', 'T', 'true', 'TRUE']
 
@@ -439,6 +448,36 @@ def self.add_module(module_name, options = {})
     Devise::Mapping.add_module module_name
   end
 
+  def self.register_two_factor_method(name, options = {})
+    options.assert_valid_keys(:model, :strategy, :controller, :route)
+    two_factor_method_configs[name.to_sym] = options
+    STRATEGIES[name.to_sym] = options[:strategy] if options[:strategy]
+
+    if controller = options[:controller]
+      controller = (controller == true ? name : controller)
+      CONTROLLERS[name.to_sym] = controller
+    end
+
+    if route = options[:route]
+      case route
+      when TrueClass
+        key, value = name, []
+      when Symbol
+        key, value = route, []
+      when Hash
+        key, value = route.keys.first, route.values.flatten
+      else
+        raise ArgumentError, ":route should be true, a Symbol or a Hash"
+      end
+
+      URL_HELPERS[key] ||= []
+      URL_HELPERS[key].concat(value)
+      URL_HELPERS[key].uniq!
+
+      ROUTES[name.to_sym] = key
+    end
+  end
+
   # Sets warden configuration using a block that will be invoked on warden
   # initialization.
   #

lib/devise/mapping.rb

@@ -84,15 +84,27 @@ def to
     end
 
     def strategies
-      @strategies ||= STRATEGIES.values_at(*self.modules).compact.uniq.reverse
+      @strategies ||= begin
+        keys = self.modules
+        if to.respond_to?(:two_factor_methods) && to.two_factor_methods
+          keys = keys + Array(to.two_factor_methods)
+        end
+        STRATEGIES.values_at(*keys).compact.uniq.reverse
+      end
     end
 
     def no_input_strategies
       self.strategies & Devise::NO_INPUT
     end
 
     def routes
-      @routes ||= ROUTES.values_at(*self.modules).compact.uniq
+      @routes ||= begin
+        keys = self.modules
+        if to.respond_to?(:two_factor_methods) && to.two_factor_methods
+          keys = keys + Array(to.two_factor_methods)
+        end
+        ROUTES.values_at(*keys).compact.uniq
+      end
     end
 
     def authenticatable?

lib/devise/models.rb

@@ -120,3 +120,4 @@ def devise_modules_hook!
 end
 
 require 'devise/models/authenticatable'
+require 'devise/models/two_factor_authenticatable'

lib/devise/models/two_factor_authenticatable.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Devise
+  module Models
+    module TwoFactorAuthenticatable
+      extend ActiveSupport::Concern
+
+      def self.required_fields(klass)
+        []
+      end
+
+      module ClassMethods
+        Devise::Models.config(self, :two_factor_methods)
+
+        def two_factor_methods=(methods)
+          @two_factor_methods = methods
+          Array(methods).each do |method_name|
+            config = Devise.two_factor_method_configs[method_name]
+            raise "Unknown two-factor method: #{method_name}. " \
+              "Did you call Devise.register_two_factor_method?" unless config
+            begin
+              require config[:model]
+            rescue LoadError
+              raise unless config[:model].camelize.safe_constantize
+            end
+            mod = config[:model].camelize.constantize
+            include mod
+          end
+        end
+
+        def two_factor_modules
+          Array(two_factor_methods)
+        end
+      end
+
+      def enabled_two_factors
+        self.class.two_factor_modules.select do |method_name|
+          send(:"#{method_name}_two_factor_enabled?")
+        end
+      end
+
+      def two_factor_enabled?
+        enabled_two_factors.any?
+      end
+    end
+  end
+end

lib/devise/modules.rb

@@ -13,6 +13,9 @@
   # Other authentications
   d.add_module :omniauthable, controller: :omniauth_callbacks,  route: :omniauth_callback
 
+  # Two-factor authentication
+  d.add_module :two_factor_authenticatable, controller: :two_factor, route: :two_factor
+
   # Misc after
   routes = [nil, :new, :edit]
   d.add_module :recoverable,  controller: :passwords,     route: { password: routes }