otto 2.8.0 → 2.9.0

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.9.0:
+
+2.9.0 — 2026-08-18
+==================
+
+Added
+-----
+
+- Add opt-in request-scoped CSP directive extras for sources that are known
+  only while handling a request. Enable the feature at boot with
+  ``security_config.enable_csp_request_extras!``, then add approved source
+  origins by directive through ``env['otto.csp.extra_directives']``. This
+  supports cases such as adding a tenant's SSO provider to ``form-action``.
+  Disabled by default. (#243)
+
+Fixed
+-----
+
+- Prevent request-scoped CSP extras from invalidating valueless directives,
+  including ``upgrade-insecure-requests`` and ``block-all-mixed-content``.
+  Unsupported extras are ignored and logged; valid extras for other
+  directives continue to apply. (#243)
+
+Security
+--------
+
+- Validate request-scoped CSP extras before adding them to a response policy.
+  Extras can only add valid HTTP(S) origins to compatible directives already
+  present in the configured policy; script and default source directives are
+  excluded. Invalid or unsupported entries are ignored and logged without
+  affecting the remaining policy. (#243)
+
+- Reject request-scoped CSP extras for valueless directives during input
+  validation, with equivalent protection for direct CSP policy generation.
+  (#243)
+
+.. _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

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.8.0)
+    otto (2.9.0)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
@@ -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/README.md

@@ -129,7 +129,70 @@ result.skip_reason     # => nil (or :disabled / :blank_nonce / :non_html / :exis
 
 Apps with an existing nonce env-key convention can point the accessor at it with
 `app.security_config.csp_nonce_key = 'onetime.nonce'` — the views and the header
-still share one value.
+still share one value. Boot-time policy shaping goes through
+`security_config.csp_directive_overrides = { 'worker-src' => "'self' data: blob:" }`,
+which replaces (or with `nil`, removes) a directive's sources wholesale.
+
+#### Request-scoped directive extras
+
+Some directive values only exist at request time — the canonical case is a
+multi-tenant app that must allow the resolved tenant's SSO IdP origin in
+`form-action`. The channel is **boot-time opt-in** (the env key is a write
+surface any middleware in the Rack stack can reach, so it does not exist until
+boot code says so):
+
+```ruby
+app.security_config.enable_csp_request_extras!  # default: off
+```
+
+With the channel enabled, a handler (or middleware) writes a hash of directive
+name => additional source tokens to the env before the response is finalized:
+
+```ruby
+def signin(req, res)
+  idp_origin = resolve_tenant(req).idp_origin  # e.g. "https://login.example-idp.com"
+  req.env['otto.csp.extra_directives'] = { 'form-action' => [idp_origin] }
+  # ... render as usual; the emitted CSP now carries the origin
+end
+```
+
+Without the opt-in, the env key is ignored entirely — no sanitization, no
+logs. The `Writer::Result` returned by the emission surfaces reports what
+actually happened: `result.extra_directives` carries only the extras that
+landed in the policy; rejected or dropped entries are excluded and logged with
+request context instead.
+
+The extras channel is **additive-only** and deliberately narrow:
+
+- Tokens are appended to directives already present in the built policy,
+  deduplicated. A directive that is *absent* (not in the base set, or removed
+  by a boot override) is dropped — creating one at request time would tighten
+  the policy (`form-action` does not fall back to `default-src`), and
+  re-adding one would resurrect a deliberate removal.
+- Directives that take **no value** (`upgrade-insecure-requests`,
+  `block-all-mixed-content`) are refused during sanitization: a source appended
+  there would emit `upgrade-insecure-requests https://…`, which browsers treat
+  as malformed and discard — an extras key would silently switch the directive
+  *off*. The policy assembler independently leaves such directives
+  byte-identical for direct callers that bypass the sanitizer.
+- Only **origins** are accepted: `scheme://host[:port]` with an http(s) scheme
+  — no keywords (`'self'`, `'unsafe-inline'`), no scheme sources (`data:`,
+  `https:`), no wildcards, no paths, nothing that could smuggle a separator.
+- `script-src` (and `-elem`/`-attr`) and `default-src` are refused outright.
+  For the script family that is defence-in-depth policy, not nonce protection
+  (extras append, so the nonce would survive); `default-src` is refused
+  because widening it widens every unlisted directive at once.
+- Everything that fails validation is **dropped and logged** (`warn`, with the
+  directive, token, and reason) — a hostile value never raises, and the
+  response ships with the rest of the policy intact.
+
+Otto validates defensively, but it is not the policy authority: the app
+decides *which* origins to admit (resolve them from trusted per-request data,
+never echo attacker-controlled input). Extras live only in the request env —
+nothing is memoized on the (frozen-in-production) security config, so
+concurrent requests can never bleed into each other. The constant
+`Otto::EnvKeys::CSP::EXTRA_DIRECTIVES` (via `require 'otto/env_keys'`) names
+the key for downstream apps.
 
 > [!NOTE]
 > `res.send_csp_headers(content_type, nonce)` is **deprecated** in favour of

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
 

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

@@ -74,6 +74,28 @@ class Otto
     #   (e.g. 'onetime.nonce'), so the header and views still share one value.
     NONCE = 'otto.nonce'
 
+    # Content-Security-Policy request-scoped keys
+    module CSP
+      # Request-scoped CSP directive extras (delano/otto#243).
+      # Type: Hash{String|Symbol directive-name => String|Array<String> tokens}
+      # Set by: the consuming application (a handler, logic class, or
+      #   middleware) any time before the response is finalized
+      # Used by: Otto::Security::CSP::RequestExtras (read + sanitized) and
+      #   folded ADDITIVELY into the nonce policy by
+      #   Otto::Security::CSP::Policy.append_extra_sources at build time
+      # Note: BOOT-TIME OPT-IN — the channel does not exist until the app
+      #   calls Otto::Security::Config#enable_csp_request_extras! (default
+      #   off); without it the key is ignored entirely, no sanitize work and
+      #   no logs. The env key is a write surface any middleware in the Rack
+      #   stack can reach, a lower-trust position than boot code.
+      # Note: additive-only — extras can only APPEND origin tokens
+      #   (scheme://host[:port], http/https) to directives already present in
+      #   the built policy. The script-src family and default-src are refused
+      #   outright, keyword/scheme sources and wildcards are dropped, and every
+      #   drop is logged. See Otto::Security::CSP::RequestExtras.
+      EXTRA_DIRECTIVES = 'otto.csp.extra_directives'
+    end
+
     # 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
@@ -193,6 +215,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

data/lib/otto/privacy/anonymizer_resolver.rb

@@ -0,0 +1,138 @@
+# lib/otto/privacy/anonymizer_resolver.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Privacy
+    # Anonymizer (Tor / VPN / proxy / hosting) classification for IP addresses
+    #
+    # Answers one question — "is this address a known anonymizing egress, and
+    # of what kind?" — as a single label a downstream allow/deny rule can
+    # compare directly. Database-only, and the ONLY thing that ever leaves
+    # this resolver is the label.
+    #
+    # ## Why this one reads the UNMASKED address
+    #
+    # Every other database lookup in Otto operates on the masked IP, because
+    # country and ASN networks are >= /24 and a masked address lands in the
+    # same network as the real one. Anonymizer data breaks that equivalence:
+    # providers list individual egress nodes at or near /32, so a /24-masked
+    # lookup answers a question about the node's *neighbours* rather than the
+    # node. That produces wrong verdicts in both directions — flagging a whole
+    # /24 because one host in it is an exit node, and missing the exit node
+    # itself. A signal that quietly lies is worse than no signal.
+    #
+    # So this resolver takes the real address and returns only a label, which
+    # is the same trade Otto already makes twice: {IPPrivacy.hash_ip} consumes
+    # the full IP to emit an opaque digest, and +env['otto.ip_match']+ closes
+    # over the full IP to emit a boolean. The invariant Otto defends is that a
+    # raw address is never persisted, serialized, or handed downstream — not
+    # that it is unreachable in-process. A label honours that invariant; a
+    # masked lookup here would honour the letter of it while breaking the
+    # feature.
+    #
+    # ## Reading the 'none' label
+    #
+    # 'none' means "the database was consulted and did not list this address".
+    # Anonymizer databases are allow-list-by-omission — an address absent from
+    # the file is simply not a known egress — so absence is a real answer, not
+    # a miss. It is NOT a positive assertion that the address is a residential
+    # user, and it is only as fresh as the database file. '**' is reserved for
+    # "no database, or the lookup failed" — genuinely no answer.
+    #
+    # @example Configuring
+    #   otto.configure_ip_privacy(
+    #     anonymizer: true,
+    #     anonymizer_db_path: 'data/GeoIP2-Anonymous-IP.mmdb',
+    #   )
+    #
+    # @example Reading
+    #   req.anonymizer                 # => 'tor' | 'vpn' | 'none' | '**' | nil
+    #   env['otto.privacy.anonymizer']
+    #
+    class AnonymizerResolver
+      # Returned when classification is enabled but no database answered.
+      UNKNOWN = '**'
+
+      # Returned when the database was consulted and did not list the address.
+      NONE = 'none'
+
+      # Database flag => label, in precedence order. An address can carry
+      # several flags at once (a Tor exit node hosted at a cloud provider sets
+      # both +is_tor_exit_node+ and +is_hosting_provider+); the FIRST match
+      # wins, so the most specific and most access-relevant classification is
+      # what surfaces. Ordering rationale: Tor and public proxies are
+      # deliberate anonymity, commercial VPNs next, then residential proxies
+      # (frequently abuse infrastructure), then hosting — which is merely "not
+      # an eyeball network" and the weakest signal of the set.
+      CLASSIFICATIONS = [
+        %w[is_tor_exit_node tor],
+        %w[is_public_proxy proxy],
+        %w[is_anonymous_vpn vpn],
+        %w[is_residential_proxy residential_proxy],
+        %w[is_hosting_provider hosting],
+        # Generic catch-all: the provider says "anonymous" without saying how.
+        # Last, so it never masks a specific classification above.
+        %w[is_anonymous anonymous],
+      ].freeze
+
+      # Every label this resolver can emit, for consumers building zone rules.
+      LABELS = (CLASSIFICATIONS.map(&:last) + [NONE, UNKNOWN]).freeze
+
+      class << self
+        # Classify an IP address.
+        #
+        # @param ip [String] the UNMASKED client IP (see the class docs)
+        # @param config [Otto::Privacy::Config, nil] privacy configuration
+        # @return [String] one of {LABELS}
+        def resolve(ip, config = nil)
+          return UNKNOWN if ip.nil? || ip.empty?
+
+          check_anonymizer_database(ip, config) || UNKNOWN
+        end
+
+        private
+
+        # Look the address up in the configured anonymizer database.
+        #
+        # No masking: see the class documentation for why this resolver is the
+        # one exception, and note the record is reduced to a label before it
+        # returns, so the address itself goes no further.
+        #
+        # @return [String, nil] a label, or nil to fall through to UNKNOWN
+        def check_anonymizer_database(ip, config)
+          reader = config&.anonymizer_db_reader
+          return nil unless reader
+
+          classify(reader.get(ip))
+        rescue StandardError => e
+          warn "AnonymizerResolver database lookup error: #{e.message}" if $DEBUG
+          nil
+        end
+
+        # Reduce a database record to a single label.
+        #
+        # A nil record means "not listed", which for an anonymizer database is
+        # the meaningful answer NONE rather than a miss — these files record
+        # only flagged addresses. A non-Hash record is a malformed answer and
+        # falls through to UNKNOWN.
+        #
+        # @return [String, nil]
+        def classify(record)
+          return NONE if record.nil?
+          return nil unless record.is_a?(Hash)
+
+          match = CLASSIFICATIONS.find { |flag, _label| flagged?(record[flag]) }
+          match ? match.last : NONE
+        end
+
+        # MaxMind omits these keys entirely when false, so absent and false are
+        # the same answer. Accept the string forms too, since MMDB builds from
+        # other vendors sometimes encode the flags as text.
+        def flagged?(value)
+          value == true || value.to_s == 'true' || value.to_s == '1'
+        end
+      end
+    end
+  end
+end