verify_it 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0638bdc85958eb337d3239d426d9b68a640d1130614406711dad37c1da11c7a2'
-  data.tar.gz: 7c40e0432c8e2627c26cbfac91b32f13358fa13a476cb22bc922d3fa1d5db897
+  metadata.gz: be733b2c9a751f9163ffcc41c67a22c88b19a92baf8e8e5d478f0d2cfb3c1c3b
+  data.tar.gz: fb2580dd55fda49704fa8c327721eda31d470fff6f8f4177adb3741d24d89553
 SHA512:
-  metadata.gz: 159d3ae1264b6095b229c4d5d24a925074c1a49c7be7894b44d1c9a8dfb5f87e840f569f5b54ba9d6b968d3092d34dfe1e9d2d5fb608101d1a730c75f572421d
-  data.tar.gz: 46c8621291849844500dfb31753870e7d7de574dbb178c1db318fe64a680cf612110361b162479cb5521047f319d8e609443f5f1f1a7d022a26d5cd0ec8c0fd5
+  metadata.gz: d87fdcf7e40044a25259f945151644337b21d6e404e6fc793a3b9d856f745da23fe1014e34a7240d1386ca24a7e096b2233c19548e0ba8a86470faf98eb459db
+  data.tar.gz: bf5ef12903fe759e87de6ff9cd6bda4cb53b4abe3fe5c71aaae00c63a0efd3f2290abdff32706e0b7868e276a68580d78af847a15d82beab19531a522703e5dc

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+## [0.5.0] - 2026-03-22
+
+### Added
+- **IP-based rate limiting** — new opt-in configuration options `max_ip_send_attempts`
+  and `max_ip_verification_attempts` protect against SMS pumping, distributed brute
+  force, and IP-based abuse. Both default to `nil` (disabled). When configured, IP
+  attempts are tracked using the existing storage backends with no schema changes required.
+- `Verifier#send_code` now accepts an optional `request:` keyword, matching
+  `verify_code`. The engine controller and `Verifiable` concern forward it automatically.
+- `RateLimiter` gains `ip_send_rate_limited?`, `ip_verification_rate_limited?`,
+  `record_ip_send_attempt`, and `record_ip_verification_attempt` methods.
+- `Verifiable#send_{channel}_code` now accepts an optional `request:` keyword.
+
+### Fixed
+- **DatabaseStorage race conditions** — `store_code` and `increment_attempt_count`
+  now use atomic patterns with `rescue ActiveRecord::RecordNotUnique` + retry,
+  preventing duplicate records and rate limit bypass under concurrency.
+- Migration template indexes on `verify_it_codes` and `verify_it_attempts` are now
+  `unique: true`, enforcing data integrity at the database level.
+- `Attempt` model validation now accepts `ip_send` and `ip_verification` attempt types.
+
+### Changed
+- README: generator commands now show the bare command first; `--storage` and
+  `--engine` are documented as opt-in flags with defaults explained
+- README: moved Rails Engine section right after Rails Setup, before Plain Ruby,
+  so all Rails content is grouped together
+- README: Plain Ruby examples use `record: user` instead of `record: current_user`
+  to avoid implying a Rails dependency
+- README: Engine section notes that `--engine` already generates mount and resolver
+  config, so users don't duplicate setup
+- README: Engine resolver example no longer hardcodes Redis storage; replaced with
+  a storage-agnostic comment pointing to the Configuration Reference
+
 ## [0.4.2] - 2026-03-21
 
 ### Added

data/README.md

@@ -35,21 +35,21 @@ bundle install
 ### 1. Generate configuration files
 
 ```bash
-rails generate verify_it:install --storage=redis
+rails generate verify_it:install
 ```
 
-The installer generates:
-
-- `config/initializers/verify_it.rb` — your main configuration
-- A database migration (if you chose `--storage=database`)
+Available options:
+- `--storage=memory|redis|database` (default: `memory`)
+- `--engine` — mount the VerifyIt engine and generate resolver config
 
-Pass `--engine` to also mount the engine routes and generate resolver config:
+Examples:
 
 ```bash
-rails generate verify_it:install --storage=redis --engine
+rails generate verify_it:install --storage=redis
+rails generate verify_it:install --storage=database --engine
 ```
 
-If you chose database storage, run:
+If you chose `--storage=database`, run the migration:
 
 ```bash
 rails db:migrate
@@ -165,32 +165,6 @@ current_user.send_email_code(context: {
 
 ---
 
-## Plain Ruby
-
-```ruby
-require "verify_it"
-
-VerifyIt.configure do |config|
-  config.secret_key_base = ENV.fetch("VERIFY_IT_SECRET")
-  config.storage         = :memory  # :memory, :redis, or :database
-
-  config.sms_sender = ->(to:, code:, context:) {
-    MySmsSender.deliver(to: to, body: "Your code: #{code}")
-  }
-end
-
-# Send a code
-result = VerifyIt.send_code(to: "+15551234567", channel: :sms, record: current_user)
-
-# Verify a code
-result = VerifyIt.verify_code(to: "+15551234567", code: "123456", record: current_user)
-
-# Clean up
-VerifyIt.cleanup(to: "+15551234567", record: current_user)
-```
-
----
-
 ## Rails Engine (HTTP Endpoints)
 
 VerifyIt ships a mountable Rails Engine that exposes two JSON endpoints. Use the
@@ -198,6 +172,8 @@ engine when you want drop-in endpoints without writing controller code. This is
 optional - skip this section if you prefer to handle verification in your own
 controllers using the `Verifiable` concern or the plain Ruby API.
 
+> If you ran the installer with `--engine`, the mount and resolver config are already generated for you. The details below are for reference or manual setup.
+
 ### Mount the engine
 
 ```ruby
@@ -220,8 +196,7 @@ Two additional config options are **required** when using the engine endpoints:
 # config/initializers/verify_it.rb
 VerifyIt.configure do |config|
   config.secret_key_base = Rails.application.secret_key_base
-  config.storage         = :redis
-  config.redis_client    = Redis.new
+  # ... your storage config (see Configuration Reference) ...
 
   # Resolve the authenticated record from the request (e.g. from a session or JWT).
   config.current_record_resolver = ->(request) {
@@ -291,6 +266,32 @@ en:
 
 ---
 
+## Plain Ruby
+
+```ruby
+require "verify_it"
+
+VerifyIt.configure do |config|
+  config.secret_key_base = ENV.fetch("VERIFY_IT_SECRET")
+  config.storage         = :memory  # :memory, :redis, or :database
+
+  config.sms_sender = ->(to:, code:, context:) {
+    MySmsSender.deliver(to: to, body: "Your code: #{code}")
+  }
+end
+
+# Send a code
+result = VerifyIt.send_code(to: "+15551234567", channel: :sms, record: user)
+
+# Verify a code
+result = VerifyIt.verify_code(to: "+15551234567", code: "123456", record: user)
+
+# Clean up
+VerifyIt.cleanup(to: "+15551234567", record: user)
+```
+
+---
+
 ## Configuration Reference
 
 | Option | Default | Accepted values |
@@ -304,6 +305,8 @@ en:
 | `max_send_attempts` | `3` | Integer |
 | `max_verification_attempts` | `5` | Integer |
 | `max_identifier_changes` | `5` | Integer |
+| `max_ip_send_attempts` | `nil` | Integer or `nil` (disabled) — max sends per IP per window |
+| `max_ip_verification_attempts` | `nil` | Integer or `nil` (disabled) — max verifications per IP per window |
 | `rate_limit_window` | `3600` | Seconds (integer) |
 | `delivery_channel` | `:sms` | `:sms`, `:email` |
 | `sms_sender` | `nil` | Lambda `(to:, code:, context:) { }` |
@@ -400,6 +403,16 @@ end
 - Use `:redis` or `:database` storage in production
 - Keep `code_ttl` short.
 - Use `on_verify_failure` to monitor and alert on repeated failures
+- **IP-based rate limiting** — enable `max_ip_send_attempts` and `max_ip_verification_attempts` to protect against SMS pumping and distributed brute force attacks:
+
+```ruby
+VerifyIt.configure do |config|
+  config.max_ip_send_attempts = 10          # max 10 sends per IP per window
+  config.max_ip_verification_attempts = 20  # max 20 verifications per IP per window
+end
+```
+
+IP rate limiting requires passing `request:` to `send_code`/`verify_code`. The engine controller does this automatically. For custom controllers, pass `request:` explicitly.
 
 ---
 

data/app/controllers/verify_it/verifications_controller.rb

@@ -13,7 +13,7 @@ module VerifyIt
 
       channel    = resolve_channel
       identifier = resolve_identifier(record, channel)
-      result     = VerifyIt.send_code(to: identifier, record: record, channel: channel, context: {})
+      result     = VerifyIt.send_code(to: identifier, record: record, channel: channel, context: {}, request: request)
 
       if result.success?
         payload = { message: I18n.t("verify_it.responses.sent") }

data/config/locales/en.yml

@@ -9,6 +9,7 @@ en:
       code_not_found: "No active verification code found. Please request a new one."
       locked: "Your account is temporarily locked due to too many failed attempts."
       delivery_failed: "Failed to deliver verification code. Please try again."
+      ip_rate_limited: "Too many requests from this IP address. Please try again later."
     sms:
       default_message: "%{code} is your verification code."
     email:

data/lib/generators/verify_it/install/templates/create_verify_it_tables.rb

@@ -8,7 +8,7 @@ class CreateVerifyItTables < ActiveRecord::Migration[<%= ActiveRecord::Migration
       t.datetime :expires_at, null: false
       t.timestamps
 
-      t.index [:identifier, :record_type, :record_id], name: "index_verify_it_codes_on_record"
+      t.index [:identifier, :record_type, :record_id], name: "index_verify_it_codes_on_record", unique: true
       t.index :expires_at
     end
 
@@ -22,7 +22,7 @@ class CreateVerifyItTables < ActiveRecord::Migration[<%= ActiveRecord::Migration
       t.timestamps
 
       t.index [:identifier, :record_type, :record_id, :attempt_type],
-              name: "index_verify_it_attempts_on_record_and_type"
+              name: "index_verify_it_attempts_on_record_and_type", unique: true
       t.index :expires_at
     end
 

data/lib/verify_it/configuration.rb

@@ -21,6 +21,8 @@ module VerifyIt
                   :test_mode,
                   :bypass_delivery,
                   :secret_key_base,
+                  :max_ip_send_attempts,
+                  :max_ip_verification_attempts,
                   :current_record_resolver,
                   :identifier_resolver
 
@@ -55,6 +57,8 @@ module VerifyIt
       @test_mode = false
       @bypass_delivery = false
       @secret_key_base = nil
+      @max_ip_send_attempts = nil
+      @max_ip_verification_attempts = nil
       @current_record_resolver = nil
       @identifier_resolver = nil
     end

data/lib/verify_it/rate_limiter.rb

@@ -64,5 +64,29 @@ module VerifyIt
     def reset_verification_attempts(identifier:, record:)
       @storage.reset_attempts(identifier: identifier, record: record)
     end
+
+    def ip_send_rate_limited?(ip:)
+      max = VerifyIt.configuration.max_ip_send_attempts
+      return false unless max
+
+      count = @storage.send_count(identifier: ip, record: nil)
+      count >= max
+    end
+
+    def ip_verification_rate_limited?(ip:)
+      max = VerifyIt.configuration.max_ip_verification_attempts
+      return false unless max
+
+      count = @storage.attempts(identifier: ip, record: nil)
+      count >= max
+    end
+
+    def record_ip_send_attempt(ip:)
+      @storage.increment_send_count(identifier: ip, record: nil)
+    end
+
+    def record_ip_verification_attempt(ip:)
+      @storage.increment_attempts(identifier: ip, record: nil)
+    end
   end
 end

data/lib/verify_it/storage/database_storage.rb

@@ -25,13 +25,14 @@ module VerifyIt
           attrs[:record_id] = record.id
         end
 
-        # Find existing or create new
         existing = find_code(identifier: identifier, record: record)
         if existing
-          existing.update!(attrs)
+          existing.update!(code: code, expires_at: expires_at)
         else
           Models::Code.create!(attrs)
         end
+      rescue ActiveRecord::RecordNotUnique
+        retry
       end
 
       def fetch_code(identifier:, record:)
@@ -146,48 +147,41 @@ module VerifyIt
       end
 
       def find_attempt(identifier:, record:, attempt_type:)
+        build_attempt_scope(identifier:, record:, attempt_type:).first
+      end
+
+      def build_attempt_scope(identifier:, record:, attempt_type:)
         scope = Models::Attempt
                 .for_identifier(identifier)
                 .where(attempt_type: attempt_type)
 
         scope = scope.for_record(record) if record
-        scope.first
+        scope
       end
 
       def increment_attempt_count(identifier:, record:, attempt_type:)
-        attempt = find_attempt(
-          identifier: identifier,
-          record: record,
-          attempt_type: attempt_type
-        )
+        # Clean expired attempts first
+        build_attempt_scope(identifier:, record:, attempt_type:).expired.delete_all
 
         window = VerifyIt.configuration.rate_limit_window
         expires_at = Time.now + window
+        attrs = {
+          identifier: identifier.to_s,
+          attempt_type: attempt_type,
+          count: 0,
+          expires_at: expires_at
+        }
 
-        if attempt.nil? || attempt.expired?
-          # Create new attempt record
-          attrs = {
-            identifier: identifier.to_s,
-            attempt_type: attempt_type,
-            count: 1,
-            expires_at: expires_at
-          }
-
-          if record
-            attrs[:record_type] = record.class.name
-            attrs[:record_id] = record.id
-          end
-
-          # Delete old expired attempt if exists
-          attempt&.destroy
-
-          Models::Attempt.create!(attrs)
-          1
-        else
-          # Increment existing
-          attempt.increment!(:count)
-          attempt.count
+        if record
+          attrs[:record_type] = record.class.name
+          attrs[:record_id] = record.id
         end
+
+        attempt = build_attempt_scope(identifier:, record:, attempt_type:).first_or_create!(attrs)
+        attempt.increment!(:count)
+        attempt.count
+      rescue ActiveRecord::RecordNotUnique
+        retry
       end
 
       def get_attempt_count(identifier:, record:, attempt_type:)

data/lib/verify_it/storage/models/attempt.rb

@@ -7,7 +7,7 @@ module VerifyIt
         self.table_name = "verify_it_attempts"
 
         validates :identifier, presence: true
-        validates :attempt_type, presence: true, inclusion: { in: %w[verification send] }
+        validates :attempt_type, presence: true, inclusion: { in: %w[verification send ip_send ip_verification] }
         validates :count, presence: true, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
         validates :expires_at, presence: true
 

data/lib/verify_it/verifiable.rb

@@ -20,13 +20,14 @@ module VerifyIt
 
         raise ArgumentError, "Method #{send_method} is already defined on #{name}" if method_defined?(send_method)
 
-        define_method(send_method) do |context: {}|
+        define_method(send_method) do |context: {}, request: nil|
           identifier = send(attribute)
           VerifyIt.send_code(
             to: identifier,
             record: self,
             channel: channel,
-            context: context
+            context: context,
+            request: request
           )
         end
 

data/lib/verify_it/verifier.rb

@@ -11,9 +11,14 @@ module VerifyIt
       @rate_limiter = RateLimiter.new(storage)
     end
 
-    def send_code(to:, record:, channel: nil, context: {})
+    def send_code(to:, record:, channel: nil, context: {}, request: nil)
       channel ||= config.delivery_channel
 
+      ip = extract_ip(request)
+      if ip && rate_limiter.ip_send_rate_limited?(ip: ip)
+        return rate_limited_result("IP address rate limited for sending")
+      end
+
       rate_limit_result = check_send_rate_limits(to: to, record: record)
       return rate_limit_result if rate_limit_result
 
@@ -27,10 +32,17 @@ module VerifyIt
       )
       return delivery_result if delivery_result
 
+      rate_limiter.record_ip_send_attempt(ip: ip) if ip
+
       finalize_send(to: to, record: record, channel: channel, code_data: code_data)
     end
 
     def verify_code(to:, code:, record:, request: nil)
+      ip = extract_ip(request)
+      if ip && rate_limiter.ip_verification_rate_limited?(ip: ip)
+        return rate_limited_result("IP address rate limited for verification")
+      end
+
       rate_limit_result = check_verification_rate_limit(to: to, record: record)
       return rate_limit_result if rate_limit_result
 
@@ -38,6 +50,7 @@ module VerifyIt
       return code_not_found_result unless stored_code
 
       current_attempts = rate_limiter.record_verification_attempt(identifier: to, record: record)
+      rate_limiter.record_ip_verification_attempt(ip: ip) if ip
 
       if code_matches?(code, stored_code)
         handle_verification_success(to: to, record: record, attempts: current_attempts, request: request)
@@ -159,6 +172,16 @@ module VerifyIt
       end
     end
 
+    def extract_ip(request)
+      return nil unless request
+
+      if request.respond_to?(:remote_ip)
+        request.remote_ip
+      elsif request.respond_to?(:ip)
+        request.ip
+      end
+    end
+
     def invoke_callback(callback, **args)
       callback&.call(**args)
     end

data/lib/verify_it/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VerifyIt
-  VERSION = "0.4.2"
+  VERSION = "0.5.0"
 end

data/lib/verify_it.rb

@@ -33,8 +33,8 @@ module VerifyIt
       yield(configuration)
     end
 
-    def send_code(to:, record:, channel: nil, context: {})
-      verifier.send_code(to: to, record: record, channel: channel, context: context)
+    def send_code(to:, record:, channel: nil, context: {}, request: nil)
+      verifier.send_code(to: to, record: record, channel: channel, context: context, request: request)
     end
 
     def verify_code(to:, code:, record:, request: nil)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verify_it
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Jeremias Ramirez