openasn 0.2.0

data/lib/openasn/parsers.rb

@@ -0,0 +1,515 @@
+# frozen_string_literal: true
+
+require "json"
+require "rexml/document"
+require "zlib"
+
+module OpenASN
+  # Tier B body parsers, keyed by the `parser` ids in fetch-manifest.json.
+  #
+  # Contract: parse(parser_id, body) -> Array of CIDR/IP string tokens
+  # (junk tokens are fine — CidrUtils drops them). UNKNOWN parser ids make
+  # #known? false and the executor SKIPS that source with a warning: that's
+  # the forward-compatibility deal that lets the data repo add sources
+  # without breaking old gems.
+  #
+  # Parsers are deliberately tolerant of cosmetic drift (extra columns,
+  # comments, header rows) and deliberately strict about shape drift (a
+  # JSON schema change raises ParseError -> the executor keeps stale data
+  # and records the error, visible in OpenASN.dataset_info).
+  module Parsers
+    class ParseError < Error; end
+
+    PARSERS = {}
+
+    def self.register(id, &block) = PARSERS[id] = block
+    def self.known?(id)           = PARSERS.key?(id)
+
+    def self.parse(id, body)
+      handler = PARSERS[id] or raise ParseError, "unknown parser #{id}"
+      handler.call(body)
+    rescue ParseError
+      raise
+    rescue StandardError => e
+      raise ParseError, "#{id}: #{e.class}: #{e.message}"
+    end
+
+    # --- plain text shapes ---------------------------------------------------
+
+    register "plain_ip_per_line" do |body|
+      body.each_line.filter_map do |line|
+        t = line.strip
+        t unless t.empty? || t.start_with?("#")
+      end
+    end
+
+    register "plain_cidr_per_line" do |body|
+      body.each_line.filter_map do |line|
+        t = line.strip
+        t unless t.empty? || t.start_with?("#")
+      end
+    end
+
+    # First CSV column is a CIDR; used by Apple's relay list
+    # ("2.16.9.0/24,US,US-CA,,") and similar exports. Non-CIDR first
+    # columns (headers) simply fail CIDR parsing downstream and drop out.
+    register "csv_cidr_first_column" do |body|
+      body.each_line.filter_map do |line|
+        t = line.strip
+        next if t.empty? || t.start_with?("#")
+
+        t.split(",", 2).first&.strip
+      end
+    end
+
+    # RFC 8805 geofeeds: "prefix,country,region,city,zip" with '#' comments.
+    register "geofeed_csv" do |body|
+      body.each_line.filter_map do |line|
+        t = line.strip
+        next if t.empty? || t.start_with?("#")
+
+        t.split(",", 2).first&.strip
+      end
+    end
+
+    # --- structured cloud publications ---------------------------------------
+
+    register "aws_json" do |body|
+      data = JSON.parse(body)
+      v4 = (data["prefixes"] || []).filter_map { |p| p["ip_prefix"] }
+      v6 = (data["ipv6_prefixes"] || []).filter_map { |p| p["ipv6_prefix"] }
+      raise ParseError, "aws_json: no prefixes — schema changed?" if v4.empty? && v6.empty?
+
+      v4 + v6
+    end
+
+    register "gcp_json" do |body|
+      data = JSON.parse(body)
+      prefixes = (data["prefixes"] || []).filter_map { |p| p["ipv4Prefix"] || p["ipv6Prefix"] }
+      raise ParseError, "gcp_json: no prefixes — schema changed?" if prefixes.empty?
+
+      prefixes
+    end
+
+    register "azure_servicetags_json" do |body|
+      data = JSON.parse(body)
+      prefixes = (data["values"] || []).flat_map { |v| v.dig("properties", "addressPrefixes") || [] }
+      raise ParseError, "azure_servicetags_json: no addressPrefixes — schema changed?" if prefixes.empty?
+
+      prefixes
+    end
+
+    register "oci_json" do |body|
+      data = JSON.parse(body)
+      cidrs = (data["regions"] || []).flat_map { |r| (r["cidrs"] || []).filter_map { |c| c["cidr"] } }
+      raise ParseError, "oci_json: no cidrs — schema changed?" if cidrs.empty?
+
+      cidrs
+    end
+
+    # Zscaler CENR: nested {"zscaler.net": {"continent …": {"city …": [{"range": …}]}}}.
+    # Shape verified live 2026-07-04; we walk generically so cosmetic
+    # nesting changes don't break us.
+    register "zscaler_json" do |body|
+      ranges = []
+      walk = lambda do |node|
+        case node
+        when Hash
+          ranges << node["range"] if node["range"].is_a?(String)
+          node.each_value { |v| walk.call(v) }
+        when Array
+          node.each { |v| walk.call(v) }
+        end
+      end
+      walk.call(JSON.parse(body))
+      raise ParseError, "zscaler_json: no ranges — schema changed?" if ranges.empty?
+
+      ranges
+    end
+
+    # --- structured VPN provider publications -------------------------------
+
+    register "mullvad_relays_json" do |body|
+      data = JSON.parse(body)
+      raise ParseError, "mullvad_relays_json: expected array" unless data.is_a?(Array)
+
+      # First-party public API behind https://mullvad.net/en/servers. Mozilla
+      # VPN / Firefox VPN use Mullvad infrastructure, but the relay list cannot
+      # distinguish a Mozilla customer from a direct Mullvad customer, so the
+      # provider attribution remains the network operator: Mullvad.
+      tokens = data.select { |r| r["active"] != false }.flat_map do |relay|
+        [relay["ipv4_addr_in"], relay["ipv6_addr_in"]]
+      end.compact
+      raise ParseError, "mullvad_relays_json: no active relay IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "ivpn_servers_json" do |body|
+      data = JSON.parse(body)
+      tokens = []
+      (data["wireguard"] || []).each do |location|
+        (location["hosts"] || []).each { |host| tokens << host["host"] }
+      end
+      (data["openvpn"] || []).each do |location|
+        tokens.concat(location["ip_addresses"] || [])
+      end
+      tokens.compact!
+      raise ParseError, "ivpn_servers_json: no server IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "pia_servers_json" do |body|
+      # PIA appends a detached signature after the first JSON line. The first
+      # line is the server document the official clients consume.
+      data = JSON.parse(body.lines.first.to_s)
+      tokens = (data["regions"] || []).flat_map do |region|
+        next [] if region["offline"] == true
+
+        (region["servers"] || {}).values.flatten.filter_map { |server| server["ip"] }
+      end
+      raise ParseError, "pia_servers_json: no server IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "airvpn_status_json" do |body|
+      data = JSON.parse(body)
+      tokens = (data["servers"] || []).flat_map do |server|
+        server.filter_map do |key, value|
+          value if key.match?(/\Aip_v[46]_in\d+\z/)
+        end
+      end
+      raise ParseError, "airvpn_status_json: no entry IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "windscribe_serverlist_json" do |body|
+      data = JSON.parse(body)
+      tokens = (data["data"] || []).flat_map do |location|
+        next [] unless location["status"] == 1
+
+        (location["groups"] || []).flat_map do |group|
+          group_tokens = [group["ping_ip"]]
+          group_tokens.concat((group["nodes"] || []).flat_map { |node| [node["ip"], node["ip2"], node["ip3"]] })
+          group_tokens
+        end
+      end.compact
+      raise ParseError, "windscribe_serverlist_json: no server IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "privado_servers_json" do |body|
+      data = JSON.parse(body)
+      tokens = (data["servers"] || []).filter_map { |server| server["ip"] }
+      raise ParseError, "privado_servers_json: no server IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "leap_eip_service_json" do |body|
+      data = JSON.parse(body)
+      tokens = (data["gateways"] || []).filter_map { |gateway| gateway["ip_address"] }
+      raise ParseError, "leap_eip_service_json: no gateway IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "wlvpn_server_list_xml" do |body|
+      doc = REXML::Document.new(body)
+      tokens = []
+      doc.elements.each("//server") do |server|
+        next unless server.attributes["visible"].to_s == "1" && server.attributes["status"].to_s == "1"
+
+        ip = server.attributes["ip"].to_s.strip
+        tokens << ip unless ip.empty?
+      end
+      raise ParseError, "wlvpn_server_list_xml: no visible active server IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "surfshark_clusters_json" do |body|
+      data = JSON.parse(body)
+      raise ParseError, "surfshark_clusters_json: expected array" unless data.is_a?(Array)
+
+      tokens = data.filter_map { |cluster| cluster["connectionName"] }
+      raise ParseError, "surfshark_clusters_json: no connectionName hostnames — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "nordvpn_servers_json" do |body|
+      data = JSON.parse(body)
+      data = data["servers"] if data.is_a?(Hash)
+      raise ParseError, "nordvpn_servers_json: expected array" unless data.is_a?(Array)
+
+      tokens = data.select { |server| server["status"] == "online" }.flat_map do |server|
+        ips = [server["station"], server["ipv6_station"], server["station_ipv6"]]
+        ips.concat((server["ips"] || []).filter_map { |entry| entry.dig("ip", "ip") })
+        ips
+      end.compact.reject(&:empty?)
+      raise ParseError, "nordvpn_servers_json: no server IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "vpngate_csv" do |body|
+      tokens = body.each_line.filter_map do |line|
+        next if line.start_with?("*", "#")
+
+        line.split(",", 3)[1]&.strip
+      end
+      raise ParseError, "vpngate_csv: no relay IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "ovpn_zip_remote_hosts" do |body|
+      tokens = unzip_files(body).flat_map do |name, content|
+        # TunnelBear's first-party Linux ZIP currently includes a few valid
+        # OpenVPN configs with a defensive ".ovpn.txt" suffix. Accept only
+        # the two explicit OpenVPN suffixes so README/license text cannot
+        # accidentally become source data.
+        next [] unless name.downcase.end_with?(".ovpn", ".ovpn.txt")
+
+        openvpn_remote_hosts(content)
+      end
+      raise ParseError, "ovpn_zip_remote_hosts: no OpenVPN remote hosts — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "vpnbook_html_hosts" do |body|
+      tokens = body.scan(/\b[a-z0-9-]+\.vpnbook\.com\b/i).reject { |host| host.downcase == "www.vpnbook.com" }
+      raise ParseError, "vpnbook_html_hosts: no vpnbook.com hosts — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "html_table_hostnames" do |body|
+      tokens = body.scan(%r{<td\b[^>]*>(.*?)</td>}im).flat_map do |cell|
+        # Some first-party support tables split hostnames across inline tags,
+        # e.g. `ca1.<span>vpn.giganews.com</span>`. Strip markup inside each
+        # cell before scanning so the parser stays generic without scraping
+        # arbitrary hostnames from the whole page chrome.
+        text = cell.first.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+                   .gsub(/<[^>]*>/, "").gsub(/&nbsp;|&#160;/i, " ").tr("\u00A0", " ")
+        text.scan(/\b[a-z0-9.-]+\.[a-z]{2,63}\b/i)
+      end.map(&:downcase)
+      raise ParseError, "html_table_hostnames: no hostnames — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "strongvpn_locations_html" do |body|
+      tokens = body.scan(/\bvpn-[a-z0-9-]+\.reliablehosting\.com\b/i).map(&:downcase)
+      raise ParseError, "strongvpn_locations_html: no StrongVPN hostnames — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "vpnsecure_locations_html" do |body|
+      tokens = body.scan(%r{</div>\s*([a-z]{2,3}\d+)\s*<span[^>]*class=["'][^"']*\bstatus--up\b[^"']*["'][^>]*>\s*up\s*</span>}i)
+                   .flatten
+                   .map { |host| "#{host.downcase}.isponeder.com" }
+      raise ParseError, "vpnsecure_locations_html: no up hosts — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "worldvpn_servers_html" do |body|
+      # WorldVPN's public server table gives exact IPs next to
+      # *.ocservvpn.com hostnames. Keep this parser table-shaped instead of
+      # doing a whole-page IP scrape; WordPress/CSS assets can contain
+      # version-looking strings that must not become VPN evidence.
+      tokens = body.scan(/<tr\b.*?<\/tr>/mi).filter_map do |row|
+        cells = row.scan(/<td\b[^>]*>(.*?)<\/td>/mi).flatten.map { |cell| strip_html(cell) }
+        ip = cells[1].to_s
+        host = cells[2].to_s.downcase
+        next unless ip.match?(/\A(?:\d{1,3}\.){3}\d{1,3}\z/) && host.match?(/\A[a-z]{2}\d+\.ocservvpn\.com\z/)
+
+        ip
+      end
+      raise ParseError, "worldvpn_servers_html: no server IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "ovpn_status_servers_json" do |body|
+      data = JSON.parse(body)
+      rows = data["data"]
+      raise ParseError, "ovpn_status_servers_json: expected data array" unless rows.is_a?(Array)
+
+      tokens = rows.filter_map do |server|
+        next if server["online"] == false
+
+        server["ip"]
+      end
+      raise ParseError, "ovpn_status_servers_json: no online server IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "anonine_status_json" do |body|
+      data = JSON.parse(body)
+      raise ParseError, "anonine_status_json: expected array" unless data.is_a?(Array)
+
+      tokens = data.flat_map do |row|
+        server_ips = (row["servers"] || []).flat_map { |server| server["ips"] || [] }
+        [row["primary_ip"], *server_ips]
+      end.compact
+      raise ParseError, "anonine_status_json: no server IPs — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "azirevpn_locations_json" do |body|
+      data = JSON.parse(body)
+      rows = data["locations"]
+      raise ParseError, "azirevpn_locations_json: expected locations array" unless rows.is_a?(Array)
+
+      tokens = rows.filter_map { |location| location["pool"] }
+      raise ParseError, "azirevpn_locations_json: no pool hostnames — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "vpnac_status_html" do |body|
+      tokens = body.scan(%r{<td\b[^>]*>\s*([a-z0-9][a-z0-9.-]*\.vpn\.ac)\s*</td>}i)
+                   .flatten
+                   .map(&:downcase)
+      raise ParseError, "vpnac_status_html: no status table hostnames — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "trustzone_servers_html" do |body|
+      tokens = body.scan(/\b[a-z0-9]+(?:-[a-z0-9]+)*\.trust\.zone\b/i)
+                   .map(&:downcase)
+                   .reject { |host| host == "www.trust.zone" || host == "trust.zone" }
+      raise ParseError, "trustzone_servers_html: no Trust.Zone server hostnames — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "slickvpn_locations_html" do |body|
+      tokens = body.scan(%r{<a\b[^>]*href=["']https://members\.newsdemon\.com/vpn/2025/[^"']+\.ovpn["'][^>]*>(.*?)</a>}im).flat_map do |label|
+        label.first.to_s.gsub(/<[^>]*>/, " ").scan(/\bgw\d+\.[a-z0-9.-]+\.slickvpn\.com\b/i)
+      end.map(&:downcase)
+      raise ParseError, "slickvpn_locations_html: no SlickVPN config-linked hostnames — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    register "freevpn_us_status_html" do |body|
+      allowed = {
+        "openvpn" => /\Aovpn-[a-z0-9-]+\.vpnv\.cc\z/i,
+        "wireguard" => /\Awireguard-[a-z0-9-]+\.vpnv\.cc\z/i,
+        "pptp" => /\Apptp-[a-z0-9-]+\.vpnv\.cc\z/i
+      }
+
+      tokens = body.scan(/<tr\b[^>]*>/i).filter_map do |tag|
+        type = tag[/\bdata-type=["']([^"']+)["']/i, 1].to_s.downcase
+        host = tag[/\bdata-host=["']([^"']+)["']/i, 1].to_s.downcase
+        pattern = allowed[type]
+        host if pattern && host.match?(pattern)
+      end
+      raise ParseError, "freevpn_us_status_html: no VPN hosts — schema changed?" if tokens.empty?
+
+      tokens.uniq
+    end
+
+    class << self
+      private
+
+      def strip_html(fragment)
+        fragment.gsub(/<[^>]+>/, " ")
+                .gsub(/&nbsp;|&#160;/i, " ")
+                .gsub(/\s+/, " ")
+                .strip
+      end
+
+      def openvpn_remote_hosts(content)
+        content.each_line.filter_map do |line|
+          match = line.match(/\Aremote\s+([^\s]+)(?:\s|$)/i)
+          match && match[1].delete_prefix("[").delete_suffix("]")
+        end
+      end
+
+      # Deflate expands up to ~1000:1 and these archives arrive from remote
+      # servers: cap inflated output so a hostile/compromised archive costs
+      # at most bounded memory (ParseError -> keep-stale), never an OOM.
+      # Real provider config archives inflate to single-digit MB.
+      MAX_INFLATED_BYTES = 64 * 1024 * 1024
+
+      # Minimal ZIP reader for first-party OpenVPN config archives. We keep
+      # this in stdlib Ruby instead of adding rubyzip so the gem stays
+      # dependency-free. It supports the two methods seen in provider archives:
+      # stored (0) and deflated (8), using the central directory so data
+      # descriptors in local file headers do not matter.
+      def unzip_files(body)
+        bytes = body.b
+        eocd = bytes.rindex("PK\x05\x06".b) or raise ParseError, "zip: missing end of central directory"
+        entries = bytes.byteslice(eocd + 10, 2).unpack1("v")
+        cd_offset = bytes.byteslice(eocd + 16, 4).unpack1("V")
+        pos = cd_offset
+        files = []
+        total_inflated = 0
+
+        entries.times do
+          raise ParseError, "zip: malformed central directory" unless bytes.byteslice(pos, 4) == "PK\x01\x02".b
+
+          method = bytes.byteslice(pos + 10, 2).unpack1("v")
+          compressed_size = bytes.byteslice(pos + 20, 4).unpack1("V")
+          name_length = bytes.byteslice(pos + 28, 2).unpack1("v")
+          extra_length = bytes.byteslice(pos + 30, 2).unpack1("v")
+          comment_length = bytes.byteslice(pos + 32, 2).unpack1("v")
+          local_offset = bytes.byteslice(pos + 42, 4).unpack1("V")
+          name = bytes.byteslice(pos + 46, name_length).force_encoding(Encoding::UTF_8).scrub
+          pos += 46 + name_length + extra_length + comment_length
+
+          next if name.end_with?("/")
+          raise ParseError, "zip: malformed local header for #{name}" unless bytes.byteslice(local_offset, 4) == "PK\x03\x04".b
+
+          local_name_length = bytes.byteslice(local_offset + 26, 2).unpack1("v")
+          local_extra_length = bytes.byteslice(local_offset + 28, 2).unpack1("v")
+          data_start = local_offset + 30 + local_name_length + local_extra_length
+          compressed = bytes.byteslice(data_start, compressed_size)
+          content = case method
+                    when 0 then compressed
+                    when 8 then bounded_inflate(compressed, name)
+                    else
+                      raise ParseError, "zip: unsupported compression method #{method} for #{name}"
+                    end
+          total_inflated += content.bytesize
+          raise ParseError, "zip: archive inflates past #{MAX_INFLATED_BYTES} bytes - refusing" if total_inflated > MAX_INFLATED_BYTES
+
+          files << [name, content.force_encoding(Encoding::UTF_8).scrub]
+        end
+
+        files
+      end
+
+      # Inflate in chunks, aborting the moment cumulative output crosses the
+      # cap; the bomb never gets to materialize in memory.
+      def bounded_inflate(compressed, name)
+        inflater = Zlib::Inflate.new(-Zlib::MAX_WBITS)
+        out = +"".b
+        begin
+          inflater.inflate(compressed) do |chunk|
+            out << chunk
+            raise ParseError, "zip: #{name} inflates past #{MAX_INFLATED_BYTES} bytes - refusing" if out.bytesize > MAX_INFLATED_BYTES
+          end
+          out << inflater.finish unless inflater.finished?
+        ensure
+          inflater.close
+        end
+        out
+      end
+    end
+  end
+end

data/lib/openasn/railtie.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenASN
+  class Railtie < Rails::Railtie
+    # Make OpenASN::UpdateJob exist as soon as ActiveJob does.
+    initializer "openasn.update_job" do
+      ActiveSupport.on_load(:active_job) { require "openasn/update_job" }
+    end
+
+    # Opportunistic staleness check: if the newest data on
+    # disk is older than a week and auto_update is on, enqueue a refresh.
+    # Uses a cheap file probe — it must NOT force the dataset to load at
+    # boot (lazy-load is the contract; eager_load! is opt-in). Deliberately
+    # skipped in test env, deliberately best-effort: a broken queue must
+    # never break boot.
+    config.after_initialize do
+      next if Rails.env.test?
+      next unless OpenASN.configuration.auto_update
+
+      begin
+        if OpenASN.data_stale_on_disk? && defined?(OpenASN::UpdateJob)
+          OpenASN::UpdateJob.perform_later
+          OpenASN.configuration.logger.info("openasn: dataset older than 7 days — background refresh enqueued")
+        end
+      rescue StandardError => e
+        OpenASN.configuration.logger.warn("openasn: boot staleness check skipped (#{e.message})")
+      end
+    end
+  end
+end

data/lib/openasn/result.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module OpenASN
+  # The answer to "where is this IP really coming from?". Immutable.
+  #
+  # Verdict-first design: `verdict` is the closed enum; the predicates are
+  # sugar. There is deliberately NO `suspicious?` — that's a policy word,
+  # and drawing that line belongs to your application, not this gem.
+  #
+  # STABILITY CONTRACT (README "API stability contract" is the canonical
+  # text; keep in sync): VERDICTS is append-only — never remove, rename,
+  # or redefine an entry; additions land in minor versions with a loud
+  # CHANGELOG note. Verdicts are compiled code, never data: a data refresh
+  # cannot introduce one. to_h keys are append-only. The same contract
+  # binds every future client (openasn-js, …) — the enum is the project's
+  # cross-language API, defined in the data repo's DECISIONS.md.
+  class Result
+    VERDICTS = %i[
+      residential_isp mobile business hosting vpn tor_exit relay
+      enterprise_gateway education government cgnat private unknown
+    ].freeze
+
+    # High-confidence "this is infrastructure, not an eyeball connection".
+    INFRASTRUCTURE_VERDICTS = %i[hosting vpn tor_exit].freeze
+
+    # "Very likely a human being on the other end" — including the classes
+    # people wrongly block: relay users are paying iCloud+ customers,
+    # CGNAT/mobile IPs are hundreds of people each, enterprise gateways are
+    # entire offices. Note the deliberate asymmetry: business/education/
+    # government/unknown are NEITHER infrastructure nor likely_human — your
+    # app decides those.
+    LIKELY_HUMAN_VERDICTS = %i[residential_isp mobile relay cgnat enterprise_gateway].freeze
+
+    attr_reader :ip, :verdict, :asn, :as_org, :category, :network_role,
+                :provider, :sources, :flags, :context_flags
+
+    def initialize(ip:, verdict:, asn: nil, as_org: nil, category: nil,
+                   network_role: nil, provider: nil, sources: [], flags: 0,
+                   context_flags: [], unrouted: false)
+      @ip = ip
+      @verdict = verdict
+      @asn = asn
+      @as_org = as_org
+      @category = category
+      @network_role = network_role
+      @provider = provider
+      @sources = sources.freeze
+      @flags = flags
+      @context_flags = context_flags.freeze
+      @unrouted = unrouted
+      freeze
+    end
+
+    def infrastructure? = INFRASTRUCTURE_VERDICTS.include?(verdict)
+    def likely_human?   = LIKELY_HUMAN_VERDICTS.include?(verdict)
+
+    def vpn?     = verdict == :vpn
+    def hosting? = verdict == :hosting
+    def tor?     = verdict == :tor_exit
+    def relay?   = verdict == :relay
+    def mobile?  = verdict == :mobile
+    def private? = verdict == :private
+    def cgnat?   = verdict == :cgnat
+
+    # True when no ASN announces this IP (unallocated/unrouted space).
+    def unrouted? = @unrouted
+
+    # Everything, for logging and shadow mode. Stable keys — CarHey-style
+    # shadow analyses depend on this shape staying append-only.
+    def to_h
+      {
+        ip: ip,
+        verdict: verdict,
+        infrastructure: infrastructure?,
+        likely_human: likely_human?,
+        asn: asn,
+        as_org: as_org,
+        category: category,
+        network_role: network_role,
+        provider: provider,
+        sources: sources,
+        flags: flags,
+        context_flags: context_flags,
+        unrouted: unrouted?
+      }
+    end
+
+    def inspect
+      "#<OpenASN::Result #{ip} verdict=#{verdict}#{asn ? " AS#{asn}" : ''}#{as_org ? " (#{as_org})" : ''} sources=#{sources.inspect}>"
+    end
+    alias to_s inspect
+  end
+end