searls-auth 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 608a7738fece38d0fce18f906f68c5d91122aaf2d274cdcf48dba6b770c04069
-  data.tar.gz: 76d7b5e89479236705a1cb866d7358016510fa9899dffd2474fe9139cfc688bf
+  metadata.gz: '09b9515ef89e82e747cc35c415a4de145cf8e61634caccb137ceb8f429a54bdc'
+  data.tar.gz: e5b456ac99cc9ad784ed8727266dc3e073e6ee850ad720be0a4a42e894e2bbe8
 SHA512:
-  metadata.gz: c23b8352aaeec522b1878bf3b32c721cd14d06ef31b306a23fcb7e8b1ca1b3659a39904409e30c4492724289057b1a4594486e7878d01304b2830a7ed39e3ecf
-  data.tar.gz: 387b365eb74882a67258552f0da17d58913d001ea574fcf4d4c2b0c1487aeac939e6431e210c0b8bbb1471c00bfd01591e3f6aa6969520cee7727850a4d8552f
+  metadata.gz: 6c5163daa1551674b1c128ecf8a6d155cde36123780bf2332ef5d9f79166d37a964616f6fda17c97eb2608df9d13ad54f6f25e5c384ef2308b8740f93e326302
+  data.tar.gz: 4bfdd8c989591a52aeb52cf91bbf55e189442e57031d877f0e81f88c45d51d8cd22bd8ca21f31be10370c68b3981e410b2a034ed6c69738b28ee10cfcca078d0

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [1.0.0] - 2025-10-04
+
+* **BREAKING:** Rename `default_redirect_path_after_register` to `redirect_path_after_register`
+* **BREAKING:** Rename `flash_notice_after_verification` to `flash_notice_after_login`
+* Add password reset flow with default controllers, mailer, views, and configuration hooks
+* Add `before_password_reset` hook to optionally throttle or reject reset requests
+* Add configurable `password_reset_request_view` and `password_reset_edit_view` settings
+* Add `password_reset_enabled` flag to disable the forgot-password link/flow when email delivery is unavailable
+* Add account settings controller/view for password rotation and email changes, plus related configuration hooks
+* Switch from flash[:error] to the conventional flash[:alert] (TIL, 20 years in that :alert is more common)
+
 ## [0.2.0] - 2025-09-11
 
 * Add `auth_methods` configuration with default `[:email_link, :email_otp]`
@@ -10,7 +21,7 @@
 
 ## [0.1.0] - 2025-04-26
 
-* Add `max_allowed_short_code_attempts` configuration, beyond which the code is erased from the session and the user needs to login again (default: 10)
+* Add `max_allowed_email_otp_attempts` configuration, beyond which the code is erased from the session and the user needs to login again (default: 10)
 * Allow configuration of flash messages
 * Fix a routing error if the user is already registered
 

data/README.md

@@ -1,5 +1,7 @@
 # searls-auth
 
+[![Certified Shovelware](https://justin.searls.co/img/shovelware.svg)](https://justin.searls.co/shovelware/)
+
 This gem provides a Ruby on Rails engine that implements a minimal, opinionated, and pleasant email-based authentication system. It has zero other dependencies, which is the correct number of dependencies.
 
 For a detailed walk-through with pictures and whatnot, check out this [example app README](/example/simple_app/README.md). Below you'll find the basic steps for getting started.
@@ -93,6 +95,9 @@ Rails.application.config.after_initialize do
     # Defaults:
     config.auth_methods = [:email_link, :email_otp]
 
+    # Email OTPs expire after 30 minutes by default.
+    # config.email_otp_expiry_minutes = 10
+
     # Link-only (no code in emails, no OTP input shown):
     # config.auth_methods = :email_link
 
@@ -104,6 +109,163 @@ end
 
 One reason you might want to disable e-mail OTP is that it exposes your users to [a pretty easy-to-implement man-in-the-middle attack](https://blog.danielh.cc/blog/passwords).
 
+### Email verification modes
+
+Control whether registration triggers verification emails and whether password login requires a verified email.
+
+```ruby
+# config/initializers/searls_auth.rb
+Rails.application.config.after_initialize do
+  Searls::Auth.configure do |config|
+    # :none (default): No verification emails on registration; password login allowed immediately.
+    # :optional: Send a verification email on registration, allow password login, but remind users until verified.
+    # :required: Send a verification email on registration and block password login until verified.
+    config.email_verification_mode = :none # or :optional, :required
+  end
+end
+```
+
+If you enable the built‑in password login (`config.auth_methods` includes `:password`), we assume your `User` model uses `has_secure_password` (or you can provide custom hooks via `password_verifier` and `password_setter`). Verification status is checked via `email_verified_at` by default and can be customized with `email_verified_predicate`/`email_verified_setter`.
+
+### Password login
+
+Enabling `:password` adds email+password fields to the login and registration flows. Minimal setup looks like this:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_secure_password
+
+  # uncomment if enabling auth_methods :email_link or :email_otp
+  # generates_token_for :email_auth, expires_in: 30.minutes
+end
+
+# db/migrate/XXXX_add_password_columns.rb
+class AddPasswordColumns < ActiveRecord::Migration[8.0]
+  def change
+    add_column :users, :password_digest, :string
+    add_column :users, :email_verified_at, :datetime
+  end
+end
+
+# config/initializers/searls_auth.rb
+Rails.application.config.after_initialize do
+  Searls::Auth.configure do |config|
+    config.auth_methods = [:password] # or any combination like [:password, :email_link, :email_otp]
+    config.email_verification_mode = :required # :none and :optional supported too
+  end
+end
+```
+
+If you already have legacy password hashing, override `password_verifier`/`password_setter` to wrap it, otherwise we'll use conventional `bcrypt` with `has_secure_password` and `password_digest` comparisons. Likewise, if email verification lives on a different column or association, use `email_verified_predicate`/`email_verified_setter` to adapt.
+
+All successful logins still render through the same flows, so make sure your app handles `session[:user_id]` uniformly regardless of which auth method succeeded.
+
+If a registration request doesn't supply a `redirect_path` parameter, searls-auth now falls back to `config.redirect_path_after_register` when choosing both the post-registration redirect and the link embedded in verification emails. Override that proc to point brand-new users somewhere more purposeful than the default root path.
+
+Likewise, successful logins fall back to `config.redirect_path_after_login` whenever no redirect parameters are supplied. Set it to a dashboard or home screen to spare users from landing on `/`.
+
+### Password reset
+
+When `auth_methods` includes `:password`, the engine renders a "Forgot your password?" link beneath the login form. Clicking it walks through a two-step flow: request a reset email and then choose a new password. To enable it, make sure your `User` model issues a token named `:password_reset`. If your app cannot send email, disable the link entirely with `config.password_reset_enabled = false`.
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_secure_password
+
+  # You can skip this if password reset is not enabled:
+  generates_token_for :password_reset, expires_in: 30.minutes
+end
+```
+
+Adjust the expiry window by updating the `expires_in` value above or by providing a custom generator via configuration.
+
+Need rate limiting or business rules before delivering reset emails? Return `false` or `:halt` from `before_password_reset` to silently skip sending while preserving the standard response.
+
+By default we generate tokens via `generates_token_for`, send mail from `Searls::Auth::PasswordResetMailer`, and log the user in immediately after a successful reset. You can override any piece of that behavior:
+
+```ruby
+Searls::Auth.configure do |config|
+  config.password_reset_token_generator = ->(user) { user.generate_token_for(:password_reset) }
+  config.password_reset_token_finder = ->(token) { PasswordResetTokenStore.lookup(token) }
+  config.auto_login_after_password_reset = false # redirect back to login instead
+  config.mail_password_reset_template_path = "my_auth/password_reset_mailer"
+  config.mail_password_reset_template_name = "email"
+  config.before_password_reset = ->(user, params, controller) do
+    PasswordResetThrottle.allow?(user_id: user&.id, ip: controller.request.remote_ip)
+  end
+  config.password_reset_request_view = "my_auth/password_resets/request"
+  config.password_reset_edit_view = "my_auth/password_resets/edit"
+  config.password_reset_enabled = false if Rails.env.development? # hide link without SMTP
+end
+```
+
+### Account settings
+
+When password authentication is enabled you can wire any settings UI to the engine by posting to `searls_auth.settings_path`. A simple Rails form looks like:
+
+```erb
+<%= form_with scope: :settings,
+      url: searls_auth.settings_path,
+      method: :patch,
+      local: true do |f| %>
+  <%= f.password_field :current_password %>
+  <%= f.password_field :password %>
+  <%= f.password_field :password_confirmation %>
+  <%= f.submit "Save" %>
+<% end %>
+```
+
+The controller will rotate or set passwords, requiring the current password when appropriate.
+
+Configure where users land afterwards by overriding `config.redirect_path_after_settings_change` in your initializer so it points back to your own settings page:
+
+```ruby
+Searls::Auth.configure do |config|
+  config.redirect_path_after_settings_change = ->(_user, _params, _request, routes) { routes.settings_path }
+end
+```
+
+If you track password state differently, provide your own `config.password_present_predicate`. You can also adjust the flash messages: `flash_notice_after_settings_update`, `flash_error_after_settings_current_password_missing`, and `flash_error_after_settings_current_password_invalid`.
+
+Want to tweak copy? Override the flash messages `flash_notice_after_password_reset_email`, `flash_notice_after_password_reset`, `flash_error_after_password_reset_token_invalid`, `flash_error_after_password_reset_password_mismatch`, and `flash_error_after_password_reset_password_blank`, or shadow the mailer templates at `app/views/searls/auth/password_reset_mailer/password_reset.html.erb` and `.text.erb`.
+
+#### Triggering a (re)verification email
+
+Users can request another verification email. The engine exposes a PATCH endpoint and helper you can call from your app:
+
+```erb
+<%# Anywhere in your app %>
+<%= link_to "Resend verification email",
+            searls_auth.resend_email_verification_path,
+            data: { turbo_method: :patch } %>
+```
+
+This uses the same mailer and template as login emails. You can override the template in two ways:
+
+- Configure the template path/name:
+
+```ruby
+Searls::Auth.configure do |config|
+  config.mail_login_template_path = "my_auth/mailer"
+  config.mail_login_template_name = "login_link"
+end
+```
+
+- Or create views that shadow the engine’s defaults at `app/views/searls/auth/login_link_mailer/login_link.html.erb` and `.text.erb` in your app.
+
+### Common configurations
+
+| `auth_methods` | `email_verification_mode` | Behavior |
+| --- | --- | --- |
+| `[:email_link, :email_otp]` (default) | `:none` | Passwordless magic link + email OTP. Registration links go straight to the verify screen. |
+| `[:password]` | `:none` | Classic email/password. No email is sent; verify routes redirect back to login. |
+| `[:password, :email_link, :email_otp]` | `:optional` | Users can log in with either password or email. Registration logs the user in immediately and also emails a verification link. |
+| `[:password, :email_link]` | `:required` | Registration emails a link and blocks password login until verified. Resend verification is exposed at `searls_auth.resend_email_verification_path`. |
+
+In every case, `redirect_path` values are normalized to on-site URLs, so forwarding someone to login with `redirect_path: some_path` keeps the eventual redirect on your domain (cross-subdomain redirects still work via `redirect_subdomain`).
+
 ## Use it
 
 Of course, having a user be "logged in" or not doesn't mean anything if your application doesn't do anything with the knowledge. Users that are logged in will have `session[:user_id]` set to the value of the logged-in user's ID. Logged out users won't have anything set to `session[:user_id]`. What you do with that is your job, not this gem. (Wait, after 20 years does this mean I finally understand the difference between authentication and authorization? Better late than never.)

data/app/controllers/searls/auth/base_controller.rb

@@ -2,40 +2,61 @@ require "securerandom"
 
 module Searls
   module Auth
-    class BaseController < ApplicationController # TODO should this be ActionController::Base? Trade-offs?
+    class BaseController < ApplicationController
       helper Rails.application.helpers
       helper Rails.application.routes.url_helpers
+      helper_method :forwardable_params
+
+      def forwardable_params
+        {redirect_path: params[:redirect_path], redirect_subdomain: params[:redirect_subdomain]}.compact_blank
+      end
 
       protected
 
-      def searls_auth_config
-        Searls::Auth.config
+      def attach_email_otp_to_session!(user)
+        session[:searls_auth_email_otp_user_id] = user.id
+        session[:searls_auth_email_otp] = SecureRandom.random_number(1000000).to_s.rjust(6, "0")
+        session[:searls_auth_email_otp_generated_at] = Time.current
+        session[:searls_auth_email_otp_verification_attempts] = 0
       end
 
-      def attach_short_code_to_session!(user)
-        session[:searls_auth_short_code_user_id] = user.id
-        session[:searls_auth_short_code] = SecureRandom.random_number(1000000).to_s.rjust(6, "0")
-        session[:searls_auth_short_code_generated_at] = Time.current
-        session[:searls_auth_short_code_verification_attempts] = 0
+      def reset_expired_email_otp
+        generated_at = session[:searls_auth_email_otp_generated_at]
+        cutoff = Searls::Auth.config.email_otp_expiry_minutes.minutes.ago
+        unless generated_at.present? && (parsed = Searls::Auth::ParsesTimeSafely.new.parse(generated_at)) && parsed > cutoff
+          clear_email_otp_from_session!
+        end
       end
 
-      def reset_expired_short_code
-        if session[:searls_auth_short_code_generated_at].present? &&
-            Time.zone.parse(session[:searls_auth_short_code_generated_at]) < Searls::Auth.config.token_expiry_minutes.minutes.ago
-          clear_short_code_from_session!
-        end
+      def clear_email_otp_from_session!
+        session.delete(:searls_auth_email_otp_user_id)
+        session.delete(:searls_auth_email_otp_generated_at)
+        session.delete(:searls_auth_email_otp)
+        session.delete(:searls_auth_email_otp_verification_attempts)
       end
 
-      def clear_short_code_from_session!
-        session.delete(:searls_auth_short_code_user_id)
-        session.delete(:searls_auth_short_code_generated_at)
-        session.delete(:searls_auth_short_code)
-        session.delete(:searls_auth_short_code_verification_attempts)
+      def log_email_otp_verification_attempt!
+        session[:searls_auth_email_otp_verification_attempts] ||= 0
+        session[:searls_auth_email_otp_verification_attempts] += 1
       end
 
-      def log_short_code_verification_attempt!
-        session[:searls_auth_short_code_verification_attempts] ||= 0
-        session[:searls_auth_short_code_verification_attempts] += 1
+      def target_redirect_url
+        Searls::Auth::BuildsTargetRedirectUrl.new.build(request, params)
+      end
+
+      def redirect_with_host_awareness(target)
+        redirect_to target, allow_other_host: target&.start_with?("http://", "https://")
+      end
+
+      def redirect_after_login(user)
+        if (target = target_redirect_url)
+          redirect_with_host_awareness(target)
+        else
+          redirect_to Searls::Auth.config.resolve(
+            :redirect_path_after_login,
+            user, params, request, main_app
+          ) || searls_auth.login_path
+        end
       end
     end
   end

data/app/controllers/searls/auth/email_verifications_controller.rb

@@ -0,0 +1,57 @@
+module Searls
+  module Auth
+    class EmailVerificationsController < BaseController
+      def resend
+        user = if session[:user_id].present?
+          Searls::Auth.config.user_finder_by_id.call(session[:user_id])
+        elsif session[:searls_auth_pending_email].present?
+          Searls::Auth.config.user_finder_by_email.call(session[:searls_auth_pending_email])
+        end
+
+        if user.blank? || Searls::Auth.config.email_verification_mode == :none
+          flash[:alert] = Searls::Auth.config.resolve(:flash_error_after_verify_attempt_invalid_link, params)
+        else
+          EmailsVerification.new.email(user: user, **forwardable_params)
+          flash[:notice] = Searls::Auth.config.resolve(:flash_notice_after_verification_email_resent, params)
+        end
+
+        if session[:user_id].present?
+          redirect_to searls_auth.verify_path
+        else
+          fallback = if session[:searls_auth_pending_email].present?
+            searls_auth.pending_email_verification_path({
+              email: session[:searls_auth_pending_email],
+              redirect_path: session[:searls_auth_pending_redirect_path],
+              redirect_subdomain: session[:searls_auth_pending_redirect_subdomain]
+            }.compact_blank)
+          else
+            searls_auth.login_path
+          end
+          redirect_back fallback_location: fallback
+        end
+      end
+
+      def show
+        user = Searls::Auth.config.user_finder_by_token.call(params[:token])
+
+        if user.present?
+          unless Searls::Auth.config.email_verified_predicate.call(user)
+            Searls::Auth.config.email_verified_setter.call(user)
+          end
+
+          flash[:notice] = Searls::Auth.config.resolve(:flash_notice_after_email_verified, user, params)
+
+          Searls::Auth.config.after_login_success.call(user)
+          session[:user_id] = user.id
+          session[:has_logged_in_before] = true
+
+          redirect_after_login(user)
+        else
+          flash[:alert] = Searls::Auth.config.resolve(:flash_error_after_verify_attempt_invalid_link, params)
+
+          redirect_to searls_auth.login_path(**forwardable_params)
+        end
+      end
+    end
+  end
+end

data/app/controllers/searls/auth/logins_controller.rb

@@ -1,58 +1,79 @@
 module Searls
   module Auth
     class LoginsController < BaseController
-      before_action :reset_expired_short_code
+      before_action :reset_expired_email_otp
 
       def show
-        render searls_auth_config.login_view, layout: searls_auth_config.layout
+        render Searls::Auth.config.login_view, layout: Searls::Auth.config.layout
       end
 
       def create
-        user = searls_auth_config.user_finder_by_email.call(params[:email])
+        if Searls::Auth.config.auth_methods.include?(:password) && params[:send_login_email].blank?
+          handle_password_login
+        else
+          handle_email_login
+        end
+      end
 
-        if user.present?
-          if searls_auth_config.auth_methods.include?(:email_otp)
-            attach_short_code_to_session!(user)
+      def destroy
+        ResetsSession.new.reset(self, except_for: [:has_logged_in_before])
+        flash[:notice] = Searls::Auth.config.resolve(:flash_notice_after_logout, params)
+        redirect_to searls_auth.login_path
+      end
+
+      private
+
+      def handle_password_login
+        authenticator = AuthenticatesUser.new
+        result = authenticator.authenticate_by_password(params[:email], params[:password], session)
+
+        if result.success?
+          session[:user_id] = result.user.id
+          session[:has_logged_in_before] = true
+
+          flash[:notice] = if Searls::Auth.config.email_verification_mode != :none && !Searls::Auth.config.email_verified_predicate.call(result.user)
+            resend_path = searls_auth.resend_email_verification_path(**forwardable_params)
+            Searls::Auth.config.resolve(:flash_notice_after_login_with_unverified_email, resend_path, params)
           else
-            clear_short_code_from_session!
+            Searls::Auth.config.resolve(:flash_notice_after_login, result.user, params)
           end
-
-          EmailsLink.new.email(
-            user:,
-            redirect_path: params[:redirect_path],
-            redirect_subdomain: params[:redirect_subdomain],
-            short_code: session[:searls_auth_short_code]
-          )
-          flash[:notice] = searls_auth_config.resolve(
-            :flash_notice_after_login_attempt,
-            user, params
-          )
-          redirect_to searls_auth.verify_path(
-            redirect_path: params[:redirect_path],
-            redirect_subdomain: params[:redirect_subdomain]
-          )
+          redirect_after_login(result.user)
+        elsif result.email_unverified?
+          session[:searls_auth_pending_email] = params[:email]
+          resend_path = searls_auth.resend_email_verification_path(**forwardable_params)
+          flash.now[:alert] = Searls::Auth.config.resolve(:flash_error_after_login_attempt_unverified_email, resend_path, params)
+          render Searls::Auth.config.login_view, layout: Searls::Auth.config.layout, status: :unprocessable_content
         else
-          flash.now[:error] = searls_auth_config.resolve(
-            :flash_error_after_login_attempt_unknown_email,
-            searls_auth.register_path(
-              email: params[:email],
-              redirect_path: params[:redirect_path],
-              redirect_subdomain: params[:redirect_subdomain]
-            ),
-            params
-          )
-          render searls_auth_config.login_view, layout: searls_auth_config.layout, status: :unprocessable_entity
+          user = Searls::Auth.config.user_finder_by_email.call(params[:email])
+          flash.now[:alert] = if user.blank?
+            Searls::Auth.config.resolve(:flash_error_after_login_attempt_unknown_email, searls_auth.register_path(email: params[:email], **forwardable_params), params)
+          else
+            Searls::Auth.config.resolve(:flash_error_after_login_attempt_invalid_password, params)
+          end
+          render Searls::Auth.config.login_view, layout: Searls::Auth.config.layout, status: :unprocessable_content
         end
+      rescue NameError
+        flash.now[:alert] = Searls::Auth.config.resolve(:flash_error_after_password_misconfigured, params)
+        render Searls::Auth.config.login_view, layout: Searls::Auth.config.layout, status: :unprocessable_content
       end
 
-      def destroy
-        ResetsSession.new.reset(self, except_for: [:has_logged_in_before])
+      def handle_email_login
+        user = Searls::Auth.config.user_finder_by_email.call(params[:email])
 
-        flash[:notice] = searls_auth_config.resolve(
-          :flash_notice_after_logout,
-          params
-        )
-        redirect_to searls_auth.login_path
+        if user.present?
+          if Searls::Auth.config.auth_methods.include?(:email_otp)
+            attach_email_otp_to_session!(user)
+          else
+            clear_email_otp_from_session!
+          end
+
+          EmailsLink.new.email(user:, email_otp: session[:searls_auth_email_otp], **forwardable_params)
+          flash[:notice] = Searls::Auth.config.resolve(:flash_notice_after_login_attempt, user, params)
+          redirect_to searls_auth.verify_path(**forwardable_params)
+        else
+          flash.now[:alert] = Searls::Auth.config.resolve(:flash_error_after_login_attempt_unknown_email, searls_auth.register_path(email: params[:email], **forwardable_params), params)
+          render Searls::Auth.config.login_view, layout: Searls::Auth.config.layout, status: :unprocessable_content
+        end
       end
     end
   end

data/app/controllers/searls/auth/registrations_controller.rb

@@ -2,47 +2,99 @@ module Searls
   module Auth
     class RegistrationsController < BaseController
       def show
-        render searls_auth_config.register_view, layout: searls_auth_config.layout
+        render Searls::Auth.config.register_view, layout: Searls::Auth.config.layout
       end
 
       def create
         result = CreatesUser.new.call(params)
 
         if result.success?
-          attach_short_code_to_session!(result.user)
-
-          redirect_params = {
-            redirect_path: searls_auth_config.resolve(
-              :redirect_path_after_register,
-              result.user, params, request, main_app
-            )
-          }
-
-          EmailsLink.new.email(
-            user: result.user,
-            short_code: session[:searls_auth_short_code],
-            **redirect_params
-          )
-          flash[:notice] = searls_auth_config.resolve(
-            :flash_notice_after_registration,
-            result.user, params
-          )
-
-          redirect_to searls_auth.verify_path(**redirect_params)
+          user = result.user
+          if password_registration?
+            handle_password_registration(user)
+          else
+            handle_email_registration(user)
+          end
         else
-          flash.now[:error] = searls_auth_config.resolve(
-            :flash_error_after_register_attempt,
-            result.error_messages,
-            searls_auth.login_path(
-              email: params[:email],
-              redirect_path: params[:redirect_path],
-              redirect_subdomain: params[:redirect_subdomain]
-            ),
-            params
-          )
-          render searls_auth_config.register_view, layout: searls_auth_config.layout, status: :unprocessable_entity
+          flash.now[:alert] = Searls::Auth.config.resolve(:flash_error_after_register_attempt, result.error_messages, searls_auth.login_path(email: params[:email], **forwardable_params), params)
+          render Searls::Auth.config.register_view, layout: Searls::Auth.config.layout, status: :unprocessable_content
         end
       end
+
+      def pending_email_verification
+        render Searls::Auth.config.pending_email_verification_view, layout: Searls::Auth.config.layout
+      end
+
+      private
+
+      def password_registration?
+        Searls::Auth.config.auth_methods.include?(:password) && params[:password].present?
+      end
+
+      def email_methods_enabled?
+        (Searls::Auth.config.auth_methods & [:email_link, :email_otp]).any?
+      end
+
+      def handle_password_registration(user)
+        target_path, target_subdomain = registration_redirect_destination(user)
+        if Searls::Auth.config.email_verification_mode != :none
+          EmailsVerification.new.email(user: user, redirect_path: target_path, redirect_subdomain: target_subdomain)
+          session[:searls_auth_pending_email] = user.email
+          session[:searls_auth_pending_redirect_path] = target_path
+          session[:searls_auth_pending_redirect_subdomain] = target_subdomain
+        end
+
+        if Searls::Auth.config.email_verification_mode == :required
+          flash[:notice] = Searls::Auth.config.resolve(:flash_notice_after_registration, user, params)
+          redirect_to searls_auth.pending_email_verification_path({email: user.email, redirect_path: target_path, redirect_subdomain: target_subdomain}.compact_blank)
+        else
+          session[:user_id] = user.id
+          session[:has_logged_in_before] = true
+          flash[:notice] = Searls::Auth.config.resolve(:flash_notice_after_login, user, params)
+          if (target = target_redirect_url)
+            redirect_with_host_awareness(target)
+          else
+            fallback = Searls::Auth.config.resolve(:redirect_path_after_login, user, params, request, main_app)
+            redirect_to(fallback || searls_auth.login_path)
+          end
+        end
+      end
+
+      def handle_email_registration(user)
+        return unless email_methods_enabled?
+        target_path, target_subdomain = registration_redirect_destination(user)
+        enqueue_login_verification_email(user, target_path:, target_subdomain:)
+        flash[:notice] = Searls::Auth.config.resolve(:flash_notice_after_registration, user, params)
+        redirect_to searls_auth.verify_path(**forwardable_params)
+      end
+
+      def registration_redirect_destination(user)
+        if redirect_params_supplied?
+          [params[:redirect_path], params[:redirect_subdomain]]
+        else
+          [Searls::Auth.config.resolve(:redirect_path_after_register, user, params, request, main_app), nil]
+        end
+      end
+
+      def redirect_params_supplied?
+        params[:redirect_path].present? || params[:redirect_subdomain].present?
+      end
+
+      def enqueue_login_verification_email(user, target_path:, target_subdomain:)
+        email_otp = nil
+        if Searls::Auth.config.auth_methods.include?(:email_otp)
+          attach_email_otp_to_session!(user)
+          email_otp = session[:searls_auth_email_otp]
+        else
+          clear_email_otp_from_session!
+        end
+        EmailsLink.new.email(
+          user: user,
+          email_otp: email_otp,
+          redirect_path: target_path,
+          redirect_subdomain: target_subdomain
+        )
+      end
     end
   end
 end

data/app/controllers/searls/auth/requests_password_resets_controller.rb

@@ -0,0 +1,55 @@
+module Searls
+  module Auth
+    class RequestsPasswordResetsController < BaseController
+      before_action :ensure_password_reset_enabled
+      before_action :clear_email_otp_from_session!, only: [:show, :create]
+
+      def show
+        render Searls::Auth.config.password_reset_request_view, layout: Searls::Auth.config.layout
+      end
+
+      def create
+        email = params[:email].to_s.strip
+        user = Searls::Auth.config.user_finder_by_email.call(email)
+
+        if proceed_with_password_reset_request?(user) && deliverable_user?(user)
+          Searls::Auth::DeliversPasswordReset.new.deliver(
+            user:,
+            redirect_path: params[:redirect_path],
+            redirect_subdomain: params[:redirect_subdomain]
+          )
+        end
+
+        flash[:notice] = Searls::Auth.config.resolve(:flash_notice_after_password_reset_email, params)
+        redirect_to searls_auth.password_reset_request_path(
+          email: email,
+          redirect_path: params[:redirect_path],
+          redirect_subdomain: params[:redirect_subdomain]
+        )
+      end
+
+      private
+
+      def ensure_password_reset_enabled
+        return if Searls::Auth.config.password_reset_enabled?
+
+        flash[:alert] = Searls::Auth.config.resolve(:flash_error_after_password_reset_not_enabled, params)
+        redirect_to searls_auth.login_path(
+          redirect_path: params[:redirect_path],
+          redirect_subdomain: params[:redirect_subdomain]
+        )
+        nil
+      end
+
+      def deliverable_user?(user)
+        return false if user.blank?
+        Searls::Auth.config.password_present?(user)
+      end
+
+      def proceed_with_password_reset_request?(user)
+        result = Searls::Auth.config.before_password_reset.call(user, params, self)
+        !(result == false || result == :halt)
+      end
+    end
+  end
+end