otto 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d14c212b610b94a8a21abdae0c1d691e342c849e6160dc03615c8c00e30ddca8
-  data.tar.gz: 0a22e90e372914211b0828eb4c0048edb3171c011407778af73d0be098a79a68
+  metadata.gz: 2d4e92c540f41f9cad40b495f8a7106f49a11d8eb9b5011981c97bf585026065
+  data.tar.gz: 10c592de40e1b0b35f57379b5dfca20a51b76967898e0cccce33d903fbfcb75d
 SHA512:
-  metadata.gz: f1c55db0ffbe490ad295c6d73b1e6012f1e12702dd33f971f3e7a2a42f9b269cceaf0deccdb5e9fb958f56dfe338bbbb71561ea01ec8b2c7e18d71e507ddb065
-  data.tar.gz: 78f3e09cd71f33caceab30691d562a65552c765f4b1690b4b1ad36776cf89600839bf1fb37ab2a7d4335fd58e2d75ad403f6129f7e879dc12581ded07f1aa3ac
+  metadata.gz: 21268aaf0ec8b815f8981691ef76fe9a41347eeb184b8bb04b7403d5c1aefda9339acd97bee280e53845f3acf17a17cd68175cb272153acfd176ff16183cb0c6
+  data.tar.gz: 0d30534c168a390f3dec1cf8e35388e0cec48c7285a0c10e1358af71b03032a52043cb0fbad09d9578ccea34c8ee27ac49eb90eefc09d4b5cbe740f530a6b5f2

data/CHANGELOG.rst

@@ -7,6 +7,42 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.8.0:
+
+2.8.0 — 2026-08-07
+==================
+
+Changed
+-------
+
+- ``env['otto.via_trusted_proxy']`` is now tri-state: written only when proxy
+  trust is configured (CIDR matchers or ``trusted_proxy_depth``). A present
+  key is authoritative in both directions; an absent key means
+  "unconfigured". Consumers reading the raw env key should presence-check
+  (``env.key?``) rather than compare ``== true``. (#228)
+
+- Configuring an ip-privacy ``geo_header`` together with
+  ``trusted_proxy_depth`` now raises ``ArgumentError`` at configuration time:
+  geo headers are only honored for CIDR-verified proxies, so under depth mode
+  the header could never be consulted. Database-backed geo (``geo_db_path`` /
+  ``geo_db_reader``) remains fully supported under depth. (#228)
+
+Fixed
+-----
+
+- Depth mode now records a peer-trust verdict in
+  ``env['otto.via_trusted_proxy']`` (previously always ``false``, leaving
+  downstream middleware with no trust signal);
+  ``Otto::Request#forwarded_by_trusted_proxy?`` mirrors the grant on its
+  no-middleware fallback path. (#226)
+
+Documentation
+-------------
+
+- Corrected the v2.3.0 migration guide's depth-porting guidance: map depth
+  values directly, not ``+1`` — otto's chain index already accounts for the
+  appended ``REMOTE_ADDR``. (#227, #228)
+
 .. _changelog-2.7.0:
 
 2.7.0 — 2026-08-03

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.7.0)
+    otto (2.8.0)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
@@ -59,7 +59,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.20.0)
+    json (2.21.2)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)

data/docs/geo-country.md

@@ -152,7 +152,15 @@ Origins Otto cannot verify are **not** trusted:
   no `trusted_proxies` configured, header steps are skipped and resolution falls
   to the resolver / database (`'**'` if neither is set).
 - **Count-based `trusted_proxy_depth` mode.** The header-setting hop cannot be
-  verified as a geo-CDN, so depth mode does not enable header trust.
+  verified as a geo-CDN, so depth mode does not enable header trust. This
+  conflict fails loud: configuring a `geo_header` together with a
+  `trusted_proxy_depth` raises `ArgumentError` at configuration time (in
+  either order) instead of silently ignoring the header per-request.
+  Database-backed geo remains fully supported under depth. The built-in
+  provider headers stay legal (there is nothing to configure, so nothing
+  can raise) but are equally inert — header trust requires CIDR-verified
+  proxies — so only an explicitly configured `geo_header` is rejected, and
+  depth deployments that want geo should set `geo_db_path`.
 
 **Migration:** to keep header-based geo, configure `trusted_proxies` (CIDR
 matchers) so Otto can verify the proxy origin. Depth-mode and header-only

data/docs/migrating/v2.3.0.md

@@ -55,8 +55,16 @@ 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.
+Since the first release after 2.7.0 the key is **tri-state**: it is written
+only when proxy trust is actually configured (CIDR matchers or a depth), so a
+present key is authoritative in both directions and an *absent* key means "no
+proxy trust configured". When the key is absent (standalone request use, or an
+unconfigured deployment), `secure?` falls back to the same decision the
+middleware would have implied: a CIDR check of the connecting peer — or, since
+the depth-mode peer-trust fix
+([#226](https://github.com/delano/otto/issues/226), first release after
+2.7.0), an unconditional grant when `trusted_proxy_depth` is configured. No
+app changes are required.
 
 ### 3. Privacy helpers now return values (previously `nil`)
 
@@ -100,7 +108,7 @@ use `Otto::Request` standalone without the Otto middleware stack.
 | 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?`. |
+| `otto.via_trusted_proxy` | Boolean (tri-state: may be absent) | Peer trust decided before masking, written **only when proxy trust is configured** (first release after 2.7.0): `true` on a CIDR match — or unconditionally when depth mode is configured ([#226](https://github.com/delano/otto/issues/226)); `false` means trust is configured and the peer failed it (authoritative deny). Absent = no proxy trust configured — the only case for consumer-side fallback heuristics. Read by `Request#secure?`. |
 
 The privacy data keys remain `otto.privacy.{fingerprint,masked_ip,hashed_ip,geo_country}`.
 
@@ -187,15 +195,26 @@ 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.
+**Depth grants peer trust ([#226](https://github.com/delano/otto/issues/226),
+first release after 2.7.0).** Configuring a depth asserts that the connecting
+peer *is* your proxy tier — that is what the setting means — so depth mode
+records `env['otto.via_trusted_proxy'] = true` on every request, and
+`Otto::Request#secure?` (which consults that flag) honors a forwarded
+`X-Forwarded-Proto` / `X-Scheme` in depth mode. Releases up to and including
+2.7.0 behaved differently: the flag was derived solely from the
+`trusted_proxies` CIDR identity check, which is always empty under depth
+(the modes are mutually exclusive), so it was recorded `false` and `secure?`
+reflected only a direct TLS connection (`HTTPS=on` / port 443). Because the
+grant is unconditional, the *origin lockdown* prerequisite below now covers
+proto trust exactly as it covers IP resolution. Geo headers are unaffected:
+they remain gated on enumerated `trusted_proxies` matchers and are still
+**not** trusted in depth mode (a hop trusted by count cannot be verified as a
+geo-setting CDN). As of the first release after 2.7.0 this carve-out fails
+loud instead of silently: configuring an ip-privacy `geo_header` together
+with a `trusted_proxy_depth` raises `ArgumentError` at configuration time
+(in either order, with a freeze-time backstop) — use filter mode for
+header-based geo, or a geo database (`geo_db_path`) under depth. Database-
+backed geo with depth remains fully supported.
 
 ### Selecting the forwarded header (added in 2.3.1)
 
@@ -249,9 +268,10 @@ Otto.new(routes, trusted_proxy_depth: 1, trusted_proxy_header: 'Forwarded')
 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.)
+a forged value lands at `chain[-(N+1)]`, spoofing the resolved client IP. (Since
+[#226](https://github.com/delano/otto/issues/226) this applies to proto trust
+too: depth grants `otto.via_trusted_proxy`, so a directly-reachable origin
+could spoof the scheme via `X-Forwarded-Proto` as well as the client IP.)
 
 Before enabling depth, ensure the origin only accepts connections from the proxy
 tier (private networking, security groups, an authenticating header the proxy
@@ -262,13 +282,26 @@ injects, etc.). If you can enumerate your proxies instead, prefer CIDR-walk.
 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.
+- **Map depth values directly — do NOT add one.** Otto's chain is
+  `X-Forwarded-For` **plus** `REMOTE_ADDR`, and the client is selected at
+  `chain[-(N+1)]` — the appended peer is already accounted for by the index
+  arithmetic. `trusted_proxy_depth = N` therefore means "N proxy hops,
+  counting the connecting peer as hop 1", which is exactly what the
+  operator-facing OTS `depth: N` documents ("1 = standard single reverse
+  proxy"). Map **`trusted_proxy_depth = ots_depth`**, and keep a parity
+  regression test on the OTS side — including a padded-chain case asserting a
+  forged leftmost `X-Forwarded-For` entry is never selected.
+
+  > **Correction.** Earlier revisions of this guide recommended
+  > `trusted_proxy_depth = ots_depth + 1` to "keep existing `depth:` values'
+  > meaning". That reproduced an internal off-by-one of the deleted OTS
+  > walker (whose indexed path selected `XFF[-(depth+1)]`, one position left
+  > of its own documented contract), not the operator-facing meaning. Under
+  > the `+1` remap every honest documented-topology request hit the
+  > short-chain fallback and resolved the **proxy** address as the client,
+  > and a single forged leftmost `X-Forwarded-For` entry re-lengthened the
+  > chain so the forged value was selected. The direct mapping resolves the
+  > true client on honest chains and is padding-resistant.
 
 - **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

data/lib/otto/env_keys.rb

@@ -5,10 +5,13 @@
 # Central registry of all env['otto.*'] keys used throughout Otto framework.
 # This documentation helps prevent key conflicts and aids multi-app integration.
 #
-# DOCUMENTATION-ONLY MODULE: The constants defined here are intentionally NOT used
-# in the codebase. Otto uses string literals (e.g., env['otto.strategy_result'])
-# for readibility/simplicity. This module exists as reference documentation but
-# may be considered for future use if needed.
+# Otto's own code writes the string literals directly (e.g.
+# env['otto.strategy_result']) for readability/simplicity, so this file is
+# not loaded by `require 'otto'` — consumers must `require 'otto/env_keys'`
+# explicitly. The constants are nevertheless PUBLIC API: downstream
+# applications reference them at runtime to pin the cross-gem env contract
+# (OneTimeSecret's Rack::DetectHost reads VIA_TRUSTED_PROXY). Renaming or
+# removing a constant — or this file — is a breaking change.
 #
 class Otto
   # Rack environment keys used by Otto framework
@@ -71,15 +74,26 @@ class Otto
     #   (e.g. 'onetime.nonce'), so the header and views still share one value.
     NONCE = 'otto.nonce'
 
-    # Whether the request arrived via a trusted proxy.
-    # Type: Boolean
-    # Set by: IPPrivacyMiddleware (every request, evaluated on the original
-    #   peer BEFORE REMOTE_ADDR is masked). This is the trusted-proxy identity
-    #   check (does REMOTE_ADDR match a configured trusted_proxies CIDR?) — it is
-    #   independent of count-based depth mode, which resolves the client IP but
-    #   never grants proxy trust for forwarded proto.
+    # Whether the request arrived via a trusted proxy. TRI-STATE.
+    # Type: Boolean when present; the key may be ABSENT.
+    # Set by: IPPrivacyMiddleware, evaluated on the original peer BEFORE
+    #   REMOTE_ADDR is masked — but ONLY when proxy trust is configured
+    #   (Security::Config#proxy_trust_configured?: CIDR matchers or a depth).
+    #   True when the peer matches a configured trusted_proxies CIDR (filter
+    #   mode), or unconditionally when count-based depth mode is active
+    #   (trusted_proxy_depth >= 1) — the modes are mutually exclusive, and
+    #   configuring a depth is the operator's assertion that the connecting
+    #   peer is their proxy tier (#226). False means trust IS configured and
+    #   this peer failed it — an authoritative deny. When no proxy trust is
+    #   configured the key is NOT written, so consumers can distinguish
+    #   "denied" from "unconfigured" and apply legacy heuristics only in the
+    #   latter case.
     # Used by: Otto::Request#secure? to authorize X-Forwarded-Proto / X-Scheme
-    #   without depending on the (masked) REMOTE_ADDR
+    #   without depending on the (masked) REMOTE_ADDR, and by downstream
+    #   middleware (e.g. forwarded-host handling) as the peer-trust signal now
+    #   that REMOTE_ADDR no longer identifies the connecting peer. Consumers
+    #   should treat a PRESENT key as authoritative in both directions and
+    #   reserve fallback heuristics for the absent case.
     VIA_TRUSTED_PROXY = 'otto.via_trusted_proxy'
 
     # Whether the connecting peer was the loopback interface.

data/lib/otto/privacy/core.rb

@@ -106,6 +106,17 @@ class Otto
         # rubocop:enable Metrics/ParameterLists
         ensure_not_frozen!
         config = @security_config.ip_privacy_config
+
+        # Geo headers are honored only for peers matching enumerated CIDR
+        # matchers, never for count-trusted hops, so a geo_header configured
+        # alongside depth mode could never be consulted. Fail loud here
+        # (depth-then-geo order; the trusted_proxy_depth= setter catches
+        # geo-then-depth). A blank geo_header canonicalizes to nil ("clear"),
+        # which stays legal under depth.
+        if Otto::Privacy::Config.canonicalize_geo_header(geo_header) &&
+           @security_config.trusted_proxy_depth_mode?
+          raise ArgumentError, Otto::Security::Config::GEO_HEADER_DEPTH_CONFLICT_MESSAGE
+        end
         knobs = { profile: profile, octet_precision: octet_precision,
                   hash_rotation: hash_rotation, geo: geo,
                   correlation_secret: correlation_secret, redis: redis }

data/lib/otto/request.rb

@@ -241,19 +241,28 @@ class Otto
     #
     # Prefers the canonical decision recorded once by IPPrivacyMiddleware in
     # env['otto.via_trusted_proxy'] — evaluated against the original peer before
-    # REMOTE_ADDR is masked, so it stays correct even after masking. Falls back
-    # to evaluating the current REMOTE_ADDR when the middleware has not run
-    # (standalone request use).
-    #
-    # This is the trusted-proxy *identity* check only and is independent of
-    # count-based depth mode: depth resolves the client IP but never grants
-    # proxy trust for X-Forwarded-Proto.
+    # REMOTE_ADDR is masked, so it stays correct even after masking. The key is
+    # tri-state: written only when proxy trust is configured, so its absence
+    # covers both "middleware not mounted" (standalone request use) and "no
+    # proxy trust configured" — the fallback below answers both by evaluating
+    # the config directly against the current REMOTE_ADDR (an unconfigured
+    # config yields false, matching what the middleware would have implied).
+    #
+    # A peer earns trust two ways (#226): its identity matches a configured
+    # trusted-proxy CIDR (filter mode), or count-based depth mode is active —
+    # configuring a depth asserts the connecting peer is the operator's
+    # (non-enumerable) proxy tier. The fallback mirrors the grant
+    # IPPrivacyMiddleware records so the two paths cannot disagree.
     #
     # @return [Boolean]
     def forwarded_by_trusted_proxy?
       return env['otto.via_trusted_proxy'] if env.key?('otto.via_trusted_proxy')
 
-      otto_security_config ? trusted_proxy?(env['REMOTE_ADDR']) : false
+      config = otto_security_config
+      return false unless config
+      return true if config.trusted_proxy_depth_mode?
+
+      trusted_proxy?(env['REMOTE_ADDR'])
     end
 
     # See: http://stackoverflow.com/questions/10013812/how-to-prevent-jquery-ajax-from-following-a-redirect-after-a-post

data/lib/otto/security/config.rb

@@ -38,6 +38,23 @@ class Otto
         hop count, not both.
       MSG
 
+      # Error raised when an app-configured trusted geo header (ip_privacy
+      # geo_header) is combined with count-based depth mode. Geo headers are
+      # honored only for peers matching enumerated trusted_proxies CIDRs
+      # (geo_headers_trusted? gates on trusted_proxies_configured?) — a hop
+      # trusted by count cannot be verified as the geo-setting CDN — so a
+      # geo_header configured alongside a depth could never be consulted.
+      # Failing loud at config time replaces a silent database/'**' fallback
+      # at request time.
+      GEO_HEADER_DEPTH_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        Cannot configure a trusted geo header (ip_privacy geo_header) together
+        with trusted_proxy_depth (count mode): geo headers are only honored
+        for peers matching enumerated trusted_proxies CIDRs, so the header
+        would be silently ignored. Use filter mode (add_trusted_proxy) for
+        header-based geo, or drop geo_header and use database-backed geo
+        (geo_db_path or geo_db_reader).
+      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
@@ -219,18 +236,30 @@ class Otto
 
       # Whether any trusted-proxy IP/CIDR/Regexp matchers are configured.
       #
-      # This mirrors {#trusted_proxy?}, which consults the same matcher list, so
-      # the two answers stay consistent: a request can only be "via a trusted
-      # proxy" when matchers exist. It deliberately EXCLUDES count-based depth
-      # mode — depth resolves the client IP but never confers proxy identity
-      # trust (the same decoupling {Otto::Request#forwarded_by_trusted_proxy?}
-      # applies to X-Forwarded-Proto). Used to gate geo-header trust.
+      # This mirrors {#trusted_proxy?}, which consults the same matcher list.
+      # It deliberately EXCLUDES count-based depth mode: depth grants the peer
+      # blanket trust for otto.via_trusted_proxy (#226), but it cannot verify
+      # that the hop is a geo-setting CDN, so header-based geo stays gated on
+      # enumerated matchers only. Used to gate geo-header trust.
       #
       # @return [Boolean] true when at least one trusted-proxy matcher exists
       def trusted_proxies_configured?
         @trusted_proxy_matchers.any?
       end
 
+      # Whether ANY proxy-trust mode is configured — CIDR matchers (filter
+      # mode) or count-based depth. This is the gate for writing
+      # env['otto.via_trusted_proxy'] at all: when neither mode is configured
+      # the key is left ABSENT (tri-state contract), so downstream consumers
+      # can distinguish "operator configured trust and this peer failed it"
+      # (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
+      def proxy_trust_configured?
+        trusted_proxies_configured? || trusted_proxy_depth_mode?
+      end
+
       # Whether count-based ("trust the last N hops") proxy resolution is active.
       #
       # When true, Otto::Utils.resolve_client_ip ignores trusted-proxy CIDRs and
@@ -260,6 +289,9 @@ class Otto
 
         validate_trusted_proxy_depth!(depth)
         raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if depth.to_i >= 1 && @trusted_proxies.any?
+        # 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
 
         @trusted_proxy_depth = depth
       end
@@ -763,6 +795,12 @@ class Otto
         return if @trusted_proxy_depth.nil?
 
         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.
+        return unless @trusted_proxy_depth >= 1 && @ip_privacy_config&.geo_header
+
+        raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE
       end
 
       # Parse a value into an IPAddr, returning nil for invalid / non-IP input.

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

@@ -21,7 +21,9 @@ class Otto
       # Because it now runs ahead of everything, facts about the ORIGINAL peer
       # that downstream code can no longer derive from the (masked) REMOTE_ADDR
       # are recorded first, as leak-free booleans — never as addresses:
-      # env['otto.via_trusted_proxy'] and env['otto.peer_loopback'].
+      # env['otto.via_trusted_proxy'] (only when proxy trust is configured —
+      # absent otherwise, see the tri-state note in #call) and
+      # env['otto.peer_loopback'].
       #
       # @example Default behavior (privacy enabled)
       #   # env['REMOTE_ADDR'] is masked to 192.168.1.0
@@ -62,11 +64,22 @@ class Otto
           # secure? can authorize X-Forwarded-Proto canonically even after
           # REMOTE_ADDR is rewritten to the masked client IP. Leak-free boolean.
           #
-          # This is the trusted-proxy *identity* check only — it is deliberately
-          # independent of count-based depth mode. Depth resolves the client IP;
-          # it never grants proxy trust for X-Forwarded-Proto (matching the
-          # downstream OneTimeSecret behavior).
-          env['otto.via_trusted_proxy'] = trusted_proxy?(env['REMOTE_ADDR'])
+          # TRI-STATE: the key is written ONLY when the operator configured
+          # proxy trust (CIDR matchers or a depth). 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);
+          # false means trust IS configured and this peer failed it. Absent
+          # means no proxy trust is configured at all, so downstream consumers
+          # may fall back to their own heuristics without this key vetoing
+          # them. Writing false on unconfigured deployments made false
+          # ambiguous between "untrusted peer" and "nothing configured", which
+          # 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
 
           # Same rationale, for loopback: this middleware runs outermost, so a
           # downstream middleware that must authenticate a DIRECT LOCAL CALL
@@ -420,12 +433,20 @@ class Otto
           Otto.logger.debug "[IPPrivacyMiddleware] Masked forwarded headers" if Otto.debug
         end
 
-        # Check if an IP is from a trusted proxy
+        # Check if the connecting peer counts as a trusted proxy
+        #
+        # CIDR filter mode checks the peer's identity against the configured
+        # matchers. Count-based depth mode has no enumerable matchers — the
+        # depth setting itself is the operator's assertion that the peer is
+        # their proxy tier — so an active depth grants peer trust outright
+        # (#226). Geo-header trust is unaffected: geo_headers_trusted? gates on
+        # trusted_proxies_configured?, which stays matcher-only.
         #
         # @param ip [String] IP address to check
         # @return [Boolean] true if IP is from a trusted proxy
         def trusted_proxy?(ip)
           return false unless @security_config
+          return true if @security_config.trusted_proxy_depth_mode?
 
           @security_config.trusted_proxy?(ip)
         end

data/lib/otto/version.rb

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

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.8.0
 platform: ruby
 authors:
 - Delano Mandelbaum
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-08-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -329,6 +330,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -346,7 +348,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Define your rack-apps in plaintext.
 test_files: []