standard_id 0.32.0 → 0.34.0

data/app/models/concerns/standard_id/account_associations.rb

@@ -3,11 +3,24 @@ module StandardId
     extend ActiveSupport::Concern
 
     included do
-      has_many :identifiers, class_name: "StandardId::Identifier", dependent: :restrict_with_exception
-      has_many :credentials, class_name: "StandardId::Credential", through: :identifiers, source: :credentials, dependent: :restrict_with_exception
-      has_many :sessions, class_name: "StandardId::Session", dependent: :restrict_with_exception
-      has_many :refresh_tokens, class_name: "StandardId::RefreshToken", dependent: :restrict_with_exception
-      has_many :client_applications, class_name: "StandardId::ClientApplication", as: :owner, dependent: :restrict_with_exception
+      # `strict_loading:` is passed at declaration time — the supported Rails
+      # API, and the only thing that works for the `:through` association below,
+      # where re-declaration in the host risks ordering breakage. It resolves to
+      # NO OPTION AT ALL unless `config.association_strict_loading` is set, so
+      # these associations keep inheriting the owner's setting by default. See
+      # StandardId::AssociationStrictLoading for why `nil` must not become
+      # `strict_loading: nil`.
+      #
+      # This block runs when the HOST's Account class body runs, so the config
+      # must already be set by then; `AssociationStrictLoading.verify_consistency!`
+      # turns a too-late assignment into a boot failure instead of a silent one.
+      strict_loading_option = StandardId::AssociationStrictLoading.option
+
+      has_many :identifiers, class_name: "StandardId::Identifier", dependent: :restrict_with_exception, **strict_loading_option
+      has_many :credentials, class_name: "StandardId::Credential", through: :identifiers, source: :credentials, dependent: :restrict_with_exception, **strict_loading_option
+      has_many :sessions, class_name: "StandardId::Session", dependent: :restrict_with_exception, **strict_loading_option
+      has_many :refresh_tokens, class_name: "StandardId::RefreshToken", dependent: :restrict_with_exception, **strict_loading_option
+      has_many :client_applications, class_name: "StandardId::ClientApplication", as: :owner, dependent: :restrict_with_exception, **strict_loading_option
 
       accepts_nested_attributes_for :identifiers
     end

data/app/models/standard_id/identifier.rb

@@ -2,7 +2,10 @@ module StandardId
   class Identifier < ApplicationRecord
     belongs_to :account, class_name: StandardId.config.account_class_name
 
-    has_many :credentials, class_name: "StandardId::Credential", dependent: :restrict_with_exception
+    # See StandardId::AssociationStrictLoading — resolves to no option at all
+    # unless config.association_strict_loading is set.
+    has_many :credentials, class_name: "StandardId::Credential", dependent: :restrict_with_exception,
+             **StandardId::AssociationStrictLoading.option
 
     scope :verified, -> { where.not(verified_at: nil) }
     scope :unverified, -> { where(verified_at: nil) }

data/app/models/standard_id/session.rb

@@ -5,7 +5,10 @@ module StandardId
     self.table_name = "standard_id_sessions"
 
     belongs_to :account, class_name: StandardId.config.account_class_name
-    has_many :refresh_tokens, class_name: "StandardId::RefreshToken", dependent: :nullify
+    # See StandardId::AssociationStrictLoading — resolves to no option at all
+    # unless config.association_strict_loading is set.
+    has_many :refresh_tokens, class_name: "StandardId::RefreshToken", dependent: :nullify,
+             **StandardId::AssociationStrictLoading.option
 
     before_destroy :revoke_active_refresh_tokens, prepend: true
 
@@ -97,6 +100,118 @@ module StandardId
       false
     end
 
+    # Counts returned by the bulk-revocation class methods. Callers use these to
+    # emit their own aggregate event (see
+    # StandardId::Api::Oauth::RevocationsController#emit_token_revoked) — the
+    # bulk methods deliberately do NOT publish an aggregate themselves.
+    RevocationResult = Struct.new(:sessions_revoked, :refresh_tokens_revoked, keyword_init: true)
+
+    # Revoke every not-yet-revoked session for an account, cascading to refresh
+    # tokens, in two set-based UPDATEs.
+    #
+    # Honours the current scope, so callers narrow as they need:
+    #
+    #   StandardId::Session.revoke_all_for!(account, reason: "password_reset")
+    #   StandardId::DeviceSession.active.revoke_all_for!(account, reason: "logout")
+    #
+    # Why this exists rather than `sessions.each(&:revoke!)`: the loop is O(N)
+    # UPDATEs plus O(N) refresh-token cascades, and the call sites are admin bulk
+    # actions and password resets.
+    #
+    # Events: one SESSION_REVOKED per revoked session, never a single aggregate —
+    # subscribers must not need a second code path for bulk revocation. Each is
+    # published individually and individually rescued (see .revoke_sessions!).
+    #
+    # @param account [ActiveRecord::Base, String, Integer] the account, or its id
+    # @param reason [String, nil] carried on each SESSION_REVOKED event
+    # @return [RevocationResult] counts of revoked sessions and refresh tokens
+    def self.revoke_all_for!(account, reason: nil)
+      account_id = account.is_a?(ActiveRecord::Base) ? account.id : account
+      sessions = where(account_id: account_id).where(revoked_at: nil).to_a
+      account_record = account.is_a?(ActiveRecord::Base) ? account : nil
+
+      revoke_sessions!(sessions, account: account_record, reason: reason)
+    end
+
+    # Set-based revocation of an explicit collection of sessions.
+    #
+    # Bulk-revoke in two queries (one UPDATE per table) instead of issuing
+    # session.revoke! per row, which would be O(N) UPDATEs plus another O(N)
+    # cascades to refresh_tokens.
+    #
+    # Tradeoff: update_all skips ActiveRecord callbacks, so the per-row
+    # SESSION_REVOKED event emitted by #revoke! (via its after_commit) does not
+    # fire automatically. We re-emit it explicitly below so audit-trail
+    # subscribers (account status/locking, etc.) still see one event per revoked
+    # session — the semantics are preserved, only the SQL shape has changed.
+    #
+    # @param sessions [Enumerable<StandardId::Session>] sessions to revoke; all
+    #   must belong to the same account
+    # @param account [ActiveRecord::Base, nil] the shared account, when the
+    #   caller already has it loaded. Passed through rather than read per row:
+    #   `session.account` would issue N extra SELECTs. Falls back to
+    #   `sessions.first.account`.
+    # @param reason [String, nil] carried on each SESSION_REVOKED event
+    # @return [RevocationResult] counts of revoked sessions and refresh tokens
+    def self.revoke_sessions!(sessions, account: nil, reason: nil)
+      sessions = sessions.to_a
+      return RevocationResult.new(sessions_revoked: 0, refresh_tokens_revoked: 0) if sessions.empty?
+
+      now = Time.current
+      session_ids = sessions.map(&:id)
+      refresh_tokens_revoked = 0
+
+      ActiveRecord::Base.transaction do
+        StandardId::Session.where(id: session_ids).update_all(revoked_at: now)
+        refresh_tokens_revoked = StandardId::RefreshToken
+          .where(session_id: session_ids, revoked_at: nil)
+          .update_all(revoked_at: now)
+      end
+
+      publish_session_revocations(sessions, account: account, reason: reason, now: now)
+
+      RevocationResult.new(
+        sessions_revoked: sessions.size,
+        refresh_tokens_revoked: refresh_tokens_revoked
+      )
+    end
+
+    # DB state is already committed by the time this runs; event publishing is
+    # best-effort audit emission. A failing subscriber must not short-circuit the
+    # loop and leave later sessions without their SESSION_REVOKED event, which
+    # would permanently desync audit-trail consumers from the DB.
+    def self.publish_session_revocations(sessions, account:, reason:, now:)
+      shared_account = account || sessions.first.account
+
+      sessions.each do |session|
+        session.revoked_at = now
+
+        begin
+          StandardId::Events.publish(
+            StandardId::Events::SESSION_REVOKED,
+            session: session,
+            account: shared_account,
+            reason: reason
+          )
+        rescue StandardError => e
+          # The rescue exists so a failing subscriber cannot short-circuit the
+          # loop. Logging must therefore not be able to raise either, or the
+          # guarantee evaporates on the first bad log call: StandardId.logger is
+          # a memoized `config.logger || Rails.logger`, so whatever the first
+          # reader saw is what every later caller gets — including a value that
+          # is not a logger at all.
+          logger = StandardId.logger
+          next unless logger.respond_to?(:error)
+
+          logger.error(
+            "[StandardId::Session] Failed to publish SESSION_REVOKED " \
+            "for session #{session.id}: #{e.class}: #{e.message}"
+          )
+        end
+      end
+    end
+    private_class_method :publish_session_revocations
+
     attr_reader :token
 
     before_validation :generate_token, :generate_token_digest, :generate_lookup_hash, on: :create

data/config/routes/api.rb

@@ -18,6 +18,11 @@ StandardId::ApiEngine.routes.draw do
       resource :token, only: [:create]
       resource :revoke, only: [:create], controller: :revocations
 
+      # RFC 7662 Token Introspection -> POST /oauth/introspect.
+      # The controller returns 404 when oauth.introspection_enabled is false, so
+      # the endpoint is fully absent unless explicitly enabled.
+      resource :introspect, only: [:create], controller: :introspections
+
       # RFC 7591 Dynamic Client Registration -> POST /oauth/register.
       # The controller returns 404 when oauth.dynamic_registration_enabled is
       # false, so the endpoint is fully absent unless explicitly enabled.

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

@@ -20,6 +20,60 @@ StandardId.configure do |c|
   # Default: nil
   # c.issuer = "https://auth.example.com"
 
+  # ---------------------------------------------------------------------------
+  # Discovery documents (/.well-known/openid-configuration and
+  # /.well-known/oauth-authorization-server)
+  # ---------------------------------------------------------------------------
+  # READ THIS IF YOU MOUNT ApiEngine UNDER A PREFIX (/api, /api/v1, ...).
+  #
+  # The issuer and the endpoint base are different things. `issuer` is a stable
+  # security identifier (RFC 8414 §2) that clients compare byte-for-byte with the
+  # URL they used for discovery and with the `iss` claim of issued tokens. It is
+  # never derived from the request and cannot be overridden.
+  #
+  # `discovery_endpoint_base` is where /authorize, /oauth/token etc. ACTUALLY
+  # are. It defaults to the issuer, which is right only if your issuer carries
+  # the mount path (e.g. "https://host/auth/api"). If it does not, the document
+  # advertises endpoints at the bare origin and every one of them 404s.
+  #
+  #   nil (default) — the issuer
+  #   :request      — request.base_url + the detected mount path  <- prefixed mounts
+  #   "https://..." — verbatim
+  #   callable      — receives (request:); for a proxy that rewrites base_url, or
+  #                   an app mounting ApiEngine more than once
+  #
+  # Default: nil
+  # c.oauth.discovery_endpoint_base = :request
+
+  # Members that cannot be derived. Values static or callable; a callable gets
+  # { origin:, endpoint_base:, issuer:, request: } (origin has no path). A nil
+  # value REMOVES the member rather than emitting null. Setting `issuer` raises.
+  # Default: {}
+  # c.oauth.discovery_metadata_overrides = {
+  #   # a host-owned shim that injects the audience before handing off to the
+  #   # engine's /authorize
+  #   authorization_endpoint: ->(ctx) { "#{ctx[:origin]}/oauth/authorize" },
+  #   # narrower than everything the server can mint
+  #   scopes_supported: %w[mcp mcp:read],
+  #   # MUST mirror your dynamic-registration policy, or spec-following clients
+  #   # register in a way that policy then rejects
+  #   token_endpoint_auth_methods_supported: %w[none],
+  #   # omit a member entirely
+  #   userinfo_endpoint: nil
+  # }
+  #
+  # RFC 8615 clients probe the ORIGIN ROOT, which is outside every engine mount,
+  # so those routes must be drawn in config/routes.rb — the gem cannot:
+  #
+  #   standard_id_well_known_routes at: "/api"   # your ApiEngine mount path
+  #
+  # That draws the root form AND the RFC 8414 §3.1 path-inserted form
+  # (/.well-known/oauth-authorization-server/api). The second looks redundant
+  # and is not: it is the URL Claude Code actually requests against a
+  # path-carrying issuer. Accepts only:/except: (:oauth_authorization_server,
+  # :openid_configuration, :jwks) — e.g. `only: :jwks` if you keep your own
+  # metadata controller. See docs/MIGRATION_GUIDE.md.
+
   # Login URL used for redirects when authentication is required but missing.
   # Default: "/login"
   # c.login_url = "/login"
@@ -44,6 +98,31 @@ StandardId.configure do |c|
   # Default: false
   # c.alias_current_user = true
 
+  # Opt StandardId's OWN associations out of an app-wide
+  # `strict_loading_by_default = true`.
+  #
+  # Affects Account#identifiers/credentials/sessions/refresh_tokens/
+  # client_applications, StandardId::Session#refresh_tokens and
+  # StandardId::Identifier#credentials. Set it to false if strict loading is on
+  # app-wide and you don't want to eager-load the gem's internals at every call
+  # site (the gem lazy-loads some of them itself).
+  #
+  # Tri-state, and nil is NOT the same as false:
+  #   nil   — declare no `strict_loading:` option at all; the associations
+  #           inherit your model's setting, exactly as before this option
+  #           existed. This is the default and preserves existing behaviour.
+  #   false — opt out: these associations may lazy-load even with strict
+  #           loading on app-wide.
+  #   true  — opt in: force strict loading on them even if it is off app-wide.
+  #
+  # Must be set HERE, in an initializer — not in an `after_initialize` block.
+  # The associations read it when your Account class body runs, so a later
+  # assignment has no effect. StandardId raises a ConfigurationError at boot if
+  # it detects that, rather than letting it fail silently.
+  #
+  # Default: nil
+  # c.association_strict_loading = false
+
   # Default scope applied when loading the current account — eager-load the
   # associations your views/controllers touch to avoid N+1s.
   # Default: nil
@@ -241,6 +320,29 @@ StandardId.configure do |c|
   # Must return a Hash. Reserved JWT keys (sub, exp, iat, etc.) are excluded.
   # c.oauth.custom_claims = ->(account:, **) { { channel_id: account.channel_id } }
 
+  # RFC 7662 token introspection (POST /oauth/introspect).
+  #
+  # Off by default: the endpoint returns 404 and `introspection_endpoint` is not
+  # advertised in the discovery documents. An endpoint that answers questions
+  # about other people's tokens is not something to expose by accident.
+  #
+  # Confidential clients only — the caller presents client_id + client_secret
+  # (HTTP Basic or form body). Every failure renders `{"active": false}` with no
+  # other members, per RFC 7662 §2.2, including a tripped rate limit (a 429
+  # would distinguish "throttled" from "token invalid" and make the limiter a
+  # token-validity oracle).
+  #
+  # KNOW THE LIMIT BEFORE BUILDING AN AUTHORIZATION GATE ON THIS. Access tokens
+  # are stateless — never persisted, and carrying no `sid` — so a revoked
+  # session's access token introspects as `active: true` until its `exp`.
+  # Introspection answers "did we mint this, and is it unexpired?", NOT "is it
+  # still honoured?". The mitigation is a short access-token lifetime. Refresh
+  # tokens ARE persisted and are checked against the row, so a revoked refresh
+  # token introspects as inactive immediately.
+  #
+  # Default: false
+  # c.oauth.introspection_enabled = true
+
   # JWT signing configuration.
   #
   # Default: :hs256 symmetric signing with Rails.application.secret_key_base.
@@ -313,8 +415,20 @@ StandardId.configure do |c|
   # ---------------------------------------------------------------------------
   # Social login
   # ---------------------------------------------------------------------------
-  # Requires the standard_id-google and/or standard_id-apple provider gems to
-  # be installed and registered.
+  # These fields are declared by the PROVIDER PLUGIN GEMS, not by standard_id
+  # itself, so each line below requires the matching gem in your Gemfile:
+  # `standard_id-google` for the google_* fields, `standard_id-apple` for the
+  # apple_* fields. Uncommenting a line without its gem raises
+  # StandardId::ConfigurationError ("Unknown field ... for scope 'social'") —
+  # the field genuinely does not exist, because nothing declared it.
+  #
+  # With the gem present, writing them here — in a plain initializer, in the
+  # `social` scope, exactly as shown — is correct and supported. standard_id
+  # >= 0.33.0 declares every loaded provider's fields before initializers run.
+  # On 0.32.0 and earlier these same lines raised, because the fields were only
+  # declared later from the plugin's Railtie, and apps worked around it by
+  # wrapping the writes in `Rails.application.config.after_initialize`. That
+  # wrapper is no longer needed, and it still works if you have one.
 
   # c.social.google_client_id     = ENV["GOOGLE_CLIENT_ID"]
   # c.social.google_client_secret = ENV["GOOGLE_CLIENT_SECRET"]
@@ -377,6 +491,12 @@ StandardId.configure do |c|
   # c.rate_limits.api_passwordless_start_per_target = 5  # per 15 minutes
   # c.rate_limits.api_token_per_ip               = 30  # per 15 minutes
 
+  # Token introspection (only relevant with c.oauth.introspection_enabled).
+  # Throttles by IP so the endpoint can't be used to bulk-classify stolen
+  # tokens. Note the limit renders the ordinary {"active": false} / 200 rather
+  # than 429 — see the introspection_enabled comment above for why.
+  # c.rate_limits.introspection_per_ip           = 30  # per 15 minutes
+
   # Optional per-audience tightening on top of api_token_per_ip. Only token
   # requests targeting a configured audience count toward its cap (per IP,
   # per 15 minutes); unlisted audiences are governed by the global ceiling.

data/lib/standard_id/association_strict_loading.rb

@@ -0,0 +1,121 @@
+module StandardId
+  # Resolves the `strict_loading:` option the gem's own associations declare,
+  # from `StandardId.config.association_strict_loading`.
+  #
+  # WHY THIS EXISTS
+  #
+  # Apps that set `strict_loading_by_default = true` globally cannot fix the
+  # gem's associations by re-declaring them: they are declared inside
+  # `StandardId::AccountAssociations`, and `credentials` is a `has_many
+  # :through`, where re-declaration risks ordering breakage. So two consuming
+  # apps reached into Rails internals instead —
+  #
+  #     Account.reflect_on_association(assoc)&.options&.[]=(:strict_loading, false)
+  #
+  # — both with a comment asking for exactly this hook. Passing
+  # `strict_loading:` at declaration time is the supported Rails API, and unlike
+  # re-declaration it works for the `:through` association.
+  #
+  # WHY A HELPER RATHER THAN `strict_loading: config.association_strict_loading`
+  #
+  # Because `nil` must mean OMITTED, not `false`. Rails checks
+  # `reflection.options.key?(:strict_loading)` *before* consulting the owner:
+  #
+  #     # ActiveRecord::Associations::Association#violates_strict_loading?
+  #     return reflection.strict_loading? if reflection.options.key?(:strict_loading)
+  #     owner.strict_loading? && !owner.strict_loading_n_plus_one_only?
+  #
+  # so declaring `strict_loading: nil` would put the key in the options hash and
+  # make `reflection.strict_loading?` return `!!nil` == false — silently
+  # disabling strict loading on every gem association in every app that never
+  # asked for it. This returns an empty hash in that case instead, so the option
+  # is genuinely absent and the owner's setting still governs.
+  module AssociationStrictLoading
+    module_function
+
+    # Splat into a `has_many` / `has_one` / `belongs_to` declaration:
+    #
+    #   has_many :sessions, class_name: "StandardId::Session",
+    #            **StandardId::AssociationStrictLoading.option
+    #
+    # @return [Hash] `{}` when unconfigured, else `{ strict_loading: <value> }`
+    def option
+      value = StandardId.config.association_strict_loading
+      return {} if value.nil?
+
+      { strict_loading: value }
+    end
+
+    # Associations declared with `**option`, as `owner_class_name => [names]`.
+    # Used by the boot-time consistency check.
+    #
+    # Account's are keyed by the configured account class rather than listed
+    # here, since the host owns that constant.
+    GEM_OWNED = {
+      "StandardId::Session" => %i[refresh_tokens],
+      "StandardId::Identifier" => %i[credentials]
+    }.freeze
+
+    ACCOUNT_ASSOCIATIONS = %i[
+      identifiers credentials sessions refresh_tokens client_applications
+    ].freeze
+
+    # Raise if a declared association disagrees with the configured value.
+    #
+    # The `included do` block in AccountAssociations reads the config when the
+    # host's `Account` class body runs — during autoload, which can happen
+    # *before* an initializer that sets `association_strict_loading`. The result
+    # is silent: strict loading behaves as though the setting were never made,
+    # and the app either raises StrictLoadingViolationError deep in a request or
+    # quietly N+1s in production. This converts that into a boot failure that
+    # names the ordering problem.
+    #
+    # Called from the Engine's `after_initialize`, when both the config and the
+    # host's model are settled.
+    #
+    # @raise [StandardId::ConfigurationError]
+    def verify_consistency!
+      configured = StandardId.config.association_strict_loading
+      return if configured.nil?
+
+      mismatched = mismatched_associations(configured)
+      return if mismatched.empty?
+
+      raise StandardId::ConfigurationError, <<~MESSAGE.strip
+        StandardId.config.association_strict_loading is #{configured.inspect}, but these
+        associations were declared without it: #{mismatched.join(', ')}.
+
+        This means the model class body ran BEFORE the config was set. StandardId's
+        associations read the setting at declaration time, so it must be assigned in
+        `config/initializers/standard_id.rb` — not in an `after_initialize` block, and
+        not anywhere else that can run after your Account class is autoloaded.
+
+        Left unchecked this fails silently: strict loading behaves as though you never
+        made the setting, and the app either raises
+        ActiveRecord::StrictLoadingViolationError inside a request or quietly N+1s in
+        production.
+      MESSAGE
+    end
+
+    def mismatched_associations(configured)
+      pairs = GEM_OWNED.flat_map do |class_name, names|
+        names.map { |name| [class_name.constantize, name] }
+      end
+
+      account_class = begin
+        StandardId.account_class
+      rescue StandardError
+        nil
+      end
+      pairs += ACCOUNT_ASSOCIATIONS.map { |name| [account_class, name] } if account_class
+
+      pairs.filter_map do |klass, name|
+        reflection = klass.reflect_on_association(name)
+        next if reflection.nil?
+        next if reflection.options[:strict_loading] == configured
+
+        "#{klass.name}##{name}"
+      end
+    end
+  end
+end

data/lib/standard_id/config/schema.rb

@@ -12,6 +12,26 @@ StandardId::ConfigSchema.define do
     field :passwordless_email_sender, type: :any, default: nil
     field :passwordless_sms_sender, type: :any, default: nil
     field :issuer, type: :string, default: nil
+
+    # Whether `JwtService.decode` REQUIRES a matching `iss` claim.
+    #
+    # `nil` (default) means "follow the issuer": verification is on exactly
+    # when `issuer` is set. That is the historic behaviour and is what you
+    # want once an issuer has always been configured.
+    #
+    # Set `false` to MINT an `iss` claim without yet REQUIRING one. This
+    # exists because the two were coupled, and that coupling makes adopting an
+    # issuer an all-or-nothing flag day: every token already in flight was
+    # minted without an `iss`, so turning the issuer on rejected all of them at
+    # once — every access token and, far worse, every refresh token. For an app
+    # that had never set an issuer there was no safe single step, which is
+    # exactly the position nutripod-web was stuck in (rarebit-one/nutripod-web#1111).
+    #
+    # The migration is then: set `issuer` with `verify_issuer = false`, wait
+    # out `refresh_token_lifetime` (the long pole — access tokens are short),
+    # then remove the override. Setting `true` with no issuer raises at boot
+    # rather than silently verifying nothing.
+    field :verify_issuer, type: :boolean, default: nil
     field :login_url, type: :string, default: nil
     field :allowed_post_logout_redirect_uris, type: :array, default: []
     field :account_scope, type: :any, default: nil
@@ -19,6 +39,22 @@ StandardId::ConfigSchema.define do
     field :inertia_component_namespace, type: :string, default: "standard_id"
     field :alias_current_user, type: :boolean, default: false
 
+    # Opt the gem's own associations out of an app-wide
+    # `strict_loading_by_default = true`.
+    #
+    # `nil` (default) means "say nothing": the `strict_loading:` option is
+    # omitted from the association declarations entirely, so they inherit the
+    # owner's setting exactly as they always have. `false` opts them out; `true`
+    # forces them on even in an app that has strict loading off.
+    #
+    # This must stay tri-state and `nil` must mean OMITTED, not `false`. Rails
+    # checks `reflection.options.key?(:strict_loading)` before consulting the
+    # owner (ActiveRecord::Associations::Association#violates_strict_loading?),
+    # so declaring `strict_loading: nil` would put the key in the hash and make
+    # `reflection.strict_loading?` return false — silently disabling strict
+    # loading for every app that never asked for it.
+    field :association_strict_loading, type: :any, default: nil
+
     # Scope-aware authentication: maps scope names to profile-based access config.
     # Each scope is a hash with keys: :profile_types (Array<String>), :after_sign_in_path,
     # :no_profile_message, :label, :allow_registration, :authorizer.
@@ -300,6 +336,80 @@ StandardId::ConfigSchema.define do
     # OAuth clients), so it is opt-in: a deployment must explicitly turn it on.
     field :dynamic_registration_enabled, type: :boolean, default: false
 
+    # Enable the RFC 7662 token introspection endpoint (POST /oauth/introspect).
+    #
+    # When false (the default), the endpoint is fully absent (404) and
+    # `introspection_endpoint` is NOT advertised in the discovery documents. An
+    # endpoint that answers questions about other people's tokens is not something
+    # to expose by accident, so it is opt-in — same posture as
+    # `dynamic_registration_enabled`.
+    #
+    # Confidential clients only: the caller authenticates with client_id +
+    # client_secret (HTTP Basic or form body). Every failure renders
+    # `{"active": false}` with no other members, per RFC 7662 §2.2.
+    #
+    # KNOW THE LIMIT BEFORE BUILDING ON IT: access tokens are stateless — never
+    # persisted, and carrying no `sid` — so a revoked session's access token
+    # introspects as `active: true` until its `exp`. Introspection answers "did we
+    # mint this, and is it unexpired?", NOT "is it still honoured?". Keep
+    # `access_token_lifetime` short. Refresh tokens ARE persisted and are checked
+    # against the row, so a revoked refresh token introspects as inactive
+    # immediately.
+    field :introspection_enabled, type: :boolean, default: false
+
+    # Where the discovery documents say the ENDPOINTS live.
+    #
+    # The issuer and the endpoint base are different things. The issuer is a
+    # stable security identifier (RFC 8414 §2) that clients match byte-for-byte
+    # against their discovery URL and against the `iss` claim; it is never
+    # derived from the request and cannot be overridden. This says where
+    # /authorize, /oauth/token etc. actually are.
+    #
+    #   nil (default) — the issuer. Byte-identical to the behaviour before this
+    #                   option existed. Already correct if your issuer carries
+    #                   the ApiEngine mount path (e.g. "https://host/auth/api").
+    #                   WRONG if it does not: the document then advertises
+    #                   endpoints at the bare origin, which 404.
+    #   :request      — request.base_url + the detected mount path. What you want
+    #                   when ApiEngine is mounted under a prefix ("/api",
+    #                   "/api/v1") the issuer does not carry.
+    #   "https://..." — used verbatim.
+    #   callable      — receives (request:). Use when a proxy rewrites
+    #                   request.base_url, or when ApiEngine is mounted more than
+    #                   once (e.g. under host constraints) so no single detected
+    #                   path is right.
+    #
+    # Request-derived is opt-in rather than the default on purpose: defaulting to
+    # it would silently rewrite the document of every app whose issuer host
+    # differs from the host serving the request — the split-host setup a separate
+    # issuer exists to express.
+    field :discovery_endpoint_base, type: :any, default: nil
+
+    # Members of the discovery documents that cannot be derived, as
+    # `{ member => value }`. Values may be static or callable.
+    #
+    # A callable receives one Hash — `{ origin:, endpoint_base:, issuer:,
+    # request: }`, where `origin` is scheme+host+port with no path.
+    #
+    # A `nil` value REMOVES the member rather than emitting null.
+    #
+    # Setting `issuer` RAISES — see discovery_endpoint_base above.
+    #
+    #   c.oauth.discovery_metadata_overrides = {
+    #     # a host-owned shim that injects the audience before handing off to the
+    #     # engine's /authorize
+    #     authorization_endpoint: ->(ctx) { "#{ctx[:origin]}/oauth/authorize" },
+    #     # deliberately narrower than everything the server can mint
+    #     scopes_supported: %w[mcp mcp:read],
+    #     # MUST mirror your dynamic-registration policy: advertising
+    #     # client_secret_* while DCR only accepts public clients makes
+    #     # spec-following clients register in a way DCR then rejects
+    #     token_endpoint_auth_methods_supported: %w[none],
+    #     # omit a member entirely
+    #     grant_types_supported: nil
+    #   }
+    field :discovery_metadata_overrides, type: :hash, default: -> { {} }
+
     # Callable resolving the polymorphic owner assigned to clients created via
     # Dynamic Client Registration (the `owner` association on ClientApplication
     # is required). Example: `-> { Organization.default }`.
@@ -445,5 +555,12 @@ StandardId::ConfigSchema.define do
     # Dynamic client registration (RFC 7591) — throttle the open registration
     # endpoint by IP so an enabled deployment can't be flooded with client rows.
     field :dynamic_registration_per_ip, type: :integer, default: 10      # per hour
+
+    # Token introspection (RFC 7662) — throttle by IP so the endpoint cannot be
+    # used to bulk-classify stolen tokens. Note the limit renders the ordinary
+    # `{"active": false}` / 200 rather than 429: a 429 would distinguish
+    # "throttled" from "token invalid" and turn the limiter into a token-validity
+    # oracle.
+    field :introspection_per_ip, type: :integer, default: 30              # per 15 minutes
   end
 end

data/lib/standard_id/engine.rb

@@ -10,6 +10,33 @@ module StandardId
   class Engine < ::Rails::Engine
     isolate_namespace StandardId
 
+    # Declare provider plugins' `social` config fields BEFORE the host app's
+    # `config/initializers/standard_id.rb` runs, so an initializer can write
+    # `c.social.google_client_id` the way every doc says it can.
+    #
+    # Without this, the only thing that declared those fields was
+    # `ProviderRegistry.register`, called from each plugin Railtie's
+    # `config.after_initialize` — which runs long after
+    # `:load_config_initializers`. The host's write hit
+    # `ConfigSchema::Scope#[]=` → `validate!` against a schema that did not yet
+    # know the field and raised `StandardId::ConfigurationError`, with nothing
+    # in the message to hint that the cause was boot ordering. Consuming apps
+    # each independently rediscovered the same
+    # `Rails.application.config.after_initialize { ... }` wrapper to get around
+    # it, and the install template plus two plugin READMEs documented three
+    # mutually inconsistent forms, two of which raised.
+    #
+    # `before:` rather than a plain positional declaration: engine initializers
+    # otherwise run in `Rails::Engine`-collection order relative to the
+    # application's own, and `:load_config_initializers` is an application
+    # bootstrap step, so an explicit edge is the only ordering guarantee.
+    #
+    # This needs no plugin release — provider classes are required at
+    # gem-require time, so they are already loaded here.
+    initializer "standard_id.provider_config_schemas", before: :load_config_initializers do
+      StandardId::ProviderRegistry.declare_config_schemas!
+    end
+
     initializer "standard_id.filter_parameters" do |app|
       app.config.filter_parameters += %i[
         code_verifier
@@ -39,6 +66,12 @@ module StandardId
                           "Set StandardId.config.issuer in your initializer for production use.")
       end
 
+      # Fail loudly if `association_strict_loading` was assigned after the
+      # host's Account class body already ran — that assignment has no effect,
+      # and its only symptom otherwise is a StrictLoadingViolationError deep in
+      # a request or a silent N+1 in production.
+      StandardId::AssociationStrictLoading.verify_consistency!
+
       # Validate configured callables have the right shape and that every
       # claim listed in scope_claims has a resolver registered. Raising here
       # surfaces typos at boot instead of at callback time in production.