standard_id 0.41.1 → 0.43.0

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/otp.rb

@@ -44,15 +44,24 @@ module StandardId
   #
   # == Delivery modes
   #
-  # * +:built_in+ — uses the engine's bundled mailer
-  #   (+StandardId::PasswordlessMailer+) when
-  #   +StandardId.config.passwordless.delivery+ is +:built_in+. Works for
-  #   +channel: :email+ only.
-  # * +:custom+ — calls the configured +passwordless_email_sender+ or
-  #   +passwordless_sms_sender+ callback.
-  # * +:manual+ — skip delivery entirely; the raw +code+ is returned on the
-  #   result so the caller can deliver it however they like. Useful for
-  #   custom widget/embedded flows that want full control over the channel.
+  # Every mode publishes +StandardId::Events::PASSWORDLESS_CODE_GENERATED+
+  # (synchronously, inside the call); the payload carries +delivery:+ and
+  # +skip_sender:+ so subscribers can tell the modes apart.
+  #
+  # * +:built_in+ (default) — follow the global
+  #   +StandardId.config.passwordless.delivery+: when that is +:built_in+ the
+  #   engine's +PasswordlessMailer+ sends the code (+channel: :email+ only);
+  #   otherwise the host's own +PASSWORDLESS_CODE_GENERATED+ subscriber does.
+  # * +:custom+ — the host's +PASSWORDLESS_CODE_GENERATED+ subscriber delivers
+  #   this code; the engine mailer never does, even when the global setting is
+  #   +:built_in+. Use it for a realm whose message differs from the sign-in
+  #   email. Nothing is sent unless the host subscribes. (Before 0.43 this
+  #   called +passwordless_email_sender+ / +passwordless_sms_sender+, both
+  #   removed in 0.43.)
+  # * +:manual+ — no subscriber should deliver (+skip_sender: true+); the raw
+  #   +code+ is returned on the result so the caller can deliver it however
+  #   they like. Useful for custom widget/embedded flows that want full
+  #   control over the channel.
   module Otp
     VALID_CHANNELS  = %w[email sms].freeze
     VALID_DELIVERIES = %i[built_in custom manual].freeze
@@ -112,13 +121,6 @@ module StandardId
           return failure_issue_result(:invalid_request, "target: is required")
         end
 
-        # Fail loud when the caller asked for :custom delivery but has not
-        # configured the corresponding sender callback. Without this guard
-        # BaseStrategy#start! would silently skip delivery (the sender_callback
-        # is nil and `&.call` no-ops) while Otp.issue still returned a success
-        # result — making host apps believe the OTP was sent when it was not.
-        assert_custom_sender_configured!(channel_s) if delivery_sym == :custom
-
         strategy = build_strategy(channel_s, request, realm: realm_s)
 
         begin
@@ -127,7 +129,8 @@ module StandardId
             code_length: code_length,
             expires_in: normalize_expires_in(expires_in),
             metadata: metadata,
-            skip_sender: delivery_sym == :manual
+            skip_sender: delivery_sym == :manual,
+            delivery: delivery_sym
           )
         rescue StandardId::InvalidRequestError => e
           # Validation failures from the strategy (invalid email/phone format,
@@ -226,17 +229,6 @@ module StandardId
           error_message: error_message
         )
       end
-
-      def assert_custom_sender_configured!(channel)
-        attr = channel == "email" ? :passwordless_email_sender : :passwordless_sms_sender
-        sender = StandardId.config.public_send(attr)
-        return if sender.respond_to?(:call)
-
-        raise StandardId::ConfigurationError,
-          "Otp.issue(delivery: :custom) requires StandardId.config.#{attr} to be a callable " \
-          "(got #{sender.inspect}). Configure it in an initializer, or use delivery: :built_in " \
-          "to let the engine's event subscriber deliver, or delivery: :manual to receive the raw code."
-      end
     end
 
     # Minimal stand-in used when no request is available (e.g. jobs, tests).

data/lib/standard_id/passwordless/base_strategy.rb

@@ -12,14 +12,23 @@ module StandardId
         raise NotImplementedError
       end
 
-      # Start flow: validate recipient, create challenge, and trigger sender
-      # attrs: { connection:, username:, code_length:, expires_in:, metadata:, skip_sender: }
+      # Start flow: validate recipient, create challenge, and publish
+      # PASSWORDLESS_CODE_GENERATED — delivery happens in a subscriber to that
+      # event (the engine's PasswordlessDeliverySubscriber when
+      # c.passwordless.delivery == :built_in, otherwise the host's own).
+      #
+      # attrs: { connection:, username:, code_length:, expires_in:, metadata:, skip_sender:, delivery: }
+      #
+      # +delivery+ (:built_in / :custom / :manual, or nil when not called via
+      # StandardId::Otp.issue) is forwarded in the event payload; see
+      # Otp.issue for what each value means to the subscribers.
       def start!(attrs)
         username = attrs[:username]
         code_length = attrs[:code_length]
         expires_in = attrs[:expires_in]
         metadata = attrs[:metadata] || {}
         skip_sender = attrs[:skip_sender] == true
+        delivery = attrs[:delivery]&.to_sym
 
         validate_username!(username)
         run_username_validator!(username)
@@ -33,11 +42,10 @@ module StandardId
         )
         # skip_sender is forwarded into the event payload so subscribers that
         # deliver on PASSWORDLESS_CODE_GENERATED (e.g. PasswordlessDeliverySubscriber)
-        # can honor a per-call manual-delivery request — not just the legacy
-        # sender_callback. Without this, Otp.issue(delivery: :manual) silently
-        # double-delivers when c.passwordless.delivery == :built_in.
-        emit_code_generated(challenge, username, skip_sender: skip_sender)
-        sender_callback&.call(username, challenge.code) unless skip_sender
+        # can honor a per-call manual-delivery request. Without this,
+        # Otp.issue(delivery: :manual) silently double-delivers when
+        # c.passwordless.delivery == :built_in.
+        emit_code_generated(challenge, username, skip_sender: skip_sender, delivery: delivery)
         emit_code_sent(username) unless skip_sender
         challenge
       end
@@ -156,11 +164,6 @@ module StandardId
         raise NotImplementedError
       end
 
-      def sender_callback
-        # Implement in subclasses
-        nil
-      end
-
       private
 
       # Extract request parameters safely. Returns an empty hash if the request
@@ -187,7 +190,7 @@ module StandardId
         )
       end
 
-      def emit_code_generated(challenge, username, skip_sender: false)
+      def emit_code_generated(challenge, username, skip_sender: false, delivery: nil)
         StandardId::Events.publish(
           StandardId::Events::PASSWORDLESS_CODE_GENERATED,
           code_challenge: challenge,
@@ -195,7 +198,8 @@ module StandardId
           channel: connection_type,
           realm: @realm,
           expires_at: challenge.expires_at,
-          skip_sender: skip_sender
+          skip_sender: skip_sender,
+          delivery: delivery
         )
       end
 

data/lib/standard_id/passwordless/email_strategy.rb

@@ -20,11 +20,6 @@ module StandardId
         identifier = StandardId::EmailIdentifier.includes(:account).find_by(value: normalized)
         identifier&.account
       end
-
-      def sender_callback
-        return nil if StandardId.config.passwordless.delivery == :built_in
-        StandardId.config.passwordless_email_sender
-      end
     end
   end
 end

data/lib/standard_id/passwordless/sms_strategy.rb

@@ -25,10 +25,6 @@ module StandardId
         identifier = StandardId::PhoneNumberIdentifier.includes(:account).find_by(value: phone_number)
         identifier&.account
       end
-
-      def sender_callback
-        StandardId.config.passwordless_sms_sender
-      end
     end
   end
 end

data/lib/standard_id/provider_registry.rb

@@ -5,6 +5,10 @@ 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
+
     @providers = Concurrent::Map.new
 
     class << self
@@ -19,7 +23,6 @@ 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)
         provider_class
       end
 
@@ -44,9 +47,8 @@ module StandardId
       # 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.
+      # `validate_provider!` — deliberately stays in `after_initialize`, where
+      # the host's configuration is complete.
       #
       # Idempotent: `ConfigSchema#add_field` uses `compute_if_absent`, so a field
       # already declared here is untouched when the plugin later calls `register`.
@@ -84,10 +86,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 +186,24 @@ 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
+
+      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,