standard_id 0.35.0 → 0.36.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5e5289f6f264b4175abb757c1423d9fc656e5b2e5057239e7486d843a3eaf7a
-  data.tar.gz: 209d3a72e8a16049ef1e633216c38939e69518e526baea0110dd99567ac23083
+  metadata.gz: 5519e19cd0f121d012683a24a10d0052ce4bf33e508ede831712db3851abace9
+  data.tar.gz: 9786b159f6ad07238cb7e636f3cfd5e028ec31cb6014f38e0349de3760f0deaf
 SHA512:
-  metadata.gz: bdc0a65782aa7ea1299b49b0eb946dc72e56391de6e7d5132b65e59e27281d9d16a5ef28e1d75fadca282768d853a95d703b1c81278b8008699ddfeb05ab02e1
-  data.tar.gz: ed73c2092285091f034f9d0b33423e4013004a6e129c37220d8a004f94e3c9bb79b1d9d95679f4e18f126db28243201f80cc7126780225e5114b6439a74ff214
+  metadata.gz: b18d51d0fc882c6aaf4c9a6482e58600bf82594860715c1b6f5850dd0175834f72dc5735dbb23b2e1f45fbc4ceb8f975dffdc2484a3ee1871b882e89d76c4df6
+  data.tar.gz: 7039cfdf1894c351a3802b893e31a2ff23754acd0a861116b190ca5875540a7ba45d35589cefef79ad1a65444feca3eb999740285bc5af0bd073139d41fdedbc

data/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+### Fixed
+
+- **`StandardId::Api::BaseController` now answers `401` — not `500` — when the authenticated account is deactivated or locked.** 0.36.0 made `AccountStatus` / `AccountLocking` fire on a live authenticated request for the first time, which is the intended behaviour. But `AccountDeactivatedError` and `AccountLockedError` are bare `StandardError` subclasses, under neither `InvalidSessionError` nor `OAuthError`, and the API base controller rescued only those three families. So the very change that started refusing a disabled account's bearer token turned every route under `ApiEngine` — `/api/v1/sessions`, `/api/v1/userinfo`, all of it — into an unhandled exception for that account. Every consumer mounting `ApiEngine` inherited it. Before 0.36.0 the guard was inert on that path, so the hole existed but was unreachable; the release is what exposed it.
+
+  Observed independently in two consumers during the 0.36.0 rollout: `luminality-web`, which has an app-side handler on `Api::ErrorHandling` and so saw only the *gem-owned* routes fail, and `sidekick-web`, which has none and saw its whole API tree fail.
+
+  A 500 is not a refusal. It carries no `WWW-Authenticate`, tells the client nothing about discarding a token that will never work again, and pages the on-call for a routine account state. Both errors now render the established bearer shape — `401`, `{ "error": "invalid_token", "error_description": … }`, plus the matching `WWW-Authenticate` challenge — via the same `render_bearer_unauthorized!` the other credential failures use. No new response shape was invented.
+
+  **Why `invalid_token`.** RFC 6750 §3.1 defines exactly three codes. `invalid_token` covers a token "expired, revoked, malformed, or **invalid for other reasons**", and a token whose subject account has been disabled is invalid for one of those other reasons; it also carries the right client instruction — discard the token and re-authenticate — which is precisely correct here, since no retry with this token can ever succeed. `insufficient_scope` (403) would be wrong twice over: nothing about this is a scope failure, and 403 invites a client to keep the token and retry. `invalid_request` (400) would be wrong because the request is perfectly well-formed.
+
+  `AccountLockedError#lock_reason` is **not** surfaced. It is operator-authored text meant for logs and admin screens, and `WWW-Authenticate` is a quoted string that arbitrary text would break as well as leak. A spec pins that the reason appears in neither the body nor the header.
+
+### Unchanged, deliberately — two decisions worth knowing about
+
+- **The `WebEngine`'s own routes (`/sessions`, `/account`, `/logout`) get no gem-side handler, and this is not an oversight.** `StandardId::Web::BaseController` descends from the **host's** `ApplicationController`, so the `rescue_from StandardId::AccountDeactivatedError` the README has always told hosts to write already covers those routes. A gem handler there would not add safety, it would remove it: Rails scans `rescue_handlers` most-recently-registered-first, and a subclass registers after its parent, so anything the gem registered on `Web::BaseController` would outrank and silently override the host's — replacing a host's "your account has been deactivated" page with whatever the gem chose. `Api::BaseController` has no such escape hatch; descending from `ActionController::API`, there is nowhere in its ancestry for a host to put a handler, which is exactly why only that side is rescued in the gem.
+
+  **Hosts must therefore still carry their own `ApplicationController` handler for these two errors.** If you do not have one, a deactivated or locked account hitting a web route — yours or the engine's — is an unhandled exception. That was true before 0.36.0 for the sign-in path and remains true; 0.36.0 simply widened the set of requests that can reach it from "sign-in and token mint" to "any authenticated request". The README's account sections now spell out which routes the engine answers for and which it does not.
+
+- **`AccountDeactivatedError` / `AccountLockedError` still descend from `StandardError`, not from `InvalidSessionError`.** Reparenting them was considered as the broader fix — it would make every consumer's existing `rescue_from StandardId::InvalidSessionError` catch them automatically, with no consumer change at all — and rejected on two grounds. First, they mean something genuinely different: an `InvalidSessionError` says the credential is no good and the remedy is to sign in again, while these say the credential is fine and the account is disabled, where signing in again will not help and the user needs to be told so. Consumers who deliberately distinguish the two would lose that distinction silently. Second, and decisively, it would hijack handlers hosts have already written: `Web::BaseController` registers `rescue_from NotAuthenticatedError, InvalidSessionError, with: :redirect_unauthenticated_to_login`, so under the reparented hierarchy a host's `rescue_from AccountDeactivatedError` — registered *earlier*, on the parent — would lose to the gem's subclass registration, and every consumer following the README would start bouncing disabled users to `/login` instead of to their account-disabled page. A patch release that quietly re-routes a documented UX is not a patch. The narrow fix leaves both hierarchies and both sets of host handlers exactly as they were.
+
+### Testing
+
+`spec/requests/standard_id/live_session_account_guard_spec.rb` gains three API examples (401 shape for deactivated, 401 shape for locked, and `lock_reason` non-disclosure) and two web examples pinning the delegate-to-host design above. Proven by negative control: with the two `rescue_from` lines deleted from `Api::BaseController`, the three API examples fail with the raw error escaping the request; restored, the file is 14/14 and the suite 2097/2097.
+
+Relates to rarebit-one/rarebit-ops#306.
+
+## [0.36.0] - 2026-08-04
+
+### Security
+
+- **`SESSION_VALIDATING` now carries the `account:` its subscribers guard on, so `AccountStatus` and `AccountLocking` finally stop a LIVE authenticated request.** Both concerns subscribe to `OAUTH_TOKEN_ISSUING`, `SESSION_CREATING` and `SESSION_VALIDATING` and branch on `event[:account]&.inactive?` / `&.locked?`. Neither publisher of `SESSION_VALIDATING` ever sent an `account:` — `Web::AuthenticationGuard#emit_session_validating` and `Api::AuthenticationGuard#emit_session_validating` both published `session:` alone. `Events#enrich_payload` injects `:current_account`, a *different* key, so `event[:account]` was `nil` and that leg of both guards never fired.
+
+  That it was an omission rather than a design is plain from the sibling emitters in the same two files: `emit_session_validated` and `emit_session_expired` each pass `account:`. Only the *validating* hook — the one that runs before the request is allowed to proceed, and therefore the only one of the three that can stop it — left it out.
+
+  **Upgrade implication — expect previously-working sessions and tokens to start failing. That is the fix.** Three shapes were getting through and now do not:
+
+  1. **API bearer tokens, the big one.** `AccountStatusSubscriber` / `AccountLockingSubscriber` revoke `account.sessions.active` on `deactivate!` / `lock!`, but an access token is a stateless JWT with no `Session` row — revoking sessions does nothing to it. Until its `exp`, `SESSION_VALIDATING` was the only thing that could refuse it, and it was inert. Any client holding an access token minted before the account went bad kept working; it now gets `AccountDeactivatedError` / `AccountLockedError` on the next request.
+  2. **A status change that skips the callbacks** — `update_all`, `update_column`, a data migration, direct SQL, an admin bulk action. No `ACCOUNT_DEACTIVATED` / `ACCOUNT_LOCKED` event fires, so no session revocation happens, and the browser session stayed live until it expired.
+  3. **A session minted after the account went bad by a path that emits no `SESSION_CREATING`.** `Web::SessionManager#load_session_from_remember_token` calls `create_browser_session` directly and publishes nothing, so remember-me re-auth walked straight past the sign-in guard.
+
+  Hosts that lock or deactivate accounts should expect support traffic from users whose sessions used to survive. `sidekick-web`'s `LockAccountModal` copy — *"The user will be immediately locked out / All active sessions will be terminated"* — is now true rather than aspirational.
+
+  **No new query on either hot path.** The web guard reads the `:account` association only when it is already loaded (`SessionManager` loads the session with `eager_load(:account)`) and otherwise falls back to a single indexed `find_by` — it must never lazily touch the association, because several consumers run `strict_loading_by_default` and this emitter is on the path of *every* authenticated request, where a `StrictLoadingViolationError` would turn an inert guard into a 500. It also runs *before* the blank/expired/revoked checks, so it handles a nil session. The API guard threads its `SessionManager` through to reuse the memoized, strict-loading-cleared `#current_account` that `emit_session_validated` resolves anyway.
+
+  The spec that let this survive for so long asserted enforcement by publishing `SESSION_VALIDATING` **by hand** with the very key the real publisher omitted — proof that the subscriber reacts to a correctly-shaped payload, not that any caller produces one. Those examples now drive the real guards over real HTTP requests (`spec/requests/standard_id/live_session_account_guard_spec.rb`), and were confirmed to fail with the `account:` key removed.
+
+  Tracked in rarebit-one/rarebit-ops#306.
+
+### Added
+
+- **`POST /oauth/revoke` logs a warning when `revocation_scope: :grant` resolves a presented `jti` to no `RefreshToken`.** Under `:grant`, presenting an access token is a deliberate no-op that still answers 200 (RFC 7009 §2.2) — correct, because access tokens are stateless and never persisted, but until now completely silent. A client that only ever presents access tokens looked like it was revoking when it was not. As `:grant` is adopted across the estate, post-flip no-ops need to be visible. Emitted via `StandardId.logger&.warn`, consistent with the existing `revocation_scope` fallback warning. No behaviour change. Relates to rarebit-one/rarebit-ops#304.
+
 ## [0.35.0] - 2026-07-31
 
 ### Security

data/README.md

@@ -784,7 +784,14 @@ User.inactive   # => Users with status 'inactive'
 
 ### Handling AccountDeactivatedError
 
-When an inactive account attempts to authenticate, `StandardId::AccountDeactivatedError` is raised. You need to handle this error in your application controller:
+When an inactive account attempts to authenticate — at sign-in, at token mint, and (since 0.36.0) on every request made with an already-issued credential — `StandardId::AccountDeactivatedError` is raised. You need to handle this error in your application controller:
+
+> **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.
+> - **`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.
 
 ```ruby
 # app/controllers/application_controller.rb
@@ -900,7 +907,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:
+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.
 
 ```ruby
 # app/controllers/application_controller.rb

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

@@ -16,6 +16,16 @@ module StandardId
       rescue_from StandardId::InvalidSessionError, with: :handle_invalid_session
       rescue_from StandardId::OAuthError, with: :handle_oauth_error
 
+      # AccountStatus / AccountLocking raise these from the SESSION_VALIDATING
+      # subscriber, i.e. mid-request on an ALREADY authenticated call, not just
+      # at sign-in or token mint. Unrescued they are a 500 on every gem-owned
+      # API route. Unlike Web::BaseController — which descends from the host's
+      # ApplicationController, so a host `rescue_from` covers it — this class
+      # descends from ActionController::API, so the host has nowhere to put a
+      # handler in the ancestry and the gem must answer for itself.
+      rescue_from StandardId::AccountDeactivatedError, with: :handle_account_deactivated
+      rescue_from StandardId::AccountLockedError, with: :handle_account_locked
+
       protected
 
       def validate_content_type!
@@ -43,6 +53,27 @@ module StandardId
         render_bearer_unauthorized!(error_description: default_invalid_token_message)
       end
 
+      # RFC 6750 §3.1 offers exactly three error codes, and `invalid_token` is
+      # the right one: it covers a token "expired, revoked, malformed, or
+      # invalid for other reasons", and a bearer token whose subject account has
+      # been disabled is invalid for one of those other reasons. It also carries
+      # the correct client instruction — discard the token and re-authenticate —
+      # which is what we want, since no retry with this token will ever succeed.
+      # `insufficient_scope` (403) would be wrong: nothing here is about scope,
+      # and a 403 invites the client to keep the token and retry. `invalid_request`
+      # (400) would be wrong: the request is well-formed.
+      def handle_account_deactivated(_error)
+        render_bearer_unauthorized!(error_description: "The account is deactivated")
+      end
+
+      # Deliberately does NOT surface `error.lock_reason`. It is operator-authored
+      # text intended for logs and admin screens (see StandardId::AccountLockedError),
+      # and the WWW-Authenticate header this renders into is a quoted string that
+      # arbitrary text would break as well as leak.
+      def handle_account_locked(_error)
+        render_bearer_unauthorized!(error_description: "The account is locked")
+      end
+
       def handle_oauth_error(error)
         render json: {
           error: error.oauth_error_code,

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

@@ -93,10 +93,27 @@ module StandardId
             .where(token_digest: StandardId::RefreshToken.digest_for(jti))
             .includes(:session, :account)
             .first
+          # No persisted grant for this jti. Per RFC 7009 §2.2 the endpoint
+          # still answers 200, and for an access token that is the correct
+          # no-op (access tokens are stateless JWTs and are never persisted).
+          # But under :grant the no-op is otherwise completely silent, so a
+          # client that only ever presents access tokens looks like it is
+          # revoking when it is not. Log it so post-flip no-ops are visible.
+          if record.nil?
+            StandardId.logger&.warn(
+              "[StandardId::Revocations] revocation_scope=:grant — presented jti " \
+              "resolved to no RefreshToken for account #{payload[:sub]}; nothing " \
+              "revoked (RFC 7009 §2.2 still returns 200). This is expected when " \
+              "an access token is presented; present the refresh token for " \
+              "revocation to take effect."
+            )
+            return
+          end
+
           # A jti that resolves to another subject's grant must never revoke
           # it — the token was signature-verified, but bind the two identities
           # anyway rather than trusting a single claim.
-          return if record.nil? || record.account_id.to_s != payload[:sub].to_s
+          return if record.account_id.to_s != payload[:sub].to_s
 
           refresh_tokens_revoked = record.revoke_family!
 

data/lib/standard_id/api/authentication_guard.rb

@@ -3,7 +3,7 @@ module StandardId
     class AuthenticationGuard
       def require_session!(session_manager, request: nil)
         api_session = session_manager.current_session
-        emit_session_validating(api_session, request)
+        emit_session_validating(api_session, request, session_manager: session_manager)
 
         if api_session.blank?
           raise StandardId::NotAuthenticatedError, "Invalid or missing access token"
@@ -55,10 +55,16 @@ module StandardId
         end
       end
 
-      def emit_session_validating(api_session, request)
+      # Mirrors emit_session_validated/expired below. The session_manager is
+      # threaded through so resolve_account takes its memoized, strict-loading-
+      # cleared #current_account rather than a lazy `api_session.account` —
+      # this emitter runs on every authenticated request, before the
+      # blank/expired/revoked checks, so it must not be able to raise.
+      def emit_session_validating(api_session, request, session_manager: nil)
         StandardId::Events.publish(
           StandardId::Events::SESSION_VALIDATING,
-          session: api_session
+          session: api_session,
+          account: resolve_account(api_session, session_manager)
         )
       end
 

data/lib/standard_id/errors.rb

@@ -7,6 +7,31 @@ module StandardId
   class RevokedSessionError < InvalidSessionError; end
 
   # Account errors
+  #
+  # These deliberately do NOT descend from InvalidSessionError, even though
+  # doing so would make every host's existing `rescue_from InvalidSessionError`
+  # catch them for free. Two reasons:
+  #
+  #   1. They mean something different. An InvalidSessionError says the
+  #      credential is no good — expired, revoked — and the remedy is to sign in
+  #      again. These say the credential is fine and the ACCOUNT is disabled;
+  #      signing in again will not help, and the user needs to be told so.
+  #      Hosts document that distinction in their UX (see the README's
+  #      "Handling AccountDeactivatedError" / "Handling AccountLockedError").
+  #   2. Reparenting them would silently HIJACK the handlers hosts already
+  #      wrote. Web::BaseController registers
+  #      `rescue_from NotAuthenticatedError, InvalidSessionError, with:
+  #      :redirect_unauthenticated_to_login`, and Rails resolves rescue_from
+  #      handlers most-recently-registered-first — a subclass's registration
+  #      wins over its parent's. A host's `rescue_from AccountDeactivatedError`
+  #      on ApplicationController is registered EARLIER than the gem's
+  #      subclass registration, so as a subclass of InvalidSessionError these
+  #      would start bouncing to /login instead of reaching the host's
+  #      account-deactivated page. That is a behaviour regression for every
+  #      consumer who followed the README.
+  #
+  # Consequently every entry point that must not raise has to rescue these
+  # explicitly; StandardId::Api::BaseController does.
   class AccountDeactivatedError < StandardError; end
 
   class AccountLockedError < StandardError

data/lib/standard_id/version.rb

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

data/lib/standard_id/web/authentication_guard.rb

@@ -27,7 +27,8 @@ module StandardId
       def emit_session_validating(browser_session, request)
         StandardId::Events.publish(
           StandardId::Events::SESSION_VALIDATING,
-          session: browser_session
+          session: browser_session,
+          account: resolve_account(browser_session)
         )
       end
 
@@ -47,6 +48,37 @@ module StandardId
           expired_at: browser_session.expires_at
         )
       end
+
+      # SESSION_VALIDATING is the only one of the three emitters that runs
+      # BEFORE the blank/expired/revoked checks, so it cannot borrow the
+      # assumptions its siblings rely on:
+      #
+      #   * the session may be nil (the blank? check has not run yet), so a
+      #     bare `browser_session.account` would NoMethodError; and
+      #   * it also fires for sessions the host app installed into
+      #     `Current.session` itself, which — unlike SessionManager's
+      #     `eager_load(:account)` path — carries no loaded :account
+      #     association. Several consumers run `strict_loading_by_default`
+      #     (jumpdrive-web, luminality-web), where a lazy `record.account`
+      #     raises StrictLoadingViolationError. Since this emitter is on the
+      #     path of EVERY authenticated request, that would turn an inert
+      #     guard into a 500.
+      #
+      # So: read the association only when it is already loaded, and otherwise
+      # fall back to the same single indexed lookup Api::AuthenticationGuard's
+      # resolve_account uses. Neither branch can raise under strict loading.
+      def resolve_account(browser_session)
+        return if browser_session.blank?
+
+        if browser_session.respond_to?(:association) && browser_session.association(:account).loaded?
+          return browser_session.account
+        end
+
+        account_id = browser_session.account_id if browser_session.respond_to?(:account_id)
+        return if account_id.blank?
+
+        StandardId.account_class.find_by(id: account_id)
+      end
     end
   end
 end

metadata

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