trackdown 0.3.0 → 0.4.0

data/lib/trackdown/location_result.rb

@@ -3,15 +3,93 @@
 require 'countries'
 
 module Trackdown
+  # Where an IP address probably is — and an honest account of how we know.
+  #
+  # Every result carries its own provenance: which provider answered, from which
+  # source, when it answered, how precise that provider says the answer is, and
+  # whether the host vouched for the path the request arrived through.
+  #
+  # Nothing here is guessed. Every field is either what the provider said or
+  # something derived from it by a documented rule — never a plausible-looking
+  # placeholder. A field the answering provider cannot supply is `nil`, so a
+  # caller can always tell "the provider said no" apart from "it never said".
+  #
+  # GeoIP is an estimate. It never proves that a person or a device was in a
+  # place. MaxMind documents those limits exactly:
+  # https://support.maxmind.com/knowledge-base/articles/maxmind-geolocation-accuracy
   class LocationResult
+    # What providers have always returned for a value they don't have. Kept for
+    # backwards compatibility — new code should ask #available? and read the
+    # nil-able fields instead of parsing display strings.
+    UNKNOWN = 'Unknown'
+    UNKNOWN_FLAG = '🏳️'
+
+    # Why a lookup came back with no location. Stable and machine-readable:
+    # these symbols are part of the public API and are never translated.
+    UNAVAILABLE_REASONS = %i[
+      no_provider_available
+      address_not_found
+      provider_returned_unknown_country
+      provider_data_incomplete
+    ].freeze
+
+    # How much the host vouches for the source of a request-backed result.
+    # :host_verified only ever comes from the host's own verifier — see
+    # Trackdown::Configuration#verify_request_came_through_trusted_cloudflare_path_with
+    # and #verify_request_came_through_trusted_cloudfront_path_with.
+    SOURCE_TRUSTS = %i[unverified host_verified].freeze
+
+    # Where the IP is.
+    LOCATION_FIELDS = %i[
+      country_code country_name city flag_emoji
+      region region_code continent timezone
+      latitude longitude postal_code metro_code
+    ].freeze
+
+    # How we know, and how sure we are.
+    PROVENANCE_FIELDS = %i[
+      provider_name provider_source source_trust resolved_at
+      available estimated unavailable_reason
+      accuracy_radius_in_kilometers accuracy_radius_confidence_percentage
+      database_build_epoch database_built_at database_sha256
+    ].freeze
+
+    # Every field #to_h can emit, in the order it emits them.
+    FIELDS = (LOCATION_FIELDS + PROVENANCE_FIELDS + %i[country_info]).freeze
+
+    # What a no-argument #to_h returns: the exact shape Trackdown returned before
+    # provenance existed, kept that way as an API compatibility guarantee. Ask for
+    # the rest with `include_provenance: true` or name it in `only:`.
+    DEFAULT_FIELDS = (LOCATION_FIELDS + %i[country_info]).freeze
+
+    # The digest is the one field that costs real work — a full read of the
+    # database file — so nothing hands it to you unless you say its name.
+    FIELDS_EXCEPT_DIGEST = (FIELDS - %i[database_sha256]).freeze
+    private_constant :FIELDS_EXCEPT_DIGEST
+
     attr_reader :country_code, :country_name, :city, :flag_emoji,
                 :region, :region_code, :continent, :timezone, :latitude, :longitude,
-                :postal_code, :metro_code
+                :postal_code, :metro_code,
+                :provider_name, :provider_source, :source_trust, :resolved_at,
+                :unavailable_reason,
+                :accuracy_radius_in_kilometers, :accuracy_radius_confidence_percentage,
+                :database_build_epoch
 
+    # Every keyword is optional, so a provider only supplies what it actually knows.
+    #
+    # @param database_sha256 [String, #call, nil] the digest itself, or something
+    #   that returns it, so an expensive digest is computed only if someone asks.
+    #   Concurrent readers may each call it, so a callable should memoize its own
+    #   work — Trackdown's does.
     def initialize(country_code, country_name, city, flag_emoji,
                    region: nil, region_code: nil, continent: nil,
                    timezone: nil, latitude: nil, longitude: nil,
-                   postal_code: nil, metro_code: nil)
+                   postal_code: nil, metro_code: nil,
+                   provider_name: nil, provider_source: nil, source_trust: nil,
+                   resolved_at: nil, unavailable_reason: nil,
+                   accuracy_radius_in_kilometers: nil,
+                   accuracy_radius_confidence_percentage: nil,
+                   database_build_epoch: nil, database_sha256: nil)
       @country_code = country_code
       @country_name = country_name
       @city = city
@@ -24,34 +102,161 @@ module Trackdown
       @longitude = longitude
       @postal_code = postal_code
       @metro_code = metro_code
+
+      @provider_name = provider_name
+      @provider_source = provider_source
+      @source_trust = validate!(source_trust, SOURCE_TRUSTS, 'source trust')
+      @resolved_at = resolved_at || Time.now.utc
+      @unavailable_reason = validate!(unavailable_reason, UNAVAILABLE_REASONS, 'unavailable reason') ||
+                            (:provider_data_incomplete if blank?(country_code))
+      @accuracy_radius_in_kilometers = accuracy_radius_in_kilometers
+      @accuracy_radius_confidence_percentage = accuracy_radius_confidence_percentage
+      @database_build_epoch = database_build_epoch
+      @database_sha256 = database_sha256
+    end
+
+    # A lookup that resolved nothing, and says why.
+    #
+    #   LocationResult.unavailable(:address_not_found, provider_name: :maxmind)
+    def self.unavailable(reason, **provenance)
+      if reason.nil?
+        raise ArgumentError, "An unavailable result has to say why. Must be one of: #{UNAVAILABLE_REASONS.join(', ')}"
+      end
+      if provenance.key?(:unavailable_reason)
+        raise ArgumentError, 'Pass the unavailable reason once, as the first argument to LocationResult.unavailable'
+      end
+
+      new(nil, UNKNOWN, UNKNOWN, UNKNOWN_FLAG, unavailable_reason: reason, **provenance)
     end
 
     alias_method :country, :country_name
     alias_method :emoji, :flag_emoji
     alias_method :emoji_flag, :flag_emoji
     alias_method :country_flag, :flag_emoji
+    alias_method :provider, :provider_name
+    alias_method :accuracy_radius_km, :accuracy_radius_in_kilometers
+
+    # Did we actually resolve a location?
+    def available?
+      @unavailable_reason.nil?
+    end
+
+    def unavailable?
+      !available?
+    end
+
+    # True whenever a provider resolved any location data, including a partial
+    # result that has a city or coordinates but no country. Availability answers
+    # "could we name a country?"; estimated answers "is any returned location an
+    # inference?" Those are deliberately independent questions.
+    def estimated?
+      available? || partial_location_estimate?
+    end
+
+    # True only when the host's own verifier vouched for this request's path.
+    # Header presence alone never gets you here.
+    def source_was_verified_by_host?
+      @source_trust == :host_verified
+    end
+    alias_method :host_verified?, :source_was_verified_by_host?
+
+    # The MaxMind database digest, computed the first time it's asked for.
+    def database_sha256
+      @database_sha256 = @database_sha256.call if @database_sha256.respond_to?(:call)
+      @database_sha256
+    end
+
+    # When the database that answered was built.
+    def database_built_at
+      Time.at(@database_build_epoch).utc if @database_build_epoch.is_a?(Numeric)
+    end
 
     def country_info
       return nil unless country_code
+
       ISO3166::Country.new(country_code)
     end
 
-    def to_h
-      {
-        country_code: @country_code,
-        country_name: @country_name,
-        city: @city,
-        flag_emoji: @flag_emoji,
-        region: @region,
-        region_code: @region_code,
-        continent: @continent,
-        timezone: @timezone,
-        latitude: @latitude,
-        longitude: @longitude,
-        postal_code: @postal_code,
-        metro_code: @metro_code,
-        country_info: country_info&.data || {}
-      }
+    # The whole result as a hash, or exactly the fields you name.
+    #
+    #   result.to_h
+    #   result.to_h(only: %i[country_code city latitude longitude provider_name])
+    #   result.to_h(include_country_info: false)
+    #   result.to_h(include_provenance: true)
+    #
+    # @param only [Array<Symbol>, Symbol, nil] the exact fields to serialize, in
+    #   the order you name them. What you name is what you get: naming a field
+    #   that doesn't exist raises, and nothing you name is ever dropped, so a typo
+    #   can't silently cost you a column in a record you're keeping. The full list
+    #   of names is FIELDS.
+    # @param include_country_info [Boolean] the derived `countries` gem payload is
+    #   large; pass false to leave it out of the default shape. Ignored when you
+    #   pass `only:`, which already says exactly what you want.
+    # @param include_provenance [Boolean] add every provenance field except the
+    #   database digest, whose first read costs a full pass over the database file.
+    #   Ignored when `only:` names an exact shape.
+    def to_h(only: nil, include_country_info: true, include_provenance: false)
+      fields = if only
+                 requested_fields(only)
+               elsif include_provenance
+                 provenance_fields(include_country_info: include_country_info)
+               elsif include_country_info
+                 DEFAULT_FIELDS
+               else
+                 DEFAULT_FIELDS - %i[country_info]
+               end
+
+      fields.to_h { |field| [field, value_of(field)] }
+    end
+
+    private
+
+    def value_of(field)
+      case field
+      when :available then available?
+      when :estimated then estimated?
+      when :country_info then country_info&.data || {}
+      else public_send(field)
+      end
+    end
+
+    def requested_fields(only)
+      fields = Array(only).map { |field| field.respond_to?(:to_sym) ? field.to_sym : field }
+      unknown = fields - FIELDS
+
+      unless unknown.empty?
+        raise ArgumentError, "Unknown #{unknown.one? ? 'field' : 'fields'} for LocationResult#to_h: " \
+                             "#{unknown.map(&:inspect).join(', ')}. Available fields: #{FIELDS.join(', ')}"
+      end
+
+      fields.uniq
+    end
+
+    def provenance_fields(include_country_info:)
+      return FIELDS_EXCEPT_DIGEST if include_country_info
+
+      FIELDS_EXCEPT_DIGEST - %i[country_info]
+    end
+
+    def validate!(value, allowed, description)
+      return nil if value.nil?
+      return value if allowed.include?(value)
+
+      raise ArgumentError, "Unknown #{description}: #{value.inspect}. Must be one of: #{allowed.join(', ')}"
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def partial_location_estimate?
+      named_place = [@country_name, @city].any? { |value| !blank?(value) && value != UNKNOWN }
+      provider_fields = [
+        @region, @region_code, @continent, @timezone,
+        @latitude, @longitude, @postal_code, @metro_code
+      ]
+
+      named_place || provider_fields.any? { |value| !blank?(value) }
     end
   end
 end

data/lib/trackdown/providers/auto_provider.rb

@@ -1,25 +1,59 @@
 # frozen_string_literal: true
 
+require 'ipaddr'
+
 require_relative 'base_provider'
 require_relative 'cloudflare_provider'
+require_relative 'cloudfront_provider'
 require_relative 'maxmind_provider'
 
 module Trackdown
   module Providers
     # Intelligent provider that automatically selects the best available provider
-    # Priority order:
-    # 1. Cloudflare (fastest, zero overhead, no external dependencies)
-    # 2. MaxMind (fallback when Cloudflare not available)
+    # Selection order:
+    # 1. Use the single edge provider whose client-IP header matches the target IP.
+    # 2. Try MaxMind, then return Unknown, when no edge provider can be verified.
+    # 3. Fail closed when both edge providers appear valid; header names alone cannot
+    #    distinguish an authentic stacked-CDN request from forwarded viewer input.
     #
     # This is the recommended default for most applications
+    #
+    # IMPORTANT: When there's an upstream proxy before the CDN (e.g., a legacy
+    # API gateway), the CDN's geo headers will reflect the proxy's location, not
+    # the real client. AutoProvider detects this by comparing the CDN's own view
+    # of the client IP (CF-Connecting-IP for Cloudflare, CloudFront-Viewer-Address
+    # for CloudFront) with the passed IP and falls back to MaxMind (or Unknown when
+    # MaxMind is unavailable) on a mismatch.
+    #
+    # Cloudflare documents that CF-Connecting-IP is added only on edge-to-origin traffic:
+    # https://developers.cloudflare.com/fundamentals/reference/http-headers/#cf-connecting-ip
+    # AWS documents that the managed CloudFront policy forwards every viewer header,
+    # so CF-* names can still be viewer-controlled when they arrive through CloudFront:
+    # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-origin-request-policies.html#managed-origin-request-policy-all-viewer-and-cloudfront
     class AutoProvider < BaseProvider
-      @@warned_no_providers = false
-      @@warn_mutex = Mutex.new
+      CF_CONNECTING_IP_HEADER = 'HTTP_CF_CONNECTING_IP'
+      CLOUDFRONT_VIEWER_ADDRESS_HEADER = 'HTTP_CLOUDFRONT_VIEWER_ADDRESS'
+
+      @warned_no_providers = false
+      @warned_ip_mismatch = false
+      @warned_ambiguous_edge = false
+      @warn_mutex = Mutex.new
 
       class << self
+        # :auto has no identity of its own. Every result names whichever provider
+        # actually won, and a result with no provider at all names none.
+        def provider_name
+          nil
+        end
+
+        def provider_source
+          nil
+        end
+
         # Auto provider is available if at least one provider is available
         def available?(request: nil)
-          CloudflareProvider.available?(request: request) ||
+          cloudflare_auto_available?(request) ||
+            cloudfront_auto_available?(request) ||
             MaxmindProvider.available?(request: request)
         end
 
@@ -28,34 +62,227 @@ module Trackdown
         # @param request [ActionDispatch::Request, nil] Optional Rails request object
         # @return [LocationResult] The location information
         def locate(ip, request: nil)
-          # Try Cloudflare first - it's instant and free!
-          if CloudflareProvider.available?(request: request)
-            return CloudflareProvider.locate(ip, request: request)
-          end
+          edge_provider = select_edge_provider(ip, request)
+          return edge_provider.locate(ip, request: request) if edge_provider
 
           # Fall back to MaxMind if available
-          if MaxmindProvider.available?(request: request)
-            return MaxmindProvider.locate(ip, request: request)
-          end
+          return MaxmindProvider.locate(ip, request: request) if MaxmindProvider.available?(request: request)
 
           # No providers available - fail gracefully with a warning
           warn_no_providers
-          LocationResult.new(nil, 'Unknown', 'Unknown', '🏳️')
+          LocationResult.unavailable(:no_provider_available)
         end
 
         private
 
+        def select_edge_provider(ip, request)
+          candidates = edge_candidates(ip, request)
+          verified_indices = candidates.each_index.select { |index| candidates[index][:matches] }
+
+          if verified_indices.length > 1
+            # The AWS managed policy forwards all viewer headers, so a CloudFront viewer
+            # can manufacture a matching CF-Connecting-IP. Conversely, Cloudflare forwards
+            # ordinary viewer headers, including CloudFront-* names. With both candidates
+            # matching, :auto has no authenticated signal that can safely break the tie.
+            warn_ambiguous_edge(ip)
+            return nil
+          end
+
+          return warn_first_unverified(candidates, ip) if verified_indices.empty?
+
+          selected_index = verified_indices.first
+          skipped_candidate = candidates.first(selected_index).find { |candidate| candidate[:available] }
+          warn_unverified_candidate(skipped_candidate, ip) if skipped_candidate
+          candidates[selected_index][:provider]
+        end
+
+        def edge_candidates(ip, request)
+          cloudflare_available = CloudflareProvider.available?(request: request)
+          cloudfront_available = CloudfrontProvider.available?(request: request)
+
+          [
+            {
+              provider: CloudflareProvider,
+              name: 'Cloudflare',
+              header_name: 'CF-Connecting-IP',
+              header_value: request&.env&.dig(CF_CONNECTING_IP_HEADER),
+              available: cloudflare_available,
+              matches: cloudflare_available && cloudflare_ip_matches?(ip, request)
+            },
+            {
+              provider: CloudfrontProvider,
+              name: 'CloudFront',
+              header_name: 'CloudFront-Viewer-Address',
+              header_value: request&.env&.dig(CLOUDFRONT_VIEWER_ADDRESS_HEADER),
+              available: cloudfront_available,
+              matches: cloudfront_available && cloudfront_ip_matches?(ip, request)
+            }
+          ]
+        end
+
+        def warn_first_unverified(candidates, ip)
+          candidate = candidates.find { |item| item[:available] }
+          warn_unverified_candidate(candidate, ip) if candidate
+          nil
+        end
+
+        def warn_unverified_candidate(candidate, ip)
+          warn_ip_mismatch(
+            provider: candidate[:name],
+            ip: ip,
+            header_name: candidate[:header_name],
+            header_value: candidate[:header_value]
+          )
+        end
+
+        # Check if the IP we want to geolocate matches what Cloudflare saw as the client
+        # If they don't match, there's an upstream proxy and Cloudflare's geo headers are wrong
+        def cloudflare_ip_matches?(ip, request)
+          return false unless request
+
+          cf_connecting_ip = request.env[CF_CONNECTING_IP_HEADER]
+          return false unless cf_connecting_ip.is_a?(String)
+          return false if cf_connecting_ip.empty?
+
+          # Normalize IPs for comparison (handle IPv6 formatting differences)
+          normalized_ip = normalize_ip(ip)
+          normalized_cf_ip = normalize_ip(cf_connecting_ip)
+          !normalized_ip.nil? && normalized_ip == normalized_cf_ip
+        end
+
+        # Check if the IP we want to geolocate matches what CloudFront saw as the client.
+        # CloudFront-Viewer-Address is "IP:port" (the port trails the last colon, which
+        # also works for IPv6 since the address itself contains colons).
+        def cloudfront_ip_matches?(ip, request)
+          return false unless request
+
+          normalized_ip = normalize_ip(ip)
+          cloudfront_ip = cloudfront_viewer_ip(request)
+          !normalized_ip.nil? && normalized_ip == cloudfront_ip
+        end
+
+        def cloudflare_auto_available?(request)
+          CloudflareProvider.available?(request: request) &&
+            !normalize_ip(request.env[CF_CONNECTING_IP_HEADER]).nil?
+        end
+
+        def cloudfront_auto_available?(request)
+          CloudfrontProvider.available?(request: request) && !cloudfront_viewer_ip(request).nil?
+        end
+
+        # AWS specifies CloudFront-Viewer-Address as the viewer IP followed by its
+        # source port. Split on the final colon for AWS's unbracketed IPv6 form, while
+        # also accepting RFC 3986 bracketed IP literals defensively.
+        # AWS: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/adding-cloudfront-headers.html#cloudfront-headers-viewer-location
+        # RFC 3986: https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2
+        # Port range/reserved zero: https://www.rfc-editor.org/rfc/rfc6335#section-6
+        def cloudfront_viewer_ip(request)
+          return nil unless request
+
+          viewer_address = request.env[CLOUDFRONT_VIEWER_ADDRESS_HEADER]
+          return nil unless viewer_address.is_a?(String)
+
+          value = viewer_address.strip
+          return nil if value.empty?
+
+          match = value.match(/\A\[(.+)\]:(\d+)\z/)
+          if match
+            ip = match[1]
+            port = match[2]
+          else
+            ip, separator, port = value.rpartition(':')
+            return nil if separator.empty?
+          end
+
+          return nil unless valid_source_port?(port)
+
+          normalize_ip(ip)
+        end
+
+        def valid_source_port?(port)
+          return false unless /\A\d{1,5}\z/.match?(port)
+
+          (1..65_535).cover?(Integer(port, 10))
+        rescue ArgumentError
+          false
+        end
+
+        def normalize_ip(ip)
+          return nil unless ip.is_a?(String)
+
+          value = ip.to_s.strip
+          return nil if value.empty?
+
+          parsed_ip = IPAddr.new(value)
+          # IPAddr normalizes equivalent IPv6 spellings; #native converts an
+          # IPv4-mapped IPv6 address to its native IPv4 representation.
+          # https://docs.ruby-lang.org/en/3.3/IPAddr.html
+          # https://docs.ruby-lang.org/en/3.3/IPAddr.html#method-i-native
+          parsed_ip = parsed_ip.native if parsed_ip.ipv4_mapped?
+          parsed_ip.to_s.downcase
+        rescue IPAddr::Error
+          nil
+        end
+
+        def warn_ip_mismatch(provider:, ip:, header_name:, header_value:)
+          return if @warned_ip_mismatch
+
+          warn_mutex.synchronize do
+            return if @warned_ip_mismatch
+
+            @warned_ip_mismatch = true
+
+            reason = if header_value.nil? || (header_value.is_a?(String) && header_value.empty?)
+                       "#{header_name} is missing"
+                     elsif !header_value.is_a?(String)
+                       "#{header_name} is malformed"
+                     else
+                       "#{header_name} (#{header_value}) does not match the request IP (#{ip})"
+                     end
+            message = "[Trackdown] Cannot verify #{provider} geolocation because #{reason}. " \
+                      "Skipping #{provider} and trying the next available provider."
+
+            if defined?(Rails)
+              Rails.logger.info(message)
+            else
+              warn(message)
+            end
+          end
+        end
+
+        def warn_ambiguous_edge(ip)
+          return if @warned_ambiguous_edge
+
+          warn_mutex.synchronize do
+            return if @warned_ambiguous_edge
+
+            @warned_ambiguous_edge = true
+
+            message = "[Trackdown] Both Cloudflare and CloudFront headers match request IP (#{ip}). " \
+                      'Because forwarded viewer headers can spoof this combination, :auto cannot ' \
+                      'choose safely. Trying MaxMind and otherwise returning Unknown; configure ' \
+                      'an explicit provider if this is an intentional stacked-CDN deployment.'
+
+            if defined?(Rails)
+              Rails.logger.warn(message)
+            else
+              warn(message)
+            end
+          end
+        end
+
         def warn_no_providers
           # Only warn once per process to avoid log spam
-          return if @@warned_no_providers
+          return if @warned_no_providers
+
+          warn_mutex.synchronize do
+            return if @warned_no_providers
 
-          @@warn_mutex.synchronize do
-            return if @@warned_no_providers
-            @@warned_no_providers = true
+            @warned_no_providers = true
 
             message = "[Trackdown] No IP geolocation provider available. Returning 'Unknown' for all lookups. " \
-                      "Configure Cloudflare headers or MaxMind to enable geolocation. " \
-                      "See: https://github.com/rameerez/trackdown"
+                      'Configure verified Cloudflare or CloudFront headers, or MaxMind, to enable geolocation. ' \
+                      'See: https://github.com/rameerez/trackdown'
 
             if defined?(Rails)
               Rails.logger.warn(message)
@@ -64,6 +291,10 @@ module Trackdown
             end
           end
         end
+
+        def warn_mutex
+          @warn_mutex ||= Mutex.new
+        end
       end
     end
   end