otto 2.9.0 → 2.10.0

data/lib/otto/security/config.rb

@@ -6,6 +6,7 @@ require 'securerandom'
 require 'digest'
 require 'openssl'
 require 'ipaddr'
+require 'rack/request'
 require_relative '../core/freezable'
 require_relative 'csp/policy'
 
@@ -55,6 +56,46 @@ class Otto
         (geo_db_path or geo_db_reader).
       MSG
 
+      # Error raised when the explicit "trust no proxy" assertion
+      # (#trust_no_proxies!, `trusted_proxies: :none`) is combined with an
+      # actual trust grant (enumerated CIDRs or a depth >= 1). The two say
+      # opposite things about the same peer, so the combination is refused at
+      # configuration time rather than silently resolved in one direction.
+      TRUST_NO_PROXIES_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        Cannot combine trusted_proxies: :none (trust no proxy) with
+        trusted_proxies CIDRs or trusted_proxy_depth >= 1. Assert :none OR
+        grant trust, not both.
+      MSG
+
+      # Error raised when the trust-nobody sentinel arrives as a proxy ENTRY
+      # (`trusted_proxies: ['none']`, as a YAML/JSON list naturally yields, or
+      # `add_trusted_proxy('none')`) instead of as the whole option. Inside a
+      # list it would otherwise register a legacy string-prefix matcher that
+      # matches nothing: peers would be untrusted, but trust_no_proxies? would
+      # stay false and the config would stake a forwarding-family claim, so the
+      # explicit assertion would be silently replaced by a lookalike.
+      TRUST_NO_PROXIES_ENTRY_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        trusted_proxies entry :none is the trust-nobody assertion, not a proxy
+        address. Pass trusted_proxies: :none as the whole option (not inside a
+        list) or call trust_no_proxies! instead.
+      MSG
+
+      # Sentinel accepted wherever a trusted_proxies list is accepted, meaning
+      # "the operator asserts that NO proxy is trusted". See #trust_no_proxies!.
+      TRUST_NO_PROXIES = :none
+
+      # Whether a trusted_proxies option value is the trust-nobody sentinel.
+      # Accepts the symbol and the String spelling 'none' (case-insensitive),
+      # which is what YAML/ENV-driven configuration naturally produces; without
+      # this, 'none' would fall through to add_trusted_proxy and install a
+      # legacy string-prefix matcher, silently inverting the assertion.
+      #
+      # @param value [Object] raw trusted_proxies option
+      # @return [Boolean]
+      def self.trust_no_proxies_option?(value)
+        (value.is_a?(Symbol) || value.is_a?(String)) && value.to_s.casecmp?('none')
+      end
+
       # Forwarded-header sources depth mode (#trusted_proxy_depth) can count
       # hops from: X-Forwarded-For (default), the RFC 7239 Forwarded header, or
       # Both (Forwarded when present, else X-Forwarded-For). Mirrors
@@ -62,6 +103,133 @@ class Otto
       # depth mode; CIDR-walk is unaffected.
       TRUSTED_PROXY_HEADERS = %w[X-Forwarded-For Forwarded Both].freeze
 
+      # Rack uses one process-global priority for forwarded host, port, scheme,
+      # and IP resolution. Keep it aligned with Otto's configured forwarding
+      # family so the two request views cannot silently disagree.
+      RACK_REQUEST = ::Rack::Request
+      DEFAULT_RACK_FORWARDED_PRIORITY = RACK_REQUEST.forwarded_priority.dup.freeze
+      RACK_FORWARDED_PRIORITIES = {
+        'X-Forwarded-For' => [:x_forwarded].freeze,
+        'Forwarded' => [:forwarded].freeze,
+        'Both' => %i[forwarded x_forwarded].freeze,
+      }.freeze
+      DEFAULT_TRUSTED_PROXY_HEADER = 'X-Forwarded-For'
+      FORWARDING_FAMILY_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        Cannot use forwarding family %s (trusted_proxy_header) because another
+        Otto application in this process already uses %s. Rack's forwarded
+        host, port, scheme, and IP policy is process-global, so every Otto
+        application in one process that resolves proxied requests must use the
+        same forwarding family.
+      MSG
+      # Error raised when a non-default trusted_proxy_header is combined with
+      # CIDR filter mode. Otto's CIDR-walk resolves the client IP from the
+      # X-Forwarded-For family only (X-Forwarded-For, then X-Real-IP, then
+      # X-Client-IP — Otto::Utils::FORWARDED_FOR_HEADERS), never RFC 7239
+      # Forwarded, while trusted_proxy_header also pins Rack's
+      # forwarding family; honoring 'Forwarded' or 'Both' there would make Rack
+      # read a header Otto ignores, recreating the disagreement the pin exists
+      # to close.
+      FORWARDED_HEADER_CIDR_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        Cannot configure trusted_proxy_header 'Forwarded' or 'Both' together
+        with trusted_proxies (CIDR filter mode): CIDR-walk resolves client IPs
+        from the X-Forwarded-For family only (X-Forwarded-For, X-Real-IP,
+        X-Client-IP), never RFC 7239 Forwarded. Use trusted_proxy_depth (count
+        mode) to read the RFC 7239 Forwarded header.
+      MSG
+
+      # Eager so the first two concurrent Otto.new calls cannot race on
+      # creating the lock itself.
+      RACK_FORWARDING_MUTEX = Mutex.new
+      private_constant :RACK_FORWARDING_MUTEX
+
+      class << self
+        # Pin Rack's process-global forwarding family to Otto's.
+        #
+        # Rack::Request.forwarded_priority is one setting per process, so two
+        # Otto applications that commit to different families cannot coexist:
+        # the later commitment raises. A config commits (claim: true) when the
+        # operator sets trusted_proxy_header or configures proxy trust at all
+        # (trusted_proxies or a depth): an app that resolves proxied requests
+        # from X-Forwarded-For depends on Rack reading the same family, even
+        # though it never named one. A config may revise its own commitment
+        # before it freezes, as long as no other config has committed to the
+        # previous family.
+        #
+        # A config with no proxy trust and no explicit header (claim: false, a
+        # bare Otto.new) is indifferent: it pins Rack to the default only while
+        # nothing is committed and otherwise defers, so a no-options sub-mount
+        # constructed first cannot block a later `trusted_proxy_header:
+        # 'Forwarded'` with an error naming a family nobody chose.
+        #
+        # Committed configs are held strongly on purpose. A weak registry made
+        # the conflict check depend on whether the earlier config had been
+        # garbage collected, so boot order and GC timing decided whether the
+        # app raised. Otto#initialize releases the claim when construction
+        # fails after the config committed (see .release_rack_forwarding_family!).
+        #
+        # @param config [Otto::Security::Config] the config applying the family
+        # @param header [String] canonical TRUSTED_PROXY_HEADERS value
+        # @param claim [Boolean] whether this config depends on the family
+        # @raise [ArgumentError] on a conflict with another committed config
+        def apply_rack_forwarding_family!(config, header, claim: true)
+          RACK_FORWARDING_MUTEX.synchronize do
+            if claim
+              committed = rack_forwarding_family
+              if committed && committed != header &&
+                 rack_forwarding_owners.each_key.any? { |owner| !owner.equal?(config) }
+                raise ArgumentError, format(FORWARDING_FAMILY_CONFLICT_MESSAGE, header, committed)
+              end
+
+              rack_forwarding_owners[config] = true
+              @rack_forwarding_family = header
+            elsif rack_forwarding_family
+              # A committed choice already governs Rack; the default defers.
+              next
+            end
+
+            RACK_REQUEST.forwarded_priority = RACK_FORWARDED_PRIORITIES.fetch(header).dup
+          end
+        end
+
+        # Withdraw a config's commitment, e.g. when Otto.new fails after the
+        # config committed. Rack's priority is left as-is: it is either still
+        # backed by another owner or will be re-pinned by the next app.
+        #
+        # @param config [Otto::Security::Config]
+        # @return [void]
+        def release_rack_forwarding_family!(config)
+          RACK_FORWARDING_MUTEX.synchronize do
+            rack_forwarding_owners.delete(config)
+            @rack_forwarding_family = nil if rack_forwarding_owners.empty?
+          end
+        end
+
+        # The forwarding family explicitly committed for this process, or nil.
+        #
+        # @return [String, nil]
+        attr_reader :rack_forwarding_family
+
+        # Clear process-global forwarding state between isolated RSpec examples.
+        #
+        # @api private
+        def reset_rack_forwarding_family_for_testing!
+          raise 'reset_rack_forwarding_family_for_testing! is only available in RSpec test environment' unless defined?(RSpec)
+
+          RACK_FORWARDING_MUTEX.synchronize do
+            @rack_forwarding_owners = nil
+            @rack_forwarding_family = nil
+            RACK_REQUEST.forwarded_priority = DEFAULT_RACK_FORWARDED_PRIORITY.dup
+          end
+        end
+
+        private
+
+        # Identity-keyed set of configs committed to the family.
+        def rack_forwarding_owners
+          @rack_forwarding_owners ||= {}.compare_by_identity
+        end
+      end
+
       # Endpoint group name shared by the CSP `report-to` directive and the
       # `Reporting-Endpoints` response header (modern Reporting API). Browsers
       # match the directive's group to the header's key, so both must agree.
@@ -106,8 +274,9 @@ class Otto
         @max_param_keys         = 64
         @trusted_proxies        = []
         @trusted_proxy_matchers = []
+        @trust_no_proxies       = false
         @trusted_proxy_depth    = nil
-        @trusted_proxy_header   = 'X-Forwarded-For'
+        @trusted_proxy_header   = DEFAULT_TRUSTED_PROXY_HEADER
         @require_secure_cookies = false
         @security_headers       = default_security_headers
         @input_validation       = true
@@ -187,6 +356,17 @@ class Otto
         # conflict eagerly here (and in #trusted_proxy_depth=) so it surfaces at
         # configuration time, not only at freeze (which the test harness skips).
         raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if trusted_proxy_depth_mode?
+        raise ArgumentError, TRUST_NO_PROXIES_CONFLICT_MESSAGE if @trust_no_proxies
+        # Same pattern for header-then-proxies; proxies-then-header is caught
+        # in #trusted_proxy_header=.
+        raise ArgumentError, FORWARDED_HEADER_CIDR_CONFLICT_MESSAGE unless default_trusted_proxy_header?
+
+        # The trust-nobody sentinel is an option value, never an entry; validate
+        # the whole list before registering anything so a bad list leaves the
+        # config untouched.
+        Array(proxy).each do |entry|
+          raise ArgumentError, TRUST_NO_PROXIES_ENTRY_MESSAGE if self.class.trust_no_proxies_option?(entry)
+        end
 
         case proxy
         when String, Regexp
@@ -256,8 +436,56 @@ class Otto
       # (false) from "no proxy trust configured" (absent) and apply their own
       # legacy heuristics only in the latter case.
       #
-      # @return [Boolean] true when filter or depth mode is configured
+      # @return [Boolean] true when filter or depth mode is configured, or when
+      #   the operator explicitly asserted that no proxy is trusted
       def proxy_trust_configured?
+        trusted_proxies_configured? || trusted_proxy_depth_mode? || trust_no_proxies?
+      end
+
+      # Assert that NO proxy is trusted for this application.
+      #
+      # This is a positive operator assertion, not the absence of one: an app
+      # that never configures proxy trust leaves env['otto.via_trusted_proxy']
+      # ABSENT (the tri-state contract from #228) so downstream consumers may
+      # apply their own heuristics. After this call the key is written as
+      # `false` for EVERY peer — loopback included, since Otto has no
+      # loopback special case in either resolution mode — which means client
+      # IP resolution ignores X-Forwarded-For entirely (REMOTE_ADDR wins) and
+      # IPPrivacyMiddleware strips the forwarded host/scheme/port carriers, so
+      # Rack::Request#host resolves only from the Host header (#259).
+      #
+      # Mutually exclusive with any actual trust grant (trusted_proxies CIDRs
+      # or trusted_proxy_depth >= 1). It stakes no claim on the process-global
+      # Rack forwarding family: an app that trusts nobody reads no forwarded
+      # chain, so it cannot conflict with another app's explicit choice.
+      #
+      # @raise [FrozenError] if configuration is frozen
+      # @raise [ArgumentError] if trusted proxies or a depth >= 1 are configured
+      # @return [void]
+      #
+      # @example
+      #   config.trust_no_proxies!
+      def trust_no_proxies!
+        ensure_not_frozen!
+        raise ArgumentError, TRUST_NO_PROXIES_CONFLICT_MESSAGE if trusted_proxies_configured? || trusted_proxy_depth_mode?
+
+        @trust_no_proxies = true
+      end
+
+      # Whether the operator explicitly asserted that no proxy is trusted.
+      #
+      # @return [Boolean]
+      def trust_no_proxies?
+        @trust_no_proxies
+      end
+
+      # Whether this config's request handling DEPENDS on Rack's process-global
+      # forwarding family — i.e. it actually reads a forwarded chain. True for
+      # filter and depth mode; false for trust-nobody (reads nothing) and for
+      # unconfigured apps.
+      #
+      # @return [Boolean]
+      def forwarding_family_dependent?
         trusted_proxies_configured? || trusted_proxy_depth_mode?
       end
 
@@ -290,6 +518,7 @@ class Otto
 
         validate_trusted_proxy_depth!(depth)
         raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if depth.to_i >= 1 && @trusted_proxies.any?
+        raise ArgumentError, TRUST_NO_PROXIES_CONFLICT_MESSAGE if depth.to_i >= 1 && @trust_no_proxies
         # Depth-then-geo assignment order is caught by configure_ip_privacy;
         # this catches geo-then-depth so both orders fail eagerly.
         raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE if depth.to_i >= 1 && @ip_privacy_config&.geo_header
@@ -297,10 +526,15 @@ class Otto
         @trusted_proxy_depth = depth
       end
 
-      # Select which forwarded header depth mode counts hops from:
-      # 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239), or 'Both'. Only
-      # consulted when depth mode is active (#trusted_proxy_depth_mode?);
-      # CIDR-walk always uses X-Forwarded-For / X-Real-IP / X-Client-IP.
+      # Select which forwarded header family Otto and Rack read from:
+      # 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239), or 'Both'
+      # (Forwarded when present, else X-Forwarded-For).
+      #
+      # Otto consults the value in count-based depth mode
+      # (#trusted_proxy_depth_mode?) to pick the chain it counts hops from.
+      # CIDR-walk always resolves from X-Forwarded-For / X-Real-IP /
+      # X-Client-IP, so 'Forwarded' and 'Both' are rejected once trusted_proxies
+      # are configured (and vice versa in #add_trusted_proxy).
       #
       # The value is matched case-insensitively (surrounding whitespace ignored)
       # and stored in its canonical spelling, so a hand-edited config can write
@@ -309,13 +543,64 @@ class Otto
       # header, the way a permissive default would), so a typo surfaces at config
       # time instead of as subtly-wrong client IPs at request time.
       #
+      # Applying this setting also pins Rack::Request.forwarded_priority to the
+      # corresponding family. Rack exposes that policy process-wide, so every
+      # Otto application in one process must agree; see
+      # Config.apply_rack_forwarding_family!.
+      #
       # @param header [String] one of TRUSTED_PROXY_HEADERS (case-insensitive)
       # @raise [FrozenError] if configuration is frozen
-      # @raise [ArgumentError] if header is not a recognized value
+      # @raise [ArgumentError] if header is not a recognized value, conflicts
+      #   with configured trusted_proxies, or conflicts with another Otto
+      #   application's explicit choice in this process
       def trusted_proxy_header=(header)
         ensure_not_frozen!
 
-        @trusted_proxy_header = canonicalize_trusted_proxy_header(header)
+        canonical_header = canonicalize_trusted_proxy_header(header)
+        cidr_conflict = canonical_header != DEFAULT_TRUSTED_PROXY_HEADER && @trusted_proxies.any?
+        raise ArgumentError, FORWARDED_HEADER_CIDR_CONFLICT_MESSAGE if cidr_conflict
+
+        self.class.apply_rack_forwarding_family!(self, canonical_header)
+        @trusted_proxy_header = canonical_header
+      end
+
+      # Align Rack's forwarding family with this config's current value. Used by
+      # Otto.new when no trusted_proxy_header option was given, so a bare app
+      # still pins Rack to X-Forwarded-For instead of inheriting Rack's
+      # process-global default. The pin is a commitment only when this config
+      # already depends on the family (proxy trust configured); otherwise it
+      # defers to any commitment made elsewhere in the process.
+      #
+      # @raise [FrozenError] if configuration is frozen
+      # @return [void]
+      def apply_default_rack_forwarding_family!
+        ensure_not_frozen!
+
+        self.class.apply_rack_forwarding_family!(self, @trusted_proxy_header, claim: forwarding_family_dependent?)
+      end
+
+      # Commit this config's current family process-wide once it depends on
+      # one (proxy trust configured). Not called from the trusted_proxies /
+      # depth setters themselves, so assignment order relative to
+      # trusted_proxy_header= cannot raise a spurious conflict; instead it runs
+      # at the configuration boundaries: Otto.new
+      # (#apply_default_rack_forwarding_family!), Configurator#configure, and
+      # freeze (#validate_trusted_proxy_config!). A no-op without proxy trust.
+      #
+      # @raise [ArgumentError] on a conflict with another committed config
+      # @return [void]
+      def commit_rack_forwarding_family!
+        ensure_not_frozen!
+        return unless forwarding_family_dependent?
+
+        self.class.apply_rack_forwarding_family!(self, @trusted_proxy_header)
+      end
+
+      # Whether trusted_proxy_header is the X-Forwarded-For default.
+      #
+      # @return [Boolean]
+      def default_trusted_proxy_header?
+        @trusted_proxy_header == DEFAULT_TRUSTED_PROXY_HEADER
       end
 
       # Validate that a request size is within acceptable limits
@@ -334,6 +619,28 @@ class Otto
         true
       end
 
+      # Set the MCP authenticator used by Otto::MCP::Auth::TokenMiddleware.
+      #
+      # Validated eagerly (must be nil or respond to #authenticate) so a
+      # mis-wired authenticator fails at configuration time rather than by
+      # letting unauthenticated MCP requests through at request time. The
+      # middleware fails closed when this is nil, so clearing it disables the
+      # endpoint rather than opening it.
+      #
+      # @param auth [#authenticate, nil]
+      # @raise [FrozenError] if configuration is frozen
+      # @raise [ArgumentError] if auth does not respond to #authenticate
+      def mcp_auth=(auth)
+        ensure_not_frozen!
+
+        unless auth.nil? || auth.respond_to?(:authenticate)
+          raise ArgumentError,
+                "MCP auth must respond to #authenticate (or be nil), got #{auth.class}"
+        end
+
+        @mcp_auth = auth
+      end
+
       # Set the server-side secret used to sign (HMAC) CSRF tokens. Set this to
       # a stable value (e.g. ENV['OTTO_CSRF_SECRET']) in multi-process or
       # multi-host deployments so tokens stay valid across workers and restarts.
@@ -837,15 +1144,22 @@ class Otto
       def validate_trusted_proxy_config!
         validate_trusted_proxy_header!(@trusted_proxy_header)
         validate_trusted_proxy_depth!(@trusted_proxy_depth)
-        return if @trusted_proxy_depth.nil?
+        raise ArgumentError, FORWARDED_HEADER_CIDR_CONFLICT_MESSAGE if !default_trusted_proxy_header? && @trusted_proxies.any?
 
-        raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if @trusted_proxy_depth >= 1 && @trusted_proxies.any?
+        raise ArgumentError, TRUST_NO_PROXIES_CONFLICT_MESSAGE if @trust_no_proxies && (@trusted_proxies.any? || @trusted_proxy_depth.to_i >= 1)
 
-        # Backstop for the direct path (ip_privacy_config.geo_header=) that
-        # bypasses both eager checks; the setters cover the common orders.
-        return unless @trusted_proxy_depth >= 1 && @ip_privacy_config&.geo_header
+        if @trusted_proxy_depth
+          raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if @trusted_proxy_depth >= 1 && @trusted_proxies.any?
+
+          # Backstop for the direct path (ip_privacy_config.geo_header=) that
+          # bypasses both eager checks; the setters cover the common orders.
+          raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE if @trusted_proxy_depth >= 1 && @ip_privacy_config&.geo_header
+        end
 
-        raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE
+        # Last, so a config that fails the checks above never registers as an
+        # owner: late-configured proxy trust (after Otto.new) commits here at
+        # the latest, so a process-wide family conflict still fails loud.
+        commit_rack_forwarding_family!
       end
 
       # Parse a value into an IPAddr, returning nil for invalid / non-IP input.

data/lib/otto/security/configurator.rb

@@ -35,13 +35,17 @@ class Otto
       # @param rate_limiting [Boolean, Hash] Enable rate limiting
       #   - `true`: Enable with default settings
       #   - `Hash`: Provide custom rate limiting rules
-      # @param trusted_proxies [String, Array<String>] IP addresses or CIDR ranges to trust
+      # @param trusted_proxies [String, Array<String>, Symbol] IP addresses or
+      #   CIDR ranges to trust, or :none to assert that no proxy is trusted
       # @param trusted_proxy_depth [Integer, nil] Count-based proxy depth ("trust
       #   the last N hops") for non-enumerable proxy tiers; mutually exclusive
       #   with trusted_proxies (validated at configuration freeze)
       # @param trusted_proxy_header [String, nil] Forwarded header depth mode
       #   counts hops from: 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239),
-      #   or 'Both'. Only consulted in depth mode.
+      #   or 'Both'. Otto reads it only in depth mode, but setting it always
+      #   pins Rack::Request.forwarded_priority (process-global) to that family
+      #   and claims the family for this process; see
+      #   Otto::Security::Config.apply_rack_forwarding_family!.
       # @param security_headers [Hash] Custom security headers to merge with defaults
       # @param hsts [Boolean] Enable HTTP Strict Transport Security
       # @param csp [Boolean, String] Enable Content Security Policy
@@ -76,9 +80,19 @@ class Otto
         enable_request_validation! if request_validation
         enable_rate_limiting!(rate_limiting.is_a?(Hash) ? rate_limiting : {}) if rate_limiting
 
-        Array(trusted_proxies).each { |proxy| add_trusted_proxy(proxy) }
+        if Otto::Security::Config.trust_no_proxies_option?(trusted_proxies)
+          trust_no_proxies!
+        else
+          # Pass the list whole so add_trusted_proxy validates every entry
+          # before registering any; a mixed list like ['10.0.0.0/8', 'none']
+          # must not leave the first half installed.
+          add_trusted_proxy(Array(trusted_proxies)) unless Array(trusted_proxies).empty?
+        end
         self.trusted_proxy_depth = trusted_proxy_depth unless trusted_proxy_depth.nil?
         self.trusted_proxy_header = trusted_proxy_header unless trusted_proxy_header.nil?
+        # Proxy trust configured here (after Otto.new) commits the app to its
+        # forwarding family now rather than at freeze.
+        @security_config.commit_rack_forwarding_family!
         self.security_headers = security_headers unless security_headers.empty?
 
         enable_hsts! if hsts
@@ -114,6 +128,7 @@ class Otto
       def enable_rate_limiting!(options = {})
         return if middleware_enabled?(Otto::Security::Middleware::RateLimitMiddleware)
 
+        Otto::Security::RateLimiting.ensure_available!
         configure_rate_limiting(options)
         @middleware_stack.add(Otto::Security::Middleware::RateLimitMiddleware)
       end
@@ -137,6 +152,17 @@ class Otto
         @security_config.add_trusted_proxy(proxy)
       end
 
+      # Assert that NO proxy is trusted (equivalent to `trusted_proxies:
+      # :none`). Makes env['otto.via_trusted_proxy'] false for every peer, so
+      # forwarded client-IP and host/scheme/port carriers are ignored and
+      # stripped. See Otto::Security::Config#trust_no_proxies!.
+      #
+      # @raise [ArgumentError] if trusted proxies or a depth >= 1 are configured
+      # @return [void]
+      def trust_no_proxies!
+        @security_config.trust_no_proxies!
+      end
+
       # Set count-based trusted-proxy depth ("trust the last N hops") for
       # non-enumerable proxy tiers (Fly, cloud load balancers, dynamic reverse
       # proxies). Mutually exclusive with trusted_proxies; the conflict is
@@ -148,9 +174,13 @@ class Otto
       end
 
       # Select which forwarded header depth mode counts hops from:
-      # 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239), or 'Both'. Only
-      # consulted when depth mode is active. Mirrors OneTimeSecret's
-      # site.network.trusted_proxy.header.
+      # 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239), or 'Both'. Otto
+      # reads the value only when depth mode is active, but setting it always
+      # pins Rack::Request.forwarded_priority (process-global) to that family
+      # and claims the family for this process, even under
+      # `trusted_proxies: :none`; see
+      # Otto::Security::Config.apply_rack_forwarding_family!. Mirrors
+      # OneTimeSecret's site.network.trusted_proxy.header.
       #
       # @param header [String] one of Otto::Security::Config::TRUSTED_PROXY_HEADERS
       def trusted_proxy_header=(header)

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!