add_auth 0.2.1

data/lib/add_auth/rails/doctor.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "add_auth/rails/ejection"
+
+module AddAuth
+  module Rails
+    class Doctor
+      attr_reader :ejections
+
+      SESSION_COLUMNS = %w[user_id token_digest authenticated_with authenticated_at expires_at last_seen_at revoked_at
+        elevated_at elevated_with elevation_purpose elevation_credential_id elevation_uv].freeze
+      TOKEN_COLUMNS = %w[user_id digest identifier_digest purpose expires_at consumed_at revoked_at delivery_payload
+        request_id delivery_lease_key delivery_lease_until delivered_at].freeze
+
+      def call
+        @problems = []
+        config = AddAuth.configuration
+        check("Configure valid maintenance batch size and retention durations") do
+          Core::Maintenance.new(stores: {}, options: config.maintenance, enqueue: ->(*) {})
+        end
+        if config.session.enabled
+          columns(::Session, SESSION_COLUMNS, "session")
+          unique_index(::Session, "token_digest")
+          unique_index(::User, "email_address")
+          check("Include AddAuth authentication after the host Authentication concern") do
+            ::ApplicationController.instance_method(:find_session_by_cookie).owner == Authentication
+          end
+          %i[add_auth_write_cookie add_auth_accept add_auth_replacement_session terminate_session require_add_auth_authentication].each do |hook|
+            check("Restore the hardened cookie/session hook #{hook}") do
+              ::ApplicationController.instance_method(hook).owner == Authentication
+            end
+          end
+          check("Include AddAuth::Rails::UserLifecycle in User") { ::User < UserLifecycle }
+          check("Set passwords_enabled to true or false") { [true, false].include?(config.passwords_enabled) }
+          if config.passwords_enabled || defined?(::SessionsController)
+            check("Install the shared password entry in SessionsController") { ::SessionsController < PasswordEntry }
+          end
+          if config.passwords_enabled
+            check("Keep Rails password authentication on User when passwords are enabled") do
+              ::User.column_names.include?("password_digest") && ::User.respond_to?(:authenticate_by)
+            end
+          end
+          %w[/sign-in /add_auth.css /add_auth/boot.js /add_auth/turbo.js /add_auth/stimulus.js /add_auth/challenge.js /sessions].each do |path|
+            check("Install route #{path}") { ::Rails.application.routes.recognize_path(path, method: :get) }
+          end
+          check("Configure valid session timeouts and digest adapters") { Runtime.sessions }
+          cache = config.rate_limit_store || ::Rails.cache
+          check("Configure an atomic rate-limit cache") do
+            key = "add_auth:doctor:#{SecureRandom.hex(16)}"
+            begin
+              cache.increment(key, 1, expires_in: 30, initial: 0) == 1 && cache.increment(key, 1, expires_in: 30, initial: 0) == 2
+            ensure
+              cache.delete(key)
+            end
+          end
+          if ::Rails.env.production?
+            check("Enable CSRF protection for authentication") { ::ApplicationController.allow_forgery_protection }
+            check("Use a shared rate-limit cache in production") do
+              !cache.is_a?(ActiveSupport::Cache::MemoryStore) && !cache.is_a?(ActiveSupport::Cache::NullStore)
+            end
+          end
+        end
+        if config.email_link.enabled
+          check("Enable session_upgrade before email_link") { config.session.enabled }
+          check("Configure base_url as a fixed HTTPS origin (HTTP only outside production)") { Runtime.sign_in_url("validation") }
+          columns(defined?(::AddAuthSignInToken) && ::AddAuthSignInToken, TOKEN_COLUMNS, "email delivery")
+          if defined?(::AddAuthSignInToken)
+            unique_index(::AddAuthSignInToken, "digest")
+            unique_index(::AddAuthSignInToken, "request_id")
+          end
+          if config.email_link.same_browser
+            columns(defined?(::AddAuthSignInToken) && ::AddAuthSignInToken, ["browser_digest"], "email browser binding")
+          end
+        end
+        if config.email_link.enabled || config.notifications.enabled
+          check("Configure mail_from") { config.mail_from.is_a?(String) && !config.mail_from.strip.empty? }
+          check("Enable Action Mailer delivery") { ActionMailer::Base.perform_deliveries && ActionMailer::Base.raise_delivery_errors }
+          if ::Rails.env.production?
+            check("Use a durable job adapter in production") { !ActiveJob::Base.queue_adapter.class.name.match?(/Async|Inline|Test/) }
+            check("Configure production mail delivery") { !%i[test file].include?(ActionMailer::Base.delivery_method) }
+          end
+        end
+        maintenance_needed = config.passkeys.enabled || config.email_link.enabled || config.notifications.enabled || config.maintenance.session_retention
+        if ::Rails.env.production? && maintenance_needed
+          check("Schedule add_auth:deliver_pending every minute; no successful cleanup in the last two minutes") { Runtime.maintenance_current? }
+        end
+        if config.passkeys.enabled
+          check("Configure passkey prerequisites, RP ID, exact origins, anonymous_limit and a safe support path") { Runtime.passkeys }
+          columns(::User, %w[webauthn_id add_auth_strict add_auth_policy_version], "passkeys")
+          columns(::Session, %w[authentication_policy_version authentication_credential_id authentication_uv], "passkeys")
+          columns(defined?(::AddAuthCredential) && ::AddAuthCredential,
+            %w[user_id external_id public_key sign_count revoked_at backup_eligible backup_state], "passkeys")
+          columns(defined?(::AddAuthCeremony) && ::AddAuthCeremony,
+            %w[digest challenge kind browser_digest configuration_digest session_id session_digest expires_at consumed_at], "passkeys")
+          unique_index(::User, "webauthn_id")
+          unique_index(::AddAuthCredential, "external_id") if defined?(::AddAuthCredential)
+          unique_index(::AddAuthCeremony, "digest") if defined?(::AddAuthCeremony)
+          check("Supply a trusted recovery address callback") { config.trusted_recovery_address.respond_to?(:call) }
+          %w[/passkeys /recover /add_auth/passkey.js /add_auth/codec.js].each do |path|
+            check("Install route #{path}") { ::Rails.application.routes.recognize_path(path, method: :get) }
+          end
+          check("Keep a support route for strict accounts") do
+            !::User.exists?(add_auth_strict: true) || Core::Sessions.safe_return(config.support_url)
+          end
+        end
+        if config.notifications.enabled
+          columns(defined?(::AddAuthSecurityEvent) && ::AddAuthSecurityEvent,
+            %w[kind digest delivery_payload delivery_lease_key delivery_lease_until delivered_at revoked_at expires_at], "security notifications")
+          check("Enable security notification delivery errors") { ::AddAuth::SecurityMailer.raise_delivery_errors }
+        end
+        if config.step_up.enabled
+          check("Enable session and email prerequisites for step_up") { config.session.enabled && config.email_link.enabled }
+          columns(::Session, %w[elevation_version elevation_expires_at], "reauthentication")
+          columns(defined?(::AddAuthSignInToken) && ::AddAuthSignInToken,
+            %w[browser_digest session_id session_digest authentication_purpose], "reauthentication")
+          check("Declare valid step-up purposes and safe return destinations") { Runtime.step_up_purposes.any? && Runtime.step_up_policy }
+          %w[/reauthenticate /reauthenticate/link].each do |path|
+            check("Install route #{path}") { ::Rails.application.routes.recognize_path(path, method: :get) }
+          end
+        end
+        if config.challenge_on.any?
+          check("Unknown challenge actions") { (config.challenge_on - %i[sign_in email_link reauthenticate passkey_enrollment]).empty? }
+          check("Configure a challenge provider before setting challenge_on") { !config.challenge.is_a?(Core::Challenge::Null) }
+          if ::Rails.env.production?
+            check("Configure challenge hostname restrictions") { config.challenge.allowed_hostnames&.any? }
+          end
+        end
+        check("Review the ejection manifest and changed upstream files") do
+          @ejections = Ejection.new(host_root: ::Rails.root).report
+          @ejections.none? { |entry| entry[:missing] || entry[:upstream_changed] }
+        end
+        @problems
+      end
+
+      private
+
+      def columns(model, required, feature)
+        check("Run pending #{feature} migrations (required: #{required.join(", ")})") { model && (required - model.column_names).empty? }
+      end
+
+      def unique_index(model, column)
+        check("Add a unique #{model.name}.#{column} index") do
+          model.connection.indexes(model.table_name).any? { |index| index.unique && index.columns == [column] && !index.where }
+        end
+      end
+
+      def check(message)
+        @problems << message unless yield
+      rescue
+        @problems << message
+      end
+    end
+  end
+end

data/lib/add_auth/rails/ejection.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "fileutils"
+
+module AddAuth
+  module Rails
+    class Ejection
+      MANIFEST = "config/add_auth-ejections.json"
+      VIEW_GROUPS = {"email_link" => %w[sign_ins], "sessions" => %w[sessions],
+                     "step_up" => %w[reauthentications], "passkeys" => %w[passkeys recoveries]}.freeze
+
+      def initialize(host_root:, engine_root: File.expand_path("../../..", __dir__))
+        @host, @engine = host_root.to_s, engine_root.to_s
+      end
+
+      def files(kind:, only: "all")
+        case kind
+        when :views
+          groups = (only == "all") ? VIEW_GROUPS.keys : only.split(",")
+          raise ArgumentError, "unknown view group" unless (groups - VIEW_GROUPS.keys).empty?
+          groups.flat_map { |group| VIEW_GROUPS.fetch(group) }.flat_map do |directory|
+            glob("app/views/add_auth/#{directory}/**/*.*erb")
+          end.concat(glob("app/views/layouts/add_auth/**/*.*erb")).uniq.to_h { |path| [path, path] }
+        when :controllers
+          glob("app/controllers/add_auth/*_controller.rb").reject { |path| path.end_with?("assets_controller.rb") }.to_h { |path| [path, path] }
+        when :javascript
+          %w[application codec passkey].to_h do |name|
+            ["app/javascript/add_auth/#{name}.js", "lib/generators/add_auth/javascript/templates/#{name}.js"]
+          end.merge("app/javascript/add_auth/challenge.js" => "lib/generators/add_auth/email_link/templates/add_auth_challenge.js")
+        when :mailer_views
+          glob("app/views/add_auth/*_mailer/*.*erb").to_h { |path| [path, path] }
+        else
+          raise ArgumentError, "unknown ejection kind"
+        end
+      end
+
+      def install(kind:, only: "all")
+        manifest = read_manifest
+        results = files(kind: kind, only: only).map do |destination, source|
+          body = File.read(File.join(@engine, source))
+          generated = decorate(body, destination)
+          path = File.join(@host, destination)
+          existed = File.exist?(path)
+          unless existed
+            FileUtils.mkdir_p(File.dirname(path))
+            File.write(path, generated)
+          end
+          # Reruns never advance the baseline of a file already owned by a host.
+          manifest[destination] ||= {"version" => AddAuth::VERSION, "source" => source,
+                                     "source_hash" => hash(body), "generated_hash" => hash(generated), "baseline" => body}
+          {path: destination, preserved: existed}
+        end
+        path = File.join(@host, MANIFEST)
+        FileUtils.mkdir_p(File.dirname(path))
+        temporary = "#{path}.#{Process.pid}.tmp"
+        File.write(temporary, JSON.pretty_generate({"files" => manifest}) + "\n")
+        File.rename(temporary, path)
+        results
+      ensure
+        FileUtils.rm_f(temporary) if temporary
+      end
+
+      def report
+        inventory = %i[views controllers javascript mailer_views].each_with_object({}) { |kind, all| all.merge!(files(kind: kind)) }
+        read_manifest.map do |destination, entry|
+          unless inventory[destination] == entry["source"] && entry["baseline"].is_a?(String) && hash(entry["baseline"]) == entry["source_hash"]
+            raise AddAuth::Error, "invalid ejection manifest entry"
+          end
+          source = File.read(File.join(@engine, entry.fetch("source")))
+          path = File.join(@host, destination)
+          upstream_changed = hash(source) != entry.fetch("source_hash")
+          {path: destination, missing: !File.file?(path), customized: File.file?(path) && hash(File.read(path)) != entry["generated_hash"],
+           upstream_changed: upstream_changed,
+           diff: upstream_changed ? difference(destination, entry.fetch("baseline"), source, entry.fetch("version")) : nil}
+        end
+      end
+
+      def asset(name)
+        destination = "app/javascript/add_auth/#{name}.js"
+        source = files(kind: :javascript).fetch(destination)
+        host_path = File.join(@host, destination)
+        File.file?(host_path) ? host_path : File.join(@engine, source)
+      end
+
+      private
+
+      def glob(pattern)
+        Dir.glob(File.join(@engine, pattern)).sort.map { |path| path.delete_prefix(@engine + "/") }
+      end
+
+      def hash(body) = ::Digest::SHA256.hexdigest(body)
+
+      def decorate(body, path)
+        text = "AddAuth ejection: #{AddAuth::VERSION}; source SHA256: #{hash(body)}"
+        prefix = if path.end_with?(".erb")
+          "<%# #{text} %>"
+        elsif path.end_with?(".js")
+          "// #{text}"
+        else
+          "# #{text}"
+        end
+        "#{prefix}\n#{body}"
+      end
+
+      def read_manifest
+        path = File.join(@host, MANIFEST)
+        return {} unless File.exist?(path)
+        raise AddAuth::Error, "ejection manifest is too large" if File.size(path) > 5_000_000
+        value = JSON.parse(File.read(path)).fetch("files")
+        raise AddAuth::Error, "invalid ejection manifest" unless value.is_a?(Hash) && value.values.all? { |entry| entry.is_a?(Hash) }
+        value
+      rescue JSON::ParserError, KeyError
+        raise AddAuth::Error, "invalid ejection manifest"
+      end
+
+      # A valid unified replacement hunk, trimmed to three unchanged context
+      # lines at each end. Compare pristine upstream versions, never host secrets.
+      def difference(path, before, after, version)
+        old, current = before.lines, after.lines
+        prefix = 0
+        prefix += 1 while prefix < [old.size, current.size].min && old[prefix] == current[prefix]
+        suffix = 0
+        suffix += 1 while suffix < [old.size, current.size].min - prefix && old[-suffix - 1] == current[-suffix - 1]
+        first = [prefix - 3, 0].max
+        tail = [suffix - 3, 0].max
+        old_part = old[first...(old.size - tail)]
+        new_part = current[first...(current.size - tail)]
+        old_start = old_part.empty? ? first : first + 1
+        new_start = new_part.empty? ? first : first + 1
+        header = "--- #{path} (#{version})\n+++ #{path} (#{AddAuth::VERSION})\n"
+        header += "@@ -#{old_start},#{old_part.size} +#{new_start},#{new_part.size} @@\n"
+        header + old_part.map { |line| "-#{line}" }.join + new_part.map { |line| "+#{line}" }.join
+      end
+    end
+  end
+end

data/lib/add_auth/rails/elevation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "add_auth/rails/runtime"
+
+module AddAuth
+  module Rails
+    module Elevation
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # A navigation guard, not mutation authorization. Use the block helper
+        # below for writes, alongside the host's resource authorization.
+        def require_elevated_session(purpose:, **options)
+          before_action(**options) { add_auth_require_elevation(purpose) }
+        end
+      end
+
+      private
+
+      def with_elevated_session(purpose:, &block)
+        raise ArgumentError, "a database mutation block is required" unless block
+        Runtime.sessions.with_elevation(user: Current.user, session: Current.session,
+          purpose: purpose, policy: Runtime.step_up_policy, &block)
+      end
+
+      def add_auth_require_elevation(purpose)
+        return require_authentication unless authenticated?
+        result = Runtime.sessions.with_elevation(user: Current.user, session: Current.session,
+          purpose: purpose, policy: Runtime.step_up_policy)
+        return if result.success?
+        redirect_to "/reauthenticate?#{URI.encode_www_form(purpose: purpose)}", status: request.get? ? :found : :see_other
+      end
+    end
+  end
+end

data/lib/add_auth/rails/engine.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "turbo-rails"
+require "add_auth/rails/authentication_pages"
+
+module AddAuth
+  module Rails
+    # Non-isolated: host controllers/views remain in the host namespace.
+    class Engine < ::Rails::Engine
+      engine_name "add_auth"
+
+      initializer "add_auth.filter_parameters" do |app|
+        app.config.filter_parameters += [:token, :password, :delivery_payload, :token_digest, :encrypted_identifier, :browser_digest, :session_digest, :elevation_version, :add_auth_browser, :credential, :transaction, :challenge, :external_id, :public_key, :"cf-turnstile-response", :"g-recaptcha-response"]
+      end
+
+      config.to_prepare do
+        if AddAuth.configuration.session.enabled
+          require "add_auth/rails/password_entry"
+          require "add_auth/rails/elevation"
+          ::ApplicationController.include AddAuth::Rails::Elevation
+          if AddAuth.configuration.passwords_enabled || defined?(::SessionsController)
+            ::SessionsController.include AddAuth::Rails::PasswordEntry
+          end
+        end
+      end
+
+      initializer "add_auth.configuration", before: :load_config_initializers do |app|
+        AddAuth.configuration.digest_secret ||= -> {
+          app.key_generator.generate_key("add_auth.digest-base-secret.v1", 32)
+        }
+      end
+    end
+  end
+end

data/lib/add_auth/rails/password_entry.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "add_auth/rails/authentication_pages"
+
+module AddAuth
+  module Rails
+    # Protects every route to the generated SessionsController#create, including
+    # host aliases. Keep the host file intact, but make the shared entry point the
+    # authority. Verify CSRF explicitly before rendering halts later callbacks.
+    module PasswordEntry
+      extend ActiveSupport::Concern
+      include AuthenticationPages
+
+      included do
+        helper AddAuth::SignInsHelper
+        protect_from_forgery with: :exception
+        prepend_before_action :add_auth_password_entry, only: %i[new create]
+        rescue_from AddAuth::Error, with: :service_unavailable
+      end
+
+      private
+
+      def add_auth_password_entry
+        if action_name == "new"
+          private_response
+          return page("form")
+        end
+        verify_authenticity_token
+        private_response
+        add_auth_password_sign_in
+      end
+    end
+  end
+end

data/lib/add_auth/rails/runtime.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "uri"
+require "add_auth/rails/stores/sessions"
+require "add_auth/rails/stores/email_tokens"
+require "add_auth/rails/delivery_cipher"
+
+module AddAuth
+  module Rails
+    module Runtime
+      module_function
+
+      def config = AddAuth.configuration
+
+      def sessions
+        Core::Sessions.new(store: Stores::Sessions.new(user_model: ::User, session_model: ::Session),
+          digest: config.session_token_digest, eligible: config.eligible, lifetime: config.session.lifetime,
+          idle_timeout: config.session.idle_timeout, legacy_bridge_until: config.session.legacy_bridge_until, access_policy: access_policy)
+      end
+
+      def security_events
+        raise AddAuth::Error, "enable notifications first" unless config.notifications.enabled
+        require "add_auth/rails/stores/security_events"
+        Core::SecurityEvents.new(store: Stores::SecurityEvents.new(user_model: ::User, event_model: ::AddAuthSecurityEvent),
+          digest: config.sign_in_token_digest, delivery_cipher: DeliveryCipher.new(key: key("security-notifications")))
+      end
+
+      def access_policy
+        Core::AccessPolicy.new(credentials: ->(id) {
+          ::AddAuthCredential.find_by(external_id: id) if defined?(::AddAuthCredential) && ::AddAuthCredential.table_exists?
+        }, passkeys_enabled: config.passkeys.enabled, email_enabled: Core::Intake.email_available?(config),
+          trusted_recovery_address: config.trusted_recovery_address, password_enabled: config.passwords_enabled)
+      end
+
+      def email(purpose: :sign_in)
+        if purpose.to_s != "sign_in" && !config.step_up.enabled
+          raise AddAuth::Error, "enable step_up first"
+        end
+        raise AddAuth::Error, "enable session_upgrade and email_link first" unless Core::Intake.email_available?(config)
+        Core::Strategies::EmailLink.new(store: Stores::EmailTokens.new(user_model: ::User,
+          token_model: ::AddAuthSignInToken, session_model: ::Session), digest: config.sign_in_token_digest,
+          delivery_cipher: DeliveryCipher.new(key: key("delivery")), eligible: config.eligible,
+          normalize_identifier: method(:normalize), identifier_for: ->(user) { user.email_address },
+          token_lifetime: {"reauthentication" => 300, "recovery" => 1200}.fetch(purpose.to_s, config.email_link.token_lifetime),
+          same_browser: (purpose.to_s == "recovery") ? false : config.email_link.same_browser, purpose: purpose,
+          proof_allowed: ->(user) { (purpose.to_s == "recovery") ? access_policy.recoverable?(user) && config.passkeys.enabled : purpose.to_s != "sign_in" || access_policy.sign_in_allowed?(user, :email_link) },
+          sessions: (purpose.to_s == "sign_in") ? nil : sessions,
+          policy: (purpose.to_s == "sign_in") ? nil : step_up_policy)
+      end
+
+      def revoke_all(user:, session:, **proof)
+        policy = step_up_policy
+        current = sessions.with_elevation(user: user, session: session, purpose: :sign_out_everywhere, policy: policy)
+        if current.success?
+          count = sessions.revoke_all(user: user, session: session, grant: current.credential)
+          return count ? Result.success(user: user, strategy: :step_up) : Result.failure(reason: :elevation_required)
+        end
+        authorization = reauthenticate(user: user, session: session, **proof)
+        return authorization unless authorization.success?
+        count = sessions.revoke_all(user: user, session: session, grant: authorization.credential)
+        count ? Result.success(user: user, strategy: :step_up) : Result.failure(reason: :elevation_required)
+      end
+
+      def reauthenticate(user:, session:, password:, ip:, challenge_token:)
+        admitted = intake.call(identifier: user.email_address, ip: ip, action: :reauthenticate, challenge_token: challenge_token)
+        return Result.failure(reason: admitted) if admitted.is_a?(Symbol)
+        policy = config.step_up.enabled ? step_up_policy : Core::StepUp.new(purposes: {sign_out_everywhere: {methods: [:password]}})
+        sessions.reauthenticate(user: user, session: session, purpose: :sign_out_everywhere, policy: policy) do |account|
+          authenticate_password(identifier: account.email_address, password: password)
+        end
+      end
+
+      def step_up_purposes
+        defaults = if config.passkeys.enabled
+          {
+            manage_passkeys: {methods: [:password, :email_link, :passkey], return_to: "/passkeys", label: "manage your passkeys"},
+            manage_policy: {methods: [:passkey], require_passkey: true, return_to: "/passkeys", label: "change your recovery policy"},
+            recover_passkeys: {methods: [:email_link], return_to: "/passkeys", label: "replace a lost passkey", reauthentication: false}
+          }
+        else
+          {}
+        end
+        {sign_out_everywhere: {methods: [:password, :email_link, :passkey], return_to: "/sessions/revoke-all", label: "sign out everywhere"}}.merge(defaults).merge(config.step_up.purposes)
+      end
+
+      def passkeys
+        raise AddAuth::Error, "enable passkeys and their prerequisites first" unless config.passkeys.enabled && config.step_up.enabled && config.notifications.enabled
+        require "add_auth/rails/stores/passkeys"
+        Core::Strategies::Passkey.new(store: Stores::Passkeys.new(user_model: ::User, session_model: ::Session,
+          credential_model: ::AddAuthCredential, ceremony_model: ::AddAuthCeremony, token_model: ::AddAuthSignInToken), sessions: sessions,
+          policy: step_up_policy, access_policy: access_policy, digest: config.sign_in_token_digest,
+          eligible: config.eligible, rp_id: config.passkeys.rp_id, origins: config.passkeys.origins, name: config.passkeys.name,
+          limiter: method(:limit), anonymous_limit: config.passkeys.anonymous_limit,
+          notify: ->(**event) { security_events.issue(**event) }, allow_localhost: !::Rails.env.production?, support_url: config.support_url,
+          on_failure: ->(reason) { ::ActiveSupport::Notifications.instrument("passkey_failure.add_auth", reason: reason) })
+      end
+
+      def step_up_policy
+        Core::StepUp.new(purposes: config.step_up.enabled ? step_up_purposes : {}, fresh_for: config.step_up.fresh_for,
+          strong_for: config.step_up.strong_for,
+          password_version: ->(user) { config.sign_in_token_digest.digest("password:#{user.password_digest}") },
+          credential_current: ->(user:, evidence:) {
+            evidence.method == :password ||
+              (evidence.method == :passkey && access_policy.credential_current?(user: user, id: evidence.credential_id) &&
+                ::AddAuthCredential.find_by(external_id: evidence.credential_id)&.public_key == evidence.credential_version) ||
+              (evidence.method == :email_link && Core::Intake.email_available?(config) &&
+              config.sign_in_token_digest.matches?(evidence.credential_version, "identifier:#{normalize(user.email_address)}"))
+          }, methods_available: ->(user) { access_policy.methods_for(user) })
+      end
+
+      def elevate_password(user:, session:, purpose:, password:, ip:, challenge_token:)
+        return Result.failure(reason: :elevation_required) unless step_up_policy.reauthentication_rule_for(purpose)
+        admitted = intake.call(identifier: user.email_address, ip: ip, action: :reauthenticate, challenge_token: challenge_token)
+        return Result.failure(reason: admitted) if admitted.is_a?(Symbol)
+        proof = sessions.reauthenticate(user: user, session: session, purpose: purpose, policy: step_up_policy) do |account|
+          authenticate_password(identifier: account.email_address, password: password)
+        end
+        return proof unless proof.success?
+        grant = sessions.rotate_for_step_up(user: user, session: session, grant: proof.credential)
+        grant ? Result.success(user: user, strategy: :step_up, session: grant.session, credential: grant) : Result.failure(reason: :elevation_required)
+      end
+
+      def enqueue_recovery(identifier) = enqueue_email_payload({identifier: identifier, purpose: "recovery"})
+
+      def enqueue_reauthentication(user:, session:, purpose:, browser_secret:)
+        payload = {identifier: user.email_address, purpose: "reauthentication", authentication_purpose: purpose.to_s,
+                   session_id: session.id, session_digest: session.token_digest, browser_digest: browser_binding.digest(browser_secret)}
+        enqueue_email_payload(payload)
+      end
+
+      def authenticate_password(identifier:, password:)
+        return unless config.passwords_enabled && ::User.respond_to?(:authenticate_by)
+        ::User.authenticate_by(email_address: identifier, password: password.is_a?(String) ? password : "")
+      end
+
+      def sign_in_path = "/sign-in"
+
+      def normalize(value) = ::User.normalize_value_for(:email_address, value)
+      def key(purpose) = ::Rails.application.key_generator.generate_key("add_auth.#{purpose}.v1", 32)
+
+      def intake_cipher
+        ActiveSupport::MessageEncryptor.new(key("intake"), cipher: "aes-256-gcm", serializer: :json)
+      end
+
+      def browser_binding = Core::BrowserBinding.new(digest: config.sign_in_token_digest)
+
+      def enqueue_email(identifier, browser_secret: nil)
+        payload = {identifier: identifier, browser_digest: email.browser_digest(browser_secret)}
+        enqueue_email_payload(payload)
+      end
+
+      def enqueue_email_payload(payload)
+        job = ::AddAuth::EmailRequestJob.perform_later(encrypt_intake(payload))
+        raise AddAuth::Error, "sign-in queue unavailable" unless job
+        job
+      rescue
+        raise AddAuth::Error, "sign-in queue unavailable", cause: nil
+      end
+
+      def encrypt_intake(identifier)
+        intake_cipher.encrypt_and_sign(identifier, purpose: "sign_in_request", expires_in: 300)
+      end
+
+      def decrypt_intake(payload)
+        intake_cipher.decrypt_and_verify(payload, purpose: "sign_in_request")
+      rescue ActiveSupport::MessageEncryptor::InvalidMessage
+        nil
+      end
+
+      def intake
+        Core::Intake.new(digest: config.sign_in_token_digest, normalizer: method(:normalize),
+          limiter: method(:limit), challenge: config.challenge, challenge_on: config.challenge_on,
+          challenge_when_unavailable: config.challenge_when_unavailable,
+          on_challenge_unavailable: method(:record_challenge_bypass))
+      end
+
+      def record_challenge_bypass(action:)
+        ::ActiveSupport::Notifications.instrument("challenge_bypass.add_auth", action: action)
+      end
+
+      def limit(key:, limit:)
+        Core::RateLimit.new(counter: ->(key:, expires_in:) {
+          rate_limit_cache.increment(key, 1, expires_in: expires_in, initial: 0)
+        }).call(key: key, limit: limit)
+      rescue
+        raise AddAuth::Error, "rate limit store unavailable", cause: nil
+      end
+
+      def rate_limit_cache = config.rate_limit_store || ::Rails.cache
+
+      def maintenance_cache_key = "add_auth:maintenance:v1:#{config.sign_in_token_digest.digest("last-success")}"
+
+      def record_maintenance
+        unless rate_limit_cache.write(maintenance_cache_key, Time.now.to_i, expires_in: 180)
+          raise AddAuth::Error, "maintenance heartbeat store unavailable"
+        end
+      end
+
+      def maintenance_current?
+        completed = rate_limit_cache.read(maintenance_cache_key)
+        completed.is_a?(Integer) && (0..120).cover?(Time.now.to_i - completed)
+      end
+
+      def sign_in_url(token, purpose: "sign_in")
+        uri = URI.parse(config.base_url.to_s)
+        valid = uri.host && !uri.userinfo && !uri.query && !uri.fragment && ["", "/"].include?(uri.path) &&
+          (uri.scheme == "https" || (!::Rails.env.production? && uri.scheme == "http"))
+        unless valid
+          raise AddAuth::Error, "configure base_url as a fixed HTTPS origin (HTTP allowed only outside production)"
+        end
+        path = {"sign_in" => "/sign-in/link", "reauthentication" => "/reauthenticate/link", "recovery" => "/recover/link"}.fetch(purpose.to_s)
+        "#{uri.to_s.delete_suffix("/")}#{path}?token=#{URI.encode_www_form_component(token)}"
+      end
+    end
+  end
+end

data/lib/add_auth/rails/stores/account_lock.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Rails
+    module Stores
+      class AccountLock
+        def initialize(user_model)
+          @users = user_model
+        end
+
+        def call(id:, additional_id: nil)
+          return yield nil unless id
+          if @users.connection.transaction_open?
+            raise AddAuth::Error, "authentication must own its transaction, not run inside an outer transaction"
+          end
+          completed = false
+          result = nil
+          @users.uncached do
+            @users.transaction(requires_new: true) do |transaction|
+              transaction.after_commit { completed = true }
+              # Opposing account switches acquire their locks in the same order.
+              accounts = [id, additional_id].compact.uniq.sort_by(&:to_s).map do |account_id|
+                if @users.connection.adapter_name == "SQLite"
+                  pk = @users.connection.quote_column_name(@users.primary_key)
+                  @users.where(@users.primary_key => account_id).update_all("#{pk} = #{pk}")
+                  @users.find_by(@users.primary_key => account_id)
+                else
+                  @users.lock.find_by(@users.primary_key => account_id)
+                end
+              end
+              result = yield accounts.compact.find { |account| account.id == id }
+            end
+          end
+          raise AddAuth::Error, "authentication transaction rolled back" unless completed
+          result
+        end
+      end
+    end
+  end
+end