reputable 0.1.0

data/lib/reputable/reputation.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Reputable
+  # Reputation management functionality
+  #
+  # RESILIENCE: All reputation methods are designed to fail silently.
+  # - Write operations return false on any failure
+  # - Read operations return nil on any failure
+  # - Boolean checks (trusted_ip?, blocked_ip?) return false on failure
+  # - Never raises exceptions during normal operation
+  module Reputation
+    VALID_STATUSES = %i[
+      trusted_verified
+      trusted_behavior
+      untrusted_challenge
+      untrusted_block
+      untrusted_ignore
+    ].freeze
+
+    VALID_ENTITY_TYPES = %i[ip asn ja4 session user].freeze
+
+    class << self
+      # Apply a reputation status to an entity
+      #
+      # @param entity_type [Symbol] Type of entity (:ip, :asn, :ja4, :session, :user)
+      # @param entity_id [String] The entity identifier (IP address, ASN, etc.)
+      # @param status [Symbol] Reputation status to apply
+      # @param options [Hash] Additional options
+      # @option options [String] :reason Human-readable reason for the status
+      # @option options [Integer] :ttl TTL in seconds (0 = forever, nil = use default)
+      # @option options [Hash] :metadata Additional metadata for audit
+      # @return [Boolean] true if successfully pushed to buffer, false otherwise
+      #
+      # @example Trust an IP after payment
+      #   Reputable::Reputation.apply(
+      #     entity_type: :ip,
+      #     entity_id: "203.0.113.45",
+      #     status: :trusted_verified,
+      #     reason: "payment_completed",
+      #     ttl: 0,
+      #     metadata: { order_id: "order_123", amount: 150.00 }
+      #   )
+      #
+      # @example Block a suspicious IP
+      #   Reputable::Reputation.apply(
+      #     entity_type: :ip,
+      #     entity_id: "198.51.100.23",
+      #     status: :untrusted_block,
+      #     reason: "abuse_detected"
+      #   )
+      def apply(entity_type:, entity_id:, status:, **options)
+        return false unless Reputable.enabled?
+        return false unless valid_entity_type?(entity_type)
+        return false unless valid_status?(status)
+
+        entry = build_reputation_entry(entity_type, entity_id, status, options)
+        push_to_buffer(entry)
+      rescue StandardError => e
+        Reputable.logger&.debug("Reputable apply error: #{e.class} - #{e.message}")
+        false
+      end
+
+      # Convenience method: Trust an IP (verified status, forever TTL)
+      def trust_ip(ip, reason: "manual_trust", **metadata)
+        apply(
+          entity_type: :ip,
+          entity_id: ip,
+          status: :trusted_verified,
+          reason: reason,
+          ttl: 0,
+          metadata: metadata
+        )
+      end
+
+      # Convenience method: Block an IP
+      def block_ip(ip, reason: "manual_block", ttl: nil, **metadata)
+        apply(
+          entity_type: :ip,
+          entity_id: ip,
+          status: :untrusted_block,
+          reason: reason,
+          ttl: ttl,
+          metadata: metadata
+        )
+      end
+
+      # Convenience method: Challenge an IP (CAPTCHA, etc.)
+      def challenge_ip(ip, reason: "suspicious_activity", ttl: nil, **metadata)
+        apply(
+          entity_type: :ip,
+          entity_id: ip,
+          status: :untrusted_challenge,
+          reason: reason,
+          ttl: ttl,
+          metadata: metadata
+        )
+      end
+
+      # Convenience method: Mark IP to be ignored in analytics
+      def ignore_ip(ip, reason: "internal_traffic", ttl: nil, **metadata)
+        apply(
+          entity_type: :ip,
+          entity_id: ip,
+          status: :untrusted_ignore,
+          reason: reason,
+          ttl: ttl,
+          metadata: metadata
+        )
+      end
+
+      # Trust a user (by internal user ID)
+      def trust_user(user_id, reason: "verified_user", **metadata)
+        apply(
+          entity_type: :user,
+          entity_id: user_id.to_s,
+          status: :trusted_verified,
+          reason: reason,
+          ttl: 0,
+          metadata: metadata
+        )
+      end
+
+      # Trust a session
+      def trust_session(session_id, reason: "verified_session", ttl: nil, **metadata)
+        apply(
+          entity_type: :session,
+          entity_id: session_id,
+          status: :trusted_verified,
+          reason: reason,
+          ttl: ttl || (24 * 3600), # Default 24 hours for sessions
+          metadata: metadata
+        )
+      end
+
+      # ========================================================================
+      # LOOKUP METHODS (O(1) Redis hash lookups)
+      # ========================================================================
+
+      # Lookup the current reputation status for an entity
+      # This is an O(1) Redis HGETALL operation
+      #
+      # @param entity_type [Symbol] Type of entity (:ip, :asn, :ja4, :session, :user)
+      # @param entity_id [String] The entity identifier
+      # @return [Hash, nil] Reputation data or nil if not found/expired/error
+      #
+      # @example Check IP reputation
+      #   rep = Reputable::Reputation.lookup(:ip, "203.0.113.45")
+      #   if rep && rep[:status] == "trusted_verified"
+      #     # Allow through
+      #   end
+      def lookup(entity_type, entity_id)
+        return nil unless Reputable.enabled?
+        return nil unless valid_entity_type?(entity_type)
+
+        key = "reputation:#{entity_type}:#{entity_id}"
+
+        data = Connection.safe_with(default: nil, context: "reputation_lookup") do |redis|
+          redis.hgetall(key)
+        end
+
+        return nil if data.nil? || data.empty?
+
+        # 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
+          return nil
+        end
+
+        {
+          status: data["status"],
+          reason: data["reason"],
+          source: data["source"],
+          updated_at: data["updated_at"].to_i,
+          expires_at: expires_at,
+          metadata: safe_parse_json(data["metadata"])
+        }
+      rescue StandardError => e
+        Reputable.logger&.debug("Reputable lookup error: #{e.class} - #{e.message}")
+        nil
+      end
+
+      # Quick lookup for IP reputation status
+      # Returns just the status string (or nil)
+      #
+      # @param ip [String] IP address
+      # @return [String, nil] Status string or nil
+      #
+      # @example
+      #   status = Reputable::Reputation.lookup_ip("203.0.113.45")
+      #   # => "trusted_verified" or nil
+      def lookup_ip(ip)
+        result = lookup(:ip, ip)
+        result&.dig(:status)
+      end
+
+      # Check if an IP is trusted (any trusted_* status)
+      #
+      # @param ip [String] IP address
+      # @return [Boolean]
+      #
+      # @example
+      #   if Reputable::Reputation.trusted_ip?("203.0.113.45")
+      #     # Skip CAPTCHA
+      #   end
+      def trusted_ip?(ip)
+        status = lookup_ip(ip)
+        status&.start_with?("trusted")
+      end
+
+      # Check if an IP should be blocked
+      #
+      # @param ip [String] IP address
+      # @return [Boolean]
+      def blocked_ip?(ip)
+        lookup_ip(ip) == "untrusted_block"
+      end
+
+      # Check if an IP should be challenged
+      #
+      # @param ip [String] IP address
+      # @return [Boolean]
+      def challenged_ip?(ip)
+        lookup_ip(ip) == "untrusted_challenge"
+      end
+
+      # Lookup user reputation
+      #
+      # @param user_id [String, Integer] User ID
+      # @return [String, nil] Status string or nil
+      def lookup_user(user_id)
+        result = lookup(:user, user_id.to_s)
+        result&.dig(:status)
+      end
+
+      # Check if a user is trusted
+      #
+      # @param user_id [String, Integer] User ID
+      # @return [Boolean]
+      def trusted_user?(user_id)
+        status = lookup_user(user_id)
+        status&.start_with?("trusted")
+      end
+
+      # Lookup session reputation
+      #
+      # @param session_id [String] Session ID
+      # @return [String, nil] Status string or nil
+      def lookup_session(session_id)
+        result = lookup(:session, session_id)
+        result&.dig(:status)
+      end
+
+      # Check if a session is trusted
+      #
+      # @param session_id [String] Session ID
+      # @return [Boolean]
+      def trusted_session?(session_id)
+        status = lookup_session(session_id)
+        status&.start_with?("trusted")
+      end
+
+      private
+
+      def valid_entity_type?(entity_type)
+        VALID_ENTITY_TYPES.include?(entity_type.to_sym)
+      end
+
+      def valid_status?(status)
+        VALID_STATUSES.include?(status.to_sym)
+      end
+
+      def safe_parse_json(str)
+        return nil if str.nil? || str.empty?
+        JSON.parse(str)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def build_reputation_entry(entity_type, entity_id, status, options)
+        ttl = options[:ttl]
+        ttl = Reputable.configuration.default_ttl_for(status) if ttl.nil?
+
+        {
+          ts: (Time.now.to_f * 1000).to_i,
+          entity_type: entity_type.to_s,
+          entity_id: entity_id.to_s,
+          status: status.to_s,
+          reason: options[:reason] || "manual",
+          ttl: ttl,
+          metadata: options[:metadata]
+        }.compact
+      end
+
+      def push_to_buffer(entry)
+        key = Reputable.configuration.reputation_buffer_key
+
+        Connection.safe_with(default: false, context: "reputation_push") do |redis|
+          redis.lpush(key, entry.to_json)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/reputable/tracker.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Reputable
+  # Request tracking functionality
+  #
+  # RESILIENCE: All tracking methods are designed to fail silently.
+  # - Returns false on any failure
+  # - Never raises exceptions
+  # - Async mode runs in separate thread
+  module Tracker
+    class << self
+      # Track a request for behavioral analysis
+      #
+      # @param ip [String] Client IP address (required)
+      # @param path [String] Request path (required)
+      # @param options [Hash] Additional options
+      # @option options [String] :query Query string
+      # @option options [String] :method HTTP method (GET, POST, etc.)
+      # @option options [String] :session_id Session identifier
+      # @option options [Boolean] :session_present Whether a session cookie exists
+      # @option options [String] :user_id Internal user ID (for logged-in users)
+      # @option options [String] :fingerprint Browser fingerprint hash
+      # @option options [String] :user_agent User-Agent header
+      # @option options [String] :referer Referer header
+      # @option options [String] :country Country code (ISO 3166-1 alpha-2)
+      # @option options [Array<String>] :tags Custom classification tags
+      # @option options [Hash] :metadata Additional metadata
+      # @return [Boolean] true if successfully pushed to buffer, false otherwise
+      #
+      # @example Basic usage
+      #   Reputable::Tracker.track_request(
+      #     ip: "203.0.113.45",
+      #     path: "/products/123"
+      #   )
+      #
+      # @example Full usage
+      #   Reputable::Tracker.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", "trust:channel:organic"]
+      #   )
+      def track_request(ip:, path:, **options)
+        return false unless Reputable.enabled?
+        
+        entry = build_request_entry(ip, path, options)
+        push_to_buffer(:request, entry)
+      rescue StandardError => e
+        Reputable.logger&.debug("Reputable track_request error: #{e.class} - #{e.message}")
+        false
+      end
+
+      # Track a request asynchronously (fire-and-forget)
+      # Uses a thread to avoid blocking the request
+      # @return [Boolean] Always returns true (async)
+      def track_request_async(ip:, path:, **options)
+        return true unless Reputable.enabled?
+        
+        Thread.new do
+          track_request(ip: ip, path: path, **options)
+        rescue StandardError
+          # Silently ignore all errors in async thread
+        end
+        true
+      end
+
+      private
+
+      def build_request_entry(ip, path, options)
+        {
+          ts: (Time.now.to_f * 1000).to_i,
+          ip: ip,
+          path: path,
+          query: options[:query],
+          method: options[:method] || "GET",
+          session_id: options[:session_id],
+          session_present: options[:session_present],
+          user_id: options[:user_id],
+          fingerprint: options[:fingerprint],
+          user_agent: options[:user_agent],
+          referer: options[:referer],
+          country: options[:country],
+          tags: options[:tags] || [],
+          metadata: options[:metadata]
+        }.compact
+      end
+
+      def push_to_buffer(type, entry)
+        key = case type
+              when :request then Reputable.configuration.request_buffer_key
+              when :reputation then Reputable.configuration.reputation_buffer_key
+              else return false
+              end
+
+        Connection.safe_with(default: false, context: "track_request") do |redis|
+          redis.lpush(key, entry.to_json)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/reputable/version.rb

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

data/lib/reputable.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "reputable/version"
+require_relative "reputable/configuration"
+require_relative "reputable/connection"
+require_relative "reputable/tracker"
+require_relative "reputable/reputation"
+require_relative "reputable/middleware"
+
+# Optional Rails integration
+begin
+  require_relative "reputable/rails"
+rescue LoadError
+  # Rails not available, skip
+end
+
+# Reputable - Bot detection and reputation scoring client
+#
+# RESILIENCE: This gem is designed to fail silently and never break your app.
+# - All methods return safe defaults (false/nil) on any error
+# - Can be disabled via REPUTABLE_ENABLED=false
+# - Circuit breaker prevents connection storms
+# - All Redis timeouts are configurable via ENV
+#
+# @example Basic setup
+#   Reputable.configure do |config|
+#     config.redis_url = "rediss://user:pass@dragonfly.example.com:6379"
+#     config.tenant_id = "my-tenant"
+#   end
+#
+# @example Track a request
+#   Reputable.track_request(
+#     ip: "203.0.113.45",
+#     path: "/products/123",
+#     session_present: true
+#   )
+#
+# @example Apply reputation after payment
+#   Reputable.trust_ip("203.0.113.45", reason: "payment_completed")
+#
+# @example Disable completely via ENV
+#   # In your environment: REPUTABLE_ENABLED=false
+#
+module Reputable
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class ConnectionError < Error; end
+
+  class << self
+    attr_accessor :logger
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      Connection.reset! # Reset pool on reconfiguration
+    end
+
+    def reset!
+      @configuration = nil
+      Connection.reset!
+    end
+
+    # Check if Reputable is enabled
+    # Can be disabled via REPUTABLE_ENABLED=false environment variable
+    # @return [Boolean]
+    def enabled?
+      configuration.enabled?
+    end
+
+    # Check if Reputable is disabled
+    # @return [Boolean]
+    def disabled?
+      !enabled?
+    end
+
+    # Delegate tracking methods to Tracker
+    def track_request(ip:, path:, **options)
+      Tracker.track_request(ip: ip, path: path, **options)
+    end
+
+    def track_request_async(ip:, path:, **options)
+      Tracker.track_request_async(ip: ip, path: path, **options)
+    end
+
+    # Delegate reputation methods to Reputation module
+    def apply_reputation(entity_type:, entity_id:, status:, **options)
+      Reputation.apply(entity_type: entity_type, entity_id: entity_id, status: status, **options)
+    end
+
+    def trust_ip(ip, reason: "manual_trust", **metadata)
+      Reputation.trust_ip(ip, reason: reason, **metadata)
+    end
+
+    def block_ip(ip, reason: "manual_block", **metadata)
+      Reputation.block_ip(ip, reason: reason, **metadata)
+    end
+
+    def challenge_ip(ip, reason: "suspicious_activity", **metadata)
+      Reputation.challenge_ip(ip, reason: reason, **metadata)
+    end
+
+    def ignore_ip(ip, reason: "internal_traffic", **metadata)
+      Reputation.ignore_ip(ip, reason: reason, **metadata)
+    end
+
+    def trust_user(user_id, reason: "verified_user", **metadata)
+      Reputation.trust_user(user_id, reason: reason, **metadata)
+    end
+
+    def trust_session(session_id, reason: "verified_session", **metadata)
+      Reputation.trust_session(session_id, reason: reason, **metadata)
+    end
+
+    # Delegate lookup methods to Reputation module (O(1) Redis lookups)
+    def lookup_reputation(entity_type, entity_id)
+      Reputation.lookup(entity_type, entity_id)
+    end
+
+    def lookup_ip(ip)
+      Reputation.lookup_ip(ip)
+    end
+
+    def trusted_ip?(ip)
+      Reputation.trusted_ip?(ip)
+    end
+
+    def blocked_ip?(ip)
+      Reputation.blocked_ip?(ip)
+    end
+
+    def challenged_ip?(ip)
+      Reputation.challenged_ip?(ip)
+    end
+
+    def lookup_user(user_id)
+      Reputation.lookup_user(user_id)
+    end
+
+    def trusted_user?(user_id)
+      Reputation.trusted_user?(user_id)
+    end
+
+    def lookup_session(session_id)
+      Reputation.lookup_session(session_id)
+    end
+
+    def trusted_session?(session_id)
+      Reputation.trusted_session?(session_id)
+    end
+  end
+end