standard_id 0.41.0 → 0.42.0

data/app/models/concerns/standard_id/credentiable.rb

@@ -3,7 +3,14 @@ module StandardId
     extend ActiveSupport::Concern
 
     included do
-      has_one :credential, as: :credentialable, touch: true
+      # strict_loading: false — `touch: true` makes Rails read this association
+      # from inside its own after_create/after_update/after_destroy callbacks
+      # (ActiveRecord::Associations::Builder::HasOne.touch_record), which no
+      # `includes` at a call site can reach. Without the exemption every save of
+      # a PasswordCredential / ClientSecretCredential raises
+      # StrictLoadingViolationError in hosts running strict_loading_by_default.
+      # It is a one-row has_one read, never an N+1.
+      has_one :credential, as: :credentialable, touch: true, strict_loading: false
       accepts_nested_attributes_for :credential
 
       delegate :account, to: :credential

data/app/models/standard_id/application_record.rb

@@ -1,5 +1,31 @@
 module StandardId
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
+
+    # Load +associations+ onto already-instantiated +records+ without tripping
+    # strict loading.
+    #
+    # Gem models run under hosts that set `strict_loading_by_default = true`.
+    # A lazy `record.account` then raises ActiveRecord::StrictLoadingViolationError
+    # even for a single-row belongs_to read. Where the gem did not load the
+    # record itself (model callbacks, records handed in by host code) it cannot
+    # add `includes` at the query, so it preloads here instead — the supported
+    # Rails API, which also skips associations that are already loaded.
+    #
+    # @return [Array<ActiveRecord::Base>] the records
+    def self.preload_associations(records, *associations)
+      records = Array(records).compact
+      return records if records.empty?
+
+      ActiveRecord::Associations::Preloader.new(records: records, associations: associations).call
+      records
+    end
+
+    private
+
+    def preload_associations(*associations)
+      StandardId::ApplicationRecord.preload_associations(self, *associations)
+      self
+    end
   end
 end

data/app/models/standard_id/authorization_code.rb

@@ -60,8 +60,10 @@ module StandardId
       )
     end
 
+    # Preloads :account — every caller (the token exchange) reads it, and hosts
+    # running strict_loading_by_default would otherwise raise on the lazy read.
     def self.lookup(plaintext_code)
-      find_by(code_hash: hash_for(plaintext_code))
+      includes(:account).find_by(code_hash: hash_for(plaintext_code))
     end
 
     def self.hash_for(plaintext_code)

data/app/models/standard_id/client_application.rb

@@ -1,6 +1,17 @@
 module StandardId
   class ClientApplication < ApplicationRecord
     self.table_name = "standard_id_client_applications"
+
+    # 0.41.0 dropped `refresh_token_lifetime` (migration 20260915000000) without
+    # ignoring it first, so a rolling deploy broke: processes still running the
+    # old code had the column in their cached schema and wrote it on every
+    # INSERT/UPDATE once the migration had removed it. Ignoring it here lets
+    # hosts ship this release first and drop the column in a LATER deploy —
+    # the order strong_migrations requires for remove_column.
+    #
+    # Remove this line in a future minor, once every host has run 20260915000000.
+    self.ignored_columns += %w[refresh_token_lifetime]
+
     belongs_to :owner, polymorphic: true
 
     has_many :client_secret_credentials, dependent: :destroy

data/app/models/standard_id/identifier.rb

@@ -36,6 +36,7 @@ module StandardId
     end
 
     def mark_account_verified!
+      preload_associations(:account)
       return if account.nil?
 
       return unless account.has_attribute?(:verified)

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/db/migrate/20260924000000_add_unique_active_device_index_to_standard_id_sessions.rb

@@ -0,0 +1,115 @@
+class AddUniqueActiveDeviceIndexToStandardIdSessions < ActiveRecord::Migration[8.0]
+  # One ACTIVE DeviceSession per (account, device).
+  #
+  # `OauthSessionPersistence.upsert_device_session!` keys OAuth-issued device
+  # sessions on a stable device_id and reuses the active row for repeat
+  # sign-ins. Until now nothing in the schema backed that: the upsert
+  # serialised on a row lock, a race or an older gem could still leave two
+  # active rows for one device, and the lookup then picked one arbitrarily.
+  # This partial unique index makes "one active row per device" a database
+  # invariant; the upsert inserts inside a savepoint and, on
+  # RecordNotUnique, reuses the row that won.
+  #
+  # Partial on purpose:
+  #   - `revoked_at IS NULL` — revoked rows are history (audit trail, admin
+  #     session list) and a device legitimately accumulates one per sign-out.
+  #   - `device_id IS NOT NULL` — BrowserSession / ServiceSession rows share
+  #     the table and carry no device_id.
+  #
+  # Existing duplicates are resolved BEFORE the index is built, without
+  # revoking anything: in each duplicated (account_id, device_id) group the
+  # newest active row keeps its device_id and every other row has
+  # ":detached:<id>" appended to its own. Detached rows stay active — their
+  # refresh tokens keep working until they expire or are revoked — they are
+  # simply no longer the row a new sign-in on that device reuses. Not undone
+  # by `down`: the original device_id is recoverable by stripping the suffix.
+  #
+  # Idempotent (if_not_exists / if_exists), CONCURRENTLY on Postgres, same
+  # conventions as 20260416180511. StrongMigrations treats a concurrent
+  # add_index as safe, but it cannot inspect the raw-SQL detach UPDATE and
+  # stops the migration there whenever a host actually has duplicates — so
+  # that data fix is asserted safe (see #assert_safe) when the gem is loaded.
+  disable_ddl_transaction!
+
+  INDEX_NAME = "index_standard_id_sessions_on_active_account_device".freeze
+  WHERE = "revoked_at IS NULL AND device_id IS NOT NULL".freeze
+  DETACHED_MARKER = ":detached:".freeze
+
+  def up
+    pg = connection.adapter_name.downcase.include?("postgres")
+    concurrent = pg ? { algorithm: :concurrently } : {}
+
+    # A CONCURRENTLY build that failed (e.g. a duplicate inserted mid-build)
+    # leaves an INVALID index behind, which if_not_exists would then skip.
+    # Drop it so a re-run actually rebuilds.
+    if pg && invalid_postgres_index?(INDEX_NAME)
+      remove_index :standard_id_sessions, name: INDEX_NAME, if_exists: true, **concurrent
+    end
+
+    detach_duplicate_active_device_sessions!
+
+    add_index :standard_id_sessions,
+      [:account_id, :device_id],
+      unique: true,
+      where: WHERE,
+      name: INDEX_NAME,
+      if_not_exists: true,
+      **concurrent
+  end
+
+  def down
+    pg = connection.adapter_name.downcase.include?("postgres")
+    concurrent = pg ? { algorithm: :concurrently } : {}
+
+    remove_index :standard_id_sessions, name: INDEX_NAME, if_exists: true, **concurrent
+  end
+
+  private
+
+  def detach_duplicate_active_device_sessions!
+    rows = select_all(<<~SQL.squish).to_a
+      SELECT s.id, s.account_id, s.device_id
+      FROM standard_id_sessions s
+      INNER JOIN (
+        SELECT account_id, device_id
+        FROM standard_id_sessions
+        WHERE #{WHERE}
+        GROUP BY account_id, device_id
+        HAVING COUNT(*) > 1
+      ) dup ON dup.account_id = s.account_id AND dup.device_id = s.device_id
+      WHERE s.revoked_at IS NULL AND s.device_id IS NOT NULL
+      ORDER BY s.account_id, s.device_id, s.created_at DESC, s.id DESC
+    SQL
+
+    rows.group_by { |row| [row["account_id"], row["device_id"]] }.each_value do |group|
+      # group.first is the newest active row: it keeps the device_id.
+      group.drop(1).each do |row|
+        detached = "#{row["device_id"]}#{DETACHED_MARKER}#{row["id"]}"
+        assert_safe do
+          execute(<<~SQL.squish)
+            UPDATE standard_id_sessions
+            SET device_id = #{connection.quote(detached)}
+            WHERE id = #{connection.quote(row["id"])}
+          SQL
+        end
+      end
+    end
+  end
+
+  # A single-row UPDATE by primary key, run only for duplicated device rows:
+  # a deliberate, bounded data fix. Every known host runs StrongMigrations,
+  # which cannot inspect raw SQL; assert safety when it is loaded, and run the
+  # block as-is when it is not (the gem does not depend on it).
+  def assert_safe(&block)
+    respond_to?(:safety_assured) ? safety_assured(&block) : yield
+  end
+
+  def invalid_postgres_index?(name)
+    select_value(<<~SQL.squish).present?
+      SELECT 1
+      FROM pg_index i
+      INNER JOIN pg_class c ON c.oid = i.indexrelid
+      WHERE c.relname = #{connection.quote(name)} AND NOT i.indisvalid
+    SQL
+  end
+end

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

@@ -225,8 +225,9 @@ StandardId.configure do |c|
   # challenge is burned so further submissions fail fast. Distinct from the
   # per-IP rate limit (c.rate_limits.otp_verify_per_ip) — this defends
   # against distributed brute-force against a single challenge.
-  # Default: nil — falls back to :max_attempts for backwards compatibility.
-  # c.passwordless.max_attempts_per_challenge = 5
+  # Default: nil — falls back to :max_attempts (default 3) for backwards
+  # compatibility, so the effective default ceiling is 3.
+  # c.passwordless.max_attempts_per_challenge = 3
 
   # Default: 3 — deprecated alias for :max_attempts_per_challenge. Retained
   # for backwards compatibility; new installs should set the newer key.
@@ -252,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
@@ -429,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://"]
@@ -478,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