otto 2.2.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0616e034fc5859c42ed2eb48e1d123abdd1b36bca93422cf858d51331843c2c9
-  data.tar.gz: 667c3067cdd71ed41ef733c479798836522c32d37044edeb5f78d33c04b14818
+  metadata.gz: 72c7a8fdbc299b202666d5f94532e4eed6d3fc2b2ee6a58234519deba65bfb0c
+  data.tar.gz: d82daec0441d3e9a8c196e6306aa8945292b8a322e3acbdf146294bc55345782
 SHA512:
-  metadata.gz: c219d4864ffc3090983ee50828279914dc052d0d65f5fd75dbaff812a1fee5d32880c325956d778c9a68e39e396e0f855f271eb3355ddee9d846e186586c57a2
-  data.tar.gz: d32b8d2235fe0d2c95510c4ec5f1623f30a6039bac1a309878af03907458fd9a51ea18f6e5584dfe88754a45cef25469f52ba72bee7847e97b87f2e481672e9d
+  metadata.gz: 64e1787e35c416585076ba4befa922c4306f0f023cba463877a66b821ab9e1518e3afda4edd6e8a319a04750c3c29d5b79196fc4961f807438b1f27eed4d0687
+  data.tar.gz: e6384fc6c848c602ea4c7f2c7eee7aaab7a715df054e404d6660e9c72fb85b52f4ff0a98108121a4995fe401a09bc67bcb459d0e37d00f4897a42df6b90d2d10

data/.github/workflows/ci.yml

@@ -63,7 +63,7 @@ jobs:
             lockfile: "unlocked"
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v6.0.3
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         continue-on-error: ${{ matrix.experimental }}
@@ -74,7 +74,7 @@ jobs:
           bundler-cache: ${{ !matrix.experimental && matrix.lockfile == 'locked' }}
 
       - name: Setup tmate session
-        uses: mxschmitt/action-tmate@c0afd6f790e3a5564914980036ebf83216678101 # v3
+        uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3
         if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
         with:
           detached: true

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

@@ -27,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.3
         with:
           fetch-depth: 1
 
@@ -37,6 +37,11 @@ jobs:
         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"
+
           # Direct prompt for automated review (no @claude mention needed)
           direct_prompt: |
             Please review this pull request and provide feedback on:
@@ -46,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

@@ -26,16 +26,21 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.3
         with:
           fetch-depth: 1
 
       - 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/.github/workflows/code-smells.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.3
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
@@ -88,7 +88,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.3
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/.github/workflows/release-gem.yml

@@ -124,7 +124,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 

data/CHANGELOG.rst

@@ -7,6 +7,195 @@ 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
+==================
+
+Added
+-----
+
+- Count-based trusted-proxy resolution ("trust the last N hops"), the Express
+  ``trust proxy = N`` primitive, via a new
+  ``Otto::Security::Config#trusted_proxy_depth`` accessor (Integer, default
+  ``nil``). ``nil`` / ``0`` keeps the existing CIDR-walk; ``>= 1`` enables depth
+  mode. This is the sound model for non-enumerable proxy tiers (Fly, cloud load
+  balancers, dynamic reverse proxies) whose addresses cannot be listed as CIDRs.
+  Resolution flows through the shared ``Otto::Utils.resolve_client_ip``, so the
+  canonical ``env['otto.client_ip']`` (masking, idempotency, "read everywhere")
+  and the standalone ``Request#client_ipaddress`` fallback both honor depth with
+  no further wiring. Settable through ``Otto::Security::Configurator#configure``
+  (``trusted_proxy_depth:``) and the ``trusted_proxy_depth`` option of
+  ``configure_security``. Depth resolves the client *IP* only; it is decoupled
+  from proxy proto-trust — ``env['otto.via_trusted_proxy']`` (and therefore
+  ``Otto::Request#secure?`` honoring ``X-Forwarded-Proto`` / ``X-Scheme``) remains
+  the trusted-proxy *identity* check and is never derived from hop depth,
+  matching the downstream OneTimeSecret behavior. (onetimesecret#3436,
+  onetimesecret#3116)
+
+Changed
+-------
+
+- ``Otto::Security::Config#trusted_proxy?`` now matches string entries with
+  proper ``IPAddr`` CIDR containment for both IPv4 and IPv6, replacing the
+  previous ``==`` / ``start_with?`` text matching. Bare hosts (e.g.
+  ``192.168.1.1``) match only exactly, and CIDR ranges (e.g. ``10.0.0.0/8``)
+  now actually match contained addresses. Non-IP entries (e.g. ``172.16.``)
+  still fall back to the legacy prefix match, and ``Regexp`` entries are
+  unchanged. This is a behavior change: addresses that were previously
+  matched only because they shared a textual prefix are no longer treated as
+  trusted. (otto#58, onetimesecret#3436)
+- ``IPPrivacyMiddleware`` now resolves the client IP once into a canonical
+  ``env['otto.client_ip']`` ("resolve once, read everywhere") and is
+  idempotent: a second pass (e.g. when the middleware is mounted both at the
+  app and router levels) yields instead of re-resolving and double-masking.
+- ``Otto::Request#ip`` and ``#client_ipaddress`` now prefer
+  ``env['otto.client_ip']`` when present, falling back to Rack's native
+  resolution when the middleware has not run. Downstream code no longer
+  depends on ``REMOTE_ADDR`` / ``X-Forwarded-For`` rewriting being
+  load-bearing.
+- ``Otto::Request#secure?`` now authorizes ``X-Forwarded-Proto`` /
+  ``X-Scheme`` from a canonical, leak-free ``env['otto.via_trusted_proxy']``
+  flag recorded by ``IPPrivacyMiddleware`` before masking, instead of
+  re-deriving trust from the (now masked) ``REMOTE_ADDR``. It falls back to
+  the previous behavior when the middleware has not run.
+- ``add_trusted_proxy`` now logs a warning when given a string that is not a
+  valid IP or CIDR (e.g. ``'172.16.'``), since such entries use legacy
+  string-prefix matching; prefer a CIDR range.
+- IP validation and port-stripping were consolidated into
+  ``Otto::Utils.normalize_ip`` / ``strip_ip_port`` (previously duplicated in
+  ``IPPrivacyMiddleware`` and ``Otto::Request``).
+- Trusted-proxy string entries are now parsed to ``IPAddr`` once at
+  registration (in ``add_trusted_proxy``) and cached, so ``trusted_proxy?``
+  no longer re-parses each entry on every request.
+- Client-IP resolution from forwarded headers is now a single shared
+  ``Otto::Utils.resolve_client_ip`` used by both ``IPPrivacyMiddleware``
+  ("resolve once") and ``Otto::Request#client_ipaddress`` (its no-middleware
+  fallback), so the two paths can no longer disagree on which headers to trust
+  or how to walk a proxy chain. The standalone ``Request`` fallback now walks
+  the forwarded chain skipping trusted proxies (matching the middleware) and
+  consults ``X-Client-IP`` instead of the legacy ``Client-IP`` header.
+
+- ``RouteHandlers::BaseHandler`` raises ``ArgumentError`` (was ``NameError``)
+  for an unresolvable handler class name. (otto#147)
+- ``Otto.logger`` never returns ``nil`` (lazy ``$stdout`` default); assign
+  ``Otto.logger=`` to override or silence. (otto#147)
+
+Removed
+-------
+
+- SQL-injection pattern matching from input validation
+  (``ValidationMiddleware::SQL_INJECTION_PATTERNS`` and related checks). It
+  produced false positives and was trivially bypassable; defend against SQL
+  injection with parameterized queries at the data-access layer. (otto#147)
+
+Fixed
+-----
+
+- IPv6 addresses are no longer truncated during proxy resolution.
+  ``validate_ip_address`` previously did ``ip.split(':').first``, collapsing
+  an IPv6 address to its first hextet; it now uses ``IPAddr`` validation with
+  IPv6-safe port stripping (bracketed ``[2001:db8::1]:443`` and IPv4
+  ``host:port``). IPv6 clients behind trusted proxies now resolve and mask
+  correctly. (onetimesecret#3436)
+- ``Otto::Request#redacted_fingerprint``, ``#geo_country``, ``#hashed_ip``
+  and ``#masked_ip`` (plus ``NoAuthStrategy`` metadata and
+  ``LoggingHelpers`` country) read the canonical ``otto.privacy.*`` env keys
+  the middleware actually writes; they previously read un-namespaced keys
+  that were never set and so always returned ``nil``.
+- ``Otto::Request#private_ip?`` (and therefore ``#local_or_private_ip?`` /
+  ``#local?``) is now IPv4- **and** IPv6-aware via ``Otto::Utils.private_ip?``.
+  It recognizes IPv6 loopback (``::1``), unique-local (``fc00::/7``),
+  link-local (``fe80::/10``), multicast and unspecified addresses; the previous
+  IPv4-only regex silently classified every IPv6 address as public.
+- Anonymous and auth-failure metadata (``NoAuthStrategy``,
+  ``RouteAuthWrapper``) and ``LoggingHelpers.request_context`` now record the
+  canonical ``otto.client_ip`` (falling back to ``REMOTE_ADDR``), so the real
+  client — not the connecting proxy — is logged when IP privacy is disabled
+  behind a trusted proxy.
+
+- The CSRF ``<meta>`` tag is now injected into ``<head>`` tags that carry
+  attributes, not only a bare ``<head>``. (otto#147)
+
+Security
+--------
+
+- Trusted-proxy matching is now correct CIDR containment rather than text
+  prefix matching, removing both false positives (e.g. ``192.168.1.100``
+  matching the host ``192.168.1.1``) and false negatives (CIDR ranges that
+  never matched). ``secure?`` no longer silently fails to trust
+  ``X-Forwarded-Proto`` behind a TLS-terminating trusted proxy when IP
+  privacy is enabled. (onetimesecret#3436)
+
+- CSRF tokens are now signed with HMAC-SHA256 keyed by a server-side secret and
+  bound to the session id, so they can no longer be self-minted or replayed
+  across sessions. Set the secret via ``OTTO_CSRF_SECRET`` or
+  ``Otto::Security::Config#csrf_secret=``; enabling CSRF in production without
+  one now raises instead of silently using a per-process secret. (otto#147)
+- All route/handler class-name resolution goes through
+  ``Otto::Security::ConstantResolver``, extending the existing format check and
+  forbidden-class blocklist to ``RouteHandlers::BaseHandler`` and the MCP
+  registry/server (previously unguarded). Forbidden classes reached via a
+  namespace prefix or constant inheritance (e.g. ``Object::Kernel``) are now
+  rejected as well. (otto#147)
+- MCP bearer tokens and API keys are compared in constant time. (otto#147)
+
+- Depth resolution trusts exactly N hops counted from the right of
+  ``X-Forwarded-For`` plus ``REMOTE_ADDR``, so a forged leftmost forwarded entry
+  is never reached. Positions are counted raw (never dropped) so junk padding
+  cannot shift the index, and only the selected entry is validated. A chain
+  shorter than ``N + 1`` (a request that may have bypassed the proxy tier) or an
+  invalid target entry falls back to ``REMOTE_ADDR`` rather than a spoofable
+  forwarded value. Depth mode is XFF-only (single-value ``X-Real-IP`` /
+  ``X-Client-IP`` cannot express a hop chain) and **assumes origin lockdown** —
+  the app must be unreachable except through the proxy tier. CIDR-walk and depth
+  are mutually exclusive, and ``trusted_proxy_depth`` must be a non-negative
+  Integer or ``nil``; both are validated immediately at configuration time (with
+  a freeze-time backstop), so an invalid or contradictory setup fails fast.
+
+Documentation
+-------------
+
+- Extended ``docs/migrating/v2.3.0.md`` with a count-based depth section covering
+  when to use depth vs CIDR-walk, the origin-lockdown prerequisite, configuration
+  examples, Express parity, and the XFF-only / short-chain / mutual-exclusivity
+  semantics.
+
+AI Assistance
+-------------
+
+- Issue #147 findings triaged, fixed, and verified with AI assistance, including
+  an adversarial review that surfaced the namespace-prefix blocklist bypass.
+
+- Trusted-proxy depth design review, threat-model analysis (origin-lockdown
+  trade vs CIDR enumerability, raw-position counting to defeat XFF padding),
+  implementation and test coverage developed with AI pair programming.
+
 .. _changelog-2.2.0:
 
 2.2.0 — 2026-06-09

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,9 +1,8 @@
 PATH
   remote: .
   specs:
-    otto (2.2.0)
+    otto (2.3.1)
       concurrent-ruby (~> 1.3, < 2.0)
-      ipaddr (~> 1, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
       rack (~> 3.1, < 4.0)
@@ -55,7 +54,6 @@ GEM
     erb (6.0.4)
     hana (1.3.7)
     io-console (0.8.2)
-    ipaddr (1.2.9)
     irb (1.18.0)
       pp (>= 0.6.0)
       prism (>= 1.3.0)
@@ -115,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)
@@ -218,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

@@ -0,0 +1,288 @@
+# Otto v2.3.0 Migration Guide
+
+## Overview
+
+This release harmonizes IP address and trusted-proxy resolution (the upstream
+work for [onetimesecret#3436](https://github.com/onetimesecret/onetimesecret/issues/3436)).
+The client IP is now resolved **once** into a canonical `env['otto.client_ip']`
+that downstream code reads, trusted-proxy matching uses real CIDR containment,
+and several privacy helpers that silently returned `nil` now work. It also adds
+an additive, opt-in **count-based trusted-proxy depth** mode for proxy tiers
+whose addresses cannot be enumerated as CIDRs (see the *New feature* section
+below). Most apps need no changes; the one behavior change to review is
+trusted-proxy matching.
+
+## Breaking / behavior changes
+
+### 1. Trusted-proxy matching is now real CIDR containment
+
+`Otto::Security::Config#trusted_proxy?` previously compared entries with
+`==` / `String#start_with?`. It now parses entries with `IPAddr` and matches
+by containment for both IPv4 and IPv6.
+
+What changes in practice:
+
+```ruby
+config.add_trusted_proxy('10.0.0.0/8')
+config.trusted_proxy?('10.1.2.3')      # was false (CIDR never matched), now true
+
+config.add_trusted_proxy('192.168.1.1')
+config.trusted_proxy?('192.168.1.100') # was true (textual prefix), now false
+```
+
+- **CIDR ranges now actually work.** Previously `add_trusted_proxy('10.0.0.0/8')`
+  was effectively a no-op because no real IP literally starts with the string
+  `'10.0.0.0/8'`. If you relied on a single-IP entry acting as a prefix to
+  cover a range, replace it with an explicit CIDR.
+- **Bare hosts match only themselves.** `192.168.1.1` no longer matches
+  `192.168.1.100`, `192.168.1.10`, etc.
+- **Non-IP strings still work via the legacy path.** An entry like `'172.16.'`
+  that does not parse as an IP/CIDR falls back to the old prefix match, and
+  `add_trusted_proxy` now logs a warning suggesting a CIDR (`172.16.0.0/12`).
+- **`Regexp` entries are unchanged.**
+
+**Action:** audit your `trusted_proxies` configuration. Convert any single-IP
+or bare-prefix entries that were meant to cover a range into proper CIDR
+notation.
+
+### 2. `secure?` trusts forwarded proto via a canonical flag
+
+`Otto::Request#secure?` previously decided whether to honor `X-Forwarded-Proto`
+/ `X-Scheme` by checking `trusted_proxy?(REMOTE_ADDR)`. With IP privacy enabled,
+`IPPrivacyMiddleware` rewrites `REMOTE_ADDR` to the masked client IP, so that
+check could no longer see the connecting proxy and `secure?` could wrongly
+return `false` behind a TLS-terminating trusted proxy.
+
+The middleware now records the peer-trust decision once (before masking) in a
+leak-free boolean `env['otto.via_trusted_proxy']`, and `secure?` reads it.
+When the middleware has not run (standalone request use), `secure?` falls back
+to its previous behavior. No app changes are required.
+
+### 3. Privacy helpers now return values (previously `nil`)
+
+These helpers read the un-namespaced env keys that the middleware never set,
+so they always returned `nil`. They now read the canonical `otto.privacy.*`
+keys and return real values when IP privacy is enabled:
+
+- `Otto::Request#redacted_fingerprint`
+- `Otto::Request#geo_country`
+- `Otto::Request#hashed_ip`
+- `Otto::Request#masked_ip`
+
+If you worked around these returning `nil`, you can now use them directly.
+
+### 4. `private_ip?` is now IPv6-aware
+
+`Otto::Request#private_ip?` (used by `#local_or_private_ip?` and `#local?`) was
+an IPv4-only regex that classified **every** IPv6 address — including `::1` and
+ULA `fc00::/7` — as public. It now delegates to `Otto::Utils.private_ip?`, which
+recognizes IPv6 loopback, unique-local, link-local, multicast and unspecified
+addresses (and folds IPv4-mapped IPv6). IPv4 behavior is preserved for the
+RFC1918, link-local and unspecified ranges; two IPv4 cases are now *also*
+classified non-public that the old regex missed: loopback `127.0.0.0/8` and the
+full multicast block `224.0.0.0/4` (the old regex only matched `224.0.0.0/8`).
+Both are harmless — `#local_or_private_ip?` already special-cased `127.0.0.1`,
+and `private_ip?` no longer participates in client-IP resolution.
+
+### 5. Standalone `client_ipaddress` matches the middleware
+
+`Otto::Request#client_ipaddress` and `IPPrivacyMiddleware` now share one
+resolver (`Otto::Utils.resolve_client_ip`). With the middleware mounted (the
+normal case) `client_ipaddress` returns the canonical `env['otto.client_ip']`
+unchanged. **Without** the middleware, its fallback now walks the
+`X-Forwarded-For` chain skipping trusted proxies (instead of skipping private
+IPs) and consults `X-Client-IP` rather than the legacy `Client-IP` header —
+making the no-middleware path agree with production. This only affects apps that
+use `Otto::Request` standalone without the Otto middleware stack.
+
+## New / canonical env keys
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| `otto.client_ip` | String | Canonical client IP, resolved once. Masked when privacy is enabled; resolved real IP when disabled or exempt. Read by `Request#ip` / `#client_ipaddress`. |
+| `otto.via_trusted_proxy` | Boolean | Whether the request arrived via a trusted proxy, decided before masking. Read by `Request#secure?`. |
+
+The privacy data keys remain `otto.privacy.{fingerprint,masked_ip,hashed_ip,geo_country}`.
+
+## New feature: count-based trusted-proxy depth (additive, opt-in)
+
+New in 2.3.0 alongside the harmonization above: count-based trusted-proxy
+resolution ("trust the last N hops"), the Express `trust proxy = N` primitive,
+for proxy tiers whose addresses cannot be enumerated as CIDRs. It is
+**additive** — `trusted_proxy_depth` defaults to `nil`, leaving CIDR-walk
+behavior unchanged. This is the upstream landing point for the depth logic
+previously carried in
+[onetimesecret#3436](https://github.com/onetimesecret/onetimesecret/issues/3436)
+and the `ConfigureTrustedProxy` monkeypatch
+([onetimesecret#3116](https://github.com/onetimesecret/onetimesecret/issues/3116)).
+
+### When to use depth vs CIDR-walk
+
+| Use… | When… |
+|------|-------|
+| **CIDR-walk** (`add_trusted_proxy`, the default) | Your proxy IPs are **enumerable** — a fixed set of load balancers / reverse proxies you can list as IPs or CIDR ranges. The client is the first address in the forwarded chain that is not itself a trusted proxy. |
+| **Depth** (`trusted_proxy_depth = N`) | Your proxy tier is **non-enumerable** — Fly, cloud load balancers, dynamic/autoscaling reverse proxies whose addresses you cannot pin down. You instead know the **fixed number of hops** between the client and your app. |
+
+The two modes are **mutually exclusive**. Configuring both `trusted_proxies` and
+`trusted_proxy_depth >= 1` raises an `ArgumentError` immediately (the moment the
+second of the two is set), with a freeze-time backstop, so a contradictory setup
+fails fast rather than silently picking one.
+
+### Configuration
+
+```ruby
+# Non-enumerable single-proxy edge (e.g. one reverse proxy in front of the app):
+otto.security_config.trusted_proxy_depth = 1
+
+# Two hops (e.g. cloud LB -> app proxy -> app):
+otto.security_config.trusted_proxy_depth = 2
+```
+
+Or via the security facade / options, alongside the other security knobs:
+
+```ruby
+otto.security.configure(trusted_proxy_depth: 1)
+
+# or at construction (a top-level option, like `trusted_proxies`):
+Otto.new(routes, trusted_proxy_depth: 1)
+```
+
+`nil` or `0` disables depth mode (CIDR-walk applies). The accessor validates the
+mutual-exclusion rule on assignment and raises `FrozenError` once the
+configuration is frozen, like the other security scalars.
+
+### How depth resolution works
+
+The resolver builds a chain of `X-Forwarded-For` (left = client … right =
+nearest proxy) followed by `REMOTE_ADDR` (the direct peer), and trusts exactly
+`N` hops from the **right**:
+
+```
+chain  = X-Forwarded-For (left → right)  +  [REMOTE_ADDR]
+client = chain[-(N + 1)]                 # == Express addrs[N]
+```
+
+**Express parity.** `trusted_proxy_depth = N` matches Express / `proxy-addr`
+`trust proxy = N`: both trust `N` hops from the connecting peer inward and return
+the next address as the client. When the chain is long enough, Otto's
+`chain[-(N+1)]` is exactly Express's `addrs[N]`.
+
+**Robust against `X-Forwarded-For` padding.** Because hops are counted from the
+right, a forged **leftmost** entry is never reached. With `depth = 1`, a request
+arriving as `X-Forwarded-For: 9.9.9.9, 203.0.113.50` (where `9.9.9.9` is
+attacker-supplied and `203.0.113.50` is appended by the proxy) resolves to
+`203.0.113.50`. Positions are counted **raw** — entries are never dropped before
+counting, so an attacker cannot pad the header with junk/invalid entries to shift
+the index. Only the single selected entry is validated.
+
+**Short-chain and invalid-target fallback.** If the chain is shorter than
+`N + 1` (a request that may have **bypassed** the proxy tier), or the selected
+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.
+
+**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`.
+`env['otto.via_trusted_proxy']` — which `Otto::Request#secure?` consults to honor
+a forwarded proto — is derived solely from the trusted-proxy *identity* check
+(does `REMOTE_ADDR` match a configured `trusted_proxies` CIDR?), never from hop
+depth. Because depth mode and `trusted_proxies` are mutually exclusive, that
+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.**
+
+This is the inherent trade-off versus CIDR-walk: depth relies on a fixed network
+**topology** instead of enumerable proxy **addresses**. If a client can reach
+your app directly (origin not locked down), it can pad `X-Forwarded-For` so that
+a forged value lands at `chain[-(N+1)]`, spoofing the resolved client IP. (Proto
+trust is unaffected — depth never feeds `secure?` — but the resolved IP is only
+as trustworthy as the lockdown.)
+
+Before enabling depth, ensure the origin only accepts connections from the proxy
+tier (private networking, security groups, an authenticating header the proxy
+injects, etc.). If you can enumerate your proxies instead, prefer CIDR-walk.
+
+### Migrating from OneTimeSecret depth (`ConfigureTrustedProxy`)
+
+If you are collapsing OneTimeSecret's `ClientIpHelpers` / `ConfigureTrustedProxy`
+depth logic onto this resolver, note two intentional differences:
+
+- **Off-by-one (Otto counts the peer).** Otto's chain is `X-Forwarded-For`
+  **plus** `REMOTE_ADDR`, so it is one hop longer than OTS's XFF-only chain. To
+  resolve the same client, Otto's depth must be **one higher** than the
+  operator's OTS `depth:`. When the YAML→Otto translator is built, map
+  **`trusted_proxy_depth = ots_depth + 1`** so existing `depth:` values keep
+  their meaning. Keep a parity regression test on the OTS side to lock this
+  mapping.
+
+- **Stricter short-chain behavior (kept on purpose).** When the chain is shorter
+  than `N + 1`, Otto returns `REMOTE_ADDR` (the peer), whereas OTS returned the
+  leftmost — spoofable — `X-Forwarded-For` entry. Otto's behavior is the safer
+  one and is **not** reconciled down to OTS; expect a short-chain request to
+  resolve to the proxy peer rather than a forwarded value, and document this when
+  migrating.
+
+## No action required for
+
+- Apps that pass `trusted_proxies` as CIDR ranges or `Regexp`.
+- Apps that read `req.ip` / `req.client_ipaddress` (now backed by the canonical
+  value, same masked result).
+- Apps relying on IPv6 — IPv6 client resolution behind trusted proxies is now
+  correct (it was previously truncated to the first hextet).
+- Apps that do not set `trusted_proxy_depth` (default `nil` → unchanged
+  CIDR-walk behavior; depth mode is entirely opt-in).