otto 2.8.0 → 2.8.1

data/CHANGELOG.rst

@@ -7,6 +7,46 @@ 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

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.8.1)
       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/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

@@ -193,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

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

data/lib/otto/privacy/asn_resolver.rb

@@ -0,0 +1,149 @@
+# lib/otto/privacy/asn_resolver.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Privacy
+    # Autonomous System Number (ASN) resolution for IP addresses
+    #
+    # Provides the network operator an address belongs to, as a privacy-safe
+    # label a downstream allow/deny rule can compare directly. Resolution is
+    # database-only and operates on Otto's already-MASKED IP, exactly as
+    # {GeoResolver}'s database fallback does — the unmasked address never
+    # reaches this resolver.
+    #
+    # Resolution order (first hit wins), when a privacy Config is supplied:
+    # 1. Local MMDB lookup, masked before lookup (Config#asn_db_reader)
+    # 2. '**' (unknown)
+    #
+    # Resolution is honest: when no database resolves an ASN, the answer is
+    # '**' — never a guess. A caller can therefore distinguish three states:
+    # nil (ASN resolution is switched off), '**' (on, but no answer), and a
+    # real label.
+    #
+    # ## Why database-only
+    #
+    # Unlike country, no CDN publishes a client-ASN header with meaningful
+    # deployment, so there is no header tier to trust. Staying database-only
+    # also keeps ASN clear of the geo_header/trusted_proxy_depth boot conflict
+    # ({Otto::Security::Config::GEO_HEADER_DEPTH_CONFLICT_MESSAGE}): there is
+    # no header to be silently ignored under count-based proxy trust.
+    #
+    # ## Masking and accuracy
+    #
+    # IPv4 BGP routes are not announced longer than /24, so a /24-masked
+    # address lands in the same announced prefix — and therefore the same
+    # ASN — as the real one. That equivalence is what makes a masked lookup
+    # honest here, and it is weaker than it looks for IPv6: at
+    # +octet_precision: 1+ Otto zeroes the last 80 bits (a /48), which is
+    # coarser than many IPv6 announcements. Treat IPv6 ASN as best-effort.
+    #
+    # @example Configuring
+    #   otto.configure_ip_privacy(asn: true, asn_db_path: 'data/GeoLite2-ASN.mmdb')
+    #
+    # @example Reading
+    #   req.asn                       # => 'AS15169' | '**' | nil
+    #   env['otto.privacy.asn']
+    #
+    class AsnResolver
+      # Returned when ASN resolution is enabled but nothing resolved. Shared
+      # spelling with {GeoResolver::UNKNOWN} so consumers can treat every
+      # privacy label the same way.
+      UNKNOWN = '**'
+
+      # Reserved ASNs that carry no operator meaning: 0 is "reserved by the
+      # IANA" (RFC 7607) and 23456 is the AS_TRANS placeholder a 2-byte-only
+      # speaker substitutes for a 4-byte ASN (RFC 6793). A database that
+      # returns either has told us nothing, so both resolve to UNKNOWN rather
+      # than being dressed up as an answer.
+      RESERVED = [0, 23_456].freeze
+
+      # Highest assignable ASN; 4_294_967_295 is reserved (RFC 7300).
+      MAX_ASN = 4_294_967_294
+
+      class << self
+        # Resolve an ASN label for an IP address.
+        #
+        # @param ip [String] the ALREADY-MASKED client IP
+        # @param config [Otto::Privacy::Config, nil] privacy configuration
+        # @return [String] 'AS<number>' or {UNKNOWN}
+        def resolve(ip, config = nil)
+          return UNKNOWN if ip.nil? || ip.empty?
+
+          check_asn_database(ip, config) || UNKNOWN
+        end
+
+        private
+
+        # Look the masked IP up in the configured ASN database.
+        #
+        # The reader is any object responding to +#get(ip)+. A database read
+        # must never crash a request, so every StandardError falls through to
+        # "unknown" — the same posture {GeoResolver.check_geo_database} takes.
+        #
+        # @return [String, nil] 'AS<number>', or nil to fall through
+        def check_asn_database(ip, config)
+          reader = config&.asn_db_reader
+          return nil unless reader
+
+          # Re-mask defensively: masking is idempotent, so this costs nothing
+          # for an already-masked address and closes the hole if a caller ever
+          # hands us a raw one directly.
+          lookup_ip = IPPrivacy.mask_ip(ip, config.octet_precision) || ip
+          format_asn(extract_db_asn(reader.get(lookup_ip)))
+        rescue StandardError => e
+          warn "AsnResolver database lookup error: #{e.message}" if $DEBUG
+          nil
+        end
+
+        # Pull the AS number out of a database record.
+        #
+        # MaxMind's GeoLite2-ASN stores a flat +autonomous_system_number+ as a
+        # uint32. Some combined builds nest it under an 'asn' map, and a few
+        # emit the bare key 'asn'. Accept all three; anything else is not an
+        # answer.
+        #
+        # NOTE: the value is an Integer, not a String — the opposite of
+        # {GeoResolver.extract_db_country}'s terminal guard. Copying that
+        # method's String check here would discard every real hit.
+        #
+        # @return [Integer, nil]
+        def extract_db_asn(result)
+          return nil unless result.is_a?(Hash)
+
+          asn = result['asn']
+          number =
+            if asn.is_a?(Hash)
+              asn['autonomous_system_number'] || asn['number']
+            else
+              result['autonomous_system_number'] || asn
+            end
+          valid_asn?(number) ? number : nil
+        end
+
+        # @return [Boolean] whether the number is an assignable, meaningful ASN
+        def valid_asn?(number)
+          number.is_a?(Integer) &&
+            number.positive? &&
+            number <= MAX_ASN &&
+            !RESERVED.include?(number)
+        end
+
+        # Render as the conventional 'AS<number>' text form.
+        #
+        # A String — never the bare Integer — because the whole resolution
+        # chain, and Otto::Request's env fallbacks, treat a falsey value as
+        # "keep looking". A label is also what a downstream zone rule compares
+        # against, and it leaves room for the '**' sentinel that an Integer
+        # representation has no way to express.
+        #
+        # @return [String, nil]
+        def format_asn(number)
+          return nil if number.nil?
+
+          "AS#{number}"
+        end
+      end
+    end
+  end
+end