trackdown 0.3.0 → 0.4.0

data/lib/generators/trackdown/templates/trackdown.rb

@@ -7,9 +7,10 @@ Trackdown.configure do |config|
   # Choose your IP geolocation provider:
   #
   # :auto (recommended, default)
-  #   - Tries Cloudflare first (instant, zero overhead)
-  #   - Falls back to MaxMind if Cloudflare not available
-  #   - Perfect for hybrid deployments
+  #   - Verifies CDN geolocation against the CDN's client-IP header
+  #   - Supports Cloudflare and Amazon CloudFront
+  #   - Falls back to MaxMind when neither CDN can be verified
+  #   - Tries MaxMind, then Unknown, when both CDN candidates appear valid
   #
   # :cloudflare
   #   - Uses Cloudflare CF-IPCountry header
@@ -17,6 +18,14 @@ Trackdown.configure do |config|
   #   - Zero additional dependencies!
   #   - Must pass request object: Trackdown.locate(ip, request: request)
   #
+  # :cloudfront
+  #   - Uses Amazon CloudFront CloudFront-Viewer-* headers
+  #   - Requires: a CloudFront origin request policy forwarding location headers
+  #   - Requires: direct-origin access blocked before headers can be trusted
+  #   - Must pass request object: Trackdown.locate(ip, request: request)
+  #   - Exact AWS header contract:
+  #     https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/adding-cloudfront-headers.html#cloudfront-headers-viewer-location
+  #
   # :maxmind
   #   - Uses MaxMind GeoLite2 database
   #   - Requires: maxmind-db and connection_pool gems
@@ -31,8 +40,29 @@ Trackdown.configure do |config|
   # 2. In Cloudflare dashboard → Network → Enable "IP Geolocation"
   #    OR under Rules → Transform Rules → Managed Transforms → Enable "Add visitor location headers"
   # 3. Use: Trackdown.locate(request.remote_ip, request: request)
+  # 4. Restrict direct-origin traffic before trusting CF-* headers:
+  #    https://developers.cloudflare.com/fundamentals/concepts/cloudflare-ip-addresses/#block-other-ip-addresses-recommended
+  #    https://developers.cloudflare.com/ssl/origin-configuration/authenticated-origin-pull/
+  #
+  # No gems, API keys, or database are needed after the CDN/origin setup.
+
+  # ========================================
+  # Amazon CloudFront Setup (for :cloudfront or :auto providers)
+  # ========================================
+  # 1. Attach an origin request policy containing CloudFront's viewer-location
+  #    headers and CloudFront-Viewer-Address. Exact AWS policy documentation:
+  #    https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/controlling-origin-requests.html
+  # 2. Restrict the origin so direct clients cannot forge CloudFront-* headers.
+  #    AWS's exact custom-origin guidance:
+  #    https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html
+  #    https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-overview.html
+  # 3. Use: Trackdown.locate(request.remote_ip, request: request)
   #
-  # That's it! No gems, no API keys, no database needed.
+  # AWS's AllViewerAndCloudFrontHeaders-2022-06 managed policy includes the
+  # required headers, but also forwards every viewer header, cookie, and query:
+  # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-origin-request-policies.html#managed-origin-request-policy-all-viewer-and-cloudfront
+  # Prefer a custom least-privilege policy, or explicitly select :cloudfront for
+  # a secured deployment where both CDN header families intentionally coexist.
 
   # ========================================
   # MaxMind Setup (for :maxmind or :auto providers)
@@ -66,6 +96,59 @@ Trackdown.configure do |config|
   # config.pool_timeout = 3   # Pool wait timeout (seconds)
   # config.memory_mode = MaxMind::DB::MODE_MEMORY # or MODE_FILE to reduce memory
 
+  # ========================================
+  # Trusted CDN Path Verification (optional, provider-specific)
+  # ========================================
+  # CDN geolocation headers are just headers: anyone who can reach an
+  # unprotected origin directly can send you a convincing set of them. Trackdown
+  # therefore marks every request-backed result :unverified unless you tell it
+  # how *you* know the request really came through that specific CDN. Keep these
+  # checks separate: a trusted CloudFront request must not authenticate CF-*
+  # headers that CloudFront forwarded from a viewer, and vice versa.
+  #
+  # Cloudflare example: have the ingress/middleware that actually checked
+  # Authenticated Origin Pulls or the Cloudflare peer network set this private
+  # Rack-environment flag. A viewer must never be able to set it:
+  #
+  # config.verify_request_came_through_trusted_cloudflare_path_with do |request|
+  #   request.env['my_app.cloudflare_origin_was_verified'] == true
+  # end
+  #
+  # CloudFront example: require the origin-only custom header configured on the
+  # distribution. Refuse to boot if the expected secret is absent, and require
+  # a non-empty supplied value before comparing:
+  #
+  # expected_cloudfront_origin_secret =
+  #   Rails.application.credentials.dig(:cloudfront, :origin_secret).to_s
+  # raise 'Missing CloudFront origin secret' if expected_cloudfront_origin_secret.empty?
+  #
+  # config.verify_request_came_through_trusted_cloudfront_path_with do |request|
+  #   supplied_cloudfront_origin_secret =
+  #     request.env['HTTP_X_CLOUDFRONT_ORIGIN_SECRET'].to_s
+  #
+  #   !supplied_cloudfront_origin_secret.empty? &&
+  #     ActiveSupport::SecurityUtils.secure_compare(
+  #       supplied_cloudfront_origin_secret,
+  #       expected_cloudfront_origin_secret
+  #     )
+  # end
+  #
+  # Both empty checks matter: Rails secure_compare('', '') is true because the
+  # implementation checks equal byte lengths and then compares the bytes:
+  # https://api.rubyonrails.org/classes/ActiveSupport/SecurityUtils.html#method-c-secure_compare
+  #
+  # Results then report `source_trust` as :host_verified instead of :unverified,
+  # and `source_was_verified_by_host?` becomes true. Trackdown reports this; it
+  # does not act on it. Deciding what an unverified location may be used for is
+  # your application's call.
+  #
+  # https://developers.cloudflare.com/ssl/origin-configuration/authenticated-origin-pull/
+  # https://developers.cloudflare.com/fundamentals/concepts/cloudflare-ip-addresses/#block-other-ip-addresses-recommended
+  # https://developers.cloudflare.com/fundamentals/reference/http-headers/#request-headers
+  # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html
+  # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-overview.html
+  # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-origin-request-policies.html#managed-origin-request-policy-all-viewer-and-cloudfront
+
   # ========================================
   # General Options
   # ========================================

data/lib/trackdown/configuration.rb

@@ -9,19 +9,22 @@ rescue LoadError
 end
 
 module Trackdown
+  # Runtime choices for providers, MaxMind, and provider-specific source trust.
   class Configuration
-    attr_accessor :provider, :maxmind_license_key, :maxmind_account_id, :database_path,
-                  :timeout, :pool_size, :pool_timeout, :memory_mode,
-                  :reject_private_ips
+    attr_reader :provider
+    attr_accessor :maxmind_license_key, :maxmind_account_id, :database_path,
+                  :timeout, :pool_size, :pool_timeout, :memory_mode, :reject_private_ips
 
     # Available provider types:
-    # :auto - Try Cloudflare first, fall back to MaxMind (recommended)
+    # :auto - Use one IP-corroborated CDN provider, otherwise fall back to MaxMind (recommended)
     # :cloudflare - Only use Cloudflare headers
+    # :cloudfront - Only use Amazon CloudFront headers
     # :maxmind - Only use MaxMind database
-    VALID_PROVIDERS = [:auto, :cloudflare, :maxmind].freeze
+    VALID_PROVIDERS = %i[auto cloudflare cloudfront maxmind].freeze
+    TRUSTED_CDN_PROVIDERS = %i[cloudflare cloudfront].freeze
 
     def initialize
-      @provider = :auto # Intelligent default: try Cloudflare first, fall back to MaxMind
+      @provider = :auto # Safe default: use one verified edge candidate, otherwise MaxMind
       @maxmind_license_key = nil
       @maxmind_account_id = nil
       @database_path = defined?(Rails) ? Rails.root.join('db', 'GeoLite2-City.mmdb').to_s : 'db/GeoLite2-City.mmdb'
@@ -30,17 +33,120 @@ module Trackdown
       @pool_timeout = 3 # seconds
       @memory_mode = MAXMIND_AVAILABLE ? MaxMind::DB::MODE_MEMORY : nil
       @reject_private_ips = true
+      @trusted_cdn_path_verifiers = {}
+      @warned_verifier_raised = {}
+      @verifier_mutex = Mutex.new
     end
 
     def provider=(value)
       unless VALID_PROVIDERS.include?(value)
         raise ArgumentError, "Invalid provider: #{value}. Must be one of: #{VALID_PROVIDERS.join(', ')}"
       end
+
       @provider = value
     end
 
     def reject_private_ips?
       @reject_private_ips
     end
+
+    # Tell Trackdown how *you* know a request really came through Cloudflare, so
+    # only Cloudflare results can say `source_trust: :host_verified`:
+    #
+    #   expected = Rails.application.credentials.cloudflare_origin_secret.to_s
+    #   raise 'Missing Cloudflare origin secret' if expected.empty?
+    #
+    #   config.verify_request_came_through_trusted_cloudflare_path_with do |request|
+    #     supplied = request.env['HTTP_X_ORIGIN_SECRET'].to_s
+    #     !supplied.empty? && ActiveSupport::SecurityUtils.secure_compare(supplied, expected)
+    #   end
+    #
+    # The non-empty checks are essential: secure_compare('', '') is true. Rails:
+    # https://api.rubyonrails.org/classes/ActiveSupport/SecurityUtils.html#method-c-secure_compare
+    #
+    # Trackdown never infers trust from headers. Anyone who can reach an
+    # unprotected origin can set them. Verify each CDN independently so a trusted
+    # CloudFront path can never vouch for forwarded, viewer-supplied CF-* headers:
+    # https://developers.cloudflare.com/ssl/origin-configuration/authenticated-origin-pull/
+    # https://developers.cloudflare.com/fundamentals/concepts/cloudflare-ip-addresses/#block-other-ip-addresses-recommended
+    # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html
+    # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-overview.html
+    # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-origin-request-policies.html#managed-origin-request-policy-all-viewer-and-cloudfront
+    #
+    # Trackdown reports this trust state; it does not act on it. Deciding what an
+    # unverified location may be used for is your application's call.
+    def verify_request_came_through_trusted_cloudflare_path_with(verifier = nil, &block)
+      verify_request_came_through_trusted_cdn_path_with(:cloudflare, verifier, &block)
+    end
+
+    def verify_request_came_through_trusted_cloudfront_path_with(verifier = nil, &block)
+      verify_request_came_through_trusted_cdn_path_with(:cloudfront, verifier, &block)
+    end
+
+    # Provider-aware lower-level form used by the two plain-English helpers above.
+    def verify_request_came_through_trusted_cdn_path_with(provider_name, verifier = nil, &block)
+      validate_trusted_cdn_provider!(provider_name)
+      verifier ||= block
+
+      if verifier.nil?
+        raise ArgumentError, "verify_request_came_through_trusted_#{provider_name}_path_with needs a block or " \
+                             'a callable saying how you know a request came through that CDN'
+      end
+
+      unless verifier.respond_to?(:call)
+        raise ArgumentError, "The trusted #{provider_name} path verifier must respond to #call " \
+                             "(a block, proc, lambda, or any callable object), got: #{verifier.inspect}"
+      end
+
+      @verifier_mutex.synchronize do
+        @warned_verifier_raised.delete(provider_name)
+        @trusted_cdn_path_verifiers[provider_name] = verifier
+      end
+    end
+
+    # Did the host vouch for this request? Asked fresh every time, never cached,
+    # and a verifier that blows up means "no" — a geolocation lookup must not be
+    # able to take an application down.
+    def request_came_through_trusted_cdn_path?(request, provider_name:)
+      validate_trusted_cdn_provider!(provider_name)
+      verifier = trusted_cdn_path_verifier_for(provider_name)
+      return false unless request && verifier
+
+      begin
+        !!verifier.call(request)
+      rescue StandardError => e
+        warn_verifier_raised(provider_name, e)
+        false
+      end
+    end
+
+    def trusted_cdn_path_verifier_for(provider_name)
+      validate_trusted_cdn_provider!(provider_name)
+      @verifier_mutex.synchronize { @trusted_cdn_path_verifiers[provider_name] }
+    end
+
+    private
+
+    def validate_trusted_cdn_provider!(provider_name)
+      return if TRUSTED_CDN_PROVIDERS.include?(provider_name)
+
+      raise ArgumentError, "Invalid trusted CDN provider: #{provider_name.inspect}. " \
+                           "Must be one of: #{TRUSTED_CDN_PROVIDERS.join(', ')}"
+    end
+
+    def warn_verifier_raised(provider_name, error)
+      should_warn = @verifier_mutex.synchronize do
+        next false if @warned_verifier_raised[provider_name]
+
+        @warned_verifier_raised[provider_name] = true
+        true
+      end
+      return unless should_warn
+
+      message = "[Trackdown] Your trusted #{provider_name} path verifier raised " \
+                "#{error.class}: #{error.message}. Treating the #{provider_name} request source as :unverified."
+
+      defined?(Rails) ? Rails.logger.error(message) : warn(message)
+    end
   end
 end

data/lib/trackdown/database_fingerprint.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Trackdown
+  # The identity of the MaxMind database file that answered a lookup.
+  #
+  # `build_epoch` comes straight from the database's own metadata, so it costs
+  # nothing. The SHA-256 digest costs a full read of the database file, so it is
+  # computed the first time somebody asks for it and then reused by every
+  # reader bound to that exact file generation — never once per lookup.
+  #
+  # If the file changes underneath us the digest becomes `nil` rather than a
+  # number that describes a file we are no longer reading.
+  #
+  # MaxMind documents the exact build_epoch metadata field here:
+  # https://maxmind.github.io/MaxMind-DB/#build_epoch
+  class DatabaseFingerprint
+    READ_CHUNK_BYTES = 1 << 20 # 1 MiB
+    CAPTURE_CURRENT_FILE_IDENTITY = Object.new.freeze
+    private_constant :CAPTURE_CURRENT_FILE_IDENTITY
+
+    attr_reader :path, :build_epoch
+
+    def initialize(path:, build_epoch: nil, captured_file_identity: CAPTURE_CURRENT_FILE_IDENTITY)
+      @path = path.to_s.dup.freeze
+      @build_epoch = build_epoch
+      @identity = if captured_file_identity.equal?(CAPTURE_CURRENT_FILE_IDENTITY)
+                    current_file_identity
+                  else
+                    captured_file_identity
+                  end
+      @mutex = Mutex.new
+    end
+
+    # Attach the metadata read by a database reader without losing the file
+    # identity captured *before* that reader opened the path. This is what keeps
+    # a reader that still has database A in memory from ever digesting database B
+    # after the path is replaced.
+    def with_build_epoch(build_epoch)
+      self.class.new(path: @path, build_epoch: build_epoch, captured_file_identity: @identity)
+    end
+
+    # Stable inside one process and suitable for sharing one lazy digest between
+    # all pooled readers that opened the same database generation.
+    def cache_key
+      [@path, @build_epoch, @identity].freeze
+    end
+
+    # When MaxMind built this database.
+    def built_at
+      Time.at(@build_epoch).utc if @build_epoch.is_a?(Numeric)
+    end
+
+    # Has the file been replaced since we fingerprinted it?
+    def changed?
+      current_file_identity != @identity
+    end
+
+    # The digest of the database we read, or nil if we can't honestly compute one.
+    def sha256
+      return @sha256 if defined?(@sha256)
+
+      @mutex.synchronize do
+        @sha256 = compute_sha256 unless defined?(@sha256)
+      end
+
+      @sha256
+    end
+
+    private
+
+    # Read the file whole, but hold only a chunk of it in memory at a time, and
+    # confirm on both sides of the read that we digested a single stable file.
+    def compute_sha256
+      return nil if @identity.nil? || changed?
+
+      digest = Digest::SHA256.new
+      File.open(@path, 'rb') do |file|
+        return nil unless identity_of(file.stat) == @identity
+
+        digest << file.read(READ_CHUNK_BYTES) until file.eof?
+
+        return nil unless identity_of(file.stat) == @identity
+      end
+
+      changed? ? nil : digest.hexdigest
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    def current_file_identity
+      identity_of(File.stat(@path))
+    rescue SystemCallError
+      nil
+    end
+
+    def identity_of(stat)
+      [stat.dev, stat.ino, stat.size, stat.mtime, stat.ctime].freeze
+    end
+  end
+end

data/lib/trackdown/database_updater.rb

@@ -1,15 +1,44 @@
+# frozen_string_literal: true
+
 require 'open-uri'
+require 'fileutils'
+require 'tempfile'
 require 'zlib'
 require 'rubygems/package'
 
 module Trackdown
+  # Downloads and safely installs the configured MaxMind GeoLite2 City database.
   class DatabaseUpdater
-    DOWNLOAD_URL = "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=%{license_key}&suffix=tar.gz"
+    DOWNLOAD_URL = 'https://download.maxmind.com/app/geoip_download?' \
+                   'edition_id=GeoLite2-City&license_key=%<license_key>s&suffix=tar.gz'
 
     class << self
       def update
-        download_url = DOWNLOAD_URL % { license_key: Trackdown.configuration.maxmind_license_key }
+        download_database { |remote_file| install_download(remote_file) }
+
+        # Serve the database we just downloaded, not the one already open in memory.
+        Providers::MaxmindProvider.reset_database!
 
+        Rails.logger.info('MaxMind database updated successfully') if defined?(Rails)
+        true
+      rescue OpenURI::HTTPError => e
+        message = http_error_message(e)
+        Rails.logger.error("Error updating MaxMind database: #{message}") if defined?(Rails)
+        raise Error, message
+      rescue Error
+        raise
+      rescue StandardError => e
+        Rails.logger.error("Error updating MaxMind database: #{e.message}") if defined?(Rails)
+        raise Error, "Failed to update database: #{e.message}"
+      end
+
+      private
+
+      def download_database(&block)
+        download_url = format(
+          DOWNLOAD_URL,
+          license_key: Trackdown.configuration.maxmind_license_key
+        )
         options = {
           http_basic_authentication: [
             Trackdown.configuration.maxmind_account_id.to_s,
@@ -18,39 +47,71 @@ module Trackdown
           ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER
         }
 
-        URI.open(download_url, **options) do |remote_file|
-          Zlib::GzipReader.wrap(remote_file) do |gz|
-            Gem::Package::TarReader.new(gz) do |tar|
-              tar.each do |entry|
-                if entry.full_name.end_with?('.mmdb')
-                  FileUtils.mkdir_p(File.dirname(Trackdown.configuration.database_path))
-
-                  File.open(Trackdown.configuration.database_path, 'wb') do |file|
-                    file.write(entry.read)
-                  end
-                  break
-                end
-              end
-            end
+        URI.parse(download_url).open(**options, &block)
+      end
+
+      def install_download(remote_file)
+        Zlib::GzipReader.wrap(remote_file) do |gzip_reader|
+          Gem::Package::TarReader.new(gzip_reader) do |tar_reader|
+            entry = tar_reader.find { |candidate| database_entry?(candidate) }
+            raise Error, 'The downloaded MaxMind archive did not contain a .mmdb database' unless entry
+
+            install_database(entry)
           end
         end
+      end
 
-        Rails.logger.info("MaxMind database updated successfully") if defined?(Rails)
-        true
-      rescue OpenURI::HTTPError => e
-        message = case e.message
+      def database_entry?(entry)
+        entry.file? && entry.full_name.end_with?('.mmdb')
+      end
+
+      def http_error_message(error)
+        case error.message
         when /401/
-          "Authentication failed. Please check your MaxMind account ID and license key."
+          'Authentication failed. Please check your MaxMind account ID and license key.'
         when /403/
-          "Access forbidden. Your MaxMind license may not have access to this database."
+          'Access forbidden. Your MaxMind license may not have access to this database.'
         else
-          "HTTP Error: #{e.message}"
+          "HTTP Error: #{error.message}"
         end
-        Rails.logger.error("Error updating MaxMind database: #{message}") if defined?(Rails)
-        raise Error, message
-      rescue => e
-        Rails.logger.error("Error updating MaxMind database: #{e.message}") if defined?(Rails)
-        raise Error, "Failed to update database: #{e.message}"
+      end
+
+      # Write beside the destination, flush the complete database, and only then
+      # replace the path. Existing MODE_FILE readers keep their already-open file
+      # instead of observing a truncate-and-rewrite in progress.
+      # Ruby File.rename contract:
+      # https://docs.ruby-lang.org/en/3.3/File.html#method-c-rename
+      # maxmind-db MODE_FILE reader:
+      # https://github.com/maxmind/MaxMind-DB-Reader-ruby/blob/v1.2.0/lib/maxmind/db/file_reader.rb#L36-L55
+      def install_database(entry)
+        destination = Trackdown.configuration.database_path
+        directory = File.dirname(destination)
+        FileUtils.mkdir_p(directory)
+
+        Tempfile.create(['trackdown-', '.mmdb'], directory) do |temporary_file|
+          temporary_file.binmode
+          copy_database(entry, temporary_file)
+          temporary_file.flush
+          temporary_file.fsync
+          File.chmod(database_permissions(destination), temporary_file.path)
+          temporary_file.close
+          File.rename(temporary_file.path, destination)
+        end
+      end
+
+      def copy_database(entry, destination)
+        until entry.eof?
+          chunk = entry.read(1 << 20)
+          break if chunk.nil? || chunk.empty?
+
+          destination.write(chunk)
+        end
+      end
+
+      def database_permissions(destination)
+        File.stat(destination).mode & 0o777
+      rescue SystemCallError
+        0o644
       end
     end
   end

data/lib/trackdown/ip_locator.rb

@@ -4,6 +4,7 @@ require_relative 'location_result'
 require_relative 'ip_validator'
 require_relative 'providers/auto_provider'
 require_relative 'providers/cloudflare_provider'
+require_relative 'providers/cloudfront_provider'
 require_relative 'providers/maxmind_provider'
 
 module Trackdown
@@ -11,7 +12,7 @@ module Trackdown
     class << self
       # Locate an IP address using the configured provider
       # @param ip [String] The IP address to locate
-      # @param request [ActionDispatch::Request, nil] Optional Rails request object for Cloudflare provider
+      # @param request [#env, nil] Optional Rack-compatible request object for CDN providers
       # @return [LocationResult] The location information
       def locate(ip, request: nil)
         IpValidator.validate!(ip)
@@ -32,6 +33,8 @@ module Trackdown
           Providers::AutoProvider
         when :cloudflare
           Providers::CloudflareProvider
+        when :cloudfront
+          Providers::CloudfrontProvider
         when :maxmind
           Providers::MaxmindProvider
         else