otto 2.6.0 → 2.8.0

data/docs/1108-STREAMING_SUPPORT_SUMMARY.md

@@ -0,0 +1,376 @@
+# Otto Streaming Support: Executive Summary
+
+**Investigation Date**: 2025-11-08
+**Question**: Should Otto support Server-Sent Events (SSE) and WebSockets?
+**Answer**: **No** - Use separate services or long-polling instead
+
+> **Note**: The Ruby snippets below illustrate the recommended architecture. They
+> are written against the current Otto Logic-class contract
+> (`initialize(context, params, locale)` + `process`), but have not been executed
+> end-to-end. Runnable examples are tracked separately.
+
+---
+
+## Quick Recommendation
+
+| Use Case | Solution | Complexity | Otto Compatible? |
+|----------|----------|------------|------------------|
+| **Low-frequency updates (<1/min)** | Long-polling | ⭐ Simple | ✅ Yes |
+| **Medium-frequency updates (1-10/sec)** | Separate SSE service | ⭐⭐ Moderate | ✅ Via integration |
+| **High-frequency updates (>10/sec)** | Separate WebSocket service | ⭐⭐⭐ Complex | ✅ Via integration |
+| **Bidirectional communication** | Separate WebSocket service | ⭐⭐⭐ Complex | ✅ Via integration |
+
+---
+
+## Key Findings
+
+### 1. **Otto's Architecture is Fundamentally Incompatible with Streaming**
+
+Otto is designed as a **stateless, synchronous, request/response** framework:
+
+```
+Request → Middleware → Route → Handler → Response → Close Connection
+```
+
+SSE/WebSocket require **stateful, long-lived connections**:
+
+```
+Request → Upgrade → Keep Open → Stream Data (minutes/hours) → Close
+```
+
+**Incompatibilities**:
+- ❌ Response handlers expect complete responses (not streaming enumerators)
+- ❌ Middleware stack can't unwind during long-lived connections
+- ❌ Configuration freezing prevents runtime streaming adjustments
+- ❌ Requires async servers (Falcon, Iodine) - breaks server-agnostic design
+- ❌ Stateful routing complicates horizontal scaling
+
+### 2. **Industry Best Practice: Separate Services**
+
+Modern frameworks separate real-time communication from REST APIs:
+
+**Rails (ActionCable)**:
+```
+Rails App (Puma) → Redis Pub/Sub ← ActionCable (Separate Process)
+```
+
+**Node.js (Express + Socket.IO)**:
+```
+Express (HTTP Routes) + Socket.IO (Separate Layer)
+```
+
+**Benefits**:
+- ✅ Independent scaling (scale WebSocket separately from API)
+- ✅ Technology choice (use best tool for each job)
+- ✅ Fault isolation (WebSocket crash doesn't affect API)
+- ✅ Clear architectural boundaries
+
+### 3. **Long-Polling Works Perfectly with Otto**
+
+For low-to-medium frequency updates, long-polling is **simple and effective**:
+
+```ruby
+# Otto route (works with any Rack server)
+GET /api/notifications/poll NotificationPollLogic response=json auth=session
+
+class NotificationPollLogic
+  attr_reader :context, :params, :locale
+
+  def initialize(context, params, locale)
+    @context = context
+    @params  = params
+    @locale  = locale
+  end
+
+  def process
+    # Logic-class params are string-keyed (LogicClassHandler does not apply
+    # Otto::Static.indifferent_params).
+    timeout    = params['timeout'].to_i.clamp(1, 30)
+    last_id    = params['last_id'].to_i
+    start_time = Time.now
+
+    # Identity comes from the StrategyResult, never from request params.
+    user_id = context.user_id
+
+    loop do
+      notifications = fetch_new(user_id, last_id)
+      return { notifications: notifications } if notifications.any?
+
+      break if Time.now - start_time > timeout
+
+      sleep 0.5
+    end
+
+    { notifications: [] }
+  end
+end
+```
+
+**Benefits**:
+- ✅ HTTP-based (cacheable, proxy-friendly, standard tooling)
+- ✅ Works with Otto's synchronous model
+- ✅ Compatible with any Rack server (Puma, Unicorn, Passenger)
+- ✅ Simple debugging (standard HTTP requests/responses)
+- ✅ No external dependencies
+
+---
+
+## Recommended Solutions
+
+### Option 1: Long-Polling (SIMPLEST)
+
+**When to use**:
+- Updates less than 1 per minute
+- Moderate concurrency (<10,000 clients)
+- Simple deployment preferred
+
+**Example**: see the `NotificationPollLogic` sketch above.
+
+**Complexity**: ⭐ Simple
+**Otto Integration**: ✅ Native support (no changes needed)
+
+---
+
+### Option 2: Separate SSE Service (RECOMMENDED FOR REAL-TIME)
+
+**When to use**:
+- Updates 1-10 per second
+- High concurrency (>10,000 clients)
+- Near-instant updates required (<100ms latency)
+
+**Architecture**:
+```
+┌─────────────────┐
+│   Otto API      │  ← Stateless HTTP (authentication, business logic)
+│   (Puma)        │
+└─────────────────┘
+         ↓
+    ┌─────────┐
+    │  Redis  │  ← Message queue (pub/sub)
+    │ Pub/Sub │
+    └─────────┘
+         ↓
+┌─────────────────┐
+│  SSE Service    │  ← Stateful streaming (Falcon/Iodine)
+│  (Falcon)       │
+└─────────────────┘
+```
+
+**Example**: see "Otto + Falcon SSE Integration" in
+`docs/1108-STREAMING_ARCHITECTURE_ANALYSIS.md`.
+
+**Complexity**: ⭐⭐ Moderate
+**Otto Integration**: ✅ Via Redis pub/sub
+
+---
+
+### Option 3: Third-Party Service (COMMERCIAL)
+
+**When to use**:
+- Don't want to manage WebSocket infrastructure
+- Need global CDN distribution
+- Require guaranteed SLA
+
+**Options**:
+- **Mercure**: Open-source SSE hub (self-hosted or managed)
+- **Ably**: Commercial real-time messaging platform
+- **Pusher**: Commercial WebSocket/SSE service
+
+**Complexity**: ⭐⭐ Moderate (integration)
+**Otto Integration**: ✅ Via HTTP API
+
+---
+
+## Documentation Created
+
+### **docs/1108-STREAMING_ARCHITECTURE_ANALYSIS.md** (15,000+ words)
+Comprehensive technical analysis covering:
+- Otto's current architecture (detailed lifecycle analysis)
+- Technical requirements for SSE/WebSocket (Rack 3, hijacking, etc.)
+- Industry patterns (Rails, Sinatra, Roda, Go, Node.js)
+- Compatibility analysis (why it doesn't fit)
+- Best practices and anti-patterns
+- Detailed recommendations with code examples
+
+### Runnable examples: not yet published
+
+Draft `examples/otto_falcon_sse_integration.rb` and
+`examples/long_polling_example.rb` were written alongside this analysis but
+targeted an Otto API surface that does not exist (`Otto::RequestContext`,
+`enable_sessions!`, `raise_concern`, a `session` helper, `Rack::Handler::Puma`
+under the Rack 3 pin) and used symbol-keyed params that Logic routes never
+populate. They were withheld rather than shipped as copy-paste material; the
+architecture they demonstrated is preserved in the snippets here and in the
+analysis document.
+
+---
+
+## Key Insights
+
+### The Real Question
+
+**Not**: "Can Otto support SSE/WebSocket?"
+(Technically possible with massive refactoring)
+
+**But**: "Should Otto support SSE/WebSocket?"
+(Architecturally inadvisable)
+
+### Answer: **No**
+
+Otto should remain focused on its core strengths:
+- ✅ **Stateless** HTTP APIs
+- ✅ **Security-first** design (CSRF, rate limiting, validation)
+- ✅ **Privacy by default** (IP masking, geo-location)
+- ✅ **Server-agnostic** (works with any Rack server)
+- ✅ **Simple** and predictable architecture
+
+Adding SSE/WebSocket would:
+- ❌ Compromise architectural integrity
+- ❌ Force specific async servers (Falcon, Iodine)
+- ❌ Complicate security guarantees (middleware assumptions broken)
+- ❌ Add significant complexity for niche use case
+- ❌ Go against industry best practices (separation of concerns)
+
+---
+
+## What Otto SHOULD Do
+
+### 1. ✅ Document Integration Patterns
+
+Add official guide: "Integrating Otto with Real-Time Services"
+- Long-polling patterns (built-in support)
+- Separate SSE service pattern (Otto + Falcon + Redis)
+- Third-party service integration (Mercure, Ably, Pusher)
+
+### 2. ✅ Provide Example Code
+
+Add to `examples/` directory, written against the real Logic-class contract and
+verified to boot:
+- `long_polling_example.rb`
+- `otto_falcon_sse_integration.rb`
+- `otto_mercure_integration.rb`
+
+### 3. ⚠️ Consider Plugin System (If Community Demands)
+
+**Only if there's strong demand**, create experimental plugin:
+- Clearly marked "experimental" and "unsupported"
+- Requires Falcon/Iodine (documented)
+- Security implications documented
+- No core changes required
+
+### 4. ❌ Do NOT Add to Core
+
+Preserve Otto's architectural integrity by:
+- Keeping core stateless and synchronous
+- Maintaining server-agnostic design
+- Focusing on security and simplicity
+- Following industry best practices (separation of concerns)
+
+---
+
+## Migration Guide for Existing Users
+
+If you currently need real-time updates:
+
+### Step 1: Assess Your Use Case
+
+**Low-frequency updates (<1/min)**:
+→ Use long-polling (Otto native support)
+
+**Medium-frequency updates (1-10/sec)**:
+→ Use separate SSE service (Otto + Falcon + Redis)
+
+**High-frequency or bidirectional**:
+→ Use separate WebSocket service or commercial solution
+
+### Step 2: Implementation Path
+
+#### For Long-Polling:
+1. Create Otto route with long-polling logic
+2. Use `sleep` loop with timeout
+3. Client polls with timeout parameter
+4. No external dependencies needed
+
+See the `NotificationPollLogic` sketch above.
+
+#### For Separate SSE Service:
+1. Otto API handles authentication and publishes to Redis
+2. Separate Falcon app subscribes to Redis and streams SSE
+3. Client connects to SSE service with JWT token from Otto
+4. Scale Otto and SSE services independently
+
+See "Otto + Falcon SSE Integration" in
+`docs/1108-STREAMING_ARCHITECTURE_ANALYSIS.md`.
+
+### Step 3: Deployment
+
+**Long-Polling**:
+- Deploy with existing Otto setup (Puma, Unicorn, Passenger)
+- Increase thread pool size for long-polling routes
+- Monitor connection pool (ensure enough threads)
+
+**Separate SSE Service**:
+- Deploy Otto API with Puma (standard)
+- Deploy Falcon SSE service separately (dedicated servers)
+- Use Redis for pub/sub (cluster-ready)
+- Configure Nginx with sticky sessions for SSE
+- Scale services independently based on load
+
+---
+
+## Performance Guidance
+
+### Long-Polling Capacity
+
+**Example**: Puma with 5 workers × 32 threads = 160 concurrent requests
+
+If long-polling uses 30s timeout:
+- 160 concurrent connections
+- ~320 clients with 50% utilization
+- Up to 10,000 clients with proper thread tuning
+
+**Good for**: Dashboard metrics, low-volume notifications
+
+### SSE/WebSocket Capacity
+
+**Example**: Falcon with 4 workers (async)
+
+Each worker handles thousands of concurrent connections via fibers:
+- 10,000+ concurrent SSE connections per server
+- Horizontal scaling via Redis pub/sub
+- Near-instant message delivery
+
+**Good for**: Chat, multiplayer, high-frequency updates
+
+---
+
+## Conclusion
+
+**Otto should NOT integrate SSE/WebSocket support** because:
+
+1. **Architectural mismatch**: Stateless vs stateful paradigms
+2. **Industry consensus**: Separate services is best practice
+3. **Complexity cost**: Massive refactoring for niche use case
+4. **Better alternatives**: Long-polling (simple) or separate services (powerful)
+
+**Instead, Otto should**:
+
+1. ✅ Document long-polling patterns (works today)
+2. ✅ Provide integration examples (Otto + Falcon + Redis)
+3. ✅ Recommend third-party solutions (Mercure, Ably, Pusher)
+4. ✅ Stay focused on stateless HTTP APIs
+
+**This preserves Otto's core strengths** while enabling users who need real-time functionality to integrate appropriate solutions.
+
+---
+
+## Further Reading
+
+- **Technical Analysis**: `docs/1108-STREAMING_ARCHITECTURE_ANALYSIS.md`
+- **Rack 3 Streaming**: https://github.com/rack/rack/issues/1600
+- **ActionCable Architecture**: https://guides.rubyonrails.org/action_cable_overview.html
+- **SSE vs WebSocket**: https://ably.com/blog/websockets-vs-sse
+
+---
+
+**End of Summary**

data/docs/geo-country.md

@@ -0,0 +1,180 @@
+# Geo-country resolution
+
+Otto resolves a country-level ISO 3166-1 alpha-2 code for each request and
+exposes it as `req.geo_country` / `env['otto.privacy.geo_country']`. Resolution
+is country-only by design — that is the privacy posture; there is no city or
+region lookup.
+
+## Resolution order
+
+`Otto::Privacy::GeoResolver.resolve` returns the first hit from:
+
+1. **Application-configured header** (`geo_header:`) — e.g. `X-Client-Country`.
+2. **Known provider headers** — Cloudflare (`CF-IPCountry`), AWS CloudFront,
+   Fastly, Akamai Edgescape, Azure Front Door, **Vercel**
+   (`X-Vercel-IP-Country`), and a few semi-standard names
+   (`X-Geo-Country`, `X-Country-Code`, `Country-Code`).
+3. **Custom resolver** (`GeoResolver.custom_resolver`) — your own callable.
+   Unlike the other geo settings, this is **class-level** (see
+   [Configuration](#configuration)).
+4. **Local MMDB database** (`geo_db_path:` / `geo_db_reader:`) — a MaxMind-DB
+   country database.
+5. **`'**'`** — the unknown sentinel, when nothing else matches.
+
+Steps 1 and 2 are **only consulted when geo headers can be trusted** (see
+[Header trust](#header-trust-and-spoofing) below).
+
+Resolution is **honest**: Otto does not guess from a hardcoded IP-range table.
+When no header, custom resolver, or database resolves a country, the result is
+`'**'`.
+
+### Privacy: masked IP and masked env
+
+The database lookup in step 4 runs on the request's **masked** IP
+(e.g. `203.0.113.0`), never the real address. `check_geo_database` masks the IP
+internally with the config's `octet_precision` before the lookup, so even a
+direct `GeoResolver.resolve` caller passing a real IP does not expose it to the
+database. Country-level MMDB networks are almost always ≥ /24, so the default
+/24-masked value (`octet_precision: 1`) resolves to the same country.
+
+In the middleware path Otto additionally hands `resolve` a **masked env view**:
+`REMOTE_ADDR`, `X-Forwarded-For`, `X-Real-IP`, `X-Client-IP`, and the RFC 7239
+`Forwarded` header are masked. So a `custom_resolver` cannot read the raw client
+IP out of `env` either — use the `ip` argument (already masked), not `env`.
+
+> **`octet_precision: 2`** masks two octets (a /16). That is coarser than most
+> country networks, so it can reduce database hit rate for the small share of
+> countries whose ranges are finer than /16 — those requests fall through to
+> `'**'`. Header and custom-resolver sources are unaffected (they ignore the
+> IP). Keep the default precision if you rely on the MMDB fallback.
+
+## Configuration
+
+All geo configuration is **boot-time only** (set once during single-threaded
+initialization, before serving requests), matching `custom_resolver`'s
+contract. `geo_header`, `geo_db_path`, and `geo_db_reader` are stored on the
+instance's `Otto::Privacy::Config`, so separate Otto instances hold independent
+geo configuration.
+
+> **`custom_resolver` is the exception — it is class-level, not per-instance.**
+> `GeoResolver.custom_resolver=` sets a singleton on the `GeoResolver` class, so
+> it is **shared across every Otto instance in the process** (last write wins).
+> If you run multiple Otto instances that need different resolver strategies,
+> the custom resolver cannot distinguish them — branch inside a single resolver
+> on `env`, or use per-instance `geo_db_reader` instead.
+
+```ruby
+otto.configure_ip_privacy(
+  geo:           true,                                # default; false disables geo entirely
+  geo_header:    'X-Client-Country',                 # trusted app header (optional)
+  geo_db_path:   'data/geo-whois-asn-country.mmdb',  # local MMDB fallback (optional)
+  # geo_db_reader: MaxMind::DB.new(path),            # or bring your own reader (optional)
+)
+```
+
+- **`geo: false`** short-circuits everything: no header reads, and any loaded
+  database is unloaded from memory (`req.geo_country` becomes `nil`).
+- **`geo_header:`** accepts either the HTTP header name (`X-Client-Country`) or
+  the Rack CGI env key (`HTTP_X_CLIENT_COUNTRY`), in any case, and is
+  canonicalized to the env-key form. Pass `''` to clear.
+- **`geo_db_path:`** is loaded once at boot in `MODE_MEMORY`. An unreadable
+  path, a corrupt/non-MMDB file, or a missing `maxmind-db` gem raises
+  `ArgumentError` **at configuration time**, not per-request. Pass `''` to
+  unload.
+- **`geo_db_reader:`** injects any object responding to `#get(ip)` (a
+  preconfigured `MaxMind::DB` reader or a test double), keeping the reader and
+  data-source choice independent of Otto. It **overrides** `geo_db_path` when
+  both are given in the same call; supplying `geo_db_path` alone in a later call
+  clears a prior reader override.
+
+Each keyword follows a `nil` = "leave unchanged" contract; pass `''` to a header
+or path to clear it. Any geo-affecting change triggers the boot-time database
+(re)load, so a bad `geo_db_path` fails at the `configure_ip_privacy` call.
+
+## The database: gem and datafile
+
+The reader and the data file are independent — the MMDB format is the interop
+point.
+
+### Reader gem (`maxmind-db`)
+
+The [`maxmind-db`](https://rubygems.org/gems/maxmind-db) gem (official MaxMind
+reader, Apache-2.0, pure Ruby, zero runtime deps) is an **optional**
+dependency. Otto only `require`s it when a database is configured. Add it to
+your app when you use the database fallback:
+
+```ruby
+# Gemfile
+gem 'maxmind-db', '~> 1.4'
+```
+
+### Data file (`geo-whois-asn-country`)
+
+The recommended data file is
+[`geo-whois-asn-country`](https://github.com/sapics/ip-location-db) from
+sapics/ip-location-db: **PDDL v1.0 (public domain, no attribution required)**,
+rebuilt daily, shipped as MMDB. Otto vendors no database — country data goes
+stale, and a public-domain file you refresh on your own schedule keeps
+licensing and freshness in your control.
+
+Download it (IPv4+IPv6) into a path of your choosing:
+
+```bash
+mkdir -p data
+curl -fsSL -o data/geo-whois-asn-country.mmdb \
+  https://github.com/sapics/ip-location-db/releases/download/latest/geo-whois-asn-country.mmdb
+```
+
+Refresh it on your own schedule (e.g. a daily cron job running the same curl).
+Any MMDB country database works — GeoLite2-Country, DB-IP Country Lite,
+iplocate, etc. — since `GeoResolver` tolerates the record shapes country
+databases actually use: nested `country.iso_code` (GeoLite2-Country style), a
+flat `country_code` string, and a bare-string `country`.
+
+> **Note on GeoLite2:** its EULA requires a MaxMind account/license key and
+> obliges consumers to refresh within 30 days of each release. A PDDL dataset
+> avoids both obligations.
+
+## Header trust and spoofing
+
+Every geo header is trivially client-spoofable unless the request actually
+arrived through the CDN that sets it. Otto trusts geo headers — both the
+configured `geo_header` and the provider headers — **only** for a request that
+demonstrably arrived via a configured **CIDR trusted proxy**
+(`env['otto.via_trusted_proxy']` with `trusted_proxies` configured). A spoofed
+header on a direct connection is ignored, and resolution falls through to the
+custom resolver / database.
+
+Origins Otto cannot verify are **not** trusted:
+
+- **No trusted-proxy configuration.** A direct internet client could otherwise
+  pick its own country by sending `CF-IPCountry` / `X-Client-Country`, so with
+  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. 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
+deployments should set `geo_db_path` for a local database instead; otherwise
+resolution returns `'**'`.
+
+## Acceptance behavior summary
+
+| Scenario | Result |
+| --- | --- |
+| Configured `geo_header` present and trusted | wins over provider headers |
+| Request not via a verified CIDR trusted proxy | geo headers skipped |
+| No `trusted_proxies` configured | geo headers skipped (not trusted) |
+| Database lookup | uses the masked IP only |
+| `geo: false` | `nil`, no database in memory |
+| Bad `geo_db_path` | raises at boot, not per-request |
+| Nothing matches | `'**'` |

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