standard_id 0.31.0 → 0.33.0

data/app/controllers/standard_id/api/well_known/openid_configuration_controller.rb

@@ -6,17 +6,20 @@ module StandardId
         public_controller
 
         def show
-          issuer = StandardId.config.issuer
+          resolved = StandardId::Oauth::DiscoveryResolver.resolve(request: request)
 
-          unless issuer.present?
+          unless resolved[:issuer].present?
             render json: { error: "Issuer not configured" }, status: :not_found
             return
           end
 
           response.headers["Cache-Control"] = "public, max-age=3600"
           render json: StandardId::Oauth::DiscoveryDocument.build(
-            issuer,
-            registration_enabled: StandardId.config.oauth.dynamic_registration_enabled
+            resolved[:issuer],
+            endpoint_base: resolved[:endpoint_base],
+            registration_enabled: StandardId.config.oauth.dynamic_registration_enabled,
+            introspection_enabled: StandardId.config.oauth.introspection_enabled,
+            overrides: resolved[:overrides]
           )
         end
       end

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
 
@@ -23,9 +26,10 @@ module StandardId
     #
     # `by_token` is NOT authentication on its own: it matches the SHA256
     # `lookup_hash`, which exists only to find the candidate row from an
-    # indexed column. The credential is the BCrypt `token_digest`, and every
-    # consumer previously had to remember to verify it by hand (and to rescue
-    # BCrypt::Errors::InvalidHash). This is that step, done once, here.
+    # indexed column. The credential is `token_digest` (see #authenticate_token
+    # for the two schemes it may hold), and every consumer previously had to
+    # remember to verify it by hand — and to rescue BCrypt::Errors::InvalidHash.
+    # This is that step, done once, here.
     #
     # Honours the current scope, so callers keep their own filters:
     #
@@ -43,24 +47,171 @@ module StandardId
       session.authenticate_token(token) ? session : nil
     end
 
-    # Timing-safe verification of `token` against this session's stored
-    # BCrypt digest. Re-hashes the presented token with the stored salt and
-    # compares the two digests with a constant-time compare, so the response
-    # time carries no information about how much of the digest matched.
+    # Keyed digest of an opaque session token — the default scheme.
+    #
+    # HMAC-SHA256 under `secret_key_base`, domain-separated from `lookup_hash`
+    # by both construction (HMAC vs plain SHA256) and an explicit versioned
+    # prefix, so the two stored values can never coincide even though both
+    # derive from the same token and secret.
+    #
+    # Why not BCrypt (which this was, and which `token_digest_cost` still
+    # selects): BCrypt's cost factor exists to make brute-force of a LOW-entropy
+    # secret expensive. Session tokens are `SecureRandom.urlsafe_base64(32)` —
+    # 256 bits — so guessing one is infeasible regardless of how fast the hash
+    # is, and the stretching bought nothing while costing a measured ~181 ms of
+    # CPU on EVERY authenticated request (cost 12). That is the same reasoning
+    # under which `RefreshToken` digests with plain SHA256 and `lookup_hash`
+    # with SHA256; this brings session tokens in line with both.
+    DIGEST_PREFIX = "standard_id.session.token_digest.v1:".freeze
+
+    def self.hmac_token_digest(token)
+      OpenSSL::HMAC.hexdigest(
+        "SHA256", Rails.configuration.secret_key_base, "#{DIGEST_PREFIX}#{token}"
+      )
+    end
+
+    # Timing-safe verification of `token` against this session's stored digest.
+    #
+    # Handles BOTH schemes, because digests written before the HMAC default —
+    # and any written since by an app that sets `token_digest_cost` — are
+    # BCrypt. A BCrypt digest is self-identifying by its `$2<x>$` prefix, so the
+    # scheme is read off the stored value rather than off configuration; that
+    # way a config change never strands existing sessions, and no rewrite of
+    # stored digests is needed. Both branches end in a constant-time compare, so
+    # the response time carries no information about how much of the digest
+    # matched.
     #
     # @return [Boolean] false for a blank or malformed digest — never raises.
     def authenticate_token(token)
       return false if token.blank? || token_digest.blank?
 
-      stored = BCrypt::Password.new(token_digest)
-      ActiveSupport::SecurityUtils.secure_compare(
-        stored.to_s,
-        BCrypt::Engine.hash_secret(token, stored.salt)
-      )
+      if token_digest.start_with?("$2")
+        stored = BCrypt::Password.new(token_digest)
+        ActiveSupport::SecurityUtils.secure_compare(
+          stored.to_s,
+          BCrypt::Engine.hash_secret(token, stored.salt)
+        )
+      else
+        ActiveSupport::SecurityUtils.secure_compare(
+          token_digest, self.class.hmac_token_digest(token)
+        )
+      end
     rescue BCrypt::Errors::InvalidHash, BCrypt::Errors::InvalidSalt
       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
@@ -94,11 +245,17 @@ module StandardId
       @token ||= SecureRandom.urlsafe_base64(32)
     end
 
+    # HMAC by default; BCrypt only when an app explicitly asks for it by setting
+    # `token_digest_cost`. That inverts the previous default (BCrypt at
+    # bcrypt-ruby's cost 12) — see .hmac_token_digest for why — while leaving
+    # the escape hatch meaning exactly what it says for anyone who set it
+    # deliberately. Existing rows are untouched either way: #authenticate_token
+    # reads the scheme off the stored digest, not off this config.
     def generate_token_digest
       configured_cost = StandardId.config.session.token_digest_cost
       self.token_digest =
         if configured_cost.nil?
-          BCrypt::Password.create(token)
+          self.class.hmac_token_digest(token)
         else
           cost = configured_cost.clamp(BCrypt::Engine::MIN_COST, BCrypt::Engine::MAX_COST)
           BCrypt::Password.create(token, cost: cost)

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