reputable 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cfe6bbd421f190d87e5f0be242142988e269d8df74186f85f66c8f5996f115f
-  data.tar.gz: 4db1343a290ef95d775b0694a50d84d48c861af293bf0d3e4d388e44c031c9d0
+  metadata.gz: ca78832e420ad0cacad0c44bbfbf2a682f1b9f702bbaf8aa07a44e4e04d7d53b
+  data.tar.gz: 9e15f534984a4e3d67560a98cbede0c596d02d30fb7f7171b380b043b0781384
 SHA512:
-  metadata.gz: 211cb949190c13bd0f3d8f6c4f0296a84c92653e64c2971d5866e0606cc777ebfe356a8a73d10e5a269f6701105372f9c4c8203f90bf75f279958b385874c3ad
-  data.tar.gz: 14dbcf3338f725de441618100e0b57e99314974e0ff89b787c45141dcec56fa6c230c9acaa69feaed42233a87cf10add2cc2ccca2e80883eddb656779821ace6
+  metadata.gz: 23832e31d409bb3316c33c931e6207f24eb2ea078c2fa79d3d0c4618e4ffd3359f525d0c6b090344bb5d8e79cf9fdc714752ae09180ce973dd353d93015afb6c
+  data.tar.gz: 9eb4a989b111a493e7555672057946c2928251a1112e7b75e011bf7183c329ee3b9c6c6cb0e34a163d3803cb5956321b443b25f2d9fcbfca5c90ad16b73cd766

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    reputable (0.1.2)
+    reputable (0.1.3)
       connection_pool (~> 2.2)
       redis (>= 4.0, < 6.0)
 

data/README.md

@@ -135,6 +135,11 @@ Reputable.configure do |config|
     REMOTE_ADDR
   ]
   
+  # Verification Configuration
+  # Supports comma-separated list in REPUTABLE_TRUSTED_KEYS or single key in REPUTABLE_TRUSTED_KEY
+  config.trusted_keys = ENV['REPUTABLE_TRUSTED_KEYS']&.split(',') || ENV['REPUTABLE_TRUSTED_KEY']
+  config.verification_base_url = ENV['REPUTABLE_VERIFY_URL']     # URL of your Reputable API verify endpoint
+  
   # Error callback (optional)
   config.on_error = ->(error, context) {
     # Report to your error tracking service
@@ -359,6 +364,78 @@ Reputable.lookup_reputation(:ip, request.ip)
 
 ---
 
+## User Verification & Trust Flow
+
+When you identify a suspicious user (e.g., high risk score or specific tag), you can redirect them to the Reputable verification page. This page performs advanced browser checks and challenges (CAPTCHA) if necessary.
+
+### 1. Generating a Signed Redirect URL
+
+To effectively hand off verification handling to Reputable, generate a signed verification URL:
+
+```ruby
+# In your controller
+if suspicious_activity_detected?
+  redirect_url = Reputable.verification_url(
+    return_url: request.original_url, # Where to send them back after verification
+    failure_url: root_url,            # Optional: where to send if they fail/garbage token
+    session_id: session.id            # Optional: link specific session
+  )
+  
+  redirect_to redirect_url
+end
+```
+
+### 2. Handling the Return Redirect
+
+When the user passes verification (or is determined to be already trusted/clean), they are immediately redirected back to your `return_url` with signed parameters.
+
+**Middleware (Automatic Handling):**
+If you are using `Reputable::Middleware` (recommended), this is handled automatically. The middleware detects the return parameters, verifies the signature, and sets `env['reputable.verified'] = true`.
+
+```ruby
+# In your controller
+if request.env['reputable.verified']
+  # User just passed verification!
+  # You might want to graduate them to trusted status locally
+  trust_current_ip(reason: 'interactive_verification')
+end
+```
+
+**Manual Verification:**
+If you need to verify manually (e.g., custom controller logic):
+
+```ruby
+# In your controller action (the return_url target)
+if params[:reputable_signature]
+  if Reputable.verify_redirect_return(params)
+    # Signature is VALID. Meaning Reputable actually sent this user back.
+    
+    # Inspect outcomes
+    status = params[:reputable_status]   # 'pass', 'fail'
+    outcome = params[:reputable_outcome] # 'trusted_verified', 'trusted_behavior', 'unknown'
+    country = params[:reputable_country] # 'US', 'DE', etc.
+    
+    if status == 'pass'
+      # Grant access
+    end
+  else
+    # Invalid signature - potential tampering attempt!
+    render plain: "Verification failed", status: 403
+  end
+end
+```
+
+**Return Parameters:**
+The return URL will contain:
+- `reputable_status`: `pass` or `fail`
+- `reputable_session_id`: The session ID you provided
+- `reputable_outcome`: The specific reputation outcome (e.g., `trusted_verified`)
+- `reputable_ignore_analytics`: 'true'/'false' flag
+- `reputable_country`: ISO country code
+- `reputable_signature`: HMAC-SHA256 signature of the above
+
+---
+
 ## Resilience & Failsafe Features
 
 ### Never Breaks Your App

data/lib/reputable/configuration.rb

@@ -14,7 +14,7 @@ module Reputable
                   :default_ttls, :pool_size, :pool_timeout,
                   :connect_timeout, :read_timeout, :write_timeout,
                   :ssl_params, :trusted_proxies, :ip_header_priority,
-                  :on_error, :secret_key, :verification_base_url
+                  :on_error, :trusted_keys, :verification_base_url
 
     # Default TTLs in seconds (0 = forever)
     DEFAULT_TTLS = {
@@ -63,10 +63,36 @@ module Reputable
       @trusted_proxies = nil  # Additional trusted proxy IPs/ranges
       @ip_header_priority = DEFAULT_IP_HEADERS.dup
       @on_error = nil  # Optional error callback: ->(error, context) { ... }
-      @secret_key = ENV["REPUTABLE_SECRET_KEY"]
+      
+      # Support multiple trusted keys (comma-separated), fallback to old secret key env var
+      @trusted_keys = []
+      if ENV["REPUTABLE_TRUSTED_KEYS"]
+        @trusted_keys = ENV["REPUTABLE_TRUSTED_KEYS"].split(",").map(&:strip)
+      elsif ENV["REPUTABLE_TRUSTED_KEY"]
+        @trusted_keys = [ENV["REPUTABLE_TRUSTED_KEY"]]
+      elsif ENV["REPUTABLE_SECRET_KEY"]
+        @trusted_keys = [ENV["REPUTABLE_SECRET_KEY"]]
+      end
       @verification_base_url = ENV.fetch("REPUTABLE_VERIFY_URL", "https://api.reputable.click/_reputable/verify")
     end
 
+    # Alias for backward compatibility
+    def secret_key
+      @trusted_keys.first
+    end
+
+    def secret_key=(key)
+      @trusted_keys = [key]
+    end
+
+    def trusted_keys=(keys)
+      @trusted_keys = Array(keys)
+    end
+
+    def trusted_keys
+      @trusted_keys
+    end
+
     # Check if Reputable is enabled (can be disabled via ENV)
     def enabled?
       env_value = ENV["REPUTABLE_ENABLED"]

data/lib/reputable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Reputable
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/reputable.rb

@@ -127,12 +127,15 @@ module Reputable
 
     # Generate a signed verification URL
     def verification_url(return_url:, failure_url: nil, session_id: nil)
-      secret = configuration.secret_key
-      unless secret
-        logger&.warn "Reputable: Missing secret_key, cannot generate verification URL"
+      keys = configuration.trusted_keys
+      if keys.nil? || keys.empty?
+        logger&.warn "Reputable: Missing trusted_keys, cannot generate verification URL"
         return return_url 
       end
       
+      # Use the first key for signing new requests
+      secret = keys.first
+      
       base_url = configuration.verification_base_url
       
       # JWT Header
@@ -165,19 +168,35 @@ module Reputable
       status = params["reputable_status"]
       session_id = params["reputable_session_id"]
       signature = params["reputable_signature"]
+      outcome = params["reputable_outcome"]
+      ignore_analytics = params["reputable_ignore_analytics"]
+      country = params["reputable_country"] || ""
       
       return false unless status && session_id && signature
       
-      secret = configuration.secret_key
-      unless secret
-        logger&.warn "Reputable: Missing secret_key, cannot verify redirect"
+      keys = configuration.trusted_keys
+      if keys.nil? || keys.empty?
+        logger&.warn "Reputable: Missing trusted_keys, cannot verify redirect"
         return false
       end
       
-      data = "#{status}:#{session_id}"
-      expected_signature = OpenSSL::HMAC.hexdigest("SHA256", secret, data)
+      # Reconstruct data string: status:sessionId:outcome:ignoreAnalytics:country
+      # Note: optional params default to empty strings if missing in reconstruction logic on server
+      data_parts = [
+        status,
+        session_id,
+        outcome || "",
+        ignore_analytics.nil? ? "" : ignore_analytics,
+        country
+      ]
+      
+      data = data_parts.join(":")
       
-      secure_compare(expected_signature, signature)
+      # Iterate through all trusted keys to find a match
+      keys.any? do |key|
+        expected_signature = OpenSSL::HMAC.hexdigest("SHA256", key, data)
+        secure_compare(expected_signature, signature)
+      end
     end
 
     private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reputable
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Reputable
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-25 00:00:00.000000000 Z
+date: 2025-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis