standard_id 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c621a201633467c0738625eacb1f0c59c0b8ee5b670903cb09b1a1a4f6bfd01
-  data.tar.gz: 2b4b97e69b5b8dba07f1df919fd3d3b5ef4dda4fa6b72ae54c317cfb96bb1320
+  metadata.gz: 7ad192cf3b1bad92d1ec8322e203804401d8c10e54ebfcde4340f7840fa624bd
+  data.tar.gz: 0eb0cc7c613bd3fdd981818c6d4fd359f809003da34d6e15f5e2fea9fd0eab74
 SHA512:
-  metadata.gz: 22613e053bfa27512b39c38af4be699686ed8ef83b296efbbd17b131e60f12923fc6efdb8b572833849807c3928fb8cecbaee4d72e1e6da60e0b37b606555a3b
-  data.tar.gz: 36e22ae1dca29a4350350c079eb7f1b4166c341f3d435bcdd666d7603b8f479de0dbee957b75fd807a42f7deeaf272d69badf6fe61d978151dcebb1f48c92401
+  metadata.gz: 478082fd5a80a66ded10834c7bd1db32912a222086f5fc8db521a90acceb1459418492581d89ca90d5a7d8fb438b3c74845372fe551d52eb892c297136acc002
+  data.tar.gz: bca63014a4ca013f152bb5bd9112f3649d0e7848d22b7d1114e9bd2715e2847369610e735b83f20bda3aad3fca45936d0f7452438f2a8144d24ddba7b3cb2c07

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

@@ -57,7 +57,8 @@ module StandardId
         password_reset: web.password_reset,
         email_verification: web.email_verification,
         phone_verification: web.phone_verification,
-        sessions_management: web.sessions_management
+        sessions_management: web.sessions_management,
+        passwordless_registration: web.passwordless_registration
       }
     end
   end

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

@@ -0,0 +1,27 @@
+module StandardId
+  module RateLimitHandling
+    extend ActiveSupport::Concern
+
+    RATE_LIMIT_STORE = StandardId::RateLimitStore.new
+
+    included do
+      rescue_from ActionController::TooManyRequests, with: :handle_rate_limited
+    end
+
+    private
+
+    def handle_rate_limited(_exception)
+      response.set_header("Retry-After", 15.minutes.to_i.to_s)
+
+      if self.class.ancestors.include?(ActionController::API)
+        render json: {
+          error: "rate_limit_exceeded",
+          error_description: "Too many requests. Please try again later."
+        }, status: :too_many_requests
+      else
+        flash[:alert] = "Too many requests. Please try again later."
+        redirect_to request.referer || main_app.root_path, status: :see_other
+      end
+    end
+  end
+end

data/app/controllers/standard_id/api/base_controller.rb

@@ -1,9 +1,11 @@
 module StandardId
   module Api
     class BaseController < ActionController::API
+      include ActionController::RateLimiting
       include StandardId::ControllerPolicy
       include StandardId::ApiAuthentication
       include StandardId::SetCurrentRequestDetails
+      include StandardId::RateLimitHandling
 
       before_action -> { Current.scope = :api if defined?(::Current) }
       before_action :validate_content_type!

data/app/controllers/standard_id/api/oauth/tokens_controller.rb

@@ -6,6 +6,12 @@ module StandardId
 
         skip_before_action :validate_content_type!
 
+        # RAR-51/RAR-60: Rate limit token requests by IP (30 per 15 minutes)
+        rate_limit to: StandardId.config.rate_limits.api_token_per_ip,
+                   within: 15.minutes,
+                   only: :create,
+                   store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
         FLOW_STRATEGIES = {
           "client_credentials" => StandardId::Oauth::ClientCredentialsFlow,
           "authorization_code" => StandardId::Oauth::AuthorizationCodeFlow,

data/app/controllers/standard_id/api/passwordless_controller.rb

@@ -5,6 +5,21 @@ module StandardId
 
       include StandardId::PasswordlessStrategy
 
+      # RAR-60: Rate limit OTP initiation by IP (10 per hour)
+      rate_limit to: StandardId.config.rate_limits.api_passwordless_start_per_ip,
+                 within: 1.hour,
+                 name: "passwordless-ip",
+                 only: :start,
+                 store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
+      # RAR-60: Rate limit OTP initiation by target (5 per 15 minutes)
+      rate_limit to: StandardId.config.rate_limits.api_passwordless_start_per_target,
+                 within: 15.minutes,
+                 by: -> { "api-passwordless:#{(params[:username] || params[:email] || params[:phone_number]).to_s.strip.downcase}" },
+                 name: "passwordless-target",
+                 only: :start,
+                 store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
       def start
         raise StandardId::InvalidRequestError, "username, email, or phone_number parameter is required" if start_params[:username].blank?
 

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

@@ -5,6 +5,7 @@ module StandardId
       include StandardId::WebAuthentication
       include StandardId::SetCurrentRequestDetails
       include StandardId::WebMechanismGate
+      include StandardId::RateLimitHandling
 
       include StandardId::WebEngine.routes.url_helpers
       helper StandardId::WebEngine.routes.url_helpers

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

@@ -10,6 +10,21 @@ module StandardId
 
       layout "public"
 
+      # RAR-51: Rate limit login attempts by IP (20 per 15 minutes)
+      rate_limit to: StandardId.config.rate_limits.password_login_per_ip,
+                 within: 15.minutes,
+                 name: "login-ip",
+                 only: :create,
+                 store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
+      # RAR-51: Rate limit login attempts by email target (5 per 15 minutes)
+      rate_limit to: StandardId.config.rate_limits.password_login_per_email,
+                 within: 15.minutes,
+                 by: -> { "login-email:#{params.dig(:login, :email).to_s.strip.downcase}" },
+                 name: "login-email",
+                 only: :create,
+                 store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
       skip_before_action :require_browser_session!, only: [:show, :create]
 
       before_action :redirect_if_authenticated, only: [:show]

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

@@ -9,6 +9,13 @@ module StandardId
 
       layout "public"
 
+      # RAR-60: Rate limit OTP verification attempts by IP (20 per 15 minutes)
+      rate_limit to: StandardId.config.rate_limits.otp_verify_per_ip,
+                 within: 15.minutes,
+                 name: "otp-verify-ip",
+                 only: :update,
+                 store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
       skip_before_action :require_browser_session!, only: [:show, :update]
       before_action :redirect_if_authenticated, only: [:show]
       before_action :require_otp_payload!
@@ -26,11 +33,12 @@ module StandardId
           return
         end
 
-        result = StandardId::Passwordless::VerificationService.verify(
-          connection: @otp_data[:connection],
+        result = StandardId::Passwordless.verify(
           username: @otp_data[:username],
           code: code,
-          request: request
+          connection: @otp_data[:connection],
+          request: request,
+          allow_registration: passwordless_registration_enabled?
         )
 
         unless result.success?
@@ -45,7 +53,10 @@ module StandardId
         session_manager.sign_in_account(account)
         emit_authentication_succeeded(account)
 
-        invoke_after_account_created(account, { mechanism: "passwordless", provider: nil }) if newly_created
+        if newly_created
+          emit_passwordless_account_created(account)
+          invoke_after_account_created(account, { mechanism: "passwordless", provider: nil })
+        end
 
         context = { connection: @otp_data[:connection], provider: nil }
         redirect_override = invoke_after_sign_in(account, context)
@@ -81,6 +92,19 @@ module StandardId
         end
       end
 
+      def passwordless_registration_enabled?
+        StandardId.config.web.passwordless_registration
+      end
+
+      def emit_passwordless_account_created(account)
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORDLESS_ACCOUNT_CREATED,
+          account: account,
+          channel: @otp_data[:connection],
+          identifier: @otp_data[:username]
+        )
+      end
+
       def emit_authentication_succeeded(account)
         StandardId::Events.publish(
           StandardId::Events::AUTHENTICATION_SUCCEEDED,

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

@@ -2,6 +2,21 @@ module StandardId
   module Web
     module VerifyEmail
       class StartController < BaseController
+        # RAR-56: Rate limit verification code generation by IP (10 per hour)
+        rate_limit to: StandardId.config.rate_limits.verification_start_per_ip,
+                   within: 1.hour,
+                   name: "verify-email-ip",
+                   only: :create,
+                   store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
+        # RAR-56: Rate limit verification code generation by email target (3 per 15 minutes)
+        rate_limit to: StandardId.config.rate_limits.verification_start_per_target,
+                   within: 15.minutes,
+                   by: -> { "verify-email:#{params[:email].to_s.strip.downcase}" },
+                   name: "verify-email-target",
+                   only: :create,
+                   store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
         def show
           render plain: "verify email start", status: :ok
         end

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

@@ -2,6 +2,21 @@ module StandardId
   module Web
     module VerifyPhone
       class StartController < BaseController
+        # RAR-56: Rate limit verification code generation by IP (10 per hour)
+        rate_limit to: StandardId.config.rate_limits.verification_start_per_ip,
+                   within: 1.hour,
+                   name: "verify-phone-ip",
+                   only: :create,
+                   store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
+        # RAR-56: Rate limit verification code generation by phone target (3 per 15 minutes)
+        rate_limit to: StandardId.config.rate_limits.verification_start_per_target,
+                   within: 15.minutes,
+                   by: -> { "verify-phone:#{params[:phone_number].to_s.strip}" },
+                   name: "verify-phone-target",
+                   only: :create,
+                   store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
         def show
           render plain: "verify phone start", status: :ok
         end

data/app/mailers/standard_id/passwordless_mailer.rb

@@ -0,0 +1,16 @@
+module StandardId
+  class PasswordlessMailer < ApplicationMailer
+    layout false
+
+    def otp_email
+      @otp_code = params[:otp_code]
+      @email = params[:email]
+
+      mail(
+        to: @email,
+        from: StandardId.config.passwordless.mailer_from,
+        subject: StandardId.config.passwordless.mailer_subject
+      )
+    end
+  end
+end

data/app/views/standard_id/passwordless_mailer/otp_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>Hi,</p>
+    <p>Use the following code to sign in:</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>
+    <div class="footer">
+      <p>This is an automated message. Please do not reply.</p>
+    </div>
+  </div>
+</body>
+</html>

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

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

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

@@ -54,6 +54,11 @@ StandardId.configure do |c|
   #   }
   # }
   # c.oauth.allowed_audiences = %w[web mobile admin] # Empty = no validation
+  #
+  # Custom claims added to every access token (independent of scopes).
+  # Receives keyword arguments: account:, client:, request:, audience:
+  # Must return a Hash. Reserved JWT keys (sub, exp, iat, etc.) are excluded.
+  # c.oauth.custom_claims = ->(account:, **) { { channel_id: account.channel_id } }
 
   # JWT Signing Configuration (Asymmetric Algorithms)
   # By default, JWTs are signed with HS256 using Rails.application.secret_key_base.

data/lib/standard_id/config/schema.rb

@@ -50,6 +50,20 @@ StandardConfig.schema.draw do
     field :max_attempts, type: :integer, default: 3
     field :retry_delay, type: :integer, default: 30 # 30 seconds
     field :bypass_code, type: :string, default: nil # E2E testing only — NEVER set in production
+
+    # Custom account factory for passwordless registration.
+    # When set, replaces the default find_or_create_account! logic in strategies.
+    # Must be a callable (lambda/proc) that receives (identifier:, params:, request:)
+    # and returns an Account (or account-like) record.
+    # When nil (default), uses the built-in strategy behavior.
+    field :account_factory, type: :any, default: nil
+
+    # OTP email delivery mode:
+    #   :custom   — (default) host app handles delivery via event subscriber
+    #   :built_in — engine sends OTP emails automatically using PasswordlessMailer
+    field :delivery, type: :symbol, default: :custom
+    field :mailer_from, type: :string, default: "noreply@example.com"
+    field :mailer_subject, type: :string, default: "Your sign-in code"
   end
 
   scope :password do
@@ -90,6 +104,12 @@ StandardConfig.schema.draw do
     # Asymmetric (RSA): :rs256, :rs384, :rs512
     # Asymmetric (ECDSA): :es256, :es384, :es512
     field :signing_algorithm, type: :symbol, default: :hs256
+
+    # Custom claims callable for encoding additional claims into JWT access tokens.
+    # Receives keyword arguments: account:, client:, request:, audience:
+    # Must return a Hash of custom claims to merge into the JWT payload.
+    # Example: ->(account:, **) { { channel_id: account.channel_id } }
+    field :custom_claims, type: :any, default: nil
   end
 
   scope :social do
@@ -108,5 +128,25 @@ StandardConfig.schema.draw do
     field :email_verification, type: :boolean, default: true
     field :phone_verification, type: :boolean, default: true
     field :sessions_management, type: :boolean, default: true
+    field :passwordless_registration, type: :boolean, default: false
+  end
+
+  # Rate limiting defaults (used by Rails 8 built-in rate_limit DSL)
+  scope :rate_limits do
+    # RAR-51: Password login
+    field :password_login_per_ip, type: :integer, default: 20        # per 15 minutes
+    field :password_login_per_email, type: :integer, default: 5      # per 15 minutes
+
+    # RAR-60: OTP verification
+    field :otp_verify_per_ip, type: :integer, default: 20            # per 15 minutes
+
+    # RAR-56: Email/phone verification code generation
+    field :verification_start_per_target, type: :integer, default: 3 # per 15 minutes
+    field :verification_start_per_ip, type: :integer, default: 10    # per hour
+
+    # API equivalents
+    field :api_passwordless_start_per_ip, type: :integer, default: 10    # per hour
+    field :api_passwordless_start_per_target, type: :integer, default: 5 # per 15 minutes
+    field :api_token_per_ip, type: :integer, default: 30                 # per 15 minutes
   end
 end

data/lib/standard_id/engine.rb

@@ -23,6 +23,7 @@ module StandardId
 
       StandardId::Events::Subscribers::AccountStatusSubscriber.attach
       StandardId::Events::Subscribers::AccountLockingSubscriber.attach
+      StandardId::Events::Subscribers::PasswordlessDeliverySubscriber.attach
 
       if StandardId.config.issuer.blank?
         Rails.logger.warn("[StandardId] No issuer configured. JWT tokens will not include or verify the 'iss' claim. " \

data/lib/standard_id/events/subscribers/passwordless_delivery_subscriber.rb

@@ -0,0 +1,37 @@
+module StandardId
+  module Events
+    module Subscribers
+      class PasswordlessDeliverySubscriber < Base
+        subscribe_to StandardId::Events::PASSWORDLESS_CODE_GENERATED
+
+        def call(event)
+          return unless built_in_delivery?
+          return unless event[:channel] == "email"
+
+          identifier = event[:identifier]
+          code = event[:code_challenge]&.code
+
+          return if identifier.blank? || code.blank?
+
+          StandardId::PasswordlessMailer.with(
+            email: identifier,
+            otp_code: code
+          ).otp_email.deliver_later
+        end
+
+        def handle_error(error, event)
+          StandardId.logger.error(
+            "[StandardId::PasswordlessDelivery] Failed to deliver OTP email " \
+            "for #{event[:identifier]}: #{error.message}"
+          )
+        end
+
+        private
+
+        def built_in_delivery?
+          StandardId.config.passwordless.delivery == :built_in
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/jwt_service.rb

@@ -7,7 +7,7 @@ require "digest"
 module StandardId
   class JwtService
     RESERVED_JWT_KEYS = %i[sub client_id scope grant_type exp iat aud iss nbf jti]
-    BASE_SESSION_FIELDS = %i[account_id client_id scopes grant_type aud]
+    BASE_SESSION_FIELDS = %i[account_id client_id scopes grant_type aud claims]
 
     # Supported signing algorithms categorized by type
     # Symmetric: use shared secret (Rails.application.secret_key_base)
@@ -187,7 +187,8 @@ module StandardId
         client_id: payload[:client_id],
         scopes: scopes,
         grant_type: payload[:grant_type],
-        aud: payload[:aud]
+        aud: payload[:aud],
+        claims: payload.to_h
       )
     end
 
@@ -239,7 +240,7 @@ module StandardId
     def self.claim_resolver_keys
       resolvers = StandardId.config.oauth.claim_resolvers
       keys = Hash.try_convert(resolvers)&.keys
-      keys.compact.map(&:to_sym).uniq.excluding(*RESERVED_JWT_KEYS)
+      keys.compact.map(&:to_sym).uniq.excluding(*RESERVED_JWT_KEYS, *BASE_SESSION_FIELDS)
     rescue StandardError
       []
     end

data/lib/standard_id/oauth/token_grant_flow.rb

@@ -62,7 +62,7 @@ module StandardId
           aud: audience
         }.compact
 
-        base_payload.merge(claims_from_scope_mapping)
+        base_payload.merge(claims_from_scope_mapping).merge(claims_from_custom_claims)
       end
 
       def token_expiry
@@ -74,6 +74,7 @@ module StandardId
       end
 
       def generate_refresh_token
+        # custom_claims not included — refresh tokens carry identity only
         jti = SecureRandom.uuid
         payload = {
           sub: subject_id,
@@ -155,6 +156,21 @@ module StandardId
         end
       end
 
+      def claims_from_custom_claims
+        callable = StandardId.config.oauth.custom_claims
+        return {} unless callable.respond_to?(:call)
+
+        result = StandardId::Utils::CallableParameterFilter.filter(callable, claim_resolvers_context)
+        claims = callable.call(**result)
+        return {} unless claims.is_a?(Hash)
+
+        # Prevent custom claims from overriding reserved JWT keys or base session fields
+        claims.symbolize_keys.except(*StandardId::JwtService::RESERVED_JWT_KEYS, *StandardId::JwtService::BASE_SESSION_FIELDS)
+      rescue StandardError => e
+        StandardId.config.logger&.error("[StandardId] custom_claims callable raised: #{e.message}")
+        {}
+      end
+
       def claims_from_scope_mapping
         scope_claims = StandardId.config.oauth.scope_claims.with_indifferent_access
         resolvers = StandardId.config.oauth.claim_resolvers.with_indifferent_access

data/lib/standard_id/passwordless/base_strategy.rb

@@ -53,12 +53,37 @@ module StandardId
         raise NotImplementedError
       end
 
+      def find_existing_account(_username)
+        raise NotImplementedError
+      end
+
       public
 
-      # Public wrapper to reuse account lookup/creation outside OTP verification
+      # Public wrapper to reuse account lookup/creation outside OTP verification.
+      # When a custom account_factory is configured, delegates to it instead of
+      # the built-in find_or_create_account! logic.
       def find_or_create_account(username)
         validate_username!(username)
-        find_or_create_account!(username)
+
+        factory = StandardId.config.passwordless.account_factory
+        if factory.respond_to?(:call)
+          account = factory.call(
+            identifier: username,
+            params: request_params,
+            request: request
+          )
+          raise StandardId::InvalidRequestError, "account_factory must return an account" unless account.present?
+          account
+        else
+          find_or_create_account!(username)
+        end
+      end
+
+      # Public wrapper to look up an existing account without creating one.
+      # Returns nil if no account is found for the given username.
+      def find_account(username)
+        validate_username!(username)
+        find_existing_account(username)
       end
 
       def identifier_class
@@ -72,6 +97,13 @@ module StandardId
 
       private
 
+      # Extract request parameters safely. Returns an empty hash if the request
+      # does not support parameters (e.g. test doubles).
+      def request_params
+        return {} unless request.respond_to?(:params)
+        request.params
+      end
+
       def emit_code_requested(username)
         StandardId::Events.publish(
           StandardId::Events::PASSWORDLESS_CODE_REQUESTED,

data/lib/standard_id/passwordless/email_strategy.rb

@@ -15,7 +15,14 @@ module StandardId
         Account.find_or_create_by_verified_email!(email)
       end
 
+      def find_existing_account(email)
+        normalized = email.to_s.strip.downcase
+        identifier = StandardId::EmailIdentifier.includes(:account).find_by(value: normalized)
+        identifier&.account
+      end
+
       def sender_callback
+        return nil if StandardId.config.passwordless.delivery == :built_in
         StandardId.config.passwordless_email_sender
       end
     end

data/lib/standard_id/passwordless/sms_strategy.rb

@@ -21,6 +21,11 @@ module StandardId
         Account.create!(identifiers_attributes:)
       end
 
+      def find_existing_account(phone_number)
+        identifier = StandardId::PhoneNumberIdentifier.includes(:account).find_by(value: phone_number)
+        identifier&.account
+      end
+
       def sender_callback
         StandardId.config.passwordless_sms_sender
       end

data/lib/standard_id/passwordless/verification_service.rb

@@ -5,10 +5,13 @@ module StandardId
       # - success?: true/false
       # - account: the resolved account (nil on failure)
       # - challenge: the consumed CodeChallenge (nil on failure)
-      # - error: error message string (nil on success)
+      # - error: human-readable error message string (nil on success)
+      # - error_code: machine-readable symbol (nil on success)
+      #   One of :invalid_code, :expired, :max_attempts, :not_found, :blank_code,
+      #   :account_not_found, :server_error
       # - attempts: nil on success, 0 when no challenge was found (fabricated
       #   target), or 1+ for wrong-code failures against an active challenge
-      Result = Data.define(:success?, :account, :challenge, :error, :attempts)
+      Result = Data.define(:success?, :account, :challenge, :error, :error_code, :attempts)
 
       STRATEGY_MAP = {
         "email" => StandardId::Passwordless::EmailStrategy,
@@ -54,7 +57,7 @@ module StandardId
         #     render_error(result.error)
         #   end
         #
-        def verify(email: nil, phone: nil, code:, request:, connection: nil, username: nil)
+        def verify(email: nil, phone: nil, code:, request:, connection: nil, username: nil, allow_registration: true)
           # Allow callers to use connection:/username: instead of email:/phone:
           if connection.present?
             if username.blank?
@@ -68,31 +71,42 @@ module StandardId
             end
           end
 
-          new(email: email, phone: phone, code: code, request: request).verify
+          new(email: email, phone: phone, code: code, request: request, allow_registration: allow_registration).verify
         end
       end
 
-      def initialize(email: nil, phone: nil, code:, request:)
+      def initialize(email: nil, phone: nil, code:, request:, allow_registration: true)
         @code = code.to_s.strip
         @request = request
+        @allow_registration = allow_registration
         resolve_target_and_channel!(email, phone)
       end
 
       def verify
         if @code.blank?
-          return failure("Code is required")
+          return failure("Code is required", error_code: :blank_code)
         end
 
         bypass_result = try_bypass
         return bypass_result if bypass_result
 
         challenge = find_active_challenge
-        code_matches = challenge.present? && secure_compare(challenge.code, @code)
+
+        unless challenge.present?
+          return failure("Invalid or expired verification code", error_code: :not_found, attempts: 0)
+        end
+
+        code_matches = secure_compare(challenge.code, @code)
         attempts = record_failed_attempt(challenge, code_matches)
 
         unless code_matches
-          emit_otp_validation_failed(attempts) if challenge.present?
-          return failure("Invalid or expired verification code", attempts: attempts)
+          emit_otp_validation_failed(attempts)
+
+          if attempts >= StandardId.config.passwordless.max_attempts
+            return failure("Too many failed attempts. Please request a new code.", error_code: :max_attempts, attempts: attempts)
+          end
+
+          return failure("Invalid or expired verification code", error_code: :invalid_code, attempts: attempts)
         end
 
         # Re-fetch with lock inside a transaction to prevent concurrent use.
@@ -103,12 +117,18 @@ module StandardId
             # No OTP_VALIDATION_FAILED event here: the code was correct but the
             # challenge was consumed by a concurrent request — not an attacker
             # guessing codes. Emitting a failure event would be misleading.
-            result = failure("Invalid or expired verification code", attempts: attempts)
+            result = failure("Invalid or expired verification code", error_code: :expired, attempts: attempts)
             raise ActiveRecord::Rollback
           end
 
           strategy = strategy_for(@channel)
-          account = strategy.find_or_create_account(@target)
+          account = resolve_account(strategy)
+
+          unless account
+            label = @channel == "sms" ? "phone number" : "email address"
+            result = failure("No account found for this #{label}", error_code: :account_not_found)
+            raise ActiveRecord::Rollback
+          end
 
           locked_challenge.use!
 
@@ -123,9 +143,9 @@ module StandardId
 
         result
       rescue ActiveRecord::RecordNotFound
-        failure("Invalid or expired verification code")
+        failure("Invalid or expired verification code", error_code: :expired)
       rescue ActiveRecord::RecordInvalid => e
-        failure("Unable to complete verification: #{e.record.errors.full_messages.to_sentence}")
+        failure("Unable to complete verification: #{e.record.errors.full_messages.to_sentence}", error_code: :server_error)
       end
 
       private
@@ -147,7 +167,15 @@ module StandardId
         return unless secure_compare(bypass_code, @code)
 
         strategy = strategy_for(@channel)
-        account = strategy.find_or_create_account(@target)
+        account = nil
+        ActiveRecord::Base.transaction do
+          account = resolve_account(strategy)
+        end
+
+        unless account
+          label = @channel == "sms" ? "phone number" : "email address"
+          return failure("No account found for this #{label}", error_code: :account_not_found)
+        end
 
         StandardId::Events.publish(
           StandardId::Events::OTP_VALIDATED,
@@ -183,7 +211,6 @@ module StandardId
       # rescued alongside account-creation errors. This is intentional — both
       # represent unexpected persistence failures and warrant the same response.
       def record_failed_attempt(challenge, code_matches)
-        return 0 if challenge.blank?
         return 0 if code_matches
 
         attempts = (challenge.metadata["attempts"] || 0) + 1
@@ -199,6 +226,17 @@ module StandardId
         ActiveSupport::SecurityUtils.secure_compare(a.to_s, b.to_s)
       end
 
+      # Resolve the account for the target identifier.
+      # When @allow_registration is true, creates a new account if none exists.
+      # When false, returns nil if no account is found.
+      def resolve_account(strategy)
+        if @allow_registration
+          strategy.find_or_create_account(@target)
+        else
+          strategy.find_account(@target)
+        end
+      end
+
       def strategy_for(channel)
         klass = STRATEGY_MAP[channel]
         raise StandardId::InvalidRequestError, "Unsupported connection type: #{channel}" unless klass
@@ -240,17 +278,19 @@ module StandardId
           account: account,
           challenge: challenge,
           error: nil,
+          error_code: nil,
           attempts: nil
         )
       end
 
       # attempts is nil on success (not meaningful) and 0 when no challenge was found.
-      def failure(error, attempts: nil)
+      def failure(error, error_code: nil, attempts: nil)
         Result.new(
           "success?": false,
           account: nil,
           challenge: nil,
           error: error,
+          error_code: error_code,
           attempts: attempts
         )
       end

data/lib/standard_id/passwordless.rb

@@ -0,0 +1,56 @@
+require "standard_id/passwordless/verification_service"
+
+module StandardId
+  module Passwordless
+    class << self
+      # Public API for verifying a passwordless OTP code.
+      #
+      # This is the recommended entry point for host apps that need OTP
+      # verification without mounting WebEngine. It wraps
+      # VerificationService.verify with the same interface and result type.
+      #
+      # @param username [String] The identifier value (email or phone number)
+      # @param code [String] The OTP code to verify
+      # @param connection [String] Channel type ("email" or "sms")
+      # @param request [ActionDispatch::Request] The current request
+      # @return [VerificationService::Result] A result with:
+      #   - success? — true when verification succeeded
+      #   - account  — the authenticated/created account (nil on failure)
+      #   - challenge — the consumed CodeChallenge (nil on failure)
+      #   - error — human-readable message (nil on success)
+      #   - error_code — machine-readable symbol (nil on success):
+      #       :invalid_code, :expired, :max_attempts, :not_found, :blank_code,
+      #       :account_not_found, :server_error
+      #   - attempts — failed attempt count (nil on success)
+      #
+      # @example
+      #   result = StandardId::Passwordless.verify(
+      #     username: "user@example.com",
+      #     code: "123456",
+      #     connection: "email",
+      #     request: request
+      #   )
+      #
+      #   if result.success?
+      #     sign_in(result.account)
+      #   else
+      #     case result.error_code
+      #     when :invalid_code then render_invalid_code
+      #     when :expired      then render_expired
+      #     when :max_attempts then render_locked_out
+      #     when :not_found    then render_not_found
+      #     end
+      #   end
+      #
+      def verify(username:, code:, connection:, request:, allow_registration: true)
+        VerificationService.verify(
+          connection: connection,
+          username: username,
+          code: code,
+          request: request,
+          allow_registration: allow_registration
+        )
+      end
+    end
+  end
+end

data/lib/standard_id/rate_limit_store.rb

@@ -0,0 +1,42 @@
+module StandardId
+  # A delegating cache store for rate limiting that lazily resolves the
+  # backing store at request time. This allows the engine's rate_limit
+  # declarations to work regardless of boot order, and respects the host
+  # app's cache configuration.
+  #
+  # Resolution order:
+  #   1. StandardId.config.cache_store (if it responds to :increment)
+  #   2. Rails.cache
+  class RateLimitStore
+    def increment(name, amount = 1, **options)
+      resolve_store.increment(name, amount, **options)
+    end
+
+    def read(name, **options)
+      resolve_store.read(name, **options)
+    end
+
+    def write(name, value, **options)
+      resolve_store.write(name, value, **options)
+    end
+
+    def delete(name, **options)
+      resolve_store.delete(name, **options)
+    end
+
+    def clear(**options)
+      resolve_store.clear(**options)
+    end
+
+    private
+
+    def resolve_store
+      configured = StandardId.config.cache_store
+      if configured.respond_to?(:increment)
+        configured
+      else
+        Rails.cache
+      end
+    end
+  end
+end

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/standard_id.rb

@@ -10,6 +10,7 @@ require "standard_id/events/subscribers/base"
 require "standard_id/events/subscribers/logging_subscriber"
 require "standard_id/events/subscribers/account_status_subscriber"
 require "standard_id/events/subscribers/account_locking_subscriber"
+require "standard_id/events/subscribers/passwordless_delivery_subscriber"
 require "standard_id/account_status"
 require "standard_id/account_locking"
 require "standard_id/http_client"
@@ -40,9 +41,11 @@ require "standard_id/passwordless/base_strategy"
 require "standard_id/passwordless/email_strategy"
 require "standard_id/passwordless/sms_strategy"
 require "standard_id/passwordless/verification_service"
+require "standard_id/passwordless"
 require "standard_id/authorization_bypass"
 require "standard_id/utils/callable_parameter_filter"
 require "standard_id/utils/ip_normalizer"
+require "standard_id/rate_limit_store"
 
 require "concurrent/delay"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -114,6 +114,7 @@ files:
 - app/controllers/concerns/standard_id/inertia_support.rb
 - app/controllers/concerns/standard_id/lifecycle_hooks.rb
 - app/controllers/concerns/standard_id/passwordless_strategy.rb
+- app/controllers/concerns/standard_id/rate_limit_handling.rb
 - app/controllers/concerns/standard_id/sentry_context.rb
 - app/controllers/concerns/standard_id/set_current_request_details.rb
 - app/controllers/concerns/standard_id/social_authentication.rb
@@ -156,6 +157,7 @@ files:
 - app/jobs/standard_id/cleanup_expired_refresh_tokens_job.rb
 - app/jobs/standard_id/cleanup_expired_sessions_job.rb
 - app/mailers/standard_id/application_mailer.rb
+- app/mailers/standard_id/passwordless_mailer.rb
 - app/models/concerns/standard_id/account_associations.rb
 - app/models/concerns/standard_id/credentiable.rb
 - app/models/concerns/standard_id/password_strength.rb
@@ -175,6 +177,8 @@ files:
 - app/models/standard_id/service_session.rb
 - app/models/standard_id/session.rb
 - app/models/standard_id/username_identifier.rb
+- app/views/standard_id/passwordless_mailer/otp_email.html.erb
+- app/views/standard_id/passwordless_mailer/otp_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
@@ -227,6 +231,7 @@ files:
 - lib/standard_id/events/subscribers/account_status_subscriber.rb
 - lib/standard_id/events/subscribers/base.rb
 - lib/standard_id/events/subscribers/logging_subscriber.rb
+- lib/standard_id/events/subscribers/passwordless_delivery_subscriber.rb
 - lib/standard_id/http_client.rb
 - lib/standard_id/jwt_service.rb
 - lib/standard_id/oauth/authorization_code_authorization_flow.rb
@@ -244,12 +249,14 @@ files:
 - lib/standard_id/oauth/subflows/traditional_code_grant.rb
 - lib/standard_id/oauth/token_grant_flow.rb
 - lib/standard_id/oauth/token_lifetime_resolver.rb
+- lib/standard_id/passwordless.rb
 - lib/standard_id/passwordless/base_strategy.rb
 - lib/standard_id/passwordless/email_strategy.rb
 - lib/standard_id/passwordless/sms_strategy.rb
 - lib/standard_id/passwordless/verification_service.rb
 - lib/standard_id/provider_registry.rb
 - lib/standard_id/providers/base.rb
+- lib/standard_id/rate_limit_store.rb
 - lib/standard_id/testing.rb
 - lib/standard_id/testing/authentication_helpers.rb
 - lib/standard_id/testing/factories/credentials.rb