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
@@ -312,6 +314,14 @@ def self.mappings
   mattr_accessor :sign_in_after_change_password
   @@sign_in_after_change_password = true
 
+  # 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
+  @@two_factor_method_configs = {}
+
   # Default way to set up Devise. Run rails generate devise_install to create
   # a fresh initializer with all configuration values.
   def self.setup
@@ -439,6 +449,59 @@ def self.add_module(module_name, options = {})
     Devise::Mapping.add_module module_name
   end
 
+
+  # Register available devise two factor methods.
+  # Third-party modules that intend to add a 2FA method need to be added explicitly using this method.
+  #
+  # Note that adding a module using this method does not cause it to be used in the authentication
+  # process. That requires the `:two_factor_authenticatable` module to be listed in the arguments passed
+  # to the 'devise' method in the model class definition along with the two factor method name listed under
+  # the `:two_factor_methods` argument passed to the 'devise' method.
+  #
+  # == Options:
+  #
+  #   +name+       - String representing the name of the 2FA method. This will be used to identify it.
+  #   +model+      - String representing the load path to a custom *model* for this 2FA method (to autoload.)
+  #   +strategy+   - Symbol representing if this module got a custom *strategy*.
+  #   +route+      - Generates extension-specific routes and URL helpers (e.g., credential management
+  #                  endpoints). This is separate from the core challenge/create routes that Devise
+  #                  generates automatically from +two_factor_methods+. Accepts true (defaults route
+  #                  name to the method name), a Symbol, or a Hash. Works the same as the +:route+
+  #                  option in +add_module+.
+  #
+  # == Examples:
+  #
+  #   Devise.register_two_factor_method(:my_two_factor_method)
+  #   Devise.register_two_factor_method(:my_two_factor_method, model: 'my_two_factor_method/model')
+  #   Devise.register_two_factor_method(:my_two_factor_method, model: 'my_two_factor_method/model', strategy: :my_two_factor_method, route: true)
+  #
+  def self.register_two_factor_method(name, options = {})
+    options.assert_valid_keys(:model, :strategy, :route)
+
+    two_factor_method_configs[name.to_sym] = options
+
+    STRATEGIES[name.to_sym] = options[:strategy] if options[:strategy]
+
+    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 }