nondisposable 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d6da844eae687a1d72201694a880a5ec5f16dcbd5e498de792a19d421027e6b
-  data.tar.gz: ea77c8f6ea5ddf4726f95b3438fadb7c7f0dedaed83bf7b674fdba78f95cbbed
+  metadata.gz: 691fa38ec02a652cd53aa77bd8fac7513553bfd5b0dac8ba0e224be41ff58fdd
+  data.tar.gz: f145924d4cb664331fc215ae0e562f2e4110ff04bf501ea52fddf5f7089de0f9
 SHA512:
-  metadata.gz: af761f9347d7e630239973256600cb52996f166f8479908c2ee8d379cae8b46d2035455c4bc2dc3c305941d7fe393dcac634e8d6b287e95eeee4b8bf9271db64
-  data.tar.gz: f58d7598f288515f684aaffc55a9399e01398fc9644b5744fd8e136510e4e51d358db12b4b33f99a58c7d06b5a05bd06a5313ff8e5f9f35e2d8ce95166791d38
+  metadata.gz: 97ce0386481ec1e70fa828ce3a18b0b2dce4a19855b34660c2abc782042d14512da0c77a7f09b6687a4f602a52d5c5d045ea8f9d9fa8f0e68a5123dbe067b36a
+  data.tar.gz: df2aaf590f850fe10fe9ee588861630721679f4bd2ae3bfb43a8cd6aab904bba2069cced44ce8fb60644e0f6ca21d679f3cf9593d1e90592a6f675029fcf8e0e

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [0.3.0] - 2026-08-09
+
+### Added
+
+- **Bundled seed list**: the gem now ships a snapshot of the upstream blocklist (8,201 domains) and `DomainListUpdater.seed` populates the table from it when (and only when) the table is empty. The install generator's migration seeds automatically, and `DomainListUpdater.update` falls back to seeding when the remote fetch fails against an empty table. This closes the fresh-install fail-open window where every signup passed until the first successful remote update.
+- **Parent-domain matching** (`config.check_parent_domains`, default `true`): an email at `x.tempmail.com` is now blocked when `tempmail.com` is on the list. The check walks up to 3 parent labels and never matches bare TLDs. Set to `false` to restore exact-only matching.
+- **Configurable failure mode** (`config.on_check_failure`, default `:allow`): controls what happens when the disposable check itself raises (e.g. database hiccup). `:allow` lets the record through with a loud error log (availability-first); `:reject` preserves the previous behavior and error message. Invalid values raise `ArgumentError`.
+
+### Changed
+
+- **Behavior change**: a broken check no longer rejects signups by default (previously any `StandardError` during validation added an error to the record). Set `config.on_check_failure = :reject` to keep the old fail-closed behavior.
+- **Behavior change**: subdomains of listed domains are now blocked by default (see parent-domain matching above). Set `config.check_parent_domains = false` for the old exact-only behavior.
+- `DomainListUpdater` now uses 10s open/read timeouts on the fetch (previously Net::HTTP's 60s defaults) so a hung connection can't block the update job.
+- Domain list updates use a single bulk `insert_all` instead of per-row `create`, and report any rows skipped by the unique index instead of silently swallowing them.
+- Downloaded domains are normalized before insert: whitespace/CR stripped, blank lines dropped, case-insensitive dedupe. `additional_domains` and `excluded_domains` now match case-insensitively everywhere.
+- An exact entry in `excluded_domains` always wins, so a specific subdomain can be allowlisted under a listed parent domain.
+- `Nondisposable.configuration` is lazily initialized: apps without an initializer no longer fail every validation with "cannot check if it's disposable".
+
+### Removed
+
+- Dead `require 'open-uri'` in the domain list updater.
+
 ## [0.2.1] - 2026-01-17
 
 - Add `[nondisposable]` prefix to all logger calls for better log identification

data/README.md

@@ -43,7 +43,7 @@ This will create the necessary migration file, initializer, and a job for schedu
 rails db:migrate
 ```
 
-Finally, populate the initial list of disposable domains:
+The migration also seeds the table from a snapshot of the disposable-domain list bundled with the gem, so your app is protected immediately. To fetch the very latest list, run:
 
 ```ruby
 Nondisposable::DomainListUpdater.update
@@ -94,9 +94,28 @@ Nondisposable.configure do |config|
   config.error_message = "provider is not allowed. Please use a non-disposable email address."
   config.additional_domains = ['custom-disposable-domain.com']
   config.excluded_domains = ['false-positive-domain.com']
+
+  # What to do when the disposable check itself fails (e.g. database hiccup):
+  #   :allow  - let the signup through and log an error (availability-first, default)
+  #   :reject - block the signup with a validation error (fail closed)
+  config.on_check_failure = :allow
+
+  # Also match parent domains: an email at x.tempmail.com is blocked when
+  # tempmail.com is on the list. Set to false for exact matches only.
+  config.check_parent_domains = true
 end
 ```
 
+#### Parent domain matching
+
+With `check_parent_domains` enabled (the default since 0.3.0), `user@x.tempmail.com` is blocked when `tempmail.com` is on the list. The check walks up to 3 parent labels (`a.b.c.tempmail.com` → `b.c.tempmail.com` → `c.tempmail.com` → `tempmail.com`) and never matches against bare TLDs like `com`. All candidates are checked in a single indexed query.
+
+This is a deliberately minimal, dependency-free approximation of "registrable domain" matching: the gem doesn't ship a full [public suffix list](https://publicsuffix.org), so it can't tell that `co.uk` is a public suffix — which is harmless in practice, because public suffixes don't appear on the blocklist. If you need to allowlist a specific subdomain under a listed parent, add the exact subdomain to `excluded_domains`; an exact exclusion always wins. Excluding a parent domain also unblocks its subdomains.
+
+#### Failure mode
+
+By default (`on_check_failure = :allow`), if the disposable check raises — say, the database is briefly unavailable — the signup goes through and an error is logged. This is availability-first: a broken check should not lock everyone out of signup. If you'd rather fail closed (reject signups whenever the check cannot run, as versions before 0.3.0 did), set `config.on_check_failure = :reject`.
+
 ### Direct Check
 
 You can also check if an email is disposable directly:
@@ -114,6 +133,8 @@ To manually update the list of disposable domains, run:
 Nondisposable::DomainListUpdater.update
 ```
 
+The fetch uses 10-second open/read timeouts and replaces the whole table atomically. If the remote fetch fails and your table is empty (e.g. a fresh install without network access), the updater automatically seeds from the blocklist snapshot bundled with the gem so you're never left unprotected; you can also trigger that explicitly with `Nondisposable::DomainListUpdater.seed` (it only seeds an empty table, and never overwrites existing data).
+
 It's important you keep your disposable domain list up to date. `nondisposable` will read from the latest version of the [`disposable-email-domains`](https://github.com/disposable-email-domains/disposable-email-domains) list, which is typically updated every few days.
 
 For this, `nondisposable` provides you with an Active Job (`DisposableEmailDomainListUpdateJob`) that you can use to schedule daily updates. How you do that, exactly, depends on the queueing system you're using.

data/app/models/nondisposable/disposable_domain.rb

@@ -4,12 +4,52 @@ module Nondisposable
   class DisposableDomain < ApplicationRecord
     validates :name, presence: true, uniqueness: { case_sensitive: false }
 
+    # How many leading labels the parent-domain walk strips when
+    # check_parent_domains is enabled: user@a.b.c.tempmail.com is checked as
+    # a.b.c.tempmail.com, b.c.tempmail.com, c.tempmail.com and tempmail.com.
+    #
+    # Trade-off (documented instead of pulling in a full public-suffix-list
+    # dependency): the walk never queries single-label suffixes (bare TLDs like
+    # "com"), but without a PSL it cannot tell that multi-label suffixes like
+    # "co.uk" are public — those candidates are harmless unless a public suffix
+    # is deliberately added to the list. Conversely, a throwaway address nested
+    # more than 3 labels below a listed domain escapes the walk; blocklisted
+    # domains are registrable domains, so 3 levels covers practical abuse.
+    PARENT_MATCH_DEPTH = 3
+
     class << self
       def disposable?(domain)
         return false if domain.blank?
+
         domain = domain.to_s.downcase
-        Nondisposable.configuration.additional_domains.include?(domain) ||
-          (where(name: domain).exists? && !Nondisposable.configuration.excluded_domains.include?(domain))
+        config = Nondisposable.configuration
+        candidates = match_candidates(domain)
+
+        additional = config.additional_domains.map { |d| d.to_s.downcase }
+        return true if (candidates & additional).any? # rubocop compat: Array#intersect? needs Ruby >= 3.1, gem supports 3.0
+
+        excluded = config.excluded_domains.map { |d| d.to_s.downcase }
+        # An exact exclusion always wins, so a specific subdomain can be
+        # allowlisted even when a parent domain is on the list.
+        return false if excluded.include?(domain)
+
+        where(name: candidates - excluded).exists?
+      end
+
+      # The exact domain plus up to PARENT_MATCH_DEPTH parent domains,
+      # never descending below two labels (bare TLDs are never candidates).
+      def match_candidates(domain)
+        return [domain] unless Nondisposable.configuration.check_parent_domains
+
+        labels = domain.split('.')
+        candidates = [domain]
+        1.upto(PARENT_MATCH_DEPTH) do |depth|
+          parent = labels.drop(depth)
+          break if parent.size < 2
+
+          candidates << parent.join('.')
+        end
+        candidates
       end
     end
 

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/nondisposable",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}