standard_id 0.53.0 → 0.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1aa1e111cbaf2abc19d4b43e57a7c276054bf0522418c7303f855659cb3c259f
-  data.tar.gz: 583e0568a53fbf9880c11cd0fbf4e17ae2b98d73b52b2db2725ed5dbe4a5dab0
+  metadata.gz: de8ced4a8e48a3b14437ece4082079510d1f7466737be90f3dffe3ac3959d56c
+  data.tar.gz: af90eba1873dd457c207ce3151d75215cf5de2e8a5cb37d42ab32a1227fb5017
 SHA512:
-  metadata.gz: d5410924e96b90aca074e3a322cfa7e59fc54c5412e41927157b19f03c723355724295a67cc9ddb3dec70ca38e548c1bf8062431a46859c6ab153c6416f3b9e6
-  data.tar.gz: 3216249e86cd957cc0196518374b2b21073ef03f3f134988f97bedc064ecbbbd9e10a7be88a48606ae7502c9b1dcdecbd8fdd606bea9aa81b361269e2cc9cbbc
+  metadata.gz: d5bb7b2e920c26ae28e3b8ddd09ea4c475bb8b0562b89f057adf9573737fc225c43470faf94e202545d3840a4ab2b41e6abc8b17836fd8272a6b17711e47d5f6
+  data.tar.gz: b64139dbd6641e978e75d4dec5f89a14891b603755edf6e67e2a566c5ace604d678aaeb4f75a6e924f1da2d04fdd5af3de8b0f005c05c344486aa2796d45b096

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.54.0] - 2026-10-22
+
+### Added
+
+- **`PasswordlessFlow#start_passwordless_login(username:, connection:, return_to:)`.**
+  Sends the code and stores the signed hand-off the WebEngine's `login_verify` page
+  requires, so a host controller (a sign-up or invite form) can start a passwordless
+  login and redirect to `standard_id_web.login_verify_path` without copying the
+  gem's `message_verifier(:otp)` / `session[:standard_id_otp_payload]` internals.
+  Nothing is stored when the code cannot be sent. The gem's own login controllers
+  now use the same code. (rarebit-one/rarebit-sre#479)
+- **`c.mailer_parent_class`** (default `"ActionMailer::Base"`). The class
+  StandardId's mailers inherit from; set it to `"ApplicationMailer"` so built-in OTP
+  and password-reset mail uses the host's layout, helpers, `default_url_options`
+  and locale handling. With a host parent the gem no longer sets its placeholder
+  `default from:` or `layout "mailer"`, so the parent's apply. A value that is
+  not an `ActionMailer::Base` subclass raises `StandardId::ConfigurationError`
+  naming the setting.
+  (rarebit-one/rarebit-sre#479)
+
 ## [0.53.0] - 2026-10-22
 
 ### Added

data/README.md

@@ -817,6 +817,14 @@ 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.
 
+The built-in mailers inherit from `ActionMailer::Base`. Set
+`c.mailer_parent_class = "ApplicationMailer"` to have them inherit your mailer
+base instead, with its layout, helpers, `default_url_options` and locale
+handling. It is read when the gem's mailers load, so set it in an initializer.
+The sender still comes from `c.passwordless.mailer_from` and
+`c.reset_password.mailer_from`, which every gem message passes explicitly, so a
+parent's `default from:` does not apply to them.
+
 Event payload includes:
 - `channel` - `"email"` or `"sms"`
 - `identifier` - The email address or phone number
@@ -828,6 +836,31 @@ Event payload includes:
 
 > **Note**: `passwordless_email_sender` / `passwordless_sms_sender` were removed in 0.43; see the [Migration Guide](docs/MIGRATION_GUIDE.md).
 
+### Starting a passwordless login from your own controller
+
+To send the code from your own controller (a sign-up form, an invite page) and
+let the WebEngine's verify page finish the sign-in, include
+`StandardId::PasswordlessFlow` and call `start_passwordless_login`. It sends the
+code and stores the signed hand-off the verify page requires, then you redirect
+there through the engine's mounted helper, which includes the mount path:
+
+```ruby
+class Onboarding::SignupsController < ApplicationController
+  include StandardId::PasswordlessFlow
+
+  def create
+    start_passwordless_login(username: params[:email], return_to: welcome_path)
+    redirect_to standard_id_web.login_verify_path, status: :see_other
+  rescue StandardId::InvalidRequestError => e
+    redirect_to new_signup_path, alert: e.message
+  end
+end
+```
+
+`connection:` defaults to `c.passwordless.connection`. `return_to:` becomes the
+post-sign-in destination, still subject to the verify page's safe-redirect check.
+Nothing is stored when the code cannot be sent.
+
 ### Using OTP for non-authentication flows
 
 The same hardened OTP machinery (enumeration defense, atomic attempt tracking, pessimistic locking, bypass_code hook) is exposed as a public primitive via `StandardId::Otp`. Use it when you need one-time codes for purposes *other* than authentication — contact verification widgets, step-up challenges, custom confirmation flows, etc.

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

@@ -6,7 +6,8 @@ module StandardId
   #
   # Requires the including controller to have access to `request` (standard in
   # all Rails controllers). No other dependencies are needed -- both
-  # `generate_passwordless_otp` and `verify_passwordless_otp` only use `request`.
+  # `generate_passwordless_otp` and `verify_passwordless_otp` only use `request`;
+  # `start_passwordless_login` also writes to `session`.
   #
   # @example Usage in a host app controller
   #   class Auth::LoginController < ApplicationController
@@ -29,13 +30,76 @@ module StandardId
   #       end
   #     end
   #   end
+  #
+  # @example Hand off to the WebEngine's verify page (no custom verify action)
+  #   class Onboarding::SignupsController < ApplicationController
+  #     include StandardId::PasswordlessFlow
+  #
+  #     def create
+  #       start_passwordless_login(username: params[:email], return_to: welcome_path)
+  #       redirect_to standard_id_web.login_verify_path, status: :see_other
+  #     rescue StandardId::InvalidRequestError => e
+  #       redirect_to new_signup_path, alert: e.message
+  #     end
+  #   end
   module PasswordlessFlow
     extend ActiveSupport::Concern
 
     include StandardId::PasswordlessStrategy
 
+    # Session key for the signed hand-off the WebEngine's login_verify page reads.
+    OTP_PAYLOAD_SESSION_KEY = :standard_id_otp_payload
+
     private
 
+    # Start a passwordless login that the WebEngine's login_verify page finishes.
+    #
+    # Sends the code (as `generate_passwordless_otp`), then stores the signed
+    # hand-off that login_verify requires, valid for `passwordless.code_ttl`.
+    # The caller redirects to that page itself, through the engine's mounted
+    # helper so the mount path is included (e.g. `standard_id_web.login_verify_path`).
+    #
+    # Nothing is stored when sending fails, so the verify page is never reachable
+    # for a code that was not sent.
+    #
+    # @param username [String] the recipient's email address or phone number
+    # @param connection [String] the delivery channel, defaults to `passwordless.connection`
+    # @param return_to [String, nil] where to send the account after it verifies;
+    #   the verify page still checks it is a safe destination. Non-String values are ignored.
+    # @return [StandardId::CodeChallenge] the created code challenge
+    # @raise [StandardId::InvalidRequestError] when the username format is invalid
+    #   or the connection type is unsupported
+    def start_passwordless_login(username:, connection: StandardId.config.passwordless.connection, return_to: nil)
+      challenge = generate_passwordless_otp(username: username, connection: connection)
+      store_passwordless_handoff(username: username, connection: connection)
+      session[:return_to_after_authenticating] = return_to if return_to.is_a?(String) && return_to.present?
+      challenge
+    end
+
+    def store_passwordless_handoff(username:, connection:)
+      session[OTP_PAYLOAD_SESSION_KEY] = Rails.application.message_verifier(:otp).generate(
+        { username: username, connection: connection },
+        expires_in: StandardId.config.passwordless.code_ttl.seconds
+      )
+    end
+
+    # The stored hand-off as `{ username:, connection: }`, or nil when there is
+    # none. A tampered or expired hand-off is deleted and raises
+    # ActiveSupport::MessageVerifier::InvalidSignature.
+    def read_passwordless_handoff
+      signed_payload = session[OTP_PAYLOAD_SESSION_KEY]
+      return if signed_payload.blank?
+
+      Rails.application.message_verifier(:otp).verify(signed_payload).symbolize_keys
+    rescue ActiveSupport::MessageVerifier::InvalidSignature
+      clear_passwordless_handoff
+      raise
+    end
+
+    def clear_passwordless_handoff
+      session.delete(OTP_PAYLOAD_SESSION_KEY)
+    end
+
     # Generate a passwordless OTP code and send it to the user.
     #
     # Delegates to the appropriate strategy (EmailStrategy or SmsStrategy)

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

@@ -100,25 +100,16 @@ module StandardId
         end
 
         begin
-          generate_passwordless_otp(username: username, connection: connection)
+          # string_param rejects Array/Hash-shaped redirect_uri values (see
+          # BaseController#string_param); start_passwordless_login also ignores
+          # non-Strings, since login_verify passes the stored value to redirect_to.
+          start_passwordless_login(username: username, connection: connection, return_to: string_param(:redirect_uri))
         rescue StandardId::InvalidRequestError => e
           flash.now[:alert] = e.message
           render_with_inertia action: :show, props: auth_page_props(passwordless_enabled: passwordless_enabled?), status: :unprocessable_content
           return
         end
 
-        code_ttl = StandardId.config.passwordless.code_ttl
-        signed_payload = Rails.application.message_verifier(:otp).generate(
-          { username: username, connection: connection },
-          expires_in: code_ttl.seconds
-        )
-        session[:standard_id_otp_payload] = signed_payload
-        # Use string_param to reject Array/Hash-shaped values — login_verify_controller
-        # consumes this via after_authentication_url and passes it to redirect_to;
-        # storing a non-String here would crash that flow with ArgumentError.
-        redirect_uri = string_param(:redirect_uri)
-        session[:return_to_after_authenticating] = redirect_uri if redirect_uri
-
         redirect_to engine_path(login_verify_path), status: :see_other
       end
 

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

@@ -75,7 +75,7 @@ module StandardId
         }
         redirect_override = invoke_after_sign_in(account, context)
 
-        session.delete(:standard_id_otp_payload)
+        clear_passwordless_handoff
 
         # after_authentication_url returns whatever was stashed in
         # session[:return_to_after_authenticating] — which could be an attacker-controlled
@@ -85,7 +85,7 @@ module StandardId
         destination = redirect_override || (safe_destination?(fallback) ? fallback : safe_post_signin_default)
         redirect_after_authentication destination, notice: "Successfully signed in"
       rescue StandardId::AuthenticationDenied => e
-        session.delete(:standard_id_otp_payload)
+        clear_passwordless_handoff
         handle_authentication_denied(e, account: account, newly_created: newly_created)
       end
 
@@ -96,19 +96,10 @@ module StandardId
       end
 
       def require_otp_payload!
-        signed_payload = session[:standard_id_otp_payload]
-
-        if signed_payload.blank?
-          redirect_to engine_path(login_path), alert: "Please start the login process"
-          return
-        end
-
-        begin
-          @otp_data = Rails.application.message_verifier(:otp).verify(signed_payload).symbolize_keys
-        rescue ActiveSupport::MessageVerifier::InvalidSignature
-          session.delete(:standard_id_otp_payload)
-          redirect_to engine_path(login_path), alert: "Your verification session has expired. Please try again."
-        end
+        @otp_data = read_passwordless_handoff
+        redirect_to engine_path(login_path), alert: "Please start the login process" if @otp_data.nil?
+      rescue ActiveSupport::MessageVerifier::InvalidSignature
+        redirect_to engine_path(login_path), alert: "Your verification session has expired. Please try again."
       end
 
       # Global web.passwordless_registration AND the active scope's

data/app/mailers/standard_id/application_mailer.rb

@@ -1,11 +1,18 @@
 module StandardId
-  class ApplicationMailer < ActionMailer::Base
+  # Inherits from `StandardId.config.mailer_parent_class` (ActionMailer::Base by
+  # default). The class is resolved when this file loads, which is after the
+  # host's initializers have run.
+  class ApplicationMailer < StandardId.mailer_parent_class
     # Use a delivery job that doesn't log its arguments — the gem's mailers pass
     # sensitive params (OTP code, password-reset token) that ActiveJob would
     # otherwise print in plaintext. Applies to all StandardId mailers.
     self.delivery_job = StandardId::SecureMailDeliveryJob
 
-    default from: "from@example.com"
-    layout "mailer"
+    # A host parent brings its own defaults and layout; keep the gem's only on
+    # the bare ActionMailer::Base.
+    if superclass == ActionMailer::Base
+      default from: "from@example.com"
+      layout "mailer"
+    end
   end
 end

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

@@ -108,6 +108,11 @@ StandardId.configure do |c|
   # Default: nil (StandardId's packaged layout)
   # c.web_layout = "application"
 
+  # The class StandardId's mailers inherit from. Set it to your own mailer base
+  # so OTP and password-reset mail picks up your layout, helpers and locale.
+  # Default: "ActionMailer::Base"
+  # c.mailer_parent_class = "ApplicationMailer"
+
   # Expose current_account as current_user (useful for ActionPolicy / Pundit).
   # Default: false
   # c.alias_current_user = true

data/lib/standard_id/config/schema.rb

@@ -9,6 +9,11 @@ StandardId::ConfigSchema.define do
     field :cache_store, type: :any, default: nil
     field :logger, type: :any, default: nil
     field :web_layout, type: :string, default: nil
+    # The class StandardId's mailers inherit from, e.g. "ApplicationMailer" so
+    # they pick up the host's layout, helpers, default_url_options and locale
+    # handling. Read once, when the gem's mailers load, so set it in an
+    # initializer.
+    field :mailer_parent_class, type: :string, default: "ActionMailer::Base"
     # Removed in 0.43 (deprecated since 0.1.7): assigning either raises
     # StandardId::ConfigurationError with this hint.
     removed :passwordless_email_sender,

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.53.0"
+  VERSION = "0.54.0"
 end

data/lib/standard_id.rb

@@ -116,6 +116,21 @@ module StandardId
       config.account_class_name.constantize
     end
 
+    # The class StandardId::ApplicationMailer inherits from
+    # (`c.mailer_parent_class`); it must be an ActionMailer::Base subclass,
+    # anything else raises ConfigurationError. safe_constantize returns nil only when the
+    # name itself is undefined; an error raised while loading that class (a
+    # typo inside the host's mailer) still propagates as itself.
+    def mailer_parent_class
+      name = config.mailer_parent_class
+      parent = name.to_s.safe_constantize
+      return parent if parent.is_a?(Class) && parent <= ActionMailer::Base
+
+      raise ConfigurationError,
+        "c.mailer_parent_class = #{name.inspect} does not name an ActionMailer::Base subclass. " \
+        "Set it to your mailer base, e.g. \"ApplicationMailer\", or leave it unset for ActionMailer::Base."
+    end
+
     def scope_for(name)
       return nil if config.scopes.blank? || name.blank?
       scope_hash = config.scopes[name.to_sym]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.53.0
+  version: 0.54.0
 platform: ruby
 authors:
 - Jaryl Sim