standard_id 0.40.0 → 0.41.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89d297a5e9c69566991b97cca501fd5a714b2d2e1200d2e740b3e45684981aab
-  data.tar.gz: d93fc7206735373f14ac2cd51c4612aaf7b1d19244022d884f0c84757d8f78c6
+  metadata.gz: eda13bb222bf26a20444378b4fe6d0e7661f86a0058388986fb2710e5f01802d
+  data.tar.gz: 96835ff10cd72cc01c8654ddf86d5cb44555079eafad8f521b8c62061a63dde9
 SHA512:
-  metadata.gz: 1ce536a136af167e65ec9d01e370a187d71f77a2f60f0c5af47ee5c23a9b58cb87444b95191a019fa06689902765f51eaff20656aeedcdef288e34f577c99c91
-  data.tar.gz: f825db9970c937a76592c421fb71a9607f3ea0667dfafa105ff2d6ce78bbd754f5ca01f873cf3321962876c3ab0f8c7f7314ec95604cf5900d56291cede6ec57
+  metadata.gz: 68698115969ba88727515927a9afaf0d1f14245b215abed59220afbbacb0533667715688fa395df46013c32c384d854e44cc58bb760e83c7f2c1dcac6063bed0
+  data.tar.gz: 48918bda97f0345b8b462dde9fbf4c77b6bff7851764fbee998f8af6d779caa8efc6f7e8f68f0971c33c1d8110af8effe69c172a82ad96c068d41b8a38495538

data/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.41.1] - 2026-09-24
+
+Bug-fix release. Four of these were found in sidekick-web, which has been carrying host-side prepend patches for three of them; the dummy app now runs with `strict_loading_by_default` so this class of bug fails in the gem's own suite first.
+
+### Upgrade
+
+Read this before bumping — the order matters if you have not yet deployed 0.41.0's migration:
+
+1. **Deploy 0.41.1 first, WITHOUT running `20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications`.** 0.41.1 ignores the column (see Fixed), so running processes stop reading and writing it.
+2. **Run `20260915000000` in a later deploy.** With strong_migrations it still needs wrapping: `safety_assured { remove_column ... }` inside the copied migration's `up` — the column is already ignored, which is the condition strong_migrations asks you to confirm. Hosts that already ran it under 0.41.0 have nothing to do here.
+3. **Install and run the new `20260924000000_add_unique_active_device_index_to_standard_id_sessions`** (`bin/rails standard_id:install:migrations`). It is idempotent, builds CONCURRENTLY on Postgres, and needs no `safety_assured` in the host: the one raw-SQL step (detaching duplicate rows) asserts itself safe to StrongMigrations when that gem is loaded. It detaches any existing duplicate active device rows before building the index (see Fixed); nothing is revoked.
+4. **Hosts carrying the sidekick-web prepend patches can delete them:** `config/initializers/standard_id_refresh_token_strict_loading.rb`, `standard_id_rotation_leeway.rb` and `standard_id_device_session_upsert.rb` (and their specs). The upsert patch's signature guard will keep passing, so it will not remind you — remove it deliberately.
+
+### Fixed
+
+- **Signing in again after signing out no longer resurrects the revoked device session.** `OauthSessionPersistence.upsert_device_session!` looked the device's row up with a bare `find_by(account:, device_id:)`. Sign-out (`/oauth/revoke` under the default `:account` `revocation_scope`) revokes every active `DeviceSession`, so the next sign-in reused the revoked row, every refresh token minted afterwards pointed at a revoked parent, and `RefreshTokenFlow#validate_parent_session!` refused the very first refresh. The client was sent back to sign-in each time its access token expired, on every device, forever — sidekick-web's companion app, where the audit trail showed dozens of sign-ins a day and not one successful refresh.
+
+  Only rows with `revoked_at: nil` are now reused (newest first); a revoked row stays as history and the sign-in gets a new one. Expiry is deliberately still not part of eligibility — an expired-but-unrevoked row is reused with its `expires_at` bumped, as before. The insert runs inside a savepoint, and on `ActiveRecord::RecordNotUnique` the row that won a concurrent first sign-in is reused rather than failing the token request.
+
+  **New migration `20260924000000`**: a partial unique index on `standard_id_sessions (account_id, device_id) WHERE revoked_at IS NULL AND device_id IS NOT NULL`, so "one active session per device" is a database invariant rather than a property of the account row lock. Before building it, each duplicated group of active rows keeps its newest row as-is and has `:detached:<id>` appended to the others' `device_id`. Detached rows stay active — their refresh tokens keep working until they expire or are revoked — they are just no longer the row a new sign-in reuses. `down` drops the index and leaves the detached suffixes in place (strip `:detached:<id>` to recover the original).
+
+- **The refresh-token reuse leeway no longer 500s under strict loading.** When `refresh_token_reuse_leeway` graces a replayed token, `graced_successor_for` loaded the successor without its `:session`, and `validate_parent_session!` then read it lazily — `StrictLoadingViolationError` on exactly the retry the leeway exists to rescue (sidekick-web SIDEKICK-WEB-3E). The successor is now `eager_load(:session)`ed like the primary lookup. The existing grace specs used session-less tokens, where a nil foreign key never queries; the new ones link the family to a `DeviceSession`.
+
+- **Two graced retries racing to rotate the same successor no longer log the client out.** Two retries of one lost response can both pass `graced_successor_for` while the successor is untouched, then race to rotate it. The loser landed in `handle_concurrent_reuse!` and revoked the family, killing the token the winner had just issued. A request served from a graced successor that loses the rotation race now gets `invalid_grant` **without** revoking anything; the client keeps the winner's response. A request presenting its token directly and losing the race still revokes the family, and a later replay of the superseded token still finds a used successor and revokes as before — the leeway is not widened.
+
+- **A lifecycle hook rejecting a brand-new account no longer 500s under strict loading.** `LifecycleHooks#destroy_newly_created_account` read `account.sessions` / `account.identifiers` lazily, so a `before_sign_in` / `after_sign_in` rejection of a just-created signup raised `StrictLoadingViolationError` instead of redirecting to login, and left the orphaned account behind. The cleanup now reads each association through `.strict_loading(false)`.
+
+- **`StandardId::ClientApplication` ignores the dropped `refresh_token_lifetime` column.** 0.41.0 removed the column without ignoring it first, so on a rolling deploy processes still on the old code named it in every INSERT/UPDATE once the migration ran. `self.ignored_columns += %w[refresh_token_lifetime]` makes the deploy-then-drop order in **Upgrade** safe. It will be removed in a future minor.
+
+- **The documented per-challenge OTP attempt ceiling was wrong.** `passwordless.max_attempts_per_challenge` is unset by default and falls back to `max_attempts` (default `3`), so an untouched install burns a challenge after 3 wrong codes — but the install generator template, the schema comment and the 0.16.0 entry below all said `5`. They now say `3`, and a spec pins the template's value to the runtime default. The literal `5` in the resolver is a real last resort (both settings nil or zero, since a zero ceiling would burn every challenge on its first wrong code) and is now named `StandardId::Passwordless::FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE`. No behaviour change.
+
+### Changed
+
+- **The dummy app runs with `strict_loading_by_default = true`** and `:raise`, as every consumer does. `spec/dummy/config/initializers/strict_loading.rb` exempts the gem models hosts exempt (`Identifier`, `Session`, `Credential`, `PasswordCredential`, `ClientSecretCredential`, `AuthorizationCode`); `RefreshToken`, `ClientApplication`, `ClientGrant`, `CodeChallenge` and `Account` stay strict. `STRICT_LOADING=full bundle exec rspec` drops the exemptions to show the remaining backlog. Test-suite only; no runtime change.
+
+## [0.41.0] - 2026-09-15
+
+### Added
+
+- **Per-audience scope vocabulary hook.** An app can now declare, per audience, the set of scopes a client targeting that audience may request and be granted — the mechanism sidekick-web needs to express its per-audience MCP scope vocabularies (`mcp`, `mcp:read`, `mcp:eval:run`, …) through the gem instead of hard-coding a single flat `scopes_supported` list shared by every audience. This is the scope-side counterpart to the existing `audience_profile_types` binding: that binds an audience to a required profile, this binds an audience to a grantable scope vocabulary, and the two are configured and read the same way on purpose.
+
+  `c.oauth.audience_scopes` is a static `audience => Array<String>` map; `c.oauth.audience_scope_resolver` is an optional callable `->(audience:, client:, configured_scopes:) { … }` for apps that compute the vocabulary dynamically (per-client entitlements), filtered by arity like every other gem callable and returning `nil` to fall back to the static map. `StandardId::Oauth::AudienceScopeResolver` reads them and exposes `scopes_for`, `configured_for?`, `permits?`, `filter` (narrow a grant to the vocabulary), `disallowed`, and `assert!` (fail-closed, raising `InvalidScopeError` / RFC 6749 `invalid_scope`, naming only the client's offending scopes so the endpoint is not a vocabulary-enumeration oracle).
+
+  An **unconfigured** audience fails **open** everywhere — `filter`/`assert!` pass requested scopes through unchanged — exactly like `audience_profile_types` skips its check when unmapped, so an app that does not model per-audience vocabularies sees no behaviour change. The resolver ships ahead of any mint-/registration-time wiring so the hook API can be settled in review first, mirroring how `AudienceProfileResolver#resolve!` shipped before its strict path was wired.
+
+### Removed
+
+- **The per-client `refresh_token_lifetime` column is dropped** (`standard_id_client_applications`), resolving the #765 asymmetry. It was never honoured: `TokenLifetimeResolver.refresh_token_lifetime` resolves the refresh-token lifetime **globally** from `oauth.refresh_token_lifetime` and has no per-client branch, so the column advertised a knob that did nothing. Refresh-token lifetime is a global policy by design — a client's re-authorization cadence is governed by **revocation**, not by a per-client lifetime (see the 0.39.x linked-session reasoning: "Revocation is the property the estate wants; lifetime remains `refresh_token_lifetime`'s job, which already exists and is already configured per host"). Access- and authorization-code lifetimes remain per-client.
+
+  **Migration:** consumers pick up `20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications` (idempotent, reversible). The global `oauth.refresh_token_lifetime` config is unchanged and continues to govern refresh-token lifetime for every client.
+
 ## [0.40.0] - 2026-09-05
 
 ### Fixed
@@ -1121,7 +1172,7 @@ An explicit per-grant `profile_id` parameter is intentionally out of scope for t
 
 ### Security
 
-- **OTP verification race-condition fix and per-challenge brute-force defenses** — `VerificationService.verify` now wraps the challenge lookup, failed-attempt increment, and consumption in a single `SELECT ... FOR UPDATE` transaction, closing the TOCTOU window between "find active challenge" and "mark it used." Failed-attempt counting is now atomic and scoped to the specific challenge (previously a loose read-modify-write on the account). Events are deferred to post-commit so observers never see rolled-back state. New `config.passwordless.max_attempts_per_challenge` (default `5`) supersedes the now-deprecated account-wide `max_attempts` (kept as a fallback for existing installs). (#169)
+- **OTP verification race-condition fix and per-challenge brute-force defenses** — `VerificationService.verify` now wraps the challenge lookup, failed-attempt increment, and consumption in a single `SELECT ... FOR UPDATE` transaction, closing the TOCTOU window between "find active challenge" and "mark it used." Failed-attempt counting is now atomic and scoped to the specific challenge (previously a loose read-modify-write on the account). Events are deferred to post-commit so observers never see rolled-back state. New `config.passwordless.max_attempts_per_challenge` (unset by default, so the effective ceiling is `max_attempts`' default of `3`; `5` is only a last-resort fallback when both are unset or zero) supersedes the now-deprecated account-wide `max_attempts` (kept as a fallback for existing installs). (#169)
 - **JWT audience enforcement at decode time** — `JwtService.decode` now accepts an `allowed_audiences:` kwarg and raises `StandardId::InvalidAudienceError` on mismatch. `Api::TokenManager#verify_jwt_token` threads `config.oauth.allowed_audiences` through automatically, so cross-audience JWT replay is now blocked even on controllers that forget to include the `AudienceVerification` concern. Production emits a warning when `allowed_audiences` is unset. (#170, #174)
 - **Web flow polish** — password-reset delivery moved to an async job with a constant-time success response (closes enumeration timing leak); OAuth `redirect_uri` validation tightened to exact scheme+host+port+path match at both registration and authorize time (blocks query-string piggyback); engine logs a warning when the host app has no `secret_key_base` configured so encrypted session cookies can't silently fall back to plaintext. New `reset_password` config scope with `:delivery` (`:custom` default, `:built_in` opt-in) and mailer-sender/subject knobs. `CREDENTIAL_PASSWORD_RESET_INITIATED` event now fires from the job. (#171)
 - **Per-client PKCE enforcement at the authorize endpoint** — honors the existing `require_pkce` column on `ClientApplication`. Requests missing `code_challenge` are rejected with `invalid_request` when the client requires PKCE. Per-client `code_challenge_methods` replaces the global S256-only hardcode (case-insensitive). New validation blocks public clients from opting out (`public_clients_must_require_pkce`). (#175)

data/README.md

@@ -235,6 +235,38 @@ end
 
 Resolvers receive keyword arguments with the context containing `client`, `account`, and `request`, so you can reference only what you need. This lets you, for example, pull organization info off the client application or decorate claims with account attributes.
 
+### Per-Audience Scope Vocabulary
+
+Declare, per audience, the set of scopes a client targeting that audience may request and be granted. This lets each audience expose its own MCP scope vocabulary rather than sharing one flat `scopes_supported` list. It is the scope-side counterpart to the `audience_profile_types` binding: that binds an audience to a required profile, this binds it to a grantable scope vocabulary.
+
+```ruby
+StandardId.configure do |config|
+  config.oauth.audience_scopes = {
+    "harness"       => %w[mcp mcp:read mcp:eval:run mcp:prompt:write],
+    "companion_kit" => %w[mcp mcp:read],
+    "admin_kit"     => %w[mcp mcp:read mcp:admin]
+  }
+
+  # Optional: compute a vocabulary dynamically (e.g. per-client entitlements).
+  # Return an Array<String>, or nil to fall back to the static map above.
+  config.oauth.audience_scope_resolver = ->(audience:, client:, configured_scopes:) {
+    Entitlements.mcp_scopes_for(client, audience) || configured_scopes
+  }
+end
+```
+
+`StandardId::Oauth::AudienceScopeResolver` reads this config:
+
+```ruby
+R = StandardId::Oauth::AudienceScopeResolver
+R.scopes_for(audience: "companion_kit")                          # => ["mcp", "mcp:read"]
+R.permits?(scope: "mcp:admin", audience: "companion_kit")        # => false
+R.filter(requested: %w[mcp mcp:admin], audience: "companion_kit") # => ["mcp"]  (narrows, never raises)
+R.assert!(requested: %w[mcp mcp:admin], audience: "companion_kit") # => raises InvalidScopeError
+```
+
+An **unconfigured** audience fails **open** — `filter` and `assert!` pass the requested scopes through unchanged — so an app that does not model per-audience vocabularies sees no behaviour change; narrowing only bites once an audience has an explicit vocabulary.
+
 ### Social Login Setup
 
 The `social.google_*` and `social.apple_*` fields are declared by the **provider

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

@@ -208,13 +208,22 @@ module StandardId
 
     # Destroy a newly created account and all its dependents.
     # Used when after_sign_in rejects a just-created account to avoid orphans.
+    #
+    # Every association read goes through `.strict_loading(false)`: the account
+    # was built in this request, so none of its associations are loaded, and a
+    # host running `strict_loading_by_default = true` (most consumers) would
+    # otherwise raise StrictLoadingViolationError on `account.sessions` — turning
+    # a hook's clean rejection of a new signup into a 500 and leaving the
+    # orphaned account behind. Relation-level `strict_loading(false)` also covers
+    # the records it loads, so `identifier.credentials` below is safe too.
     def destroy_newly_created_account(account)
       return unless account&.persisted?
 
       ActiveRecord::Base.transaction do
-        account.sessions.destroy_all
-        account.identifiers.each { |i| i.credentials.destroy_all }
-        account.identifiers.destroy_all
+        account.sessions.strict_loading(false).destroy_all
+        identifiers = account.identifiers.strict_loading(false).to_a
+        identifiers.each { |i| i.credentials.strict_loading(false).destroy_all }
+        identifiers.each(&:destroy!)
         account.destroy
       end
     end

data/app/models/standard_id/client_application.rb

@@ -1,6 +1,17 @@
 module StandardId
   class ClientApplication < ApplicationRecord
     self.table_name = "standard_id_client_applications"
+
+    # 0.41.0 dropped `refresh_token_lifetime` (migration 20260915000000) without
+    # ignoring it first, so a rolling deploy broke: processes still running the
+    # old code had the column in their cached schema and wrote it on every
+    # INSERT/UPDATE once the migration had removed it. Ignoring it here lets
+    # hosts ship this release first and drop the column in a LATER deploy —
+    # the order strong_migrations requires for remove_column.
+    #
+    # Remove this line in a future minor, once every host has run 20260915000000.
+    self.ignored_columns += %w[refresh_token_lifetime]
+
     belongs_to :owner, polymorphic: true
 
     has_many :client_secret_credentials, dependent: :destroy
@@ -19,8 +30,13 @@ module StandardId
     validates :scopes, presence: true
     validates :code_challenge_methods, presence: true, if: :require_pkce?
 
-    # Lifecycle validations
-    validates :access_token_lifetime, :refresh_token_lifetime, :authorization_code_lifetime,
+    # Lifecycle validations.
+    #
+    # Refresh-token lifetime is deliberately NOT per-client: it is resolved
+    # globally by TokenLifetimeResolver from `oauth.refresh_token_lifetime`, so
+    # there is no `refresh_token_lifetime` column to validate here (removed in
+    # migration 20260915000000, the #765 asymmetry fix).
+    validates :access_token_lifetime, :authorization_code_lifetime,
               presence: true, numericality: { greater_than: 0 }
 
     # Security: public clients cannot opt out of PKCE. Public clients run in

data/db/migrate/20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications.rb

@@ -0,0 +1,23 @@
+class RemoveRefreshTokenLifetimeFromStandardIdClientApplications < ActiveRecord::Migration[7.1]
+  # Drops the per-client `refresh_token_lifetime` column. It was never honoured:
+  # `TokenLifetimeResolver.refresh_token_lifetime` resolves the refresh-token
+  # lifetime GLOBALLY from `oauth.refresh_token_lifetime` and has no per-client
+  # branch, so the column advertised a knob that did nothing (the #765
+  # asymmetry). Refresh-token lifetime is a global policy by design — a client's
+  # session cadence is governed by revocation, not by a per-client lifetime
+  # (see CHANGELOG, "Revocation is the property the estate wants") — so the
+  # column is removed rather than wired up.
+  #
+  # Access- and authorization-code lifetimes remain per-client.
+  def up
+    return unless column_exists?(:standard_id_client_applications, :refresh_token_lifetime)
+
+    remove_column :standard_id_client_applications, :refresh_token_lifetime
+  end
+
+  def down
+    return if column_exists?(:standard_id_client_applications, :refresh_token_lifetime)
+
+    add_column :standard_id_client_applications, :refresh_token_lifetime, :integer, default: 2592000
+  end
+end

data/db/migrate/20260924000000_add_unique_active_device_index_to_standard_id_sessions.rb

@@ -0,0 +1,115 @@
+class AddUniqueActiveDeviceIndexToStandardIdSessions < ActiveRecord::Migration[8.0]
+  # One ACTIVE DeviceSession per (account, device).
+  #
+  # `OauthSessionPersistence.upsert_device_session!` keys OAuth-issued device
+  # sessions on a stable device_id and reuses the active row for repeat
+  # sign-ins. Until now nothing in the schema backed that: the upsert
+  # serialised on a row lock, a race or an older gem could still leave two
+  # active rows for one device, and the lookup then picked one arbitrarily.
+  # This partial unique index makes "one active row per device" a database
+  # invariant; the upsert inserts inside a savepoint and, on
+  # RecordNotUnique, reuses the row that won.
+  #
+  # Partial on purpose:
+  #   - `revoked_at IS NULL` — revoked rows are history (audit trail, admin
+  #     session list) and a device legitimately accumulates one per sign-out.
+  #   - `device_id IS NOT NULL` — BrowserSession / ServiceSession rows share
+  #     the table and carry no device_id.
+  #
+  # Existing duplicates are resolved BEFORE the index is built, without
+  # revoking anything: in each duplicated (account_id, device_id) group the
+  # newest active row keeps its device_id and every other row has
+  # ":detached:<id>" appended to its own. Detached rows stay active — their
+  # refresh tokens keep working until they expire or are revoked — they are
+  # simply no longer the row a new sign-in on that device reuses. Not undone
+  # by `down`: the original device_id is recoverable by stripping the suffix.
+  #
+  # Idempotent (if_not_exists / if_exists), CONCURRENTLY on Postgres, same
+  # conventions as 20260416180511. StrongMigrations treats a concurrent
+  # add_index as safe, but it cannot inspect the raw-SQL detach UPDATE and
+  # stops the migration there whenever a host actually has duplicates — so
+  # that data fix is asserted safe (see #assert_safe) when the gem is loaded.
+  disable_ddl_transaction!
+
+  INDEX_NAME = "index_standard_id_sessions_on_active_account_device".freeze
+  WHERE = "revoked_at IS NULL AND device_id IS NOT NULL".freeze
+  DETACHED_MARKER = ":detached:".freeze
+
+  def up
+    pg = connection.adapter_name.downcase.include?("postgres")
+    concurrent = pg ? { algorithm: :concurrently } : {}
+
+    # A CONCURRENTLY build that failed (e.g. a duplicate inserted mid-build)
+    # leaves an INVALID index behind, which if_not_exists would then skip.
+    # Drop it so a re-run actually rebuilds.
+    if pg && invalid_postgres_index?(INDEX_NAME)
+      remove_index :standard_id_sessions, name: INDEX_NAME, if_exists: true, **concurrent
+    end
+
+    detach_duplicate_active_device_sessions!
+
+    add_index :standard_id_sessions,
+      [:account_id, :device_id],
+      unique: true,
+      where: WHERE,
+      name: INDEX_NAME,
+      if_not_exists: true,
+      **concurrent
+  end
+
+  def down
+    pg = connection.adapter_name.downcase.include?("postgres")
+    concurrent = pg ? { algorithm: :concurrently } : {}
+
+    remove_index :standard_id_sessions, name: INDEX_NAME, if_exists: true, **concurrent
+  end
+
+  private
+
+  def detach_duplicate_active_device_sessions!
+    rows = select_all(<<~SQL.squish).to_a
+      SELECT s.id, s.account_id, s.device_id
+      FROM standard_id_sessions s
+      INNER JOIN (
+        SELECT account_id, device_id
+        FROM standard_id_sessions
+        WHERE #{WHERE}
+        GROUP BY account_id, device_id
+        HAVING COUNT(*) > 1
+      ) dup ON dup.account_id = s.account_id AND dup.device_id = s.device_id
+      WHERE s.revoked_at IS NULL AND s.device_id IS NOT NULL
+      ORDER BY s.account_id, s.device_id, s.created_at DESC, s.id DESC
+    SQL
+
+    rows.group_by { |row| [row["account_id"], row["device_id"]] }.each_value do |group|
+      # group.first is the newest active row: it keeps the device_id.
+      group.drop(1).each do |row|
+        detached = "#{row["device_id"]}#{DETACHED_MARKER}#{row["id"]}"
+        assert_safe do
+          execute(<<~SQL.squish)
+            UPDATE standard_id_sessions
+            SET device_id = #{connection.quote(detached)}
+            WHERE id = #{connection.quote(row["id"])}
+          SQL
+        end
+      end
+    end
+  end
+
+  # A single-row UPDATE by primary key, run only for duplicated device rows:
+  # a deliberate, bounded data fix. Every known host runs StrongMigrations,
+  # which cannot inspect raw SQL; assert safety when it is loaded, and run the
+  # block as-is when it is not (the gem does not depend on it).
+  def assert_safe(&block)
+    respond_to?(:safety_assured) ? safety_assured(&block) : yield
+  end
+
+  def invalid_postgres_index?(name)
+    select_value(<<~SQL.squish).present?
+      SELECT 1
+      FROM pg_index i
+      INNER JOIN pg_class c ON c.oid = i.indexrelid
+      WHERE c.relname = #{connection.quote(name)} AND NOT i.indisvalid
+    SQL
+  end
+end

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

@@ -225,8 +225,9 @@ StandardId.configure do |c|
   # challenge is burned so further submissions fail fast. Distinct from the
   # per-IP rate limit (c.rate_limits.otp_verify_per_ip) — this defends
   # against distributed brute-force against a single challenge.
-  # Default: nil — falls back to :max_attempts for backwards compatibility.
-  # c.passwordless.max_attempts_per_challenge = 5
+  # Default: nil — falls back to :max_attempts (default 3) for backwards
+  # compatibility, so the effective default ceiling is 3.
+  # c.passwordless.max_attempts_per_challenge = 3
 
   # Default: 3 — deprecated alias for :max_attempts_per_challenge. Retained
   # for backwards compatibility; new installs should set the newer key.

data/lib/standard_id/config/schema.rb

@@ -162,7 +162,10 @@ StandardId::ConfigSchema.define do
     # rate limit (config.rate_limits.otp_verify_per_ip) — the per-IP limit
     # prevents brute-forcing from a single source, while this ceiling defends
     # against distributed brute-force attempts against the same challenge.
-    # When nil, falls back to :max_attempts for backwards compatibility.
+    # When nil, falls back to :max_attempts for backwards compatibility, so the
+    # effective default is 3 (:max_attempts' default), not 5. 5 is only the
+    # last resort when both are unset or non-positive
+    # (StandardId::Passwordless::FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE).
     field :max_attempts_per_challenge, type: :integer, default: nil
 
     field :retry_delay, type: :integer, default: 30 # 30 seconds
@@ -341,6 +344,39 @@ StandardId::ConfigSchema.define do
     # and prefers an `active?`-responding record if multiple match.
     field :audience_profile_resolver, type: :any, default: nil
 
+    # Audience → scope-vocabulary binding (the per-audience MCP scope hook).
+    #
+    # Maps each configured audience string to the Array<String> of scopes a
+    # client targeting that audience may request and be granted. This is the
+    # scope-side counterpart to `audience_profile_types`: that binds an audience
+    # to a required profile, this binds an audience to a grantable scope
+    # vocabulary. `StandardId::Oauth::AudienceScopeResolver` reads it.
+    #
+    # Values may be a single space-delimited String or an Array<String>.
+    #
+    # Example:
+    #   c.oauth.audience_scopes = {
+    #     "harness"       => %w[mcp mcp:read mcp:eval:run mcp:prompt:write],
+    #     "companion_kit" => %w[mcp mcp:read],
+    #     "admin_kit"     => %w[mcp mcp:read mcp:admin]
+    #   }
+    #
+    # When empty (default) or the matched audience is absent from the map, the
+    # vocabulary is empty and the resolver's enforcement helpers fail OPEN
+    # (requested scopes pass through unchanged) — back-compat with apps that do
+    # not model per-audience scope vocabularies.
+    field :audience_scopes, type: :hash, default: -> { {} }
+
+    # Optional resolver for computing an audience's scope vocabulary
+    # dynamically (e.g. per-client entitlements). Called with keyword arguments
+    # `(audience:, client:, configured_scopes:)` — any subset is accepted,
+    # arguments are filtered by arity — where `configured_scopes` is the
+    # `Array<String>` from `audience_scopes` for that audience. Must return an
+    # Array<String> (or nil to fall back to the static `audience_scopes` map).
+    #
+    # When nil (default), only the static `audience_scopes` map is consulted.
+    field :audience_scope_resolver, type: :any, default: nil
+
     # JWT signing configuration (for asymmetric algorithms)
     # If nil, uses HS256 with Rails.application.secret_key_base
     field :signing_key, type: :any, default: nil

data/lib/standard_id/oauth/audience_scope_resolver.rb

@@ -0,0 +1,179 @@
+module StandardId
+  module Oauth
+    # Resolves the scope VOCABULARY a given audience is allowed to express —
+    # the set of scope strings a client targeting that audience may request and
+    # be granted. This is the hook an app uses to declare its per-audience MCP
+    # scope vocabulary through the gem, rather than hard-coding a single flat
+    # `scopes_supported` list that every audience shares.
+    #
+    # It is the scope-side counterpart to `AudienceProfileResolver`
+    # (`c.oauth.audience_profile_types` + `c.oauth.audience_profile_resolver`):
+    # that one binds an audience to the PROFILE an account must hold; this one
+    # binds an audience to the SCOPES a client may carry. The two are read the
+    # same way and configured the same way, on purpose.
+    #
+    # Configuration (both optional, both default to "unconfigured"):
+    #
+    #   # Static map: audience string => Array<String> of grantable scopes.
+    #   c.oauth.audience_scopes = {
+    #     "harness"       => %w[mcp mcp:read mcp:eval:run mcp:prompt:write],
+    #     "companion_kit" => %w[mcp mcp:read],
+    #     "admin_kit"     => %w[mcp mcp:read mcp:admin]
+    #   }
+    #
+    #   # Optional callable, for apps that compute the vocabulary dynamically
+    #   # (e.g. per-client entitlements). Receives keyword args
+    #   # `(audience:, client:, configured_scopes:)` — any subset is accepted,
+    #   # arguments are filtered by arity — and must return an Array<String>
+    #   # (or nil to fall back to the static map for that audience).
+    #   c.oauth.audience_scope_resolver = ->(audience:, client:, **) {
+    #     Entitlements.mcp_scopes_for(client, audience)
+    #   }
+    #
+    # When an audience is UNCONFIGURED (absent from the map and the resolver
+    # returns nil / is unset), the vocabulary is empty and the enforcement
+    # helpers below fail OPEN — they pass the requested scopes through
+    # unchanged. This mirrors `audience_profile_types`: an app that does not
+    # model per-audience scope vocabularies sees no behaviour change. Narrowing
+    # only bites once an audience has an explicit vocabulary.
+    #
+    # @example
+    #   StandardId::Oauth::AudienceScopeResolver.filter(
+    #     requested: %w[mcp mcp:admin openid],
+    #     audience: "companion_kit"
+    #   ) # => ["mcp"]   (mcp:admin + openid are not in companion_kit's vocabulary)
+    module AudienceScopeResolver
+      class << self
+        # The scope vocabulary for `audience` as an Array<String>.
+        #
+        # Resolution order:
+        #   1. the configured callable `audience_scope_resolver`, when set and
+        #      it returns a non-nil value — filtered by arity like every other
+        #      gem callable, and handed the static-map value as
+        #      `configured_scopes:` so it can extend rather than replace it;
+        #   2. otherwise the static `audience_scopes` map entry;
+        #   3. otherwise `[]` (unconfigured).
+        #
+        # Always returns a de-duplicated Array<String> with blanks removed.
+        #
+        # @param audience [String, Symbol, nil]
+        # @param client [Object, nil] the ClientApplication in play, when known;
+        #   passed through to the resolver callable for per-client vocabularies.
+        # @return [Array<String>]
+        def scopes_for(audience:, client: nil)
+          return [] if audience.blank?
+
+          configured = static_scopes_for(audience)
+
+          resolver = StandardId.config.oauth.audience_scope_resolver
+          if resolver.respond_to?(:call)
+            filtered = StandardId::Utils::CallableParameterFilter.filter(
+              resolver,
+              { audience: audience.to_s, client: client, configured_scopes: configured }
+            )
+            resolved = resolver.call(**filtered)
+            return normalize(resolved) unless resolved.nil?
+          end
+
+          configured
+        end
+
+        # True when `audience` has a non-empty scope vocabulary. Callers use
+        # this to distinguish "audience is unconfigured, pass everything" from
+        # "audience is configured with an empty vocabulary, allow nothing".
+        def configured_for?(audience, client: nil)
+          scopes_for(audience: audience, client: client).any?
+        end
+
+        # True when `scope` is within `audience`'s vocabulary. An unconfigured
+        # audience permits every scope (fail-open) — see the module note.
+        #
+        # @param scope [String, Symbol]
+        def permits?(scope:, audience:, client: nil)
+          return false if scope.blank?
+
+          vocabulary = scopes_for(audience: audience, client: client)
+          return true if vocabulary.empty? # unconfigured -> fail open
+
+          vocabulary.include?(scope.to_s)
+        end
+
+        # The subset of `requested` that `audience`'s vocabulary permits, in the
+        # requested order, de-duplicated. An unconfigured audience returns the
+        # requested scopes unchanged (fail-open). Use this to NARROW a grant
+        # down to what the audience allows without raising.
+        #
+        # @param requested [Array<String>, String] space-delimited String or Array
+        # @return [Array<String>]
+        def filter(requested:, audience:, client: nil)
+          req = normalize(requested)
+          vocabulary = scopes_for(audience: audience, client: client)
+          return req if vocabulary.empty? # unconfigured -> pass through
+
+          allowed = vocabulary.to_set
+          req.select { |s| allowed.include?(s) }
+        end
+
+        # The scopes in `requested` that `audience`'s vocabulary does NOT permit.
+        # Empty for an unconfigured audience (nothing is out of vocabulary when
+        # there is no vocabulary).
+        #
+        # @return [Array<String>]
+        def disallowed(requested:, audience:, client: nil)
+          req = normalize(requested)
+          vocabulary = scopes_for(audience: audience, client: client)
+          return [] if vocabulary.empty?
+
+          allowed = vocabulary.to_set
+          req.reject { |s| allowed.include?(s) }
+        end
+
+        # Strict, fail-closed variant for mint / registration enforcement.
+        #
+        # Returns the requested scopes (normalized) when every one is within the
+        # audience's vocabulary, and raises `StandardId::InvalidScopeError` —
+        # which renders as RFC 6749 `invalid_scope` — the moment one is not. An
+        # unconfigured audience is a no-op pass-through (fail-open), so wiring
+        # this into a mint path does not change behaviour for audiences that
+        # have not opted in.
+        #
+        # The error message names the offending scopes (which are the CLIENT's
+        # own request, not internal taxonomy) but never the full vocabulary, so
+        # the endpoint does not become a scope-enumeration oracle.
+        #
+        # @raise [StandardId::InvalidScopeError]
+        # @return [Array<String>]
+        def assert!(requested:, audience:, client: nil)
+          bad = disallowed(requested: requested, audience: audience, client: client)
+          return normalize(requested) if bad.empty?
+
+          raise StandardId::InvalidScopeError,
+            "Scope(s) not permitted for audience '#{audience}': #{bad.join(', ')}"
+        end
+
+        private
+
+        def static_scopes_for(audience)
+          mapping = StandardId.config.oauth.audience_scopes || {}
+          return [] if mapping.empty?
+
+          normalize(mapping[audience.to_s] || mapping[audience.to_sym])
+        end
+
+        # Coerce a String (space-delimited) or Array into a clean, de-duplicated
+        # Array<String>. Matches the space-delimited scope convention used by
+        # ClientApplication#scopes_array and RFC 6749.
+        def normalize(value)
+          list =
+            case value
+            when nil then []
+            when Array then value
+            else value.to_s.split(/\s+/)
+            end
+
+          list.map { |s| s.to_s.strip }.reject(&:blank?).uniq
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/oauth/oauth_session_persistence.rb

@@ -37,41 +37,83 @@ module StandardId
         end
       end
 
+      # Reuse the device's ACTIVE session row, or start a new one.
+      #
+      # Only a non-revoked row is eligible. Sign-out (/oauth/revoke under the
+      # default :account revocation_scope) revokes every active DeviceSession
+      # for the account; reusing that revoked row on the next sign-in — which a
+      # bare `find_by(account:, device_id:)` did — linked every new refresh
+      # token to a revoked parent, so RefreshTokenFlow#validate_parent_session!
+      # refused the very first refresh and the client was bounced to sign-in
+      # after every access-token expiry, forever. A revoked row is history (the
+      # audit trail and admin session lists still read it); a new sign-in gets
+      # a new row. Expiry is deliberately NOT part of eligibility: an expired
+      # but unrevoked row is reused with its expires_at bumped, as before.
       def upsert_device_session!(account:, request:, audience:, grant_type:)
         user_agent = request.user_agent
         device_id = stable_device_id(account: account, user_agent: user_agent, audience: audience)
         ip_address = StandardId::Utils::IpNormalizer.normalize(request.remote_ip)
 
-        # Serialize concurrent upserts for the same account. There's no
-        # DB-level unique constraint on (account_id, device_id), so a raw
-        # find_by + create! would TOCTOU-race two concurrent token requests
-        # for the same device into two duplicate rows. We acquire a SELECT
-        # ... FOR UPDATE on the account row to serialize — account.with_lock
-        # is unavailable because StandardId::AccountLocking overrides lock!
-        # with a business-level method that takes a :reason kwarg.
-        # The outer transaction (opened by TokenGrantFlow#generate_token_response)
+        # Serialize concurrent upserts for the same account. We acquire a
+        # SELECT ... FOR UPDATE on the account row — account.with_lock is
+        # unavailable because StandardId::AccountLocking overrides lock! with a
+        # business-level method that takes a :reason kwarg. The outer
+        # transaction (opened by TokenGrantFlow#generate_token_response)
         # releases the lock on commit/rollback.
+        #
+        # The lock alone is not the guarantee: the partial unique index from
+        # 20260924000000 (one active row per account + device_id) is. The lock
+        # keeps the common case free of unique violations; the savepoint below
+        # handles the rest, and keeps hosts that have not yet run that
+        # migration no worse off than before.
         account.class.where(id: account.id).lock.first
 
-        existing = StandardId::DeviceSession.find_by(account: account, device_id: device_id)
-        if existing
-          existing.update!(
-            expires_at: StandardId::DeviceSession.expiry,
-            ip_address: ip_address || existing.ip_address,
-            device_agent: user_agent || existing.device_agent
-          )
-          existing
-        else
-          StandardId::DeviceSession.create!(
-            account: account,
-            device_id: device_id,
-            device_agent: user_agent.presence || "OAuth:#{grant_type}",
-            ip_address: ip_address || "0.0.0.0",
-            expires_at: StandardId::DeviceSession.expiry
-          )
+        existing = active_device_session(account: account, device_id: device_id)
+        return refresh_device_session!(existing, ip_address: ip_address, user_agent: user_agent) if existing
+
+        begin
+          # Savepoint, so a unique violation does not abort the enclosing token
+          # transaction (Postgres refuses every later statement in an aborted
+          # transaction).
+          StandardId::DeviceSession.transaction(requires_new: true) do
+            StandardId::DeviceSession.create!(
+              account: account,
+              device_id: device_id,
+              device_agent: user_agent.presence || "OAuth:#{grant_type}",
+              ip_address: ip_address || "0.0.0.0",
+              expires_at: StandardId::DeviceSession.expiry
+            )
+          end
+        rescue ActiveRecord::RecordNotUnique
+          # A concurrent sign-in for the same device committed its row first.
+          # Reuse the winner rather than failing the token request.
+          winner = active_device_session(account: account, device_id: device_id)
+          raise unless winner
+
+          refresh_device_session!(winner, ip_address: ip_address, user_agent: user_agent)
         end
       end
 
+      # Newest first: before the unique index existed, a race could leave two
+      # active rows for one device, and an unordered lookup picked one
+      # arbitrarily. The migration detaches such duplicates, but hosts that
+      # have not run it yet still benefit from a deterministic choice.
+      def active_device_session(account:, device_id:)
+        StandardId::DeviceSession
+          .where(account: account, device_id: device_id, revoked_at: nil)
+          .order(created_at: :desc, id: :desc)
+          .first
+      end
+
+      def refresh_device_session!(session, ip_address:, user_agent:)
+        session.update!(
+          expires_at: StandardId::DeviceSession.expiry,
+          ip_address: ip_address || session.ip_address,
+          device_agent: user_agent || session.device_agent
+        )
+        session
+      end
+
       def stable_device_id(account:, user_agent:, audience:)
         audience_key = Array(audience).join(",")
         Digest::SHA256.hexdigest("oauth:#{audience_key}:#{account.id}:#{user_agent}")[0, 36]

data/lib/standard_id/oauth/refresh_token_flow.rb

@@ -81,6 +81,7 @@ module StandardId
           if (successor = graced_successor_for(@current_refresh_token_record))
             emit_reuse_graced_event(@current_refresh_token_record, successor)
             @current_refresh_token_record = successor
+            @served_from_graced_successor = true
           else
             # Reuse detected: this token was already rotated. Revoke entire family.
             @current_refresh_token_record.revoke_family!
@@ -166,9 +167,24 @@ module StandardId
         raise ActiveRecord::Rollback
       end
 
+      # Only a request that presented the lost-the-race token ITSELF is treated
+      # as reuse. A request served from a graced successor that loses the race
+      # is the leeway's own retry colliding with another retry of the same lost
+      # response — a client re-sending the superseded token twice in quick
+      # succession. Both passed #graced_successor_for while the successor was
+      # untouched; one rotated it. Revoking the family here would kill the
+      # token the winning request just issued and log the honest client out,
+      # which is exactly what the leeway exists to prevent. The loser gets a
+      # plain invalid_grant and the client keeps the winner's response.
+      #
+      # This does not widen the leeway: the winner already consumed the
+      # successor, so a later replay of the superseded token finds a USED
+      # successor and revokes the family as before.
       def handle_concurrent_reuse!
         @current_refresh_token_record&.reload
         if @current_refresh_token_record&.revoked?
+          raise StandardId::InvalidGrantError, "Refresh token is no longer valid" if @served_from_graced_successor
+
           @current_refresh_token_record.revoke_family!
           emit_reuse_detected_event
           raise StandardId::InvalidGrantError, "Refresh token reuse detected"
@@ -208,7 +224,12 @@ module StandardId
         return nil if revoked_record.revoked_at.blank?
         return nil if revoked_record.revoked_at < leeway.seconds.ago
 
-        successor = StandardId::RefreshToken.find_by(previous_token_id: revoked_record.id)
+        # eager_load(:session), matching the primary lookup in
+        # #validate_refresh_token_record!: the successor becomes
+        # @current_refresh_token_record, and #validate_parent_session! reads its
+        # :session. A bare find_by left that a lazy read, which raises
+        # StrictLoadingViolationError (a 500) under strict loading.
+        successor = StandardId::RefreshToken.eager_load(:session).find_by(previous_token_id: revoked_record.id)
         return nil unless successor&.active?
         return nil if StandardId::RefreshToken.exists?(previous_token_id: successor.id)
 

data/lib/standard_id/passwordless.rb

@@ -2,6 +2,12 @@ require "standard_id/passwordless/verification_service"
 
 module StandardId
   module Passwordless
+    # Last-resort per-challenge attempt ceiling, used only when neither
+    # :max_attempts_per_challenge nor :max_attempts is a positive number. NOT
+    # the default: with default config the ceiling is 3 (see
+    # .max_attempts_per_challenge).
+    FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE = 5
+
     class << self
       # Public API for verifying a passwordless OTP code.
       #
@@ -76,12 +82,18 @@ module StandardId
       # Resolve the per-challenge attempt ceiling, preferring the newer
       # :max_attempts_per_challenge setting but falling back to :max_attempts
       # for backwards compatibility with apps that configured the older name.
+      #
+      # With default config this resolves to 3 (:max_attempts' default).
+      # FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE applies only when BOTH settings are
+      # unset or non-positive (e.g. `max_attempts = 0` / nil) — a ceiling of
+      # zero would burn every challenge on its first wrong code, so it is never
+      # honoured.
       def max_attempts_per_challenge
         configured = StandardId.config.passwordless.max_attempts_per_challenge
         return configured.to_i if configured && configured.to_i.positive?
 
         legacy = StandardId.config.passwordless.max_attempts.to_i
-        legacy.positive? ? legacy : 5
+        legacy.positive? ? legacy : FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE
       end
 
       # Minimum seconds that must elapse between successive code requests for

data/lib/standard_id/testing/factories/oauth.rb

@@ -12,7 +12,6 @@ FactoryBot.define do
     require_pkce { true }
     code_challenge_methods { "S256" }
     access_token_lifetime { 3600 }
-    refresh_token_lifetime { 2_592_000 }
     authorization_code_lifetime { 600 }
     active { true }
 

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.40.0"
+  VERSION = "0.41.1"
 end

data/lib/standard_id.rb

@@ -29,6 +29,7 @@ require "standard_id/api/token_manager"
 require "standard_id/api/authentication_guard"
 require "standard_id/utils/callable_parameter_filter"
 require "standard_id/oauth/audience_profile_resolver"
+require "standard_id/oauth/audience_scope_resolver"
 require "standard_id/oauth/base_request_flow"
 require "standard_id/oauth/token_lifetime_resolver"
 require "standard_id/oauth/oauth_session_persistence"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.40.0
+  version: 0.41.1
 platform: ruby
 authors:
 - Jaryl Sim
@@ -230,6 +230,8 @@ files:
 - db/migrate/20260414200000_add_target_created_at_index_to_code_challenges.rb
 - db/migrate/20260416180511_add_partial_indexes_for_active_session_and_challenge_lookups.rb
 - db/migrate/20260611000000_create_standard_id_client_grants.rb
+- db/migrate/20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications.rb
+- db/migrate/20260924000000_add_unique_active_device_index_to_standard_id_sessions.rb
 - lib/generators/standard_id/install/install_generator.rb
 - lib/generators/standard_id/install/templates/standard_id.rb
 - lib/standard_id.rb
@@ -261,6 +263,7 @@ files:
 - lib/standard_id/http_client.rb
 - lib/standard_id/jwt_service.rb
 - lib/standard_id/oauth/audience_profile_resolver.rb
+- lib/standard_id/oauth/audience_scope_resolver.rb
 - lib/standard_id/oauth/authorization_code_authorization_flow.rb
 - lib/standard_id/oauth/authorization_code_flow.rb
 - lib/standard_id/oauth/authorization_flow.rb