standard_id 0.52.0 → 0.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d91a49478fd5f477e7a20395c4c2f5b142b3bd813e96145af349143935a96482
-  data.tar.gz: 00d708402823a344e451032db69e6097c62ecc77d80ce66d4d1d68b24fed478a
+  metadata.gz: de8ced4a8e48a3b14437ece4082079510d1f7466737be90f3dffe3ac3959d56c
+  data.tar.gz: af90eba1873dd457c207ce3151d75215cf5de2e8a5cb37d42ab32a1227fb5017
 SHA512:
-  metadata.gz: 101b91f61aa5d72e333322c21c0fbe160105a9adda2bc851046ea625400e4fcda61cbc6131fdcefd8f6c7927f54f1308834be383e2d4fec1d83110276a3b9087
-  data.tar.gz: 853ef8ee5ea04b8feb98c1343025b692c8c41d9a597c3e2ae82bf31c32e16f03d810375849d0d04e5412ff96966643bdaf8529fdddeb3f30cca7f73d32edb282
+  metadata.gz: d5bb7b2e920c26ae28e3b8ddd09ea4c475bb8b0562b89f057adf9573737fc225c43470faf94e202545d3840a4ab2b41e6abc8b17836fd8272a6b17711e47d5f6
+  data.tar.gz: b64139dbd6641e978e75d4dec5f89a14891b603755edf6e67e2a566c5ace604d678aaeb4f75a6e924f1da2d04fdd5af3de8b0f005c05c344486aa2796d45b096

data/CHANGELOG.md

@@ -7,6 +7,62 @@ 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
+
+- **`StandardId::Testing::RequestHelpers#sign_in_as(account, scope: nil)`.** Signs an
+  account in for the following requests in a request spec: it creates a real
+  `BrowserSession` and writes the encrypted `session_token` cookie a real sign-in
+  writes, built with the host's own cookie jar, so no test-only route is added to
+  the app. `scope:` also writes `standard_id_scopes` into the Rails session cookie
+  (cookie session store only; any other store raises `ArgumentError`, before
+  anything is created). Like a real sign-in it always replaces the Rails session
+  cookie, so a later `sign_in_as` never inherits an earlier one's scopes or any
+  other session data (flash, CSRF token). Replaces per-app controller
+  stubs and `/test/set-session` routes.
+- **`RequestHelpers#bearer_headers_for(account, **jwt_options)`:** `build_jwt` plus
+  `bearer_auth_header` in one call.
+
+### Changed
+
+- **"Production" follows `APP_ENVIRONMENT`, failing closed.** The new
+  `StandardId::AppEnvironment.production?` decides every production check in the
+  gem: the bypass-code guard (when `passwordless.production_env_detector` is
+  unset), the provider-misconfiguration `:raise` mode, and the empty
+  `allowed_audiences` boot warning. It reads `APP_ENVIRONMENT` when set (only
+  `staging`, `preview`, `development` and `test` are non-production; any other
+  value is production), else `Rails.env.production?`. A staging box with
+  `RAILS_ENV=production` and `APP_ENVIRONMENT=staging` is therefore no longer
+  treated as production, and `-> { AppEnv.production? }` detectors can be
+  deleted. Same convention as standard_audit, standard_health and
+  standard_singpass.
+- **`rails g standard_id:install` writes a minimal initializer.** It holds only
+  `account_class_name`, plus commented `issuer` and `c.preset :inertia_web` lines,
+  instead of several hundred lines of commented defaults that apps then kept
+  verbatim. `--with-reference` writes
+  the annotated initializer as before. Existing initializers are not touched.
+
 ## [0.52.0] - 2026-10-22
 
 ### Added
@@ -14,10 +70,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`c.preset :inertia_web`.** Applies the settings an Inertia app with
   passwordless or social sign-in flips: `use_inertia` and `alias_current_user`
   true; `web.signup`, `web.password_login` and `web.password_reset` false;
-  `oauth.discovery_endpoint_base = :request`. Four of the five estate apps set
-  exactly this by hand. A preset fills only settings the host has not assigned
-  (via `Scope#assigned?`), so explicit assignments win in either order; an
-  unknown name raises `ArgumentError`. The public defaults are unchanged.
+  `oauth.discovery_endpoint_base = :request`. Each setting is hand-set in four
+  of the five estate apps, though the full bundle matches only two of them. A
+  preset fills only settings the host has not assigned (via
+  `Scope#assigned?`), so explicit assignments win in either order; an unknown
+  name raises `ArgumentError`. The public defaults are unchanged.
   Presets live in `StandardId::Config::Presets`.
 
 ## [0.51.2] - 2026-10-21

data/README.md

@@ -63,6 +63,13 @@ $ bundle install
 rails generate standard_id:install
 ```
 
+This writes a short `config/initializers/standard_id.rb` holding only what an
+app must decide (`account_class_name`, plus commented `issuer` and
+`c.preset :inertia_web` lines). Add a setting only when you change it from the
+default. `--with-reference` writes the annotated initializer instead, with every
+commonly changed setting and its default commented out; it is a reference to
+read, not a file to keep whole.
+
 ### 2. Configure Your Account Model
 
 ```ruby
@@ -810,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
@@ -821,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.
@@ -869,15 +909,19 @@ end
 
 **Bypass code (E2E testing).** When `StandardId.config.passwordless.bypass_code` is set (and the deploy is not production), `Otp.verify` accepts the bypass code for **any realm**. This replaces per-app bypass ENV checks and works consistently across `Otp.verify` and the built-in passwordless login flow. Never set `bypass_code` in production — it will raise if you try.
 
-By default "production" means `Rails.env.production?`. Apps that distinguish a physical deploy environment from `RAILS_ENV` (e.g. a staging box that still runs `RAILS_ENV=production`) can override the decision with a callable:
+"Production" is decided by `StandardId::AppEnvironment`, the same rule every
+check in the gem uses: `APP_ENVIRONMENT` when it is set, where only `staging`,
+`preview`, `development` and `test` count as non-production (any other value,
+including a typo, is production), else `Rails.env.production?`. So a staging box
+running `RAILS_ENV=production` with `APP_ENVIRONMENT=staging` is not
+production, and needs no extra wiring:
 
 ```ruby
-# Allow the bypass code on a physically-staging box, still refused on real prod.
-c.passwordless.production_env_detector = -> { AppEnv.production? }
-c.passwordless.bypass_code = ENV["STANDARD_ID_BYPASS_CODE"] unless AppEnv.production?
+c.passwordless.bypass_code = ENV["STANDARD_ID_BYPASS_CODE"] unless StandardId::AppEnvironment.production?
 ```
 
-`production_env_detector` takes no arguments and returns a boolean; when `nil` (the default) the gem falls back to `Rails.env.production?`, so existing consumers are unaffected.
+`production_env_detector` (a callable taking no arguments, returning a boolean)
+still overrides that, for an app with a different discriminator.
 
 **Back-compat.** The existing passwordless authentication flow continues to work unchanged. `Otp.issue`/`Otp.verify` are a new addition — you can migrate direct `CodeChallenge.create!` calls at your own pace.
 
@@ -1943,6 +1987,38 @@ Notes:
 
 ## Testing
 
+### Signing in from your app's request specs
+
+```ruby
+# spec/rails_helper.rb
+require "standard_id/testing"
+
+RSpec.configure do |config|
+  config.include StandardId::Testing::RequestHelpers, type: :request
+end
+```
+
+```ruby
+sign_in_as(account)                    # a real BrowserSession, via the session_token cookie
+sign_in_as(account, scope: :platform)  # also grants standard_id_scopes (current_scope_names)
+get "/dashboard"
+
+get "/api/orders", headers: bearer_headers_for(account, scope: "orders.read")
+```
+
+`sign_in_as` creates a real `BrowserSession` and writes the same encrypted
+`session_token` cookie a real sign-in writes, so `current_account`,
+`require_browser_session!`, expiry and revocation behave exactly as in
+production. It adds nothing to your app: the cookies are built with your app's
+own encrypted cookie jar, so there is no test-only route. `scope:` writes the
+Rails session cookie and so needs the cookie session store (the Rails default);
+with another store it raises `ArgumentError`, and you sign in through your own
+scoped login request instead. It replaces controller stubbing
+(`stub_web_authentication`, `allow_any_instance_of(...).to receive(:current_user)`)
+and per-app `/test/set-session` routes.
+
+### This gem's own suite
+
 StandardId includes comprehensive test coverage:
 
 ```bash

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/install_generator.rb

@@ -28,6 +28,8 @@ module StandardId
 
       class_option :skip_initializer, type: :boolean, default: false,
         desc: "Do not write config/initializers/standard_id.rb"
+      class_option :with_reference, type: :boolean, default: false,
+        desc: "Write the annotated initializer (every common setting with its default) instead of the minimal one"
       class_option :skip_routes, type: :boolean, default: false,
         desc: "Do not append engine mount lines to config/routes.rb"
       class_option :skip_migrations, type: :boolean, default: false,
@@ -51,7 +53,8 @@ module StandardId
       def create_initializer_file
         return say_status("skip", "config/initializers/standard_id.rb (--skip-initializer)", :yellow) if options[:skip_initializer]
 
-        template "standard_id.rb", "config/initializers/standard_id.rb"
+        source = options[:with_reference] ? "standard_id_reference.rb" : "standard_id.rb"
+        template source, "config/initializers/standard_id.rb"
       end
 
       def mount_engines