otto 2.5.0 → 2.7.0

data/lib/otto/privacy/geo_resolver.rb

@@ -2,16 +2,33 @@
 #
 # frozen_string_literal: true
 
-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. Supports headers from major CDN/infrastructure
-    # providers (Cloudflare, AWS CloudFront, Fastly, Akamai, Azure) with
-    # fallback to basic IP range detection.
+    # Provides country-level geo-location. Headers from major CDN/infrastructure
+    # providers are checked first; an optional local MaxMind-format (.mmdb)
+    # database gives an offline fallback that operates on Otto's already-MASKED
+    # IP (no external API calls, and the unmasked address never reaches the
+    # resolver).
+    #
+    # Resolution order (first hit wins), when a privacy Config is supplied:
+    # 1. App-configured trusted header (Config#geo_header), e.g. 'X-Client-Country'
+    # 2. Built-in CDN/infrastructure provider headers (see below)
+    # 3. Custom resolver hook ({.custom_resolver})
+    # 4. Local MMDB lookup, masked before lookup (Config#geo_db_reader)
+    # 5. '**' (unknown)
+    #
+    # Steps 1 and 2 are SKIPPED when the request's geo headers are not trusted.
+    # Every geo header is client-spoofable unless you are actually behind the CDN
+    # that sets it, so the middleware trusts them only for a request that arrived
+    # via a configured trusted proxy; otherwise resolution falls straight to the
+    # custom resolver / database.
+    #
+    # Resolution is HONEST: when no header, custom resolver, or database resolves
+    # a country, the answer is '**' (unknown). Otto does not guess from a
+    # hardcoded IP-range table — configure a database or an edge header for real
+    # geo-location.
     #
     # Supported CDN/Infrastructure Headers:
     # - Cloudflare: CF-IPCountry
@@ -19,6 +36,7 @@ class Otto
     # - Fastly: Fastly-Client-IP-Country
     # - Akamai: X-Akamai-Edgescape (country_code=XX format)
     # - Azure Front Door: X-Azure-ClientIP-Country
+    # - Vercel: X-Vercel-IP-Country
     # - Semi-standard: X-Geo-Country, X-Country-Code, Country-Code
     #
     # @example Resolve country from Cloudflare header
@@ -31,9 +49,9 @@ class Otto
     #   GeoResolver.resolve('1.2.3.4', env)
     #   # => 'GB'
     #
-    # @example Resolve without CDN headers
+    # @example Resolve without any header, resolver, or database
     #   GeoResolver.resolve('8.8.8.8', {})
-    #   # => 'US' (Google DNS via range detection)
+    #   # => '**' (unknown — Otto does not guess)
     #
     # @example Using a custom resolver (MaxMind)
     #   GeoResolver.custom_resolver = ->(ip, env) {
@@ -45,7 +63,7 @@ class Otto
     #
     # @example Extending via subclass
     #   class MyGeoResolver < Otto::Privacy::GeoResolver
-    #     def self.detect_by_range(ip)
+    #     def self.check_geo_database(ip, config)
     #       # Custom logic here
     #       super  # Fall back to parent
     #     end
@@ -54,14 +72,16 @@ class Otto
     #
     # Resolution flow
     #
-    #    Request → Has familiar HTTP Header?
-    #              ├─ Yes → Return country (Cloudflare, AWS, etc.)
-    #              └─ No → Custom Resolver?
-    #                      ├─ Configured → Call & validate
-    #                      │               ├─ Valid → Return country
-    #                      │               └─ Invalid/Error → Continue
-    #                      └─ Not configured → Built-in range detection
-    #                                          └─ Unknown ('**')
+    #    Request → Headers trusted?
+    #              ├─ Yes → Config#geo_header set & valid? → Return country
+    #              │        └─ Provider header present & valid? → Return country
+    #              └─ (headers skipped when not trusted)
+    #                 → Custom Resolver configured?
+    #                   ├─ Valid → Return country
+    #                   └─ Invalid/Error → Continue
+    #                 → Local MMDB reader configured?
+    #                   ├─ Hit → Return country
+    #                   └─ Miss → Unknown ('**')
     #
     class GeoResolver
       # Unknown country code (not ISO 3166-1 alpha-2, intentionally distinct)
@@ -114,40 +134,150 @@ class Otto
         end
       end
 
-      # Resolve country code for an IP address
+      # Resolve country code for an IP address.
+      #
+      # Resolution order (first hit wins). Header steps (1–2) are skipped when
+      # +headers_trusted+ is false, since geo headers are client-spoofable
+      # unless the request actually arrived through the trusted CDN/proxy:
+      # 1. App-configured trusted header (+config.geo_header+)
+      # 2. Built-in CDN/infrastructure provider headers
+      # 3. Custom resolver hook ({.custom_resolver})
+      # 4. Local MMDB lookup (+config.geo_db_reader+), masked before lookup
+      # 5. '**' for unknown (no guessing)
       #
-      # Resolution priority:
-      # 1. CDN/infrastructure provider headers (Cloudflare, AWS, Fastly, etc.)
-      # 2. Basic IP range detection for major countries/providers
-      # 3. Return '**' for unknown
+      # Country-level MMDB networks are almost always >= /24, so a /24-masked
+      # +x.y.z.0+ resolves to the same country as the real IP. The database
+      # lookup masks internally, and the Otto middleware additionally hands this
+      # method a masked IP and a masked env, so neither the database nor a custom
+      # resolver ever sees the unmasked address.
       #
-      # @param ip [String] IP address to resolve
-      # @param env [Hash] Rack environment (may contain geo headers)
+      # @param ip [String] IP address to resolve. When called from the Otto
+      #   middleware this is already the masked IP; the database lookup masks
+      #   again internally, so a direct caller passing a real IP still never
+      #   exposes the unmasked address to the database.
+      # @param env [Hash] Rack environment (may contain geo headers). In the
+      #   framework path this is a masked view (REMOTE_ADDR/forwarded headers
+      #   masked), so a custom resolver never sees the raw IP through env either.
+      # @param config [Otto::Privacy::Config, nil] privacy config supplying the
+      #   configured header and MMDB reader. When nil, only the built-in provider
+      #   headers and the custom resolver are consulted.
+      # @param headers_trusted [Boolean] whether request geo headers may be
+      #   trusted for this request (default true; the middleware computes this
+      #   from the trusted-proxy decision).
       # @return [String] ISO 3166-1 alpha-2 country code or '**'
-      def self.resolve(ip, env = {})
+      def self.resolve(ip, env = {}, config = nil, headers_trusted: true)
         return UNKNOWN if ip.nil? || ip.empty?
 
-        # Check CDN/infrastructure headers in priority order
-        # Priority based on reliability and deployment frequency
-        country = check_geo_headers(env)
-        return country if country
+        # Resolution is honest: when no header, custom resolver, or database
+        # resolves a country, the answer is '**' (unknown) — never a guess.
+        resolve_from_sources(ip, env, config, headers_trusted) || UNKNOWN
+      end
 
-        # Try custom resolver if configured
-        if @custom_resolver
-          begin
-            country = @custom_resolver.call(ip, env)
-            return country if country && valid_country_code?(country)
-          rescue StandardError => e
-            # Log error but don't crash - fall through to built-in detection
-            warn "GeoResolver custom resolver error: #{e.message}" if $DEBUG
-          end
+      # Walk the ordered resolution sources and return the first country found.
+      #
+      # @return [String, nil] country code, or nil if no source resolved
+      # @api private
+      def self.resolve_from_sources(ip, env, config, headers_trusted)
+        if headers_trusted
+          # 1. Configured header wins over 2. built-in provider headers.
+          country = check_configured_header(env, config) || check_geo_headers(env)
+          return country if country
         end
 
-        # Fallback: Basic range detection
-        detect_by_range(ip)
-      rescue IPAddr::InvalidAddressError
-        UNKNOWN
+        # 3. Custom resolver hook, then 4. local MMDB lookup.
+        check_custom_resolver(ip, env) || check_geo_database(ip, config)
+      end
+      private_class_method :resolve_from_sources
+
+      # Check the app-configured trusted geo header, if any.
+      #
+      # @param env [Hash] Rack environment
+      # @param config [Otto::Privacy::Config, nil]
+      # @return [String, nil] valid country code from the configured header, or nil
+      # @api private
+      def self.check_configured_header(env, config)
+        header = config&.geo_header
+        return nil unless header
+
+        country = env[header]
+        valid_country_code?(country) ? country : nil
+      end
+      private_class_method :check_configured_header
+
+      # Invoke the configured custom resolver, guarding against errors.
+      #
+      # @param ip [String] IP address handed to the resolver (masked in the
+      #   framework path — see {.resolve})
+      # @param env [Hash] Rack environment (masked view in the framework path)
+      # @return [String, nil] a valid country code, or nil
+      # @api private
+      def self.check_custom_resolver(ip, env)
+        resolver = @custom_resolver
+        return nil unless resolver
+
+        country = resolver.call(ip, env)
+        country if country && valid_country_code?(country)
+      rescue StandardError => e
+        # A custom resolver must never crash a request; fall through.
+        warn "GeoResolver custom resolver error: #{e.message}" if $DEBUG
+        nil
       end
+      private_class_method :check_custom_resolver
+
+      # Look up the country for an IP in the configured MMDB database.
+      #
+      # No-op (returns nil) when no config or reader is available. The IP is
+      # masked (with the config's octet precision) before the lookup so the
+      # unmasked address never reaches the database; masking is idempotent, so
+      # an already-masked IP is unaffected. Country-level networks are >= /24,
+      # so a /24-masked address resolves to the same country as the real one.
+      #
+      # The reader is any object responding to +#get(ip)+; result shapes from
+      # both GeoLite2-Country-compatible ('country' => {'iso_code' => ...}) and
+      # flat ('country_code' => ...) mmdb builds are handled.
+      #
+      # @param ip [String] IP address (masked internally before lookup)
+      # @param config [Otto::Privacy::Config, nil]
+      # @return [String, nil] valid country code, or nil on miss/error
+      # @api private
+      def self.check_geo_database(ip, config)
+        reader = config&.geo_db_reader
+        return nil unless reader
+
+        lookup_ip = IPPrivacy.mask_ip(ip, config.octet_precision) || ip
+        country = extract_db_country(reader.get(lookup_ip))
+        valid_country_code?(country) ? country : nil
+      rescue StandardError => e
+        # A DB read must never crash a request; fall through.
+        warn "GeoResolver database lookup error: #{e.message}" if $DEBUG
+        nil
+      end
+      private_class_method :check_geo_database
+
+      # Extract an ISO country code from an MMDB lookup result.
+      #
+      # Handles the shapes country databases actually use: GeoLite2-Country
+      # style ('country' => {'iso_code' => 'US'}), the flat 'country_code' =>
+      # 'US', and a bare 'country' => 'US'. The nested case is checked with an
+      # explicit Hash guard rather than Hash#dig so a bare-String 'country'
+      # value does not raise (String has no #dig).
+      #
+      # @param result [Object] whatever the reader returned for the IP
+      # @return [String, nil] country code string, or nil
+      # @api private
+      def self.extract_db_country(result)
+        return nil unless result.is_a?(Hash)
+
+        country = result['country']
+        code =
+          if country.is_a?(Hash)
+            country['iso_code']
+          else
+            result['country_code'] || country
+          end
+        code.is_a?(String) ? code : nil
+      end
+      private_class_method :extract_db_country
 
       # Check CDN/infrastructure provider geo headers
       #
@@ -157,47 +287,70 @@ class Otto
       # 3. Fastly (Fastly-Client-IP-Country)
       # 4. Akamai (X-Akamai-Edgescape) - Complex format, extract country
       # 5. Azure Front Door (X-Azure-ClientIP-Country)
-      # 6. Semi-standard headers (X-Geo-Country, X-Country-Code, Country-Code)
+      # 6. Vercel (X-Vercel-IP-Country)
+      # 7. Semi-standard headers (X-Geo-Country, X-Country-Code, Country-Code)
+      #
+      # Simple provider headers whose value is the country code directly, checked
+      # ahead of Akamai (whose value is a compound Edgescape string). Cloudflare
+      # first (most widely deployed), then AWS CloudFront, then Fastly.
+      PRIMARY_COUNTRY_HEADERS = %w[
+        HTTP_CF_IPCOUNTRY
+        HTTP_CLOUDFRONT_VIEWER_COUNTRY
+        HTTP_FASTLY_CLIENT_IP_COUNTRY
+      ].freeze
+
+      # Remaining direct country-code headers, checked after Akamai: Azure Front
+      # Door, Vercel, then the least-reliable semi-standard headers.
+      SECONDARY_COUNTRY_HEADERS = %w[
+        HTTP_X_AZURE_CLIENTIP_COUNTRY
+        HTTP_X_VERCEL_IP_COUNTRY
+        HTTP_X_GEO_COUNTRY
+        HTTP_X_COUNTRY_CODE
+        HTTP_COUNTRY_CODE
+      ].freeze
+
+      # Check CDN/infrastructure provider geo headers, in priority order:
+      # Cloudflare, AWS CloudFront, Fastly, Akamai, Azure, Vercel, then the
+      # semi-standard headers.
       #
       # @param env [Hash] Rack environment
       # @return [String, nil] ISO 3166-1 alpha-2 country code or nil
       # @api private
       def self.check_geo_headers(env)
-        # Cloudflare (most common)
-        country = env['HTTP_CF_IPCOUNTRY']
-        return country if valid_country_code?(country)
-
-        # AWS CloudFront
-        country = env['HTTP_CLOUDFRONT_VIEWER_COUNTRY']
-        return country if valid_country_code?(country)
-
-        # Fastly
-        country = env['HTTP_FASTLY_CLIENT_IP_COUNTRY']
-        return country if valid_country_code?(country)
+        first_valid_country(env, PRIMARY_COUNTRY_HEADERS) ||
+          akamai_country(env) ||
+          first_valid_country(env, SECONDARY_COUNTRY_HEADERS)
+      end
+      private_class_method :check_geo_headers
 
-        # Akamai Edgescape (format: country_code=US,region_code=CA,...)
-        if (edgescape = env['HTTP_X_AKAMAI_EDGESCAPE'])
-          country = extract_akamai_country(edgescape)
+      # First valid country code among the given env header keys, or nil.
+      #
+      # @param env [Hash] Rack environment
+      # @param keys [Array<String>] env keys to check in order
+      # @return [String, nil]
+      # @api private
+      def self.first_valid_country(env, keys)
+        keys.each do |key|
+          country = env[key]
           return country if valid_country_code?(country)
         end
+        nil
+      end
+      private_class_method :first_valid_country
 
-        # Azure Front Door
-        country = env['HTTP_X_AZURE_CLIENTIP_COUNTRY']
-        return country if valid_country_code?(country)
-
-        # Semi-standard headers (least reliable, check last)
-        country = env['HTTP_X_GEO_COUNTRY']
-        return country if valid_country_code?(country)
-
-        country = env['HTTP_X_COUNTRY_CODE']
-        return country if valid_country_code?(country)
-
-        country = env['HTTP_COUNTRY_CODE']
-        return country if valid_country_code?(country)
+      # Country code from the Akamai Edgescape header, if present and valid.
+      #
+      # @param env [Hash] Rack environment
+      # @return [String, nil]
+      # @api private
+      def self.akamai_country(env)
+        edgescape = env['HTTP_X_AKAMAI_EDGESCAPE']
+        return nil unless edgescape
 
-        nil
+        country = extract_akamai_country(edgescape)
+        valid_country_code?(country) ? country : nil
       end
-      private_class_method :check_geo_headers
+      private_class_method :akamai_country
 
       # Extract country code from Akamai Edgescape header
       #
@@ -216,68 +369,15 @@ class Otto
       end
       private_class_method :extract_akamai_country
 
-      # 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 CDN headers or configure a custom resolver.
-      #
-      # @param ip [String] IP address
-      # @return [String] Country code or '**'
-      # @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
-
-      # Known IP ranges for major providers (limited set for basic detection)
-      # For comprehensive geo-location, use CDN headers or custom resolver
-      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
-
       # 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}$/)
+        # \A / \z (string anchors), not ^ / $ (line anchors), so an embedded
+        # newline can never satisfy the pattern.
+        code.is_a?(String) && code.length == 2 && code.match?(/\A[A-Z]{2}\z/)
       end
       private_class_method :valid_country_code?
     end

data/lib/otto/privacy/ip_privacy.rb

@@ -119,6 +119,30 @@ class Otto
         false
       end
 
+      # Redact the client identifier(s) in an RFC 7239 Forwarded header value.
+      #
+      # Only the `for=` node value is replaced with the masked IP; `proto=`,
+      # `host=`, `by=` and the overall structure are preserved so downstream
+      # scheme/host/proxy decisions (absolute URLs, redirects, secure cookies)
+      # still work. Every `for=` element in the chain is redacted. IPv6 is
+      # bracketed and quoted as the RFC requires. This is the structured-header
+      # counterpart to the wholesale X-Forwarded-For swap.
+      #
+      # @param value [String, nil] the Forwarded header value
+      # @param masked_ip [String, nil] the masked client IP
+      # @return [String, nil] the header with every `for=` value redacted, or
+      #   the value unchanged when there is nothing to mask
+      def self.mask_forwarded_for(value, masked_ip)
+        return value if value.nil? || masked_ip.nil? || masked_ip.empty?
+
+        replacement = masked_ip.include?(':') ? %("[#{masked_ip}]") : masked_ip
+        # Match `for=` only at an element/pair boundary (start, comma, or
+        # semicolon) so a parameter merely ending in "for" is never touched.
+        value.gsub(/(\A|[,;]\s*)for\s*=\s*("[^"]*"|[^;,]+)/i) do
+          "#{Regexp.last_match(1)}for=#{replacement}"
+        end
+      end
+
       # Mask IPv4 address
       #
       # @param addr [IPAddr] IPAddr object (must be IPv4)

data/lib/otto/privacy/redacted_fingerprint.rb

@@ -25,18 +25,41 @@ class Otto
                   :country, :anonymized_ua, :request_path,
                   :request_method, :referer
 
+      # IP-bearing forwarded headers overwritten with the masked IP in the
+      # geo-resolution env view. Mirrors the set
+      # IPPrivacyMiddleware#mask_forwarded_headers rewrites, so a custom resolver
+      # reading env sees masked values everywhere the middleware would. The
+      # structured RFC 7239 Forwarded header (HTTP_FORWARDED) is handled
+      # separately in {#geo_env} (dropped, not swapped, to keep valid syntax).
+      GEO_MASKED_FORWARDED_HEADERS = %w[
+        HTTP_X_FORWARDED_FOR
+        HTTP_X_REAL_IP
+        HTTP_X_CLIENT_IP
+      ].freeze
+
       # 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)
+      # @param geo_headers_trusted [Boolean] whether request geo headers may be
+      #   trusted for this request. The middleware passes false for a
+      #   non-trusted-proxy request when trusted proxies are configured, so
+      #   spoofed geo headers are ignored. Defaults to true for standalone use.
+      def initialize(env, config, geo_headers_trusted: true)
         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
+        # hashed_ip is computed above from the real IP; geo resolution then runs
+        # against a MASKED view — the masked IP AND an env with the IP-bearing
+        # headers masked — so neither a custom resolver nor the database can see
+        # the unmasked address, via the argument or via env. Country-level
+        # networks are >= /24, so the /24-masked IP resolves to the same country.
+        @country = if config.geo_enabled
+                     GeoResolver.resolve(@masked_ip, geo_env(env), config, headers_trusted: geo_headers_trusted)
+                   end
         @anonymized_ua = anonymize_user_agent(env['HTTP_USER_AGENT'])
         @request_path = env['PATH_INFO']
         @request_method = env['REQUEST_METHOD']
@@ -90,32 +113,45 @@ class Otto
 
       private
 
+      # A shallow copy of env with the client-IP fields masked, for geo
+      # resolution. Country-level geo needs nothing finer than the masked /24,
+      # so a custom resolver (arbitrary app code that might log or forward what
+      # it receives) is handed only the masked address here — never the raw host
+      # IP that env['REMOTE_ADDR'] and the forwarded headers still carry at this
+      # point in the middleware. Non-IP keys (including geo headers like
+      # CF-IPCountry) are preserved. Returns env unchanged when there is no
+      # masked IP (nothing to hide, and geo resolution short-circuits anyway).
+      #
+      # @param env [Hash] Rack environment
+      # @return [Hash] masked env view
+      def geo_env(env)
+        return env if @masked_ip.nil?
+
+        masked = env.dup
+        masked['REMOTE_ADDR'] = @masked_ip
+        GEO_MASKED_FORWARDED_HEADERS.each do |key|
+          masked[key] = @masked_ip if masked.key?(key)
+        end
+        # HTTP_FORWARDED (RFC 7239) carries the client IP in a structured `for=`
+        # token — and Otto reads it as an authoritative client-IP source in
+        # depth mode with trusted_proxy_header 'Forwarded'/'Both'. A wholesale
+        # swap would produce invalid Forwarded syntax, and geo resolution needs
+        # nothing from it, so drop it from the geo view entirely rather than
+        # leak the raw address to a custom resolver.
+        masked.delete('HTTP_FORWARDED')
+        masked
+      end
+
       # Anonymize user agent string by removing version numbers and build identifiers
       #
-      # Removes specific version numbers (*.*.* pattern) and build identifiers
-      # (e.g., Build/MRA58N) to reduce fingerprinting granularity while maintaining
-      # browser/OS info.
+      # Delegates to the public {UserAgentPrivacy.anonymize} so there is a single
+      # source of truth for the reduction (removes version numbers and build
+      # identifiers, preserving browser/OS info) shared with downstream consumers.
       #
       # @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 build identifiers (e.g., Build/MRA58N, Build/MPJ24.139-64)
-        # This must run BEFORE version stripping to avoid partial matches.
-        # If we strip versions first, Build/MPJ24.139-64 becomes Build/MPJ*.*-64,
-        # and the regex won't match properly (asterisks not in [\w.-] class).
-        anonymized = ua.gsub(/Build\/[\w.-]+/, 'Build/*')
-
-        # Remove version patterns (*.*.*.*, *.*.*, *.*)
-        # Support both dot and underscore separators (e.g., 10.15.7 and 10_15_7)
-        anonymized = anonymized
-                     .gsub(/\d+[._]\d+[._]\d+[._]\d+/, '*.*.*.*')
-                     .gsub(/\d+[._]\d+[._]\d+/, '*.*.*')
-                     .gsub(/\d+[._]\d+/, '*.*')
-
-        # Truncate if too long (prevent DoS via huge UA strings)
-        anonymized.length > 500 ? anonymized[0..499] : anonymized
+        UserAgentPrivacy.anonymize(ua)
       end
 
       # Anonymize referer URL

data/lib/otto/privacy/user_agent_privacy.rb

@@ -0,0 +1,64 @@
+# lib/otto/privacy/user_agent_privacy.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Privacy
+    # User-Agent anonymization utilities.
+    #
+    # Reduces a User-Agent string to a lower-entropy form by stripping build
+    # identifiers and version numbers and truncating, so it can be logged or
+    # stored for analytics without a high-entropy fingerprint while preserving
+    # browser/OS family information. This is the User-Agent analogue of
+    # {IPPrivacy} for IP addresses, exposed as a public surface so downstream
+    # consumers can reduce a UA outside of the full RedactedFingerprint /
+    # middleware flow without re-implementing (and drifting from) these regexes.
+    #
+    # @example
+    #   UserAgentPrivacy.anonymize(
+    #     'Mozilla/5.0 (Windows NT 10.0) Chrome/119.0.0.0 Safari/537.36'
+    #   )
+    #   # => 'Mozilla/*.* (Windows NT *.*) Chrome/*.*.*.* Safari/*.*'
+    #
+    # @note Idempotent: re-anonymizing already-anonymized output is a no-op, so
+    #   a UA reduced at the edge and one reduced again downstream agree.
+    class UserAgentPrivacy
+      # Default cap on the returned string, guarding against a DoS via a huge
+      # User-Agent header. Matches the length RedactedFingerprint has always
+      # applied.
+      DEFAULT_MAX_LENGTH = 500
+
+      # Anonymize a User-Agent string.
+      #
+      # Removes build identifiers (e.g. +Build/MRA58N+) and version numbers
+      # (+*.*.*.*+, +*.*.*+, +*.*+; dot- or underscore-separated), then
+      # truncates to +max_length+. Browser/OS family text is preserved -- the
+      # point is a partial, not a full redaction.
+      #
+      # Build identifiers are stripped BEFORE versions: if versions went first,
+      # a token like +Build/MPJ24.139-64+ would become +Build/MPJ*.*-64+ and the
+      # build regex (which matches only +[\w.-]+) would no longer catch it.
+      #
+      # @param ua [String, nil] the raw User-Agent string.
+      # @param max_length [Integer] maximum length of the returned string.
+      # @return [String, nil] the anonymized UA, or nil for nil/empty input.
+      def self.anonymize(ua, max_length: DEFAULT_MAX_LENGTH)
+        return nil if ua.nil? || ua.empty?
+
+        # Remove build identifiers (e.g., Build/MRA58N, Build/MPJ24.139-64).
+        # Must run BEFORE version stripping (see method note).
+        anonymized = ua.gsub(%r{Build/[\w.-]+}, 'Build/*')
+
+        # Remove version patterns (*.*.*.*, *.*.*, *.*), longest first.
+        # Support both dot and underscore separators (e.g. 10.15.7 and 10_15_7).
+        anonymized = anonymized
+                     .gsub(/\d+[._]\d+[._]\d+[._]\d+/, '*.*.*.*')
+                     .gsub(/\d+[._]\d+[._]\d+/, '*.*.*')
+                     .gsub(/\d+[._]\d+/, '*.*')
+
+        # Truncate if too long (prevent DoS via huge UA strings).
+        anonymized.length > max_length ? anonymized[0...max_length] : anonymized
+      end
+    end
+  end
+end

data/lib/otto/privacy.rb

@@ -5,6 +5,7 @@
 require_relative 'privacy/core'
 require_relative 'privacy/config'
 require_relative 'privacy/ip_privacy'
+require_relative 'privacy/user_agent_privacy'
 require_relative 'privacy/geo_resolver'
 require_relative 'privacy/redacted_fingerprint'
 
@@ -17,7 +18,9 @@ require_relative 'privacy/redacted_fingerprint'
 # 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)
+# - Geo-location resolution (country-level only): a configurable trusted header,
+#   built-in CDN provider headers, an optional local MaxMind-format (.mmdb)
+#   database looked up on the masked IP, or a custom resolver
 # - User agent anonymization (removes version numbers)
 #
 # Privacy is ENABLED BY DEFAULT. To disable: