reputable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 022cbf56ba79954bcae6450e3fe7d31791498a1bbde2ee3d6add895124cde28b
+  data.tar.gz: 6f3cddf2cbc0f69241d7affd69d9322a521a03eb0727a6c7e1695d6fe3194106
+SHA512:
+  metadata.gz: 6a03a6f38827b0eb79ce4b8db2ed57640614822caf5f31165020da33324eaf39a6ded64a9d5a19e5b557a03e3b2e06348b02dcd78472a407f680cd18b4c4086d
+  data.tar.gz: 0a52fc4e6a6fe20b799841e2dd4e475afc0a8ff4a20a48240812b343538e8f2a3b0e11863b6a2dea89748b9f8f8931f45889142d5d7f690144223958cde890b6

data/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rubocop", "~> 1.21"

data/README.md

@@ -0,0 +1,512 @@
+# Reputable Ruby Client
+
+Ruby gem for integrating with Reputable - bot detection and reputation scoring for Rails applications.
+
+**Resilience First**: This gem is designed to never break your application. All operations fail silently with safe defaults.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'reputable'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Rails Quick Start
+
+### 1. Create Initializer
+
+```ruby
+# config/initializers/reputable.rb
+Reputable.configure do |config|
+  # Required: Redis/Dragonfly URL (TLS supported via rediss://)
+  config.redis_url = ENV['REPUTABLE_REDIS_URL']
+  
+  # Required: Your tenant ID
+  config.tenant_id = ENV['REPUTABLE_TENANT_ID']
+  
+  # Optional: Enable logging (logs at debug level)
+  Reputable.logger = Rails.logger
+end
+```
+
+### 2. Add Middleware
+
+```ruby
+# config/application.rb
+module YourApp
+  class Application < Rails::Application
+    # Add Reputable middleware (recommended: async mode, non-blocking)
+    config.middleware.use Reputable::Middleware, async: true
+  end
+end
+```
+
+### 3. Use Controller Helpers
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include Reputable::Rails::ControllerHelpers
+end
+
+# app/controllers/payments_controller.rb
+class PaymentsController < ApplicationController
+  def create
+    @order = Order.create!(order_params)
+    
+    if @order.payment_successful?
+      # Trust this IP after successful payment (forever)
+      trust_current_ip(reason: 'payment_completed', order_id: @order.id)
+    end
+  end
+end
+```
+
+That's it! Reputable will now track all requests and you can query/apply reputations.
+
+---
+
+## Configuration Reference
+
+### Environment Variables
+
+All configuration can be set via environment variables:
+
+```bash
+# Required
+REPUTABLE_REDIS_URL=rediss://user:password@your-dragonfly.example.com:6379
+REPUTABLE_TENANT_ID=your-tenant-id
+
+# Optional: Disable entirely (useful for test environments)
+REPUTABLE_ENABLED=false
+
+# Optional: Connection tuning
+REPUTABLE_CONNECT_TIMEOUT=0.5   # Redis connect timeout (seconds)
+REPUTABLE_READ_TIMEOUT=0.5      # Redis read timeout (seconds)
+REPUTABLE_WRITE_TIMEOUT=0.5     # Redis write timeout (seconds)
+REPUTABLE_POOL_SIZE=5           # Connection pool size
+REPUTABLE_POOL_TIMEOUT=1.0      # Pool checkout timeout (seconds)
+
+# Optional: SSL (for custom certificates)
+REPUTABLE_SSL_VERIFY=false      # Disable SSL verification (NOT recommended for production)
+```
+
+### Full Configuration Options
+
+```ruby
+Reputable.configure do |config|
+  # Redis connection (supports redis:// and rediss:// for TLS)
+  config.redis_url = ENV['REPUTABLE_REDIS_URL']
+  
+  # Your tenant identifier
+  config.tenant_id = ENV['REPUTABLE_TENANT_ID']
+  
+  # Connection pool settings
+  config.pool_size = 5           # Number of Redis connections
+  config.pool_timeout = 1.0      # Max wait for connection (seconds)
+  
+  # Redis operation timeouts
+  config.connect_timeout = 0.5   # Connection timeout
+  config.read_timeout = 0.5      # Read timeout  
+  config.write_timeout = 0.5     # Write timeout
+  
+  # Custom SSL parameters (for self-signed certs, etc.)
+  config.ssl_params = {
+    ca_file: '/path/to/ca.crt',
+    verify_mode: OpenSSL::SSL::VERIFY_PEER
+  }
+  
+  # Customize TTLs (in seconds, 0 = forever)
+  config.default_ttls = {
+    trusted_verified: 0,              # Forever
+    trusted_behavior: 30 * 24 * 3600, # 30 days
+    untrusted_challenge: 7 * 24 * 3600,
+    untrusted_block: 7 * 24 * 3600,
+    untrusted_ignore: 7 * 24 * 3600
+  }
+  
+  # IP header priority (for proxy environments)
+  # Default covers Heroku, Cloudflare, AWS ALB, nginx, HAProxy
+  config.ip_header_priority = %w[
+    HTTP_CF_CONNECTING_IP
+    HTTP_X_FORWARDED_FOR
+    HTTP_X_REAL_IP
+    HTTP_TRUE_CLIENT_IP
+    REMOTE_ADDR
+  ]
+  
+  # Error callback (optional)
+  config.on_error = ->(error, context) {
+    # Report to your error tracking service
+    Sentry.capture_exception(error, extra: { context: context })
+  }
+end
+
+# Enable logging
+Reputable.logger = Rails.logger
+```
+
+---
+
+## Proxy & Load Balancer Support
+
+The gem automatically handles IP extraction in proxy environments including:
+
+- **Heroku** - Uses `X-Forwarded-For`
+- **Cloudflare** - Uses `CF-Connecting-IP` (highest priority by default)
+- **AWS ALB/ELB** - Uses `X-Forwarded-For`
+- **nginx** - Uses `X-Real-IP` or `X-Forwarded-For`
+- **HAProxy** - Uses `X-Forwarded-For`
+- **Google Cloud Load Balancer** - Uses `X-Forwarded-For`
+
+### How IP Extraction Works
+
+1. Headers are checked in priority order (configurable via `ip_header_priority`)
+2. For `X-Forwarded-For`, we parse the leftmost **public** IP (skipping private ranges)
+3. Private IP ranges (10.x, 172.16.x, 192.168.x, etc.) are automatically filtered
+
+### Custom Proxy Configuration
+
+```ruby
+# If your proxy uses a non-standard header
+config.ip_header_priority = %w[
+  HTTP_X_MY_CUSTOM_IP
+  HTTP_X_FORWARDED_FOR
+  REMOTE_ADDR
+]
+```
+
+---
+
+## TLS/SSL Support
+
+The gem fully supports TLS connections to Redis/Dragonfly:
+
+```ruby
+# Use rediss:// scheme for TLS
+config.redis_url = "rediss://user:password@your-server:6379"
+```
+
+### SSL Error Handling
+
+All SSL errors are caught and logged, never breaking your application:
+
+- Certificate verification failures
+- Handshake timeouts
+- Protocol errors
+- Self-signed certificate issues
+
+### Custom Certificates
+
+```ruby
+config.ssl_params = {
+  ca_file: '/path/to/custom-ca.crt',
+  cert: OpenSSL::X509::Certificate.new(File.read('/path/to/client.crt')),
+  key: OpenSSL::PKey::RSA.new(File.read('/path/to/client.key'))
+}
+```
+
+### Disable SSL Verification (Development Only)
+
+```bash
+# NOT recommended for production
+REPUTABLE_SSL_VERIFY=false
+```
+
+---
+
+## Middleware Configuration
+
+### Basic Usage
+
+```ruby
+# config/application.rb
+config.middleware.use Reputable::Middleware
+```
+
+### With Options
+
+```ruby
+config.middleware.use Reputable::Middleware,
+  # Skip certain paths (health checks, assets, etc.)
+  skip_paths: ['/health', '/healthz', '/assets', '/packs'],
+  
+  # Skip by file extension
+  skip_extensions: ['.js', '.css', '.png', '.jpg', '.svg'],
+  
+  # Custom skip logic
+  skip_if: ->(env) { 
+    env['HTTP_X_INTERNAL'] == 'true' ||
+    env['PATH_INFO'].start_with?('/admin')
+  },
+  
+  # Add custom tags based on request
+  tag_builder: ->(env) {
+    tags = []
+    tags << "env:#{Rails.env}"
+    tags << "mobile:true" if env['HTTP_USER_AGENT']&.include?('Mobile')
+    tags
+  },
+  
+  # Async mode (default: true) - tracking runs in background thread
+  async: true
+```
+
+### Default Skipped Paths
+
+The middleware automatically skips:
+- `/health`, `/healthz`, `/ready`, `/readyz`, `/live`, `/livez`
+- `/metrics`, `/favicon.ico`
+- Static assets (`.js`, `.css`, `.png`, `.jpg`, `.svg`, `.woff`, etc.)
+
+---
+
+## Controller Helpers (Rails)
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Reputable::Rails::ControllerHelpers
+end
+```
+
+### Available Methods
+
+```ruby
+# Track current request manually (if not using middleware)
+track_reputable_request(tags: ['custom:tag'])
+
+# Trust methods (after successful actions)
+trust_current_ip(reason: 'payment_completed', order_id: '123')
+trust_current_user(reason: 'email_verified')
+trust_current_session(reason: 'captcha_passed')
+
+# Challenge/Block methods
+challenge_current_ip(reason: 'suspicious_activity')
+block_current_ip(reason: 'abuse_detected')
+
+# Lookup methods
+if current_ip_trusted?
+  # Skip CAPTCHA, higher rate limits
+end
+
+if current_ip_blocked?
+  render status: 403
+  return
+end
+
+# Get full reputation data
+rep = current_ip_reputation
+# => { status: 'trusted_verified', reason: 'payment', ... }
+```
+
+---
+
+## Manual API Usage
+
+### Request Tracking
+
+```ruby
+# Synchronous (blocks until complete)
+Reputable.track_request(
+  ip: request.ip,
+  path: request.path,
+  query: request.query_string,
+  method: request.request_method,
+  session_id: session.id,
+  session_present: true,
+  user_agent: request.user_agent,
+  referer: request.referer,
+  tags: ['ctx:page:product']
+)
+
+# Asynchronous (fire-and-forget, recommended)
+Reputable.track_request_async(
+  ip: request.ip,
+  path: request.path
+)
+```
+
+### Reputation Management
+
+```ruby
+# Trust IP forever (after payment, verification, etc.)
+Reputable.trust_ip(request.ip, reason: 'payment_completed', order_id: order.id)
+
+# Trust a user
+Reputable.trust_user(current_user.id, reason: 'email_verified')
+
+# Trust a session (default: 24 hour TTL)
+Reputable.trust_session(session.id, reason: 'captcha_passed')
+
+# Challenge (require CAPTCHA, etc.)
+Reputable.challenge_ip(request.ip, reason: 'unusual_activity')
+
+# Block (with custom TTL)
+Reputable.block_ip(request.ip, reason: 'abuse', ttl: 7.days.to_i)
+
+# Ignore in analytics (internal monitoring, etc.)
+Reputable.ignore_ip(request.ip, reason: 'internal_monitoring')
+```
+
+### Reputation Lookup (O(1) Redis)
+
+```ruby
+# Quick boolean checks
+Reputable.trusted_ip?(request.ip)    # => true/false
+Reputable.blocked_ip?(request.ip)    # => true/false
+Reputable.challenged_ip?(request.ip) # => true/false
+
+# Get status string
+Reputable.lookup_ip(request.ip)
+# => "trusted_verified" or "untrusted_block" or nil
+
+# Full lookup with metadata
+Reputable.lookup_reputation(:ip, request.ip)
+# => { status: "trusted_verified", reason: "payment_completed", 
+#      source: "app_server", updated_at: 1703123456789, 
+#      expires_at: 0, metadata: { order_id: "123" } }
+
+# User/Session lookups
+Reputable.trusted_user?(current_user.id)
+Reputable.trusted_session?(session.id)
+```
+
+---
+
+## Resilience & Failsafe Features
+
+### Never Breaks Your App
+
+The gem is designed with resilience as the top priority:
+
+1. **All operations fail silently** - Returns `false`/`nil` on any error
+2. **No exceptions propagate** - Everything is wrapped in rescue blocks
+3. **Circuit breaker** - After 5 failures, stops trying for 30 seconds
+
+### Disable via Environment
+
+```bash
+# Completely disable (useful for test/CI environments)
+REPUTABLE_ENABLED=false
+```
+
+```ruby
+# Check in code
+if Reputable.enabled?
+  # Only when enabled
+end
+```
+
+### Safe Return Values
+
+| Operation | Returns on Failure |
+|-----------|-------------------|
+| `track_request` | `false` |
+| `trust_ip`, `block_ip`, etc. | `false` |
+| `lookup_ip`, `lookup_reputation` | `nil` |
+| `trusted_ip?`, `blocked_ip?` | `false` |
+| Middleware tracking | silently skipped |
+
+### Circuit Breaker
+
+- Opens after 5 consecutive failures
+- While open, returns defaults immediately (no Redis calls)
+- Resets after 30 seconds
+
+### Error Callback
+
+```ruby
+config.on_error = ->(error, context) {
+  # Log to your error service
+  Rails.logger.warn("Reputable error: #{error.class} in #{context}")
+  Sentry.capture_exception(error)
+}
+```
+
+---
+
+## Tags for Classification
+
+Use tags to classify requests for behavioral analysis:
+
+```ruby
+# Page context
+tags: ['ctx:page:product']
+tags: ['ctx:page:checkout']
+tags: ['ctx:page:cart']
+tags: ['ctx:page:login']
+
+# Traffic source
+tags: ['trust:channel:email']
+tags: ['trust:channel:ad']
+tags: ['trust:channel:organic']
+
+# Trust signals (from verified actions)
+tags: ['trust:financial:payment']
+tags: ['trust:auth:login']
+tags: ['trust:identity:verified']
+tags: ['trust:interactive:captcha']
+```
+
+---
+
+## Testing
+
+### Disable in Test Environment
+
+```ruby
+# config/environments/test.rb
+ENV['REPUTABLE_ENABLED'] = 'false'
+
+# Or in spec_helper.rb
+RSpec.configure do |config|
+  config.before(:suite) do
+    ENV['REPUTABLE_ENABLED'] = 'false'
+  end
+end
+```
+
+### Mock Lookups
+
+```ruby
+# In tests, lookups return nil when disabled
+expect(Reputable.trusted_ip?('1.2.3.4')).to eq(false)
+expect(Reputable.lookup_ip('1.2.3.4')).to be_nil
+```
+
+---
+
+## How It Works
+
+1. **Request Tracking**: Your Rails app pushes request data to Redis buffers
+2. **Async Processing**: Reputable API processes buffers asynchronously  
+3. **Behavioral Analysis**: Requests go through classification and pattern analysis
+4. **Reputation Storage**: Scores stored in Redis for O(1) lookups
+
+### What's Available from Rails
+
+- IP reputation and history
+- Session tracking
+- Request classification
+- UA churn detection
+- Cross-request pattern analysis
+- Manual reputation overrides
+
+### What Requires Edge Deployment
+
+- JA4/JA3 TLS fingerprints
+- HAProxy timing analysis
+- Geo-latency heuristics
+
+---
+
+## License
+
+MIT

data/lib/reputable/configuration.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "ipaddr"
+
+module Reputable
+  # Configuration class for Reputable client
+  #
+  # Supports TLS connections with automatic SSL error handling.
+  # All SSL/connection errors are caught and logged, never breaking your app.
+  class Configuration
+    attr_accessor :redis_url, :redis_options, :tenant_id, :buffer_prefix,
+                  :request_buffer_key, :reputation_buffer_key,
+                  :default_ttls, :pool_size, :pool_timeout,
+                  :connect_timeout, :read_timeout, :write_timeout,
+                  :ssl_params, :trusted_proxies, :ip_header_priority,
+                  :on_error
+
+    # Default TTLs in seconds (0 = forever)
+    DEFAULT_TTLS = {
+      trusted_verified: 0,          # Forever
+      trusted_behavior: 30 * 24 * 3600, # 30 days
+      untrusted_challenge: 7 * 24 * 3600, # 7 days
+      untrusted_block: 7 * 24 * 3600,     # 7 days
+      untrusted_ignore: 7 * 24 * 3600     # 7 days
+    }.freeze
+
+    # Default IP header priority (first match wins)
+    # Covers: Heroku, Cloudflare, AWS ALB/ELB, nginx, HAProxy, generic proxies
+    DEFAULT_IP_HEADERS = %w[
+      HTTP_CF_CONNECTING_IP
+      HTTP_X_FORWARDED_FOR
+      HTTP_X_REAL_IP
+      HTTP_TRUE_CLIENT_IP
+      HTTP_X_CLIENT_IP
+      HTTP_X_CLUSTER_CLIENT_IP
+      HTTP_FORWARDED
+      REMOTE_ADDR
+    ].freeze
+
+    # Common private/internal IP ranges to skip when parsing X-Forwarded-For
+    PRIVATE_IP_RANGES = %w[
+      127.0.0.0/8
+      10.0.0.0/8
+      172.16.0.0/12
+      192.168.0.0/16
+      ::1/128
+      fc00::/7
+      fe80::/10
+    ].freeze
+
+    def initialize
+      @redis_url = ENV.fetch("REPUTABLE_REDIS_URL", "redis://127.0.0.1:6379")
+      @redis_options = {}
+      @tenant_id = ENV.fetch("REPUTABLE_TENANT_ID", "default")
+      @buffer_prefix = "reputable:buffer"
+      @pool_size = Integer(ENV.fetch("REPUTABLE_POOL_SIZE", "5"))
+      @pool_timeout = Float(ENV.fetch("REPUTABLE_POOL_TIMEOUT", "1.0"))
+      @connect_timeout = Float(ENV.fetch("REPUTABLE_CONNECT_TIMEOUT", "0.5"))
+      @read_timeout = Float(ENV.fetch("REPUTABLE_READ_TIMEOUT", "0.5"))
+      @write_timeout = Float(ENV.fetch("REPUTABLE_WRITE_TIMEOUT", "0.5"))
+      @default_ttls = DEFAULT_TTLS.dup
+      @ssl_params = nil  # Use system defaults, or override for custom CA/certs
+      @trusted_proxies = nil  # Additional trusted proxy IPs/ranges
+      @ip_header_priority = DEFAULT_IP_HEADERS.dup
+      @on_error = nil  # Optional error callback: ->(error, context) { ... }
+    end
+
+    # Check if Reputable is enabled (can be disabled via ENV)
+    def enabled?
+      env_value = ENV["REPUTABLE_ENABLED"]
+      return true if env_value.nil?  # Enabled by default
+      
+      !%w[0 false no off disabled].include?(env_value.to_s.downcase)
+    end
+
+    def request_buffer_key
+      @request_buffer_key || "#{buffer_prefix}:requests:#{tenant_id}"
+    end
+
+    def reputation_buffer_key
+      @reputation_buffer_key || "#{buffer_prefix}:reputation:#{tenant_id}"
+    end
+
+    def default_ttl_for(status)
+      status_sym = status.to_sym
+      @default_ttls[status_sym] || DEFAULT_TTLS[:untrusted_challenge]
+    end
+
+    # Check if Redis URL uses TLS (rediss:// scheme)
+    def tls?
+      redis_url&.start_with?("rediss://")
+    end
+
+    # Build SSL params for Redis connection
+    # Merges custom ssl_params with sensible defaults
+    def effective_ssl_params
+      return nil unless tls?
+      
+      defaults = {
+        verify_mode: OpenSSL::SSL::VERIFY_PEER
+      }
+      
+      # Allow disabling SSL verification via ENV (not recommended for production)
+      if ENV["REPUTABLE_SSL_VERIFY"] == "false"
+        defaults[:verify_mode] = OpenSSL::SSL::VERIFY_NONE
+      end
+      
+      ssl_params ? defaults.merge(ssl_params) : defaults
+    end
+
+    # Parse private IP ranges for filtering X-Forwarded-For
+    def private_ip_ranges
+      @private_ip_ranges ||= PRIVATE_IP_RANGES.map { |cidr| IPAddr.new(cidr) }
+    end
+
+    # Check if an IP is private/internal
+    def private_ip?(ip)
+      return true if ip.nil? || ip.empty?
+      
+      addr = IPAddr.new(ip)
+      private_ip_ranges.any? { |range| range.include?(addr) }
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+  end
+end