standard_id 0.41.1 → 0.42.0

data/app/models/standard_id/session.rb

@@ -181,7 +181,7 @@ module StandardId
     # loop and leave later sessions without their SESSION_REVOKED event, which
     # would permanently desync audit-trail consumers from the DB.
     def self.publish_session_revocations(sessions, account:, reason:, now:)
-      shared_account = account || sessions.first.account
+      shared_account = account || preload_associations(sessions.first, :account).first&.account
 
       sessions.each do |session|
         session.revoked_at = now
@@ -277,6 +277,7 @@ module StandardId
     end
 
     def emit_session_revoked_event
+      preload_associations(:account)
       StandardId::Events.publish(
         StandardId::Events::SESSION_REVOKED,
         session: self,

data/app/views/standard_id/web/login/_social_buttons.html.erb

@@ -6,14 +6,14 @@
 %>
 <section aria-label="Other sign-in options">
   <p>Or continue with</p>
-  <% if StandardId.config.google_client_id.present? %>
+  <% if StandardId.social_provider_enabled?(:google) %>
     <%= form_with url: login_path, method: :post, local: true, data: { turbo: false } do |form| %>
       <%= form.hidden_field :connection, value: "google" %>
       <%= form.hidden_field :redirect_uri, value: @redirect_uri %>
       <button type="submit">Google</button>
     <% end %>
   <% end %>
-  <% if StandardId.config.apple_client_id.present? %>
+  <% if StandardId.social_provider_enabled?(:apple) %>
     <%= form_with url: login_path, method: :post, local: true, data: { turbo: false } do |form| %>
       <%= form.hidden_field :connection, value: "apple" %>
       <%= form.hidden_field :redirect_uri, value: @redirect_uri %>

data/app/views/standard_id/web/login/show.html.erb

@@ -53,7 +53,7 @@
       })();
     </script>
 
-    <% if StandardId.config.google_client_id.present? || StandardId.config.apple_client_id.present? %>
+    <% if StandardId.social_provider_enabled?(:google) || StandardId.social_provider_enabled?(:apple) %>
       <%= render "standard_id/web/login/social_buttons" %>
     <% end %>
 
@@ -128,7 +128,7 @@
           </div>
         <% end %>
 
-        <% if StandardId.config.google_client_id.present? || StandardId.config.apple_client_id.present? %>
+        <% if StandardId.social_provider_enabled?(:google) || StandardId.social_provider_enabled?(:apple) %>
           <div>
             <div class="mt-10 flex items-center gap-x-6">
               <div class="w-full flex-1 border-t border-gray-200 dark:border-white/10"></div>
@@ -137,7 +137,7 @@
             </div>
 
             <div class="mt-6 grid grid-cols-2 gap-4">
-              <% if StandardId.config.google_client_id.present? %>
+              <% if StandardId.social_provider_enabled?(:google) %>
                 <%= form_with url: login_path, method: :post, local: true, data: { turbo: false } do |form| %>
                   <%= form.hidden_field :connection, value: "google" %>
                   <%= form.hidden_field :redirect_uri, value: @redirect_uri %>
@@ -153,7 +153,7 @@
                 <% end %>
               <% end %>
 
-              <% if StandardId.config.apple_client_id.present? %>
+              <% if StandardId.social_provider_enabled?(:apple) %>
                 <%= form_with url: login_path, method: :post, local: true, data: { turbo: false } do |form| %>
                   <%= form.hidden_field :connection, value: "apple" %>
                   <%= form.hidden_field :redirect_uri, value: @redirect_uri %>
@@ -185,7 +185,7 @@
   <main>
     <h1>Sign in</h1>
     <p>No login method is enabled.</p>
-    <% if StandardId.config.google_client_id.present? || StandardId.config.apple_client_id.present? %>
+    <% if StandardId.social_provider_enabled?(:google) || StandardId.social_provider_enabled?(:apple) %>
       <%= render "standard_id/web/login/social_buttons" %>
     <% end %>
   </main>

data/app/views/standard_id/web/signup/show.html.erb

@@ -46,7 +46,7 @@
         </div>
       <% end %>
 
-      <% if StandardId.config.google_client_id.present? || StandardId.config.apple_client_id.present? %>
+      <% if StandardId.social_provider_enabled?(:google) || StandardId.social_provider_enabled?(:apple) %>
         <div>
           <div class="mt-10 flex items-center gap-x-6">
             <div class="w-full flex-1 border-t border-gray-200 dark:border-white/10"></div>
@@ -55,7 +55,7 @@
           </div>
 
           <div class="mt-6 grid grid-cols-2 gap-4">
-            <% if StandardId.config.google_client_id.present? %>
+            <% if StandardId.social_provider_enabled?(:google) %>
               <%= form_with url: signup_path, method: :post, local: true do |form| %>
                 <%= form.hidden_field :connection, value: "google" %>
                 <%= form.hidden_field :redirect_uri, value: @redirect_uri %>
@@ -71,7 +71,7 @@
               <% end %>
             <% end %>
 
-            <% if StandardId.config.apple_client_id.present? %>
+            <% if StandardId.social_provider_enabled?(:apple) %>
               <%= form_with url: signup_path, method: :post, local: true do |form| %>
                 <%= form.hidden_field :connection, value: "apple" %>
                 <%= form.hidden_field :redirect_uri, value: @redirect_uri %>

data/db/migrate/20250830000000_create_standard_id_client_applications.rb

@@ -1,4 +1,6 @@
 class CreateStandardIdClientApplications < ActiveRecord::Migration[7.1]
+  include StandardId::MigrationHelpers
+
   def change
     create_table :standard_id_client_applications, id: primary_key_type do |t|
       # Polymorphic owner association (Account, Organization, etc.)

data/db/migrate/20250830171553_create_standard_id_password_credentials.rb

@@ -1,4 +1,6 @@
 class CreateStandardIdPasswordCredentials < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
   def change
     create_table :standard_id_password_credentials, id: primary_key_type do |t|
       t.string :login, null: false, index: { unique: true }

data/db/migrate/20250830232800_create_standard_id_identifiers.rb

@@ -1,4 +1,6 @@
 class CreateStandardIdIdentifiers < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
   def change
     create_table :standard_id_identifiers, id: primary_key_type do |t|
       t.references :account, type: primary_key_type, null: false, foreign_key: { to_table: StandardId.account_class.table_name }, index: true

data/db/migrate/20250831075703_create_standard_id_credentials.rb

@@ -1,4 +1,6 @@
 class CreateStandardIdCredentials < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
   def change
     create_table :standard_id_credentials, id: primary_key_type do |t|
       t.references :identifier, type: primary_key_type, null: false, foreign_key: { to_table: :standard_id_identifiers }, index: true

data/db/migrate/20250831154635_create_standard_id_sessions.rb

@@ -1,4 +1,6 @@
 class CreateStandardIdSessions < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
   def change
     create_table :standard_id_sessions, id: primary_key_type do |t|
       t.references :account, type: primary_key_type, null: false, foreign_key: true, index: true

data/db/migrate/20250901134520_create_standard_id_client_secret_credentials.rb

@@ -1,4 +1,6 @@
 class CreateStandardIdClientSecretCredentials < ActiveRecord::Migration[7.1]
+  include StandardId::MigrationHelpers
+
   def change
     create_table :standard_id_client_secret_credentials, id: primary_key_type do |t|
       t.string :name, null: false

data/db/migrate/20250903063000_create_standard_id_authorization_codes.rb

@@ -1,4 +1,6 @@
 class CreateStandardIdAuthorizationCodes < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
   def change
     create_table :standard_id_authorization_codes, id: primary_key_type do |t|
       # Link to account when available (can be nil for pre-auth flows)

data/db/migrate/20250907090000_create_standard_id_code_challenges.rb

@@ -1,4 +1,6 @@
 class CreateStandardIdCodeChallenges < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
   def change
     create_table :standard_id_code_challenges, id: primary_key_type do |t|
       t.string :realm, null: false         # e.g., authentication, verification

data/db/migrate/20260311100000_create_standard_id_refresh_tokens.rb

@@ -1,4 +1,6 @@
 class CreateStandardIdRefreshTokens < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
   def change
     create_table :standard_id_refresh_tokens, id: primary_key_type do |t|
       t.references :account, type: primary_key_type, null: false, foreign_key: true, index: true

data/db/migrate/20260414200000_add_target_created_at_index_to_code_challenges.rb

@@ -1,3 +1,4 @@
+# Superseded by 20260416180511's partial index_code_challenges_on_active_target_created_at; hosts that installed that may skip this one (StandardId::MigrationCheck::SUPERSEDED_BY).
 class AddTargetCreatedAtIndexToCodeChallenges < ActiveRecord::Migration[8.0]
   def change
     add_index :standard_id_code_challenges,

data/db/migrate/20260416180511_add_partial_indexes_for_active_session_and_challenge_lookups.rb

@@ -7,8 +7,10 @@ class AddPartialIndexesForActiveSessionAndChallengeLookups < ActiveRecord::Migra
   # except for the GIN drop in step 3. We guard that drop with an `if_exists`
   # check so StrongMigrations/host apps that never ran the creating migration
   # (e.g. SQLite dummies) don't error. StrongMigrations considers partial-
-  # index-add and remove_index safe when concurrently + if_exists are used, so
-  # no ignore comment is needed.
+  # index-add and remove_index safe when concurrently + if_exists are used —
+  # except its "non-unique index with more than three columns" heuristic, which
+  # rejects the 4-column code_challenges index below; that one add_index is
+  # asserted safe (see #assert_safe and the comment at the call site).
   #
   # Split into def up / def down because `remove_index :table, name: "..."`
   # (name-only, no column list) is not auto-reversible via def change — Rails
@@ -55,12 +57,20 @@ class AddPartialIndexesForActiveSessionAndChallengeLookups < ActiveRecord::Migra
     # The existing [:realm, :channel, :target, :created_at] index works but
     # covers every row, including long-since-consumed ones. A partial variant
     # stays tiny (only live challenges) and matches the exact query shape.
-    add_index :standard_id_code_challenges,
-      [:realm, :channel, :target, :created_at],
-      where: "used_at IS NULL",
-      name: "index_code_challenges_on_active_target_created_at",
-      if_not_exists: true,
-      **concurrent
+    #
+    # StrongMigrations flags any non-unique index over more than three columns.
+    # The shape here is deliberate: three equality predicates plus the ORDER BY
+    # column, partial on live challenges, built CONCURRENTLY — so assert it safe
+    # rather than make every host wrap it by hand (fundbright, luminality and
+    # nutripod all had to).
+    assert_safe do
+      add_index :standard_id_code_challenges,
+        [:realm, :channel, :target, :created_at],
+        where: "used_at IS NULL",
+        name: "index_code_challenges_on_active_target_created_at",
+        if_not_exists: true,
+        **concurrent
+    end
 
     # Drop the GIN metadata index on Postgres: metadata is only written to
     # (record_failed_attempt bumps `attempts`), never queried with containment
@@ -114,4 +124,11 @@ class AddPartialIndexesForActiveSessionAndChallengeLookups < ActiveRecord::Migra
       if_exists: true,
       **concurrent
   end
+
+  private
+
+  # StrongMigrations is optional for hosts (the gem does not depend on it).
+  def assert_safe(&block)
+    respond_to?(:safety_assured) ? safety_assured(&block) : yield
+  end
 end

data/db/migrate/20260611000000_create_standard_id_client_grants.rb

@@ -1,4 +1,6 @@
 class CreateStandardIdClientGrants < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
   def change
     create_table :standard_id_client_grants, id: primary_key_type do |t|
       # The account that granted consent. Required — consent is per-user.

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) }
+  # c.passwordless_email_sender / c.passwordless_sms_sender are DEPRECATED
+  # (assigning them emits a StandardId deprecation warning). Deliver codes from
+  # an event subscriber instead — it runs synchronously in the request, so
+  # I18n.locale etc. are still available:
+  #
+  # 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,10 @@ 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; the old password_login_per_ip/_per_email names
+  # still work but emit a deprecation warning (the new name wins when both are set).
   # 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,11 @@ 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
+    # Deprecated since 0.1.7 (see docs/MIGRATION_GUIDE.md), still honoured.
+    field :passwordless_email_sender, type: :any, default: nil,
+      deprecated: "deliver the code from a StandardId::Events::PASSWORDLESS_CODE_GENERATED subscriber instead (it runs synchronously in the request, so I18n.locale is still available; skip it when event[:skip_sender] is true) and call Otp.issue with its default delivery: :built_in. Removal in v2.0; see docs/MIGRATION_GUIDE.md."
+    field :passwordless_sms_sender, type: :any, default: nil,
+      deprecated: "deliver the code from a StandardId::Events::PASSWORDLESS_CODE_GENERATED subscriber instead (it runs synchronously in the request, so I18n.locale is still available; skip it when event[:skip_sender] is true) and call Otp.issue with its default delivery: :built_in. Removal in v2.0; see docs/MIGRATION_GUIDE.md."
     field :issuer, type: :string, default: nil
 
     # Whether `JwtService.decode` REQUIRES a matching `iss` claim.
@@ -55,6 +58,17 @@ 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.
@@ -139,9 +153,11 @@ 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
+    # Deprecated since 0.8: use web.passwordless_login to control WebEngine
+    # passwordless login. Never read; retained so host initializers that set it
+    # still boot.
+    field :enabled, type: :boolean, default: false,
+      deprecated: "it has had no effect since 0.8. Use web.passwordless_login (WebEngine) instead, and remove this line. Removal in v2.0."
     field :connection, type: :string, default: "email"
     field :code_ttl, type: :integer, default: 600 # 10 minutes in seconds
 
@@ -296,8 +312,12 @@ 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
+    # Never read by the gem. OAuth clients are StandardId::ClientApplication
+    # rows with ClientSecretCredential secrets.
+    field :client_id, type: :string, default: nil,
+      deprecated: "it is not read anywhere — OAuth clients are StandardId::ClientApplication records. Remove this line. Removal in v2.0."
+    field :client_secret, type: :string, default: nil,
+      deprecated: "it is not read anywhere — client secrets are StandardId::ClientSecretCredential records. Remove this line. Removal in v2.0."
     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 +571,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
@@ -583,8 +608,10 @@ StandardId::ConfigSchema.define do
     # 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
+    field :password_login_per_ip, type: :integer, default: 20, # per 15 minutes; deprecated alias of login_per_ip
+      deprecated: "use rate_limits.login_per_ip (same meaning; it also governs passwordless OTP sends). Removal in v2.0."
+    field :password_login_per_email, type: :integer, default: 5, # per 15 minutes; deprecated alias of login_per_email
+      deprecated: "use rate_limits.login_per_email (same meaning; it also governs passwordless OTP sends). Removal in v2.0."
 
     # RAR-60: OTP verification
     field :otp_verify_per_ip, type: :integer, default: 20            # per 15 minutes