standard_id 0.36.1 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5519e19cd0f121d012683a24a10d0052ce4bf33e508ede831712db3851abace9
-  data.tar.gz: 9786b159f6ad07238cb7e636f3cfd5e028ec31cb6014f38e0349de3760f0deaf
+  metadata.gz: 26e62c374edcaa53ab63756178e869a2d0c54c7ab00d26c2da823b28867fbeb6
+  data.tar.gz: 1a9a4e63f3e7f0e603c771c78f9fe503aad2768ea6302f675c360056f9d7c8d7
 SHA512:
-  metadata.gz: b18d51d0fc882c6aaf4c9a6482e58600bf82594860715c1b6f5850dd0175834f72dc5735dbb23b2e1f45fbc4ceb8f975dffdc2484a3ee1871b882e89d76c4df6
-  data.tar.gz: 7039cfdf1894c351a3802b893e31a2ff23754acd0a861116b190ca5875540a7ba45d35589cefef79ad1a65444feca3eb999740285bc5af0bd073139d41fdedbc
+  metadata.gz: d29d16c5b0d02017f574df54ee5a14a2455e4440da51c72d6cb480e89c284de9167fbb5f0dbdf4bb8e659009c2020ec06d80f7e7b56c2e06323969b5356c9db2
+  data.tar.gz: 510aaa0c2252ae3a1a1ab548a9f4272fdaa304cef732cb9b87995d0996734340f5673750abfe827af29b875dde7e0b08cf88b345da2e1543b9459879d4072168

data/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+### Fixed
+
+- **`POST /api/oauth/token` answers `400 invalid_grant` again — not `401 invalid_token` — when the account behind the grant is deactivated or locked.** 0.36.1 registered `rescue_from StandardId::AccountDeactivatedError` / `AccountLockedError` on `StandardId::Api::BaseController`, rendering RFC 6750 §3.1's bearer challenge. That is right for a bearer-**protected resource** (`/api/v1/sessions`, `/api/v1/userinfo`): the caller presented an access token and must be told to discard it. But `StandardId::Api::Oauth::BaseController` re-rescues only `OAuthError`, so both account errors fell through to the inherited bearer handler on every OAuth protocol route as well. The token endpoint is not a protected resource — the client is *obtaining* a credential, not presenting one — so there is no token to challenge, and RFC 6749 §5.2 requires a token-endpoint error object instead. A `401` carrying `WWW-Authenticate: Bearer …` is not a legal answer to a grant request, and a conformant client has no defined way to interpret it.
+
+  `StandardId::Api::Oauth::BaseController` now rescues both errors itself. Rails resolves `rescue_from` handlers most-recently-registered-first and a subclass registers after its parent, so the OAuth handler wins on OAuth routes while `Api::BaseController`'s `401` continues to govern every other API route — unchanged. Specs now pin **both** contracts side by side (`spec/requests/standard_id/api/account_error_response_shape_spec.rb`), since the whole defect was one shape applied to two contracts; the file carries the negative control for each half.
+
+- **Why `invalid_grant`, and why it is rendered explicitly.** RFC 6749 §5.2 enumerates six codes. `invalid_grant` — the grant is "invalid, expired, revoked, … or was issued to another client" — is what an authorization code or refresh token belonging to a disabled account has become: the resource owner's authorization no longer stands and no retry will succeed. `unauthorized_client` was the alternative and is wrong on **subject**: it says the *client* is not permitted to use this grant type, a property of client registration that has not changed. The client is fine; the account behind the grant is not. Mapping account state onto a client-scoped code would send well-behaved clients off to audit a registration that is correct.
+
+  The handler renders that code and status literally rather than routing through `handle_oauth_error`. Both account errors are bare `StandardError`s with no `oauth_error_code` / `http_status`, so `handle_oauth_error`'s `respond_to?` fallbacks would yield `invalid_request` / `400`. The status is right by luck; the code is not — §5.2 reserves `invalid_request` for a **malformed** request, and this request is perfectly well-formed. Worse, the fallback path uses `exception.message`, which would put `"Account is deactivated"` / `"Account has been locked"` straight into `error_description`. Depending on a default that is wrong in two of three fields is a coincidence, not reuse.
+
+- **The `error_description` discloses nothing about account state.** Both errors render the same generic sentence — `"The provided authorization grant is invalid, expired or revoked"` — because whoever presents a grant may not be its legitimate holder, which is the exact scenario the account guard exists for. Telling the presenter of a leaked refresh token that the account is suspended is a disclosure, and returning distinguishable text for "deactivated" versus "locked" is a smaller one. `AccountLockedError#lock_reason` is operator-authored text for logs and admin screens and is surfaced in neither the body nor any header; a spec pins that across both. The specific reason belongs in the host's `ACCOUNT_LOCKED` / `ACCOUNT_DEACTIVATED` subscriber, server-side.
+
+### Documentation
+
+- **README: never guard a `rescue_from` with a `rescue_handlers` check.** This release exists partly because a consumer's own token-endpoint shim was written as `rescue_from X unless StandardId::Api::BaseController.rescue_handlers.any? { … }` — defensive-looking, and a trap. When 0.36.1 registered a handler for that class on the gem superclass, the guard stopped matching, the host's block never registered, and the gem's `401` silently replaced the host's `400` with no error, no deprecation, and nothing in the host's diff. The two failure modes compounded: the gem shipped the wrong shape *and* disabled the shim that would have corrected it. The README now says to register unconditionally — a later registration already outranks the gem's, which is what the guard was groping for. The hazard is the gem's to warn about, since only the gem can create it.
+
 ## [0.36.1] - 2026-08-04
 
 **A follow-up to 0.36.0's own regression, released the same day.** 0.36.0 is correct and stays — read its entry first for why `SESSION_VALIDATING` had to start carrying `account:`. This release repairs the fallout of that fix on the gem's own API routes. Two releases land together because the second is only reachable *because* of the first.

data/README.md

@@ -788,11 +788,23 @@ When an inactive account attempts to authenticate — at sign-in, at token mint,
 
 > **What the engine's own routes do.** You are responsible for **your** controllers only. The engine handles its own:
 >
-> - **`ApiEngine` routes** (`/api/v1/sessions`, `/api/v1/userinfo`, …) answer **`401` with `error: "invalid_token"`** per RFC 6750 — `StandardId::Api::BaseController` descends from `ActionController::API`, so your `rescue_from` is not in its ancestry and could never have covered it.
+> - **`ApiEngine` resource routes** (`/api/v1/sessions`, `/api/v1/userinfo`, …) answer **`401` with `error: "invalid_token"`** plus a `WWW-Authenticate` challenge, per RFC 6750 §3.1 — the caller *presented* an access token and must be told to discard it. `StandardId::Api::BaseController` descends from `ActionController::API`, so your `rescue_from` is not in its ancestry and could never have covered it.
+> - **`ApiEngine` OAuth protocol routes** (`POST /api/oauth/token`, `/introspect`, `/revoke`, `/register`) answer **`400` with `error: "invalid_grant"`** per RFC 6749 §5.2 — a client at the token endpoint is *obtaining* a credential, not presenting one, so there is no bearer token to challenge. The `error_description` is deliberately generic (`"The provided authorization grant is invalid, expired or revoked"`) and identical for deactivated and locked accounts: whoever presents a grant may not be its legitimate holder, so the response must not confirm account state. `lock_reason` is never surfaced.
 > - **`WebEngine` routes** (`/sessions`, `/account`, `/logout`) are covered by the `rescue_from` you write on `ApplicationController` below, because `StandardId::Web::BaseController` descends from it. The engine deliberately registers no handler of its own there — one would take precedence over yours and override your UX.
 >
 > So: write the `ApplicationController` handler (it covers your pages *and* the web engine's), and write the `Api::BaseController` handler only for **your own** API controllers.
 
+> **⚠️ Never guard a `rescue_from` with a `rescue_handlers` check.** A shim written like this looks defensive and is a trap:
+>
+> ```ruby
+> # DON'T — silently becomes a no-op the moment the gem registers its own handler
+> unless StandardId::Api::BaseController.rescue_handlers.any? { |k, _| k == "StandardId::AccountDeactivatedError" }
+>   StandardId::Api::BaseController.rescue_from(StandardId::AccountDeactivatedError) { ... }
+> end
+> ```
+>
+> When a superclass in the gem gains a handler for that class — as `Api::BaseController` did in 0.36.1 — the guard stops matching, your block never registers, and *the gem's* response shape silently replaces yours with no error, no deprecation, and nothing in the diff. Register unconditionally instead: Rails resolves `rescue_from` handlers most-recently-registered-first, so a later registration already wins over the gem's without any guard. This is exactly how one consumer's `400 invalid_grant` token-endpoint shim was defeated by the gem's `401 invalid_token`.
+
 ```ruby
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
@@ -907,7 +919,7 @@ User.unlocked.active  # => Users who can log in
 
 ### Handling AccountLockedError
 
-When a locked account attempts to authenticate, `StandardId::AccountLockedError` is raised. The error includes metadata about the lock. The same engine-owned-route rules described under [Handling AccountDeactivatedError](#handling-accountdeactivatederror) apply: `ApiEngine` routes answer `401 invalid_token` themselves (never echoing `lock_reason`), `WebEngine` routes defer to your `ApplicationController` handler.
+When a locked account attempts to authenticate, `StandardId::AccountLockedError` is raised. The error includes metadata about the lock. The same engine-owned-route rules described under [Handling AccountDeactivatedError](#handling-accountdeactivatederror) apply: `ApiEngine` resource routes answer `401 invalid_token` themselves, `ApiEngine` OAuth protocol routes answer `400 invalid_grant`, and `WebEngine` routes defer to your `ApplicationController` handler. Neither engine-owned response ever echoes `lock_reason`.
 
 ```ruby
 # app/controllers/application_controller.rb

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

@@ -4,6 +4,24 @@ module StandardId
       class BaseController < StandardId::Api::BaseController
         rescue_from StandardId::OAuthError, with: :handle_oauth_error
 
+        # These two are ALREADY rescued on Api::BaseController (since 0.36.1),
+        # which renders RFC 6750 §3.1 `401 invalid_token` with a
+        # `WWW-Authenticate` challenge. That is the correct answer for a
+        # bearer-PROTECTED RESOURCE — /api/v1/sessions, /api/v1/userinfo —
+        # where the caller presented a token and must be told to discard it.
+        #
+        # It is the wrong answer here. Everything under Api::Oauth is an OAuth
+        # PROTOCOL endpoint: at /api/oauth/token the client is *obtaining* a
+        # credential, not presenting one, so there is no bearer token to
+        # challenge and RFC 6749 §5.2 mandates a token-endpoint error object
+        # (HTTP 400, `error`, `error_description`) instead. Re-registering the
+        # pair here is what keeps the two contracts apart — Rails resolves
+        # rescue_from handlers most-recently-registered-first, and a subclass
+        # registers after its parent, so these win for OAuth routes only and
+        # the resource-endpoint 401 is left exactly as 0.36.1 shipped it.
+        rescue_from StandardId::AccountDeactivatedError, with: :handle_account_unusable
+        rescue_from StandardId::AccountLockedError, with: :handle_account_unusable
+
         private
 
         def handle_oauth_error(exception)
@@ -16,6 +34,49 @@ module StandardId
             error_description: description
           }, status: status
         end
+
+        # `invalid_grant` — chosen deliberately from the RFC 6749 §5.2
+        # enumeration, and rendered explicitly rather than by falling through
+        # `handle_oauth_error`.
+        #
+        # WHY invalid_grant. §5.2 defines it as the grant being "invalid,
+        # expired, revoked, ... or issued to another client", which is exactly
+        # what an authorization code or refresh token belonging to a disabled
+        # account has become: the resource owner's authorization no longer
+        # stands, and no retry of this grant will ever succeed.
+        # `unauthorized_client` was the alternative and is wrong on subject —
+        # it says the CLIENT is not permitted to use this grant type, a
+        # property of client registration that has not changed here; the
+        # client is fine, the account behind the grant is not. Mapping account
+        # state onto a client-scoped code would send well-behaved clients off
+        # to audit their registration.
+        #
+        # WHY EXPLICIT, not the respond_to? fallback. AccountDeactivatedError
+        # and AccountLockedError are bare StandardErrors with no
+        # `oauth_error_code` / `http_status`, so routing them through
+        # `handle_oauth_error` would yield `invalid_request` / 400 by default.
+        # 400 is right; `invalid_request` is not — §5.2 reserves it for a
+        # MALFORMED request (missing parameter, repeated parameter), and this
+        # request is perfectly well-formed. It would also leak the raw
+        # exception message ("Account is deactivated" / "Account has been
+        # locked") into `error_description`, which is precisely what must not
+        # happen. Relying on a default that is wrong in both fields is not
+        # reuse, it is a coincidence waiting to break.
+        #
+        # WHY THE DESCRIPTION IS GENERIC. Whoever presents a grant may not be
+        # its legitimate holder — a leaked refresh token is the scenario the
+        # account guard exists for — so the response must not confirm account
+        # state to the presenter. Both errors therefore render the same
+        # RFC-shaped sentence, and `AccountLockedError#lock_reason` (operator
+        # text for logs and admin screens) is never surfaced. The specific
+        # reason belongs in the host's ACCOUNT_LOCKED / ACCOUNT_DEACTIVATED
+        # subscriber, server-side.
+        def handle_account_unusable(_error)
+          render json: {
+            error: "invalid_grant",
+            error_description: "The provided authorization grant is invalid, expired or revoked"
+          }, status: :bad_request
+        end
       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.1"
+  VERSION = "0.37.0"
 end

metadata

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