otto 2.3.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50aa75316f4a3f73a0784cf78fb29e05c030901fa75ac1b8285a6ec0ad89fc3b
-  data.tar.gz: 38c18d2dc357589e1377a5df0cecd0de26370b002061d9bde6d66994b4990610
+  metadata.gz: 72c7a8fdbc299b202666d5f94532e4eed6d3fc2b2ee6a58234519deba65bfb0c
+  data.tar.gz: d82daec0441d3e9a8c196e6306aa8945292b8a322e3acbdf146294bc55345782
 SHA512:
-  metadata.gz: e5f9c0693f83c423a77b20ac88c6af74db6c3d4a9ea345304085b31249a1d20537d64d5c091c5ffb5f6382bfd3fe291d4bcc85f5949928ef09ab8ae74fe09c3b
-  data.tar.gz: 29fb704139356b0e0df805567e761593b10faf519f7977087425f9752711dfe4315b41266d864c071779f1e37b55e1a9d40c454c74f5973f728f3f1e1ff1bb97
+  metadata.gz: 64e1787e35c416585076ba4befa922c4306f0f023cba463877a66b821ab9e1518e3afda4edd6e8a319a04750c3c29d5b79196fc4961f807438b1f27eed4d0687
+  data.tar.gz: e6384fc6c848c602ea4c7f2c7eee7aaab7a715df054e404d6660e9c72fb85b52f4ff0a98108121a4995fe401a09bc67bcb459d0e37d00f4897a42df6b90d2d10

data/.github/workflows/claude-code-review.yml

@@ -51,7 +51,7 @@ jobs:
             - Security concerns
             - Test coverage
 
-            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+            Use the repository's CLAUDE.md or AGENTS.md for guidance on style and conventions. Be constructive and helpful in your feedback.
 
           # Use sticky comments to reuse the same comment on subsequent pushes to the same PR
           use_sticky_comment: true

data/.github/workflows/claude.yml

@@ -32,10 +32,15 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@beta
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
+          # Fall back to Sonnet when the primary model is unavailable/overloaded.
+          # Without this, an unavailable primary surfaces as "Claude encountered
+          # an error" and fails the claude-review check.
+          fallback_model: "claude-sonnet-4-6"
+
           # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |
             actions: read

data/CHANGELOG.rst

@@ -7,6 +7,31 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.3.1:
+
+2.3.1 — 2026-06-22
+==================
+
+Added
+-----
+
+- Depth mode (``Otto::Security::Config#trusted_proxy_depth``) can now count hops
+  from a configurable forwarded header, via a new ``#trusted_proxy_header``
+  accessor: ``X-Forwarded-For`` (default), ``Forwarded`` (RFC 7239), or ``Both``
+  (``Forwarded`` when it carries a ``for=``, otherwise ``X-Forwarded-For``).
+  Settable through ``Otto::Security::Configurator#configure`` and the
+  ``trusted_proxy_header`` option of ``Otto.new`` / ``configure_security``; an
+  unrecognized value raises ``ArgumentError`` at assignment. This reaches parity
+  with OneTimeSecret's ``site.network.trusted_proxy.header``. (delano/otto#150,
+  onetimesecret#3436)
+
+AI Assistance
+-------------
+
+- RFC 7239 ``Forwarded`` / ``Both`` depth-header support designed and implemented
+  with AI pair programming, with per-header, quoted-IPv6, and ``Both``-precedence
+  test coverage.
+
 .. _changelog-2.3.0:
 
 2.3.0 — 2026-06-21

data/Gemfile

@@ -27,6 +27,7 @@ group :development do
   gem 'benchmark'
   gem 'debug'
   gem 'rackup' # Used to boot examples/ apps; not needed by specs
+  gem 'rake', '~> 13.0', require: false # Provides `rake release` for release-gem.yml
   gem 'rubocop', '~> 1.86.2', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rspec', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.3.0)
+    otto (2.3.1)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
@@ -113,6 +113,7 @@ GEM
     rackup (2.3.1)
       rack (>= 3)
     rainbow (3.1.1)
+    rake (13.1.0)
     rbs (4.0.2)
       logger
       prism (>= 1.6.0)
@@ -216,6 +217,7 @@ DEPENDENCIES
   rack-attack
   rack-test
   rackup
+  rake (~> 13.0)
   reek (~> 6.5)
   rspec (~> 3.13)
   rubocop (~> 1.86.2)

data/Rakefile

@@ -0,0 +1,21 @@
+# Rakefile
+#
+# frozen_string_literal: true
+
+# `bundler/gem_tasks` defines the build/install/release tasks the
+# release-gem.yml workflow drives via `bundle exec rake release`
+# (RubyGems Trusted Publishing). `rake release` builds the gem, pushes the
+# git tag (a no-op when the release tag already exists), and publishes to
+# RubyGems.
+require 'bundler/gem_tasks'
+
+# Make `rake` (no task) run the specs, mirroring CI's `bundle exec rspec`.
+# Guarded so `rake release` still works in an install without the test
+# group (rspec lives in the :test group).
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+  # rspec unavailable (e.g. a production/release-only bundle); skip the task.
+end

data/docs/migrating/v2.3.0.md

@@ -181,9 +181,11 @@ entry is not a valid IP, the resolver returns `REMOTE_ADDR` rather than a
 spoofable forwarded value. This is intentionally **stricter than Express**, which
 returns the leftmost (most spoofable) forwarded entry in that case.
 
-**`X-Forwarded-For` only.** Depth mode consults **only** `X-Forwarded-For`.
-`X-Real-IP` and `X-Client-IP` are single-value headers that cannot express a hop
-chain, so they are ignored in depth mode (CIDR-walk still consults them).
+**Single-value headers are never consulted.** `X-Real-IP` and `X-Client-IP`
+cannot express a hop chain, so depth mode ignores them (CIDR-walk still consults
+them). Which *multi-hop* header depth counts from — `X-Forwarded-For` (default),
+the RFC 7239 `Forwarded` header, or `Both` — is configurable as of 2.3.1; see
+*Selecting the forwarded header* below.
 
 **`secure?` is independent of depth.** Depth mode resolves the client **IP**
 only; it does **not** grant proxy trust for `X-Forwarded-Proto` / `X-Scheme`.
@@ -195,6 +197,51 @@ check is `false` under depth, so `secure?` does not honor a forwarded proto and
 reflects only a direct TLS connection (`HTTPS=on` / port 443). This mirrors the
 downstream (OneTimeSecret) behavior: proto-trust is never derived from depth.
 
+### Selecting the forwarded header (added in 2.3.1)
+
+By default depth counts hops from `X-Forwarded-For`. Deployments fronted by a
+proxy that emits the RFC 7239 `Forwarded` header can change the source via
+`trusted_proxy_header`, mirroring OneTimeSecret's
+`site.network.trusted_proxy.header`:
+
+```ruby
+otto.security_config.trusted_proxy_header = 'Forwarded'   # RFC 7239 only
+
+# or via the facade / construction options, alongside the depth:
+otto.security.configure(trusted_proxy_depth: 1, trusted_proxy_header: 'Both')
+Otto.new(routes, trusted_proxy_depth: 1, trusted_proxy_header: 'Forwarded')
+```
+
+| Value | Chain source |
+|-------|--------------|
+| `'X-Forwarded-For'` (default) | `X-Forwarded-For` |
+| `'Forwarded'` | RFC 7239 `Forwarded` — the `for=` of each forwarded-element |
+| `'Both'` | `Forwarded` when it carries a `for=`, otherwise `X-Forwarded-For` |
+
+- **`Both` precedence is fallback, not merge.** If the `Forwarded` header carries
+  at least one `for=`, only its chain is used and `X-Forwarded-For` is ignored;
+  otherwise the `X-Forwarded-For` chain is used. The two chains are never
+  concatenated. (Matches OTS's
+  `extract_rfc7239_forwarded(env) || extract_x_forwarded_for(env)`.)
+- **RFC 7239 parsing.** Each comma-separated forwarded-element is one hop; its
+  `for=` parameter is read case-insensitively and unquoted. Quoted IPv6 with a
+  port (`for="[2001:db8::1]:443"`) resolves to `2001:db8::1`. Obfuscated
+  (`for=_hidden`) and `for=unknown` identifiers still occupy a hop position but
+  are not valid IPs, so if one is the selected hop the resolver falls back to
+  `REMOTE_ADDR`. Multiple `Forwarded` headers (joined by Rack into one
+  comma-separated value) are handled.
+- **Raw position counting is preserved** in all three modes: elements are never
+  dropped before counting (an element without a `for=` still counts as a hop),
+  so padding cannot shift the index; only the selected hop is validated.
+- **Depth mode only.** `trusted_proxy_header` is consulted solely in depth mode;
+  CIDR-walk is unaffected.
+- **Lenient spelling, strict validation.** The value is matched
+  case-insensitively with surrounding whitespace ignored (`forwarded`, `both`,
+  `  X-Forwarded-For ` all work) and stored canonicalized. A genuinely
+  unrecognized value raises `ArgumentError` at assignment rather than silently
+  falling back to a default header — a typo surfaces at config time instead of
+  as subtly-wrong client IPs at request time.
+
 ### Security prerequisite: origin lockdown
 
 > **Depth trust assumes your app is unreachable except through the proxy tier.**

data/lib/otto/core/configuration.rb

@@ -59,7 +59,15 @@ class Otto
 
         # Set count-based trusted-proxy depth if provided (mutually exclusive
         # with trusted_proxies; conflict validated at configuration freeze).
-        @security_config.trusted_proxy_depth = opts[:trusted_proxy_depth] if opts[:trusted_proxy_depth]
+        # Guard on presence (`unless nil?`), not truthiness, so an explicitly
+        # provided invalid value (e.g. `false`) reaches the validating setter
+        # and fails loud instead of being silently dropped.
+        @security_config.trusted_proxy_depth = opts[:trusted_proxy_depth] unless opts[:trusted_proxy_depth].nil?
+
+        # Select the forwarded header depth mode reads from ('X-Forwarded-For',
+        # 'Forwarded', or 'Both'). Only consulted in depth mode. Same presence
+        # guard: a provided-but-invalid value is validated, not ignored.
+        @security_config.trusted_proxy_header = opts[:trusted_proxy_header] unless opts[:trusted_proxy_header].nil?
 
         # Set custom security headers
         return unless opts[:security_headers]

data/lib/otto/security/config.rb

@@ -37,6 +37,13 @@ class Otto
         hop count, not both.
       MSG
 
+      # 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
+      # OneTimeSecret's site.network.trusted_proxy.header. Only consulted in
+      # depth mode; CIDR-walk is unaffected.
+      TRUSTED_PROXY_HEADERS = %w[X-Forwarded-For Forwarded Both].freeze
+
       # Error raised when CSRF protection is enabled in production without an
       # explicitly configured secret. A randomly-generated per-process secret
       # silently breaks token verification across workers and restarts, so we
@@ -56,7 +63,7 @@ class Otto
                   :trusted_proxies, :require_secure_cookies,
                   :security_headers,
                   :csp_nonce_enabled, :debug_csp, :mcp_auth,
-                  :ip_privacy_config, :trusted_proxy_depth
+                  :ip_privacy_config, :trusted_proxy_depth, :trusted_proxy_header
 
       # Initialize security configuration with safe defaults
       #
@@ -73,6 +80,7 @@ class Otto
         @trusted_proxies        = []
         @trusted_proxy_matchers = []
         @trusted_proxy_depth    = nil
+        @trusted_proxy_header   = 'X-Forwarded-For'
         @require_secure_cookies = false
         @security_headers       = default_security_headers
         @input_validation       = true
@@ -225,6 +233,27 @@ 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.
+      #
+      # The value is matched case-insensitively (surrounding whitespace ignored)
+      # and stored in its canonical spelling, so a hand-edited config can write
+      # `forwarded` or `both` without surprise. A genuinely unrecognized value
+      # fails loud at assignment (rather than silently resolving from the wrong
+      # header, the way a permissive default would), so a typo surfaces at config
+      # time instead of as subtly-wrong client IPs at request time.
+      #
+      # @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
+      def trusted_proxy_header=(header)
+        ensure_not_frozen!
+
+        @trusted_proxy_header = canonicalize_trusted_proxy_header(header)
+      end
+
       # Validate that a request size is within acceptable limits
       #
       # @param content_length [String, Integer, nil] Content-Length header value
@@ -453,6 +482,42 @@ class Otto
         raise ArgumentError, "trusted_proxy_depth must be >= 0, got #{depth}" if depth.negative?
       end
 
+      # Canonicalize a candidate trusted_proxy_header value: match it
+      # case-insensitively (ignoring surrounding whitespace) against the
+      # recognized set and return the canonical spelling. Liberal in the spelling
+      # it accepts (e.g. 'forwarded' => 'Forwarded') but fail-loud on a genuinely
+      # unrecognized value, so a typo is caught at config time rather than
+      # silently resolving the client IP from the wrong header.
+      #
+      # @param header [Object] candidate value
+      # @raise [ArgumentError] if header is not one of TRUSTED_PROXY_HEADERS
+      # @return [String] the canonical header value
+      def canonicalize_trusted_proxy_header(header)
+        candidate = header.to_s.strip
+        canonical = TRUSTED_PROXY_HEADERS.find { |allowed| allowed.casecmp?(candidate) }
+        return canonical if canonical
+
+        raise ArgumentError,
+              "trusted_proxy_header must be one of #{TRUSTED_PROXY_HEADERS.join(', ')}, got #{header.inspect}"
+      end
+
+      # Strictly validate a stored trusted_proxy_header value against the allowed
+      # set. The eager #trusted_proxy_header= setter already canonicalizes, so by
+      # freeze time the value is canonical; this freeze-time backstop catches a
+      # value smuggled in through a direct-ivar path that bypassed the setter,
+      # failing loud rather than silently mis-resolving the client IP at request
+      # time.
+      #
+      # @param header [Object] candidate value
+      # @raise [ArgumentError] if header is not one of TRUSTED_PROXY_HEADERS
+      # @return [void]
+      def validate_trusted_proxy_header!(header)
+        return if TRUSTED_PROXY_HEADERS.include?(header)
+
+        raise ArgumentError,
+              "trusted_proxy_header must be one of #{TRUSTED_PROXY_HEADERS.join(', ')}, got #{header.inspect}"
+      end
+
       # Validate trusted-proxy configuration coherence at freeze time.
       #
       # The eager setters (#trusted_proxy_depth=, #add_trusted_proxy) already
@@ -464,6 +529,7 @@ class Otto
       #   trusted_proxies and a depth >= 1 are configured
       # @return [void]
       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?
 

data/lib/otto/security/configurator.rb

@@ -39,6 +39,9 @@ class Otto
       # @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.
       # @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
@@ -62,6 +65,7 @@ class Otto
         rate_limiting: false,
         trusted_proxies: [],
         trusted_proxy_depth: nil,
+        trusted_proxy_header: nil,
         security_headers: {},
         hsts: false,
         csp: false,
@@ -74,6 +78,7 @@ class Otto
 
         Array(trusted_proxies).each { |proxy| add_trusted_proxy(proxy) }
         self.trusted_proxy_depth = trusted_proxy_depth unless trusted_proxy_depth.nil?
+        self.trusted_proxy_header = trusted_proxy_header unless trusted_proxy_header.nil?
         self.security_headers = security_headers unless security_headers.empty?
 
         enable_hsts! if hsts
@@ -142,6 +147,16 @@ class Otto
         @security_config.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. Mirrors OneTimeSecret's
+      # site.network.trusted_proxy.header.
+      #
+      # @param header [String] one of Otto::Security::Config::TRUSTED_PROXY_HEADERS
+      def trusted_proxy_header=(header)
+        @security_config.trusted_proxy_header = header
+      end
+
       # Set custom security headers that will be added to all responses.
       # These merge with the default security headers.
       #

data/lib/otto/utils.rb

@@ -143,37 +143,41 @@ class Otto
     # from the right of the forwarded chain (Express `trust proxy = N`). Used
     # when the proxy tier's addresses cannot be enumerated as CIDRs.
     #
-    # The chain is X-Forwarded-For (leftmost = client .. rightmost = nearest
-    # proxy) plus REMOTE_ADDR (the direct peer). With depth N the client is
-    # chain[-(N+1)] — exactly N trusted hops from the right, equivalent to
-    # Express's addrs[N]. This is robust to X-Forwarded-For padding: a forged
-    # leftmost entry is never reached.
+    # The chain is the configured forwarded header (leftmost = client ..
+    # rightmost = nearest proxy) plus REMOTE_ADDR (the direct peer). With depth
+    # N the client is chain[-(N+1)] — exactly N trusted hops from the right,
+    # equivalent to Express's addrs[N]. This is robust to forwarded-header
+    # padding: a forged leftmost entry is never reached.
     #
     # SECURITY: depth trust ASSUMES ORIGIN LOCKDOWN — the app must be
     # unreachable except through the proxy tier. Without it, a direct client
-    # could pad X-Forwarded-For to land a forged value at the target index.
+    # could pad the forwarded header to land a forged value at the target index.
     # This is the inherent trade vs CIDR-walk (a fixed hop count instead of
     # enumerable proxy addresses).
     #
-    # Only X-Forwarded-For is consulted; X-Real-IP / X-Client-IP are
-    # single-value and cannot express a hop chain. Positions are counted raw
-    # (never dropped), so junk padding cannot shift the index; only the
-    # selected entry is validated. If the chain is shorter than N+1 (a request
-    # that may have bypassed the proxy tier) or the selected entry is invalid,
-    # REMOTE_ADDR is returned rather than a spoofable forwarded value.
+    # The forwarded chain is selected by security_config.trusted_proxy_header:
+    # 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239), or 'Both' (RFC 7239
+    # when it carries a `for=`, otherwise X-Forwarded-For — mirrors
+    # OneTimeSecret's site.network.trusted_proxy.header). X-Real-IP / X-Client-IP
+    # are single-value and cannot express a hop chain, so they are never
+    # consulted in depth mode. Positions are counted raw (never dropped), so junk
+    # padding cannot shift the index; only the selected entry is validated. If
+    # the chain is shorter than N+1 (a request that may have bypassed the proxy
+    # tier) or the selected entry is invalid, REMOTE_ADDR is returned rather than
+    # a spoofable forwarded value.
     #
     # @param env [Hash] Rack environment
-    # @param security_config [Otto::Security::Config] config exposing #trusted_proxy_depth
+    # @param security_config [Otto::Security::Config] config exposing #trusted_proxy_depth and #trusted_proxy_header
     # @return [String, nil] resolved client IP (REMOTE_ADDR on short chain / invalid target)
     def resolve_client_ip_by_depth(env, security_config)
       remote_addr = env['REMOTE_ADDR']
       depth       = security_config.trusted_proxy_depth.to_i
 
-      # Split on commas keeping every position (-1 preserves trailing empty
-      # fields) so a malformed hop still counts as a position. The client must
-      # be located by counting from the right; dropping entries here would let
-      # padding shift the index.
-      forwarded = env['HTTP_X_FORWARDED_FOR'].to_s.split(',', -1)
+      # Build the positional hop chain from the configured header, keeping every
+      # position (junk/empty entries included) so the client can be located by
+      # counting from the right; dropping entries would let padding shift the
+      # index. REMOTE_ADDR (the direct peer) is the rightmost hop.
+      forwarded = forwarded_chain_for_depth(env, security_config.trusted_proxy_header)
       chain     = forwarded + [remote_addr]
 
       index = chain.length - (depth + 1)
@@ -182,6 +186,81 @@ class Otto
       normalize_ip(chain[index].to_s.strip) || remote_addr
     end
 
+    # Positional forwarded-hop chain for depth resolution, selected by header
+    # mode. Each element is one hop (preserving count); values are raw — only the
+    # finally-selected entry is normalized. Mirrors OneTimeSecret's
+    # site.network.trusted_proxy.header semantics.
+    #
+    # @param env [Hash] Rack environment
+    # @param header_mode [String] 'X-Forwarded-For', 'Forwarded', or 'Both'
+    # @return [Array<String>] one entry per hop (may include blank/invalid entries)
+    def forwarded_chain_for_depth(env, header_mode)
+      case header_mode
+      when 'Forwarded'
+        rfc7239_for_chain(env['HTTP_FORWARDED'])
+      when 'Both'
+        # RFC 7239 wins when it carries at least one `for=`; otherwise fall back
+        # to X-Forwarded-For. The chains are NOT merged (matches OTS's
+        # `extract_rfc7239_forwarded(env) || extract_x_forwarded_for(env)`).
+        forwarded = rfc7239_for_chain(env['HTTP_FORWARDED'])
+        forwarded.any? { |entry| !entry.empty? } ? forwarded : xff_chain(env['HTTP_X_FORWARDED_FOR'])
+      else
+        xff_chain(env['HTTP_X_FORWARDED_FOR'])
+      end
+    end
+
+    # Split X-Forwarded-For into raw positional entries. `-1` keeps trailing
+    # empty fields so a malformed/empty hop still counts as a position.
+    #
+    # @param value [String, nil] raw X-Forwarded-For header value
+    # @return [Array<String>]
+    def xff_chain(value)
+      value.to_s.split(',', -1)
+    end
+
+    # Extract the per-hop `for=` chain from an RFC 7239 Forwarded header,
+    # preserving one position per forwarded-element. Elements without a `for=`
+    # parameter yield a blank placeholder so they still occupy a hop position
+    # (raw position counting). The extracted token is only unquoted here; port
+    # and IPv6 brackets are left for normalize_ip when the entry is selected.
+    # Obfuscated (`for=_hidden`) and `for=unknown` identifiers are preserved as
+    # positions but normalize to nil (→ REMOTE_ADDR fallback if selected).
+    # Commas separate forwarded-elements (and join multiple Forwarded headers).
+    # A nil/blank header splits to [] (not ['']), so an absent Forwarded header
+    # yields an empty chain and depth's explicit short-chain guard returns
+    # REMOTE_ADDR — symmetric with xff_chain.
+    #
+    # @param value [String, nil] raw Forwarded header value
+    # @return [Array<String>] one `for=` token per forwarded-element
+    def rfc7239_for_chain(value)
+      value.to_s.split(',', -1).map { |element| rfc7239_for_value(element) }
+    end
+
+    # Pull the `for=` token out of a single RFC 7239 forwarded-element. The value
+    # is a quoted-string (which may itself legally contain ';') or an unquoted
+    # token ending at the next ';'. The quoted form is matched first so a ';'
+    # inside DQUOTEs is NOT treated as a parameter separator — otherwise a value
+    # like for="1.2.3.4;junk" would be truncated to a valid-looking IP instead of
+    # being rejected. Only DQUOTE wrappers are stripped: RFC 7239 quoted-strings
+    # use DQUOTE exclusively, so a value like for='1.2.3.4' keeps its quotes,
+    # fails normalize_ip, and safely falls back to REMOTE_ADDR rather than being
+    # permissively accepted. This is deliberately stricter than OTS (which strips
+    # both ['"]), consistent with depth's other intentionally-not-reconciled-down
+    # safety properties. The raw value (port / IPv6 brackets intact) is left for
+    # normalize_ip when the entry is selected. Returns '' when the element carries
+    # no `for=` parameter, preserving the hop position. The `for=` pair may be the
+    # element's first pair or follow a ';'; leading whitespace (e.g. after a comma
+    # split) is tolerated.
+    #
+    # @param element [String] one forwarded-element (e.g. 'for=1.2.3.4;proto=https')
+    # @return [String]
+    def rfc7239_for_value(element)
+      match = element.match(/(?:\A|;)\s*for=(?:"([^"]*)"|([^;]+))/i)
+      return '' unless match
+
+      (match[1] || match[2]).strip
+    end
+
     # Whether an address is non-public: RFC1918 private, loopback, link-local,
     # multicast, or unspecified — for both IPv4 and IPv6.
     #

data/lib/otto/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.3.1
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -135,6 +135,7 @@ files:
 - Gemfile.lock
 - LICENSE.txt
 - README.md
+- Rakefile
 - bin/rspec
 - changelog.d/README.md
 - changelog.d/scriv.ini