otto 2.5.0 → 2.7.0

data/lib/otto/security/csrf_enforcement_wrapper.rb

@@ -0,0 +1,68 @@
+# lib/otto/security/csrf_enforcement_wrapper.rb
+#
+# frozen_string_literal: true
+
+require_relative 'csrf_validation'
+
+class Otto
+  module Security
+    # Per-route CSRF enforcement, applied at the handler layer.
+    #
+    # CSRF enforcement lives here rather than in the global +CSRFMiddleware+
+    # because +csrf=exempt+ is a per-route option: it is only known once a
+    # route has been matched (the middleware runs *ahead* of route matching and
+    # never sees route options, so a global block could not honor exemption —
+    # issue #186). This wrapper runs after matching, alongside +RouteAuthWrapper+,
+    # where +route_definition.csrf_exempt?+ is directly available. It is composed
+    # by +HandlerFactory+ only when CSRF protection is enabled, and wraps outside
+    # +RouteAuthWrapper+ so a forged unsafe request is rejected before any
+    # authentication work runs.
+    #
+    # The global +CSRFMiddleware+ retains only token *injection* into HTML
+    # responses (a response-shaping concern that is method/content-type based,
+    # not route based, so it stays global).
+    class CSRFEnforcementWrapper
+      include CSRFValidation
+
+      attr_reader :wrapped_handler, :route_definition, :config
+
+      # @param wrapped_handler [#call] the handler to guard
+      # @param route_definition [Otto::RouteDefinition] the matched route
+      # @param config [Otto::Security::Config] security config exposing CSRF settings
+      def initialize(wrapped_handler, route_definition, config)
+        @wrapped_handler  = wrapped_handler
+        @route_definition = route_definition
+        @config           = config
+      end
+
+      # @param env [Hash] Rack environment
+      # @param extra_params [Hash] Additional parameters passed through to the handler
+      # @return [Array] Rack response tuple
+      def call(env, extra_params = {})
+        return wrapped_handler.call(env, extra_params) unless enforce?(env)
+
+        request = Otto::Request.new(env)
+        return wrapped_handler.call(env, extra_params) if valid_csrf_token?(request)
+
+        Otto.structured_log(:warn, 'CSRF validation failed',
+          Otto::LoggingHelpers.request_context(env).merge(
+            handler: route_definition.definition,
+            referrer: request.referrer
+          ))
+        csrf_error_response
+      end
+
+      private
+
+      # Whether this request must present a valid CSRF token. Only unsafe
+      # methods on a non-exempt route are enforced when protection is enabled.
+      def enforce?(env)
+        return false unless config&.csrf_enabled?
+        return false if safe_method?(env['REQUEST_METHOD'])
+        return false if route_definition.csrf_exempt?
+
+        true
+      end
+    end
+  end
+end

data/lib/otto/security/csrf_validation.rb

@@ -0,0 +1,75 @@
+# lib/otto/security/csrf_validation.rb
+#
+# frozen_string_literal: true
+
+require 'json'
+
+class Otto
+  module Security
+    # Shared CSRF token mechanics.
+    #
+    # Both the global +CSRFMiddleware+ (which injects tokens into HTML
+    # responses) and the per-route +CSRFEnforcementWrapper+ (which enforces
+    # tokens on unsafe requests, honoring +csrf=exempt+) mix this in so the
+    # two cannot drift on what counts as a safe method, where a token may be
+    # carried, or how a rejection is shaped. The including object must expose a
+    # +@config+ (an +Otto::Security::Config+).
+    module CSRFValidation
+      # HTTP methods that never mutate state and so are exempt from token
+      # validation (RFC 7231 safe methods plus TRACE).
+      SAFE_METHODS = %w[GET HEAD OPTIONS TRACE].freeze
+
+      # Static 403 body. Frozen once so a rejected request does not re-serialize
+      # the same JSON on every call.
+      CSRF_ERROR_BODY = {
+          error: 'CSRF token validation failed',
+        message: 'The request could not be authenticated. Please refresh the page and try again.',
+      }.to_json.freeze
+
+      private
+
+      def safe_method?(method)
+        SAFE_METHODS.include?(method.to_s.upcase)
+      end
+
+      def valid_csrf_token?(request)
+        token = extract_csrf_token(request)
+        # Reject nil / blank / whitespace-only tokens up front, before creating
+        # a session or running HMAC verification — obviously-malformed input
+        # should not cause session churn (#186 review).
+        return false if token.nil? || token.strip.empty?
+
+        session_id = extract_session_id(request)
+        @config.verify_csrf_token(token, session_id)
+      end
+
+      def extract_csrf_token(request)
+        # Try form parameter first
+        token = request.params[@config.csrf_token_key]
+
+        # Try header if not in params
+        token ||= request.env[@config.csrf_header_key]
+
+        # Try alternative header format
+        token ||= request.env['HTTP_X_CSRF_TOKEN'] if request.env['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest'
+
+        token
+      end
+
+      def extract_session_id(request)
+        @config.get_or_create_session_id(request)
+      end
+
+      def csrf_error_response
+        [
+          403,
+          {
+            'content-type' => 'application/json',
+            'content-length' => CSRF_ERROR_BODY.bytesize.to_s,
+          },
+          [CSRF_ERROR_BODY],
+        ]
+      end
+    end
+  end
+end

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

@@ -7,10 +7,18 @@ require_relative '../config'
 class Otto
   module Security
     module Middleware
-      # Middleware that provides Cross-Site Request Forgery (CSRF) protection
+      # Global middleware that injects CSRF tokens into HTML responses.
+      #
+      # Token *enforcement* deliberately does NOT live here. This middleware
+      # runs ahead of route matching, so it cannot see per-route options like
+      # +csrf=exempt+ (issue #186); enforcing globally would block routes an
+      # operator explicitly exempted. Enforcement is applied after matching by
+      # +Otto::Security::CSRFEnforcementWrapper+ at the handler layer, where the
+      # route definition is available. This middleware keeps only the
+      # response-shaping half — injecting a fresh token into HTML responses so
+      # forms and meta tags can carry it — which is method/content-type based
+      # and correctly stays global.
       class CSRFMiddleware
-        SAFE_METHODS = %w[GET HEAD OPTIONS TRACE].freeze
-
         def initialize(app, config = nil)
           @app    = app
           @config = config || Otto::Security::Config.new
@@ -19,60 +27,14 @@ class Otto
         def call(env)
           return @app.call(env) unless @config.csrf_enabled?
 
-          request = Otto::Request.new(env)
-
-          # Skip CSRF protection for safe methods
-          if safe_method?(request.request_method)
-            response = @app.call(env)
-            response = inject_csrf_token(request, response) if html_response?(response)
-            return response
-          end
-
-          # Validate CSRF token for unsafe methods
-          unless valid_csrf_token?(request)
-            # Log CSRF validation failure
-            Otto.structured_log(:warn, "CSRF validation failed",
-              Otto::LoggingHelpers.request_context(env).merge(
-                referrer: request.referrer
-              )
-            )
-            return csrf_error_response
-          end
-
-          @app.call(env)
+          request  = Otto::Request.new(env)
+          response = @app.call(env)
+          response = inject_csrf_token(request, response) if html_response?(response)
+          response
         end
 
         private
 
-        def safe_method?(method)
-          SAFE_METHODS.include?(method.upcase)
-        end
-
-        def valid_csrf_token?(request)
-          token = extract_csrf_token(request)
-          return false if token.nil? || token.empty?
-
-          session_id = @config.get_or_create_session_id(request)
-          @config.verify_csrf_token(token, session_id)
-        end
-
-        def extract_csrf_token(request)
-          # Try form parameter first
-          token = request.params[@config.csrf_token_key]
-
-          # Try header if not in params
-          token ||= request.env[@config.csrf_header_key]
-
-          # Try alternative header format
-          token ||= request.env['HTTP_X_CSRF_TOKEN'] if request.env['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest'
-
-          token
-        end
-
-        def extract_session_id(request)
-          @config.get_or_create_session_id(request)
-        end
-
         def inject_csrf_token(request, response)
           return response unless response.is_a?(Array) && response.length >= 3
 
@@ -138,24 +100,6 @@ class Otto
           content_type = headers.find { |k, _v| k.downcase == 'content-type' }&.last
           content_type&.include?('text/html')
         end
-
-        def csrf_error_response
-          [
-            403,
-            {
-              'content-type' => 'application/json',
-              'content-length' => csrf_error_body.bytesize.to_s,
-            },
-            [csrf_error_body],
-          ]
-        end
-
-        def csrf_error_body
-          {
-            error: 'CSRF token validation failed',
-            message: 'The request could not be authenticated. Please refresh the page and try again.',
-          }.to_json
-        end
       end
     end
   end

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,12 +92,56 @@ class Otto
 
         private
 
-        # Apply privacy settings to environment
+        # Whether IP privacy is on for this request.
         #
-        # @param env [Hash] Rack environment
-        # Apply privacy settings to environment
+        # 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
@@ -83,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
@@ -100,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
 
@@ -116,7 +204,22 @@ class Otto
               # Canonical client IP downstream reads (exempt: not masked)
               env['otto.client_ip'] = client_ip
               # Don't mask forwarded headers for private IPs
-              Otto.logger.debug "[IPPrivacyMiddleware] Private/localhost IP exempted: #{client_ip}" if Otto.debug
+              #
+              # This early return also means NONE of the privacy fingerprint
+              # values are produced for exempt IPs — no otto.privacy.fingerprint,
+              # masked_ip, hashed_ip, geo_country, or correlation_hash. That is
+              # intentional and consistent: the correlation hash targets public
+              # audit-trail traffic, so req.ip_correlation_hash is nil for
+              # 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.
+              # 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
@@ -125,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
@@ -134,6 +239,14 @@ class Otto
           env['otto.privacy.hashed_ip'] = fingerprint.hashed_ip
           env['otto.privacy.geo_country'] = fingerprint.country
 
+          # Fingerprint the FULL client IP here — while client_ip is still the
+          # real address, before REMOTE_ADDR is masked below — so it identifies
+          # the visitor, not just their /24. Uses the caller's stable secret
+          # (unlike hashed_ip's daily key), so the same IP matches across days.
+          # nil when no secret is set. The real IP is never written to env; only
+          # this hash leaves the middleware.
+          env['otto.privacy.correlation_hash'] = correlation_hash(client_ip)
+
           # CRITICAL: Replace REMOTE_ADDR and forwarded headers with masked values
           # This ensures downstream code (rate limiting, auth, logging, Rack's request.ip)
           # automatically uses the masked values without modification
@@ -158,6 +271,23 @@ class Otto
           # or env['otto.original_referer']. This prevents accidental leakage of the real values.
         end
 
+        # Fingerprint of the full client IP, keyed with the caller's stable
+        # correlation secret (not hashed_ip's daily-rotating key). The same IP
+        # and secret always produce the same value, so it can match a visitor
+        # across days — which the daily hash can't.
+        #
+        # Returns nil when no secret is configured. An empty key is never used
+        # to hash (that would let anyone reverse it); we return nil rather than
+        # raise, since "no secret" just means the feature is off.
+        #
+        # @param client_ip [String] Resolved full client IP (pre-masking)
+        # @return [String, nil] Hex HMAC-SHA256 digest, or nil when unconfigured
+        def correlation_hash(client_ip)
+          secret = @config.correlation_secret
+          return nil if secret.nil? || secret.empty?
+
+          Otto::Privacy::IPPrivacy.hash_ip(client_ip, secret)
+        end
 
         # Set or clear a Rack env header in a SPEC-compliant way.
         #
@@ -211,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
@@ -233,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
 
@@ -246,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
@@ -256,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']

data/lib/otto/security/rate_limiter.rb

@@ -80,9 +80,15 @@ class Otto
         # Log blocked requests if ActiveSupport is available
         return unless defined?(ActiveSupport::Notifications)
 
+        # Rack::Attack is mounted by the hosting app AHEAD of Otto, so this
+        # subscriber sees the raw peer regardless of where IPPrivacyMiddleware
+        # sits in Otto's own stack. Log a masked address, never req.ip: a
+        # deployment on the default :masked profile must not write raw client
+        # IPs to its logs every time a limit trips (issue #219).
         ActiveSupport::Notifications.subscribe('rack.attack') do |_name, _start, _finish, _request_id, payload|
           req = payload[:request]
-          Otto.logger.warn "[Otto] Rate limit #{payload[:match_type]} for #{req.ip}: #{payload[:matched]}"
+          ip  = Otto::LoggingHelpers.privacy_safe_ip(req.env, req.ip)
+          Otto.logger.warn "[Otto] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
         end
       end
     end

data/lib/otto/security.rb

@@ -9,6 +9,7 @@ require_relative 'security/authorization_error'
 require_relative 'security/config'
 require_relative 'security/configurator'
 require_relative 'security/middleware/csrf_middleware'
+require_relative 'security/csrf_enforcement_wrapper'
 require_relative 'security/middleware/validation_middleware'
 require_relative 'security/middleware/rate_limit_middleware'
 require_relative 'security/middleware/ip_privacy_middleware'