nondisposable 0.3.0 → 0.6.0

data/lib/nondisposable.rb

@@ -2,8 +2,20 @@
 
 require_relative "nondisposable/version"
 require_relative "nondisposable/engine"
+require_relative "nondisposable/domain"
+require_relative "nondisposable/public_suffix"
+require_relative "nondisposable/precedence"
+require_relative "nondisposable/source"
+require_relative "nondisposable/source_merge"
+require_relative "nondisposable/source_fetcher"
+require_relative "nondisposable/tld"
+require_relative "nondisposable/known_typos"
+require_relative "nondisposable/suggestion"
+require_relative "nondisposable/confirmable_email"
 require_relative "nondisposable/email_validator"
 require_relative "nondisposable/domain_list_updater"
+require_relative "nondisposable/tld_list_updater"
+require_relative "nondisposable/public_suffix_list_updater"
 
 module Nondisposable
   class Error < StandardError; end
@@ -24,28 +36,150 @@ module Nondisposable
   end
 
   def self.disposable?(email)
-    return false if email.nil? || !email.include?('@')
-    domain = email.to_s.split('@').last
-    return false if domain.nil? || domain.empty?
-    DisposableDomain.disposable?(domain.downcase)
+    return false if email.nil? || !email.to_s.include?('@')
+    # Unicode form: DisposableDomain canonicalises it itself, and needs the
+    # unencoded spelling to match rows stored before 0.5.0.
+    domain = Domain.from_email(email, unicode: true)
+    return false if domain.empty?
+    DisposableDomain.disposable?(domain)
+  end
+
+  # Does this address end in a TLD that actually exists?
+  #
+  # A different question from #disposable?, catching a different kind of bad
+  # address: `user@gmail.con` is not a throwaway, it is a typo that produces an
+  # account nobody can ever reach. Answers true for anything we cannot judge —
+  # no domain, no dot, an IP literal — so it is safe to call on any input; pair
+  # it with a format validation if you also care about shape.
+  def self.valid_tld?(email)
+    return true unless Tld.judgeable?(email)
+
+    tld = Tld.extract(email)
+    return false if tld.nil? # A domain with no TLD can't end in a real one
+
+    Tld.valid?(tld) && !Tld.blocked?(tld)
+  end
+
+  # "someone@gmial.com" => "someone@gmail.com", or nil when we have nothing
+  # useful to say. Never blocks anything by itself — hand it to a user and let
+  # them decide. See Nondisposable::Suggestion for how it decides.
+  def self.suggestion_for(email)
+    Suggestion.for(email)
   end
 
   class Configuration
     ON_CHECK_FAILURE_MODES = [:allow, :reject].freeze
+    LOOKALIKE_MODES = [false, true, :confirmable].freeze
 
     attr_accessor :error_message, :additional_domains, :excluded_domains
     # Whether to also match parent domains: with the default true, an email at
-    # x.tempmail.com is blocked when tempmail.com is on the list (checks up to
-    # DisposableDomain::PARENT_MATCH_DEPTH parent labels, never a bare TLD).
+    # x.tempmail.com is blocked when tempmail.com is on the list (checks
+    # every parent down to the registrable domain, never a public suffix).
     attr_accessor :check_parent_domains
     attr_reader :on_check_failure
 
+    # ---- Blocklist sources (Nondisposable::Source) --------------------------
+
+    # Where the list of disposable domains comes from: an ordered list of
+    # Nondisposable::Source objects (or Hashes of their attributes). The
+    # default is the single list this gem has always used, so upgrading changes
+    # nothing. Nondisposable::Sources::RECOMMENDED adds a second, independent
+    # primary. Needs the nondisposable_source_snapshots table
+    # (`rails g nondisposable:upgrade`); without it only the default is used.
+    attr_accessor :sources
+
+    # How many independent ORIGINS must list a domain before a :corroborating
+    # source's entry is blocked. Copies don't count: see Nondisposable::Source.
+    attr_accessor :corroboration_threshold
+
+    # Privacy relays (Apple Hide My Email, DuckDuckGo, Firefox Relay,
+    # SimpleLogin, addy.io — data/privacy_relays.txt) forward to a real,
+    # long-lived inbox. false (the default) ALLOWS them even when an upstream
+    # list carries them; true REFUSES them even when none does.
+    attr_accessor :block_privacy_relays
+
+    # ---- TLD validity (Nondisposable::Tld) ----------------------------------
+
+    # OFF by default, and it stays off: upgrading a gem must never silently
+    # start rejecting addresses that were fine yesterday. Turn it on to reject
+    # addresses whose TLD is not in the IANA root zone — `user@gmail.con` and
+    # friends, which are typos rather than throwaways but produce an account
+    # nobody can ever reach.
+    attr_accessor :check_tld
+
+    # Your escape hatch from a stale snapshot. A TLD delegated after this gem's
+    # release is unknown to the bundled list; naming it here accepts it
+    # immediately, with no release to wait for. Dots optional: "app" == ".app".
+    attr_accessor :additional_tlds
+
+    # TLDs to refuse even though they are perfectly real. The usual reason is
+    # abuse economics rather than validity — the historically free Freenom set
+    # (%w[tk ml ga cf gq]) is the classic example.
+    attr_accessor :blocked_tlds
+
+    # Allowlist mode: when set, ONLY these TLDs are accepted and every other one
+    # is refused. nil (the default) means "any TLD in the root zone". ⚠️ This is
+    # a blunt instrument — `%w[es]` turns away every customer who happens to use
+    # a .com address. Reach for blocked_tlds first.
+    attr_accessor :allowed_tlds
+
+    # ---- Lookalike domains (Nondisposable::Suggestion) ----------------------
+
+    # Flag addresses one edit away from a well-known provider — `gmail.co`,
+    # `gmial.com`, `hotmial.com` — with a message naming the correction.
+    #
+    #   false        (default) never flag; Nondisposable.suggestion_for still works
+    #   :confirmable flag them. Reviewed typos (data/known_typo_domains.txt) are
+    #                refused outright; every other lookalike is a guess, and the
+    #                user can confirm the address as typed and pass — see
+    #                Nondisposable::ConfirmableEmail.
+    #   true         the same as :confirmable. Before 0.5.0 it refused every
+    #                lookalike, including real organisations' domains (ge.com,
+    #                bol.com, one.com…) one edit from a provider.
+    #
+    # Worth leaving off unless your form can show the confirmation: without it a
+    # user at a domain that merely looks like a typo has no way through.
+    attr_reader :reject_lookalike_domains
+
+    # How many edits still count as "a typo". 1 (the default) is the distance at
+    # which acting on a guess is safe; at 2, genuinely different domains start
+    # colliding with each other. 0 disables suggestions entirely.
+    attr_accessor :lookalike_distance
+
+    # Providers to add to the bundled list — your own domain, a regional
+    # provider we missed. Adding one both makes it a suggestion candidate and,
+    # more importantly, stops its users being told they made a typo.
+    attr_accessor :additional_email_providers
+
+    # ---- Error messages -----------------------------------------------------
+
+    attr_accessor :invalid_tld_error_message, :blocked_tld_error_message
+    # %{suggestion} is replaced with the full corrected address.
+    attr_accessor :lookalike_error_message
+
     def initialize
       @error_message = "provider is not allowed"
       @additional_domains = []
       @excluded_domains = []
       @on_check_failure = :allow
       @check_parent_domains = true
+
+      @sources = Nondisposable::Sources::DEFAULT
+      @corroboration_threshold = 2
+      @block_privacy_relays = false
+
+      @check_tld = false
+      @additional_tlds = []
+      @blocked_tlds = []
+      @allowed_tlds = nil
+
+      @reject_lookalike_domains = false
+      @lookalike_distance = 1
+      @additional_email_providers = []
+
+      @invalid_tld_error_message = "doesn't look like a real email address"
+      @blocked_tld_error_message = "domain ending is not allowed"
+      @lookalike_error_message = "looks like a typo. Did you mean %{suggestion}?"
     end
 
     # What the validator does when the disposable check itself raises
@@ -60,5 +194,18 @@ module Nondisposable
 
       @on_check_failure = mode
     end
+
+    # Strings are accepted for config loaded from YAML/ENV ("confirmable",
+    # "true"); anything else raises, so a typo in an initializer fails at boot
+    # instead of silently meaning "on".
+    def reject_lookalike_domains=(mode)
+      mode = false if mode.nil?
+      mode = { 'true' => true, 'false' => false }.fetch(mode, mode.to_sym) if mode.is_a?(String)
+      unless LOOKALIKE_MODES.include?(mode)
+        raise ArgumentError, "reject_lookalike_domains must be one of #{LOOKALIKE_MODES.map(&:inspect).join(', ')} (got #{mode.inspect})"
+      end
+
+      @reject_lookalike_domains = mode
+    end
   end
 end

data/lib/tasks/nondisposable.rake

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+namespace :nondisposable do
+  namespace :tlds do
+    desc "Refresh the vendored IANA TLD snapshot (maintenance task — run in a gem checkout before a release)"
+    task :update do
+      # Deliberately NOT `require "nondisposable"`: that loads the Engine, which
+      # needs Rails, which a bare `rake` in a gem checkout doesn't have. Nothing
+      # this task touches reads configuration — only `Tld.valid?`/`blocked?` do,
+      # and it calls neither.
+      require_relative "../nondisposable/tld"
+      require_relative "../nondisposable/tld_list_updater"
+
+      before = begin
+        Nondisposable::Tld.all.size
+      rescue StandardError
+        0
+      end
+
+      count = Nondisposable::TldListUpdater.update
+
+      if count.nil?
+        abort "[nondisposable] TLD list unchanged. See the error above."
+      else
+        added = count - before
+        change =
+          if added.positive? then "+#{added}"
+          elsif added.negative? then added.to_s
+          else "no change"
+          end
+        puts "[nondisposable] TLD snapshot now holds #{count} entries (#{change})."
+        puts "[nondisposable] IANA version: #{Nondisposable::Tld.version}"
+        puts "[nondisposable] Commit data/iana_tlds.txt if it changed."
+      end
+    end
+  end
+end
+
+namespace :nondisposable do
+  namespace :psl do
+    desc "Refresh the vendored Public Suffix List snapshot (maintenance task — run in a gem checkout before a release)"
+    task :update do
+      # Same reasoning as tlds:update: no Rails here. The parser normalizes
+      # rules through Domain, so it comes along.
+      require_relative "../nondisposable/domain"
+      require_relative "../nondisposable/public_suffix"
+      require_relative "../nondisposable/public_suffix_list_updater"
+
+      before = begin
+        Nondisposable::PublicSuffix.rule_count
+      rescue StandardError
+        0
+      end
+
+      count = Nondisposable::PublicSuffixListUpdater.update
+
+      if count.nil?
+        abort "[nondisposable] Public Suffix List unchanged. See the error above."
+      else
+        puts "[nondisposable] PSL snapshot now holds #{count} rules (was #{before})."
+        puts "[nondisposable] PSL version: #{Nondisposable::PublicSuffix.version}"
+        puts "[nondisposable] Commit data/public_suffix_list.dat if it changed."
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nondisposable
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.6.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -41,20 +41,42 @@ files:
 - README.md
 - Rakefile
 - app/models/nondisposable/disposable_domain.rb
+- app/models/nondisposable/source_snapshot.rb
 - context7.json
 - data/disposable_email_blocklist.conf
+- data/email_providers.txt
+- data/iana_tlds.txt
+- data/known_typo_domains.txt
+- data/never_disposable.txt
+- data/privacy_relays.txt
+- data/public_suffix_list.dat
 - gemfiles/rails_7.2.gemfile
 - gemfiles/rails_8.0.gemfile
 - gemfiles/rails_8.1.gemfile
 - lib/generators/nondisposable/install_generator.rb
 - lib/generators/nondisposable/templates/create_nondisposable_disposable_domains.rb.erb
+- lib/generators/nondisposable/templates/create_nondisposable_source_snapshots.rb.erb
 - lib/generators/nondisposable/templates/disposable_email_domain_list_update_job.rb
 - lib/generators/nondisposable/templates/nondisposable.rb
+- lib/generators/nondisposable/upgrade_generator.rb
 - lib/nondisposable.rb
+- lib/nondisposable/confirmable_email.rb
+- lib/nondisposable/domain.rb
 - lib/nondisposable/domain_list_updater.rb
 - lib/nondisposable/email_validator.rb
 - lib/nondisposable/engine.rb
+- lib/nondisposable/known_typos.rb
+- lib/nondisposable/precedence.rb
+- lib/nondisposable/public_suffix.rb
+- lib/nondisposable/public_suffix_list_updater.rb
+- lib/nondisposable/source.rb
+- lib/nondisposable/source_fetcher.rb
+- lib/nondisposable/source_merge.rb
+- lib/nondisposable/suggestion.rb
+- lib/nondisposable/tld.rb
+- lib/nondisposable/tld_list_updater.rb
 - lib/nondisposable/version.rb
+- lib/tasks/nondisposable.rake
 - sig/nondisposable.rbs
 homepage: https://github.com/rameerez/nondisposable
 licenses: