standard_id 0.33.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5341add412ad2ef395a4252d31f751e5b9eeb9df585f1eb3e5c276d7071211f
-  data.tar.gz: b53b6dc29f5aa4a5994b040f5a6cdca2441c4c0c57cb2449b1fc1aead9caf4a7
+  metadata.gz: e5e5289f6f264b4175abb757c1423d9fc656e5b2e5057239e7486d843a3eaf7a
+  data.tar.gz: 209d3a72e8a16049ef1e633216c38939e69518e526baea0110dd99567ac23083
 SHA512:
-  metadata.gz: a4162b488000bc8e889dba2887ffe2257ad8ac342d7612aff936c74fccbf30f22560f4194c39e0552446e3e6a93b2d335c2d34b3d27ceb67586fdeb188de5181
-  data.tar.gz: fd04fc771429eaf0ed9efd4fa01fa85263983be3dd8cdf9a5b3df16194959387d929aa7bcf27711681dfb0262c3d57fd1df11f64761128646f43d9bb495ad8da
+  metadata.gz: bdc0a65782aa7ea1299b49b0eb946dc72e56391de6e7d5132b65e59e27281d9d16a5ef28e1d75fadca282768d853a95d703b1c81278b8008699ddfeb05ab02e1
+  data.tar.gz: ed73c2092285091f034f9d0b33423e4013004a6e129c37220d8a004f94e3c9bb79b1d9d95679f4e18f126db28243201f80cc7126780225e5114b6439a74ff214

data/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.35.0] - 2026-07-31
+
+### Security
+
+- **A refresh token is now refused when its parent session is revoked or expired.** `Oauth::RefreshTokenFlow` validated the `RefreshToken` row only — found, not revoked, not expired — and never consulted the session it belongs to.
+
+  So "revoking a session ends that session's access" was not a property of the gem. It was an emergent consequence of every caller reaching for `Session#revoke!` (a transaction that ALSO does `refresh_tokens.active.update_all(revoked_at:)`) rather than the obvious-looking `session.update!(revoked_at: ...)`, which revokes the session row and leaves its refresh tokens live. Two apps wrote the second form independently and shipped it (rarebit-one/nutripod-web#1100, luminalityai/luminality-web#1048), because the natural spec asserts the session's own `revoked_at` — exactly the half that does work.
+
+  On the device path that meant a refresh-token holder kept minting access tokens after the user had explicitly signed that device out. Checking the parent in the flow makes the property true by construction: it now holds however the session was revoked — `revoke!`, a bare `update!`, a bulk `update_all`, a DBA, a data fix — and covers session expiry too.
+
+  **Unaffected:** refresh tokens with no session (`session_id` nil) — the machine-to-machine shape, including `client_credentials`. There is no parent to outlive, so nothing is checked. No configuration flag was added because no flow in the gem legitimately needs a refresh to outlive its session; every token that carries a `session_id` was minted against that session, and rotation carries the same `session_id` forward.
+
+  The refusal reuses the existing `invalid_grant` / `"Refresh token is no longer valid"` response verbatim (RFC 6749 §5.2). A distinct error would be an oracle — it would tell a holder that the token itself is still good and only the session was pulled.
+
+  The parent session is fetched by `eager_load` in the same query as the token row, so the hot `/oauth/token` path gains no extra round trip.
+
+  Tracked in rarebit-one/rarebit-ops#297.
+
+- **`POST /oauth/introspect` reports the same refresh token as `active: false`.** The RFC 7662 endpoint (off by default, behind `config.oauth.introspection_enabled`) checked the `RefreshToken` row and not its session, so it had the identical gap. Left alone it would have reported `active: true` for a token `/oauth/token` now refuses — introspection contradicting the endpoint it describes. Access tokens are unchanged and still introspect as active until their `exp`; that documented limit is unaffected, because they are stateless and carry no `sid`.
+
+## [0.34.0] - 2026-07-31
+
+### Added
+
+- **`config.verify_issuer`** — decouples MINTING an `iss` claim from REQUIRING one. `nil` (default) follows `config.issuer`, which is the historic behaviour and changes nothing. Set `false` to stamp `iss` on new tokens without yet verifying it.
+
+  This exists because the two were one switch, which made adopting an issuer a flag day: every token already in flight was minted without an `iss`, so setting `config.issuer` rejected all of them at once — every access token and, far worse, every refresh token. An app that had never configured an issuer had no safe single step, which is where `nutripod-web` was stuck (rarebit-one/nutripod-web#1111) and why it could not retire its hand-rolled discovery controller with the rest of the estate.
+
+  Migration: set `issuer` with `verify_issuer = false`, wait out `refresh_token_lifetime` (the long pole — access tokens are short), then remove the override. Setting `true` with no issuer raises at boot rather than silently verifying against `nil` and accepting anything.
+
 ## [0.33.0] - 2026-07-30
 
 ### Added

data/app/controllers/standard_id/api/oauth/introspections_controller.rb

@@ -32,8 +32,12 @@ module StandardId
       # lifetime.
       #
       # Refresh tokens ARE persisted (as `SHA256(jti)`), so those are checked
-      # against the row: a revoked or expired refresh token introspects as
-      # inactive, correctly and immediately.
+      # against the row AND against the parent session: a refresh token that is
+      # itself revoked or expired — or whose session is — introspects as
+      # inactive, correctly and immediately. That second half matters because
+      # the session can be revoked without the cascade ever running (a bare
+      # `update!`, a bulk `update_all`); see Oauth::RefreshTokenFlow and
+      # rarebit-one/rarebit-ops#297.
       class IntrospectionsController < BaseController
         public_controller
 
@@ -86,8 +90,21 @@ module StandardId
           return render_inactive if payload.nil?
 
           # Persisted refresh tokens are checkable; access tokens are not.
-          persisted = StandardId::RefreshToken.find_by_jti(payload[:jti].to_s) if payload[:jti].present?
+          #
+          # eager_load the parent session in the same query: the answer must
+          # match what Oauth::RefreshTokenFlow would do with the same token, and
+          # that flow refuses a refresh whose session is revoked or expired
+          # (rarebit-one/rarebit-ops#297). Reporting `active: true` here for a
+          # token /oauth/token would refuse would make introspection an
+          # authority that disagrees with the endpoint it describes.
+          #
+          # A nil session means no parent — the machine-to-machine shape — and
+          # is not a reason to call the token inactive.
+          if payload[:jti].present?
+            persisted = StandardId::RefreshToken.eager_load(:session).find_by_jti(payload[:jti].to_s)
+          end
           return render_inactive if persisted && !persisted.active?
+          return render_inactive if persisted&.session && !persisted.session.active?
 
           render json: active_response(payload, persisted), status: :ok
         end

data/lib/standard_id/config/schema.rb

@@ -12,6 +12,26 @@ StandardId::ConfigSchema.define do
     field :passwordless_email_sender, type: :any, default: nil
     field :passwordless_sms_sender, type: :any, default: nil
     field :issuer, type: :string, default: nil
+
+    # Whether `JwtService.decode` REQUIRES a matching `iss` claim.
+    #
+    # `nil` (default) means "follow the issuer": verification is on exactly
+    # when `issuer` is set. That is the historic behaviour and is what you
+    # want once an issuer has always been configured.
+    #
+    # Set `false` to MINT an `iss` claim without yet REQUIRING one. This
+    # exists because the two were coupled, and that coupling makes adopting an
+    # issuer an all-or-nothing flag day: every token already in flight was
+    # minted without an `iss`, so turning the issuer on rejected all of them at
+    # once — every access token and, far worse, every refresh token. For an app
+    # that had never set an issuer there was no safe single step, which is
+    # exactly the position nutripod-web was stuck in (rarebit-one/nutripod-web#1111).
+    #
+    # The migration is then: set `issuer` with `verify_issuer = false`, wait
+    # out `refresh_token_lifetime` (the long pole — access tokens are short),
+    # then remove the override. Setting `true` with no issuer raises at boot
+    # rather than silently verifying nothing.
+    field :verify_issuer, type: :boolean, default: nil
     field :login_url, type: :string, default: nil
     field :allowed_post_logout_redirect_uris, type: :array, default: []
     field :account_scope, type: :any, default: nil

data/lib/standard_id/jwt_service.rb

@@ -52,6 +52,30 @@ module StandardId
       SUPPORTED_ALGORITHMS[algorithm] || raise(ArgumentError, "Unsupported algorithm: #{algorithm}. Supported: #{SUPPORTED_ALGORITHMS.keys.join(', ')}")
     end
 
+    # Whether decode REQUIRES a matching `iss`. `nil` (the default) follows the
+    # issuer, which is the historic behaviour: verification on exactly when an
+    # issuer is configured.
+    #
+    # The override exists so an app can START MINTING an `iss` without yet
+    # REQUIRING one. Coupled, adopting an issuer is a flag day — every token
+    # already in flight was minted without the claim, so enabling the issuer
+    # rejects all of them at once, refresh tokens included. Decoupled, the app
+    # sets `verify_issuer = false`, waits out `refresh_token_lifetime`, and then
+    # drops the override with no window in which valid tokens are refused.
+    def self.verify_issuer?
+      configured = StandardId.config.verify_issuer
+      return StandardId.config.issuer.present? if configured.nil?
+
+      if configured && StandardId.config.issuer.blank?
+        raise StandardId::ConfigurationError,
+              "verify_issuer is true but no issuer is configured — decode would " \
+              "verify against nil and accept any token. Set config.issuer, or " \
+              "leave verify_issuer nil to follow it."
+      end
+
+      configured
+    end
+
     def self.asymmetric?
       algorithm_config[:type] == :asymmetric
     end
@@ -152,7 +176,7 @@ module StandardId
     def self.decode(token, allowed_audiences: nil)
       options = { algorithms: [algorithm] }
 
-      if StandardId.config.issuer.present?
+      if StandardId.config.issuer.present? && verify_issuer?
         options[:iss] = StandardId.config.issuer
         options[:verify_iss] = true
       end

data/lib/standard_id/oauth/refresh_token_flow.rb

@@ -47,7 +47,11 @@ module StandardId
         # once all pre-jti tokens have expired (refresh_token_lifetime after deploy).
         return if jti.blank?
 
-        @current_refresh_token_record = StandardId::RefreshToken.find_by_jti(jti)
+        # eager_load (not includes/lazy) so the parent session arrives in the
+        # SAME query via a LEFT OUTER JOIN. #validate_parent_session! below
+        # reads it on every refresh, and /oauth/token is a hot path — a lazy
+        # `.session` would add a second SELECT per request.
+        @current_refresh_token_record = StandardId::RefreshToken.eager_load(:session).find_by_jti(jti)
 
         unless @current_refresh_token_record
           raise StandardId::InvalidGrantError, "Refresh token not found"
@@ -63,6 +67,41 @@ module StandardId
         unless @current_refresh_token_record.active?
           raise StandardId::InvalidGrantError, "Refresh token is no longer valid"
         end
+
+        validate_parent_session!
+      end
+
+      # Refuse a refresh whose parent session is no longer active.
+      #
+      # Without this, "revoking a session ends that session's access" was not a
+      # property of the gem at all — it was an emergent consequence of every
+      # caller reaching for Session#revoke! (a transaction that ALSO does
+      # `refresh_tokens.active.update_all(revoked_at:)`) rather than the
+      # obvious-looking `session.update!(revoked_at:)`, which revokes the
+      # session row and leaves its refresh tokens live. Two apps wrote the
+      # second form independently and shipped it, because a spec asserting the
+      # session's own `revoked_at` passes against the buggy code.
+      #
+      # 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.
+      # See rarebit-one/rarebit-ops#297.
+      #
+      # 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
+      # to outlive and nothing to check.
+      #
+      # The message is deliberately IDENTICAL to the inactive-token case above.
+      # A distinct error would be an oracle: it would tell an attacker holding a
+      # stolen refresh token that the token itself is still good and only the
+      # session was pulled. RFC 6749 §5.2 wants `invalid_grant` either way.
+      def validate_parent_session!
+        session = @current_refresh_token_record.session
+        return if session.nil?
+        return if session.active?
+
+        raise StandardId::InvalidGrantError, "Refresh token is no longer valid"
       end
 
       # Atomically revoke the current token as part of rotation.

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.33.0"
+  VERSION = "0.35.0"
 end

metadata

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