verify_it 0.1.0

data/README.md

@@ -0,0 +1,414 @@
+# VerifyIt
+
+A production-grade, storage-agnostic verification system for Ruby applications. VerifyIt provides a flexible framework for implementing SMS, email, and other verification workflows with built-in rate limiting and multiple storage backends.
+
+## Features
+
+- **Storage Agnostic**: Redis, Memory, or Database storage
+- **Delivery Agnostic**: Bring your own SMS/email provider (Twilio, SendGrid, etc.)
+- **Built-in Rate Limiting**: Configurable limits for sends and verifications
+- **Thread-Safe**: Designed for concurrent access
+- **Test Mode**: Expose codes for testing without delivery
+- **Rails Optional**: Works standalone or with Rails
+- **Zero Runtime Dependencies**: Only ActiveSupport required
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'verify_it'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install verify_it
+```
+
+### Rails Installation
+
+For Rails applications, use the installer to 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)
+
+If you selected Database storage, run the migration:
+
+```bash
+rails db:migrate
+```
+
+## Quick Start
+
+### Basic Configuration
+
+```ruby
+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.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
+  }
+end
+```
+
+### Sending a Verification Code
+
+```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
+```
+
+### 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
+```
+
+### Cleanup
+
+```ruby
+# Clean up verification data for a user
+VerifyIt.cleanup(
+  to: "+15551234567",
+  record: current_user
+)
+```
+
+## Configuration Options
+
+### Storage Backends
+
+#### Memory Storage (Default)
+Perfect for testing and development:
+
+```ruby
+config.storage = :memory
+```
+
+#### Redis Storage
+Recommended for production:
+
+```ruby
+config.storage = :redis
+config.redis_client = Redis.new(url: ENV['REDIS_URL'])
+```
+
+#### Database Storage
+Uses ActiveRecord models for persistent storage:
+
+```ruby
+config.storage = :database
+```
+
+Requires running the migration:
+
+```bash
+rails generate verify_it:install
+rails db:migrate
+```
+
+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
+
+### Code Settings
+
+```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
+```
+
+### 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
+```
+
+### Callbacks
+
+Hook into the verification lifecycle:
+
+```ruby
+config.on_send = ->(record:, identifier:, channel:) {
+  Analytics.track('verification_sent', user_id: record.id)
+}
+
+config.on_verify_success = ->(record:, identifier:) {
+  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)
+}
+```
+
+### Namespacing
+
+Isolate verification data by tenant or organization:
+
+```ruby
+config.namespace = ->(record) {
+  record.respond_to?(:organization_id) ? "org:#{record.organization_id}" : nil
+}
+```
+
+### Test Mode
+
+Expose codes in test environment:
+
+```ruby
+config.test_mode = true           # Includes code in Result object
+config.bypass_delivery = true     # Skip actual delivery
+```
+
+## Rails Integration
+
+VerifyIt automatically integrates with Rails when detected.
+
+### Model Integration
+
+```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
+
+Create an initializer `config/initializers/verify_it.rb`:
+
+```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
+```
+
+## Result Object API
+
+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
+
+```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
+    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
+
+### Memory Storage
+- Fast for testing and development
+- Not recommended for production
+- Data lost on restart
+
+## Error Handling
+
+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 Best Practices
+
+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
+```
+
+## Roadmap
+
+- [ ] Database storage adapter
+- [ ] Voice verification support
+- [ ] WebAuthn integration
+- [ ] Backup code generation
+- [ ] Multi-factor authentication helpers
+- [ ] Rails generators
+
+## 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).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the VerifyIt project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/JeremasPosta/verify_it/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/verify_it

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "verify_it"
+require "verify_it/cli"
+
+VerifyIt::CLI.start(ARGV)

data/lib/verify_it/cli.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "erb"
+require_relative "../verify_it" unless defined?(VerifyIt::VERSION)
+
+module VerifyIt
+  class CLI
+    def self.start(args)
+      new(args).run
+    end
+
+    def initialize(args)
+      @args = args
+      @command = args[0]
+    end
+
+    def run
+      case @command
+      when "install"
+        install
+      when "version", "-v", "--version"
+        puts "VerifyIt #{VerifyIt::VERSION}"
+      when "help", "-h", "--help", nil
+        show_help
+      else
+        puts "Unknown command: #{@command}"
+        show_help
+        exit 1
+      end
+    end
+
+    private
+
+    def install
+      puts "VerifyIt Installer"
+      puts "=" * 50
+      puts
+
+      check_rails_environment
+
+      storage_type = prompt_storage_type
+      generate_initializer(storage_type)
+      generate_migration if storage_type == "database"
+
+      puts
+      puts "✓ Installation complete!"
+      puts
+      puts "Next steps:"
+      puts "  1. Review the generated initializer"
+      if storage_type == "database"
+        puts "  2. Run: rails db:migrate"
+        puts "  3. Configure your delivery method in the initializer"
+      else
+        puts "  2. Configure your delivery method in the initializer"
+        puts "  3. Start using VerifyIt in your models!"
+      end
+    end
+
+    def check_rails_environment
+      unless defined?(Rails)
+        puts "Error: Rails environment not detected."
+        puts "Please run this command from your Rails application root."
+        exit 1
+      end
+    end
+
+    def prompt_storage_type
+      puts "Select storage backend:"
+      puts "  1) Memory (for development/testing)"
+      puts "  2) Redis (recommended for production)"
+      puts "  3) Database (uses ActiveRecord)"
+      puts
+
+      loop do
+        print "Enter choice (1-3): "
+        choice = $stdin.gets.chomp
+
+        case choice
+        when "1"
+          return "memory"
+        when "2"
+          return "redis"
+        when "3"
+          return "database"
+        else
+          puts "Invalid choice. Please enter 1, 2, or 3."
+        end
+      end
+    end
+
+    def generate_initializer(storage_type)
+      template_path = File.expand_path("../templates/initializer.rb.erb", __FILE__)
+      output_path = Rails.root.join("config", "initializers", "verify_it.rb")
+
+      if File.exist?(output_path)
+        print "Initializer already exists. Overwrite? (y/n): "
+        return unless $stdin.gets.chomp.downcase == "y"
+      end
+
+      template = ERB.new(File.read(template_path))
+      content = template.result(binding)
+
+      FileUtils.mkdir_p(File.dirname(output_path))
+      File.write(output_path, content)
+
+      puts "✓ Created initializer: config/initializers/verify_it.rb"
+    end
+
+    def generate_migration
+      timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+      template_path = File.expand_path("../templates/migration.rb.erb", __FILE__)
+      output_path = Rails.root.join("db", "migrate", "#{timestamp}_create_verify_it_tables.rb")
+
+      template = ERB.new(File.read(template_path))
+      content = template.result(binding)
+
+      FileUtils.mkdir_p(File.dirname(output_path))
+      File.write(output_path, content)
+
+      puts "✓ Created migration: db/migrate/#{timestamp}_create_verify_it_tables.rb"
+    end
+
+    def show_help
+      puts "VerifyIt - Verification system for Ruby applications"
+      puts
+      puts "Usage:"
+      puts "  verify_it install    Generate initializer and optional migration"
+      puts "  verify_it version    Show version number"
+      puts "  verify_it help       Show this help message"
+      puts
+      puts "For more information, visit: https://github.com/JeremasPosta/verify_it"
+    end
+  end
+end

data/lib/verify_it/code_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module VerifyIt
+  class CodeGenerator
+    def self.generate(length:, format:)
+      case format
+      when :numeric
+        generate_numeric(length)
+      when :alphanumeric
+        generate_alphanumeric(length)
+      when :alpha
+        generate_alpha(length)
+      else
+        raise ArgumentError, "Invalid code format: #{format}. Must be :numeric, :alphanumeric, or :alpha"
+      end
+    end
+
+    def self.generate_numeric(length)
+      Array.new(length) { rand(0..9) }.join
+    end
+
+    def self.generate_alphanumeric(length)
+      chars = ("0".."9").to_a + ("A".."Z").to_a
+      Array.new(length) { chars.sample }.join
+    end
+
+    def self.generate_alpha(length)
+      chars = ("A".."Z").to_a
+      Array.new(length) { chars.sample }.join
+    end
+  end
+end

data/lib/verify_it/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module VerifyIt
+  class Configuration
+    attr_accessor :storage,
+                  :redis_client,
+                  :delivery_channel,
+                  :code_length,
+                  :code_ttl,
+                  :code_format,
+                  :max_send_attempts,
+                  :max_verification_attempts,
+                  :max_identifier_changes,
+                  :rate_limit_window,
+                  :sms_sender,
+                  :email_sender,
+                  :on_send,
+                  :on_verify_success,
+                  :on_verify_failure,
+                  :namespace,
+                  :test_mode,
+                  :bypass_delivery
+
+    def initialize
+      # Default values
+      @storage = :memory
+      @redis_client = nil
+      @delivery_channel = :sms
+      @code_length = 6
+      @code_ttl = 300 # 5 minutes
+      @code_format = :numeric
+      @max_send_attempts = 3
+      @max_verification_attempts = 5
+      @max_identifier_changes = 5
+      @rate_limit_window = 3600 # 1 hour
+      @sms_sender = nil
+      @email_sender = nil
+      @on_send = nil
+      @on_verify_success = nil
+      @on_verify_failure = nil
+      @namespace = nil
+      @test_mode = false
+      @bypass_delivery = false
+    end
+  end
+end

data/lib/verify_it/delivery/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module VerifyIt
+  module Delivery
+    class Base
+      def deliver(to:, code:, context:)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/verify_it/delivery/email_delivery.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module VerifyIt
+  module Delivery
+    class EmailDelivery < Base
+      def deliver(to:, code:, context:)
+        return if VerifyIt.configuration.bypass_delivery
+
+        sender = VerifyIt.configuration.email_sender
+        raise ConfigurationError, "Email sender not configured" unless sender
+
+        sender.call(to: to, code: code, context: context)
+      end
+    end
+  end
+end

data/lib/verify_it/delivery/sms_delivery.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module VerifyIt
+  module Delivery
+    class SmsDelivery < Base
+      def deliver(to:, code:, context:)
+        return if VerifyIt.configuration.bypass_delivery
+
+        sender = VerifyIt.configuration.sms_sender
+        raise ConfigurationError, "SMS sender not configured" unless sender
+
+        sender.call(to: to, code: code, context: context)
+      end
+    end
+  end
+end

data/lib/verify_it/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module VerifyIt
+  class Railtie < Rails::Railtie
+    initializer "verify_it.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        require_relative "verifiable"
+        include VerifyIt::Verifiable
+      end
+    end
+  end
+end