add_auth 0.2.2 → 0.3.0

data/lib/add_auth/rails/provider_libraries/request_protection.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Rails
+    module ProviderLibraries
+      # Mint the form token with the actual maintained OmniAuth validator. A
+      # Rails adopter may already configure its session key; using a separate
+      # default Rack validator would generate a token that cannot be accepted.
+      module RequestProtection
+        module_function
+
+        def validator
+          return unless defined?(::OmniAuth::AuthenticityTokenProtection)
+          require "rack/protection"
+          phase = ::OmniAuth.config.request_validation_phase
+          candidate = (phase.is_a?(Class) && phase <= ::Rack::Protection::AuthenticityToken) ? phase.new : phase
+          candidate if candidate.is_a?(::Rack::Protection::AuthenticityToken) || rails_validator?(candidate)
+        end
+
+        def token(session:, rails_token: nil)
+          configured = validator
+          raise AddAuth::Error, "configure a supported OmniAuth request validator" unless configured
+          if rails_validator?(configured)
+            raise AddAuth::Error, "Rails request token is unavailable" unless rails_token.respond_to?(:call)
+            return rails_token.call
+          end
+          configured.mask_authenticity_token(session)
+        end
+
+        def parameter
+          configured = validator
+          raise AddAuth::Error, "configure a supported OmniAuth request validator" unless configured
+          rails_validator?(configured) ? ::ActionController::Base.request_forgery_protection_token : configured.options.fetch(:authenticity_param)
+        end
+
+        def rails_validator?(candidate)
+          defined?(::OmniAuth::RailsCsrfProtection::TokenVerifier) && candidate.is_a?(::OmniAuth::RailsCsrfProtection::TokenVerifier)
+        end
+        private_class_method :rails_validator?
+      end
+    end
+  end
+end

data/lib/add_auth/rails/runtime.rb

@@ -14,10 +14,147 @@ module AddAuth
 
       def config = AddAuth.configuration
 
+      def account_policy
+        Core::AccountPolicy.new(enabled: config.lifecycle.enabled, eligible: config.lifecycle.eligible)
+      end
+
+      def eligible(user)
+        config.eligible.call(user) == true && account_policy.allowed?(user)
+      end
+
+      def authority
+        require "add_auth/rails/stores/authority"
+        tokens = []
+        tokens << ::AddAuthSignInToken if defined?(::AddAuthSignInToken) && ::AddAuthSignInToken.table_exists?
+        tokens << ::AddAuthAccountToken if defined?(::AddAuthAccountToken) && ::AddAuthAccountToken.table_exists?
+        ceremonies = []
+        ceremonies << ::AddAuthCeremony if defined?(::AddAuthCeremony) && ::AddAuthCeremony.table_exists?
+        ceremonies << ::AddAuthExternalTransaction if defined?(::AddAuthExternalTransaction) && ::AddAuthExternalTransaction.table_exists?
+        ceremonies << ::AddAuthMobileHandoff if defined?(::AddAuthMobileHandoff) && ::AddAuthMobileHandoff.table_exists?
+        invalidator = if defined?(::AddAuthExternalIdentity) && ::AddAuthExternalIdentity.table_exists?
+          ->(user_id:, at:) { Core::ExternalIdentities.invalidate_credentials_in_transaction(store: external_identity_store, user_id: user_id, at: at) }
+        end
+        Stores::Authority.new(user_model: ::User, session_model: ::Session, token_models: tokens, ceremony_models: ceremonies, external_invalidator: invalidator)
+      end
+
+      def external_identity_store
+        require "add_auth/rails/stores/external_identities"
+        Stores::ExternalIdentities.new(user_model: ::User, identity_model: ::AddAuthExternalIdentity, transaction_model: ::AddAuthExternalTransaction)
+      end
+
+      def external_provider(id)
+        config.external_identities.provider(id) if config.external_identities.enabled
+      end
+
+      def external_reauthentication? = config.external_identities.enabled && config.external_identities.providers.any?(&:reauthentication?)
+
+      def external_identities
+        options = config.external_identities
+        raise AddAuth::Error, "enable external identities and register a provider first" unless options.enabled && options.configurations.any?
+        Core::ExternalIdentities.new(store: external_identity_store, configurations: options.configurations,
+          sessions: sessions, access_policy: access_policy, policy: step_up_policy, eligible: method(:eligible),
+          digest: config.sign_in_token_digest, revoke_authority: authority.method(:revoke),
+          remaining_method: remaining_factors,
+          enrollment_eligible: ->(user) { account_policy.allowed?(user, purpose: :confirm) }, enabled: true, mobile_enabled: config.mobile.enabled)
+      end
+
+      def remaining_factors
+        require "add_auth/core/remaining_factors"
+        require "add_auth/core/passwords/credential"
+        credential = Core::Passwords::Credential.new(legacy_verifier: config.legacy_password_verifier)
+        Core::RemainingFactors.new(access_policy: access_policy,
+          passkey_count: ->(user) { (defined?(::AddAuthCredential) && ::AddAuthCredential.table_exists?) ? ::AddAuthCredential.where(user_id: user.id, revoked_at: nil).count : 0 },
+          password_available: ->(user) { credential.available?(user: user, current: config.current_password_support) })
+      end
+
+      def provider_enrollment
+        require "add_auth/rails/provider_enrollment"
+        ProviderEnrollment.new(model: ::AddAuthExternalTransaction, digest: config.sign_in_token_digest, key: key("external-enrollment"))
+      end
+
+      def accounts
+        raise AddAuth::Error, "enable account lifecycle first" unless config.lifecycle.enabled
+        require "add_auth/rails/stores/account_tokens"
+        Core::AccountLifecycle.new(store: Stores::AccountTokens.new(user_model: ::User, token_model: ::AddAuthAccountToken,
+          session_model: ::Session, address_model: ::AddAuthAddressClaim, authority: authority, provision: config.lifecycle.provision, delete_account: config.lifecycle.delete_account),
+          digest: config.sign_in_token_digest, delivery_cipher: DeliveryCipher.new(key: key("account-proofs")),
+          policy: account_policy, password_policy: config.lifecycle.password_policy, trusted_address: config.trusted_recovery_address,
+          lifetime: config.lifecycle.proof_lifetime, notify: ->(**event) { security_events.issue(**event) if config.notifications.enabled },
+          sessions: sessions, step_up_policy: step_up_policy, profile_attributes: config.lifecycle.profile_attributes, deletion_allowed: config.lifecycle.deletion_allowed,
+          external_identities: -> { external_identities })
+      end
+
+      def enqueue_account_request(identifier:, purpose:)
+        job = ::AddAuth::AccountRequestJob.perform_later(encrypt_intake(identifier: identifier, purpose: purpose))
+        raise AddAuth::Error, "account request queue unavailable" unless job
+        job
+      rescue
+        raise AddAuth::Error, "account request queue unavailable", cause: nil
+      end
+
+      def account_proof_url(token, purpose:)
+        raise AddAuth::Error, "unsupported account proof" unless Core::AccountLifecycle::PURPOSES.include?(purpose)
+        authentication_url("/account/proofs/#{purpose}", token: token)
+      end
+
       def sessions
         Core::Sessions.new(store: Stores::Sessions.new(user_model: ::User, session_model: ::Session),
-          digest: config.session_token_digest, eligible: config.eligible, lifetime: config.session.lifetime,
-          idle_timeout: config.session.idle_timeout, legacy_bridge_until: config.session.legacy_bridge_until, access_policy: access_policy)
+          digest: config.session_token_digest, eligible: method(:eligible), lifetime: config.session.lifetime,
+          idle_timeout: config.session.idle_timeout, legacy_bridge_until: config.session.legacy_bridge_until, access_policy: access_policy,
+          password_lifecycle: password_lifecycle,
+          mobile_profile: mobile_profile,
+          verified_denial: ->(user) { (config.eligible.call(user) == true) ? account_policy.denial(user) : :disabled },
+          remembered_profile: config.lifecycle.enabled ? {lifetime: config.lifecycle.remember_lifetime, idle_timeout: config.lifecycle.remember_idle_timeout} : nil,
+          on_sign_in: method(:record_sign_in))
+      end
+
+      def mobile_profile
+        options = config.mobile
+        return unless options.enabled
+        raise AddAuth::Error, "enable session_upgrade before mobile sessions" unless config.session.enabled
+        Core::MobileProfile.new(lifetime: options.lifetime, idle_timeout: options.idle_timeout, clients: options.clients, callbacks: options.callbacks)
+      end
+
+      def mobile_authentication
+        require "add_auth/core/mobile_authentication"
+        Core::MobileAuthentication.new(sessions: sessions, profile: mobile_profile,
+          intake: intake, verify_password: method(:authenticate_password))
+      end
+
+      def mobile_handoffs
+        require "add_auth/core/mobile_handoffs"
+        require "add_auth/rails/stores/mobile_handoffs"
+        Core::MobileHandoffs.new(store: Stores::MobileHandoffs.new(user_model: ::User, handoff_model: ::AddAuthMobileHandoff, session_model: ::Session),
+          profile: mobile_profile, sessions: sessions, access_policy: access_policy, digest: config.sign_in_token_digest)
+      end
+
+      def native_apple
+        require "add_auth/core/native_authentication"
+        require "add_auth/rails/provider_libraries/apple_native"
+        require "add_auth/rails/provider_libraries/apple_jwks"
+        raise AddAuth::Error, "install and require ruby-jwt for native Apple authentication" unless defined?(::JWT)
+        raise AddAuth::Error, "configure native Apple providers as an explicit client map" unless config.mobile.apple_providers.is_a?(Hash)
+        providers = config.mobile.apple_providers.transform_values { |id| config.external_identities.native_provider(id) }
+        Core::NativeAuthentication.new(external_identities: external_identities, profile: mobile_profile,
+          providers: providers, intake: intake, accounts: (method(:accounts) if config.lifecycle.enabled), verify: ->(**arguments) {
+            ProviderLibraries::AppleNative::CallbackResult.capture(**arguments, jwks: ProviderLibraries::AppleJwks.new(cache: ::Rails.cache))
+          })
+      end
+
+      def record_sign_in(user:, session:, at:)
+        require "add_auth/rails/stores/commit_dispatch"
+        Stores::CommitDispatch.event(transaction: ::User.current_transaction, event: "session_created.add_auth",
+          payload: {user_id: user.id, session_id: session.id, method: session.authenticated_with, occurred_at: at})
+      end
+
+      def password_lifecycle
+        return unless config.lifecycle.enabled || ::User.column_names.include?("add_auth_password_scheme")
+        require "add_auth/core/passwords/lifecycle"
+        require "add_auth/rails/stores/account_credentials"
+        Core::Passwords::Lifecycle.new(store: Stores::AccountCredentials.new(user_model: ::User, authority: authority),
+          policy: method(:eligible), enabled: config.lifecycle.enabled,
+          maximum_attempts: config.lifecycle.maximum_attempts, unlock_in: config.lifecycle.unlock_in,
+          issue_unlock: ->(user) { accounts.issue_unlock_in_transaction(user: user) })
       end
 
       def security_events
@@ -31,7 +168,9 @@ module AddAuth
         Core::AccessPolicy.new(credentials: ->(id) {
           ::AddAuthCredential.find_by(external_id: id) if defined?(::AddAuthCredential) && ::AddAuthCredential.table_exists?
         }, passkeys_enabled: config.passkeys.enabled, email_enabled: Core::Intake.email_available?(config),
-          trusted_recovery_address: config.trusted_recovery_address, password_enabled: config.passwords_enabled)
+          trusted_recovery_address: config.trusted_recovery_address, password_enabled: config.passwords_enabled,
+          external_enabled: config.external_identities.enabled,
+          external_current: ->(**arguments) { external_identities.credential_current?(**arguments) })
       end
 
       def email(purpose: :sign_in)
@@ -41,7 +180,7 @@ module AddAuth
         raise AddAuth::Error, "enable session_upgrade and email_link first" unless Core::Intake.email_available?(config)
         Core::Strategies::EmailLink.new(store: Stores::EmailTokens.new(user_model: ::User,
           token_model: ::AddAuthSignInToken, session_model: ::Session), digest: config.sign_in_token_digest,
-          delivery_cipher: DeliveryCipher.new(key: key("delivery")), eligible: config.eligible,
+          delivery_cipher: DeliveryCipher.new(key: key("delivery")), eligible: method(:eligible),
           normalize_identifier: method(:normalize), identifier_for: ->(user) { user.email_address },
           token_lifetime: {"reauthentication" => 300, "recovery" => 1200}.fetch(purpose.to_s, config.email_link.token_lifetime),
           same_browser: (purpose.to_s == "recovery") ? false : config.email_link.same_browser, purpose: purpose,
@@ -82,7 +221,23 @@ module AddAuth
         else
           {}
         end
-        {sign_out_everywhere: {methods: [:password, :email_link, :passkey], return_to: "/sessions/revoke-all", label: "sign out everywhere"}}.merge(defaults).merge(config.step_up.purposes)
+        if config.lifecycle.enabled
+          defaults = defaults.merge(
+            change_email: {methods: [:password, :email_link, :passkey], return_to: "/account/email", label: "change your email address"},
+            change_password: {methods: [:password, :email_link, :passkey], return_to: "/account/password", label: "change your password"},
+            delete_account: {methods: [:password, :email_link, :passkey], return_to: "/account/delete", label: "delete your account"}
+          )
+        end
+        if config.external_identities.enabled
+          defaults = defaults.merge(
+            link_external_identity: {methods: [:password, :email_link, :passkey], return_to: "/account/external-identities", label: "link a sign-in provider"},
+            unlink_external_identity: {methods: [:password, :email_link, :passkey], return_to: "/account/external-identities", label: "remove a sign-in provider"}
+          )
+          defaults = defaults.transform_values do |rule|
+            (!external_reauthentication? || rule[:require_passkey] || rule[:reauthentication] == false) ? rule : rule.merge(methods: (rule[:methods] + [:external_identity]).uniq)
+          end
+        end
+        {sign_out_everywhere: {methods: [:password, :email_link, :passkey, *(:external_identity if external_reauthentication?)], return_to: "/sessions/revoke-all", label: "sign out everywhere"}}.merge(defaults).merge(config.step_up.purposes)
       end
 
       def passkeys
@@ -91,7 +246,7 @@ module AddAuth
         Core::Strategies::Passkey.new(store: Stores::Passkeys.new(user_model: ::User, session_model: ::Session,
           credential_model: ::AddAuthCredential, ceremony_model: ::AddAuthCeremony, token_model: ::AddAuthSignInToken), sessions: sessions,
           policy: step_up_policy, access_policy: access_policy, digest: config.sign_in_token_digest,
-          eligible: config.eligible, rp_id: config.passkeys.rp_id, origins: config.passkeys.origins, name: config.passkeys.name,
+          eligible: method(:eligible), rp_id: config.passkeys.rp_id, origins: config.passkeys.origins, name: config.passkeys.name,
           limiter: method(:limit), anonymous_limit: config.passkeys.anonymous_limit,
           notify: ->(**event) { security_events.issue(**event) }, allow_localhost: !::Rails.env.production?, support_url: config.support_url,
           on_failure: ->(reason) { ::ActiveSupport::Notifications.instrument("passkey_failure.add_auth", reason: reason) })
@@ -103,6 +258,7 @@ module AddAuth
           password_version: ->(user) { config.sign_in_token_digest.digest("password:#{user.password_digest}") },
           credential_current: ->(user:, evidence:) {
             evidence.method == :password ||
+              (evidence.method == :external_identity && access_policy.external_credential_current?(user: user, id: evidence.credential_id, version: evidence.credential_version)) ||
               (evidence.method == :passkey && access_policy.credential_current?(user: user, id: evidence.credential_id) &&
                 ::AddAuthCredential.find_by(external_id: evidence.credential_id)&.public_key == evidence.credential_version) ||
               (evidence.method == :email_link && Core::Intake.email_available?(config) &&
@@ -204,14 +360,20 @@ module AddAuth
       end
 
       def sign_in_url(token, purpose: "sign_in")
+        path = {"sign_in" => "/sign-in/link", "reauthentication" => "/reauthenticate/link", "recovery" => "/recover/link"}.fetch(purpose.to_s)
+        authentication_url(path, token: token)
+      end
+
+      def authentication_url(path, **query)
         uri = URI.parse(config.base_url.to_s)
         valid = uri.host && !uri.userinfo && !uri.query && !uri.fragment && ["", "/"].include?(uri.path) &&
           (uri.scheme == "https" || (!::Rails.env.production? && uri.scheme == "http"))
         unless valid
           raise AddAuth::Error, "configure base_url as a fixed HTTPS origin (HTTP allowed only outside production)"
         end
-        path = {"sign_in" => "/sign-in/link", "reauthentication" => "/reauthenticate/link", "recovery" => "/recover/link"}.fetch(purpose.to_s)
-        "#{uri.to_s.delete_suffix("/")}#{path}?token=#{URI.encode_www_form_component(token)}"
+        "#{uri.to_s.delete_suffix("/")}#{path}?#{URI.encode_www_form(query)}"
+      rescue URI::InvalidURIError
+        raise AddAuth::Error, "configure a fixed HTTPS origin", cause: nil
       end
     end
   end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Rails
+    module Stores
+      class AccountCredentials
+        def initialize(user_model:, authority:)
+          @users, @authority = user_model, authority
+        end
+
+        def update_account(user:, **attributes)
+          raise AddAuth::Error, "credential changes require an account transaction" unless @users.connection.transaction_open?
+          user.update_columns(attributes)
+          user.reload
+        rescue ActiveRecord::RecordNotUnique
+          raise Core::AccountLifecycle::Conflict
+        end
+
+        def replace_password(user:, password:)
+          raise AddAuth::Error, "credential changes require an account transaction" unless @users.connection.transaction_open?
+          user.password = password
+          unless user.valid?
+            user.reload
+            raise Core::AccountLifecycle::InvalidPassword
+          end
+          persist_password(user: user, digest: user.password_digest)
+        end
+
+        def rehash_password(user:, password:)
+          fresh = @users.new(password: password)
+          persist_password(user: user, digest: fresh.password_digest)
+        end
+
+        def revoke_authority(user:, at:) = @authority.revoke(user_id: user.id, at: at)
+
+        private
+
+        def persist_password(user:, digest:)
+          update_account(user: user, password_digest: digest, add_auth_password_scheme: "rails")
+        end
+      end
+    end
+  end
+end

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,96 @@
+# 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: {})
+          raise AddAuth::Error, "registration must own its transaction" if @users.connection.transaction_open?
+          completed = false
+          @users.transaction do |transaction|
+            transaction.after_commit { completed = true }
+            user = @users.new(profile)
+            user.email_address = email
+            user.password = password
+            user.add_auth_authority = "add_auth"
+            user.save!
+            yield user
+          end
+          raise AddAuth::Error, "registration transaction rolled back" unless completed
+          :created
+        rescue ActiveRecord::RecordNotUnique, Core::AccountLifecycle::Conflict
+          :duplicate
+        rescue ActiveRecord::RecordInvalid => error
+          (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)
+
+        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