standard_id 0.42.0 → 0.43.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e1701f28a06762afc1eac4d5d31408180ab6b89bf617d420124301ad55c0f8b
-  data.tar.gz: be9d2d78656afd4d0d2e67e17bbf1fdb3cd6c586af6ad85e5514385b1b52f025
+  metadata.gz: 8003e8ad18d3a88d9684bb3877d88bbc1d9d207a897776e6ef3a6cd01b0f1191
+  data.tar.gz: 3fb388482c096695f36d79ee02e122e1cbede9fc1d11b14c6236a4d423a82a0b
 SHA512:
-  metadata.gz: 924d298113db49b3014dd440b49d038476f23bab8474cf02a661839079580a4ee772c8cdaeb0cf330bfe85fa437b6042af1ffbf1d299d8a4ecbf7ac091c0bafa
-  data.tar.gz: a9f4da6de783d8e7d0c8f862c2a5ca80c708856746a45ec61605f51160ef8d85b596b1fbad7b75bda3e5cae6311061fb43424db74005e0c24d9ba7fb3a4c55ab
+  metadata.gz: 2aade7f1bba3cb85827120d4ac19e55b0a2a039955097cd43af6ef75a84f1516080c4e6c0fc36a87d15731bb332603eab987c93130e69e2e2f5701a5ac929053
+  data.tar.gz: c0a8bc153ac8db1de5f5186fb014e4ed89e0b5db06ef7e295ee276f032fc59ec39a591eb6e54e440263a22d43faf8b426f6e1acf4ab09fed72870e96c4e17f85

data/CHANGELOG.md

@@ -7,6 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.43.1] - 2026-09-24
+
+Fixes found while shipping 0.43.0. **Take this instead of 0.43.0** — hosts on `c.passwordless.delivery = :built_in` with the WebEngine mounted (jumpdrive-web, nutripod-web) would otherwise email email-verification codes as "your sign-in code".
+
+### Fixed
+
+- **Verification codes no longer use the sign-in email.** The built-in `PasswordlessDeliverySubscriber` sent `PasswordlessMailer#otp_email` ("Your sign-in code" / "Use the following code to sign in") for every realm, which 0.43.0 made reachable from WebEngine `verify_email/start` (realm `"verification"`). Only the `"authentication"` realm gets `otp_email` now. Every other realm — `verify_email`, `Otp.issue` contact verification, step-up — gets the new **`PasswordlessMailer#verification_email`** ("Your verification code" / "Use the following code to complete your verification"). Both emails state the challenge's actual expiry (the new `expires_in_minutes` param) instead of assuming `code_ttl`. There is still no built-in SMS delivery.
+- **The WebEngine `verify_email` / `verify_phone` start 422 now gives the real reason.** The response body used to be a fixed `"invalid email"` / `"invalid phone"`; it now matches the flash: the format error, the host `username_validator`'s message, or the retry cooldown ("Please wait N seconds before requesting another code").
+- **`PASSWORDLESS_CODE_SENT` no longer claims `delivery_status: "sent"` for codes the engine never delivered.** It was emitted as `"sent"` after every non-manual issue, including when delivery belonged to a host subscriber, or to none at all (`Otp.issue(delivery: :custom)` with no subscriber). It is still emitted in the same cases (so audit trails that record `standard_id.passwordless.*` keep their row), but `delivery_status` is now:
+  - `"sent"` — the built-in mailer enqueued the email (`deliver_later` returned a job);
+  - `"failed"` — the built-in mailer was responsible but did not enqueue it: the enqueue raised (the subscriber logs the error) or Active Job refused it (`deliver_later` returned `false`);
+  - `"delegated"` — a host `PASSWORDLESS_CODE_GENERATED` subscriber is responsible (global `:custom`, `Otp.issue(delivery: :custom)`, or SMS), so the engine cannot confirm a send.
+
+  Never emitted for `Otp.issue(delivery: :manual)`, as before. None of the five apps subscribes to `PASSWORDLESS_CODE_SENT` or reads `delivery_status`. fundbright-web, luminality-web and nutripod-web audit `standard_id.passwordless.*`, and jumpdrive-web audits all `standard_id.*`, so their stored `passwordless.code.sent` rows will now carry `"delegated"` (fundbright-web, luminality-web) or `"sent"` / `"failed"` (jumpdrive-web, nutripod-web) instead of a blanket `"sent"`.
+
+### Added
+
+- **i18n for the built-in OTP emails** (`config/locales/en.yml`): `standard_id.passwordless_mailer.{otp_email,verification_email}.{subject,greeting,intro,expiry,ignore,footer}`. Override any key in the host's locale files. The gem ships only `en`; in any other `I18n.locale` a key the host has not translated falls back to the English copy (no "translation missing", with or without I18n fallbacks enabled). An **assigned** `c.passwordless.mailer_subject` still wins for the sign-in subject (jumpdrive-web sets one), and its unassigned default equals the i18n default, so nothing changes for a host that overrides neither.
+- `PasswordlessDeliverySubscriber.handles?(payload)` — whether the built-in mailer delivers a given `PASSWORDLESS_CODE_GENERATED` payload.
+- `CodeChallenge#built_in_delivered` — a transient flag (not persisted) the built-in subscriber sets once it has enqueued the email.
+
+### Upgrade notes
+
+Nothing is required. A host that overrides `app/views/standard_id/passwordless_mailer/otp_email.*` (luminality-web, via its React email build) keeps its sign-in template. With `:built_in` delivery, verification-realm codes now render the gem's `verification_email` template unless the host overrides that one too. luminality-web calls `PasswordlessMailer.with(...).otp_email` directly for its own verification flow; that call is unchanged.
+
+## [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

data/README.md

@@ -299,6 +299,30 @@ 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|
   # Only needed when not using the canonical ENV names above:
@@ -518,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
@@ -527,13 +552,28 @@ 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 — `otp_email` ("Your sign-in code") for the `"authentication"`
+realm and `verification_email` ("Your verification code") for every other realm
+(WebEngine `verify_email`, `Otp.issue` contact verification / step-up). There is
+no built-in SMS delivery. The copy is in `config/locales/en.yml` under
+`standard_id.passwordless_mailer.{otp_email,verification_email}.*` (`subject`,
+`greeting`, `intro`, `expiry`, `ignore`, `footer`); override any key in your own
+locale files, or the templates in `app/views/standard_id/passwordless_mailer/`.
+An assigned `c.passwordless.mailer_subject` still sets the sign-in subject. 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
 
@@ -575,9 +615,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.
 
@@ -660,7 +700,7 @@ Every StandardId event automatically carries tracing metadata (`event_id`, `time
 |  | `oauth.code.consumed` | `authorization_code`, `client_id`, `account` | After an authorization code is exchanged |
 | Passwordless | `passwordless.code.requested` | `identifier`, `channel` (email/sms) | Before generating an OTP |
 |  | `passwordless.code.generated` | `code_challenge`, `identifier`, `channel`, `expires_at` | After an OTP is created |
-|  | `passwordless.code.sent` | `identifier`, `channel`, `delivery_status` | After an OTP is delivered |
+|  | `passwordless.code.sent` | `identifier`, `channel`, `realm`, `delivery_status` | After an OTP is handed to delivery (not for `Otp.issue(delivery: :manual)`). `delivery_status`: `"sent"` (built-in mailer enqueued it), `"failed"` (built-in mailer was responsible but did not enqueue), `"delegated"` (a host `PASSWORDLESS_CODE_GENERATED` subscriber delivers — the engine can't confirm it) |
 |  | `passwordless.code.verified` | `code_challenge`, `account`, `channel` | After OTP verification succeeds |
 |  | `passwordless.code.failed` | `identifier`, `channel`, `attempts` | After OTP verification fails |
 |  | `passwordless.account.created` | `account`, `channel`, `identifier` | When an account is created via passwordless flow |
@@ -795,6 +835,7 @@ module StandardIdSentrySpans
   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
@@ -808,7 +849,10 @@ module StandardIdSentrySpans
     return unless span
 
     span.finish
-    Sentry.get_current_scope.set_span(parent)
+    # 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
 
@@ -1350,7 +1394,8 @@ end
 | `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` was removed in 0.42 — do
+`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:**
@@ -1482,6 +1527,23 @@ Retention is bounded by the grace windows, not the cadence; each job is a single
     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/rate_limit_handling.rb

@@ -41,29 +41,15 @@ module StandardId
       end
     end
 
-    # Resolve the effective per-IP login rate limit, preferring the
-    # mechanism-agnostic `login_per_ip` alias and falling back to the deprecated
-    # `password_login_per_ip` when the host left the alias at its default (i.e.
-    # only configured the old name). The new alias wins whenever explicitly set.
-    # Mirrors the max_attempts -> max_attempts_per_challenge deprecation-alias
-    # precedent (prefer-new, fall-back-to-old).
+    # Effective per-IP login rate limit (`rate_limits.login_per_ip`). The
+    # deprecated `password_login_per_ip` fallback was removed in 0.43.
     def self.login_per_ip
-      resolve_login_alias(:login_per_ip, :password_login_per_ip)
+      StandardId.config.rate_limits.login_per_ip
     end
 
-    # Effective per-email login rate limit; see .login_per_ip.
+    # Effective per-email login rate limit (`rate_limits.login_per_email`).
     def self.login_per_email
-      resolve_login_alias(:login_per_email, :password_login_per_email)
-    end
-
-    # Return the alias value unless it still equals its schema default, in which
-    # case fall back to the deprecated field. Both fields share the same default,
-    # so the effective default is unchanged when neither is set.
-    def self.resolve_login_alias(new_field, old_field)
-      rate_limits = StandardId.config.rate_limits
-      default = StandardId.config.__schema__.field_for(:rate_limits, new_field).default_value
-      new_value = rate_limits[new_field]
-      new_value == default ? rate_limits[old_field] : new_value
+      StandardId.config.rate_limits.login_per_email
     end
 
     private

data/app/controllers/standard_id/web/login_controller.rb

@@ -11,8 +11,7 @@ module StandardId
       layout "public"
 
       # RAR-51: Rate limit login attempts by IP (20 per 15 minutes). Reads the
-      # mechanism-agnostic `login_per_ip` alias, falling back to the deprecated
-      # `password_login_per_ip` — this action branches password OR passwordless,
+      # mechanism-agnostic `login_per_ip` — this action branches password OR passwordless,
       # so on a passwordless app this governs the OTP-send limit, not a password
       # login. See StandardId::RateLimitHandling.login_per_ip.
       rate_limit to: StandardId::RateLimitHandling.login_per_ip,

data/app/controllers/standard_id/web/verify_email/start_controller.rb

@@ -32,20 +32,27 @@ module StandardId
           email = params[:email].to_s.strip.downcase
           if email.blank?
             flash[:alert] = "Please enter your email address"
-            render plain: "missing email", status: :unprocessable_content and return
+            render plain: flash[:alert], status: :unprocessable_content and return
           end
 
-          challenge = StandardId::CodeChallenge.create!(
+          # Issued through the passwordless strategy (validation, retry delay,
+          # previous-code invalidation) so delivery goes through the
+          # PASSWORDLESS_CODE_GENERATED event like every other OTP. Before 0.43
+          # this called the since-removed passwordless_email_sender directly.
+          result = StandardId::Otp.issue(
             realm: "verification",
-            channel: "email",
             target: email,
-            code: StandardId::Passwordless.generate_otp_code,
-            expires_at: 10.minutes.from_now,
-            ip_address: StandardId::Utils::IpNormalizer.normalize(request.remote_ip),
-            user_agent: request.user_agent
+            channel: :email,
+            request: request,
+            expires_in: 10.minutes
           )
-
-          StandardId.config.passwordless_email_sender&.call(email, challenge.code)
+          unless result.success?
+            # The body carries the same reason as the flash: a malformed
+            # target, the host's username_validator message, or the retry
+            # cooldown ("Please wait N seconds ...").
+            flash[:alert] = result.error_message
+            render plain: result.error_message, status: :unprocessable_content and return
+          end
 
           redirect_to standard_id_web.login_path, notice: "Verification code sent to your email", status: :see_other
         end

data/app/controllers/standard_id/web/verify_phone/start_controller.rb

@@ -32,20 +32,27 @@ module StandardId
           phone = params[:phone_number].to_s.strip
           if phone.blank? || !(phone.match?(/\A\+?[1-9]\d{1,14}\z/))
             flash[:alert] = "Please enter a valid phone number"
-            render plain: "invalid phone", status: :unprocessable_content and return
+            render plain: flash[:alert], status: :unprocessable_content and return
           end
 
-          challenge = StandardId::CodeChallenge.create!(
+          # Issued through the passwordless strategy (validation, retry delay,
+          # previous-code invalidation) so delivery goes through the
+          # PASSWORDLESS_CODE_GENERATED event like every other OTP. Before 0.43
+          # this called the since-removed passwordless_sms_sender directly.
+          result = StandardId::Otp.issue(
             realm: "verification",
-            channel: "sms",
             target: phone,
-            code: StandardId::Passwordless.generate_otp_code,
-            expires_at: 10.minutes.from_now,
-            ip_address: StandardId::Utils::IpNormalizer.normalize(request.remote_ip),
-            user_agent: request.user_agent
+            channel: :sms,
+            request: request,
+            expires_in: 10.minutes
           )
-
-          StandardId.config.passwordless_sms_sender&.call(phone, challenge.code)
+          unless result.success?
+            # The body carries the same reason as the flash: a malformed
+            # target, the host's username_validator message, or the retry
+            # cooldown ("Please wait N seconds ...").
+            flash[:alert] = result.error_message
+            render plain: result.error_message, status: :unprocessable_content and return
+          end
 
           redirect_to standard_id_web.login_path, notice: "Verification code sent via SMS", status: :see_other
         end

data/app/jobs/standard_id/cleanup_all_job.rb

@@ -0,0 +1,46 @@
+module StandardId
+  # Runs all four expired-row cleanup jobs inline, in one job.
+  #
+  # Schedule this ONE job instead of the four individual ones when you want a
+  # single recurring entry — typically so the schedule carries one cron
+  # monitor (Sentry, Honeybadger, …) rather than four. Subclass it in the host
+  # to attach the monitor:
+  #
+  #   # 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 * * * *")
+  #   end
+  #
+  # One table's DELETE failing (a lock timeout, say) does not skip the others;
+  # the first error is re-raised once all four have run, so the run still
+  # fails its cron check-in and lands in the queue's failed executions.
+  #
+  # Each job keeps its default grace windows (see README "Scheduled
+  # Maintenance"); retention is bounded by those, not by the cadence.
+  class CleanupAllJob < ApplicationJob
+    queue_as :default
+
+    # @return [Array<Class>] the cleanup jobs run, in order
+    def self.jobs
+      [
+        StandardId::CleanupExpiredSessionsJob,
+        StandardId::CleanupExpiredRefreshTokensJob,
+        StandardId::CleanupExpiredAuthorizationCodesJob,
+        StandardId::CleanupExpiredCodeChallengesJob
+      ]
+    end
+
+    def perform
+      errors = self.class.jobs.filter_map do |job|
+        job.perform_now
+        nil
+      rescue StandardError => e
+        Rails.logger.warn("[StandardId] #{job.name} failed: #{e.class}: #{e.message}")
+        e
+      end
+      raise errors.first if errors.any?
+    end
+  end
+end

data/app/mailers/standard_id/passwordless_mailer.rb

@@ -1,16 +1,72 @@
 module StandardId
+  # Built-in OTP emails, sent by Events::Subscribers::PasswordlessDeliverySubscriber
+  # when `c.passwordless.delivery = :built_in`.
+  #
+  # * #otp_email — the sign-in code (realm "authentication").
+  # * #verification_email — every other realm: WebEngine verify_email/start
+  #   (realm "verification") and `Otp.issue(realm: ...)` for contact
+  #   verification, step-up and the like. It must not tell the recipient the
+  #   code is for signing in.
+  #
+  # Copy lives under `standard_id.passwordless_mailer.<action>.*` in
+  # config/locales/en.yml; override any key in the host's locale files, or
+  # override the templates in app/views/standard_id/passwordless_mailer/.
+  # `c.passwordless.mailer_subject`, when assigned, still sets the sign-in
+  # subject (it wins over the i18n key).
   class PasswordlessMailer < ApplicationMailer
     layout false
 
+    helper_method :otp_copy
+
+    # @param email [String]
+    # @param otp_code [String]
+    # @param expires_in_minutes [Integer, nil] defaults to passwordless.code_ttl
     def otp_email
-      @otp_code = params[:otp_code]
-      @email = params[:email]
+      assign_otp_params
+      subject = if StandardId.config.passwordless.assigned?(:mailer_subject)
+        StandardId.config.passwordless.mailer_subject
+      else
+        otp_copy(:subject, default: StandardId.config.passwordless.mailer_subject)
+      end
+
+      mail(to: @email, from: StandardId.config.passwordless.mailer_from, subject: subject)
+    end
+
+    # @param email [String]
+    # @param otp_code [String]
+    # @param realm [String, nil] the OTP realm, available to overriding templates
+    # @param expires_in_minutes [Integer, nil] defaults to passwordless.code_ttl
+    def verification_email
+      assign_otp_params
+      @realm = params[:realm]
 
       mail(
         to: @email,
         from: StandardId.config.passwordless.mailer_from,
-        subject: StandardId.config.passwordless.mailer_subject
+        subject: otp_copy(:subject)
       )
     end
+
+    # Copy for the current action from
+    # standard_id.passwordless_mailer.<action>.<key>, in I18n.locale. Falls
+    # back to the gem's English copy when the host has no translation for
+    # that locale (the gem ships only `en`, and a host need not enable
+    # I18n fallbacks), so a zh-SG request never renders "translation missing".
+    #
+    # @param key [Symbol, String]
+    # @param default [String, nil] final fallback when even `en` has no key
+    def otp_copy(key, default: nil, **options)
+      scope = "standard_id.passwordless_mailer.#{action_name}"
+      english = I18n.t(key, scope: scope, locale: :en, default: default, **options)
+      I18n.t(key, scope: scope, default: english, **options)
+    end
+
+    private
+
+    def assign_otp_params
+      @otp_code = params[:otp_code]
+      @email = params[:email]
+      @expires_in_minutes = params[:expires_in_minutes] || (StandardId.config.passwordless.code_ttl / 60)
+    end
   end
 end

data/app/models/standard_id/code_challenge.rb

@@ -1,5 +1,9 @@
 module StandardId
   class CodeChallenge < ApplicationRecord
+    # Transient (not persisted): set by the built-in PasswordlessDeliverySubscriber
+    # once it has enqueued the email, so the passwordless strategy can report
+    # PASSWORDLESS_CODE_SENT truthfully.
+    attr_accessor :built_in_delivered
     self.table_name = "standard_id_code_challenges"
 
     # Well-known realms used by the engine itself. Host apps may create

data/app/views/standard_id/passwordless_mailer/otp_email.html.erb

@@ -11,13 +11,13 @@
 </head>
 <body>
   <div class="container">
-    <p>Hi,</p>
-    <p>Use the following code to sign in:</p>
+    <p><%= otp_copy(:greeting) %></p>
+    <p><%= otp_copy(:intro) %></p>
     <div class="code"><%= @otp_code %></div>
-    <p>This code will expire in <%= StandardId.config.passwordless.code_ttl / 60 %> minutes.</p>
-    <p>If you did not request this code, you can safely ignore this email.</p>
+    <p><%= otp_copy(:expiry, count: @expires_in_minutes) %></p>
+    <p><%= otp_copy(:ignore) %></p>
     <div class="footer">
-      <p>This is an automated message. Please do not reply.</p>
+      <p><%= otp_copy(:footer) %></p>
     </div>
   </div>
 </body>

data/app/views/standard_id/passwordless_mailer/otp_email.text.erb

@@ -1,12 +1,12 @@
-Hi,
+<%= otp_copy(:greeting) %>
 
-Use the following code to sign in:
+<%= otp_copy(:intro) %>
 
   <%= @otp_code %>
 
-This code will expire in <%= StandardId.config.passwordless.code_ttl / 60 %> minutes.
+<%= otp_copy(:expiry, count: @expires_in_minutes) %>
 
-If you did not request this code, you can safely ignore this email.
+<%= otp_copy(:ignore) %>
 
 --
-This is an automated message. Please do not reply.
+<%= otp_copy(:footer) %>

data/app/views/standard_id/passwordless_mailer/verification_email.html.erb

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; background-color: #f5f5f5; margin: 0; padding: 0; }
+    .container { max-width: 480px; margin: 40px auto; background-color: #ffffff; border-radius: 8px; padding: 40px; }
+    .code { font-size: 32px; font-weight: bold; letter-spacing: 8px; text-align: center; padding: 20px; background-color: #f0f0f0; border-radius: 6px; margin: 24px 0; font-family: monospace; }
+    .footer { margin-top: 32px; font-size: 13px; color: #888888; text-align: center; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <p><%= otp_copy(:greeting) %></p>
+    <p><%= otp_copy(:intro) %></p>
+    <div class="code"><%= @otp_code %></div>
+    <p><%= otp_copy(:expiry, count: @expires_in_minutes) %></p>
+    <p><%= otp_copy(:ignore) %></p>
+    <div class="footer">
+      <p><%= otp_copy(:footer) %></p>
+    </div>
+  </div>
+</body>
+</html>

data/app/views/standard_id/passwordless_mailer/verification_email.text.erb

@@ -0,0 +1,12 @@
+<%= otp_copy(:greeting) %>
+
+<%= otp_copy(:intro) %>
+
+  <%= @otp_code %>
+
+<%= otp_copy(:expiry, count: @expires_in_minutes) %>
+
+<%= otp_copy(:ignore) %>
+
+--
+<%= otp_copy(:footer) %>

data/config/locales/en.yml

@@ -0,0 +1,22 @@
+en:
+  standard_id:
+    passwordless_mailer:
+      otp_email:
+        # Used only when c.passwordless.mailer_subject is not assigned.
+        subject: "Your sign-in code"
+        greeting: "Hi,"
+        intro: "Use the following code to sign in:"
+        expiry:
+          one: "This code will expire in %{count} minute."
+          other: "This code will expire in %{count} minutes."
+        ignore: "If you did not request this code, you can safely ignore this email."
+        footer: "This is an automated message. Please do not reply."
+      verification_email:
+        subject: "Your verification code"
+        greeting: "Hi,"
+        intro: "Use the following code to complete your verification:"
+        expiry:
+          one: "This code will expire in %{count} minute."
+          other: "This code will expire in %{count} minutes."
+        ignore: "If you did not request this code, you can safely ignore this email."
+        footer: "This is an automated message. Please do not reply."

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

@@ -253,10 +253,10 @@ StandardId.configure do |c|
   #   Account.create!(email: identifier.value)
   # }
 
-  # 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:
+  # With c.passwordless.delivery = :custom, deliver codes from an event
+  # subscriber (c.passwordless_email_sender / _sms_sender were removed in
+  # 0.43). It runs synchronously in the request, so I18n.locale etc. are still
+  # available. The same subscriber delivers Otp.issue(delivery: :custom) codes.
   #
   # StandardId::Events.subscribe(StandardId::Events::PASSWORDLESS_CODE_GENERATED) do |event|
   #   next if event[:skip_sender] # Otp.issue(delivery: :manual)
@@ -510,8 +510,7 @@ 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 old password_login_per_ip/_per_email names
-  # still work but emit a deprecation warning (the new name wins when both are set).
+  # mechanism-agnostic names (password_login_per_ip/_per_email were removed in 0.43).
   # c.rate_limits.login_per_ip                   = 20  # per 15 minutes
   # c.rate_limits.login_per_email                = 5   # per 15 minutes
   # c.rate_limits.otp_verify_per_ip              = 20  # per 15 minutes