otto 2.8.0 → 2.9.0

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

data/lib/otto/privacy/config.rb

@@ -24,6 +24,10 @@ class Otto
     #   config = Otto::Privacy::Config.new
     #   config.octet_precision = 2  # Mask 2 octets instead of 1
     #
+    # rubocop:disable Metrics/ClassLength -- three parallel database
+    # configurations (geo, ASN, anonymizer) live here by design: each is a
+    # thin, symmetric writer/reader/loader trio, and splitting them into
+    # modules would hide the symmetry that makes them reviewable.
     class Config
       include Otto::Core::Freezable
 
@@ -49,8 +53,10 @@ class Otto
             audit: { disabled: true }.freeze,
       }.freeze
 
-      attr_accessor :octet_precision, :hash_rotation_period, :geo_enabled, :mask_private_ips
-      attr_reader :disabled, :correlation_secret, :geo_header, :geo_db_path
+      attr_accessor :octet_precision, :hash_rotation_period, :geo_enabled, :mask_private_ips,
+                    :asn_enabled, :anonymizer_enabled
+      attr_reader :disabled, :correlation_secret, :geo_header, :geo_db_path,
+                  :asn_db_path, :anonymizer_db_path
 
       # Class-level rotation key storage (mutable, not frozen with instances)
       # This is stored at the class level so it persists across frozen config instances
@@ -82,6 +88,23 @@ class Otto
       # @option options [#get] :geo_db_reader Bring-your-own MMDB reader (any object responding
       #   to #get, e.g. a MaxMind::DB or a compatible reader). Overrides :geo_db_path when set,
       #   so the reader choice stays independent of Otto. Default nil.
+      # @option options [Boolean] :asn_enabled Enable ASN resolution (default: FALSE — unlike
+      #   :geo_enabled, this signal is opt-in, so a deployment that never asks for it pays
+      #   nothing and no database is opened)
+      # @option options [String] :asn_db_path Filesystem path to a MaxMind-format (.mmdb) ASN
+      #   database (looked up on the already MASKED IP, like the geo database). Requires the
+      #   'maxmind-db' gem. A bad/unreadable path raises at boot, not per-request. Default nil.
+      # @option options [#get] :asn_db_reader Bring-your-own MMDB reader for ASN lookups (any
+      #   object responding to #get). Overrides :asn_db_path when set. Default nil.
+      # @option options [Boolean] :anonymizer_enabled Enable anonymizer (Tor/VPN/proxy/hosting)
+      #   classification (default: FALSE — opt-in, same as :asn_enabled)
+      # @option options [String] :anonymizer_db_path Filesystem path to a MaxMind-format (.mmdb)
+      #   anonymous-IP database. Looked up on the UNMASKED IP — anonymizer data lists individual
+      #   egress nodes at /32, so a masked lookup would answer for the node's neighbours; only
+      #   the resulting label leaves the resolver. Requires the 'maxmind-db' gem. A bad path
+      #   raises at boot. Default nil.
+      # @option options [#get] :anonymizer_db_reader Bring-your-own MMDB reader for anonymizer
+      #   lookups (any object responding to #get). Overrides :anonymizer_db_path. Default nil.
       # @option options [Boolean] :disabled Disable privacy entirely (default: false)
       # @option options [Boolean] :mask_private_ips Mask private/localhost IPs (default: false)
       # @option options [String] :correlation_secret A secret string that turns
@@ -119,8 +142,24 @@ class Otto
         @geo_db_override = nil # reader injected via geo_db_reader= (wins over path)
         self.geo_header = options[:geo_header] # canonicalized to an HTTP_* env key (or nil)
         self.geo_db_reader = options[:geo_db_reader] if options.key?(:geo_db_reader)
-        @geo_db_path = normalize_geo_db_path(options[:geo_db_path])
+        @geo_db_path = normalize_db_path(options[:geo_db_path])
         load_geo_database! # build/attach the reader now so a bad path fails at boot
+
+        # ASN enrichment (opt-in, boot-time only). Same two-ivar shape as geo.
+        @asn_enabled = options.fetch(:asn_enabled, false)
+        @asn_db_reader = nil
+        @asn_db_override = nil
+        self.asn_db_reader = options[:asn_db_reader] if options.key?(:asn_db_reader)
+        @asn_db_path = normalize_db_path(options[:asn_db_path])
+        load_asn_database!
+
+        # Anonymizer classification (opt-in, boot-time only).
+        @anonymizer_enabled = options.fetch(:anonymizer_enabled, false)
+        @anonymizer_db_reader = nil
+        @anonymizer_db_override = nil
+        self.anonymizer_db_reader = options[:anonymizer_db_reader] if options.key?(:anonymizer_db_reader)
+        @anonymizer_db_path = normalize_db_path(options[:anonymizer_db_path])
+        load_anonymizer_database!
       end
 
       # Set the stable correlation secret, validating its type up front.
@@ -163,7 +202,42 @@ class Otto
       #
       # @param value [String, nil] filesystem path to a .mmdb file, or nil
       def geo_db_path=(value)
-        @geo_db_path = normalize_geo_db_path(value)
+        @geo_db_path = normalize_db_path(value)
+      end
+
+      # Path to a MaxMind-format ASN database. See {#geo_db_path=}; the same
+      # boot-time contract applies — call {#load_asn_database!} to attach it.
+      #
+      # @param value [String, nil] filesystem path to a .mmdb file, or nil
+      def asn_db_path=(value)
+        @asn_db_path = normalize_db_path(value)
+      end
+
+      # Path to a MaxMind-format anonymous-IP database. See {#geo_db_path=};
+      # call {#load_anonymizer_database!} to attach it.
+      #
+      # @param value [String, nil] filesystem path to a .mmdb file, or nil
+      def anonymizer_db_path=(value)
+        @anonymizer_db_path = normalize_db_path(value)
+      end
+
+      # Replace one enrichment database path only after its new reader has
+      # opened successfully. Used by the boot-time configuration path; direct
+      # callers should normally use Otto#configure_ip_privacy.
+      #
+      # @param prefix [:asn, :anonymizer] database source to replace
+      # @param value [String, nil] new database path
+      # @return [void]
+      # @raise [ArgumentError] if an enabled signal's path cannot be opened
+      # @api private
+      def replace_enrichment_database_path!(prefix, value)
+        path = normalize_db_path(value)
+        enabled = instance_variable_get(:"@#{prefix}_enabled")
+        reader = path && enabled ? build_maxmind_reader(path, option_name: "#{prefix}_db_path") : nil
+
+        instance_variable_set(:"@#{prefix}_db_path", path)
+        instance_variable_set(:"@#{prefix}_db_override", nil)
+        instance_variable_set(:"@#{prefix}_db_reader", reader)
       end
 
       # Inject a ready-made MMDB reader (any object responding to #get).
@@ -202,6 +276,45 @@ class Otto
         @geo_enabled ? @geo_db_reader : nil
       end
 
+      # Inject a ready-made MMDB reader for ASN lookups. See {#geo_db_reader=}.
+      #
+      # @param reader [#get, nil] MMDB-compatible reader, or nil to clear
+      # @raise [ArgumentError] if reader does not respond to :get
+      def asn_db_reader=(reader)
+        unless reader.nil? || reader.respond_to?(:get)
+          raise ArgumentError, "asn_db_reader must respond to :get, got: #{reader.class}"
+        end
+
+        @asn_db_override = reader
+      end
+
+      # The effective ASN reader, or nil when ASN resolution is off.
+      #
+      # @return [#get, nil]
+      def asn_db_reader
+        @asn_enabled ? @asn_db_reader : nil
+      end
+
+      # Inject a ready-made MMDB reader for anonymizer lookups.
+      # See {#geo_db_reader=}.
+      #
+      # @param reader [#get, nil] MMDB-compatible reader, or nil to clear
+      # @raise [ArgumentError] if reader does not respond to :get
+      def anonymizer_db_reader=(reader)
+        unless reader.nil? || reader.respond_to?(:get)
+          raise ArgumentError, "anonymizer_db_reader must respond to :get, got: #{reader.class}"
+        end
+
+        @anonymizer_db_override = reader
+      end
+
+      # The effective anonymizer reader, or nil when classification is off.
+      #
+      # @return [#get, nil]
+      def anonymizer_db_reader
+        @anonymizer_enabled ? @anonymizer_db_reader : nil
+      end
+
       # Build/attach the geo database reader for the current configuration.
       #
       # Boot-time only. Resolves the effective reader (injected override wins
@@ -224,6 +337,39 @@ class Otto
           end
       end
 
+      # Build/attach the ASN database reader. See {#load_geo_database!} — same
+      # boot-time contract, same override-wins-over-path resolution.
+      #
+      # @return [void]
+      # @raise [ArgumentError] if the path is unreadable or maxmind-db is absent
+      def load_asn_database!
+        @asn_db_reader = nil
+        return unless @asn_enabled
+
+        @asn_db_reader =
+          if @asn_db_override
+            @asn_db_override
+          elsif @asn_db_path
+            build_maxmind_reader(@asn_db_path, option_name: 'asn_db_path')
+          end
+      end
+
+      # Build/attach the anonymizer database reader. See {#load_geo_database!}.
+      #
+      # @return [void]
+      # @raise [ArgumentError] if the path is unreadable or maxmind-db is absent
+      def load_anonymizer_database!
+        @anonymizer_db_reader = nil
+        return unless @anonymizer_enabled
+
+        @anonymizer_db_reader =
+          if @anonymizer_db_override
+            @anonymizer_db_override
+          elsif @anonymizer_db_path
+            build_maxmind_reader(@anonymizer_db_path, option_name: 'anonymizer_db_path')
+          end
+      end
+
       # Look up the preset hash for a named profile, failing fast on typos.
       #
       # @param profile [Symbol, String] one of the {PROFILES} keys
@@ -368,11 +514,12 @@ class Otto
 
       private
 
-      # Normalize a geo_db_path option to a non-empty String or nil.
+      # Normalize a database-path option to a non-empty String or nil. Shared by
+      # the geo, ASN and anonymizer paths — the rule is identical for all three.
       #
       # @param value [String, nil] raw path option
       # @return [String, nil]
-      def normalize_geo_db_path(value)
+      def normalize_db_path(value)
         return nil if value.nil?
 
         path = value.to_s.strip
@@ -390,22 +537,22 @@ class Otto
       # @param path [String] filesystem path to a .mmdb file
       # @return [MaxMind::DB] in-memory reader
       # @raise [ArgumentError] if the path is unreadable or the gem is missing
-      def build_maxmind_reader(path)
-        raise ArgumentError, "geo_db_path is not readable: #{path.inspect}" unless File.readable?(path)
+      def build_maxmind_reader(path, option_name: 'geo_db_path')
+        raise ArgumentError, "#{option_name} is not readable: #{path.inspect}" unless File.readable?(path)
 
         begin
           require 'maxmind/db'
         rescue LoadError
           raise ArgumentError,
-                "geo_db_path is set (#{path.inspect}) but the 'maxmind-db' gem is not available. " \
+                "#{option_name} is set (#{path.inspect}) but the 'maxmind-db' gem is not available. " \
                 "Add `gem 'maxmind-db'` to your Gemfile, or inject your own reader via " \
-                'configure_ip_privacy(geo_db_reader: ...).'
+                "configure_ip_privacy(#{option_name.sub('_path', '_reader')}: ...)."
         end
 
         begin
           MaxMind::DB.new(path, mode: MaxMind::DB::MODE_MEMORY)
         rescue StandardError => e
-          raise ArgumentError, "Failed to open geo_db_path #{path.inspect}: #{e.class}: #{e.message}"
+          raise ArgumentError, "Failed to open #{option_name} #{path.inspect}: #{e.class}: #{e.message}"
         end
       end
 
@@ -475,5 +622,6 @@ class Otto
         key
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/otto/privacy/core.rb

@@ -102,7 +102,9 @@ class Otto
       # them into a hash would only obscure the supported settings.
       def configure_ip_privacy(octet_precision: nil, hash_rotation: nil, geo: nil, redis: nil,
                                correlation_secret: nil, geo_header: nil, geo_db_path: nil,
-                               geo_db_reader: nil, profile: nil)
+                               geo_db_reader: nil, profile: nil, asn: nil, asn_db_path: nil,
+                               asn_db_reader: nil, anonymizer: nil, anonymizer_db_path: nil,
+                               anonymizer_db_reader: nil)
         # rubocop:enable Metrics/ParameterLists
         ensure_not_frozen!
         config = @security_config.ip_privacy_config
@@ -130,6 +132,8 @@ class Otto
 
         apply_geo_config(config, geo: geo, geo_header: geo_header,
                                  geo_db_path: geo_db_path, geo_db_reader: geo_db_reader)
+        apply_enrichment_signal(config, :asn, asn, asn_db_path, asn_db_reader)
+        apply_enrichment_signal(config, :anonymizer, anonymizer, anonymizer_db_path, anonymizer_db_reader)
       end
 
       private
@@ -184,6 +188,54 @@ class Otto
 
         config.load_geo_database! if geo_touched
       end
+
+      # Apply one opt-in enrichment signal (ASN or anonymizer classification).
+      #
+      # Same contract as {#apply_geo_config}: nil means "leave unchanged", a
+      # reader supplied in this call wins over a path, and a path supplied on
+      # its own clears any prior injected reader so it actually takes effect.
+      # Any touched knob triggers a boot-time (re)load so a bad path fails
+      # here, not on the first request that needs a lookup.
+      #
+      # These deliberately live outside apply_privacy_knobs. That runs twice —
+      # once against a shallow config.dup for the dry-run validation — and a
+      # dup shares reader ivars with the original, so loading a database there
+      # would touch live state during what is supposed to be a rehearsal.
+      #
+      # @param config [Otto::Privacy::Config] the privacy config to mutate
+      # @param prefix [Symbol] :asn or :anonymizer, selecting the config members
+      # @api private
+      def apply_enrichment_signal(config, prefix, enabled, path, reader)
+        previous_enabled = config.public_send(:"#{prefix}_enabled")
+        config.public_send(:"#{prefix}_enabled=", enabled) unless enabled.nil?
+        source_replaced = replace_db_source?(config, prefix, path, reader)
+        config.public_send(:"load_#{prefix}_database!") if !source_replaced && [enabled, path, reader].any? { |v| !v.nil? }
+      rescue StandardError
+        # A path replacement is validated before it is committed, but restoring
+        # the enabled flag here also keeps a combined `enabled: ..., path: ...`
+        # call all-or-nothing when the replacement cannot be opened.
+        config.public_send(:"#{prefix}_enabled=", previous_enabled) unless previous_enabled.nil?
+        raise
+      end
+
+      # Reader-vs-path precedence for one enrichment signal, mirroring the geo
+      # branch in {#apply_geo_config}.
+      #
+      # @api private
+      def replace_db_source?(config, prefix, path, reader)
+        if !reader.nil?
+          config.public_send(:"#{prefix}_db_reader=", reader)
+          config.public_send(:"#{prefix}_db_path=", path) unless path.nil?
+          false
+        elsif !path.nil?
+          # Build the replacement before changing the active source. A failed
+          # path must leave the previous reader available for future requests.
+          config.replace_enrichment_database_path!(prefix, path)
+          true
+        else
+          false
+        end
+      end
     end
   end
 end

data/lib/otto/privacy/redacted_fingerprint.rb

@@ -22,8 +22,8 @@ class Otto
     #
     class RedactedFingerprint
       attr_reader :session_id, :timestamp, :masked_ip, :hashed_ip,
-                  :country, :anonymized_ua, :request_path,
-                  :request_method, :referer
+                  :country, :asn, :anonymizer, :anonymized_ua,
+                  :request_path, :request_method, :referer
 
       # IP-bearing forwarded headers overwritten with the masked IP in the
       # geo-resolution env view. Mirrors the set
@@ -60,6 +60,17 @@ class Otto
         @country = if config.geo_enabled
                      GeoResolver.resolve(@masked_ip, geo_env(env), config, headers_trusted: geo_headers_trusted)
                    end
+        # ASN keeps the masked-IP contract: IPv4 routes are not announced longer
+        # than /24, so a masked address falls in the same announced prefix and
+        # therefore the same ASN.
+        @asn = AsnResolver.resolve(@masked_ip, config) if config.asn_enabled
+        # The anonymizer is the one lookup that gets the REAL address, for the
+        # same reason hashed_ip above does: masking would destroy the answer.
+        # Anonymizer databases list individual egress nodes at or near /32, so a
+        # /24-masked lookup would report on the node's neighbours instead of the
+        # node. Only the resulting label is retained — the address goes no
+        # further than the resolver, exactly as it goes no further than hash_ip.
+        @anonymizer = AnonymizerResolver.resolve(remote_ip, config) if config.anonymizer_enabled
         @anonymized_ua = anonymize_user_agent(env['HTTP_USER_AGENT'])
         @request_path = env['PATH_INFO']
         @request_method = env['REQUEST_METHOD']
@@ -78,6 +89,8 @@ class Otto
                masked_ip: @masked_ip,
                hashed_ip: @hashed_ip,
                  country: @country,
+                     asn: @asn,
+              anonymizer: @anonymizer,
            anonymized_ua: @anonymized_ua,
           request_method: @request_method,
             request_path: @request_path,

data/lib/otto/privacy.rb

@@ -7,6 +7,8 @@ require_relative 'privacy/config'
 require_relative 'privacy/ip_privacy'
 require_relative 'privacy/user_agent_privacy'
 require_relative 'privacy/geo_resolver'
+require_relative 'privacy/asn_resolver'
+require_relative 'privacy/anonymizer_resolver'
 require_relative 'privacy/redacted_fingerprint'
 
 # Otto::Privacy module provides IP address anonymization and privacy features
@@ -21,6 +23,13 @@ require_relative 'privacy/redacted_fingerprint'
 # - Geo-location resolution (country-level only): a configurable trusted header,
 #   built-in CDN provider headers, an optional local MaxMind-format (.mmdb)
 #   database looked up on the masked IP, or a custom resolver
+# - ASN resolution (opt-in, default off): the network operator an address
+#   belongs to, from a local .mmdb looked up on the masked IP. Database-only —
+#   no CDN publishes a client-ASN header worth trusting
+# - Anonymizer classification (opt-in, default off): whether an address is a
+#   known Tor / VPN / proxy / hosting egress, from a local .mmdb. The only
+#   lookup that reads the unmasked address, because anonymizer data lists
+#   individual nodes at /32 — it returns a label, never the address
 # - User agent anonymization (removes version numbers)
 #
 # Privacy is ENABLED BY DEFAULT. To disable:

data/lib/otto/request.rb

@@ -15,6 +15,8 @@ class Otto
   #   def show(req, res)
   #     req.masked_ip      # Privacy-safe masked IP
   #     req.geo_country    # ISO country code
+  #     req.asn            # Network operator, when enabled
+  #     req.anonymizer     # Tor/VPN/proxy label, when enabled
   #     req.check_locale!  # Set locale for request
   #   end
   #
@@ -63,6 +65,10 @@ class Otto
     # If you need the geo country:
     #   req.geo_country  # => 'US' or nil
     #
+    # If you need the opt-in enrichment signals (nil unless enabled):
+    #   req.asn         # => 'AS15169', '**', or nil
+    #   req.anonymizer  # => 'tor', 'none', '**', or nil
+    #
     # If you need the full privacy fingerprint:
     #   req.redacted_fingerprint  # => RedactedFingerprint object or nil
 
@@ -92,6 +98,39 @@ class Otto
       redacted_fingerprint&.country || env['otto.privacy.geo_country']
     end
 
+    # Get the Autonomous System Number of the client's network
+    #
+    # Opt-in: nil unless the operator enabled ASN resolution. '**' means it is
+    # enabled but nothing resolved — distinguishable from "switched off", which
+    # is what makes the three-state contract worth keeping.
+    #
+    # Read straight from env rather than through the fingerprint. The
+    # `fingerprint&.x || env[...]` idiom used above treats any falsey value as
+    # "fall through", which is wrong for a value whose vocabulary is fixed and
+    # whose absence is itself meaningful.
+    #
+    # @return [String, nil] 'AS15169', '**', or nil when disabled
+    # @example
+    #   req.asn  # => 'AS15169'
+    def asn
+      env['otto.privacy.asn']
+    end
+
+    # Get the anonymizing-egress classification for the client address
+    #
+    # Opt-in: nil unless the operator enabled classification. 'none' means the
+    # database was consulted and did not list the address; '**' means no
+    # database answered. Do not collapse the two — 'none' is evidence that the
+    # address is not a known egress, '**' is the absence of any evidence.
+    #
+    # @return [String, nil] 'tor', 'proxy', 'vpn', 'residential_proxy',
+    #   'hosting', 'anonymous', 'none', '**', or nil when disabled
+    # @example
+    #   req.anonymizer  # => 'tor'
+    def anonymizer
+      env['otto.privacy.anonymizer']
+    end
+
     # Get anonymized user agent string
     #
     # Returns user agent with version numbers stripped for privacy.

data/lib/otto/response.rb

@@ -124,6 +124,11 @@ class Otto
     # @return [Otto::Security::CSP::Writer::Result] the outcome (applied?, policy,
     #   skip_reason) for uniform observability
     #
+    # @note request-scoped directive extras (`env['otto.csp.extra_directives']`,
+    #   delano/otto#243) are seen only when this response has its {#request}
+    #   wired — the env is resolved via `request&.env`, so a bare Response
+    #   degrades gracefully to the base policy.
+    #
     # @example
     #   res['content-type'] = 'text/html; charset=utf-8'
     #   res.apply_csp(req.csp_nonce)
@@ -131,7 +136,8 @@ class Otto
       config = security_config || (request&.env && request.env['otto.security_config'])
       Otto::Security::CSP::Writer.apply(
         headers, nonce,
-        config: config, mode: mode, development_mode: development_mode
+        config: config, mode: mode, development_mode: development_mode,
+        env: request&.env # nil-safe: specs and bare responses have no request
       )
     end