reputable 0.1.21 → 0.1.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbabd6630a3e0d348391e2795ea58cd8a858944101b0ac8a0dfaa04277b16035
-  data.tar.gz: 3939cf81a472b76d4084d6236a39242d7a693e9f2434df576ac73bb153e8c5d0
+  metadata.gz: 1f667ca542120eb294a6c61a0650a1c1deb82b5383c87e8d744c98c9fba7548a
+  data.tar.gz: d061fbe002a8ae3c96bbbf45b7470f5df4bdac89f49bcb36f42ab1e676ee5699
 SHA512:
-  metadata.gz: 4e868fd7037ffbecfda2be3103486940210bae975619d51d9c9f68521c0a9d7ea36bf7ebbea7ae5da8c90e19158fc11bbe82762b65c00d216d03d1342eb78d2a
-  data.tar.gz: f664f98a97054be9f2f9ddc89611f2fb68028b641eb47057534633dec2291939f770a792bc0b0506d7ce2297f0c5648e36d885315490810b338fe6dee1c6ca34
+  metadata.gz: 0f47bb9c880009d89a36d71ef0021edd07de2b87fb38ab5625625b89d7ad0240391fbc5ff4e5630e12bc7fafc4290a9649aec9685c25cfca5c28546e8e9699f6
+  data.tar.gz: 7223bdf677132850ccb4ef226c8540dad07fba22853c9461873a696b3c16f52a65fc06eba1757aeb121607470baea291e027db7364a19ee9c505a92bbec1b49d

data/Gemfile.lock

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

data/README.md

@@ -29,10 +29,13 @@ bundle install
 Reputable.configure do |config|
   # Required: Redis/Dragonfly URL (TLS supported via rediss://)
   config.redis_url = ENV['REPUTABLE_REDIS_URL']
-  
-  # Optional: Enable logging (logs at debug level)
-  Reputable.logger = Rails.logger
+
+  # Optional: Verbose logging (logs every middleware decision)
+  # config.verbose = true
 end
+
+# Optional: Enable logging
+Reputable.logger = Rails.logger
 ```
 
 ### 2. Add Middleware
@@ -100,6 +103,9 @@ 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: Verbose logging (logs every middleware decision at info level)
+REPUTABLE_VERBOSE=true
+
 # Optional: SSL (for custom certificates)
 REPUTABLE_SSL_VERIFY=false      # Disable SSL verification (NOT recommended for production)
 ```
@@ -155,6 +161,10 @@ Reputable.configure do |config|
   config.support_email = ENV['REPUTABLE_SUPPORT_EMAIL']
   config.support_url = ENV['REPUTABLE_SUPPORT_URL']
   
+  # Verbose logging — logs every middleware decision at info level
+  # Also available via REPUTABLE_VERBOSE=true
+  config.verbose = true
+
   # Error callback (optional)
   config.on_error = ->(error, context) {
     # Report to your error tracking service
@@ -162,7 +172,7 @@ Reputable.configure do |config|
   }
 end
 
-# Enable logging
+# Enable logging (required for verbose output)
 Reputable.logger = Rails.logger
 ```
 
@@ -719,6 +729,42 @@ config.on_error = ->(error, context) {
 
 ---
 
+## Verbose Logging / Debugging
+
+When troubleshooting middleware behavior (e.g., unexpected redirects or blocked requests), enable verbose mode to see every decision the gem makes:
+
+```ruby
+# config/initializers/reputable.rb
+Reputable.configure do |config|
+  config.verbose = true
+  # ...
+end
+Reputable.logger = Rails.logger
+```
+
+Or via environment variable:
+
+```bash
+REPUTABLE_VERBOSE=true
+```
+
+When enabled, the middleware logs at `info` level with a `[Reputable]` prefix. Example output for a challenged request:
+
+```
+[Reputable] request: GET / ip=68.6.118.12 rid=abc-123
+[Reputable] state: enabled=true operational=true gate=true track=false
+[Reputable] extract_ip: 68.6.118.12 (from HTTP_X_FORWARDED_FOR: 68.6.118.12, 10.0.0.1)
+[Reputable] lookup: reputation:ip:68.6.118.12 → status=untrusted_challenge reason=inherited:asn:7922 source=inherited
+[Reputable] gate: ip=68.6.118.12 status="untrusted_challenge"
+[Reputable] verified_session?: false (reputable_verified_at= reputable_verified=)
+[Reputable] gate: CHALLENGING ip=68.6.118.12 action=verify
+[Reputable] challenge: REDIRECTING 302 → https://api.reputable.click/_reputable/verify?token=...
+```
+
+When verbose is `false` (the default), none of these logs are emitted.
+
+---
+
 ## Tags for Classification
 
 Use tags to classify requests for behavioral analysis:

data/lib/reputable/configuration.rb

@@ -15,7 +15,8 @@ module Reputable
                   :connect_timeout, :read_timeout, :write_timeout,
                   :ssl_params, :trusted_proxies, :ip_header_priority,
                   :on_error, :trusted_keys, :base_url,
-                  :site_name, :support_email, :support_url
+                  :site_name, :support_email, :support_url,
+                  :verbose
 
     # Alias for backward compatibility
     alias_method :verification_base_url, :base_url
@@ -82,6 +83,7 @@ module Reputable
       @site_name = ENV["REPUTABLE_SITE_NAME"]
       @support_email = ENV["REPUTABLE_SUPPORT_EMAIL"]
       @support_url = ENV["REPUTABLE_SUPPORT_URL"]
+      @verbose = %w[1 true yes on].include?(ENV.fetch("REPUTABLE_VERBOSE", "").downcase)
     end
 
     # Alias for backward compatibility

data/lib/reputable/middleware.rb

@@ -67,6 +67,10 @@ module Reputable
       # This ID is exposed to views so it can be included in the JS snippet
       env['reputable.request_id'] = SecureRandom.uuid
 
+      ip = extract_ip(env)
+      env["reputable.ip"] = ip
+      path = env["PATH_INFO"] || "/"
+
       # Check for verification return parameters and verify signature if present
       handle_verification_return(env)
 
@@ -90,6 +94,12 @@ module Reputable
       # All tracking is wrapped in rescue to ensure it never fails
       safe_track_request(env)
 
+      # Single summary line for requests that passed through without intervention
+      if Reputable.verbose?
+        rep_status = env["reputable.reputation_status"]
+        Reputable.logger&.info("[Reputable] #{env['REQUEST_METHOD']} #{path} ip=#{ip} status=#{rep_status || 'unknown'} gate=#{@reputation_gate} result=pass")
+      end
+
       [status, headers, response]
     end
 
@@ -98,25 +108,34 @@ module Reputable
     def safe_reputation_gate(env)
       return nil unless @reputation_gate
       return nil unless Reputable.enabled?
-      return nil unless Reputable.operational?
+      unless Reputable.operational?
+        Reputable.logger&.warn("[Reputable] gate: skipped (not operational, circuit_breaker=#{Connection.circuit_open? ? 'open' : 'closed'})") if Reputable.verbose?
+        return nil
+      end
       return nil if skip_request?(env)
 
       enforce_reputation_gate(env)
     rescue StandardError => e
-      Reputable.logger&.debug("Reputable reputation gate: #{e.class} - #{e.message}")
+      Reputable.logger&.warn("[Reputable] gate: exception #{e.class} - #{e.message}")
+      Reputable.logger&.debug(e.backtrace&.first(5)&.join("\n")) if Reputable.verbose?
       nil
     end
 
     def enforce_reputation_gate(env)
       status = reputation_status(env)
-      return nil if status.nil?
       ip = env["reputable.ip"] || extract_ip(env)
 
+      return nil if status.nil?
+
       case status
       when "untrusted_block"
+        Reputable.logger&.info("[Reputable] gate: BLOCKING ip=#{ip} action=#{@block_action}")
         handle_block_action(env, ip)
       when "untrusted_challenge"
-        return nil if verified_session?(env)
+        if verified_session?(env)
+          return nil
+        end
+        Reputable.logger&.info("[Reputable] gate: CHALLENGING ip=#{ip} action=#{@challenge_action}")
         handle_challenge_action(env)
       else
         nil
@@ -160,15 +179,19 @@ module Reputable
 
       # Determine status from new format or legacy format
       status = if params["reputable_r"]
-        decoded = Reputable.decode_reputable_response(params)
-        decoded&.dig("status")
+        Reputable.decode_reputable_response(params)&.dig("status")
       else
         params["reputable_status"]
       end
 
-      return unless status == "pass"
+      unless status == "pass"
+        Reputable.logger&.info("[Reputable] verification: status=#{status.inspect} (not 'pass'), ignoring") if Reputable.verbose?
+        return
+      end
+
+      sig_valid = Reputable.verify_redirect_return(params)
 
-      if Reputable.verify_redirect_return(params)
+      if sig_valid
         env["reputable.verified"] = true
 
         # Extract ignore_analytics from new format or legacy format
@@ -182,15 +205,20 @@ module Reputable
         unless ignore_analytics.nil?
           env["reputable.ignore_analytics"] = ignore_analytics == true || ignore_analytics.to_s == "true"
         end
-        
+
         # Store in session if available
         if env["rack.session"]
           env["rack.session"]["reputable_verified"] = true
           env["rack.session"]["reputable_verified_at"] = Time.now.to_i
         end
+
+        Reputable.logger&.info("[Reputable] verification: pass, stored in session") if Reputable.verbose?
+      else
+        Reputable.logger&.warn("[Reputable] verification: INVALID signature, rejecting")
       end
     rescue StandardError => e
-      Reputable.logger&.debug("Reputable verification error: #{e.message}")
+      Reputable.logger&.warn("[Reputable] verification: exception #{e.class} - #{e.message}")
+      Reputable.logger&.debug(e.backtrace&.first(5)&.join("\n")) if Reputable.verbose?
     end
 
     def handle_blocked_page_request(env)
@@ -212,6 +240,7 @@ module Reputable
         build_blocked_page_response(ip)
       when :blocked_page_remote
         url = resolve_blocked_redirect_url(env) || Reputable.blocked_page_url
+        Reputable.logger&.info("[Reputable] block: REDIRECTING #{@blocked_redirect_status} → #{url}")
         redirect_response(url, @blocked_redirect_status)
       when :forbidden
         [403, { "Content-Type" => "text/plain; charset=utf-8" }, ["Forbidden"]]
@@ -226,7 +255,10 @@ module Reputable
       case @challenge_action
       when :verify
         keys = Reputable.configuration.trusted_keys
-        return nil if keys.nil? || keys.empty?
+        if keys.nil? || keys.empty?
+          Reputable.logger&.warn("[Reputable] challenge: no trusted_keys configured, cannot redirect to verification")
+          return nil
+        end
 
         request = Rack::Request.new(env)
         return_url = request.url
@@ -242,6 +274,7 @@ module Reputable
 
         return nil if redirect_url == return_url
 
+        Reputable.logger&.info("[Reputable] challenge: REDIRECTING #{@challenge_redirect_status} → #{redirect_url}")
         redirect_response(redirect_url, @challenge_redirect_status)
       when Proc
         @challenge_action.call(env)
@@ -408,12 +441,12 @@ module Reputable
 
     def extract_ip(env)
       config = Reputable.configuration
-      
+
       # Try each header in priority order
       config.ip_header_priority.each do |header|
         value = env[header]
         next if value.nil? || value.empty?
-        
+
         # X-Forwarded-For and Forwarded can contain multiple IPs
         if header == "HTTP_X_FORWARDED_FOR"
           ip = extract_from_xff(value)
@@ -428,7 +461,6 @@ module Reputable
         end
       end
 
-      # Ultimate fallback
       "0.0.0.0"
     rescue StandardError
       "0.0.0.0"

data/lib/reputable/reputation.rb

@@ -138,15 +138,19 @@ module Reputable
           redis.hgetall(key)
         end
 
-        return nil if data.nil? || data.empty?
+        if data.nil? || data.empty?
+          Reputable.logger&.debug("[Reputable] lookup: #{key} → (none)") if Reputable.verbose?
+          return nil
+        end
 
         # Check if expired (Redis TTL should handle this, but double-check)
         expires_at = data["expires_at"].to_i
         if expires_at > 0 && expires_at < (Time.now.to_f * 1000).to_i
+          Reputable.logger&.debug("[Reputable] lookup: #{key} → expired") if Reputable.verbose?
           return nil
         end
 
-        {
+        result = {
           status: data["status"],
           reason: data["reason"],
           source: data["source"],
@@ -154,8 +158,11 @@ module Reputable
           expires_at: expires_at,
           metadata: safe_parse_json(data["metadata"])
         }
+
+        Reputable.logger&.info("[Reputable] lookup: #{key} → status=#{result[:status]} reason=#{result[:reason]} source=#{result[:source]}") if Reputable.verbose?
+        result
       rescue StandardError => e
-        Reputable.logger&.debug("Reputable lookup error: #{e.class} - #{e.message}")
+        Reputable.logger&.warn("[Reputable] lookup: exception #{e.class} - #{e.message}")
         nil
       end
 

data/lib/reputable/version.rb

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

data/lib/reputable.rb

@@ -69,6 +69,12 @@ module Reputable
       configuration.enabled?
     end
 
+    # Check if verbose logging is enabled
+    # @return [Boolean]
+    def verbose?
+      configuration.verbose
+    end
+
     # Check if Reputable is disabled
     # @return [Boolean]
     def disabled?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reputable
 version: !ruby/object:Gem::Version
-  version: 0.1.21
+  version: 0.1.23
 platform: ruby
 authors:
 - Reputable
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-07 00:00:00.000000000 Z
+date: 2026-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis