verify_it 0.2.0 → 0.4.0.beta

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
@@ -15,393 +20,387 @@ 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.
+**Redis + Twilio example:**
 
-### Model Integration
+```ruby
+VerifyIt.configure do |config|
+  config.secret_key_base = Rails.application.secret_key_base
+
+  config.storage    = :redis
+  config.redis_client = Redis.new(url: ENV["REDIS_URL"])
+
+  config.sms_sender = ->(to:, code:, context:) {
+    Twilio::REST::Client.new.messages.create(
+      from: ENV["TWILIO_NUMBER"],
+      to:   to,
+      body: "Your verification code is: #{code}"
+    )
+  }
+
+  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
+```
+
+### 3. Add `Verifiable` to your model
 
 ```ruby
 class User < ApplicationRecord
   include VerifyIt::Verifiable
-  
-  verifies :phone_number, channel: :sms
+
+  verifies :phone_number           # defaults to channel: :sms
   verifies :email, channel: :email
 end
+```
 
-# Usage
-user = User.find(params[:id])
+This generates the following methods on `User`:
 
-# Send code (no context needed)
-result = user.send_sms_code
+| 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 |
 
-# Send with custom message template
-result = user.send_sms_code(context: { 
-  message_template: "Your #{user.company_name} verification code is: %{code}"
-})
+### 4. Use it in your controllers
 
-# Send with tracking metadata
-result = user.send_email_code(context: { 
-  ip: request.ip,
-  user_agent: request.user_agent,
-  action: 'password_reset'
-})
+**Sending a code:**
 
-# Verify code
-result = user.verify_sms_code(params[:code])
+```ruby
+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
-user.cleanup_sms_verification
+**Verifying a code:**
+
+```ruby
+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: :forbidden
+    else
+      remaining = VerifyIt.configuration.max_verification_attempts - result.attempts
+      render json: { error: "Invalid code. #{remaining} attempts remaining." }
+    end
+  end
+end
 ```
 
-### Rails Configuration
+### Passing context
 
-Create an initializer `config/initializers/verify_it.rb`:
+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
-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}")
-  }
-  
-  config.test_mode = Rails.env.test?
-  config.bypass_delivery = Rails.env.test?
-end
+current_user.send_sms_code(context: {
+  message_template: :code_verification_v1,
+  locale: :es
+})
+
+current_user.send_email_code(context: {
+  ip:         request.ip,
+  user_agent: request.user_agent
+})
 ```
 
-## Plain Ruby Configuration
+---
+
+## Plain Ruby
 
 ```ruby
-require 'verify_it'
+require "verify_it"
 
 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.secret_key_base = ENV.fetch("VERIFY_IT_SECRET")
+  config.storage         = :memory  # :memory, :redis, or :database
+
   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
+    MySmsSender.deliver(to: to, body: "Your code: #{code}")
   }
 end
-```
 
-### Sending a Verification Code
+# Send a code
+result = VerifyIt.send_code(to: "+15551234567", channel: :sms, record: current_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
+# Verify a code
+result = VerifyIt.verify_code(to: "+15551234567", code: "123456", record: current_user)
+
+# Clean up
+VerifyIt.cleanup(to: "+15551234567", record: current_user)
 ```
 
-### Verifying 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"
-end
-```
+## 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.
 
-### Cleanup
+### Mount the engine
 
 ```ruby
-# Clean up verification data for a user
-VerifyIt.cleanup(
-  to: "+15551234567",
-  record: current_user
-)
+# config/routes.rb
+mount VerifyIt::Engine, at: "/verify"
 ```
 
-## Configuration Options
+This adds two routes:
 
-### Storage Backends
+| Method | Path | Action |
+|---|---|---|
+| POST | `/verify/send` | Send a verification code |
+| POST | `/verify/confirm` | Confirm a verification code |
 
-#### Memory Storage (Default)
-Perfect for testing and development:
+### Configure the resolvers
+
+Two additional config options are **required** when using the engine endpoints:
 
 ```ruby
-config.storage = :memory
-```
+# 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
 
-#### Redis Storage
-Recommended for production:
+  # 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])
+  }
 
-```ruby
-config.storage = :redis
-config.redis_client = Redis.new(url: ENV['REDIS_URL'])
+  # 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
 ```
 
-#### Database Storage
-Uses ActiveRecord models for persistent storage:
+### Request/response examples
 
-```ruby
-config.storage = :database
+**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." }
 ```
 
-Requires running the migration:
+**Confirm a code:**
 
 ```bash
-bundle exec verify_it install
-rails db:migrate
-```
+POST /verify/confirm
+Content-Type: application/json
 
-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
+{ "channel": "sms", "code": "123456" }
 
-### Code Settings
+# 200 OK
+{ "message": "Successfully verified." }
 
-```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
+# 422 Unprocessable Entity
+{ "error": "The code you entered is invalid." }
 ```
 
-### Rate Limiting
+### I18n overrides
 
-```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
+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."
 ```
 
-### Callbacks
+---
+
+## Configuration Reference
+
+| Option | Default | Accepted values |
+|---|---|---|
+| `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 |
+| `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 |
 
-Hook into the verification lifecycle:
+### Callbacks
 
 ```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:
-
-```ruby
-config.test_mode = true           # Includes code in Result object
-config.bypass_delivery = true     # Skip actual delivery
-```
+## Result Object
 
-## Result Object API
+Every operation returns a `VerifyIt::Result`:
 
-All operations return a `VerifyIt::Result` object:
+| 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 |
 
-```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
-
-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
+In a request spec:
 
-### 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
+- 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
 
-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/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