standard_id 0.38.0 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea8084bb866fc4da82d81ec18d2b24676e3209ac8d21975c20deb9aa334160fc
-  data.tar.gz: 1cc922486ca4204c8308ff489dc5f425424c06e758a1a4b77276b6670a637f10
+  metadata.gz: aafcc86281b43717bf4afeae67e469f9f773f62bb674137adce6b7924eb24be2
+  data.tar.gz: 1236e399e761f545b7c2c749d44bd317f48355650b1f76accbf22704940f00d5
 SHA512:
-  metadata.gz: 3e030d75f3f08d7961ac1cab6ede04da0940ee5471191bfc5c06ef832469f6da2a9af44539fa04e889801defded08c8bdf138c7a8bd1661d8c0628c5b707d08f
-  data.tar.gz: b5301f0db610433bcb542699f95beddcd9e91e93dda098f940edafc9af5c70ab264ef6c70b427e84ac34a9edae861316cf3d608f4f5c2dad6996eb6b9780cbcf
+  metadata.gz: 0cbb9b1a8fd120918f0dbf986822b70990105c6e288ede4b8f2fc790b82cfa2f5ded7cbc774ae4e18afc6e03b29f40e93ffc736d8fd7021ce2ae81f10b03a59c
+  data.tar.gz: dcbdbea82b00733fb9de47a2ba1b4f44362f819ee27ccac2bbb3b1c10573a225afac8d98c50644648ca9756d5a15ecc4262448ff899632f109e8510f2edf5fcd

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.39.0] - 2026-08-10
+
+### Added
+
+- **A refresh whose RESPONSE never arrived no longer costs the user their session.** Rotation assumes the client receives the new token. When it does not — a timeout, a dead radio, the process dying between our `COMMIT` and the client's write — the server has rotated and the client still holds the previous token. Its next refresh presents an already-rotated token, which is indistinguishable from an attacker replaying a stolen one.
+
+  Treating both as an attack costs a healthy session, and the cost is total: `revoke_family!` also kills the **successor the client never received**, so the session cannot be recovered by retrying — every attempt re-presents the same dead token against an already-revoked family. `spec/lib/standard_id/refresh_rotation_lost_response_spec.rb` pins that behaviour before the fix, because it is the part that surprises.
+
+  `config.oauth.refresh_token_reuse_leeway` (default **`0` — off**) allows a replayed token to rotate from its successor instead, but ONLY while that successor is untouched: it must still be active and never itself have been rotated. A **used** successor proves the legitimate client received it, so anything presented afterwards is a genuine replay and the family dies exactly as before. The value is clamped to `RefreshTokenFlow::MAX_REUSE_LEEWAY_SECONDS` (120).
+
+- **`OAUTH_REFRESH_TOKEN_REUSE_GRACED`** is published when the leeway fires. Graced replays are the quiet half of the feature: without an event, the only evidence the leeway is load-bearing is an absence of complaints.
+
+### Notes for hosts
+
+- **Default-off means this release is inert on upgrade for every consumer.** Existing reuse-detection specs pass unchanged. A host opts in explicitly.
+
+- **Enabling it is a deliberate security narrowing, and worth understanding before you do.** It does not claim to distinguish an attacker from an unlucky client — the server cannot. It bounds the damage. An attacker replaying inside the window gets a session, but the real client still holds the successor, and the moment it refreshes, that token is revoked-and-reused: the family dies and the user re-authenticates. Exposure is one refresh interval, against the current guarantee that the *honest* client loses its session.
+
+- **Re-delivering the successor — the ideal, idempotent answer — is not possible here.** Only its digest is stored, by design, so the token string is unrecoverable. Rotating from it is the closest safe equivalent; the unused successor is retired rather than left live.
+
 ## [0.38.0] - 2026-08-06
 
 ### Added

data/lib/standard_id/config/schema.rb

@@ -285,6 +285,13 @@ StandardId::ConfigSchema.define do
   scope :oauth do
     field :default_token_lifetime, type: :integer, default: 3600 # 1 hour in seconds
     field :refresh_token_lifetime, type: :integer, default: 2592000 # 30 days in seconds
+    # Seconds for which a just-rotated refresh token is still honoured, so a
+    # client that never RECEIVED its successor (dropped response, killed process)
+    # can retry instead of losing the session to reuse detection. 0 = off, which
+    # is the default: this trades a bounded replay window for resilience and no
+    # host should get it by upgrading. Clamped to
+    # RefreshTokenFlow::MAX_REUSE_LEEWAY_SECONDS.
+    field :refresh_token_reuse_leeway, type: :integer, default: 0
     field :token_lifetimes, type: :hash, default: -> { {} }
     field :client_id, type: :string, default: nil
     field :client_secret, type: :string, default: nil

data/lib/standard_id/events/definitions.rb

@@ -41,6 +41,7 @@ module StandardId
       OAUTH_CODE_CONSUMED = "oauth.code.consumed"
       OAUTH_TOKEN_REVOKED = "oauth.token.revoked"
       OAUTH_REFRESH_TOKEN_REUSE_DETECTED = "oauth.refresh_token.reuse_detected"
+      OAUTH_REFRESH_TOKEN_REUSE_GRACED = "oauth.refresh_token.reuse_graced"
       OAUTH_AUDIENCE_MISMATCH = "oauth.audience.mismatch"
 
       PASSWORDLESS_CODE_REQUESTED = "passwordless.code.requested"
@@ -116,6 +117,7 @@ module StandardId
         OAUTH_CODE_CONSUMED,
         OAUTH_TOKEN_REVOKED,
         OAUTH_REFRESH_TOKEN_REUSE_DETECTED,
+        OAUTH_REFRESH_TOKEN_REUSE_GRACED,
         OAUTH_AUDIENCE_MISMATCH
       ].freeze
 

data/lib/standard_id/oauth/refresh_token_flow.rb

@@ -1,6 +1,11 @@
 module StandardId
   module Oauth
     class RefreshTokenFlow < TokenGrantFlow
+      # Ceiling on `oauth.refresh_token_reuse_leeway`. A long leeway is a long
+      # window in which a stolen token still works, so the setting is clamped
+      # rather than trusted: this is a resilience allowance, not a lifetime.
+      MAX_REUSE_LEEWAY_SECONDS = 120
+
       expect_params :refresh_token, :client_id
       permit_params :client_secret, :scope, :audience
 
@@ -58,10 +63,30 @@ module StandardId
         end
 
         if @current_refresh_token_record.revoked?
-          # Reuse detected: this token was already rotated. Revoke entire family.
-          @current_refresh_token_record.revoke_family!
-          emit_reuse_detected_event
-          raise StandardId::InvalidGrantError, "Refresh token reuse detected"
+          # A rotated token can be presented for two reasons the server cannot tell
+          # apart: an attacker replaying a stolen one, or an honest client that
+          # never RECEIVED the successor — a timeout, a dead radio, the process
+          # dying between our COMMIT and the client's write. Rotation assumes
+          # delivery; nothing guarantees it.
+          #
+          # Treating both as an attack costs a healthy session: revoke_family!
+          # also kills the successor the client never saw, so a single dropped
+          # response becomes a forced re-login that no client-side retry or
+          # failure-budget can recover from (see
+          # spec/lib/standard_id/refresh_rotation_lost_response_spec.rb).
+          #
+          # So, within a short leeway, rotate from the successor instead — but
+          # ONLY while that successor is untouched (see #graced_successor_for).
+          # Disabled by default: a host must opt in.
+          if (successor = graced_successor_for(@current_refresh_token_record))
+            emit_reuse_graced_event(@current_refresh_token_record, successor)
+            @current_refresh_token_record = successor
+          else
+            # Reuse detected: this token was already rotated. Revoke entire family.
+            @current_refresh_token_record.revoke_family!
+            emit_reuse_detected_event
+            raise StandardId::InvalidGrantError, "Refresh token reuse detected"
+          end
         end
 
         unless @current_refresh_token_record.active?
@@ -151,6 +176,77 @@ module StandardId
         raise StandardId::InvalidGrantError, "Refresh token is no longer valid"
       end
 
+      # The successor to a revoked token, when re-issuing from it is safer than
+      # revoking the family — otherwise nil, and reuse detection proceeds unchanged.
+      #
+      # Every condition here narrows the window in which a replayed token is
+      # honoured:
+      #
+      # - **Opt-in.** Zero (the default) disables this entirely, so no existing
+      #   host changes behaviour by upgrading.
+      # - **Recently rotated.** Outside the leeway a replay is not a plausible
+      #   in-flight retry.
+      # - **Successor still active, and never itself rotated.** This is the load-
+      #   bearing one. If the successor has been USED, the legitimate client
+      #   demonstrably received it, so the token being replayed now is a replay,
+      #   not a lost response — and the family dies as before.
+      #
+      # What this deliberately does NOT do is claim to distinguish an attacker
+      # from an unlucky client; the server cannot. It bounds the damage instead.
+      # An attacker replaying inside the window gets a session, but the real
+      # client still holds the successor, and the moment it refreshes, that token
+      # is revoked-and-reused: the family dies and the user re-authenticates.
+      # The exposure is therefore one refresh interval, not indefinite — versus
+      # today, where the honest client is guaranteed to lose its session.
+      #
+      # The successor cannot simply be RE-DELIVERED, which would be the ideal
+      # (idempotent) answer: only its digest is stored, by design, so its token
+      # string is unrecoverable. Rotating from it is the closest safe equivalent.
+      def graced_successor_for(revoked_record)
+        leeway = reuse_leeway_seconds
+        return nil unless leeway.positive?
+        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)
+        return nil unless successor&.active?
+        return nil if StandardId::RefreshToken.exists?(previous_token_id: successor.id)
+
+        successor
+      end
+
+      # Seconds for which a just-rotated token is still honoured. Absent or
+      # non-positive config means OFF — reuse detection behaves exactly as it did
+      # before this existed.
+      def reuse_leeway_seconds
+        config = StandardId.config.oauth
+        return 0 unless config.respond_to?(:refresh_token_reuse_leeway)
+
+        value = config.refresh_token_reuse_leeway
+        seconds =
+          case value
+          when ActiveSupport::Duration then value.to_i
+          when Numeric, String then value.to_i
+          else 0
+          end
+        return 0 unless seconds.positive?
+
+        [seconds, MAX_REUSE_LEEWAY_SECONDS].min
+      end
+
+      # Graced replays are the quiet half of this feature: nothing fails, so
+      # without an event the only evidence a host has that the leeway is load-
+      # bearing (or mis-tuned) is its absence of complaints.
+      def emit_reuse_graced_event(replayed, successor)
+        StandardId::Events.publish(
+          StandardId::Events::OAUTH_REFRESH_TOKEN_REUSE_GRACED,
+          account_id: @refresh_payload[:sub],
+          client_id: @refresh_payload[:client_id],
+          refresh_token_id: replayed.id,
+          successor_refresh_token_id: successor.id
+        )
+      end
+
       def emit_reuse_detected_event
         StandardId::Events.publish(
           StandardId::Events::OAUTH_REFRESH_TOKEN_REUSE_DETECTED,

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.38.0"
+  VERSION = "0.39.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.38.0
+  version: 0.39.0
 platform: ruby
 authors:
 - Jaryl Sim