standard_id 0.43.0 → 0.43.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f9798d4a8c4db5cbc69cc0c4f569cc41e825b5df159124fab15f39923ca602f
-  data.tar.gz: 1b06dc3eee0795f25633df9dc93dae5376c0bc5f6e1b0cd97ef3ce37fca6fc02
+  metadata.gz: 4bb59a29db3ed35482b44a1a0755a3827d7e02a6ad3a78bad5e5bd22e309d048
+  data.tar.gz: 93491ec90c91e2fdc6cf900bc62f9475ee786c723f4591dc40446964fbac1492
 SHA512:
-  metadata.gz: 10594cb5f3206999becca9fb582bfcc714f8371713160192ddf72fdeb39fe4f9552e9d551991fcf294af2eca71fcd8266f8c1f0a27e94c069a7f597581a54d8e
-  data.tar.gz: 1ababa07f26cea7f6240666372f25ada38a7c3672313306c1ce7eddedded43efaff08b27df71d50c1b78f75e75d6f909f421236c455d1ac9c1658015752bdc4c
+  metadata.gz: 0daceb3e839301ec3b294b8aa36af72441ec5b52ea82bcdcb7066fbc1bfef97cb5efaa11d62f729995c4a7ad22b22afd946e3ed1ff4999fa694a3dc2446b8a50
+  data.tar.gz: ab971a917f3ea552ca3c54d6928a88086bfef17066131cb727a12df721d6bfd2988fb348a33ded3fd529d09102ea053b904ff5146129e9b5008e10e64d7b2f15

data/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.43.2] - 2026-09-25
+
+### Fixed
+
+- **`CleanupExpiredSessionsJob` failed on every run once an expired session had a refresh token** (sidekick-web SIDEKICK-WEB-3K / cron monitor SIDEKICK-WEB-3M: `PG::ForeignKeyViolation … violates foreign key constraint "fk_rails_db44ba6f6e" on table "standard_id_refresh_tokens"`). `standard_id_refresh_tokens.session_id` references `standard_id_sessions` with no `ON DELETE` action, and `Session.where(...).delete_all` skipped the model's `dependent: :nullify`. This affected every host that schedules the job, directly or through `CleanupAllJob`, and nothing was ever cleaned up. Now, per batch of 1,000 (`batch_size:`), in one transaction, with the candidate rows re-checked under `FOR UPDATE SKIP LOCKED`:
+  - **An expired session that still has a live refresh token (unrevoked, unexpired) is kept.** Refresh tokens deliberately outlive their session's expiry: `RefreshTokenFlow#validate_parent_session!` checks revocation, not expiry, since 0.35.x, so `refresh_token_lifetime` alone decides how long a client stays signed in (jumpdrive-web runs 1-day browser sessions against 30-day refresh tokens). Deleting such a session would detach its token and lose "revoking this session ends its access". Revoking the token, as `Session#destroy` does, would sign the client out early. The session is collected on a later run, once its tokens are dead, so at most `refresh_token_lifetime` after it would otherwise have gone.
+  - **Dead refresh tokens (revoked or expired) of the sessions being deleted are detached** (`session_id` → `NULL`, as `dependent: :nullify` does) rather than deleted. `CleanupExpiredRefreshTokensJob` removes them on its own window, and until then a replayed revoked token still triggers reuse detection.
+  - A host whose copy of the migration added `on_delete: :nullify` to that FK (sidekick-web's `db/schema.rb` shows one, although its production constraint evidently has none) no longer has live tokens silently detached from their sessions either.
+- The other cleanup jobs had no such hazard. Nothing references `standard_id_authorization_codes` or `standard_id_code_challenges`, and the only foreign key into `standard_id_refresh_tokens` is its own `previous_token_id`, which is `ON DELETE SET NULL`. `standard_id_refresh_tokens.session_id` is the only foreign key into `standard_id_sessions`, in the gem, standard_id-provider and all five apps.
+
+### Changed
+
+- **Requires Rails 8.1** (`rails >= 8.1`, was `>= 8.0`; #344, merged since 0.43.1). All five consumer apps already run Rails 8.1.3.1, and 8.0 was never tested in CI.
+
+### Upgrade notes
+
+Bump only. The first run after upgrading deletes, in batches, the backlog of expired sessions the job never managed to remove.
+
+## [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**.

data/README.md

@@ -554,7 +554,14 @@ 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
+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:
@@ -693,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 |

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

@@ -32,7 +32,7 @@ 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
 
           # Issued through the passwordless strategy (validation, retry delay,
@@ -47,8 +47,11 @@ module StandardId
             expires_in: 10.minutes
           )
           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: "invalid email", status: :unprocessable_content and return
+            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

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

@@ -32,7 +32,7 @@ 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
 
           # Issued through the passwordless strategy (validation, retry delay,
@@ -47,8 +47,11 @@ module StandardId
             expires_in: 10.minutes
           )
           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: "invalid phone", status: :unprocessable_content and return
+            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

data/app/jobs/standard_id/cleanup_expired_sessions_job.rb

@@ -2,14 +2,70 @@ module StandardId
   class CleanupExpiredSessionsJob < ApplicationJob
     queue_as :default
 
+    DEFAULT_BATCH_SIZE = 1_000
+
     # Delete sessions that expired more than `grace_period_seconds` ago.
     # A grace period avoids deleting sessions that just expired and might
     # still be referenced in in-flight requests.
     # Accepts integer seconds for reliable ActiveJob serialization across all queue adapters.
-    def perform(grace_period_seconds: 7.days.to_i)
+    #
+    # Refresh tokens reference their session (standard_id_refresh_tokens.session_id,
+    # a foreign key with no ON DELETE action in the gem's migration), and
+    # `delete_all` skips the model's `dependent: :nullify`, so a bare delete
+    # failed the whole run once any expired session had a refresh token
+    # (sidekick-web SIDEKICK-WEB-3K). Per batch, in one transaction:
+    #
+    # * An expired session that still has a LIVE refresh token (unrevoked,
+    #   unexpired) is kept. Refresh tokens deliberately outlive their session's
+    #   expiry — RefreshTokenFlow#validate_parent_session! checks revocation,
+    #   not expiry, so refresh_token_lifetime alone governs how long a client
+    #   stays signed in. Deleting the session would detach the token from it and
+    #   lose "revoking this session ends its access"; revoking the token (what
+    #   Session#destroy does) would sign the client out early. The session is
+    #   collected on a later run, once its tokens are dead — at most
+    #   refresh_token_lifetime later.
+    # * Dead refresh tokens (revoked or expired) of the sessions being deleted
+    #   are detached (`session_id` → NULL, the model's `dependent: :nullify`),
+    #   not deleted: CleanupExpiredRefreshTokensJob removes them on its own
+    #   window, and until then a replayed revoked token still triggers reuse
+    #   detection.
+    #
+    # Batches (`in_batches`) keep each transaction and its locks small.
+    def perform(grace_period_seconds: 7.days.to_i, batch_size: DEFAULT_BATCH_SIZE)
       cutoff = grace_period_seconds.seconds.ago
-      deleted = StandardId::Session.where("expires_at < ?", cutoff).delete_all
+      deleted = 0
+
+      StandardId::Session.where("expires_at < ?", cutoff).in_batches(of: batch_size) do |batch|
+        deleted += delete_batch(batch.pluck(:id), cutoff)
+      end
+
       Rails.logger.info("[StandardId] Cleaned up #{deleted} expired sessions older than #{cutoff}")
     end
+
+    private
+
+    def delete_batch(candidate_ids, cutoff)
+      StandardId::Session.transaction do
+        # Re-check under a row lock: a sign-in may have revived one of these
+        # rows (OauthSessionPersistence reuses an expired, unrevoked device
+        # session and bumps expires_at) or issued it a refresh token since the
+        # batch was read. SKIP LOCKED leaves a row another transaction holds for
+        # the next run. (SQLite ignores the lock clause; it serialises writers.)
+        ids = StandardId::Session
+          .where(id: candidate_ids)
+          .where("expires_at < ?", cutoff)
+          .where.not(id: live_refresh_tokens.select(:session_id))
+          .lock("FOR UPDATE SKIP LOCKED")
+          .pluck(:id)
+        next 0 if ids.empty?
+
+        StandardId::RefreshToken.where(session_id: ids).update_all(session_id: nil)
+        StandardId::Session.where(id: ids).delete_all
+      end
+    end
+
+    def live_refresh_tokens
+      StandardId::RefreshToken.active.where.not(session_id: nil)
+    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/standard_id/events/subscribers/passwordless_delivery_subscriber.rb

@@ -1,31 +1,56 @@
 module StandardId
   module Events
     module Subscribers
+      # Built-in OTP email delivery (`c.passwordless.delivery = :built_in`).
+      #
+      # Sign-in codes (realm "authentication") get PasswordlessMailer#otp_email;
+      # every other realm — WebEngine email verification, Otp.issue step-up /
+      # contact verification — gets #verification_email, so a verification code
+      # never arrives as "your sign-in code". There is no built-in SMS delivery.
+      #
+      # On a successful enqueue it marks the code challenge
+      # (CodeChallenge#built_in_delivered), which is how the strategy knows to
+      # report PASSWORDLESS_CODE_SENT as "sent" rather than "failed".
       class PasswordlessDeliverySubscriber < Base
         subscribe_to StandardId::Events::PASSWORDLESS_CODE_GENERATED
 
+        # Whether the built-in mailer is responsible for delivering this
+        # PASSWORDLESS_CODE_GENERATED payload.
+        #
+        # @param payload [Hash] event payload (symbol or string keys)
+        # @return [Boolean]
+        def self.handles?(payload)
+          payload = payload.with_indifferent_access
+          # Per-call manual delivery (Otp.issue(delivery: :manual)) and
+          # Otp.issue(delivery: :custom) leave delivery to the caller / host
+          # subscriber, even when the engine mailer is the global default.
+          return false if payload[:skip_sender]
+          return false if payload[:delivery]&.to_sym == :custom
+
+          StandardId.config.passwordless.delivery == :built_in && payload[:channel].to_s == "email"
+        end
+
         def call(event)
-          # Per-call manual-delivery request takes precedence over the global
-          # delivery config. Honors Otp.issue(delivery: :manual) callers who
-          # deliver the code themselves (custom widget flows, step-up
-          # challenges, etc.) and would otherwise receive a duplicate email
-          # from this subscriber when c.passwordless.delivery == :built_in.
-          return if event[:skip_sender]
-          # Otp.issue(delivery: :custom): the host's own subscriber delivers
-          # this code, even where the engine mailer is the global default.
-          return if event[:delivery]&.to_sym == :custom
-          return unless built_in_delivery?
-          return unless event[:channel] == "email"
+          return unless self.class.handles?(event.payload)
 
           identifier = event[:identifier]
-          code = event[:code_challenge]&.code
+          challenge = event[:code_challenge]
+          code = challenge&.code
 
           return if identifier.blank? || code.blank?
 
-          StandardId::PasswordlessMailer.with(
+          enqueued = StandardId::PasswordlessMailer.with(
             email: identifier,
-            otp_code: code
-          ).otp_email.deliver_later
+            otp_code: code,
+            realm: event[:realm],
+            expires_in_minutes: expires_in_minutes(event[:expires_at])
+          ).public_send(mailer_action(event[:realm])).deliver_later
+
+          # deliver_later returns false (without raising) when Active Job
+          # refuses the enqueue, e.g. an aborting before_enqueue callback.
+          if enqueued && challenge.respond_to?(:built_in_delivered=)
+            challenge.built_in_delivered = true
+          end
         end
 
         def handle_error(error, event)
@@ -37,8 +62,17 @@ module StandardId
 
         private
 
-        def built_in_delivery?
-          StandardId.config.passwordless.delivery == :built_in
+        def mailer_action(realm)
+          realm.blank? || realm.to_s == StandardId::Passwordless::DEFAULT_REALM ? :otp_email : :verification_email
+        end
+
+        def expires_in_minutes(expires_at)
+          return nil if expires_at.blank?
+
+          expires_at = Time.zone.parse(expires_at) if expires_at.is_a?(String)
+          [((expires_at - Time.current) / 60.0).ceil, 1].max
+        rescue ArgumentError, TypeError, NoMethodError
+          nil
         end
       end
     end

data/lib/standard_id/passwordless/base_strategy.rb

@@ -45,8 +45,8 @@ module StandardId
         # can honor a per-call manual-delivery request. Without this,
         # Otp.issue(delivery: :manual) silently double-delivers when
         # c.passwordless.delivery == :built_in.
-        emit_code_generated(challenge, username, skip_sender: skip_sender, delivery: delivery)
-        emit_code_sent(username) unless skip_sender
+        generated_payload = emit_code_generated(challenge, username, skip_sender: skip_sender, delivery: delivery)
+        emit_code_sent(username, delivery_status: delivery_status_for(challenge, generated_payload)) unless skip_sender
         challenge
       end
 
@@ -190,9 +190,9 @@ module StandardId
         )
       end
 
+      # @return [Hash] the published payload (used to decide the delivery status)
       def emit_code_generated(challenge, username, skip_sender: false, delivery: nil)
-        StandardId::Events.publish(
-          StandardId::Events::PASSWORDLESS_CODE_GENERATED,
+        payload = {
           code_challenge: challenge,
           identifier: username,
           channel: connection_type,
@@ -200,16 +200,31 @@ module StandardId
           expires_at: challenge.expires_at,
           skip_sender: skip_sender,
           delivery: delivery
-        )
+        }
+        StandardId::Events.publish(StandardId::Events::PASSWORDLESS_CODE_GENERATED, payload)
+        payload
+      end
+
+      # delivery_status of PASSWORDLESS_CODE_SENT:
+      # - "sent"      — the built-in mailer (delivery :built_in) enqueued the email.
+      # - "failed"    — the built-in mailer was responsible but did not enqueue
+      #                 it (its error was logged by the subscriber).
+      # - "delegated" — delivery belongs to the host's PASSWORDLESS_CODE_GENERATED
+      #                 subscriber (delivery :custom, or SMS); the engine cannot
+      #                 know whether it sent anything.
+      def delivery_status_for(challenge, generated_payload)
+        return "delegated" unless StandardId::Events::Subscribers::PasswordlessDeliverySubscriber.handles?(generated_payload)
+
+        challenge.built_in_delivered ? "sent" : "failed"
       end
 
-      def emit_code_sent(username)
+      def emit_code_sent(username, delivery_status:)
         StandardId::Events.publish(
           StandardId::Events::PASSWORDLESS_CODE_SENT,
           identifier: username,
           channel: connection_type,
           realm: @realm,
-          delivery_status: "sent"
+          delivery_status: delivery_status
         )
       end
     end

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.43.0"
+  VERSION = "0.43.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.43.0
+  version: 0.43.2
 platform: ruby
 authors:
 - Jaryl Sim
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: bcrypt
   requirement: !ruby/object:Gem::Requirement
@@ -200,6 +200,8 @@ files:
 - app/views/standard_id/password_reset_mailer/reset_email.text.erb
 - app/views/standard_id/passwordless_mailer/otp_email.html.erb
 - app/views/standard_id/passwordless_mailer/otp_email.text.erb
+- app/views/standard_id/passwordless_mailer/verification_email.html.erb
+- app/views/standard_id/passwordless_mailer/verification_email.text.erb
 - app/views/standard_id/web/account/edit.html.erb
 - app/views/standard_id/web/account/show.html.erb
 - app/views/standard_id/web/auth/callback/providers/mobile_callback.html.erb
@@ -214,6 +216,7 @@ files:
 - app/views/standard_id/web/signup/show.html.erb
 - config/brakeman.ignore
 - config/initializers/generators.rb
+- config/locales/en.yml
 - config/routes/api.rb
 - config/routes/web.rb
 - db/migrate/20250830000000_create_standard_id_client_applications.rb
@@ -342,7 +345,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A comprehensive authentication engine for Rails, built on the security primitives
   introduced in Rails 8.