add_auth 0.2.2 → 0.4.0

data/app/views/add_auth/external_identities/_unavailable.html.erb

@@ -0,0 +1,3 @@
+<h1 id="add_auth-title">Try again shortly</h1>
+<p role="alert"><%= @error %></p>
+<p><%= link_to "Back to sign in", "/sign-in" %></p>

data/app/views/add_auth/passkeys/_controls.html.erb

@@ -1,15 +1,17 @@
 <div data-controller="add-auth-passkey"
+  data-add-auth-passkey-turbo-value="<%= AddAuth.configuration.turbo_enabled %>"
   data-add-auth-passkey-options-url-value="<%= options_url %>"
   data-add-auth-passkey-finish-url-value="<%= finish_url %>"
   data-add-auth-passkey-mode-value="<%= mode %>"
   data-add-auth-passkey-purpose-value="<%= local_assigns[:purpose] %>"
   data-add-auth-passkey-conditional-value="<%= local_assigns.fetch(:conditional, false) && !AddAuth.configuration.challenge_on.include?(action) %>"
   data-add-auth-passkey-csrf-value="<%= form_authenticity_token %>"
-  data-action="turbo:before-cache@document->add-auth-passkey#beforeCache submit@document->add-auth-passkey#otherSubmission">
+  data-action="turbo:before-cache@document->add-auth-passkey#beforeCache pagehide@window->add-auth-passkey#beforeCache pageshow@window->add-auth-passkey#restore submit@document->add-auth-passkey#otherSubmission">
   <p data-add-auth-passkey-target="unavailable">Passkeys need JavaScript and a compatible browser or device. Use another method allowed by your account policy if available.</p>
   <%= form_with url: options_url, data: add_auth_challenge_form_data(action).merge(add_auth_passkey_target: "form", action: [add_auth_challenge_form_data(action)[:action], "submit->add-auth-passkey#submit"].compact.join(" ")) do |form| %>
     <%= add_auth_challenge_tag action, id: "passkey_#{action}" %>
     <div hidden data-add-auth-passkey-target="controls">
+      <%= render "add_auth/sign_ins/remember", form: form, id: "passkey" if action == :sign_in %>
       <%= form.submit label, class: add_auth_class(:button), data: {add_auth_challenge_target: "submit", add_auth_passkey_target: "button"} %>
     </div>
   <% end %>

data/app/views/add_auth/provider_sign_ins/_enrollment.html.erb

@@ -0,0 +1,12 @@
+<% content_for :title, "Create an account" %>
+<h1 id="add_auth-title">Create an account with <%= @provider.label %></h1>
+<p>Enter your email, then continue to your provider. We’ll email you a separate confirmation link before you can sign in.</p>
+<%= form_with url: "/account/sign-up/providers/#{@provider.middleware_name}", method: :post, data: add_auth_challenge_form_data(:register).merge(turbo: false) do |form| %>
+  <div class="<%= add_auth_class(:field) %>">
+    <%= form.label :email_address, "Email address" %>
+    <%= form.email_field :email_address, required: true, maxlength: 254, autocomplete: "email", class: add_auth_class(:input) %>
+  </div>
+  <%= add_auth_challenge_tag :register %>
+  <%= form.submit "Continue with #{@provider.label}", class: add_auth_class(:button), data: {add_auth_challenge_target: "submit"} %>
+<% end %>
+<p><%= link_to "Already have an account? Sign in", "/sign-in" %></p>

data/app/views/add_auth/provider_sign_ins/_failure.html.erb

@@ -0,0 +1,3 @@
+<h1 id="add_auth-title">Provider sign-in could not be completed</h1>
+<p class="<%= add_auth_class(:notice) %>" role="alert"><%= @error %></p>
+<p><%= link_to "Return to sign in", "/sign-in" %></p>

data/app/views/add_auth/provider_sign_ins/_prepare.html.erb

@@ -0,0 +1,7 @@
+<h1 id="add_auth-title"><%= @heading %></h1>
+<p class="<%= add_auth_class(:muted) %>">You will continue to <%= @provider.label %> to verify this request.</p>
+<%= form_with url: @provider_path, method: :post, authenticity_token: false, data: {turbo: false} do |form| %>
+  <%= hidden_field_tag @omniauth_csrf_parameter, @omniauth_csrf_token %>
+  <%= form.submit "Continue with #{@provider.label}", class: add_auth_class(:button) %>
+<% end %>
+<p><%= link_to "Cancel", "/sign-in" %></p>

data/app/views/add_auth/reauthentications/_form.html.erb

@@ -19,6 +19,15 @@
     <%= form.submit "Email me a verification link", class: add_auth_class(:button), data: {add_auth_challenge_target: "submit"} %>
   <% end %>
 <% end %>
+<% if Array(@methods).include?(:external_identity) && AddAuth.configuration.external_identities.enabled %>
+  <% AddAuth.configuration.external_identities.providers.select(&:reauthentication?).each do |provider| %>
+    <%= form_with url: "/reauthenticate/providers/#{provider.middleware_name}", method: :post, data: add_auth_challenge_form_data(:reauthenticate).merge(turbo: false) do |form| %>
+      <%= form.hidden_field :purpose, value: @purpose %>
+      <%= add_auth_challenge_tag :reauthenticate, id: "verify_#{provider.middleware_name}" %>
+      <%= form.submit "Verify with #{provider.label}", class: add_auth_class(:button), data: {add_auth_challenge_target: "submit"} %>
+    <% end %>
+  <% end %>
+<% end %>
 <% if Array(@methods).empty? %><p role="status">No permitted verification method is available here. Contact your account administrator for an allowed way to continue.</p><% end %>
 <p><%= link_to "Cancel", @rule&.return_to || "/", class: add_auth_class(:link) %></p>
 

data/app/views/add_auth/sessions/_list.html.erb

@@ -2,7 +2,7 @@
   <% @sessions.each do |session| %>
     <li class="add_auth-session" id="session_<%= session.id %>">
       <div>
-        <strong><%= session.current ? "This browser" : "Signed-in browser" %></strong>
+        <strong><%= session.transport == "mobile" ? "Signed-in mobile device (#{session.client_id})" : (session.current ? "This browser" : "Signed-in browser") %></strong>
         <p class="<%= add_auth_class(:muted) %>">
           <%= session.authenticated_with ? "Signed in with #{session.authenticated_with.tr("_", " ")}" : "Imported session" %>
           · <%= session.last_seen_at ? "Last active #{session.last_seen_at.strftime("%Y-%m-%d %H:%M UTC")}" : "Activity unknown" %>

data/app/views/add_auth/sessions/index.html.erb

@@ -8,5 +8,12 @@
   <h1 id="add_auth-title">Your sessions</h1>
   <p class="<%= add_auth_class(:muted) %>">Review browsers signed in to your account and revoke any you no longer use.</p>
   <p><%= link_to "Sign out everywhere", "/sessions/revoke-all", class: add_auth_class(:link) %></p>
+  <% if AddAuth.configuration.lifecycle.enabled %>
+    <p><%= link_to "Change email", "/account/email" %> · <%= link_to "Change password", "/account/password" %> · <%= link_to "Delete account", "/account/delete" %></p>
+  <% end %>
   <div id="add_auth-session-content"><%= render "add_auth/sessions/list" %></div>
 </main>
+
+<% if AddAuth.configuration.external_identities.enabled %>
+  <p><%= link_to "Manage sign-in providers", "/account/external-identities" %></p>
+<% end %>

data/app/views/add_auth/sign_ins/_confirmation.html.erb

@@ -4,6 +4,7 @@
 <%= form_with url: "/sign-in/link", data: {turbo_frame: "_top"} do |form| %>
   <%= form.hidden_field :token, value: params[:token] %>
   <%= form.hidden_field :switch_account, value: "1" %>
+  <%= render "add_auth/sign_ins/remember", form: form, id: "email" %>
   <%= form.submit "Sign in to this account", class: add_auth_class(:button) %>
 <% end %>
 <p><%= link_to "Cancel", "/sign-in", class: add_auth_class(:link) %></p>

data/app/views/add_auth/sign_ins/_form.html.erb

@@ -1,5 +1,8 @@
 <h1 id="add_auth-title">Sign in</h1>
 <p class="<%= add_auth_class(:muted) %>">Choose an available sign-in method.</p>
+<% if AddAuth.configuration.lifecycle.enabled %>
+  <p><%= link_to "Create an account", "/account/sign-up" %> · <%= link_to "Forgot your password?", "/account/requests/reset_password" %></p>
+<% end %>
 <% if @error %><p class="<%= add_auth_class(:notice) %>" role="alert"><%= @error %></p><% end %>
 <% if AddAuth.configuration.passwords_enabled %>
 <%= form_with url: "/sign-in/password", id: "add_auth-password-form", data: add_auth_challenge_form_data(:sign_in) do |form| %>
@@ -12,6 +15,7 @@
     <%= form.password_field :password, required: true, autocomplete: "current-password", class: add_auth_class(:input) %>
   </div>
   <%= add_auth_challenge_tag :sign_in %>
+  <%= render "add_auth/sign_ins/remember", form: form, id: "password" %>
   <%= form.submit "Sign in with password", class: add_auth_class(:button), data: {add_auth_challenge_target: "submit"} %>
 <% end %>
 <% end %>
@@ -32,3 +36,16 @@
   <%= render "add_auth/passkeys/controls", mode: "get", options_url: "/passkeys/sign-in/options", finish_url: "/passkeys/sign-in", label: "Sign in with a passkey", action: :sign_in, conditional: true %>
   <p><%= link_to "I can’t use my passkeys", "/recover" %></p>
 <% end %>
+<% if AddAuth.configuration.external_identities.enabled && AddAuth.configuration.external_identities.providers.any? %>
+  <hr class="<%= add_auth_class(:divider) %>">
+  <% AddAuth.configuration.external_identities.providers.each do |provider| %>
+    <%= form_with url: "/sign-in/providers/#{provider.middleware_name}", method: :post, data: add_auth_challenge_form_data(:provider).merge(turbo: false) do |form| %>
+      <%= render "add_auth/sign_ins/remember", form: form, id: "provider_#{provider.middleware_name}" %>
+      <%= add_auth_challenge_tag :provider, id: "provider_#{provider.middleware_name}" %>
+      <%= form.submit "Continue with #{provider.label}", class: add_auth_class(:button), data: {add_auth_challenge_target: "submit"} %>
+    <% end %>
+    <% if AddAuth.configuration.lifecycle.enabled %>
+      <p><%= link_to "Create an account with #{provider.label}", "/account/sign-up/providers/#{provider.middleware_name}" %></p>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/add_auth/sign_ins/_remember.html.erb

@@ -0,0 +1,6 @@
+<% if AddAuth.configuration.lifecycle.enabled %>
+  <div class="<%= add_auth_class(:field) %>">
+    <%= form.check_box :remember, id: "#{id}_remember" %>
+    <%= form.label :remember, "Keep me signed in on this browser", for: "#{id}_remember" %>
+  </div>
+<% end %>

data/app/views/layouts/add_auth/authentication.html.erb

@@ -1,9 +1,9 @@
 <!DOCTYPE html>
-<html lang="en">
+<html lang="en"<% unless AddAuth.configuration.turbo_enabled %> data-turbo="false"<% end %>>
   <head>
-    <title>Sign in</title>
+    <title><%= content_for?(:title) ? yield(:title) : "Sign in" %></title>
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta name="referrer" content="no-referrer">
+    <meta name="referrer" content="<%= response.headers["Referrer-Policy"] || "no-referrer" %>">
     <% turbo_exempts_page_from_cache %>
     <% turbo_page_requires_reload if request.headers["Turbo-Frame"].present? %>
     <%= yield :head %>
@@ -13,6 +13,7 @@
   </head>
   <body class="<%= add_auth_class(:body) %>">
     <main class="<%= add_auth_class(:panel) %>" aria-labelledby="add_auth-title">
+      <% if flash[:notice] %><p role="status" data-turbo-temporary><%= flash[:notice] %></p><% end %>
       <div id="add_auth-content"><%= yield %></div>
     </main>
   </body>

data/exe/add_auth-preflight

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "add_auth/migration/static_inventory"
+
+options = {root: Dir.pwd}
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: add_auth-preflight [--root PATH] (static inspection; does not boot Rails)"
+  opts.on("--root PATH", "Host source directory") { |value| options[:root] = value }
+  opts.on("-h", "--help") {
+    puts opts
+    exit
+  }
+end
+begin
+  parser.parse!
+  raise OptionParser::InvalidArgument unless ARGV.empty?
+  report = AddAuth::Migration::StaticInventory.new(**options).call
+  puts JSON.pretty_generate(report)
+  exit(report.dig(:facts, :complete) ? 0 : 2)
+rescue OptionParser::ParseError, SystemCallError, ArgumentError
+  warn "Unable to inspect source. Supply a readable host directory with --root; see --help."
+  exit 2
+end

data/lib/add_auth/configuration.rb

@@ -1,24 +1,98 @@
 # frozen_string_literal: true
 
+require "add_auth/core/passwords/bcrypt_support"
+
 module AddAuth
   class Configuration
     attr_accessor :challenge, :challenge_on,
-      :digest_secret, :eligible, :stylesheet, :css_classes, :mail_from, :base_url, :rate_limit_store, :trusted_recovery_address, :support_url
+      :digest_secret, :eligible, :stylesheet, :css_classes, :mail_from, :base_url, :rate_limit_store, :trusted_recovery_address, :support_url, :legacy_password_verifier, :current_password_support
     attr_writer :session_token_digest, :sign_in_token_digest
 
     SessionOptions = Struct.new(:enabled, :lifetime, :idle_timeout, :legacy_bridge_until)
+    MobileOptions = Struct.new(:enabled, :lifetime, :idle_timeout, :clients, :callbacks, :apple_providers)
     EmailOptions = Struct.new(:enabled, :token_lifetime, :same_browser)
     StepUpOptions = Struct.new(:enabled, :purposes, :fresh_for, :strong_for)
     PasskeyOptions = Struct.new(:enabled, :rp_id, :origins, :name, :anonymous_limit)
     NotificationOptions = Struct.new(:enabled)
-    MaintenanceOptions = Struct.new(:batch_size, :session_retention, :email_retention, :notification_retention)
-    attr_accessor :passwords_enabled
-    attr_reader :maintenance, :notifications, :passkeys, :session, :email_link, :step_up, :challenge_when_unavailable
+    MaintenanceOptions = Struct.new(:batch_size, :session_retention, :email_retention, :notification_retention, :account_retention)
+    LifecycleOptions = Struct.new(:enabled, :password_policy, :eligible, :provision, :profile_attributes, :maximum_attempts, :unlock_in, :proof_lifetime, :remember_lifetime, :remember_idle_timeout, :deletion_allowed, :delete_account, :confirmation_required, :reset_unconfirmed)
+    class ExternalProvider
+      attr_reader :id, :label, :middleware_name, :configuration, :apple_form_post, :reauthentication
+
+      def initialize(id:, label:, middleware_name:, configuration:, apple_form_post: false, reauthentication: false)
+        @id, @label, @middleware_name = [id, label, middleware_name].map { |value| text(value) }
+        raise ArgumentError, "external provider middleware name is invalid" unless middleware_name.match?(/\A[a-z][a-z0-9_]{0,63}\z/)
+        raise ArgumentError, "external provider configuration does not match its id" unless configuration.respond_to?(:id) && configuration.id == id
+        raise ArgumentError, "Apple form_post must be explicit" unless apple_form_post == true || apple_form_post == false
+
+        raise ArgumentError, "provider reauthentication must be explicit" unless [true, false].include?(reauthentication)
+        @reauthentication = reauthentication
+        @configuration, @apple_form_post = configuration, apple_form_post
+        freeze
+      end
+
+      def reauthentication? = reauthentication
+      def apple_form_post? = apple_form_post
+
+      private
+
+      def text(value)
+        raise ArgumentError, "external provider value is invalid" unless value.is_a?(String) && value.valid_encoding? &&
+          value.bytesize.between?(1, 2048) && !value.match?(/[\x00-\x1f\x7f]/)
+
+        value.dup.freeze
+      end
+    end
+
+    class ExternalIdentityOptions
+      attr_accessor :enabled
+
+      def initialize
+        @enabled = false
+        @providers = []
+        @native_providers = {}
+      end
+
+      def register(**attributes)
+        provider = ExternalProvider.new(**attributes)
+        raise ArgumentError, "external provider id is already registered" if configurations.any? { |item| item.id == provider.id }
+        raise ArgumentError, "external provider middleware is already registered" if @providers.any? { |item| item.middleware_name == provider.middleware_name }
+
+        @providers << provider
+        provider
+      end
+
+      def provider(id)
+        @providers.find { |item| item.id == id.to_s }
+      end
+
+      def providers = @providers.dup.freeze
+
+      def register_native(configuration:)
+        raise ArgumentError, "a native provider configuration is required" unless configuration.is_a?(Core::ExternalIdentities::Configuration)
+        raise ArgumentError, "external provider id is already registered" if configurations.any? { |item| item.id == configuration.id }
+        @native_providers[configuration.id] = configuration
+      end
+
+      def native_provider(id) = @native_providers[id]
+      def configurations = (providers.map(&:configuration) + @native_providers.values).freeze
+    end
+
+    attr_accessor :passwords_enabled, :turbo_enabled
+    attr_reader :maintenance, :notifications, :passkeys, :session, :email_link, :step_up, :challenge_when_unavailable, :lifecycle, :external_identities, :mobile
 
     def initialize
       @passwords_enabled = true
+      @current_password_support = Core::Passwords::BcryptSupport.new
+      @turbo_enabled = true
+      @lifecycle = LifecycleOptions.new(enabled: false, password_policy: ->(password) { password.length >= 12 && password.bytesize <= 72 },
+        eligible: ->(_user) { true }, provision: ->(_user) {}, profile_attributes: ->(_profile) { {} }, maximum_attempts: 20, unlock_in: 3600, proof_lifetime: 3600,
+        remember_lifetime: 14 * 86_400, remember_idle_timeout: 7 * 86_400,
+        deletion_allowed: ->(_user) { true }, delete_account: ->(user) { user.destroy! }, confirmation_required: true, reset_unconfirmed: false)
       @session = SessionOptions.new(enabled: false, lifetime: 43_200, idle_timeout: 1800)
+      @mobile = MobileOptions.new(enabled: false, clients: [], callbacks: {}, apple_providers: {})
       @email_link = EmailOptions.new(enabled: false, token_lifetime: 1200, same_browser: false)
+      @external_identities = ExternalIdentityOptions.new
       @notifications = NotificationOptions.new(enabled: false)
       @maintenance = MaintenanceOptions.new(batch_size: 100)
       @passkeys = PasskeyOptions.new(enabled: false, origins: [], name: "Your account", anonymous_limit: 1000)

data/lib/add_auth/core/access_policy.rb

@@ -5,10 +5,11 @@ module AddAuth
     # Account policy survives feature toggles; disabling passkeys cannot restore
     # weaker access to an account that explicitly adopted strict policy.
     class AccessPolicy
-      def initialize(credentials:, passkeys_enabled:, email_enabled:, trusted_recovery_address:, password_enabled: true)
+      def initialize(credentials:, passkeys_enabled:, email_enabled:, trusted_recovery_address:, password_enabled: true, external_enabled: false, external_current: nil)
         @credentials, @passkeys_enabled, @email_enabled = credentials, passkeys_enabled, email_enabled
         @trusted_recovery_address = trusted_recovery_address
         @password_enabled = password_enabled
+        @external_enabled, @external_current = external_enabled == true, external_current
       end
 
       def strict?(user) = user.respond_to?(:add_auth_strict) && user.add_auth_strict == true
@@ -20,6 +21,7 @@ module AddAuth
         when :password then @password_enabled && user.respond_to?(:password_digest) && user.password_digest.is_a?(String) && !user.password_digest.empty?
         when :email_link then @email_enabled
         when :passkey then @passkeys_enabled
+        when :external_identity then @external_enabled
         else false
         end
       end
@@ -41,8 +43,16 @@ module AddAuth
         credential && credential.user_id == user.id && !credential.revoked_at
       end
 
+      def external_credential_current?(user:, id:, version:)
+        @external_enabled && @external_current && @external_current.call(user: user, id: id, version: version) == true
+      end
+
       def session_allowed?(user, row)
         return false if row.respond_to?(:authentication_policy_version) && row.authentication_policy_version != version(user)
+        if row.authenticated_with == "external_identity"
+          return false unless row.respond_to?(:authentication_external_id) &&
+            external_credential_current?(user: user, id: row.authentication_external_id, version: row.authentication_external_version)
+        end
         if row.authenticated_with == "passkey"
           return false unless row.authentication_uv && credential_current?(user: user, id: row.authentication_credential_id)
         end

data/lib/add_auth/core/account_lifecycle.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module AddAuth
+  module Core
+    class AccountLifecycle
+      include Delivery
+
+      PURPOSES = %w[confirm reset_password unlock].freeze
+      TOKEN = /\Aac1:[A-Za-z0-9_-]{43}\z/
+      SECURITY_ATTRIBUTES = %w[id email email_address password password_confirmation password_digest encrypted_password
+        confirmed_at unconfirmed_email locked_at disabled_at deleted_at failed_attempts confirmation_token
+        reset_password_token unlock_token authentication_token].freeze
+      class Conflict < StandardError; end
+      class InvalidPassword < StandardError; end
+      class DeletionRejected < StandardError; end
+      class RegistrationRejected < StandardError; end
+
+      class NewAccount
+        attr_reader :user, :user_id
+        def initialize(user:)
+          @user, @user_id = user, user.id
+          freeze
+        end
+        private_class_method :new
+        def inspect = "#<AddAuth::Core::AccountLifecycle::NewAccount [FILTERED]>"
+      end
+
+      def self.validate_host_write!(changes:, enabled:)
+        if enabled && (changes.keys.map(&:to_s) & %w[email_address unconfirmed_email]).any?
+          raise AddAuth::Error, "change account email through the account lifecycle command"
+        end
+      end
+
+      def initialize(store:, digest:, delivery_cipher:, policy:, password_policy:, trusted_address:, clock: Time, random: SecureRandom,
+        lifetime: 3600, notify: ->(**) {}, sessions: nil, step_up_policy: nil, profile_attributes: ->(_profile) { {} }, deletion_allowed: ->(_user) { true }, external_identities: nil)
+        raise ArgumentError, "proof lifetime must be between 60 and 86400 seconds" unless lifetime.is_a?(Numeric) && lifetime.between?(60, 86_400)
+        @store, @digest, @cipher, @policy, @password_policy, @trusted_address = store, digest, delivery_cipher, policy, password_policy, trusted_address
+        @clock, @random, @lifetime, @notify = clock, random, lifetime, notify
+        @sessions, @step_up_policy = sessions, step_up_policy
+        @profile_attributes = profile_attributes
+        @deletion_allowed = deletion_allowed
+        @external_identities = external_identities
+      end
+
+      def register(identifier:, password:, profile: {}, replacing: nil, user_agent: nil, ip_address: nil, remember: false)
+        return failure unless valid_new_password?(password)
+        register_account(identifier: identifier, password: password, profile: profile,
+          immediate: !@policy.confirmation_required?, replacing: replacing,
+          session_hints: {user_agent: user_agent, ip_address: ip_address, remember: remember})
+      end
+
+      # Generic non-grant result mapping; never authenticate a duplicate result.
+      def registration_next_path
+        @policy.confirmation_required? ? "/account/check-email" : "/sign-in"
+      end
+
+      def registration_instructions
+        @policy.confirmation_required? ? "We’ll email you a link to confirm your address before you sign in." :
+          "Create your account and sign in right away. Your email address stays unverified until you confirm it."
+      end
+
+      def register_external(identifier:, evidence:, profile: {})
+        return failure unless @external_identities
+        external = @external_identities.call
+        register_account(identifier: identifier, password: nil, profile: profile) do |user|
+          external.bind_new_account_in_transaction(registration: NewAccount.send(:new, user: user), evidence: evidence)
+        end
+      rescue ExternalIdentities::EnrollmentRejected
+        failure
+      end
+
+      def issue(identifier:, purpose:, request_id: @random.uuid)
+        return failure unless PURPOSES.include?(purpose.to_s)
+        email = normalize(identifier)
+        return accepted unless email
+        @store.with_user(identifier: email) do |user|
+          next if @store.issued?(request_id: request_id)
+          next unless @policy.allowed?(user, purpose: purpose)
+          recipient = recipient_for(user, purpose.to_s)
+          next unless recipient
+          issue_in_transaction(user: user, purpose: purpose.to_s, recipient: recipient, request_id: request_id)
+        end
+        accepted
+      end
+
+      def preview(token:, purpose:)
+        return failure unless token.is_a?(String) && TOKEN.match?(token) && PURPOSES.include?(purpose.to_s)
+        user, record = @store.inspect_token(digest: @digest.digest(token))
+        reason = rejection(user, record, purpose: purpose.to_s)
+        reason ? Result.failure(reason: reason) : Result.success(user: user, strategy: purpose.to_sym)
+      end
+
+      def consume(token:, purpose:, password: nil)
+        return failure unless token.is_a?(String) && TOKEN.match?(token) && PURPOSES.include?(purpose.to_s)
+        @store.with_token(digest: @digest.digest(token)) do |user, record|
+          reason = rejection(user, record, purpose: purpose.to_s)
+          next Result.failure(reason: reason) if reason
+          now = @clock.now
+          case purpose.to_s
+          when "confirm"
+            pending = user.unconfirmed_email
+            if pending && !pending.empty?
+              old_address = user.email_address
+              @store.promote_address(user: user, digest: address_digest(pending))
+              @store.update_account(user: user, email_address: pending, unconfirmed_email: nil, confirmed_at: now)
+              @store.revoke_authority(user: user, at: now)
+              @notify.call(user: user, kind: :email_changed, at: now, recipient: old_address)
+              @notify.call(user: user, kind: :email_changed, at: now, recipient: pending)
+            else
+              @store.update_account(user: user, confirmed_at: now)
+              provision_account(user)
+            end
+          when "reset_password"
+            next failure unless valid_new_password?(password)
+            @store.replace_password(user: user, password: password)
+            @store.revoke_authority(user: user, at: now)
+            @notify.call(user: user, kind: :password_changed, at: now)
+          when "unlock"
+            @store.update_account(user: user, locked_at: nil, add_auth_locked_until: nil, failed_attempts: 0)
+          end
+          @store.consume(record: record, at: now)
+          Result.success(user: user, strategy: purpose.to_sym)
+        end
+      rescue Conflict, InvalidPassword
+        failure
+      end
+
+      def change_email(user:, session:, identifier:)
+        email = normalize(identifier)
+        return failure unless email
+        with_account_change(user: user, session: session, purpose: :change_email) do |account|
+          next accepted if email == normalize(account.email_address)
+          @store.claim_address(user: account, digest: address_digest(email), address: email, state: "pending")
+          @store.update_account(user: account, unconfirmed_email: email)
+          issue_in_transaction(user: account, purpose: "confirm", recipient: email)
+          accepted
+        end
+      rescue Conflict
+        failure
+      end
+
+      def change_password(user:, session:, password:)
+        return failure unless valid_new_password?(password)
+        with_account_change(user: user, session: session, purpose: :change_password) do |account|
+          @store.replace_password(user: account, password: password)
+          @store.revoke_authority(user: account, at: @clock.now)
+          @notify.call(user: account, kind: :password_changed, at: @clock.now)
+          accepted
+        end
+      rescue InvalidPassword
+        failure
+      end
+
+      def valid_new_password?(password)
+        password.is_a?(String) && password.valid_encoding? && !password.include?("\0") && password.bytesize.between?(1, 1024) && @password_policy.call(password) == true
+      end
+
+      def delete_account(user:, session:)
+        with_account_change(user: user, session: session, purpose: :delete_account) do |account|
+          next failure unless @deletion_allowed.call(account) == true
+          @store.revoke_authority(user: account, at: @clock.now)
+          @store.delete_account(user: account)
+          accepted
+        end
+      rescue DeletionRejected
+        failure
+      end
+
+      # The password lifecycle already owns the account transaction and lock.
+      def issue_unlock_in_transaction(user:)
+        return unless @policy.allowed?(user, purpose: :unlock)
+        recipient = recipient_for(user, "unlock")
+        issue_in_transaction(user: user, purpose: "unlock", recipient: recipient) if recipient
+      end
+
+      private
+
+      def register_account(identifier:, password:, profile:, immediate: false, replacing: nil, session_hints: {})
+        email = normalize(identifier)
+        return failure unless email && profile.is_a?(Hash) && profile.length <= 20
+        attributes = @profile_attributes.call(profile)
+        profile_valid = attributes.is_a?(Hash) && attributes.keys.all? { |name| (name.is_a?(String) || name.is_a?(Symbol)) && !SECURITY_ATTRIBUTES.include?(name.to_s) && !name.to_s.start_with?("add_auth_") }
+        raise AddAuth::Error, "registration profile must contain host profile fields only" unless profile_valid
+        registered = nil
+        outcome = @store.create_account(email: email, password: password, profile: attributes, replacing: replacing) do |user|
+          raise Conflict unless @policy.allowed?(user, purpose: :confirm)
+          yield user if block_given?
+          @store.claim_address(user: user, digest: address_digest(email), address: email, state: "current")
+          if immediate
+            raise AddAuth::Error, "optional confirmation requires sessions and the provisioning migration" unless @sessions && user.respond_to?(:add_auth_provisioned_at)
+            raise RegistrationRejected unless @policy.allowed?(user)
+            password_version = user.password_digest
+            provision_account(user)
+            unless user.email_address == email && user.password_digest == password_version && !user.confirmed_at && user.unconfirmed_email.to_s.empty?
+              raise RegistrationRejected
+            end
+            grant = nil
+            @store.finalize_session(user: user) do |writer|
+              grant = @sessions.create_in_transaction(user: user, method: :password, persist: writer, replacing: replacing, **session_hints)
+              raise RegistrationRejected unless grant
+              grant.session
+            end
+            registered = Result.success(user: user, strategy: :password, session: grant.session, grant: grant)
+          else
+            issue_in_transaction(user: user, purpose: "confirm", recipient: email)
+          end
+        end
+        return failure if outcome == :invalid
+        (outcome == :created && registered) || accepted
+      rescue RegistrationRejected
+        failure
+      end
+
+      def provision_account(user)
+        tracked = user.respond_to?(:add_auth_provisioned_at)
+        return if tracked && user.add_auth_provisioned_at
+        @store.provision(user: user)
+        @store.update_account(user: user, add_auth_provisioned_at: @clock.now) if tracked
+      end
+
+      def with_account_change(user:, session:, purpose:)
+        outcome = Result.failure(reason: :elevation_required)
+        return outcome unless @sessions && @step_up_policy
+        authorization = @sessions.with_elevation(user: user, session: session, purpose: purpose, policy: @step_up_policy) do |account|
+          outcome = @policy.allowed?(account, purpose: :manage) ? yield(account) : failure
+        end
+        authorization.success? ? outcome : authorization
+      end
+
+      def accepted = Result.success(user: nil, strategy: :account_request)
+      def failure = Result.failure(reason: :invalid_credentials)
+
+      def normalize(value)
+        return unless value.is_a?(String) && value.valid_encoding? && value.bytesize.between?(1, 254)
+        value = value.strip.downcase
+        value if value.match?(/\A[^\s@]+@[^\s@]+\z/) && value.bytesize <= 254
+      end
+
+      def address_digest(email) = @digest.digest("account-address:#{normalize(email)}")
+
+      def recipient_for(user, purpose)
+        if purpose == "confirm"
+          normalize(user.unconfirmed_email.to_s.empty? ? user.email_address : user.unconfirmed_email)
+        elsif purpose == "reset_password" && @policy.unconfirmed_reset?(user)
+          normalize(user.email_address)
+        else
+          return unless @policy.trusted_address?(user)
+          address = normalize(@trusted_address.call(user))
+          address if address == normalize(user.email_address)
+        end
+      end
+
+      def version(user, purpose)
+        @digest.digest(JSON.generate([purpose, user.id, user.email_address, user.unconfirmed_email,
+          user.password_digest, user.confirmed_at&.to_f, user.locked_at&.to_f, user.disabled_at&.to_f,
+          user.deleted_at&.to_f, user.add_auth_manual_lock]))
+      end
+
+      def issue_in_transaction(user:, purpose:, recipient:, request_id: @random.uuid)
+        token = "ac1:#{@random.urlsafe_base64(32)}"
+        digest = @digest.digest(token)
+        expires_at = @clock.now + @lifetime
+        payload = @cipher.encrypt(token: JSON.generate(token: token, recipient: recipient, purpose: purpose), digest: digest, expires_at: expires_at)
+        @store.replace_pending(user: user, purpose: purpose, digest: digest, request_id: request_id,
+          address_digest: address_digest(recipient), account_version: version(user, purpose),
+          expires_at: expires_at, delivery_payload: payload, created_at: @clock.now)
+      end
+
+      def rejection(user, record, purpose: record&.purpose)
+        return :invalid_credentials unless user && record && record.purpose == purpose && PURPOSES.include?(purpose)
+        return :consumed_token if record.consumed_at
+        return :revoked_token if record.revoked_at
+        return :expired_token if record.expires_at <= @clock.now
+        return :invalid_credentials unless @policy.allowed?(user, purpose: purpose)
+        recipient = recipient_for(user, purpose)
+        return :invalid_credentials unless recipient && record.address_digest == address_digest(recipient) && record.account_version == version(user, purpose)
+        nil
+      end
+
+      def delivery_details(user, record)
+        raw = @cipher.decrypt(payload: record.delivery_payload, digest: record.digest)
+        return unless raw
+        payload = JSON.parse(raw)
+        return unless payload["purpose"] == record.purpose && payload["recipient"] == recipient_for(user, record.purpose) &&
+          payload["token"].is_a?(String) && @digest.matches?(record.digest, payload["token"])
+        {recipient: payload.fetch("recipient"), token: payload.fetch("token"), purpose: record.purpose}
+      rescue JSON::ParserError, KeyError
+        nil
+      end
+    end
+  end
+end