truemail 2.3.3 → 2.4.3

data/README.md

@@ -10,7 +10,7 @@
 [![GitHub](https://img.shields.io/github/license/truemail-rb/truemail)](LICENSE.txt)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
 
-Configurable framework agnostic plain Ruby email validator. Verify email via Regex, DNS and SMTP. Be sure that email address valid and exists.
+Configurable framework agnostic plain Ruby email validator. Verify email via Regex, DNS, SMTP and even more. Be sure that email address valid and exists.
 
 > Actual and maintainable documentation :books: for developers is living [here](https://truemail-rb.org/truemail-gem).
 
@@ -39,6 +39,7 @@ Configurable framework agnostic plain Ruby email validator. Verify email via Reg
     - [DNS (MX) validation](#mx-validation)
       - [RFC MX lookup flow](#rfc-mx-lookup-flow)
       - [Not RFC MX lookup flow](#not-rfc-mx-lookup-flow)
+    - [MX blacklist validation](#mx-blacklist-validation)
     - [SMTP validation](#smtp-validation)
       - [SMTP fail fast enabled](#smtp-fail-fast-enabled)
       - [SMTP safe check disabled](#smtp-safe-check-disabled)
@@ -80,10 +81,11 @@ Also Truemail gem allows performing an audit of the host in which runs.
 ## Features
 
 - Configurable validator, validate only what you need
-- Minimal runtime dependencies
+- Only one runtime dependency
 - Supporting of internationalized emails ([EAI](https://en.wikipedia.org/wiki/Email_address#Internationalization))
 - Whitelist/blacklist validation layers
 - Ability to configure different MX/SMTP validation flows
+- Ability to configure [DEA](https://en.wikipedia.org/wiki/Disposable_email_address) validation flow
 - Simple SMTP debugger
 - Event logger
 - Host auditor tools (helps to detect common host problems interfering to proper email verification)
@@ -132,6 +134,7 @@ You can use global gem configuration or custom independent configuration. Availa
 - whitelisted domains
 - whitelist validation
 - blacklisted domains
+- blacklisted mx ip-addresses
 - custom DNS gateway(s)
 - RFC MX lookup flow
 - SMTP fail fast
@@ -175,11 +178,12 @@ Truemail.configure do |config|
 
   # Optional parameter. You can predefine default validation type for
   # Truemail.validate('email@email.com') call without with-parameter
-  # Available validation types: :regex, :mx, :smtp
+  # Available validation types: :regex, :mx, :mx_blacklist, :smtp
   config.default_validation_type = :mx
 
   # Optional parameter. You can predefine which type of validation will be used for domains.
-  # Also you can skip validation by domain. Available validation types: :regex, :mx, :smtp
+  # Also you can skip validation by domain.
+  # Available validation types: :regex, :mx, :mx_blacklist, :smtp
   # This configuration will be used over current or default validation type parameter
   # All of validations for 'somedomain.com' will be processed with regex validation only.
   # And all of validations for 'otherdomain.com' will be processed with mx validation only.
@@ -189,7 +193,7 @@ Truemail.configure do |config|
   # Optional parameter. Validation of email which contains whitelisted domain always will
   # return true. Other validations will not processed even if it was defined in validation_type_for
   # It is equal to empty array by default.
-  config.whitelisted_domains = ['somedomain1.com', 'somedomain2.com']
+  config.whitelisted_domains = %w[somedomain1.com somedomain2.com]
 
   # Optional parameter. With this option Truemail will validate email which contains whitelisted
   # domain only, i.e. if domain whitelisted, validation will passed to Regex, MX or SMTP validators.
@@ -200,13 +204,18 @@ Truemail.configure do |config|
   # Optional parameter. Validation of email which contains blacklisted domain always will
   # return false. Other validations will not processed even if it was defined in validation_type_for
   # It is equal to empty array by default.
-  config.blacklisted_domains = ['somedomain1.com', 'somedomain2.com']
+  config.blacklisted_domains = %w[somedomain3.com somedomain4.com]
+
+  # Optional parameter. With this option Truemail will filter out unwanted mx servers via
+  # predefined list of ip addresses. It can be used as a part of DEA (disposable email
+  # address) validations. It is equal to empty array by default.
+  config.blacklisted_mx_ip_addresses = %w[1.1.1.1 2.2.2.2]
 
   # Optional parameter. This option will provide to use custom DNS gateway when Truemail
-  # interacts with DNS. If you won't specify nameserver's ports Truemail will use default
-  # DNS TCP/UDP port 53. By default Truemail uses DNS gateway from system settings
-  # and this option is equal to empty array.
-  config.dns = ['10.0.0.1', '10.0.0.2:54']
+  # interacts with DNS. Valid port numbers are in the range 1-65535. If you won't specify
+  # nameserver's ports Truemail will use default DNS TCP/UDP port 53. By default Truemail
+  # uses DNS gateway from system settings and this option is equal to empty array.
+  config.dns = %w[10.0.0.1 10.0.0.2:54]
 
   # Optional parameter. This option will provide to use not RFC MX lookup flow.
   # It means that MX and Null MX records will be cheked on the DNS validation layer only.
@@ -214,7 +223,7 @@ Truemail.configure do |config|
   config.not_rfc_mx_lookup_flow = true
 
   # Optional parameter. This option will provide to use smtp fail fast behaviour. When
-  # smtp_fail_fast = true it means that truemail ends smtp validation session after first
+  # smtp_fail_fast = true it means that Truemail ends smtp validation session after first
   # attempt on the first mx server in any fail cases (network connection/timeout error,
   # smtp validation error). This feature helps to reduce total time of SMTP validation
   # session up to 1 second. By default this option is disabled.
@@ -245,11 +254,13 @@ Truemail.configuration
  @smtp_error_body_pattern=/regex_pattern/,
  @response_timeout=1,
  @connection_attempts=3,
- @validation_type_by_domain={},
- @whitelisted_domains=[],
+ @default_validation_type=:mx,
+ @validation_type_by_domain={"somedomain.com" => :regex, "otherdomain.com" => :mx},
+ @whitelisted_domains=["somedomain1.com", "somedomain2.com"],
  @whitelist_validation=true,
- @blacklisted_domains=[],
- @dns=[],
+ @blacklisted_domains=["somedomain3.com", "somedomain4.com"],
+ @blacklisted_mx_ip_addresses=["1.1.1.1", "2.2.2.2"],
+ @dns=["10.0.0.1", "10.0.0.2:54"],
  @verifier_domain="somedomain.com",
  @verifier_email="verifier@example.com",
  @not_rfc_mx_lookup_flow=true,
@@ -276,11 +287,13 @@ Truemail.configuration
  @smtp_error_body_pattern=/regex_pattern/,
  @response_timeout=4,
  @connection_attempts=1,
- @validation_type_by_domain={},
- @whitelisted_domains=[],
+ @default_validation_type=:mx,
+ @validation_type_by_domain={"somedomain.com" => :regex, "otherdomain.com" => :mx},
+ @whitelisted_domains=["somedomain1.com", "somedomain2.com"],
  @whitelist_validation=true,
- @blacklisted_domains=[],
- @dns=[],
+ @blacklisted_domains=["somedomain3.com", "somedomain4.com"],
+ @blacklisted_mx_ip_addresses=["1.1.1.1", "2.2.2.2"],
+ @dns=["10.0.0.1", "10.0.0.2:54"],
  @verifier_domain="somedomain.com",
  @verifier_email="verifier@example.com",
  @not_rfc_mx_lookup_flow=true,
@@ -338,8 +351,8 @@ require 'truemail'
 
 Truemail.configure do |config|
   config.verifier_email = 'verifier@example.com'
-  config.whitelisted_domains = ['white-domain.com', 'somedomain.com']
-  config.blacklisted_domains = ['black-domain.com', 'somedomain.com']
+  config.whitelisted_domains = %w[white-domain.com somedomain.com]
+  config.blacklisted_domains = %w[black-domain.com somedomain.com]
   config.validation_type_for = { 'somedomain.com' => :mx }
 end
 ```
@@ -361,6 +374,7 @@ Truemail.validate('email@white-domain.com')
     smtp_debug=nil>,
     configuration=#<Truemail::Configuration:0x00005629f801bd28
      @blacklisted_domains=["black-domain.com", "somedomain.com"],
+     @blacklisted_mx_ip_addresses=[],
      @dns=[],
      @connection_attempts=2,
      @connection_timeout=2,
@@ -386,7 +400,7 @@ require 'truemail'
 
 Truemail.configure do |config|
   config.verifier_email = 'verifier@example.com'
-  config.whitelisted_domains = ['white-domain.com']
+  config.whitelisted_domains = %w[white-domain.com]
   config.whitelist_validation = true
 end
 ```
@@ -409,6 +423,7 @@ Truemail.validate('email@white-domain.com', with: :regex)
     configuration=
     #<Truemail::Configuration:0x0000563f0d2605c8
      @blacklisted_domains=[],
+     @blacklisted_mx_ip_addresses=[],
      @dns=[],
      @connection_attempts=2,
      @connection_timeout=2,
@@ -443,6 +458,7 @@ Truemail.validate('email@domain.com', with: :regex)
     configuration=
     #<Truemail::Configuration:0x0000563f0cd82ab0
      @blacklisted_domains=[],
+     @blacklisted_mx_ip_addresses=[],
      @dns=[],
      @connection_attempts=2,
      @connection_timeout=2,
@@ -463,7 +479,7 @@ Truemail.validate('email@domain.com', with: :regex)
 
 ##### Blacklist case
 
-When email in blacklist, validation type will be redefined too. Validation result returns ```false```
+When email in blacklist, validation type will be redefined too. Validation result returns `false`.
 
 ```ruby
 Truemail.validate('email@black-domain.com')
@@ -479,6 +495,7 @@ Truemail.validate('email@black-domain.com')
     configuration=
     #<Truemail::Configuration:0x0000563f0d36f4f0
      @blacklisted_domains=[],
+     @blacklisted_mx_ip_addresses=[],
      @dns=[],
      @connection_attempts=2,
      @connection_timeout=2,
@@ -515,6 +532,7 @@ Truemail.validate('email@somedomain.com')
     configuration=
     #<Truemail::Configuration:0x0000563f0d3f8fc0
      @blacklisted_domains=[],
+     @blacklisted_mx_ip_addresses=[],
      @dns=[],
      @connection_attempts=2,
      @connection_timeout=2,
@@ -559,7 +577,8 @@ Truemail.validate('email@example.com', with: :regex)
 => #<Truemail::Validator:0x000055590cc9bdb8
   @result=
     #<struct Truemail::Validator::Result
-      success=true, email="email@example.com",
+      success=true,
+      email="email@example.com",
       domain=nil,
       mail_servers=[],
       errors={},
@@ -567,6 +586,7 @@ Truemail.validate('email@example.com', with: :regex)
       configuration=
       #<Truemail::Configuration:0x000055aa56a54d48
        @blacklisted_domains=[],
+       @blacklisted_mx_ip_addresses=[],
        @dns=[],
        @connection_attempts=2,
        @connection_timeout=2,
@@ -611,6 +631,7 @@ Truemail.validate('email@example.com', with: :regex)
       configuration=
       #<Truemail::Configuration:0x0000560e58d80830
        @blacklisted_domains=[],
+       @blacklisted_mx_ip_addresses=[],
        @dns=[],
        @connection_attempts=2,
        @connection_timeout=2,
@@ -666,6 +687,7 @@ Truemail.validate('email@example.com', with: :mx)
       configuration=
       #<Truemail::Configuration:0x0000559b6e44af70
        @blacklisted_domains=[],
+       @blacklisted_mx_ip_addresses=[],
        @dns=[],
        @connection_attempts=2,
        @connection_timeout=2,
@@ -712,6 +734,7 @@ Truemail.validate('email@example.com', with: :mx)
       configuration=
       #<Truemail::Configuration:0x0000559b6e44af70
        @blacklisted_domains=[],
+       @blacklisted_mx_ip_addresses=[],
        @dns=[],
        @connection_attempts=2,
        @connection_timeout=2,
@@ -730,12 +753,63 @@ Truemail.validate('email@example.com', with: :mx)
   @validation_type=:mx>
 ```
 
+#### MX blacklist validation
+
+MX blacklist validation is the third validation level. This layer provides checking extracted mail server(s) IP address from MX validation with predefined blacklisted IP addresses list. It can be used as a part of DEA ([disposable email address](https://en.wikipedia.org/wiki/Disposable_email_address)) validations.
+
+```code
+[Whitelist/Blacklist] -> [Regex validation] -> [MX validation] -> [MX blacklist validation]
+```
+
+Example of usage:
+
+```ruby
+require 'truemail'
+
+Truemail.configure do |config|
+  config.verifier_email = 'verifier@example.com'
+  config.blacklisted_mx_ip_addresses = %w[127.0.1.2]
+end
+
+Truemail.validate('email@example.com', with: :mx_blacklist)
+
+=> #<Truemail::Validator:0x00007fca0c8aea70
+ @result=
+  #<struct Truemail::Validator::Result
+   success=false,
+   email="email@example.com",
+   domain="example.com",
+   mail_servers=["127.0.1.1", "127.0.1.2"],
+   errors={:mx_blacklist=>"blacklisted mx server ip address"},
+   smtp_debug=nil,
+   configuration=
+    #<Truemail::Configuration:0x00007fca0c8aeb38
+     @blacklisted_domains=[],
+     @blacklisted_mx_ip_addresses=["127.0.1.2"],
+     @connection_attempts=2,
+     @connection_timeout=2,
+     @default_validation_type=:smtp,
+     @dns=[],
+     @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-.+]*)@((?i-mx:[\p{L}0-9]+([\-.]{1}[\p{L}0-9]+)*\.\p{L}{2,63}))\z)/,
+     @not_rfc_mx_lookup_flow=false,
+     @response_timeout=2,
+     @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+     @smtp_fail_fast=false,
+     @smtp_safe_check=false,
+     @validation_type_by_domain={},
+     @verifier_domain="example.com",
+     @verifier_email="verifier@example.com",
+     @whitelist_validation=false,
+     @whitelisted_domains=[]>>,
+ @validation_type=:mx_blacklist>
+```
+
 #### SMTP validation
 
-SMTP validation is a final, third validation level. This type of validation tries to check real existence of email account on a current email server. This validation runs a chain of previous validations and if they're complete successfully then runs itself.
+SMTP validation is a final, fourth validation level. This type of validation tries to check real existence of email account on a current email server. This validation runs a chain of previous validations and if they're complete successfully then runs itself.
 
 ```code
-[Whitelist/Blacklist] -> [Regex validation] -> [MX validation] -> [SMTP validation]
+[Whitelist/Blacklist] -> [Regex validation] -> [MX validation] -> [MX blacklist validation] -> [SMTP validation]
 ```
 
 If total count of MX servers is equal to one, `Truemail::Smtp` validator will use value from `Truemail.configuration.connection_attempts` as connection attempts. By default it's equal `2`.
@@ -787,6 +861,7 @@ Truemail.validate('email@example.com')
         configuration=
           #<Truemail::Configuration:0x00007fdc4504f5c8
             @blacklisted_domains=[],
+            @blacklisted_mx_ip_addresses=[],
             @dns=[],
             @connection_attempts=2,
             @connection_timeout=2,
@@ -831,6 +906,7 @@ Truemail.validate('email@example.com')
       configuration=
       #<Truemail::Configuration:0x00005615e87b9298
        @blacklisted_domains=[],
+       @blacklisted_mx_ip_addresses=[],
        @dns=[],
        @connection_attempts=2,
        @connection_timeout=2,
@@ -882,6 +958,7 @@ Truemail.validate('email@example.com')
           configuration=
             #<Truemail::Configuration:0x00005615e87b9298
              @blacklisted_domains=[],
+             @blacklisted_mx_ip_addresses=[],
              @dns=[],
              @connection_attempts=2,
              @connection_timeout=2,
@@ -945,6 +1022,7 @@ Truemail.validate('email@example.com')
         configuration=
             #<Truemail::Configuration:0x00005615e87b9298
              @blacklisted_domains=[],
+             @blacklisted_mx_ip_addresses=[],
              @dns=[],
              @connection_attempts=2,
              @connection_timeout=2,
@@ -993,6 +1071,7 @@ Truemail.validate('email@example.com')
       configuration=
             #<Truemail::Configuration:0x00005615e87b9298
              @blacklisted_domains=[],
+             @blacklisted_mx_ip_addresses=[],
              @dns=[],
              @connection_attempts=2,
              @connection_timeout=2,
@@ -1042,6 +1121,7 @@ Truemail.host_audit
        configuration=
         #<Truemail::Configuration:0x00005615e86327a8
          @blacklisted_domains=[],
+         @blacklisted_mx_ip_addresses=[],
          @dns=[],
          @connection_attempts=2,
          @connection_timeout=2,
@@ -1070,6 +1150,7 @@ Truemail.host_audit
        configuration=
         #<Truemail::Configuration:0x00005615e86327a8
          @blacklisted_domains=[],
+         @blacklisted_mx_ip_addresses=[],
          @dns=[],
          @connection_attempts=2,
          @connection_timeout=2,
@@ -1123,6 +1204,7 @@ Truemail::Log::Serializer::AuditorJson.call(Truemail.host_audit)
   },
  "configuration": {
     "blacklisted_domains": null,
+    "blacklisted_mx_ip_addresses": null,
     "dns": null,
     "email_pattern": "default gem value",
     "not_rfc_mx_lookup_flow": false,
@@ -1163,6 +1245,7 @@ Truemail::Log::Serializer::ValidatorJson.call(Truemail.validate('nonexistent_ema
   ],
   "configuration": {
     "blacklisted_domains": null,
+    "blacklisted_mx_ip_addresses": null,
     "dns": null,
     "email_pattern": "default gem value",
     "not_rfc_mx_lookup_flow": false,
@@ -1205,6 +1288,7 @@ Truemail.host_audit.as_json
   },
  "configuration": {
     "blacklisted_domains": null,
+    "blacklisted_mx_ip_addresses": null,
     "dns": null,
     "email_pattern": "default gem value",
     "not_rfc_mx_lookup_flow": false,
@@ -1242,6 +1326,7 @@ Truemail.validate('nonexistent_email@bestweb.com.ua').as_json
   ],
   "configuration": {
     "blacklisted_domains": null,
+    "blacklisted_mx_ip_addresses": null,
     "dns": null,
     "email_pattern": "default gem value",
     "not_rfc_mx_lookup_flow": false,

data/lib/truemail/configuration.rb

@@ -15,13 +15,14 @@ module Truemail
       connection_attempts
       whitelisted_domains
       blacklisted_domains
+      blacklisted_mx_ip_addresses
+      dns
     ].freeze
 
     attr_reader :verifier_email,
                 :verifier_domain,
                 :default_validation_type,
                 :validation_type_by_domain,
-                :dns,
                 :logger,
                 *Truemail::Configuration::SETTERS
 
@@ -55,9 +56,9 @@ module Truemail
       validation_type_by_domain.merge!(settings)
     end
 
-    def argument_consistent?(argument)
+    def argument_consistent?(method, argument)
       case argument
-      when ::Array then check_domain_list(argument)
+      when ::Array then items_match_regex?(argument, regex_by_method(method))
       when ::Integer then argument.positive?
       when ::Regexp then true
       end
@@ -65,16 +66,11 @@ module Truemail
 
     Truemail::Configuration::SETTERS.each do |method|
       define_method("#{method}=") do |argument|
-        raise_unless(argument, __method__, argument_consistent?(argument))
+        raise_unless(argument, __method__, argument_consistent?(method, argument))
         instance_variable_set(:"@#{method}", argument)
       end
     end
 
-    def dns=(argument)
-      raise_unless(argument, __method__, argument.is_a?(::Array) && check_dns_settings(argument))
-      @dns = argument
-    end
-
     def logger=(options)
       tracking_event, stdout, log_absolute_path = logger_options(options)
       valid_event = Truemail::Log::Event::TRACKING_EVENTS.key?(tracking_event)
@@ -104,6 +100,7 @@ module Truemail
         whitelisted_domains: [],
         whitelist_validation: false,
         blacklisted_domains: [],
+        blacklisted_mx_ip_addresses: [],
         dns: [],
         not_rfc_mx_lookup_flow: false,
         smtp_fail_fast: false,
@@ -115,25 +112,27 @@ module Truemail
       raise Truemail::ArgumentError.new(argument_context, argument_name) unless condition
     end
 
+    def match_regex?(regex_pattern, object)
+      regex_pattern.match?(object.to_s)
+    end
+
     def validate_arguments(argument, method)
-      constant = Truemail::RegexConstant.const_get("regex_#{method[/\A.+_(.+)=\z/, 1]}_pattern".upcase)
-      raise_unless(argument, method, constant.match?(argument.to_s))
+      regex_pattern = Truemail::RegexConstant.const_get("regex_#{method[/\A.+_(.+)=\z/, 1]}_pattern".upcase)
+      raise_unless(argument, method, match_regex?(regex_pattern, argument))
     end
 
     def default_verifier_domain
       self.verifier_domain ||= verifier_email[Truemail::RegexConstant::REGEX_EMAIL_PATTERN, 3]
     end
 
-    def domain_matcher
-      ->(domain) { Truemail::RegexConstant::REGEX_DOMAIN_PATTERN.match?(domain.to_s) }
+    def regex_by_method(method)
+      return Truemail::RegexConstant::REGEX_IP_ADDRESS_PATTERN if method.eql?(:blacklisted_mx_ip_addresses)
+      return Truemail::RegexConstant::REGEX_DNS_SERVER_ADDRESS_PATTERN if method.eql?(:dns)
+      Truemail::RegexConstant::REGEX_DOMAIN_PATTERN
     end
 
-    def check_domain(domain)
-      raise_unless(domain, 'domain', domain_matcher.call(domain))
-    end
-
-    def check_domain_list(domains)
-      domains.all?(&domain_matcher)
+    def items_match_regex?(items, regex_pattern)
+      items.all? { |item| match_regex?(regex_pattern, item) }
     end
 
     def check_validation_type(validation_type)
@@ -143,15 +142,11 @@ module Truemail
     def validate_validation_type(settings)
       raise_unless(settings, 'hash with settings', settings.is_a?(::Hash))
       settings.each do |domain, validation_type|
-        check_domain(domain)
+        raise_unless(domain, 'domain', match_regex?(Truemail::RegexConstant::REGEX_DOMAIN_PATTERN, domain))
         check_validation_type(validation_type)
       end
     end
 
-    def check_dns_settings(dns_servers)
-      dns_servers.all? { |dns_server| Truemail::RegexConstant::REGEX_DNS_SERVER_ADDRESS_PATTERN.match?(dns_server.to_s) }
-    end
-
     def logger_options(current_options)
       Truemail::Configuration::DEFAULT_LOGGER_OPTIONS.merge(current_options).values
     end