feat: add TwoFactorController with OmniAuth-style routes and URL helpers

Add TwoFactorController following the OmniAuth callbacks pattern:
a single controller with per-method new_<method> actions, a central
POST create endpoint, and an ActiveSupport.on_load hook for extensions.

Generate per-method challenge routes from mapping.to.two_factor_methods.
Add generic URL helpers (new_two_factor_challenge_path, two_factor_path)
included via engine initializer when 2FA methods are registered.

Author: santiagorodriguez96

app/controllers/devise/two_factor_controller.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class Devise::TwoFactorController < DeviseController
+  prepend_before_action :require_no_authentication
+  prepend_before_action :ensure_sign_in_initiated
+
+  # Extensions can inject custom actions or override defaults via on_load
+  ActiveSupport.run_load_hooks(:devise_two_factor_controller, self)
+
+  # Auto-generate default new_<module> actions for each registered 2FA module.
+  # Extensions that injected a custom action via on_load won't be overwritten.
+  Devise.two_factor_method_configs.each_key do |mod|
+    unless method_defined?(:"new_#{mod}")
+      define_method(:"new_#{mod}") do
+        @resource = find_pending_resource
+      end
+    end
+  end
+
+  # POST /users/two_factor
+  # All methods POST here. Warden picks the right strategy via valid?.
+  def create
+    self.resource = warden.authenticate!(auth_options)
+    set_flash_message!(:notice, :signed_in, scope: :"devise.sessions")
+    sign_in(resource_name, resource)
+    yield resource if block_given?
+    respond_with resource, location: after_sign_in_path_for(resource)
+  end
+
+  protected
+
+  def auth_options
+    resource = find_pending_resource
+    default_method = resource.enabled_two_factors.first
+    { scope: resource_name, recall: "#{controller_path}#new_#{default_method}" }
+  end
+
+  def translation_scope
+    'devise.two_factor'
+  end
+
+  def find_pending_resource
+    return unless session[:devise_two_factor_resource_id]
+    resource_class.where(id: session[:devise_two_factor_resource_id]).first
+  end
+
+  private
+
+  def ensure_sign_in_initiated
+    return if session[:devise_two_factor_resource_id].present?
+    set_flash_message!(:alert, :sign_in_not_initiated, scope: :"devise.failure")
+    redirect_to new_session_path(resource_name)
+  end
+end

lib/devise/rails.rb

@@ -37,6 +37,14 @@ class Engine < ::Rails::Engine
       end
     end
 
+    initializer "devise.two_factor" do
+      config.after_initialize do
+        if Devise.two_factor_method_configs.any?
+          Devise.include_helpers(Devise::TwoFactor)
+        end
+      end
+    end
+
     initializer "devise.secret_key" do |app|
       Devise.secret_key ||= app.secret_key_base
 

lib/devise/rails/routes.rb

@@ -398,6 +398,25 @@ def devise_unlock(mapping, controllers) #:nodoc:
         end
       end
 
+      def devise_two_factor(mapping, controllers) #:nodoc:
+        return unless mapping.to.respond_to?(:two_factor_methods) && mapping.to.two_factor_methods.present?
+
+        controller = controllers[:two_factor] || "devise/two_factor"
+        two_factor_path = mapping.path_names[:two_factor] || "two_factor"
+
+        # Central POST endpoint — all methods submit here
+        post two_factor_path,
+          to: "#{controller}#create",
+          as: "two_factor"
+
+        # Per-method challenge routes
+        Array(mapping.to.two_factor_methods).each do |method_name|
+          get "#{two_factor_path}/#{method_name}/new",
+            to: "#{controller}#new_#{method_name}",
+            as: "new_two_factor_#{method_name}"
+        end
+      end
+
       def devise_registration(mapping, controllers) #:nodoc:
         path_names = {
           new: mapping.path_names[:sign_up],

lib/devise/two_factor.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Devise
+  module TwoFactor
+    autoload :UrlHelpers, "devise/two_factor/url_helpers"
+  end
+end

lib/devise/two_factor/url_helpers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Devise
+  module TwoFactor
+    module UrlHelpers
+      def new_two_factor_challenge_path(resource_or_scope, method, *args)
+        scope = Devise::Mapping.find_scope!(resource_or_scope)
+        _devise_route_context.send(:"#{scope}_new_two_factor_#{method}_path", *args)
+      end
+
+      def new_two_factor_challenge_url(resource_or_scope, method, *args)
+        scope = Devise::Mapping.find_scope!(resource_or_scope)
+        _devise_route_context.send(:"#{scope}_new_two_factor_#{method}_url", *args)
+      end
+
+      def two_factor_path(resource_or_scope, *args)
+        scope = Devise::Mapping.find_scope!(resource_or_scope)
+        _devise_route_context.send(:"#{scope}_two_factor_path", *args)
+      end
+
+      def two_factor_url(resource_or_scope, *args)
+        scope = Devise::Mapping.find_scope!(resource_or_scope)
+        _devise_route_context.send(:"#{scope}_two_factor_url", *args)
+      end
+    end
+  end
+end