nondisposable 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96ee85d55e05d52d472cb9a4b9897e318499282c35818579621daec1bcd7bf9e
-  data.tar.gz: f633e949328cb2972dfdff7c44f33072b29dae4b5bd95ab116af24ec504f676c
+  metadata.gz: 2193d2a242a699cdd8b05767d364d5da7f039f5f2e3203592d0f3222bb8c29db
+  data.tar.gz: bb866074eb28008df4eecd8fab1df646ebbde5eddd6907dfaa43126c3348a315
 SHA512:
-  metadata.gz: 71c6fbbfcac0534c320decc1cee69147497984a9dc12f19569a2231eacc192a5a2cc328e88decdc5e8f692384bf8ae39705a9c77ff134fb5cccc02fc455c133d
-  data.tar.gz: 8abdd8d29e8bfeb5f51da7cc98a6b213a8af428b561a8be6a9d2e84bce470f96a5e2c5bbeeff2f9a4e0dda0d719f5e696562c97b9643278a5d92a5c90ae8ff06
+  metadata.gz: d88abe6d8b21e332bab766e6a132a1d3e311bba0f067c4a80e5148172249465a58d8053ce3d100d842a3bfebe08dd8910daed05aa8f10d622d9e7a8802ebffa7
+  data.tar.gz: 967dbdbfea2858290d97b150b8e19827314c7031250fd69c274b14a06d4bd9036999ef180a794bc76537c785847babae3a707f69e0837c61b018f159579259b7

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.6.2] - 2026-10-18
+
+### Fixed
+
+- **A reviewed typo that a blocklist also lists now gets "Did you mean …?", not the disposable message.** The bundled upstream snapshot lists `gmial.com`, `hotmai.com` and `hotmial.com`, three of the entries in `data/known_typo_domains.txt`, and the validator asked the disposable table first, so with `reject_lookalike_domains` on and the table loaded, `ana@gmial.com` was told "provider is not allowed" instead of "Did you mean ana@gmail.com?". The address was refused either way; the message was wrong, and it sent a person who missed a key looking for a problem they don't have. The two **hard** corrections (a reviewed typo, and an impossible TLD with a nameable correction such as `gmail.con`) are now answered before the disposable check, without touching the database: a lookup that raises can neither let `ana@gmial.com` through under `on_check_failure = :allow` nor replace the correction with the generic "cannot check" error under `:reject`. A **guess** still comes after it, and so does the ranker that produces it, so an ordinary listed throwaway never pays for the distance walk: `gotmail.com` and `tmail.com` are both one finger from a provider and listed throwaways, and a confirmable "did you mean" there would only let the user confirm an address that is then refused anyway. **What changes, exactly** (every case below was refused before and is still refused; only the message differs): with `reject_lookalike_domains` on, a reviewed typo gets "Did you mean …?" even when it is listed, whether by an upstream source or by the host's own `additional_domains`, and even over a validator's own `message:` option. With `check_tld` on (alone or not), so does a listed domain whose ending does not exist and for which a correction can be named. Nothing changes with both checks off, at `lookalike_distance = 0`, or for a domain a host put in `additional_email_providers`: the table answers, with the disposable message, as before. The overlap with the blocklist is deliberately **not** filtered out of the stored list: that would let those typos through for every host without the lookalike layer, and for `Nondisposable.disposable?`. Reported by a review of a Rails app integrating the gem.
+- **Reading a "Did you mean …?" error can no longer raise, or rewrite what the user typed.** `%`, `{` and `}` are legal in the local part of an address, and the confirmable error was added as `errors.add(:email, :lookalike_domain, message: …)`, which ActiveModel looks up and I18n-interpolates again on every read. So since 0.5.0, `a%{x}b@gnail.com` made `errors.full_messages` raise `I18n::MissingInterpolationArgument` (a broken signup response), and `a%{value}b@gnail.com` pasted the whole address into the middle of the message. The lookalike errors are now `Nondisposable::LookalikeError`s: an `ActiveModel::Error` whose message is resolved once, when the address is validated, and returned as is from then on. Type and details are unchanged (`errors.of_kind?(:email, :lookalike_domain)`, `errors.details[:email]` => `[{ error: :lookalike_domain, suggestion: … }]`), and `merge!`/`dup` keep the message. The text is computed the way ActiveModel computed it before, once: a per-model `lookalike_domain` translation (`activerecord.errors.models.user.attributes.email.lookalike_domain`) still wins over a configured String, and `%{attribute}` and `%{value}` still interpolate in that String; only what the user typed is no longer read as a pattern.
+
+### Added
+
+- **`config.lookalike_error_message` accepts a Rails error name or a callable**, as well as a String. A Symbol means what it already means for `error_message` and the TLD messages: a short error name (`:email_lookalike`) resolved through ActiveModel's lookup chain (`activerecord.errors.models.user.attributes.email.email_lookalike`, …, `errors.messages.email_lookalike`) in the locale of the request, with `%{suggestion}` (plus `%{attribute}`, `%{value}`) to interpolate. It is resolved once, when the address is validated, so an error read later (in another locale, or by a translation Proc that would raise the second time) shows what was resolved and never "Translation missing". The hard error is added with that name, as `error_message` is; the confirmable one stays typed `:lookalike_domain` with the Symbol as its message, so forms still tell it apart. `:lookalike_domain` itself is refused at boot, since a hard error of that type would offer the confirmation checkbox. A callable is called with the suggestion (`->(suggestion) { … }`) and must return a String. A String works exactly as before, and so does any object answering `#sub`, which until now was the only way to localise this message. `Configuration#lookalike_message(suggestion)` resolves it outside a model (a Symbol under `errors.messages`).
+- **A message that cannot be used never weakens the refusal.** A missing translation, one naming a variable the gem does not pass, a key naming a whole translation group, a `nil` message, a callable that raises, takes no argument or returns something other than a String: each is logged and replaced by the default English message, and the address is still refused. Before, a raise there reached the validator's rescue, where the default `on_check_failure = :allow` accepted the address. A String is now substituted with the block form of `#sub`, so a `\0` or `\&` typed in the local part is printed as typed.
+
 ## [0.6.1] - 2026-10-17
 
 ### Fixed

data/README.md

@@ -135,7 +135,7 @@ Nondisposable.configure do |config|
 
   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}?"
+  config.lookalike_error_message = "looks like a typo. Did you mean %{suggestion}?" # or a Rails error name (:email_lookalike), or a lambda
 end
 ```
 
@@ -252,7 +252,9 @@ config.reject_lookalike_domains = :confirmable # `true` means the same thing
 | any other lookalike the ranker suggests | `gnail.com` | **confirmable**: same message, unless the user confirmed the address |
 | anything else | `ge.com`, `yahoo.com.au` | accepted |
 
-A disposable provider is still refused first, and a blocked TLD is still refused after a confirmation. A host's `additional_email_providers` outranks the known-typo list.
+A disposable provider is refused before any **guess** (a confirmable "did you mean" would only let the user confirm an address that is then refused anyway), and a blocked TLD is still refused after a confirmation. A host's `additional_email_providers` outranks the known-typo list.
+
+The two **hard** corrections — an impossible TLD and a reviewed typo — are answered before the disposable check, without a database query (since 0.6.2). Upstream blocklists carry some reviewed typos (the bundled snapshot lists `gmial.com`, `hotmai.com` and `hotmial.com`), and the address is refused either way; but `ana@gmial.com` is a person who missed a key, not someone hiding behind a temporary inbox, so they get "Did you mean ana@gmail.com?" rather than the disposable message — also over a validator's own `message:`, and when the domain is in your `additional_domains`. Before 0.6.2 these typos got the disposable message whenever the table was loaded.
 
 The known-typo list is short (41 entries) on purpose. An entry needs direct evidence that nobody has a mailbox there — a redirect to the provider or the provider's own DNS (`yaho.com`, `homail.com`), a parking or for-sale network (`gamail.com`, `hotmial.com`), a typosquat redirect or catch-all (`gmial.com`, `gmali.com`), or a registered domain with no MX, A or AAAA record (`gmal.com`). "No MX" alone is not enough: SMTP falls back to the A record. The evidence for every entry is in `test/fixtures/lookalike_corpus.csv`, and the suite fails if an entry loses it.
 
@@ -296,9 +298,31 @@ At most one error is added, however many checks fire — and whenever the gem ca
 | `user@gnail.com` | accepted | same message, confirmable |
 | `user@ge.com` | accepted | accepted |
 | `user@tempmail.com` | "provider is not allowed" | same |
+| `user@gmial.com` (a reviewed typo the blocklist also lists) | "provider is not allowed" | "looks like a typo. Did you mean user@gmail.com?" |
 
 "Doesn't look like a real email address" is true but useless when we know what they meant, so a nameable correction always outranks the generic message.
 
+#### Translating the "Did you mean" message
+
+`lookalike_error_message` takes a String (with `%{suggestion}`), a Rails error name, or anything callable. A Symbol means what it means for `error_message` and the TLD messages: a short error name, looked up when the address is validated through the usual ActiveModel chain (`activerecord.errors.models.user.attributes.email.<name>`, …, `errors.messages.<name>`), so it answers in the current request's locale and can differ per model or attribute:
+
+```ruby
+# config/initializers/nondisposable.rb
+config.lookalike_error_message = :email_lookalike
+```
+
+```yaml
+# config/locales/es.yml
+es:
+  errors:
+    messages:
+      email_lookalike: "parece una errata. ¿Querías decir %{suggestion}?"
+```
+
+`%{suggestion}` is the full corrected address (`ana@gmail.com`), or just the corrected domain when nothing was typed before the `@`; `%{attribute}` and `%{value}` work as in any Rails error message. The hard error is added under that name (`errors.of_kind?(:email, :email_lookalike)`), like `error_message`; the confirmable one stays `:lookalike_domain`, so your checkbox logic doesn't change. That is also why `:lookalike_domain` itself is refused as the name. Unlike an ordinary Rails error, the text is resolved once, when the address is validated, and kept: rendering never looks it up again, so it can't fail later, and whatever the user typed (`%{…}` is legal in an address) is printed as typed.
+
+If the key has no translation in the current locale, Rails' lookup (and I18n's locale fallbacks, if you've turned them on) gets the first try; only when nothing is found does the gem use its default English message, never "Translation missing". The same goes for a translation that names a variable the gem doesn't pass, a key that names a whole group, or a callable that raises: the message falls back and the error is logged, and the address is refused either way, so a broken locale file can never let it through. For anything else, pass a callable that returns a String: `config.lookalike_error_message = ->(suggestion) { I18n.t("my_app.email_typo", suggestion: suggestion) }`. A String works exactly as before, including on the confirmable error: `%{attribute}` and `%{value}` interpolate, and a translation of that model's `lookalike_domain` (`activerecord.errors.models.user.attributes.email.lookalike_domain`) wins over it.
+
 ### Direct Check
 
 You can also check if an email is disposable directly:

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

@@ -82,4 +82,8 @@ Nondisposable.configure do |config|
   # 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}?"
+  # ...or a Rails error name, like the messages above: looked up per request
+  # through ActiveModel's chain, e.g. errors.messages.email_lookalike in your
+  # locale files, with %{suggestion} to interpolate:
+  # config.lookalike_error_message = :email_lookalike
 end

data/lib/nondisposable/email_validator.rb

@@ -1,25 +1,98 @@
 # frozen_string_literal: true
 
+module Nondisposable
+  # A validation error whose message was resolved when it was added, and is
+  # never resolved again.
+  #
+  # An ordinary `errors.add(:email, :some_type, message: "…")` keeps the type
+  # and looks the message up AGAIN every time it is read: the first key of
+  # ActiveModel's chain in whatever locale is current then, and I18n
+  # interpolation over the text. For "Did you mean …?" both are hazards. The
+  # text contains what the user typed, and `%`, `{` and `}` are legal in a
+  # local part, so `a%{x}b@gnail.com` made errors.full_messages raise
+  # I18n::MissingInterpolationArgument (since 0.5.0) and `a%{value}b@…` pasted
+  # the whole address into the middle of it. And a Symbol message we already
+  # checked could resolve differently at render time (another locale, a
+  # translation Proc that raises the second time), outside any fallback.
+  #
+  # So the message is frozen here, while the type and details stay what a
+  # form and an API expect: `errors.of_kind?(:email, :lookalike_domain)`,
+  # `errors.details[:email]` => [{ error: :lookalike_domain, suggestion: … }].
+  # It is in the locale of the request that validated, which is the request
+  # that renders it.
+  class LookalikeError < ActiveModel::Error
+    def initialize(base, attribute, type, resolved_message, **options)
+      super(base, attribute, type, **options)
+      @resolved_message = resolved_message
+    end
+
+    def message
+      @resolved_message
+    end
+  end
+end
+
 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:
+      # Three independent questions about one address, 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:
+      #
+      #   - Is this a throwaway provider?        (always on — the gem's whole job)
+      #   - Can we name the address they meant?  (config.reject_lookalike_domains,
+      #     or any invalid TLD we can correct — see below)
+      #   - Is the TLD real, and allowed?        (config.check_tld)
+      #
+      # The answer is chosen in this order, first match wins:
+      #
+      #   1. A HARD correction: an impossible TLD or a reviewed typo we can name
+      #      the fix for (`gmail.con`, `gmial.com`). "Did you mean …?"
+      #   2. A throwaway provider. "provider is not allowed"
+      #   3. A GUESS (`gnail.com`): the same "Did you mean …?", but confirmable.
+      #   4. An invalid or blocked TLD.
+      #
+      # WHY A HARD CORRECTION OUTRANKS THE THROWAWAY CHECK (since 0.6.2)
+      #
+      # Upstream blocklists carry some of the very typos we reviewed: the
+      # bundled snapshot lists `gmial.com`, `hotmai.com` and `hotmial.com`.
+      # Both verdicts refuse the address, so the order only decides the
+      # MESSAGE, and only one of them is true about the person typing: someone
+      # at `ana@gmial.com` did not pick a temporary inbox, they missed a key
+      # on the way to gmail.com. Being told their provider is a throwaway
+      # sends them looking for a problem they don't have; "Did you mean
+      # ana@gmail.com?" fixes it in one click. A hard correction is certain (no mail reaches
+      # `.con`; somebody checked `gmial.com`), so it is safe to let it phrase a
+      # refusal the blocklist would have made anyway. Until 0.6.2 the throwaway
+      # check ran first, and these typos got the wrong message whenever the
+      # table was loaded.
+      #
+      # It is answered BEFORE the blocklist is even asked, not just phrased
+      # after it: a certain correction needs no database, so a lookup that
+      # raises can neither wave `ana@gmial.com` through (on_check_failure =
+      # :allow) nor bury the correction under the generic "cannot check"
+      # error (:reject). And it is cheap — a hash lookup in the reviewed list,
+      # and the ranker only for an ending that does not exist.
       #
-      #   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)
+      # A guess stays BEHIND the throwaway check. It is only a likelihood, and
+      # the user can answer it: `gotmail.com` and `tmail.com` are both one
+      # finger from a provider AND listed throwaways, so asking "did you mean
+      # hotmail.com?" there would let them tick "yes, this is right" only to
+      # be refused anyway on the next submit. A listed throwaway is the
+      # stronger evidence, and the more useful answer. It is also the
+      # expensive part (a distance walk over every provider), so it runs only
+      # for addresses the blocklist did not already refuse: an ordinary
+      # throwaway never pays for it.
       #
       # 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.
+      # `user@gmail.con` fails both the lookalike and the TLD question. "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 — unless it is a guess about a domain we
+      # KNOW is a throwaway (above).
       #
       # HARD vs CONFIRMABLE — WHICH LOOKALIKES CAN BE WAVED THROUGH
       #
@@ -58,52 +131,34 @@ module ActiveModel
             return reject(record, attribute, config.invalid_tld_error_message)
           end
 
+          spelling = spelling_of(value, config)
+
+          # 1. A certain correction: no database, no ranker for a real ending.
+          # See "why a hard correction outranks the throwaway check" above. A
+          # plain message, not the confirmable :lookalike_domain kind, so a
+          # form never offers "yes, this is right" for it.
+          return add_lookalike_error(record, attribute, config, spelling.correction, confirmable: false) if spelling&.correction
+
+          # 2. A throwaway provider.
           if Nondisposable::DisposableDomain.disposable?(domain)
             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)
-          impossible = tld.nil? || !Nondisposable::Tld.valid?(tld)
-          invalid = config.check_tld && impossible
-          blocked = config.check_tld && !invalid && Nondisposable::Tld.blocked?(tld)
-
-          if invalid || config.reject_lookalike_domains
+          return unless spelling
+
+          # 3. A guess, which the user can confirm. Not when the ending is
+          # impossible: spelling_of already asked the ranker then, and it had
+          # nothing to name.
+          if config.reject_lookalike_domains && !spelling.impossible
             suggestion = Nondisposable::Suggestion.for(value)
-            # `@gmial.com` has no local part to build "Did you mean ..." from,
-            # but it is still a reviewed typo: name the domain instead.
-            if suggestion.nil? && config.lookalike_distance.to_i.positive?
-              suggestion = Nondisposable::KnownTypos.correction_for(value)
-            end
-            if suggestion
-              message = config.lookalike_error_message.sub('%{suggestion}', suggestion)
-              # Hard: no confirmation can make an impossible TLD deliverable —
-              # whether or not the host turned check_tld on, `gmail.con` cannot
-              # receive the confirmation email — and a reviewed typo is not a
-              # guess. The error stays a plain message, exactly as before 0.5.0.
-              return reject(record, attribute, message) if impossible || Nondisposable::KnownTypos.include?(value)
-
-              unless Nondisposable::ConfirmableEmail.confirmed?(record, attribute)
-                # Typed, so a form can tell this error apart and offer the
-                # "yes, this is right" checkbox: errors.of_kind?(:email, :lookalike_domain).
-                record.errors.add(attribute, :lookalike_domain, message: message, suggestion: suggestion)
-                return
-              end
+            if suggestion && !Nondisposable::ConfirmableEmail.confirmed?(record, attribute)
+              return add_lookalike_error(record, attribute, config, suggestion, confirmable: true)
             end
           end
 
-          return reject(record, attribute, config.invalid_tld_error_message) if invalid
-          return reject(record, attribute, config.blocked_tld_error_message) if blocked
+          # 4. The TLD itself.
+          return reject(record, attribute, config.invalid_tld_error_message) if spelling.invalid
+          return reject(record, attribute, config.blocked_tld_error_message) if spelling.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)"
@@ -116,6 +171,152 @@ module ActiveModel
 
       private
 
+      # What the TLD and lookalike checks make of an address BEFORE anything
+      # costly runs: no database, and no ranker unless the ending is
+      # impossible.
+      #
+      #   correction  a CERTAIN correction (see #certain_correction), or nil
+      #   impossible  the ending is not a TLD at all (`.con`, or no dot)
+      #   invalid     the TLD fails check_tld
+      #   blocked     the TLD is real, but blocked_tlds/allowed_tlds refuse it
+      Spelling = Struct.new(:correction, :impossible, :invalid, :blocked, keyword_init: true)
+      private_constant :Spelling
+
+      # nil when neither check applies to this value at all.
+      def spelling_of(value, config)
+        return nil 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 nil unless value.to_s.include?('@')
+        return nil 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)
+        impossible = tld.nil? || !Nondisposable::Tld.valid?(tld)
+        invalid = config.check_tld && impossible
+
+        Spelling.new(
+          correction: certain_correction(value, config, impossible),
+          impossible: impossible,
+          invalid: invalid,
+          blocked: config.check_tld && !invalid && Nondisposable::Tld.blocked?(tld)
+        )
+      end
+
+      # A correction no confirmation can override, or nil. Two kinds:
+      #
+      # - An impossible ending with anything the ranker can name (`gmail.con`):
+      #   no mail reaches `.con`, so the guess about WHICH address they meant
+      #   is the only uncertain part, and the refusal is not. Applies whether
+      #   or not the host turned check_tld on — `gmail.con` cannot receive the
+      #   confirmation email either way.
+      # - A reviewed typo (`gmial.com`): somebody checked; nobody has a mailbox
+      #   there. Only with reject_lookalike_domains on, and not at
+      #   lookalike_distance 0, which switches the whole layer off.
+      #
+      # `@gmial.com` has no local part to build "Did you mean ..." from, but
+      # it is still a reviewed typo: name the domain instead.
+      def certain_correction(value, config, impossible)
+        return nil unless config.lookalike_distance.to_i.positive?
+
+        if impossible
+          Nondisposable::Suggestion.for(value) || Nondisposable::KnownTypos.correction_for(value)
+        elsif config.reject_lookalike_domains && Nondisposable::KnownTypos.include?(value)
+          # Suggestion.for asks the reviewed list before the ranker, so this
+          # never pays for a distance walk.
+          Nondisposable::Suggestion.for(value) || Nondisposable::KnownTypos.correction_for(value)
+        end
+      end
+
+      # The "Did you mean …?" error, hard or confirmable.
+      #
+      # The confirmable one is always typed :lookalike_domain (with the
+      # suggestion in its details), so a form can tell it apart and offer the
+      # "yes, this is right" checkbox: errors.of_kind?(:email, :lookalike_domain).
+      # The hard one is a plain message, exactly as before 0.5.0 — or, for a
+      # Symbol, an error of that name, just as error_message and the TLD
+      # messages are added.
+      #
+      # A Symbol resolves through the same ActiveModel chain as every other
+      # Rails error name, and the confirmable error still honours a per-model
+      # `lookalike_domain` translation (#confirmable_message) — but NOW, once,
+      # into a String (see Nondisposable::LookalikeError for why it is never
+      # resolved again). A
+      # translation that is missing, names a variable we don't pass, or is a
+      # whole group (a Hash) is a refusal with a broken message, and we refuse
+      # with the default message instead — never a raise, which
+      # on_check_failure = :allow would turn into an acceptance.
+      def add_lookalike_error(record, attribute, config, suggestion, confirmable:)
+        key = config.lookalike_error_message
+
+        if confirmable
+          add_resolved(record, attribute, :lookalike_domain, confirmable_message(record, attribute, config, suggestion), suggestion)
+        elsif key.is_a?(Symbol)
+          message = resolve_rails_message(record, attribute, config, key, suggestion) || config.default_lookalike_message(suggestion)
+          add_resolved(record, attribute, key, message, suggestion)
+        else
+          # A plain String error, as since 0.5.0: no translation lookup, and
+          # never interpolated when read, so nothing to freeze.
+          record.errors.add(attribute, config.lookalike_message(suggestion))
+        end
+        nil
+      end
+
+      # The confirmable error's text, computed exactly as ActiveModel used to
+      # compute it on every read of `errors.add(attr, :lookalike_domain,
+      # message: …)`, but once:
+      #
+      # - A Symbol replaces the type in Rails' lookup, so it is its own
+      #   chain (#resolve_rails_message).
+      # - Anything else is the default for the FIRST key of the chain,
+      #   activemodel/activerecord.errors.models.<model>.attributes.<attr>.lookalike_domain,
+      #   so an app that translated that key keeps its translation (it did
+      #   until 0.6.1, and must not lose it on upgrade). A String goes in as
+      #   the template it is, with %{suggestion} as a VALUE: I18n never
+      #   rescans a value, so a `%{x}` the user typed is printed, not
+      #   interpolated. A callable's (or a #sub object's) output is already
+      #   final, so its `%` are escaped for the same reason.
+      def confirmable_message(record, attribute, config, suggestion)
+        key = config.lookalike_error_message
+        if key.is_a?(Symbol)
+          return resolve_rails_message(record, attribute, config, key, suggestion) || config.default_lookalike_message(suggestion)
+        end
+
+        template = key.is_a?(String) ? key : config.lookalike_message(suggestion).gsub('%', '%%')
+        text = record.errors.generate_message(attribute, :lookalike_domain, message: template, suggestion: suggestion)
+        raise TypeError, "it resolved to #{text.class}, not a String" unless text.is_a?(String)
+
+        text
+      rescue StandardError => e
+        config.default_lookalike_message(suggestion, e) # logs it
+      end
+
+      # Errors#add would build an ActiveModel::Error that re-resolves its
+      # message on every read; this appends one that does not, the same way
+      # Errors#add appends its own.
+      def add_resolved(record, attribute, type, message, suggestion)
+        record.errors.objects.append(
+          Nondisposable::LookalikeError.new(record, attribute.to_sym, type, message, suggestion: suggestion)
+        )
+      end
+
+      # This Rails error name as a String for this record, in the current
+      # locale (and its I18n fallbacks, when the host has them on), or nil
+      # when it cannot be one.
+      def resolve_rails_message(record, attribute, config, key, suggestion)
+        text = record.errors.generate_message(attribute, key, suggestion: suggestion, raise: true)
+        raise TypeError, "it resolved to #{text.class}, not a String" unless text.is_a?(String)
+
+        text
+      rescue StandardError => e
+        config.default_lookalike_message(suggestion, e) # logs it
+        nil
+      end
+
       def reject(record, attribute, message)
         record.errors.add(attribute, message)
         nil

data/lib/nondisposable/known_typos.rb

@@ -17,6 +17,14 @@ module Nondisposable
   # test/fixtures/lookalike_corpus.csv, and the test suite fails if an entry
   # loses it. Nothing generates this list automatically; see the file's header
   # for the bar an entry has to clear.
+  #
+  # Upstream blocklists list some of these too: the bundled snapshot has
+  # `gmial.com`, `hotmai.com` and `hotmial.com`. That is left alone on purpose: both lists say "refuse it", and dropping the typos from
+  # the stored list would let them through for every host that never switched
+  # the lookalike layer on, and for every Nondisposable.disposable? caller.
+  # What the overlap must not change is the MESSAGE, and the validator settles
+  # that by asking this list before the throwaway check (see
+  # NondisposableValidator), whatever the daily update brings in.
   module KnownTypos
     LIST_PATH = File.expand_path('../../data/known_typo_domains.txt', __dir__)
 

data/lib/nondisposable/version.rb

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

data/lib/nondisposable.rb

@@ -70,6 +70,7 @@ module Nondisposable
   class Configuration
     ON_CHECK_FAILURE_MODES = [:allow, :reject].freeze
     LOOKALIKE_MODES = [false, true, :confirmable].freeze
+    DEFAULT_LOOKALIKE_ERROR_MESSAGE = "looks like a typo. Did you mean %{suggestion}?"
 
     attr_accessor :error_message, :additional_domains, :excluded_domains
     # Whether to also match parent domains: with the default true, an email at
@@ -154,8 +155,22 @@ module Nondisposable
     # ---- 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
+
+    # "Did you mean …?", in one of three forms:
+    #
+    #   "looks like a typo. Did you mean %{suggestion}?"   a String (default)
+    #   :email_lookalike                                   a Rails error name
+    #   ->(suggestion) { "…#{suggestion}…" }               a callable
+    #
+    # %{suggestion} is the full corrected address (or the corrected domain,
+    # for a value with nothing before the "@").
+    #
+    # A Symbol means what it means for error_message and the TLD messages: a
+    # Rails error name, looked up through ActiveModel's chain
+    # (activerecord.errors.models.user.attributes.email.email_lookalike, …,
+    # errors.messages.email_lookalike), with %{suggestion} as well as
+    # %{attribute} and %{value} to interpolate.
+    attr_reader :lookalike_error_message
 
     def initialize
       @error_message = "provider is not allowed"
@@ -179,7 +194,79 @@ module Nondisposable
 
       @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}?"
+      @lookalike_error_message = DEFAULT_LOOKALIKE_ERROR_MESSAGE
+    end
+
+    # `:lookalike_domain` is the TYPE of the confirmable error — the one a form
+    # offers "yes, this is right" for (errors.of_kind?(:email, :lookalike_domain)).
+    # As the name of the hard error too it would put that checkbox next to a
+    # refusal no confirmation can lift, so it fails at boot instead.
+    def lookalike_error_message=(message)
+      if message == :lookalike_domain
+        raise ArgumentError, "lookalike_error_message cannot be :lookalike_domain, the type of the confirmable error: " \
+                             "name the translation anything else (e.g. :email_lookalike)"
+      end
+
+      @lookalike_error_message = message
+    end
+
+    # The lookalike error for this suggestion as a String, resolved NOW, at
+    # validation time, so it answers in the locale of the request being
+    # validated rather than whichever locale the initializer ran in.
+    #
+    # - A Symbol: outside a model there is no ActiveModel chain to walk, so
+    #   this looks up its last link, errors.messages.<name>. (The validator
+    #   adds a Symbol through errors.add instead, so a per-model or
+    #   per-attribute translation wins there.)
+    # - Anything that responds to #call is called with the suggestion.
+    # - Anything else is treated as before 0.6.2: `%{suggestion}` replaced
+    #   with #sub. That keeps a String exactly as it was, and keeps working
+    #   any object a host passed that answers #sub (the only way to localise
+    #   this message until now). A String is substituted with the block
+    #   form, so a `\0` or `\&` typed in the local part is printed, not read
+    #   as a back-reference.
+    #
+    # NEVER RAISES. By the time we phrase this message the address is already
+    # refused; the only open question is the wording. A missing translation,
+    # one naming a variable we don't pass (`%{address}`), a key naming a whole
+    # translation group (a Hash), a nil message, or a callable that raises or
+    # takes no argument would otherwise reach the validator's rescue, where
+    # the default on_check_failure = :allow ACCEPTS the address — a listed
+    # typo let through by a broken locale file. So any failure, or anything
+    # that is not a String, falls back to the default English message, logged
+    # so the host can fix it.
+    def lookalike_message(suggestion)
+      message = lookalike_error_message
+      text =
+        if message.is_a?(Symbol)
+          I18n.t(:"errors.messages.#{message}", suggestion: suggestion, raise: true)
+        elsif message.respond_to?(:call)
+          message.call(suggestion)
+        elsif message.is_a?(String)
+          message.sub('%{suggestion}') { suggestion }
+        else
+          message.sub('%{suggestion}', suggestion) # a host's own object, called exactly as before 0.6.2
+        end
+      raise TypeError, "it resolved to #{text.class}, not a String" unless text.is_a?(String)
+
+      text
+    rescue StandardError => e
+      default_lookalike_message(suggestion, e)
+    end
+
+    # The gem's own English message, for when the host's cannot be used.
+    # Given the error that made it necessary, logs it.
+    def default_lookalike_message(suggestion, error = nil)
+      if error
+        log_message = "[nondisposable] Could not use lookalike_error_message #{lookalike_error_message.inspect} " \
+                      "(#{error.class}: #{error.message}); using the default message, the address is still refused."
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.error(log_message)
+        else
+          warn log_message
+        end
+      end
+      DEFAULT_LOOKALIKE_ERROR_MESSAGE.sub('%{suggestion}') { suggestion.to_s }
     end
 
     # What the validator does when the disposable check itself raises

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nondisposable
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - rameerez