otto 2.6.0 → 2.7.0

data/lib/otto/security/authentication/authorization_failure.rb

@@ -26,6 +26,13 @@ class Otto
       # StrategyResult. This type covers the complementary case: a strategy that
       # owns authorization itself (including permission tiers, which Layer-1 does
       # not model) and needs to signal a 403 directly.
+      #
+      # DELIBERATELY has no `terminal` member (unlike AuthFailure): an
+      # authorization denial must not halt the strategy chain — a later
+      # strategy's success still wins (a different credential may well be
+      # permitted). When the chain DOES end in failure, a recorded denial
+      # already takes response precedence (403 over 401, even over a terminal
+      # halt), so there is nothing a terminal flag here would add.
       AuthorizationFailure = Data.define(:failure_reason, :auth_method) do
         # Authorization failures are not an authenticated request state. The
         # request never reaches the handler, so handler-facing predicates report

data/lib/otto/security/authentication/route_auth_wrapper.rb

@@ -12,9 +12,26 @@ class Otto
       # This is the main orchestrator that:
       # - Sets anonymous StrategyResult for unauthenticated routes
       # - Enforces authentication for protected routes
-      # - Supports multi-strategy with OR logic (first success wins)
+      # - Supports multi-strategy with OR logic (first authenticated success wins)
       # - Performs Layer 1 (route-level) role authorization
       #
+      # Multi-strategy chain semantics (in precedence order):
+      # - AUTHENTICATED success wins immediately; later strategies never run.
+      # - TERMINAL failure (AuthFailure with terminal: true — explicit
+      #   credentials examined and rejected) halts the chain and fails closed,
+      #   regardless of strategy order. An anonymous success from an
+      #   anonymous-capable strategy elsewhere in the chain does not rescue the
+      #   request. See AuthFailure.
+      # - ANONYMOUS success (StrategyResult with no user, e.g. from noauth) is
+      #   held as a fallback while the rest of the chain runs. It wins once the
+      #   chain completes without an authenticated success or terminal failure,
+      #   so credential-less requests still fall through to noauth. When more
+      #   than one strategy produces an anonymous success, the first declared
+      #   is the fallback; later ones are deliberately ignored.
+      # - Plain failures are recorded and the next strategy is consulted
+      #   (OR logic). If everything fails, an AuthorizationFailure (valid
+      #   credential, denied) yields 403; otherwise 401.
+      #
       # @example Basic usage
       #   wrapper = RouteAuthWrapper.new(handler, route_def, auth_config)
       #   response = wrapper.call(env)
@@ -53,7 +70,8 @@ class Otto
           validation_error = validate_strategies(auth_requirements, env)
           return validation_error if validation_error
 
-          # Try each strategy in order (first success wins)
+          # Try each strategy in order (first authenticated success wins;
+          # anonymous success is a fallback; terminal failure halts the chain)
           authenticate_and_authorize(env, extra_params, auth_requirements)
         end
 
@@ -83,8 +101,15 @@ class Otto
         end
 
         # Main authentication and authorization flow
+        #
+        # chain tracks two views of the run: :executed is every strategy that
+        # ran (including one whose anonymous success is merely held as the
+        # fallback), :failed only those that returned a failure result. Failure
+        # metadata reports :executed as attempted_strategies so a terminal halt
+        # after a deferred anonymous success doesn't under-report what ran.
         def authenticate_and_authorize(env, extra_params, auth_requirements)
-          failed_strategies = []
+          chain = { failed: [], executed: [] }
+          anonymous_fallback = nil
           total_start_time = Otto::Utils.now_in_μs
 
           auth_requirements.each do |requirement|
@@ -96,39 +121,90 @@ class Otto
             start_time = Otto::Utils.now_in_μs
             result = strategy.authenticate(env, requirement)
             duration = Otto::Utils.now_in_μs - start_time
+            chain[:executed] << strategy_name
 
             # Inject strategy_name into result
             result = result.with(strategy_name: strategy_name) if result.is_a?(StrategyResult)
 
-            # Handle authentication success
-            if result.is_a?(StrategyResult) && (result.authenticated? || result.anonymous?)
+            # Handle authenticated success - wins immediately
+            if authenticated_result?(result)
               return handle_auth_success(env, extra_params, result, strategy_name,
-                                        duration, total_start_time, failed_strategies)
+                                        duration, total_start_time, chain)
+            end
+
+            # An anonymous success (e.g. noauth) is held as a fallback rather
+            # than winning outright, so a credentialed strategy elsewhere in
+            # the chain still gets to examine explicitly presented credentials
+            # and reject them terminally, regardless of declaration order.
+            # When the chain completes without a terminal failure, the
+            # fallback wins (see below), preserving OR fallthrough for
+            # credential-less requests.
+            if anonymous_result?(result)
+              anonymous_fallback ||= { result: result, strategy_name: strategy_name, duration: duration }
+              next
             end
 
             # Handle a failure (authentication OR authorization) - record it and
             # continue to the next strategy (OR logic; a later success still wins).
             # AuthorizationFailure (valid credential, denied) is tagged so the
             # final response is 403 instead of 401. See handle_all_strategies_failed.
-            next unless result.is_a?(AuthFailure) || result.is_a?(AuthorizationFailure)
+            # Anything else is a strategy-author bug (wrong return type): the
+            # chain skips it as if it failed without a reason, but leaves a
+            # trace — a silent drop makes those bugs hard to debug.
+            unless result.is_a?(AuthFailure) || result.is_a?(AuthorizationFailure)
+              log_unexpected_result(env, strategy_name, result)
+              next
+            end
 
             log_strategy_failure(env, strategy_name, result, duration, auth_requirements, requirement)
-            failed_strategies << {
-              strategy: strategy_name,
-              reason: result.failure_reason,
-              authorization: result.is_a?(AuthorizationFailure),
-            }
+
+            # A terminal failure means explicit credentials were examined and
+            # rejected: fail the whole chain closed (401) instead of letting an
+            # anonymous-capable strategy accept the request as anonymous.
+            if record_failure(chain[:failed], strategy_name, result)
+              return handle_all_strategies_failed(env, auth_requirements, chain,
+                                                  total_start_time, terminal: true)
+            end
+          end
+
+          # Chain completed without authenticated success or terminal failure:
+          # a held anonymous success wins (OR fallthrough to noauth et al.)
+          if anonymous_fallback
+            return handle_auth_success(env, extra_params, anonymous_fallback[:result],
+                                       anonymous_fallback[:strategy_name],
+                                       anonymous_fallback[:duration],
+                                       total_start_time, chain)
           end
 
           # All strategies failed
-          handle_all_strategies_failed(env, auth_requirements, failed_strategies, total_start_time)
+          handle_all_strategies_failed(env, auth_requirements, chain, total_start_time)
+        end
+
+        def authenticated_result?(result)
+          result.is_a?(StrategyResult) && result.authenticated?
+        end
+
+        def anonymous_result?(result)
+          result.is_a?(StrategyResult) && result.anonymous?
+        end
+
+        # Append the failure to the running list; returns true when it was terminal
+        def record_failure(failed_strategies, strategy_name, result)
+          terminal = result.is_a?(AuthFailure) && result.terminal?
+          failed_strategies << {
+            strategy: strategy_name,
+            reason: result.failure_reason,
+            authorization: result.is_a?(AuthorizationFailure),
+            terminal: terminal,
+          }
+          terminal
         end
 
         # Handle successful authentication
-        def handle_auth_success(env, extra_params, result, strategy_name, duration, total_start_time, failed_strategies)
+        def handle_auth_success(env, extra_params, result, strategy_name, duration, total_start_time, chain)
           total_duration = Otto::Utils.now_in_μs - total_start_time
 
-          log_auth_success(env, strategy_name, result, duration, total_duration, failed_strategies)
+          log_auth_success(env, strategy_name, result, duration, total_duration, chain)
 
           # Set environment variables for controllers/logic
           env['otto.strategy_result'] = result
@@ -148,14 +224,19 @@ class Otto
           wrapped_handler.call(env, extra_params)
         end
 
-        # Handle case when all authentication strategies fail
-        def handle_all_strategies_failed(env, auth_requirements, failed_strategies, total_start_time)
+        # Handle case when authentication fails for the whole chain — either
+        # every strategy failed, or a terminal failure halted the chain early
+        # (terminal: true; remaining strategies were deliberately not consulted).
+        # chain is the { failed:, executed: } state built by
+        # authenticate_and_authorize.
+        def handle_all_strategies_failed(env, auth_requirements, chain, total_start_time, terminal: false)
+          failed_strategies = chain[:failed]
           total_duration = Otto::Utils.now_in_μs - total_start_time
 
-          log_all_failed(env, failed_strategies, total_duration)
+          log_all_failed(env, chain, total_duration, terminal: terminal)
 
           # Create anonymous result with failure info
-          metadata = build_failure_metadata(env, failed_strategies)
+          metadata = build_failure_metadata(env, chain, terminal: terminal)
           failure_strategy_name = determine_failure_strategy_name(auth_requirements, failed_strategies)
 
           env['otto.strategy_result'] = StrategyResult.anonymous(
@@ -167,14 +248,18 @@ class Otto
           # authenticated the subject but denied authorization (wrong role/missing
           # permission), respond 403 Forbidden rather than 401 — the subject IS
           # authenticated, they simply lack access. A bare 401 would (incorrectly)
-          # tell a logged-in client to re-authenticate.
+          # tell a logged-in client to re-authenticate. This precedence also holds
+          # on a terminal halt: the denial's 403 is the more specific outcome.
           authz_denial = failed_strategies.find { |f| f[:authorization] }
           return @response_builder.forbidden(env, authz_denial[:reason]) if authz_denial
 
+          # On a terminal halt the terminal failure is necessarily the last one
+          # recorded, so its reason is what gets rendered.
           last_failure = if failed_strategies.any?
                            AuthFailure.new(
                              failure_reason: failed_strategies.last[:reason],
-                             auth_method: failed_strategies.last[:strategy]
+                             auth_method: failed_strategies.last[:strategy],
+                             terminal: failed_strategies.last[:terminal] || false
                            )
                          else
                            AuthFailure.new(
@@ -194,13 +279,21 @@ class Otto
         end
 
         # Build metadata for failed authentication
-        def build_failure_metadata(env, failed_strategies)
+        #
+        # attempted_strategies lists every strategy that EXECUTED (including
+        # one whose anonymous success was held as the fallback and then
+        # overruled by a terminal failure); failure_reasons lists only the
+        # reasons of strategies that FAILED, in failure order. The two arrays
+        # are therefore not index-aligned.
+        def build_failure_metadata(env, chain, terminal: false)
+          summary = terminal ? 'Authentication halted by terminal failure' : 'All authentication strategies failed'
           metadata = {
                           ip: env['otto.client_ip'] || env['REMOTE_ADDR'],
-                auth_failure: 'All authentication strategies failed',
-            attempted_strategies: failed_strategies.map { |f| f[:strategy] },
-                 failure_reasons: failed_strategies.map { |f| f[:reason] },
+                auth_failure: summary,
+            attempted_strategies: chain[:executed],
+                 failure_reasons: chain[:failed].map { |f| f[:reason] },
           }
+          metadata[:terminal_failure] = true if terminal
           metadata[:country] = env['otto.privacy.geo_country'] if env['otto.privacy.geo_country']
           metadata
         end
@@ -228,7 +321,7 @@ class Otto
             ))
         end
 
-        def log_auth_success(env, strategy_name, result, duration, total_duration, failed_strategies)
+        def log_auth_success(env, strategy_name, result, duration, total_duration, chain)
           Otto.structured_log(:info, 'Auth strategy result',
             Otto::LoggingHelpers.request_context(env).merge(
               strategy: strategy_name,
@@ -236,7 +329,11 @@ class Otto
               user_id: result.user_id,
               duration: duration,
               total_duration: total_duration,
-              strategies_attempted: failed_strategies.size + 1
+              # Every strategy that ran, including the winner (already in
+              # chain[:executed] by the time a success is handled) and any
+              # held anonymous fallback — not just the failures. Same array
+              # shape as the failure log so consumers see one type.
+              strategies_attempted: chain[:executed]
             ))
         end
 
@@ -251,12 +348,22 @@ class Otto
             ))
         end
 
-        def log_all_failed(env, failed_strategies, total_duration)
-          Otto.structured_log(:warn, 'All auth strategies failed',
+        def log_unexpected_result(env, strategy_name, result)
+          Otto.structured_log(:warn, 'Auth strategy returned unexpected type',
+            Otto::LoggingHelpers.request_context(env).merge(
+              strategy: strategy_name,
+              result_class: result.class.name
+            ))
+        end
+
+        def log_all_failed(env, chain, total_duration, terminal: false)
+          message = terminal ? 'Auth chain halted by terminal failure' : 'All auth strategies failed'
+          Otto.structured_log(:warn, message,
             Otto::LoggingHelpers.request_context(env).merge(
-              strategies_attempted: failed_strategies.map { |f| f[:strategy] },
+              strategies_attempted: chain[:executed],
               total_duration: total_duration,
-              failure_count: failed_strategies.size
+              failure_count: chain[:failed].size,
+              terminal: terminal
             ))
         end
       end

data/lib/otto/security/config.rb

@@ -217,6 +217,20 @@ class Otto
         end
       end
 
+      # Whether any trusted-proxy IP/CIDR/Regexp matchers are configured.
+      #
+      # This mirrors {#trusted_proxy?}, which consults the same matcher list, so
+      # the two answers stay consistent: a request can only be "via a trusted
+      # proxy" when matchers exist. It deliberately EXCLUDES count-based depth
+      # mode — depth resolves the client IP but never confers proxy identity
+      # trust (the same decoupling {Otto::Request#forwarded_by_trusted_proxy?}
+      # applies to X-Forwarded-Proto). Used to gate geo-header trust.
+      #
+      # @return [Boolean] true when at least one trusted-proxy matcher exists
+      def trusted_proxies_configured?
+        @trusted_proxy_matchers.any?
+      end
+
       # Whether count-based ("trust the last N hops") proxy resolution is active.
       #
       # When true, Otto::Utils.resolve_client_ip ignores trusted-proxy CIDRs and
@@ -768,12 +782,20 @@ class Otto
       # 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)
+        range = parse_ipaddr(entry)&.native
         warn_legacy_proxy_entry(entry) unless range
         [entry, range]
       end

data/lib/otto/security/core.rb

@@ -181,7 +181,10 @@ class Otto
       # The middleware is pinned to run OUTERMOST (ahead of CSRF and every other
       # middleware), so it short-circuits report POSTs before CSRF validation —
       # browsers can post reports without a CSRF token. This holds regardless of
-      # the order in which you enable security features.
+      # the order in which you enable security features. The one thing that runs
+      # ahead of it is IPPrivacyMiddleware, pinned to the outer :entrypoint tier
+      # so nothing observes a raw client IP; being a pass-through, it cannot
+      # affect the short-circuit.
       #
       # SECURITY / DoS: running outermost also means the receiver sits ahead of
       # rate limiting (rate limiting is inner middleware). This is intentional —

data/lib/otto/security/csp/report_middleware.rb

@@ -27,7 +27,9 @@ class Otto
       #   with no CSRF token: the report never reaches the CSRF middleware.
       #   {Otto::Security::Core#enable_csp_reporting!} pins this middleware
       #   OUTERMOST (via the :outermost stack position), so the guarantee holds
-      #   regardless of the order security features are enabled in. The flip side
+      #   regardless of the order security features are enabled in. Only
+      #   IPPrivacyMiddleware (pinned to the outer :entrypoint tier) runs ahead
+      #   of it, and it is a pass-through. The flip side
       #   is that reports also bypass rate limiting — see the DoS note on
       #   {Otto::Security::Core#enable_csp_reporting!}; keep callbacks cheap.
       # - Enforces a hard {MAX_BODY_BYTES} body cap. Oversized bodies are

data/lib/otto/security/middleware/ip_privacy_middleware.rb

@@ -10,8 +10,18 @@ class Otto
       # Automatically masks IP addresses for privacy by default. Original IPs
       # are never stored unless privacy is explicitly disabled.
       #
-      # This middleware runs FIRST in the stack to ensure all downstream
-      # middleware and application code receives masked IPs by default.
+      # Otto pins this middleware to the OUTERMOST position of the stack (the
+      # :entrypoint tier — see Otto::Core::MiddlewareStack#add_with_position),
+      # so it is the first middleware to touch a request and every other
+      # middleware, plus the application, reads masked IPs by default. Before
+      # #219 it was registered `position: :first`, which is first-in-array and
+      # therefore INNERMOST: only the wrapped app saw masked values while every
+      # other middleware still saw the raw peer address.
+      #
+      # Because it now runs ahead of everything, facts about the ORIGINAL peer
+      # that downstream code can no longer derive from the (masked) REMOTE_ADDR
+      # are recorded first, as leak-free booleans — never as addresses:
+      # env['otto.via_trusted_proxy'] and env['otto.peer_loopback'].
       #
       # @example Default behavior (privacy enabled)
       #   # env['REMOTE_ADDR'] is masked to 192.168.1.0
@@ -32,9 +42,6 @@ class Otto
           @app = app
           @security_config = security_config
           @config = security_config&.ip_privacy_config || Otto::Privacy::Config.new
-
-          # Privacy is enabled by default unless explicitly disabled
-          @privacy_enabled = @config.enabled?
         end
 
         # Process request with IP privacy
@@ -46,7 +53,10 @@ class Otto
           # canonical client IP for this request, do not re-resolve or re-mask.
           # This makes stacking two instances (e.g. an app-level mount plus
           # Otto's built-in router mount) order-safe instead of double-masking.
-          return @app.call(env) if env.key?('otto.client_ip')
+          if env.key?('otto.client_ip')
+            ensure_ip_match_present(env)
+            return @app.call(env)
+          end
 
           # Record the connecting peer's trust decision BEFORE any masking, so
           # secure? can authorize X-Forwarded-Proto canonically even after
@@ -58,7 +68,20 @@ class Otto
           # downstream OneTimeSecret behavior).
           env['otto.via_trusted_proxy'] = trusted_proxy?(env['REMOTE_ADDR'])
 
-          if @privacy_enabled
+          # Same rationale, for loopback: this middleware runs outermost, so a
+          # downstream middleware that must authenticate a DIRECT LOCAL CALL
+          # (Otto::CaddyTLS::LocalhostGuard) can no longer read the true socket
+          # peer from REMOTE_ADDR. Record the verdict here, on the untouched
+          # peer, as a boolean — the address itself is never exposed.
+          #
+          # Deliberately the raw peer, NOT the resolved client IP: resolution
+          # honors forwarded headers from trusted proxies, and a co-located
+          # reverse proxy on loopback is itself a natural trusted proxy, so
+          # resolving first would let `X-Forwarded-For: 127.0.0.1` promote a
+          # remote caller to "localhost".
+          env['otto.peer_loopback'] = Otto::Utils.loopback_address?(env['REMOTE_ADDR'])
+
+          if privacy_enabled?
             apply_privacy(env)
           else
             apply_no_privacy(env)
@@ -69,6 +92,56 @@ class Otto
 
         private
 
+        # Whether IP privacy is on for this request.
+        #
+        # Read live from the config rather than cached at construction. Otto
+        # builds its middleware stack at the end of Otto.new, but
+        # configure_ip_privacy stays legal until the first request (the
+        # configuration freeze is deferred — see Otto#initialize). A flag
+        # captured in #initialize would therefore ignore a post-construction
+        # `configure_ip_privacy(profile: :audit)` and keep masking under a
+        # profile the operator explicitly turned off. One predicate call per
+        # request buys that correctness.
+        #
+        # @return [Boolean]
+        def privacy_enabled?
+          @config.enabled?
+        end
+
+        # Guarantee env['otto.ip_match'] exists on the idempotent-return path.
+        #
+        # Every path in this middleware that sets otto.client_ip installs the
+        # capability first, so a second IPPrivacyMiddleware pass that reaches
+        # this guard finds both keys and leaves the precise closure in place.
+        # (The no-resolvable-IP path installs the capability but never sets
+        # otto.client_ip, so a second pass re-runs apply_privacy and reinstalls
+        # an equivalent fail-closed closure — idempotent, since there is nothing
+        # to double-mask.) The gap is out-of-contract writes: otto.client_ip is
+        # documented as "Set by: IPPrivacyMiddleware" (see Otto::EnvKeys), but
+        # an app or test harness that sets it directly trips the idempotency
+        # guard and leaves the advertised capability nil — downstream policy
+        # code then raises NoMethodError on nil.
+        #
+        # The repair installs a fail-closed check, NOT one derived from
+        # env['otto.client_ip']. That value may already be masked, and matching
+        # a masked address against a narrow CIDR produces false ALLOWs (masked
+        # 192.168.1.0 falls inside 192.168.1.0/28 when the real client was
+        # .200). A universal deny is the safe verdict; the warning below is
+        # what makes it diagnosable instead of a silent lockout.
+        #
+        # @param env [Hash] Rack environment
+        def ensure_ip_match_present(env)
+          return if env.key?('otto.ip_match')
+
+          Otto.logger.warn(
+            '[IPPrivacyMiddleware] otto.client_ip was set outside this ' \
+            'middleware, so otto.ip_match could not be built from the ' \
+            'unmasked address; installing a fail-closed check (every CIDR ' \
+            'test returns false). Let IPPrivacyMiddleware resolve the client IP.'
+          )
+          env['otto.ip_match'] = ->(_cidrs) { false }
+        end
+
         # Apply privacy settings to environment
         #
         # @param env [Hash] Rack environment
@@ -77,7 +150,19 @@ class Otto
           # canonical resolution step; masking below operates on this value.
           client_ip = resolve_client_ip(env)
 
-          Otto.logger.debug "[IPPrivacyMiddleware] Resolved client IP: #{client_ip}" if Otto.debug
+          # Install the verdict-only precision capability while client_ip is
+          # still the real address — after this method returns, the raw
+          # material is gone (REMOTE_ADDR and forwarded headers rewritten).
+          install_ip_match(env, client_ip)
+
+          # There is deliberately no debug line for the resolution itself. It
+          # used to interpolate client_ip, which handed back through the log
+          # exactly what these profiles withhold from env — and logs travel
+          # further than a process does. Stripped of the address it carried no
+          # information worth a line: this method only runs on the masking
+          # profiles (:masked / :anonymous), and every branch below already logs
+          # its own outcome. To trace resolution here, log a derived value (the
+          # masked IP, the family, the trusted-proxy verdict) — never the address.
 
           # No resolvable client IP (REMOTE_ADDR absent or blank, and no trusted
           # forwarded value). There is nothing to mask, and masking would derive
@@ -94,9 +179,18 @@ class Otto
           # original sensitive data. So still scrub those headers before
           # bailing — a request with no resolvable IP must not leak an
           # un-anonymized User-Agent or Referer.
+          #
+          # Likewise, forwarded headers may still carry raw client addresses
+          # (e.g. an X-Forwarded-For / Forwarded value with no usable REMOTE_ADDR
+          # to anchor resolution). There is no masked IP to rewrite them to, so
+          # DELETE them — leaving them would leak the raw address downstream.
           if client_ip.to_s.empty?
             Otto.logger.debug '[IPPrivacyMiddleware] No resolvable client IP; skipping IP masking' if Otto.debug
-            scrub_sensitive_headers(env, Otto::Privacy::RedactedFingerprint.new(env, @config))
+            scrub_sensitive_headers(
+              env,
+              Otto::Privacy::RedactedFingerprint.new(env, @config, geo_headers_trusted: geo_headers_trusted?(env))
+            )
+            scrub_forwarded_headers(env)
             return
           end
 
@@ -119,7 +213,13 @@ class Otto
               # localhost / RFC-1918 addresses (the default dev path) even when a
               # correlation_secret is configured. Set mask_private_ips to treat
               # private IPs as public and run them through the full path below.
-              Otto.logger.debug "[IPPrivacyMiddleware] Private/localhost IP exempted: #{client_ip}" if Otto.debug
+              # No address interpolated (see the resolution note at the top of
+              # this method). Exempt IPs skip fingerprinting entirely, so there
+              # is no derived value to log either — the line records only that
+              # the exemption fired. The address is not lost to debugging: this
+              # path leaves REMOTE_ADDR unmasked and sets otto.client_ip to the
+              # same value, so downstream request logs still carry it.
+              Otto.logger.debug '[IPPrivacyMiddleware] Private/localhost IP exempted from masking' if Otto.debug
               return
             end
           end
@@ -128,7 +228,9 @@ class Otto
           # We temporarily set REMOTE_ADDR to the client IP for fingerprint creation
           original_remote_addr = env['REMOTE_ADDR']
           env['REMOTE_ADDR'] = client_ip
-          fingerprint = Otto::Privacy::RedactedFingerprint.new(env, @config)
+          fingerprint = Otto::Privacy::RedactedFingerprint.new(
+            env, @config, geo_headers_trusted: geo_headers_trusted?(env)
+          )
           env['REMOTE_ADDR'] = original_remote_addr
 
           # Set privacy-safe values in environment
@@ -239,6 +341,51 @@ class Otto
           Otto::Utils.resolve_client_ip(env, @security_config)
         end
 
+        # Install env['otto.ip_match']: a verdict-only CIDR membership check
+        # over the resolved, UNMASKED client IP.
+        #
+        # This is the precision axis of the privacy design, decoupled from the
+        # observability axis (the privacy profile): policy code downstream —
+        # e.g. a per-tenant IP allowlist — can ask "is this client inside
+        # these ranges?" at full /32-/128 precision under ANY profile,
+        # including full masking. The unmasked address itself never lands in
+        # env; only this closure does, and a closure serializes to nothing
+        # useful, so env dumps, loggers, and error reporters that walk env
+        # cannot leak the IP accidentally.
+        #
+        # Threat model: the capability is a membership oracle, so deliberate
+        # in-process code could reconstruct the address via adaptive queries —
+        # but in-process code is already trusted (it could monkeypatch this
+        # middleware). The invariant defended is accidental persistence and
+        # serialization, and a Proc preserves it where a raw string could not.
+        #
+        # The closure is installed on every path that resolves an IP (masked,
+        # private-exempt, and privacy-disabled). When the request has no
+        # resolvable client IP the check returns false — fail-closed for
+        # allowlist callers. Invalid CIDR entries raise (configuration error);
+        # see Otto::Utils.ip_in_cidrs?.
+        #
+        # @param env [Hash] Rack environment
+        # @param client_ip [String, nil] resolved, unmasked client IP
+        def install_ip_match(env, client_ip)
+          env['otto.ip_match'] = ->(cidrs) { Otto::Utils.ip_in_cidrs?(client_ip, cidrs) }
+        end
+
+        # Delete forwarded IP headers outright.
+        #
+        # Used on the no-resolvable-client-IP path, where there is no masked IP
+        # to rewrite these to. Leaving them would leak a raw client address (in
+        # X-Forwarded-For / X-Real-IP / X-Client-IP / RFC 7239 Forwarded)
+        # downstream. Deleting is Rack-SPEC-safe: an absent CGI key is valid.
+        #
+        # @param env [Hash] Rack environment
+        def scrub_forwarded_headers(env)
+          env.delete('HTTP_X_FORWARDED_FOR')
+          env.delete('HTTP_X_REAL_IP')
+          env.delete('HTTP_X_CLIENT_IP')
+          env.delete('HTTP_FORWARDED')
+        end
+
         # Mask X-Forwarded-For and related proxy headers
         #
         # Replaces forwarded IP headers with the masked IP to prevent leakage
@@ -261,6 +408,15 @@ class Otto
           env['HTTP_X_REAL_IP'] = masked_ip if env['HTTP_X_REAL_IP']
           env['HTTP_X_CLIENT_IP'] = masked_ip if env['HTTP_X_CLIENT_IP']
 
+          # RFC 7239 Forwarded carries the client IP in a structured `for=`
+          # token, and Otto reads it as an authoritative client-IP source in
+          # count-based depth mode (trusted_proxy_header 'Forwarded'/'Both').
+          # Left as-is it would leak the real IP to downstream code. Redact only
+          # the `for=` value(s) so proto=/host=/by= metadata survives.
+          if env['HTTP_FORWARDED']
+            env['HTTP_FORWARDED'] = Otto::Privacy::IPPrivacy.mask_forwarded_for(env['HTTP_FORWARDED'], masked_ip)
+          end
+
           Otto.logger.debug "[IPPrivacyMiddleware] Masked forwarded headers" if Otto.debug
         end
 
@@ -274,6 +430,34 @@ class Otto
           @security_config.trusted_proxy?(ip)
         end
 
+        # Whether request geo headers may be trusted for this request.
+        #
+        # Geo headers (CF-IPCountry and friends, plus any app-configured header)
+        # are client-spoofable unless the request actually arrived through the
+        # CDN/proxy that sets them. So Otto trusts them ONLY when it can verify
+        # that origin: a request that arrived via a configured CIDR trusted
+        # proxy (identity checked against REMOTE_ADDR).
+        #
+        # Every other case is untrusted, and geo falls to the local database /
+        # custom resolver:
+        # - Count-based depth mode: the hop setting the header can't be verified
+        #   as a geo-CDN (depth proxies are often plain load balancers), and
+        #   depth configures no CIDR matchers, so trusted_proxies_configured? is
+        #   false here too.
+        # - No trusted-proxy configuration: the header is client-supplied and
+        #   unverifiable. Deployments behind a real CDN should configure
+        #   trusted_proxies (or a local database) to get header-based geo.
+        #
+        # @param env [Hash] Rack environment
+        # @return [Boolean]
+        def geo_headers_trusted?(env)
+          sc = @security_config
+          return false unless sc.respond_to?(:trusted_proxies_configured?)
+          return false unless sc.trusted_proxies_configured?
+
+          env['otto.via_trusted_proxy'] == true
+        end
+
         # Apply no-privacy settings (privacy explicitly disabled)
         #
         # When privacy is disabled, original IP is available for
@@ -284,7 +468,12 @@ class Otto
           # Resolve the canonical client IP once, even with privacy disabled, so
           # downstream code can read env['otto.client_ip'] instead of re-deriving
           # it from REMOTE_ADDR / forwarded headers.
-          env['otto.client_ip'] = resolve_client_ip(env)
+          client_ip = resolve_client_ip(env)
+          env['otto.client_ip'] = client_ip
+
+          # Same precision capability as the privacy-enabled paths, so policy
+          # code has one interface regardless of profile.
+          install_ip_match(env, client_ip)
 
           # Store original values for explicit access when privacy is disabled
           if env['REMOTE_ADDR']