otto 2.7.0 → 2.8.1

data/CHANGELOG.rst

@@ -7,6 +7,82 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.8.1:
+
+2.8.1 — 2026-08-16
+==================
+
+Added
+-----
+
+- Opt-in ASN resolution: ``req.asn`` / ``env['otto.privacy.asn']`` resolves
+  the client's network operator (``'AS15169'``) from a local MaxMind-format
+  database configured via ``configure_ip_privacy(asn: true, asn_db_path:
+  ...)`` (or a bring-your-own ``asn_db_reader``). Database-only — no header
+  tier exists, so the ``geo_header``/``trusted_proxy_depth`` conflict
+  machinery does not apply — and the lookup uses the already-masked IP, which
+  is safe because IPv4 BGP routes are not announced longer than /24. Off by
+  default: ``nil`` when disabled, ``'**'`` when enabled but unresolved.
+
+- Opt-in anonymizer classification: ``req.anonymizer`` /
+  ``env['otto.privacy.anonymizer']`` labels the client address as ``'tor'``,
+  ``'proxy'``, ``'vpn'``, ``'residential_proxy'``, ``'hosting'``,
+  ``'anonymous'``, ``'none'`` (consulted, not listed), or ``'**'`` (no
+  answer), from a local anonymous-IP database
+  (``configure_ip_privacy(anonymizer: true, anonymizer_db_path: ...)``).
+  This is the one database lookup performed on the UNMASKED address:
+  anonymizer data lists individual egress nodes at or near /32, so a masked
+  lookup would answer for the node's neighbours — flagging innocent
+  addresses and missing actual exit nodes. Only the label ever leaves the
+  resolver, the same containment contract as ``hash_ip`` and
+  ``env['otto.ip_match']``. Off by default.
+
+Documentation
+-------------
+
+- New ``docs/enrichment.md`` covering both signals, including the corrected
+  dataset guidance: ``geo-whois-asn-country`` is a country database (the
+  ``asn`` in its name describes its data *sources*, not its record
+  contents); deployments wanting ASN data need a separate ASN file, e.g.
+  sapics ``origin-asn`` (PDDL, rebuilt daily) — verified against the
+  published file, whose records carry a flat ``autonomous_system_number``.
+
+.. _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

@@ -29,7 +29,7 @@ group :development do
   gem 'debug'
   gem 'rackup' # Used to boot examples/ apps; not needed by specs
   gem 'rake', '~> 13.4', require: false # Provides `rake release` for release-gem.yml
-  gem 'rubocop', '~> 1.88.2', require: false
+  gem 'rubocop', '~> 1.89.0', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rspec', require: false
   gem 'rubocop-thread_safety', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.7.0)
+    otto (2.8.1)
       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)
@@ -92,7 +92,7 @@ GEM
     nokogiri (1.19.4-x86_64-linux-musl)
       racc (~> 1.4)
     parallel (1.28.0)
-    parser (3.3.11.1)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     pastel (0.8.0)
@@ -148,7 +148,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.88.2)
+    rubocop (1.89.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -227,7 +227,7 @@ DEPENDENCIES
   rake (~> 13.4)
   reek (~> 6.5)
   rspec (~> 3.13)
-  rubocop (~> 1.88.2)
+  rubocop (~> 1.89.0)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety

data/docs/.gitignore

@@ -3,6 +3,7 @@
 !migrating/
 !migrating/*.md
 !ipaddr-encoding-quirk.md
+!enrichment.md
 !geo-country.md
 !modern-authentication-authorization-landscape.md
 !multi-strategy-authentication-design.md

data/docs/enrichment.md

@@ -0,0 +1,128 @@
+# ASN and anonymizer enrichment
+
+Two opt-in, country-adjacent signals layered on the same privacy pipeline as
+[geo-country](geo-country.md):
+
+- **ASN** — the network operator an address belongs to, as `req.asn` /
+  `env['otto.privacy.asn']`: `'AS15169'`.
+- **Anonymizer** — whether the address is a known anonymizing egress, as
+  `req.anonymizer` / `env['otto.privacy.anonymizer']`: `'tor'`, `'proxy'`,
+  `'vpn'`, `'residential_proxy'`, `'hosting'`, `'anonymous'`, `'none'`, `'**'`.
+
+Both are **off by default** (unlike geo) and **database-only**: no CDN
+publishes a client-ASN or anonymizer header with meaningful deployment, so
+there is no header tier and none of geo's header-trust machinery applies —
+including the `geo_header`/`trusted_proxy_depth` boot conflict.
+
+Every signal keeps the same three-state contract:
+
+| Value | Meaning |
+| --- | --- |
+| `nil` | the signal is switched off |
+| `'**'` | switched on, but nothing resolved (no database, or lookup failed) |
+| a label | a real answer |
+
+## Configuration
+
+```ruby
+otto.configure_ip_privacy(
+  asn: true,
+  asn_db_path: 'data/origin-asn.mmdb',
+  anonymizer: true,
+  anonymizer_db_path: 'data/anonymizer.mmdb',
+)
+```
+
+Both accept the same bring-your-own-reader seam as geo (`asn_db_reader:` /
+`anonymizer_db_reader:` — any object responding to `#get(ip)`; a reader
+supplied in the same call wins over a path). Bad paths raise at boot, not
+per-request. The [`maxmind-db`](https://rubygems.org/gems/maxmind-db) gem is
+required only when a `*_db_path` is configured.
+
+## ASN: which address is looked up, and why that's safe
+
+The ASN lookup uses the **masked** IP, same as geo. This is not a compromise:
+IPv4 BGP routes are not announced longer than /24, so a /24-masked address
+falls inside the same announced prefix — and therefore the same ASN — as the
+real one. (IPv6 is coarser: at `octet_precision: 1` Otto zeroes the last 80
+bits, wider than many IPv6 announcements, so treat IPv6 ASN as best-effort.)
+
+### Data file
+
+> **Naming caution:** the country database this project recommends,
+> `geo-whois-asn-country`, does **not** contain ASN data. In
+> sapics/ip-location-db naming, `geo-whois-asn` describes the *sources* the
+> country data was derived from; the final token (`-country`) is what the
+> records contain. ASN data is a separate file type in that project.
+
+The recommended ASN file is
+[`origin-asn`](https://github.com/sapics/ip-location-db/tree/main/origin-asn/)
+from sapics/ip-location-db — like `geo-whois-asn-country` it is **PDDL v1.0
+(public domain)** and rebuilt daily, so the licensing/freshness posture
+matches the geo guidance:
+
+```bash
+curl -fsSL -o data/origin-asn.mmdb \
+  https://github.com/sapics/ip-location-db/releases/download/latest/origin-asn.mmdb
+```
+
+Its records carry a flat `autonomous_system_number` (verified against the
+published file), which is the primary key `AsnResolver` reads. GeoLite2-ASN
+and DB-IP ASN Lite MMDBs work too (same key; GeoLite2's EULA caveats from the
+geo doc apply). Reserved ASNs (0 per RFC 7607, the AS_TRANS placeholder 23456
+per RFC 6793) resolve to `'**'` rather than being reported as operators.
+
+## Anonymizer: the one unmasked lookup
+
+Anonymizer classification reads the **unmasked** address. This is deliberate
+and documented in `AnonymizerResolver` itself: anonymizer databases list
+individual egress nodes at or near /32, so the /24 equivalence that justifies
+masked geo and ASN lookups does not hold. A masked lookup would flag a whole
+/24 because one host in it runs a Tor exit, and miss the exit node itself —
+wrong in both directions.
+
+The privacy containment is the same one Otto already relies on for
+`hash_ip` and `env['otto.ip_match']`, which also consume the full IP: **only
+the derived value leaves**. The resolver returns a label; the address is
+never persisted, serialized, or handed downstream.
+
+### Reading the labels
+
+When several database flags are set at once (a Tor exit hosted at a cloud
+provider), the **most specific** label wins: `tor` > `proxy` > `vpn` >
+`residential_proxy` > `hosting` > `anonymous`.
+
+Two labels deserve care:
+
+- **`'none'`** means the database was consulted and does not list the
+  address. For an anonymizer database that is a real answer (these files
+  record only flagged addresses), but it is *not* a positive assertion the
+  visitor is residential — it is only as fresh as your database file.
+- **`'**'`** means no database answered at all. Do not collapse it into
+  `'none'`: `'none'` is evidence, `'**'` is the absence of evidence. A
+  "block anonymizers" rule that treats `'**'` as `'none'` fails open when
+  the database file goes missing.
+
+### Data file
+
+There is no public-domain anonymizer dataset of `origin-asn`'s quality; this
+signal is bring-your-own-database. `AnonymizerResolver` reads the MaxMind
+GeoIP2 Anonymous-IP flag schema (`is_tor_exit_node`, `is_public_proxy`,
+`is_anonymous_vpn`, `is_residential_proxy`, `is_hosting_provider`,
+`is_anonymous`), which commercial and self-built MMDBs alike use. A workable
+self-built option: compile the [Tor bulk exit
+list](https://check.torproject.org/torbulkexitlist) into an MMDB with
+`is_tor_exit_node` set — that covers the highest-signal label with fully
+public data.
+
+## Acceptance behavior summary
+
+| Scenario | Result |
+| --- | --- |
+| Signal not enabled | `nil` everywhere (env key absent for exempt IPs) |
+| Enabled, no database configured | `'**'` |
+| Database read raises | `'**'` (a lookup must never crash a request) |
+| ASN lookup | masked IP only (re-masked defensively in the resolver) |
+| Anonymizer lookup | unmasked IP in, label out, nothing else retained |
+| Private/localhost client (privacy-exempt) | no enrichment keys in env |
+| Bad `*_db_path` | raises at boot, not per-request |

data/docs/geo-country.md

@@ -3,7 +3,8 @@
 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.
+region lookup. (Two opt-in, database-only companion signals — ASN and
+anonymizer classification — are covered in [enrichment](enrichment.md).)
 
 ## Resolution order
 
@@ -152,7 +153,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/core/error_handler.rb

@@ -11,8 +11,8 @@ class Otto
     # Error handling module providing secure error reporting and logging functionality
     module ErrorHandler
       def handle_error(error, env)
-        # Check if this is a registered expected error
-        if handler_config = @error_handlers[error.class.name]
+        # Check if this is a registered expected error (exact match first, then ancestors)
+        if handler_config = find_error_handler(error)
           return handle_expected_error(error, env, handler_config)
         end
 
@@ -116,6 +116,19 @@ class Otto
 
       private
 
+      # Find the best matching error handler by walking the exception's ancestor chain.
+      # Returns the handler config for the most specific registered class, or nil.
+      def find_error_handler(error)
+        error.class.ancestors.each do |klass|
+          next unless klass.is_a?(Class)
+
+          if handler_config = @error_handlers[klass.name]
+            return handler_config
+          end
+        end
+        nil
+      end
+
       # Register all Otto framework error classes with appropriate status codes
       #
       # This method auto-registers base HTTP error classes and all framework-specific

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.
@@ -179,6 +193,30 @@ class Otto
       # Used by: Analytics, localization
       GEO_COUNTRY = 'otto.privacy.geo_country'
 
+      # Autonomous System Number of the network the client belongs to
+      # Type: String ('AS15169'), '**' when unresolved, or nil when disabled
+      # Set by: IPPrivacyMiddleware (opt-in; off unless asn_enabled)
+      # Used by: Network-operator allow/deny rules, dynamic access zones
+      # Read via: Otto::Request#asn
+      # Note: resolved from a local database against the MASKED IP, so it is
+      #   subject to the same /24 equivalence country relies on.
+      ASN = 'otto.privacy.asn'
+
+      # Anonymizing-egress classification for the client address
+      # Type: String label, or nil when disabled. One of: 'tor', 'proxy',
+      #   'vpn', 'residential_proxy', 'hosting', 'anonymous', 'none', '**'
+      # Set by: IPPrivacyMiddleware (opt-in; off unless anonymizer_enabled)
+      # Used by: "Block anonymizers" access zones, abuse triage
+      # Read via: Otto::Request#anonymizer
+      # Note: 'none' means the database was consulted and did not list the
+      #   address — a real answer, since these databases record only flagged
+      #   addresses. '**' means no database answered at all. The two are not
+      #   interchangeable: 'none' is evidence, '**' is the absence of it.
+      # Contrast: this is the one lookup performed on the UNMASKED address,
+      #   because anonymizer data is per-node (~/32) and a masked lookup would
+      #   answer for the node's neighbours. Only the label is retained.
+      ANONYMIZER = 'otto.privacy.anonymizer'
+
       # Daily-rotating IP hash for session correlation
       # Type: String (hexadecimal)
       # Set by: IPPrivacyMiddleware