add_auth 0.2.2 → 0.4.0

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

@@ -20,13 +20,7 @@ module AddAuth
               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
+                current_in_transaction(id: account_id)
               end
               result = yield accounts.compact.find { |account| account.id == id }
             end
@@ -34,6 +28,21 @@ module AddAuth
           raise AddAuth::Error, "authentication transaction rolled back" unless completed
           result
         end
+
+        # For model save callbacks, whose Active Record transaction already owns
+        # the write. All actual row-lock acquisition lives in this adapter.
+        def current_in_transaction(id:)
+          raise AddAuth::Error, "account row locking requires an owning transaction" unless @users.connection.transaction_open?
+          @users.uncached do
+            if @users.connection.adapter_name == "SQLite"
+              pk = @users.connection.quote_column_name(@users.primary_key)
+              @users.unscoped.where(@users.primary_key => id).update_all("#{pk} = #{pk}")
+              @users.unscoped.find_by(@users.primary_key => id)
+            else
+              @users.unscoped.lock.find_by(@users.primary_key => id)
+            end
+          end
+        end
       end
     end
   end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "add_auth/rails/stores/email_tokens"
+require "add_auth/rails/stores/commit_dispatch"
+require "add_auth/rails/stores/account_credentials"
+
+module AddAuth
+  module Rails
+    module Stores
+      class AccountTokens < EmailTokens
+        def initialize(user_model:, token_model:, session_model:, address_model:, authority:, provision:, delete_account: ->(user) { user.destroy! })
+          super(user_model: user_model, token_model: token_model, session_model: session_model)
+          raise ArgumentError, "address claims must share the account connection pool" unless address_model.connection_pool.equal?(user_model.connection_pool)
+          @addresses, @authority, @provision = address_model, authority, provision
+          @delete_account = delete_account
+          @account_credentials = AccountCredentials.new(user_model: user_model, authority: authority)
+        end
+
+        def create_account(email:, password:, profile: {}, replacing: nil)
+          raise AddAuth::Error, "registration must own its transaction" if @users.connection.transaction_open?
+          completed = false
+          saved = false
+          @users.transaction do |transaction|
+            transaction.after_commit { completed = true }
+            AccountLock.new(@users).current_in_transaction(id: replacing.user_id) if replacing
+            user = @users.new(profile)
+            user.email_address = email
+            user.password = password
+            user.add_auth_authority = "add_auth"
+            user.save!
+            saved = true
+            yield user
+          end
+          raise AddAuth::Error, "registration transaction rolled back" unless completed
+          :created
+        rescue ActiveRecord::RecordNotUnique, Core::AccountLifecycle::Conflict
+          :duplicate
+        rescue ActiveRecord::RecordInvalid => error
+          raise if saved
+          (error.record.errors.attribute_names - [:email_address]).empty? ? :duplicate : :invalid
+        end
+
+        def replace_pending(**attributes)
+          raise AddAuth::Error, "account proof must join its owning transaction" unless @users.current_transaction.open?
+          record = super
+          CommitDispatch.enqueue(transaction: @users.current_transaction, job: ::AddAuth::AccountDeliveryJob,
+            id: record.id, failure_event: "account_enqueue_failed.add_auth", payload: {issuance_id: record.id})
+          record
+        end
+
+        def claim_address(user:, digest:, address:, state:)
+          raise Core::AccountLifecycle::Conflict if @users.where(email_address: address).where.not(id: user.id).exists?
+          @addresses.where(user_id: user.id, state: state).where.not(digest: digest).delete_all
+          existing = @addresses.find_by(digest: digest)
+          if existing
+            raise Core::AccountLifecycle::Conflict unless existing.user_id == user.id && existing.state == state
+          else
+            @addresses.create!(user_id: user.id, digest: digest, state: state)
+          end
+        rescue ActiveRecord::RecordNotUnique
+          raise Core::AccountLifecycle::Conflict
+        end
+
+        def promote_address(user:, digest:)
+          pending = @addresses.find_by!(user_id: user.id, digest: digest, state: "pending")
+          @addresses.where(user_id: user.id, state: "current").delete_all
+          pending.update!(state: "current")
+        end
+
+        def inspect_token(digest:)
+          @tokens.uncached do
+            record = @tokens.find_by(digest: digest)
+            [record && @users.find_by(id: record.user_id), record]
+          end
+        end
+
+        def update_account(user:, **attributes)
+          # Core owns notices and invalidation for this transition. Avoid firing
+          # a second independent model callback for the same committed change.
+          @account_credentials.update_account(user: user, **attributes)
+        end
+
+        def replace_password(user:, password:)
+          @account_credentials.replace_password(user: user, password: password)
+        end
+
+        def revoke_authority(user:, at:) = @authority.revoke(user_id: user.id, at: at)
+
+        def provision(user:)
+          @provision.call(user)
+          user.reload
+        end
+
+        def delete_account(user:)
+          raise AddAuth::Error, "account deletion requires its owning transaction" unless @users.connection.transaction_open?
+          @delete_account.call(user)
+          raise Core::AccountLifecycle::DeletionRejected if @users.unscoped.exists?(id: user.id)
+        rescue ActiveRecord::RecordNotDestroyed, ActiveRecord::InvalidForeignKey
+          raise Core::AccountLifecycle::DeletionRejected, cause: nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Rails
+    module Stores
+      # One persistence implementation for retiring outstanding account authority.
+      # Core chooses the event, account and time; callers own the account lock.
+      class Authority
+        def initialize(user_model:, session_model:, token_models: [], ceremony_models: [], credential_models: [], external_invalidator: nil)
+          @external_invalidator = external_invalidator
+          @users, @sessions, @tokens, @ceremonies, @credentials = user_model, session_model, token_models, ceremony_models, credential_models
+          unless [session_model, *token_models, *ceremony_models, *credential_models].all? { |model| model.connection_pool.equal?(user_model.connection_pool) }
+            raise ArgumentError, "authentication models must share one connection pool"
+          end
+        end
+
+        def revoke(user_id:, at:)
+          raise AddAuth::Error, "authority revocation requires an account transaction" unless @users.connection.transaction_open?
+          @external_invalidator&.call(user_id: user_id, at: at)
+          @sessions.where(user_id: user_id, revoked_at: nil).update_all(revoked_at: at)
+          @tokens.each { |model| model.where(user_id: user_id, consumed_at: nil, revoked_at: nil).update_all(revoked_at: at, delivery_payload: nil) }
+          @ceremonies.each { |model| model.where(user_id: user_id, consumed_at: nil).update_all(consumed_at: at) }
+          @credentials.each { |model| model.where(user_id: user_id, revoked_at: nil).update_all(revoked_at: at) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Rails
+    module Stores
+      module CommitDispatch
+        module_function
+
+        def enqueue(transaction:, job:, id:, failure_event:, payload:)
+          raise AddAuth::Error, "outbox dispatch must join its owning transaction" unless transaction.open?
+          transaction.after_commit do
+            raise AddAuth::Error unless job.perform_later(id)
+          rescue
+            notify(event: failure_event, payload: payload)
+          end
+        end
+
+        def event(transaction:, event:, payload:)
+          raise AddAuth::Error, "commit events must join their owning transaction" unless transaction.open?
+          transaction.after_commit { notify(event: event, payload: payload) }
+        end
+
+        def notify(event:, payload:)
+          ActiveSupport::Notifications.instrument(event, payload)
+        rescue
+          # Optional observers cannot report a committed operation as failed.
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "add_auth/rails/stores/account_lock"
+
+module AddAuth
+  module Rails
+    module Stores
+      class ExternalIdentities
+        def initialize(user_model:, identity_model:, transaction_model:)
+          @users, @identities, @transactions = user_model, identity_model, transaction_model
+          unless [identity_model, transaction_model].all? { |model| model.connection_pool.equal?(@users.connection_pool) }
+            raise ArgumentError, "authentication models must share one connection pool"
+          end
+          @lock = AccountLock.new(@users)
+        end
+
+        def with_user(id:, &block) = @lock.call(id: id, &block)
+
+        def with_identity(namespace:, replacing: nil)
+          @identities.uncached do
+            locator = binding(namespace: namespace)
+            @lock.call(id: locator&.user_id, additional_id: replacing&.user_id) do |user|
+              yield user, user && binding(namespace: namespace)
+            end
+          end
+        end
+
+        # The G3 capability establishes fresh-account provenance. The adapter
+        # additionally enforces the exact user model/pool and owning transaction
+        # before a pending transaction can be consumed.
+        def registration_account(user:)
+          return unless @users.connection.transaction_open? && user.is_a?(@users) && user.persisted? && !user.destroyed?
+          @users.uncached { @users.find_by(id: user.id) }
+        end
+
+        def binding(namespace:) = @identities.find_by(namespace: namespace)
+        def binding_for_user(user_id:, id:) = @identities.find_by(user_id: user_id, id: id)
+        def bindings(user_id:) = @identities.where(user_id: user_id, revoked_at: nil).to_a
+
+        def bind(user:, evidence:, at:)
+          require_transaction!
+          # A savepoint contains unique-index failures on PostgreSQL. Account
+          # locks serialize same-owner callbacks; the unique namespace index
+          # arbitrates different owners without choosing one by email.
+          @identities.transaction(requires_new: true) do
+            identity = binding(namespace: evidence.namespace)
+            if identity
+              return unless identity.user_id == user.id
+              return identity unless identity.revoked_at
+              identity.update!(revoked_at: nil, linked_at: at, credential_version: SecureRandom.hex(16), provenance: evidence.provenance)
+              identity
+            else
+              @identities.create!(user_id: user.id, namespace: evidence.namespace, provider_id: evidence.provider_id,
+                issuer: evidence.issuer, audience: evidence.audience, subject: evidence.subject,
+                provenance: evidence.provenance, linked_at: at, credential_version: SecureRandom.hex(16))
+            end
+          end
+        rescue ActiveRecord::RecordNotUnique
+          nil
+        end
+
+        def revoke(identity:, at:)
+          require_transaction!
+          identity.update!(revoked_at: at, credential_version: SecureRandom.hex(16))
+        end
+
+        def invalidate_credentials(user_id:, at:, credential_version:)
+          require_transaction!
+          # Never move the cutoff backwards if a delayed invalidation arrives.
+          @identities.where(user_id: user_id, revoked_at: nil).where("invalidated_at IS NULL OR invalidated_at <= ?", at)
+            .update_all(invalidated_at: at, credential_version: credential_version, updated_at: at)
+        end
+
+        def create_transaction(**attributes) = @transactions.create!(**attributes)
+        def transaction_by_digest(digest:) = @transactions.uncached { @transactions.find_by(digest: digest) }
+
+        def consume_transaction(digest:, at:)
+          @transactions.where(digest: digest, consumed_at: nil).where("issued_at <= ? AND expires_at > ?", at, at)
+            .update_all(consumed_at: at) == 1
+        end
+
+        private
+
+        def require_transaction!
+          raise AddAuth::Error, "identity mutation requires an account transaction" unless @users.connection.transaction_open?
+        end
+      end
+    end
+  end
+end

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

@@ -12,7 +12,7 @@ module AddAuth
           scope = @model.where("expires_at <= ?", before)
           if @kind == :session
             scope = scope.or(@model.where("revoked_at <= ?", before))
-          elsif @kind != :ceremony
+          elsif !Core::Maintenance::EXPIRING.key?(@kind)
             scope = without_live_lease(scope, now)
           end
           bounded(scope, limit).delete_all

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "add_auth/rails/stores/account_lock"
+
+module AddAuth
+  module Rails
+    module Stores
+      class MobileHandoffs
+        def initialize(user_model:, handoff_model:, session_model:)
+          @users, @handoffs = user_model, handoff_model
+          unless [handoff_model, session_model].all? { |model| model.connection_pool.equal?(@users.connection_pool) }
+            raise ArgumentError, "mobile authentication models must share one connection pool"
+          end
+          @lock = AccountLock.new(@users)
+        end
+
+        def create_pending(**attributes)
+          @handoffs.transaction(requires_new: true) { @handoffs.create!(**attributes) }
+        rescue ActiveRecord::RecordNotUnique
+          nil
+        end
+
+        def by_external_digest(digest:) = @handoffs.uncached { @handoffs.find_by(external_digest: digest) }
+
+        def issue(row:, **attributes)
+          require_transaction!
+          @handoffs.where(id: row.id, digest: nil, consumed_at: nil, user_id: nil).update_all(**attributes) == 1
+        end
+
+        def with_code(digest:)
+          @handoffs.uncached do
+            locator = @handoffs.find_by(digest: digest)
+            @lock.call(id: locator&.user_id) do |user|
+              yield user, user && @handoffs.find_by(digest: digest, user_id: user.id)
+            end
+          end
+        end
+
+        def consume(row:, at:)
+          require_transaction!
+          @handoffs.where(id: row.id, user_id: row.user_id, consumed_at: nil).where("expires_at > ?", at)
+            .update_all(consumed_at: at) == 1
+        end
+
+        private
+
+        def require_transaction!
+          raise AddAuth::Error, "mobile handoff requires an account transaction" unless @users.connection.transaction_open?
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "add_auth/rails/stores/delivery_state"
+require "add_auth/rails/stores/commit_dispatch"
 
 module AddAuth
   module Rails
@@ -16,12 +17,8 @@ module AddAuth
         def append(user:, **attributes)
           raise AddAuth::Error, "security notifications must join the account transaction" unless @users.current_transaction.open?
           event = @events.create!(**attributes, user_id: user.id)
-          @users.current_transaction.after_commit do
-            job = ::AddAuth::SecurityNotificationJob.perform_later(event.id)
-            raise AddAuth::Error unless job
-          rescue
-            ActiveSupport::Notifications.instrument("notification_enqueue_failed.add_auth", event_id: event.id)
-          end
+          CommitDispatch.enqueue(transaction: @users.current_transaction, job: ::AddAuth::SecurityNotificationJob,
+            id: event.id, failure_event: "notification_enqueue_failed.add_auth", payload: {event_id: event.id})
           event
         end
 

data/lib/add_auth/rails/user_lifecycle.rb

@@ -6,29 +6,27 @@ module AddAuth
       extend ActiveSupport::Concern
 
       included do
+        before_update :add_auth_validate_account_write
         after_update :add_auth_invalidate_proofs
       end
 
       private
 
+      def add_auth_validate_account_write
+        Core::AccountLifecycle.validate_host_write!(changes: changes_to_save, enabled: AddAuth.configuration.lifecycle.enabled)
+      end
+
       def add_auth_invalidate_proofs
         return unless Core::Intake.revoke_after_change?(saved_changes)
         now = Time.current
-        if AddAuth.configuration.notifications.enabled
-          kind = saved_changes.key?("password_digest") ? :password_changed : :email_changed
+        kind = Core::Intake.notification_after_change(saved_changes)
+        if AddAuth.configuration.notifications.enabled && kind
           Runtime.security_events.issue(user: self, kind: kind, at: now)
           if saved_change_to_email_address? && email_address_before_last_save != email_address
             Runtime.security_events.issue(user: self, kind: :email_changed, at: now, recipient: email_address_before_last_save)
           end
         end
-        if defined?(::AddAuthCeremony) && ::AddAuthCeremony.table_exists?
-          ::AddAuthCeremony.where(user_id: id, consumed_at: nil).update_all(consumed_at: now)
-        end
-        sessions.where(revoked_at: nil).update_all(revoked_at: now)
-        if defined?(::AddAuthSignInToken) && ::AddAuthSignInToken.table_exists?
-          ::AddAuthSignInToken.where(user_id: id, consumed_at: nil, revoked_at: nil)
-            .update_all(revoked_at: now, delivery_payload: nil)
-        end
+        Runtime.authority.revoke(user_id: id, at: now)
       end
     end
   end

data/lib/add_auth/result.rb

@@ -16,6 +16,7 @@ module AddAuth
       consumed_token revoked_token challenge_rejected
       challenge_unavailable rate_limited origin_mismatch
       counter_regression elevation_required
+      identity_unbound identity_conflict last_credential
     ].freeze
 
     attr_reader :user, :strategy, :credential, :reason, :session, :grant

data/lib/add_auth/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AddAuth
-  VERSION = "0.2.2"
+  VERSION = "0.4.0"
 end

data/lib/add_auth.rb

@@ -13,11 +13,15 @@ require "add_auth/configuration"
 # ejectable, disposable UI on top of it.
 require "add_auth/core/browser_binding"
 require "add_auth/core/access_policy"
+require "add_auth/core/account_policy"
 require "add_auth/core/sessions"
+require "add_auth/core/mobile_response"
 require "add_auth/core/step_up"
+require "add_auth/core/external_identities"
 require "add_auth/core/intake"
 require "add_auth/core/rate_limit"
 require "add_auth/core/delivery"
+require "add_auth/core/account_lifecycle"
 require "add_auth/core/maintenance"
 require "add_auth/core/security_events"
 require "add_auth/core/strategies/email_link"

data/lib/generators/add_auth/accounts/accounts_generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module AddAuth
+  module Generators
+    class AccountsGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      class_option :email_link, type: :boolean, default: true, desc: "Enable email sign-in as a step-up dependency"
+      desc "Prepare optional account lifecycle schema and pages; review existing account confirmation and policy before enabling"
+
+      def self.next_migration_number(dirname) = ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+
+      def prerequisites
+        invoke "add_auth:notifications"
+        invoke "add_auth:step_up", [], email_link: options[:email_link]
+      end
+
+      def persistence
+        unless Dir[File.join(destination_root, "db/migrate/*_add_add_auth_accounts.rb")].any?
+          migration_template "add_add_auth_accounts.rb.tt", "db/migrate/add_add_auth_accounts.rb"
+        end
+        unless Dir[File.join(destination_root, "db/migrate/*_add_add_auth_provisioning.rb")].any?
+          migration_template "add_add_auth_provisioning.rb.tt", "db/migrate/add_add_auth_provisioning.rb"
+        end
+        %w[add_auth_account_token add_auth_address_claim].each do |name|
+          template "#{name}.rb", "app/models/#{name}.rb" unless File.exist?(File.join(destination_root, "app/models/#{name}.rb"))
+        end
+        say "Account lifecycle is prepared but disabled. Map existing account policy and confirmation state, then set config.lifecycle.enabled = true."
+      end
+
+      def routes
+        return if File.read(File.join(destination_root, "config/routes.rb")).include?("# AddAuth account lifecycle")
+        route <<~ROUTES
+          # AddAuth account lifecycle
+          get "account/sign-up", to: "add_auth/accounts#new"
+          post "account/sign-up", to: "add_auth/accounts#create"
+          get "account/check-email", to: "add_auth/accounts#check_email"
+          get "account/requests/:purpose", to: "add_auth/accounts#request_form", constraints: {purpose: /confirm|reset_password|unlock/}
+          post "account/requests/:purpose", to: "add_auth/accounts#request_proof", constraints: {purpose: /confirm|reset_password|unlock/}
+          get "account/proofs/:purpose", to: "add_auth/accounts#proof", constraints: {purpose: /confirm|reset_password|unlock/}
+          post "account/proofs/:purpose", to: "add_auth/accounts#consume", constraints: {purpose: /confirm|reset_password|unlock/}
+          get "account/email", to: "add_auth/accounts#edit_email"
+          post "account/email", to: "add_auth/accounts#change_email"
+          get "account/password", to: "add_auth/accounts#edit_password"
+          post "account/password", to: "add_auth/accounts#change_password"
+          get "account/delete", to: "add_auth/accounts#confirm_deletion"
+          delete "account", to: "add_auth/accounts#destroy"
+        ROUTES
+      end
+    end
+  end
+end

data/lib/generators/add_auth/accounts/templates/add_add_auth_accounts.rb.tt

@@ -0,0 +1,49 @@
+require "add_auth/rails/migration/key_type"
+
+class AddAddAuthAccounts < ActiveRecord::Migration[8.0]
+  def up
+    user_key_type = AddAuth::Rails::Migration::KeyType.for(connection, :users)
+    false_default = (connection.adapter_name == "SQLite") ? -> { "0" } : false
+    %i[confirmed_at locked_at disabled_at deleted_at add_auth_locked_until].each do |name|
+      add_column :users, name, :datetime unless column_exists?(:users, name)
+    end
+    add_column :users, :unconfirmed_email, :string unless column_exists?(:users, :unconfirmed_email)
+    add_column :users, :failed_attempts, :integer, default: 0, null: false unless column_exists?(:users, :failed_attempts)
+    add_column :users, :add_auth_manual_lock, :boolean, default: false_default, null: false unless column_exists?(:users, :add_auth_manual_lock)
+    add_column :users, :add_auth_password_scheme, :string unless column_exists?(:users, :add_auth_password_scheme)
+    add_column :users, :add_auth_authority, :string, default: "add_auth", null: false unless column_exists?(:users, :add_auth_authority)
+    add_column :sessions, :remembered, :boolean, default: false_default, null: false unless column_exists?(:sessions, :remembered)
+    add_column :sessions, :idle_timeout, :integer unless column_exists?(:sessions, :idle_timeout)
+    create_table :add_auth_address_claims do |t|
+      t.references :user, type: user_key_type, null: false, foreign_key: {on_delete: :cascade}
+      t.string :digest, null: false
+      t.string :state, null: false
+      t.timestamps
+    end
+    add_index :add_auth_address_claims, :digest, unique: true
+    add_index :add_auth_address_claims, [:user_id, :state], unique: true
+    create_table :add_auth_account_tokens do |t|
+      t.references :user, type: user_key_type, null: false, foreign_key: {on_delete: :cascade}
+      t.string :digest, null: false
+      t.string :purpose, null: false
+      t.string :address_digest, null: false
+      t.string :account_version, null: false
+      t.string :request_id, null: false
+      t.datetime :expires_at, null: false
+      t.datetime :consumed_at
+      t.datetime :revoked_at
+      t.text :delivery_payload
+      t.string :delivery_lease_key
+      t.datetime :delivery_lease_until
+      t.datetime :delivered_at
+      t.timestamps
+    end
+    add_index :add_auth_account_tokens, :digest, unique: true
+    add_index :add_auth_account_tokens, :request_id, unique: true
+    add_index :add_auth_account_tokens, :expires_at
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Retain account policy, address claims and spent proofs during rollback; retire them only after reviewed reconciliation"
+  end
+end

data/lib/generators/add_auth/accounts/templates/add_add_auth_provisioning.rb.tt

@@ -0,0 +1,9 @@
+class AddAddAuthProvisioning < ActiveRecord::Migration[8.0]
+  def up
+    add_column :users, :add_auth_provisioned_at, :datetime unless column_exists?(:users, :add_auth_provisioned_at)
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Retain provisioning receipts to prevent repeating account setup"
+  end
+end

data/lib/generators/add_auth/accounts/templates/add_auth_account_token.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class AddAuthAccountToken < ApplicationRecord
+  belongs_to :user
+  self.filter_attributes += [:digest, :address_digest, :account_version, :delivery_payload, :delivery_lease_key]
+end

data/lib/generators/add_auth/accounts/templates/add_auth_address_claim.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class AddAuthAddressClaim < ApplicationRecord
+  belongs_to :user
+  self.filter_attributes += [:digest]
+end

data/lib/generators/add_auth/devise_accounts/devise_accounts_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module AddAuth
+  module Generators
+    class DeviseAccountsGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Prepare additive account columns for a reviewed Devise migration; does not convert accounts or switch authentication"
+
+      def self.next_migration_number(dirname) = ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+
+      def migration
+        return if Dir[File.join(destination_root, "db/migrate/*_prepare_add_auth_devise_accounts.rb")].any?
+        migration_template "prepare_add_auth_devise_accounts.rb.tt", "db/migrate/prepare_add_auth_devise_accounts.rb"
+        say "Review the generated migration and run preflight before conversion. Authentication and host models are unchanged."
+      end
+    end
+  end
+end

data/lib/generators/add_auth/devise_accounts/templates/prepare_add_auth_devise_accounts.rb.tt

@@ -0,0 +1,17 @@
+require "add_auth/rails/migration/key_type"
+
+class PrepareAddAuthDeviseAccounts < ActiveRecord::Migration[8.0]
+  def up
+    AddAuth::Rails::Migration::KeyType.for(connection, :users)
+    add_column :users, :email_address, :string unless column_exists?(:users, :email_address)
+    add_column :users, :password_digest, :string unless column_exists?(:users, :password_digest)
+    add_column :users, :add_auth_password_scheme, :string unless column_exists?(:users, :add_auth_password_scheme)
+    add_column :users, :add_auth_migration_stamp, :string unless column_exists?(:users, :add_auth_migration_stamp)
+    add_column :users, :add_auth_authority, :string, default: "devise", null: false unless column_exists?(:users, :add_auth_authority)
+    add_index :users, :email_address, unique: true unless index_exists?(:users, :email_address, unique: true)
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Retain canonical credentials for the reviewed bridge rollback; retire columns only after reconciliation"
+  end
+end

data/lib/generators/add_auth/email_link/email_link_generator.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 require "rails/generators"
+require "generators/add_auth/feature_configuration"
 require "rails/generators/active_record"
 
 module AddAuth
   module Generators
     class EmailLinkGenerator < ::Rails::Generators::Base
       include ::Rails::Generators::Migration
+      include FeatureConfiguration
 
       source_root File.expand_path("templates", __dir__)
+      class_option :enable, type: :boolean, default: true, desc: "Enable email sign-in after preparing its storage"
       def self.next_migration_number(dirname) = ::ActiveRecord::Generators::Base.next_migration_number(dirname)
 
       def dependencies
@@ -48,7 +51,7 @@ module AddAuth
         unless File.read(File.join(destination_root, "config/routes.rb")).include?("add_auth/challenge.js")
           route 'get "add_auth/challenge.js", to: "add_auth/assets#challenge"'
         end
-        gsub_file "config/initializers/add_auth.rb", "# config.email_link.enabled = true", "config.email_link.enabled = true"
+        enable_feature(:email_link) if options[:enable]
         say "Review and migrate, configure base_url/mail_from, a durable queue, shared rate-limit cache and a recurring add_auth:deliver_pending sweep."
       end
     end