nondisposable 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b423ab4d910c50439d17398fcb84d95013ecd20be9c281f540c7b4540f79cb22
-  data.tar.gz: b09ff53a1ac0cf5d47f4b597e89f30e6522836d6fbdcd0bd3de4ed564edfa69f
+  metadata.gz: 691fa38ec02a652cd53aa77bd8fac7513553bfd5b0dac8ba0e224be41ff58fdd
+  data.tar.gz: f145924d4cb664331fc215ae0e562f2e4110ff04bf501ea52fddf5f7089de0f9
 SHA512:
-  metadata.gz: 6506a82600a139b2ac20b2abb8e84e2215f08af55eacbb43fac4d4524b7feb3b338dfd4cc73e7808957bbc9243f9d72c90fa3c28bc4b248ece56ea6f7d240ba2
-  data.tar.gz: d840467aa4befe4c934883cc18bfc33ba847889d4808dd94e633f84ef6a5c690b5c9b93e5d1fbc0a5e45daa5d1524f3534fce9db52aea3939a9ef01a490c18ef
+  metadata.gz: 97ce0386481ec1e70fa828ce3a18b0b2dce4a19855b34660c2abc782042d14512da0c77a7f09b6687a4f602a52d5c5d045ea8f9d9fa8f0e68a5123dbe067b36a
+  data.tar.gz: df2aaf590f850fe10fe9ee588861630721679f4bd2ae3bfb43a8cd6aab904bba2069cced44ce8fb60644e0f6ca21d679f3cf9593d1e90592a6f675029fcf8e0e

data/.simplecov

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# SimpleCov configuration file (auto-loaded before test suite)
+# This keeps test_helper.rb clean and follows best practices
+
+SimpleCov.start do
+  # Use SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  # Track coverage for the lib directory (gem source code)
+  add_filter "/test/"
+
+  # Track the lib and app directories
+  track_files "{lib,app}/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
+  enable_coverage :branch
+
+  # Set minimum coverage threshold to prevent coverage regression
+  minimum_coverage line: 90, branch: 90
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+end
+
+# Print coverage summary to terminal after tests complete
+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,5 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (like OpenAI's Codex, Cursor Agent, Claude Code, etc) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/Appraisals

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Note: Rails < 7.2 is not compatible with Ruby 3.4
+# (Logger became a bundled gem in Ruby 3.4, and only Rails 7.2+ handles this)
+# See: https://stdgems.org/logger/
+
+# Test against Rails 7.2 (minimum version compatible with Ruby 3.4)
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+# Test against Rails 8.0
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0.0"
+end
+
+# Test against Rails 8.1 (latest)
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.2"
+end

data/CHANGELOG.md

@@ -1,4 +1,35 @@
-## [Unreleased]
+## [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
+
+## [0.2.0] - 2026-01-16
+
+- Fixed `NoMethodError` when email is `"@"` or malformed (empty domain after split)
+- Removed non-existent asset references from engine (`nondisposable/application.css` and `.js`)
+- Removed buggy `railtie.rb` file that attempted to include a class instead of a module
+- Added comprehensive Minitest 6 test suite with 256 tests and 90%+ line / branch coverage
 
 ## [0.1.0] - 2024-09-25
 

data/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/README.md

@@ -1,5 +1,10 @@
 # 🗑️ `nondisposable` - Block disposable email addresses from signing up to your Rails app
 
+[![Gem Version](https://badge.fury.io/rb/nondisposable.svg)](https://badge.fury.io/rb/nondisposable) [![Build Status](https://github.com/rameerez/nondisposable/workflows/Tests/badge.svg)](https://github.com/rameerez/nondisposable/actions)
+
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=nondisposable)**, 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=nondisposable)!
+
 `nondisposable` is a Ruby gem that prevents users from signing up to your Rails app with disposable email addresses.
 
 Simply add to your User model:
@@ -38,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
@@ -89,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:
@@ -109,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.
@@ -122,6 +148,38 @@ production:
     schedule: every day at 3am US/Pacific
 ```
 
+## Troubleshooting
+
+### SSL certificate verify failed (unable to get certificate CRL)
+
+If you see this error when running `Nondisposable::DomainListUpdater.update`:
+
+```
+SSL_connect returned=1 errno=0 peeraddr=[::1]:10011 state=error: certificate verify failed (unable to get certificate CRL) (OpenSSL::SSL::SSLError)
+```
+
+This is **not** a bug in `nondisposable`. It's a known incompatibility between OpenSSL 3.6.0 and older versions of Ruby's `openssl` gem (3.3.0 and earlier).
+
+The fix is to update the `openssl` gem to version 3.3.1 or later **in your Rails project**.
+
+Add this to your Rails' project `Gemfile`:
+
+```ruby
+gem "openssl", "~> 3.3.2"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+This issue is unlikely to occur in production, it's mostly a development-only issue. It's likely that the exact same codebase fails in development but works fine in production. It only occurs when you have OpenSSL 3.6.0 system-wide AND something intercepting HTTPS traffic (like Cursor's proxy). Users in production or using a regular terminal won't experience it.
+
+This issue is more likely to occur if you're running your Rails console from within certain IDEs (like Cursor) that intercept HTTPS traffic through a local proxy. The updated `openssl` gem properly handles certificate verification in these environments.
+
+For more details, see the [Ruby openssl gem issue](https://github.com/ruby/openssl/issues/949).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -1,4 +1,13 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.warning = false
+end
+
+task default: %i[test]

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"
+}