standard_id 0.36.2 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6ea917e3795560901ae1213d21a172e84fb836ecd6885f96f99c138291ffd40
-  data.tar.gz: e4582d67367ee6026bc058ffb60a17ee729fb23635318c3acec42a153b0d2b19
+  metadata.gz: ea8084bb866fc4da82d81ec18d2b24676e3209ac8d21975c20deb9aa334160fc
+  data.tar.gz: 1cc922486ca4204c8308ff489dc5f425424c06e758a1a4b77276b6670a637f10
 SHA512:
-  metadata.gz: b00ae747d7337e330bf1187f600d8a979c345ea64b72a438657ee28c37d0e685ef00205f4db5726532be0f8db04c3c6386ef98322420ba290999d63b80f9ff80
-  data.tar.gz: d7c7f079b61c66c65f7c76d5f214e08f11643359199f2cc8b28192b41eff175431a9d8826c224363f94f71adecbd59ff81ff6dd6594d89c15d5498f558b9aebf
+  metadata.gz: 3e030d75f3f08d7961ac1cab6ede04da0940ee5471191bfc5c06ef832469f6da2a9af44539fa04e889801defded08c8bdf138c7a8bd1661d8c0628c5b707d08f
+  data.tar.gz: b5301f0db610433bcb542699f95beddcd9e91e93dda098f940edafc9af5c70ab264ef6c70b427e84ac34a9edae861316cf3d608f4f5c2dad6996eb6b9780cbcf

data/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`refresh_tokens.session_id` is finally populated, and the cause was statement ordering, not a missing feature.** Every refresh token in every consuming app had a nil `session_id`, so every session→refresh revocation cascade — the gem's own `Session#revoke!`, `Session.revoke_sessions!`, and each app's equivalent — matched **zero rows**, and 0.35.0's parent-session check had no parent to consult. Measured in production: jumpdrive 15 tokens / 0 linked; nutripod 238 / 0, with **177 live at the time of measurement**.
+
+  `generate_token_response` created the refresh token one statement *before* `maybe_persist_session_for_token!` ran, inside the same transaction — so when `persist_refresh_token!` wrote `session_id`, there was no session yet to point at. The link was nil **by construction**, not by omission. Swapping the two statements is the fix; `refresh_token_session_id` now returns the session the same grant just materialised.
+
+  See rarebit-one/rarebit-ops#304.
+
+### Changed
+
+- **BEHAVIOUR NARROWED — `validate_parent_session!` now refuses only on a REVOKED parent, no longer on an expired one.** This is a deliberate relaxation of what 0.35.0 shipped, and hosts should read it before upgrading.
+
+  `Session#active?` is `!revoked? && !expired?`, so the original `return if session.active?` also refused a refresh whose parent had merely aged out. That was harmless while nothing was linked — with no parent, neither branch could fire. The moment linkage above becomes real, an expiry branch silently becomes a **lifetime policy**, and a badly-scaled one: an app running an 86400s `browser_session_lifetime` against a 2592000s `refresh_token_lifetime` would see its session-backed clients drop from monthly to **daily** re-authorization, as a side effect of a security fix that was never about login frequency.
+
+  Revocation is the property the estate wants: an operator revokes a session and access ends. Lifetime remains `refresh_token_lifetime`'s job, which already exists and is already configured per host. Keeping them separate is what lets linkage ship without renegotiating anyone's login cadence.
+
+- **`ServiceSession` is carved out of linkage on purpose.** Machine credentials keep their own lifecycle, matching the exclusion the `:account` revocation scope already makes, so a human's browser logout cannot kill a running CLI or MCP agent sharing the account.
+
+### Notes for hosts
+
+**This release does not retroactively repair your app.** Linkage happens only where the host materialises a session at token-issue time via `config.session.session_type_resolver`. A host with no resolver configured keeps nil `session_id` and is unchanged in every respect. The gem now makes the property *achievable and automatic*; enabling it per app is separate work.
+
+Existing rows cannot be linked retroactively — there is no record of which session issued them.
+
 ## [0.36.2] - 2026-08-04
 
 **The third release in one chain, and the last of it.** 0.36.0 made the account guards bite on live sessions; 0.36.1 repaired the 500 that exposed on `ApiEngine`; this repairs 0.36.1's own overreach onto the OAuth token endpoint. That reads like flailing, so state it plainly: 0.36.0 was a correct behaviour change, and each follow-up is a narrower blast radius of the same root cause — an exception pair that no controller in the ancestry had ever had to answer for, meeting two route families with two different wire contracts. 0.36.1 fixed the first family and, by rescuing on the shared parent, silently annexed the second. 0.36.2 draws the line between them. Nothing here reverts 0.36.0 or 0.36.1; resource-endpoint behaviour is byte-identical to 0.36.1.

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

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

@@ -84,9 +84,26 @@ module StandardId
       #
       # Checking the parent here makes the property true by construction: it
       # holds however the session was revoked — `revoke!`, a bare `update!`, a
-      # bulk `update_all`, a DBA, a data fix — and it covers expiry as well.
+      # bulk `update_all`, a DBA, a data fix.
       # See rarebit-one/rarebit-ops#297.
       #
+      # REVOCATION, NOT EXPIRY — deliberately, and this is a narrowing of what
+      # 0.35.0 shipped. `Session#active?` is `!revoked? && !expired?`, so the
+      # original `return if session.active?` also refused a refresh whose parent
+      # had merely aged out. That was harmless while `session_id` was nil
+      # everywhere; the moment rarebit-one/rarebit-ops#304 makes linkage real it
+      # silently becomes a lifetime policy — and a badly-scaled one. jumpdrive
+      # runs an 86400s browser_session_lifetime against a 2592000s
+      # refresh_token_lifetime, so tying the two would cut its session-backed
+      # MCP clients from monthly to DAILY re-authorization, as a side effect of
+      # a security fix nobody asked to change login frequency.
+      #
+      # Revocation is the property the estate actually wants: an operator clicks
+      # "revoke this session" and access ends. Expiry is a lifetime decision that
+      # belongs to `refresh_token_lifetime`, which already exists and is already
+      # configured per app. Keeping them separate means linkage can ship without
+      # renegotiating anyone's login cadence.
+      #
       # A refresh token with no session (`session_id` nil) is unaffected: that
       # is the machine-to-machine shape (client_credentials and any other grant
       # the gem issues without persisting a session), where there is no parent
@@ -99,7 +116,7 @@ module StandardId
       def validate_parent_session!
         session = @current_refresh_token_record.session
         return if session.nil?
-        return if session.active?
+        return unless session.revoked?
 
         raise StandardId::InvalidGrantError, "Refresh token is no longer valid"
       end

data/lib/standard_id/oauth/token_grant_flow.rb

@@ -63,8 +63,15 @@ module StandardId
         # (see there for why) — that path is safe because the swallowed
         # exception fires before any DB work in this block.
         ActiveRecord::Base.transaction do
+          # Session FIRST, refresh token second. The order is load-bearing, not
+          # stylistic: `persist_refresh_token!` writes `session_id`, so the
+          # session row has to exist before the token row is built or the link
+          # is nil by construction. It was the other way round until
+          # rarebit-one/rarebit-ops#304, which is the whole reason
+          # `refresh_tokens.session_id` was nil in every app in the estate —
+          # there was no session to point at yet.
+          @oauth_session = maybe_persist_session_for_token!
           response[:refresh_token] = generate_refresh_token if supports_refresh_token?
-          maybe_persist_session_for_token!
         end
 
         emit_token_issued(expires_in)
@@ -166,8 +173,33 @@ module StandardId
         )
       end
 
+      # The parent session for the refresh token issued by THIS grant, when the
+      # host materialised one via `config.session.session_type_resolver`.
+      #
+      # Returning a real id here is what makes "revoking a session ends that
+      # session's access" true by construction rather than an emergent property
+      # of every caller remembering to reach for the right method. With it nil —
+      # which it was everywhere before rarebit-one/rarebit-ops#304 — every
+      # session→refresh cascade in the gem and in the apps matched zero rows,
+      # and 0.35.0's parent-session check had no parent to consult.
+      #
+      # Still nil where there is genuinely no parent: no resolver configured
+      # (the default), or a grant the host does not materialise a session for.
+      # That keeps machine-to-machine grants (client_credentials) exactly as
+      # they were — there is no session to outlive.
+      #
+      # ServiceSessions are carved out on purpose. Machine credentials have
+      # their own lifecycle, and the gem's `:account` revocation scope already
+      # excludes them; linking one here would let a human's browser logout kill
+      # a running CLI or MCP agent sharing the account. `OauthSessionPersistence`
+      # refuses to build one at all, so this guard is belt-and-braces against a
+      # host that reaches around it — cheap, and the failure it prevents is
+      # silent.
       def refresh_token_session_id
-        nil
+        return nil if @oauth_session.nil?
+        return nil if @oauth_session.is_a?(StandardId::ServiceSession)
+
+        @oauth_session.id
       end
 
       def previous_refresh_token_record

data/lib/standard_id/version.rb

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

metadata

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