otto 2.11.0 → 2.12.0

data/lib/otto/security/config.rb

@@ -5,10 +5,10 @@
 require 'securerandom'
 require 'digest'
 require 'openssl'
-require 'ipaddr'
 require 'rack/request'
 require_relative '../core/freezable'
 require_relative 'csp/policy'
+require_relative 'trusted_proxy_config'
 
 class Otto
   module Security
@@ -30,14 +30,200 @@ class Otto
     class Config
       include Otto::Core::Freezable
 
-      # Error raised when the two mutually-exclusive trusted-proxy resolution
-      # modes are configured together: CIDR-walk (enumerated #trusted_proxies)
-      # and count-based depth (#trusted_proxy_depth >= 1).
-      PROXY_MODE_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
-        Cannot configure both trusted_proxies (CIDR filter mode) and
-        trusted_proxy_depth >= 1 (count mode). Enumerate proxy CIDRs OR set a
-        hop count, not both.
-      MSG
+      # Otto accepts exactly one W3C Referrer Policy token for its
+      # referrer_policy setting. The supported tokens are enumerated below:
+      # https://www.w3.org/TR/referrer-policy/#referrer-policy-header-dfn
+      REFERRER_POLICIES = %w[
+        no-referrer
+        no-referrer-when-downgrade
+        strict-origin
+        strict-origin-when-cross-origin
+        same-origin
+        origin
+        origin-when-cross-origin
+        unsafe-url
+      ].freeze
+      DEFAULT_REFERRER_POLICY = 'strict-origin-when-cross-origin'
+
+      # Hash-compatible storage that keeps the generic security-header API and
+      # the dedicated referrer_policy setting on one validated code path.
+      # Existing callers may continue to mutate Config#security_headers like a
+      # Hash. Every destructive Hash operation keeps the required
+      # Referrer-Policy entry canonical, validates any replacement before
+      # committing it, and prevents removal of the dedicated setting.
+      class SecurityHeaders < Hash
+        REFERRER_POLICY_HEADER = 'referrer-policy'
+        REFERRER_POLICY_REMOVAL_MESSAGE =
+          'referrer-policy cannot be removed; assign a valid referrer_policy token instead'
+
+        def initialize(referrer_policy_validator)
+          @referrer_policy_validator = referrer_policy_validator
+          super()
+        end
+
+        def []=(header, value)
+          if referrer_policy_header?(header)
+            validated = @referrer_policy_validator.call(value).dup.freeze
+            super(REFERRER_POLICY_HEADER, validated)
+          else
+            super
+          end
+        end
+        alias store []=
+
+        def merge!(*other_hashes)
+          raise FrozenError, "can't modify frozen #{self.class}" if frozen?
+
+          replacement = dup
+          other_hashes.each do |other_hash|
+            converted = Hash.try_convert(other_hash)
+            raise TypeError, "no implicit conversion of #{other_hash.class} into Hash" unless converted
+
+            converted.each_pair do |header, value|
+              key = referrer_policy_header?(header) ? REFERRER_POLICY_HEADER : header
+              value = yield(key, replacement[key], value) if block_given? && replacement.key?(key)
+              replacement[key] = value
+            end
+          end
+
+          super(replacement, &nil)
+        end
+        alias update merge!
+
+        def replace(other_hash)
+          replacement = self.class.new(@referrer_policy_validator)
+          replacement.merge!(other_hash)
+          replacement[REFERRER_POLICY_HEADER] = self[REFERRER_POLICY_HEADER] unless replacement.key?(
+            REFERRER_POLICY_HEADER
+          )
+          super(replacement)
+        end
+
+        # Clearing custom security headers must not remove Otto's required,
+        # dedicated referrer_policy setting.
+        def clear
+          policy = self[REFERRER_POLICY_HEADER]
+          super
+          self[REFERRER_POLICY_HEADER] = policy
+          self
+        end
+
+        def delete(header, &)
+          raise ArgumentError, REFERRER_POLICY_REMOVAL_MESSAGE if referrer_policy_header?(header)
+
+          super
+        end
+
+        def delete_if(&block)
+          return enum_for(__method__) unless block
+
+          filter_entries!(remove_when: true, return_nil_when_unchanged: false, &block)
+        end
+
+        def reject!(&block)
+          return enum_for(__method__) unless block
+
+          filter_entries!(remove_when: true, return_nil_when_unchanged: true, &block)
+        end
+
+        def keep_if(&block)
+          return enum_for(__method__) unless block
+
+          filter_entries!(remove_when: false, return_nil_when_unchanged: false, &block)
+        end
+
+        def select!(&block)
+          return enum_for(__method__) unless block
+
+          filter_entries!(remove_when: false, return_nil_when_unchanged: true, &block)
+        end
+        alias filter! select!
+
+        # Remove the first non-Referrer-Policy entry, keeping the dedicated
+        # setting even when it is the only entry left.
+        def shift
+          raise FrozenError, "can't modify frozen #{self.class}" if frozen?
+
+          header = each_key.find { |key| !referrer_policy_header?(key) }
+          return nil unless header
+
+          [header, delete(header)]
+        end
+
+        def transform_values!
+          return enum_for(__method__) unless block_given?
+
+          replacement = self.class.new(@referrer_policy_validator)
+          each_pair { |header, value| replacement[header] = yield(value) }
+          replace(replacement)
+        end
+
+        # Hash#transform_keys! accepts an optional key-mapping Hash, a block,
+        # or both (the mapping wins for keys it contains). Referrer-Policy may
+        # change case but cannot be renamed to a different field.
+        def transform_keys!(*args, &block)
+          if args.empty? && !block
+            return enum_for(__method__, *args)
+          elsif args.length > 1
+            raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 0..1)"
+          end
+
+          mapping = args.first
+          replacement = self.class.new(@referrer_policy_validator)
+          each_pair do |header, value|
+            transformed = transformed_header(header, mapping, block)
+            raise ArgumentError, REFERRER_POLICY_REMOVAL_MESSAGE if referrer_policy_header?(header) &&
+                                                                    !referrer_policy_header?(transformed)
+
+            replacement[transformed] = value
+          end
+          replace(replacement)
+        end
+
+        # Identity comparison would make normal String lookups miss the
+        # canonical Referrer-Policy key and create apparent duplicates.
+        def compare_by_identity
+          raise ArgumentError, 'security_headers cannot use identity comparison'
+        end
+
+        private
+
+        def referrer_policy_header?(header)
+          header.to_s.casecmp?(REFERRER_POLICY_HEADER)
+        end
+
+        def filter_entries!(remove_when:, return_nil_when_unchanged:)
+          replacement = self.class.new(@referrer_policy_validator)
+          each_pair do |header, value|
+            selected = yield(header, value)
+            keep = remove_when ? !selected : selected
+            raise ArgumentError, REFERRER_POLICY_REMOVAL_MESSAGE if referrer_policy_header?(header) && !keep
+
+            replacement[header] = value if keep
+          end
+
+          return nil if return_nil_when_unchanged && replacement == self
+
+          replace(replacement)
+        end
+
+        def transformed_header(header, mapping, block)
+          return mapping[header] if mapping&.key?(header)
+          return block.call(header) if block
+
+          header
+        end
+      end
+
+      # Trusted-proxy error messages and values, owned by TrustedProxyConfig
+      # and aliased here because callers have always referenced them on Config.
+      PROXY_MODE_CONFLICT_MESSAGE            = TrustedProxyConfig::PROXY_MODE_CONFLICT_MESSAGE
+      TRUST_NO_PROXIES_CONFLICT_MESSAGE      = TrustedProxyConfig::TRUST_NO_PROXIES_CONFLICT_MESSAGE
+      TRUST_NO_PROXIES_ENTRY_MESSAGE         = TrustedProxyConfig::TRUST_NO_PROXIES_ENTRY_MESSAGE
+      FORWARDED_HEADER_CIDR_CONFLICT_MESSAGE = TrustedProxyConfig::FORWARDED_HEADER_CIDR_CONFLICT_MESSAGE
+      TRUST_NO_PROXIES                       = TrustedProxyConfig::TRUST_NO_PROXIES
+      TRUSTED_PROXY_HEADERS                  = TrustedProxyConfig::HEADERS
+      DEFAULT_TRUSTED_PROXY_HEADER           = TrustedProxyConfig::DEFAULT_HEADER
 
       # Error raised when an app-configured trusted geo header (ip_privacy
       # geo_header) is combined with count-based depth mode. Geo headers are
@@ -56,53 +242,16 @@ class Otto
         (geo_db_path or geo_db_reader).
       MSG
 
-      # Error raised when the explicit "trust no proxy" assertion
-      # (#trust_no_proxies!, `trusted_proxies: :none`) is combined with an
-      # actual trust grant (enumerated CIDRs or a depth >= 1). The two say
-      # opposite things about the same peer, so the combination is refused at
-      # configuration time rather than silently resolved in one direction.
-      TRUST_NO_PROXIES_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
-        Cannot combine trusted_proxies: :none (trust no proxy) with
-        trusted_proxies CIDRs or trusted_proxy_depth >= 1. Assert :none OR
-        grant trust, not both.
-      MSG
-
-      # Error raised when the trust-nobody sentinel arrives as a proxy ENTRY
-      # (`trusted_proxies: ['none']`, as a YAML/JSON list naturally yields, or
-      # `add_trusted_proxy('none')`) instead of as the whole option. Inside a
-      # list it would otherwise register a legacy string-prefix matcher that
-      # matches nothing: peers would be untrusted, but trust_no_proxies? would
-      # stay false and the config would stake a forwarding-family claim, so the
-      # explicit assertion would be silently replaced by a lookalike.
-      TRUST_NO_PROXIES_ENTRY_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
-        trusted_proxies entry :none is the trust-nobody assertion, not a proxy
-        address. Pass trusted_proxies: :none as the whole option (not inside a
-        list) or call trust_no_proxies! instead.
-      MSG
-
-      # Sentinel accepted wherever a trusted_proxies list is accepted, meaning
-      # "the operator asserts that NO proxy is trusted". See #trust_no_proxies!.
-      TRUST_NO_PROXIES = :none
-
-      # Whether a trusted_proxies option value is the trust-nobody sentinel.
-      # Accepts the symbol and the String spelling 'none' (case-insensitive),
-      # which is what YAML/ENV-driven configuration naturally produces; without
-      # this, 'none' would fall through to add_trusted_proxy and install a
-      # legacy string-prefix matcher, silently inverting the assertion.
+      # Whether a trusted_proxies option value is the trust-nobody sentinel
+      # (:none, or 'none' in any case). See
+      # TrustedProxyConfig.trust_no_proxies_option?.
       #
       # @param value [Object] raw trusted_proxies option
       # @return [Boolean]
       def self.trust_no_proxies_option?(value)
-        (value.is_a?(Symbol) || value.is_a?(String)) && value.to_s.casecmp?('none')
+        TrustedProxyConfig.trust_no_proxies_option?(value)
       end
 
-      # Forwarded-header sources depth mode (#trusted_proxy_depth) can count
-      # hops from: X-Forwarded-For (default), the RFC 7239 Forwarded header, or
-      # Both (Forwarded when present, else X-Forwarded-For). Mirrors
-      # OneTimeSecret's site.network.trusted_proxy.header. Only consulted in
-      # depth mode; CIDR-walk is unaffected.
-      TRUSTED_PROXY_HEADERS = %w[X-Forwarded-For Forwarded Both].freeze
-
       # Rack uses one process-global priority for forwarded host, port, scheme,
       # and IP resolution. Keep it aligned with Otto's configured forwarding
       # family so the two request views cannot silently disagree.
@@ -113,28 +262,14 @@ class Otto
         'Forwarded' => [:forwarded].freeze,
         'Both' => %i[forwarded x_forwarded].freeze,
       }.freeze
-      DEFAULT_TRUSTED_PROXY_HEADER = 'X-Forwarded-For'
       FORWARDING_FAMILY_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
         Cannot use forwarding family %s (trusted_proxy_header) because another
         Otto application in this process already uses %s. Rack's forwarded
         host, port, scheme, and IP policy is process-global, so every Otto
         application in one process that resolves proxied requests must use the
-        same forwarding family.
-      MSG
-      # Error raised when a non-default trusted_proxy_header is combined with
-      # CIDR filter mode. Otto's CIDR-walk resolves the client IP from the
-      # X-Forwarded-For family only (X-Forwarded-For, then X-Real-IP, then
-      # X-Client-IP — Otto::Utils::FORWARDED_FOR_HEADERS), never RFC 7239
-      # Forwarded, while trusted_proxy_header also pins Rack's
-      # forwarding family; honoring 'Forwarded' or 'Both' there would make Rack
-      # read a header Otto ignores, recreating the disagreement the pin exists
-      # to close.
-      FORWARDED_HEADER_CIDR_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
-        Cannot configure trusted_proxy_header 'Forwarded' or 'Both' together
-        with trusted_proxies (CIDR filter mode): CIDR-walk resolves client IPs
-        from the X-Forwarded-For family only (X-Forwarded-For, X-Real-IP,
-        X-Client-IP), never RFC 7239 Forwarded. Use trusted_proxy_depth (count
-        mode) to read the RFC 7239 Forwarded header.
+        same forwarding family. A test suite that builds applications with
+        different families must clear this between tests: require
+        'otto/testing' and call Otto::Testing.reset!.
       MSG
 
       # Eager so the first two concurrent Otto.new calls cannot race on
@@ -210,16 +345,16 @@ class Otto
         attr_reader :rack_forwarding_family
 
         # Clear process-global forwarding state between isolated RSpec examples.
+        # Otto::Testing.reset! does the same under any test framework.
         #
         # @api private
         def reset_rack_forwarding_family_for_testing!
-          raise 'reset_rack_forwarding_family_for_testing! is only available in RSpec test environment' unless defined?(RSpec)
-
-          RACK_FORWARDING_MUTEX.synchronize do
-            @rack_forwarding_owners = nil
-            @rack_forwarding_family = nil
-            RACK_REQUEST.forwarded_priority = DEFAULT_RACK_FORWARDED_PRIORITY.dup
+          unless defined?(RSpec)
+            raise 'reset_rack_forwarding_family_for_testing! is only available in RSpec test environment; ' \
+                  "outside RSpec, require 'otto/testing' and call Otto::Testing.reset!"
           end
+
+          reset_rack_forwarding_family!
         end
 
         private
@@ -228,6 +363,17 @@ class Otto
         def rack_forwarding_owners
           @rack_forwarding_owners ||= {}.compare_by_identity
         end
+
+        # Drop every commitment and restore Rack's load-time priority. Private
+        # because production must never do this: it is what lets two configs
+        # with different families coexist. Otto::Testing.reset! reaches it.
+        def reset_rack_forwarding_family!
+          RACK_FORWARDING_MUTEX.synchronize do
+            @rack_forwarding_owners = nil
+            @rack_forwarding_family = nil
+            RACK_REQUEST.forwarded_priority = DEFAULT_RACK_FORWARDED_PRIORITY.dup
+          end
+        end
       end
 
       # Endpoint group name shared by the CSP `report-to` directive and the
@@ -253,10 +399,10 @@ class Otto
                     :max_param_keys
 
       attr_reader :csrf_protection,  :csrf_header_key,
-                  :trusted_proxies, :require_secure_cookies,
+                  :require_secure_cookies,
                   :security_headers,
                   :csp_nonce_enabled, :debug_csp, :mcp_auth, :csp_nonce_key,
-                  :ip_privacy_config, :trusted_proxy_depth, :trusted_proxy_header,
+                  :ip_privacy_config,
                   :csp_report_uri, :csp_report_to_url, :csp_violation_callback,
                   :csp_directive_overrides, :csp_request_extras_enabled
 
@@ -272,13 +418,10 @@ class Otto
         @max_request_size       = 10 * 1024 * 1024 # 10MB
         @max_param_depth        = 32
         @max_param_keys         = 64
-        @trusted_proxies        = []
-        @trusted_proxy_matchers = []
-        @trust_no_proxies       = false
-        @trusted_proxy_depth    = nil
-        @trusted_proxy_header   = DEFAULT_TRUSTED_PROXY_HEADER
+        @trusted_proxy_config   = TrustedProxyConfig.new
         @require_secure_cookies = false
-        @security_headers       = default_security_headers
+        @security_headers       = SecurityHeaders.new(method(:validate_referrer_policy!))
+        @security_headers.merge!(default_security_headers)
         @input_validation       = true
         @csp_nonce_enabled      = false
         @debug_csp              = false
@@ -331,14 +474,52 @@ class Otto
         @csrf_protection
       end
 
+      # The active trusted-proxy mode: :filter, :depth, :none, or nil when
+      # proxy trust is unconfigured. The TrustedProxyConfig behind it is not
+      # exposed, because its setters would skip the Rack forwarding-family pin
+      # and the geo_header check this class adds.
+      #
+      # @return [Symbol, nil]
+      def trusted_proxy_mode
+        @trusted_proxy_config.mode
+      end
+
+      # Proxy entries registered with #add_trusted_proxy, in order.
+      #
+      # @return [Array<String, Regexp>]
+      def trusted_proxies
+        @trusted_proxy_config.proxies
+      end
+
+      # Count-based trusted-proxy depth, or nil. See #trusted_proxy_depth=.
+      #
+      # @return [Integer, nil]
+      def trusted_proxy_depth
+        @trusted_proxy_config.depth
+      end
+
+      # Forwarded header family depth mode counts hops from. See
+      # #trusted_proxy_header=.
+      #
+      # @return [String] one of TRUSTED_PROXY_HEADERS
+      def trusted_proxy_header
+        @trusted_proxy_config.header
+      end
+
       # Add a trusted proxy server for accurate client IP detection
       #
       # Only requests from trusted proxies will have their X-Forwarded-For
       # and similar headers honored for IP detection. This prevents IP spoofing
       # from untrusted sources.
       #
-      # @param proxy [String, Array] IP address, CIDR range, or array of addresses
-      # @raise [ArgumentError] if proxy is not a String or Array
+      # Mutually exclusive with count-based depth, with the trust-nobody
+      # assertion, and with a trusted_proxy_header other than X-Forwarded-For;
+      # each conflict raises here rather than only at freeze (which the test
+      # harness skips). A list is validated whole before any entry is
+      # registered. See TrustedProxyConfig#add.
+      #
+      # @param proxy [String, Regexp, Array] IP address, CIDR range, Regexp, or array of these
+      # @raise [ArgumentError] if proxy is not a String, Regexp, or Array, or on a conflict
       # @raise [FrozenError] if configuration is frozen
       # @return [void]
       #
@@ -352,67 +533,21 @@ class Otto
       #   config.add_trusted_proxy(['10.0.0.1', '172.16.0.0/12'])
       def add_trusted_proxy(proxy)
         ensure_not_frozen!
-        # CIDR-walk and count-based depth are mutually exclusive. Catch the
-        # conflict eagerly here (and in #trusted_proxy_depth=) so it surfaces at
-        # configuration time, not only at freeze (which the test harness skips).
-        raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if trusted_proxy_depth_mode?
-        raise ArgumentError, TRUST_NO_PROXIES_CONFLICT_MESSAGE if @trust_no_proxies
-        # Same pattern for header-then-proxies; proxies-then-header is caught
-        # in #trusted_proxy_header=.
-        raise ArgumentError, FORWARDED_HEADER_CIDR_CONFLICT_MESSAGE unless default_trusted_proxy_header?
-
-        # The trust-nobody sentinel is an option value, never an entry; validate
-        # the whole list before registering anything so a bad list leaves the
-        # config untouched.
-        Array(proxy).each do |entry|
-          raise ArgumentError, TRUST_NO_PROXIES_ENTRY_MESSAGE if self.class.trust_no_proxies_option?(entry)
-        end
 
-        case proxy
-        when String, Regexp
-          @trusted_proxies << proxy
-          @trusted_proxy_matchers << register_proxy_matcher(proxy)
-        when Array
-          proxy.each { |entry| @trusted_proxy_matchers << register_proxy_matcher(entry) }
-          @trusted_proxies.concat(proxy)
-        else
-          raise ArgumentError, 'Proxy must be a String, Regexp, or Array'
-        end
+        @trusted_proxy_config.add(proxy)
       end
 
       # Check if an IP address is from a trusted proxy
       #
-      # String entries that parse as an IP or CIDR range are matched with
-      # proper IPAddr containment (IPv4 and IPv6). Entries that are not valid
-      # IPs (e.g. a bare prefix like '172.16.') fall back to the legacy
-      # exact/prefix string match for backward compatibility. Regexp entries
-      # are matched against the raw IP string.
-      #
-      # Proxy entries are parsed once at registration (see #add_trusted_proxy)
-      # into @trusted_proxy_matchers, so this never re-parses per request.
+      # IP and CIDR entries match by IPAddr containment (IPv4 and IPv6, with
+      # IPv4-mapped addresses folded), Regexp entries match the raw string, and
+      # non-IP strings fall back to legacy prefix matching. Entries are parsed
+      # once at registration. See TrustedProxyConfig#trusted?.
       #
       # @param ip [String] IP address to check
       # @return [Boolean] true if the IP is from a trusted proxy
       def trusted_proxy?(ip)
-        return false if @trusted_proxy_matchers.empty? || ip.nil? || ip.empty?
-
-        # Fold IPv4-mapped IPv6 (::ffff:a.b.c.d) to plain IPv4 so a dual-stack
-        # peer presented in mapped form still matches an IPv4 proxy entry.
-        client = parse_ipaddr(ip)&.native
-
-        @trusted_proxy_matchers.any? do |entry, range|
-          if range
-            # Pre-parsed IP/CIDR entry -> proper containment
-            client && ip_in_range?(range, client)
-          elsif entry.is_a?(Regexp)
-            entry.match?(ip)
-          elsif entry.is_a?(String)
-            # Legacy non-IP entry (e.g. '172.16.') -> exact/prefix match
-            ip == entry || ip.start_with?(entry)
-          else
-            false
-          end
-        end
+        @trusted_proxy_config.trusted?(ip)
       end
 
       # Whether any trusted-proxy IP/CIDR/Regexp matchers are configured.
@@ -425,7 +560,7 @@ class Otto
       #
       # @return [Boolean] true when at least one trusted-proxy matcher exists
       def trusted_proxies_configured?
-        @trusted_proxy_matchers.any?
+        @trusted_proxy_config.filter?
       end
 
       # Whether ANY proxy-trust mode is configured — CIDR matchers (filter
@@ -439,7 +574,7 @@ class Otto
       # @return [Boolean] true when filter or depth mode is configured, or when
       #   the operator explicitly asserted that no proxy is trusted
       def proxy_trust_configured?
-        trusted_proxies_configured? || trusted_proxy_depth_mode? || trust_no_proxies?
+        @trusted_proxy_config.configured?
       end
 
       # Assert that NO proxy is trusted for this application.
@@ -467,16 +602,15 @@ class Otto
       #   config.trust_no_proxies!
       def trust_no_proxies!
         ensure_not_frozen!
-        raise ArgumentError, TRUST_NO_PROXIES_CONFLICT_MESSAGE if trusted_proxies_configured? || trusted_proxy_depth_mode?
 
-        @trust_no_proxies = true
+        @trusted_proxy_config.trust_none!
       end
 
       # Whether the operator explicitly asserted that no proxy is trusted.
       #
       # @return [Boolean]
       def trust_no_proxies?
-        @trust_no_proxies
+        @trusted_proxy_config.trust_none?
       end
 
       # Whether this config's request handling DEPENDS on Rack's process-global
@@ -486,7 +620,7 @@ class Otto
       #
       # @return [Boolean]
       def forwarding_family_dependent?
-        trusted_proxies_configured? || trusted_proxy_depth_mode?
+        @trusted_proxy_config.forwarding_family_dependent?
       end
 
       # Whether count-based ("trust the last N hops") proxy resolution is active.
@@ -499,7 +633,7 @@ class Otto
       #
       # @return [Boolean] true when trusted_proxy_depth is an Integer >= 1
       def trusted_proxy_depth_mode?
-        @trusted_proxy_depth.is_a?(Integer) && @trusted_proxy_depth >= 1
+        @trusted_proxy_config.depth?
       end
 
       # Set the count-based trusted-proxy depth ("trust the last N hops").
@@ -507,7 +641,8 @@ class Otto
       # Validates eagerly so a misconfiguration fails at assignment rather than
       # only at freeze (which the test harness skips): the value must be a
       # non-negative Integer or nil, and the mode is mutually exclusive with
-      # CIDR-walk (trusted_proxies). nil/0 disable depth mode.
+      # CIDR-walk (trusted_proxies), with the trust-nobody assertion, and with
+      # a trusted ip_privacy geo_header. nil/0 disable depth mode.
       #
       # @param depth [Integer, nil] number of trusted hops (nil/0 disables depth mode)
       # @raise [FrozenError] if configuration is frozen
@@ -516,14 +651,12 @@ class Otto
       def trusted_proxy_depth=(depth)
         ensure_not_frozen!
 
-        validate_trusted_proxy_depth!(depth)
-        raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if depth.to_i >= 1 && @trusted_proxies.any?
-        raise ArgumentError, TRUST_NO_PROXIES_CONFLICT_MESSAGE if depth.to_i >= 1 && @trust_no_proxies
+        @trusted_proxy_config.check_depth!(depth)
         # Depth-then-geo assignment order is caught by configure_ip_privacy;
         # this catches geo-then-depth so both orders fail eagerly.
         raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE if depth.to_i >= 1 && @ip_privacy_config&.geo_header
 
-        @trusted_proxy_depth = depth
+        @trusted_proxy_config.depth = depth
       end
 
       # Select which forwarded header family Otto and Rack read from:
@@ -556,12 +689,9 @@ class Otto
       def trusted_proxy_header=(header)
         ensure_not_frozen!
 
-        canonical_header = canonicalize_trusted_proxy_header(header)
-        cidr_conflict = canonical_header != DEFAULT_TRUSTED_PROXY_HEADER && @trusted_proxies.any?
-        raise ArgumentError, FORWARDED_HEADER_CIDR_CONFLICT_MESSAGE if cidr_conflict
-
+        canonical_header = @trusted_proxy_config.check_header!(header)
         self.class.apply_rack_forwarding_family!(self, canonical_header)
-        @trusted_proxy_header = canonical_header
+        @trusted_proxy_config.header = canonical_header
       end
 
       # Align Rack's forwarding family with this config's current value. Used by
@@ -576,7 +706,7 @@ class Otto
       def apply_default_rack_forwarding_family!
         ensure_not_frozen!
 
-        self.class.apply_rack_forwarding_family!(self, @trusted_proxy_header, claim: forwarding_family_dependent?)
+        self.class.apply_rack_forwarding_family!(self, trusted_proxy_header, claim: forwarding_family_dependent?)
       end
 
       # Commit this config's current family process-wide once it depends on
@@ -593,14 +723,14 @@ class Otto
         ensure_not_frozen!
         return unless forwarding_family_dependent?
 
-        self.class.apply_rack_forwarding_family!(self, @trusted_proxy_header)
+        self.class.apply_rack_forwarding_family!(self, trusted_proxy_header)
       end
 
       # Whether trusted_proxy_header is the X-Forwarded-For default.
       #
       # @return [Boolean]
       def default_trusted_proxy_header?
-        @trusted_proxy_header == DEFAULT_TRUSTED_PROXY_HEADER
+        @trusted_proxy_config.default_header?
       end
 
       # Validate that a request size is within acceptable limits
@@ -892,10 +1022,24 @@ class Otto
       # For the turnkey setup that also injects the receiving middleware, prefer
       # {Otto::Security::Core#enable_csp_reporting!} on the Otto instance.
       #
-      # @param uri [String, nil] path browsers POST reports to (matched against
-      #   `PATH_INFO`, e.g. `/_/csp-report`), or nil to disable reporting. A
-      #   value without a leading slash is coerced to an absolute path so it
-      #   matches the slash-prefixed `PATH_INFO` the middleware compares against.
+      # The value is a site-absolute path: the path from the site root that the
+      # browser POSTs to, including any prefix the app is mounted under. It is
+      # emitted verbatim in the `report-uri` directive, which browsers resolve
+      # against the site root, and the middleware compares it against the
+      # request's full path (`SCRIPT_NAME` + `PATH_INFO`), so one value is right
+      # for both. With Otto mounted by `map '/api' { run otto }`, configure
+      # `/api/csp-report`, not `/csp-report`. Unmounted, `SCRIPT_NAME` is empty
+      # and the full path is `PATH_INFO`.
+      #
+      # The comparison normalizes both sides with {Otto::Utils.normalize_path}
+      # (percent-decoding, one trailing slash stripped), so `/_/csp-report/`
+      # and a percent-encoded spelling of the path are also intercepted.
+      #
+      # @param uri [String, nil] site-absolute path browsers POST reports to
+      #   (e.g. `/_/csp-report`, or `/api/csp-report` when mounted at `/api`),
+      #   or nil to disable reporting. A value without a leading slash is
+      #   coerced to an absolute path, since browsers would otherwise resolve
+      #   it relative to the document URL.
       # @return [void]
       # @raise [FrozenError] if configuration is frozen
       def csp_report_uri=(uri)
@@ -920,7 +1064,8 @@ class Otto
       # The value MUST be an ABSOLUTE URL (Reporting-Endpoints does not accept a
       # bare path). Point it at the same receiver as {#csp_report_uri=}: its path
       # component should equal the report URI so {Otto::Security::CSP::ReportMiddleware}
-      # (which matches on PATH_INFO) intercepts modern reports too.
+      # (which matches the full request path, mount prefix included) intercepts
+      # modern reports too.
       #
       # When nil/empty (the default), NO `report-to` directive or
       # `Reporting-Endpoints` header is emitted and policy output is
@@ -1023,6 +1168,24 @@ class Otto
         @security_headers['x-frame-options'] = option
       end
 
+      # The Referrer-Policy value applied to Otto-generated responses.
+      #
+      # @return [String] one of {REFERRER_POLICIES}
+      def referrer_policy
+        @security_headers['referrer-policy']
+      end
+
+      # Configure the Referrer-Policy value applied to Otto responses.
+      #
+      # @param policy [String] one W3C Referrer Policy HTTP policy token
+      # @return [String] the configured policy
+      # @raise [ArgumentError] when +policy+ is not a recognized token
+      # @raise [FrozenError] if configuration is frozen
+      def referrer_policy=(policy)
+        ensure_not_frozen!
+        @security_headers['referrer-policy'] = policy
+      end
+
       # Set custom security headers
       #
       # @param headers [Hash] Hash of header name => value pairs
@@ -1049,6 +1212,7 @@ class Otto
       def deep_freeze!
         # Ensure custom_rules is initialized (should already be done in constructor)
         @rate_limiting_config[:custom_rules] ||= {}
+        validate_referrer_policy!(@security_headers['referrer-policy'])
         validate_trusted_proxy_config!
         validate_csrf_secret_config!
         super
@@ -1075,86 +1239,21 @@ class Otto
         raise FrozenError, 'Cannot modify frozen configuration' if frozen?
       end
 
-      # Validate a candidate trusted_proxy_depth value (type and range).
-      #
-      # Shared by the eager #trusted_proxy_depth= setter and the freeze-time
-      # backstop so an invalid value raises a clear ArgumentError instead of a
-      # downstream NoMethodError from #to_i coercion. nil disables depth mode.
-      #
-      # @param depth [Object] candidate value
-      # @raise [ArgumentError] if depth is non-nil and not a non-negative Integer
-      # @return [void]
-      def validate_trusted_proxy_depth!(depth)
-        return if depth.nil?
-
-        unless depth.is_a?(Integer)
-          raise ArgumentError,
-                "trusted_proxy_depth must be an Integer or nil, got #{depth.class}"
-        end
-
-        raise ArgumentError, "trusted_proxy_depth must be >= 0, got #{depth}" if depth.negative?
-      end
-
-      # Canonicalize a candidate trusted_proxy_header value: match it
-      # case-insensitively (ignoring surrounding whitespace) against the
-      # recognized set and return the canonical spelling. Liberal in the spelling
-      # it accepts (e.g. 'forwarded' => 'Forwarded') but fail-loud on a genuinely
-      # unrecognized value, so a typo is caught at config time rather than
-      # silently resolving the client IP from the wrong header.
-      #
-      # @param header [Object] candidate value
-      # @raise [ArgumentError] if header is not one of TRUSTED_PROXY_HEADERS
-      # @return [String] the canonical header value
-      def canonicalize_trusted_proxy_header(header)
-        candidate = header.to_s.strip
-        canonical = TRUSTED_PROXY_HEADERS.find { |allowed| allowed.casecmp?(candidate) }
-        return canonical if canonical
-
-        raise ArgumentError,
-              "trusted_proxy_header must be one of #{TRUSTED_PROXY_HEADERS.join(', ')}, got #{header.inspect}"
-      end
-
-      # Strictly validate a stored trusted_proxy_header value against the allowed
-      # set. The eager #trusted_proxy_header= setter already canonicalizes, so by
-      # freeze time the value is canonical; this freeze-time backstop catches a
-      # value smuggled in through a direct-ivar path that bypassed the setter,
-      # failing loud rather than silently mis-resolving the client IP at request
-      # time.
-      #
-      # @param header [Object] candidate value
-      # @raise [ArgumentError] if header is not one of TRUSTED_PROXY_HEADERS
-      # @return [void]
-      def validate_trusted_proxy_header!(header)
-        return if TRUSTED_PROXY_HEADERS.include?(header)
-
-        raise ArgumentError,
-              "trusted_proxy_header must be one of #{TRUSTED_PROXY_HEADERS.join(', ')}, got #{header.inspect}"
-      end
-
       # Validate trusted-proxy configuration coherence at freeze time.
       #
-      # The eager setters (#trusted_proxy_depth=, #add_trusted_proxy) already
-      # reject invalid types and the mutually-exclusive CIDR-walk vs depth
-      # combination at assignment. This re-checks at finalization as a backstop
-      # for a direct/ivar configuration path that bypassed the setters.
+      # TrustedProxyConfig#validate! re-checks its own rules (header value,
+      # depth type, mode exclusivity) as a backstop for state that bypassed the
+      # eager setters; the geo_header rule spans two sub-configs, so it is
+      # checked here.
       #
-      # @raise [ArgumentError] if depth is non-integer/negative, or if both
-      #   trusted_proxies and a depth >= 1 are configured
+      # @raise [ArgumentError] if any trusted-proxy rule is violated
       # @return [void]
       def validate_trusted_proxy_config!
-        validate_trusted_proxy_header!(@trusted_proxy_header)
-        validate_trusted_proxy_depth!(@trusted_proxy_depth)
-        raise ArgumentError, FORWARDED_HEADER_CIDR_CONFLICT_MESSAGE if !default_trusted_proxy_header? && @trusted_proxies.any?
-
-        raise ArgumentError, TRUST_NO_PROXIES_CONFLICT_MESSAGE if @trust_no_proxies && (@trusted_proxies.any? || @trusted_proxy_depth.to_i >= 1)
-
-        if @trusted_proxy_depth
-          raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if @trusted_proxy_depth >= 1 && @trusted_proxies.any?
+        @trusted_proxy_config.validate!
 
-          # Backstop for the direct path (ip_privacy_config.geo_header=) that
-          # bypasses both eager checks; the setters cover the common orders.
-          raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE if @trusted_proxy_depth >= 1 && @ip_privacy_config&.geo_header
-        end
+        # Backstop for the direct path (ip_privacy_config.geo_header=) that
+        # bypasses both eager checks; the setters cover the common orders.
+        raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE if trusted_proxy_depth_mode? && @ip_privacy_config&.geo_header
 
         # Last, so a config that fails the checks above never registers as an
         # owner: late-configured proxy trust (after Otto.new) commits here at
@@ -1162,67 +1261,6 @@ class Otto
         commit_rack_forwarding_family!
       end
 
-      # Parse a value into an IPAddr, returning nil for invalid / non-IP input.
-      #
-      # @param value [String] candidate IP or CIDR string
-      # @return [IPAddr, nil]
-      def parse_ipaddr(value)
-        IPAddr.new(value)
-      rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
-        nil
-      end
-
-      # Build a cached matcher tuple for a proxy entry at registration time.
-      #
-      # String entries are parsed to an IPAddr exactly once here; the result is
-      # reused for both the legacy-entry warning and per-request matching, so
-      # trusted_proxy? never re-parses. Non-IP strings and Regexp/other entries
-      # store a nil range and fall back to prefix/regexp matching.
-      #
-      # The parsed range is folded through IPAddr#native at registration, to
-      # match the fold trusted_proxy? applies to the client address. Without
-      # it a mapped-IPv6 proxy entry (::ffff:10.0.0.0/104) could never match,
-      # because ip_in_range?'s family check would reject the folded IPv4
-      # client — a proxy silently untrusted, which is what gates
-      # otto.via_trusted_proxy, secure?, and geo-header trust. #native returns
-      # self for entries that are not IPv4-mapped/compatible.
-      #
-      # @param entry [String, Regexp, Object] trusted proxy entry being added
-      # @return [Array(Object, IPAddr)] [raw_entry, parsed_range_or_nil]
-      def register_proxy_matcher(entry)
-        return [entry, nil] unless entry.is_a?(String)
-
-        range = parse_ipaddr(entry)&.native
-        warn_legacy_proxy_entry(entry) unless range
-        [entry, range]
-      end
-
-      # Warn that a string proxy entry is not a valid IP/CIDR and will use
-      # legacy string-prefix matching.
-      #
-      # @param entry [String] trusted proxy entry
-      # @return [void]
-      def warn_legacy_proxy_entry(entry)
-        Otto.logger.warn(
-          "[Otto::Security::Config] trusted proxy #{entry.inspect} is not a " \
-          'valid IP or CIDR; using legacy string-prefix matching. Prefer a ' \
-          "CIDR range (e.g. '172.16.0.0/12')."
-        )
-      end
-
-      # CIDR/host containment that is safe across address families.
-      #
-      # @param range [IPAddr] trusted proxy range or host
-      # @param client [IPAddr] client address
-      # @return [Boolean]
-      def ip_in_range?(range, client)
-        return false unless range.family == client.family
-
-        range.include?(client)
-      rescue IPAddr::InvalidAddressError
-        false
-      end
-
       def extract_existing_session_id(request)
         # Try session first
         begin
@@ -1265,10 +1303,17 @@ class Otto
         {
           'x-content-type-options' => 'nosniff',
           'x-xss-protection' => '1; mode=block',
-          'referrer-policy' => 'strict-origin-when-cross-origin',
+          'referrer-policy' => DEFAULT_REFERRER_POLICY,
         }
       end
 
+      def validate_referrer_policy!(policy)
+        return policy if policy.is_a?(String) && REFERRER_POLICIES.include?(policy)
+
+        raise ArgumentError,
+          "Invalid referrer_policy #{policy.inspect}; expected one of: #{REFERRER_POLICIES.join(', ')}"
+      end
+
       # Perform constant-time string comparison to prevent timing attacks
       #
       # This method compares two strings in constant time regardless of where
@@ -1374,13 +1419,14 @@ class Otto
         stripped.empty? ? nil : stripped
       end
 
-      # Normalize a configured report PATH: the local endpoint the receiver
-      # matches on `PATH_INFO`. Same strip/blank-to-nil handling as
-      # {#normalize_report_uri}, but a bare relative value is coerced to an
-      # absolute path — a value like `"csp-report"` would otherwise (a) never
-      # equal the slash-prefixed `PATH_INFO` the middleware compares against, and
-      # (b) be resolved by browsers relative to the document URL. An absolute URL
-      # (contains a scheme) is left untouched.
+      # Normalize a configured report PATH: the site-absolute endpoint the
+      # receiver matches against `SCRIPT_NAME` + `PATH_INFO`. Same
+      # strip/blank-to-nil handling as {#normalize_report_uri}, but a bare
+      # relative value is coerced to an absolute path — a value like
+      # `"csp-report"` would otherwise (a) never equal the slash-prefixed request
+      # path the middleware compares against, and (b) be resolved by browsers
+      # relative to the document URL. An absolute URL (contains a scheme) is left
+      # untouched.
       #
       # @param uri [String, nil]
       # @return [String, nil]