otto 2.8.1 → 2.10.0

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

@@ -2,6 +2,8 @@
 #
 # frozen_string_literal: true
 
+require_relative 'request_extras'
+
 class Otto
   module Security
     module CSP
@@ -39,6 +41,10 @@ class Otto
         CSP_HEADER = 'content-security-policy'
         CONTENT_TYPE_HEADER = 'content-type'
 
+        # Method#parameters types that declare a keyword parameter (used by
+        # {.supports_extra_directives?}).
+        KEYWORD_PARAM_TYPES = %i[key keyreq].freeze
+
         # Emission modes. `:override` is a deliberate per-request call that
         # REPLACES any existing CSP (the caller owns this response's policy).
         # `:backstop` is a passive layer that DEFERS to an existing CSP (it only
@@ -51,23 +57,26 @@ class Otto
         # written". `policy` is the emitted policy on success, or the pre-existing
         # policy when a `:backstop` deferred to one. `skip_reason` is one of
         # `:disabled`, `:blank_nonce`, `:non_html`, `:existing_csp` when skipped,
-        # else nil.
+        # else nil. `extra_directives` carries the request-scoped extras that
+        # were ACTUALLY folded into the policy — entries dropped during the
+        # append (absent directive) are excluded — or nil when none landed.
         class Result
           # Recognized skip reasons, in the order {Writer.apply} evaluates them.
           SKIP_REASONS = %i[disabled blank_nonce non_html existing_csp].freeze
 
-          attr_reader :policy, :skip_reason, :mode
+          attr_reader :policy, :skip_reason, :mode, :extra_directives
 
-          def initialize(applied:, mode:, policy: nil, skip_reason: nil)
+          def initialize(applied:, mode:, policy: nil, skip_reason: nil, extra_directives: nil)
             @applied = applied
             @mode = mode
             @policy = policy
             @skip_reason = skip_reason
+            @extra_directives = extra_directives
           end
 
           # Build an "applied" result for a written policy.
-          def self.applied(policy, mode:)
-            new(applied: true, mode: mode, policy: policy)
+          def self.applied(policy, mode:, extra_directives: nil)
+            new(applied: true, mode: mode, policy: policy, extra_directives: extra_directives)
           end
 
           # Build a "skipped" result. `policy` carries the pre-existing policy for
@@ -96,23 +105,35 @@ class Otto
         #   and the policy string ({Otto::Security::Config#generate_nonce_csp}).
         # @param mode [Symbol] one of {MODES}.
         # @param development_mode [Boolean] use the development directive set.
+        # @param env [Hash, nil] the Rack environment. When given AND the
+        #   config has opted the channel in
+        #   ({Otto::Security::Config#enable_csp_request_extras!}), any
+        #   request-scoped directive extras the app wrote to
+        #   `env['otto.csp.extra_directives']` are sanitized
+        #   ({Otto::Security::CSP::RequestExtras.from_env}) and folded
+        #   ADDITIVELY into the policy. Nil (surfaces with no env in hand)
+        #   simply builds the policy without extras; without the opt-in the
+        #   env key is ignored entirely.
         # @return [Result]
         # @raise [ArgumentError] if mode is not one of {MODES}
         # @raise [FrozenError] if a write is attempted against a frozen headers hash
-        def self.apply(headers, nonce, config:, mode: :override, development_mode: false)
+        def self.apply(headers, nonce, config:, mode: :override, development_mode: false, env: nil)
           unless MODES.include?(mode)
             raise ArgumentError, "mode must be one of #{MODES.join(', ')}, got #{mode.inspect}"
           end
 
-          result = evaluate(headers, nonce, config, mode, development_mode)
+          result = evaluate(headers, nonce, config, mode, development_mode, env)
           log_debug(config, result)
           result
         end
 
         # Guarded core: returns a Result and performs the in-place write when it
         # applies. Guards are evaluated most-fundamental first so the reported
-        # skip_reason is stable and meaningful.
-        def self.evaluate(headers, nonce, config, mode, development_mode)
+        # skip_reason is stable and meaningful. Request-scoped extras are
+        # resolved only once every guard has passed — so a skipped response
+        # never logs extras drops for a policy that was never built — and only
+        # when the config opted the channel in (see {.resolve_extras}).
+        def self.evaluate(headers, nonce, config, mode, development_mode, env)
           return Result.skipped(:disabled, mode: mode) unless enabled?(config)
           return Result.skipped(:blank_nonce, mode: mode) if blank?(nonce)
           return Result.skipped(:non_html, mode: mode) unless html_response?(headers)
@@ -120,12 +141,126 @@ class Otto
           existing = existing_csp(headers)
           return Result.skipped(:existing_csp, mode: mode, policy: existing) if existing && mode == :backstop
 
-          policy = config.generate_nonce_csp(nonce, development_mode: development_mode)
+          extras = resolve_extras(config, env)
+          policy, applied_extras = build_policy(config, nonce, development_mode, extras, env)
           write_csp(headers, policy)
-          Result.applied(policy, mode: mode)
+          Result.applied(policy, mode: mode, extra_directives: applied_extras)
         end
         private_class_method :evaluate
 
+        # Build the policy string, folding in the request-scoped extras when
+        # the config supports them. Returns `[policy, applied_extras]` where
+        # applied_extras is the hash of extras entries that ACTUALLY landed in
+        # the policy (nil when none did), as reported back by
+        # {Policy.append_extra_sources} through the outcome block — never the
+        # pre-append input, so {Result#extra_directives} and the debug log can
+        # only claim what happened. Entries the append dropped (absent
+        # directive) are logged HERE, the one place with the env in hand, with
+        # full request context; Policy stays a pure function of its arguments.
+        #
+        # Configs are duck-typed (see {.enabled?}): one with the pre-#243
+        # `generate_nonce_csp` signature would raise ArgumentError on the
+        # `extra_directives:` kwarg at request time — violating the extras
+        # channel's never-raises invariant — so the kwarg is passed only when
+        # the signature declares it. Otherwise the historical call shape is
+        # used and the extras are dropped with a single structured warn
+        # (`reason: :config_without_extras_support`).
+        #
+        # Declaring the kwarg is only half the duck-config protocol: opting
+        # in means BOTH accepting `extra_directives:` AND invoking the
+        # outcome block. A config that takes the kwarg but never yields
+        # leaves the outcome unknown — its policy string is still used as
+        # returned, but no applied extras are reported
+        # ({Result#extra_directives} stays nil; never fabricated from the
+        # pre-append input) and a single structured warn
+        # (`reason: :config_outcome_not_reported`) flags the gap.
+        def self.build_policy(config, nonce, development_mode, extras, env)
+          return [config.generate_nonce_csp(nonce, development_mode: development_mode), nil] if extras.nil?
+
+          unless supports_extra_directives?(config)
+            Otto.structured_log(
+              :warn, 'CSP request extras dropped',
+              Otto::LoggingHelpers.request_context(env).merge(
+                directives: extras.keys.join(' '),
+                reason: :config_without_extras_support
+              )
+            )
+            return [config.generate_nonce_csp(nonce, development_mode: development_mode), nil]
+          end
+
+          applied = nil
+          reported = false
+          policy = config.generate_nonce_csp(
+            nonce, development_mode: development_mode, extra_directives: extras
+          ) do |applied_extras, dropped_extras|
+            reported = true
+            applied = applied_extras unless applied_extras.empty?
+            log_dropped_extras(env, dropped_extras)
+          end
+          unless reported
+            Otto.structured_log(
+              :warn, 'CSP request extras outcome unreported',
+              Otto::LoggingHelpers.request_context(env).merge(
+                directives: extras.keys.join(' '),
+                reason: :config_outcome_not_reported
+              )
+            )
+          end
+          [policy, applied]
+        end
+        private_class_method :build_policy
+
+        # Whether the config's generate_nonce_csp declares the
+        # `extra_directives:` keyword (or accepts arbitrary keywords).
+        def self.supports_extra_directives?(config)
+          parameters = config.method(:generate_nonce_csp).parameters
+          parameters.any? { |type, name| KEYWORD_PARAM_TYPES.include?(type) && name == :extra_directives } ||
+            parameters.any? { |type, _name| type == :keyrest }
+        rescue NameError
+          false
+        end
+        private_class_method :supports_extra_directives?
+
+        # Log each extras entry the policy build dropped, once per entry, with
+        # full request context. The reason distinguishes the two ways an entry
+        # fails to land: its directive was absent from the built policy
+        # (:absent_directive) or the directive takes no value at all, so a
+        # source could never be appended to it (:valueless_directive) — the
+        # latter is an app bug worth naming precisely, since the entry is a
+        # no-op rather than a policy gap.
+        def self.log_dropped_extras(env, dropped)
+          return if dropped.nil? || dropped.empty?
+
+          context = Otto::LoggingHelpers.request_context(env)
+          dropped.each do |name, tokens|
+            reason = Policy.valueless_directive?(name) ? :valueless_directive : :absent_directive
+            Otto.structured_log(
+              :warn, 'CSP request extra dropped',
+              context.merge(
+                directive: name,
+                token: Array(tokens).join(' ').inspect.slice(0, 128),
+                reason: reason
+              )
+            )
+          end
+        end
+        private_class_method :log_dropped_extras
+
+        # Resolve the request-scoped extras, gated on the boot-time opt-in.
+        # The env key is a write surface ANY middleware in the Rack stack can
+        # reach — a lower-trust position than boot code — so the channel does
+        # not exist until {Otto::Security::Config#enable_csp_request_extras!}
+        # was called: when disabled (including duck-typed configs without the
+        # predicate) the env key is ignored entirely, with no sanitize work
+        # and no logs.
+        def self.resolve_extras(config, env)
+          return nil unless env
+          return nil unless config.respond_to?(:csp_request_extras_enabled?) && config.csp_request_extras_enabled?
+
+          RequestExtras.from_env(env)
+        end
+        private_class_method :resolve_extras
+
         # In-place, key-scoped write. Delete any case-variant of the CSP key
         # (correcting a downstream SPEC violation), then write the canonical
         # lowercase key into the caller's hash. Variant keys are collected before
@@ -182,12 +317,18 @@ class Otto
 
         # Uniform debug observability: when the config opts into CSP debugging,
         # log the outcome — applied policy OR skip reason — so "why didn't my page
-        # get a CSP?" no longer needs a debugger.
+        # get a CSP?" no longer needs a debugger. When request-scoped extras
+        # were folded in, note which directives and how many tokens: the
+        # EmitMiddleware backstop is otherwise silent about them, so this is
+        # the observable trace that a request's extras actually landed.
         def self.log_debug(config, result)
           return unless config.respond_to?(:debug_csp?) && config.debug_csp?
           return unless defined?(Otto.logger) && Otto.logger
 
           detail = result.applied? ? "applied (#{result.mode}) #{result.policy}" : "skipped (#{result.skip_reason})"
+          if (extras = result.extra_directives)
+            detail += " extras[#{extras.keys.join(' ')}](#{extras.each_value.sum(&:length)} tokens)"
+          end
           Otto.logger.debug("[CSP] #{detail}")
         end
         private_class_method :log_debug

data/lib/otto/security/csp.rb

@@ -14,6 +14,10 @@
 #                  Result object, :override / :backstop modes) that every surface
 #                  routes through: Otto::Response#apply_csp, the EmitMiddleware,
 #                  and the deprecated Otto::Response#send_csp_headers shim.
+# - RequestExtras — reads + sanitizes the opt-in request-scoped directive
+#                  extras from env['otto.csp.extra_directives'] (delano/otto#243);
+#                  the Writer folds the survivors in additively via
+#                  Policy.append_extra_sources.
 # - EmitMiddleware — passive backstop that emits a nonce CSP for responses whose
 #                  request consumed a nonce (emit-if-consumed). See
 #                  Otto::Security::Core#enable_csp_emission!.
@@ -23,6 +27,7 @@
 #   callback API. See Otto::Security::Core#enable_csp_reporting!.
 
 require_relative 'csp/policy'
+require_relative 'csp/request_extras'
 require_relative 'csp/nonce'
 require_relative 'csp/writer'
 require_relative 'csp/report'

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/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.8.1'
+  VERSION = '2.10.0'
 end