standard_id 0.36.0 → 0.36.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dd8850abb672f638f6db5cf4d60ae8ec64b26bdb8d5835405c72e7bebc4d800
-  data.tar.gz: 69575f6669362c905ed16059f35f15044f1ee2bbade449b6dc5c62bfd93caeb5
+  metadata.gz: e6ea917e3795560901ae1213d21a172e84fb836ecd6885f96f99c138291ffd40
+  data.tar.gz: e4582d67367ee6026bc058ffb60a17ee729fb23635318c3acec42a153b0d2b19
 SHA512:
-  metadata.gz: 87ed7e67e16666c2c576a2e7bb55e43ff2a861ecf93c824d5995da4d8f383d09f4bb60e8b389e9821e2d85acfb849690548cc0e6fbfabaa3e73d0f02dd44015c
-  data.tar.gz: 9036f22d16ee08ac97a4e5d6ae46d8c6fc7c63130da4ed66a815dfef2b21ecce787f576cc2127dbd6040405e6a6dbd2f4f71c5303d1c6e803770347af6d85b9f
+  metadata.gz: b00ae747d7337e330bf1187f600d8a979c345ea64b72a438657ee28c37d0e685ef00205f4db5726532be0f8db04c3c6386ef98322420ba290999d63b80f9ff80
+  data.tar.gz: d7c7f079b61c66c65f7c76d5f214e08f11643359199f2cc8b28192b41eff175431a9d8826c224363f94f71adecbd59ff81ff6dd6594d89c15d5498f558b9aebf

data/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+### 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

data/README.md

@@ -784,7 +784,26 @@ 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` 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
@@ -900,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:
+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/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/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/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.36.0"
+  VERSION = "0.36.2"
 end

metadata

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