verify_it 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ede88092d9b66d9853d5f03713b719f1bc664eefdfe0cc245140494110bda8a8
-  data.tar.gz: 1da02a88fc2c6262c6386eaac4f63184dad9bfebbd9bb694762a0e050f416aa3
+  metadata.gz: 9c975ad8c3016c930d9b8071d4f6c21fef89eece05332a48c5b1ebfebebf7386
+  data.tar.gz: 40adb101cba36f8cb6b1c89f81977558e4d21ae0de87a93333a70e3bf92006d1
 SHA512:
-  metadata.gz: 584f310188b429e0e6d77b9ca6c89cd0042b97bae8809b4ae8fad8699863666184fbbdf059c77eaabc5610d37d9355fffbbf9cd238056a06acc83626955f955e
-  data.tar.gz: 41394cf8edff07829dab5beecd3a4d723e8aaa1b89a6e8910095a77f1af3335a1f9988a56c92d5d77585aec2f23e4d683ca1f9ded3e494a2a0f938fc18417e41
+  metadata.gz: e4b862df0a1be371deb7fa9ea1d4eb2ed85da2f83852771a3efd52156187cf0c7a5057c162cd5e6e04ab5f6c88571c3fa6bc9c4d0427f901a7f4dbf5f23b6fe9
+  data.tar.gz: af94994c116729b2f0670b1664618ac1c01877755996ae00bd2b97069292fba1c0b2ef48d73f91a48d2c5653c2b49d5fc500a40c3a37e1cf304c77d7cf9d852c

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-03
+
+### Security
+- Verification codes are now hashed with HMAC-SHA256 before storage; a compromised storage backend no longer exposes usable codes
+- New required configuration: `secret_key_base` — must be set to a random secret in your initializer
+
+### Added
+- `VerifyIt::CodeHasher` module for HMAC-SHA256 code digesting (stdlib `openssl` only — no new dependencies)
+- `config.secret_key_base` configuration option
+
 ## [0.1.1] - 2026-03-02
 
 ### Fixed

data/README.md

@@ -15,393 +15,285 @@ VerifyIt provides a flexible framework for implementing SMS and email verificati
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
 gem 'verify_it'
 ```
 
-And then execute:
-
 ```bash
 bundle install
 ```
 
-Or install it yourself as:
-
-```bash
-gem install verify_it
-```
-
-### Rails Installation
+## Rails Setup
 
-For Rails applications, use the installer to generate configuration files:
+### 1. Generate configuration files
 
 ```bash
 bundle exec verify_it install
 ```
 
-This will:
-1. Prompt you to select a storage backend (Memory, Redis, or Database)
-2. Generate an initializer at `config/initializers/verify_it.rb`
-3. Generate a migration (if Database storage is selected)
+The installer will ask you to choose a storage backend and generate:
+
+- `config/initializers/verify_it.rb` — your main configuration
+- A database migration (if you chose Database storage)
 
-If you selected Database storage, run the migration:
+If you chose Database storage, run:
 
 ```bash
 rails db:migrate
 ```
 
-# Quick Start
+### 2. Configure the initializer
 
-## Rails Integration
+Open `config/initializers/verify_it.rb` and fill in your delivery lambdas.
 
-VerifyIt automatically integrates with Rails when detected.
-
-### Model Integration
+**Redis + Twilio example:**
 
 ```ruby
-class User < ApplicationRecord
-  include VerifyIt::Verifiable
-  
-  verifies :phone_number, channel: :sms
-  verifies :email, channel: :email
-end
-
-# Usage
-user = User.find(params[:id])
-
-# Send code (no context needed)
-result = user.send_sms_code
-
-# Send with custom message template
-result = user.send_sms_code(context: { 
-  message_template: "Your #{user.company_name} verification code is: %{code}"
-})
-
-# Send with tracking metadata
-result = user.send_email_code(context: { 
-  ip: request.ip,
-  user_agent: request.user_agent,
-  action: 'password_reset'
-})
-
-# Verify code
-result = user.verify_sms_code(params[:code])
-
-# Cleanup
-user.cleanup_sms_verification
-```
-
-### Rails Configuration
+VerifyIt.configure do |config|
+  config.secret_key_base = Rails.application.secret_key_base
 
-Create an initializer `config/initializers/verify_it.rb`:
+  config.storage    = :redis
+  config.redis_client = Redis.new(url: ENV["REDIS_URL"])
 
-```ruby
-VerifyIt.configure do |config|
-  config.storage = :redis
-  config.redis_client = Redis.new(url: ENV['REDIS_URL'])
-  
   config.sms_sender = ->(to:, code:, context:) {
-    TwilioService.send_sms(to: to, body: "Your code is: #{code}")
+    Twilio::REST::Client.new.messages.create(
+      from: ENV["TWILIO_NUMBER"],
+      to:   to,
+      body: "Your verification code is: #{code}"
+    )
   }
-  
-  config.test_mode = Rails.env.test?
+
+  config.test_mode       = Rails.env.test?
   config.bypass_delivery = Rails.env.test?
 end
 ```
 
-## Plain Ruby Configuration
+### 3. Add `Verifiable` to your model
 
 ```ruby
-require 'verify_it'
+class User < ApplicationRecord
+  include VerifyIt::Verifiable
 
-VerifyIt.configure do |config|
-  # Storage backend
-  config.storage = :memory  # or :redis, :database
-  
-  # For Redis storage
-  # config.redis_client = Redis.new(url: ENV['REDIS_URL'])
-  
-  # Code settings
-  config.code_length = 6
-  config.code_ttl = 300  # 5 minutes
-  config.code_format = :numeric  # or :alphanumeric, :alpha
-  
-  # Rate limiting
-  config.max_send_attempts = 3
-  config.max_verification_attempts = 5
-  config.max_identifier_changes = 5
-  config.rate_limit_window = 3600  # 1 hour
-  
-  # Delivery (SMS example with Twilio)
-  config.sms_sender = ->(to:, code:, context:) {
-    # Use custom template from context, or default
-    message = if context[:message_template]
-      context[:message_template] % { code: code }
-    else
-      "Your verification code is: #{code}"
-    end
-    
-    twilio_client.messages.create(
-      to: to,
-      from: '+15551234567',
-      body: message
-    )
-  }
-  
-  # Email delivery
-  config.email_sender = ->(to:, code:, context:) {
-    # Context available for customization
-    UserMailer.verification_code(to, code, context).deliver_now
-  }
+  verifies :phone_number           # defaults to channel: :sms
+  verifies :email, channel: :email
 end
 ```
 
-### Sending a Verification Code
+This generates the following methods on `User`:
 
-```ruby
-result = VerifyIt.send_code(
-  to: "+15551234567",
-  record: current_user,
-  channel: :sms,
-  context: { user_id: current_user.id }
-)
-
-if result.success?
-  puts "Code sent successfully!"
-  puts "Expires at: #{result.expires_at}"
-else
-  puts "Error: #{result.message}"
-  puts "Rate limited!" if result.rate_limited?
-end
-```
+| Method | Description |
+|---|---|
+| `send_sms_code` | Send a code to `phone_number` via SMS |
+| `send_email_code` | Send a code to `email` via email |
+| `verify_sms_code(code)` | Verify an SMS code |
+| `verify_email_code(code)` | Verify an email code |
+| `cleanup_sms_verification` | Remove stored verification data |
+| `cleanup_email_verification` | Remove stored verification data |
+
+### 4. Use it in your controllers
 
-### Verifying a Code
+**Sending a code:**
 
 ```ruby
-result = VerifyIt.verify_code(
-  to: "+15551234567",
-  code: params[:code],
-  record: current_user
-)
-
-if result.verified?
-  # Success! Code is valid
-  session[:verified] = true
-  redirect_to dashboard_path
-elsif result.locked?
-  # Too many failed attempts
-  flash[:error] = "Account locked due to too many attempts"
-elsif result.success? == false
-  # Invalid code
-  flash[:error] = "Invalid verification code. #{5 - result.attempts} attempts remaining"
+class VerificationsController < ApplicationController
+  def create
+    result = current_user.send_sms_code
+
+    if result.success?
+      render json: { expires_at: result.expires_at }
+    elsif result.rate_limited?
+      render json: { error: "Too many requests" }, status: :too_many_requests
+    else
+      render json: { error: result.message }, status: :unprocessable_entity
+    end
+  end
 end
 ```
 
-### Cleanup
+**Verifying a code:**
 
 ```ruby
-# Clean up verification data for a user
-VerifyIt.cleanup(
-  to: "+15551234567",
-  record: current_user
-)
+class VerificationsController < ApplicationController
+  def update
+    result = current_user.verify_sms_code(params[:code])
+
+    if result.verified?
+      session[:phone_verified] = true
+      render json: { verified: true }
+    elsif result.locked?
+      render json: { error: "Too many failed attempts. Try again later." }, status: :locked
+    else
+      remaining = VerifyIt.configuration.max_verification_attempts - result.attempts
+      render json: { error: "Invalid code. #{remaining} attempts remaining." }, status: :unprocessable_entity
+    end
+  end
+end
 ```
 
-## Configuration Options
-
-### Storage Backends
+### Passing context
 
-#### Memory Storage (Default)
-Perfect for testing and development:
+Both `send_*` methods accept an optional `context:` hash that is forwarded to your sender lambda. Use it for custom message templates or request metadata:
 
 ```ruby
-config.storage = :memory
-```
-
-#### Redis Storage
-Recommended for production:
+current_user.send_sms_code(context: {
+  message_template: "Your Acme login code: %{code}"
+})
 
-```ruby
-config.storage = :redis
-config.redis_client = Redis.new(url: ENV['REDIS_URL'])
+current_user.send_email_code(context: {
+  ip:         request.ip,
+  user_agent: request.user_agent
+})
 ```
 
-#### Database Storage
-Uses ActiveRecord models for persistent storage:
+---
+
+## Plain Ruby
 
 ```ruby
-config.storage = :database
-```
+require "verify_it"
 
-Requires running the migration:
+VerifyIt.configure do |config|
+  config.secret_key_base = ENV.fetch("VERIFY_IT_SECRET")
+  config.storage         = :memory  # :memory, :redis, or :database
 
-```bash
-bundle exec verify_it install
-rails db:migrate
-```
+  config.sms_sender = ->(to:, code:, context:) {
+    MySmsSender.deliver(to: to, body: "Your code: #{code}")
+  }
+end
 
-Creates three tables:
-- `verify_it_codes` - Stores verification codes
-- `verify_it_attempts` - Tracks verification and send attempts
-- `verify_it_identifier_changes` - Tracks identifier change history
+# Send a code
+result = VerifyIt.send_code(to: "+15551234567", channel: :sms, record: current_user)
 
-### Code Settings
+# Verify a code
+result = VerifyIt.verify_code(to: "+15551234567", code: "123456", record: current_user)
 
-```ruby
-config.code_length = 6              # Length of verification code
-config.code_ttl = 300               # Time-to-live in seconds (5 minutes)
-config.code_format = :numeric       # :numeric, :alphanumeric, or :alpha
+# Clean up
+VerifyIt.cleanup(to: "+15551234567", record: current_user)
 ```
 
-### Rate Limiting
-
-```ruby
-config.max_send_attempts = 3              # Max sends per window
-config.max_verification_attempts = 5      # Max verification tries per window
-config.max_identifier_changes = 5         # Max identifier changes per window
-config.rate_limit_window = 3600           # Window duration in seconds
-```
+---
+
+## Configuration Reference
+
+| Option | Default | Accepted values |
+|---|---|---|
+| `secret_key_base` | `nil` | Any string — **required** |
+| `storage` | `:memory` | `:memory`, `:redis`, `:database` |
+| `redis_client` | `nil` | A `Redis` instance (required when `storage: :redis`) |
+| `code_length` | `6` | Integer |
+| `code_ttl` | `300` | Seconds (integer) |
+| `code_format` | `:numeric` | `:numeric`, `:alphanumeric`, `:alpha` |
+| `max_send_attempts` | `3` | Integer |
+| `max_verification_attempts` | `5` | Integer |
+| `max_identifier_changes` | `5` | Integer |
+| `rate_limit_window` | `3600` | Seconds (integer) |
+| `sms_sender` | `nil` | Lambda `(to:, code:, context:) { }` |
+| `email_sender` | `nil` | Lambda `(to:, code:, context:) { }` |
+| `on_send` | `nil` | Lambda `(record:, identifier:, channel:) { }` |
+| `on_verify_success` | `nil` | Lambda `(record:, identifier:) { }` |
+| `on_verify_failure` | `nil` | Lambda `(record:, identifier:, attempts:) { }` |
+| `namespace` | `nil` | Lambda `(record) { }` returning a string or nil |
+| `test_mode` | `false` | Boolean — exposes `result.code` |
+| `bypass_delivery` | `false` | Boolean — skips actual delivery |
 
 ### Callbacks
 
-Hook into the verification lifecycle:
-
 ```ruby
 config.on_send = ->(record:, identifier:, channel:) {
-  Analytics.track('verification_sent', user_id: record.id)
+  Analytics.track("verification_sent", user_id: record.id, channel: channel)
 }
 
 config.on_verify_success = ->(record:, identifier:) {
-  Analytics.track('verification_success', user_id: record.id)
+  Analytics.track("verification_success", user_id: record.id)
 }
 
 config.on_verify_failure = ->(record:, identifier:, attempts:) {
-  Analytics.track('verification_failure', user_id: record.id, attempts: attempts)
+  Analytics.track("verification_failure", user_id: record.id, attempts: attempts)
 }
 ```
 
 ### Namespacing
 
-Isolate verification data by tenant or organization:
+Isolate verification data per tenant:
 
 ```ruby
-config.namespace = ->(record) {
-  record.respond_to?(:organization_id) ? "org:#{record.organization_id}" : nil
-}
+config.namespace = ->(record) { "org:#{record.organization_id}" }
 ```
 
-### Test Mode
+---
 
-Expose codes in test environment:
+## Result Object
 
-```ruby
-config.test_mode = true           # Includes code in Result object
-config.bypass_delivery = true     # Skip actual delivery
-```
+Every operation returns a `VerifyIt::Result`:
 
-## Result Object API
+| Method | Type | Description |
+|---|---|---|
+| `success?` | Boolean | Operation completed without error |
+| `verified?` | Boolean | Code matched successfully |
+| `rate_limited?` | Boolean | Rate limit was exceeded |
+| `locked?` | Boolean | Max verification attempts reached |
+| `error` | Symbol | `:invalid_code`, `:rate_limited`, `:code_not_found`, `:locked`, `:delivery_failed` |
+| `message` | String | Human-readable description |
+| `code` | String | The verification code (only when `test_mode: true`) |
+| `expires_at` | Time | When the code expires |
+| `attempts` | Integer | Number of verification attempts so far |
 
-All operations return a `VerifyIt::Result` object:
-
-```ruby
-result.success?       # true if operation succeeded
-result.verified?      # true if code was verified successfully
-result.locked?        # true if max attempts exceeded
-result.rate_limited?  # true if rate limit hit
-result.error          # Symbol error code (:invalid_code, :rate_limited, etc.)
-result.message        # Human-readable message
-result.code           # Verification code (only in test_mode)
-result.expires_at     # Time when code expires
-result.attempts       # Number of verification attempts
-```
+---
 
 ## Testing
 
-### RSpec Example
+Configure VerifyIt in your spec helper to avoid real delivery and expose codes:
 
 ```ruby
-RSpec.describe "Phone Verification", type: :request do
-  before do
-    VerifyIt.configure do |config|
-      config.storage = :memory
-      config.test_mode = true
-      config.bypass_delivery = true
+# spec/support/verify_it.rb
+RSpec.configure do |config|
+  config.before(:each) do
+    VerifyIt.configure do |c|
+      c.storage         = :memory
+      c.test_mode       = true
+      c.bypass_delivery = true
+      c.secret_key_base = "test_secret"
     end
   end
-  
-  it "verifies phone number" do
-    post '/verify/send', params: { phone: '+15551234567' }
-    
-    # Get code from response (test mode)
-    code = JSON.parse(response.body)['code']
-    
-    post '/verify/confirm', params: { phone: '+15551234567', code: code }
-    expect(response).to have_http_status(:success)
-  end
 end
 ```
 
-## Thread Safety
+In a request spec:
 
-VerifyIt is designed to be thread-safe:
-
-- Memory storage uses `Mutex` for synchronization
-- Redis operations are atomic
-- No shared mutable state in core logic
-
-## Performance Considerations
-
-### Redis Storage
-- Uses key expiration for TTL
-- Sorted sets for identifier tracking
-- Atomic operations for counters
-
-### Memory Storage
-- Fast for testing and development
-- Not recommended for production
-- Data lost on restart
+```ruby
+it "verifies phone number" do
+  post "/verify/send", params: { phone: "+15551234567" }
+  code = JSON.parse(response.body)["code"]  # available in test_mode
 
-## Error Handling
+  post "/verify/confirm", params: { phone: "+15551234567", code: code }
+  expect(response).to have_http_status(:ok)
+end
+```
 
-VerifyIt uses explicit error states in Result objects:
+---
 
-- `:rate_limited` - Rate limit exceeded
-- `:invalid_code` - Code doesn't match
-- `:code_not_found` - No code stored or expired
-- `:locked` - Max attempts reached
-- `:delivery_failed` - Delivery provider error
+## Security
 
-## Security Best Practices
+- **`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
+- Use `on_verify_failure` to monitor and alert on repeated failures
+- Always serve verification endpoints over HTTPS
 
-1. **Always use rate limiting** in production
-2. **Use Redis storage** for distributed systems
-3. **Set short TTLs** (5 minutes recommended)
-4. **Monitor failed attempts** via callbacks
-5. **Use HTTPS** for all verification endpoints
-6. **Sanitize phone numbers** before storage
+---
 
 ## Development
 
-After checking out the repo:
-
 ```bash
-bin/setup                 # Install dependencies
-bundle exec rspec         # Run tests
-bin/console              # Interactive console
-bundle exec rake build    # Build gem
+bin/setup           # Install dependencies
+bundle exec rspec   # Run tests
+bundle exec rubocop # Lint
+bin/console         # Interactive console
 ```
 
-## Roadmap
-
-- [x] Database storage adapter
-- [ ] Voice verification support
-- [ ] WebAuthn integration
-- [ ] Backup code generation
-- [ ] Multi-factor authentication helpers
-- [x] Rails installer (CLI)
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/JeremasPosta/verify_it. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/JeremasPosta/verify_it/blob/main/CODE_OF_CONDUCT.md).

data/lib/verify_it/code_hasher.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module VerifyIt
+  # Hashes verification codes with HMAC-SHA256 before storage.
+  #
+  # Using a secret key makes offline brute-force of the small OTP keyspace
+  # infeasible even if the storage layer is compromised.
+  module CodeHasher
+    # @param code [String] the plaintext verification code
+    # @param secret [String] the HMAC secret (config.secret_key_base)
+    # @return [String] hex-encoded HMAC-SHA256 digest
+    # @raise [ArgumentError] if secret is nil or empty
+    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."
+      end
+
+      OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, code.to_s)
+    end
+  end
+end

data/lib/verify_it/configuration.rb

@@ -19,7 +19,8 @@ module VerifyIt
                   :on_verify_failure,
                   :namespace,
                   :test_mode,
-                  :bypass_delivery
+                  :bypass_delivery,
+                  :secret_key_base
 
     def initialize
       # Default values
@@ -41,6 +42,7 @@ module VerifyIt
       @namespace = nil
       @test_mode = false
       @bypass_delivery = false
+      @secret_key_base = nil
     end
   end
 end

data/lib/verify_it/templates/initializer.rb.erb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 VerifyIt.configure do |config|
+  # Required: set a secret key to hash verification codes before storage.
+  # It is not required to use the Rails secret key base.
+  config.secret_key_base = Rails.application.secret_key_base
+
 <% if storage_type == "redis" %>
   config.storage = :redis
   config.redis_client = Redis.new(url: ENV.fetch("REDIS_URL", "redis://localhost:6379/0"))
@@ -19,7 +23,7 @@ VerifyIt.configure do |config|
     # e.g. Twilio, Vonage, etc.
   }
 
-  # Optional overrides (sensible defaults are set automatically):
+  # Some other config options (with defaults):
   # config.code_length = 6
   # config.code_ttl = 300
   # config.code_format = :numeric

data/lib/verify_it/verifier.rb

@@ -41,11 +41,12 @@ module VerifyIt
       )
       expires_at = Time.now + VerifyIt.configuration.code_ttl
 
-      # Store code
+      # Store hashed code
+      hashed_code = CodeHasher.digest(code, secret: VerifyIt.configuration.secret_key_base)
       storage.store_code(
         identifier: to,
         record: record,
-        code: code,
+        code: hashed_code,
         expires_at: expires_at
       )
 
@@ -115,7 +116,7 @@ module VerifyIt
       current_attempts = rate_limiter.record_verification_attempt(identifier: to, record: record)
 
       # Verify code
-      if stored_code == code.to_s
+      if stored_code == CodeHasher.digest(code, secret: VerifyIt.configuration.secret_key_base)
         # Success - cleanup
         storage.delete_code(identifier: to, record: record)
         storage.reset_attempts(identifier: to, record: record)

data/lib/verify_it/version.rb

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

data/lib/verify_it.rb

@@ -4,6 +4,7 @@ require_relative "verify_it/version"
 require_relative "verify_it/configuration"
 require_relative "verify_it/result"
 require_relative "verify_it/code_generator"
+require_relative "verify_it/code_hasher"
 require_relative "verify_it/rate_limiter"
 require_relative "verify_it/storage/base"
 require_relative "verify_it/storage/memory_storage"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verify_it
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jeremias Ramirez
@@ -157,6 +157,7 @@ files:
 - lib/verify_it.rb
 - lib/verify_it/cli.rb
 - lib/verify_it/code_generator.rb
+- lib/verify_it/code_hasher.rb
 - lib/verify_it/configuration.rb
 - lib/verify_it/delivery/base.rb
 - lib/verify_it/delivery/email_delivery.rb