standard_id 0.41.1 → 0.42.0

data/lib/standard_id/config_schema.rb

@@ -1,5 +1,6 @@
 require "active_support/ordered_options"
 require "concurrent/map"
+require "standard_id/deprecator"
 
 module StandardId
   # Lightweight configuration schema backed by ActiveSupport::OrderedOptions.
@@ -9,7 +10,10 @@ module StandardId
   # to the owning scope (so host apps can read base-scope fields like
   # `config.account_class_name` without the `base.` prefix).
   class ConfigSchema
-    Field = Struct.new(:name, :type, :default) do
+    # +deprecation+ is a message (String) for a field kept only so existing
+    # host initializers still boot. Assigning a non-nil value warns through
+    # StandardId.deprecator; reads and schema defaults never warn.
+    Field = Struct.new(:name, :type, :default, :deprecation) do
       def default_value
         return default.call if default.respond_to?(:call)
         return default.dup if default.is_a?(Array) || default.is_a?(Hash)
@@ -35,9 +39,9 @@ module StandardId
       self
     end
 
-    def add_field(scope:, name:, type: :string, default: nil)
+    def add_field(scope:, name:, type: :string, default: nil, deprecated: nil)
       fields = ensure_scope(scope)
-      fields.compute_if_absent(name.to_sym) { Field.new(name.to_sym, type, default) }
+      fields.compute_if_absent(name.to_sym) { Field.new(name.to_sym, type, default, deprecated) }
     end
 
     # Register a scope without adding a field. Allows `define { scope :foo }` so
@@ -100,8 +104,8 @@ module StandardId
         DSL.new(@schema, name.to_sym).instance_eval(&block) if block
       end
 
-      def field(name, type: :string, default: nil, **)
-        @schema.add_field(scope: @scope_name, name: name, type: type, default: default)
+      def field(name, type: :string, default: nil, deprecated: nil, **)
+        @schema.add_field(scope: @scope_name, name: name, type: type, default: default, deprecated: deprecated)
       end
     end
 
@@ -122,6 +126,7 @@ module StandardId
 
       def []=(key, value)
         validate!(key)
+        warn_if_deprecated(key, value)
         super(key.to_sym, value)
       end
 
@@ -154,6 +159,24 @@ module StandardId
           "Unknown field '#{key}' for scope '#{@scope_name}'. Valid fields: #{@schema.scopes[@scope_name]&.keys}"
       end
 
+      def warn_if_deprecated(key, value)
+        return if value.nil?
+
+        message = @schema.field_for(@scope_name, key)&.deprecation
+        return if message.nil?
+
+        # Point the warning at the host's assignment, not at this file.
+        # (OrderedOptions' method_missing forwards `c.foo = x` to #[]=.)
+        callstack = caller_locations(1).reject do |location|
+          location.path == __FILE__ || location.path.end_with?("active_support/ordered_options.rb")
+        end
+        StandardId.deprecator.warn("StandardId.config.#{config_path(key)} is deprecated: #{message}", callstack)
+      end
+
+      def config_path(key)
+        @scope_name == :base ? key.to_s : "#{@scope_name}.#{key}"
+      end
+
       def cast_read(key, value)
         field = @schema.field_for(@scope_name, key)
         return value unless field

data/lib/standard_id/deprecator.rb

@@ -0,0 +1,17 @@
+require "active_support/deprecation"
+
+module StandardId
+  # The gem's single ActiveSupport::Deprecation instance.
+  #
+  # The engine registers it in `Rails.application.deprecators[:standard_id]`,
+  # so the host's `config.active_support.deprecation` behaviour (:raise in
+  # test, :log / :notify in production, ...) and
+  # `Rails.application.deprecators.silence` apply to StandardId warnings exactly
+  # as they do to Rails' own. An unregistered deprecator only ever printed to
+  # stderr, whatever the host configured.
+  #
+  # @return [ActiveSupport::Deprecation]
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("2.0", "StandardId")
+  end
+end

data/lib/standard_id/engine.rb

@@ -37,6 +37,26 @@ module StandardId
       StandardId::ProviderRegistry.declare_config_schemas!
     end
 
+    # Route StandardId deprecation warnings through the host's deprecation
+    # behaviour (`config.active_support.deprecation`, `report_deprecations`,
+    # `Rails.application.deprecators.silence`).
+    initializer "standard_id.deprecator" do |app|
+      app.deprecators[:standard_id] = StandardId.deprecator if app.respond_to?(:deprecators)
+    end
+
+    # Check every enabled social provider is fully configured, once all of
+    # them have registered.
+    #
+    # Provider plugins register from `config.after_initialize` hooks added
+    # when their gem is required — before any initializer runs. A hook added
+    # from inside an initializer is appended after all of those, so it sees
+    # the complete registry.
+    initializer "standard_id.validate_social_providers" do |app|
+      app.config.after_initialize do
+        StandardId::ProviderRegistry.validate_configuration!
+      end
+    end
+
     initializer "standard_id.filter_parameters" do |app|
       app.config.filter_parameters += %i[
         code_verifier
@@ -79,6 +99,7 @@ module StandardId
       StandardId::Config::ScopeClaimsValidator.validate!
 
       StandardId::Engine.verify_host_cookie_encryption!(app)
+      StandardId::MigrationCheck.verify_at_boot!
       StandardId::Engine.warn_if_allowed_audiences_empty_in_production!
     end
 

data/lib/standard_id/instrumentation.rb

@@ -0,0 +1,49 @@
+require "active_support/notifications"
+
+module StandardId
+  # ActiveSupport::Notifications hooks around the expensive, opaque steps of
+  # the OAuth token endpoint, so hosts can attach tracing spans (Sentry,
+  # OpenTelemetry, Datadog) or timing metrics without prepending onto private
+  # gem methods.
+  #
+  # Names follow the Rails `<event>.<library>` convention (like
+  # `process_action.action_controller`), deliberately distinct from the
+  # `standard_id.<domain>.<event>` names StandardId::Events publishes: these
+  # are timing hooks, not audit events, and must not reach audit subscribers
+  # listening on `standard_id.*`.
+  #
+  # Every event is a block instrument, so subscribers get start/finish (and
+  # `:exception` / `:exception_object` in the payload when the step raised).
+  # Events nest: AUDIENCE_PROFILE_RESOLVE fires inside AUDIENCE_PROFILE_BINDING.
+  #
+  # Subscribe to all of them with:
+  #
+  #   ActiveSupport::Notifications.subscribe(StandardId::Instrumentation::PATTERN) { |event| ... }
+  module Instrumentation
+    # TokenGrantFlow#authenticate! — client authentication plus grant
+    # validation (for refresh_token: JWT decode + token row lookup + reuse
+    # detection). Payload: :flow (class name), :grant_type.
+    AUTHENTICATE = "authenticate.standard_id".freeze
+
+    # TokenGrantFlow#enforce_audience_profile_binding! — the account load and
+    # profile resolution for audience→profile binding. Fires on every token
+    # grant, including when no binding is configured (then it is a no-op).
+    # Payload: :flow, :grant_type, :audience (Array<String>).
+    AUDIENCE_PROFILE_BINDING = "audience_profile_binding.standard_id".freeze
+
+    # Oauth::AudienceProfileResolver.resolve! — just the resolver call (the
+    # host's `oauth.audience_profile_resolver` or the built-in strict lookup).
+    # Payload: :audience (String).
+    AUDIENCE_PROFILE_RESOLVE = "audience_profile_resolve.standard_id".freeze
+
+    EVENTS = [AUTHENTICATE, AUDIENCE_PROFILE_BINDING, AUDIENCE_PROFILE_RESOLVE].freeze
+
+    # Matches every instrumentation event above and nothing StandardId::Events
+    # publishes.
+    PATTERN = /\.standard_id\z/
+
+    def self.instrument(name, payload = {}, &)
+      ActiveSupport::Notifications.instrument(name, payload, &)
+    end
+  end
+end

data/lib/standard_id/migration_check.rb

@@ -0,0 +1,183 @@
+module StandardId
+  # Detects StandardId migrations a host never installed (or installed but
+  # never ran).
+  #
+  # WHY
+  #
+  # `bin/rails standard_id:install:migrations` copies the engine's migrations
+  # into the host with NEW timestamps. Rails' pending-migration check only
+  # sees files that are in the host's db/migrate, so a gem migration that was
+  # never copied is invisible to it — fundbright-web, luminality-web and
+  # nutripod-web each ran for months without 20260416180511's indexes, and
+  # two still lack 20260414200000. This compares by migration NAME (the part
+  # after the timestamp, with or without the `.standard_id` suffix Rails adds),
+  # which survives the re-timestamping.
+  #
+  # COST
+  #
+  # A Dir.glob over the host's migration paths; the database is only consulted
+  # (one `schema_migrations` read) when `check_database: true`, which the boot
+  # check never passes.
+  module MigrationCheck
+    GEM_MIGRATIONS_PATH = File.expand_path("../../db/migrate", __dir__)
+    FILENAME = /\A(\d+)_(\w+?)(?:\.[a-z_]+)?\.rb\z/
+
+    # A gem migration whose job is fully done by a LATER gem migration, so a
+    # host that installed the later one may skip it. name => superseding name.
+    #
+    # 20260414200000 adds a plain, non-concurrent 4-column index on
+    # standard_id_code_challenges; 20260416180511 adds the partial
+    # `index_code_challenges_on_active_target_created_at` (same columns,
+    # WHERE used_at IS NULL, built CONCURRENTLY) that serves the same lookups.
+    # Hosts on busy tables (fundbright-web, luminality-web) skipped the former
+    # on purpose rather than take the write lock.
+    SUPERSEDED_BY = {
+      "add_target_created_at_index_to_code_challenges" =>
+        "add_partial_indexes_for_active_session_and_challenge_lookups"
+    }.freeze
+
+    # Gem migrations hosts are EXPECTED to hold back for a while — reported as
+    # a pending upgrade step (severity :info), never as an error, so they do
+    # not warn at boot, fail boot in :raise mode, or degrade the health check.
+    #
+    # 20260915000000 drops a column 0.41.1 ignores; per the 0.41.1 upgrade
+    # notes it must only run once 0.41.1+ is deployed everywhere.
+    DEFERRED_UPGRADE_STEPS = {
+      "remove_refresh_token_lifetime_from_standard_id_client_applications" =>
+        "run once StandardId >= 0.41.1 is deployed to every process (it drops a column 0.41.1 ignores)"
+    }.freeze
+
+    # state:    :not_installed — no host migration file with this name
+    #           :not_run       — the host file exists but its version is not in schema_migrations
+    # severity: :error — a migration the host should have
+    #           :info  — a DEFERRED_UPGRADE_STEPS entry: pending, but intentionally
+    Missing = Data.define(:name, :version, :state, :severity) do
+      def initialize(name:, version:, state:, severity: :error) = super
+
+      def info? = severity == :info
+
+      def to_s
+        label = state.to_s.tr("_", " ")
+        info? ? "#{version}_#{name} (#{label}; pending upgrade step: #{DEFERRED_UPGRADE_STEPS[name]})" : "#{version}_#{name} (#{label})"
+      end
+    end
+
+    MODES = %i[warn raise ignore].freeze
+
+    module_function
+
+    # @return [Array<Array(String, String)>] [[original_version, name], ...] for every gem migration
+    def gem_migrations
+      @gem_migrations ||= parse_dir(GEM_MIGRATIONS_PATH).sort.freeze
+    end
+
+    # @param paths [Array<String>] host migration directories
+    # @param check_database [Boolean] also report installed-but-unrun migrations
+    # @param ignore [Array<String>] migration names (or original versions) to skip
+    # @return [Array<Missing>]
+    def pending(paths: host_migration_paths, check_database: false, ignore: StandardId.config.ignored_migrations)
+      ignore = Array(ignore).map(&:to_s)
+      host = host_versions_by_name(paths)
+      applied = check_database ? applied_versions : nil
+
+      present = ->(migration_name) { present_in_host?(host[migration_name], applied) }
+
+      gem_migrations.filter_map do |version, name|
+        next if ignore.include?(name) || ignore.include?(version)
+
+        host_versions = host[name]
+        state = if host_versions.blank?
+                  :not_installed
+        elsif applied && (host_versions & applied).empty?
+                  :not_run
+        end
+        next if state.nil?
+        next if (successor = SUPERSEDED_BY[name]) && present.call(successor)
+
+        severity = DEFERRED_UPGRADE_STEPS.key?(name) ? :info : :error
+        Missing.new(name: name, version: version, state: state, severity: severity)
+      end
+    end
+
+    # Installed (and, when +applied+ is given, run).
+    def present_in_host?(host_versions, applied)
+      return false if host_versions.blank?
+
+      applied.nil? || (host_versions & applied).any?
+    end
+
+    # The mode in effect: config.missing_migrations, else :warn in
+    # development/test and :ignore everywhere else (never raise in production
+    # by default).
+    def mode
+      configured = StandardId.config.missing_migrations
+      return configured.to_sym if configured.present?
+
+      Rails.env.local? ? :warn : :ignore
+    end
+
+    # Called from the engine's after_initialize. File-system only — boot must
+    # not need a database (assets:precompile, db:create).
+    #
+    # @raise [StandardId::ConfigurationError] in :raise mode when migrations are missing
+    def verify_at_boot!
+      current = mode
+      unless MODES.include?(current)
+        raise StandardId::ConfigurationError,
+          "StandardId.config.missing_migrations must be one of #{MODES.inspect} (got #{current.inspect})"
+      end
+      return if current == :ignore
+
+      all_missing = pending
+      deferred, missing = all_missing.partition(&:info?)
+      Rails.logger.info(deferred_message(deferred)) if deferred.any?
+      return if missing.empty?
+
+      message = boot_message(missing)
+      raise StandardId::ConfigurationError, message if current == :raise
+
+      Rails.logger.warn(message)
+      warn(message) if Rails.env.local?
+    end
+
+    def boot_message(missing)
+      <<~MESSAGE.strip
+        [StandardId] #{missing.size} StandardId migration(s) are not installed in this app:
+          #{missing.map(&:to_s).join("\n  ")}
+        Run `bin/rails standard_id:install:migrations && bin/rails db:migrate`.
+        If one is deliberately skipped (e.g. superseded by a host migration), list its name in
+        `StandardId.config.ignored_migrations`. Set `config.missing_migrations = :raise` to fail
+        boot instead, or `:ignore` to silence this check.
+      MESSAGE
+    end
+
+    def deferred_message(deferred)
+      "[StandardId] Pending upgrade step(s), held back intentionally: #{deferred.map(&:to_s).join('; ')}"
+    end
+
+    def host_migration_paths
+      paths = Rails.application.paths["db/migrate"].existent
+      paths += Array(ActiveRecord::Migrator.migrations_paths).map { |p| File.expand_path(p, Rails.root) }
+      paths.uniq.select { |p| File.directory?(p) }
+    end
+
+    def host_versions_by_name(paths)
+      Array(paths).flat_map { |dir| parse_dir(dir) }.each_with_object({}) do |(version, name), acc|
+        (acc[name] ||= []) << version
+      end
+    end
+
+    def parse_dir(dir)
+      Dir.children(dir).filter_map do |file|
+        match = FILENAME.match(file)
+        [match[1], match[2]] if match
+      end
+    rescue Errno::ENOENT
+      []
+    end
+
+    def applied_versions
+      ActiveRecord::Base.connection_pool.schema_migration.versions
+    end
+  end
+end

data/lib/standard_id/migration_helpers.rb

@@ -0,0 +1,65 @@
+require "active_support/concern"
+
+module StandardId
+  # `primary_key_type` / `foreign_key_type` for StandardId's own migrations:
+  # the host's generator `primary_key_type` (e.g. :uuid), else :bigint.
+  #
+  # These used to be monkey-patched onto ActiveRecord::Migration itself, so
+  # every migration in every host app gained three methods it never asked for.
+  # They are now scoped to StandardId migrations:
+  #
+  # * the gem's migrations `include StandardId::MigrationHelpers` explicitly
+  #   (so newly installed copies carry the include with them), and
+  # * copies installed BEFORE that line existed — which call the helpers with
+  #   no include — are recognised by file name (a StandardId migration name,
+  #   with or without the `.standard_id` suffix) when their class is defined,
+  #   and get the module then. No other migration is touched.
+  module MigrationHelpers
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def primary_and_foreign_key_types
+        config = Rails.configuration.generators
+        config.options[config.orm][:primary_key_type] || :bigint
+      end
+
+      def primary_key_type = primary_and_foreign_key_types
+      def foreign_key_type = primary_and_foreign_key_types
+    end
+
+    def primary_and_foreign_key_types = self.class.primary_and_foreign_key_types
+    def primary_key_type = self.class.primary_key_type
+    def foreign_key_type = self.class.foreign_key_type
+
+    # Is +path+ a (possibly host-copied) StandardId migration file?
+    def self.standard_id_migration_file?(path)
+      return false if path.nil?
+
+      match = StandardId::MigrationCheck::FILENAME.match(File.basename(path))
+      return false unless match
+
+      gem_migration_names.include?(match[2])
+    end
+
+    def self.gem_migration_names
+      @gem_migration_names ||= StandardId::MigrationCheck.gem_migrations.to_set(&:last).freeze
+    end
+
+    # Prepended onto ActiveRecord::Migration's singleton class. `inherited`
+    # fires while the migration's `class ... < ActiveRecord::Migration[x]`
+    # line runs, so the caller location is the migration file itself.
+    module LegacyCopySupport
+      def inherited(subclass)
+        super
+        path = caller_locations(1, 1).first&.path
+        return unless StandardId::MigrationHelpers.standard_id_migration_file?(path)
+
+        subclass.include(StandardId::MigrationHelpers)
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  ActiveRecord::Migration.singleton_class.prepend(StandardId::MigrationHelpers::LegacyCopySupport)
+end

data/lib/standard_id/oauth/audience_profile_resolver.rb

@@ -78,6 +78,14 @@ module StandardId
         # @raise [StandardId::NoBoundProfileError]
         # @raise [StandardId::AmbiguousProfileError]
         def resolve!(account:, audience:)
+          StandardId::Instrumentation.instrument(
+            StandardId::Instrumentation::AUDIENCE_PROFILE_RESOLVE, audience: audience
+          ) { resolve_bound_profile!(account, audience) }
+        end
+
+        private
+
+        def resolve_bound_profile!(account, audience)
           types = profile_types_for(audience)
           raise ArgumentError, "audience #{audience.inspect} has no profile binding" if types.empty?
 
@@ -101,8 +109,6 @@ module StandardId
           strict_default_lookup(account, audience, types)
         end
 
-        private
-
         def default_lookup(account, types)
           return nil unless account.respond_to?(:profiles)
 

data/lib/standard_id/oauth/refresh_token_flow.rb

@@ -14,7 +14,7 @@ module StandardId
       # Only the normal rotation path (revoke old + create new) is wrapped
       # in a transaction for atomicity.
       def execute
-        authenticate!
+        instrumented_authenticate!
         response = nil
         StandardId::RefreshToken.transaction do
           rotate_current_refresh_token!

data/lib/standard_id/oauth/token_grant_flow.rb

@@ -16,18 +16,37 @@ module StandardId
       end
 
       def execute
-        authenticate!
+        instrumented_authenticate!
         generate_token_response
       end
 
       private
 
+      # authenticate!, wrapped in the Instrumentation::AUTHENTICATE event.
+      def instrumented_authenticate!
+        StandardId::Instrumentation.instrument(StandardId::Instrumentation::AUTHENTICATE, instrumentation_payload) do
+          authenticate!
+        end
+      end
+
+      def instrumentation_payload
+        { flow: self.class.name, grant_type: instrumentation_grant_type }
+      end
+
+      # Abstract/anonymous flows (specs) may not implement grant_type; the
+      # instrumentation payload must never be what raises.
+      def instrumentation_grant_type
+        grant_type
+      rescue NotImplementedError
+        nil
+      end
+
       def authenticate!
         raise NotImplementedError, "Subclasses must implement authenticate!"
       end
 
       def validate_client_secret!(client_id, client_secret)
-        client_secret_credential = StandardId::ClientSecretCredential.active.find_by(client_id: client_id)
+        client_secret_credential = StandardId::ClientSecretCredential.active.includes(:client_application).find_by(client_id: client_id)
         unless client_secret_credential&.authenticate_client_secret(client_secret)
           raise StandardId::InvalidClientError, "Client authentication failed"
         end
@@ -36,7 +55,10 @@ module StandardId
 
       def generate_token_response
         validate_audience!
-        enforce_audience_profile_binding!
+        StandardId::Instrumentation.instrument(
+          StandardId::Instrumentation::AUDIENCE_PROFILE_BINDING,
+          instrumentation_payload.merge(audience: Array(audience).reject(&:blank?))
+        ) { enforce_audience_profile_binding! }
         emit_token_issuing
         expires_in = token_expiry
         payload = build_jwt_payload(expires_in)

data/lib/standard_id/provider_registry.rb

@@ -5,6 +5,15 @@ module StandardId
     class ProviderNotFoundError < StandardError; end
     class InvalidProviderError < StandardError; end
 
+    # Keys a provider's `config_schema` entry may carry that belong to
+    # StandardId (see Providers::Base) rather than to ConfigSchema.
+    PROVIDER_FIELD_OPTIONS = %i[env required].freeze
+
+    # The gem-wide StandardId.deprecator (registered in
+    # Rails.application.deprecators), kept as a constant for existing callers.
+    # The Base.setup message names its own removal version (1.0).
+    DEPRECATOR = StandardId.deprecator
+
     @providers = Concurrent::Map.new
 
     class << self
@@ -19,7 +28,7 @@ module StandardId
         validate_provider!(provider_class)
         providers[name.to_s] = provider_class
         declare_config_schema(provider_class)
-        provider_class.setup if provider_class.respond_to?(:setup)
+        run_deprecated_setup(provider_class)
         provider_class
       end
 
@@ -84,10 +93,80 @@ module StandardId
         return if schema.nil? || schema.empty?
 
         schema.each do |field_name, options|
-          StandardId::ConfigSchema.add_field(scope: :social, name: field_name, **options)
+          field_options = options.except(*PROVIDER_FIELD_OPTIONS)
+          env_name = env_var_for(field_name, options)
+          field_options[:default] = env_default(env_name, options[:default]) if env_name
+
+          StandardId::ConfigSchema.add_field(scope: :social, name: field_name, **field_options)
         end
       end
 
+      # The ENV variable a provider config field falls back to, or nil.
+      #
+      # Canonical scheme: the upper-cased field name (`apple_private_key` →
+      # `APPLE_PRIVATE_KEY`). A provider overrides it per field with
+      # `env: "OTHER_NAME"`, or opts out with `env: false`.
+      #
+      # @param field_name [Symbol, String]
+      # @param options [Hash] the field's config_schema entry
+      # @return [String, nil]
+      def env_var_for(field_name, options = {})
+        env = options.fetch(:env, true)
+        return nil if env == false || env.nil?
+
+        env == true ? field_name.to_s.upcase : env.to_s
+      end
+
+      # Registered providers the host app has switched on (see
+      # Providers::Base.enabled?).
+      #
+      # @return [Hash{String => Class}] Provider name => class
+      def enabled
+        all.select { |_name, provider_class| provider_class.enabled? }
+      end
+
+      # Configuration problems across every registered provider.
+      #
+      # @return [Hash{String => Array<String>}] Provider name => errors, only
+      #   for providers that have any
+      def configuration_errors
+        all.each_with_object({}) do |(name, provider_class), errors|
+          provider_errors = provider_class.configuration_errors
+          errors[name] = provider_errors if provider_errors.any?
+        end
+      end
+
+      # Boot-time check that every enabled provider is fully configured.
+      #
+      # Run by StandardId::Engine once every plugin has registered. A provider
+      # whose client ID is set but whose other required fields are not starts
+      # its sign-in flow fine and only fails at the callback — after the user
+      # has already authenticated with the provider — so this surfaces it at
+      # boot instead.
+      #
+      # Behaviour follows `c.social.provider_misconfiguration`:
+      # - `:warn` (default) — log a warning in every environment.
+      # - `:raise` — raise StandardId::ConfigurationError in production; log a
+      #   warning in every other environment, so a developer without production
+      #   credentials can still boot the app.
+      #
+      # @param mode [Symbol] Override the configured mode
+      # @param logger [Logger, nil]
+      # @return [Hash{String => Array<String>}] the errors found
+      # @raise [StandardId::ConfigurationError]
+      def validate_configuration!(mode: StandardId.config.social.provider_misconfiguration, logger: StandardId.logger)
+        errors = configuration_errors
+        return errors if errors.empty?
+
+        message = "StandardId social provider configuration is incomplete: " +
+                  errors.map { |name, provider_errors| "#{name} (#{provider_errors.join('; ')})" }.join(", ")
+
+        raise StandardId::ConfigurationError, message if mode.to_s == "raise" && production?
+
+        logger&.warn("[StandardId] #{message}")
+        errors
+      end
+
       # Get provider by name
       # @param name [Symbol, String] Provider identifier
       # @return [Class] Provider class
@@ -114,6 +193,38 @@ module StandardId
 
       private
 
+      # A default that prefers a non-blank ENV value, then the field's own
+      # default. Evaluated lazily (ConfigSchema calls it when the config is
+      # built, or on first read of a field declared afterwards), and only when
+      # the host never assigned the field — an explicit assignment, even of
+      # nil, always wins.
+      def env_default(env_name, fallback)
+        lambda do
+          value = ENV[env_name]
+          next value if value.present?
+
+          fallback.respond_to?(:call) ? fallback.call : fallback
+        end
+      end
+
+      # Providers::Base.setup was removed in 0.42: no known plugin overrode
+      # it, and register — its only caller — runs from after_initialize, where
+      # a plugin's own Railtie can do the same work. A provider that still
+      # defines `setup` keeps working, with a deprecation warning.
+      def run_deprecated_setup(provider_class)
+        return unless provider_class.respond_to?(:setup)
+
+        DEPRECATOR.warn(
+          "#{provider_class.name || provider_class}.setup is deprecated and will not be called " \
+          "by StandardId 1.0. Move provider initialization into the plugin's Railtie."
+        )
+        provider_class.setup
+      end
+
+      def production?
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+      end
+
       def validate_provider!(provider_class)
         unless provider_class.is_a?(Class)
           raise InvalidProviderError,