otto 2.6.0 → 2.7.0

data/lib/otto/caddy_tls/localhost_guard.rb

@@ -2,8 +2,6 @@
 #
 # frozen_string_literal: true
 
-require 'ipaddr'
-
 require_relative '../utils'
 
 class Otto
@@ -22,11 +20,15 @@ class Otto
     #
     # == Security: authenticate the RAW peer, not the resolved client IP
     #
-    # The guard reads the ORIGINAL +env['REMOTE_ADDR']+ — the TCP socket peer —
-    # and MUST run before +IPPrivacyMiddleware+ rewrites +REMOTE_ADDR+ from
-    # forwarded headers. Installed via +Otto#use+ (appended, hence outermost in
-    # the reduce-built stack) it always executes ahead of +IPPrivacyMiddleware+
-    # (which is pinned innermost), so it inspects the true socket peer.
+    # The guard authenticates the TCP socket peer as it arrived, before
+    # +IPPrivacyMiddleware+ rewrites +REMOTE_ADDR+ from forwarded headers.
+    # +IPPrivacyMiddleware+ is pinned OUTERMOST (issue #219), so it runs ahead
+    # of this guard and records its verdict on the untouched peer as
+    # +env['otto.peer_loopback']+ — a boolean, never an address. The guard reads
+    # that record when present and falls back to evaluating +REMOTE_ADDR+
+    # itself when it is not (no Otto privacy middleware in the stack, or the
+    # guard mounted outside Otto). Either way the decision is made on the raw
+    # peer.
     #
     # Reading Otto's resolved +otto.client_ip+ (or the rewritten +REMOTE_ADDR+)
     # would be exploitable: a co-located reverse proxy on loopback is itself a
@@ -92,11 +94,28 @@ class Otto
       # @param env [Hash] Rack environment
       # @return [Boolean]
       def direct_local_call?(env)
-        loopback_peer?(env['REMOTE_ADDR']) && !relayed?(env)
+        loopback_peer?(env) && !relayed?(env)
       end
 
       # Whether any forwarding header is present (request came via a proxy).
       #
+      # Unlike the peer check, this reads header STATE, which IPPrivacyMiddleware
+      # has already touched by the time the guard runs. That is safe in both of
+      # its paths, but only for a reason worth writing down:
+      #
+      # - Masking REWRITES a forwarded header to the masked IP rather than
+      #   removing it, so a relayed request still looks relayed. Correct — it was.
+      # - The no-resolvable-client-IP path DELETES them, which would make a
+      #   relayed request look direct. That path is reached only when REMOTE_ADDR
+      #   is absent or blank, which forces otto.peer_loopback to false, so
+      #   #direct_local_call? denies on the peer check before this one matters.
+      #
+      # So header deletion upstream cannot turn a deny into an allow — but that
+      # rests on the peer check failing closed for a blank address. Anything that
+      # makes an unresolvable-IP request keep a loopback peer verdict would need
+      # to record the relay state pre-scrub too (an otto.peer_relayed sibling to
+      # otto.peer_loopback).
+      #
       # @param env [Hash] Rack environment
       # @return [Boolean]
       def relayed?(env)
@@ -125,28 +144,27 @@ class Otto
         Otto::Utils.normalize_path(path)
       end
 
-      # Whether the connecting peer is a loopback address. Fails closed: a
-      # blank or otherwise unparseable value is treated as non-loopback
-      # (denied) rather than raising on the hot path.
+      # Whether the connecting peer is a loopback address.
       #
-      # +.native+ folds IPv4-mapped IPv6 (+::ffff:127.0.0.1+, which dual-stack
-      # servers commonly present) so it is correctly recognized as loopback;
-      # plain +IPAddr#loopback?+ returns false for the mapped form.
+      # Prefers +env['otto.peer_loopback']+ — IPPrivacyMiddleware's verdict on
+      # the ORIGINAL peer, recorded before it rewrites +REMOTE_ADDR+ (it runs
+      # outermost, so by the time this guard sees the env the address may
+      # already be the resolved-and-masked client IP). Only a real Boolean is
+      # honored; anything else falls through to evaluating +REMOTE_ADDR+, which
+      # is the correct source when no privacy middleware ran.
       #
-      # A conforming Rack server sets +REMOTE_ADDR+ to a bare IP (the peer's
-      # port lives in +REMOTE_PORT+). We deliberately do NOT strip a +:port+
-      # suffix here: an unexpected format is a signal something upstream is
-      # non-standard, so denying (fail-closed) is safer than coercing it.
+      # Both paths share +Otto::Utils.loopback_address?+, so the recorded
+      # verdict and the fallback cannot disagree. It fails closed: a blank,
+      # ported, or unparseable value is treated as non-loopback (denied) rather
+      # than raising on the hot path.
       #
-      # @param remote_addr [String, nil] the raw socket peer address
+      # @param env [Hash] Rack environment
       # @return [Boolean]
-      def loopback_peer?(remote_addr)
-        addr = remote_addr.to_s.strip
-        return false if addr.empty?
+      def loopback_peer?(env)
+        recorded = env['otto.peer_loopback']
+        return recorded if [true, false].include?(recorded)
 
-        IPAddr.new(addr).native.loopback?
-      rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
-        false
+        Otto::Utils.loopback_address?(env['REMOTE_ADDR'])
       end
 
       # @return [Array] 401 Rack response tuple

data/lib/otto/core/middleware_stack.rb

@@ -13,12 +13,24 @@ class Otto
       include Enumerable
       include Otto::Core::Freezable
 
+      # Pin tiers honored by #ordered_stack, outward-ascending. #wrap folds the
+      # stack with reduce, so a LATER array position is a FURTHER OUT wrapper;
+      # sorting by tier therefore sorts by how early the middleware sees the
+      # request. Unpinned entries are tier 0 and keep their insertion order.
+      #
+      # A tier is recorded on the ENTRY (as entry[:pin_tier]), not on the
+      # middleware class. Entries are identified by (class, args, options), so
+      # the same class can legitimately be registered more than once with
+      # different configuration; a class-wide pin would drag those other
+      # registrations into the pinned tier along with it.
+      PIN_TIERS = {
+         outermost: 1,
+        entrypoint: 2,
+      }.freeze
+
       def initialize
         @stack = []
         @middleware_set = Set.new
-        # Classes pinned to run OUTERMOST regardless of insertion order (see
-        # the :outermost position in #add_with_position and #ordered_stack).
-        @outermost = Set.new
         @on_change_callback = nil
       end
 
@@ -52,8 +64,15 @@ class Otto
 
       # Add middleware with position hint for optimal ordering
       #
-      # Positions:
-      # - :first     — innermost (runs last, closest to the app)
+      # Positions name a place in the ARRAY; #wrap folds the array with reduce,
+      # so array order is the REVERSE of execution order — the last entry is the
+      # outermost wrapper and therefore the first to see a request.
+      #
+      # - :first/:innermost — innermost: the LAST middleware to see the request,
+      #                closest to the app. Note the trap in the older `:first`
+      #                spelling: it is first-in-array, hence last-to-execute.
+      #                `:innermost` says the same thing in execution terms and is
+      #                the preferred spelling.
       # - :last/nil  — append (outermost among currently-registered middleware,
       #                but a later append displaces it)
       # - :outermost — pin to run OUTERMOST (first to see the request) and STAY
@@ -62,10 +81,18 @@ class Otto
       #                at build time. Use for middleware that must short-circuit
       #                ahead of everything else (e.g. the CSP report receiver,
       #                which must intercept before CSRF).
+      # - :entrypoint — pin OUTSIDE even the :outermost tier: the very first
+      #                middleware to touch a request. Reserved for middleware
+      #                that must normalize the request before anything else can
+      #                observe it. Otto pins IPPrivacyMiddleware here so every
+      #                other middleware — its own, an :outermost pin, and
+      #                anything the app adds via Otto#use — reads a masked
+      #                REMOTE_ADDR and the canonical env['otto.client_ip'].
       #
       # @param middleware_class [Class] Middleware class
       # @param args [Array] Middleware arguments
-      # @param position [Symbol, nil] Position hint (:first, :last, :outermost, or nil)
+      # @param position [Symbol, nil] Position hint (:first, :innermost, :last,
+      #   :outermost, :entrypoint, or nil)
       def add_with_position(middleware_class, *args, position: nil, **options)
         raise FrozenError, 'Cannot modify frozen middleware stack' if frozen?
 
@@ -81,11 +108,10 @@ class Otto
         entry = { middleware: middleware_class, args: args, options: options }
 
         case position
-        when :first
+        when :first, :innermost
           @stack.unshift(entry)
-        when :outermost
-          @stack << entry
-          @outermost.add(middleware_class)
+        when *PIN_TIERS.keys
+          @stack << entry.merge(pin_tier: PIN_TIERS.fetch(position))
         else
           @stack << entry # :last / nil — default append
         end
@@ -160,9 +186,9 @@ class Otto
         # Update middleware set if any matching entries were found
         return unless matches
 
-        # Rebuild the set of unique middleware classes
+        # Rebuild the set of unique middleware classes. Pins need no cleanup:
+        # each removed entry took its own tier with it.
         @middleware_set = Set.new(@stack.map { |entry| entry[:middleware] })
-        @outermost.delete(middleware_class)
         # Notify of change
         @on_change_callback&.call
       end
@@ -179,7 +205,6 @@ class Otto
 
         @stack.clear
         @middleware_set.clear
-        @outermost.clear
         # Notify of change
         @on_change_callback&.call
       end
@@ -192,9 +217,15 @@ class Otto
       # Build Rack application with middleware chain
       #
       # The stack folds via reduce, so the LAST entry becomes the OUTERMOST
-      # wrapper (first to see the request). #ordered_stack moves any :outermost-
-      # pinned middleware to the end so it stays outermost regardless of the
-      # order middleware was registered in.
+      # wrapper (first to see the request). #ordered_stack moves any pinned
+      # middleware (:outermost, :entrypoint) to the end so it stays outermost
+      # regardless of the order middleware was registered in.
+      #
+      # NOT a request-path method. Its only caller is Otto's build_app!, which
+      # runs at construction and again whenever the stack changes; requests are
+      # served by the chain it returns. So the ordering work here (and in
+      # #ordered_stack) is per-BUILD, not per-request — don't add caching
+      # machinery on the assumption that it is hot.
       def wrap(base_app, security_config = nil)
         ordered_stack.reduce(base_app) do |app, entry|
           middleware = entry[:middleware]
@@ -215,11 +246,23 @@ class Otto
         end
       end
 
-      # Returns list of middleware classes in order
+      # Returns list of middleware classes in REGISTRATION order — the order
+      # they were added, which is the reverse of execution order and ignores pin
+      # tiers. Use #execution_order to see what actually runs first.
       def middleware_list
         @stack.map { |entry| entry[:middleware] }
       end
 
+      # Returns middleware classes in EXECUTION order: the first entry is the
+      # outermost wrapper #wrap builds, i.e. the first to see a request. This is
+      # #middleware_list resolved through the pin tiers and reversed, so it
+      # answers "what does this stack actually do?" without building the app.
+      #
+      # @return [Array<Class>] outermost (first to execute) first
+      def execution_order
+        ordered_stack.reverse.map { |entry| entry[:middleware] }
+      end
+
       # Detailed introspection
       def middleware_details
         @stack.map do |entry|
@@ -254,16 +297,20 @@ class Otto
 
       private
 
-      # The stack ordered for #wrap: identical to @stack unless some middleware
-      # is pinned :outermost, in which case pinned entries are moved to the end
-      # (outermost) while preserving the relative order of both groups. Returns
-      # @stack itself (no copy) in the common no-pin case, so ordinary apps are
-      # completely unaffected.
+      # The stack ordered for #wrap: identical to @stack unless some entry is
+      # pinned, in which case entries are sorted by pin tier (PIN_TIERS,
+      # outward-ascending) so pinned entries move to the end (outermost) while
+      # the relative order within every tier is preserved. Ruby's sort_by is not
+      # stable, hence the explicit index tiebreak. Returns @stack itself (no
+      # copy) in the common no-pin case, so ordinary apps are unaffected.
+      #
+      # Runs per build, not per request — see #wrap.
       def ordered_stack
-        return @stack if @outermost.empty?
+        return @stack if @stack.none? { |entry| entry[:pin_tier] }
 
-        pinned, rest = @stack.partition { |entry| @outermost.include?(entry[:middleware]) }
-        rest + pinned
+        @stack.each_with_index
+              .sort_by { |entry, index| [entry[:pin_tier] || 0, index] }
+              .map(&:first)
       end
 
       def middleware_needs_config?(middleware_class)

data/lib/otto/env_keys.rb

@@ -82,6 +82,17 @@ class Otto
     #   without depending on the (masked) REMOTE_ADDR
     VIA_TRUSTED_PROXY = 'otto.via_trusted_proxy'
 
+    # Whether the connecting peer was the loopback interface.
+    # Type: Boolean
+    # Set by: IPPrivacyMiddleware (every request, evaluated on the ORIGINAL
+    #   socket peer BEFORE REMOTE_ADDR is masked/rewritten). A boolean, never
+    #   an address, so it carries no identifying data.
+    # Used by: Otto::CaddyTLS::LocalhostGuard to authenticate a direct local
+    #   call now that IPPrivacyMiddleware runs outermost. Deliberately the raw
+    #   peer, not the resolved client IP: forwarded headers must play no part
+    #   in a localhost trust decision.
+    PEER_LOOPBACK = 'otto.peer_loopback'
+
     # =========================================================================
     # LOCALIZATION (I18N)
     # =========================================================================
@@ -134,6 +145,27 @@ class Otto
     # Note: presence also acts as the idempotency guard for the middleware
     CLIENT_IP = 'otto.client_ip'
 
+    # Verdict-only CIDR membership check over the resolved, UNMASKED client IP
+    # Type: Proc — call with an Enumerable of CIDR strings or IPAddr objects,
+    #       returns true/false
+    # Set by: IPPrivacyMiddleware (every path that resolves an IP, all
+    #         privacy profiles)
+    # Used by: Downstream IP policy code (allowlists, denylists, network
+    #          zones) that needs full /32-/128 precision without changing the
+    #          observability posture — CLIENT_IP is masked under the default
+    #          profile, so it cannot express a single host
+    # Note: the unmasked IP never lands in env; only this closure does, and a
+    #       Proc serializes to nothing useful, so env dumps and loggers cannot
+    #       leak the address accidentally. Returns false when the request had
+    #       no resolvable client IP (fail-closed for allowlist callers);
+    #       raises IPAddr::InvalidAddressError for invalid CIDR entries
+    #       (configuration error). See Otto::Utils.ip_in_cidrs?.
+    # Note: setting CLIENT_IP yourself is out of contract — it trips the
+    #       middleware's idempotency guard, so the unmasked address is never
+    #       captured and this capability degrades to a logged fail-closed
+    #       check that denies every range.
+    IP_MATCH = 'otto.ip_match'
+
     # Privacy-safe masked IP address
     # Type: String (e.g., '192.168.1.0')
     # Set by: IPPrivacyMiddleware

data/lib/otto/logging_helpers.rb

@@ -76,12 +76,61 @@ class Otto
       {
             method: env['REQUEST_METHOD'],
               path: env['PATH_INFO'],
-                ip: env['otto.client_ip'] || env['REMOTE_ADDR'], # Canonical client IP (masked when privacy on)
+                ip: privacy_safe_ip(env), # Canonical client IP (masked when privacy on)
            country: env['otto.privacy.geo_country'],
         user_agent: env['HTTP_USER_AGENT']&.slice(0, 100), # Already anonymized by IPPrivacyMiddleware
       }.compact
     end
 
+    # A client IP that is safe to write to a log.
+    #
+    # Prefers the canonical env['otto.client_ip'] that IPPrivacyMiddleware
+    # resolves once per request: masked when privacy is on, and deliberately
+    # the real address when the app has disabled privacy. That key is present
+    # for anything running inside Otto, since the middleware is pinned
+    # outermost.
+    #
+    # It is ABSENT for code that runs outside Otto's stack — notably
+    # Rack::Attack, which the hosting app mounts ahead of Otto (see
+    # Otto::Security::Middleware::RateLimitMiddleware), so its 'rack.attack'
+    # subscriber observes the raw peer no matter how Otto orders its own
+    # middleware. There we mask the address ourselves rather than log it whole:
+    # a public IP is reduced with the default precision (privacy config is not
+    # reachable from a global subscriber), and private/localhost addresses pass
+    # through unmasked, matching the middleware's own exemption so development
+    # logs stay readable.
+    #
+    # Never raises and never returns a raw public address: an unparseable value
+    # (a ported REMOTE_ADDR, a malformed forwarded entry) becomes '[redacted]'.
+    #
+    # @param env [Hash] Rack environment hash
+    # @param fallback_ip [String, nil] address to fall back to when the env
+    #   carries no canonical client IP — e.g. Rack::Request#ip, which factors in
+    #   forwarded headers. Defaults to REMOTE_ADDR.
+    # @return [String, nil] log-safe address, or nil when there is none
+    def self.privacy_safe_ip(env, fallback_ip = nil)
+      canonical = env['otto.client_ip']
+      return canonical unless canonical.to_s.empty?
+
+      candidate = fallback_ip.to_s.empty? ? env['REMOTE_ADDR'] : fallback_ip
+      redact_ip(candidate)
+    end
+
+    # Reduce a raw address to a log-safe form. See .privacy_safe_ip.
+    #
+    # @param ip [String, nil] raw address
+    # @return [String, nil] masked address, the address itself when
+    #   private/localhost, '[redacted]' when unparseable, nil when blank
+    def self.redact_ip(ip)
+      address = ip.to_s.strip
+      return nil if address.empty?
+      return address if Otto::Privacy::IPPrivacy.private_or_localhost?(address)
+
+      Otto::Privacy::IPPrivacy.mask_ip(address) || '[redacted]'
+    rescue ArgumentError
+      '[redacted]'
+    end
+
     # Log a timed operation with consistent timing and error handling
     #
     # @param level [Symbol] The log level (:debug, :info, :warn, :error)

data/lib/otto/mcp/rate_limiting.rb

@@ -113,14 +113,17 @@ class Otto
       def self.configure_mcp_logging
         return unless defined?(ActiveSupport::Notifications)
 
+        # Masked address only — see the note on the sibling subscriber in
+        # Otto::Security::RateLimiting.configure_rack_attack! (issue #219).
         ActiveSupport::Notifications.subscribe('rack.attack') do |_name, _start, _finish, _request_id, payload|
           req      = payload[:request]
           endpoint = req.env['otto.mcp_http_endpoint'] || '/_mcp'
+          ip       = Otto::LoggingHelpers.privacy_safe_ip(req.env, req.ip)
 
           if req.path.start_with?(endpoint)
-            Otto.logger.warn "[MCP] Rate limit #{payload[:match_type]} for #{req.ip}: #{payload[:matched]}"
+            Otto.logger.warn "[MCP] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
           else
-            Otto.logger.warn "[Otto] Rate limit #{payload[:match_type]} for #{req.ip}: #{payload[:matched]}"
+            Otto.logger.warn "[Otto] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
           end
         end
       end