standard_id 0.3.1 → 0.4.0

data/lib/standard_id/authorization_bypass.rb

@@ -0,0 +1,121 @@
+module StandardId
+  module AuthorizationBypass
+    FRAMEWORK_CALLBACKS = {
+      action_policy: :verify_authorized,
+      pundit: :verify_authorized,
+      cancancan: :check_authorization
+    }.freeze
+
+    MUTEX = Mutex.new
+    private_constant :MUTEX
+
+    class << self
+      # Skips the host app's authorization callback on all engine controllers,
+      # and also skips authenticate_account! on public controllers (login,
+      # signup, callbacks, etc.) since those must be accessible without a session.
+      #
+      # In production (eager_load=true), controllers are already loaded when
+      # this runs so the registry is populated. In development (eager_load=false),
+      # controllers are loaded lazily on first request; newly registered
+      # controllers receive skips immediately via apply_to_controller (called
+      # from ControllerPolicy.register). The to_prepare block handles class
+      # reloading — after Zeitwerk unloads/reloads classes, the freshly loaded
+      # controllers re-register and receive skips again.
+      def apply(framework: nil, callback: nil)
+        if framework && callback
+          raise ArgumentError, "Provide framework: or callback:, not both"
+        end
+
+        register_prepare = false
+
+        MUTEX.synchronize do
+          # Guard against duplicate to_prepare registrations if called more than
+          # once (e.g. in tests or misconfigured initializers). skip_before_action
+          # is idempotent so duplicates are harmless, but this keeps things tidy.
+          return if @callback_name
+
+          @callback_name = resolve_callback(framework, callback)
+          # @prepared is intentionally NOT cleared by reset!. This ensures
+          # at most one to_prepare block is registered per process lifetime.
+          # Trade-off: after reset! + apply (e.g. in tests switching
+          # frameworks), the to_prepare code path is not re-registered, so
+          # it can only be verified by the first test that calls apply.
+          register_prepare = !@prepared
+          @prepared = true
+        end
+
+        apply_skips!
+
+        # Re-apply after class reloading in development. In dev (eager_load=false),
+        # reset_registry! + apply_skips! is effectively a no-op because the
+        # registry is empty at this point — lazy-loaded controllers haven't
+        # registered yet. The real work for lazy-loaded controllers is done by
+        # apply_to_controller (called from ControllerPolicy.register). This
+        # block is still needed because after a Zeitwerk reload, controllers
+        # re-register and apply_to_controller fires again for each one, but the
+        # reset_registry! here clears stale references to the old class objects
+        # to prevent memory leaks in long dev sessions.
+        return unless register_prepare
+
+        Rails.application.config.to_prepare do
+          StandardId::ControllerPolicy.reset_registry!
+          StandardId::AuthorizationBypass.apply_skips!
+        end
+      end
+
+      # Whether apply has been called. Used by ControllerPolicy.register to
+      # decide if newly loaded controllers need immediate skip_before_action.
+      def applied?
+        MUTEX.synchronize { !@callback_name.nil? }
+      end
+
+      # Apply skips to a single controller. Called by ControllerPolicy.register
+      # when a controller is lazily loaded after apply has already been called.
+      def apply_to_controller(controller, policy)
+        callback = MUTEX.synchronize { @callback_name }
+        return unless callback
+
+        controller.skip_before_action callback, raise: false
+        if policy == :public
+          # authenticate_account! is defined in WebAuthentication, not on API
+          # controllers. raise: false ensures this is a safe no-op for API
+          # controllers that don't have the callback.
+          controller.skip_before_action :authenticate_account!, raise: false
+        end
+      end
+
+      # @api private — called internally by apply and the to_prepare block.
+      # Must remain public because it is invoked from a to_prepare lambda
+      # registered in apply, which executes outside this module's scope.
+      def apply_skips!
+        StandardId::ControllerPolicy.registry_snapshot.each do |policy, controllers|
+          controllers.each { |controller| apply_to_controller(controller, policy) }
+        end
+      end
+
+      # @api private — intended for test isolation only.
+      # NOTE: This clears @callback_name (so applied? returns false and apply
+      # can be called again with a different framework) but intentionally does
+      # NOT clear @prepared, so no additional to_prepare block is registered.
+      def reset!
+        MUTEX.synchronize { @callback_name = nil }
+      end
+
+      private
+
+      def resolve_callback(framework, callback)
+        if callback
+          callback.to_sym
+        elsif framework
+          FRAMEWORK_CALLBACKS.fetch(framework.to_sym) do
+            raise ArgumentError, "Unknown framework: #{framework}. " \
+              "Supported: #{FRAMEWORK_CALLBACKS.keys.join(', ')}. " \
+              "Or pass callback: :your_callback_name instead."
+          end
+        else
+          raise ArgumentError, "Provide either framework: or callback:"
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/config/schema.rb

@@ -14,8 +14,10 @@ StandardConfig.schema.draw do
     field :issuer, type: :string, default: nil
     field :login_url, type: :string, default: nil
     field :allowed_post_logout_redirect_uris, type: :array, default: []
+    field :account_scope, type: :any, default: nil
     field :use_inertia, type: :boolean, default: false
     field :inertia_component_namespace, type: :string, default: "standard_id"
+    field :alias_current_user, type: :boolean, default: false
   end
 
   scope :events do

data/lib/standard_id/jwt_service.rb

@@ -1,5 +1,6 @@
 require "jwt"
 require "concurrent/delay"
+require "concurrent/atomic/atomic_reference"
 require "openssl"
 require "digest"
 
@@ -34,6 +35,11 @@ module StandardId
       end
     end
 
+    @signing_key_ref = Concurrent::AtomicReference.new
+    @key_id_ref = Concurrent::AtomicReference.new
+    @previous_keys_ref = Concurrent::AtomicReference.new
+    @jwks_ref = Concurrent::AtomicReference.new
+
     def self.session_class
       SESSION_CLASS.value
     end
@@ -52,7 +58,11 @@ module StandardId
 
     def self.signing_key
       if asymmetric?
-        @signing_key_cache ||= parse_private_key(StandardId.config.oauth.signing_key)
+        @signing_key_ref.get || begin
+          computed = parse_private_key(StandardId.config.oauth.signing_key)
+          @signing_key_ref.compare_and_set(nil, computed)
+          @signing_key_ref.get
+        end
       else
         Rails.application.secret_key_base
       end
@@ -74,16 +84,24 @@ module StandardId
 
       # Generate stable key ID from public key fingerprint
       # Use public_to_pem which works for both RSA and EC keys
-      @key_id ||= Digest::SHA256.hexdigest(signing_key.public_to_pem)[0..7]
+      @key_id_ref.get || begin
+        computed = Digest::SHA256.hexdigest(signing_key.public_to_pem)[0..7]
+        @key_id_ref.compare_and_set(nil, computed)
+        @key_id_ref.get
+      end
     end
 
     def self.previous_keys
       return [] unless asymmetric?
 
-      @previous_keys_cache ||= Array(StandardId.config.oauth.previous_signing_keys).filter_map do |entry|
-        parse_previous_key_entry(entry)
-      rescue StandardError
-        nil
+      @previous_keys_ref.get || begin
+        computed = Array(StandardId.config.oauth.previous_signing_keys).filter_map do |entry|
+          parse_previous_key_entry(entry)
+        rescue StandardError
+          nil
+        end
+        @previous_keys_ref.compare_and_set(nil, computed)
+        @previous_keys_ref.get
       end
     end
 
@@ -93,11 +111,15 @@ module StandardId
       [{ kid: key_id, key: verification_key, algorithm: algorithm }] + previous_keys
     end
 
+    # NOTE: Individual resets are atomic but the group is not — a concurrent
+    # reader between two .set(nil) calls may see a mix of old and new values.
+    # This is acceptable: key rotation is an infrequent operator action and
+    # the worst case is one request using a stale (but still valid) key.
     def self.reset_cached_key!
-      @key_id = nil
-      @signing_key_cache = nil
-      @previous_keys_cache = nil
-      @jwks = nil
+      @key_id_ref.set(nil)
+      @signing_key_ref.set(nil)
+      @previous_keys_ref.set(nil)
+      @jwks_ref.set(nil)
     end
 
     def self.encode(payload, expires_in: 1.hour)
@@ -168,12 +190,16 @@ module StandardId
     def self.jwks
       return nil unless asymmetric?
 
-      @jwks ||= begin
-        exported_keys = all_verification_keys.map do |entry|
-          jwk = JWT::JWK.new(entry[:key], kid: entry[:kid]).export
-          jwk.merge(alg: entry[:algorithm], use: "sig")
+      @jwks_ref.get || begin
+        computed = begin
+          exported_keys = all_verification_keys.map do |entry|
+            jwk = JWT::JWK.new(entry[:key], kid: entry[:kid]).export
+            jwk.merge(alg: entry[:algorithm], use: "sig")
+          end
+          { keys: exported_keys }
         end
-        { keys: exported_keys }
+        @jwks_ref.compare_and_set(nil, computed)
+        @jwks_ref.get
       end
     end
 

data/lib/standard_id/oauth/password_flow.rb

@@ -1,9 +1,13 @@
+require "concurrent/delay"
+
 module StandardId
   module Oauth
     class PasswordFlow < TokenGrantFlow
       expect_params :username, :password, :client_id
       permit_params :client_secret, :audience, :scope, :realm
 
+      DUMMY_PASSWORD_DIGEST = Concurrent::Delay.new { BCrypt::Password.create("").freeze }
+
       def authenticate!
         validate_client_secret!(params[:client_id], params[:client_secret]) if params[:client_secret].present?
         emit_authentication_started
@@ -95,7 +99,7 @@ module StandardId
       end
 
       def dummy_password_digest
-        @dummy_password_digest ||= BCrypt::Password.create("").freeze
+        DUMMY_PASSWORD_DIGEST.value
       end
 
       def default_scope

data/lib/standard_id/oauth/passwordless_otp_flow.rb

@@ -6,53 +6,22 @@ module StandardId
 
       def authenticate!
         validate_client_secret!(params[:client_id], params[:client_secret]) if params[:client_secret].present?
+        validate_requested_scope!
 
-        if code_challenge.blank?
-          emit_otp_validation_failed
-          raise StandardId::InvalidGrantError, "Invalid or expired verification code"
-        end
+        @verification_result = StandardId::Passwordless::VerificationService.verify(
+          connection: params[:connection],
+          username: params[:username],
+          code: params[:otp],
+          request: request
+        )
 
-        if account.blank?
-          raise StandardId::InvalidGrantError, "Unable to authenticate user"
+        unless @verification_result.success?
+          raise StandardId::InvalidGrantError, @verification_result.error
         end
-
-        validate_requested_scope!
-
-        code_challenge.use!
-        emit_otp_validated
       end
 
       private
 
-      def emit_otp_validated
-        StandardId::Events.publish(
-          StandardId::Events::OTP_VALIDATED,
-          account: account,
-          channel: params[:connection]
-        )
-        StandardId::Events.publish(
-          StandardId::Events::PASSWORDLESS_CODE_VERIFIED,
-          code_challenge: code_challenge,
-          account: account,
-          channel: params[:connection]
-        )
-      end
-
-      def emit_otp_validation_failed
-        StandardId::Events.publish(
-          StandardId::Events::OTP_VALIDATION_FAILED,
-          identifier: params[:username],
-          channel: params[:connection],
-          attempts: nil
-        )
-        StandardId::Events.publish(
-          StandardId::Events::PASSWORDLESS_CODE_FAILED,
-          identifier: params[:username],
-          channel: params[:connection],
-          attempts: nil
-        )
-      end
-
       def subject_id
         account.id
       end
@@ -77,28 +46,8 @@ module StandardId
         true
       end
 
-      def code_challenge
-        @code_challenge ||= StandardId::CodeChallenge.active.find_by(
-          realm: "authentication",
-          channel: params[:connection],
-          target: params[:username],
-          code: params[:otp]
-        )
-      end
-
       def account
-        @account ||= strategy_for(params[:connection]).find_or_create_account(params[:username])
-      end
-
-      def strategy_for(connection)
-        case connection
-        when "email"
-          StandardId::Passwordless::EmailStrategy.new(request)
-        when "sms"
-          StandardId::Passwordless::SmsStrategy.new(request)
-        else
-          raise StandardId::InvalidRequestError, "Unsupported connection type: #{connection}"
-        end
+        @verification_result&.account
       end
 
       def validate_requested_scope!

data/lib/standard_id/passwordless/base_strategy.rb

@@ -35,7 +35,7 @@ module StandardId
           target: username,
           code: code,
           expires_at: StandardId.config.passwordless.code_ttl.seconds.from_now,
-          ip_address: request.remote_ip,
+          ip_address: StandardId::Utils::IpNormalizer.normalize(request.remote_ip),
           user_agent: request.user_agent
         )
         cc

data/lib/standard_id/passwordless/verification_service.rb

@@ -0,0 +1,227 @@
+module StandardId
+  module Passwordless
+    class VerificationService
+      # Result object returned by .verify.
+      # - success?: true/false
+      # - account: the resolved account (nil on failure)
+      # - challenge: the consumed CodeChallenge (nil on failure)
+      # - error: error message string (nil on success)
+      # - 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)
+
+      STRATEGY_MAP = {
+        "email" => StandardId::Passwordless::EmailStrategy,
+        "sms"   => StandardId::Passwordless::SmsStrategy
+      }.freeze
+
+      class << self
+        # Verify a passwordless OTP code and resolve the account.
+        #
+        # @param email [String, nil] The email address (mutually exclusive with phone)
+        # @param phone [String, nil] The phone number (mutually exclusive with email)
+        # @param connection [String, nil] Channel type ("email" or "sms") — convenience
+        #   alternative to email:/phone: (use with username:)
+        # @param username [String, nil] The identifier value — used with connection:
+        # @param code [String] The OTP code to verify
+        # @param request [ActionDispatch::Request] The current request (needed for strategy)
+        # @return [Result] A result object with success?, account, challenge, error, and attempts
+        #
+        # OTP_VALIDATION_FAILED / PASSWORDLESS_CODE_FAILED events are only emitted
+        # when an active challenge exists but the code is wrong. Requests with no
+        # matching challenge (e.g. fabricated usernames) do not emit failure events
+        # — this avoids noise from speculative probes that never triggered a code.
+        # NOTE: This is a behavioral change from the pre-extraction API flow
+        # (PasswordlessOtpFlow), which emitted failure events unconditionally.
+        #
+        # @example Using connection/username (preferred for callers with channel info)
+        #   result = StandardId::Passwordless::VerificationService.verify(
+        #     connection: "email",
+        #     username: "user@example.com",
+        #     code: "123456",
+        #     request: request
+        #   )
+        #
+        # @example Using email/phone directly
+        #   result = StandardId::Passwordless::VerificationService.verify(
+        #     email: "user@example.com",
+        #     code: "123456",
+        #     request: request
+        #   )
+        #   if result.success?
+        #     sign_in(result.account)
+        #   else
+        #     render_error(result.error)
+        #   end
+        #
+        def verify(email: nil, phone: nil, code:, request:, connection: nil, username: nil)
+          # Allow callers to use connection:/username: instead of email:/phone:
+          if connection.present?
+            if username.blank?
+              raise StandardId::InvalidRequestError, "username: is required when connection: is provided"
+            end
+
+            case connection.to_s
+            when "email" then email = username
+            when "sms"   then phone = username
+            else raise StandardId::InvalidRequestError, "Unsupported connection type: #{connection}"
+            end
+          end
+
+          new(email: email, phone: phone, code: code, request: request).verify
+        end
+      end
+
+      def initialize(email: nil, phone: nil, code:, request:)
+        @code = code.to_s.strip
+        @request = request
+        resolve_target_and_channel!(email, phone)
+      end
+
+      def verify
+        if @code.blank?
+          return failure("Code is required")
+        end
+
+        challenge = find_active_challenge
+        code_matches = challenge.present? && 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)
+        end
+
+        # Re-fetch with lock inside a transaction to prevent concurrent use.
+        result = nil
+        ActiveRecord::Base.transaction do
+          locked_challenge = StandardId::CodeChallenge.lock.find(challenge.id)
+          unless locked_challenge.active?
+            # 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)
+            raise ActiveRecord::Rollback
+          end
+
+          strategy = strategy_for(@channel)
+          account = strategy.find_or_create_account(@target)
+
+          locked_challenge.use!
+
+          result = success(account: account, challenge: locked_challenge)
+        end
+
+        raise "BUG: transaction block failed to set result" if result.nil?
+
+        # Emit events after the transaction commits so subscribers never see
+        # events for rolled-back state.
+        emit_otp_validated(result.account, result.challenge) if result.success?
+
+        result
+      rescue ActiveRecord::RecordNotFound
+        failure("Invalid or expired verification code")
+      rescue ActiveRecord::RecordInvalid => e
+        failure("Unable to complete verification: #{e.record.errors.full_messages.to_sentence}")
+      end
+
+      private
+
+      def resolve_target_and_channel!(email, phone)
+        if email.present?
+          @target = email.to_s.strip
+          @channel = "email"
+        elsif phone.present?
+          @target = phone.to_s.strip
+          @channel = "sms"
+        else
+          raise StandardId::InvalidRequestError, "Either email: or phone: must be provided"
+        end
+      end
+
+      def find_active_challenge
+        StandardId::CodeChallenge.active.find_by(
+          realm: "authentication",
+          channel: @channel,
+          target: @target
+        )
+      end
+
+      # NOTE: The update! here can raise ActiveRecord::RecordInvalid, which is
+      # 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
+        challenge.update!(metadata: challenge.metadata.merge("attempts" => attempts))
+
+        max_attempts = StandardId.config.passwordless.max_attempts
+        challenge.use! if attempts >= max_attempts
+
+        attempts
+      end
+
+      def secure_compare(a, b)
+        ActiveSupport::SecurityUtils.secure_compare(a.to_s, b.to_s)
+      end
+
+      def strategy_for(channel)
+        klass = STRATEGY_MAP[channel]
+        raise StandardId::InvalidRequestError, "Unsupported connection type: #{channel}" unless klass
+        klass.new(@request)
+      end
+
+      def emit_otp_validated(account, challenge)
+        StandardId::Events.publish(
+          StandardId::Events::OTP_VALIDATED,
+          account: account,
+          channel: @channel
+        )
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORDLESS_CODE_VERIFIED,
+          code_challenge: challenge,
+          account: account,
+          channel: @channel
+        )
+      end
+
+      def emit_otp_validation_failed(attempts)
+        StandardId::Events.publish(
+          StandardId::Events::OTP_VALIDATION_FAILED,
+          identifier: @target,
+          channel: @channel,
+          attempts: attempts
+        )
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORDLESS_CODE_FAILED,
+          identifier: @target,
+          channel: @channel,
+          attempts: attempts
+        )
+      end
+
+      def success(account:, challenge:)
+        Result.new(
+          "success?": true,
+          account: account,
+          challenge: challenge,
+          error: nil,
+          attempts: nil
+        )
+      end
+
+      # attempts is nil on success (not meaningful) and 0 when no challenge was found.
+      def failure(error, attempts: nil)
+        Result.new(
+          "success?": false,
+          account: nil,
+          challenge: nil,
+          error: error,
+          attempts: attempts
+        )
+      end
+    end
+  end
+end

data/lib/standard_id/testing/authentication_helpers.rb

@@ -0,0 +1,75 @@
+module StandardId
+  module Testing
+    # Helpers for stubbing StandardId authentication in controller and request specs.
+    #
+    # Usage in rails_helper.rb:
+    #
+    #   require "standard_id/testing"
+    #
+    #   RSpec.configure do |config|
+    #     config.include StandardId::Testing::AuthenticationHelpers, type: :request
+    #     config.include StandardId::Testing::AuthenticationHelpers, type: :controller
+    #   end
+    #
+    module AuthenticationHelpers
+      # Stub web (cookie-based) authentication for controllers that include
+      # StandardId::WebAuthentication.
+      #
+      # Stubs the following methods on the given controller class:
+      # - current_account → returns the given account
+      # - authenticated? → true when account is present
+      # - authenticate_account! → no-op (returns true)
+      # - require_browser_session! → no-op (returns true)
+      #
+      # @param account [Object] the account to return from current_account
+      # @param controller_class [Class] the controller class to stub (default: ApplicationController)
+      #
+      # Example:
+      #   stub_web_authentication(account: my_account)
+      #   stub_web_authentication(account: my_account, controller_class: BackendController)
+      #
+      def stub_web_authentication(account:, controller_class: ApplicationController)
+        allow_any_instance_of(controller_class).to receive(:current_account).and_return(account)
+        allow_any_instance_of(controller_class).to receive(:authenticated?).and_return(account.present?)
+        allow_any_instance_of(controller_class).to receive(:authenticate_account!).and_return(true)
+        allow_any_instance_of(controller_class).to receive(:require_browser_session!).and_return(true)
+      end
+
+      # Stub API (JWT-based) authentication for controllers that include
+      # StandardId::ApiAuthentication.
+      #
+      # @param account [Object] the account to return from current_account
+      # @param session [Object, nil] optional session object for current_session
+      # @param controller_class [Class] the controller class to stub (default: inferred)
+      #
+      # Example:
+      #   stub_api_authentication(account: my_account)
+      #   stub_api_authentication(account: my_account, session: mock_session)
+      #
+      # When controller_class is not provided, defaults to Api::BaseController — the
+      # conventional base class generated by StandardId's install generator.
+      #
+      # Note: Uses allow_any_instance_of which RSpec discourages. For more targeted
+      # stubbing, pass the exact controller class your spec exercises:
+      #
+      #   stub_api_authentication(account: my_account, controller_class: Api::V1::WidgetsController)
+      #
+      def stub_api_authentication(account:, session: nil, controller_class: nil)
+        if controller_class.nil?
+          unless defined?(Api::BaseController)
+            raise ArgumentError,
+              "Could not infer API controller class. Api::BaseController is not defined. " \
+              "Pass controller_class: explicitly (e.g. controller_class: YourApi::BaseController)."
+          end
+
+          controller_class = Api::BaseController
+        end
+
+        allow_any_instance_of(controller_class).to receive(:current_account).and_return(account)
+        allow_any_instance_of(controller_class).to receive(:authenticated?).and_return(account.present?)
+        allow_any_instance_of(controller_class).to receive(:verify_access_token!).and_return(true)
+        allow_any_instance_of(controller_class).to receive(:current_session).and_return(session)
+      end
+    end
+  end
+end

data/lib/standard_id/testing/factories/credentials.rb

@@ -0,0 +1,24 @@
+FactoryBot.define do
+  factory :standard_id_password_credential, class: "StandardId::PasswordCredential" do
+    sequence(:login) { |n| "user#{n}@example.com" }
+    password { "password123" }
+    password_confirmation { "password123" }
+  end
+
+  factory :standard_id_credential, class: "StandardId::Credential" do
+    association :identifier, factory: [:standard_id_email_identifier, :verified]
+    association :credentialable, factory: :standard_id_password_credential
+
+    # Sync login to identifier value so authentication works out of the box.
+    # If you override credentialable after build, set login manually.
+    after(:build) do |credential|
+      credential.credentialable.login = credential.identifier.value
+    end
+  end
+
+  factory :standard_id_client_secret_credential, class: "StandardId::ClientSecretCredential" do
+    association :client_application, factory: :standard_id_client_application
+    name { "Default Secret" }
+    active { true }
+  end
+end