standard_id 0.47.0 → 0.48.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c487f3a2265110f88e093a27b30e78742ecc04cbf460e94cbe35df02dbd2621
-  data.tar.gz: 6ad0ecc9edb3a9c2e5cbc51096ac08f6164b7bcb4671098f85806d3a1f605f6e
+  metadata.gz: cdf22579e98c4ceb592cb20766d510d937d0e5d2f7f70c41074f984ddc3b0393
+  data.tar.gz: 35fbb21a24d40a307bd55279a86fa0d91549641e30f30d4101d667d9c5d7c793
 SHA512:
-  metadata.gz: 818624622fef93866c46945cbe85c5a5e5898aea0d9770dab65596ab2524f03470f3f51b26286cea93a3cca639823be9566a7ef270cdbeec34794c6ebd4772e0
-  data.tar.gz: cea418b10ae16fa7d90caa16dfc4c394aa9445d4b6085380d38950c15c1d381a17b7bace3e786327fd21ac82b165525a95ad73b72a087b6cbb0b3c78ef13bf4a
+  metadata.gz: cd202ffabe7287cb374442e6aeee83d0f2853a17d9cb7654ba816f28f48c4d6970b859b7d4d83581f09ef4a2793689b5fc620b545246bfb515691fda9a4cd1dd
+  data.tar.gz: 0e17bfff08af26fc343dedaf0d9500bbef69fe118031c305bdc29f33ede7231c8641c14b2b6156395702c4957c58b605dc6a24b54b4f975fa19618c8f4cade01

data/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.48.1] - 2026-10-20
+
+### Added
+
+- **`StandardId::RetryDelayError`** (an `InvalidRequestError`, with `retry_after` seconds) is what the OTP resend cooldown (`passwordless.retry_delay`) now raises, and **`Otp.issue` reports it as `error_code: :cooldown`** instead of the generic `:invalid_request`. A host that wraps `Otp.issue` can tell "a usable code was issued moments ago" apart from a real failure and keep its own cooldown copy — which is what fundbright-web needed before it could drop its advisory lock around `Otp.issue` now that the cooldown check is atomic (0.48.0). Every existing `rescue StandardId::InvalidRequestError` keeps working.
+
+## [0.48.0] - 2026-10-20
+
+### Added
+
+- **Refresh tokens are bound to their `ClientApplication`**, and the `refresh_token` grant refuses a token whose application has been deactivated or deleted. Migration `20261020000000_add_client_application_id_to_standard_id_refresh_tokens` adds the nullable column; each grant records the application its `client_id` resolved to (authorization_code, client_credentials, any grant whose `client_id` names one) and every rotation copies it to the successor. The refusal is the same 400 `invalid_grant` / "Refresh token is no longer valid" every other dead token gets, so a leaked token learns nothing from it. Deactivation suspends (reactivating the application restores its tokens, with one deliberate exception: a replayed, already-rotated token still trips reuse detection and revokes its family, suspended or not); deletion is final. A row minted before the migration ran is bound lazily on its next rotation by `client_id`, and refused meanwhile if an application with that `client_id` exists and is inactive. A token whose `client_id` is not a registered application (social sign-in refreshes as the provider's name) is untouched. `/oauth/introspect` reports a refresh token bound to a gone or deactivated application as inactive. Replaces the host-side prepend sidekick-web carried as `config/initializers/standard_id_refresh_client_guard.rb` (core-platform-brain#490), which can be deleted once this is installed. `ClientApplication#refresh_tokens` is the new association; there is deliberately no foreign key, so a deleted application stays detectable from the token's side.
+- **`c.inactive_account_status`** (symbol, default `:inactive`): the enum key `StandardId::AccountStatus` declares for a deactivated account, and so its stored value and predicate. A host whose status column already says `"suspended"` sets `:suspended` and adopts the concern — `suspended?`, the `suspended` scope, `deactivate!`, and the OAUTH_TOKEN_ISSUING / SESSION_CREATING / SESSION_VALIDATING guard (which then raises `AccountDeactivatedError, "Account is suspended"`) — without renaming a database enum value under running processes. `inactive?` stays as an alias; `:active` itself is refused with a `ConfigurationError` at include time. `activate!` / `deactivate!` stamp `activated_at` / `deactivated_at` only when the columns exist. Replaces the hand-rolled subscriber fundbright-web carries in its initializer (fundbright/delivery-ops#438).
+- **`c.oauth.introspection_liveness`** (callable, default nil) and **`c.oauth.introspection_claims`** (array, default `[]`): `/oauth/introspect` runs the host's own liveness check after the gem's (signature, expiry, refresh-token row, parent session, bound ClientApplication) and renders the bare `{"active": false}` on a falsy answer or an exception (logged); and echoes the named extra claims (`profile_type`, `gid`, …) on an active response, standard members winning. Lets sidekick-web delete its app-owned RFC 7662 controller (187 lines + spec), which existed to re-check the token's profile row and return those two claims.
+- **`ClientApplication.live`**: the scope form of `#active?` (`active` AND no `deactivated_at`), now what `RefreshToken#client_application_live?` queries, so there is one definition of a live application.
+- **Lib-level OTP start limits**: `c.rate_limits.otp_start_per_target` (default 5 per 15 minutes, keyed per realm + channel + address) and `c.rate_limits.otp_start_per_ip` (per hour, default 0 = off) are enforced inside `Passwordless::BaseStrategy#start!`, so they hold for a host that drives `generate_passwordless_otp`, `StandardId::Otp.issue` or the strategy from its own controllers, operations or jobs — paths the engine's controller-level limits never see. Counted on the same store as those (`StandardId::RateLimiter::STORE`, which `RateLimitHandling::RATE_LIMIT_STORE` now aliases). A tripped limit raises the new `StandardId::RateLimitExceededError` (an `InvalidRequestError`; 429 `rate_limit_exceeded` with `Retry-After` from the API error handler, a flash on the web login page, `error_code: :rate_limited` from `Otp.issue`). Raise it alongside any controller per-target limit you raise, or it becomes the binding one. The per-target default equals the API's existing per-target limit, so an API caller sees no change; the per-IP limit is opt-in because the right ceiling depends on how many real users share an address.
+
+### Changed
+
+- **The OTP resend cooldown is atomic.** `BaseStrategy#start!` now runs the `retry_delay` check and the challenge insert in one transaction, serialised per (realm, channel, address) with a PostgreSQL transaction-scoped advisory lock (a no-op on other adapters). Two concurrent starts for one address used to both pass the check and both issue, and creating the second code invalidated the first, so the user held a dead one (fundbright delivery-ops#345; fundbright-web wraps `Otp.issue` in its own advisory lock for this and can stop). `PASSWORDLESS_CODE_REQUESTED` is published once that transaction has committed (still before `PASSWORDLESS_CODE_GENERATED`), so a subscriber's own writes cannot be rolled back with a failed insert; the flip side is that a subscriber which raises now leaves the user with an invalidated previous code and no new one delivered, so subscribers to this event should not raise.
+
+### Fixed
+
+- **The mobile bounce (`POST /auth/callback_mobile/:provider`) no longer corrupts every relayed key after the first.** Its page wrote the redirect URL into a JS string with `j()`, which ERB then HTML-escaped, so the browser navigated to `?code=…&amp;state=…` and each later key (`state`, `user`, `id_token`, …) arrived as `amp;<key>`. The URL is now emitted with `to_json`.
+- **The mobile bounce relays `error`.** Apple posts `error=user_cancelled_authorize` (and no code) when the user backs out; the app now receives it, so it can tell a cancel from a failure.
+
+### Upgrade
+
+- Run `bin/rails standard_id:install:migrations && bin/rails db:migrate`. Until the column exists the gem neither writes nor reads the binding, and the boot-time migration check names it. Deactivated applications are refused by `client_id` lookup even before the migration; deleted ones need the column. Tokens minted before the migration whose application had **already been deleted** cannot be told from a provider-named token and keep rotating, unbound, until `refresh_token_lifetime` expires them; revoke their sessions by hand if that is too long.
+
 ## [0.47.0] - 2026-10-19
 
 ### Added

data/README.md

@@ -207,6 +207,18 @@ StandardId.configure do |config|
 end
 ```
 
+Refresh tokens are **bound to the `ClientApplication`** their grant resolved
+(`standard_id_refresh_tokens.client_application_id`, since 0.48). Deactivating
+the application suspends every refresh token it was issued — the grant answers
+the generic `invalid_grant` — and reactivating it restores them (a replayed,
+already-rotated token still trips reuse detection meanwhile and revokes its
+family, as it always did); deleting the application ends them for good, which
+is what makes RFC 7592 `DELETE` on a dynamically registered client an actual
+revocation. A token whose `client_id`
+is not a registered application (social sign-in refreshes as the provider's
+name) has no application to share a fate with and is left alone. There is no
+setting: this is how the grant behaves once the migration has run.
+
 Under `:grant`, revoking a **stateless access token is a no-op** — this engine
 has no per-access-token store, so it cannot invalidate one before its `exp`
 (the response is still `200`, per RFC 7009 §2.2). Clients that need revocation
@@ -217,6 +229,40 @@ a wrong hint must not change the outcome.
 `ServiceSession`s are never touched by `/oauth/revoke` under either setting —
 machine credentials have their own lifecycle.
 
+### Token Introspection (RFC 7662)
+
+`POST /oauth/introspect` is off by default (`config.oauth.introspection_enabled`);
+once on, confidential clients can ask whether a token is live. The gem checks
+the signature and expiry, and for a refresh token also its row, its parent
+session and the `ClientApplication` it is bound to. Two settings let the host
+add what only it knows:
+
+```ruby
+StandardId.configure do |config|
+  config.oauth.introspection_enabled = true
+
+  # Run after the gem's checks pass. Takes any subset of payload:,
+  # refresh_token: (nil for an access token) and request:. Falsy — or an
+  # exception, which is logged — renders {"active": false}.
+  config.oauth.introspection_liveness = ->(payload:) {
+    next true if payload[:gid].blank?   # a token with no host row to check (client_credentials)
+
+    profile = GlobalID::Locator.locate(payload[:gid])
+    profile.present? && profile.active?
+  rescue ActiveRecord::RecordNotFound  # the row was deleted: inactive, and no log line needed
+    false
+  }
+
+  # Extra claims echoed VERBATIM on an ACTIVE response, beyond the RFC 7662
+  # members — list scalar claims. Absent claims are omitted; the standard
+  # members cannot be overridden.
+  config.oauth.introspection_claims = %w[profile_type gid]
+end
+```
+
+Access tokens are stateless, so a revoked session's access token still
+introspects as active until its `exp`; keep `access_token_lifetime` short.
+
 ### Authenticating Opaque Session Tokens
 
 `Session.by_token` is a **lookup**, not authentication: it matches the SHA256
@@ -717,7 +763,7 @@ Every StandardId event automatically carries tracing metadata (`event_id`, `time
 |  | `oauth.token.issued` | `access_token_id`, `grant_type`, `client_id`, `account`, `expires_in` | After tokens are generated |
 |  | `oauth.token.refreshed` | `old_token_id`, `new_token_id`, `client_id`, `account` | After a refresh token is redeemed |
 |  | `oauth.code.consumed` | `authorization_code`, `client_id`, `account` | After an authorization code is exchanged |
-| Passwordless | `passwordless.code.requested` | `identifier`, `channel` (email/sms) | Before generating an OTP |
+| Passwordless | `passwordless.code.requested` | `identifier`, `channel` (email/sms), `realm` | After the challenge row is committed, before `code.generated` / delivery. Subscribers should not raise: the previous code is already invalidated by then |
 |  | `passwordless.code.generated` | `code_challenge`, `identifier`, `channel`, `expires_at` | After an OTP is created |
 |  | `passwordless.code.sent` | `identifier`, `channel`, `realm`, `delivery_status` | After an OTP is handed to delivery (not for `Otp.issue(delivery: :manual)`). `delivery_status`: `"sent"` (built-in mailer enqueued it), `"failed"` (built-in mailer was responsible but did not enqueue), `"delegated"` (a host `PASSWORDLESS_CODE_GENERATED` subscriber delivers — the engine can't confirm it) |
 |  | `passwordless.code.verified` | `code_challenge`, `account`, `channel` | After OTP verification succeeds |
@@ -932,6 +978,15 @@ end
 
 The concern works with both PostgreSQL enum and string columns - Rails enum handles both transparently.
 
+If your column already carries a different value for a deactivated account,
+keep it: `c.inactive_account_status = :suspended` (set in the initializer,
+before the model loads) makes the concern declare `{ active: "active",
+suspended: "suspended" }`, so `suspended?`, the `suspended` scope and
+`deactivate!` all use your word, and the sign-in / token / live-session guard
+raises `AccountDeactivatedError, "Account is suspended"`. `inactive?` remains as
+an alias. `activated_at` / `deactivated_at` are stamped only when the columns
+exist.
+
 ### Usage
 
 ```ruby
@@ -1684,6 +1739,33 @@ bundle exec rspec spec/controllers/
   rejected with `invalid_request`.
 - Rate limiting on authentication endpoints
 
+## OTP Start Limits
+
+The engine's controllers throttle their own OTP endpoints (`rate_limits.api_passwordless_start_*`,
+`login_per_*`, `verification_start_*`). A host that drives the passwordless strategy from its own
+controllers, an operation or a job (`generate_passwordless_otp`, `StandardId::Otp.issue`) never
+passes those, so two limits are enforced inside the strategy itself, on the same store:
+
+```ruby
+StandardId.configure do |config|
+  config.rate_limits.otp_start_per_target = 5   # per (realm, channel, address), per 15 minutes; 0 = off
+  config.rate_limits.otp_start_per_ip     = 0   # per hour; off by default — pick a ceiling that fits CGNAT/office traffic
+end
+```
+
+A tripped limit raises `StandardId::RateLimitExceededError` (an `InvalidRequestError` that the API
+error handler renders as `429 rate_limit_exceeded` with `Retry-After`, the web login page shows as a
+flash, and `Otp.issue` returns as a failed result with `error_code: :rate_limited`). The per-target
+default matches the API's `api_passwordless_start_per_target`; if you raise that (or `login_per_email`)
+raise `otp_start_per_target` with it, or it becomes the binding limit.
+
+The resend cooldown (`passwordless.retry_delay`) is reported separately from those limits:
+`StandardId::RetryDelayError` (an `InvalidRequestError` carrying `retry_after` seconds), which
+`Otp.issue` returns as `error_code: :cooldown`, so a host can tell "a code is already on its way"
+apart from a failure. The 30-second resend
+cooldown (`passwordless.retry_delay`) and the challenge insert run in one transaction, serialised per
+address with a PostgreSQL advisory lock, so two concurrent starts cannot both issue a code.
+
 ## Missing Migrations
 
 `standard_id:install:migrations` copies the engine's migrations with new timestamps, so a gem migration that was never copied is invisible to Rails' own pending-migration check. StandardId checks for that itself, by migration name:

data/app/controllers/concerns/standard_id/rate_limit_handling.rb

@@ -2,7 +2,9 @@ module StandardId
   module RateLimitHandling
     extend ActiveSupport::Concern
 
-    RATE_LIMIT_STORE = StandardId::RateLimitStore.new
+    # The one store object the engine counts on, shared with the lib-level
+    # limits (StandardId::RateLimiter) so `c.cache_store` governs both.
+    RATE_LIMIT_STORE = StandardId::RateLimiter::STORE
 
     # Fallback window for the Retry-After header when the tripped limit's window
     # was not captured on the instance — e.g. a hand-rolled `raise

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

@@ -91,6 +91,11 @@ module StandardId
       end
 
       def handle_oauth_error(error)
+        # A lib-level rate limit (StandardId::RateLimiter) knows its window;
+        # say so, as the controller-level limits do.
+        if error.respond_to?(:retry_after) && error.retry_after.to_i.positive?
+          response.set_header("Retry-After", error.retry_after.to_i.to_s)
+        end
         render json: {
           error: error.oauth_error_code,
           error_description: error.message

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

@@ -105,6 +105,12 @@ module StandardId
           end
           return render_inactive if persisted && !persisted.active?
           return render_inactive if persisted&.session && !persisted.session.active?
+          # ...and whose ClientApplication is gone or deactivated, which the
+          # refresh grant refuses too (#validate_client_application_liveness!).
+          return render_inactive if persisted && !persisted.client_application_live?
+          # ...and whatever the host knows that the gem cannot (a claim that
+          # points at a host row which has since been deactivated).
+          return render_inactive unless host_liveness?(payload, persisted)
 
           render json: active_response(payload, persisted), status: :ok
         end
@@ -155,10 +161,30 @@ module StandardId
           nil
         end
 
+        # `config.oauth.introspection_liveness`, when set. Called with the
+        # subset of payload:/refresh_token:/request: its signature accepts.
+        # Anything but a truthy answer — including an exception, which is
+        # logged — is inactive: a check that cannot answer must not say yes.
+        def host_liveness?(payload, persisted)
+          callable = StandardId.config.oauth.introspection_liveness
+          return true unless callable.respond_to?(:call)
+
+          context = { payload: payload, refresh_token: persisted, request: request }
+          !!callable.call(**StandardId::Utils::CallableParameterFilter.filter(callable, context))
+        rescue StandardError => e
+          # StandardId.logger, not config.logger: the latter is nil unless the
+          # host set it, and a broken hook that silently turns every token
+          # inactive would otherwise look like an outage with no signal.
+          StandardId.logger&.error("[StandardId] oauth.introspection_liveness raised: #{e.class}: #{e.message}")
+          false
+        end
+
         # RFC 7662 §2.2. `.compact` so absent claims are omitted rather than
-        # emitted as null.
+        # emitted as null. Host-configured extra claims
+        # (`config.oauth.introspection_claims`) come first so the standard
+        # members always win.
         def active_response(payload, persisted)
-          {
+          extra_claims(payload).merge(
             active: true,
             token_type: persisted ? "refresh_token" : "Bearer",
             sub: payload[:sub],
@@ -169,7 +195,15 @@ module StandardId
             jti: payload[:jti],
             client_id: payload[:client_id],
             scope: payload[:scope]
-          }.compact
+          ).compact
+        end
+
+        def extra_claims(payload)
+          names = Array(StandardId.config.oauth.introspection_claims).map(&:to_s)
+          return {} if names.empty?
+
+          claims = payload.to_h.with_indifferent_access
+          names.to_h { |name| [name.to_sym, claims[name]] }.compact
         end
 
         def render_inactive

data/app/controllers/standard_id/web/auth/callback/providers_controller.rb

@@ -210,8 +210,11 @@ module StandardId
             redirect_to StandardId::WebEngine.routes.url_helpers.login_path(redirect_uri: redirect_uri), alert: error_message
           end
 
+          # `error` is relayed so the app can tell a cancel from a failure: Apple
+          # posts `error=user_cancelled_authorize` (with the state) when the user
+          # backs out, and no code.
           def mobile_relay_params
-            params.permit(:code, :state, :user, :userIdentifier, :id_token, :identity_token, :nonce).to_h.compact
+            params.permit(:code, :state, :user, :userIdentifier, :id_token, :identity_token, :nonce, :error).to_h.compact
           end
 
           def build_mobile_redirect(destination, extra_params)

data/app/models/standard_id/client_application.rb

@@ -16,6 +16,10 @@ module StandardId
 
     has_many :client_secret_credentials, dependent: :destroy
     has_many :authorization_codes, foreign_key: :client_id, primary_key: :client_id, dependent: :destroy
+    # Refresh tokens issued to this application (migration 20261020000000). Not
+    # a dependent association: rows outlive a deleted application on purpose,
+    # so the refresh_token grant and introspection can see that it is gone.
+    has_many :refresh_tokens, class_name: "StandardId::RefreshToken", inverse_of: :client_application
 
     accepts_nested_attributes_for :client_secret_credentials, allow_destroy: false
 
@@ -46,6 +50,11 @@ module StandardId
 
     # Scopes
     scope :active, -> { where(active: true) }
+    # The scope form of #active?: `active` AND no `deactivated_at`. The two
+    # fields are kept in step by the before_update callback, but a row where
+    # they drift (update_columns, a data fix) must read the same from a query
+    # as from the instance — the refresh grant and introspection rely on it.
+    scope :live, -> { where(active: true, deactivated_at: nil) }
     scope :confidential, -> { where(client_type: "confidential") }
     scope :public_clients, -> { where(client_type: "public") }
     scope :for_owner, ->(owner) { where(owner: owner) }

data/app/models/standard_id/refresh_token.rb

@@ -5,6 +5,12 @@ module StandardId
     belongs_to :account, class_name: StandardId.config.account_class_name
     belongs_to :session, class_name: "StandardId::Session", optional: true
     belongs_to :previous_token, class_name: "StandardId::RefreshToken", optional: true
+    # The ClientApplication this token was issued to, when the grant's client_id
+    # named one (migration 20261020000000). NULL for tokens whose client_id is
+    # not an application (social sign-in refreshes as the provider's name) and
+    # for rows minted before the column existed. No FK on purpose: a deleted
+    # application has to stay detectable as "gone" (see #client_application_live?).
+    belongs_to :client_application, class_name: "StandardId::ClientApplication", optional: true
 
     scope :active, -> { where(revoked_at: nil).where("expires_at > ?", Time.current) }
     scope :expired, -> { where("expires_at <= ?", Time.current) }
@@ -25,6 +31,28 @@ module StandardId
       !revoked? && !expired?
     end
 
+    # Whether the host has run migration 20261020000000. Until then the gem
+    # neither writes nor reads the binding.
+    def self.client_binding_column?
+      column_names.include?("client_application_id")
+    rescue ActiveRecord::ActiveRecordError
+      false
+    end
+
+    # false once the application this token is bound to has been deactivated
+    # or deleted. An unbound token (NULL, or the column not yet migrated) is
+    # live by this measure: there is no application whose fate it shares.
+    #
+    # `ClientApplication.live` is the scope form of #active? (`active` AND no
+    # `deactivated_at`), so this and the refresh grant can never disagree
+    # about a row whose two fields drifted apart.
+    def client_application_live?
+      return true unless self.class.client_binding_column?
+      return true if client_application_id.nil?
+
+      StandardId::ClientApplication.live.exists?(id: client_application_id)
+    end
+
     def expired?
       expires_at <= Time.current
     end

data/app/views/standard_id/web/auth/callback/providers/mobile_callback.html.erb

@@ -34,7 +34,10 @@
     </style>
     <script>
       document.addEventListener("DOMContentLoaded", function () {
-        var target = "<%= j @mobile_redirect_url %>";
+        <%# to_json, not j(): ERB HTML-escapes the j() output, so every "&" in the
+            query became "&amp;" and each key after the first arrived as "amp;<key>".
+            to_json emits a JS string literal with & < > as \u escapes. %>
+        var target = <%= raw @mobile_redirect_url.to_json %>;
         if (target) {
           window.location.replace(target);
         }

data/db/migrate/20261020000000_add_client_application_id_to_standard_id_refresh_tokens.rb

@@ -0,0 +1,23 @@
+# Binds each refresh token to the ClientApplication it was issued to, so the
+# refresh_token grant can refuse a token whose application has since been
+# deactivated or deleted (see StandardId::Oauth::RefreshTokenFlow
+# #validate_client_application_liveness!). Set at mint from the grant's
+# resolved client (authorization_code, client_credentials, any grant whose
+# client_id names a registered application); copied to each rotated successor;
+# NULL where the client_id is not an application (social sign-in refreshes as
+# the provider's name) and on rows minted before this ran, which are bound on
+# their next rotation.
+#
+# Deliberately NO foreign key: a deleted application must stay detectable as
+# "gone" from the token's side, which a cascading or nullifying FK would erase.
+# One nullable column, no default, no index, no backfill: metadata-only on
+# PostgreSQL, so safe on a large table and under StrongMigrations. Until the
+# migration has run the gem does not write or read the column; a deactivated
+# application is still refused by client_id lookup, a deleted one is not.
+class AddClientApplicationIdToStandardIdRefreshTokens < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
+  def change
+    add_column :standard_id_refresh_tokens, :client_application_id, foreign_key_type
+  end
+end

data/lib/generators/standard_id/install/templates/standard_id.rb

@@ -13,6 +13,10 @@ StandardId.configure do |c|
   # include StandardId::AccountAssociations (see post-install checklist).
   # Default: "User"
   c.account_class_name = "User"
+  # The enum key StandardId::AccountStatus uses for a deactivated account
+  # (default :inactive). Set it to the value your status column already
+  # carries, e.g. :suspended, to adopt the concern without renaming it.
+  # c.inactive_account_status = :inactive
 
   # JWT "iss" claim — typically your application's canonical base URL. When
   # set, tokens embed it and verification enforces it. Strongly recommended

data/lib/standard_id/account_status.rb

@@ -12,8 +12,26 @@ module StandardId
       attr_accessor :subscribed
     end
 
+    # The configured enum key for a deactivated account (`config.inactive_account_status`).
+    # `:active` is refused: the enum would collapse to one key and every
+    # account would read as deactivated.
+    def self.inactive_status
+      status = StandardId.config.inactive_account_status.to_s.presence&.to_sym || :inactive
+      raise StandardId::ConfigurationError, "inactive_account_status cannot be :active" if status == :active
+
+      status
+    end
+
     included do
-      enum :status, { active: "active", inactive: "inactive" }, default: :active
+      # The deactivated key is read from config ONCE, here, when the concern is
+      # included: a host whose column already says "suspended" declares
+      # `c.inactive_account_status = :suspended` and gets `suspended?`, the
+      # `suspended` scope and status "suspended", with no enum value to rename.
+      inactive_status = StandardId::AccountStatus.inactive_status
+      class_attribute :standard_id_inactive_status, instance_writer: false, default: inactive_status
+
+      enum :status, { active: "active", inactive_status => inactive_status.to_s }, default: :active
+      alias_method :inactive?, :"#{inactive_status}?" unless inactive_status == :inactive
 
       after_commit :emit_account_status_changed_event, on: :update, if: :status_previously_changed?
 
@@ -26,29 +44,52 @@ module StandardId
           StandardId::Events::SESSION_VALIDATING
         ) do |event|
           account = event[:account]
-          if account&.inactive?
-            raise StandardId::AccountDeactivatedError, "Account is deactivated"
+          if StandardId::AccountStatus.deactivated?(account)
+            raise StandardId::AccountDeactivatedError, StandardId::AccountStatus.deactivated_message(account)
           end
         end
       end
     end
 
+    # Whether +account+ is in its configured deactivated status. False for nil
+    # and for a model that does not include this concern.
+    def self.deactivated?(account)
+      return false unless account.respond_to?(:standard_id_inactive_status)
+
+      account.public_send(:"#{account.standard_id_inactive_status}?")
+    end
+
+    # "Account is deactivated" for the default key; "Account is suspended" (the
+    # host's own word) for a renamed one.
+    def self.deactivated_message(account)
+      status = account.standard_id_inactive_status
+      status == :inactive ? "Account is deactivated" : "Account is #{status}"
+    end
+
     def activate!
       return true if active?
 
-      update!(status: :active, activated_at: Time.current)
+      attributes = { status: :active }
+      attributes[:activated_at] = Time.current if has_attribute?(:activated_at)
+      update!(**attributes)
     end
 
     def deactivate!
-      return true if inactive?
+      return true if standard_id_deactivated?
 
-      update!(status: :inactive, deactivated_at: Time.current)
+      attributes = { status: standard_id_inactive_status }
+      attributes[:deactivated_at] = Time.current if has_attribute?(:deactivated_at)
+      update!(**attributes)
     end
 
     private
 
+    def standard_id_deactivated?
+      StandardId::AccountStatus.deactivated?(self)
+    end
+
     def emit_account_status_changed_event
-      event = inactive? ? StandardId::Events::ACCOUNT_DEACTIVATED : StandardId::Events::ACCOUNT_ACTIVATED
+      event = standard_id_deactivated? ? StandardId::Events::ACCOUNT_DEACTIVATED : StandardId::Events::ACCOUNT_ACTIVATED
       StandardId::Events.publish(
         event,
         account: self,

data/lib/standard_id/config/schema.rb

@@ -43,6 +43,17 @@ StandardId::ConfigSchema.define do
     field :inertia_component_namespace, type: :string, default: "standard_id"
     field :alias_current_user, type: :boolean, default: false
 
+    # The enum key `StandardId::AccountStatus` declares for a deactivated
+    # account, and so its stored value and predicate: `:inactive` (default)
+    # gives `inactive?` / status "inactive"; `:suspended` gives `suspended?` /
+    # status "suspended". For a host whose status column already carries a
+    # different value and whose code reads that predicate everywhere, so it can
+    # adopt the concern (and the sign-in / token / live-session guard it
+    # installs) without renaming a database enum value under running
+    # processes. `inactive?` stays available as an alias. Read when the concern
+    # is included, so set it in the initializer, before the account model loads.
+    field :inactive_account_status, type: :symbol, default: :inactive
+
     # Opt the gem's own associations out of an app-wide
     # `strict_loading_by_default = true`.
     #
@@ -457,6 +468,24 @@ StandardId::ConfigSchema.define do
     # immediately.
     field :introspection_enabled, type: :boolean, default: false
 
+    # A host-side liveness check for `/oauth/introspect`, run after the gem's
+    # own checks pass (signature, expiry, refresh-token row, parent session,
+    # bound ClientApplication) and before the active response is rendered. A
+    # callable taking any subset of `payload:` (the decoded claims, string or
+    # symbol keys), `refresh_token:` (the persisted StandardId::RefreshToken,
+    # nil for an access token) and `request:`. A falsy return renders
+    # `{"active": false}`, nothing else. For claims the host mints that point
+    # at its own rows — a profile `gid`, a tenant — whose liveness only the
+    # host can judge. An exception is logged and counts as inactive: a check
+    # that cannot answer must not say yes.
+    field :introspection_liveness, type: :any, default: nil
+
+    # Extra claim names copied from the token into an ACTIVE introspection
+    # response, beyond the RFC 7662 members the gem always returns — e.g.
+    # `%w[profile_type gid]`. A claim the token lacks is omitted; the standard
+    # members (`active`, `sub`, `aud`, …) cannot be overridden.
+    field :introspection_claims, type: :array, default: -> { [] }
+
     # Grant types the token endpoint refuses even though the engine implements
     # them. Values are the `grant_type` strings: "authorization_code",
     # "refresh_token", "client_credentials", "password", "passwordless_otp".
@@ -670,6 +699,26 @@ StandardId::ConfigSchema.define do
     field :api_passwordless_start_per_ip, type: :integer, default: 10    # per hour
     field :api_passwordless_start_per_target, type: :integer, default: 5 # per 15 minutes
 
+    # OTP start limits enforced INSIDE the passwordless strategy
+    # (Passwordless::BaseStrategy#start!), not on a controller — so they hold
+    # for a host that drives `generate_passwordless_otp`, `StandardId::Otp.issue`
+    # or the strategy from its own controllers, operations or jobs, where the
+    # controller-level limits above are never consulted. Counted on the same
+    # store, keyed per (realm, channel, target) and per IP, raising
+    # StandardId::RateLimitExceededError (a 429 through the API error handler,
+    # a flash on the web login page, a failed result from Otp.issue).
+    #
+    # The per-target limit defaults to the API's per-target value, so a path
+    # that already runs the controller limit sees no change (the controller
+    # trips first, with its Retry-After). A host that RAISES a controller
+    # per-target limit (api_passwordless_start_per_target, login_per_email)
+    # must raise this one too, or it becomes the binding limit. The per-IP
+    # limit defaults OFF: the
+    # right ceiling depends on how many real users share one address (CGNAT,
+    # an office), and a wrong default would bounce them. 0 disables either.
+    field :otp_start_per_target, type: :integer, default: 5     # per 15 minutes
+    field :otp_start_per_ip, type: :integer, default: 0         # per hour; 0 = off
+
     # OAuth token endpoint — requests per IP.
     field :api_token_per_ip, type: :integer, default: 30                 # per 15 minutes
 

data/lib/standard_id/errors.rb

@@ -74,6 +74,40 @@ module StandardId
     def oauth_error_code = :invalid_request
   end
 
+  # A lib-level rate limit tripped (StandardId::RateLimiter). A subclass of
+  # InvalidRequestError so every path that already turns a refused OTP start
+  # into a flash, a failure result or an OAuth error body keeps doing so; the
+  # API error handler renders it as 429 `rate_limit_exceeded`, the same shape
+  # the controller-level limits produce.
+  class RateLimitExceededError < InvalidRequestError
+    # Length in seconds of the window that tripped (an upper bound on the
+    # wait, not the time remaining), for a Retry-After header.
+    attr_reader :retry_after
+
+    def initialize(message = "Too many requests. Please try again later.", retry_after: nil)
+      super(message)
+      @retry_after = retry_after
+    end
+
+    def oauth_error_code = :rate_limit_exceeded
+    def http_status = :too_many_requests
+  end
+
+  # The OTP resend cooldown (`passwordless.retry_delay`) refused a start: a code
+  # for this target was issued less than retry_delay seconds ago and is still
+  # usable, so nothing new was sent. A subclass of InvalidRequestError so every
+  # existing rescue keeps working; Otp.issue reports it as `error_code:
+  # :cooldown` so a host can show its own "a code is already on its way" copy
+  # and tell it apart from a send failure. `retry_after` is the seconds left.
+  class RetryDelayError < InvalidRequestError
+    attr_reader :retry_after
+
+    def initialize(message = "Please wait before requesting another code", retry_after: nil)
+      super(message)
+      @retry_after = retry_after
+    end
+  end
+
   class InvalidClientError < OAuthError
     def oauth_error_code = :invalid_client
     def http_status = :unauthorized

data/lib/standard_id/oauth/refresh_token_flow.rb

@@ -42,6 +42,7 @@ module StandardId
 
         validate_refresh_token_record!
         validate_scope_narrowing!
+        validate_client_application_liveness!
       end
 
       private
@@ -77,6 +78,66 @@ module StandardId
         raise StandardId::InvalidGrantError, "Refresh token is no longer valid"
       end
 
+      # Refuse a refresh whose ClientApplication has been deactivated or deleted.
+      #
+      # Deleting a client is the only revocation RFC 7592 gives a client manager,
+      # and a public (DCR, PKCE) client never sends a secret, so until this check
+      # existed the grant never looked the client up at all: DELETE
+      # /oauth/register/:client_id answered 204 while every refresh token it had
+      # issued kept rotating. Hosts closed that with a prepend on this class.
+      #
+      # The binding is the row's `client_application_id` (migration
+      # 20261020000000), copied down each rotation. A row without one — minted
+      # before the column existed, or on a host that has not migrated yet — is
+      # checked by the token's client_id instead: refused if an application with
+      # that client_id exists and is inactive, and (once the column exists) its
+      # successor carries the id. So deactivation bites with or without the
+      # migration; only deletion needs the column, because a deleted
+      # application leaves nothing to look up by client_id. A token whose
+      # client_id is not an application at all (social sign-in refreshes as the
+      # provider's name; a free-form client_id that happens to collide with a
+      # registered one is treated as that application) is left alone.
+      #
+      # Deactivation suspends: nothing is revoked, so reactivating the
+      # application restores its tokens. One exception, deliberate: reuse
+      # detection in #validate_refresh_token_record! runs first, so a replayed
+      # already-rotated token still revokes its family while the application is
+      # suspended. That is the theft signal it always was, and suspension is
+      # not a reason to stop honouring it. Deletion is final because the row is
+      # gone and client_ids are random. Either way the answer is the generic
+      # `invalid_grant` every other dead token gets (RFC 6749 §5.2): a distinct
+      # message would tell whoever holds a leaked token why it stopped working.
+      def validate_client_application_liveness!
+        return if @current_refresh_token_record.nil?
+        return if client_application_live?
+
+        raise StandardId::InvalidGrantError, "Refresh token is no longer valid"
+      end
+
+      def client_application_live?
+        record = @current_refresh_token_record
+        return record.client_application_live? if record.try(:client_application_id).present?
+
+        client = token_client
+        client.nil? || client.active?
+      end
+
+      # Resolved by client_id (TokenGrantFlow#token_client), memoised: the
+      # liveness check, the successor's binding and the claim resolvers all
+      # read it on the hot path.
+      def token_client
+        return @token_client if defined?(@token_client)
+
+        @token_client = super
+      end
+
+      # The successor inherits the presented token's binding; a legacy unbound
+      # token's successor is bound by client_id (see
+      # #validate_client_application_liveness!).
+      def bound_client_application_id
+        @current_refresh_token_record.try(:client_application_id) || super
+      end
+
       def validate_refresh_token_record!
         jti = @refresh_payload[:jti]
         # Legacy tokens minted before jti tracking was added cannot be looked

data/lib/standard_id/oauth/token_grant_flow.rb

@@ -230,10 +230,27 @@ module StandardId
           token_digest: StandardId::RefreshToken.digest_for(jti),
           expires_at: expires_at,
           previous_token: previous_refresh_token_record,
-          **StandardId::AuthLineage.refresh_token_attributes(refresh_token_auth_lineage)
+          **StandardId::AuthLineage.refresh_token_attributes(refresh_token_auth_lineage),
+          **client_binding_attributes
         )
       end
 
+      # The ClientApplication the refresh token is bound to, so the
+      # refresh_token grant can refuse it once that application is deactivated
+      # or deleted. Nothing is written until migration 20261020000000 has run.
+      def client_binding_attributes
+        return {} unless StandardId::RefreshToken.client_binding_column?
+
+        { client_application_id: bound_client_application_id }
+      end
+
+      # nil when the grant's client_id is not a registered application (the
+      # social flow, a password/passwordless grant with a free-form client_id):
+      # such a token has no application whose fate to share.
+      def bound_client_application_id
+        token_client&.id
+      end
+
       # How the authentication behind this grant was established, recorded on
       # the refresh token so the refresh_token grant can re-check the
       # login-method policy against it. Grants that authenticate an account

data/lib/standard_id/otp.rb

@@ -74,7 +74,10 @@ module StandardId
     # - success?: true/false
     # - challenge: the created CodeChallenge (nil on failure)
     # - code: raw OTP code — only populated when delivery: :manual
-    # - error_code: machine-readable symbol on failure
+    # - error_code: machine-readable symbol on failure — :invalid_request
+    #   (bad target, username_validator rejection), :cooldown (a usable code
+    #   was issued less than passwordless.retry_delay seconds ago; nothing new
+    #   was sent), :rate_limited (rate_limits.otp_start_per_* tripped)
     # - error_message: human-readable message on failure
     IssueResult = Data.define(:success?, :challenge, :code, :error_code, :error_message) do
       # Parallel naming with VerificationService::Result, which exposes the
@@ -132,6 +135,15 @@ module StandardId
             skip_sender: delivery_sym == :manual,
             delivery: delivery_sym
           )
+        rescue StandardId::RetryDelayError => e
+          # The resend cooldown (passwordless.retry_delay): a usable code was
+          # issued moments ago and nothing new was sent. Distinct code so a
+          # caller can say "it's on its way" rather than report a failure.
+          return failure_issue_result(:cooldown, e.message)
+        rescue StandardId::RateLimitExceededError => e
+          # A lib-level start limit (rate_limits.otp_start_per_*) tripped.
+          # Distinct code so a caller can answer 429 rather than 400.
+          return failure_issue_result(:rate_limited, e.message)
         rescue StandardId::InvalidRequestError => e
           # Validation failures from the strategy (invalid email/phone format,
           # custom username_validator rejections, etc.) are surfaced as a

data/lib/standard_id/passwordless/base_strategy.rb

@@ -32,14 +32,26 @@ module StandardId
 
         validate_username!(username)
         run_username_validator!(username)
-        enforce_retry_delay!(username)
+        enforce_start_rate_limits!(username)
+        # Cooldown check and challenge creation in ONE transaction, serialised
+        # per target (see #lock_target!), so two concurrent starts for the same
+        # address cannot both pass the check and both issue a code — which
+        # invalidated the first code the moment the second was created and
+        # left the user holding a dead one (fundbright delivery-ops#345).
+        challenge = ActiveRecord::Base.transaction do
+          lock_target!(username)
+          enforce_retry_delay!(username)
+          create_challenge!(
+            username,
+            code_length: code_length,
+            expires_in: expires_in,
+            metadata: metadata
+          )
+        end
+        # Published once the row is committed: a subscriber that writes must
+        # not have its work rolled back with a failed insert, nor hold the
+        # per-target lock for its whole runtime. Still before CODE_GENERATED.
         emit_code_requested(username)
-        challenge = create_challenge!(
-          username,
-          code_length: code_length,
-          expires_in: expires_in,
-          metadata: metadata
-        )
         # skip_sender is forwarded into the event payload so subscribers that
         # deliver on PASSWORDLESS_CODE_GENERATED (e.g. PasswordlessDeliverySubscriber)
         # can honor a per-call manual-delivery request. Without this,
@@ -52,6 +64,44 @@ module StandardId
 
       protected
 
+      # Per-target and per-IP ceilings on starts (rate_limits.otp_start_per_*),
+      # counted here rather than on a controller so they hold whichever way a
+      # host reaches the strategy. The target key carries the realm and
+      # channel, so an authentication code and a verification code for the
+      # same address are separate budgets, as they are separate challenges.
+      def enforce_start_rate_limits!(username)
+        limits = StandardId.config.rate_limits
+        target = username.to_s.strip.downcase
+        StandardId::RateLimiter.hit!(
+          "standard_id:otp-start:target:#{@realm}:#{connection_type}:#{target}",
+          limit: limits.otp_start_per_target, window: 15.minutes
+        )
+
+        ip = request.respond_to?(:remote_ip) ? request.remote_ip : nil
+        return if ip.blank?
+
+        StandardId::RateLimiter.hit!(
+          "standard_id:otp-start:ip:#{StandardId::Utils::IpNormalizer.normalize(ip)}",
+          limit: limits.otp_start_per_ip, window: 1.hour
+        )
+      end
+
+      # Serialise concurrent starts for one (realm, channel, target) for the
+      # rest of the enclosing transaction. On PostgreSQL this is a transaction-
+      # scoped advisory lock, released at commit or rollback, so a second start
+      # waits for the first to finish and then sees the challenge it created.
+      # Other adapters get no cross-process lock: the retry-delay check there
+      # stays what it was, a read followed by a write. Keyed on the normalised
+      # target (as the rate limit is), so "User@x" and "user@x" contend for one
+      # lock even when a caller skipped the web login's own downcasing.
+      def lock_target!(username)
+        connection = StandardId::CodeChallenge.connection
+        return unless connection.adapter_name.match?(/postg/i)
+
+        key = "standard_id:otp:#{@realm}:#{connection_type}:#{username.to_s.strip.downcase}"
+        connection.execute("SELECT pg_advisory_xact_lock(hashtext(#{connection.quote(key)}))")
+      end
+
       # Reject a resend that arrives within passwordless.retry_delay seconds of
       # the most recent still-active code for this target. A soft cooldown that
       # complements the coarser per-target rate limits: it does not consume the
@@ -71,8 +121,10 @@ module StandardId
         return if elapsed >= delay
 
         wait = (delay - elapsed).ceil
-        raise StandardId::InvalidRequestError,
-          "Please wait #{wait} #{'second'.pluralize(wait)} before requesting another code"
+        raise StandardId::RetryDelayError.new(
+          "Please wait #{wait} #{'second'.pluralize(wait)} before requesting another code",
+          retry_after: wait
+        )
       end
 
       def create_challenge!(username, code_length: nil, expires_in: nil, metadata: {})

data/lib/standard_id/rate_limiter.rb

@@ -0,0 +1,35 @@
+module StandardId
+  # Fixed-window counters on the configured rate-limit store, for limits the
+  # engine enforces OUTSIDE a controller — where Rails' `rate_limit` macro
+  # cannot reach. The first one is the OTP start path (Passwordless::BaseStrategy
+  # #start!), which a host can drive from its own controllers, an operation or
+  # a job without ever passing the engine's throttled actions.
+  #
+  # `STORE` is the same lazily-resolved RateLimitStore the engine's controllers
+  # count on (RateLimitHandling::RATE_LIMIT_STORE is this object), so one
+  # `c.cache_store` governs both, and a spec that stubs one stubs the other.
+  module RateLimiter
+    STORE = StandardId::RateLimitStore.new
+
+    module_function
+
+    # Count one hit against +key+ and raise once the window holds more than
+    # +limit+. A non-positive limit disables the check. A store that cannot
+    # count (`ActiveSupport::Cache::NullStore` answers nil) disables it too:
+    # there is nothing to count against, and refusing everyone is worse than
+    # counting nothing.
+    #
+    # @param key [String]
+    # @param limit [Integer]
+    # @param window [ActiveSupport::Duration, Integer] seconds
+    # @raise [StandardId::RateLimitExceededError]
+    def hit!(key, limit:, window:)
+      return if limit.to_i <= 0
+
+      count = STORE.increment(key, 1, expires_in: window)
+      return if count.nil? || count.to_i <= limit.to_i
+
+      raise StandardId::RateLimitExceededError.new(retry_after: window.to_i)
+    end
+  end
+end

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.47.0"
+  VERSION = "0.48.1"
 end

data/lib/standard_id.rb

@@ -69,6 +69,7 @@ require "standard_id/otp"
 require "standard_id/authorization_bypass"
 require "standard_id/utils/ip_normalizer"
 require "standard_id/rate_limit_store"
+require "standard_id/rate_limiter"
 
 require "concurrent/delay"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.47.0
+  version: 0.48.1
 platform: ruby
 authors:
 - Jaryl Sim
@@ -238,6 +238,7 @@ files:
 - db/migrate/20260924000000_add_unique_active_device_index_to_standard_id_sessions.rb
 - db/migrate/20261002000000_create_standard_id_social_identities.rb
 - db/migrate/20261004000000_add_auth_method_to_standard_id_refresh_tokens.rb
+- db/migrate/20261020000000_add_client_application_id_to_standard_id_refresh_tokens.rb
 - lib/generators/standard_id/install/install_generator.rb
 - lib/generators/standard_id/install/templates/standard_id.rb
 - lib/standard_id.rb
@@ -309,6 +310,7 @@ files:
 - lib/standard_id/providers/base.rb
 - lib/standard_id/providers/plugin_railtie.rb
 - lib/standard_id/rate_limit_store.rb
+- lib/standard_id/rate_limiter.rb
 - lib/standard_id/routing.rb
 - lib/standard_id/scope_config.rb
 - lib/standard_id/session_type_resolver.rb