standard_id 0.31.0 → 0.33.0

data/lib/standard_id/config/schema.rb

@@ -19,6 +19,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.
@@ -173,18 +189,24 @@ StandardId::ConfigSchema.define do
     field :device_session_lifetime, type: :integer, default: 2592000 # 30 days in seconds
     field :service_session_lifetime, type: :integer, default: 7776000 # 90 days in seconds
 
-    # BCrypt cost factor for the session token digest. Default `nil` means
-    # use bcrypt-ruby's built-in default (cost 12 in production, MIN_COST
-    # in the test env). Since session tokens are 256-bit random
-    # (`SecureRandom.urlsafe_base64(32)`), any cost >= 10 is well beyond
-    # realistic brute-force, and dropping from 12 to 10 saves ~200ms of
-    # CPU per session creation. Host apps with many logins-per-second can
-    # set this to `10`; apps that value hash work over login latency can
-    # leave it alone or raise it.
-    #
-    # When set, value is clamped to BCrypt::Engine::MIN_COST..MAX_COST.
-    # Applies only to newly-created sessions; existing token_digests keep
-    # their original cost.
+    # Opt IN to BCrypt for the session token digest, at this cost factor.
+    #
+    # Default `nil` means HMAC-SHA256 under `secret_key_base`, which is the
+    # right primitive here: session tokens are 256-bit random
+    # (`SecureRandom.urlsafe_base64(32)`), and BCrypt's cost factor exists to
+    # slow brute-force of LOW-entropy secrets. Against a token that cannot be
+    # guessed at any hash speed the stretching bought nothing, while costing a
+    # measured ~181 ms of CPU on every authenticated API request at cost 12 —
+    # note this is paid per REQUEST, not merely per session creation.
+    #
+    # Set it only if you specifically want hash work on this path anyway. When
+    # set, the value is clamped to BCrypt::Engine::MIN_COST..MAX_COST.
+    #
+    # Changing it is always safe and never strands a session:
+    # Session#authenticate_token reads the scheme off the stored digest (BCrypt
+    # digests are self-identifying by their `$2<x>$` prefix), so both schemes
+    # verify side by side and existing rows are never rewritten. As before, a
+    # change applies only to newly-created sessions.
     field :token_digest_cost, type: :integer, default: nil
 
     # Callable that resolves the session class to create for a given auth flow.
@@ -294,6 +316,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 }`.
@@ -439,5 +535,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.

data/lib/standard_id/oauth/discovery_document.rb

@@ -5,28 +5,57 @@ module StandardId
     #   * /.well-known/oauth-authorization-server (RFC 8414)
     #
     # Both well-known controllers render this single builder so the two
-    # documents cannot drift. Endpoint URLs are derived from the configured
-    # issuer.
+    # documents cannot drift.
     #
-    # NOTE on mounting (RFC 8414 caveat): the ApiEngine is consumer-mounted at
-    # a sub-path (e.g. `/auth/api`), so the gem can only serve
-    # `/auth/api/.well-known/oauth-authorization-server`. A strict RFC 8414
-    # client that derives a *root-anchored* metadata URL from a path-carrying
-    # issuer would probe `<host>/.well-known/oauth-authorization-server/auth/api`,
-    # which falls outside any engine mount. Hosts that need the root-anchored
-    # form must add their own root route — the gem cannot.
+    # ## `issuer` and the endpoint base are two different things
+    #
+    # This used to derive every endpoint from the issuer
+    # (`base = issuer.to_s.chomp("/")`), which is wrong for any app mounting
+    # `ApiEngine` under a prefix its issuer does not carry: the document
+    # advertised `<issuer>/oauth/token` while the endpoint actually lived at
+    # `<origin>/api/oauth/token`. Every consuming app hand-rolled a replacement
+    # controller because of it.
+    #
+    # The two are now separate, and must stay separate:
+    #
+    #   * `issuer` is a stable **security identifier** (RFC 8414 §2). Clients
+    #     compare it 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 can never be overridden — see .apply_overrides!.
+    #   * `endpoint_base` is where the endpoints actually are. It defaults to the
+    #     issuer, which preserves the previous behaviour exactly for apps whose
+    #     issuer already carries the mount path.
+    #
+    # ## Overrides
+    #
+    # Some members are not derivable at all — a host-owned authorization shim
+    # that injects an audience, a scope list deliberately narrower than what the
+    # server can mint, an auth-method list that must mirror the host's dynamic
+    # registration policy. `overrides` covers those; see
+    # StandardId::Oauth::DiscoveryResolver for the config surface.
     module DiscoveryDocument
       module_function
 
-      # @param issuer [String] the configured issuer (e.g. "https://auth.example.com")
+      # @param issuer [String] the configured issuer, emitted verbatim
+      # @param endpoint_base [String, nil] base URL for the endpoints. Defaults
+      #   to `issuer` — the previous behaviour — so existing callers are
+      #   unaffected.
       # @param registration_enabled [Boolean] when true, advertises the RFC 7591
       #   dynamic client registration endpoint. The well-known controllers pass
       #   `StandardId.config.oauth.dynamic_registration_enabled` here, so the
       #   `registration_endpoint` is emitted only when DCR is turned on. Defaults
       #   to false so callers (and tests) that omit it get no registration_endpoint.
+      # @param introspection_enabled [Boolean] when true, advertises the RFC 7662
+      #   introspection endpoint. The well-known controllers pass
+      #   `StandardId.config.oauth.introspection_enabled`, so it is advertised only
+      #   when the endpoint actually exists (the controller 404s when off).
+      #   Defaults to false, matching registration_enabled.
+      # @param overrides [Hash] members to replace, add, or (with a nil value)
+      #   remove. Already resolved — callables are evaluated by the caller.
       # @return [Hash]
-      def build(issuer, registration_enabled: false)
-        base = issuer.to_s.chomp("/")
+      def build(issuer, endpoint_base: nil, registration_enabled: false,
+        introspection_enabled: false, overrides: {})
+        base = (endpoint_base.presence || issuer).to_s.chomp("/")
 
         doc = {
           issuer: issuer,
@@ -55,6 +84,38 @@ module StandardId
         doc[:jwks_uri] = "#{base}/.well-known/jwks.json" if StandardId::JwtService.asymmetric?
 
         doc[:registration_endpoint] = "#{base}/oauth/register" if registration_enabled
+        doc[:introspection_endpoint] = "#{base}/oauth/introspect" if introspection_enabled
+
+        apply_overrides!(doc, overrides)
+      end
+
+      # Merge resolved overrides into the document.
+      #
+      # A `nil` value REMOVES the member rather than emitting `null`. Real apps
+      # need that — one omits `scopes_supported` entirely — and a `null` would be
+      # worse than either alternative, since RFC 8414 members are typed.
+      #
+      # `issuer` is REFUSED rather than silently dropped. It is a security
+      # identifier clients match byte-for-byte against both their discovery URL
+      # and the `iss` claim; letting a metadata override diverge it from what the
+      # token service actually stamps would produce a document that validates
+      # against nothing, and the failure would surface a long way from here.
+      def apply_overrides!(doc, overrides)
+        return doc if overrides.blank?
+
+        overrides = overrides.symbolize_keys
+        if overrides.key?(:issuer)
+          raise StandardId::ConfigurationError,
+            "discovery_metadata_overrides cannot set `issuer`. The issuer is a stable " \
+            "security identifier (RFC 8414 §2): clients compare it byte-for-byte with " \
+            "the URL they used for discovery and with the `iss` claim of issued tokens, " \
+            "so it must stay exactly StandardId.config.issuer. To move where the " \
+            "ENDPOINTS live, set config.oauth.discovery_endpoint_base instead."
+        end
+
+        overrides.each do |key, value|
+          value.nil? ? doc.delete(key) : doc[key] = value
+        end
 
         doc
       end

data/lib/standard_id/oauth/discovery_resolver.rb

@@ -0,0 +1,158 @@
+module StandardId
+  module Oauth
+    # Resolves the three request-dependent inputs of a discovery document:
+    # the issuer, the endpoint base, and the overrides.
+    #
+    # Lives apart from DiscoveryDocument so the builder stays a pure function of
+    # its arguments (and stays trivially testable without a request), while all
+    # the "where am I actually mounted" reasoning is in one place.
+    module DiscoveryResolver
+      # Values of `discovery_endpoint_base` that mean "derive it from the
+      # request". Compared as strings so `:request` and `"request"` both work —
+      # this is set from an initializer and the symbol/string distinction is not
+      # something a config file should have to get right.
+      REQUEST_DERIVED = %w[request].freeze
+
+      module_function
+
+      # The issuer, verbatim from config. Never derived from the request, never
+      # overridable: RFC 8414 §2 makes it a stable security identifier that
+      # clients match byte-for-byte against their discovery URL and against the
+      # `iss` claim of issued tokens.
+      #
+      # @return [String, nil]
+      def issuer
+        StandardId.config.issuer
+      end
+
+      # Base URL the advertised endpoints hang off, from
+      # `config.oauth.discovery_endpoint_base`:
+      #
+      #   nil (default) — the issuer. EXACTLY the behaviour before this option
+      #                   existed, so an upgrade changes no document. Correct
+      #                   already for an app whose issuer carries the mount path
+      #                   (`https://host/auth/api`); wrong, and the bug this
+      #                   option exists for, when it does not.
+      #   :request      — `request.base_url` + the detected mount path. This is
+      #                   what an app mounting ApiEngine under a prefix wants.
+      #   String        — used verbatim.
+      #   callable      — called with `(request:)`. The escape hatch for a proxy
+      #                   that rewrites `request.base_url`, and for an app that
+      #                   mounts ApiEngine more than once (under host constraints,
+      #                   say) where no single detected path is right.
+      #
+      # Request-derived is deliberately OPT-IN rather than the default. Making it
+      # the default would silently rewrite the document of every app whose issuer
+      # host differs from the host serving the request — which is exactly the
+      # split-host setup a separate issuer exists to express.
+      #
+      # @param request [ActionDispatch::Request, nil]
+      # @return [String, nil]
+      def endpoint_base(request: nil)
+        configured = StandardId.config.oauth.discovery_endpoint_base
+
+        return issuer if configured.blank?
+
+        if configured.respond_to?(:call)
+          resolved = configured.call(request: request)
+          return resolved.present? ? resolved.to_s.chomp("/") : issuer
+        end
+
+        return configured.to_s.chomp("/") unless REQUEST_DERIVED.include?(configured.to_s)
+        return issuer if request.nil?
+
+        "#{request.base_url}#{mount_path(request)}".chomp("/")
+      end
+
+      # The path ApiEngine is mounted at, as seen from this request.
+      #
+      # Two cases, and the difference is why this is not a config lookup:
+      #
+      #   * The document is served from INSIDE the engine mount (the gem's own
+      #     `scope ".well-known"` routes). Rails sets SCRIPT_NAME to the mount
+      #     prefix, so `request.script_name` IS the mount path, exactly, with no
+      #     detection or guessing. This is the case that used to produce 404-ing
+      #     endpoint URLs.
+      #   * The document is served from a ROOT route drawn by
+      #     `standard_id_well_known_routes` (RFC 8615 clients probe the origin
+      #     root, which is outside any engine mount). There `script_name` is
+      #     empty, so the helper stamps the mount path it was given into the
+      #     route defaults and we read it back from `params`.
+      #
+      # @return [String] "" when neither is available, which resolves to the
+      #   origin root — correct for an app that mounts ApiEngine at "/".
+      def mount_path(request)
+        from_defaults = request.params[MOUNT_PATH_PARAM].presence
+        return normalize_path(from_defaults) if from_defaults
+
+        normalize_path(request.script_name)
+      end
+
+      # Route default the routing helper uses to carry the mount path to a
+      # root-served document. Named rather than positional so it cannot collide
+      # with a host's own params.
+      MOUNT_PATH_PARAM = :standard_id_mount_path
+
+      # Resolve `config.oauth.discovery_metadata_overrides` for this request.
+      #
+      # Values may be static or callable. A callable receives one Hash argument
+      # so members can be built from the request without each app re-deriving the
+      # origin:
+      #
+      #   {
+      #     # 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 what the server can mint
+      #     scopes_supported: %w[mcp mcp:read],
+      #     # must mirror the host's DCR policy, or spec-following clients
+      #     # register in a way that policy then rejects
+      #     token_endpoint_auth_methods_supported: %w[none],
+      #     # remove a member entirely
+      #     grant_types_supported: nil
+      #   }
+      #
+      # Context keys: `:origin` (scheme+host+port, no path), `:endpoint_base`,
+      # `:issuer`, `:request`.
+      #
+      # @return [Hash] with callables evaluated
+      def metadata_overrides(request: nil, endpoint_base: nil)
+        configured = StandardId.config.oauth.discovery_metadata_overrides
+        return {} if configured.blank?
+
+        context = {
+          origin: request&.base_url,
+          endpoint_base: endpoint_base,
+          issuer: issuer,
+          request: request
+        }
+
+        configured.to_h.each_with_object({}) do |(key, value), acc|
+          acc[key.to_sym] = value.respond_to?(:call) ? value.call(context) : value
+        end
+      end
+
+      # Everything a well-known controller needs, in one call.
+      #
+      # @return [Hash] `{ issuer:, endpoint_base:, overrides: }`
+      def resolve(request: nil)
+        base = endpoint_base(request: request)
+
+        {
+          issuer: issuer,
+          endpoint_base: base,
+          overrides: metadata_overrides(request: request, endpoint_base: base)
+        }
+      end
+
+      # "" or "/foo" — never "/" and never a trailing slash, so string
+      # concatenation against an origin cannot produce a double slash.
+      def normalize_path(path)
+        normalized = path.to_s.chomp("/")
+        return "" if normalized.empty?
+
+        normalized.start_with?("/") ? normalized : "/#{normalized}"
+      end
+    end
+  end
+end

data/lib/standard_id/provider_registry.rb

@@ -18,11 +18,76 @@ module StandardId
       def register(name, provider_class)
         validate_provider!(provider_class)
         providers[name.to_s] = provider_class
-        register_config_schema(provider_class)
+        declare_config_schema(provider_class)
         provider_class.setup if provider_class.respond_to?(:setup)
         provider_class
       end
 
+      # Declare the `social` config fields of every provider class that has been
+      # LOADED, whether or not it has been `register`ed yet.
+      #
+      # Called by a core Engine initializer that runs `before:
+      # :load_config_initializers` — see StandardId::Engine. It exists because
+      # provider plugins register themselves from their Railtie's
+      # `config.after_initialize`, which runs long AFTER the host's
+      # `config/initializers/standard_id.rb`. A host initializer writing
+      # `c.social.google_client_id` therefore hit `Scope#[]=` → `validate!`
+      # before the field existed and raised StandardId::ConfigurationError, with
+      # nothing in the message to suggest the cause was ordering. Every consuming
+      # app that used a provider plugin independently discovered the same
+      # `Rails.application.config.after_initialize { ... }` wrapper to work
+      # around it.
+      #
+      # This is safe to do early because provider classes are required at
+      # gem-require time (`require "standard_id/google/providers/google"` in the
+      # plugin's entry file), so `Providers::Base.subclasses` is already
+      # populated before any initializer runs.
+      #
+      # Only FIELD DECLARATION moves earlier. Full `register` — which also runs
+      # `validate_provider!` and the provider's `setup` — deliberately stays in
+      # `after_initialize`, where the host's configuration is complete and
+      # `setup` can rely on it.
+      #
+      # Idempotent: `ConfigSchema#add_field` uses `compute_if_absent`, so a field
+      # already declared here is untouched when the plugin later calls `register`.
+      #
+      # @return [Array<Class>] the provider classes whose fields were declared
+      def declare_config_schemas!
+        provider_classes.each { |provider_class| declare_config_schema(provider_class) }
+      end
+
+      # Provider classes known to the process: every loaded subclass of
+      # Providers::Base, plus anything already registered (a registered class
+      # need not be a direct subclass).
+      #
+      # @return [Array<Class>]
+      def provider_classes
+        (StandardId::Providers::Base.subclasses + providers.values).uniq
+      end
+
+      # Declare one provider's config fields against the `social` scope.
+      #
+      # Thread-safe and idempotent — adding the same field twice is a no-op.
+      #
+      # `add_field` is retroactive: `ConfigSchema::Scope#validate!` and `#[]`
+      # both consult the schema live (the latter falling back to
+      # `field_for(...).default_value` for an unwritten key), so declaring a
+      # field after `StandardId.config` has been built works exactly as if it
+      # had been declared before. That is what makes the existing host-side
+      # `after_initialize` wrappers keep working untouched.
+      #
+      # @param provider_class [Class] Provider implementation class
+      def declare_config_schema(provider_class)
+        return unless provider_class.respond_to?(:config_schema)
+
+        schema = provider_class.config_schema
+        return if schema.nil? || schema.empty?
+
+        schema.each do |field_name, options|
+          StandardId::ConfigSchema.add_field(scope: :social, name: field_name, **options)
+        end
+      end
+
       # Get provider by name
       # @param name [Symbol, String] Provider identifier
       # @return [Class] Provider class
@@ -49,18 +114,6 @@ module StandardId
 
       private
 
-      # Register provider's config schema fields with the StandardId schema.
-      # Thread-safe and idempotent — adding the same field twice is a no-op.
-      # @param provider_class [Class] Provider implementation class
-      def register_config_schema(provider_class)
-        schema = provider_class.config_schema
-        return if schema.nil? || schema.empty?
-
-        schema.each do |field_name, options|
-          StandardId::ConfigSchema.add_field(scope: :social, name: field_name, **options)
-        end
-      end
-
       def validate_provider!(provider_class)
         unless provider_class.is_a?(Class)
           raise InvalidProviderError,