add_auth 0.2.2 → 0.3.0

data/lib/add_auth/core/external_identities/evidence.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module AddAuth
+  module Core
+    class ExternalIdentities
+      # Only configured server code may supply this verifier. It must validate a
+      # live middleware/library result, including issuer, audience, state/nonce
+      # and (for reauthentication) auth_time/max_age. A request auth hash is not
+      # such a result. Core deliberately contains no protocol or token decoder.
+      class Configuration
+        attr_reader :id, :issuer, :audience
+
+        def initialize(id:, issuer:, audience:, verifier:, clock: Time)
+          @id, @issuer, @audience = [id, issuer, audience].map { |value| self.class.text(value) }
+          raise ArgumentError, "a trusted server verifier is required" unless verifier.respond_to?(:call)
+          @verifier, @clock = verifier, clock
+          freeze
+        end
+
+        def self.text(value)
+          raise ArgumentError, "invalid external identity field" unless value.is_a?(String) && value.valid_encoding? &&
+            value.bytesize.between?(1, 2048) && !value.match?(/[\x00-\x1f\x7f]/)
+          value.dup.freeze
+        end
+
+        def verify(server_result:, transaction:)
+          return unless transaction.is_a?(Pending) && transaction.configuration.equal?(self)
+          claims = @verifier.call(server_result: server_result, transaction: transaction)
+          return unless claims.is_a?(Hash) && claims[:issuer] == issuer && claims[:audience] == audience
+          VerifiedIdentity.send(:new, configuration: self, transaction: transaction,
+            subject: self.class.text(claims[:subject]), provenance: self.class.text(claims[:provenance]),
+            authenticated_at: claims[:authenticated_at], verified_at: @clock.now)
+        rescue ArgumentError
+          nil
+        end
+
+        def namespace(subject) = ::Digest::SHA256.hexdigest(JSON.generate([id, issuer, audience, subject]))
+        def inspect = "#<AddAuth::Core::ExternalIdentities::Configuration [FILTERED]>"
+      end
+
+      class Pending
+        attr_reader :configuration, :id, :purpose, :user_id, :session_id, :session_digest,
+          :policy_version, :issued_at, :expires_at
+
+        def initialize(configuration:, id:, purpose:, user_id:, session_id:, session_digest:, policy_version:, issued_at:, expires_at:)
+          @configuration = configuration
+          @id, @purpose = id.dup.freeze, purpose.to_sym
+          @user_id, @session_id = user_id&.dup&.freeze, session_id&.dup&.freeze
+          @session_digest = session_digest&.dup&.freeze
+          @policy_version = policy_version
+          @issued_at, @expires_at = issued_at.dup.freeze, expires_at.dup.freeze
+          freeze
+        end
+        private_class_method :new
+
+        def inspect = "#<AddAuth::Core::ExternalIdentities::Pending [FILTERED]>"
+      end
+
+      class VerifiedIdentity
+        attr_reader :configuration, :transaction, :subject, :provenance, :authenticated_at, :verified_at
+
+        def initialize(configuration:, transaction:, subject:, provenance:, authenticated_at:, verified_at:)
+          raise ArgumentError, "invalid authentication occurrence time" unless authenticated_at.nil? || authenticated_at.is_a?(Time)
+          @configuration, @transaction, @subject, @provenance = configuration, transaction, subject, provenance
+          @authenticated_at = authenticated_at&.dup&.freeze
+          @verified_at = verified_at.dup.freeze
+          freeze
+        end
+        private_class_method :new
+
+        def provider_id = configuration.id
+        def issuer = configuration.issuer
+        def audience = configuration.audience
+        def transaction_id = transaction.id
+        def purpose = transaction.purpose
+        def namespace = configuration.namespace(subject)
+        def inspect = "#<AddAuth::Core::ExternalIdentities::VerifiedIdentity [FILTERED]>"
+      end
+
+      # Session evidence is issued only after locked binding resolution. It is
+      # never a StepUp::Evidence merely because the callback was just received.
+      class SessionProof
+        attr_reader :user_id, :credential_id, :credential_version, :verified_at
+        def initialize(user_id:, credential_id:, credential_version:, verified_at:)
+          @user_id, @credential_id = user_id, credential_id.to_s.dup.freeze
+          @credential_version, @verified_at = credential_version.dup.freeze, verified_at.dup.freeze
+          freeze
+        end
+        private_class_method :new
+        def user_verification = false
+        def inspect = "#<AddAuth::Core::ExternalIdentities::SessionProof [FILTERED]>"
+      end
+    end
+  end
+end

data/lib/add_auth/core/external_identities.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require "add_auth/core/external_identities/evidence"
+require "securerandom"
+
+module AddAuth
+  module Core
+    class ExternalIdentities
+      LINK = :link_external_identity
+      UNLINK = :unlink_external_identity
+      ENROLL = :enroll_external_identity
+      MOBILE = :mobile_sign_in
+      NATIVE = :native_sign_in
+      NATIVE_ENROLL = :native_enroll_external_identity
+      ENROLLMENT_PURPOSES = [ENROLL, NATIVE_ENROLL].freeze
+
+      # G3 rescues this outside its fresh-account transaction. Returning a
+      # failure Result here would commit a partially registered account.
+      class EnrollmentRejected < StandardError
+        attr_reader :reason
+        def initialize(reason:)
+          @reason = reason
+          super("external identity enrollment rejected")
+        end
+      end
+
+      # remaining_method is a Core policy port evaluated under the account lock;
+      # it must check actual enabled/usable password, passkey or trusted recovery
+      # credentials. Authority invalidation uses the shared lifecycle transaction.
+      def initialize(store:, configurations:, sessions:, access_policy:, policy:, eligible:,
+        digest:, revoke_authority:, remaining_method:, enrollment_eligible: ->(_user) { false }, clock: Time, lifetime: 300, enabled: false, mobile_enabled: false)
+        raise ArgumentError, "invalid transaction lifetime" unless lifetime.is_a?(Integer) && lifetime.between?(1, 600)
+        @store, @sessions, @access, @policy, @eligible = store, sessions, access_policy, policy, eligible
+        @configurations = configurations.to_h { |config| [config.id, config] }.freeze
+        raise ArgumentError, "duplicate provider configuration" unless @configurations.size == configurations.size
+        @digest, @revoke, @remaining, @clock, @lifetime, @enabled = digest, revoke_authority, remaining_method, clock, lifetime, enabled == true
+        @enrollment_eligible = enrollment_eligible
+        @mobile_enabled = mobile_enabled == true
+        @binding = BrowserBinding.new(digest: digest)
+      end
+
+      def begin_transaction(configuration_id:, browser_secret:, user: nil, session: nil, purpose: :sign_in, binding_context: nil)
+        return failure(:disabled) unless @enabled
+        config = @configurations[configuration_id]
+        return failure unless config && @binding.valid?(browser_secret) && valid_context?(binding_context)
+        return failure(:disabled) if [MOBILE.to_s, NATIVE.to_s, NATIVE_ENROLL.to_s].include?(purpose.to_s) && !@mobile_enabled
+        if ["sign_in", ENROLL.to_s, MOBILE.to_s, NATIVE.to_s, NATIVE_ENROLL.to_s].include?(purpose.to_s)
+          return failure if user || session
+          return issue(config, browser_secret, purpose, binding_context: binding_context)
+        end
+        @store.with_user(id: user&.id) do |account|
+          row = account && @sessions.current_in_transaction(user: account, session: session)
+          allowed = purpose.to_s == LINK.to_s || @policy.reauthentication_rule_for(purpose)
+          next failure(:elevation_required) unless row && @eligible.call(account) == true && allowed
+          issue(config, browser_secret, purpose, account, row, binding_context: binding_context)
+        end
+      end
+
+      def pending(transaction:, browser_secret:, binding_context: nil)
+        return unless @enabled && @binding.valid?(transaction) && @binding.valid?(browser_secret) && valid_context?(binding_context)
+        row = @store.transaction_by_digest(digest: @digest.digest(transaction))
+        return unless row && row.browser_digest == binding_digest(browser_secret, binding_context) && !row.consumed_at &&
+          row.expires_at > @clock.now && row.issued_at <= @clock.now
+        config = @configurations[row.provider_id]
+        return unless config && row.issuer == config.issuer && row.audience == config.audience
+        Pending.send(:new, configuration: config, id: transaction, purpose: row.purpose,
+          user_id: row.user_id, session_id: row.session_id, session_digest: row.session_digest,
+          policy_version: row.policy_version, issued_at: row.issued_at, expires_at: row.expires_at)
+      end
+
+      # Cancellation is correlation-bound, idempotent and grants no authority.
+      def cancel(transaction:, browser_secret:, binding_context: nil)
+        proof = pending(transaction: transaction, browser_secret: browser_secret, binding_context: binding_context)
+        return false unless proof
+        @store.consume_transaction(digest: @digest.digest(proof.id), at: @clock.now)
+      end
+
+      def sign_in(evidence:, replacing: nil, **hints)
+        finalize_sign_in(evidence: evidence, purpose: :sign_in, replacing: replacing) do |account, identity, proof|
+          grant = @sessions.create_in_transaction(user: account, method: :external_identity,
+            proof: proof, replacing: replacing, **hints)
+          raise AddAuth::Error, "external identity session could not finalize" unless grant
+          Result.success(user: account, strategy: :external_identity, credential: identity, session: grant.session, grant: grant)
+        end
+      end
+
+      def mobile_handoff(evidence:, handoffs:)
+        return failure(:disabled) unless @mobile_enabled
+        finalize_sign_in(evidence: evidence, purpose: MOBILE) do |account, _identity, proof|
+          handoffs.issue_in_transaction(user: account, proof: proof, pending: evidence.transaction)
+        end
+      end
+
+      def native_sign_in(evidence:, client_id:, **hints)
+        return failure(:disabled) unless @mobile_enabled
+        finalize_sign_in(evidence: evidence, purpose: NATIVE) do |account, identity, proof|
+          grant = @sessions.create_in_transaction(user: account, method: :external_identity,
+            proof: proof, transport: :mobile, client_id: client_id, **hints)
+          raise AddAuth::Error, "native identity session could not finalize" unless grant
+          Result.success(user: account, strategy: :external_identity, credential: identity, session: grant.session, grant: grant)
+        end
+      end
+
+      def link(user:, session:, evidence:, grant:)
+        return failure(:disabled) unless @enabled
+        return failure unless trusted?(evidence) && evidence.purpose == LINK
+        @store.with_user(id: user&.id) do |account|
+          next failure(:elevation_required) unless management?(account, session, grant, LINK) && bound?(evidence, account, session)
+          finalize(evidence, account) do
+            identity = @store.binding(namespace: evidence.namespace)
+            if identity && (identity.user_id != account.id || !matches?(identity, evidence))
+              next failure(:identity_conflict)
+            end
+            identity = @store.bind(user: account, evidence: evidence, at: @clock.now)
+            next failure(:identity_conflict) unless identity
+            Result.success(user: account, strategy: :external_identity, credential: identity)
+          end
+        end
+      end
+
+      # Registration capability is minted by G3 only in create_account's fresh
+      # user block. This joins that transaction; it never authenticates the user.
+      def bind_new_account_in_transaction(registration:, evidence:)
+        reject_enrollment(:disabled) unless @enabled
+        valid_registration = defined?(AccountLifecycle::NewAccount) && registration.instance_of?(AccountLifecycle::NewAccount)
+        reject_enrollment unless valid_registration && trusted?(evidence) && ENROLLMENT_PURPOSES.include?(evidence.purpose)
+        reject_enrollment(:disabled) if evidence.purpose == NATIVE_ENROLL && !@mobile_enabled
+        tx = evidence.transaction
+        reject_enrollment unless tx.user_id.nil? && tx.session_id.nil? && tx.session_digest.nil? && tx.policy_version.nil?
+        account = @store.registration_account(user: registration.user)
+        reject_enrollment unless account && account.id == registration.user_id && @enrollment_eligible.call(account) == true
+        reject_enrollment(:expired_token) unless tx.issued_at <= @clock.now && tx.expires_at > @clock.now
+        reject_enrollment(:identity_conflict) if @store.binding(namespace: evidence.namespace)
+        reject_enrollment(:consumed_token) unless @store.consume_transaction(digest: @digest.digest(tx.id), at: @clock.now)
+        identity = @store.bind(user: account, evidence: evidence, at: @clock.now)
+        reject_enrollment(:identity_conflict) unless identity
+        Result.success(user: account, strategy: :external_identity, credential: identity)
+      end
+
+      def unlink(user:, session:, identity_id:, grant:)
+        return failure(:disabled) unless @enabled
+        @store.with_user(id: user&.id) do |account|
+          next failure(:elevation_required) unless management?(account, session, grant, UNLINK)
+          identity = @store.binding_for_user(user_id: account.id, id: identity_id)
+          next failure unless identity && !identity.revoked_at
+          remaining = @store.bindings(user_id: account.id).any? { |other| other.id != identity.id && configured?(other) } &&
+            @access.sign_in_allowed?(account, :external_identity)
+          next failure(:last_credential) unless remaining || @remaining.call(account) == true
+          @store.revoke(identity: identity, at: @clock.now)
+          @revoke.call(user_id: account.id, at: @clock.now)
+          Result.success(user: account, strategy: :external_identity)
+        end
+      end
+
+      def reauthenticate(user:, session:, evidence:, policy: @policy)
+        return failure(:disabled) unless @enabled
+        return failure(:elevation_required) unless trusted?(evidence) && ![:sign_in, LINK, ENROLL].include?(evidence.purpose)
+        @store.with_user(id: user&.id) do |account|
+          row = account && @sessions.current_in_transaction(user: account, session: session)
+          next failure(:elevation_required) unless row && @eligible.call(account) == true && bound?(evidence, account, row) &&
+            @access.sign_in_allowed?(account, :external_identity)
+          identity = @store.binding(namespace: evidence.namespace)
+          next failure unless current_identity?(identity, evidence) && identity.user_id == account.id
+          # A callback timestamp is never substituted for provider auth_time.
+          time = evidence.authenticated_at
+          next failure(:elevation_required) unless time && time >= Time.at(evidence.transaction.issued_at.to_i) && time <= @clock.now
+          proof = StepUp::ExternalEvidence.send(:new, user_id: account.id, session_id: row.id,
+            method: :external_identity, verified_at: time, credential_id: identity.id.to_s,
+            credential_version: identity.credential_version, session_digest: row.token_digest, purpose: evidence.purpose)
+          authorized = policy.authorize(user: account, session_id: row.id, purpose: evidence.purpose, evidence: proof)
+          next authorized unless authorized.success?
+          finalize(evidence, account) { authorized }
+        end
+      end
+
+      # Called by the shared authority-revocation transaction even while provider
+      # sign-in is disabled. A binding survives the event, but older anonymous
+      # transactions and previously issued session/elevation proofs do not.
+      def self.invalidate_credentials_in_transaction(store:, user_id:, at:)
+        raise ArgumentError, "invalidation requires an occurrence time" unless at.is_a?(Time)
+        store.invalidate_credentials(user_id: user_id, at: at, credential_version: SecureRandom.hex(16))
+      end
+
+      def invalidate_credentials_in_transaction(user_id:, at:)
+        self.class.invalidate_credentials_in_transaction(store: @store, user_id: user_id, at: at)
+      end
+
+      def credential_current?(user:, id:, version:)
+        return false unless @enabled
+        identity = @store.binding_for_user(user_id: user.id, id: id)
+        !!(identity && !identity.revoked_at && identity.credential_version == version && configured?(identity))
+      end
+
+      private
+
+      def finalize_sign_in(evidence:, purpose:, replacing: nil)
+        return failure(:disabled) unless @enabled
+        return failure unless trusted?(evidence) && evidence.purpose == purpose
+        @store.with_identity(namespace: evidence.namespace, replacing: replacing) do |account, identity|
+          next failure(:identity_unbound) unless bound_identity?(identity, evidence)
+          next failure unless current_identity?(identity, evidence)
+          next failure unless account && @eligible.call(account) == true && @access.sign_in_allowed?(account, :external_identity)
+          finalize(evidence, account) do
+            proof = SessionProof.send(:new, user_id: account.id, credential_id: identity.id,
+              credential_version: identity.credential_version, verified_at: @clock.now)
+            yield account, identity, proof
+          end
+        end
+      end
+
+      def issue(config, browser_secret, purpose, account = nil, session = nil, binding_context: nil)
+        raw = @binding.generate
+        now = @clock.now
+        @store.create_transaction(digest: @digest.digest(raw), browser_digest: binding_digest(browser_secret, binding_context),
+          provider_id: config.id, issuer: config.issuer, audience: config.audience, purpose: purpose.to_s,
+          user_id: account&.id, session_id: session&.id, session_digest: session&.token_digest,
+          policy_version: account && @access.version(account), issued_at: now, expires_at: now + @lifetime)
+        Result.success(user: account, strategy: :external_identity, credential: pending(transaction: raw, browser_secret: browser_secret, binding_context: binding_context))
+      end
+
+      def valid_context?(context)
+        context.nil? || (context.is_a?(String) && context.ascii_only? && /\A[a-z][a-z0-9_:-]{0,127}\z/.match?(context))
+      end
+
+      def binding_digest(secret, context)
+        @digest.digest(context ? JSON.generate(["context", context, secret]) : secret)
+      end
+
+      def trusted?(evidence)
+        evidence.is_a?(VerifiedIdentity) && @configurations[evidence.provider_id].equal?(evidence.configuration)
+      end
+
+      def configured?(identity)
+        config = @configurations[identity.provider_id]
+        config && config.issuer == identity.issuer && config.audience == identity.audience
+      end
+
+      def matches?(identity, evidence)
+        identity.provider_id == evidence.provider_id && identity.issuer == evidence.issuer &&
+          identity.audience == evidence.audience && identity.subject == evidence.subject
+      end
+
+      def bound_identity?(identity, evidence) = identity && !identity.revoked_at && matches?(identity, evidence)
+
+      def current_identity?(identity, evidence)
+        bound_identity?(identity, evidence) && identity.linked_at <= evidence.transaction.issued_at &&
+          (!identity.invalidated_at || evidence.transaction.issued_at > identity.invalidated_at)
+      end
+
+      def bound?(evidence, account, session)
+        tx = evidence.transaction
+        tx.user_id == account.id && tx.session_id == session.id && tx.session_digest == session.token_digest &&
+          tx.policy_version == @access.version(account)
+      end
+
+      def management?(account, session, grant, purpose)
+        row = account && @sessions.current_in_transaction(user: account, session: session)
+        row && @eligible.call(account) == true && grant.is_a?(StepUp::Grant) &&
+          grant.valid_for?(user: account, user_id: account.id, session_id: row.id,
+            session_digest: row.token_digest, purpose: purpose, now: @clock.now)
+      end
+
+      def finalize(evidence, account)
+        tx = evidence.transaction
+        return failure(:expired_token) unless tx.issued_at <= @clock.now && tx.expires_at > @clock.now
+        return failure unless @eligible.call(account) == true
+        return failure(:consumed_token) unless @store.consume_transaction(digest: @digest.digest(tx.id), at: @clock.now)
+        yield
+      end
+
+      def reject_enrollment(reason = :invalid_credentials)
+        raise EnrollmentRejected.new(reason: reason)
+      end
+
+      def failure(reason = :invalid_credentials) = Result.failure(reason: reason)
+    end
+  end
+end

data/lib/add_auth/core/intake.rb

@@ -52,7 +52,12 @@ module AddAuth
       end
 
       def self.revoke_after_change?(changes)
-        (changes.keys.map(&:to_s) & %w[password_digest email_address]).any?
+        (changes.keys.map(&:to_s) & %w[password_digest email_address confirmed_at locked_at disabled_at deleted_at add_auth_authority add_auth_manual_lock]).any?
+      end
+
+      def self.notification_after_change(changes)
+        return :password_changed if changes.key?("password_digest")
+        :email_changed if changes.key?("email_address")
       end
     end
   end

data/lib/add_auth/core/maintenance.rb

@@ -5,12 +5,14 @@ module AddAuth
     # One bounded, replayable pass. Stores repeat cutoffs at mutation time;
     # returning counts records committed work, never a claim of an empty backlog.
     class Maintenance
+      EXPIRING = {ceremony: :ceremonies_deleted, external_transaction: :external_transactions_deleted,
+                  mobile_handoff: :mobile_handoffs_deleted}.freeze
       def initialize(stores:, options:, enqueue:, clock: Time)
         @stores, @options, @enqueue, @clock = stores, options, enqueue, clock
         unless options.batch_size.is_a?(Integer) && (1..1000).cover?(options.batch_size)
           raise ArgumentError, "maintenance.batch_size must be an integer from 1 to 1000"
         end
-        %i[session email notification].each do |kind|
+        %i[session email notification account].each do |kind|
           value = options.public_send(:"#{kind}_retention")
           valid = value.nil? || (value.is_a?(Numeric) && value.finite? && value >= 0)
           unless valid
@@ -23,8 +25,8 @@ module AddAuth
         now, limit = @clock.now, @options.batch_size
         counts = {}
         @stores.each do |kind, store|
-          if kind == :ceremony
-            counts[:ceremonies_deleted] = store.purge_expired(before: now, now: now, limit: limit)
+          if EXPIRING.key?(kind)
+            counts[EXPIRING.fetch(kind)] = store.purge_expired(before: now, now: now, limit: limit)
             next
           end
           retention = @options.public_send(:"#{kind}_retention")

data/lib/add_auth/core/migration/account_adoption.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "digest"
+require "add_auth/core/passwords/legacy_bcrypt"
+
+module AddAuth
+  module Core
+    module Migration
+      class AccountAdoption
+        # A retired source may still save harmless profile/tracking fields, but
+        # every credential, lifecycle flag and outstanding Devise proof remains
+        # owned by its selected authority. The bridge supplies dirty field names;
+        # only Core classifies their security meaning.
+        SOURCE_AUTHORITY_FIELDS = %w[email encrypted_password email_address password_digest confirmed_at unconfirmed_email
+          confirmation_token confirmation_sent_at reset_password_token reset_password_sent_at
+          locked_at failed_attempts unlock_token remember_created_at
+          add_auth_locked_until add_auth_manual_lock add_auth_password_scheme add_auth_migration_stamp
+          add_auth_strict add_auth_policy_version webauthn_id disabled_at deleted_at].freeze
+
+        def initialize(store:)
+          @store = store
+        end
+
+        def call(after: nil, limit: 100)
+          raise ArgumentError, "batch size must be between 1 and 1000" unless limit.is_a?(Integer) && limit.between?(1, 1000)
+          page = @store.source_page(after: after, limit: limit + 1)
+          counts = {inspected: 0, prepared: 0, unchanged: 0, conflicts: 0, changed_source: 0, active_destination: 0}
+          page.first(limit).each do |snapshot|
+            counts[:inspected] += 1
+            outcome = @store.with_account(snapshot.fetch(:id)) do |source|
+              next :changed_source unless source && stamp(source) == stamp(snapshot)
+              next :active_destination unless source[:authority] == "devise"
+              attributes = self.class.projection(email: source[:email], encrypted_password: source[:encrypted_password])
+              next :conflicts unless attributes
+              next :unchanged if source[:migration_stamp] == attributes[:add_auth_migration_stamp] && source[:email_address] == attributes[:email_address] && source[:password_digest] == attributes[:password_digest] && source[:scheme] == "devise_bcrypt"
+              @store.prepare(id: source[:id], **attributes)
+              :prepared
+            end
+            counts[outcome || :conflicts] += 1
+          end
+          counts.merge(next_cursor: (page.length > limit) ? page[limit - 1][:id] : nil)
+        end
+
+        def self.stamp(email:, encrypted_password:)
+          values = [email, encrypted_password].map { |value| value.nil? ? "nil:" : "#{value.bytesize}:#{value}" }
+          ::Digest::SHA256.hexdigest(values.join("|"))
+        end
+
+        def self.source_authority?(value) = value == "devise"
+
+        def self.authorize_source_write!(authority:, changed_fields:, authority_changed: false)
+          raise AddAuth::Error, "switch account authority through the reviewed migration procedure" if authority_changed
+          return if source_authority?(authority)
+          return if authority == "add_auth" && (changed_fields.map(&:to_s) & SOURCE_AUTHORITY_FIELDS).empty?
+          raise AddAuth::Error, "source authentication state is no longer authoritative"
+        end
+
+        def self.projection_for_write(authority:, authority_changed:, changed_fields:, **source)
+          authorize_source_write!(authority: authority, authority_changed: authority_changed, changed_fields: changed_fields)
+          source_authority?(authority) ? projection(**source) || raise(AddAuth::Error, "unsupported source credential profile; reconcile before writing") : {}
+        end
+
+        def self.projection(email:, encrypted_password:)
+          return unless email.is_a?(String) && email.valid_encoding? && email.bytesize.between?(1, 254)
+          identifier = email.strip.downcase
+          return unless identifier.match?(/\A[^\s@]+@[^\s@]+\z/) && identifier.bytesize <= 254
+          match = encrypted_password.is_a?(String) && Passwords::LegacyBcrypt::PATTERN.match(encrypted_password)
+          return unless match && match[1].to_i.between?(4, 14)
+          {email_address: identifier, password_digest: encrypted_password, add_auth_password_scheme: "devise_bcrypt",
+           add_auth_migration_stamp: stamp(email: email, encrypted_password: encrypted_password)}
+        end
+
+        private
+
+        def stamp(source) = self.class.stamp(email: source[:email], encrypted_password: source[:encrypted_password])
+      end
+    end
+  end
+end

data/lib/add_auth/core/migration/readiness.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    module Migration
+      # A census is evidence for planning, never permission to change authority.
+      class Readiness
+        MODULES = %w[database_authenticatable registerable recoverable rememberable validatable confirmable lockable trackable omniauthable timeoutable].freeze
+        EXTENSIONS = %w[devise-jwt devise_token_auth devise-two-factor devise-security devise-encryptable devise-passkeys devise-webauthn mongoid].freeze
+        TARGETS = %w[app/models/user.rb app/models/session.rb app/models/current.rb app/controllers/concerns/authentication.rb].freeze
+        ACTIONS = {
+          source_version: "Use a separately tested source profile; the initial fixture target is Devise 5.0.4.",
+          effective_inventory: "Run the effective inspection in an isolated local copy to verify schema, options and account counts.",
+          incomplete_inventory: "Resolve unreadable, oversized, dynamic or truncated input and repeat inspection.",
+          unsupported_extension: "Review each extension's credential and policy semantics before conversion.",
+          multiple_scopes: "Use an explicitly reviewed identity-scope conversion; do not merge scopes.",
+          account_contract: "Prepare additive Rails User/Session/Authentication contracts and review existing files.",
+          password_profile: "Prove the effective legacy verifier and a reset route for unsupported credentials.",
+          identifier_conflicts: "Resolve missing or normalization-colliding identifiers without merging accounts.",
+          policy_mapping: "Map every active account restriction and lifecycle operation before switch.",
+          migration_acceptance: "Complete account, lifecycle, provider, client and rollback rehearsals before switching authority."
+        }.freeze
+
+        def call(facts)
+          codes = [:migration_acceptance]
+          codes << :source_version unless facts.dig(:versions, :devise) == "5.0.4"
+          codes << :effective_inventory unless facts[:mode] == "effective"
+          codes << :incomplete_inventory unless facts[:complete]
+          codes << :unsupported_extension if facts.fetch(:extensions, []).any? || facts.fetch(:unknown_modules, 0).positive?
+          codes << :multiple_scopes if facts.fetch(:scope_count, 0) > 1
+          codes << :account_contract unless facts[:rails_contract]
+          codes << :password_profile if facts[:mode] != "effective" || facts.fetch(:accounts, []).any? { |a| a[:custom_verifier] || a[:pepper_configured] || a.dig(:counts, :unknown_password).to_i.positive? }
+          codes << :identifier_conflicts if facts.fetch(:accounts, []).any? { |a| a.dig(:counts, :missing_identifier).to_i.positive? || a.dig(:counts, :identifier_collisions).to_i.positive? }
+          codes << :policy_mapping if facts.fetch(:modules, []).any? { |name| name != "database_authenticatable" }
+          {schema_version: 1, status: "inventory", migration_ready: false,
+           facts: facts, blockers: codes.uniq.map { |code| {code: code.to_s, action: ACTIONS.fetch(code)} }}
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/core/mobile_authentication.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    class MobileAuthentication
+      def initialize(sessions:, profile:, intake:, verify_password:)
+        @sessions, @profile, @intake, @verify_password = sessions, profile, intake, verify_password
+      end
+
+      def password(identifier:, password:, client_id:, ip:, user_agent: nil, challenge_token: nil)
+        admitted = @intake.call(identifier: identifier, ip: ip, action: :sign_in, challenge_token: challenge_token)
+        return Result.failure(reason: admitted) if admitted.is_a?(Symbol)
+        return Result.failure(reason: :invalid_credentials) unless @profile&.client?(client_id) && password.is_a?(String) &&
+          password.valid_encoding? && password.bytesize.between?(1, 1024) && !password.include?("\0")
+
+        @sessions.authenticate_result(identifier: admitted, password: password, transport: :mobile, client_id: client_id, disclose_policy: true,
+          ip_address: hint(ip, 128), user_agent: hint(user_agent, 512)) do
+          @verify_password.call(identifier: admitted, password: password)
+        end
+      end
+
+      def self.bearer(header)
+        return unless header.is_a?(String) && header.bytesize == 54
+        match = /\ABearer (am1:[A-Za-z0-9_-]{43})\z/i.match(header)
+        match[1] if match && MobileProfile::PATTERN.match?(match[1])
+      end
+
+      private
+
+      def hint(value, limit)
+        value if value.is_a?(String) && value.valid_encoding? && value.bytesize <= limit && !value.match?(/[\x00-\x1f\x7f]/)
+      end
+    end
+  end
+end

data/lib/add_auth/core/mobile_handoffs.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "digest"
+require "base64"
+
+module AddAuth
+  module Core
+    # The native verifier protects this application handoff. It does not replace
+    # upstream provider state/nonce/PKCE, which remain the library's responsibility.
+    class MobileHandoffs
+      PURPOSE = ExternalIdentities::MOBILE
+      CODE = /\Aah1:[A-Za-z0-9_-]{43}\z/
+      STATE = /\A[A-Za-z0-9_-]{43,128}\z/
+      VERIFIER = /\A[A-Za-z0-9._~-]{43,128}\z/
+      CHALLENGE = /\A[A-Za-z0-9_-]{43}\z/
+      Handoff = Struct.new(:code, :state, :callback) do
+        def inspect = "#<AddAuth::Core::MobileHandoffs::Handoff [FILTERED]>"
+      end
+
+      def initialize(store:, profile:, sessions:, access_policy:, digest:, clock: Time, lifetime: 60)
+        raise ArgumentError, "handoff lifetime must be between 1 and 120 seconds" unless lifetime.is_a?(Integer) && lifetime.between?(1, 120)
+        @store, @profile, @sessions, @access, @digest, @clock, @lifetime = store, profile, sessions, access_policy, digest, clock, lifetime
+      end
+
+      def begin_transaction(pending:, client_id:, callback:, state:, code_challenge:, code_challenge_method:)
+        return failure unless pending.is_a?(ExternalIdentities::Pending) && pending.purpose == PURPOSE &&
+          @profile&.client?(client_id) && @profile.callback(client_id) == callback && callback &&
+          text?(state, STATE) && text?(code_challenge, CHALLENGE) && code_challenge_method == "S256" &&
+          pending.issued_at <= @clock.now && pending.expires_at > @clock.now
+        row = @store.create_pending(external_digest: @digest.digest(pending.id), client_id: client_id, callback: callback,
+          state: state, challenge_digest: @digest.digest(code_challenge), issued_at: pending.issued_at, expires_at: pending.expires_at)
+        row ? Result.success(user: nil, strategy: :external_identity) : failure
+      end
+
+      # Called only from ExternalIdentities' verified binding finalizer, inside
+      # the owning account transaction. No Session or bearer exists at this point.
+      def issue_in_transaction(user:, proof:, pending:)
+        return failure unless proof.is_a?(ExternalIdentities::SessionProof) && proof.user_id == user.id && pending.purpose == PURPOSE
+        row = @store.by_external_digest(digest: @digest.digest(pending.id))
+        return failure unless row && current_profile?(row) && !row.digest && !row.consumed_at && row.expires_at > @clock.now
+        code = "ah1:#{SecureRandom.urlsafe_base64(32)}"
+        issued = @store.issue(row: row, user_id: user.id, digest: @digest.digest(code),
+          credential_id: proof.credential_id, credential_version: proof.credential_version,
+          policy_version: @access.version(user), authenticated_at: proof.verified_at,
+          expires_at: [row.expires_at, @clock.now + @lifetime].min)
+        return failure unless issued
+        Result.success(user: user, strategy: :external_identity, credential: Handoff.new(code: code, state: row.state, callback: row.callback))
+      end
+
+      def exchange(code:, state:, code_verifier:, client_id:, ip: nil, user_agent: nil)
+        return failure unless @profile&.client?(client_id) && text?(code, CODE) && text?(state, STATE) && text?(code_verifier, VERIFIER)
+        challenge = Base64.urlsafe_encode64(::Digest::SHA256.digest(code_verifier), padding: false)
+        @store.with_code(digest: @digest.digest(code)) do |user, row|
+          now = @clock.now
+          next failure unless user && row && current_profile?(row) && row.client_id == client_id &&
+            @digest.matches?(row.challenge_digest, challenge) && @digest.matches?(@digest.digest(row.state), state)
+          next failure(:consumed_token) if row.consumed_at
+          next failure(:expired_token) unless row.issued_at <= now && row.expires_at > now
+          next failure unless row.policy_version == @access.version(user)
+          proof = ExternalIdentities::SessionProof.send(:new, user_id: user.id, credential_id: row.credential_id,
+            credential_version: row.credential_version, verified_at: row.authenticated_at)
+          grant = @sessions.create_in_transaction(user: user, method: :external_identity, proof: proof,
+            transport: :mobile, client_id: row.client_id, ip_address: hint(ip, 128), user_agent: hint(user_agent, 512))
+          next failure unless grant
+          # Session creation and consume commit together. An unexpected lost CAS
+          # rolls back issuance; it must never return a credential for this request.
+          raise AddAuth::Error, "mobile handoff could not finalize" unless @store.consume(row: row, at: now)
+          Result.success(user: user, strategy: :external_identity, session: grant.session, grant: grant)
+        end
+      end
+
+      private
+
+      def current_profile?(row) = @profile&.client?(row.client_id) && @profile.callback(row.client_id) == row.callback
+      def text?(value, pattern) = value.is_a?(String) && value.ascii_only? && pattern.match?(value)
+      def failure(reason = :invalid_credentials) = Result.failure(reason: reason)
+
+      def hint(value, limit)
+        value if value.is_a?(String) && value.valid_encoding? && value.bytesize <= limit && !value.match?(/[\x00-\x1f\x7f]/)
+      end
+    end
+  end
+end