otto 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0616e034fc5859c42ed2eb48e1d123abdd1b36bca93422cf858d51331843c2c9
-  data.tar.gz: 667c3067cdd71ed41ef733c479798836522c32d37044edeb5f78d33c04b14818
+  metadata.gz: 50aa75316f4a3f73a0784cf78fb29e05c030901fa75ac1b8285a6ec0ad89fc3b
+  data.tar.gz: 38c18d2dc357589e1377a5df0cecd0de26370b002061d9bde6d66994b4990610
 SHA512:
-  metadata.gz: c219d4864ffc3090983ee50828279914dc052d0d65f5fd75dbaff812a1fee5d32880c325956d778c9a68e39e396e0f855f271eb3355ddee9d846e186586c57a2
-  data.tar.gz: d32b8d2235fe0d2c95510c4ec5f1623f30a6039bac1a309878af03907458fd9a51ea18f6e5584dfe88754a45cef25469f52ba72bee7847e97b87f2e481672e9d
+  metadata.gz: e5f9c0693f83c423a77b20ac88c6af74db6c3d4a9ea345304085b31249a1d20537d64d5c091c5ffb5f6382bfd3fe291d4bcc85f5949928ef09ab8ae74fe09c3b
+  data.tar.gz: 29fb704139356b0e0df805567e761593b10faf519f7977087425f9752711dfe4315b41266d864c071779f1e37b55e1a9d40c454c74f5973f728f3f1e1ff1bb97

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:

data/.github/workflows/claude.yml

@@ -26,7 +26,7 @@ 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
 

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,170 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _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.lock

@@ -1,9 +1,8 @@
 PATH
   remote: .
   specs:
-    otto (2.2.0)
+    otto (2.3.0)
       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)

data/docs/migrating/v2.3.0.md

@@ -0,0 +1,241 @@
+# 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.
+
+**`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).
+
+**`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.
+
+### 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).

data/lib/otto/core/configuration.rb

@@ -57,6 +57,10 @@ class Otto
         # Add trusted proxies if provided
         Array(opts[:trusted_proxies]).each { |proxy| add_trusted_proxy(proxy) } if opts[:trusted_proxies]
 
+        # 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]
+
         # Set custom security headers
         return unless opts[:security_headers]
 

data/lib/otto/env_keys.rb

@@ -61,6 +61,17 @@ class Otto
     # Used by: All security middleware (CSRF, Headers, Validation)
     SECURITY_CONFIG = 'otto.security_config'
 
+    # 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.
+    # Used by: Otto::Request#secure? to authorize X-Forwarded-Proto / X-Scheme
+    #   without depending on the (masked) REMOTE_ADDR
+    VIA_TRUSTED_PROXY = 'otto.via_trusted_proxy'
+
     # =========================================================================
     # LOCALIZATION (I18N)
     # =========================================================================
@@ -103,6 +114,16 @@ class Otto
     # PRIVACY (IP MASKING)
     # =========================================================================
 
+    # Canonical client IP, resolved once early by IPPrivacyMiddleware
+    # ("resolve once, read everywhere"). Downstream code (client_ipaddress,
+    # Request#ip) reads this instead of re-deriving from REMOTE_ADDR / XFF.
+    # Type: String
+    # Set by: IPPrivacyMiddleware (every request, all modes)
+    # Value: masked IP when privacy enabled; resolved real IP when privacy
+    #        disabled or the address is exempt (private/localhost)
+    # Note: presence also acts as the idempotency guard for the middleware
+    CLIENT_IP = 'otto.client_ip'
+
     # Privacy-safe masked IP address
     # Type: String (e.g., '192.168.1.0')
     # Set by: IPPrivacyMiddleware

data/lib/otto/helpers/validation.rb

@@ -38,11 +38,9 @@ class Otto
           input_str       = sanitized_input
         end
 
-        # Always check for SQL injection
-        ValidationMiddleware::SQL_INJECTION_PATTERNS.each do |pattern|
-          raise Otto::Security::ValidationError, 'Potential SQL injection detected' if input_str.match?(pattern)
-        end
-
+        # NOTE: no SQL-injection inspection here on purpose — see
+        # ValidationMiddleware. Defend against SQL injection with parameterized
+        # queries at the data-access layer, not input blocklists.
         input_str
       end
 

data/lib/otto/logging_helpers.rb

@@ -76,8 +76,8 @@ class Otto
       {
             method: env['REQUEST_METHOD'],
               path: env['PATH_INFO'],
-                ip: env['REMOTE_ADDR'], # Already masked by IPPrivacyMiddleware for public IPs
-           country: env['otto.geo_country'],
+                ip: env['otto.client_ip'] || env['REMOTE_ADDR'], # Canonical client IP (masked when privacy on)
+           country: env['otto.privacy.geo_country'],
         user_agent: env['HTTP_USER_AGENT']&.slice(0, 100), # Already anonymized by IPPrivacyMiddleware
       }.compact
     end

data/lib/otto/mcp/auth/token.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'rack/utils'
 
 class Otto
   module MCP
@@ -17,11 +18,21 @@ class Otto
           token = extract_token(env)
           return false unless token
 
-          @tokens.include?(token)
+          valid_token?(token)
         end
 
         private
 
+        def valid_token?(candidate)
+          # Constant-time membership: compare against every configured token without
+          # short-circuiting on the first match, so neither match position nor
+          # membership leaks via timing. Rack::Utils.secure_compare itself is
+          # constant-time for equal-length strings.
+          @tokens.reduce(false) do |matched, token|
+            Rack::Utils.secure_compare(token, candidate) || matched
+          end
+        end
+
         def extract_token(env)
           # Try Authorization header first (Bearer token)
           auth_header = env['HTTP_AUTHORIZATION']

data/lib/otto/mcp/registry.rb

@@ -2,6 +2,8 @@
 #
 # frozen_string_literal: true
 
+require_relative '../security/constant_resolver'
+
 class Otto
   module MCP
     # Registry for managing MCP resources and tools
@@ -82,7 +84,7 @@ class Otto
           klass_name   = klass_method[0..-2].join('::')
           method_name  = klass_method.last
 
-          klass  = Object.const_get(klass_name)
+          klass  = Otto::Security::ConstantResolver.safe_const_get(klass_name)
           result = klass.public_send(method_name, arguments, env)
         else
           raise "Invalid tool handler: #{handler}"

data/lib/otto/mcp/server.rb

@@ -8,6 +8,7 @@ require_relative 'route_parser'
 require_relative 'auth/token'
 require_relative 'schema_validation'
 require_relative 'rate_limiting'
+require_relative '../security/constant_resolver'
 
 class Otto
   module MCP
@@ -124,7 +125,7 @@ class Otto
 
         # Create resource handler
         handler = lambda do
-          klass = Object.const_get(klass_name)
+          klass = Otto::Security::ConstantResolver.safe_const_get(klass_name)
           method = klass.method(method_name)
           if method.arity != 0
             raise ArgumentError, "Handler #{klass_name}.#{method_name} must be a zero-arity method for resource #{uri}"