standard_id 0.41.1 → 0.43.0

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

@@ -18,6 +18,8 @@ module StandardId
           * writes config/initializers/standard_id.rb
           * mounts StandardId::WebEngine and StandardId::ApiEngine in config/routes.rb
           * copies the engine's migrations into db/migrate/
+          * schedules the four cleanup jobs in config/recurring.yml (Solid Queue),
+            when that file exists
 
         Use --skip-* flags to opt out of individual steps when re-running on an
         existing install. The generator is idempotent — already-installed
@@ -30,6 +32,20 @@ module StandardId
         desc: "Do not append engine mount lines to config/routes.rb"
       class_option :skip_migrations, type: :boolean, default: false,
         desc: "Do not copy StandardId migrations into db/migrate"
+      class_option :skip_recurring, type: :boolean, default: false,
+        desc: "Do not add the cleanup jobs to config/recurring.yml"
+
+      # Every cleanup job the engine ships, with the recommended Solid Queue
+      # schedule. Hourly, staggered off minute 0: each job is one DELETE, and
+      # running it hourly keeps that batch small on busy tables. The jobs'
+      # own grace windows (7 days expired / 1 day consumed) are what bound
+      # retention, not the cadence — daily is fine for small apps.
+      CLEANUP_JOBS = {
+        "standard_id_cleanup_expired_sessions" => ["StandardId::CleanupExpiredSessionsJob", "every hour at minute 6"],
+        "standard_id_cleanup_expired_refresh_tokens" => ["StandardId::CleanupExpiredRefreshTokensJob", "every hour at minute 3"],
+        "standard_id_cleanup_expired_authorization_codes" => ["StandardId::CleanupExpiredAuthorizationCodesJob", "every hour at minute 9"],
+        "standard_id_cleanup_expired_code_challenges" => ["StandardId::CleanupExpiredCodeChallengesJob", "every hour at minute 13"]
+      }.freeze
 
       def create_initializer_file
         return say_status("skip", "config/initializers/standard_id.rb (--skip-initializer)", :yellow) if options[:skip_initializer]
@@ -79,6 +95,35 @@ module StandardId
         run_migration_copy_task
       end
 
+      # Solid Queue reads a single recurring schedule (config/recurring.yml);
+      # an engine cannot contribute entries to it, so the generator writes
+      # them. Inserted under the `production:` key only — the one environment
+      # every recurring.yml has and where cleanup matters.
+      def schedule_cleanup_jobs
+        return say_status("skip", "config/recurring.yml (--skip-recurring)", :yellow) if options[:skip_recurring]
+
+        path = "config/recurring.yml"
+        full_path = File.join(destination_root, path)
+
+        unless File.exist?(full_path)
+          say_status("skip", "#{path} not found — schedule the cleanup jobs with your scheduler (see below)", :yellow)
+          return
+        end
+
+        content = File.read(full_path)
+        if content.include?("StandardId::CleanupExpired")
+          say_status("identical", "#{path} (StandardId cleanup jobs already scheduled)", :blue)
+          return
+        end
+
+        unless content.match?(/^production:[ \t]*\r?\n/)
+          say_status("warn", "#{path} has no top-level `production:` key — add the cleanup jobs manually:\n#{recurring_snippet}", :red)
+          return
+        end
+
+        inject_into_file path, indent(recurring_snippet, 2), after: /^production:[ \t]*\r?\n/
+      end
+
       def print_post_install_message
         say ""
         say "=" * 79
@@ -116,10 +161,13 @@ module StandardId
         say ""
         say "     bin/rails db:migrate"
         say ""
-        say "5. Scheduled maintenance — schedule the cleanup jobs (e.g. daily):"
+        say "5. Scheduled maintenance — the cleanup jobs must run on a schedule"
+        say "   (added to config/recurring.yml if you use Solid Queue; otherwise"
+        say "   schedule them yourself, hourly or at least daily):"
+        say ""
+        CLEANUP_JOBS.each_value { |(job, _)| say "     #{job}" }
         say ""
-        say "     StandardId::CleanupExpiredSessionsJob"
-        say "     StandardId::CleanupExpiredRefreshTokensJob"
+        say "   See the README's Scheduled Maintenance section."
         say ""
         say "6. Social providers — install provider plugins and register them:"
         say ""
@@ -160,6 +208,19 @@ module StandardId
           text.each_line.map { |line| line.strip.empty? ? line : prefix + line }.join
         end
 
+        def recurring_snippet
+          entries = CLEANUP_JOBS.map do |key, (job, schedule)|
+            <<~YAML
+              #{key}:
+                class: #{job}
+                schedule: #{schedule}
+            YAML
+          end
+          "# StandardId cleanup jobs (added by standard_id:install). Retention is\n" \
+            "# bounded by each job's grace window; the cadence only sizes the DELETE.\n" +
+            entries.join
+        end
+
         def engine_mount_snippet
           <<~RUBY
             # Mount the StandardId engines. The web engine serves cookie-based

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

@@ -253,9 +253,18 @@ StandardId.configure do |c|
   #   Account.create!(email: identifier.value)
   # }
 
-  # Deprecated senders (prefer event subscriptions + built_in delivery):
-  # c.passwordless_email_sender = ->(email, code) { PasswordlessMailer.with(code: code, to: email).deliver_later }
-  # c.passwordless_sms_sender   = ->(phone, code) { SmsProvider.send_code(phone: phone, code: code) }
+  # With c.passwordless.delivery = :custom, deliver codes from an event
+  # subscriber (c.passwordless_email_sender / _sms_sender were removed in
+  # 0.43). It runs synchronously in the request, so I18n.locale etc. are still
+  # available. The same subscriber delivers Otp.issue(delivery: :custom) codes.
+  #
+  # StandardId::Events.subscribe(StandardId::Events::PASSWORDLESS_CODE_GENERATED) do |event|
+  #   next if event[:skip_sender] # Otp.issue(delivery: :manual)
+  #   case event[:channel]
+  #   when "email" then PasswordlessMailer.with(code: event[:code_challenge].code, to: event[:identifier]).deliver_later
+  #   when "sms"   then SmsProvider.send_code(phone: event[:identifier], code: event[:code_challenge].code)
+  #   end
+  # end
 
   # ---------------------------------------------------------------------------
   # API engine — OAuth / JWT
@@ -430,15 +439,37 @@ StandardId.configure do |c|
   # 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"]
-  # c.social.apple_mobile_client_id = ENV["APPLE_MOBILE_CLIENT_ID"]
-  # c.social.apple_client_id        = ENV["APPLE_CLIENT_ID"]
-  # c.social.apple_private_key      = ENV["APPLE_PRIVATE_KEY"]
+  #
+  # ENV defaults (standard_id >= 0.42): every provider field you do not assign
+  # falls back to the ENV variable named after it, upper-cased — so with the
+  # canonical variables below set, you need none of these lines. Assign a
+  # field only to read it from somewhere else (a differently named variable,
+  # Rails credentials); an explicit assignment, even of nil, always wins.
+  #
+  #   GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
+  #   APPLE_CLIENT_ID, APPLE_MOBILE_CLIENT_ID,
+  #   APPLE_PRIVATE_KEY, APPLE_KEY_ID, APPLE_TEAM_ID
+  #
+  # A provider is enabled when its client ID is present
+  # (StandardId.social_provider_enabled?(:google)). An enabled provider missing
+  # fields its plugin marks required is reported at boot — see
+  # c.social.provider_misconfiguration below.
+
+  # c.social.google_client_id       = Rails.application.credentials.dig(:google, :client_id)
+  # c.social.google_client_secret   = Rails.application.credentials.dig(:google, :client_secret)
+  # c.social.apple_client_id        = ENV["APPLE_CLIENT_ID"]         # web (Services ID) flow
+  # c.social.apple_mobile_client_id = ENV["APPLE_MOBILE_CLIENT_ID"]  # native id_token flow
+  # c.social.apple_private_key      = ENV["APPLE_PRIVATE_KEY"]       # .p8 PEM, newlines intact
   # c.social.apple_key_id           = ENV["APPLE_KEY_ID"]
   # c.social.apple_team_id          = ENV["APPLE_TEAM_ID"]
 
+  # What to do at boot when an enabled provider is missing required fields
+  # (e.g. APPLE_CLIENT_ID set without APPLE_PRIVATE_KEY — the sign-in flow
+  # would start, then fail at the callback). :warn logs a warning; :raise
+  # raises StandardId::ConfigurationError in production and warns elsewhere.
+  # Default: :warn
+  # c.social.provider_misconfiguration = :raise
+
   # Mobile redirect URI allow-list — custom schemes used by native apps.
   # Default: []
   # c.social.allowed_redirect_url_prefixes = ["example-app://"]
@@ -479,12 +510,9 @@ StandardId.configure do |c|
 
   # Login limits. The login action branches password OR passwordless, so on a
   # passwordless app these govern the OTP-SEND limit. Prefer the
-  # mechanism-agnostic names; the deprecated password_login_* names still work
-  # (the new name wins when both are set).
+  # mechanism-agnostic names (password_login_per_ip/_per_email were removed in 0.43).
   # c.rate_limits.login_per_ip                   = 20  # per 15 minutes
   # c.rate_limits.login_per_email                = 5   # per 15 minutes
-  # c.rate_limits.password_login_per_ip          = 20  # deprecated alias of login_per_ip
-  # c.rate_limits.password_login_per_email       = 5   # deprecated alias of login_per_email
   # c.rate_limits.otp_verify_per_ip              = 20  # per 15 minutes
   # c.rate_limits.verification_start_per_target  = 3   # per 15 minutes
   # c.rate_limits.verification_start_per_ip      = 10  # per hour

data/lib/standard_id/checks/migrations.rb

@@ -0,0 +1,61 @@
+module StandardId
+  module Checks
+    # A StandardHealth-compatible readiness check reporting StandardId
+    # migrations the host never installed or never ran (see
+    # StandardId::MigrationCheck).
+    #
+    # Duck-typed like StandardAudit::Checks::Retention — no dependency on
+    # standard_health; it exposes the `#initialize(name:, critical:)` + `#run`
+    # contract the aggregator calls. Register it NON-critical, so a missing
+    # index degrades /health/ready (HTTP 200) instead of failing the probe:
+    #
+    #   c.register_check :standard_id_migrations,
+    #                    StandardId::Checks::Migrations,
+    #                    critical: false
+    #
+    # Cheap: one directory scan plus one `schema_migrations` read, and once
+    # everything is present the :ok result is memoized for the life of the
+    # process (migration files cannot change without a deploy).
+    class Migrations
+      attr_reader :name
+
+      def initialize(name: :standard_id_migrations, critical: false)
+        @name = name
+        @critical = critical
+      end
+
+      def critical? = !!@critical
+
+      def run
+        return { status: :ok } if self.class.all_present?
+
+        all_missing = StandardId::MigrationCheck.pending(check_database: true)
+        if all_missing.empty?
+          self.class.all_present = true
+          return { status: :ok }
+        end
+
+        # Deferred upgrade steps (MigrationCheck::DEFERRED_UPGRADE_STEPS) are
+        # reported but never degrade readiness.
+        deferred, missing = all_missing.partition(&:info?)
+        if missing.empty?
+          return { status: :ok, pending_upgrade_steps: deferred.map(&:to_s) }
+        end
+
+        {
+          status: :warn,
+          message: "#{missing.size} StandardId migration(s) missing: #{missing.map(&:to_s).join(', ')}",
+          missing: missing.map { |m| { name: m.name, version: m.version, state: m.state } }
+        }
+      rescue StandardError => e
+        { status: :fail, error: e.message, error_class: e.class.name }
+      end
+
+      class << self
+        attr_writer :all_present
+
+        def all_present? = !!@all_present
+      end
+    end
+  end
+end

data/lib/standard_id/config/schema.rb

@@ -9,8 +9,12 @@ StandardId::ConfigSchema.define do
     field :cache_store, type: :any, default: nil
     field :logger, type: :any, default: nil
     field :web_layout, type: :string, default: nil
-    field :passwordless_email_sender, type: :any, default: nil
-    field :passwordless_sms_sender, type: :any, default: nil
+    # Removed in 0.43 (deprecated since 0.1.7): assigning either raises
+    # StandardId::ConfigurationError with this hint.
+    removed :passwordless_email_sender,
+      "deliver the code from a StandardId::Events::PASSWORDLESS_CODE_GENERATED subscriber (it runs synchronously in the request, so I18n.locale is still available; skip it when event[:skip_sender] is true) and set c.passwordless.delivery = :custom. See docs/MIGRATION_GUIDE.md."
+    removed :passwordless_sms_sender,
+      "deliver the code from a StandardId::Events::PASSWORDLESS_CODE_GENERATED subscriber (skip it when event[:skip_sender] is true). See docs/MIGRATION_GUIDE.md."
     field :issuer, type: :string, default: nil
 
     # Whether `JwtService.decode` REQUIRES a matching `iss` claim.
@@ -55,12 +59,22 @@ StandardId::ConfigSchema.define do
     # loading for every app that never asked for it.
     field :association_strict_loading, type: :any, default: nil
 
+    # Boot-time check for StandardId migrations the host never copied in
+    # (StandardId::MigrationCheck). :warn, :raise or :ignore. nil (default)
+    # means :warn in development/test and :ignore elsewhere — it never raises
+    # in production unless you ask it to.
+    field :missing_migrations, type: :symbol, default: nil
+
+    # Gem migration names (e.g. "add_target_created_at_index_to_code_challenges")
+    # or original versions the check should skip — for a migration the host
+    # deliberately superseded or deferred.
+    field :ignored_migrations, type: :array, default: -> { [] }
+
     # 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.
-    # The legacy :profile_type (singular String) key is still accepted for backward
-    # compatibility and coerced into a single-element :profile_types array (deprecation
-    # warning fires on use).
+    # The legacy :profile_type (singular) key was removed in 0.43; a scope that still
+    # sets it raises StandardId::ConfigurationError at boot.
     field :scopes, type: :any, default: {}
 
     # Callable that resolves the active scope name for a given request/session.
@@ -139,9 +153,8 @@ StandardId::ConfigSchema.define do
   end
 
   scope :passwordless do
-    # Deprecated: use web.passwordless_login to control WebEngine passwordless login.
-    # Retained for backwards compatibility with consuming apps that set this field.
-    field :enabled, type: :boolean, default: false
+    # Removed in 0.43 (no effect since 0.8).
+    removed :enabled, "it had no effect since 0.8. Use web.passwordless_login (WebEngine) instead, and delete this line."
     field :connection, type: :string, default: "email"
     field :code_ttl, type: :integer, default: 600 # 10 minutes in seconds
 
@@ -296,8 +309,10 @@ StandardId::ConfigSchema.define do
     # RefreshTokenFlow::MAX_REUSE_LEEWAY_SECONDS.
     field :refresh_token_reuse_leeway, type: :integer, default: 0
     field :token_lifetimes, type: :hash, default: -> { {} }
-    field :client_id, type: :string, default: nil
-    field :client_secret, type: :string, default: nil
+    # Removed in 0.43 — never read by the gem. OAuth clients are
+    # StandardId::ClientApplication rows with ClientSecretCredential secrets.
+    removed :client_id, "it was never read — OAuth clients are StandardId::ClientApplication records. Delete this line."
+    removed :client_secret, "it was never read — client secrets are StandardId::ClientSecretCredential records. Delete this line."
     field :scope_claims, type: :hash, default: -> { {} }
     field :claim_resolvers, type: :hash, default: -> { {} }
     # List of audience values that tokens issued and accepted by this app may
@@ -551,6 +566,11 @@ StandardId::ConfigSchema.define do
     field :allowed_redirect_url_prefixes, type: :array, default: []
     field :available_scopes, type: :array, default: -> { [] }
     field :link_strategy, type: :symbol, default: :strict
+    # What to do at boot when an enabled social provider is missing required
+    # config (e.g. apple_client_id set without apple_private_key). :warn logs
+    # in every environment; :raise raises StandardId::ConfigurationError in
+    # production and logs elsewhere. See ProviderRegistry.validate_configuration!
+    field :provider_misconfiguration, type: :symbol, default: :warn
   end
 
   scope :web do
@@ -576,15 +596,9 @@ StandardId::ConfigSchema.define do
     field :login_per_ip, type: :integer, default: 20                 # per 15 minutes
     field :login_per_email, type: :integer, default: 5               # per 15 minutes
 
-    # Deprecated mechanism-specific names, retained for backwards compatibility.
-    # The schema raises ConfigurationError on unknown fields at boot, so these
-    # must NOT be removed while hosts still set them. When a host leaves the
-    # `login_per_*` alias at its default, the login controller falls back to
-    # these values (see StandardId::RateLimitHandling.login_per_ip). New name
-    # wins when explicitly set. Mirrors the max_attempts ->
-    # max_attempts_per_challenge deprecation-alias precedent.
-    field :password_login_per_ip, type: :integer, default: 20        # per 15 minutes; deprecated alias of login_per_ip
-    field :password_login_per_email, type: :integer, default: 5      # per 15 minutes; deprecated alias of login_per_email
+    # Removed in 0.43: the mechanism-specific names of login_per_ip / login_per_email.
+    removed :password_login_per_ip, "use rate_limits.login_per_ip (same meaning; it also governs passwordless OTP sends)."
+    removed :password_login_per_email, "use rate_limits.login_per_email (same meaning; it also governs passwordless OTP sends)."
 
     # RAR-60: OTP verification
     field :otp_verify_per_ip, type: :integer, default: 20            # per 15 minutes
@@ -603,7 +617,7 @@ StandardId::ConfigSchema.define do
     field :signup_per_ip, type: :integer, default: 10                    # per hour
 
     # API OTP-initiation limits — the API counterpart of the web *login* limits
-    # (login_per_* / the deprecated password_login_*): the API passwordless
+    # (login_per_*): the API passwordless
     # `start` action and the web login action both drive the passwordless
     # `start!` strategy. NOT the counterpart of verification_start_*
     # (email/phone verification), which bypasses the strategy via a direct

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)
@@ -24,7 +28,11 @@ module StandardId
       def build = instance.apply(Config.new)
     end
 
-    def initialize = @scopes = Concurrent::Map.new
+    def initialize
+      @scopes = Concurrent::Map.new
+      @removed = Concurrent::Map.new
+    end
+
     def scopes = @scopes
     def scope?(name) = @scopes.key?(name.to_sym)
     def field?(scope_name, field_name) = !!@scopes[scope_name.to_sym]&.key?(field_name.to_sym)
@@ -35,11 +43,23 @@ 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
+
+    # Record a field that has been REMOVED from the schema. Assigning it raises
+    # StandardId::ConfigurationError carrying +message+ (what to do instead),
+    # rather than the generic "Unknown field" — or, for a base-scope field
+    # assigned through the top-level config, rather than being silently
+    # stored on the top-level OrderedOptions and ignored.
+    def add_removed_field(scope:, name:, message:)
+      @removed[[scope.to_sym, name.to_sym]] = message
     end
 
+    # @return [String, nil] the removal hint for a removed field, else nil
+    def removed_field_message(scope_name, field_name) = @removed[[scope_name.to_sym, field_name.to_sym]]
+
     # Register a scope without adding a field. Allows `define { scope :foo }` so
     # provider gems can later `add_field(scope: :foo, ...)` against an existing scope.
     def ensure_scope(name)
@@ -100,8 +120,12 @@ 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
+
+      def removed(name, message)
+        @schema.add_removed_field(scope: @scope_name, name: name, message: message)
       end
     end
 
@@ -122,9 +146,46 @@ module StandardId
 
       def []=(key, value)
         validate!(key)
+        warn_if_deprecated(key, value)
+        assigned_keys << key.to_sym
         super(key.to_sym, value)
       end
 
+      # Whether the host explicitly assigned +key+ (even to nil).
+      #
+      # Unlike #key?, which is also true for every field whose schema default
+      # was written when the config was built (so it is true for a provider
+      # field the host never touched), this is only true after an assignment.
+      #
+      # @param key [Symbol, String]
+      # @return [Boolean]
+      def assigned?(key) = assigned_keys.include?(key.to_sym)
+
+      # Deleting a key also forgets that it was assigned, so reads fall back
+      # to the (live) schema default again.
+      def delete(key)
+        assigned_keys.delete(key.to_sym)
+        super(key.to_sym)
+      end
+
+      # Re-evaluate the schema default of every field the host never assigned.
+      #
+      # Defaults are resolved once, when the config is built — including the
+      # ENV fallback of provider fields (`GOOGLE_CLIENT_ID` etc.). Call this
+      # after changing ENV to make unassigned fields pick the new value up;
+      # explicitly assigned fields are left alone. Meant for tests — see
+      # StandardId::Testing.with_provider_env.
+      #
+      # @return [self]
+      def refresh_defaults!
+        @schema.scopes[@scope_name]&.each_value do |field|
+          next if assigned?(field.name)
+
+          RAW_SET.bind_call(self, field.name, field.default_value)
+        end
+        self
+      end
+
       def [](key)
         sym = key.to_sym
         validate!(sym) unless key?(sym) || resolver
@@ -148,12 +209,36 @@ module StandardId
 
       private
 
+      def assigned_keys = (@assigned_keys ||= Set.new)
+
       def validate!(key)
         return if @schema.field?(@scope_name, key)
+        if (message = @schema.removed_field_message(@scope_name, key))
+          raise StandardId::ConfigurationError,
+            "StandardId.config.#{config_path(key)} was removed in StandardId 0.43: #{message}"
+        end
         raise StandardId::ConfigurationError,
           "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
@@ -192,6 +277,9 @@ module StandardId
         sym = key.to_sym
         if __schema__ && !__schema__.scope?(sym) && !key?(sym) && (target = unique_scope_for(sym))
           self[target][sym] = value
+        elsif __schema__ && (message = __schema__.removed_field_message(:base, sym))
+          raise StandardId::ConfigurationError,
+            "StandardId.config.#{sym} was removed in StandardId 0.43: #{message}"
         else
           super(sym, value)
         end

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
@@ -77,8 +97,10 @@ module StandardId
       # surfaces typos at boot instead of at callback time in production.
       StandardId::Config::CallableValidator.validate!
       StandardId::Config::ScopeClaimsValidator.validate!
+      StandardId::ScopeConfig.validate_all!
 
       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/events/subscribers/passwordless_delivery_subscriber.rb

@@ -11,6 +11,9 @@ module StandardId
           # challenges, etc.) and would otherwise receive a duplicate email
           # from this subscriber when c.passwordless.delivery == :built_in.
           return if event[:skip_sender]
+          # Otp.issue(delivery: :custom): the host's own subscriber delivers
+          # this code, even where the engine mailer is the global default.
+          return if event[:delivery]&.to_sym == :custom
           return unless built_in_delivery?
           return unless event[:channel] == "email"
 

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