spree_otp_auth 0.2.0

data/app/views/spree/otp_mailer/send_otp.text.erb

@@ -0,0 +1,8 @@
+<%= @store.name %> Verification Code
+========================================
+
+Your verification code is: <%= @code %>
+
+This code expires in <%= @expiry_minutes %> minutes.
+
+If you did not request this login code, please safely disregard this email.

data/config/locales/en.yml

@@ -0,0 +1,39 @@
+en:
+  spree:
+    admin:
+      tab:
+        otp_authentication: "OTP Authentication"
+    otp_authentication: "OTP Authentication"
+    otp_auth:
+      admin:
+        title: "OTP Authentication Settings"
+        update_success: "OTP authentication settings updated successfully."
+        channel_header: "Channel & Timing Configuration"
+        active_channel: "Active OTP Channel"
+        otp_length: "OTP Length"
+        otp_expiry_seconds: "OTP Expiry (seconds)"
+        resend_cooldown_seconds: "Resend Cooldown (seconds)"
+        fallback_delay_seconds: "WhatsApp Fallback Delay (seconds)"
+        msg91_header: "MSG91 Provider Credentials & DLT Templates"
+        msg91_auth_key: "MSG91 Auth Key"
+        msg91_sender_id: "Sender ID (Header)"
+        msg91_sms_template_id: "SMS Template ID"
+        msg91_whatsapp_template_id: "WhatsApp Template ID"
+        gupshup_header: "WhatsApp via Gupshup"
+        gupshup_source_number: "Business WhatsApp number"
+        gupshup_app_name: "Gupshup app name"
+        gupshup_app_id: "Gupshup app ID"
+        gupshup_template_name: "Template name"
+        gupshup_template_id: "Template ID (optional)"
+        gupshup_api_key_status: "API key"
+        gupshup_webhook_url: "Delivery callback URL"
+        email_backup: "Email backup"
+        test_whatsapp: "Send test WhatsApp"
+      errors:
+        requires_email: "Please enter your email address to continue."
+        invalid_email: "Please enter a valid email address."
+        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."
+        invalid_email_code: "The code sent to your email is incorrect or expired."
+        email_fallback_disabled: "Email codes are not available right now."
+        no_email_on_account: "There is no email on this account to send a code to."
+        whatsapp_not_ready: "WhatsApp can't be switched on yet."

data/config/routes.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+Spree::Core::Engine.add_routes do
+  namespace :api, defaults: { format: 'json' } do
+    namespace :v3 do
+      namespace :store do
+        scope :otp, controller: 'otp' do
+          post :request, action: :request_otp
+          post :verify, action: :verify
+          post :resend, action: :resend
+          post :fallback, action: :fallback
+          post :status, action: :delivery_status
+          patch 'customer/mobile', action: :update_mobile
+        end
+      end
+    end
+  end
+
+  namespace :admin do
+    resource :otp_configuration, only: [:edit, :update]
+  end
+end

data/db/migrate/20260927000001_create_spree_otp_configurations.spree_otp_auth.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateSpreeOtpConfigurations < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_otp_configurations do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }, index: { unique: true }
+      t.string :active_channel, null: false, default: 'email'
+      t.integer :otp_length, null: false, default: 6
+      t.integer :otp_expiry_seconds, null: false, default: 600
+      t.integer :resend_cooldown_seconds, null: false, default: 30
+      t.integer :fallback_delay_seconds, null: false, default: 20
+      t.text :msg91_auth_key
+      t.string :msg91_sms_template_id
+      t.string :msg91_whatsapp_template_id
+      t.string :msg91_sender_id
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260927000002_create_spree_otp_attempts.spree_otp_auth.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class CreateSpreeOtpAttempts < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_otp_attempts do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }, index: true
+      t.references :user, foreign_key: { to_table: :spree_users }, index: true
+      t.string :identifier, null: false
+      t.string :channel, null: false
+      t.string :code_digest, null: false
+      t.string :salt, null: false
+      t.integer :attempts_count, null: false, default: 0
+      t.integer :max_attempts, null: false, default: 5
+      t.datetime :expires_at, null: false
+      t.datetime :verified_at
+      t.string :ip_address
+      t.string :user_agent
+
+      t.timestamps
+    end
+
+    add_index :spree_otp_attempts, [:identifier, :expires_at]
+    add_index :spree_otp_attempts, :verified_at
+    add_index :spree_otp_attempts, :created_at
+  end
+end

data/db/migrate/20260927000003_add_otp_fields_to_spree_users.spree_otp_auth.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class AddOtpFieldsToSpreeUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :spree_users, :auth_identifier, :string unless column_exists?(:spree_users, :auth_identifier)
+    add_column :spree_users, :auth_channel, :string, default: 'email', null: false unless column_exists?(:spree_users, :auth_channel)
+    add_column :spree_users, :mobile_number, :string unless column_exists?(:spree_users, :mobile_number)
+
+    add_index :spree_users, :auth_identifier unless index_exists?(:spree_users, :auth_identifier)
+    add_index :spree_users, :mobile_number, unique: true, where: "mobile_number IS NOT NULL AND mobile_number != ''", name: 'idx_spree_users_on_unique_mobile_number' unless index_exists?(:spree_users, :mobile_number, name: 'idx_spree_users_on_unique_mobile_number')
+  end
+end

data/db/migrate/20260927000004_update_otp_schema_for_mandatory_mobile_and_templates.spree_otp_auth.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class UpdateOtpSchemaForMandatoryMobileAndTemplates < ActiveRecord::Migration[8.1]
+  def change
+    # 1. spree_otp_configurations: fallback channel and email template association
+    unless column_exists?(:spree_otp_configurations, :fallback_channel)
+      add_column :spree_otp_configurations, :fallback_channel, :string, default: 'none', null: false
+    end
+
+    unless column_exists?(:spree_otp_configurations, :email_template_id)
+      if table_exists?(:spree_email_templates)
+        add_reference :spree_otp_configurations, :email_template, foreign_key: { to_table: :spree_email_templates }, index: true
+      else
+        add_reference :spree_otp_configurations, :email_template, index: true
+      end
+    end
+
+    # 2. spree_otp_attempts: staged mobile number for progressive disclosure flow
+    unless column_exists?(:spree_otp_attempts, :staged_mobile_number)
+      add_column :spree_otp_attempts, :staged_mobile_number, :string
+    end
+
+    # 3. spree_users: confirmed at timestamp for mobile phone verification
+    unless column_exists?(:spree_users, :mobile_confirmed_at)
+      add_column :spree_users, :mobile_confirmed_at, :datetime
+    end
+  end
+end

data/db/migrate/20261018000001_add_gupshup_fields_to_spree_otp_configurations.spree_otp_auth.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class AddGupshupFieldsToSpreeOtpConfigurations < ActiveRecord::Migration[8.1]
+  def change
+    add_column :spree_otp_configurations, :gupshup_source_number, :string unless column_exists?(:spree_otp_configurations, :gupshup_source_number)
+    add_column :spree_otp_configurations, :gupshup_app_name, :string unless column_exists?(:spree_otp_configurations, :gupshup_app_name)
+    add_column :spree_otp_configurations, :gupshup_app_id, :string unless column_exists?(:spree_otp_configurations, :gupshup_app_id)
+    unless column_exists?(:spree_otp_configurations, :gupshup_template_name)
+      add_column :spree_otp_configurations, :gupshup_template_name, :string, default: 'verify_otp'
+    end
+    add_column :spree_otp_configurations, :gupshup_template_id, :string unless column_exists?(:spree_otp_configurations, :gupshup_template_id)
+
+    # New stores default to WhatsApp with email backup. Existing rows keep their
+    # channel until an admin switches after a successful test send.
+    change_column_default :spree_otp_configurations, :active_channel, from: 'email', to: 'whatsapp'
+    change_column_default :spree_otp_configurations, :fallback_channel, from: 'none', to: 'email'
+  end
+end

data/db/migrate/20261018000002_add_delivery_fields_to_spree_otp_attempts.spree_otp_auth.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class AddDeliveryFieldsToSpreeOtpAttempts < ActiveRecord::Migration[8.1]
+  def change
+    change_table :spree_otp_attempts, bulk: true do |t|
+      t.string :purpose, null: false, default: 'login' unless column_exists?(:spree_otp_attempts, :purpose)
+      t.string :staged_email unless column_exists?(:spree_otp_attempts, :staged_email)
+      t.string :provider_message_id unless column_exists?(:spree_otp_attempts, :provider_message_id)
+      t.string :delivery_status, null: false, default: 'pending' unless column_exists?(:spree_otp_attempts, :delivery_status)
+      t.string :fallback_reason unless column_exists?(:spree_otp_attempts, :fallback_reason)
+    end
+
+    unless column_exists?(:spree_otp_attempts, :parent_attempt_id)
+      add_reference :spree_otp_attempts, :parent_attempt, foreign_key: { to_table: :spree_otp_attempts }, index: true
+    end
+    add_index :spree_otp_attempts, :provider_message_id unless index_exists?(:spree_otp_attempts, :provider_message_id)
+  end
+end

data/db/migrate/20261018000003_add_email_marketing_decided_at_to_spree_users.spree_otp_auth.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class AddEmailMarketingDecidedAtToSpreeUsers < ActiveRecord::Migration[8.1]
+  # Null = the customer never made a news-and-offers choice; with
+  # accepts_email_marketing = false and a timestamp, they opted out.
+  def up
+    add_column :spree_users, :email_marketing_decided_at, :datetime unless column_exists?(:spree_users, :email_marketing_decided_at)
+
+    # Customers already on a verified newsletter subscription count as
+    # subscribed, decided when they first subscribed.
+    execute <<~SQL.squish
+      UPDATE spree_users u
+      SET accepts_email_marketing = TRUE,
+          email_marketing_decided_at = s.first_subscribed_at
+      FROM (
+        SELECT COALESCE(ns.user_id, matched.id) AS user_id, MIN(ns.created_at) AS first_subscribed_at
+        FROM spree_newsletter_subscribers ns
+        LEFT JOIN spree_users matched
+          ON ns.user_id IS NULL AND LOWER(matched.email) = LOWER(ns.email)
+        WHERE ns.verified_at IS NOT NULL
+        GROUP BY COALESCE(ns.user_id, matched.id)
+      ) s
+      WHERE s.user_id IS NOT NULL AND u.id = s.user_id
+    SQL
+  end
+
+  def down
+    remove_column :spree_users, :email_marketing_decided_at if column_exists?(:spree_users, :email_marketing_decided_at)
+  end
+end

data/db/migrate/20261019000004_add_delivery_message_ref_to_spree_otp_attempts.spree_otp_auth.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddDeliveryMessageRefToSpreeOtpAttempts < ActiveRecord::Migration[8.1]
+  def change
+    add_column :spree_otp_attempts, :delivery_message_ref, :uuid unless column_exists?(:spree_otp_attempts, :delivery_message_ref)
+    add_index :spree_otp_attempts, :delivery_message_ref unless index_exists?(:spree_otp_attempts, :delivery_message_ref)
+  end
+end

data/lib/generators/spree_otp_auth/install/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module SpreeOtpAuth
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc 'Install spree_otp_auth migrations and assets'
+
+      class_option :migrate, type: :boolean, default: true, banner: 'Run migrations'
+
+      # spree_otp_auth sends codes through spree_notification_providers, so its
+      # tables are installed too (already-copied migrations are skipped).
+      def add_migrations
+        run 'bundle exec rake railties:install:migrations FROM=spree_notification_providers,spree_otp_auth'
+      end
+
+      def run_migrations
+        if options[:migrate]
+          run 'bundle exec rake db:migrate'
+        else
+          say_status :skipping, 'db:migrate, remember to run migrations manually'
+        end
+      end
+    end
+  end
+end

data/lib/spree_otp_auth/engine.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SpreeOtpAuth
+  class Engine < ::Rails::Engine
+    engine_name 'spree_otp_auth'
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    # The verify endpoint takes the one-time code as `code`; keep it out of the
+    # "Parameters:" log lines. Exact match so promo_code, country_code, etc.
+    # stay readable.
+    initializer 'spree_otp_auth.filter_parameters' do |app|
+      app.config.filter_parameters += [/\Acode\z/]
+    end
+
+    # OTP codes go out through spree_notification_providers; the code's
+    # provider-side template is entered per provider under "Login code".
+    initializer 'spree_otp_auth.message_types' do
+      SpreeNotificationProviders.register_message_type :otp_code,
+                                                       label: 'Login code', channels: %i[email sms whatsapp]
+    end
+
+    # A provider that reports a code as failed after accepting it (e.g. a
+    # Gupshup "failed" webhook) triggers the email backup. Messages sent before
+    # spree_notification_providers have no delivery row, so the webhook asks
+    # this resolver which store owns the message id.
+    config.after_initialize do
+      Spree.subscribers << Spree::Otp::DeliveryFailedSubscriber
+      SpreeNotificationProviders.register_message_resolver(:gupshup) do |provider_message_id|
+        Spree::OtpAttempt.find_by(provider_message_id: provider_message_id, channel: 'whatsapp')&.store
+      end
+    end
+
+    def self.activate
+      Dir.glob(File.join(File.dirname(__FILE__), '../../app/**/*_decorator*.rb')) do |c|
+        Rails.configuration.cache_classes ? require(c) : load(c)
+      end
+    end
+
+    config.to_prepare(&method(:activate).to_proc)
+  end
+end

data/lib/spree_otp_auth/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SpreeOtpAuth
+  VERSION = '0.2.0'
+end

data/lib/spree_otp_auth.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'spree/core'
+require 'spree_notification_providers'
+require 'spree_otp_auth/version'
+require 'spree_otp_auth/engine'
+
+module SpreeOtpAuth
+  # Domain of the placeholder email given to accounts created from a mobile
+  # number alone ("<digits>@guest.example.invalid"). Such emails count as
+  # "no email". Set it in an initializer to match your storefront:
+  #   SpreeOtpAuth.synthetic_email_domain = '@guest.example.local'
+  mattr_accessor :synthetic_email_domain, default: '@guest.example.invalid'
+
+  # Optional model (class name) for admin-editable OTP email templates. Its
+  # records need `name`, `render_subject(vars)` and `render_body(vars)`, and
+  # may be scoped by a `store_id` column. Unset: the built-in mailer view is used.
+  #   SpreeOtpAuth.email_template_class = 'Spree::EmailTemplate'
+  mattr_accessor :email_template_class, default: nil
+
+  def self.email_template_model
+    email_template_class.presence&.safe_constantize
+  end
+
+  class Error < StandardError; end
+  class DeliveryError < Error; end
+  class RateLimitError < Error; end
+end

data/spree_otp_auth.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'lib/spree_otp_auth/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'spree_otp_auth'
+  spec.version     = SpreeOtpAuth::VERSION
+  spec.authors     = ['ONTODI']
+  spec.summary     = 'Passwordless multi-channel OTP authentication and login-gated checkout for Spree Commerce'
+  spec.description = <<~DESC.strip
+    Provides mandatory login-gated checkout, passwordless customer authentication over WhatsApp,
+    SMS or email with an automatic email backup, and store-scoped admin configuration. Codes are
+    delivered through spree_notification_providers, so any provider and priority order works.
+  DESC
+  spec.license = 'BSD-3-Clause'
+
+  spec.required_ruby_version = '>= 3.3'
+
+  spec.files = Dir[
+    '{app,config,db,lib}/**/*',
+    'README.md',
+    'CHANGELOG.md',
+    'LICENSE',
+    'spree_otp_auth.gemspec'
+  ]
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'rails', '>= 8.0'
+  spec.add_dependency 'spree', '>= 5.5'
+  spec.add_dependency 'spree_core', '>= 5.5'
+  spec.add_dependency 'spree_api', '>= 5.5'
+  spec.add_dependency 'spree_notification_providers', '~> 0.1'
+  spec.add_dependency 'spree_admin', '>= 5.5'
+
+  spec.homepage = 'https://github.com/kalanjiyaVishnu/spree_otp_auth'
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

metadata

@@ -0,0 +1,167 @@
+--- !ruby/object:Gem::Specification
+name: spree_otp_auth
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- ONTODI
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: spree
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.5'
+- !ruby/object:Gem::Dependency
+  name: spree_core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.5'
+- !ruby/object:Gem::Dependency
+  name: spree_api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.5'
+- !ruby/object:Gem::Dependency
+  name: spree_notification_providers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: spree_admin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.5'
+description: |-
+  Provides mandatory login-gated checkout, passwordless customer authentication over WhatsApp,
+  SMS or email with an automatic email backup, and store-scoped admin configuration. Codes are
+  delivered through spree_notification_providers, so any provider and priority order works.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/controllers/spree/admin/otp_configurations_controller.rb
+- app/controllers/spree/api/v3/store/otp_controller.rb
+- app/mailers/spree/otp_mailer.rb
+- app/models/spree/otp_attempt.rb
+- app/models/spree/otp_configuration.rb
+- app/models/spree/otp_store_decorator.rb
+- app/models/spree/otp_user_decorator.rb
+- app/services/spree/otp/code_sent_payload.rb
+- app/services/spree/otp/delivery.rb
+- app/services/spree/otp/fallback.rb
+- app/services/spree/otp/generate.rb
+- app/services/spree/otp/identity.rb
+- app/services/spree/otp/marketing_consent.rb
+- app/services/spree/otp/rate_limiter.rb
+- app/services/spree/otp/resend.rb
+- app/services/spree/otp/verify.rb
+- app/subscribers/spree/otp/delivery_failed_subscriber.rb
+- app/views/spree/admin/otp_configurations/edit.html.erb
+- app/views/spree/otp_mailer/send_otp.html.erb
+- app/views/spree/otp_mailer/send_otp.text.erb
+- config/locales/en.yml
+- config/routes.rb
+- db/migrate/20260927000001_create_spree_otp_configurations.spree_otp_auth.rb
+- db/migrate/20260927000002_create_spree_otp_attempts.spree_otp_auth.rb
+- db/migrate/20260927000003_add_otp_fields_to_spree_users.spree_otp_auth.rb
+- db/migrate/20260927000004_update_otp_schema_for_mandatory_mobile_and_templates.spree_otp_auth.rb
+- db/migrate/20261018000001_add_gupshup_fields_to_spree_otp_configurations.spree_otp_auth.rb
+- db/migrate/20261018000002_add_delivery_fields_to_spree_otp_attempts.spree_otp_auth.rb
+- db/migrate/20261018000003_add_email_marketing_decided_at_to_spree_users.spree_otp_auth.rb
+- db/migrate/20261019000004_add_delivery_message_ref_to_spree_otp_attempts.spree_otp_auth.rb
+- lib/generators/spree_otp_auth/install/install_generator.rb
+- lib/spree_otp_auth.rb
+- lib/spree_otp_auth/engine.rb
+- lib/spree_otp_auth/version.rb
+- spree_otp_auth.gemspec
+homepage: https://github.com/kalanjiyaVishnu/spree_otp_auth
+licenses:
+- BSD-3-Clause
+metadata:
+  source_code_uri: https://github.com/kalanjiyaVishnu/spree_otp_auth
+  changelog_uri: https://github.com/kalanjiyaVishnu/spree_otp_auth/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Passwordless multi-channel OTP authentication and login-gated checkout for
+  Spree Commerce
+test_files: []