standard_id 0.37.0 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26e62c374edcaa53ab63756178e869a2d0c54c7ab00d26c2da823b28867fbeb6
-  data.tar.gz: 1a9a4e63f3e7f0e603c771c78f9fe503aad2768ea6302f675c360056f9d7c8d7
+  metadata.gz: aafcc86281b43717bf4afeae67e469f9f773f62bb674137adce6b7924eb24be2
+  data.tar.gz: 1236e399e761f545b7c2c749d44bd317f48355650b1f76accbf22704940f00d5
 SHA512:
-  metadata.gz: d29d16c5b0d02017f574df54ee5a14a2455e4440da51c72d6cb480e89c284de9167fbb5f0dbdf4bb8e659009c2020ec06d80f7e7b56c2e06323969b5356c9db2
-  data.tar.gz: 510aaa0c2252ae3a1a1ab548a9f4272fdaa304cef732cb9b87995d0996734340f5673750abfe827af29b875dde7e0b08cf88b345da2e1543b9459879d4072168
+  metadata.gz: 0cbb9b1a8fd120918f0dbf986822b70990105c6e288ede4b8f2fc790b82cfa2f5ded7cbc774ae4e18afc6e03b29f40e93ffc736d8fd7021ce2ae81f10b03a59c
+  data.tar.gz: dcbdbea82b00733fb9de47a2ba1b4f44362f819ee27ccac2bbb3b1c10573a225afac8d98c50644648ca9756d5a15ecc4262448ff899632f109e8510f2edf5fcd

data/CHANGELOG.md

@@ -7,6 +7,48 @@ 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
+
+- **Event payloads now carry record identifiers alongside the records — the emitter half of rarebit-one/rarebit-ops#296.** This gem publishes whole ActiveRecord objects on the notification bus (`account:`, `current_account:`, `session:`, `code_challenge:`), and a record serialises with **all** its attributes. That is how `account.password_digest`, `session.token_digest`, `session.lookup_hash` and the plaintext passwordless OTP in `code_challenge.code` reached append-only audit rows across the estate.
+
+  `standard_audit` 0.11.0 closed its own write path with `dereference_record_metadata`, but it could only ever protect `audit_logs`. Every host subscriber receives the same payload and may put the record into Sentry context, a structured log, or a table of its own — all outside that gem's reach. Curating at the emitter is the only fix that closes the class.
+
+  `config.events.publish_record_identifiers` (default **`true`**) adds `<key>_id` and `<key>_gid` beside every record-valued key and **removes nothing**.
+
+- **`config.events.publish_records` (default `true`) is the opt-out** for hosts ready to stop receiving the records themselves.
+
+### Notes for hosts
+
+- **This release is additive on purpose — no consumer changes behaviour today.** All five consumers configure an `actor_extractor` reading `payload[:actor] || payload[:current_account] || payload[:account]` and calling `to_global_id` on the result, so swapping records for identifiers in one step would break actor attribution in five apps simultaneously.
+
+  The migration path is per-host and provable: point your subscribers at the new `_gid` keys, confirm in staging that nothing depends on the records, then set `publish_records` to `false`. The intended end state is for that to default to `false` in a later major, and for the records to go away in the one after.
+
+- **Both `_id` and `_gid` are published.** A GlobalID carries the class, and `account_id` alone cannot tell an `Account` from anything else sharing a primary key. The audit gems key on the GID.
+
+- **`to_global_id` is rescued.** It raises on an unpersisted record, and publishing sits on the authentication path — an event must never fail because of metadata this method adds to it.
+
 ## [0.37.0] - 2026-08-05
 
 ### Fixed

data/lib/standard_id/config/schema.rb

@@ -108,6 +108,34 @@ StandardId::ConfigSchema.define do
 
   scope :events do
     field :enable_logging, type: :boolean, default: false
+
+    # Publish `<key>_id` / `<key>_gid` alongside every record-valued payload key
+    # (rarebit-one/rarebit-ops#296).
+    #
+    # StandardId publishes whole ActiveRecord objects on the notification bus —
+    # `account:`, `current_account:`, `session:`, `code_challenge:` — and a
+    # record serialises with ALL its attributes. `standard_audit` 0.11.0 stopped
+    # that reaching `audit_logs`, but the bus is not the audit gem's to police:
+    # a host's own subscribers still receive the full record and may put it in
+    # Sentry context, a structured log, or a table of their own.
+    #
+    # On by default because it only ADDS keys. Nothing that reads `account:`
+    # today changes behaviour — including every consumer's `actor_extractor`,
+    # which reads the record to call `to_global_id` on it.
+    field :publish_record_identifiers, type: :boolean, default: true
+
+    # The other half of the migration, and deliberately OFF by default.
+    #
+    # Turning it off stops the records themselves being published, leaving only
+    # the identifiers. That IS a breaking payload change — it is the whole point
+    # — so it is a host's opt-in, taken once its subscribers read the `_id`/`_gid`
+    # keys instead. A host can flip it in staging to prove nothing depends on
+    # the records before committing.
+    #
+    # The intended end state is this defaulting to false in a later major, and
+    # the records going away in the one after. Until a host opts in, behaviour
+    # is exactly as it was.
+    field :publish_records, type: :boolean, default: true
   end
 
   scope :passwordless do
@@ -257,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/events.rb

@@ -132,7 +132,65 @@ module StandardId
           enriched[:scope] ||= ::Current.scope if ::Current.respond_to?(:scope) && ::Current.scope.present?
         end
 
-        enriched.merge(payload)
+        with_record_identifiers(enriched.merge(payload))
+      end
+
+      # Adds `<key>_id` and `<key>_gid` next to every record-valued key, and —
+      # only when a host opts in — removes the records themselves.
+      #
+      # WHY (rarebit-one/rarebit-ops#296)
+      # ---------------------------------
+      # This gem publishes whole ActiveRecord objects: `account:`,
+      # `current_account:`, `session:`, `code_challenge:`. A record serialises
+      # with ALL its attributes, which is how `account.password_digest`,
+      # `session.token_digest`, `session.lookup_hash` and the plaintext
+      # passwordless OTP in `code_challenge.code` reached append-only audit rows
+      # — 3,007 of them on one app, unrepairable because the table refuses
+      # UPDATE by design.
+      #
+      # `standard_audit` 0.11.0 fixed its own write path. It cannot fix the bus:
+      # every host subscriber still receives the full record and may put it
+      # anywhere. Publishing the identifier alongside is what lets a subscriber
+      # stop needing the record at all.
+      #
+      # WHY ADDITIVE FIRST
+      # ------------------
+      # Swapping records for identifiers in one step breaks every consumer's
+      # `actor_extractor` simultaneously — all five apps configure one, and they
+      # read `payload[:actor] || payload[:current_account] || payload[:account]`
+      # expecting something they can call `to_global_id` on. So the default adds
+      # keys and removes nothing; `config.events.publish_records = false` is the
+      # opt-out a host takes once its subscribers read the identifiers.
+      #
+      # `_gid` as well as `_id` because a GlobalID carries the class, and the
+      # audit gems key on it. `to_global_id` is rescued: a new or unpersisted
+      # record raises, and an event must never fail because of the metadata this
+      # method adds to it.
+      def with_record_identifiers(payload)
+        return payload unless defined?(::ActiveRecord::Base)
+
+        config = StandardId.config.events
+        return payload unless config.publish_record_identifiers || !config.publish_records
+
+        payload.each_with_object({}) do |(key, value), out|
+          unless value.is_a?(::ActiveRecord::Base)
+            out[key] = value
+            next
+          end
+
+          out[key] = value if config.publish_records
+
+          next unless config.publish_record_identifiers
+
+          out[:"#{key}_id"] ||= value.id
+          out[:"#{key}_gid"] ||= safe_global_id(value)
+        end.compact
+      end
+
+      def safe_global_id(record)
+        record.to_global_id.to_s
+      rescue StandardError
+        nil
       end
     end
   end

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.37.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.37.0
+  version: 0.39.0
 platform: ruby
 authors:
 - Jaryl Sim