add_auth 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5856e424011a6e4b49dabd271324aadd29862aad6e0dc5a8b5e06c6e1ea27186
-  data.tar.gz: 5169c854a4428c4daee558abb68208eae29a1f5ae98b91478c9e803ccb3383d4
+  metadata.gz: b83eabd84666412ae2a83ffc20ac54c9765ef0133e0e401cffebce9e3f73f444
+  data.tar.gz: b187c3b70d0c43139f870a50231e5e024f71885218ed68770c98218c257b4be3
 SHA512:
-  metadata.gz: ee5a6a0df85d2719372eba860f0afb1030c3c1ccaf5644fd0ece45395e0f648bd689e0cb8b8b48a04ffa3fb5d066aab5aa8d4925ba502d0db26e8922c48302a9
-  data.tar.gz: 5b9bcc71dd3f72271dd140eb9b335cc93feb6222ec4a95e012afc2eaaa6f96945cd3ff7193e2fbfd816dc4e66bcaea293f9075ae9948931892952a4ba9b25b74
+  metadata.gz: 65eb201de7ebebca70a786c9664a46df8c27404e74dcd2704b25ef33673ab0f42f7a9c5a865c707cb33a943a4a933c8903fc5dafd1479c32bf0ad0266263f7d6
+  data.tar.gz: a48427dfe1145c18be90ddb4ec027b70a7179f7e742d3806ee99ee2ddbf7e9f865abbb0486d96cce600e7e5284ee7487ea7a4b17c71639b94c1801dc95b1b8ee

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.5.0 — 2026-09-18
+
+- Honor Rails' `primary_key_type` generator setting for all AddAuth-owned tables.
+  Support PostgreSQL UUID sessions and mixed integer/UUID account/session keys,
+  retaining bigint defaults and deriving references from the existing schema.
+- Use creation time and a typed ID in opaque session-page cursors; validate
+  revocation and explicitly enabled legacy session adoption for either key type.
+  For apps already using hardened sessions, re-run `add_auth:session_upgrade`
+  for the new pagination index. Existing tables retain their IDs; refresh ejected
+  controllers through the normal review process.
+  Follow the [upgrade guide](https://addauthgem.com/upgrading/#uuid-support) for
+  the release gate, migration review, opaque client cursors and rollback boundary.
+
+## 0.4.0 — 2026-09-13
+
+- Constrain JSON below 3.0 for the supported Rails decoding API; independently
+  installed hosts must be able to decrypt account and email proof deliveries.
+
+- Add explicit optional password-signup confirmation with atomic provisioning and
+  initial session issuance. Unverified email stays unverified; required
+  confirmation remains the default.
+- Add an independent opt-in for single-use password reset proofs to unconfirmed
+  password accounts, retaining account restrictions and authority revocation.
+- Allow password-only lifecycle/step-up generation without enabling email sign-in.
+- Expand the generated Rails initializer with executable defaults and commented
+  alternatives. Feature generators update their own setting in that file.
+
 ## 0.3.0 — 2026-09-09
 
 Optional account lifecycle, bounded Devise migration and native authentication.

data/README.md

@@ -1,6 +1,6 @@
 # AddAuth
 
-**0.3.0:** password, email-link and passkey sign-in extend
+Password, email-link and passkey sign-in extend
 Rails' generated authentication. AddAuth adds hardened sessions, verification
 for sensitive actions, passkey management and email recovery with an optional
 strict policy. Turnstile and reCAPTCHA integrations are available. See
@@ -9,7 +9,7 @@ strict policy. Turnstile and reCAPTCHA integrations are available. See
 AddAuth builds on top of Rails 8's built-in login system instead of
 replacing it -- it keeps using your existing `User` and `Session` models.
 
-Version 0.3.0 adds optional account lifecycle, bounded Devise migration,
+Introduced in 0.3.0: optional account lifecycle, bounded Devise migration,
 provider-library integration and finite Android/iOS sessions. See the
 [migration guide](https://addauthgem.com/migrating-from-devise/) before changing
 an existing Devise app; do not run the Rails generator over its custom files.
@@ -17,24 +17,38 @@ an existing Devise app; do not run the Rails generator over its custom files.
 Read the [documentation](https://addauthgem.com) for setup guides, configuration
 reference and troubleshooting.
 
+## Configuration and optional signup confirmation
+
+Version 0.4.0 adds optional password-signup confirmation and a
+complete, commented [Rails initializer](lib/generators/add_auth/install/templates/initializer.rb).
+Its default assignments are active; opt-in alternatives are commented out.
+Required confirmation remains the default. See the [configuration guide](https://addauthgem.com/configuration/)
+and [account setup](https://addauthgem.com/configuration-preview/), or the
+[contributor rehearsal](CONTRIBUTING.md#optional-confirmation-integration-rehearsal)
+for verification in a disposable host.
+
 ## Quickstart
 
+These commands target 0.5.0 and are available after its
+[RubyGems publication](https://rubygems.org/gems/add_auth/versions/0.5.0).
+Check package availability before changing your app’s bundle.
+
 Install the `add_auth` gem from RubyGems through your Rails app’s Gemfile,
 then enable password and email-link sign-in. Use Ruby 3.3+ and Rails 8.0+
 with Active Record, and run the commands below from your Rails app’s root.
 
-**Release availability:** these commands require the published `0.3.0` package.
+**Release availability:** these commands require the published `0.5.0` package.
 If it is not yet listed on [RubyGems](https://rubygems.org/gems/add_auth/versions),
 wait for publication; see [release status](https://addauthgem.com/release-status/).
 Start in your app’s development environment; use the deployment settings
 below before enabling sign-in for users.
 
 1. Keep `source "https://rubygems.org"` in your app’s Gemfile and add the
-   0.3 release line:
+   0.5 release line:
 
    ```ruby
    # Gemfile
-   gem "add_auth", "~> 0.3.0"
+   gem "add_auth", "~> 0.5.0"
    ```
 
    Bundler downloads the package from RubyGems and records the resolved
@@ -51,10 +65,19 @@ below before enabling sign-in for users.
    bin/rails generate authentication
    ```
 
-3. Add AddAuth:
+3. Create your configuration file:
 
    ```sh
    bin/rails generate add_auth:install
+   ```
+
+   Open `config/initializers/add_auth.rb`. Defaults are active and optional
+   alternatives are commented out. This command enables no features and preserves
+   an existing initializer. Each feature section names its generator.
+
+4. Enable password and email-link sign-in:
+
+   ```sh
    bin/rails generate add_auth:email_link
    bin/rails db:migrate
    ```
@@ -63,7 +86,7 @@ below before enabling sign-in for users.
    in, plus a page where a signed-in user can see their active sessions and
    sign out of one remotely.
 
-4. Set these values in `config/initializers/add_auth.rb`:
+5. Set these values in `config/initializers/add_auth.rb`:
 
    ```ruby
    AddAuth.configure do |config|
@@ -83,7 +106,7 @@ below before enabling sign-in for users.
    config.action_mailer.raise_delivery_errors = true
    ```
 
-5. Create a trial account in `bin/rails console` using your own test address and
+6. Create a trial account in `bin/rails console` using your own test address and
    password, then start `bin/rails server` and visit `/sign-in`. Request a link
    for that account and open the message written under `tmp/mail`. Treat these
    local messages as credentials and delete them after testing. Raw sign-in
@@ -538,13 +561,42 @@ or recovery procedures work in production.
 
 ## Scope
 
-AddAuth 0.3 implements password/email/passkey sign-in, session adoption and
+AddAuth implements password/email/passkey sign-in, session adoption and
 management, purpose-bound verification, passkey recovery and strict account
 policy, durable security mail and challenge adapters. Optional account lifecycle
 adds registration, confirmation/reconfirmation, password reset, lock/unlock and
 account changes. Hosts retain account eligibility, resource authorization and
 provider registrations.
 
+### UUID and integer primary keys in 0.5.0
+
+Version 0.5.0 adds PostgreSQL UUID sessions and configurable primary keys for all
+AddAuth authentication tables. Integer apps retain the normal Rails defaults.
+These instructions become available after the 0.5.0 package is published.
+
+For a new PostgreSQL app, set Rails' generator preference in `config/application.rb`
+before generating authentication or AddAuth features:
+
+```ruby
+config.generators do |g|
+  g.orm :active_record, primary_key_type: :uuid
+end
+```
+
+AddAuth uses this setting for every table it creates. Leave it unset for Rails'
+bigint default, or set `:bigint` or `:integer` explicitly. References follow the
+actual target table, so UUID users can have bigint sessions and vice versa.
+The generated migration records its chosen type; later configuration changes do
+not change that migration or convert existing rows. Other key types are unsupported.
+
+For an existing installation, follow the
+[version-gated package upgrade](https://addauthgem.com/upgrading/#uuid-support).
+It covers the additive pagination index, ejected controller review, opaque
+pagination cursors, verification and rollback from older gems. Integer apps need
+no ID conversion. The [primary-key guide](https://addauthgem.com/uuid-primary-keys/)
+explains mixed schemas and the separate, app-owned migration needed to convert
+existing IDs. The published 0.4.0 package cannot manage UUID sessions.
+
 ## Optional integrations in 0.3.0
 
 Enable bounded [Devise migration](https://addauthgem.com/migrating-from-devise/),

data/ROADMAP.md

@@ -4,16 +4,17 @@ AddAuth extends Rails 8's authentication generator with email-link sign-in,
 passkeys, purpose-bound reauthentication, hardened sessions and pluggable captcha.
 It reuses the host's accounts and Session model.
 
-**Reviewed 2026-09-09: 0.2.2 is published, and the planned v1 strategy features
-have shipped.** The bounded Devise migration and native additions below are locally verified
-and selected for 0.3.0. The future 1.0 support commitment remains separate. Milestones below describe priorities, not promised dates or
-versions. See [release status](https://addauthgem.com/release-status/),
-[the changelog](CHANGELOG.md) and [the manual](https://addauthgem.com/).
+**Reviewed 2026-09-13.** Check [published releases](https://github.com/taimoorq/add_auth/releases) for package availability and provenance. This checklist distinguishes verified implementation from publication.
+It adds the bounded Devise migration, optional account lifecycle, provider-library
+integration and finite native authentication below. Required PR and exact
+release-commit CI/CodeQL, protected OIDC publication, downloaded-package comparison
+and fresh-host installation passed. The matching migration and native guides are
+published in [the manual](https://addauthgem.com/).
 
-**[0.2.2 is published and verified](https://github.com/taimoorq/add_auth/releases/tag/v0.2.2).**
-It contains the counter-store correction and upgrade/operations coverage below.
-The registry package passes fresh-host installation and the matching manual is
-live. The owner selected this patch before accepting the proposed 1.0 commitment.
+The original strategy baseline shipped in 0.2.1; 0.2.2 supplied the counter-store
+correction. The separate 1.0 support commitment remains under review. Milestones
+describe priorities, not promised dates. See [release status](https://addauthgem.com/release-status/)
+and [the changelog](CHANGELOG.md).
 
 An unchecked item is remaining work; deferred candidates need a scope decision
 before implementation. Checked features have passing relevant acceptance specs.
@@ -22,7 +23,19 @@ can describe tested local work; release/publication remains a separate gate. Det
 design and decision records remain in the companion private planning workspace;
 this public checklist is derived from its section 14 and stands on its own.
 
-## Now — maintain 0.2 and learn from adoption
+## Now — maintain AddAuth and learn from adoption
+
+- [x] Honor the Rails UUID/bigint generator setting across all authentication
+  tables, including UUID sessions, mixed references and three-mode bundled/ejected
+  session management. Local PostgreSQL and browser acceptance passes on Rails
+  8.0/8.1. Added in 0.5.0; see
+  [release availability](https://github.com/taimoorq/add_auth/releases).
+
+- [x] Optional password-signup confirmation, immediate transactional provisioning
+  and session issuance, explicit unconfirmed-reset policy, password-only lifecycle
+  and the complete commented Rails initializer. Local supported-matrix, stock/
+  adopted-host, UUID PostgreSQL and three-mode bundled/ejected acceptance passes.
+  Added in the 0.4.0 source; see [release availability and provenance](https://github.com/taimoorq/add_auth/releases).
 
 - [x] **R1 · Resolve the outstanding dependency update.**
       [PR #9](https://github.com/taimoorq/add_auth/pull/9) updates the immutable
@@ -52,7 +65,7 @@ passwordless-fixture isolation failure is fixed in
 [PR #8](https://github.com/taimoorq/add_auth/pull/8); it is not an open runtime
 defect or a reason by itself to republish 0.2.1.
 
-## Next — prove upgrades, plan migrations and define the 1.0 contract
+## Roadmap — migration delivery and the future 1.0 contract
 
 - [x] **R3 · Rehearse an upgrade from published 0.2.1.** Start with a populated
       host, active sessions, passkeys, strict accounts, pending mail and customized
@@ -114,26 +127,25 @@ defect or a reason by itself to republish 0.2.1.
       supported database/runtime, ordinary HTML with JavaScript and Turbo absent,
       Turbo enhancement and permitted no-JS journeys. Draft step-by-step guides
       and prove the destination works with Devise removed.
-- [ ] **R8 · Publish migration and native guides with the feature release.**
-      Verify the released package, installation commands, HTTPS and deep links;
-      keep development guides explicitly unpublished until then.
+- [x] **R8 · Publish migration and native guides with the feature release.**
+      The 0.3.0 package, installation commands, HTTPS and deep links are verified;
+      the six guides now describe the published release.
 
-Local development has verified preflight, optional account lifecycle and
+Version 0.3.0 verifies preflight, optional account lifecycle and
 provider-library integration across the supported Ruby/Rails matrix, including
-ordinary HTML, Turbo and permitted no-JS journeys. These additions are
-unpublished. Migration/checkpoint/compatible-rollback tests and native client
+ordinary HTML, Turbo and permitted no-JS journeys. These additions ship in 0.3.0. Migration/checkpoint/compatible-rollback tests and native client
 acceptance are complete locally. The full adopter suite passes 1,330 examples
 with zero failures and three existing empty scaffold examples pending. Six
-development guides pass build, browser, keyboard and no-JS checks. Publication
-and the proposed 1.0 commitment remain separate gates.
+published guides pass build, browser, keyboard and no-JS checks. The proposed
+1.0 commitment remains a separate gate.
 
-## Locally verified — Android and iOS login
+## Shipped in 0.3.0 — Android and iOS login
 
-Mobile support is now part of the active migration implementation. It is not available in the published gem. These capabilities extend the
+Mobile support ships as an optional integration in 0.3.0. These capabilities extend the
 same account and session policies. The verified finite profile uses explicit
 30-day absolute and 14-day idle limits, with fresh sign-in after expiry. Renewable
-refresh-token families remain a distinct optional capability, currently disabled.
-The owner selected 0.3.0; publication and package verification remain pending.
+refresh-token families remain a distinct optional capability, not implemented in this release.
+The published 0.3.0 package and installed native-consumer contracts are verified.
 
 - [x] **R8 · Password and provider login for native clients.** Return credentials
       over authenticated HTTPS responses; preserve supported client contracts.
@@ -152,15 +164,15 @@ The owner selected 0.3.0; publication and package verification remain pending.
 Each change owns its tests and keeps intermediate releases usable. R3/R4 findings
 feed R5. A patch may address compatible corrections; another 0.x minor is possible
 if integration contracts change. A 0.3 release is not a prerequisite for 1.0.
-R8 follows the published 0.2.2 correction; its supported source profiles
+R8 ships in 0.3.0 after the published 0.2.2 correction; its supported source profiles
 are bounded to the verified Devise 5.0.4 fixtures. The selected delivery version is 0.3.0. Its pre-1.0 integration contracts
-remain subject to review before R5 freezes. Devise migration support is not available yet.
+remain subject to review before R5 freezes. The bounded Devise migration guide is available for 0.3.0.
 
 ## Delivery — 0.3.0 feature release, then the proposed 1.0 gate
 
 - [x] Select 0.3.0 for the locally verified migration, lifecycle, provider and native scope.
-- [ ] Pass required PR and exact default-branch CI/CodeQL for 0.3.0.
-- [ ] Publish 0.3.0 through protected OIDC and verify the downloaded package and manual.
+- [x] Pass required PR and exact default-branch CI/CodeQL for 0.3.0.
+- [x] Publish 0.3.0 through protected OIDC and verify the downloaded package and manual.
 
 - [x] **R6 · Deliver the 0.2.2 correction.**
       [PR #10](https://github.com/taimoorq/add_auth/pull/10) passed all required
@@ -172,7 +184,7 @@ remain subject to review before R5 freezes. Devise migration support is not avai
 - [ ] **R6 · Finish the adoption and compatibility review.** R1–R5 findings are
       completed or explicitly dispositioned, the supported API is accepted, and
       the published-package upgrade and documented operations profile pass.
-- [ ] **R6 · Verify the exact candidate.** Preserve the complete local
+- [ ] **R6 · Verify the exact 1.0 candidate.** Preserve the complete local
       Ruby/Rails, SQLite/PostgreSQL, generated/ejected browser and operations
       acceptance; resolve release-blocking security and upgrade findings.
       Recheck dependency currency and pass required GitHub CI/CodeQL controls.
@@ -213,13 +225,13 @@ compatible extension could ship in 1.x after an explicit scope decision.
       are promoted to R8 above; broader module parity remains outside this scope.
 - [ ] **F4 · Multiple realms.** Require a concrete identity/session-isolation need
       and migration design before adding models, cookies or routing APIs.
-- [ ] **F4 · API/token authentication.** Android/iOS login is the active R8
-      work above; multiple realms and general API-key management remain separate.
+- [ ] **F4 · API/token authentication.** Android/iOS login shipped under R8
+      above; multiple realms and general API-key management remain separate.
 - [ ] **F5 · Standalone test helpers or challenge adapters.** Extract only if
       independent demand and maintenance capacity justify another package;
       retain one implementation per concern.
 
-Optional provider-library integration is locally verified under R8. SMS/TOTP and enterprise
+Optional provider-library integration ships under R8 in 0.3.0. SMS/TOTP and enterprise
 or cross-origin WebAuthn remain outside the current roadmap. Account roles,
 invitations, authorization and email branding
 stay with the host.

data/SECURITY.md

@@ -36,7 +36,9 @@ mailing list, or social media) until a fix has been released.
   scoping, eligibility rechecks and active-delivery-lease protection.
 - Optional account lifecycle and migration boundaries: credential
   profile selection, source-write fencing, address ownership, account proofs,
-  policy and revocation. These capabilities are introduced in 0.3.0.
+  policy and revocation. These capabilities are introduced in 0.3.0; 0.4.0 adds
+  optional confirmation, atomic signup provisioning/session issuance and the
+  independent unconfirmed-password-reset policy.
 - Optional provider identity binding and mobile sessions/handoffs, including
   nonce/client/purpose binding, exact callbacks, single use and bearer/cookie
   separation. Provider protocol cryptography remains library-owned.
@@ -52,6 +54,10 @@ the currency policy).
 
 ## Supported versions
 
+UUID/integer session lookup, account-scoped pagination and revocation are also
+in scope. Version 0.5.0 adds UUID sessions and UUID authentication-table generation;
+primary keys must never substitute for browser/mobile bearer secrets.
+
 Until a 1.0 is released, only the latest published version receives security
 fixes. This table will be expanded once there are stable release lines to
 support.

data/app/controllers/add_auth/accounts_controller.rb

@@ -19,9 +19,17 @@ module AddAuth
     def create
       admitted = intake(:register)
       return intake_failure(admitted) if admitted.is_a?(Symbol)
-      result = Rails::Runtime.accounts.register(identifier: admitted, password: params[:password], profile: registration_profile)
+      accounts = Rails::Runtime.accounts
+      result = accounts.register(identifier: admitted, password: params[:password], profile: registration_profile,
+        replacing: add_auth_replacement_session, **add_auth_session_hints)
       if result.success?
-        redirect_to "/account/check-email", status: :see_other
+        if result.grant
+          destination = after_authentication_url
+          add_auth_accept(result.grant)
+          redirect_to destination, status: :see_other
+        else
+          redirect_to accounts.registration_next_path, status: :see_other
+        end
       else
         @error = "Check your email and choose a password that meets this application's requirements."
         page("register", status: :unprocessable_entity)

data/app/controllers/add_auth/reauthentications_controller.rb

@@ -8,6 +8,7 @@ module AddAuth
     skip_before_action :require_authentication, raise: false
     before_action :private_response
     before_action :enabled_feature
+    before_action :enabled_email_feature, only: %i[request_link check_email link confirm]
     before_action :require_add_auth_authentication, except: %i[link confirm]
     before_action :load_purpose, only: %i[new password request_link check_email]
     protect_from_forgery with: :exception
@@ -54,6 +55,10 @@ module AddAuth
       head :not_found unless Rails::Runtime.config.step_up.enabled
     end
 
+    def enabled_email_feature
+      head :not_found unless Core::Intake.email_available?(Rails::Runtime.config)
+    end
+
     def load_purpose
       @rule = Rails::Runtime.step_up_policy.reauthentication_rule_for(params[:purpose])
       return head :not_found unless @rule

data/app/controllers/add_auth/sessions_controller.rb

@@ -25,7 +25,7 @@ module AddAuth
 
     def destroy
       target_id = params[:id].to_s
-      if target_id.match?(/\A[1-9]\d*\z/) && target_id.to_i == Current.session.id
+      if Rails::Runtime.sessions.current_session?(session: Current.session, session_id: target_id)
         terminate_session
         return redirect_to Rails::Runtime.sign_in_path, status: :see_other
       end

data/app/views/add_auth/accounts/_register.html.erb

@@ -1,6 +1,6 @@
 <% content_for :title, "Create an account" %>
 <h1 id="add_auth-title">Create an account</h1>
-<p class="<%= add_auth_class(:muted) %>">We’ll email you a link to confirm your address before you sign in.</p>
+<p class="<%= add_auth_class(:muted) %>"><%= AddAuth::Rails::Runtime.accounts.registration_instructions %></p>
 <% if @error %><p role="alert" class="<%= add_auth_class(:notice) %>"><%= @error %></p><% end %>
 <%= form_with url: "/account/sign-up", data: add_auth_challenge_form_data(:register) do |form| %>
   <div class="<%= add_auth_class(:field) %>">

data/app/views/add_auth/accounts/_request.html.erb

@@ -2,6 +2,9 @@
 <% content_for :title, title %>
 <h1 id="add_auth-title"><%= title %></h1>
 <p class="<%= add_auth_class(:muted) %>">Enter your account email address to request a secure link.</p>
+<% if @purpose == "reset_password" %>
+  <p>You can also <%= link_to "request email confirmation", "/account/requests/confirm" %> if you haven’t confirmed your address.</p>
+<% end %>
 <% if @error %><p role="alert" class="<%= add_auth_class(:notice) %>"><%= @error %></p><% end %>
 <%= form_with url: "/account/requests/#{@purpose}", data: add_auth_challenge_form_data(:account_request) do |form| %>
   <div class="<%= add_auth_class(:field) %>">

data/lib/add_auth/configuration.rb

@@ -15,7 +15,7 @@ module AddAuth
     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, :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)
+    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
 
@@ -88,7 +88,7 @@ module AddAuth
       @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! })
+        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)

data/lib/add_auth/core/account_lifecycle.rb

@@ -16,6 +16,7 @@ module AddAuth
       class Conflict < StandardError; end
       class InvalidPassword < StandardError; end
       class DeletionRejected < StandardError; end
+      class RegistrationRejected < StandardError; end
 
       class NewAccount
         attr_reader :user, :user_id
@@ -44,9 +45,21 @@ module AddAuth
         @external_identities = external_identities
       end
 
-      def register(identifier:, password:, profile: {})
+      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)
+        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: {})
@@ -98,7 +111,7 @@ module AddAuth
               @notify.call(user: user, kind: :email_changed, at: now, recipient: pending)
             else
               @store.update_account(user: user, confirmed_at: now)
-              @store.provision(user: user)
+              provision_account(user)
             end
           when "reset_password"
             next failure unless valid_new_password?(password)
@@ -165,19 +178,47 @@ module AddAuth
 
       private
 
-      def register_account(identifier:, password:, profile:)
+      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
-        outcome = @store.create_account(email: email, password: password, profile: attributes) do |user|
+        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")
-          issue_in_transaction(user: user, purpose: "confirm", recipient: email)
+          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
-        (outcome == :invalid) ? failure : accepted
+        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:)
@@ -203,7 +244,10 @@ module AddAuth
       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

data/lib/add_auth/core/account_policy.rb

@@ -3,10 +3,24 @@
 module AddAuth
   module Core
     class AccountPolicy
-      def initialize(enabled:, eligible: ->(_user) { true }, clock: Time)
+      def initialize(enabled:, eligible: ->(_user) { true }, clock: Time, confirmation_required: true, reset_unconfirmed: false)
+        unless [confirmation_required, reset_unconfirmed].all? { |value| value == true || value == false }
+          raise ArgumentError, "confirmation_required and reset_unconfirmed must be true or false"
+        end
+        raise ArgumentError, "reset_unconfirmed requires optional confirmation" if confirmation_required && reset_unconfirmed
         @enabled, @eligible, @clock = enabled, eligible, clock
+        @confirmation_required, @reset_unconfirmed = confirmation_required, reset_unconfirmed
+      end
+
+      def confirmation_required? = @confirmation_required
+
+      def unconfirmed_reset?(user)
+        @enabled && @reset_unconfirmed && !value(user, :confirmed_at) &&
+          password_account?(user)
       end
 
+      def trusted_address?(user) = !@enabled || !!value(user, :confirmed_at)
+
       def allowed?(user, purpose: :sign_in)
         return denial(user).nil? if %i[sign_in manage].include?(purpose.to_sym)
         return false unless available?(user)
@@ -17,7 +31,7 @@ module AddAuth
         when :unlock
           locked?(user) && !value(user, :add_auth_manual_lock)
         when :reset_password
-          !!value(user, :confirmed_at) && !value(user, :add_auth_strict)
+          (!!value(user, :confirmed_at) || unconfirmed_reset?(user)) && !value(user, :add_auth_strict)
         else false
         end
       end
@@ -26,7 +40,7 @@ module AddAuth
       def denial(user)
         return :disabled unless available?(user)
         return unless @enabled
-        return :unconfirmed unless value(user, :confirmed_at)
+        return :unconfirmed if !value(user, :confirmed_at) && (confirmation_required? || !password_account?(user))
         :locked if locked?(user)
       end
 
@@ -36,6 +50,10 @@ module AddAuth
 
       private
 
+      def password_account?(user)
+        value(user, :password_digest).is_a?(String) && !user.password_digest.empty?
+      end
+
       def available?(user)
         user && @eligible.call(user) == true &&
           (!user.respond_to?(:add_auth_authority) || user.add_auth_authority == "add_auth") &&

data/lib/add_auth/core/session_cursor.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "time"
+
+module AddAuth
+  module Core
+    class SessionCursor
+      def initialize(key:)
+        @key = key
+      end
+
+      def encode(row)
+        "sc1:" + Base64.urlsafe_encode64(JSON.generate([row.created_at.utc.iso8601(6), row.id]), padding: false)
+      end
+
+      def decode(value)
+        # Retain links issued by releases with integer-only pagination.
+        legacy = @key.parse(value)
+        return {legacy_id: legacy} if legacy.is_a?(Integer)
+        return unless value.is_a?(String) && value.ascii_only? && value.bytesize <= 256 && value.match?(/\Asc1:[A-Za-z0-9_-]+\z/)
+
+        fields = JSON.parse(Base64.urlsafe_decode64(value.delete_prefix("sc1:")))
+        return unless fields.is_a?(Array) && fields.length == 2
+        timestamp, id = fields
+        return unless timestamp.is_a?(String) && timestamp.match?(/\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z\z/)
+        id = @key.parse(id)
+        return unless id
+        time = Time.iso8601(timestamp)
+        return unless time.year.positive? && time.utc.iso8601(6) == timestamp
+        {created_at: time, id: id}
+      rescue ArgumentError, JSON::ParserError
+        nil
+      end
+    end
+  end
+end