Raise EmailUndeliverableError for special use domain names and their subdomains, except @test when a new test_environment argument is passed

Some of the domain names used in tests had to be revised because they went from valid to invalid, or the exception message changed.

Author: JoshData

README.md

@@ -135,6 +135,7 @@ shown):
 
 `dns_resolver=None`: Pass an instance of [dns.resolver.Resolver](https://dnspython.readthedocs.io/en/latest/resolver-class.html) to control the DNS resolver including setting a timeout and [a cache](https://dnspython.readthedocs.io/en/latest/resolver-caching.html). The `caching_resolver` function shown above is a helper function to construct a dns.resolver.Resolver with a [LRUCache](https://dnspython.readthedocs.io/en/latest/resolver-caching.html#dns.resolver.LRUCache). Reuse the same resolver instance across calls to `validate_email` to make use of the cache.
 
+In non-production test environments, you may want to allow `@test` or `@mycompany.test` email addresses to be used as placeholder email addresses, which would normally not be permitted. In that case, pass `test_environment=True`. DNS-based deliverability checks will be disabled as well. Other [Special Use Domain Names](https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.xhtml) are always considered invalid and raise `EmailUndeliverableError`.
 
 Internationalized email addresses
 ---------------------------------
@@ -340,8 +341,11 @@ strictly conform to the standards. Many email address forms are obsolete
 or likely to cause trouble:
 
 * The validator assumes the email address is intended to be
-  deliverable on the public Internet using DNS, and so the domain part
+  deliverable on the public Internet. The domain part
   of the email address must be a resolvable domain name.
+  [Special Use Domain Names](https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.xhtml)
+  and their subdomains are always considered invalid (except see
+  the `test_environment` parameter above).
 * The "quoted string" form of the local part of the email address (RFC
   5321 4.1.2) is not permitted --- no one uses this anymore anyway.
   Quoted forms allow multiple @-signs, space characters, and other

email_validator/__init__.py

@@ -36,6 +36,25 @@
 LOCAL_PART_MAX_LENGTH = 64
 DOMAIN_MAX_LENGTH = 255
 
+# IANA Special Use Domain Names
+# Last Updated 2021-09-21
+# https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.txt
+# The domain names without dots would be caught by the check that the domain
+# name in an email address must have a period, but this list will also catch
+# subdomains of these domains, which are also reserved.
+SPECIAL_USE_DOMAIN_NAMES = (
+    "arpa",  # consolidated from a lot of arpa subdomains, we'll assume all subdomains of arpa are actually reserved
+    "example",
+    "example.com",
+    "example.net",
+    "example.org",
+    "invalid",
+    "local",
+    "localhost",
+    "onion",
+    "test",  # see special logic for 'test' where this is checked
+)
+
 # ease compatibility in type checking
 if sys.version_info >= (3,):
     unicode_class = str
@@ -194,6 +213,7 @@ def validate_email(
     allow_smtputf8=True,
     allow_empty_local=False,
     check_deliverability=True,
+    test_environment=False,
     timeout=DEFAULT_TIMEOUT,
     dns_resolver=None
 ):
@@ -230,7 +250,7 @@ def validate_email(
     ret.smtputf8 = local_part_info["smtputf8"]
 
     # Validate the email address's domain part syntax and get a normalized form.
-    domain_part_info = validate_email_domain_part(parts[1])
+    domain_part_info = validate_email_domain_part(parts[1], test_environment=test_environment)
     ret.domain = domain_part_info["domain"]
     ret.ascii_domain = domain_part_info["ascii_domain"]
 
@@ -280,9 +300,9 @@ def validate_email(
             reason = "(when encoded in bytes)"
         raise EmailSyntaxError("The email address is too long {}.".format(reason))
 
-    if check_deliverability:
-        # Validate the email address's deliverability and update the
-        # return dict with metadata.
+    if check_deliverability and not test_environment:
+        # Validate the email address's deliverability using DNS
+        # and update the return dict with metadata.
         deliverability_info = validate_email_deliverability(
             ret["domain"], ret["domain_i18n"], timeout, dns_resolver
         )
@@ -356,7 +376,7 @@ def validate_email_local_part(local, allow_smtputf8=True, allow_empty_local=Fals
         }
 
 
-def validate_email_domain_part(domain):
+def validate_email_domain_part(domain, test_environment=False):
     # Empty?
     if len(domain) == 0:
         raise EmailSyntaxError("There must be something after the @-sign.")
@@ -435,11 +455,33 @@ def validate_email_domain_part(domain):
         raise EmailSyntaxError("The email address contains invalid characters after the @-sign.")
 
     # All publicly deliverable addresses have domain named with at least
-    # one period. We also know that all TLDs end with a letter.
-    if "." not in ascii_domain:
+    # one period, and we'll consider the lack of a period a syntax error
+    # since that will match people's sense of what an email address looks
+    # like. We'll skip this in test environments to allow '@test' email
+    # addresses.
+    if "." not in ascii_domain and not (ascii_domain == "test" and test_environment):
         raise EmailSyntaxError("The domain name %s is not valid. It should have a period." % domain_i18n)
+
+    # Check special-use and reserved domain names. Raise these as
+    # deliverability errors since they are syntactically valid.
+    # Some might fail DNS-based deliverability checks, but that
+    # can be turned off, so we should fail them all sooner.
+    for d in SPECIAL_USE_DOMAIN_NAMES:
+        # RFC 6761 says that applications should not block use of the 'test'
+        # domain name, presumably because that would prevent it from being
+        # used for actual testing. We'll block it, except when a special
+        # testing flag is used, indicating that the module is being used
+        # in a test environment.
+        if d == "test" and test_environment:
+            continue
+
+        if ascii_domain == d or ascii_domain.endswith("." + d):
+            raise EmailUndeliverableError("The domain name %s is a special-use or reserved name that cannot be used with email." % domain_i18n)
+
+    # We also know that all TLDs currently end with a letter, and
+    # we'll consider that a non-DNS based deliverability check.
     if not re.search(r"[A-Za-z]\Z", ascii_domain):
-        raise EmailSyntaxError(
+        raise EmailUndeliverableError(
             "The domain name %s is not valid. It is not within a valid top-level domain." % domain_i18n
         )
 

tests/test_main.py

@@ -12,51 +12,51 @@
     'email_input,output',
     [
         (
-            'Abc@example.com',
+            'Abc@example.tld',
             ValidatedEmail(
                 local_part='Abc',
                 ascii_local_part='Abc',
                 smtputf8=False,
-                ascii_domain='example.com',
-                domain='example.com',
-                email='Abc@example.com',
-                ascii_email='Abc@example.com',
+                ascii_domain='example.tld',
+                domain='example.tld',
+                email='Abc@example.tld',
+                ascii_email='Abc@example.tld',
             ),
         ),
         (
-            'Abc.123@example.com',
+            'Abc.123@test-example.com',
             ValidatedEmail(
                 local_part='Abc.123',
                 ascii_local_part='Abc.123',
                 smtputf8=False,
-                ascii_domain='example.com',
-                domain='example.com',
-                email='Abc.123@example.com',
-                ascii_email='Abc.123@example.com',
+                ascii_domain='test-example.com',
+                domain='test-example.com',
+                email='Abc.123@test-example.com',
+                ascii_email='Abc.123@test-example.com',
             ),
         ),
         (
-            'user+mailbox/department=shipping@example.com',
+            'user+mailbox/department=shipping@example.tld',
             ValidatedEmail(
                 local_part='user+mailbox/department=shipping',
                 ascii_local_part='user+mailbox/department=shipping',
                 smtputf8=False,
-                ascii_domain='example.com',
-                domain='example.com',
-                email='user+mailbox/department=shipping@example.com',
-                ascii_email='user+mailbox/department=shipping@example.com',
+                ascii_domain='example.tld',
+                domain='example.tld',
+                email='user+mailbox/department=shipping@example.tld',
+                ascii_email='user+mailbox/department=shipping@example.tld',
             ),
         ),
         (
-            "!#$%&'*+-/=?^_`.{|}~@example.com",
+            "!#$%&'*+-/=?^_`.{|}~@example.tld",
             ValidatedEmail(
                 local_part="!#$%&'*+-/=?^_`.{|}~",
                 ascii_local_part="!#$%&'*+-/=?^_`.{|}~",
                 smtputf8=False,
-                ascii_domain='example.com',
-                domain='example.com',
-                email="!#$%&'*+-/=?^_`.{|}~@example.com",
-                ascii_email="!#$%&'*+-/=?^_`.{|}~@example.com",
+                ascii_domain='example.tld',
+                domain='example.tld',
+                email="!#$%&'*+-/=?^_`.{|}~@example.tld",
+                ascii_email="!#$%&'*+-/=?^_`.{|}~@example.tld",
             ),
         ),
         (
@@ -142,43 +142,43 @@
             ),
         ),
         (
-            'ñoñó@example.com',
+            'ñoñó@example.tld',
             ValidatedEmail(
                 local_part='ñoñó',
                 smtputf8=True,
-                ascii_domain='example.com',
-                domain='example.com',
-                email='ñoñó@example.com',
+                ascii_domain='example.tld',
+                domain='example.tld',
+                email='ñoñó@example.tld',
             ),
         ),
         (
-            '我買@example.com',
+            '我買@example.tld',
             ValidatedEmail(
                 local_part='我買',
                 smtputf8=True,
-                ascii_domain='example.com',
-                domain='example.com',
-                email='我買@example.com',
+                ascii_domain='example.tld',
+                domain='example.tld',
+                email='我買@example.tld',
             ),
         ),
         (
-            '甲斐黒川日本@example.com',
+            '甲斐黒川日本@example.tld',
             ValidatedEmail(
                 local_part='甲斐黒川日本',
                 smtputf8=True,
-                ascii_domain='example.com',
-                domain='example.com',
-                email='甲斐黒川日本@example.com',
+                ascii_domain='example.tld',
+                domain='example.tld',
+                email='甲斐黒川日本@example.tld',
             ),
         ),
         (
-            'чебурашкаящик-с-апельсинами.рф@example.com',
+            'чебурашкаящик-с-апельсинами.рф@example.tld',
             ValidatedEmail(
                 local_part='чебурашкаящик-с-апельсинами.рф',
                 smtputf8=True,
-                ascii_domain='example.com',
-                domain='example.com',
-                email='чебурашкаящик-с-апельсинами.рф@example.com',
+                ascii_domain='example.tld',
+                domain='example.tld',
+                email='чебурашкаящик-с-апельсинами.рф@example.tld',
             ),
         ),
         (
@@ -211,6 +211,7 @@ def test_email_valid(email_input, output):
 @pytest.mark.parametrize(
     'email_input,error_msg',
     [
+        ('my@localhost', 'The domain name localhost is not valid. It should have a period.'),
         ('my@.leadingdot.com', 'An email address cannot have a period immediately after the @-sign.'),
         ('my@．．leadingfwdot.com', 'An email address cannot have a period immediately after the @-sign.'),
         ('my@..twodots.com', 'An email address cannot have a period immediately after the @-sign.'),
@@ -247,15 +248,45 @@ def test_email_valid(email_input, output):
         ('my.λong.address@1111111111222222222233333333334444444444555555555.6666666666777777777788888888889999999999000000000.1111111111222222222233333333334444444444555555555.6666666666777777777788888888889999999999000000000.1111111111222222222233333333334444.info', 'The email address is too long (at least 1 character too many).'),
     ],
 )
-def test_email_invalid(email_input, error_msg):
+def test_email_invalid_syntax(email_input, error_msg):
+    # Since these all have syntax errors, deliverability
+    # checks do not arise.
     with pytest.raises(EmailSyntaxError) as exc_info:
         validate_email(email_input)
     # print(f'({email_input!r}, {str(exc_info.value)!r}),')
     assert str(exc_info.value) == error_msg
 
 
+@pytest.mark.parametrize(
+    'email_input',
+    [
+        ('me@anything.arpa'),
+        ('me@anything.example'),
+        ('me@example.com'),
+        ('me@mail.example.com'),
+        ('me@valid.invalid'),
+        ('me@link.local'),
+        ('me@host.localhost'),
+        ('me@onion.onion.onion'),
+        ('me@test.test.test'),
+    ],
+)
+def test_email_invalid_reserved_domain(email_input):
+    # Since these all fail deliverabiltiy from a static list,
+    # DNS deliverability checks do not arise.
+    with pytest.raises(EmailUndeliverableError) as exc_info:
+        validate_email(email_input)
+    # print(f'({email_input!r}, {str(exc_info.value)!r}),')
+    assert "is a special-use or reserved name" in str(exc_info.value)
+
+
+def test_email_test_domain_name_in_test_environment():
+    validate_email("anything@test", test_environment=True)
+    validate_email("anything@mycompany.test", test_environment=True)
+
+
 def test_dict_accessor():
-    input_email = "testaddr@example.com"
+    input_email = "testaddr@example.tld"
     valid_email = validate_email(input_email, check_deliverability=False)
     assert isinstance(valid_email.as_dict(), dict)
     assert valid_email.as_dict()["original_email"] == input_email
@@ -292,7 +323,7 @@ def test_deliverability_dns_timeout():
 
 def test_main_single_good_input(monkeypatch, capsys):
     import json
-    test_email = "test@example.com"
+    test_email = "google@google.com"
     monkeypatch.setattr('sys.argv', ['email_validator', test_email])
     validator_main()
     stdout, _ = capsys.readouterr()
@@ -311,7 +342,7 @@ def test_main_single_bad_input(monkeypatch, capsys):
 
 def test_main_multi_input(monkeypatch, capsys):
     import io
-    test_cases = ["test@example.com", "test2@example.com", "test@.com", "test3@.com"]
+    test_cases = ["google1@google.com", "google2@google.com", "test@.com", "test3@.com"]
     test_input = io.StringIO("\n".join(test_cases))
     monkeypatch.setattr('sys.stdin', test_input)
     monkeypatch.setattr('sys.argv', ['email_validator'])
@@ -326,7 +357,7 @@ def test_main_multi_input(monkeypatch, capsys):
 def test_main_input_shim(monkeypatch, capsys):
     import json
     monkeypatch.setattr('sys.version_info', (2, 7))
-    test_email = b"test@example.com"
+    test_email = b"google@google.com"
     monkeypatch.setattr('sys.argv', ['email_validator', test_email])
     validator_main()
     stdout, _ = capsys.readouterr()