reputable 0.1.21 → 0.1.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbabd6630a3e0d348391e2795ea58cd8a858944101b0ac8a0dfaa04277b16035
-  data.tar.gz: 3939cf81a472b76d4084d6236a39242d7a693e9f2434df576ac73bb153e8c5d0
+  metadata.gz: 594ed67d80dc9ae5bd493bbe7c3322c4ed79f1d4e661b7e36ddc57d46d350c71
+  data.tar.gz: e9b6093d3cc1a23fe9f881d292984c92e7a32c86ccb52c1581f60a12eae94078
 SHA512:
-  metadata.gz: 4e868fd7037ffbecfda2be3103486940210bae975619d51d9c9f68521c0a9d7ea36bf7ebbea7ae5da8c90e19158fc11bbe82762b65c00d216d03d1342eb78d2a
-  data.tar.gz: f664f98a97054be9f2f9ddc89611f2fb68028b641eb47057534633dec2291939f770a792bc0b0506d7ce2297f0c5648e36d885315490810b338fe6dee1c6ca34
+  metadata.gz: c921b3e37a852a8226551cd43c4787760a3c41230dbfaf7535b93c62599185b7e9438c4421cf7e03533325036b184b4a6c817cedee69606f057dec27abb93b79
+  data.tar.gz: 6da6fc589dd71010685ef7e02d68b5c0b6c4a97fd457187f1c432fc9a5c992a8821d49bda29cd2f169ed95262e28c63a0f4be08b41d811555f166c5a14717c92

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,15 @@ 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"] || "/"
+
+      if Reputable.verbose?
+        Reputable.logger&.info("[Reputable] request: #{env['REQUEST_METHOD']} #{path} ip=#{ip} rid=#{env['reputable.request_id']}")
+        Reputable.logger&.info("[Reputable] state: enabled=#{Reputable.enabled?} operational=#{Reputable.operational?} gate=#{@reputation_gate} track=#{track_request_enabled?}")
+      end
+
       # Check for verification return parameters and verify signature if present
       handle_verification_return(env)
 
@@ -96,29 +105,53 @@ module Reputable
     private
 
     def safe_reputation_gate(env)
-      return nil unless @reputation_gate
-      return nil unless Reputable.enabled?
-      return nil unless Reputable.operational?
-      return nil if skip_request?(env)
+      unless @reputation_gate
+        Reputable.logger&.info("[Reputable] gate: skipped (reputation_gate=false)") if Reputable.verbose?
+        return nil
+      end
+      unless Reputable.enabled?
+        Reputable.logger&.info("[Reputable] gate: skipped (disabled)") if Reputable.verbose?
+        return nil
+      end
+      unless Reputable.operational?
+        Reputable.logger&.info("[Reputable] gate: skipped (not operational, circuit_breaker=#{Connection.circuit_open? ? 'open' : 'closed'} failures=#{Connection.failure_count})") if Reputable.verbose?
+        return nil
+      end
+      if skip_request?(env)
+        Reputable.logger&.info("[Reputable] gate: skipped (path excluded)") if Reputable.verbose?
+        return nil
+      end
 
       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)
 
+      if Reputable.verbose?
+        Reputable.logger&.info("[Reputable] gate: ip=#{ip} status=#{status.inspect}")
+      end
+
+      return nil if status.nil?
+
       case status
       when "untrusted_block"
+        Reputable.logger&.info("[Reputable] gate: BLOCKING ip=#{ip} action=#{@block_action}") if Reputable.verbose?
         handle_block_action(env, ip)
       when "untrusted_challenge"
-        return nil if verified_session?(env)
+        if verified_session?(env)
+          Reputable.logger&.info("[Reputable] gate: ip=#{ip} has untrusted_challenge but session is verified, passing through") if Reputable.verbose?
+          return nil
+        end
+        Reputable.logger&.info("[Reputable] gate: CHALLENGING ip=#{ip} action=#{@challenge_action}") if Reputable.verbose?
         handle_challenge_action(env)
       else
+        Reputable.logger&.info("[Reputable] gate: ip=#{ip} status=#{status} — allowing") if Reputable.verbose?
         nil
       end
     end
@@ -156,19 +189,29 @@ module Reputable
       query = request.query_string
       return unless query.include?("reputable_r") || query.include?("reputable_status")
 
+      Reputable.logger&.info("[Reputable] verification return detected in query string") if Reputable.verbose?
+
       params = request.params
 
       # Determine status from new format or legacy format
       status = if params["reputable_r"]
         decoded = Reputable.decode_reputable_response(params)
+        Reputable.logger&.info("[Reputable] verification: new format decoded=#{decoded.inspect}") if Reputable.verbose?
         decoded&.dig("status")
       else
+        Reputable.logger&.info("[Reputable] verification: legacy format status=#{params['reputable_status']}") if Reputable.verbose?
         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
 
-      if Reputable.verify_redirect_return(params)
+      sig_valid = Reputable.verify_redirect_return(params)
+      Reputable.logger&.info("[Reputable] verification: signature_valid=#{sig_valid}") if Reputable.verbose?
+
+      if sig_valid
         env["reputable.verified"] = true
 
         # Extract ignore_analytics from new format or legacy format
@@ -182,15 +225,21 @@ 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
+          Reputable.logger&.info("[Reputable] verification: stored in session, verified=true") if Reputable.verbose?
+        else
+          Reputable.logger&.info("[Reputable] verification: no rack.session available, cannot persist") if Reputable.verbose?
         end
+      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)
@@ -209,15 +258,20 @@ module Reputable
     def handle_block_action(env, ip)
       case @block_action
       when :blocked_page
+        Reputable.logger&.info("[Reputable] block: rendering inline blocked page for ip=#{ip}") if Reputable.verbose?
         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}") if Reputable.verbose?
         redirect_response(url, @blocked_redirect_status)
       when :forbidden
+        Reputable.logger&.info("[Reputable] block: returning 403 for ip=#{ip}") if Reputable.verbose?
         [403, { "Content-Type" => "text/plain; charset=utf-8" }, ["Forbidden"]]
       when Proc
+        Reputable.logger&.info("[Reputable] block: calling custom proc for ip=#{ip}") if Reputable.verbose?
         @block_action.call(env, ip)
       else
+        Reputable.logger&.info("[Reputable] block: rendering default blocked page for ip=#{ip}") if Reputable.verbose?
         build_blocked_page_response(ip)
       end
     end
@@ -226,13 +280,20 @@ 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&.info("[Reputable] challenge: no trusted_keys configured, cannot redirect to verification") if Reputable.verbose?
+          return nil
+        end
 
         request = Rack::Request.new(env)
         return_url = request.url
         failure_url = build_verification_failure_url(request)
         session_id = resolve_session_id(env)
 
+        if Reputable.verbose?
+          Reputable.logger&.info("[Reputable] challenge: building verification URL return_url=#{return_url} failure_url=#{failure_url} session_id=#{session_id}")
+        end
+
         redirect_url = Reputable.verification_url(
           return_url: return_url,
           failure_url: failure_url,
@@ -240,10 +301,15 @@ module Reputable
           force_challenge: @verification_force_challenge
         )
 
-        return nil if redirect_url == return_url
+        if redirect_url == return_url
+          Reputable.logger&.info("[Reputable] challenge: verification_url == return_url, skipping redirect") if Reputable.verbose?
+          return nil
+        end
 
+        Reputable.logger&.info("[Reputable] challenge: REDIRECTING #{@challenge_redirect_status} → #{redirect_url}") if Reputable.verbose?
         redirect_response(redirect_url, @challenge_redirect_status)
       when Proc
+        Reputable.logger&.info("[Reputable] challenge: calling custom proc") if Reputable.verbose?
         @challenge_action.call(env)
       else
         nil
@@ -287,14 +353,27 @@ module Reputable
     end
 
     def verified_session?(env)
-      return true if env["reputable.verified"]
+      if env["reputable.verified"]
+        Reputable.logger&.info("[Reputable] verified_session?: true (env flag set this request)") if Reputable.verbose?
+        return true
+      end
 
       session = env["rack.session"]
-      return false unless session
+      unless session
+        Reputable.logger&.info("[Reputable] verified_session?: false (no rack.session)") if Reputable.verbose?
+        return false
+      end
 
-      @verified_session_keys.any? do |key|
+      found = @verified_session_keys.any? do |key|
         session[key] || session[key.to_s]
       end
+
+      if Reputable.verbose?
+        keys_state = @verified_session_keys.map { |k| "#{k}=#{session[k] || session[k.to_s]}" }.join(" ")
+        Reputable.logger&.info("[Reputable] verified_session?: #{found} (#{keys_state})")
+      end
+
+      found
     rescue StandardError
       false
     end
@@ -408,27 +487,36 @@ 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)
-          return ip if ip
+          if ip
+            Reputable.logger&.info("[Reputable] extract_ip: #{ip} (from #{header}: #{value})") if Reputable.verbose?
+            return ip
+          end
         elsif header == "HTTP_FORWARDED"
           ip = extract_from_forwarded(value)
-          return ip if ip
+          if ip
+            Reputable.logger&.info("[Reputable] extract_ip: #{ip} (from #{header}: #{value})") if Reputable.verbose?
+            return ip
+          end
         else
           # Single IP headers
           ip = value.to_s.strip
-          return ip unless ip.empty?
+          unless ip.empty?
+            Reputable.logger&.info("[Reputable] extract_ip: #{ip} (from #{header})") if Reputable.verbose?
+            return ip
+          end
         end
       end
 
-      # Ultimate fallback
+      Reputable.logger&.info("[Reputable] extract_ip: 0.0.0.0 (no headers matched)") if Reputable.verbose?
       "0.0.0.0"
     rescue StandardError
       "0.0.0.0"

data/lib/reputable/reputation.rb

@@ -133,20 +133,25 @@ module Reputable
         return nil unless valid_entity_type?(entity_type)
 
         key = "reputation:#{entity_type}:#{entity_id}"
+        Reputable.logger&.info("[Reputable] lookup: key=#{key}") if Reputable.verbose?
 
         data = Connection.safe_with(default: nil, context: "reputation_lookup") do |redis|
           redis.hgetall(key)
         end
 
-        return nil if data.nil? || data.empty?
+        if data.nil? || data.empty?
+          Reputable.logger&.info("[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&.info("[Reputable] lookup: #{key} → expired (expires_at=#{expires_at})") if Reputable.verbose?
           return nil
         end
 
-        {
+        result = {
           status: data["status"],
           reason: data["reason"],
           source: data["source"],
@@ -154,8 +159,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.22"
 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.22
 platform: ruby
 authors:
 - Reputable
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-07 00:00:00.000000000 Z
+date: 2026-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis