nondisposable 0.3.0 → 0.4.0

data/lib/generators/nondisposable/templates/nondisposable.rb

@@ -16,4 +16,48 @@ Nondisposable.configure do |config|
   # Also match parent domains: an email at x.tempmail.com is blocked when
   # tempmail.com is on the list (checks up to 3 parent labels). Default: true
   # config.check_parent_domains = true
+
+  # ---- Catching typos ----
+  #
+  # A disposable address is someone hiding from you. A typo is someone who
+  # wanted to reach you and won't be able to: user@gmail.con is a real person
+  # whose account nobody can ever reach, because .con does not exist.
+  # Both checks below are OFF by default.
+
+  # Reject addresses whose TLD isn't in the IANA root zone (gmail.con,
+  # outlook.ed, and domains with no dot at all like example@gmailmcom).
+  # config.check_tld = true
+  #
+  # Accept a TLD delegated after your installed gem version shipped — so a
+  # stale snapshot can never leave a real customer stuck.
+  # config.additional_tlds = ['newtld']
+  #
+  # Refuse TLDs that are real but unwelcome (the historically free Freenom set):
+  # config.blocked_tlds = %w[tk ml ga cf gq]
+  #
+  # Or invert it into an allowlist. Careful: %w[es] turns away every .com
+  # customer you have.
+  # config.allowed_tlds = nil
+
+  # Reject addresses one keystroke from a well-known provider (gmail.co,
+  # gmial.com). A TLD check CANNOT catch these — .co, .cm and .om are Colombia,
+  # Cameroon and Oman, all real.
+  #
+  # Think before switching this on: a suggestion is a guess about intent, and a
+  # wrong guess stops a real person signing up with their real address.
+  # Nondisposable.suggestion_for(email) is always available and blocks nothing,
+  # which is the gentler way to use this — show the hint, let the human decide.
+  # config.reject_lookalike_domains = true
+  #
+  # How many edits still count as a typo. 1 is safe; 2 starts colliding with
+  # genuinely different domains. 0 disables suggestions entirely.
+  # config.lookalike_distance = 1
+  #
+  # Providers we missed, or your own domain. Adding one both makes it a
+  # suggestion candidate AND stops its users being told they made a typo.
+  # config.additional_email_providers = ['yourcompany.com']
+
+  # config.invalid_tld_error_message = "doesn't look like a real email address"
+  # config.blocked_tld_error_message = "domain ending is not allowed"
+  # config.lookalike_error_message = "looks like a typo. Did you mean %{suggestion}?"
 end

data/lib/nondisposable/email_validator.rb

@@ -3,6 +3,23 @@
 module ActiveModel
   module Validations
     class NondisposableValidator < EachValidator
+      # Three independent questions about one address, in the order a human
+      # would ask them, and AT MOST ONE error however many of them fire —
+      # stacking "provider is not allowed" on top of "did you mean gmail.com?"
+      # helps nobody:
+      #
+      #   1. Is this a throwaway provider?     (always on — the gem's whole job)
+      #   2. Can we name the address they meant? (config.reject_lookalike_domains,
+      #      or any invalid TLD we can correct — see below)
+      #   3. Is the TLD real, and allowed?     (config.check_tld)
+      #
+      # WHY A NAMEABLE CORRECTION OUTRANKS THE GENERIC TLD ERROR
+      #
+      # `user@gmail.con` fails both 2 and 3. "Doesn't look like a real email
+      # address" is true but useless; "Did you mean user@gmail.com?" is the same
+      # verdict with the fix attached. So whenever we can name a correction we
+      # use that message, whether the TLD was invalid or merely lookalike. The
+      # rule is: a suggestion, if we have one, always phrases the rejection.
       def validate_each(record, attribute, value)
         return if value.blank?
 
@@ -10,9 +27,36 @@ module ActiveModel
           domain = value.to_s.split('@').last&.downcase
           return if domain.nil? # Invalid email format
 
+          config = Nondisposable.configuration
+
           if Nondisposable::DisposableDomain.disposable?(domain)
-            record.errors.add(attribute, options[:message] || Nondisposable.configuration.error_message)
+            return reject(record, attribute, options[:message] || config.error_message)
+          end
+
+          return unless config.check_tld || config.reject_lookalike_domains
+          # No "@" at all is a malformed value, and this validator has never
+          # judged shape — that is what `format:` is for (see the README). Note
+          # `example@gmailmcom` DOES have one: a domain missing its dot is a real
+          # address at an impossible domain, which is very much our business.
+          return unless value.to_s.include?('@')
+          return unless Nondisposable::Tld.judgeable?(value)
+
+          # nil here means the domain has NO TLD (`example@gmailmcom` — a
+          # production-shaped typo that missed the dot), which fails "must end in a real TLD"
+          # just as surely as `.con` does.
+          tld = Nondisposable::Tld.extract(value)
+          invalid = config.check_tld && (tld.nil? || !Nondisposable::Tld.valid?(tld))
+          blocked = config.check_tld && !invalid && Nondisposable::Tld.blocked?(tld)
+
+          if invalid || config.reject_lookalike_domains
+            suggestion = Nondisposable::Suggestion.for(value)
+            if suggestion
+              return reject(record, attribute, config.lookalike_error_message.sub('%{suggestion}', suggestion))
+            end
           end
+
+          return reject(record, attribute, config.invalid_tld_error_message) if invalid
+          return reject(record, attribute, config.blocked_tld_error_message) if blocked
         rescue StandardError => e
           if Nondisposable.configuration.on_check_failure == :reject
             Rails.logger.error "[nondisposable] Nondisposable validation error: #{e.message} — rejecting #{attribute} (on_check_failure = :reject)"
@@ -22,6 +66,13 @@ module ActiveModel
           end
         end
       end
+
+      private
+
+      def reject(record, attribute, message)
+        record.errors.add(attribute, message)
+        nil
+      end
     end
 
     module HelperMethods

data/lib/nondisposable/suggestion.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Nondisposable
+  # "Did you mean gmail.com?"
+  #
+  # A TLD check catches the typos that produce a domain ending which cannot
+  # exist — `.con`, `.cpm`, `.ocm`. It structurally cannot catch the far more
+  # common ones, because `.co` (Colombia), `.cm` (Cameroon) and `.om` (Oman) are
+  # all real, delegated TLDs, as are `.se` and `.es`. `user@gmail.co` is a
+  # perfectly well-formed address at a perfectly real TLD, and it is still
+  # almost always a finger that slipped off the `m`.
+  #
+  # So this layer asks a different question: is this domain one keystroke away
+  # from a well-known email provider, while not being one itself?
+  #
+  # HOW IT DECIDES
+  #
+  # Optimal string alignment distance (Damerau-Levenshtein restricted to
+  # adjacent transpositions) against data/email_providers.txt. Transposition
+  # matters more than it looks: `gmial.com` is the single most common Gmail
+  # misspelling, and plain Levenshtein scores it 2 while a human sees one
+  # mistake. Under OSA it scores 1, alongside `gmai.com`, `gmail.co` and
+  # `gmail.con`.
+  #
+  # WHY THE DEFAULT THRESHOLD IS 1, AND WHY THIS IS OFF BY DEFAULT
+  #
+  # Every suggestion is a guess about intent, and a wrong guess wired to
+  # `reject_lookalike_domains` stops a real person from signing up with their
+  # real address. One edit is the distance at which a guess is safe enough to
+  # act on; at two, legitimately distinct domains start colliding. The exact
+  # match check runs first and always wins, which is why the provider list has
+  # to be generous — see the header of data/email_providers.txt.
+  #
+  # Suggesting is always available and never blocks:
+  #
+  #   Nondisposable.suggestion_for("someone@gmial.com") # => "someone@gmail.com"
+  #   Nondisposable.suggestion_for("someone@gmail.com") # => nil
+  #
+  # Blocking on it is a separate, deliberate opt-in
+  # (`config.reject_lookalike_domains`), because "probably a typo" is a weaker
+  # claim than "this TLD does not exist" and deserves a weaker remedy.
+  module Suggestion
+    LIST_PATH = File.expand_path('../../data/email_providers.txt', __dir__)
+
+    class << self
+      # The full corrected address, or nil when we have nothing useful to say.
+      def for(email)
+        email = email.to_s.strip
+        local, _, domain = email.rpartition('@')
+        return nil if local.empty? || domain.empty?
+
+        corrected = correct_domain(domain.downcase)
+        return nil if corrected.nil?
+
+        "#{local}@#{corrected}"
+      end
+
+      # The corrected DOMAIN alone, or nil. Split out so a host can offer
+      # "did you mean …?" next to a domain field, not just an email field.
+      def correct_domain(domain)
+        domain = domain.to_s.strip.downcase.delete_suffix('.')
+        return nil if domain.empty?
+        # A real provider is never a typo of another real provider.
+        return nil if providers.include?(domain)
+
+        threshold = Nondisposable.configuration.lookalike_distance.to_i
+        return nil if threshold < 1
+
+        best = nil
+        best_distance = threshold + 1
+
+        providers.each do |candidate|
+          # Cheap rejection before the O(n*m) walk: an edit changes the length
+          # by at most 1 per operation, so anything further apart than the
+          # threshold in length alone cannot be within it.
+          next if (candidate.length - domain.length).abs > threshold
+
+          distance = osa_distance(domain, candidate, best_distance)
+          next if distance >= best_distance
+
+          best = candidate
+          best_distance = distance
+          break if distance == 1 # nothing can beat one edit; stop early
+        end
+
+        best
+      end
+
+      # Every domain we would suggest, as a frozen Set: the bundled list plus
+      # anything the host added. Memoised per configuration object so a host
+      # changing config in a test or console is picked up.
+      def providers
+        config = Nondisposable.configuration
+        extra = Array(config.additional_email_providers).map { |d| d.to_s.strip.downcase }
+        cache_key = extra.hash
+
+        if @cache_key != cache_key || @providers.nil?
+          @providers = (bundled_providers + extra).to_set.freeze
+          @cache_key = cache_key
+        end
+
+        @providers
+      end
+
+      def reload!
+        @providers = nil
+        @bundled_providers = nil
+        @cache_key = nil
+        self
+      end
+
+      private
+
+      def bundled_providers
+        @bundled_providers ||= File.readlines(LIST_PATH, chomp: true).filter_map do |line|
+          value = line.strip.downcase
+          value unless value.empty? || value.start_with?('#')
+        end
+      end
+
+      # Optimal string alignment distance, with an early bail-out.
+      #
+      # Two rows instead of a full matrix (we only ever need the previous two),
+      # and if the best cell in a row already exceeds `cutoff` no later row can
+      # come back under it — the distance only grows — so we stop. With ~250
+      # candidates per lookup and a threshold of 1, almost every candidate exits
+      # on the length check above or within the first row or two.
+      # (Empty inputs need no special case: with an empty `a` the loop never
+      # runs and the seeded row already holds the right answer, b.length.)
+      def osa_distance(a, b, cutoff)
+        prev_prev = nil
+        prev = (0..b.length).to_a
+        current = Array.new(b.length + 1)
+
+        a.each_char.with_index do |a_char, i|
+          current[0] = i + 1
+          row_min = current[0]
+
+          b.each_char.with_index do |b_char, j|
+            cost = a_char == b_char ? 0 : 1
+            value = [
+              current[j] + 1,      # insertion
+              prev[j + 1] + 1,     # deletion
+              prev[j] + cost       # substitution
+            ].min
+
+            # Transposition: the one that makes `gmial` a single mistake.
+            if i.positive? && j.positive? && a_char == b[j - 1] && a[i - 1] == b_char
+              value = [value, prev_prev[j - 1] + cost].min
+            end
+
+            current[j + 1] = value
+            row_min = value if value < row_min
+          end
+
+          return cutoff if row_min >= cutoff
+
+          prev_prev = prev
+          prev = current.dup
+        end
+
+        prev[b.length]
+      end
+    end
+  end
+end

data/lib/nondisposable/tld.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Nondisposable
+  # Is the bit after the last dot a real top-level domain?
+  #
+  # This is a different question from "is this a disposable provider", and it
+  # catches a different kind of bad address: the typo. `user@gmail.con` is not a
+  # throwaway — it is a real person who will never receive their confirmation
+  # email, because `.con` does not exist and never has. Those accounts are born
+  # dead: nobody can reach the user, and the user cannot recover the account.
+  #
+  # WHY A BUNDLED LIST AND NOT A DEPENDENCY
+  #
+  # The list is the IANA root zone database — the authoritative register of every
+  # delegated TLD on the internet, ~1,438 entries in about 9 KB:
+  #
+  #   https://data.iana.org/TLD/tlds-alpha-by-domain.txt
+  #
+  # Every "TLD list" repository on GitHub is a scrape of that file, so we go to
+  # the source. The `tld` gem last shipped in 2014 and its list predates roughly
+  # 1,200 of today's TLDs. `public_suffix` is excellent and alive, but it answers
+  # "is this a valid public suffix" (which includes private entries like
+  # `github.io`) and it would pull the whole Public Suffix List in as a runtime
+  # dependency — the same trade-off DisposableDomain::PARENT_MATCH_DEPTH already
+  # declined, for the same reason.
+  #
+  # WHY IN MEMORY AND NOT IN THE DATABASE
+  #
+  # Disposable domains live in a table because there are 8,000+ of them and they
+  # change every few days. TLDs are 1,438 strings that change a handful of times
+  # a year. A frozen Set costs ~100 KB of process memory, answers in O(1) with no
+  # query per signup, needs no migration, and — unlike a table — cannot be empty
+  # on a fresh install. Refresh it with `rake nondisposable:tlds:update` (or
+  # `Nondisposable::TldListUpdater.update`) when cutting a release.
+  #
+  # STALENESS, AND WHY IT CANNOT LOCK ANYONE OUT
+  #
+  # The failure mode of a stale list is rejecting somebody whose TLD was
+  # delegated after the snapshot. `Nondisposable.configuration.additional_tlds`
+  # is the escape hatch: a host can accept a brand-new TLD immediately, without
+  # waiting for a gem release. And the check is opt-in (`config.check_tld`), so
+  # upgrading the gem never silently starts rejecting anybody.
+  module Tld
+    # The vendored IANA snapshot. Its first line is IANA's own version header,
+    # kept verbatim so the provenance and date of the data ship with it.
+    LIST_PATH = File.expand_path('../../data/iana_tlds.txt', __dir__)
+
+    # The names RFC 6761 and RFC 2606 reserve so they can NEVER be delegated.
+    # They are therefore absent from the root zone, and `check_tld` rejects
+    # them — which is right for a signup form, because no human types
+    # `me@home.test`, and an address there could never receive the confirmation
+    # email anyway.
+    #
+    # It is also, on the day you switch `check_tld` on, why half your test suite
+    # goes red: fixtures live at `user@example.test` for exactly the same reason
+    # the names are reserved. That is a configuration question, not a bug, and
+    # this constant is here so the answer reads like a sentence:
+    #
+    #   config.additional_tlds = Nondisposable::Tld::SPECIAL_USE if Rails.env.local?
+    #
+    # Scope it to your non-production environments. Somewhere in the world
+    # somebody is running an app that really does deliver mail inside `.local`;
+    # if that is you, add it in production too and you are the exception that
+    # proves why this is configuration.
+    SPECIAL_USE = %w[test example invalid localhost local onion].freeze
+
+    class << self
+      # Every TLD IANA has delegated, downcased, as a frozen Set.
+      # Memoized: read once per process, never re-read.
+      def all
+        @all ||= parse(File.readlines(LIST_PATH, chomp: true)).freeze
+      end
+
+      # IANA's own version string for the bundled snapshot, e.g.
+      # "2026082301, Last Updated Mon Aug 24 07:07:01 2026 UTC". Useful in a
+      # health check to see how old your list is.
+      def version
+        @version ||= begin
+          header = File.open(LIST_PATH, &:readline).to_s.strip
+          header.start_with?('#') ? header.sub(/\A#\s*Version\s*/i, '') : nil
+        rescue StandardError
+          nil
+        end
+      end
+
+      # The TLD of an email address or a bare domain, downcased.
+      #
+      # nil means THERE IS NO TLD HERE — which is not the same as "we can't
+      # tell". `example@gmailmcom` (the dot missed entirely) and
+      # `you@localhost` both land here, and under check_tld both are rejected:
+      # a domain with no TLD cannot end in a real one. Ask #judgeable? first if
+      # you need to tell that apart from an address this gem has no opinion on.
+      def extract(email_or_domain)
+        domain = normalize(email_or_domain)
+        return nil if domain.empty?
+
+        labels = domain.split('.')
+        return nil if labels.size < 2
+
+        tld = labels.last
+        tld.empty? ? nil : tld
+      end
+
+      # Is this an address the TLD rules have anything to say about?
+      #
+      # False for the two shapes where "what is the TLD" is the wrong question
+      # rather than a question with a bad answer: an empty domain, and an IP
+      # literal (`user@192.168.0.1`, `user@[10.0.0.1]`). Both are left alone —
+      # deciding whether to accept an IP-literal address is a format policy, and
+      # a validator called `check_tld` has no business making it.
+      def judgeable?(email_or_domain)
+        domain = normalize(email_or_domain)
+        return false if domain.empty?
+        return false if domain.start_with?('[') || domain.match?(/\A[\d.]+\z/)
+
+        true
+      end
+
+      # Is this TLD in the root zone (or in the host's additional_tlds)?
+      #
+      # ⚠️ Non-ASCII TLDs always answer true. IANA lists internationalised TLDs
+      # in punycode (`XN--FIQS8S`), and converting `中国` to that form needs an
+      # IDN library we deliberately do not depend on. Rather than reject every
+      # unicode address, we decline to judge them: a false accept is a nuisance,
+      # a false reject is a locked-out human. Punycode-form addresses, which is
+      # what mail clients actually send, are checked normally.
+      def valid?(tld)
+        tld = tld.to_s.downcase
+        return false if tld.empty?
+        return true unless tld.ascii_only?
+
+        all.include?(tld) || configured(:additional_tlds).include?(tld)
+      end
+
+      # Has the host explicitly blocked this TLD — either by naming it in
+      # `blocked_tlds`, or by naming everything else in `allowed_tlds`?
+      def blocked?(tld)
+        tld = tld.to_s.downcase
+        return false if tld.empty?
+
+        allowed = configured(:allowed_tlds)
+        return true if allowed && !allowed.include?(tld)
+
+        configured(:blocked_tlds).include?(tld)
+      end
+
+      # Reset the memoized list. Called by the updater after it rewrites the
+      # file, and by tests.
+      def reload!
+        @all = nil
+        @version = nil
+        self
+      end
+
+      private
+
+      # The domain half, trimmed, downcased, and without the trailing dot a
+      # fully-qualified name may carry (`gmail.com.` is the same host).
+      def normalize(email_or_domain)
+        email_or_domain.to_s.split('@').last.to_s.strip.downcase.delete_suffix('.')
+      end
+
+      # Skips IANA's comment header and any blank lines.
+      def parse(lines)
+        lines.each_with_object(Set.new) do |line, set|
+          value = line.to_s.strip.downcase
+          next if value.empty? || value.start_with?('#')
+
+          set << value
+        end
+      end
+
+      # Config lists are host-supplied, so normalise on every read rather than
+      # trusting them to be lowercase, dotless strings. `.tk` and `TK` both work.
+      def configured(key)
+        value = Nondisposable.configuration.public_send(key)
+        return nil if value.nil?
+
+        Set.new(Array(value).map { |tld| tld.to_s.strip.downcase.delete_prefix('.') })
+      end
+    end
+  end
+end

data/lib/nondisposable/tld_list_updater.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Nondisposable
+  # Refreshes the vendored IANA TLD snapshot from the root zone database.
+  #
+  # ⚠️ This is a MAINTENANCE task, not a runtime one — the deliberate opposite of
+  # DomainListUpdater. That one runs in your app, on a schedule, because
+  # disposable domains change every few days and live in your database. This one
+  # rewrites a file inside the gem, which is read-only once the gem is installed.
+  # Run it in a checkout of the gem before cutting a release:
+  #
+  #   rake nondisposable:tlds:update
+  #
+  # If you need a TLD that is newer than your installed gem, do NOT reach for
+  # this. Add it to `config.additional_tlds` and you are unblocked immediately,
+  # with no release and no writable-gem-directory problem:
+  #
+  #   config.additional_tlds = %w[newtld]
+  #
+  # New TLDs are delegated in batches a few times a year, so a snapshot ages
+  # slowly. ICANN's next application round is the first real test of that.
+  class TldListUpdater
+    LIST_URL = 'https://data.iana.org/TLD/tlds-alpha-by-domain.txt'
+
+    OPEN_TIMEOUT = 10
+    READ_TIMEOUT = 10
+
+    # A root zone that suddenly contains a handful of entries means the fetch
+    # went wrong (a captive portal, an error page, a truncated body), not that
+    # ICANN deleted the internet. Refuse to overwrite a good list with junk.
+    MINIMUM_PLAUSIBLE_TLD_COUNT = 1_000
+
+    class << self
+      # Returns the number of TLDs written, or nil if nothing was written.
+      def update(path: Nondisposable::Tld::LIST_PATH)
+        log :info, "Fetching the IANA root zone TLD list from #{LIST_URL}..."
+
+        response = fetch
+        unless response.is_a?(Net::HTTPSuccess)
+          log :error, "Failed to download the TLD list. HTTP status: #{response.code}. Keeping the existing snapshot."
+          return nil
+        end
+
+        body = response.body.to_s
+        count = body.lines.count { |line| meaningful?(line) }
+
+        if count < MINIMUM_PLAUSIBLE_TLD_COUNT
+          log :error, "Refusing to write a TLD list with only #{count} entries (expected at least #{MINIMUM_PLAUSIBLE_TLD_COUNT}). Keeping the existing snapshot."
+          return nil
+        end
+
+        # Written whole, then moved into place, so an interrupted run can never
+        # leave a half-written root zone behind.
+        tmp = "#{path}.tmp"
+        File.write(tmp, body)
+        File.rename(tmp, path)
+        Nondisposable::Tld.reload!
+
+        log :info, "Wrote #{count} TLDs to #{path} (#{Nondisposable::Tld.version})."
+        count
+      rescue StandardError => e
+        log :error, "Could not update the TLD list: #{e.class}: #{e.message}. Keeping the existing snapshot."
+        nil
+      ensure
+        File.delete(tmp) if tmp && File.exist?(tmp)
+      end
+
+      private
+
+      def meaningful?(line)
+        value = line.to_s.strip
+        !value.empty? && !value.start_with?('#')
+      end
+
+      def fetch
+        uri = URI(LIST_URL)
+        Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == 'https',
+          open_timeout: OPEN_TIMEOUT,
+          read_timeout: READ_TIMEOUT
+        ) { |http| http.get(uri.request_uri) }
+      end
+
+      # Usable from a bare `rake` run in a gem checkout, where there is no Rails
+      # logger to talk to.
+      def log(level, message)
+        message = "[nondisposable] #{message}"
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.public_send(level, message)
+        else
+          warn message
+        end
+      end
+    end
+  end
+end

data/lib/nondisposable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nondisposable
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end