standard_id 0.3.2 → 0.4.0

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/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

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

@@ -0,0 +1,37 @@
+FactoryBot.define do
+  factory :standard_id_email_identifier, class: "StandardId::EmailIdentifier" do
+    sequence(:value) { |n| "user#{n}@example.com" }
+
+    trait :verified do
+      verified_at { Time.current }
+    end
+
+    trait :unverified do
+      verified_at { nil }
+    end
+  end
+
+  factory :standard_id_phone_number_identifier, class: "StandardId::PhoneNumberIdentifier" do
+    sequence(:value) { |n| "+1555#{(n % 10_000_000).to_s.rjust(7, '0')}" }
+
+    trait :verified do
+      verified_at { Time.current }
+    end
+
+    trait :unverified do
+      verified_at { nil }
+    end
+  end
+
+  factory :standard_id_username_identifier, class: "StandardId::UsernameIdentifier" do
+    sequence(:value) { |n| "user_#{n}" }
+
+    trait :verified do
+      verified_at { Time.current }
+    end
+
+    trait :unverified do
+      verified_at { nil }
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+FactoryBot.define do
+  # ClientApplication requires a polymorphic `owner` association.
+  # The host app must define an `:account` factory for this association to resolve.
+  factory :standard_id_client_application, class: "StandardId::ClientApplication" do
+    association :owner, factory: :account
+    sequence(:name) { |n| "Test App #{n}" }
+    redirect_uris { "https://example.com/callback" }
+    scopes { "openid profile email" }
+    grant_types { "authorization_code refresh_token" }
+    response_types { "code" }
+    client_type { "confidential" }
+    require_pkce { true }
+    code_challenge_methods { "S256" }
+    access_token_lifetime { 3600 }
+    refresh_token_lifetime { 2_592_000 }
+    authorization_code_lifetime { 600 }
+    active { true }
+
+    trait :public_client do
+      client_type { "public" }
+    end
+
+    trait :inactive do
+      active { false }
+      deactivated_at { Time.current }
+    end
+
+    # Replaces the default grant_types value. To combine with other grant types,
+    # set grant_types explicitly: grant_types { "authorization_code client_credentials" }
+    trait :with_client_credentials do
+      grant_types { "client_credentials" }
+    end
+  end
+
+  factory :standard_id_code_challenge, class: "StandardId::CodeChallenge" do
+    realm { "authentication" }
+    channel { "email" }
+    sequence(:target) { |n| "user#{n}@example.com" }
+    code { SecureRandom.random_number(10**6).to_s.rjust(6, "0") }
+    expires_at { 10.minutes.from_now }
+
+    trait :expired do
+      expires_at { 5.minutes.ago }
+    end
+
+    trait :used do
+      used_at { Time.current }
+    end
+
+    trait :for_verification do
+      realm { "verification" }
+    end
+
+    trait :for_sms do
+      channel { "sms" }
+      sequence(:target) { |n| "+1555#{(n % 10_000_000).to_s.rjust(7, '0')}" }
+    end
+  end
+
+  # AuthorizationCode has `belongs_to :account, optional: true`.
+  # client_id is a plain string (no FK to ClientApplication) — intentionally
+  # unlinked so tests can create authorization codes without a full OAuth setup.
+  factory :standard_id_authorization_code, class: "StandardId::AuthorizationCode" do
+    transient do
+      plaintext_code { SecureRandom.hex(20) }
+    end
+
+    association :account, factory: :account
+    code_hash { StandardId::AuthorizationCode.hash_for(plaintext_code) }
+    client_id { SecureRandom.hex(16) }
+    redirect_uri { "https://example.com/callback" }
+    scope { "openid profile" }
+    issued_at { Time.current }
+    expires_at { 10.minutes.from_now }
+
+    trait :expired do
+      expires_at { 5.minutes.ago }
+    end
+
+    trait :consumed do
+      consumed_at { Time.current }
+    end
+
+    trait :with_pkce do
+      code_challenge { SecureRandom.hex(32) }
+      code_challenge_method { "S256" }
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+FactoryBot.define do
+  # BrowserSession requires an `account` association (belongs_to :account).
+  # The host app must define an `:account` factory for this association to resolve.
+  factory :standard_id_browser_session, class: "StandardId::BrowserSession" do
+    association :account, factory: :account
+    user_agent { "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/120.0" }
+    sequence(:ip_address) { |n| "192.168.1.#{(n % 254) + 1}" }
+    expires_at { StandardId::BrowserSession.expiry }
+
+    trait :active do
+      revoked_at { nil }
+    end
+
+    trait :expired do
+      expires_at { 2.days.ago }
+      revoked_at { nil }
+    end
+
+    trait :revoked do
+      revoked_at { 1.day.ago }
+    end
+
+    trait :chrome do
+      user_agent { "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/120.0" }
+    end
+
+    trait :firefox do
+      user_agent { "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Firefox/121.0" }
+    end
+
+    trait :safari do
+      user_agent { "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Safari/17.2" }
+    end
+
+    trait :edge do
+      user_agent { "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Edg/120.0" }
+    end
+  end
+
+  # DeviceSession requires an `account` association (belongs_to :account).
+  # The host app must define an `:account` factory for this association to resolve.
+  factory :standard_id_device_session, class: "StandardId::DeviceSession" do
+    association :account, factory: :account
+    device_agent { "App/1.0 (iPhone; iOS 17.2)" }
+    sequence(:device_id) { |n| "device_#{n}" }
+    sequence(:ip_address) { |n| "10.0.0.#{(n % 254) + 1}" }
+    expires_at { StandardId::DeviceSession.expiry }
+    last_refreshed_at { 30.minutes.ago }
+
+    trait :active do
+      revoked_at { nil }
+      last_refreshed_at { 30.minutes.ago }
+    end
+
+    trait :expired do
+      expires_at { 15.days.ago }
+      revoked_at { nil }
+    end
+
+    trait :revoked do
+      expires_at { 30.days.from_now }
+      revoked_at { 5.days.ago }
+    end
+
+    trait :stale do
+      expires_at { 30.days.from_now }
+      revoked_at { nil }
+      last_refreshed_at { 2.hours.ago }
+    end
+
+    trait :iphone do
+      device_agent { "App/1.0 (iPhone; iOS 17.2)" }
+    end
+
+    trait :android do
+      device_agent { "App/1.0 (Android; Samsung Galaxy S24)" }
+    end
+
+    trait :ipad do
+      device_agent { "App/1.0 (iPad; iPadOS 17.2)" }
+    end
+  end
+
+  # NOTE: ServiceSession inherits `belongs_to :account` from Session and adds
+  # `belongs_to :owner` (polymorphic). Both are required.
+  # By default, account and owner are distinct :account instances. Override one
+  # or both if your test needs them to be the same object.
+  # The host app must define an `:account` factory for these associations to resolve.
+  factory :standard_id_service_session, class: "StandardId::ServiceSession" do
+    association :account, factory: :account
+    association :owner, factory: :account
+    service_name { "test-service" }
+    service_version { "1.0.0" }
+    ip_address { "10.0.0.1" }
+    user_agent { "ServiceClient/1.0" }
+    expires_at { StandardId::ServiceSession.default_expiry }
+
+    trait :active do
+      revoked_at { nil }
+    end
+
+    trait :expired do
+      expires_at { 30.days.ago }
+      revoked_at { nil }
+    end
+
+    trait :revoked do
+      expires_at { 90.days.from_now }
+      revoked_at { 1.day.ago }
+    end
+  end
+end

data/lib/standard_id/testing/factory_bot.rb

@@ -0,0 +1,7 @@
+require "factory_bot"
+
+# Factories are loaded alphabetically via glob. FactoryBot resolves associations
+# lazily, so load order does not affect correctness. If adding a factory file
+# with an explicit dependency on another, use require_relative instead.
+factory_paths = Dir[File.join(__dir__, "factories", "*.rb")]
+factory_paths.each { |f| require f }