standard_id 0.38.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea8084bb866fc4da82d81ec18d2b24676e3209ac8d21975c20deb9aa334160fc
-  data.tar.gz: 1cc922486ca4204c8308ff489dc5f425424c06e758a1a4b77276b6670a637f10
+  metadata.gz: 89d297a5e9c69566991b97cca501fd5a714b2d2e1200d2e740b3e45684981aab
+  data.tar.gz: d93fc7206735373f14ac2cd51c4612aaf7b1d19244022d884f0c84757d8f78c6
 SHA512:
-  metadata.gz: 3e030d75f3f08d7961ac1cab6ede04da0940ee5471191bfc5c06ef832469f6da2a9af44539fa04e889801defded08c8bdf138c7a8bd1661d8c0628c5b707d08f
-  data.tar.gz: b5301f0db610433bcb542699f95beddcd9e91e93dda098f940edafc9af5c70ab264ef6c70b427e84ac34a9edae861316cf3d608f4f5c2dad6996eb6b9780cbcf
+  metadata.gz: 1ce536a136af167e65ec9d01e370a187d71f77a2f60f0c5af47ee5c23a9b58cb87444b95191a019fa06689902765f51eaff20656aeedcdef288e34f577c99c91
+  data.tar.gz: f825db9970c937a76592c421fb71a9607f3ea0667dfafa105ff2d6ce78bbd754f5ca01f873cf3321962876c3ab0f8c7f7314ec95604cf5900d56291cede6ec57

data/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.40.0] - 2026-09-05
+
+### Fixed
+
+- **`sign_in_account` now supersedes a nil memoised earlier in the same request.** With the `session_resolved` / `account_resolved` memo introduced in the entry below, a guard or shared prop that read `current_account` before the sign-in action ran would have kept returning nil for the rest of that request. Sign-in now memoises the new session and resets the account memo, so the next `current_account` re-derives the account through `load_current_account` — `config.account_scope` and `strict_loading!(false)` apply exactly as on an ordinary authenticated request (caught in review of #326 and #327).
+
+- **An anonymous request no longer queries the session table on every `current_account` call, and no longer writes an empty Rails session.** `Web::SessionManager#current_session` memoised with `Current.session ||= …`, which never memoises a nil answer, so a visitor with no session paid the `BrowserSession.by_token(nil)` lookup on every read — shared props, guards, locale selection, nav helpers — five or six times per page. On one consumer's marketing homepage that was ~6 session-table queries per anonymous request and the app's single largest query by total time (fundbright/delivery-ops#598). Worse, the "no session" branch called `clear_session!`, whose `session.delete` loads the Rack session, and Rack persists every loaded session: a new empty session row and a `Set-Cookie` on every anonymous response, which is what stops a CDN from caching a public page.
+
+  Two new `Current` attributes, `session_resolved` and `account_resolved`, record that the question was answered (nil included) for the rest of the request. `load_session_from_session_token` returns without a query when there is no token, and only falls back to `session[:session_token]` when the Rails session is already loaded or its cookie is actually present on the request (`request.session_options[:key]`) — so a bare GET never allocates one. `load_session_from_remember_token` returns early without a `remember_token` cookie. `clear_session!` only touches the Rails session when it is loaded, and the no-session branch only clears at all when there is stale state to clear (a `session_token`/`remember_token` cookie, or session keys). Hosts that include `StandardId::CurrentAttributes` get the new attributes automatically; a host that hand-rolls `Current` must add them.
+
+## [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/current_attributes.rb

@@ -4,6 +4,10 @@ module StandardId
 
     included do
       attribute :session, :account, :request_id, :ip_address, :user_agent, :scope
+      # Set once Web::SessionManager has answered "which session / account is
+      # this request?" — including when the answer is nil — so the lookup is
+      # never repeated within a request. Reset with the rest of Current.
+      attribute :session_resolved, :account_resolved
     end
   end
 end

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.40.0"
 end

data/lib/standard_id/web/session_manager.rb

@@ -11,12 +11,25 @@ module StandardId
         @reset_session = reset_session
       end
 
+      # Both readers memoise their answer for the rest of the request — including
+      # a nil answer. `Current.session ||= …` never did: an anonymous visitor has
+      # no session, so every `current_account` call (shared props, before_actions,
+      # locale selection, nav helpers — five or six per page) re-ran the lookup.
+      # On one consumer's marketing homepage that was ~6 session-table queries
+      # per anonymous request, the app's single largest query by total time
+      # (fundbright/delivery-ops#598).
       def current_session
-        Current.session ||= load_current_session
+        return Current.session if Current.session_resolved
+
+        Current.session_resolved = true
+        load_current_session
       end
 
       def current_account
-        Current.account ||= load_current_account
+        return Current.account if Current.account_resolved
+
+        Current.account_resolved = true
+        Current.account = load_current_account
       end
 
       def sign_in_account(account, scope_name: nil)
@@ -41,7 +54,18 @@ module StandardId
             scopes << scope_name.to_s unless scopes.include?(scope_name.to_s)
             session[:standard_id_scopes] = scopes
           end
+          # Sign-in supersedes whatever this request already resolved: a guard
+          # or shared prop that asked `current_account` before the sign-in
+          # action ran memoised nil, and that memo must not outlive the sign-in.
+          # The session is known here, so memoise it; the account is NOT
+          # assigned directly — the memo is reset so the next `current_account`
+          # re-derives it through load_current_account, which applies
+          # `config.account_scope` and `strict_loading!(false)` exactly as an
+          # ordinary authenticated request would (review of #327).
           Current.session = browser_session
+          Current.session_resolved = true
+          Current.account = nil
+          Current.account_resolved = false
           emit_session_created(browser_session, account, "browser")
         end
       end
@@ -61,8 +85,18 @@ module StandardId
 
       def clear_session!
         # TODO: make token key names configurable
-        session.delete(:session_token)
-        session.delete(:standard_id_scopes)
+        #
+        # Only touch the Rails session when it is already loaded. Reading or
+        # deleting a key on an unloaded Rack session loads it, and Rack commits
+        # every loaded session on the way out — so on an anonymous request this
+        # used to write a brand-new empty session to the store and stamp a
+        # session cookie on the response, which is what stops any CDN from
+        # caching a public page. If the session was never loaded there is nothing
+        # in it to clear.
+        if rails_session_loaded?
+          session.delete(:session_token)
+          session.delete(:standard_id_scopes)
+        end
         # Delete the cookie outright. Assigning `cookies.encrypted[:session_token] = nil`
         # writes a fresh encrypted blob through the jar's default options (no httponly)
         # on every unauthenticated request, leaving a confusing non-HttpOnly
@@ -72,10 +106,32 @@ module StandardId
         cookies.delete(:remember_token)
 
         Current.session = nil
+        Current.account = nil
+        Current.session_resolved = true
+        Current.account_resolved = true
       end
 
       private
 
+      # A Rack session reports `loaded?`; the plain Hash the specs (and some
+      # hosts' test doubles) hand in does not, and a Hash is always "loaded".
+      def rails_session_loaded?
+        !session.respond_to?(:loaded?) || session.loaded?
+      end
+
+      # Whether the request carries the host app's Rails session cookie at all.
+      # Reading `session[...]` when it does not would make Rack allocate and
+      # then persist an empty session (see clear_session!). Without a request
+      # that can answer, assume it does — the old behaviour.
+      def rails_session_cookie_present?
+        return true unless request.respond_to?(:session_options) && request.respond_to?(:cookies)
+
+        key = request.session_options[:key]
+        return true if key.blank?
+
+        request.cookies.key?(key.to_s)
+      end
+
       # Persist the session token in an encrypted cookie whose lifetime matches
       # the DB session's expires_at, so an authenticated session survives a full
       # browser restart (a bare session cookie would be cleared on browser close,
@@ -117,19 +173,32 @@ module StandardId
             clear_session!
           end
         else
-          clear_session!
+          # Nothing identified a session. Clear stale state only when there is
+          # some — a bare anonymous GET has no cookies to delete and no session
+          # to touch, and touching it is what makes the response uncacheable.
+          clear_session! if stale_session_state?
         end
 
         Current.session
       end
 
+      def stale_session_state?
+        cookies.encrypted[:session_token].present? || cookies[:session_token].present? || cookies[:remember_token].present? ||
+          (rails_session_loaded? && (session[:session_token].present? || session[:standard_id_scopes].present?))
+      end
+
       def load_session_from_session_token
         # Try encrypted cookie first (for Action Cable), then fall back to session (for backward compatibility)
-        session_token = cookies.encrypted[:session_token] || session[:session_token]
+        session_token = cookies.encrypted[:session_token]
+        session_token ||= session[:session_token] if rails_session_loaded? || rails_session_cookie_present?
+        return if session_token.blank?
+
         StandardId::BrowserSession.eager_load(:account).by_token(session_token).first
       end
 
       def load_session_from_remember_token
+        return if cookies[:remember_token].blank?
+
         password_credential = StandardId::PasswordCredential.find_by_token_for(:remember_me, cookies[:remember_token])
         return if password_credential.blank?
 

metadata

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