add_auth 0.2.2 → 0.3.0

data/lib/add_auth/migration/static_inventory.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "ripper"
+require "pathname"
+require "add_auth/core/migration/readiness"
+
+module AddAuth
+  module Migration
+    # Reads a bounded set of source files as data. Never require/load/eval a host.
+    class StaticInventory
+      MAX_FILES = 2000
+      MAX_BYTES = 1_048_576
+      TOTAL_BYTES = 16 * 1_048_576
+      PATTERNS = %w[app/models/**/*.rb app/controllers/**/*.rb app/services/**/*.rb app/jobs/**/*.rb app/workers/**/*.rb app/mailers/**/*.rb app/helpers/**/*.rb lib/**/*.rb lib/tasks/**/*.rake config/initializers/**/*.rb config/routes.rb db/schema.rb spec/factories/**/*.rb spec/support/**/*.rb].freeze
+      SURFACES = {
+        devise: %w[Devise devise devise_for devise_scope], warden: %w[warden Warden],
+        guards: %w[authenticate_user! current_user user_signed_in? authenticated],
+        passwords: %w[encrypted_password password_digest valid_password? password=],
+        tokens: %w[authentication_token MobileAuthToken reset_password_token confirmation_token unlock_token],
+        providers: %w[OmniAuth omniauth omniauth_callbacks],
+        eligibility: %w[active_for_authentication? inactive_message locked_at confirmed_at disabled_at]
+      }.freeze
+
+      def initialize(root:)
+        @root = File.realpath(root)
+      end
+
+      def call
+        @complete = true
+        @remaining_bytes = TOTAL_BYTES
+        paths = PATTERNS.flat_map { |pattern| Dir.glob(File.join(@root, pattern)) }.uniq.sort
+        @complete = false if paths.length > MAX_FILES
+        sources = paths.first(MAX_FILES).filter_map do |path|
+          source = read(path)
+          next unless source
+          lexical = Ripper.lex(source)
+          tokens = lexical.reject { |(_, kind, _, _)| %i[on_comment on_tstring_content].include?(kind) }
+          literal_keys = lexical.filter_map { |(_, kind, value, _)| value if kind == :on_tstring_content && SURFACES.values.flatten.include?(value) }
+          tree = Ripper.sexp(source)
+          @complete = false unless tree
+          [relative(path), {tokens: tokens.map { |token| token[2] }, literal_keys: literal_keys, tree: tree}]
+        end.to_h
+        calls = sources.values.flat_map { |source| devise_calls(source[:tree]) }
+        names = calls.flatten
+        unknown = names.count { |name| !Core::Migration::Readiness::MODULES.include?(name) }
+        @complete = false if names.include?(nil)
+        lock = read(File.join(@root, "Gemfile.lock")) || ""
+        versions = %w[devise rails ruby bcrypt].to_h do |name|
+          version = if name == "ruby"
+            lock[/^   ruby (\d+\.\d+\.\d+)/, 1]
+          else
+            lock[/^    #{Regexp.escape(name)} \((\d+\.\d+(?:\.\d+)*(?:[.a-z0-9-]*))\)/, 1]
+          end
+          [name.to_sym, version]
+        end
+        extensions = Core::Migration::Readiness::EXTENSIONS.select { |name| lock.match?(/^    #{Regexp.escape(name)} \(/) }
+        targets = Core::Migration::Readiness::TARGETS.select { |path| sources.key?(path) }
+        user = sources.dig("app/models/user.rb", :tokens) || []
+        facts = {mode: "static", complete: @complete, versions: versions,
+                 modules: (names.compact & Core::Migration::Readiness::MODULES).sort,
+                 unknown_modules: unknown, extensions: extensions, scope_count: calls.length,
+                 rails_contract: targets.length == Core::Migration::Readiness::TARGETS.length && user.include?("has_secure_password") && user.include?("normalizes"),
+                 target_conflicts: targets, files_inspected: sources.length,
+                 surfaces: SURFACES.transform_values { |terms| sources.filter_map { |path, source| path if ((source[:tokens] + source[:literal_keys]) & terms).any? } }}
+        Core::Migration::Readiness.new.call(facts)
+      end
+
+      private
+
+      def read(path)
+        # Reject symlinks at any depth, even those pointing to another host file.
+        current = Pathname.new(path)
+        while current.to_s != @root
+          return incomplete if current.symlink?
+          parent = current.parent
+          return incomplete if parent == current
+          current = parent
+        end
+        return incomplete unless File.file?(path)
+        return incomplete if @remaining_bytes <= 0
+        File.open(path, "rb") do |file|
+          limit = [MAX_BYTES, @remaining_bytes].min
+          source = file.read(limit + 1)
+          @remaining_bytes -= source.bytesize
+          return incomplete if source.bytesize > limit
+          source.force_encoding(Encoding::UTF_8)
+          return incomplete unless source.valid_encoding?
+          source
+        end
+      rescue SystemCallError
+        incomplete
+      end
+
+      def incomplete
+        @complete = false
+        nil
+      end
+
+      def relative(path) = Pathname.new(path).relative_path_from(Pathname.new(@root)).to_s
+
+      def devise_calls(node)
+        return [] unless node.is_a?(Array)
+        arguments = if node[0] == :command && node.dig(1, 1) == "devise"
+          node[2]
+        elsif node[0] == :method_add_arg && node.dig(1, 0) == :fcall && node.dig(1, 1, 1) == "devise"
+          node.dig(2, 1)
+        end
+        if arguments
+          args = (arguments[0] == :args_add_block) ? arguments[1] : []
+          return [args.reject { |arg| arg[0] == :bare_assoc_hash }.map { |arg| (arg[0] == :symbol_literal) ? arg.dig(1, 1, 1) : nil }]
+        end
+        node.flat_map { |child| child.is_a?(Array) ? devise_calls(child) : [] }
+      end
+    end
+  end
+end

data/lib/add_auth/rails/account_password_entry.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Rails
+    module AccountPasswordEntry
+      extend ActiveSupport::Concern
+
+      included do
+        protect_from_forgery with: :exception
+        prepend_before_action :add_auth_account_password_entry, only: %i[new create edit update]
+      end
+
+      private
+
+      def add_auth_account_password_entry
+        return unless AddAuth.configuration.lifecycle.enabled
+        verify_authenticity_token unless request.get? || request.head?
+        response.set_header("Cache-Control", "no-store")
+        response.set_header("Referrer-Policy", "no-referrer")
+        redirect_to "/account/requests/reset_password", status: request.get? ? :found : :see_other
+      end
+    end
+  end
+end

data/lib/add_auth/rails/authentication.rb

@@ -27,7 +27,7 @@ module AddAuth
       end
 
       def add_auth_session_hints
-        {user_agent: request.user_agent.to_s.truncate_bytes(512), ip_address: request.remote_ip}
+        {user_agent: request.user_agent.to_s.truncate_bytes(512), ip_address: request.remote_ip, remember: params[:remember] == "1"}
       end
 
       def add_auth_replacement_session

data/lib/add_auth/rails/authentication_pages.rb

@@ -44,6 +44,11 @@ module AddAuth
 
       def page(partial, status: :ok)
         @page_partial = authentication_partial(partial)
+        # Turbo carries the form's stream Accept header across a 303. Prefer
+        # its HTML option on the destination GET so navigation commits the URL.
+        if (request.get? || request.head?) && request.accepts.include?(Mime[:html])
+          return render "add_auth/sign_ins/show", layout: "add_auth/authentication", formats: [:html], content_type: "text/html", status: status
+        end
         respond_to do |format|
           format.html { render "add_auth/sign_ins/show", layout: "add_auth/authentication", status: status }
           format.turbo_stream { render turbo_stream: turbo_stream.update("add_auth-content", partial: @page_partial), status: status }

data/lib/add_auth/rails/doctor.rb

@@ -33,6 +33,7 @@ module AddAuth
           end
           check("Include AddAuth::Rails::UserLifecycle in User") { ::User < UserLifecycle }
           check("Set passwords_enabled to true or false") { [true, false].include?(config.passwords_enabled) }
+          check("Set turbo_enabled to true or false") { [true, false].include?(config.turbo_enabled) }
           if config.passwords_enabled || defined?(::SessionsController)
             check("Install the shared password entry in SessionsController") { ::SessionsController < PasswordEntry }
           end
@@ -63,6 +64,25 @@ module AddAuth
             end
           end
         end
+        if config.mobile.enabled
+          columns(::Session, %w[transport client_id mobile_idle_timeout], "mobile session")
+          check("Configure explicit bounded mobile timeouts and registered client identifiers") { Runtime.mobile_profile }
+          check("Install mobile session routes") { ::Rails.application.routes.recognize_path("/mobile/session", method: :post) }
+          check("Configure mobile callbacks and Apple providers as explicit maps") do
+            config.mobile.callbacks.is_a?(Hash) && config.mobile.apple_providers.is_a?(Hash)
+          end
+          if config.mobile.callbacks.is_a?(Hash) && config.mobile.callbacks.any?
+            check("Enable reviewed provider integration before mobile handoffs") { config.external_identities.enabled }
+            columns(defined?(::AddAuthMobileHandoff) && ::AddAuthMobileHandoff,
+              %w[user_id external_digest digest client_id callback state challenge_digest credential_id credential_version policy_version authenticated_at issued_at expires_at consumed_at], "mobile handoff")
+            unique_index(::AddAuthMobileHandoff, "digest") if defined?(::AddAuthMobileHandoff)
+            unique_index(::AddAuthMobileHandoff, "external_digest") if defined?(::AddAuthMobileHandoff)
+            check("Use one database pool for mobile handoffs, accounts and sessions") { Runtime.mobile_handoffs }
+          end
+          if config.mobile.apple_providers.is_a?(Hash) && config.mobile.apple_providers.any?
+            check("Configure the optional native Apple library and exact client mapping") { Runtime.native_apple }
+          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") }
@@ -75,7 +95,54 @@ module AddAuth
             columns(defined?(::AddAuthSignInToken) && ::AddAuthSignInToken, ["browser_digest"], "email browser binding")
           end
         end
-        if config.email_link.enabled || config.notifications.enabled
+        if config.external_identities.enabled
+          check("Enable session and step-up prerequisites for provider sign-in") { config.session.enabled && config.step_up.enabled }
+          check("Declare current password verifier support metadata") { config.current_password_support.respond_to?(:available?) }
+          if config.external_identities.providers.any?
+            require "add_auth/rails/provider_libraries/request_protection"
+            check("Configure a supported OmniAuth request validator") { !!ProviderLibraries::RequestProtection.validator }
+          end
+          check("Register at least one reviewed provider profile") { config.external_identities.configurations.any? }
+          columns(defined?(::AddAuthExternalIdentity) && ::AddAuthExternalIdentity,
+            %w[user_id namespace provider_id issuer audience subject provenance credential_version linked_at revoked_at invalidated_at], "external identity")
+          columns(defined?(::AddAuthExternalTransaction) && ::AddAuthExternalTransaction,
+            %w[digest browser_digest provider_id issuer audience purpose user_id session_id session_digest policy_version issued_at expires_at consumed_at enrollment_payload], "external transaction")
+          columns(::Session, %w[authentication_external_id authentication_external_version], "external session evidence")
+          unique_index(::AddAuthExternalIdentity, "namespace") if defined?(::AddAuthExternalIdentity)
+          unique_index(::AddAuthExternalTransaction, "digest") if defined?(::AddAuthExternalTransaction)
+          check("Use one database pool for provider, account and session persistence") { Runtime.external_identities }
+          config.external_identities.providers.each do |provider|
+            check("Install the configured provider callback and preparation routes") do
+              ::Rails.application.routes.recognize_path("/sign-in/providers/#{provider.middleware_name}", method: :post) &&
+                ::Rails.application.routes.recognize_path("/auth/#{provider.middleware_name}/callback", method: provider.apple_form_post? ? :post : :get)
+            end
+          end
+          check("Install provider account management routes") { ::Rails.application.routes.recognize_path("/account/external-identities", method: :get) }
+        end
+        if config.lifecycle.enabled
+          if defined?(::PasswordsController)
+            check("Retire stock password reset entry points through the shared account flow") { ::PasswordsController < AccountPasswordEntry }
+          end
+          columns(::Session, %w[remembered idle_timeout], "remembered browser sessions")
+          check("Enable session, step-up and notification prerequisites for account lifecycle") { config.session.enabled && config.step_up.enabled && config.notifications.enabled }
+          columns(::User, %w[confirmed_at unconfirmed_email locked_at failed_attempts disabled_at deleted_at add_auth_manual_lock add_auth_locked_until add_auth_authority], "account lifecycle")
+          columns(defined?(::AddAuthAccountToken) && ::AddAuthAccountToken,
+            (TOKEN_COLUMNS - %w[identifier_digest]) + %w[address_digest account_version], "account proofs")
+          columns(defined?(::AddAuthAddressClaim) && ::AddAuthAddressClaim, %w[user_id digest state], "address claims")
+          if defined?(::AddAuthAccountToken)
+            unique_index(::AddAuthAccountToken, "digest")
+            unique_index(::AddAuthAccountToken, "request_id")
+          end
+          unique_index(::AddAuthAddressClaim, "digest") if defined?(::AddAuthAddressClaim)
+          check("Configure account policy, profile mapping and local transaction provisioning callbacks") do
+            %i[eligible password_policy profile_attributes provision deletion_allowed delete_account].all? { |name| config.lifecycle.public_send(name).respond_to?(:call) }
+          end
+          check("Configure account proof delivery, lock policy and shared account storage") { Runtime.accounts && Runtime.password_lifecycle && Runtime.account_proof_url("validation", purpose: "confirm") }
+          %w[/account/sign-up /account/requests/confirm /account/email /account/password].each do |path|
+            check("Install route #{path}") { ::Rails.application.routes.recognize_path(path, method: :get) }
+          end
+        end
+        if config.email_link.enabled || config.notifications.enabled || config.lifecycle.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?
@@ -83,7 +150,7 @@ module AddAuth
             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
+        maintenance_needed = config.passkeys.enabled || config.email_link.enabled || config.notifications.enabled || config.lifecycle.enabled || config.external_identities.enabled || config.mobile.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
@@ -122,7 +189,7 @@ module AddAuth
           end
         end
         if config.challenge_on.any?
-          check("Unknown challenge actions") { (config.challenge_on - %i[sign_in email_link reauthenticate passkey_enrollment]).empty? }
+          check("Unknown challenge actions (email proof pages cannot load third-party challenges)") { (config.challenge_on - %i[sign_in email_link reauthenticate passkey_enrollment register account_request provider]).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? }

data/lib/add_auth/rails/ejection.rb

@@ -9,7 +9,7 @@ module AddAuth
     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
+                     "step_up" => %w[reauthentications], "passkeys" => %w[passkeys recoveries], "accounts" => %w[accounts], "providers" => %w[provider_sign_ins external_identities]}.freeze
 
       def initialize(host_root:, engine_root: File.expand_path("../../..", __dir__))
         @host, @engine = host_root.to_s, engine_root.to_s

data/lib/add_auth/rails/engine.rb

@@ -2,6 +2,7 @@
 
 require "turbo-rails"
 require "add_auth/rails/authentication_pages"
+require "add_auth/rails/provider_libraries/callback_route"
 
 module AddAuth
   module Rails
@@ -10,7 +11,7 @@ module AddAuth
       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"]
+        app.config.filter_parameters += [:token, :password, :enrollment_payload, :code, :state, :nonce, :id_token, :access_token, :refresh_token, :client_secret, :authorization_code, :raw_info, :id_info, :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
@@ -21,6 +22,10 @@ module AddAuth
           if AddAuth.configuration.passwords_enabled || defined?(::SessionsController)
             ::SessionsController.include AddAuth::Rails::PasswordEntry
           end
+          if defined?(::PasswordsController)
+            require "add_auth/rails/account_password_entry"
+            ::PasswordsController.include AddAuth::Rails::AccountPasswordEntry
+          end
         end
       end
 

data/lib/add_auth/rails/migration/account_store.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "add_auth/rails/stores/account_lock"
+
+module AddAuth
+  module Rails
+    module Migration
+      class AccountStore
+        FIELDS = {id: :id, email: :email, encrypted_password: :encrypted_password,
+                  authority: :add_auth_authority, migration_stamp: :add_auth_migration_stamp,
+                  email_address: :email_address, password_digest: :password_digest, scheme: :add_auth_password_scheme}.freeze
+
+        def initialize(user_model:)
+          @users = user_model
+          @lock = Stores::AccountLock.new(user_model)
+          unless @users.primary_key == "id" && (FIELDS.values.map(&:to_s) - @users.column_names).empty?
+            raise ArgumentError, "prepare the reviewed User account schema before conversion"
+          end
+        end
+
+        def source_page(after:, limit:)
+          scope = @users.unscoped.order(:id)
+          scope = scope.where(@users.arel_table[:id].gt(after)) if after
+          scope.limit(limit).pluck(*FIELDS.values).map { |row| FIELDS.keys.zip(row).to_h }
+        end
+
+        def with_account(id)
+          @lock.call(id: id) { |user| yield(user && FIELDS.to_h { |name, field| [name, user.read_attribute(field)] }) }
+        rescue ActiveRecord::RecordNotUnique
+          :conflicts
+        end
+
+        def prepare(id:, **attributes)
+          raise AddAuth::Error, "conversion requires an account transaction" unless @users.connection.transaction_open?
+          # Source authority is retained. No callbacks, mail or host provisioning.
+          @users.unscoped.where(id: id).update_all(attributes)
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/migration/effective_inventory.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "add_auth/core/migration/readiness"
+
+module AddAuth
+  module Rails
+    module Migration
+      class EffectiveInventory
+        LIMIT = 10_000
+        ACCOUNT_FIELDS = %w[email email_address encrypted_password password_digest confirmed_at unconfirmed_email locked_at failed_attempts disabled_at deleted_at remember_created_at reset_password_token confirmation_token unlock_token authentication_token provider uid].freeze
+        OPTIONS = %i[authentication_keys case_insensitive_keys strip_whitespace_keys stretches password_length reconfirmable allow_unconfirmed_access_for confirm_within reset_password_within maximum_attempts unlock_strategy unlock_in remember_for sign_in_after_reset_password].freeze
+
+        def initialize(limit: LIMIT)
+          raise ArgumentError, "limit must be between 1 and 100000" unless limit.is_a?(Integer) && limit.between?(1, 100_000)
+          @limit = limit
+        end
+
+        def call
+          unless %w[test development].include?(::Rails.env.to_s) && defined?(::Devise)
+            raise ArgumentError, "effective preflight requires a local test/development Devise host"
+          end
+          @complete = true
+          mappings = ::Devise.mappings.values
+          models = mappings.map(&:to).uniq
+          connections = models.map(&:connection_pool).uniq
+          raise ArgumentError, "inspect one Active Record connection pool at a time" unless connections.length == 1
+          accounts = read_only(connections.first) { models.map { |model| account(model) } }
+          all_modules = accounts.flat_map { |entry| entry[:modules] }.uniq
+          facts = {mode: "effective", complete: @complete, row_limit: @limit,
+                   versions: %w[devise rails bcrypt].to_h { |name| [name.to_sym, Gem.loaded_specs[name]&.version&.to_s] }.merge(ruby: RUBY_VERSION),
+                   scope_count: mappings.length, modules: all_modules & Core::Migration::Readiness::MODULES,
+                   unknown_modules: accounts.sum { |entry| entry[:unknown_modules] },
+                   extensions: Core::Migration::Readiness::EXTENSIONS.select { |name| Gem.loaded_specs.key?(name) },
+                   rails_contract: accounts.length == 1 && accounts.first[:rails_contract], accounts: accounts}
+          Core::Migration::Readiness.new.call(facts)
+        end
+
+        private
+
+        def read_only(pool)
+          pool.with_connection do |connection|
+            raise ArgumentError, "effective preflight requires its own transaction" if connection.transaction_open?
+            case connection.adapter_name
+            when "PostgreSQL"
+              connection.transaction(requires_new: true) do
+                connection.execute("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ, READ ONLY")
+                connection.execute("SET LOCAL statement_timeout = '10s'")
+                yield
+              end
+            when "SQLite"
+              previous = connection.select_value("PRAGMA query_only").to_i
+              begin
+                connection.execute("PRAGMA query_only = ON")
+                # Rails 8.1 starts ordinary SQLite transactions with BEGIN
+                # IMMEDIATE, which requests write authority even for SELECTs.
+                connection.execute("BEGIN DEFERRED TRANSACTION")
+                begin
+                  yield
+                ensure
+                  connection.execute("ROLLBACK")
+                end
+              ensure
+                connection.execute("PRAGMA query_only = #{previous}")
+              end
+            else
+              raise ArgumentError, "effective preflight supports SQLite and PostgreSQL only"
+            end
+          end
+        end
+
+        def account(model)
+          columns = model.columns_hash
+          fields = ACCOUNT_FIELDS & columns.keys
+          # No model instances, callbacks, password verification or normalization hooks.
+          rows = model.unscoped.limit(@limit + 1).pluck(*fields).map { |values| fields.zip(Array(values)).to_h }
+          @complete = false if rows.length > @limit
+          rows = rows.first(@limit)
+          modules = model.devise_modules.map(&:to_s)
+          lookup_keys = Array(model.authentication_keys)
+          identifier = (lookup_keys.length == 1 && fields.include?(lookup_keys.first.to_s)) ? lookup_keys.first.to_s : "email"
+          @complete = false unless lookup_keys == [:email] || lookup_keys == [:email_address]
+          password = fields.include?("encrypted_password") ? "encrypted_password" : "password_digest"
+          keys = rows.map { |row| row[identifier].to_s.strip.downcase }
+          nonblank = keys.reject(&:empty?)
+          options = OPTIONS.filter_map { |name| [name, safe_option(model.public_send(name))] if model.respond_to?(name) }.to_h
+          verifier = model.instance_method(:valid_password?).source_location&.first
+          devise_root = Gem.loaded_specs.fetch("devise").full_gem_path + "/"
+          indexes = model.connection.indexes(model.table_name)
+          {model: safe_name(model.name), table: safe_name(model.table_name),
+           primary_key_type: columns[model.primary_key]&.type&.to_s,
+           database: model.connection.adapter_name, identifier: identifier,
+           identifier_type: columns[identifier]&.type&.to_s,
+           identifier_collation: columns[identifier]&.respond_to?(:collation) ? safe_name(columns[identifier].collation) : nil,
+           unique_identifier_index: indexes.any? { |index| index.unique && index.columns == [identifier] && !index.where },
+           modules: modules & Core::Migration::Readiness::MODULES,
+           unknown_modules: (modules - Core::Migration::Readiness::MODULES).length,
+           options: options, pepper_configured: model.respond_to?(:pepper) && !model.pepper.to_s.empty?,
+           custom_verifier: !verifier&.start_with?(devise_root) || !model.instance_method(:password=).source_location&.first&.start_with?(devise_root),
+           rails_contract: (model.name == "User" && fields.include?("email_address") && fields.include?("password_digest") && model.respond_to?(:authenticate_by) && defined?(::Session) && defined?(::Authentication)) ? true : false,
+           related_tables: related_tables(model),
+           counts: {inspected: rows.length, missing_identifier: keys.count(&:empty?), identifier_collisions: nonblank.length - nonblank.uniq.length,
+                    unknown_password: rows.count { |row| !row[password].to_s.match?(/\A\$2[aby]\$\d{2}\$[.\/A-Za-z0-9]{53}\z/) },
+                    unconfirmed: fields.include?("confirmed_at") ? rows.count { |row| row["confirmed_at"].nil? } : 0,
+                    reconfirming: rows.count { |row| !row["unconfirmed_email"].to_s.empty? },
+                    locked: rows.count { |row| row["locked_at"] }, disabled: rows.count { |row| row["disabled_at"] },
+                    deleted: rows.count { |row| row["deleted_at"] },
+                    outstanding_authority: rows.count { |row| %w[remember_created_at reset_password_token confirmation_token unlock_token authentication_token].any? { |key| !row[key].to_s.empty? } }}}
+        end
+
+        def related_tables(model)
+          connection = model.connection
+          tables = connection.tables.sort
+          @complete = false if tables.length > 200
+          tables.first(200).filter_map do |table|
+            next if table == model.table_name
+            columns = connection.columns(table).to_h { |column| [column.name, column] }
+            foreign_keys = connection.foreign_keys(table).select { |key| key.to_table == model.table_name }
+            reference = foreign_keys.first&.column || ("user_id" if model.name == "User" && columns.key?("user_id"))
+            next unless reference && columns.key?(reference)
+            quoted_table = connection.quote_table_name(table)
+            quote = ->(name) { connection.quote_column_name(name) }
+            identity_fields = %w[provider issuer subject uid] & columns.keys
+            selected = [reference, *identity_fields]
+            records = connection.select_rows("SELECT #{selected.map { |field| quote.call(field) }.join(", ")} FROM #{quoted_table} LIMIT #{@limit + 1}")
+            @complete = false if records.length > @limit
+            records = records.first(@limit)
+            identities = identity_fields.empty? ? [] : records.map { |row| row.drop(1) }
+            account_table = connection.quote_table_name(model.table_name)
+            key = quote.call(model.primary_key)
+            reference_column = quote.call(reference)
+            orphan_count = connection.select_value(<<~SQL).to_i
+              SELECT COUNT(*) FROM
+                (SELECT #{reference_column} FROM #{quoted_table} LIMIT #{@limit + 1}) source
+              LEFT JOIN #{account_table} account ON account.#{key} = source.#{reference_column}
+              WHERE source.#{reference_column} IS NOT NULL AND account.#{key} IS NULL
+            SQL
+            {table: safe_name(table), reference: safe_name(reference), key_type: columns[reference].type.to_s,
+             foreign_key_enforced: foreign_keys.any?, inspected: records.length,
+             orphaned_references: orphan_count, duplicate_identities: identities.length - identities.uniq.length}
+          end
+        end
+
+        def safe_name(value)
+          value.to_s.match?(/\A[A-Za-z_]\w*(?:::\w+)*\z/) ? value.to_s : nil
+        end
+
+        def safe_option(value)
+          case value
+          when nil, true, false, Numeric then value
+          when Symbol then safe_name(value)
+          when Range then [safe_option(value.begin), safe_option(value.end), value.exclude_end?]
+          when Array then value.map { |item| safe_option(item) }
+          when Hash then value.to_h { |key, item| [safe_name(key), safe_option(item)] }
+          else
+            # ActiveSupport::Duration exposes only a numeric duration.
+            value.is_a?(ActiveSupport::Duration) ? value.to_i : "custom"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/migration/key_type.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Rails
+    module Migration
+      module KeyType
+        module_function
+
+        # Resolve when the migration runs, after the host's account table exists.
+        # Session IDs remain integer until opaque cursor support is established.
+        def for(connection, table, session: false)
+          key = connection.primary_key(table)
+          column = connection.columns(table).find { |entry| entry.name == key }
+          raise ArgumentError, "AddAuth requires a single integer or UUID primary key on #{table}" unless column
+          return :bigint if column.type == :integer && column.limit == 8
+          return :integer if column.type == :integer
+          return :uuid if column.type == :uuid && !session
+          raise ArgumentError, session ? "AddAuth requires integer Session IDs; UUID accounts can use integer Sessions" : "AddAuth requires an integer or UUID account primary key"
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/migration/source_bridge.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "add_auth/core/migration/account_adoption"
+require "add_auth/rails/stores/account_lock"
+
+module AddAuth
+  module Rails
+    module Migration
+      # Include after Devise in an expanded, reviewed source model. This does
+      # not select routes or retire other host credential readers at cutover.
+      module SourceBridge
+        extend ActiveSupport::Concern
+
+        included do
+          before_save :add_auth_project_source_credentials
+        end
+
+        def valid_password?(password)
+          Core::Migration::AccountAdoption.source_authority?(self[:add_auth_authority]) && super
+        end
+
+        def active_for_authentication?
+          Core::Migration::AccountAdoption.source_authority?(self[:add_auth_authority]) && super
+        end
+
+        # Devise Lockable increments this counter through update_all before its
+        # later save callback. Fence that bypass on the same account row lock.
+        def increment_failed_attempts
+          self.class.transaction do
+            current = Stores::AccountLock.new(self.class).current_in_transaction(id: id)
+            raise AddAuth::Error, "source account no longer exists" unless current
+            Core::Migration::AccountAdoption.authorize_source_write!(authority: current[:add_auth_authority], changed_fields: [:failed_attempts])
+            super
+          end
+        end
+
+        private
+
+        def add_auth_project_source_credentials
+          current = persisted? ? Stores::AccountLock.new(self.class).current_in_transaction(id: id) : self
+          raise AddAuth::Error, "source account no longer exists" unless current
+          source = %i[email encrypted_password].to_h do |name|
+            [name, will_save_change_to_attribute?(name) ? self[name] : current[name]]
+          end
+          attributes = Core::Migration::AccountAdoption.projection_for_write(**source,
+            authority: current[:add_auth_authority], authority_changed: persisted? && will_save_change_to_add_auth_authority?,
+            changed_fields: changed_attribute_names_to_save)
+          attributes.each { |name, value| self[name] = value }
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/rails/password_adoption.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "add_auth/core/passwords/legacy_bcrypt"
+require "add_auth/core/passwords/credential"
+
+module AddAuth
+  module Rails
+    # Include after has_secure_password. Rails owns new assignment and lookup;
+    # Core chooses exactly one verifier for the persisted credential profile.
+    module PasswordAdoption
+      extend ActiveSupport::Concern
+
+      included do
+        self.filter_attributes += [:add_auth_password_scheme]
+        before_save :add_auth_retire_legacy_password
+      end
+
+      def authenticate_password(password)
+        result = Core::Passwords::Credential.new(legacy_verifier: AddAuth.configuration.legacy_password_verifier)
+          .authenticate(user: self, password: password, current: ->(value) { super(value) })
+        result.success? ? result.user : false
+      end
+
+      def authenticate(password) = authenticate_password(password)
+
+      private
+
+      def add_auth_retire_legacy_password
+        # A host's ordinary password assignment replaces the legacy credential.
+        # Direct migration copies do not set the virtual plaintext attribute.
+        self.add_auth_password_scheme = Core::Passwords::Credential.scheme_after_assignment(
+          scheme: add_auth_password_scheme, password: password, digest_changed: will_save_change_to_password_digest?
+        )
+      end
+    end
+  end
+end