otto 2.9.0 → 2.11.0

data/lib/otto/security/core.rb

@@ -46,6 +46,7 @@ class Otto
         ensure_not_frozen!
         return if @middleware.includes?(Otto::Security::Middleware::RateLimitMiddleware)
 
+        Otto::Security::RateLimiting.ensure_available!
         @security.configure_rate_limiting(options)
         use Otto::Security::Middleware::RateLimitMiddleware
       end
@@ -76,6 +77,23 @@ class Otto
         @security_config.add_trusted_proxy(proxy)
       end
 
+      # Assert that NO proxy is trusted: every peer gets
+      # env['otto.via_trusted_proxy'] = false, forwarded client-IP chains are
+      # ignored, and forwarded host/scheme/port carriers are stripped so
+      # Rack::Request#host resolves only from the Host header.
+      #
+      # Equivalent to passing `trusted_proxies: :none` to Otto.new. Distinct
+      # from configuring nothing, which asserts nothing (tri-state, #228).
+      #
+      # @raise [ArgumentError] if trusted proxies or a depth >= 1 are configured
+      # @return [void]
+      # @example
+      #   otto.trust_no_proxies!
+      def trust_no_proxies!
+        ensure_not_frozen!
+        @security_config.trust_no_proxies!
+      end
+
       # Set custom security headers that will be added to all responses.
       # These merge with the default security headers.
       #
@@ -245,7 +263,7 @@ class Otto
       # @param strategy [AuthStrategy] Strategy instance
       # @example
       #   otto.add_auth_strategy('session', SessionStrategy.new(session_key: 'user_id'))
-      #   otto.add_auth_strategy('api_key', APIKeyStrategy.new)
+      #   otto.add_auth_strategy('api_key', APIKeyStrategy.new(api_keys: ENV.fetch('API_KEYS').split(',')))
       # @raise [ArgumentError] if strategy name already registered
       def add_auth_strategy(name, strategy)
         ensure_not_frozen!

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

@@ -36,6 +36,14 @@ class Otto
       #   # env['otto.original_ip'] also contains real IP
       #
       class IPPrivacyMiddleware
+        # Forwarding metadata Rack::Request reads without consulting Otto's
+        # proxy trust verdict: host (#host/#authority), scheme (#scheme/#ssl?),
+        # and port (#port), from both the X-Forwarded-* family and RFC 7239
+        # Forwarded (host=, proto=, and the port inside for=). Defined in
+        # Otto::Utils so Otto::Utils::RELAY_MARKER_HEADERS is built from the
+        # same list and cannot fall out of step with what is scrubbed here.
+        UNTRUSTED_FORWARDING_METADATA_HEADERS = Otto::Utils::FORWARDED_AUTHORITY_HEADERS
+
         # Initialize IP Privacy middleware
         #
         # @param app [#call] Rack application
@@ -55,8 +63,13 @@ 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.
+          #
+          # Client-IP resolution is idempotent, but proxy TRUST is not: the
+          # prior pass may have run under a different (or no) configuration,
+          # so this instance still enforces its own trust posture below.
           if env.key?('otto.client_ip')
             ensure_ip_match_present(env)
+            enforce_proxy_trust_after_prior_pass(env)
             return @app.call(env)
           end
 
@@ -65,7 +78,9 @@ class Otto
           # REMOTE_ADDR is rewritten to the masked client IP. Leak-free boolean.
           #
           # TRI-STATE: the key is written ONLY when the operator configured
-          # proxy trust (CIDR matchers or a depth). Present, its value is
+          # proxy trust (CIDR matchers, a depth, or the explicit trust-nobody
+          # assertion `trusted_proxies: :none`, which makes the value false for
+          # every peer, #259). Present, its value is
           # authoritative in both directions — true means the peer matched a
           # CIDR (filter mode) or depth mode is active (configuring a depth
           # asserts the connecting peer IS the operator's proxy tier, #226);
@@ -77,9 +92,24 @@ class Otto
           # forced consumers into grant-only reads (#228).
           # respond_to?: like geo_headers_trusted?, a partial/duck-typed
           # config (or nil) that cannot report trust state is "unconfigured".
-          if @security_config.respond_to?(:proxy_trust_configured?) && @security_config.proxy_trust_configured?
-            env['otto.via_trusted_proxy'] = trusted_proxy?(env['REMOTE_ADDR'])
-          end
+          proxy_trust_configured = @security_config.respond_to?(:proxy_trust_configured?) &&
+                                   @security_config.proxy_trust_configured?
+          via_trusted_proxy = proxy_trust_configured && trusted_proxy?(env['REMOTE_ADDR'])
+          env['otto.via_trusted_proxy'] = via_trusted_proxy if proxy_trust_configured
+
+          # Record whether the request was relayed BEFORE the scrub below can
+          # delete the relay markers. Downstream middleware that must
+          # authenticate a direct local call (Otto::CaddyTLS::LocalhostGuard)
+          # runs after this one and would otherwise read a request whose
+          # HTTP_FORWARDED was deleted here as "direct". Leak-free boolean.
+          env['otto.peer_relayed'] = Otto::Utils.relayed_request?(env)
+
+          # A peer that failed configured proxy trust cannot supply forwarded
+          # host, scheme, or port either. Unconfigured trust (absent tri-state
+          # key) is left alone: the operator has asserted nothing, and the
+          # contract reserves that state for downstream heuristics (#228), so
+          # Rack keeps its own defaults there.
+          scrub_untrusted_forwarding_metadata(env) if proxy_trust_configured && !via_trusted_proxy
 
           # Same rationale, for loopback: this middleware runs outermost, so a
           # downstream middleware that must authenticate a DIRECT LOCAL CALL
@@ -121,6 +151,58 @@ class Otto
           @config.enabled?
         end
 
+        # Enforce THIS instance's proxy trust posture when a prior
+        # IPPrivacyMiddleware pass already resolved the client IP.
+        #
+        # The early return in #call keeps client-IP resolution idempotent, but
+        # trust enforcement must not ride on it: an outer instance mounted
+        # without the application's security config (the "unconfigured
+        # defaults" case in docs/guides/privacy.md) writes otto.client_ip and
+        # nothing else, and returning here would let an inner
+        # `trusted_proxies: :none` instance pass X-Forwarded-Host through
+        # untouched — the exact bypass the assertion exists to close.
+        #
+        # What can still be decided after the prior pass:
+        # - trust-nobody: the verdict is false for every peer, so it needs no
+        #   peer address. Always enforced, overriding a laxer prior verdict.
+        # - depth mode: the verdict is true by assertion. Recorded only when
+        #   no configured pass has spoken (key absent).
+        # - CIDR mode: needs the connecting peer, which the prior pass has
+        #   rewritten (REMOTE_ADDR is now the resolved, possibly masked, client
+        #   IP — matching a masked address against a narrow CIDR produces false
+        #   ALLOWs, see #ensure_ip_match_present). A verdict recorded by a prior
+        #   CONFIGURED pass is kept (the same-config stacking case). With none,
+        #   fail closed: deny, scrub, and warn so the misconfiguration is
+        #   diagnosable rather than a silent grant.
+        #
+        # Every deny also scrubs the authority carriers, which is idempotent:
+        # deleting an already-deleted key is a no-op.
+        #
+        # @param env [Hash] Rack environment
+        def enforce_proxy_trust_after_prior_pass(env)
+          return unless @security_config.respond_to?(:proxy_trust_configured?) &&
+                        @security_config.proxy_trust_configured?
+
+          if @security_config.trust_no_proxies?
+            env['otto.via_trusted_proxy'] = false
+            scrub_untrusted_forwarding_metadata(env)
+          elsif env.key?('otto.via_trusted_proxy')
+            nil # a configured pass already decided; honor it
+          elsif @security_config.trusted_proxy_depth_mode?
+            env['otto.via_trusted_proxy'] = true
+          else
+            Otto.logger.warn(
+              '[IPPrivacyMiddleware] otto.client_ip was resolved by a prior ' \
+              'pass with no proxy trust configured, so the connecting peer ' \
+              'can no longer be matched against trusted_proxies; treating ' \
+              'the peer as untrusted and stripping forwarded authority. ' \
+              'Pass the application security config to the outer instance.'
+            )
+            env['otto.via_trusted_proxy'] = false
+            scrub_untrusted_forwarding_metadata(env)
+          end
+        end
+
         # Guarantee env['otto.ip_match'] exists on the idempotent-return path.
         #
         # Every path in this middleware that sets otto.client_ip installs the
@@ -389,6 +471,25 @@ class Otto
           env['otto.ip_match'] = ->(cidrs) { Otto::Utils.ip_in_cidrs?(client_ip, cidrs) }
         end
 
+        # Remove forwarding metadata supplied by a peer that failed proxy trust.
+        #
+        # Rack honors these according only to the process-global forwarding
+        # family, so without this an untrusted client would control
+        # request.host, request.ssl?, and request.port for every mounted Rack
+        # app (Rack::Session's Secure-cookie gate reads ssl?). Delete the
+        # carriers rather than editing them: this path runs only in CIDR filter
+        # mode or under the trust-nobody assertion (`trusted_proxies: :none`,
+        # #259), neither of which reads the Forwarded header itself, and a
+        # hand-rolled RFC 7239 parser that disagrees with Rack's on quoting
+        # (e.g. `for=a"b;host=evil`) would let a host= survive the edit.
+        # X-Forwarded-For stays, masked or not, because Otto's own resolution
+        # already ignores it from an untrusted peer.
+        #
+        # @param env [Hash] Rack environment
+        def scrub_untrusted_forwarding_metadata(env)
+          UNTRUSTED_FORWARDING_METADATA_HEADERS.each { |key| env.delete(key) }
+        end
+
         # Delete forwarded IP headers outright.
         #
         # Used on the no-resolvable-client-IP path, where there is no masked IP

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

@@ -27,13 +27,8 @@ class Otto
         def initialize(app, security_config = nil)
           @app = app
           @security_config = security_config
-          @rate_limiter_available = defined?(Rack::Attack)
 
-          if @rate_limiter_available
-            configure_rate_limiting
-          else
-            Otto.logger.warn '[Otto] rack-attack not available - rate limiting disabled'
-          end
+          configure_rate_limiting
         end
 
         # Pass-through call - actual rate limiting handled by Rack::Attack

data/lib/otto/security/rate_limiter.rb

@@ -4,18 +4,25 @@
 
 require 'json'
 
-begin
-  require 'rack/attack'
-rescue LoadError
-  # rack-attack is optional - graceful fallback
-end
+require_relative '../optional_dependency'
 
 class Otto
   module Security
     # Rate limiting implementation using Rack::Attack
     class RateLimiting
+      RACK_ATTACK_REQUIREMENT = '~> 6.7'
+
+      def self.ensure_available!
+        Otto::OptionalDependency.require!(
+          'rack-attack',
+          RACK_ATTACK_REQUIREMENT,
+          require_path: 'rack/attack',
+          feature: 'Rate limiting'
+        )
+      end
+
       def self.configure_rack_attack!(config = {})
-        return unless defined?(Rack::Attack)
+        ensure_available!
 
         # Use provided cache store or default
         Rack::Attack.cache.store = config[:cache_store] if config[:cache_store]
@@ -23,9 +30,13 @@ class Otto
         # Default rules
         default_requests_per_minute = config.fetch(:requests_per_minute, 100)
 
-        # General request throttling
+        # General request throttling. Internal paths (/_mcp, /_status, ...)
+        # are skipped by default. PATH_INFO, not Rack::Request#path: #path
+        # prepends SCRIPT_NAME, so with Otto mounted under `map '/api'` the
+        # internal /_mcp request read as /api/_mcp and was counted here while
+        # the MCP throttle, comparing the same way, never saw it at all.
         Rack::Attack.throttle('requests', limit: default_requests_per_minute, period: 60) do |request|
-          request.ip unless request.path.start_with?('/_') # Skip internal paths by default
+          request.ip unless request.path_info.start_with?('/_')
         end
 
         # Apply custom rules if provided
@@ -45,52 +56,76 @@ class Otto
           end
         end
 
-        # Custom response for rate limited requests
-        Rack::Attack.throttled_responder = lambda do |request|
-          match_data = request.env['rack.attack.match_data']
-          now = match_data[:epoch_time]
-
-          headers = {
-            'content-type' => 'application/json',
-            'retry-after' => (match_data[:period] - (now % match_data[:period])).to_s,
-          }
+        configure_responses
+        configure_logging
+      end
 
-          # Content negotiation for rate limit response
-          # Route's response_type takes precedence over Accept header
-          route_def = request.env['otto.route_definition']
-          wants_json = (route_def&.response_type == 'json') ||
-                       request.env['HTTP_ACCEPT'].to_s.include?('application/json')
-
-          if wants_json
-            error_response = {
-              error: 'Rate limit exceeded',
-              message: 'Too many requests',
-              retry_after: headers['retry-after'].to_i,
-              limit: match_data[:limit],
-              period: match_data[:period],
-            }
-            [429, headers, [JSON.generate(error_response)]]
-          else
-            body = "Rate limit exceeded. Retry after #{headers['retry-after']} seconds."
-            headers['content-type'] = 'text/plain'
-            [429, headers, [body]]
-          end
-        end
+      # Rack::Attack holds a single throttled_responder and each subscriber to
+      # 'rack.attack' fires on every throttle event. Subclasses override
+      # throttled_response and log_throttled_request instead of registering
+      # their own responder or subscriber after super, so the hosting app never
+      # gets a redundant responder assignment or doubled log lines.
+      def self.configure_responses
+        Rack::Attack.throttled_responder = ->(request) { throttled_response(request) }
+      end
 
+      def self.configure_logging
         # 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]
-          ip  = Otto::LoggingHelpers.privacy_safe_ip(req.env, req.ip)
-          Otto.logger.warn "[Otto] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
+          log_throttled_request(payload)
+        end
+      end
+
+      def self.throttled_response(request)
+        match_data = request.env['rack.attack.match_data']
+        general_throttled_response(request, throttle_headers(match_data), match_data)
+      end
+
+      def self.throttle_headers(match_data)
+        now = match_data[:epoch_time]
+
+        {
+          'content-type' => 'application/json',
+          'retry-after' => (match_data[:period] - (now % match_data[:period])).to_s,
+        }
+      end
+
+      # Custom response for rate limited requests
+      def self.general_throttled_response(request, headers, match_data)
+        # Content negotiation for rate limit response
+        # Route's response_type takes precedence over Accept header
+        route_def = request.env['otto.route_definition']
+        wants_json = (route_def&.response_type == 'json') ||
+                     request.env['HTTP_ACCEPT'].to_s.include?('application/json')
+
+        if wants_json
+          error_response = {
+            error: 'Rate limit exceeded',
+            message: 'Too many requests',
+            retry_after: headers['retry-after'].to_i,
+            limit: match_data[:limit],
+            period: match_data[:period],
+          }
+          [429, headers, [JSON.generate(error_response)]]
+        else
+          body = "Rate limit exceeded. Retry after #{headers['retry-after']} seconds."
+          headers['content-type'] = 'text/plain'
+          [429, headers, [body]]
         end
       end
+
+      # 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).
+      def self.log_throttled_request(payload)
+        req = payload[:request]
+        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
 end

data/lib/otto/static.rb

@@ -15,6 +15,44 @@ class Otto
       [404, security_headers.merge({ 'content-type' => 'text/plain' }), ['Not Found']]
     end
 
+    # Return a per-request copy of a Rack triple so callers can never hand a
+    # shared object back to the Rack stack.
+    #
+    # Middleware above Otto (rack-session, Otto's own CSRF middleware, anything
+    # that calls +Rack::Utils.set_cookie_header!+) writes response headers in
+    # place. Returning a configured triple by reference lets those writes
+    # accumulate on the shared object for the life of the process, so every
+    # subsequent 404/500 replays every Set-Cookie any earlier one committed.
+    #
+    # The copy is intentionally shallow-plus-one: the headers container keeps
+    # its class (a +Rack::Headers+ stays case-insensitive), each Array-valued
+    # header (Rack 3's representation of a repeated header) is copied so an
+    # append cannot reach the shared Array, and an Array body is copied so a
+    # middleware appending chunks cannot grow the shared body. A frozen
+    # configured triple yields an unfrozen copy, so cookie middleware works
+    # after configuration freezing as well.
+    #
+    # @param response [Array] a Rack triple +[status, headers, body]+
+    # @return [Array] a new triple that shares no mutable container with +response+
+    def copy_response(response)
+      status, headers, body = response
+      [status, copy_headers(headers), body.is_a?(Array) ? body.dup : body]
+    end
+
+    # Copy a Rack headers container, keeping its class and copying Array values.
+    #
+    # @param headers [Hash, Rack::Headers, nil] the headers to copy
+    # @return [Hash, Rack::Headers] a new container of the same class
+    def copy_headers(headers)
+      return {} if headers.nil?
+
+      copied = headers.dup
+      copied.each_pair do |key, value|
+        copied[key] = value.dup if value.is_a?(Array)
+      end
+      copied
+    end
+
     def security_headers
       {
         'x-frame-options' => 'DENY',

data/lib/otto/utils.rb

@@ -19,9 +19,47 @@ class Otto
       HTTP_X_CLIENT_IP
     ].freeze
 
+    # Forwarding metadata Rack::Request reads without consulting Otto's proxy
+    # trust verdict: host (#host/#authority), scheme (#scheme/#ssl?), and port
+    # (#port), from both the X-Forwarded-* family and RFC 7239 Forwarded
+    # (host=, proto=, and the port inside for=). IPPrivacyMiddleware deletes
+    # every one of these for a peer that failed configured proxy trust.
+    FORWARDED_AUTHORITY_HEADERS = %w[
+      HTTP_FORWARDED
+      HTTP_X_FORWARDED_HOST
+      HTTP_X_FORWARDED_PROTO
+      HTTP_X_FORWARDED_SCHEME
+      HTTP_X_FORWARDED_SSL
+      HTTP_X_FORWARDED_PORT
+    ].freeze
+
+    # Headers whose presence means the request was RELAYED by a proxy rather
+    # than issued directly by the peer: every forwarding carrier Otto knows —
+    # the forwarded-for family, RFC 7239 Forwarded, and the authority (host /
+    # scheme / port) carriers. The set must cover everything IPPrivacyMiddleware
+    # may DELETE on the untrusted-peer path: a carrier that is scrubbed but not
+    # counted here would let a relayed request look direct afterwards. Shared
+    # by IPPrivacyMiddleware (which records the verdict as
+    # env['otto.peer_relayed'] BEFORE the scrub) and
+    # Otto::CaddyTLS::LocalhostGuard, so the record and the guard's own
+    # fallback scan cannot drift.
+    RELAY_MARKER_HEADERS = (FORWARDED_FOR_HEADERS + FORWARDED_AUTHORITY_HEADERS).uniq.freeze
+
     # Special-use IPv4/IPv6 ranges that IPAddr's #private?/#loopback?/#link_local?
     # predicates do not cover but that should still be treated as non-public
     # (e.g. when picking the real client out of a forwarded chain).
+    #
+    # The documentation ranges (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24,
+    # 2001:db8::/32 and the newer 3fff::/20) are deliberately NOT listed here.
+    # The predicate answers "could this be the real client", and non-public
+    # entries are skipped as proxy hops. Those ranges are not globally routable,
+    # but they are the universal convention for an example public client in tests
+    # and docs, including this repo's own specs and guides, so treating them as
+    # non-public would make the resolver skip the example client and silently
+    # invalidate those examples. There is no security gain either: an attacker who
+    # can inject into a chain injects a routable address, and a documentation
+    # address in a real chain means a misconfigured hop, which is better surfaced
+    # than skipped.
     SPECIAL_USE_RANGES = [
       IPAddr.new('0.0.0.0/8'),   # "this" network / unspecified (IPv4)
       IPAddr.new('224.0.0.0/4'), # IPv4 multicast
@@ -389,6 +427,18 @@ class Otto
       end
     end
 
+    # Whether any relay marker header is present on the request.
+    #
+    # Call this only from code that runs BEFORE forwarding carriers may be
+    # deleted (IPPrivacyMiddleware's untrusted-peer scrub); downstream code
+    # should prefer the recorded env['otto.peer_relayed'] boolean.
+    #
+    # @param env [Hash] Rack environment
+    # @return [Boolean]
+    def relayed_request?(env)
+      RELAY_MARKER_HEADERS.any? { |header| !env[header].to_s.strip.empty? }
+    end
+
     # Whether an address is on the loopback interface.
     #
     # This is the RAW SOCKET PEER test used to authenticate a direct local call

data/lib/otto/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 class Otto
-  VERSION = '2.9.0'
+  VERSION = '2.11.0'
 end