otto 2.0.0.pre2 → 2.0.0.pre3

data/lib/otto/privacy/geo_resolver.rb

@@ -0,0 +1,115 @@
+# lib/otto/privacy/geo_resolver.rb
+
+require 'ipaddr'
+
+class Otto
+  module Privacy
+    # Lightweight geo-location resolution for IP addresses
+    #
+    # Provides country-level geo-location without requiring external
+    # databases or API calls. Uses CloudFlare headers when available,
+    # with fallback to basic IP range detection.
+    #
+    # @example Resolve country from CloudFlare header
+    #   env = { 'HTTP_CF_IPCOUNTRY' => 'US' }
+    #   GeoResolver.resolve('1.2.3.4', env)
+    #   # => 'US'
+    #
+    # @example Resolve without CloudFlare
+    #   GeoResolver.resolve('9.9.9.9', {})
+    #   # => 'CH' (Quad9 in Switzerland)
+    #
+    class GeoResolver
+      # Unknown country code (ISO 3166-1 alpha-2)
+      UNKNOWN = 'XX'
+
+      # Resolve country code for an IP address
+      #
+      # Resolution priority:
+      # 1. CloudFlare CF-IPCountry header (most reliable)
+      # 2. Basic IP range detection for major countries/providers
+      # 3. Return 'XX' for unknown
+      #
+      # @param ip [String] IP address to resolve
+      # @param env [Hash] Rack environment (may contain CF headers)
+      # @return [String] ISO 3166-1 alpha-2 country code or 'XX'
+      def self.resolve(ip, env = {})
+        return UNKNOWN if ip.nil? || ip.empty?
+
+        # Priority 1: CloudFlare header (free, accurate, no database)
+        cf_country = env['HTTP_CF_IPCOUNTRY']
+        return cf_country if cf_country && valid_country_code?(cf_country)
+
+        # Priority 2: Basic range detection
+        detect_by_range(ip)
+      rescue IPAddr::InvalidAddressError
+        UNKNOWN
+      end
+
+      # Detect country by IP range (basic implementation)
+      #
+      # Detects major cloud providers and well-known IP ranges.
+      # This is intentionally limited - for comprehensive geo-location,
+      # use CloudFlare or a dedicated GeoIP database.
+      #
+      # @param ip [String] IP address
+      # @return [String] Country code or 'XX'
+      # @api private
+      def self.detect_by_range(ip)
+        addr = IPAddr.new(ip)
+
+        # Private/local addresses
+        return UNKNOWN if IPPrivacy.private_or_localhost?(ip)
+
+        # Check against known ranges
+        KNOWN_RANGES.each do |range, country|
+          return country if range.include?(addr)
+        end
+
+        UNKNOWN
+      end
+      private_class_method :detect_by_range
+
+      # Validate country code format
+      #
+      # @param code [String] Country code to validate
+      # @return [Boolean] true if valid ISO 3166-1 alpha-2 code
+      # @api private
+      def self.valid_country_code?(code)
+        code.is_a?(String) && code.length == 2 && code.match?(/^[A-Z]{2}$/)
+      end
+      private_class_method :valid_country_code?
+
+      # Known IP ranges for major providers (limited set for basic detection)
+      # For comprehensive geo-location, use CloudFlare or GeoIP database
+      KNOWN_RANGES = {
+        # Google Public DNS
+        IPAddr.new('8.8.8.0/24') => 'US',
+        IPAddr.new('8.8.4.0/24') => 'US',
+
+        # Cloudflare DNS
+        IPAddr.new('1.1.1.0/24') => 'US',
+        IPAddr.new('1.0.0.0/24') => 'US',
+
+        # AWS US-East
+        IPAddr.new('52.0.0.0/11') => 'US',
+        IPAddr.new('54.0.0.0/8') => 'US',
+
+        # AWS EU-West
+        IPAddr.new('34.240.0.0/13') => 'IE',
+        IPAddr.new('52.16.0.0/14') => 'IE',
+
+        # AWS AP-Southeast
+        IPAddr.new('13.210.0.0/15') => 'AU',
+        IPAddr.new('52.62.0.0/15') => 'AU',
+
+        # Quad9 DNS (Switzerland)
+        IPAddr.new('9.9.9.0/24') => 'CH',
+
+        # OpenDNS
+        IPAddr.new('208.67.222.0/24') => 'US',
+        IPAddr.new('208.67.220.0/24') => 'US',
+      }.freeze
+    end
+  end
+end

data/lib/otto/privacy/ip_privacy.rb

@@ -0,0 +1,175 @@
+# lib/otto/privacy/ip_privacy.rb
+
+require 'ipaddr'
+require 'digest'
+require 'openssl'
+require 'socket'
+
+class Otto
+  module Privacy
+    # IP address anonymization utilities
+    #
+    # Provides methods for masking and hashing IP addresses to enhance
+    # privacy while maintaining the ability to track sessions and analyze
+    # traffic patterns.
+    #
+    # @example Mask an IPv4 address (1 octet)
+    #   IPPrivacy.mask_ip('192.168.1.100', 1)
+    #   # => '192.168.1.0'
+    #
+    # @example Mask an IPv4 address (2 octets)
+    #   IPPrivacy.mask_ip('192.168.1.100', 2)
+    #   # => '192.168.0.0'
+    #
+    # @example Hash an IP for session correlation
+    #   key = 'daily-rotation-key'
+    #   IPPrivacy.hash_ip('192.168.1.100', key)
+    #   # => 'a3f8b2...' (consistent for same IP+key, changes when key rotates)
+    #
+    # @note All methods return UTF-8 encoded strings for Rack compatibility.
+    #   See file:docs/ipaddr-encoding-quirk.md for details on IPAddr#to_s behavior.
+    #
+    class IPPrivacy
+      # Mask an IP address by zeroing out the specified number of octets/bits
+      #
+      # For IPv4:
+      # - octet_precision=1: Masks last octet (e.g., 192.168.1.100 → 192.168.1.0)
+      # - octet_precision=2: Masks last 2 octets (e.g., 192.168.1.100 → 192.168.0.0)
+      #
+      # For IPv6:
+      # - octet_precision=1: Masks last 80 bits
+      # - octet_precision=2: Masks last 96 bits
+      #
+      # @param ip [String] IP address to mask
+      # @param octet_precision [Integer] Number of trailing octets to mask (1 or 2, default: 1)
+      # @return [String] Masked IP address (UTF-8 encoded)
+      # @raise [ArgumentError] if IP is invalid or octet_precision is not 1 or 2
+      def self.mask_ip(ip, octet_precision = 1)
+        return nil if ip.nil? || ip.empty?
+
+        raise ArgumentError, "octet_precision must be 1 or 2, got: #{octet_precision}" unless [1,
+                                                                                               2].include?(octet_precision)
+
+        begin
+          addr = IPAddr.new(ip)
+
+          if addr.ipv4?
+            mask_ipv4(addr, octet_precision)
+          else
+            mask_ipv6(addr, octet_precision)
+          end
+        rescue IPAddr::InvalidAddressError => e
+          raise ArgumentError, "Invalid IP address: #{ip} - #{e.message}"
+        end
+      end
+
+      # Hash an IP address for session correlation without storing the original
+      #
+      # Uses HMAC-SHA256 with a daily-rotating key to create a consistent
+      # identifier for the same IP within a key rotation period, but different
+      # across rotations.
+      #
+      # @param ip [String] IP address to hash
+      # @param key [String] Secret key for HMAC (should rotate daily)
+      # @return [String] Hexadecimal hash string (64 characters)
+      # @raise [ArgumentError] if IP or key is invalid
+      def self.hash_ip(ip, key)
+        return nil if ip.nil? || ip.empty?
+
+        raise ArgumentError, 'Key cannot be nil or empty' if key.nil? || key.empty?
+
+        # Normalize IP address format before hashing
+        normalized_ip = begin
+          IPAddr.new(ip).to_s
+        rescue IPAddr::InvalidAddressError => e
+          raise ArgumentError, "Invalid IP address: #{ip} - #{e.message}"
+        end
+
+        # Use HMAC-SHA256 for secure hashing with key
+        OpenSSL::HMAC.hexdigest('SHA256', key, normalized_ip)
+      end
+
+      # Check if an IP address is valid
+      #
+      # @param ip [String] IP address to validate
+      # @return [Boolean] true if valid IPv4 or IPv6 address
+      def self.valid_ip?(ip)
+        return false if ip.nil? || ip.empty?
+
+        IPAddr.new(ip)
+        true
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+
+      # Check if an IP address is localhost or private (RFC 1918)
+      #
+      # Private/localhost IPs are not masked for development convenience.
+      #
+      # @param ip [String] IP address to check
+      # @return [Boolean] true if IP is localhost or private
+      def self.private_or_localhost?(ip)
+        return false if ip.nil? || ip.empty?
+
+        addr = IPAddr.new(ip)
+        addr.private? || addr.loopback?
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+
+      # Mask IPv4 address
+      #
+      # @param addr [IPAddr] IPAddr object (must be IPv4)
+      # @param octet_precision [Integer] Number of trailing octets to mask (1 or 2)
+      # @return [String] Masked IPv4 address (UTF-8 encoded)
+      # @api private
+      # @see file:docs/ipaddr-encoding-quirk.md IPAddr encoding behavior
+      def self.mask_ipv4(addr, octet_precision)
+        # Convert to integer for bitwise operations
+        ip_int = addr.to_i
+
+        # Create mask: 0xFFFFFFFF with trailing zeros
+        # octet_precision=1: 0xFFFFFF00 (mask last 8 bits)
+        # octet_precision=2: 0xFFFF0000 (mask last 16 bits)
+        bits_to_mask = octet_precision * 8
+        mask = (0xFFFFFFFF >> bits_to_mask) << bits_to_mask
+
+        # Apply mask and convert back to IP
+        masked_int = ip_int & mask
+
+        # Force UTF-8 encoding: IPAddr#to_s returns US-ASCII for IPv4 but UTF-8
+        # for IPv6. We normalize to UTF-8 for Rack compatibility and to prevent
+        # Encoding::CompatibilityError. Safe because IP strings contain only
+        # ASCII characters.
+        # See also: https://github.com/ruby/ruby/blob/master/lib/ipaddr.rb
+        IPAddr.new(masked_int, Socket::AF_INET).to_s.force_encoding('UTF-8')
+      end
+      private_class_method :mask_ipv4
+
+      # Mask IPv6 address
+      #
+      # @param addr [IPAddr] IPAddr object (must be IPv6)
+      # @param octet_precision [Integer] Number of trailing octets to mask (1 or 2)
+      # @return [String] Masked IPv6 address (UTF-8 encoded)
+      # @api private
+      def self.mask_ipv6(addr, octet_precision)
+        ip_int = addr.to_i
+
+        # octet_precision=1: Mask last 80 bits (leave first 48 bits for network)
+        # octet_precision=2: Mask last 96 bits (leave first 32 bits)
+        bits_to_mask = octet_precision == 1 ? 80 : 96
+
+        # Create mask by setting all 128 bits, then clearing the trailing bits we want to mask
+        # Example: For bits_to_mask=80, this creates a mask with first 48 bits set to 1, last 80 bits set to 0
+        # (1 << 128) - 1 creates 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF (all 128 bits set)
+        mask = ((1 << 128) - 1) >> bits_to_mask << bits_to_mask
+
+        masked_int = ip_int & mask
+
+        IPAddr.new(masked_int, Socket::AF_INET6).to_s.force_encoding('UTF-8')
+      end
+
+      private_class_method :mask_ipv6
+    end
+  end
+end

data/lib/otto/privacy/redacted_fingerprint.rb

@@ -0,0 +1,136 @@
+# lib/otto/privacy/redacted_fingerprint.rb
+
+require 'securerandom'
+require 'time'
+require 'uri'
+
+class Otto
+  module Privacy
+    # Immutable privacy-safe request fingerprint (aka CrappyFingerprint)
+    #
+    # Contains anonymized information about a request that can be used for
+    # logging, analytics, and session tracking without storing personally
+    # identifiable information.
+    #
+    # @example Create from Rack environment
+    #   config = Otto::Privacy::Config.new
+    #   fingerprint = RedactedFingerprint.new(env, config)
+    #   fingerprint.masked_ip   # => '192.168.1.0'
+    #   fingerprint.country     # => 'US'
+    #
+    class RedactedFingerprint
+      attr_reader :session_id, :timestamp, :masked_ip, :hashed_ip,
+                  :country, :anonymized_ua, :request_path,
+                  :request_method, :referer
+
+      # Create a new RedactedFingerprint from a Rack environment
+      #
+      # @param env [Hash] Rack environment hash
+      # @param config [Otto::Privacy::Config] Privacy configuration
+      def initialize(env, config)
+        remote_ip = env['REMOTE_ADDR']
+
+        @session_id = SecureRandom.uuid
+        @timestamp = Time.now.utc
+        @masked_ip = IPPrivacy.mask_ip(remote_ip, config.octet_precision)
+        @hashed_ip = IPPrivacy.hash_ip(remote_ip, config.rotation_key)
+        @country = config.geo_enabled ? GeoResolver.resolve(remote_ip, env) : nil
+        @anonymized_ua = anonymize_user_agent(env['HTTP_USER_AGENT'])
+        @request_path = env['PATH_INFO']
+        @request_method = env['REQUEST_METHOD']
+        @referer = anonymize_referer(env['HTTP_REFERER'])
+
+        freeze
+      end
+
+      # Convert to hash for logging or serialization
+      #
+      # @return [Hash] Hash representation of fingerprint
+      def to_h
+        {
+              session_id: @session_id,
+               timestamp: @timestamp.iso8601,
+               masked_ip: @masked_ip,
+               hashed_ip: @hashed_ip,
+                 country: @country,
+           anonymized_ua: @anonymized_ua,
+          request_method: @request_method,
+            request_path: @request_path,
+                 referer: @referer,
+        }
+      end
+
+      # Convert to JSON string
+      #
+      # @return [String] JSON representation
+      def to_json(*_args)
+        require 'json'
+        to_h.to_json
+      end
+
+      # String representation
+      #
+      # @return [String] Human-readable representation
+      def to_s
+        "#<RedactedFingerprint #{@hashed_ip[0..15]}... #{@country} #{@timestamp}>"
+      end
+
+      # Inspect representation
+      #
+      # @return [String] Detailed representation for debugging
+      def inspect
+        '#<Otto::Privacy::RedactedFingerprint ' \
+          "masked_ip=#{@masked_ip.inspect} " \
+          "hashed_ip=#{@hashed_ip[0..15]}... " \
+          "country=#{@country.inspect} " \
+          "timestamp=#{@timestamp.inspect}>"
+      end
+
+      private
+
+      # Anonymize user agent string by removing version numbers
+      #
+      # Removes specific version numbers (X.X.X pattern) to reduce
+      # fingerprinting granularity while maintaining browser/OS info.
+      #
+      # @param ua [String, nil] User agent string
+      # @return [String, nil] Anonymized user agent or nil
+      def anonymize_user_agent(ua)
+        return nil if ua.nil? || ua.empty?
+
+        # Remove version patterns (X.X.X.X, X.X.X, X.X)
+        anonymized = ua
+                     .gsub(/\d+\.\d+\.\d+\.\d+/, 'X.X.X.X')
+                     .gsub(/\d+\.\d+\.\d+/, 'X.X.X')
+                     .gsub(/\d+\.\d+/, 'X.X')
+
+        # Truncate if too long (prevent DoS via huge UA strings)
+        anonymized.length > 500 ? anonymized[0..499] : anonymized
+      end
+
+      # Anonymize referer URL
+      #
+      # Strips query parameters and keeps only the path to reduce
+      # tracking potential while maintaining useful navigation data.
+      #
+      # @param referer [String, nil] Referer header value
+      # @return [String, nil] Anonymized referer or nil
+      def anonymize_referer(referer)
+        return nil if referer.nil? || referer.empty?
+
+        begin
+          uri = URI.parse(referer)
+          # Keep scheme, host, and path only (remove query and fragment)
+          if uri.scheme && uri.host
+            "#{uri.scheme}://#{uri.host}#{uri.path}"
+          else
+            uri.path
+          end
+        rescue URI::InvalidURIError
+          # If referer is malformed, return nil
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/otto/privacy.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'privacy/config'
+require_relative 'privacy/ip_privacy'
+require_relative 'privacy/geo_resolver'
+require_relative 'privacy/redacted_fingerprint'
+
+# Otto::Privacy module provides IP address anonymization and privacy features
+#
+# By default, Otto anonymizes IP addresses to enhance user privacy and
+# comply with data protection regulations like GDPR. Original IP addresses
+# are never stored unless privacy is explicitly disabled.
+#
+# Features:
+# - Configurable IP masking (1 or 2 octets for IPv4, 80 or 96 bits for IPv6)
+# - Daily-rotating IP hashing for session correlation without tracking
+# - Geo-location resolution (country-level only, via CloudFlare headers)
+# - User agent anonymization (removes version numbers)
+#
+# Privacy is ENABLED BY DEFAULT. To disable:
+#   otto.disable_ip_privacy!
+#
+# To configure privacy settings:
+#   otto.configure_ip_privacy(octet_precision: 2, geo: true)
+#
+class Otto
+  module Privacy
+  end
+end

data/lib/otto/route_handlers/base.rb

@@ -1,6 +1,5 @@
-# frozen_string_literal: true
-
 # lib/otto/route_handlers/base.rb
+
 require 'json'
 
 class Otto

data/lib/otto/route_handlers/factory.rb

@@ -3,6 +3,7 @@
 # lib/otto/route_handlers/factory.rb
 
 require_relative 'base'
+require_relative '../security/authentication/route_auth_wrapper'
 
 class Otto
   module RouteHandlers
@@ -14,24 +15,25 @@ class Otto
       # @return [BaseHandler] Appropriate handler for the route
       def self.create_handler(route_definition, otto_instance = nil)
         # Create base handler based on route kind
-        handler = case route_definition.kind
-                  when :logic
-                    LogicClassHandler.new(route_definition, otto_instance)
-                  when :instance
-                    InstanceMethodHandler.new(route_definition, otto_instance)
-                  when :class
-                    ClassMethodHandler.new(route_definition, otto_instance)
-                  else
-                    raise ArgumentError, "Unknown handler kind: #{route_definition.kind}"
-                  end
+        handler_class = case route_definition.kind
+                        when :logic then LogicClassHandler
+                        when :instance then InstanceMethodHandler
+                        when :class then ClassMethodHandler
+                        else
+                          raise ArgumentError, "Unknown handler kind: #{route_definition.kind}"
+                        end
 
-        # Wrap with auth enforcement if route has auth requirement
-        if route_definition.auth_requirement && otto_instance&.auth_config
-          require_relative '../security/authentication/route_auth_wrapper'
+        handler = handler_class.new(route_definition, otto_instance)
+
+        # Always wrap with RouteAuthWrapper to ensure env['otto.strategy_result'] is set
+        # - Routes WITH auth requirement: Enforces authentication
+        # - Routes WITHOUT auth requirement: Sets anonymous StrategyResult
+        if otto_instance&.auth_config
           handler = Otto::Security::Authentication::RouteAuthWrapper.new(
             handler,
             route_definition,
-            otto_instance.auth_config
+            otto_instance.auth_config,
+            otto_instance.security_config
           )
         end
 

data/lib/otto/route_handlers/logic_class.rb

@@ -17,8 +17,8 @@ class Otto
         res = Rack::Response.new
 
         begin
-          # Get strategy result (guaranteed to exist from auth middleware)
-          strategy_result = env['otto.strategy_result'] || Otto::Security::Authentication::StrategyResult.anonymous
+          # Get strategy result (guaranteed to exist from RouteAuthWrapper)
+          strategy_result = env['otto.strategy_result']
 
           # Initialize Logic class with new signature: context, params, locale
           logic_params = req.params.merge(extra_params)

data/lib/otto/security/authentication/{failure_result.rb → auth_failure.rb}

@@ -6,8 +6,8 @@ class Otto
   module Security
     module Authentication
       # Failure result for authentication failures
-      FailureResult = Data.define(:failure_reason, :auth_method) do
-        # FailureResult represents authentication failure
+      AuthFailure = Data.define(:failure_reason, :auth_method) do
+        # AuthFailure represents authentication failure
         # Returned by strategies when authentication fails
         # Contains failure reason for error messages
 
@@ -36,7 +36,7 @@ class Otto
         #
         # @return [String] Debug representation
         def inspect
-          "#<FailureResult reason=#{failure_reason.inspect} method=#{auth_method}>"
+          "#<AuthFailure reason=#{failure_reason.inspect} method=#{auth_method}>"
         end
       end
     end

data/lib/otto/security/authentication/auth_strategy.rb

@@ -13,7 +13,7 @@ class Otto
         # Check if the request meets the authentication requirements
         # @param env [Hash] Rack environment
         # @param requirement [String] Authentication requirement string
-        # @return [Otto::Security::Authentication::StrategyResult, nil] StrategyResult for success, nil for failure
+        # @return [Otto::Security::Authentication::StrategyResult, Otto::Security::Authentication::AuthFailure] StrategyResult for success, AuthFailure for failure
         def authenticate(env, requirement)
           raise NotImplementedError, 'Subclasses must implement #authenticate'
         end
@@ -30,10 +30,10 @@ class Otto
           )
         end
 
-        # Helper for authentication failure - return FailureResult
+        # Helper for authentication failure - return AuthFailure
         def failure(reason = nil)
           Otto.logger.debug "[#{self.class}] Authentication failed: #{reason}" if reason
-          Otto::Security::Authentication::FailureResult.new(
+          Otto::Security::Authentication::AuthFailure.new(
             failure_reason: reason || 'Authentication failed',
             auth_method: self.class.name.split('::').last
           )