spree_otp_auth 0.2.0

data/app/models/spree/otp_attempt.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'securerandom'
+
+module Spree
+  class OtpAttempt < Spree::Base
+    self.table_name = 'spree_otp_attempts'
+    has_prefix_id :otp_att
+
+    belongs_to :store, class_name: 'Spree::Store'
+    belongs_to :user, class_name: Spree.user_class.to_s, optional: true
+    belongs_to :parent_attempt, class_name: 'Spree::OtpAttempt', optional: true
+    has_one :link_email_attempt, class_name: 'Spree::OtpAttempt', foreign_key: :parent_attempt_id,
+                                 inverse_of: :parent_attempt, dependent: :destroy
+
+    CHANNELS = %w[email mobile whatsapp].freeze
+    PURPOSES = %w[login link_email].freeze
+    DELIVERY_STATUSES = %w[pending submitted failed fallback_sent].freeze
+
+    validates :store, presence: true
+    validates :identifier, presence: true
+    validates :channel, inclusion: { in: CHANNELS }
+    validates :purpose, inclusion: { in: PURPOSES }
+    validates :delivery_status, inclusion: { in: DELIVERY_STATUSES }
+    validates :code_digest, presence: true
+    validates :salt, presence: true
+    validates :expires_at, presence: true
+    validates :attempts_count, numericality: { greater_than_or_equal_to: 0 }
+    validates :max_attempts, numericality: { greater_than: 0 }
+    validates :staged_mobile_number, format: { with: /\A\+[1-9]\d{9,14}\z/, allow_blank: true }
+    validates :staged_email, format: { with: URI::MailTo::EMAIL_REGEXP, allow_blank: true }
+
+    scope :active, -> { where(verified_at: nil).where('expires_at > ?', Time.current) }
+    scope :for_identifier, ->(id) { where(identifier: id) }
+    scope :login, -> { where(purpose: 'login') }
+
+    def expired?
+      Time.current >= expires_at
+    end
+
+    def verified?
+      verified_at.present?
+    end
+
+    def locked?
+      attempts_count >= max_attempts
+    end
+
+    def valid_code?(submitted_code)
+      return false if expired? || verified? || locked?
+      return false if submitted_code.blank?
+
+      candidate_digest = self.class.digest(submitted_code, salt)
+      ActiveSupport::SecurityUtils.secure_compare(code_digest, candidate_digest)
+    end
+
+    def record_failed_attempt!
+      increment!(:attempts_count)
+    end
+
+    def mark_verified!
+      update!(verified_at: Time.current)
+    end
+
+    # Invalidates this code (and its link_email child) without deleting the
+    # record, so the hourly limiter and admin diagnostics still see it.
+    def expire!
+      now = Time.current
+      update_columns(expires_at: now, updated_at: now)
+      link_email_attempt&.update_columns(expires_at: now, updated_at: now)
+    end
+
+    def self.generate_salt
+      SecureRandom.hex(16)
+    end
+
+    def self.digest(code, salt)
+      Digest::SHA256.hexdigest("#{salt}#{code.to_s.strip}")
+    end
+  end
+end

data/app/models/spree/otp_configuration.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Spree
+  class OtpConfiguration < Spree::Base
+    self.table_name = 'spree_otp_configurations'
+    has_prefix_id :otp_cfg
+
+    belongs_to :store, class_name: 'Spree::Store'
+
+    CHANNELS = %w[email mobile whatsapp].freeze
+    FALLBACK_CHANNELS = %w[none whatsapp sms email].freeze
+
+    alias_attribute :auth_channel, :active_channel
+
+    # Legacy provider columns (msg91_*, gupshup_*) are read only by the
+    # one-time import into spree_notification_providers and are dropped in a
+    # later release. Providers, credentials and templates now live in
+    # Admin -> Settings -> Notification providers.
+    encrypts :msg91_auth_key, deterministic: false
+
+    validates :store_id, uniqueness: true, presence: true
+    validates :active_channel, inclusion: { in: CHANNELS }
+    validates :fallback_channel, inclusion: { in: FALLBACK_CHANNELS }
+    validates :otp_length, inclusion: { in: [4, 6] }
+    validates :otp_expiry_seconds, numericality: { greater_than_or_equal_to: 60 }
+    validates :resend_cooldown_seconds, numericality: { greater_than_or_equal_to: 10 }
+    validates :fallback_delay_seconds, numericality: { greater_than_or_equal_to: 10 }
+    validate :active_channel_ready, if: -> { %w[whatsapp mobile].include?(active_channel) }
+
+    # What still stops the store sending login codes on `channel`, as labels.
+    def missing_requirements(channel = active_channel)
+      return [] if channel.to_s == 'email'
+
+      provider_channel = Spree::Otp::Delivery.provider_channel(channel)
+      statuses = SpreeNotificationProviders.channel_status(store, provider_channel)
+      return ["#{channel.to_s == 'mobile' ? 'an' : 'a'} #{channel_name(channel)} provider"] if statuses.empty?
+      return [] if Spree::Otp::Delivery.ready?(store, channel)
+
+      enabled = statuses.reject { |s| s[:status] == :disabled }
+      return ["an enabled #{channel_name(channel)} provider"] if enabled.empty?
+
+      missing = enabled.flat_map { |s| s[:missing] }.uniq
+      missing.presence || ['a "Login code" template']
+    end
+
+    def channel_ready?(channel = active_channel)
+      missing_requirements(channel).empty?
+    end
+
+    # The admin-chosen email template, when the app provides a template model
+    # (SpreeOtpAuth.email_template_class).
+    def email_template
+      model = SpreeOtpAuth.email_template_model
+      model && email_template_id.present? ? model.find_by(id: email_template_id) : nil
+    end
+
+    def email_template=(template)
+      self.email_template_id = template&.id
+    end
+
+    def email_fallback_enabled?
+      fallback_channel == 'email'
+    end
+
+    def self.default_for(store)
+      find_or_initialize_by(store: store) do |cfg|
+        cfg.active_channel = 'whatsapp'
+        cfg.fallback_channel = 'email'
+        cfg.otp_length = 6
+        cfg.otp_expiry_seconds = 600
+        cfg.resend_cooldown_seconds = 30
+        cfg.fallback_delay_seconds = 20
+      end
+    end
+
+    private
+
+    def active_channel_ready
+      missing = missing_requirements
+      return if missing.empty?
+
+      errors.add(:active_channel, "can't be #{channel_name(active_channel)} yet. Missing: #{missing.join(', ')}. " \
+                                  'Set this up in Settings → Notification providers.')
+    end
+
+    def channel_name(channel)
+      channel.to_s == 'mobile' ? 'SMS' : channel.to_s.titleize.sub('Whatsapp', 'WhatsApp')
+    end
+  end
+end

data/app/models/spree/otp_store_decorator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Spree
+  module OtpStoreDecorator
+    def self.prepended(base)
+      base.has_one :otp_configuration, class_name: 'Spree::OtpConfiguration', dependent: :destroy
+    end
+
+    def effective_otp_configuration
+      otp_configuration || Spree::OtpConfiguration.default_for(self)
+    end
+  end
+
+  Spree::Store.prepend(OtpStoreDecorator) if defined?(Spree::Store)
+end

data/app/models/spree/otp_user_decorator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Spree
+  module OtpUserDecorator
+    def self.prepended(base)
+      base.has_many :otp_attempts, class_name: 'Spree::OtpAttempt', dependent: :destroy
+
+      base.validates :mobile_number,
+                     uniqueness: { case_sensitive: false, allow_blank: true },
+                     format: { with: /\A\+[1-9]\d{9,14}\z/, message: :invalid_phone_format, allow_blank: true }
+
+      base.before_validation :normalize_auth_identifiers
+    end
+
+    # :subscribed, :unsubscribed (opted out before) or :undecided (never asked,
+    # or no real email yet). Drives the news-and-offers checkbox at login.
+    def marketing_consent_state
+      return :undecided unless Spree::Otp::Identity.real_email?(email)
+      return :subscribed if accepts_email_marketing
+      return :unsubscribed if respond_to?(:email_marketing_decided_at) && email_marketing_decided_at.present?
+
+      :undecided
+    end
+
+    def mobile_confirmed?
+      respond_to?(:mobile_confirmed_at) && mobile_confirmed_at.present?
+    end
+
+    def confirm_mobile!(phone_or_timestamp = nil, timestamp = Time.current)
+      if phone_or_timestamp.is_a?(String)
+        normalized = normalize_phone(phone_or_timestamp)
+        updates = { mobile_number: normalized }
+        updates[:phone] = normalized if respond_to?(:phone=)
+        updates[:mobile_confirmed_at] = timestamp if respond_to?(:mobile_confirmed_at)
+        update!(updates)
+      else
+        ts = phone_or_timestamp || timestamp
+        update_columns(mobile_confirmed_at: ts) if respond_to?(:mobile_confirmed_at)
+      end
+    end
+
+    private
+
+    def normalize_auth_identifiers
+      self.email = email.to_s.strip.downcase.presence if respond_to?(:email)
+      self.mobile_number = normalize_phone(mobile_number) if mobile_number.present?
+      self.phone = mobile_number if respond_to?(:phone=) && mobile_number.present?
+      self.auth_identifier = (auth_channel == 'mobile' ? mobile_number : email).presence if respond_to?(:auth_identifier=)
+    end
+
+    def normalize_phone(raw)
+      digits = raw.to_s.gsub(/\D/, '')
+      digits = "91#{digits}" if digits.length == 10
+      digits.present? ? "+#{digits}" : nil
+    end
+  end
+
+  Spree.user_class.prepend(OtpUserDecorator) if Spree.user_class
+end

data/app/services/spree/otp/code_sent_payload.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Spree
+  module Otp
+    # Builds the "code sent" response shared by request, resend and fallback
+    # (CodeSent in specs/017-whatsapp-otp-marketing-consent/contracts/otp-api-v3.yaml).
+    module CodeSentPayload
+      module_function
+
+      def build(attempt:, config:, auto_fallback: false)
+        email_destination = Spree::Otp::Delivery.email_destination(attempt)
+        sent_by_email = attempt.channel == 'email'
+        target = sent_by_email ? email_destination : attempt.identifier
+        child = attempt.link_email_attempt
+        consent = consent_flags(attempt, child, email_destination)
+
+        {
+          requires_mobile: false,
+          requires_email: false,
+          requires_email_code: child.present?,
+          channel: attempt.channel,
+          masked_target: Spree::Otp::Identity.mask(target.to_s),
+          masked_email: (child || sent_by_email) ? Spree::Otp::Identity.mask_email((child&.identifier || email_destination).to_s) : nil,
+          auto_fallback: auto_fallback,
+          otp_length: config.otp_length || 6,
+          cooldown_seconds: config.resend_cooldown_seconds,
+          fallback_available_after_seconds: config.fallback_delay_seconds,
+          email_fallback_available: !sent_by_email && child.nil? && config.email_fallback_enabled? && email_destination.present?
+        }.merge(consent)
+      end
+
+      # The news-and-offers box is shown once: beside the email field when one
+      # was collected, otherwise on the code screen for returning customers who
+      # aren't subscribed (ticked unless they opted out before).
+      def consent_flags(attempt, child, email_destination)
+        state = attempt.user ? attempt.user.marketing_consent_state : :undecided
+        collected_email_now = attempt.staged_email.present? || child.present?
+        show = !collected_email_now && state != :subscribed && Spree::Otp::Identity.real_email?(email_destination)
+
+        { show_marketing_consent: show, marketing_consent_default: state != :unsubscribed }
+      end
+
+      def requires_email(user)
+        state = user ? user.marketing_consent_state : :undecided
+        {
+          requires_email: true,
+          requires_mobile: false,
+          show_marketing_consent: true,
+          marketing_consent_default: state != :unsubscribed,
+          message: 'Please enter your email address to continue.'
+        }
+      end
+    end
+  end
+end

data/app/services/spree/otp/delivery.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Spree
+  module Otp
+    # Sends login codes and picks where an attempt's code goes.
+    #
+    # SMS and WhatsApp codes go through spree_notification_providers, so the
+    # store's providers for that channel are tried in priority order. Email
+    # codes are rendered by Spree::OtpMailer and delivered later by the
+    # app's mailer (which itself can route through the providers).
+    module Delivery
+      # :sent    - a provider accepted the code
+      # :unknown - it may have gone out; never resend or switch channel for it
+      # :failed  - no provider can have sent it; safe to fall back
+      Outcome = Struct.new(:status, :message_id, :message_ref, :error_message, keyword_init: true) do
+        def sent? = status == :sent
+        def unknown? = status == :unknown
+        def failed? = status == :failed
+      end
+
+      module_function
+
+      # OTP channel names predate the provider gem: 'mobile' means SMS.
+      def provider_channel(channel)
+        channel.to_s == 'mobile' ? :sms : channel.to_sym
+      end
+
+      def deliver(channel:, store:, destination:, code:, expiry_minutes:, attempt: nil)
+        return send_email(store: store, to: destination, code: code, expiry_minutes: expiry_minutes) if channel.to_s == 'email'
+
+        message = SpreeNotificationProviders::Message.new(
+          channel: provider_channel(channel), type: :otp_code, kind: :otp, to: destination,
+          code: code, expiry_minutes: expiry_minutes, source: attempt
+        )
+        result = SpreeNotificationProviders.deliver(store: store, message: message)
+        status = if result.success? then :sent
+                 elsif result.retryable? then :failed
+                 else :unknown
+                 end
+        Outcome.new(
+          status: status, message_id: result.provider_message_id, message_ref: result.message_ref,
+          error_message: (result.reasons.join('; ').presence || result.outcome.to_s if status == :failed)
+        )
+      end
+
+      def send_email(store:, to:, code:, expiry_minutes:)
+        mail = Spree::OtpMailer.send_otp(store: store, to: to, code: code, expiry_minutes: expiry_minutes)
+        mail.deliver_later
+        Outcome.new(status: :sent, message_id: mail.message_id)
+      rescue StandardError => e
+        Rails.logger.error("[SpreeOtpAuth] email code not queued: #{e.class}: #{e.message}")
+        Outcome.new(status: :failed, error_message: e.class.name)
+      end
+
+      # Whether the store can send login codes on this OTP channel.
+      def ready?(store, channel)
+        return true if channel.to_s == 'email'
+
+        SpreeNotificationProviders.ready_for?(store, provider_channel(channel), :otp_code)
+      end
+
+      # Where an email code for this attempt would go: the identifier itself for
+      # email-first logins, else the staged email, else the account's real email.
+      def email_destination(attempt)
+        return attempt.identifier if Spree::Otp::Identity.email_identifier?(attempt.identifier)
+        return attempt.staged_email if attempt.staged_email.present?
+
+        email = attempt.user&.email
+        Spree::Otp::Identity.real_email?(email) ? email : nil
+      end
+
+      def destination_for(attempt)
+        attempt.channel == 'email' ? email_destination(attempt) : attempt.identifier
+      end
+    end
+  end
+end

data/app/services/spree/otp/fallback.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Spree
+  module Otp
+    # Sends a fresh login code by email in place of an attempt's WhatsApp code.
+    #
+    # Used for the automatic backup (immediate send failure in Generate, or a
+    # provider's later failure report) and for the customer's "Send code by email
+    # instead" link. Only the new code is valid afterwards.
+    class Fallback
+      prepend Spree::ServiceModule::Base
+
+      # discard_original: destroy the original attempt instead of expiring it
+      #   (its WhatsApp send never went out, so it shouldn't count toward limits).
+      def call(store:, attempt:, reason: nil, enforce_cooldown: true, discard_original: false)
+        config = store.effective_otp_configuration
+        return failure(:email_fallback_disabled, 'Email codes are not available right now.') unless config.email_fallback_enabled?
+
+        # Linking a number to an email-only account needs the WhatsApp code as
+        # proof of the phone; an email code can't replace it.
+        if attempt.link_email_attempt.present?
+          return failure(:email_fallback_disabled, 'Please use the code sent on WhatsApp to link this number.')
+        end
+
+        email = Spree::Otp::Delivery.email_destination(attempt)
+        unless Spree::Otp::Identity.real_email?(email)
+          return failure(:no_email_on_account, 'There is no email on this account to send a code to.')
+        end
+
+        limiter = Spree::Otp::RateLimiter.new(store: store, identifier: attempt.identifier)
+        if enforce_cooldown
+          allowed, reason_code, retry_after = limiter.check_dispatch_allowed(config.resend_cooldown_seconds)
+          unless allowed
+            if reason_code == :hourly_limit_exceeded
+              return failure(:hourly_limit_exceeded, 'Hourly limit of 5 codes exceeded. Please try again later.')
+            end
+
+            return failure(:cooldown_active, { message: "Please wait #{retry_after} seconds before requesting another code.", retry_after_seconds: retry_after })
+          end
+        elsif limiter.hourly_limit_exceeded?
+          return failure(:hourly_limit_exceeded, 'Hourly limit of 5 codes exceeded. Please try again later.')
+        end
+
+        code = Spree::Otp::Generate.generate_code(config.otp_length || 6)
+        salt = Spree::OtpAttempt.generate_salt
+        new_attempt = nil
+
+        ApplicationRecord.transaction do
+          new_attempt = Spree::OtpAttempt.create!(
+            store: store,
+            user: attempt.user,
+            identifier: attempt.identifier,
+            channel: 'email',
+            purpose: 'login',
+            code_digest: Spree::OtpAttempt.digest(code, salt),
+            salt: salt,
+            staged_mobile_number: attempt.staged_mobile_number,
+            staged_email: attempt.staged_email,
+            delivery_status: 'pending',
+            expires_at: (config.otp_expiry_seconds || 600).seconds.from_now,
+            ip_address: attempt.ip_address,
+            user_agent: attempt.user_agent
+          )
+
+          if discard_original
+            attempt.destroy!
+          else
+            attempt.expire!
+            attempt.update_columns(delivery_status: 'fallback_sent', fallback_reason: reason.to_s.truncate(120).presence)
+          end
+        end
+
+        result = Spree::Otp::Delivery.send_email(store: store, to: email, code: code,
+                                                 expiry_minutes: ((config.otp_expiry_seconds || 600) / 60))
+
+        if result.failed?
+          new_attempt.update_columns(delivery_status: 'failed', fallback_reason: result.error_message.to_s.truncate(120))
+          return failure(:delivery_failed, 'Failed to send the code by email.')
+        end
+
+        new_attempt.update_columns(delivery_status: 'submitted', provider_message_id: result.message_id)
+        success(attempt: new_attempt.reload)
+      end
+    end
+  end
+end

data/app/services/spree/otp/generate.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Spree
+  module Otp
+    # Starts a login: finds the account, decides what still has to be collected,
+    # and sends the code.
+    #
+    # Mobile-first (identifier is a phone number, the default storefront flow):
+    #   * account with a real email      -> code sent on the active channel
+    #   * new number / no real email     -> requires_email until an email is given
+    #   * email owned by another mobile  -> :email_linked_to_other_mobile
+    #   * email owned by an account with no mobile -> code on WhatsApp plus a
+    #     second code to that email (link_email child attempt); both are needed
+    #
+    # Email-first (identifier contains "@") keeps the feature-010 behaviour.
+    class Generate
+      prepend Spree::ServiceModule::Base
+
+      def self.generate_code(length)
+        min = 10**(length - 1)
+        max = (10**length) - 1
+        SecureRandom.random_number(min..max).to_s
+      end
+
+      def call(store:, identifier:, mobile_number: nil, email: nil, channel: nil, request_env: {})
+        normalized_identifier, kind = Spree::Otp::Identity.normalize_identifier(identifier)
+        return failure(:invalid_identifier, 'Invalid email or phone number format.') if normalized_identifier.blank?
+
+        config = store.effective_otp_configuration
+        context = kind == 'email' ? email_first(normalized_identifier, mobile_number) : mobile_first(normalized_identifier, email)
+        return context if context.is_a?(Spree::ServiceModule::Result)
+
+        rate_limiter = Spree::Otp::RateLimiter.new(store: store, identifier: normalized_identifier)
+        allowed, reason, retry_after = rate_limiter.check_dispatch_allowed(config.resend_cooldown_seconds)
+        unless allowed
+          if reason == :hourly_limit_exceeded
+            return failure(:hourly_limit_exceeded, 'Hourly limit of 5 codes exceeded. Please try again later.')
+          end
+
+          return failure(:cooldown_active, { message: "Please wait #{retry_after} seconds before requesting another code.", retry_after_seconds: retry_after })
+        end
+
+        active_channel = channel.presence || (kind == 'email' ? 'email' : config.active_channel)
+        expire_previous_attempts(store, normalized_identifier)
+
+        code = self.class.generate_code(config.otp_length || 6)
+        attempt = create_attempt(store, config, normalized_identifier, active_channel, code, context, request_env)
+
+        destination = Spree::Otp::Delivery.destination_for(attempt)
+        if destination.blank?
+          attempt.destroy
+          return failure(:no_email_on_account, 'There is no email on this account to send a code to.')
+        end
+
+        outcome = Spree::Otp::Delivery.deliver(
+          channel: active_channel, store: store, attempt: attempt, destination: destination, code: code,
+          expiry_minutes: ((config.otp_expiry_seconds || 600) / 60)
+        )
+
+        auto_fallback = false
+        if outcome.failed?
+          attempt.update_columns(delivery_status: 'failed', fallback_reason: outcome.error_message.to_s.truncate(120),
+                                 delivery_message_ref: outcome.message_ref)
+
+          fallback = try_email_fallback(store, config, attempt, outcome.error_message, linking: context[:link_user].present?)
+          if fallback&.success?
+            attempt = fallback.value[:attempt]
+            auto_fallback = true
+          else
+            attempt.destroy # Clean up unsent attempt so cooldown isn't unfairly triggered
+            return failure(:delivery_failed, outcome.error_message || 'Failed to deliver passcode.')
+          end
+        else
+          # :unknown may still have gone out, so it is not resent or switched to
+          # email here; a later provider failure report triggers the backup.
+          attempt.update_columns(delivery_status: outcome.sent? ? 'submitted' : 'pending',
+                                 provider_message_id: outcome.message_id, delivery_message_ref: outcome.message_ref)
+        end
+
+        if context[:link_user]
+          link_result = send_link_email_code(store, config, attempt, context[:link_user], request_env)
+          return link_result if link_result
+        end
+
+        success(Spree::Otp::CodeSentPayload.build(attempt: attempt.reload, config: config, auto_fallback: auto_fallback))
+      end
+
+      private
+
+      # Returns a context hash, or a Result to return straight away.
+      def mobile_first(mobile, email)
+        user = Spree.user_class.find_by(mobile_number: mobile)
+        return { user: user } if user && Spree::Otp::Identity.real_email?(user.email)
+
+        normalized_email = Spree::Otp::Identity.normalize_email(email)
+        if normalized_email.blank?
+          return success(Spree::Otp::CodeSentPayload.requires_email(user))
+        end
+        return failure(:invalid_email, 'Please enter a valid email address.') unless Spree::Otp::Identity.valid_email?(normalized_email)
+
+        email_owner = Spree.user_class.find_by('LOWER(email) = ?', normalized_email)
+        if email_owner && email_owner != user
+          if email_owner.mobile_number.present? || user.present?
+            return failure(:email_linked_to_other_mobile,
+                           'This email is already linked to another mobile number. Please sign in with the mobile number linked to that email.')
+          end
+
+          # Email-only account: the customer must also prove they own the email.
+          return { user: email_owner, staged_mobile: mobile, link_user: email_owner }
+        end
+
+        { user: user, staged_email: normalized_email, staged_mobile: user ? nil : mobile }
+      end
+
+      def email_first(email, mobile_number)
+        user = Spree.user_class.find_by('LOWER(email) = ?', email)
+        return { user: user } if user&.mobile_number.present?
+
+        if mobile_number.blank?
+          return success(requires_mobile: true, message: 'Mobile number is required to continue.')
+        end
+
+        normalized_mobile = Spree::Otp::Identity.normalize_phone(mobile_number)
+        return failure(:invalid_phone, 'Invalid mobile phone number format.') unless Spree::Otp::Identity.valid_phone?(normalized_mobile)
+
+        existing_mobile_user = Spree.user_class.find_by(mobile_number: normalized_mobile)
+        if existing_mobile_user && existing_mobile_user.id != user&.id
+          return failure(:phone_already_registered, 'This mobile number is already linked to another account.')
+        end
+
+        { user: user, staged_mobile: normalized_mobile }
+      end
+
+      # Only the newest login code for an identifier is valid.
+      def expire_previous_attempts(store, identifier)
+        Spree::OtpAttempt.where(store: store, identifier: identifier).login.active.find_each(&:expire!)
+      end
+
+      def create_attempt(store, config, identifier, channel, code, context, request_env)
+        salt = Spree::OtpAttempt.generate_salt
+        Spree::OtpAttempt.create!(
+          store: store,
+          user: context[:user],
+          identifier: identifier,
+          channel: channel,
+          purpose: 'login',
+          code_digest: Spree::OtpAttempt.digest(code, salt),
+          salt: salt,
+          staged_mobile_number: context[:staged_mobile],
+          staged_email: context[:staged_email],
+          expires_at: (config.otp_expiry_seconds || 600).seconds.from_now,
+          ip_address: request_env[:ip_address],
+          user_agent: request_env[:user_agent]&.truncate(255)
+        )
+      end
+
+      # Linking a number to an email-only account needs proof of the phone, so
+      # the email backup can't stand in for the WhatsApp code there.
+      def try_email_fallback(store, config, attempt, reason, linking:)
+        return nil if linking || attempt.channel == 'email' || !config.email_fallback_enabled?
+
+        Spree::Otp::Fallback.call(store: store, attempt: attempt, reason: reason, enforce_cooldown: false, discard_original: true)
+      end
+
+      # Second code for the "link this number to an email-only account" case.
+      # Returns a failure Result when it can't be sent, else nil.
+      def send_link_email_code(store, config, attempt, link_user, request_env)
+        code = self.class.generate_code(config.otp_length || 6)
+        salt = Spree::OtpAttempt.generate_salt
+        child = Spree::OtpAttempt.create!(
+          store: store,
+          user: link_user,
+          parent_attempt: attempt,
+          identifier: link_user.email.downcase,
+          channel: 'email',
+          purpose: 'link_email',
+          code_digest: Spree::OtpAttempt.digest(code, salt),
+          salt: salt,
+          expires_at: attempt.expires_at,
+          ip_address: request_env[:ip_address],
+          user_agent: request_env[:user_agent]&.truncate(255)
+        )
+
+        result = Spree::Otp::Delivery.send_email(store: store, to: child.identifier, code: code,
+                                                 expiry_minutes: ((config.otp_expiry_seconds || 600) / 60))
+        if result.failed?
+          attempt.destroy
+          return failure(:delivery_failed, 'Failed to send the code to your email.')
+        end
+
+        child.update_columns(delivery_status: 'submitted', provider_message_id: result.message_id)
+        nil
+      end
+    end
+  end
+end