verify_it 0.3.0 → 0.4.0.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c975ad8c3016c930d9b8071d4f6c21fef89eece05332a48c5b1ebfebebf7386
-  data.tar.gz: 40adb101cba36f8cb6b1c89f81977558e4d21ae0de87a93333a70e3bf92006d1
+  metadata.gz: ccaee3a9738dcd530a9afc7015401a5e13151f19b6e26e76dbf02d88b38294bd
+  data.tar.gz: 423c5f4b1354fd994be521a72303c6f61435263b5f71477177b0bbd68c9a89a4
 SHA512:
-  metadata.gz: e4b862df0a1be371deb7fa9ea1d4eb2ed85da2f83852771a3efd52156187cf0c7a5057c162cd5e6e04ab5f6c88571c3fa6bc9c4d0427f901a7f4dbf5f23b6fe9
-  data.tar.gz: af94994c116729b2f0670b1664618ac1c01877755996ae00bd2b97069292fba1c0b2ef48d73f91a48d2c5653c2b49d5fc500a40c3a37e1cf304c77d7cf9d852c
+  metadata.gz: 14e0947db04ce6fab19be9a0b1a475d99d6e16a6967ec079488fa162fecf45c37abdf37b7ad4e763d96a8110b1447dbca1a13923d3e0a5377d7f7e2bad5fe147
+  data.tar.gz: 3e5a97c488b04b36487c1ee8bb6591c2eb2c2987dd79dc62dbfe5b610ee1dac7813a5fd63927db745354f8ee54abd224fd67f587acbb273283731794c2f42904

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-07
+
+### Added
+- **Rails Engine** (`VerifyIt::Engine`) — replaces the minimal Railtie with a full mountable engine
+- **HTTP endpoints** — `POST /verify/send` and `POST /verify/confirm` served by `VerifyIt::VerificationsController`
+- **I18n locale file** (`config/locales/en.yml`) — all response/error messages and SMS/email message templates are now translatable and overridable by host apps
+- `config.current_record_resolver` — lambda `(request) { ... }` to resolve the authenticated record from a request; required when mounting the engine
+- `config.identifier_resolver` — lambda `(record, channel) { ... }` to derive the delivery identifier (phone/email) from the record; required when mounting the engine
+- `rescue_from VerifyIt::ConfigurationError` in `ApplicationController` returns a JSON 500 when resolvers are not configured
+- Dummy Rails app (`spec/dummy/`) and `spec/rails_helper.rb` for request-level integration specs
+- 10 new request specs covering auth, rate-limiting, locking, and error scenarios
+
+### Notes
+- Backward compatible: standalone Ruby usage, the `verifies` DSL, and all existing sender lambdas are unchanged
+- Non-mounting apps are completely unaffected by the new engine and resolver options
+
 ## [0.3.0] - 2026-03-03
 
 ### Security

data/README.md

@@ -1,8 +1,13 @@
 # VerifyIt
 
+[![Gem Version](https://badge.fury.io/rb/verify_it.svg)](https://badge.fury.io/rb/verify_it)
+
 A storage-agnostic verification system for Ruby applications.
+
 VerifyIt provides a flexible framework for implementing SMS and email verifications with built-in rate limiting and multiple storage backends.
 
+It allows applications to generate and validate verification codes locally, helping reduce the operational cost associated with per-verification billing models.
+
 ## Features
 
 - **Storage Agnostic**: Redis, Memory, or Database storage
@@ -65,6 +70,10 @@ VerifyIt.configure do |config|
     )
   }
 
+  config.email_sender = ->(to:, code:, context:) {
+    EmailClient.new(to:).send("Your verification code is: #{code}")
+  }
+
   config.test_mode       = Rails.env.test?
   config.bypass_delivery = Rails.env.test?
 end
@@ -123,10 +132,10 @@ class VerificationsController < ApplicationController
       session[:phone_verified] = true
       render json: { verified: true }
     elsif result.locked?
-      render json: { error: "Too many failed attempts. Try again later." }, status: :locked
+      render json: { error: "Too many failed attempts. Try again later." }, status: :forbidden
     else
       remaining = VerifyIt.configuration.max_verification_attempts - result.attempts
-      render json: { error: "Invalid code. #{remaining} attempts remaining." }, status: :unprocessable_entity
+      render json: { error: "Invalid code. #{remaining} attempts remaining." }
     end
   end
 end
@@ -138,7 +147,8 @@ Both `send_*` methods accept an optional `context:` hash that is forwarded to yo
 
 ```ruby
 current_user.send_sms_code(context: {
-  message_template: "Your Acme login code: %{code}"
+  message_template: :code_verification_v1,
+  locale: :es
 })
 
 current_user.send_email_code(context: {
@@ -175,11 +185,109 @@ VerifyIt.cleanup(to: "+15551234567", record: current_user)
 
 ---
 
+## Rails Engine (HTTP Endpoints)
+
+VerifyIt ships a mountable Rails Engine that exposes two JSON endpoints. This is
+optional, if you prefer to not use the engine, skip to the next section.
+
+### Mount the engine
+
+```ruby
+# config/routes.rb
+mount VerifyIt::Engine, at: "/verify"
+```
+
+This adds two routes:
+
+| Method | Path | Action |
+|---|---|---|
+| POST | `/verify/send` | Send a verification code |
+| POST | `/verify/confirm` | Confirm a verification code |
+
+### Configure the resolvers
+
+Two additional config options are **required** when using the engine endpoints:
+
+```ruby
+# 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
+
+  # Resolve the authenticated record from the request (e.g. from a session or JWT).
+  config.current_record_resolver = ->(request) {
+    User.find_by(id: request.session[:user_id])
+  }
+
+  # Derive the delivery identifier from the record and the requested channel.
+  config.identifier_resolver = ->(record, channel) {
+    channel == :sms ? record.phone_number : record.email
+  }
+
+  config.sms_sender = ->(to:, code:, context:) {
+    Twilio::REST::Client.new.messages.create(
+      from: ENV["TWILIO_NUMBER"],
+      to:   to,
+      body: I18n.t("verify_it.sms.default_message", code: code)
+    )
+  }
+end
+```
+
+### Request/response examples
+
+**Send a code:**
+
+```bash
+POST /verify/send
+Content-Type: application/json
+
+{ "channel": "sms" }
+
+# 201 Created
+{ "message": "Verification code sent." }
+
+# 429 Too Many Requests
+{ "error": "Too many attempts. Please try again later." }
+```
+
+**Confirm a code:**
+
+```bash
+POST /verify/confirm
+Content-Type: application/json
+
+{ "channel": "sms", "code": "123456" }
+
+# 200 OK
+{ "message": "Successfully verified." }
+
+# 422 Unprocessable Entity
+{ "error": "The code you entered is invalid." }
+```
+
+### I18n overrides
+
+All messages are stored in `config/locales/en.yml` and can be overridden in your
+application's locale files:
+
+```yaml
+en:
+  verify_it:
+    sms:
+      default_message: "%{code} is your one-time passcode."
+    responses:
+      verified: "Identity confirmed."
+```
+
+---
+
 ## Configuration Reference
 
 | Option | Default | Accepted values |
 |---|---|---|
-| `secret_key_base` | `nil` | Any string — **required** |
+| `secret_key_base` | `nil` unless using Rails | Any string — **required** |
 | `storage` | `:memory` | `:memory`, `:redis`, `:database` |
 | `redis_client` | `nil` | A `Redis` instance (required when `storage: :redis`) |
 | `code_length` | `6` | Integer |
@@ -277,11 +385,10 @@ end
 ## Security
 
 - **`secret_key_base` is required** — codes are hashed with HMAC-SHA256 before storage
-- Enable rate limiting (on by default) in all environments
-- Use `:redis` or `:database` storage in production (`:memory` does not survive restarts)
-- Keep `code_ttl` short — 5 minutes is a sensible default
+- Do not disable rate limiting
+- Use `:redis` or `:database` storage in production
+- Keep `code_ttl` short.
 - Use `on_verify_failure` to monitor and alert on repeated failures
-- Always serve verification endpoints over HTTPS
 
 ---
 

data/app/controllers/verify_it/application_controller.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module VerifyIt
+  class ApplicationController < ActionController::API
+    rescue_from VerifyIt::ConfigurationError do |_error|
+      render json: { error: "Service configuration error" }, status: :internal_server_error
+    end
+  end
+end

data/app/controllers/verify_it/verifications_controller.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module VerifyIt
+  class VerificationsController < ApplicationController
+    VALID_CHANNELS = %i[sms email].freeze
+
+    before_action :validate_resolvers_configured!
+
+    # POST /send  { channel: "sms"|"email" }
+    def create
+      record = resolve_record
+      return render json: { error: "Unauthorized" }, status: :unauthorized if record.nil?
+
+      channel    = resolve_channel
+      identifier = resolve_identifier(record, channel)
+      result     = VerifyIt.send_code(to: identifier, record: record, channel: channel, context: {})
+
+      if result.success?
+        payload = { message: I18n.t("verify_it.responses.sent") }
+        payload[:code] = result.code if VerifyIt.configuration.test_mode
+        render json: payload, status: :created
+      elsif result.rate_limited?
+        render json: { error: I18n.t("verify_it.errors.rate_limited") }, status: :too_many_requests
+      else
+        render json: { error: I18n.t("verify_it.errors.#{result.error || :delivery_failed}") },
+               status: :unprocessable_entity
+      end
+    end
+
+    # POST /confirm  { channel: "sms"|"email", code: "123456" }
+    def verify
+      record = resolve_record
+      return render json: { error: "Unauthorized" }, status: :unauthorized if record.nil?
+
+      channel    = resolve_channel
+      identifier = resolve_identifier(record, channel)
+      result     = VerifyIt.verify_code(to: identifier, code: params[:code].to_s, record: record)
+
+      if result.success?
+        render json: { message: I18n.t("verify_it.responses.verified") }, status: :ok
+      elsif result.locked?
+        render json: { error: I18n.t("verify_it.errors.locked") }, status: :too_many_requests
+      elsif result.rate_limited?
+        render json: { error: I18n.t("verify_it.errors.rate_limited") }, status: :too_many_requests
+      else
+        render json: { error: I18n.t("verify_it.errors.#{result.error || :invalid_code}") },
+               status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def validate_resolvers_configured!
+      unless VerifyIt.configuration.current_record_resolver
+        raise ConfigurationError, "VerifyIt: configure current_record_resolver to use HTTP endpoints."
+      end
+      return if VerifyIt.configuration.identifier_resolver
+
+      raise ConfigurationError, "VerifyIt: configure identifier_resolver to use HTTP endpoints."
+    end
+
+    def resolve_record = VerifyIt.configuration.current_record_resolver.call(request)
+
+    def resolve_channel
+      ch = params[:channel]&.to_sym
+      VALID_CHANNELS.include?(ch) ? ch : VerifyIt.configuration.delivery_channel
+    end
+
+    def resolve_identifier(record, channel) = VerifyIt.configuration.identifier_resolver.call(record, channel)
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,16 @@
+en:
+  verify_it:
+    responses:
+      sent: "Verification code sent."
+      verified: "Successfully verified."
+    errors:
+      rate_limited: "Too many attempts. Please try again later."
+      invalid_code: "The code you entered is invalid."
+      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."
+    sms:
+      default_message: "%{code} is your verification code."
+    email:
+      default_subject: "Your verification code"
+      default_message: "Your verification code is %{code}."

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+VerifyIt::Engine.routes.draw do
+  post "send",    to: "verifications#create",  as: :send_verification
+  post "confirm", to: "verifications#verify",  as: :confirm_verification
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/migration"
+
+module VerifyIt
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a VerifyIt initializer, mounts the engine in routes, " \
+           "and generates a migration when using database storage."
+
+      class_option :storage, type: :string, default: "memory",
+                             desc: "Storage backend to use: memory, redis, or database"
+
+      def self.next_migration_number(dirname)
+        next_num = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_num)
+      end
+
+      def create_initializer
+        template "initializer.rb.erb", "config/initializers/verify_it.rb"
+      end
+
+      def mount_engine
+        route 'mount VerifyIt::Engine, at: "/verify_it"'
+      end
+
+      def generate_migration
+        return unless storage == "database"
+
+        migration_template "create_verify_it_tables.rb",
+                           "db/migrate/create_verify_it_tables.rb"
+      end
+
+      private
+
+      def storage
+        options[:storage]
+      end
+    end
+  end
+end

data/lib/{verify_it/templates/migration.rb.erb → generators/verify_it/install/templates/create_verify_it_tables.rb}

@@ -1,6 +1,4 @@
-# frozen_string_literal: true
-
-class CreateVerifyItTables < ActiveRecord::Migration[7.0]
+class CreateVerifyItTables < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :verify_it_codes do |t|
       t.string :identifier, null: false

data/lib/{verify_it → generators/verify_it/install}/templates/initializer.rb.erb

@@ -5,16 +5,16 @@ VerifyIt.configure do |config|
   # It is not required to use the Rails secret key base.
   config.secret_key_base = Rails.application.secret_key_base
 
-<% if storage_type == "redis" %>
+<% if storage == "redis" -%>
   config.storage = :redis
   config.redis_client = Redis.new(url: ENV.fetch("REDIS_URL", "redis://localhost:6379/0"))
-<% elsif storage_type == "database" %>
+<% elsif storage == "database" -%>
   config.storage = :database
-<% else %>
+<% else -%>
   # config.storage = :memory  # default
-<% end %>
+<% end -%>
 
-  # Required: configure your delivery channel(s)
+  # Required: configure your delivery channel(s).
   config.email_sender = ->(to:, code:, context:) {
     # VerificationMailer.send_code(to, code, context).deliver_now
   }
@@ -23,7 +23,17 @@ VerifyIt.configure do |config|
     # e.g. Twilio, Vonage, etc.
   }
 
-  # Some other config options (with defaults):
+  # Required: resolve the current authenticated record from a request.
+  config.current_record_resolver = ->(request) {
+    # User.find_by(id: request.session[:user_id])
+  }
+
+  # Required: resolve the delivery identifier (phone/email) from the record and channel.
+  config.identifier_resolver = ->(record, channel) {
+    # channel == :sms ? record.phone_number : record.email
+  }
+
+  # Optional overrides (shown with defaults):
   # config.code_length = 6
   # config.code_ttl = 300
   # config.code_format = :numeric

data/lib/verify_it/code_generator.rb

@@ -16,17 +16,17 @@ module VerifyIt
     end
 
     def self.generate_numeric(length)
-      Array.new(length) { rand(0..9) }.join
+      Array.new(length) { SecureRandom.random_number(10) }.join
     end
 
     def self.generate_alphanumeric(length)
       chars = ("0".."9").to_a + ("A".."Z").to_a
-      Array.new(length) { chars.sample }.join
+      Array.new(length) { chars.sample(random: SecureRandom) }.join
     end
 
     def self.generate_alpha(length)
       chars = ("A".."Z").to_a
-      Array.new(length) { chars.sample }.join
+      Array.new(length) { chars.sample(random: SecureRandom) }.join
     end
   end
 end

data/lib/verify_it/code_hasher.rb

@@ -15,8 +15,8 @@ module VerifyIt
     def self.digest(code, secret:)
       if secret.nil? || secret.to_s.empty?
         raise ArgumentError,
-          "VerifyIt requires secret_key_base to be configured. " \
-          "Set config.secret_key_base in your initializer."
+              "VerifyIt requires secret_key_base to be configured. " \
+              "Set config.secret_key_base in your initializer."
       end
 
       OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, code.to_s)

data/lib/verify_it/configuration.rb

@@ -20,7 +20,19 @@ module VerifyIt
                   :namespace,
                   :test_mode,
                   :bypass_delivery,
-                  :secret_key_base
+                  :secret_key_base,
+                  :current_record_resolver,
+                  :identifier_resolver
+
+    def validate!
+      if secret_key_base.nil? || secret_key_base.to_s.strip.empty?
+        raise ConfigurationError, "VerifyIt: secret_key_base must be configured before use."
+      end
+
+      return unless test_mode && defined?(Rails) && Rails.env.production?
+
+      raise ConfigurationError, "VerifyIt: test_mode must not be enabled in production."
+    end
 
     def initialize
       # Default values
@@ -43,6 +55,8 @@ module VerifyIt
       @test_mode = false
       @bypass_delivery = false
       @secret_key_base = nil
+      @current_record_resolver = nil
+      @identifier_resolver = nil
     end
   end
 end

data/lib/verify_it/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module VerifyIt
+  class Engine < ::Rails::Engine
+    isolate_namespace VerifyIt
+
+    initializer "verify_it.i18n" do
+      config.i18n.load_path += Dir[Engine.root.join("config", "locales", "**", "*.yml").to_s]
+    end
+
+    initializer "verify_it.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        include VerifyIt::Verifiable
+      end
+    end
+  end
+end

data/lib/verify_it/storage/database_storage.rb

@@ -5,9 +5,7 @@ module VerifyIt
     class DatabaseStorage < Base
       def initialize
         # Verify ActiveRecord is available
-        unless defined?(::ActiveRecord)
-          raise StandardError, "ActiveRecord is required for DatabaseStorage"
-        end
+        raise StandardError, "ActiveRecord is required for DatabaseStorage" unless defined?(::ActiveRecord)
 
         # Load models only when needed
         require_relative "models/code"
@@ -130,10 +128,13 @@ module VerifyIt
         scope = scope.for_record(record) if record
         scope.delete_all
 
-        # Delete attempts
+        # Delete attempts for this identifier
         scope = Models::Attempt.for_identifier(identifier)
         scope = scope.for_record(record) if record
         scope.delete_all
+
+        # Purge all globally expired attempt records
+        Models::Attempt.cleanup_expired
       end
 
       private
@@ -146,8 +147,8 @@ module VerifyIt
 
       def find_attempt(identifier:, record:, attempt_type:)
         scope = Models::Attempt
-          .for_identifier(identifier)
-          .where(attempt_type: attempt_type)
+                .for_identifier(identifier)
+                .where(attempt_type: attempt_type)
 
         scope = scope.for_record(record) if record
         scope.first

data/lib/verify_it/storage/memory_storage.rb

@@ -118,10 +118,10 @@ module VerifyIt
       end
 
       def cleanup(identifier:, record:)
+        keys_to_delete = %w[code attempts send_count].map do |suffix|
+          build_key(identifier: identifier, record: record, suffix: suffix)
+        end
         @mutex.synchronize do
-          keys_to_delete = @data.keys.select do |key|
-            key.include?(identifier.to_s) && (record.nil? || key.include?(record.class.name))
-          end
           keys_to_delete.each { |key| @data.delete(key) }
         end
       end

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

@@ -14,9 +14,9 @@ module VerifyIt
         scope :active, -> { where("expires_at > ?", Time.now) }
         scope :expired, -> { where("expires_at <= ?", Time.now) }
         scope :for_identifier, ->(identifier) { where(identifier: identifier) }
-        scope :for_record, ->(record) do
+        scope :for_record, lambda { |record|
           where(record_type: record.class.name, record_id: record.id)
-        end
+        }
         scope :verification_type, -> { where(attempt_type: "verification") }
         scope :send_type, -> { where(attempt_type: "send") }
 

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

@@ -13,9 +13,9 @@ module VerifyIt
         scope :active, -> { where("expires_at > ?", Time.now) }
         scope :expired, -> { where("expires_at <= ?", Time.now) }
         scope :for_identifier, ->(identifier) { where(identifier: identifier) }
-        scope :for_record, ->(record) do
+        scope :for_record, lambda { |record|
           where(record_type: record.class.name, record_id: record.id)
-        end
+        }
 
         def expired?
           expires_at <= Time.now

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

@@ -9,9 +9,9 @@ module VerifyIt
         validates :identifier, presence: true
         validates :created_at, presence: true
 
-        scope :for_record, ->(record) do
+        scope :for_record, lambda { |record|
           where(record_type: record.class.name, record_id: record.id)
-        end
+        }
         scope :recent, ->(window) { where("created_at > ?", Time.now - window) }
 
         def self.cleanup_old(window)

data/lib/verify_it/verifiable.rb

@@ -18,9 +18,7 @@ module VerifyIt
         verify_method = "verify_#{channel}_code"
         cleanup_method = "cleanup_#{channel}_verification"
 
-        if method_defined?(send_method)
-          raise ArgumentError, "Method #{send_method} is already defined on #{name}"
-        end
+        raise ArgumentError, "Method #{send_method} is already defined on #{name}" if method_defined?(send_method)
 
         define_method(send_method) do |context: {}|
           identifier = send(attribute)