openasn 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f423b3d573d4d10e9062c210b0f1704520518dd0984beb6229092c36aa18c91
+  data.tar.gz: e9c15ca9d880ee0a2fd762c9b7253bfd5bbe92e50b990ac62191ab3cae59b5eb
+SHA512:
+  metadata.gz: a269180e3fd9f820e2a24f1ae0f5747fd610c4cc81a2e0b09439970cecba931c4059e3ca21fac194b271709532d40a44cdfc9345ce2c19a48891b36b93401775
+  data.tar.gz: cc2a87918a1869b661fc5624c36779e0a33ee98c7ba3db9d35686469ab9a7622ebeae77e8d77a6f4e71dc9ef0801c4c00854f32beb9e211726f8b2957463e25f

data/.simplecov

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+SimpleCov.start do
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  add_filter "/test/"
+
+  track_files "{lib,app}/**/*.rb"
+
+  enable_coverage :branch
+
+  minimum_coverage line: 80, branch: 65
+
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+end
+
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n" + "=" * 60
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  puts "Branch Coverage: #{SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || 'N/A'}%"
+  puts "=" * 60
+end

data/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+This file provides guidance to AI agents (and humans) working in this repository.
+
+This is the Ruby client for the OpenASN data project. Read `README.md`
+first; the data semantics, artifact format (FORMAT.md), precedence
+rationale (DECISIONS.md) and legal design live in the data repo:
+https://github.com/openasn/openasn
+
+Hard rules:
+
+1. **Zero runtime dependencies.** stdlib only. Rails/ActiveJob integrations
+   stay conditionally defined. Do not add gems.
+2. **The precedence ladder in lib/openasn/classifier.rb is the product.**
+   Each line encodes a documented false-positive lesson; change only with
+   the data repo's DECISIONS.md in hand, and mirror spot-panel changes.
+3. **Data never ships via gem releases** — the gem versions on code; data
+   flows through the nightly GitHub Releases + UpdateJob. (The bundled
+   seed is refreshed via `rake seed:refresh` only as part of a code release.)
+4. **Readers never block.** Snapshot swaps are single ivar assignments;
+   keep locks away from the lookup path.
+5. Tests are offline (WebMock). `bundle exec rake test` must stay green on
+   Ruby 3.1+.

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## [0.2.0] - 2026-07-06
+
+### Added
+
+- 34 new Tier B VPN provider sources (fetch-manifest entries + parsers),
+  organized into config groups:
+  - `vpn_providers` (enabled by default — provider-published exact-IP
+    endpoints): Mullvad, IVPN, Private Internet Access, AirVPN, Windscribe,
+    PrivadoVPN, RiseupVPN, WLVPN, WorldVPN, OVPN, and Anonine — joining
+    ProtonVPN from 0.1.0.
+  - `vpn_heavy` (opt-in): NordVPN (~35 MB API response; deliberate opt-in).
+  - `vpn_dns` (opt-in — provider-published hostnames resolved via local DNS):
+    Surfshark, IPVanish, PrivateVPN, PureVPN, TorGuard, FastestVPN, VPNSecure,
+    TunnelBear, StrongVPN, VyprVPN, Giganews, SlickVPN, AzireVPN, VPN.ac, and
+    Trust.Zone.
+  - `public_relays` (opt-in — volunteer-run, high-churn): VPN Gate, VPNBook,
+    and FreeVPN.us.
+- New parser machinery, all stdlib and dependency-free: HTML table/status
+  parsers, a bounded ZIP reader for `.ovpn` archive sources (64 MB inflate
+  cap), threaded DNS hostname resolution with an injectable
+  `Configuration.dns_resolver` hook, and `HttpClient#post_form` for provider
+  endpoints that require form POSTs (redirects preserve method and headers).
+
+### Changed
+
+- Overlay lookups are served from a per-family index precomputed once per
+  snapshot — measurably faster lookups with many overlays enabled (the old
+  per-lookup scan was allocation-heavy past ~8 overlays).
+
+### Fixed
+
+- The default dataset URL is now the tag-addressed
+  `releases/download/latest/…` form, which stays pinned to the rolling
+  release no matter which release holds GitHub's "Latest" badge. The
+  superficially equivalent `releases/latest/download/…` form resolves via the
+  badge and briefly served a frozen weekly snapshot on 2026-07-05. Applied
+  everywhere the URL appears (default config, install generator template,
+  docs) and pinned by a regression test. See the data repo's DECISIONS.md
+  D-REL-1.
+
+## [0.1.0] - 2026-07-05
+
+- Initial release: offline IP origin classification (verdict-first API),
+  bundled data seed, nightly refresh from OpenASN releases, Tier B
+  fetch-manifest executor (Apple Private Relay, Tor exits, cloud provider
+  ranges, provider-attributed VPN overlays), Rack middleware, Rails install
+  generator.
+
+[0.2.0]: https://github.com/openasn/openasn-ruby/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/openasn/openasn-ruby/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Javi R
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,242 @@
+# 🛰️ `openasn` — offline IP origin intelligence for Ruby
+
+[![Gem Version](https://badge.fury.io/rb/openasn.svg)](https://badge.fury.io/rb/openasn) [![Build Status](https://github.com/openasn/openasn-ruby/workflows/Tests/badge.svg)](https://github.com/openasn/openasn-ruby/actions)
+
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=openasn)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=openasn)!
+
+`openasn` tells you what kind of network an IP address is *really* coming from — **residential ISP, mobile carrier, hosting/datacenter, VPN, Tor exit, iCloud Private Relay, enterprise gateway, business, education, government, CGNAT** — entirely offline, in ~20 microseconds, with **zero API calls, zero per-lookup cost, and zero runtime dependencies**.
+
+```ruby
+result = OpenASN.lookup(request.remote_ip)
+
+result.verdict          # => :residential_isp
+result.infrastructure?  # => false  (true only for :hosting / :vpn / :tor_exit)
+result.likely_human?    # => true   (:residential_isp, :mobile, :relay, :cgnat, :enterprise_gateway)
+result.asn              # => 3352
+result.as_org           # => "TELEFONICA DE ESPANA S.A.U."
+result.sources          # => [:asn_category]  — every verdict is auditable
+```
+
+It's the missing first line of defense for signups, checkouts, and abuse-prone endpoints: the signal that today costs $79–$200/month from commercial IP-intelligence APIs, as free, open, auditable data — compiled nightly from legally clean sources by the [OpenASN data project](https://github.com/openasn/openasn), with a data seed bundled right in the gem so it works on first boot, offline.
+
+> [!IMPORTANT]
+> **What this is NOT.** A clean or `:residential_isp` verdict is **absence of evidence, not proof of innocence**. Residential proxies — malicious traffic exiting through real home IPs — are structurally hard to detect offline, and OpenASN does not claim to detect them. `:vpn`, `:hosting`, and `:tor_exit` are high-confidence; treat everything else as a signal, not a sentence. **Never hard-block `:relay`, `:cgnat`, or `:mobile` — those are real people.** OpenASN is a first line of defense, not a fraud engine.
+
+## How it works
+
+```
+┌────────────────────────────┐    nightly     ┌──────────────────────────────┐
+│ openasn/openasn (data)     │ ─────────────▶ │ your server                  │
+│ 560k+ IP ranges, all ASNs, │  GitHub        │  gem seed → daily UpdateJob  │
+│ VPN/DC overlays, curated   │  Releases      │  + Tier B overlays fetched   │
+│ corrections (CC0)          │  (free CDN)    │  from original authorities:  │
+└────────────────────────────┘                │  Apple relay list, Tor exits,│
+                                              │  AWS/GCP/Azure/OCI ranges…   │
+   lookups: local binary search, ~20µs,       └──────────────────────────────┘
+   no user IP ever leaves your server
+```
+
+- **Bundled seed**: the gem ships with a full snapshot — works offline from the first boot, forever.
+- **Nightly refresh**: `OpenASN::UpdateJob` pulls updated artifacts (SHA-256 verified, atomically swapped — readers never block, never see partial data).
+- **Tier B overlays**: fast-moving lists (Tor exits, Apple Private Relay, cloud ranges, exact VPN provider server lists) are fetched by *your* server directly from the original authorities — never proxied through anyone.
+- **Data never flows through gem releases.** The gem versions on code; the data has its own nightly release channel.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "openasn"
+```
+
+Then:
+
+```bash
+bundle install
+rails generate openasn:install
+```
+
+The generator creates `config/initializers/openasn.rb` (documented defaults) and, if you're on Solid Queue, schedules the daily `OpenASN::UpdateJob` in `config/recurring.yml`. **No migrations, no database** — data lives in `storage/openasn/` as memory-mapped-style packed files.
+
+Not on Rails? `OpenASN.lookup` works anywhere Ruby ≥ 3.1 runs; schedule `OpenASN.update!` daily with cron/whenever.
+
+## The API
+
+### Lookup
+
+```ruby
+r = OpenASN.lookup("146.70.107.100")   # aliases: OpenASN.check, OpenASN.[]
+# Never nil. Raises OpenASN::InvalidIPError (an ArgumentError) on garbage input.
+
+r.verdict         # one of: :residential_isp :mobile :business :hosting :vpn
+                  #         :tor_exit :relay :enterprise_gateway :education
+                  #         :government :cgnat :private :unknown
+r.infrastructure? # :hosting | :vpn | :tor_exit — the honest, high-confidence boolean
+r.likely_human?   # :residential_isp | :mobile | :relay | :cgnat | :enterprise_gateway
+r.vpn? r.hosting? r.tor? r.relay? r.mobile? r.private? r.cgnat?
+
+r.asn             # 9009
+r.as_org          # "M247 Europe SRL"  (nil until the first data refresh downloads org names)
+r.category        # "hosting"          (raw upstream category)
+r.network_role    # "major_transit"    (raw upstream routing role)
+r.provider        # "aws" | "ProtonVPN" | "iCloud Private Relay" | nil (overlay attribution)
+r.sources         # [:x4b_vpn] — which data layer decided; every verdict is auditable
+r.context_flags   # [:cloudflare_range] — context that never decides verdicts
+r.unrouted?       # true when no ASN announces this IP
+r.flags           # raw u16 for power users (see the data project's FORMAT.md)
+r.to_h            # everything, stable keys — built for shadow-mode logging
+```
+
+Note the deliberate asymmetry: `:business`, `:education`, `:government`, and `:unknown` are **neither** `infrastructure?` **nor** `likely_human?` — that's your call, not the gem's. There is intentionally no `suspicious?` — that's a policy word, and your app owns policy.
+
+### The mental model: verdict, category, flags, sources
+
+OpenASN returns one object, but its fields answer different questions:
+
+| Field | What it answers | How to use it |
+|---|---|---|
+| `verdict` | "What should my app consider this IP?" | Primary policy input. Switch on this. |
+| `infrastructure?` | "Is this high-confidence non-eyeball infrastructure?" | Safe shorthand for `:hosting`, `:vpn`, `:tor_exit`. |
+| `likely_human?` | "Is blocking this IP likely to hit real people?" | True for residential/mobile/relay/CGNAT/enterprise gateways. |
+| `category` | Raw ASN category from upstream data (`"isp"`, `"hosting"`, `"business"`, ...) | Context for logs and analyst UI. Do not treat it as the verdict. |
+| `network_role` | Raw routing role (`"access_provider"`, `"midsize_transit"`, `"tier1_transit"`, ...) | Explains why some ISP ASNs stay human while pure backbones stay unknown. |
+| `sources` | Which rule/data layer decided the verdict | Best debugging field. Log it. |
+| `provider` | Provider attribution from an exact overlay hit (`"aws"`, `"azure"`, `"ProtonVPN"`, ...) | Display/log it when present; nil is normal. |
+| `context_flags` | Extra context that never decides the verdict | Useful for policy experiments; do not block solely on it. |
+| `flags` | Packed low-level artifact bits | Power-user/debug field; prefer `verdict` and `sources` in app code. |
+
+Common examples:
+
+- A DIGI Spain home IP is usually `category: "isp"` and `verdict: :residential_isp`. That is expected: `category` describes the ASN; `verdict` is OpenASN's safer application-level label.
+- An Amazon IP may be `category: "hosting"`, `sources: [:x4b_dc]`, and with Tier B enabled `provider: "aws"`. The verdict remains `:hosting`; Tier B only improves attribution.
+- `bad_asn` is not an accusation and not a verdict. It means the ASN appears in `brianhama/bad-asn-list`, a curated MIT-licensed hosting/cloud/colo ASN list. When that bit decides classification, `sources` includes `:asn_bad_asn`.
+- `:residential_isp` means "known eyeball ISP, no stronger infrastructure signal found." It does **not** mean "safe user."
+
+### Verdict cheat sheet
+
+| Verdict | Meaning | Confidence | Advice |
+|---|---|---|---|
+| `:hosting` | datacenter/cloud/colo | high | fine to challenge on sensitive flows |
+| `:vpn` | known VPN egress | high | challenge > block (privacy users are customers too) |
+| `:tor_exit` | Tor exit node | high (with Tier B fresh) | your policy |
+| `:relay` | iCloud Private Relay | high | **treat like CGNAT — real paying humans** (Apple says the same) |
+| `:enterprise_gateway` | Zscaler-style corporate egress | high | humans at work; never block |
+| `:residential_isp` | eyeball ISP | *absence of evidence* | trust but verify |
+| `:mobile` | cellular carrier | high | one IP = hundreds of humans (CGNAT); no per-IP rate-limits |
+| `:cgnat` / `:private` | RFC 6598 / RFC 1918 space | certain | check your proxy config if you see these on public traffic |
+| `:business` / `:education` / `:government` | org category from ASN data | medium | your policy |
+| `:unknown` | genuinely ambiguous (e.g. tier-1 backbone, uncategorized ASN) | honest | design for it — `unknown` is a feature, not a bug |
+
+### API stability contract
+
+Your `case result.verdict` statements and shadow-log parsers are API surface. The rules, from 0.1.0 onward:
+
+- **The verdict enum is append-only.** Existing verdicts are never removed, renamed, or silently redefined (a meaning change would be a major version). New verdicts may be *added* in a minor version, announced loudly in the CHANGELOG — so give exhaustive `case` statements an `else` branch (treat unknown-to-you verdicts as you treat `:unknown`).
+- **Verdicts are code, not data: a data refresh can never emit a verdict your gem version doesn't know.** The nightly artifacts carry ranges and flag bits; the mapping to verdicts is compiled into the client. Data updates are always safe to auto-apply.
+- **`Result#to_h` keys are append-only** — shadow-mode logs you write today stay parseable tomorrow.
+- **`sources` and `context_flags` symbols are informational**: new ones appear as data sources evolve. Log them, display them, never exhaustively match on them.
+- **Config keys are additive**; artifact bytes are governed by the data project's [FORMAT.md](https://github.com/openasn/openasn/blob/main/FORMAT.md) (any layout change bumps `format_version`, and readers reject unknown versions rather than guess).
+
+### Configuration (all optional)
+
+```ruby
+OpenASN.configure do |config|
+  config.data_dir     = Rails.root.join("storage", "openasn") # default; use a persistent volume in containers
+  config.memory_mode  = :packed   # :packed ~11MB data resident, ~15µs/lookup · :arrays faster, more RAM
+  config.auto_update  = true
+  config.release_url  = "https://github.com/openasn/openasn/releases/download/latest/" # self-hostable; tag-addressed on purpose (badge-immune, see data repo DECISIONS.md D-REL-1)
+  config.pin_version  = nil       # e.g. "2026-07-04" to pin a dated data release
+  config.tier_b       = { apple_relay: true, tor: true, clouds: true,
+                          vpn_providers: true, vpn_heavy: false,
+                          vpn_dns: false, public_relays: false, zscaler: false,
+                          nazgul_mixed: false }
+  config.logger       = Rails.logger
+end
+```
+
+`vpn_providers: true` enables small/stable exact-IP provider lists such as ProtonVPN, Mullvad, IVPN, Private Internet Access, AirVPN, Windscribe, PrivadoVPN, RiseupVPN, WLVPN, WorldVPN, OVPN, and Anonine. WLVPN is backend infrastructure powered by IPVanish and used by white-label resellers such as FastVPN/Namecheap/Spaceship; OpenASN labels the exact source as `provider: "WLVPN"` rather than guessing the reseller. WorldVPN, OVPN, and Anonine publish exact IPs in first-party server/status tables or JSON endpoints, so they do not need DNS expansion. `vpn_heavy: true` opts into large or historically fragile provider APIs such as NordVPN. `vpn_dns: true` opts into provider-published hostnames resolved by your server's DNS at update time, covering sources such as Surfshark, IPVanish, PrivateVPN, PureVPN, TorGuard, FastestVPN, VPNSecure, TunnelBear, StrongVPN, VyprVPN, Giganews VyprVPN, SlickVPN, AzireVPN, VPN.AC, and Trust.Zone; this is useful but intentionally off by default because DNS answers can vary by resolver/vantage. `public_relays: true` opts into volunteer/free relay networks such as VPN Gate, VPNBook, and FreeVPN.us, which can label residential-looking IPs as `:vpn` while they are actively advertised as relays. FreeVPN.us intentionally includes only OpenVPN/WireGuard/PPTP rows; SSH Tunnel and V2Ray rows are excluded from the VPN overlay.
+
+### Updates
+
+```ruby
+OpenASN.update!        # refresh now → :updated | :tier_b_only | :unchanged | :locked
+OpenASN.dataset_info   # build id, origin (:seed/:data_dir), record counts, per-source Tier B status
+OpenASN.eager_load!    # load at boot instead of first lookup (~50–200ms once per process)
+```
+
+Updates are atomic end to end: SHA-256 verified against the release manifest → written to temp files → `rename(2)` into place → in-memory snapshot swapped in a single assignment. Concurrent lookups never block and never see partial state; concurrent updaters (multi-worker Puma) coordinate via file lock; sibling processes pick up new data within ~5 minutes via a one-`stat()` freshness probe. Every Tier B source failure keeps last-good data and surfaces in `dataset_info` — a broken upstream can never crash your app or silently blank a signal.
+
+### Rack middleware (optional)
+
+```ruby
+# config/initializers/openasn.rb
+Rails.application.config.middleware.use OpenASN::Middleware
+
+# anywhere downstream:
+request.env["openasn.result"]&.infrastructure?
+```
+
+> [!WARNING]
+> **The classic integration bug:** behind a proxy/CDN without trusted-proxy configuration, you'll classify your own load balancer on every request (everything comes back `:private` or your host's datacenter). Inside Rails the middleware uses `remote_ip` semantics (honors `config.action_dispatch.trusted_proxies`); make sure the real client IP reaches your app — e.g. with the `cloudflare-rails` gem when behind Cloudflare.
+
+## Recommended rollout: shadow mode first
+
+Log for two weeks. Then decide. (This is how we dogfood it.)
+
+```ruby
+# 1. SHADOW — measure, block nothing:
+class RegistrationsController < ApplicationController
+  def create
+    Rails.logger.info(openasn: OpenASN.lookup(request.remote_ip).to_h.merge(flow: "signup"))
+    # … existing signup logic unchanged
+  end
+end
+
+# 2. Weeks later, with YOUR false-positive data in hand, act — prefer
+#    step-up verification (email confirm, captcha, phone) over hard blocks:
+Rack::Attack.blocklist("openasn: infrastructure on signup") do |req|
+  req.post? && req.path == "/signup" && OpenASN.lookup(req.ip).infrastructure?
+end
+```
+
+**Who should NOT rely on this:** banks, crypto exchanges, KYC flows, high-chargeback marketplaces — you need paid behavioral intelligence (MaxMind Anonymous IP/Residential Proxy, IPQS…). OpenASN is your prefilter at most.
+
+## What you can and cannot conclude (honesty section)
+
+**Can:** recognize known infrastructure with high confidence; identify network type; explain every verdict (`sources`); do it all offline with zero latency budget and zero privacy leakage (user IPs never leave your server).
+
+**Cannot:** detect residential proxies (structurally invisible offline — that's why the paid products exist); prove any IP is safe; outrun VPN infrastructure churn beyond nightly + Tier B cadence; promise IPv6 range-overlay parity (v6 VPN signal rides ASN-level data; documented lower confidence).
+
+## Performance
+
+Measured on the bundled real dataset (433k+ IPv4 ranges, 125k+ IPv6, full overlays), pure Ruby, no C extensions:
+
+| mode | lookup | throughput | memory |
+|---|---|---|---|
+| `:packed` (default) | ~15µs | ~68k/sec/core | ~11MB data |
+| `:arrays` | ~9µs | ~108k/sec/core | ~40MB data |
+
+(Apple M-series, canonical-data only; GitHub's shared CI runners measure ~24µs packed / ~12µs arrays. CI asserts a generous 100µs ceiling as a regression tripwire.) Enabling many Tier B overlays adds a few µs per active overlay; with all defaults loaded (~11 overlays) a full lookup is ~35µs on Apple Silicon, still tens of thousands per second per core. Run `rake bench` to measure on your hardware.
+
+## Data provenance & licensing
+
+Every byte in the dataset is traceable: compiled nightly from PDDL/CC0/MIT-licensed sources ([sapics/ip-location-db](https://github.com/sapics/ip-location-db), [ipverse/as-metadata](https://github.com/ipverse/as-metadata), [X4BNet/lists_vpn](https://github.com/X4BNet/lists_vpn), [brianhama/bad-asn-list](https://github.com/brianhama/bad-asn-list)) plus OpenASN's own curated corrections — with upstream license texts SHA-256-pinned in CI and full per-build provenance in `manifest.json`. The dataset is CC0. The details, gates, and the "fetch ≠ redistribute" legal design live in the [data project README](https://github.com/openasn/openasn).
+
+Sibling of [`nondisposable`](https://github.com/rameerez/nondisposable) (disposable-email blocking) and [`trackdown`](https://github.com/rameerez/trackdown) (IP geolocation) — same philosophy: boring, offline, production-grade primitives for Rails apps.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test    # full suite, offline (WebMock)
+rake bench               # lookup latency on your machine
+rake seed:refresh        # pull the latest data release into lib/openasn/data/seed/
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/openasn/openasn-ruby. Wrong verdict for an IP? That's usually a *data* issue — check `result.sources` and open it against [openasn/openasn](https://github.com/openasn/openasn) (the override files are one sourced line per PR).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+desc "Refresh the bundled data seed from the latest OpenASN release (run before each gem release)"
+task "seed:refresh" do
+  require "open-uri"
+  require "fileutils"
+  base = ENV.fetch("OPENASN_RELEASE_URL", "https://github.com/openasn/openasn/releases/download/latest/") # tag-addressed, badge-immune: see Configuration#release_url
+  seed = File.expand_path("lib/openasn/data/seed", __dir__)
+  FileUtils.mkdir_p(seed)
+  %w[openasn-ipv4.bin openasn-ipv6.bin manifest.json fetch-manifest.json].each do |f|
+    puts "downloading #{f}…"
+    URI.open("#{base}#{f}", "User-Agent" => "openasn-seed-refresh") do |io| # rubocop:disable Security/Open
+      File.binwrite(File.join(seed, f), io.read)
+    end
+  end
+  puts "seed refreshed — remember: gem versions ship on CODE changes; data freshness flows through releases + UpdateJob, never through gem releases"
+end
+
+desc "Benchmark lookup latency against the bundled seed (RUN_BENCH=1 rake bench)"
+task :bench do
+  ENV["RUN_BENCH"] = "1"
+  ruby "-Ilib", "-Itest", "test/bench.rb"
+end
+
+task default: :test

data/lib/generators/openasn/install/install_generator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Openasn
+  module Generators
+    # rails generate openasn:install
+    #
+    # Creates the initializer and wires the daily update job into Solid
+    # Queue's recurring.yml when present. No migrations — OpenASN is
+    # file-based by design (storage/openasn/), nothing touches your DB.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "openasn.rb", "config/initializers/openasn.rb"
+      end
+
+      def wire_recurring_job
+        recurring = "config/recurring.yml"
+        unless File.exist?(File.expand_path(recurring, destination_root))
+          say_status :skipped, "#{recurring} not found — schedule OpenASN::UpdateJob with your own scheduler (see README)", :yellow
+          return
+        end
+
+        if File.read(File.expand_path(recurring, destination_root)).include?("OpenASN::UpdateJob")
+          say_status :identical, "#{recurring} already schedules OpenASN::UpdateJob", :blue
+          return
+        end
+
+        # 4:12am UTC: after the nightly data build (03:17 UTC) completes,
+        # off-hour to be kind to the Tier B upstreams.
+        append_to_file recurring, <<~YAML
+
+          # Added by `rails g openasn:install` — daily IP-origin data refresh
+          production:
+            openasn_update:
+              class: OpenASN::UpdateJob
+              queue: default
+              schedule: every day at 4:12am UTC
+        YAML
+      end
+
+      def display_post_install_message
+        say ""
+        say "\tThe `openasn` gem has been successfully installed!", :green
+        say ""
+        say "OpenASN works out of the box: a data seed is bundled with the gem and"
+        say "refreshes itself daily via OpenASN::UpdateJob (data flows through GitHub"
+        say "Releases — never through gem updates)."
+        say ""
+        say "To complete the setup:"
+        say "  1. Review config/initializers/openasn.rb (defaults are production-ready)."
+        say "  2. Make sure a queue backend runs OpenASN::UpdateJob daily (done for you"
+        say "     if you use Solid Queue's recurring.yml)."
+        say "  3. Start in SHADOW MODE — log verdicts, block nothing:"
+        say ""
+        say "       # e.g. in your signups controller:"
+        say "       Rails.logger.info(openasn: OpenASN.lookup(request.remote_ip).to_h)"
+        say ""
+        say "     After a week or two of data, decide your own thresholds. Remember:"
+        say "     a residential verdict is absence of evidence, not proof of innocence,"
+        say "     and :relay/:cgnat/:mobile are real humans — never hard-block them.", :yellow
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/openasn/install/templates/openasn.rb

@@ -0,0 +1,68 @@
+# OpenASN — offline IP origin intelligence.
+# Docs: https://github.com/openasn/openasn-ruby
+#
+# Everything below shows the DEFAULT — uncomment only what you change.
+
+OpenASN.configure do |config|
+  # Where downloaded data lives. Default: Rails.root/storage/openasn.
+  # Containerized? Point this at a persistent volume, or each boot starts
+  # from the bundled seed and re-downloads (~15MB) on first refresh.
+  # config.data_dir = Rails.root.join("storage", "openasn")
+
+  # :packed → ~11MB data resident, ~15-25µs per lookup (right for almost everyone)
+  # :arrays → several× the memory, ~9µs per lookup (lookup-heavy batch pipelines)
+  # config.memory_mode = :packed
+
+  # Allow automatic refreshes (UpdateJob + boot staleness check).
+  # config.auto_update = true
+
+  # Self-host or pin the data source if you need to:
+  # config.release_url = "https://github.com/openasn/openasn/releases/download/latest/"
+  # config.pin_version = "2026-07-04"   # a dated release tag, for reproducible builds
+
+  # Tier B overlays — fetched by YOUR server from the original authorities
+  # (Apple, Tor Project, AWS…), per the project's fetch-manifest. Defaults:
+  # config.tier_b = {
+  #   apple_relay: true,     # iCloud Private Relay → :relay (real users! never block)
+  #   tor: true,             # Tor Project exits    → :tor_exit
+  #   clouds: true,          # AWS/GCP/Azure/OCI/DO/Linode/Vultr → :hosting (+provider)
+  #   vpn_providers: true,   # exact VPN provider/backend IP lists → :vpn (+provider)
+  #   vpn_heavy: false,      # large/fragile provider APIs (NordVPN) — opt-in
+  #   vpn_dns: false,        # provider hostnames resolved locally (Surfshark/IPVanish/FastestVPN/VPNSecure/TunnelBear/StrongVPN/...) - opt-in
+  #   public_relays: false,  # volunteer/free public VPN relays (VPN Gate/VPNBook/FreeVPN.us) — opt-in
+  #   zscaler: false,        # extra :enterprise_gateway ranges (ASN flags already cover most)
+  #   nazgul_mixed: false    # broad "high-risk hosting" flag — NOT a VPN signal; opt-in
+  # }
+
+  # config.logger = Rails.logger
+end
+
+# Optional: classify every request once and read it anywhere downstream as
+# request.env["openasn.result"]. (Costs ~20µs/request.)
+#
+# ⚠️  Behind a proxy/CDN? Make sure Rails' trusted proxies are set up so
+# remote_ip is the real client — otherwise you'll classify your own load
+# balancer on every request. See "Trusted proxies" in the README.
+#
+# Rails.application.config.middleware.use OpenASN::Middleware
+
+# Optional: eager-load the dataset at boot (first lookup otherwise pays
+# ~50-200ms of lazy loading once per process):
+#
+# Rails.application.config.after_initialize { OpenASN.eager_load! }
+
+# ── Shadow mode (START HERE — measure before you act) ──────────────────────
+# Log verdicts on your critical flows for a couple of weeks:
+#
+#   result = OpenASN.lookup(request.remote_ip)
+#   Rails.logger.info(openasn: result.to_h.merge(flow: "signup"))
+#
+# Then, and only then, act — prefer step-up verification over hard blocks:
+#
+#   # Rack::Attack example (config/initializers/rack_attack.rb):
+#   # Rack::Attack.blocklist("openasn: infrastructure on signup") do |req|
+#   #   req.post? && req.path == "/signup" && OpenASN.lookup(req.ip).infrastructure?
+#   # end
+#
+# infrastructure? is true only for :hosting/:vpn/:tor_exit (high-confidence
+# classes). :relay, :cgnat and :mobile are REAL PEOPLE — never hard-block.