openasn 0.2.0

data/lib/openasn/binary_format.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module OpenASN
+  # Reader for the OASN v1 artifact format and the OORG v1 org-names
+  # sidecar. The byte-exact spec lives in the data repo:
+  # https://github.com/openasn/openasn/blob/main/FORMAT.md — this file is an
+  # independent implementation of that document and must never drift from
+  # it. All integers big-endian. Readers REJECT unknown format versions on
+  # purpose: half-understanding an artifact is worse than keeping last-good
+  # data.
+  module BinaryFormat
+    MAGIC = "OASN"
+    ORG_MAGIC = "OORG"
+    FORMAT_VERSION = 0x01
+    HEADER_SIZE = 32
+    ORG_HEADER_SIZE = 16
+
+    # flags (u16) bit layout — see FORMAT.md
+    FLAG_BAD_ASN       = 1 << 8
+    FLAG_VPN_PROVIDER  = 1 << 9
+    FLAG_MOBILE        = 1 << 10
+    FLAG_ENTERPRISE_GW = 1 << 11
+    FLAG_CDN           = 1 << 12
+    FLAG_HOSTING_EXTRA = 1 << 13
+
+    CATEGORY_MASK = 0x000F
+    ROLE_SHIFT    = 4
+    ROLE_MASK     = 0x00F0
+
+    CATEGORIES = [nil, "isp", "hosting", "business", "education_research", "government_admin"].freeze
+    ROLES      = [nil, "tier1_transit", "major_transit", "midsize_transit",
+                  "access_provider", "content_network", "stub"].freeze
+
+    FLAG_NAMES = {
+      FLAG_BAD_ASN => :bad_asn,
+      FLAG_VPN_PROVIDER => :vpn_provider,
+      FLAG_MOBILE => :mobile_carrier,
+      FLAG_ENTERPRISE_GW => :enterprise_gw,
+      FLAG_CDN => :cdn,
+      FLAG_HOSTING_EXTRA => :hosting_extra
+    }.freeze
+
+    module_function
+
+    def category_name(flags) = CATEGORIES[flags & CATEGORY_MASK]
+    def role_name(flags)     = ROLES[(flags & ROLE_MASK) >> ROLE_SHIFT]
+
+    def flag_names(flags)
+      FLAG_NAMES.filter_map { |bit, name| name if flags.anybits?(bit) }
+    end
+
+    def addr_size(family)        = family == :ipv4 ? 4 : 16
+    def base_rec_size(family)    = family == :ipv4 ? 14 : 38
+    def overlay_rec_size(family) = family == :ipv4 ? 8 : 32
+
+    def pack_addr(int, family)
+      if family == :ipv4
+        [int].pack("N")
+      else
+        [int >> 64, int & 0xFFFF_FFFF_FFFF_FFFF].pack("Q>Q>")
+      end
+    end
+
+    # Parse a full OASN artifact into its layers.
+    # -> { family:, build_ts:, base: BaseLayer, vpn: OverlayLayer, dc: OverlayLayer, relay: OverlayLayer }
+    def parse_artifact(bytes, mode: :packed)
+      raise FormatError, "not an OASN artifact (bad magic)" unless bytes[0, 4] == MAGIC
+
+      version = bytes.getbyte(4)
+      raise FormatError, "unsupported OASN format_version #{version} (this gem speaks v#{FORMAT_VERSION}); update the openasn gem" unless version == FORMAT_VERSION
+
+      family = bytes.getbyte(5) == 0x04 ? :ipv4 : :ipv6
+      build_ts = bytes[8, 8].unpack1("Q>")
+      base_n, vpn_n, dc_n, relay_n = bytes[16, 16].unpack("NNNN")
+
+      brec = base_rec_size(family)
+      orec = overlay_rec_size(family)
+      expected = HEADER_SIZE + base_n * brec + (vpn_n + dc_n + relay_n) * orec
+      raise FormatError, "artifact truncated or padded: #{bytes.bytesize} bytes, header implies #{expected}" unless bytes.bytesize == expected
+
+      offset = HEADER_SIZE
+      base  = bytes[offset, base_n * brec];  offset += base_n * brec
+      vpn   = bytes[offset, vpn_n * orec];   offset += vpn_n * orec
+      dc    = bytes[offset, dc_n * orec];    offset += dc_n * orec
+      relay = bytes[offset, relay_n * orec]
+
+      {
+        family: family, build_ts: build_ts,
+        base: BaseLayer.build(base, family, mode),
+        vpn: OverlayLayer.build(vpn, family, mode),
+        dc: OverlayLayer.build(dc, family, mode),
+        relay: OverlayLayer.build(relay, family, mode)
+      }
+    end
+
+    # --- Base layer: [start, end, asn, flags] records -----------------------
+
+    module BaseLayer
+      def self.build(bytes, family, mode)
+        mode == :arrays ? ArraysBase.new(bytes, family) : PackedBase.new(bytes, family)
+      end
+    end
+
+    # Packed mode: binary search directly over the artifact bytes.
+    # ~6MB resident for all of IPv4, ~19µs/lookup (measured on the format's
+    # validation prototype). Key comparisons happen on raw big-endian
+    # address bytes: for unsigned BE values, bytewise String comparison IS
+    # numeric comparison, which lets IPv4 and IPv6 share one search.
+    class PackedBase
+      attr_reader :count
+
+      def initialize(bytes, family)
+        @bytes = bytes.freeze
+        @family = family
+        @asz = BinaryFormat.addr_size(family)
+        @rec = BinaryFormat.base_rec_size(family)
+        @count = bytes.bytesize / @rec
+      end
+
+      # -> [asn, flags] | nil
+      def find(ip_int)
+        key = BinaryFormat.pack_addr(ip_int, @family)
+        lo = 0
+        hi = @count - 1
+        while lo <= hi
+          mid = (lo + hi) / 2
+          off = mid * @rec
+          if key < @bytes[off, @asz]
+            hi = mid - 1
+          elsif key > @bytes[off + @asz, @asz]
+            lo = mid + 1
+          else
+            return @bytes[off + 2 * @asz, 6].unpack("Nn")
+          end
+        end
+        nil
+      end
+    end
+
+    # Arrays mode: unpack once into parallel Integer arrays. Measured on
+    # the real dataset: full lookups drop from ~15µs to ~9µs (the raw
+    # range probe alone is ~2µs, but IP parsing + overlay checks dominate
+    # the classify pipeline) at several× the memory. Worth it for
+    # lookup-heavy batch paths; configure via `memory_mode :arrays`.
+    class ArraysBase
+      attr_reader :count
+
+      def initialize(bytes, family)
+        asz = BinaryFormat.addr_size(family)
+        rec = BinaryFormat.base_rec_size(family)
+        @count = bytes.bytesize / rec
+        @starts = Array.new(@count)
+        @ends   = Array.new(@count)
+        @asns   = Array.new(@count)
+        @flags  = Array.new(@count)
+        unpack_addr = family == :ipv4 ? ->(s) { s.unpack1("N") } : ->(s) { hi, lo = s.unpack("Q>Q>"); (hi << 64) | lo }
+        @count.times do |i|
+          off = i * rec
+          @starts[i] = unpack_addr.call(bytes[off, asz])
+          @ends[i]   = unpack_addr.call(bytes[off + asz, asz])
+          @asns[i], @flags[i] = bytes[off + 2 * asz, 6].unpack("Nn")
+        end
+        [@starts, @ends, @asns, @flags].each(&:freeze)
+      end
+
+      def find(ip_int)
+        i = bsearch_le(@starts, ip_int)
+        return nil unless i && ip_int <= @ends[i]
+
+        [@asns[i], @flags[i]]
+      end
+
+      private
+
+      # Index of the greatest start <= ip_int (rightmost candidate range).
+      def bsearch_le(arr, val)
+        lo = 0
+        hi = arr.length - 1
+        ans = nil
+        while lo <= hi
+          mid = (lo + hi) / 2
+          if arr[mid] <= val
+            ans = mid
+            lo = mid + 1
+          else
+            hi = mid - 1
+          end
+        end
+        ans
+      end
+    end
+
+    # --- Overlay layers: sorted disjoint [start, end] ranges ----------------
+
+    module OverlayLayer
+      def self.build(bytes, family, mode)
+        mode == :arrays ? ArraysOverlay.new(bytes, family) : PackedOverlay.new(bytes, family)
+      end
+    end
+
+    class PackedOverlay
+      attr_reader :count
+
+      def initialize(bytes, family)
+        @bytes = bytes.freeze
+        @family = family
+        @asz = BinaryFormat.addr_size(family)
+        @rec = BinaryFormat.overlay_rec_size(family)
+        @count = bytes.bytesize / @rec
+      end
+
+      def cover?(ip_int)
+        return false if @count.zero?
+
+        key = BinaryFormat.pack_addr(ip_int, @family)
+        lo = 0
+        hi = @count - 1
+        while lo <= hi
+          mid = (lo + hi) / 2
+          off = mid * @rec
+          if key < @bytes[off, @asz]
+            hi = mid - 1
+          elsif key > @bytes[off + @asz, @asz]
+            lo = mid + 1
+          else
+            return true
+          end
+        end
+        false
+      end
+    end
+
+    class ArraysOverlay
+      attr_reader :count
+
+      def initialize(bytes, family)
+        asz = BinaryFormat.addr_size(family)
+        rec = BinaryFormat.overlay_rec_size(family)
+        @count = bytes.bytesize / rec
+        @starts = Array.new(@count)
+        @ends   = Array.new(@count)
+        unpack_addr = family == :ipv4 ? ->(s) { s.unpack1("N") } : ->(s) { hi, lo = s.unpack("Q>Q>"); (hi << 64) | lo }
+        @count.times do |i|
+          off = i * rec
+          @starts[i] = unpack_addr.call(bytes[off, asz])
+          @ends[i]   = unpack_addr.call(bytes[off + asz, asz])
+        end
+        [@starts, @ends].each(&:freeze)
+      end
+
+      def cover?(ip_int)
+        lo = 0
+        hi = @count - 1
+        while lo <= hi
+          mid = (lo + hi) / 2
+          if ip_int < @starts[mid]
+            hi = mid - 1
+          elsif ip_int > @ends[mid]
+            lo = mid + 1
+          else
+            return true
+          end
+        end
+        false
+      end
+    end
+
+    # --- OORG v1: ASN -> organization name ----------------------------------
+
+    class OrgIndex
+      def self.load(path)
+        new(File.binread(path))
+      end
+
+      def initialize(bytes)
+        raise FormatError, "not an OORG file (bad magic)" unless bytes[0, 4] == ORG_MAGIC
+        raise FormatError, "unsupported OORG version #{bytes.getbyte(4)}" unless bytes.getbyte(4) == 0x01
+
+        @bytes = bytes.freeze
+        @count, @blob_size = bytes[8, 8].unpack("NN")
+        @blob_base = ORG_HEADER_SIZE + @count * 8
+        expected = @blob_base + @blob_size
+        raise FormatError, "OORG truncated: #{bytes.bytesize} bytes, header implies #{expected}" unless bytes.bytesize == expected
+      end
+
+      def name(asn)
+        lo = 0
+        hi = @count - 1
+        while lo <= hi
+          mid = (lo + hi) / 2
+          a, off = @bytes[ORG_HEADER_SIZE + mid * 8, 8].unpack("NN")
+          if asn < a
+            hi = mid - 1
+          elsif asn > a
+            lo = mid + 1
+          else
+            nxt = mid + 1 < @count ? @bytes[ORG_HEADER_SIZE + (mid + 1) * 8 + 4, 4].unpack1("N") : @blob_size
+            return @bytes[@blob_base + off, nxt - off].force_encoding(Encoding::UTF_8)
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/openasn/cidr_utils.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module OpenASN
+  # Range math for the Tier B executor. Mirrors the data pipeline's
+  # semantics exactly (adjacent ranges merge; inputs may overlap freely).
+  module CidrUtils
+    module_function
+
+    # "1.2.3.0/24" | "1.2.3.4" -> [family, start_int, end_int] | nil (junk)
+    def parse(token)
+      ip = IPAddr.new(token.strip)
+      r = ip.to_range
+      [ip.ipv4? ? :ipv4 : :ipv6, r.first.to_i, r.last.to_i]
+    rescue IPAddr::Error
+      nil
+    end
+
+    # Merge overlapping AND adjacent ranges. Critical for Apple's relay
+    # list: ~280k rows collapse dramatically once merged, which is the
+    # difference between a fat linear file and a lookup-friendly overlay.
+    def merge(ranges)
+      return [] if ranges.empty?
+
+      sorted = ranges.sort_by { |r| [r[0], r[1]] }
+      merged = [[sorted[0][0], sorted[0][1]]]
+      sorted.each do |(s, e)|
+        last = merged.last
+        if s <= last[1] + 1
+          last[1] = e if e > last[1]
+        else
+          merged << [s, e]
+        end
+      end
+      merged
+    end
+
+    # tokens (CIDRs/IPs, junk tolerated) -> { ipv4: merged, ipv6: merged }
+    def ranges_by_family(tokens)
+      out = { ipv4: [], ipv6: [] }
+      tokens.each do |token|
+        family, s, e = parse(token)
+        out[family] << [s, e] if family
+      end
+      { ipv4: merge(out[:ipv4]), ipv6: merge(out[:ipv6]) }
+    end
+  end
+end

data/lib/openasn/classifier.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module OpenASN
+  # The verdict precedence ladder. First match wins. This ordering IS the
+  # product — change it only with the data repo's DECISIONS.md open next to
+  # you, because every line encodes a documented false-positive lesson:
+  #
+  #    1. invalid input                       -> InvalidIPError (raised in IP.parse)
+  #    2. special ranges                      -> :private / :cgnat
+  #    3. relay overlays (Tier B: Apple)      -> :relay
+  #    4. tor overlays (Tier B)               -> :tor_exit
+  #    5. vpn ranges (canonical X4B ∪ Tier B provider lists) -> :vpn
+  #    6. ASN flag vpn_provider               -> :vpn
+  #    7. ASN flag enterprise_gw ∪ Tier B gateway ranges -> :enterprise_gateway
+  #    8. cloud provider ranges (Tier B)      -> :hosting (provider tagged)
+  #    9. canonical dc overlay (X4B)          -> :hosting
+  #   10. flags bad_asn|hosting_extra|cdn or category==hosting -> :hosting
+  #   11. ASN flag mobile_carrier             -> :mobile
+  #   12. category isp, role != tier1_transit -> :residential_isp
+  #   13. category business                   -> :business
+  #   14. category education_research         -> :education
+  #   15. category government_admin           -> :government
+  #   16. category isp + tier1_transit        -> :unknown (pure-backbone ambiguity)
+  #   17. ASN found, no category              -> :unknown
+  #   18. no ASN                              -> :unknown (unrouted)
+  #
+  # Why relay outranks EVERYTHING data-driven: iCloud Private Relay egress
+  # lives inside Cloudflare/Akamai space, which the base layer correctly
+  # calls hosting — paying iCloud+ customers would classify as datacenter
+  # traffic without rule 3. Same defensive logic for enterprise gateways
+  # (rule 7 beats the hosting rules: Zscaler ranges are offices, not
+  # servers). Rules 12/16: see the data repo's DECISIONS.md D-IMPL-1 —
+  # every national telco carries a transit role in upstream data; only
+  # pure tier-1 backbone is genuinely ambiguous.
+  module Classifier
+    module_function
+
+    def classify(snapshot, ip_input)
+      family, ip_int = IP.parse(ip_input)
+      ip_string = ip_input.is_a?(String) ? ip_input : ip_input.to_s
+
+      # Rule 2 — specials don't need data at all.
+      if (special = SpecialRanges.match(ip_int, family))
+        return Result.new(ip: ip_string, verdict: special[0], sources: [special[1]])
+      end
+
+      layers = snapshot.family(family)
+
+      # The base layer is consulted regardless of the winning rule: even a
+      # Tor exit's Result should say which ASN announces it.
+      asn, flags = layers.base.find(ip_int)
+      flags ||= 0
+      category = BinaryFormat.category_name(flags)
+      role = BinaryFormat.role_name(flags)
+
+      # Context flags never decide verdicts; they ride along for app logic.
+      context = []
+      snapshot.overlays_for(family, "flag:cloudflare_range").each do |(_, layer)|
+        context << :cloudflare_range if layer.cover?(ip_int)
+      end
+      snapshot.overlays_for(family, "flag:mixed_high_risk").each do |(_, layer)|
+        context << :mixed_high_risk if layer.cover?(ip_int)
+      end
+
+      verdict, provider, sources = decide(snapshot, layers, family, ip_int, flags, category, role, asn)
+
+      Result.new(
+        ip: ip_string, verdict: verdict, asn: asn,
+        as_org: snapshot.org_name(asn), category: category, network_role: role,
+        provider: provider, sources: sources, flags: flags,
+        context_flags: context, unrouted: asn.nil?
+      )
+    end
+
+    def decide(snapshot, layers, family, ip_int, flags, category, role, asn) # rubocop:disable Metrics
+      # 3 — relay
+      if (hit = overlay_hit(snapshot, family, "relay", ip_int))
+        return [:relay, hit.provider, [hit.id.to_sym]]
+      end
+
+      # 4 — tor
+      if (hit = overlay_hit(snapshot, family, "tor_exit", ip_int))
+        return [:tor_exit, hit.provider, [hit.id.to_sym]]
+      end
+
+      # 5 — vpn ranges. Provider-attributed Tier B lists are consulted
+      # BEFORE the anonymous canonical overlay on purpose: when both match
+      # (common — X4B covers most VPN hosting space), the verdict is
+      # identical but "ProtonVPN" beats provider=nil for explainability.
+      if (hit = overlay_hit(snapshot, family, "vpn", ip_int))
+        return [:vpn, hit.provider, [hit.id.to_sym]]
+      end
+
+      return [:vpn, nil, [:x4b_vpn]] if layers.vpn.cover?(ip_int)
+
+      # 6 — vpn by ASN flag
+      return [:vpn, nil, [:asn_vpn_provider]] if flags.anybits?(BinaryFormat::FLAG_VPN_PROVIDER)
+
+      # 7 — enterprise gateway (flag, then Tier B ranges)
+      return [:enterprise_gateway, nil, [:asn_enterprise_gw]] if flags.anybits?(BinaryFormat::FLAG_ENTERPRISE_GW)
+
+      if (hit = overlay_hit(snapshot, family, "enterprise_gateway", ip_int))
+        return [:enterprise_gateway, hit.provider, [hit.id.to_sym]]
+      end
+
+      # 8 — cloud provider ranges (provider attribution is the value-add)
+      if (hit = overlay_hit(snapshot, family, "hosting", ip_int))
+        return [:hosting, hit.provider, [hit.id.to_sym]]
+      end
+
+      # 9 — canonical datacenter overlay
+      return [:hosting, nil, [:x4b_dc]] if layers.dc.cover?(ip_int)
+
+      # 10 — hosting by ASN signal
+      if flags.anybits?(BinaryFormat::FLAG_BAD_ASN | BinaryFormat::FLAG_HOSTING_EXTRA | BinaryFormat::FLAG_CDN) ||
+         category == "hosting"
+        return [:hosting, nil, hosting_sources(flags, category)]
+      end
+
+      # 11 — mobile
+      return [:mobile, nil, [:asn_mobile_carrier]] if flags.anybits?(BinaryFormat::FLAG_MOBILE)
+
+      # 12–17 — category ladder
+      if category == "isp"
+        return role == "tier1_transit" ? [:unknown, nil, [:isp_transit_ambiguous]] : [:residential_isp, nil, [:asn_category]]
+      end
+      return [:business, nil, [:asn_category]]   if category == "business"
+      return [:education, nil, [:asn_category]]  if category == "education_research"
+      return [:government, nil, [:asn_category]] if category == "government_admin"
+      return [:unknown, nil, [:asn_no_category]] if asn
+
+      # 18 — unrouted
+      [:unknown, nil, [:unrouted]]
+    end
+
+    def overlay_hit(snapshot, family, maps_to, ip_int)
+      snapshot.overlays_for(family, maps_to).each do |(entry, layer)|
+        return entry if layer.cover?(ip_int)
+      end
+      nil
+    end
+
+    def hosting_sources(flags, category)
+      sources = []
+      sources << :asn_bad_asn       if flags.anybits?(BinaryFormat::FLAG_BAD_ASN)
+      sources << :asn_hosting_extra if flags.anybits?(BinaryFormat::FLAG_HOSTING_EXTRA)
+      sources << :asn_cdn           if flags.anybits?(BinaryFormat::FLAG_CDN)
+      sources << :asn_category      if category == "hosting"
+      sources
+    end
+  end
+end

data/lib/openasn/configuration.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "logger"
+require "tmpdir"
+
+module OpenASN
+  class Configuration
+    # Where downloaded artifacts + Tier B overlays live. Default:
+    # Rails.root/storage/openasn (survives deploys on most setups, and
+    # storage/ is gitignored by Rails convention), else Dir.tmpdir/openasn.
+    # Heads-up for containerized deploys: put this on a persistent volume
+    # or every boot starts from the bundled seed + a fresh download.
+    attr_writer :data_dir
+
+    # Measured on the real dataset, full classify (parse + all layers):
+    # :packed → ~11MB data resident; ~15µs/lookup on Apple Silicon,
+    #           ~24µs on GitHub's shared CI runners (default; right for web apps)
+    # :arrays → several× the memory; ~9µs/lookup (~1.6x faster — the raw
+    #           range probe is ~2µs, but IP parsing + overlay checks
+    #           dominate, so the full-lookup win is smaller than that
+    #           suggests). For lookup-heavy batch pipelines.
+    attr_reader :memory_mode
+
+    # Whether UpdateJob/boot staleness checks may refresh data automatically.
+    attr_accessor :auto_update
+
+    # Rolling-release base URL. Override to self-host artifacts (air-gapped
+    # deploys, internal mirrors). Must end with "/".
+    attr_writer :release_url
+
+    # Per-source Tier B switches (see fetch-manifest.json in the data repo).
+    # Keys are FEATURE names, not source ids — they fan out:
+    #   apple_relay    → apple_private_relay        (:relay)
+    #   tor            → tor_exits                  (:tor_exit)
+    #   clouds         → aws gcp azure oracle digitalocean linode vultr
+    #                    + cloudflare_ranges context flag
+    #   vpn_providers  → protonvpn mullvad ivpn pia airvpn windscribe
+    #                    privado riseup wlvpn worldvpn ovpn
+    #                    anonine
+    #                    (exact provider-attributed VPN exit/server IPs)
+    #   vpn_heavy      → nordvpn                    (large/fragile provider API)
+    #   vpn_dns        → surfshark ipvanish privatevpn purevpn torguard fastestvpn vpnsecure
+    #                    tunnelbear strongvpn vyprvpn giganews slickvpn
+    #                    azirevpn vpn.ac trust.zone
+    #                    (provider hostnames resolved locally; opt-in)
+    #   public_relays  → vpngate vpnbook freevpn.us (volunteer/free public VPN relays)
+    #   zscaler        → zscaler                    (:enterprise_gateway ranges)
+    #   nazgul_mixed   → nazgul_mixed               (flag only, never :vpn)
+    attr_accessor :tier_b
+
+    # Pin data to a dated release tag (e.g. "v2026.07.05") instead of the
+    # rolling latest. For reproducible environments and gradual rollouts.
+    attr_accessor :pin_version
+
+    # Reserved for the post-MVP edge companion (a CDN worker that stamps a
+    # trusted classification header). No behavior in this version.
+    attr_accessor :trusted_header
+
+    attr_writer :logger
+
+    # Reserved for future OpenASN Pro editions. Deliberately inert in the
+    # open gem — configuring it does nothing today and never will for the
+    # free dataset (see the data repo's open-data contract).
+    #
+    # Tier C BYOD adapters (bring-your-own MaxMind/IP2Location databases)
+    # are post-MVP and deliberately ship NO placeholder keys here: new
+    # config keys are additive and non-breaking to introduce later, whereas
+    # a placeholder whose shape turns out wrong would force a breaking
+    # rename. They'll appear alongside the adapters themselves.
+    attr_accessor :api_key
+
+    TIER_B_DEFAULTS = {
+      apple_relay: true,
+      tor: true,
+      clouds: true,
+      zscaler: false,       # ASN-level enterprise_gateway overrides already cover Zscaler
+      vpn_providers: true,
+      vpn_heavy: false,     # e.g. NordVPN's ~35MB API response; opt in deliberately
+      vpn_dns: false,       # provider-published hostnames resolved by local DNS; opt in deliberately
+      public_relays: false, # volunteer relays like VPN Gate; useful, but high-churn
+      nazgul_mixed: false   # semantics broader than VPN; opt-in only
+    }.freeze
+
+    # Feature switch → fetch-manifest source ids.
+    TIER_B_SOURCE_MAP = {
+      apple_relay: %w[apple_private_relay],
+      tor: %w[tor_exits],
+      clouds: %w[aws gcp azure oracle digitalocean linode vultr cloudflare_ranges],
+      zscaler: %w[zscaler],
+      vpn_providers: %w[protonvpn mullvad_relays ivpn_servers pia_servers airvpn_status windscribe_servers
+                        privadovpn riseup_vpn wlvpn_server_list worldvpn_servers ovpn_status_servers
+                        anonine_status],
+      vpn_heavy: %w[nordvpn_servers],
+      vpn_dns: %w[surfshark_generic surfshark_static surfshark_obfuscated ipvanish_openvpn
+                  privatevpn_openvpn purevpn_openvpn torguard_openvpn_tcp torguard_openvpn_udp
+                  fastestvpn_tcp fastestvpn_udp vpnsecure_locations tunnelbear_openvpn strongvpn_locations
+                  vyprvpn_openvpn giganews_vyprvpn_hosts slickvpn_locations azirevpn_locations
+                  vpnac_status trustzone_servers],
+      public_relays: %w[vpngate vpnbook_openvpn freevpn_us_servers],
+      nazgul_mixed: %w[nazgul_mixed]
+    }.freeze
+
+    def initialize
+      @data_dir = nil
+      @memory_mode = :packed
+      @auto_update = true
+      @release_url = nil
+      @tier_b = TIER_B_DEFAULTS.dup
+      @pin_version = nil
+      @trusted_header = nil
+      @logger = nil
+      @api_key = nil
+    end
+
+    def data_dir
+      @data_dir ||= if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+                      File.join(Rails.root.to_s, "storage", "openasn")
+                    else
+                      File.join(Dir.tmpdir, "openasn")
+                    end
+    end
+
+    def memory_mode=(mode)
+      raise ArgumentError, "memory_mode must be :packed or :arrays, got #{mode.inspect}" unless %i[packed arrays].include?(mode)
+
+      @memory_mode = mode
+    end
+
+    def release_url
+      return @release_url if @release_url
+      return "https://github.com/openasn/openasn/releases/download/#{pin_version}/" if pin_version
+
+      # Tag-addressed form: the rolling release's TAG is literally "latest",
+      # so this path stays pinned to it no matter which release holds
+      # GitHub's "Latest" BADGE. The superficially equivalent
+      # `releases/latest/download/...` resolves via that badge (whatever
+      # release was created last - REST `make_latest` defaults to "true"),
+      # and the first weekly dated snapshot stole it once (2026-07-05):
+      # default-config clients would have silently fetched up-to-6-day-old
+      # data until the next snapshot. Do not "simplify" this back.
+      # Refs: https://docs.github.com/en/repositories/releasing-projects-on-github/linking-to-releases
+      #       https://docs.github.com/en/rest/releases/releases#create-a-release
+      #       data repo DECISIONS.md D-REL-1
+      "https://github.com/openasn/openasn/releases/download/latest/"
+    end
+
+    def logger
+      @logger ||= if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+                    Rails.logger
+                  else
+                    Logger.new($stdout, level: Logger::INFO, progname: "openasn")
+                  end
+    end
+
+    def enabled_tier_b_source_ids
+      tier_b.flat_map { |feature, on| on ? TIER_B_SOURCE_MAP.fetch(feature, []) : [] }
+    end
+
+    def user_agent
+      "openasn-ruby/#{VERSION} (+https://github.com/openasn/openasn)"
+    end
+  end
+end