standard_id 0.41.1 → 0.43.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eda13bb222bf26a20444378b4fe6d0e7661f86a0058388986fb2710e5f01802d
-  data.tar.gz: 96835ff10cd72cc01c8654ddf86d5cb44555079eafad8f521b8c62061a63dde9
+  metadata.gz: 8f9798d4a8c4db5cbc69cc0c4f569cc41e825b5df159124fab15f39923ca602f
+  data.tar.gz: 1b06dc3eee0795f25633df9dc93dae5376c0bc5f6e1b0cd97ef3ce37fca6fc02
 SHA512:
-  metadata.gz: 68698115969ba88727515927a9afaf0d1f14245b215abed59220afbbacb0533667715688fa395df46013c32c384d854e44cc58bb760e83c7f2c1dcac6063bed0
-  data.tar.gz: 48918bda97f0345b8b462dde9fbf4c77b6bff7851764fbee998f8af6d779caa8efc6f7e8f68f0971c33c1d8110af8effe69c172a82ad96c068d41b8a38495538
+  metadata.gz: 10594cb5f3206999becca9fb582bfcc714f8371713160192ddf72fdeb39fe4f9552e9d551991fcf294af2eca71fcd8266f8c1f0a27e94c069a7f597581a54d8e
+  data.tar.gz: 1ababa07f26cea7f6240666372f25ada38a7c3672313306c1ce7eddedded43efaff08b27df71d50c1b78f75e75d6f909f421236c455d1ac9c1658015752bdc4c

data/CHANGELOG.md

@@ -7,6 +7,117 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.43.0] - 2026-09-24
+
+**Breaking minor.** Removes everything 0.42 deprecated. Every consumer cleared those warnings in its Phase 3 adoption, so for the five apps the upgrade is a version bump — see **Upgrade notes**.
+
+### Upgrade notes
+
+If your app boots on 0.42 with no `StandardId` deprecation warning, **you need change nothing**. Checked against `origin/main` of fundbright-web, jumpdrive-web, luminality-web, nutripod-web and sidekick-web: none assigns a removed setting, uses the singular scope `profile_type:`, calls `Otp.issue(delivery: :custom)`, defines `Providers::Base.setup` or references a `DEPRECATOR` constant. What remains is comments (jumpdrive-web and luminality-web's initializers still carry the old commented-out `# c.passwordless_*_sender` lines; jumpdrive-web the commented `# c.rate_limits.password_login_per_*` lines) — worth deleting, harmless to keep.
+
+| Removed | What to do instead |
+|---|---|
+| `c.passwordless_email_sender`, `c.passwordless_sms_sender` | A `StandardId::Events::PASSWORDLESS_CODE_GENERATED` subscriber (skip when `event[:skip_sender]`), with `c.passwordless.delivery = :custom` (the default) — as fundbright-web already does. |
+| `c.passwordless.enabled` | `c.web.passwordless_login` (it had no effect since 0.8). |
+| `c.oauth.client_id`, `c.oauth.client_secret` | Delete — never read. |
+| `c.rate_limits.password_login_per_ip`, `password_login_per_email` | `c.rate_limits.login_per_ip`, `login_per_email`. `RateLimitHandling.login_per_ip` / `.login_per_email` now read only these. |
+| Scope config `profile_type: "X"` | `profile_types: ["X"]`. |
+| `Providers::Base.setup` (called with a warning when a provider defined it) | Initialize in the plugin's Railtie; `setup` is no longer called. standard_id-apple 0.6, standard_id-google 0.5 and standard_id-provider define none. |
+| `StandardId::ScopeConfig::DEPRECATOR`, `StandardId::ProviderRegistry::DEPRECATOR` | `StandardId.deprecator` (still registered as `Rails.application.deprecators[:standard_id]`). |
+
+Assigning a removed setting now raises `StandardId::ConfigurationError` **at boot**, with the replacement in the message (`StandardId.config.oauth.client_id was removed in StandardId 0.43: …`), rather than the generic "Unknown field" — and, for the two base-scope senders written through the top-level config, rather than being silently stored and ignored. Reading `StandardId.config.passwordless_email_sender` still returns `nil`, so a host spec asserting it is unset (fundbright-web's `spec/lib/otp_delivery_spec.rb`) keeps passing. A scope still using `profile_type:` raises at boot too (`ScopeConfig.validate_all!`, run by the engine): ignoring the key would have left the scope with no profile requirement at all.
+
+`ignored_columns` for `ClientApplication#refresh_token_lifetime` is **kept**. All five apps have merged the column-drop migration, but it only runs with each app's next production deploy, and ignoring an absent column is harmless. It goes in a later minor.
+
+`ostruct` was already dropped from the runtime dependencies in 0.42 (nothing in `app/` or `lib/` uses `OpenStruct`); it stays a development dependency for the specs.
+
+### Changed
+
+- **`StandardId::Otp.issue(delivery: :custom)` no longer needs a sender callback.** It hard-required `passwordless_email_sender` / `passwordless_sms_sender` (raising `ConfigurationError` without one) even after 0.42 deprecated them. It now publishes `PASSWORDLESS_CODE_GENERATED` like the other modes, with `delivery: :custom` in the payload; the engine's `PasswordlessDeliverySubscriber` skips such events even when `c.passwordless.delivery` is `:built_in`, so the host's own subscriber is the only one that delivers. Nothing is sent unless the host subscribes. The YARD docs and README table, which still said `:custom` "calls `passwordless_email_sender`", are fixed.
+- **`PASSWORDLESS_CODE_GENERATED` payload gains `delivery:`** — the `Otp.issue` mode (`:built_in` / `:custom` / `:manual`), `nil` when the code was not issued through `Otp.issue` (sign-in). `skip_sender` is unchanged.
+- **WebEngine `verify_email` / `verify_phone` start actions issue their code through `Otp.issue`** (realm `"verification"`, 10-minute expiry as before), so delivery goes through the event — the built-in mailer under `delivery: :built_in`, the host subscriber otherwise. They used to call the sender callbacks directly and sent nothing without them. They now also get the strategy's format validation, `username_validator`, retry-delay cooldown and previous-code invalidation; a rejected target renders 422.
+- The passwordless strategies no longer have a `sender_callback`.
+
+### Added
+
+- **`StandardId::CleanupAllJob`** runs the four cleanup jobs inline — one recurring entry, so the schedule can carry one cron monitor (the gem's jobs carry none). A failure in one does not skip the rest; the first error is re-raised afterwards so the run still fails its check-in. Subclass it to attach a Sentry cron monitor — README *Scheduled Maintenance* has the snippet. This is jumpdrive-web's `StandardIdCleanupJob`, upstreamed: jumpdrive-web can make its job a subclass (keeping its monitor); the other four apps can collapse their four entries into one if they want a monitor.
+- **`ConfigSchema::Scope#assigned?(field)`** — true only when the host assigned the field (even to `nil`). `key?` is true for every declared field, since defaults are written at config build, so it could not tell a provider field set in the initializer from one falling back to ENV.
+- **`ConfigSchema::Scope#refresh_defaults!`** re-resolves the default of every unassigned field — including provider ENV fallbacks, which are otherwise read once at boot.
+- **`StandardId::Testing::ConfigHelpers#with_provider_env`** (`require "standard_id/testing"`; also `StandardId::Testing.with_provider_env`): sets ENV variables, re-resolves unassigned fields, runs the block and restores both, so a host can test "set `APPLE_CLIENT_ID` → provider enabled". The provider round-trip helper now restores a never-assigned field via `assigned?`.
+- `ConfigSchema` DSL `removed :name, "hint"` for settings taken out of the schema.
+
+### Documentation
+
+- README Sentry span snippet: `finish` now guards `set_span(parent)` (`Scope#set_span` raises `ArgumentError` on `nil`) and says why a missing parent means no span.
+- README: ENV-fallback resolution timing, `assigned?` and `with_provider_env`; the passwordless-delivery section shows the `skip_sender` guard and every payload key.
+- `docs/MIGRATION_GUIDE.md`: a 0.42 → 0.43 section.
+
+## [0.42.0] - 2026-09-24
+
+### Upgrade
+
+- **Hosts can delete their `StandardId::* .strict_loading_by_default = false` block** (fundbright-web, luminality-web, nutripod-web `config/initializers/strict_loading.rb`; sidekick-web's StandardId lines in the same file). Every gem model now works under `strict_loading_by_default = true` + `:raise` through every gem flow; see Fixed. Keep an exemption only if *your own* code lazily traverses a gem association (e.g. `identifier.account` in a host controller) — prefer `includes` there instead.
+- **sidekick-web:** replace `config/initializers/standard_id_tracing.rb` with the README's Sentry subscriber for `StandardId::Instrumentation` (see Added).
+- **Every host but fundbright-web:** schedule the cleanup jobs you are missing (README *Scheduled Maintenance*).
+- **Watch for deprecation warnings** (now routed through `Rails.application.deprecators`, so they follow each app's `config.active_support.deprecation`): fundbright-web's `passwordless_email_sender` is the one live use among consumers — see Deprecated.
+- **Hosts with `APPLE_*` / `GOOGLE_*` variables in their environment:** those now enable the provider even if never assigned — see the ENV-fallback entry under Changed.
+
+### Added
+
+- **`ActiveSupport::Notifications` instrumentation of the token endpoint** (`StandardId::Instrumentation`): `authenticate.standard_id` around every token grant's `authenticate!`, `audience_profile_binding.standard_id` around audience→profile binding, and `audience_profile_resolve.standard_id` around `AudienceProfileResolver.resolve!` (nested inside the binding event). Block events with `flow` / `grant_type` / `audience` payloads; `StandardId::Instrumentation::PATTERN` subscribes to all three and to none of the `standard_id.*` domain events. The README has a drop-in Sentry span subscriber. **sidekick-web can delete `config/initializers/standard_id_tracing.rb`** (which prepends Sentry spans onto the private `RefreshTokenFlow#authenticate!`, `TokenGrantFlow#enforce_audience_profile_binding!` and `AudienceProfileResolver.resolve!`) in favour of that subscriber; span ops stay `standard_id.authenticate` / `.audience_profile_binding` / `.audience_profile_resolve` (the prepend used `standard_id.refresh_token_flow.authenticate` etc. — update any saved Sentry queries).
+- **`rails g standard_id:install` schedules all four cleanup jobs** in `config/recurring.yml` (Solid Queue, under `production:`, hourly and staggered) when that file exists; idempotent, `--skip-recurring` to opt out. The post-install checklist now lists all four jobs (it named two). A new README *Scheduled Maintenance* table lists every job, its grace windows and the recommended cadence, with a paste-ready snippet. Only fundbright-web schedules all four today; **luminality-web, nutripod-web, sidekick-web and jumpdrive-web should add the missing ones** (paste the README snippet). No engine-side `schedule_cleanup_jobs` switch: Solid Queue reads a single schedule file, so an engine cannot register recurring tasks cleanly.
+- **Missing-migration guard.** `StandardId::MigrationCheck` compares the gem's `db/migrate` to the host's migration files **by name** (surviving `install:migrations`' re-timestamping) and, optionally, to `schema_migrations`. A boot check (`config.missing_migrations`: `:warn` by default in development/test, `:ignore` elsewhere, `:raise` opt-in; file-system only, never touches the database) catches gem migrations that were never copied — the way fundbright-web, luminality-web and nutripod-web ran for months without `20260416180511`. `StandardId::Checks::Migrations` is a standard_health-compatible, non-critical check (one directory scan + one `schema_migrations` read, `:ok` memoized per process). `config.ignored_migrations` skips a deliberately superseded/deferred one. Two built-in exceptions: `SUPERSEDED_BY` treats `20260414200000` (plain 4-column code_challenges index) as satisfied when `20260416180511` (its partial, concurrent replacement) is installed, so fundbright-web and luminality-web, which skipped it on purpose, are not flagged; `DEFERRED_UPGRADE_STEPS` reports `20260915000000` (the column drop hosts hold until 0.41.1+ is deployed) as a pending upgrade step (`severity: :info`: info log at boot, `:ok` with `pending_upgrade_steps` in the health check), never as an error. Checked against every consumer's `origin/main`: no errors, only that pending step.
+- **Provider-plugin helpers on `StandardId::Providers::Base`** (protected class methods, stable signatures): `rescue_to_oauth_error`, `verify_nonce!`, `build_authorization_url` and `extract_tokens`. standard_id-apple and standard_id-google each carry private copies of all four and can drop them in their next releases. `verify_nonce!` compares in constant time and — unlike the plugin copies — never puts the expected nonce in its error message.
+- **`StandardId::Providers.plugin_railtie(:name, klass)`** defines the Railtie that registers a provider plugin, replacing the near-identical `railtie.rb` and `if defined?(Rails)` guard every plugin carries.
+- **Provider enablement:** `Providers::Base.enabled?`, `configuration_errors`, `configured?`, `enabling_config_field` and `required_config_fields`; `StandardId.enabled_social_providers` and `StandardId.social_provider_enabled?(name)`. Plugins mark fields `required: true` in `config_schema`. Use `StandardId.social_provider_enabled?(:google)` instead of `StandardId.config.google_client_id.present?` (sidekick-web's `Bootstrap::SetupController` and `InvitationAcceptanceController`).
+- **Boot-time provider validation.** Once every plugin has registered, an enabled provider missing required fields is logged as a warning; `c.social.provider_misconfiguration = :raise` raises `StandardId::ConfigurationError` in production instead (still a warning elsewhere). This is the two-stage Apple credential check sidekick-web rebuilds by hand in `config/initializers/standard_health.rb`; it applies to a provider once its plugin declares its required fields.
+- **ENV defaults for provider config fields.** A field the host never assigns falls back to the ENV variable named after it, upper-cased (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `APPLE_CLIENT_ID`, `APPLE_MOBILE_CLIENT_ID`, `APPLE_PRIVATE_KEY`, `APPLE_KEY_ID`, `APPLE_TEAM_ID`) — the scheme sidekick-web runs in production and the install template already used. Plugins can rename a field's variable with `env: "NAME"` or opt out with `env: false`. Explicit configuration, even `nil`, always wins.
+- **`Providers::Base.flow_for(params)`** resolves the API callback flow (`:web` / `:mobile`).
+- **Inertia prop `enabled_social_providers`** (`string[]`), and `social_providers` now carries `<name>_enabled` for every registered provider. `google_enabled` / `apple_enabled` are still always present.
+- **`StandardId::Testing` provider examples:** `it_behaves_like "a registered StandardId provider", :google` and the `be_a_registered_standard_id_provider.with_config_fields(...)` matcher, replacing the duplicated `spec/initializers/standard_id_provider_*_spec.rb` in sidekick-web and luminality-web. Loaded by `require "standard_id/testing"` under RSpec.
+
+### Changed
+
+- **`ScopeConfig#allow_registration` is now enforced** (it was documented "reserved for future use" and never read). Passwordless sign-in may create an account iff the global switch allows it **and** the active scope's `allow_registration` is not `false` — a scope can only restrict:
+  - WebEngine `login_verify`: `web.passwordless_registration && scope.allow_registration`.
+  - Host controllers using `StandardId::PasswordlessFlow#verify_passwordless_otp`: the caller's `allow_registration:` (default `true`) `&&` the scope from `LifecycleHooks#current_scope_config`, when the controller includes it.
+  - The Inertia `enabled_mechanisms.passwordless_registration` prop reports the effective per-request value.
+  - With no active scope nothing changes. Consumers checked: nutripod-web (`storefront: allow_registration: true`, passes `true`) and fundbright-web (all scopes `false`, already passes `false`) see no behaviour change.
+  - Not applied to the API OAuth `passwordless_otp` grant (no scope is resolved on API token requests — `scope_resolver` is a WebEngine concept and host resolvers may assume a browser session), nor to password signup / social account creation, which have their own switches (`web.signup`, provider config).
+- `ScopeConfig#allow_registration?` and `ScopeConfig.registration_allowed?(global, scope_config)` added; an explicit `allow_registration: nil` now means the default (`true`).
+- **`primary_key_type` / `foreign_key_type` are no longer monkey-patched onto every `ActiveRecord::Migration`.** They moved to `StandardId::MigrationHelpers`, which the gem's migrations now `include` explicitly. Host copies installed before this release (which call the helpers without the include) keep working: a migration class defined from a file whose name is a StandardId migration (with or without the `.standard_id` suffix) gets the module automatically. A host's **own** migration that happened to call `primary_key_type` without defining it will now raise `NameError` — define it in that migration (Active Storage's copies define their own and are unaffected). The engine's `config/initializers/migration_helpers.rb` is gone.
+- **`ostruct` is no longer a runtime dependency** — nothing in `app/` or `lib/` uses it; it is now a development dependency for the specs' `OpenStruct` doubles. On Ruby 4 `ostruct` is a bundled gem, so a host using `OpenStruct` must list it in its own Gemfile — fundbright-web, luminality-web and nutripod-web already do; sidekick-web and jumpdrive-web don't use it.
+- Gemspec summary (and README/AGENTS) say Rails 8, matching `rails >= 8.0`, instead of "Rails 7/8".
+- **No more hard-coded provider names in the host.** Inertia `auth_page_props`, the built-in ERB login/signup views and the API callback (`connection == "apple"`) now go through `ProviderRegistry` and provider capability methods.
+- **Behaviour change — ENV fallback:** an app that has `APPLE_CLIENT_ID` (etc.) in its environment but never assigned `apple_client_id` now has that provider enabled. If that variable means something else in your app, assign the field explicitly (`c.social.apple_client_id = nil`).
+
+### Deprecated
+
+Runtime warnings only, all through `StandardId.deprecator` — everything below still works exactly as before. Config settings are removed in v2.0; `Providers::Base.setup` stops being called in 1.0.
+
+- **`StandardId.deprecator`**, registered as `Rails.application.deprecators[:standard_id]`, so StandardId warnings follow the host's `config.active_support.deprecation` behaviour (`:raise` in test, `:log`/`:notify` elsewhere) and `Rails.application.deprecators.silence`. `ScopeConfig::DEPRECATOR` and `ProviderRegistry::DEPRECATOR` are now aliases of it; the former previously was a private, unregistered instance that only ever printed to stderr. Schema fields can declare `deprecated: "message"`; assigning a non-nil value warns (pointing at the assigning line), reads never do.
+- **`oauth.client_id` / `oauth.client_secret`** — never read. OAuth clients are `ClientApplication` / `ClientSecretCredential` records. Delete the lines.
+- **`passwordless.enabled`** — no effect since 0.8. Use `web.passwordless_login`.
+- **`rate_limits.password_login_per_ip` / `password_login_per_email`** — use `rate_limits.login_per_ip` / `login_per_email` (same values; they also govern passwordless OTP sends).
+- **Scope config `profile_type:` (singular)** — already warned; now through the registered deprecator. Use `profile_types: [...]`.
+- **`passwordless_email_sender` / `passwordless_sms_sender`** — deprecated since 0.1.7 in docs, now at runtime. Deliver from a `StandardId::Events::PASSWORDLESS_CODE_GENERATED` subscriber (skip when `event[:skip_sender]`), which runs synchronously inside the request — so fundbright-web's `I18n.locale` capture for `AuthMailer` works unchanged — and leave `passwordless.delivery = :custom` so the engine's built-in mailer stays out of the way. Callers of `Otp.issue(delivery: :custom)` switch to the default `delivery: :built_in`, which then defers to that subscriber. Note: the WebEngine `verify_email` / `verify_phone` start actions still call the senders directly and emit no event, so a host relying on them should keep the sender until that is addressed.
+- **`Providers::Base.setup`** is removed from the base class (no known plugin overrode it). A provider that still defines `setup` keeps having it called on `register`, with a deprecation warning (through the shared `StandardId.deprecator`); it will stop being called in 1.0.
+
+### Fixed
+
+- **Gem flows no longer lazy-load under strict loading, so gem models run strict.** The dummy app previously exempted `Identifier`, `Session`, `Credential`, `PasswordCredential`, `ClientSecretCredential` and `AuthorizationCode`; that list is gone and the whole suite runs with every gem model strict. Fixed reads:
+  - `AuthorizationCode.lookup` preloads `:account` (read by the token exchange's `OAUTH_CODE_CONSUMED` event and `token_account` — Sentry FUNDBRIGHT-WEB-X).
+  - Client-secret authentication (`TokenGrantFlow#validate_client_secret!`) preloads `:client_application` (read by the client-credentials `AUTHENTICATION_SUCCEEDED` event and `token_client`).
+  - The social-login identifier lookup and `PasswordResetDeliveryJob` preload `:account`.
+  - `Session.revoke_sessions!` without an `account:` (the OAuth revocation endpoint), `Session#revoke!`'s `SESSION_REVOKED` event and `Identifier#mark_account_verified!` (after-commit callback on `verify!`) preload `:account` onto the already-loaded record via the new `StandardId::ApplicationRecord.preload_associations` — they receive records they did not query, so no `includes` could reach them.
+  - **One declared exemption:** `Credentiable`'s `has_one :credential` (on `PasswordCredential` and `ClientSecretCredential`) is declared `strict_loading: false`. Its `touch: true` makes Rails read the association from inside its own save/destroy callbacks (`Builder::HasOne.touch_record`), which no call site can preload; without it every credential save raised. It is a one-row read, never an N+1.
+
+- **Hosts running StrongMigrations no longer have to hand-wrap `20260416180511_add_partial_indexes_for_active_session_and_challenge_lookups`.** Its partial `standard_id_code_challenges (realm, channel, target, created_at) WHERE used_at IS NULL` index trips StrongMigrations' "non-unique index with more than three columns" check, so fundbright, luminality and nutripod each had to wrap it in `safety_assured` when installing it. The shape is deliberate (three equality predicates plus the `ORDER BY created_at` column, partial, built CONCURRENTLY), so the migration now asserts that one `add_index` safe itself when StrongMigrations is loaded — the same pattern `20260924000000` uses. Hosts that already installed a hand-wrapped copy need do nothing.
+
+### Documentation
+
+- **0.41.1 upgrade note, added after the fact:** because 0.41.1 lists `refresh_token_lifetime` in `StandardId::ClientApplication.ignored_columns`, any host code that still *assigns* it (dynamic client registration, seeds, rake tasks, factories/specs) now raises `ActiveModel::UnknownAttributeError`. Remove those writes when upgrading — the value was never honoured; refresh-token lifetime is the global `oauth.refresh_token_lifetime`.
+
 ## [0.41.1] - 2026-09-24
 
 Bug-fix release. Four of these were found in sidekick-web, which has been carrying host-side prepend patches for three of them; the dummy app now runs with `strict_loading_by_default` so this class of bug fails in the gem's own suite first.

data/README.md

@@ -1,6 +1,6 @@
 # StandardId
 
-A comprehensive authentication engine for Rails applications, built on the security primitives introduced in Rails 7/8. StandardId provides a complete, secure-by-default solution for identity management, reducing boilerplate and eliminating common security pitfalls.
+A comprehensive authentication engine for Rails applications, built on the security primitives introduced in Rails 8. StandardId provides a complete, secure-by-default solution for identity management, reducing boilerplate and eliminating common security pitfalls.
 
 ## Features
 
@@ -283,18 +283,51 @@ same code raised and apps wrapped the writes in
 `Rails.application.config.after_initialize { ... }`. That wrapper is no longer
 necessary; existing ones keep working unchanged.
 
+**ENV defaults (0.42+).** Every provider field you never assign falls back to
+the ENV variable named after it, upper-cased. With these set, the provider
+credentials need no lines in your initializer at all:
+
+| Field | ENV variable |
+|-------|--------------|
+| `google_client_id` / `google_client_secret` | `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` |
+| `apple_client_id` (web Services ID) | `APPLE_CLIENT_ID` |
+| `apple_mobile_client_id` (native bundle ID) | `APPLE_MOBILE_CLIENT_ID` |
+| `apple_private_key` (.p8 PEM, newlines intact) | `APPLE_PRIVATE_KEY` |
+| `apple_key_id` / `apple_team_id` | `APPLE_KEY_ID` / `APPLE_TEAM_ID` |
+
+Assign a field only to read it from somewhere else — a differently named
+variable, Rails credentials. An explicit assignment, even of `nil`, always wins
+over the ENV fallback.
+
+The fallback is resolved **once, when the config is built at boot** — setting
+`ENV` later (in a spec, say) changes nothing by itself. Two helpers (0.43+):
+
+- `StandardId.config.social.assigned?(:apple_client_id)` is true only when the
+  host assigned the field. (`key?` is true for every declared field, assigned or
+  not, because defaults are written into the scope at build time.)
+- In specs, `with_provider_env` (from `require "standard_id/testing"`) sets the
+  variables, re-resolves every unassigned field, runs the block and restores
+  both — so "set the env var → provider enabled" is testable:
+
+  ```ruby
+  RSpec.describe "Apple sign-in" do
+    include StandardId::Testing::ConfigHelpers
+
+    it "turns on with APPLE_CLIENT_ID" do
+      with_provider_env("APPLE_CLIENT_ID" => "com.example.web") do
+        expect(StandardId.social_provider_enabled?(:apple)).to be(true)
+      end
+    end
+  end
+  ```
+
+  A field your initializer assigns explicitly ignores ENV, inside the helper too.
+
 ```ruby
 StandardId.configure do |config|
-  # Google OAuth
-  config.social.google_client_id = ENV["GOOGLE_CLIENT_ID"]
-  config.social.google_client_secret = ENV["GOOGLE_CLIENT_SECRET"]
-
-  # Apple Sign In
-  config.social.apple_mobile_client_id = ENV["APPLE_MOBILE_CLIENT_ID"]
-  config.social.apple_client_id = ENV["APPLE_CLIENT_ID"]
-  config.social.apple_private_key = ENV["APPLE_PRIVATE_KEY"]
-  config.social.apple_key_id = ENV["APPLE_KEY_ID"]
-  config.social.apple_team_id = ENV["APPLE_TEAM_ID"]
+  # Only needed when not using the canonical ENV names above:
+  config.social.apple_private_key = Rails.application.credentials.dig(:apple, :private_key)
+
   config.social.allowed_redirect_url_prefixes = ["sidekicklabs://"]
 
   # Optional: adjust which attributes are persisted during social signup
@@ -309,6 +342,30 @@ end
 
 `social_info` is an indifferent-access hash containing at least `email`, `name`, and `provider_id`.
 
+**Is a provider on?** A provider is *enabled* when its client ID is present.
+Ask StandardId rather than checking the client ID yourself:
+
+```ruby
+StandardId.social_provider_enabled?(:google) # => false when the plugin is absent, too
+StandardId.enabled_social_providers          # => { "google" => StandardId::Providers::Google }
+StandardId::Providers::Apple.configuration_errors
+# => ["apple_private_key is required when apple_client_id is set"]
+```
+
+**Boot-time check.** Once every plugin has registered, StandardId checks each
+enabled provider for missing required fields — for example an Apple client ID
+without the private key, whose sign-in flow would start fine and then fail at
+the callback, after the user had already authenticated with Apple. By default
+it logs a warning. To fail the deploy instead:
+
+```ruby
+config.social.provider_misconfiguration = :raise # raises in production, warns elsewhere
+```
+
+Which fields are required is declared by each plugin (`required: true`, see
+[Writing a Provider Plugin](#writing-a-provider-plugin)), so the check covers a
+provider once its plugin release declares them.
+
 To handle social login completion (e.g., for analytics or audit logging), subscribe to the `SOCIAL_AUTH_COMPLETED` event:
 
 ```ruby
@@ -361,6 +418,7 @@ interface Props {
   connection: string | null
   flash: { notice?: string; alert?: string }
   social_providers: { google_enabled: boolean; apple_enabled: boolean }
+  enabled_social_providers: string[]
 }
 
 export default function LoginShow({ redirect_uri, flash, social_providers }: Props) {
@@ -455,7 +513,8 @@ Authentication pages receive the following props:
 | `redirect_uri` | `string` | URL to redirect to after authentication |
 | `connection` | `string \| null` | Social provider connection (if any) |
 | `flash` | `{ notice?: string, alert?: string }` | Flash messages |
-| `social_providers` | `{ google_enabled: boolean, apple_enabled: boolean }` | Available social providers |
+| `social_providers` | `{ [name]_enabled: boolean }` | One flag per registered provider. `google_enabled` and `apple_enabled` are always present (false when the plugin is absent) |
+| `enabled_social_providers` | `string[]` | Names of the enabled providers, e.g. `["google"]` — iterate this rather than hard-coding provider names |
 | `errors` | `object` | Validation errors (on form submission failures) |
 
 #### Using Authentication in Host App Controllers
@@ -483,6 +542,7 @@ Subscribe to the `PASSWORDLESS_CODE_GENERATED` event to deliver OTP codes:
 ```ruby
 # config/initializers/standard_id_events.rb
 StandardId::Events.subscribe(StandardId::Events::PASSWORDLESS_CODE_GENERATED) do |event|
+  next if event[:skip_sender] # Otp.issue(delivery: :manual) — the caller delivers
   case event[:channel]
   when "email"
     UserMailer.send_code(event[:identifier], event[:code_challenge].code).deliver_now
@@ -492,13 +552,21 @@ StandardId::Events.subscribe(StandardId::Events::PASSWORDLESS_CODE_GENERATED) do
 end
 ```
 
+Set `c.passwordless.delivery = :custom` (the default) so the engine's built-in
+`PasswordlessMailer` stays out of the way; with `:built_in` the engine emails
+the code itself. The subscriber runs synchronously inside the request, so
+`I18n.locale`, `Current.*` and the like are still available.
+
 Event payload includes:
 - `channel` - `"email"` or `"sms"`
 - `identifier` - The email address or phone number
 - `code_challenge` - The code challenge object with `.code` method
 - `expires_at` - When the code expires
+- `realm` - The OTP realm (`"authentication"` for sign-in)
+- `skip_sender` - `true` for `Otp.issue(delivery: :manual)`; don't deliver
+- `delivery` - The `Otp.issue` delivery mode (`:built_in` / `:custom` / `:manual`), `nil` otherwise
 
-> **Note**: If you're using the deprecated `passwordless_email_sender` or `passwordless_sms_sender` callbacks, see the [Migration Guide](docs/MIGRATION_GUIDE.md) for upgrade instructions.
+> **Note**: `passwordless_email_sender` / `passwordless_sms_sender` were removed in 0.43; see the [Migration Guide](docs/MIGRATION_GUIDE.md).
 
 ### Using OTP for non-authentication flows
 
@@ -540,9 +608,9 @@ end
 
 | Mode        | Behavior                                                                 |
 |-------------|--------------------------------------------------------------------------|
-| `:built_in` | Uses the engine's bundled `PasswordlessMailer` (email only).             |
-| `:custom`   | Invokes `passwordless_email_sender` / `passwordless_sms_sender` callback.|
-| `:manual`   | Skips delivery; returns the raw `code` on the result for caller to deliver. |
+| `:built_in` (default) | Follows `c.passwordless.delivery`: the engine's `PasswordlessMailer` (email only) when that is `:built_in`, otherwise your `PASSWORDLESS_CODE_GENERATED` subscriber. |
+| `:custom`   | Your `PASSWORDLESS_CODE_GENERATED` subscriber delivers (payload `delivery: :custom`); the engine mailer never does, even under a global `:built_in`. Nothing is sent unless you subscribe. |
+| `:manual`   | Skips delivery (payload `skip_sender: true`); returns the raw `code` on the result for the caller to deliver. |
 
 **Realm isolation.** `realm:` is a free-form string that partitions challenges by purpose. A code issued for realm `"widget_contact_verification"` cannot be used to verify against realm `"authentication"` (or any other realm) — even for the same `target`. Choose a stable string per flow.
 
@@ -738,6 +806,52 @@ StandardAudit::AuditLog.from_ip("192.168.1.1")
 
 See the [StandardAudit README](https://github.com/rarebit-one/standard_audit) for the full query interface, async processing, GDPR compliance, and multi-tenancy support.
 
+### Instrumentation (tracing spans)
+
+Separately from the domain events above, the OAuth token endpoint is instrumented with `ActiveSupport::Notifications` block events so you can add tracing spans or timings without patching gem internals. Names follow the Rails `<event>.<library>` convention, so `standard_id.*` audit subscribers never see them:
+
+| Event (`StandardId::Instrumentation::…`) | Wraps | Payload |
+|---|---|---|
+| `AUTHENTICATE` — `authenticate.standard_id` | every token grant's `authenticate!` (for `refresh_token`: JWT decode + token lookup + reuse detection) | `flow`, `grant_type` |
+| `AUDIENCE_PROFILE_BINDING` — `audience_profile_binding.standard_id` | audience→profile binding (account load + resolver) | `flow`, `grant_type`, `audience` |
+| `AUDIENCE_PROFILE_RESOLVE` — `audience_profile_resolve.standard_id` | `Oauth::AudienceProfileResolver.resolve!` (nested inside the binding event) | `audience` |
+
+A raised error appears as `:exception` / `:exception_object` in the finish payload. Sentry child spans, nested the same way:
+
+```ruby
+# config/initializers/standard_id_tracing.rb
+return unless defined?(Sentry)
+
+module StandardIdSentrySpans
+  STACK = :standard_id_sentry_spans
+
+  def self.start(name, _id, payload)
+    scope = Sentry.get_current_scope
+    parent = scope&.get_span
+    # No transaction in progress (a job, a console) → no parent → no span.
+    span = parent&.start_child(
+      op: "standard_id.#{name.delete_suffix('.standard_id')}",
+      description: Array(payload[:audience]).join(", ").presence
+    )
+    (Thread.current[STACK] ||= []) << [span, parent]
+    scope.set_span(span) if span
+  end
+
+  def self.finish(_name, _id, _payload)
+    span, parent = Thread.current[STACK]&.pop
+    return unless span
+
+    span.finish
+    # Restore the parent. Guarded: Scope#set_span raises ArgumentError on nil,
+    # and the current scope may have changed since #start.
+    scope = Sentry.get_current_scope
+    scope.set_span(parent) if scope && parent
+  end
+end
+
+ActiveSupport::Notifications.subscribe(StandardId::Instrumentation::PATTERN, StandardIdSentrySpans)
+```
+
 ## Account Status (Activation/Deactivation)
 
 StandardId provides an optional `AccountStatus` concern for managing account activation and deactivation. This uses Rails enum with the event system to enforce status checks and handle side effects without modifying core authentication logic.
@@ -1182,6 +1296,121 @@ secret = client.create_client_secret!(name: "Production Secret")
 new_secret = client.rotate_client_secret!
 ```
 
+## Writing a Provider Plugin
+
+Social providers ship as separate gems (`standard_id-google`,
+`standard_id-apple`) that subclass `StandardId::Providers::Base` and register
+themselves. A minimal plugin is a provider class plus a two-line entry file.
+
+```ruby
+# lib/standard_id/github.rb — the gem's entry file
+require "standard_id"
+require "standard_id/github/providers/github"
+
+# Defines the Railtie that registers the provider after the host app has
+# initialized. No hand-written railtie.rb, no `if defined?(Rails)` guard.
+StandardId::Providers.plugin_railtie(:github, "StandardId::Providers::GitHub")
+```
+
+```ruby
+# lib/standard_id/github/providers/github.rb
+module StandardId
+  module Providers
+    class GitHub < Base
+      AUTH_ENDPOINT = "https://github.com/login/oauth/authorize".freeze
+      TOKEN_ENDPOINT = "https://github.com/login/oauth/access_token".freeze
+
+      class << self
+        def provider_name = "github"
+        def default_scope = "read:user user:email"
+        def supported_authorization_params = %i[scope login allow_signup]
+
+        # Fields land in the `social` config scope. `env:` and `required:` are
+        # read by StandardId (>= 0.42) and not passed to ConfigSchema.
+        def config_schema
+          {
+            github_client_id: { type: :string, default: nil },                  # ENV GITHUB_CLIENT_ID
+            github_client_secret: { type: :string, default: nil, required: true },
+            github_enterprise_host: { type: :string, default: nil, env: false } # no ENV fallback
+          }
+        end
+
+        def authorization_url(state:, redirect_uri:, **options)
+          build_authorization_url(
+            endpoint: AUTH_ENDPOINT,
+            client_id: StandardId.config.github_client_id,
+            redirect_uri:, state:, options:,
+            defaults: { scope: default_scope }
+          )
+        end
+
+        def get_user_info(code: nil, redirect_uri: nil, **)
+          rescue_to_oauth_error do
+            raise StandardId::InvalidRequestError, "Missing authorization code" if code.blank?
+
+            response = HttpClient.post_form(TOKEN_ENDPOINT, { code:, redirect_uri:, ... })
+            parsed = JSON.parse(response.body)
+            build_response(fetch_profile(parsed["access_token"]), tokens: extract_tokens(parsed))
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+**Required interface:** `provider_name`, `authorization_url`, `get_user_info`.
+
+**Optional hooks** (all class methods, with safe defaults):
+
+| Hook | Default | Purpose |
+|------|---------|---------|
+| `config_schema` | `{}` | `social` config fields. Per-field `env:` (String, or `false` to opt out; default is the upper-cased field name) and `required: true` |
+| `enabling_config_field` | `:<provider_name>_client_id` if declared | Field whose presence switches the provider on |
+| `required_config_fields` | fields with `required: true` | Must be present while enabled; reported by `configuration_errors` and the boot check |
+| `enabled?` / `configuration_errors` / `configured?` | derived from the two above | Override for enablement rules the fields cannot express |
+| `default_scope` | `nil` | Scope for the social-login grant |
+| `supported_authorization_params` | `[]` | Params `build_authorization_url` forwards from `options`. Include `:nonce` for OIDC |
+| `resolve_params(params, context:)` | `params` | Adjust params per flow (`context[:flow]` is `:web` or `:mobile`) |
+| `flow_for(params)` | `:web` only for `flow=web` on providers that `supports_mobile_callback?`, else `:mobile` | Flow for the API callback |
+| `skip_csrf?` | `false` | `true` for POST (form_post) callbacks |
+| `supports_mobile_callback?` | `false` | Enables the server-side redirect back to a native app |
+
+**Protected helpers** for use inside those methods — signatures are stable:
+
+| Helper | Does |
+|--------|------|
+| `build_response(user_info, tokens:)` | The standard `get_user_info` return value |
+| `build_authorization_url(endpoint:, client_id:, redirect_uri:, state:, options: {}, defaults: {}, response_type: "code")` | `client_id`, `redirect_uri`, `response_type`, `state`, then each `supported_authorization_params` entry from `options` or `defaults`; nils dropped |
+| `extract_tokens(parsed_token)` | `{ access_token:, refresh_token:, id_token: }` from a token response, nils dropped |
+| `verify_nonce!(expected:, actual:)` | Constant-time nonce check; no-op when `expected` is blank. Raises `InvalidRequestError` without echoing either value |
+| `rescue_to_oauth_error(message_prefix = nil) { ... }` | Lets `StandardId::OAuthError` through; wraps anything else in one, keeping `cause` |
+
+A plugin using `env:`, `required:` or these helpers should depend on
+`standard_id >= 0.42`. `Providers::Base.setup` is no longer called (removed
+from the base class in 0.42; the call-with-a-warning shim went in 0.43) — do
+one-off initialization in your own Railtie instead.
+
+**Testing a plugin, or an app that uses one:**
+
+```ruby
+# spec/rails_helper.rb
+require "standard_id/testing"
+
+# spec/initializers/standard_id_providers_spec.rb
+RSpec.describe "StandardId social providers" do
+  it_behaves_like "a registered StandardId provider", :google
+  it_behaves_like "a registered StandardId provider", :apple
+end
+
+expect(:apple).to be_a_registered_standard_id_provider.with_config_fields(:apple_client_id, :apple_team_id)
+```
+
+The shared example checks the provider is registered, that its fields
+(default: its whole `config_schema`) are declared on the `social` scope, and
+that each accepts a write the way `config/initializers/standard_id.rb` makes
+one.
+
 ## Schema DSL
 
 Schema is declared using a routes-like DSL and can be extended by provider gems:
@@ -1242,9 +1471,73 @@ bundle exec rspec spec/controllers/
   rejected with `invalid_request`.
 - Rate limiting on authentication endpoints
 
+## Missing Migrations
+
+`standard_id:install:migrations` copies the engine's migrations with new timestamps, so a gem migration that was never copied is invisible to Rails' own pending-migration check. StandardId checks for that itself, by migration name:
+
+- **At boot** (file-system only, no database): `config.missing_migrations` — `:warn` (default in development/test: logs and prints to stderr), `:raise` (fails boot with `StandardId::ConfigurationError`), or `:ignore` (default in every other environment — it never raises in production unless you opt in).
+- **`StandardId::MigrationCheck.pending(check_database: true)`** returns every gem migration that is `:not_installed` or installed but `:not_run` (one `schema_migrations` read).
+- **Health check** — `StandardId::Checks::Migrations` is [standard_health](https://github.com/rarebit-one/standard_health)-compatible (duck-typed, no dependency). Register it non-critical so a missing migration degrades `/health/ready` without failing it:
+
+  ```ruby
+  c.register_check :standard_id_migrations, StandardId::Checks::Migrations, critical: false
+  ```
+
+Two cases are built in and documented in `StandardId::MigrationCheck`:
+
+- **Superseded** (`SUPERSEDED_BY`): `20260414200000_add_target_created_at_index_to_code_challenges` counts as satisfied when `20260416180511` (whose partial, concurrently built index replaces it) is installed.
+- **Deferred upgrade steps** (`DEFERRED_UPGRADE_STEPS`): `20260915000000_remove_refresh_token_lifetime_…` is reported with `severity: :info`, as a pending upgrade step to run once 0.41.1+ is deployed everywhere. It is logged at info level at boot and listed under `pending_upgrade_steps` in an `:ok` health result. It never warns, raises or degrades.
+
+Any other migration you deliberately skipped goes in `config.ignored_migrations`, by name or original version.
+
 ## Scheduled Maintenance
 
-StandardId ships cleanup jobs (`StandardId::CleanupExpiredSessionsJob`, `StandardId::CleanupExpiredRefreshTokensJob`) and rake wrappers (`standard_id:cleanup:all`, `:sessions`, `:refresh_tokens`) to prune expired rows. See [docs/OPERATIONS.md](docs/OPERATIONS.md) for SolidQueue, sidekiq-cron, whenever, and system-cron scheduling examples.
+StandardId never deletes expired rows on its own. Four cleanup jobs do, and **all four must be scheduled** — an unscheduled one lets its table grow forever (code challenges hold the plaintext OTP):
+
+| Job | Deletes | Grace windows (`perform` kwargs) | Recommended cadence |
+|---|---|---|---|
+| `StandardId::CleanupExpiredSessionsJob` | browser/device/service sessions expired > grace | `grace_period_seconds:` 7 days | hourly (minute 6) |
+| `StandardId::CleanupExpiredRefreshTokensJob` | refresh tokens expired or revoked > grace | `grace_period_seconds:` 7 days | hourly (minute 3) |
+| `StandardId::CleanupExpiredAuthorizationCodesJob` | OAuth authorization codes expired > 7 days or consumed > 1 day | `grace_period_seconds:`, `consumed_grace_period_seconds:` | hourly (minute 9) |
+| `StandardId::CleanupExpiredCodeChallengesJob` | OTP code challenges expired > 7 days or used > 1 day | `grace_period_seconds:`, `used_grace_period_seconds:` | hourly (minute 13) |
+
+Retention is bounded by the grace windows, not the cadence; each job is a single `DELETE`, so running hourly keeps that statement small on busy tables (daily is fine for small apps). Stagger them off minute 0.
+
+`rails g standard_id:install` adds all four to `config/recurring.yml` (Solid Queue) under `production:` when that file exists (`--skip-recurring` to opt out; re-running is a no-op). An engine cannot register Solid Queue recurring tasks itself — Solid Queue reads one schedule file — so existing apps should paste this under their `production:` key:
+
+```yaml
+  standard_id_cleanup_expired_sessions:
+    class: StandardId::CleanupExpiredSessionsJob
+    schedule: every hour at minute 6
+  standard_id_cleanup_expired_refresh_tokens:
+    class: StandardId::CleanupExpiredRefreshTokensJob
+    schedule: every hour at minute 3
+  standard_id_cleanup_expired_authorization_codes:
+    class: StandardId::CleanupExpiredAuthorizationCodesJob
+    schedule: every hour at minute 9
+  standard_id_cleanup_expired_code_challenges:
+    class: StandardId::CleanupExpiredCodeChallengesJob
+    schedule: every hour at minute 13
+```
+
+**One entry, one cron monitor (0.43+).** `StandardId::CleanupAllJob` runs all four inline; a failure in one does not skip the rest, and the first error is re-raised afterwards so the run still fails. Schedule it instead of the four when you want a single recurring entry — e.g. to put the schedule under one Sentry cron monitor (the gem's jobs carry none). Subclass it to attach the monitor:
+
+```ruby
+# app/jobs/standard_id_cleanup_job.rb
+class StandardIdCleanupJob < StandardId::CleanupAllJob
+  include Sentry::Cron::MonitorCheckIns
+  sentry_monitor_check_ins slug: "standard-id-cleanup",
+    monitor_config: Sentry::Cron::MonitorConfig.from_crontab("7 * * * *", checkin_margin: 5, max_runtime: 10)
+end
+```
+
+```yaml
+  standard_id_cleanup:
+    class: StandardIdCleanupJob
+    schedule: every hour at minute 7
+```
+
+Rake wrappers (`standard_id:cleanup:all`, `:sessions`, `:refresh_tokens`, `:authorization_codes`, `:code_challenges`) run the same jobs inline. See [docs/OPERATIONS.md](docs/OPERATIONS.md) for sidekiq-cron, whenever and system-cron examples.
 
 ## Contributing
 

data/app/controllers/concerns/standard_id/inertia_rendering.rb

@@ -39,14 +39,27 @@ module StandardId
           notice: flash[:notice],
           alert: flash[:alert]
         }.compact,
-        social_providers: {
-          google_enabled: StandardId.config.google_client_id.present?,
-          apple_enabled: StandardId.config.apple_client_id.present?
-        },
+        social_providers: social_provider_flags,
+        enabled_social_providers: StandardId.enabled_social_providers.keys,
         enabled_mechanisms: web_enabled_mechanisms
       }.deep_merge(additional_props)
     end
 
+    # `{ "<name>_enabled": Boolean }` for every registered provider.
+    #
+    # google_enabled / apple_enabled are always present (false when the
+    # plugin is not installed) so front ends written against the original
+    # two-key shape keep working. New front ends should iterate
+    # `enabled_social_providers` instead.
+    LEGACY_SOCIAL_PROVIDER_FLAGS = { google_enabled: false, apple_enabled: false }.freeze
+    private_constant :LEGACY_SOCIAL_PROVIDER_FLAGS
+
+    def social_provider_flags
+      StandardId::ProviderRegistry.all.each_with_object(LEGACY_SOCIAL_PROVIDER_FLAGS.dup) do |(name, provider), flags|
+        flags[:"#{name}_enabled"] = provider.enabled?
+      end
+    end
+
     def web_enabled_mechanisms
       web = StandardId.config.web
       {
@@ -58,7 +71,12 @@ module StandardId
         email_verification: web.email_verification,
         phone_verification: web.phone_verification,
         sessions_management: web.sessions_management,
-        passwordless_registration: web.passwordless_registration
+        # Effective value for this request: the active scope's
+        # allow_registration can switch it off (see ScopeConfig#allow_registration).
+        passwordless_registration: StandardId::ScopeConfig.registration_allowed?(
+          web.passwordless_registration,
+          respond_to?(:current_scope_config, true) ? current_scope_config : nil
+        )
       }
     end
   end

data/app/controllers/concerns/standard_id/lifecycle_hooks.rb

@@ -223,6 +223,7 @@ module StandardId
         account.sessions.strict_loading(false).destroy_all
         identifiers = account.identifiers.strict_loading(false).to_a
         identifiers.each { |i| i.credentials.strict_loading(false).destroy_all }
+        # Deliberately destroy! (unlike the destroy_all calls above): a failed identifier destroy raises and rolls back the whole cleanup, failing loud instead of leaving a half-cleaned orphan.
         identifiers.each(&:destroy!)
         account.destroy
       end