otto 2.5.0 → 2.7.0

data/lib/otto/privacy/config.rb

@@ -27,8 +27,30 @@ class Otto
     class Config
       include Otto::Core::Freezable
 
+      # Named privacy profiles: validated presets over the individual knobs,
+      # so a deployment's observability posture is declared in one reviewable
+      # word instead of inferred from knob combinations.
+      #
+      # - :anonymous — mask every IP, including private/localhost. For
+      #   deployments where even internal addresses are treated as PII.
+      # - :masked    — the default posture: public IPs masked, private and
+      #   localhost exempt (development-friendly privacy-by-default).
+      # - :audit     — privacy disabled: real IPs flow to env and logs. For
+      #   private/compliance environments where granular attributability
+      #   supersedes IP privacy; retention responsibility transfers to the
+      #   operator.
+      #
+      # Note the axis this controls: what PERSISTS observably (env keys, logs,
+      # fingerprints). Precise ephemeral matching against the unmasked IP does
+      # not require :audit — see EnvKeys::IP_MATCH, available in every profile.
+      PROFILES = {
+        anonymous: { disabled: false, mask_private_ips: true }.freeze,
+           masked: { disabled: false, mask_private_ips: false }.freeze,
+            audit: { disabled: true }.freeze,
+      }.freeze
+
       attr_accessor :octet_precision, :hash_rotation_period, :geo_enabled, :mask_private_ips
-      attr_reader :disabled
+      attr_reader :disabled, :correlation_secret, :geo_header, :geo_db_path
 
       # Class-level rotation key storage (mutable, not frozen with instances)
       # This is stored at the class level so it persists across frozen config instances
@@ -49,16 +71,227 @@ class Otto
       # @option options [Integer] :octet_precision Number of trailing octets to mask (1 or 2, default: 1)
       # @option options [Integer] :hash_rotation_period Seconds between key rotation (default: 86400)
       # @option options [Boolean] :geo_enabled Enable geo-location resolution (default: true)
+      # @option options [String] :geo_header Trusted, app-configured request header to read the
+      #   country code from FIRST (before the built-in CDN provider headers). Accepts either
+      #   the HTTP form ('X-Client-Country') or the Rack CGI form ('HTTP_X_CLIENT_COUNTRY');
+      #   both canonicalize to the 'HTTP_*' env key. Default nil (no app-configured header).
+      # @option options [String] :geo_db_path Filesystem path to a MaxMind-format (.mmdb)
+      #   country database used as the local IP->country fallback (looked up on the already
+      #   MASKED IP). Requires the 'maxmind-db' gem. A bad/unreadable path raises at boot,
+      #   not per-request. Default nil (no local database fallback).
+      # @option options [#get] :geo_db_reader Bring-your-own MMDB reader (any object responding
+      #   to #get, e.g. a MaxMind::DB or a compatible reader). Overrides :geo_db_path when set,
+      #   so the reader choice stays independent of Otto. Default nil.
       # @option options [Boolean] :disabled Disable privacy entirely (default: false)
       # @option options [Boolean] :mask_private_ips Mask private/localhost IPs (default: false)
+      # @option options [String] :correlation_secret A secret string that turns
+      #   on IP correlation. Default nil, meaning off.
+      #
+      #   It answers one question: "are these two requests, maybe months apart,
+      #   from the same visitor?" — without your app ever seeing the real IP.
+      #
+      #   Otto masks each IP before your app runs (203.0.113.42 becomes
+      #   203.0.113.0), which is too coarse to tell visitors apart. When a secret
+      #   is set, Otto also fingerprints the full IP, before masking, and hands
+      #   your app just the fingerprint as req.ip_correlation_hash. The same IP
+      #   always produces the same fingerprint, and it can't be turned back into
+      #   an IP without the secret.
+      #
+      #   Keep the secret stable — changing it changes every fingerprint. An empty
+      #   string is rejected, because an empty secret would let anyone reverse the
+      #   fingerprint back to an IP.
       # @option options [Redis] :redis Optional Redis connection for multi-server environments
+      # @option options [Symbol, String] :profile Named privacy profile (:anonymous,
+      #   :masked, or :audit) applied as a preset; any other explicitly passed
+      #   option overrides the preset. See {PROFILES}.
       def initialize(options = {})
+        options = self.class.profile_presets(options[:profile]).merge(options) unless options[:profile].nil?
         @octet_precision = options.fetch(:octet_precision, 1)
         @hash_rotation_period = options.fetch(:hash_rotation_period, 86_400) # 24 hours
         @geo_enabled = options.fetch(:geo_enabled, true)
         @disabled = options.fetch(:disabled, false) # Enabled by default (privacy-by-default)
         @mask_private_ips = options.fetch(:mask_private_ips, false) # Don't mask private/localhost by default
+        self.correlation_secret = options.fetch(:correlation_secret, nil) # Opt-in stable IP-correlation secret
         @redis = options[:redis] # Optional Redis connection for multi-server environments
+
+        # Geo-location fallback configuration (all opt-in, boot-time only).
+        @geo_db_reader = nil # effective MMDB reader (built from path or injected)
+        @geo_db_override = nil # reader injected via geo_db_reader= (wins over path)
+        self.geo_header = options[:geo_header] # canonicalized to an HTTP_* env key (or nil)
+        self.geo_db_reader = options[:geo_db_reader] if options.key?(:geo_db_reader)
+        @geo_db_path = normalize_geo_db_path(options[:geo_db_path])
+        load_geo_database! # build/attach the reader now so a bad path fails at boot
+      end
+
+      # Set the stable correlation secret, validating its type up front.
+      #
+      # nil or an empty string mean "correlation hash disabled" (see
+      # IPPrivacyMiddleware#correlation_hash — an empty key is never used to
+      # hash). Any other non-String is a configuration error: without this
+      # guard it would surface far from its cause, as a NoMethodError on
+      # `#empty?` deep inside per-request middleware. Fail fast here instead,
+      # at the point of misconfiguration, with a message that names the type.
+      #
+      # @param value [String, nil] stable secret, or nil/"" to disable
+      # @raise [ArgumentError] if value is neither a String nor nil
+      def correlation_secret=(value)
+        unless value.nil? || value.is_a?(String)
+          raise ArgumentError, "correlation_secret must be a String or nil, got: #{value.class}"
+        end
+
+        @correlation_secret = value
+      end
+
+      # Set the trusted, app-configured geo header.
+      #
+      # Canonicalizes to a Rack CGI env key ('HTTP_*'): 'X-Client-Country',
+      # 'x-client-country' and 'HTTP_X_CLIENT_COUNTRY' all become
+      # 'HTTP_X_CLIENT_COUNTRY'. nil / blank clears it. Rack 3's lowercase rule
+      # applies to RESPONSE headers; request headers remain 'HTTP_*' env keys,
+      # so this is the correct form to read from the request env.
+      #
+      # @param value [String, nil] header name in either HTTP or CGI form
+      def geo_header=(value)
+        @geo_header = self.class.canonicalize_geo_header(value)
+      end
+
+      # Set the geo database path (MMDB file) used for the local fallback.
+      #
+      # Does not build the reader on its own — call {#load_geo_database!} (which
+      # {Otto::Privacy::Core#configure_ip_privacy} does for you) so a bad path
+      # fails at boot rather than per-request.
+      #
+      # @param value [String, nil] filesystem path to a .mmdb file, or nil
+      def geo_db_path=(value)
+        @geo_db_path = normalize_geo_db_path(value)
+      end
+
+      # Inject a ready-made MMDB reader (any object responding to #get).
+      #
+      # This keeps the reader choice independent of Otto (MaxMind::DB, yhirose's
+      # maxminddb, or a custom object all work) and is the seam used by tests.
+      # When set, it takes precedence over {#geo_db_path}. Passing nil clears the
+      # override. Takes effect on the next {#load_geo_database!}.
+      #
+      # @param reader [#get, nil] MMDB-compatible reader, or nil to clear
+      # @raise [ArgumentError] if reader does not respond to :get
+      def geo_db_reader=(reader)
+        unless reader.nil? || reader.respond_to?(:get)
+          raise ArgumentError, "geo_db_reader must respond to :get, got: #{reader.class}"
+        end
+
+        @geo_db_override = reader
+      end
+
+      # The effective MMDB reader for this config, or nil.
+      #
+      # Returns nil when geo is disabled (so `geo: false` consults no database
+      # even if one was previously configured) or when neither a reader override
+      # nor a database path is set.
+      #
+      # The reader is a plain instance variable — no class-level store. A
+      # MaxMind::DB reader computes its IPv4 start node eagerly at construction
+      # and performs no instance mutation on #get, so it is thread-safe under
+      # concurrency and unaffected by the shallow freeze deep_freeze! applies to
+      # it. That removes the only reason to hold it off-instance, and avoids an
+      # unbounded, never-evicted process-lifetime cache — important for a
+      # long-running server.
+      #
+      # @return [#get, nil] the reader, or nil
+      def geo_db_reader
+        @geo_enabled ? @geo_db_reader : nil
+      end
+
+      # Build/attach the geo database reader for the current configuration.
+      #
+      # Boot-time only. Resolves the effective reader (injected override wins
+      # over a path). A String path is opened eagerly here so an unreadable path
+      # or a missing 'maxmind-db' gem raises now, at configuration time, rather
+      # than on the first request that needs a lookup. When geo is disabled, no
+      # database is loaded and no reader is retained.
+      #
+      # @return [void]
+      # @raise [ArgumentError] if the path is unreadable or maxmind-db is absent
+      def load_geo_database!
+        @geo_db_reader = nil
+        return unless @geo_enabled
+
+        @geo_db_reader =
+          if @geo_db_override
+            @geo_db_override
+          elsif @geo_db_path
+            build_maxmind_reader(@geo_db_path)
+          end
+      end
+
+      # Look up the preset hash for a named profile, failing fast on typos.
+      #
+      # @param profile [Symbol, String] one of the {PROFILES} keys
+      # @return [Hash] frozen preset hash
+      # @raise [ArgumentError] for an unknown profile name or an un-nameable type
+      def self.profile_presets(profile)
+        # Neither Integer nor NilClass responds to #to_sym, so an unguarded
+        # conversion raises NoMethodError for `profile: 123` or an explicit
+        # `profile: nil` — an opaque failure inconsistent with the ArgumentError
+        # the rest of this class raises for bad input (cf. correlation_secret=).
+        unless profile.respond_to?(:to_sym)
+          raise ArgumentError,
+                "Privacy profile must be a Symbol or String, got: #{profile.class}"
+        end
+
+        PROFILES.fetch(profile.to_sym) do
+          raise ArgumentError,
+                "Unknown privacy profile: #{profile.inspect} (valid: #{PROFILES.keys.join(', ')})"
+        end
+      end
+
+      # Apply a named privacy profile's presets to this config.
+      #
+      # Sets only the knobs the profile names (see {PROFILES}); other settings
+      # (octet_precision, geo, correlation_secret, ...) are untouched.
+      #
+      # Presets are applied, not reset: a knob a profile does not name keeps its
+      # previous value. Switching :anonymous -> :audit therefore leaves
+      # mask_private_ips true, because :audit names only `disabled`. That is
+      # inert rather than wrong — `disabled` short-circuits privacy_enabled?
+      # before mask_private_ips is ever read, and #profile below tests @disabled
+      # first, so the derived label stays accurate. Switching on to :masked
+      # re-sets both knobs explicitly. Only surprising if you read the raw ivars.
+      #
+      # @param profile [Symbol, String] :anonymous, :masked, or :audit
+      # @raise [ArgumentError] for an unknown profile name
+      def profile=(profile)
+        presets = self.class.profile_presets(profile)
+        @disabled = presets[:disabled] if presets.key?(:disabled)
+        @mask_private_ips = presets[:mask_private_ips] if presets.key?(:mask_private_ips)
+      end
+
+      # The profile the current knob state corresponds to.
+      #
+      # Derived from the live settings rather than remembering the last
+      # `profile=` call, so manual knob changes can never leave a stale label:
+      # what this returns is always what the config actually does.
+      #
+      # @return [Symbol] :audit, :anonymous, or :masked
+      def profile
+        return :audit if @disabled
+        return :anonymous if @mask_private_ips
+
+        :masked
+      end
+
+      # Canonicalize a geo header name to a Rack CGI env key ('HTTP_*').
+      #
+      # @param value [String, nil] header in HTTP ('X-Client-Country') or CGI form
+      # @return [String, nil] 'HTTP_*' env key, or nil for nil/blank input
+      def self.canonicalize_geo_header(value)
+        return nil if value.nil?
+
+        key = value.to_s.strip
+        return nil if key.empty?
+
+        key = key.upcase.tr('-', '_')
+        key.start_with?('HTTP_') ? key : "HTTP_#{key}"
       end
 
       # Check if privacy is enabled
@@ -124,13 +357,58 @@ class Otto
         raise ArgumentError, "octet_precision must be 1 or 2, got: #{@octet_precision}" unless [1,
                                                                                                 2].include?(@octet_precision)
 
-        return unless @hash_rotation_period < 60
+        # Type check before the numeric comparison: a non-Numeric value (false,
+        # a String from unparsed config, ...) would otherwise surface as
+        # NoMethodError/ArgumentError from #<, not a clear configuration error.
+        return if @hash_rotation_period.is_a?(Numeric) && @hash_rotation_period >= 60
 
-        raise ArgumentError, 'hash_rotation_period must be at least 60 seconds'
+        raise ArgumentError,
+              "hash_rotation_period must be at least 60 seconds, got: #{@hash_rotation_period.inspect}"
       end
 
       private
 
+      # Normalize a geo_db_path option to a non-empty String or nil.
+      #
+      # @param value [String, nil] raw path option
+      # @return [String, nil]
+      def normalize_geo_db_path(value)
+        return nil if value.nil?
+
+        path = value.to_s.strip
+        path.empty? ? nil : path
+      end
+
+      # Open an MMDB file into an in-memory reader, failing fast on problems.
+      #
+      # The 'maxmind-db' gem is an OPTIONAL dependency: it is required lazily
+      # here, only when a database path is actually configured, so Otto stays
+      # dependency-light for the (common) header-only geo setups. Callers who
+      # prefer a different reader can inject one via {#geo_db_reader=} and never
+      # trigger this path.
+      #
+      # @param path [String] filesystem path to a .mmdb file
+      # @return [MaxMind::DB] in-memory reader
+      # @raise [ArgumentError] if the path is unreadable or the gem is missing
+      def build_maxmind_reader(path)
+        raise ArgumentError, "geo_db_path is not readable: #{path.inspect}" unless File.readable?(path)
+
+        begin
+          require 'maxmind/db'
+        rescue LoadError
+          raise ArgumentError,
+                "geo_db_path is set (#{path.inspect}) but the 'maxmind-db' gem is not available. " \
+                "Add `gem 'maxmind-db'` to your Gemfile, or inject your own reader via " \
+                'configure_ip_privacy(geo_db_reader: ...).'
+        end
+
+        begin
+          MaxMind::DB.new(path, mode: MaxMind::DB::MODE_MEMORY)
+        rescue StandardError => e
+          raise ArgumentError, "Failed to open geo_db_path #{path.inspect}: #{e.class}: #{e.message}"
+        end
+      end
+
       # Redis-based rotation key (atomic across multiple servers)
       #
       # Uses SET NX GET EX to atomically:

data/lib/otto/privacy/core.rb

@@ -50,8 +50,27 @@ class Otto
       #
       # @param octet_precision [Integer] Number of octets to mask (1 or 2, default: 1)
       # @param hash_rotation [Integer] Seconds between key rotation (default: 86400)
-      # @param geo [Boolean] Enable geo-location resolution (default: true)
+      # @param geo [Boolean] Enable geo-location resolution (default: true). When
+      #   false, geo short-circuits entirely: no headers are read and no database
+      #   is loaded or consulted.
+      # @param geo_header [String] Trusted, app-configured request header checked
+      #   FIRST for the country code (e.g. 'X-Client-Country'). Accepts the HTTP
+      #   or 'HTTP_*' CGI form; both canonicalize to the env key. Pass '' to clear.
+      # @param geo_db_path [String] Path to a MaxMind-format (.mmdb) country
+      #   database for the local IP->country fallback (looked up on the MASKED
+      #   IP). Requires the optional 'maxmind-db' gem. A bad path raises at boot,
+      #   not per-request. Pass '' to clear.
+      # @param geo_db_reader [#get] Bring-your-own MMDB reader (any object
+      #   responding to #get); overrides geo_db_path. Omitted/nil leaves any
+      #   existing reader unchanged; use geo: false to stop consulting a database.
       # @param redis [Redis] Redis connection for multi-server atomic key generation
+      # @param correlation_secret [String] A secret string that turns on IP
+      #   correlation: it lets you tell whether two requests, even months apart,
+      #   came from the same visitor — without your app ever seeing the real IP.
+      #   (Otto masks the IP before your app runs; with a secret set it also
+      #   fingerprints the full IP into req.ip_correlation_hash, which can't be
+      #   reversed to an IP without the secret.) Omit it to leave any existing
+      #   secret unchanged; pass an empty string to turn the feature back off.
       #
       # @example Mask 2 octets instead of 1
       #   otto.configure_ip_privacy(octet_precision: 2)
@@ -62,20 +81,97 @@ class Otto
       # @example Custom hash rotation
       #   otto.configure_ip_privacy(hash_rotation: 24.hours)
       #
+      # @example Enable stable IP correlation (same visitor across days)
+      #   otto.configure_ip_privacy(correlation_secret: ENV['IP_CORRELATION_SECRET'])
+      #
       # @example Multi-server with Redis
       #   redis = Redis.new(url: ENV['REDIS_URL'])
       #   otto.configure_ip_privacy(redis: redis)
-      def configure_ip_privacy(octet_precision: nil, hash_rotation: nil, geo: nil, redis: nil)
+      #
+      # @example Declare the observability posture for a compliance deployment
+      #   otto.configure_ip_privacy(profile: :audit)
+      #
+      # @param profile [Symbol] Named privacy profile (:anonymous, :masked, or
+      #   :audit) applied FIRST as a preset over disabled/mask_private_ips, so
+      #   any other option in the same call overrides it. This declares the
+      #   deployment's observability posture in one reviewable word; see
+      #   Otto::Privacy::Config::PROFILES.
+      #
+      # rubocop:disable Metrics/ParameterLists -- a keyword-only configuration
+      # method; the options are self-documenting at the call site and grouping
+      # them into a hash would only obscure the supported settings.
+      def configure_ip_privacy(octet_precision: nil, hash_rotation: nil, geo: nil, redis: nil,
+                               correlation_secret: nil, geo_header: nil, geo_db_path: nil,
+                               geo_db_reader: nil, profile: nil)
+        # rubocop:enable Metrics/ParameterLists
         ensure_not_frozen!
         config = @security_config.ip_privacy_config
+        knobs = { profile: profile, octet_precision: octet_precision,
+                  hash_rotation: hash_rotation, geo: geo,
+                  correlation_secret: correlation_secret, redis: redis }
+
+        # Dry-run the assignments on a throwaway copy and validate the combined
+        # result there, so a rejected knob (octet_precision: 7 after a profile
+        # preset, say) raises before the live config has been touched — the
+        # call is all-or-nothing, never half-applied.
+        apply_privacy_knobs(config.dup, knobs).validate!
+        apply_privacy_knobs(config, knobs)
+
+        apply_geo_config(config, geo: geo, geo_header: geo_header,
+                                 geo_db_path: geo_db_path, geo_db_reader: geo_db_reader)
+      end
+
+      private
+
+      # Assign the non-geo privacy knobs onto a config.
+      #
+      # Every kwarg uses a nil guard: nil means "leave unchanged", any other
+      # value — including false or "" — is a real assignment that must either
+      # take effect or fail validation loudly. A truthiness guard would
+      # silently drop false (and, for correlation_secret, the explicit ""
+      # that disables the correlation hash).
+      #
+      # @param config [Otto::Privacy::Config] the config to mutate
+      # @param knobs [Hash] the non-geo keyword arguments from configure_ip_privacy
+      # @return [Otto::Privacy::Config] the same config, for chaining
+      # @api private
+      def apply_privacy_knobs(config, knobs)
+        config.profile = knobs[:profile] unless knobs[:profile].nil?
+        config.octet_precision = knobs[:octet_precision] unless knobs[:octet_precision].nil?
+        config.hash_rotation_period = knobs[:hash_rotation] unless knobs[:hash_rotation].nil?
+        config.geo_enabled = knobs[:geo] unless knobs[:geo].nil?
+        config.correlation_secret = knobs[:correlation_secret] unless knobs[:correlation_secret].nil?
+        config.instance_variable_set(:@redis, knobs[:redis]) unless knobs[:redis].nil?
+        config
+      end
+
+      # Apply the geo-fallback settings and (re)load the database when needed.
+      #
+      # nil means "leave unchanged"; '' clears a header or path. Any geo-affecting
+      # change triggers a boot-time (re)load so a bad geo_db_path fails here, not
+      # on the first request that needs a lookup.
+      #
+      # @param config [Otto::Privacy::Config] the privacy config to mutate
+      # @api private
+      def apply_geo_config(config, geo:, geo_header:, geo_db_path:, geo_db_reader:)
+        geo_touched = [geo, geo_header, geo_db_path, geo_db_reader].any? { |v| !v.nil? }
+
+        config.geo_header = geo_header unless geo_header.nil?
 
-        config.octet_precision = octet_precision if octet_precision
-        config.hash_rotation_period = hash_rotation if hash_rotation
-        config.geo_enabled = geo unless geo.nil?
-        config.instance_variable_set(:@redis, redis) if redis
+        # A newly supplied reader or path replaces the other database source. A
+        # reader given in this call wins over a path (documented precedence); a
+        # path given on its own clears any prior injected reader so it actually
+        # takes effect — otherwise the stale override would silently shadow the
+        # new path (leaving lookups pointed at a closed/old reader).
+        if !geo_db_reader.nil?
+          config.geo_db_reader = geo_db_reader
+          config.geo_db_path = geo_db_path unless geo_db_path.nil?
+        elsif !geo_db_path.nil?
+          config.geo_db_reader = nil
+          config.geo_db_path = geo_db_path
+        end
 
-        # Validate configuration
-        config.validate!
+        config.load_geo_database! if geo_touched
       end
     end
   end