standard_id 0.41.0 → 0.41.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cbe67c8d05fe6c7daeeb4d4a44562507e1d5104c32eeba94b701e98e6afe3ea
-  data.tar.gz: 8f9cb74cf37bb063c66547c7f563005f870a5a86509fe8f89b0bb57893f0ed82
+  metadata.gz: eda13bb222bf26a20444378b4fe6d0e7661f86a0058388986fb2710e5f01802d
+  data.tar.gz: 96835ff10cd72cc01c8654ddf86d5cb44555079eafad8f521b8c62061a63dde9
 SHA512:
-  metadata.gz: e8110399efd07b7b0455f2b8a5ee2c93acfb7dd9bb3847c1a7b43a78aec874b1709aebc05d7be37877007b81f19946322496745793da0418757ecd3de0349121
-  data.tar.gz: '08736fdbf31a259270c02c232f3a8e163c1dc80ca7f5fd3a4dba2168adb812aa91307bf662b7766bc0078b532bf549be64998342cf90f4e5c54048d31f2becd8'
+  metadata.gz: 68698115969ba88727515927a9afaf0d1f14245b215abed59220afbbacb0533667715688fa395df46013c32c384d854e44cc58bb760e83c7f2c1dcac6063bed0
+  data.tar.gz: 48918bda97f0345b8b462dde9fbf4c77b6bff7851764fbee998f8af6d779caa8efc6f7e8f68f0971c33c1d8110af8effe69c172a82ad96c068d41b8a38495538

data/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.41.1] - 2026-09-24
+
+Bug-fix release. Four of these were found in sidekick-web, which has been carrying host-side prepend patches for three of them; the dummy app now runs with `strict_loading_by_default` so this class of bug fails in the gem's own suite first.
+
+### Upgrade
+
+Read this before bumping — the order matters if you have not yet deployed 0.41.0's migration:
+
+1. **Deploy 0.41.1 first, WITHOUT running `20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications`.** 0.41.1 ignores the column (see Fixed), so running processes stop reading and writing it.
+2. **Run `20260915000000` in a later deploy.** With strong_migrations it still needs wrapping: `safety_assured { remove_column ... }` inside the copied migration's `up` — the column is already ignored, which is the condition strong_migrations asks you to confirm. Hosts that already ran it under 0.41.0 have nothing to do here.
+3. **Install and run the new `20260924000000_add_unique_active_device_index_to_standard_id_sessions`** (`bin/rails standard_id:install:migrations`). It is idempotent, builds CONCURRENTLY on Postgres, and needs no `safety_assured` in the host: the one raw-SQL step (detaching duplicate rows) asserts itself safe to StrongMigrations when that gem is loaded. It detaches any existing duplicate active device rows before building the index (see Fixed); nothing is revoked.
+4. **Hosts carrying the sidekick-web prepend patches can delete them:** `config/initializers/standard_id_refresh_token_strict_loading.rb`, `standard_id_rotation_leeway.rb` and `standard_id_device_session_upsert.rb` (and their specs). The upsert patch's signature guard will keep passing, so it will not remind you — remove it deliberately.
+
+### Fixed
+
+- **Signing in again after signing out no longer resurrects the revoked device session.** `OauthSessionPersistence.upsert_device_session!` looked the device's row up with a bare `find_by(account:, device_id:)`. Sign-out (`/oauth/revoke` under the default `:account` `revocation_scope`) revokes every active `DeviceSession`, so the next sign-in reused the revoked row, every refresh token minted afterwards pointed at a revoked parent, and `RefreshTokenFlow#validate_parent_session!` refused the very first refresh. The client was sent back to sign-in each time its access token expired, on every device, forever — sidekick-web's companion app, where the audit trail showed dozens of sign-ins a day and not one successful refresh.
+
+  Only rows with `revoked_at: nil` are now reused (newest first); a revoked row stays as history and the sign-in gets a new one. Expiry is deliberately still not part of eligibility — an expired-but-unrevoked row is reused with its `expires_at` bumped, as before. The insert runs inside a savepoint, and on `ActiveRecord::RecordNotUnique` the row that won a concurrent first sign-in is reused rather than failing the token request.
+
+  **New migration `20260924000000`**: a partial unique index on `standard_id_sessions (account_id, device_id) WHERE revoked_at IS NULL AND device_id IS NOT NULL`, so "one active session per device" is a database invariant rather than a property of the account row lock. Before building it, each duplicated group of active rows keeps its newest row as-is and has `:detached:<id>` appended to the others' `device_id`. Detached rows stay active — their refresh tokens keep working until they expire or are revoked — they are just no longer the row a new sign-in reuses. `down` drops the index and leaves the detached suffixes in place (strip `:detached:<id>` to recover the original).
+
+- **The refresh-token reuse leeway no longer 500s under strict loading.** When `refresh_token_reuse_leeway` graces a replayed token, `graced_successor_for` loaded the successor without its `:session`, and `validate_parent_session!` then read it lazily — `StrictLoadingViolationError` on exactly the retry the leeway exists to rescue (sidekick-web SIDEKICK-WEB-3E). The successor is now `eager_load(:session)`ed like the primary lookup. The existing grace specs used session-less tokens, where a nil foreign key never queries; the new ones link the family to a `DeviceSession`.
+
+- **Two graced retries racing to rotate the same successor no longer log the client out.** Two retries of one lost response can both pass `graced_successor_for` while the successor is untouched, then race to rotate it. The loser landed in `handle_concurrent_reuse!` and revoked the family, killing the token the winner had just issued. A request served from a graced successor that loses the rotation race now gets `invalid_grant` **without** revoking anything; the client keeps the winner's response. A request presenting its token directly and losing the race still revokes the family, and a later replay of the superseded token still finds a used successor and revokes as before — the leeway is not widened.
+
+- **A lifecycle hook rejecting a brand-new account no longer 500s under strict loading.** `LifecycleHooks#destroy_newly_created_account` read `account.sessions` / `account.identifiers` lazily, so a `before_sign_in` / `after_sign_in` rejection of a just-created signup raised `StrictLoadingViolationError` instead of redirecting to login, and left the orphaned account behind. The cleanup now reads each association through `.strict_loading(false)`.
+
+- **`StandardId::ClientApplication` ignores the dropped `refresh_token_lifetime` column.** 0.41.0 removed the column without ignoring it first, so on a rolling deploy processes still on the old code named it in every INSERT/UPDATE once the migration ran. `self.ignored_columns += %w[refresh_token_lifetime]` makes the deploy-then-drop order in **Upgrade** safe. It will be removed in a future minor.
+
+- **The documented per-challenge OTP attempt ceiling was wrong.** `passwordless.max_attempts_per_challenge` is unset by default and falls back to `max_attempts` (default `3`), so an untouched install burns a challenge after 3 wrong codes — but the install generator template, the schema comment and the 0.16.0 entry below all said `5`. They now say `3`, and a spec pins the template's value to the runtime default. The literal `5` in the resolver is a real last resort (both settings nil or zero, since a zero ceiling would burn every challenge on its first wrong code) and is now named `StandardId::Passwordless::FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE`. No behaviour change.
+
+### Changed
+
+- **The dummy app runs with `strict_loading_by_default = true`** and `:raise`, as every consumer does. `spec/dummy/config/initializers/strict_loading.rb` exempts the gem models hosts exempt (`Identifier`, `Session`, `Credential`, `PasswordCredential`, `ClientSecretCredential`, `AuthorizationCode`); `RefreshToken`, `ClientApplication`, `ClientGrant`, `CodeChallenge` and `Account` stay strict. `STRICT_LOADING=full bundle exec rspec` drops the exemptions to show the remaining backlog. Test-suite only; no runtime change.
+
 ## [0.41.0] - 2026-09-15
 
 ### Added
@@ -1137,7 +1172,7 @@ An explicit per-grant `profile_id` parameter is intentionally out of scope for t
 
 ### Security
 
-- **OTP verification race-condition fix and per-challenge brute-force defenses** — `VerificationService.verify` now wraps the challenge lookup, failed-attempt increment, and consumption in a single `SELECT ... FOR UPDATE` transaction, closing the TOCTOU window between "find active challenge" and "mark it used." Failed-attempt counting is now atomic and scoped to the specific challenge (previously a loose read-modify-write on the account). Events are deferred to post-commit so observers never see rolled-back state. New `config.passwordless.max_attempts_per_challenge` (default `5`) supersedes the now-deprecated account-wide `max_attempts` (kept as a fallback for existing installs). (#169)
+- **OTP verification race-condition fix and per-challenge brute-force defenses** — `VerificationService.verify` now wraps the challenge lookup, failed-attempt increment, and consumption in a single `SELECT ... FOR UPDATE` transaction, closing the TOCTOU window between "find active challenge" and "mark it used." Failed-attempt counting is now atomic and scoped to the specific challenge (previously a loose read-modify-write on the account). Events are deferred to post-commit so observers never see rolled-back state. New `config.passwordless.max_attempts_per_challenge` (unset by default, so the effective ceiling is `max_attempts`' default of `3`; `5` is only a last-resort fallback when both are unset or zero) supersedes the now-deprecated account-wide `max_attempts` (kept as a fallback for existing installs). (#169)
 - **JWT audience enforcement at decode time** — `JwtService.decode` now accepts an `allowed_audiences:` kwarg and raises `StandardId::InvalidAudienceError` on mismatch. `Api::TokenManager#verify_jwt_token` threads `config.oauth.allowed_audiences` through automatically, so cross-audience JWT replay is now blocked even on controllers that forget to include the `AudienceVerification` concern. Production emits a warning when `allowed_audiences` is unset. (#170, #174)
 - **Web flow polish** — password-reset delivery moved to an async job with a constant-time success response (closes enumeration timing leak); OAuth `redirect_uri` validation tightened to exact scheme+host+port+path match at both registration and authorize time (blocks query-string piggyback); engine logs a warning when the host app has no `secret_key_base` configured so encrypted session cookies can't silently fall back to plaintext. New `reset_password` config scope with `:delivery` (`:custom` default, `:built_in` opt-in) and mailer-sender/subject knobs. `CREDENTIAL_PASSWORD_RESET_INITIATED` event now fires from the job. (#171)
 - **Per-client PKCE enforcement at the authorize endpoint** — honors the existing `require_pkce` column on `ClientApplication`. Requests missing `code_challenge` are rejected with `invalid_request` when the client requires PKCE. Per-client `code_challenge_methods` replaces the global S256-only hardcode (case-insensitive). New validation blocks public clients from opting out (`public_clients_must_require_pkce`). (#175)

data/app/controllers/concerns/standard_id/lifecycle_hooks.rb

@@ -208,13 +208,22 @@ module StandardId
 
     # Destroy a newly created account and all its dependents.
     # Used when after_sign_in rejects a just-created account to avoid orphans.
+    #
+    # Every association read goes through `.strict_loading(false)`: the account
+    # was built in this request, so none of its associations are loaded, and a
+    # host running `strict_loading_by_default = true` (most consumers) would
+    # otherwise raise StrictLoadingViolationError on `account.sessions` — turning
+    # a hook's clean rejection of a new signup into a 500 and leaving the
+    # orphaned account behind. Relation-level `strict_loading(false)` also covers
+    # the records it loads, so `identifier.credentials` below is safe too.
     def destroy_newly_created_account(account)
       return unless account&.persisted?
 
       ActiveRecord::Base.transaction do
-        account.sessions.destroy_all
-        account.identifiers.each { |i| i.credentials.destroy_all }
-        account.identifiers.destroy_all
+        account.sessions.strict_loading(false).destroy_all
+        identifiers = account.identifiers.strict_loading(false).to_a
+        identifiers.each { |i| i.credentials.strict_loading(false).destroy_all }
+        identifiers.each(&:destroy!)
         account.destroy
       end
     end

data/app/models/standard_id/client_application.rb

@@ -1,6 +1,17 @@
 module StandardId
   class ClientApplication < ApplicationRecord
     self.table_name = "standard_id_client_applications"
+
+    # 0.41.0 dropped `refresh_token_lifetime` (migration 20260915000000) without
+    # ignoring it first, so a rolling deploy broke: processes still running the
+    # old code had the column in their cached schema and wrote it on every
+    # INSERT/UPDATE once the migration had removed it. Ignoring it here lets
+    # hosts ship this release first and drop the column in a LATER deploy —
+    # the order strong_migrations requires for remove_column.
+    #
+    # Remove this line in a future minor, once every host has run 20260915000000.
+    self.ignored_columns += %w[refresh_token_lifetime]
+
     belongs_to :owner, polymorphic: true
 
     has_many :client_secret_credentials, dependent: :destroy

data/db/migrate/20260924000000_add_unique_active_device_index_to_standard_id_sessions.rb

@@ -0,0 +1,115 @@
+class AddUniqueActiveDeviceIndexToStandardIdSessions < ActiveRecord::Migration[8.0]
+  # One ACTIVE DeviceSession per (account, device).
+  #
+  # `OauthSessionPersistence.upsert_device_session!` keys OAuth-issued device
+  # sessions on a stable device_id and reuses the active row for repeat
+  # sign-ins. Until now nothing in the schema backed that: the upsert
+  # serialised on a row lock, a race or an older gem could still leave two
+  # active rows for one device, and the lookup then picked one arbitrarily.
+  # This partial unique index makes "one active row per device" a database
+  # invariant; the upsert inserts inside a savepoint and, on
+  # RecordNotUnique, reuses the row that won.
+  #
+  # Partial on purpose:
+  #   - `revoked_at IS NULL` — revoked rows are history (audit trail, admin
+  #     session list) and a device legitimately accumulates one per sign-out.
+  #   - `device_id IS NOT NULL` — BrowserSession / ServiceSession rows share
+  #     the table and carry no device_id.
+  #
+  # Existing duplicates are resolved BEFORE the index is built, without
+  # revoking anything: in each duplicated (account_id, device_id) group the
+  # newest active row keeps its device_id and every other row has
+  # ":detached:<id>" appended to its own. Detached rows stay active — their
+  # refresh tokens keep working until they expire or are revoked — they are
+  # simply no longer the row a new sign-in on that device reuses. Not undone
+  # by `down`: the original device_id is recoverable by stripping the suffix.
+  #
+  # Idempotent (if_not_exists / if_exists), CONCURRENTLY on Postgres, same
+  # conventions as 20260416180511. StrongMigrations treats a concurrent
+  # add_index as safe, but it cannot inspect the raw-SQL detach UPDATE and
+  # stops the migration there whenever a host actually has duplicates — so
+  # that data fix is asserted safe (see #assert_safe) when the gem is loaded.
+  disable_ddl_transaction!
+
+  INDEX_NAME = "index_standard_id_sessions_on_active_account_device".freeze
+  WHERE = "revoked_at IS NULL AND device_id IS NOT NULL".freeze
+  DETACHED_MARKER = ":detached:".freeze
+
+  def up
+    pg = connection.adapter_name.downcase.include?("postgres")
+    concurrent = pg ? { algorithm: :concurrently } : {}
+
+    # A CONCURRENTLY build that failed (e.g. a duplicate inserted mid-build)
+    # leaves an INVALID index behind, which if_not_exists would then skip.
+    # Drop it so a re-run actually rebuilds.
+    if pg && invalid_postgres_index?(INDEX_NAME)
+      remove_index :standard_id_sessions, name: INDEX_NAME, if_exists: true, **concurrent
+    end
+
+    detach_duplicate_active_device_sessions!
+
+    add_index :standard_id_sessions,
+      [:account_id, :device_id],
+      unique: true,
+      where: WHERE,
+      name: INDEX_NAME,
+      if_not_exists: true,
+      **concurrent
+  end
+
+  def down
+    pg = connection.adapter_name.downcase.include?("postgres")
+    concurrent = pg ? { algorithm: :concurrently } : {}
+
+    remove_index :standard_id_sessions, name: INDEX_NAME, if_exists: true, **concurrent
+  end
+
+  private
+
+  def detach_duplicate_active_device_sessions!
+    rows = select_all(<<~SQL.squish).to_a
+      SELECT s.id, s.account_id, s.device_id
+      FROM standard_id_sessions s
+      INNER JOIN (
+        SELECT account_id, device_id
+        FROM standard_id_sessions
+        WHERE #{WHERE}
+        GROUP BY account_id, device_id
+        HAVING COUNT(*) > 1
+      ) dup ON dup.account_id = s.account_id AND dup.device_id = s.device_id
+      WHERE s.revoked_at IS NULL AND s.device_id IS NOT NULL
+      ORDER BY s.account_id, s.device_id, s.created_at DESC, s.id DESC
+    SQL
+
+    rows.group_by { |row| [row["account_id"], row["device_id"]] }.each_value do |group|
+      # group.first is the newest active row: it keeps the device_id.
+      group.drop(1).each do |row|
+        detached = "#{row["device_id"]}#{DETACHED_MARKER}#{row["id"]}"
+        assert_safe do
+          execute(<<~SQL.squish)
+            UPDATE standard_id_sessions
+            SET device_id = #{connection.quote(detached)}
+            WHERE id = #{connection.quote(row["id"])}
+          SQL
+        end
+      end
+    end
+  end
+
+  # A single-row UPDATE by primary key, run only for duplicated device rows:
+  # a deliberate, bounded data fix. Every known host runs StrongMigrations,
+  # which cannot inspect raw SQL; assert safety when it is loaded, and run the
+  # block as-is when it is not (the gem does not depend on it).
+  def assert_safe(&block)
+    respond_to?(:safety_assured) ? safety_assured(&block) : yield
+  end
+
+  def invalid_postgres_index?(name)
+    select_value(<<~SQL.squish).present?
+      SELECT 1
+      FROM pg_index i
+      INNER JOIN pg_class c ON c.oid = i.indexrelid
+      WHERE c.relname = #{connection.quote(name)} AND NOT i.indisvalid
+    SQL
+  end
+end

data/lib/generators/standard_id/install/templates/standard_id.rb

@@ -225,8 +225,9 @@ StandardId.configure do |c|
   # challenge is burned so further submissions fail fast. Distinct from the
   # per-IP rate limit (c.rate_limits.otp_verify_per_ip) — this defends
   # against distributed brute-force against a single challenge.
-  # Default: nil — falls back to :max_attempts for backwards compatibility.
-  # c.passwordless.max_attempts_per_challenge = 5
+  # Default: nil — falls back to :max_attempts (default 3) for backwards
+  # compatibility, so the effective default ceiling is 3.
+  # c.passwordless.max_attempts_per_challenge = 3
 
   # Default: 3 — deprecated alias for :max_attempts_per_challenge. Retained
   # for backwards compatibility; new installs should set the newer key.

data/lib/standard_id/config/schema.rb

@@ -162,7 +162,10 @@ StandardId::ConfigSchema.define do
     # rate limit (config.rate_limits.otp_verify_per_ip) — the per-IP limit
     # prevents brute-forcing from a single source, while this ceiling defends
     # against distributed brute-force attempts against the same challenge.
-    # When nil, falls back to :max_attempts for backwards compatibility.
+    # When nil, falls back to :max_attempts for backwards compatibility, so the
+    # effective default is 3 (:max_attempts' default), not 5. 5 is only the
+    # last resort when both are unset or non-positive
+    # (StandardId::Passwordless::FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE).
     field :max_attempts_per_challenge, type: :integer, default: nil
 
     field :retry_delay, type: :integer, default: 30 # 30 seconds

data/lib/standard_id/oauth/oauth_session_persistence.rb

@@ -37,41 +37,83 @@ module StandardId
         end
       end
 
+      # Reuse the device's ACTIVE session row, or start a new one.
+      #
+      # Only a non-revoked row is eligible. Sign-out (/oauth/revoke under the
+      # default :account revocation_scope) revokes every active DeviceSession
+      # for the account; reusing that revoked row on the next sign-in — which a
+      # bare `find_by(account:, device_id:)` did — linked every new refresh
+      # token to a revoked parent, so RefreshTokenFlow#validate_parent_session!
+      # refused the very first refresh and the client was bounced to sign-in
+      # after every access-token expiry, forever. A revoked row is history (the
+      # audit trail and admin session lists still read it); a new sign-in gets
+      # a new row. Expiry is deliberately NOT part of eligibility: an expired
+      # but unrevoked row is reused with its expires_at bumped, as before.
       def upsert_device_session!(account:, request:, audience:, grant_type:)
         user_agent = request.user_agent
         device_id = stable_device_id(account: account, user_agent: user_agent, audience: audience)
         ip_address = StandardId::Utils::IpNormalizer.normalize(request.remote_ip)
 
-        # Serialize concurrent upserts for the same account. There's no
-        # DB-level unique constraint on (account_id, device_id), so a raw
-        # find_by + create! would TOCTOU-race two concurrent token requests
-        # for the same device into two duplicate rows. We acquire a SELECT
-        # ... FOR UPDATE on the account row to serialize — account.with_lock
-        # is unavailable because StandardId::AccountLocking overrides lock!
-        # with a business-level method that takes a :reason kwarg.
-        # The outer transaction (opened by TokenGrantFlow#generate_token_response)
+        # Serialize concurrent upserts for the same account. We acquire a
+        # SELECT ... FOR UPDATE on the account row — account.with_lock is
+        # unavailable because StandardId::AccountLocking overrides lock! with a
+        # business-level method that takes a :reason kwarg. The outer
+        # transaction (opened by TokenGrantFlow#generate_token_response)
         # releases the lock on commit/rollback.
+        #
+        # The lock alone is not the guarantee: the partial unique index from
+        # 20260924000000 (one active row per account + device_id) is. The lock
+        # keeps the common case free of unique violations; the savepoint below
+        # handles the rest, and keeps hosts that have not yet run that
+        # migration no worse off than before.
         account.class.where(id: account.id).lock.first
 
-        existing = StandardId::DeviceSession.find_by(account: account, device_id: device_id)
-        if existing
-          existing.update!(
-            expires_at: StandardId::DeviceSession.expiry,
-            ip_address: ip_address || existing.ip_address,
-            device_agent: user_agent || existing.device_agent
-          )
-          existing
-        else
-          StandardId::DeviceSession.create!(
-            account: account,
-            device_id: device_id,
-            device_agent: user_agent.presence || "OAuth:#{grant_type}",
-            ip_address: ip_address || "0.0.0.0",
-            expires_at: StandardId::DeviceSession.expiry
-          )
+        existing = active_device_session(account: account, device_id: device_id)
+        return refresh_device_session!(existing, ip_address: ip_address, user_agent: user_agent) if existing
+
+        begin
+          # Savepoint, so a unique violation does not abort the enclosing token
+          # transaction (Postgres refuses every later statement in an aborted
+          # transaction).
+          StandardId::DeviceSession.transaction(requires_new: true) do
+            StandardId::DeviceSession.create!(
+              account: account,
+              device_id: device_id,
+              device_agent: user_agent.presence || "OAuth:#{grant_type}",
+              ip_address: ip_address || "0.0.0.0",
+              expires_at: StandardId::DeviceSession.expiry
+            )
+          end
+        rescue ActiveRecord::RecordNotUnique
+          # A concurrent sign-in for the same device committed its row first.
+          # Reuse the winner rather than failing the token request.
+          winner = active_device_session(account: account, device_id: device_id)
+          raise unless winner
+
+          refresh_device_session!(winner, ip_address: ip_address, user_agent: user_agent)
         end
       end
 
+      # Newest first: before the unique index existed, a race could leave two
+      # active rows for one device, and an unordered lookup picked one
+      # arbitrarily. The migration detaches such duplicates, but hosts that
+      # have not run it yet still benefit from a deterministic choice.
+      def active_device_session(account:, device_id:)
+        StandardId::DeviceSession
+          .where(account: account, device_id: device_id, revoked_at: nil)
+          .order(created_at: :desc, id: :desc)
+          .first
+      end
+
+      def refresh_device_session!(session, ip_address:, user_agent:)
+        session.update!(
+          expires_at: StandardId::DeviceSession.expiry,
+          ip_address: ip_address || session.ip_address,
+          device_agent: user_agent || session.device_agent
+        )
+        session
+      end
+
       def stable_device_id(account:, user_agent:, audience:)
         audience_key = Array(audience).join(",")
         Digest::SHA256.hexdigest("oauth:#{audience_key}:#{account.id}:#{user_agent}")[0, 36]

data/lib/standard_id/oauth/refresh_token_flow.rb

@@ -81,6 +81,7 @@ module StandardId
           if (successor = graced_successor_for(@current_refresh_token_record))
             emit_reuse_graced_event(@current_refresh_token_record, successor)
             @current_refresh_token_record = successor
+            @served_from_graced_successor = true
           else
             # Reuse detected: this token was already rotated. Revoke entire family.
             @current_refresh_token_record.revoke_family!
@@ -166,9 +167,24 @@ module StandardId
         raise ActiveRecord::Rollback
       end
 
+      # Only a request that presented the lost-the-race token ITSELF is treated
+      # as reuse. A request served from a graced successor that loses the race
+      # is the leeway's own retry colliding with another retry of the same lost
+      # response — a client re-sending the superseded token twice in quick
+      # succession. Both passed #graced_successor_for while the successor was
+      # untouched; one rotated it. Revoking the family here would kill the
+      # token the winning request just issued and log the honest client out,
+      # which is exactly what the leeway exists to prevent. The loser gets a
+      # plain invalid_grant and the client keeps the winner's response.
+      #
+      # This does not widen the leeway: the winner already consumed the
+      # successor, so a later replay of the superseded token finds a USED
+      # successor and revokes the family as before.
       def handle_concurrent_reuse!
         @current_refresh_token_record&.reload
         if @current_refresh_token_record&.revoked?
+          raise StandardId::InvalidGrantError, "Refresh token is no longer valid" if @served_from_graced_successor
+
           @current_refresh_token_record.revoke_family!
           emit_reuse_detected_event
           raise StandardId::InvalidGrantError, "Refresh token reuse detected"
@@ -208,7 +224,12 @@ module StandardId
         return nil if revoked_record.revoked_at.blank?
         return nil if revoked_record.revoked_at < leeway.seconds.ago
 
-        successor = StandardId::RefreshToken.find_by(previous_token_id: revoked_record.id)
+        # eager_load(:session), matching the primary lookup in
+        # #validate_refresh_token_record!: the successor becomes
+        # @current_refresh_token_record, and #validate_parent_session! reads its
+        # :session. A bare find_by left that a lazy read, which raises
+        # StrictLoadingViolationError (a 500) under strict loading.
+        successor = StandardId::RefreshToken.eager_load(:session).find_by(previous_token_id: revoked_record.id)
         return nil unless successor&.active?
         return nil if StandardId::RefreshToken.exists?(previous_token_id: successor.id)
 

data/lib/standard_id/passwordless.rb

@@ -2,6 +2,12 @@ require "standard_id/passwordless/verification_service"
 
 module StandardId
   module Passwordless
+    # Last-resort per-challenge attempt ceiling, used only when neither
+    # :max_attempts_per_challenge nor :max_attempts is a positive number. NOT
+    # the default: with default config the ceiling is 3 (see
+    # .max_attempts_per_challenge).
+    FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE = 5
+
     class << self
       # Public API for verifying a passwordless OTP code.
       #
@@ -76,12 +82,18 @@ module StandardId
       # Resolve the per-challenge attempt ceiling, preferring the newer
       # :max_attempts_per_challenge setting but falling back to :max_attempts
       # for backwards compatibility with apps that configured the older name.
+      #
+      # With default config this resolves to 3 (:max_attempts' default).
+      # FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE applies only when BOTH settings are
+      # unset or non-positive (e.g. `max_attempts = 0` / nil) — a ceiling of
+      # zero would burn every challenge on its first wrong code, so it is never
+      # honoured.
       def max_attempts_per_challenge
         configured = StandardId.config.passwordless.max_attempts_per_challenge
         return configured.to_i if configured && configured.to_i.positive?
 
         legacy = StandardId.config.passwordless.max_attempts.to_i
-        legacy.positive? ? legacy : 5
+        legacy.positive? ? legacy : FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE
       end
 
       # Minimum seconds that must elapse between successive code requests for

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.41.0"
+  VERSION = "0.41.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.41.0
+  version: 0.41.1
 platform: ruby
 authors:
 - Jaryl Sim
@@ -231,6 +231,7 @@ files:
 - db/migrate/20260416180511_add_partial_indexes_for_active_session_and_challenge_lookups.rb
 - db/migrate/20260611000000_create_standard_id_client_grants.rb
 - db/migrate/20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications.rb
+- db/migrate/20260924000000_add_unique_active_device_index_to_standard_id_sessions.rb
 - lib/generators/standard_id/install/install_generator.rb
 - lib/generators/standard_id/install/templates/standard_id.rb
 - lib/standard_id.rb