email_address 0.1.2 → 0.2.0

data/lib/email_address/active_record_validator.rb

@@ -1,5 +1,6 @@
-module EmailAddress
+# frozen_string_literal: true
 
+module EmailAddress
   # ActiveRecord validator class for validating an email
   # address with this library.
   # Note the initialization happens once per process.
@@ -14,14 +15,13 @@ module EmailAddress
   # Default field: :email or :email_address (first found)
   #
   class ActiveRecordValidator < ActiveModel::Validator
-
-    def initialize(options={})
+    def initialize(options = {})
       @opt = options
     end
 
     def validate(r)
       if @opt[:fields]
-        @opt[:fields].each {|f| validate_email(r, f) }
+        @opt[:fields].each { |f| validate_email(r, f) }
       elsif @opt[:field]
         validate_email(r, @opt[:field])
       elsif r.respond_to? :email
@@ -31,16 +31,15 @@ module EmailAddress
       end
     end
 
-    def validate_email(r,f)
+    def validate_email(r, f)
       return if r[f].nil?
-      e = EmailAddress.new(r[f])
+      e = Address.new(r[f])
       unless e.valid?
-        r.errors[f] << (@opt[:message] ||
-                       EmailAddress::Config.error_messages[:invalid_address] ||
-                       "Invalid Email Address")
+        error_message = @opt[:message] ||
+          Config.error_message(:invalid_address, I18n.locale.to_s) ||
+          "Invalid Email Address"
+        r.errors.add(f, error_message)
       end
     end
-
   end
-
 end

data/lib/email_address/address.rb

@@ -1,35 +1,48 @@
-require 'digest/sha1'
-require 'digest/md5'
+# frozen_string_literal: true
+
+require "digest/sha1"
+require "digest/sha2"
+require "digest/md5"
 
 module EmailAddress
   # Implements the Email Address container, which hold the Local
-  # (EmailAddress::Local) and Host (Email::AddressHost) parts.
+  # (EmailAddress::Local) and Host (EmailAddress::Host) parts.
   class Address
     include Comparable
-    attr_accessor :original, :local, :host, :config
+    include Rewriter
+
+    attr_accessor :original, :local, :host, :config, :reason, :locale
 
-    CONVENTIONAL_REGEX = /\A#{::EmailAddress::Local::CONVENTIONAL_MAILBOX_WITHIN}
-                           @#{::EmailAddress::Host::DNS_HOST_REGEX}\z/x
-    STANDARD_REGEX     = /\A#{::EmailAddress::Local::STANDARD_LOCAL_WITHIN}
-                           @#{::EmailAddress::Host::DNS_HOST_REGEX}\z/x
-    RELAXED_REGEX      = /\A#{::EmailAddress::Local::RELAXED_MAILBOX_WITHIN}
-                           @#{::EmailAddress::Host::DNS_HOST_REGEX}\z/x
+    CONVENTIONAL_REGEX = /\A#{Local::CONVENTIONAL_MAILBOX_WITHIN}
+                           @#{Host::DNS_HOST_REGEX}\z/x
+    STANDARD_REGEX = /\A#{Local::STANDARD_LOCAL_WITHIN}
+                           @#{Host::DNS_HOST_REGEX}\z/x
+    RELAXED_REGEX = /\A#{Local::RELAXED_MAILBOX_WITHIN}
+                           @#{Host::DNS_HOST_REGEX}\z/x
 
     # Given an email address of the form "local@hostname", this sets up the
     # instance, and initializes the address to the "normalized" format of the
     # address. The original string is available in the #original method.
-    def initialize(email_address, config={})
-      email_address  = email_address.strip if email_address
-      @original      = email_address
-      email_address||= ""
-      if lh = email_address.match(/(.+)@(.+)/)
-        (_, local, host) = lh.to_a
+    def initialize(email_address, config = {}, locale = "en")
+      @config = Config.new(config)
+      @original = email_address
+      @locale = locale
+      email_address = (email_address || "").strip
+      email_address = parse_rewritten(email_address) unless config[:skip_rewrite]
+      local, host = Address.split_local_host(email_address)
+
+      @host = Host.new(host, @config, locale)
+      @local = Local.new(local, @config, @host, locale)
+      @error = @error_message = nil
+    end
+
+    # Given an email address, this returns an array of [local, host] parts
+    def self.split_local_host(email)
+      if (lh = email.match(/(.+)@(.+)/))
+        lh.to_a[1, 2]
       else
-        (local, host)    = [email_address, '']
+        [email, ""]
       end
-      @host         = EmailAddress::Host.new(host, config)
-      @config       = @host.config
-      @local        = EmailAddress::Local.new(local, @config)
     end
 
     ############################################################################
@@ -42,26 +55,26 @@ module EmailAddress
 
     # Everything to the left of the @ in the address, called the local part.
     def left
-      self.local.to_s
+      local.to_s
     end
 
     # Returns the mailbox portion of the local port, with no tags. Usually, this
     # can be considered the user account or role account names. Some systems
     # employ dynamic email addresses which don't have the same meaning.
     def mailbox
-      self.local.mailbox
+      local.mailbox
     end
 
     # Returns the tag part of the local address, or nil if not given.
     def tag
-      self.local.tag
+      local.tag
     end
 
     # Retuns any comments parsed from the local part of the email address.
     # This is retained for inspection after construction, even if it is
     # removed from the normalized email address.
     def comment
-      self.local.comment
+      local.comment
     end
 
     ############################################################################
@@ -75,8 +88,8 @@ module EmailAddress
     def host_name
       @host.host_name
     end
-    alias :right :host_name
-    alias :hostname :host_name
+    alias_method :right, :host_name
+    alias_method :hostname, :host_name
 
     # Returns the ESP (Email Service Provider) or ISP name derived
     # using the provider configuration rules.
@@ -92,18 +105,18 @@ module EmailAddress
     def normal
       if !@original
         @original
-      elsif self.local.to_s.size == 0
+      elsif local.to_s.size == 0
         ""
-      elsif self.host.to_s.size == 0
-        self.local.to_s
+      elsif host.to_s.size == 0
+        local.to_s
       else
-        "#{self.local.to_s}@#{self.host.to_s}"
+        "#{local}@#{host}"
       end
     end
-    alias :to_s :normal
+    alias_method :to_s, :normal
 
     def inspect
-      "#<EmailAddress::Address:0x#{self.object_id.to_s(16)} address=\"#{self.to_s}\">"
+      "#<#{self.class}:0x#{object_id.to_s(16)} address=\"#{self}\">"
     end
 
     # Returns the canonical email address according to the provider
@@ -111,51 +124,60 @@ module EmailAddress
     # spaves and comments and tags, and any extraneous part of the address
     # not considered a unique account by the provider.
     def canonical
-      c = self.local.canonical
-      c += "@" + self.host.canonical if self.host.canonical && self.host.canonical > " "
+      c = local.canonical
+      c += "@" + host.canonical if host.canonical && host.canonical > " "
       c
     end
 
     # True if the given address is already in it's canonical form.
     def canonical?
-      self.canonical == self.to_s
+      canonical == to_s
+    end
+
+    # The base address is the mailbox, without tags, and host.
+    def base
+      mailbox + "@" + hostname
     end
 
     # Returns the redacted form of the address
     # This format is defined by this libaray, and may change as usage increases.
     # Takes either :sha1 (default) or :md5 as the argument
-    def redact(digest=:sha1)
-      raise "Unknown Digest type: #{digest}" unless %i(sha1 md5).include?(digest)
-      return self.to_s if self.local.redacted?
-      r = %Q({#{send(digest)}})
-      r += "@" + self.host.to_s if self.host.to_s && self.host.to_s > " "
+    def redact(digest = :sha1)
+      raise "Unknown Digest type: #{digest}" unless %i[sha1 md5].include?(digest)
+      return to_s if local.redacted?
+      r = %({#{send(digest)}})
+      r += "@" + host.to_s if host.to_s && host.to_s > " "
       r
     end
 
     # True if the address is already in the redacted state.
     def redacted?
-      self.local.redacted?
+      local.redacted?
     end
 
     # Returns the munged form of the address, by default "mailbox@domain.tld"
     # returns "ma*****@do*****".
     def munge
-      [self.local.munge, self.host.munge].join("@")
+      [local.munge, host.munge].join("@")
     end
 
-    # Returns and MD5 of the canonical address form. Some cross-system systems
+    # Returns and MD5 of the base address form. Some cross-system systems
     # use the email address MD5 instead of the actual address to refer to the
     # same shared user identity without exposing the actual address when it
     # is not known in common.
-    def reference
-      Digest::MD5.hexdigest(self.canonical)
+    def reference(form = :base)
+      Digest::MD5.hexdigest(send(form))
     end
-    alias :md5 :reference
+    alias_method :md5, :reference
 
-    # This returns the SHA1 digest (in a hex string) of the canonical email
+    # This returns the SHA1 digest (in a hex string) of the base email
     # address. See #md5 for more background.
-    def sha1
-      Digest::SHA1.hexdigest((canonical||"") + (@config[:sha1_secret]||""))
+    def sha1(form = :base)
+      Digest::SHA1.hexdigest((send(form) || "") + (@config[:sha1_secret] || ""))
+    end
+
+    def sha256(form = :base)
+      Digest::SHA256.hexdigest((send(form) || "") + (@config[:sha256_secret] || ""))
     end
 
     #---------------------------------------------------------------------------
@@ -164,42 +186,42 @@ module EmailAddress
 
     # Equal matches the normalized version of each address. Use the Threequal to check
     # for match on canonical or redacted versions of addresses
-    def ==(other_email)
-      self.to_s == other_email.to_s
+    def ==(other)
+      to_s == other.to_s
     end
-    alias :eql? :==
-    alias :equal? :==
+    alias_method :eql?, :==
+    alias_method :equal?, :==
 
     # Return the <=> or CMP comparison operator result (-1, 0, +1) on the comparison
     # of this addres with another, using the canonical or redacted forms.
     def same_as?(other_email)
       if other_email.is_a?(String)
-        other_email = EmailAddress::Address.new(other_email)
+        other_email = Address.new(other_email)
       end
 
-      self.canonical   == other_email.canonical ||
-        self.redact    == other_email.canonical ||
-        self.canonical == other_email.redact
+      canonical == other_email.canonical ||
+        redact == other_email.canonical ||
+        canonical == other_email.redact
     end
-    alias :include? :same_as?
+    alias_method :include?, :same_as?
 
     # Return the <=> or CMP comparison operator result (-1, 0, +1) on the comparison
     # of this addres with another, using the normalized form.
-    def <=>(other_email)
-      self.to_s <=> other_email.to_s
+    def <=>(other)
+      to_s <=> other.to_s
     end
 
     # Address matches one of these Matcher rule patterns
     def matches?(*rules)
       rules.flatten!
-      match   = self.local.matches?(rules)
-      match ||= self.host.matches?(rules)
+      match = local.matches?(rules)
+      match ||= host.matches?(rules)
       return match if match
 
       # Does "root@*.com" match "root@example.com" domain name
       rules.each do |r|
-        if r =~ /.+@.+/
-          return r if File.fnmatch?(r, self.to_s)
+        if /.+@.+/.match?(r)
+          return r if File.fnmatch?(r, to_s)
         end
       end
       false
@@ -211,39 +233,63 @@ module EmailAddress
 
     # Returns true if this address is considered valid according to the format
     # configured for its provider, It test the normalized form.
-    def valid?(options={})
+    def valid?(options = {})
       @error = nil
-      unless self.local.valid?
-        return set_error :invalid_mailbox
+      unless local.valid?
+        return set_error local.error
       end
-      unless self.host.valid?
-        return set_error :invalid_host
+      unless host.valid?
+        return set_error host.error_message
       end
-      if @config[:address_size] && !@config[:address_size].include?(self.to_s.size)
+      if @config[:address_size] && !@config[:address_size].include?(to_s.size)
         return set_error :exceeds_size
       end
       if @config[:address_validation].is_a?(Proc)
-        unless @config[:address_validation].call(self.to_s)
+        unless @config[:address_validation].call(to_s)
           return set_error :not_allowed
         end
       else
-        return false unless self.local.valid?
-        return false unless self.host.valid?
-      end
-      if !@config[:address_local] && !self.hostname.include?(".")
-        return set_error :incomplete_domain
+        return false unless local.valid?
+        return false unless host.valid?
       end
       true
     end
 
-    def set_error(err)
-      @error = EmailAddress::Config.error_messages[err] || err
+    # Connects to host to test if user can receive email. This should NOT be performed
+    # as an email address check, but is provided to assist in problem resolution.
+    # If you abuse this, you *could* be blocked by the ESP.
+    def connect
+      smtp = Net::SMTP.new(host_name || ip_address)
+      smtp.start(@config[:smtp_helo_name] || "localhost")
+      smtp.mailfrom @config[:smtp_mail_from] || "postmaster@localhost"
+      smtp.rcptto to_s
+      # p [:connect]
+      smtp.finish
+      true
+    rescue Net::SMTPUnknownError => e
+      set_error(:address_unknown, e.to_s)
+    rescue Net::SMTPFatalError => e
+      set_error(:address_unknown, e.to_s)
+    rescue SocketError => e
+      set_error(:address_unknown, e.to_s)
+    ensure
+      if smtp&.started?
+        smtp.finish
+      end
+      !!@error
+    end
+
+    def set_error(err, reason = nil)
+      @error = err
+      @reason = reason
+      @error_message = Config.error_message(err, locale)
       false
     end
 
+    attr_reader :error_message
+
     def error
-      self.valid? ? nil : @error
+      valid? ? nil : @error_message
     end
-
   end
 end

data/lib/email_address/canonical_email_address_type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 ################################################################################
 # ActiveRecord v5.0 Custom Type
 #
@@ -27,20 +29,22 @@
 #    user.canonical_email #=> "patsmith@gmail.com"
 ################################################################################
 
-class EmailAddress::CanonicalEmailAddressType < ActiveRecord::Type::Value
+module EmailAddress
+  class CanonicalEmailAddressType < ActiveRecord::Type::Value
 
-  # From user input, setter
-  def cast(value)
-    super(EmailAddress.canonical(value))
-  end
+    # From user input, setter
+    def cast(value)
+      super(Address.new(value).canonical)
+    end
 
-  # From a database value
-  def deserialize(value)
-    value && EmailAddress.normal(value)
-  end
+    # From a database value
+    def deserialize(value)
+      value && Address.new(value).normal
+    end
 
-  # To a database value (string)
-  def serialize(value)
-    value && EmailAddress.normal(value)
+    # To a database value (string)
+    def serialize(value)
+      value && Address.new(value).normal
+    end
   end
 end

data/lib/email_address/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module EmailAddress
   # Global configurations and for default/unknown providers. Settings are:
   #
@@ -7,11 +9,19 @@ module EmailAddress
   #   :a        - DNS A Record lookup (as some domains don't specify an MX incorrectly)
   #   :off      - Do not perform DNS lookup (Test mode, network unavailable)
   #
+  # * dns_timeout:        nil
+  #   False, or a timeout in seconds. Timeout on the DNS lookup, after which it will fail.
+  #
   # * sha1_secret         ""
   #   This application-level secret is appended to the email_address to compute
   #   the SHA1 Digest, making it unique to your application so it can't easily be
   #   discovered by comparing against a known list of email/sha1 pairs.
   #
+  # * sha256_secret         ""
+  #   This application-level secret is appended to the email_address to compute
+  #   the SHA256 Digest, making it unique to your application so it can't easily be
+  #   discovered by comparing against a known list of email/sha256 pairs.
+  #
   # For local part configuration:
   # * local_downcase:     true
   #   Downcase the local part. You probably want this for uniqueness.
@@ -68,6 +78,9 @@ module EmailAddress
   # * host_allow_ip:      false,
   #   Allow IP address format in host: [127.0.0.1], [IPv6:::1]
   #
+  # * host_local:         false,
+  #   Allow localhost, no domain, or local subdomains.
+  #
   # * address_validation: :parts, :smtp, ->(address) { true }
   #   Address validation policy
   #   :parts              Validate local and host.
@@ -77,8 +90,11 @@ module EmailAddress
   # * address_size:       3..254,
   #   A range specifying the size limit of the complete address
   #
-  # * address_local:      false,
-  #   Allow localhost, no domain, or local subdomains.
+  # * address_fqdn_domain: nil || "domain.tld"
+  #   Configure to complete the FQDN (Fully Qualified Domain Name)
+  #   When host is blank, this value is used
+  #   When host is computer name only, a dot and this is appended to get the FQDN
+  #   You probably don't want this unless you have host-local email accounts
   #
   # For provider rules to match to domain names and Exchanger hosts
   # The value is an array of match tokens.
@@ -86,64 +102,68 @@ module EmailAddress
   # * exchanger_match:    %w(google.com 127.0.0.1 10.9.8.0/24 ::1/64)
   #
 
+  require "yaml"
+
   class Config
     @config = {
-      dns_lookup:         :mx,  # :mx, :a, :off
-      sha1_secret:        "",
-      munge_string:       "*****",
-
-      local_downcase:     true,
-      local_fix:          true,
-      local_encoding:     :ascii, # :ascii, :unicode,
-      local_parse:        nil,   # nil, Proc
-      local_format:       :conventional, # :conventional, :relaxed, :redacted, :standard, Proc
-      local_size:         1..64,
-      tag_separator:      '+', # nil, character
-      mailbox_size:       1..64, # without tag
-      mailbox_canonical:  nil, # nil,  Proc
-      mailbox_validator:  nil, # nil,  Proc
-
-      host_encoding:      :punycode || :unicode,
-      host_validation:    :mx || :a || :connect,
-      host_size:          1..253,
-      host_allow_ip:      false,
+      dns_lookup: :mx, # :mx, :a, :off
+      dns_timeout: nil,
+      sha1_secret: "",
+      sha256_secret: "",
+      munge_string: "*****",
+
+      local_downcase: true,
+      local_fix: false,
+      local_encoding: :ascii, # :ascii, :unicode,
+      local_parse: nil, # nil, Proc
+      local_format: :conventional, # :conventional, :relaxed, :redacted, :standard, Proc
+      local_size: 1..64,
+      tag_separator: "+", # nil, character
+      mailbox_size: 1..64, # without tag
+      mailbox_canonical: nil, # nil,  Proc
+      mailbox_validator: nil, # nil,  Proc
+
+      host_encoding: :punycode || :unicode,
+      host_validation: :mx || :a || :connect || :syntax,
+      host_size: 1..253,
+      host_allow_ip: false,
+      host_remove_spaces: false,
+      host_local: false,
 
       address_validation: :parts, # :parts, :smtp, Proc
-      address_size:       3..254,
-      address_localhost:  false,
+      address_size: 3..254,
+      address_fqdn_domain: nil # Fully Qualified Domain Name = [host].[domain.tld]
     }
 
+    # 2018-04: AOL and Yahoo now under "oath.com", owned by Verizon. Keeping separate for now
     @providers = {
       aol: {
-        host_match:       %w(aol. compuserve. netscape. aim. cs.),
+        host_match: %w[aol. compuserve. netscape. aim. cs.]
       },
       google: {
-        host_match:       %w(gmail.com googlemail.com),
-        exchanger_match:  %w(google.com),
-        local_size:       5..64,
-        mailbox_canonical: ->(m) {m.gsub('.','')},
+        host_match: %w[gmail.com googlemail.com],
+        exchanger_match: %w[google.com googlemail.com],
+        local_size: 5..64,
+        local_private_size: 1..64, # When hostname not in host_match (private label)
+        mailbox_canonical: ->(m) { m.delete(".") }
       },
       msn: {
-        host_match:       %w(msn. hotmail. outlook. live.),
-        mailbox_validator: ->(m,t) { m =~ /\A[a-z0-9][\.\-a-z0-9]{5,29}\z/i},
+        host_match: %w[msn. hotmail. outlook. live.],
+        exchanger_match: %w[outlook.com],
+        mailbox_validator: ->(m, t) { m =~ /\A\w[\-\w]*(?:\.[\-\w]+)*\z/i }
       },
       yahoo: {
-        host_match:       %w(yahoo. ymail. rocketmail.),
-        exchanger_match:  %w(yahoodns yahoo-inc),
-      },
+        host_match: %w[yahoo. ymail. rocketmail.],
+        exchanger_match: %w[yahoodns yahoo-inc]
+      }
     }
 
-    @errors = {
-      invalid_address:    "Invalid Email Address",
-      invalid_mailbox:    "Invalid Recipient/Mailbox",
-      invalid_host:       "Invalid Host/Domain Name",
-      exceeds_size:       "Address too long",
-      not_allowed:        "Address is not allowed",
-      incomplete_domain:  "Domain name is incomplete",
-    }
+    # Loads messages: {"en"=>{"email_address"=>{"invalid_address"=>"Invalid Email Address",...}}}
+    # Rails/I18n gem: t(email_address.error, scope: "email_address")
+    @errors = YAML.load_file(File.dirname(__FILE__) + "/messages.yaml")
 
     # Set multiple default configuration settings
-    def self.configure(config={})
+    def self.configure(config = {})
       @config.merge!(config)
     end
 
@@ -154,30 +174,61 @@ module EmailAddress
     end
 
     # Returns the hash of Provider rules
-    def self.providers
-      @providers
+    class << self
+      attr_reader :providers
     end
 
     # Configure or lookup a provider by name.
-    def self.provider(name, config={})
+    def self.provider(name, config = {})
       name = name.to_sym
       if config.size > 0
-        @providers[name] ||= @config.clone
-        @providers[name].merge!(config)
+        @providers[name.to_sym] = config
       end
       @providers[name]
     end
 
+    def self.error_message(name, locale = "en")
+      @errors[locale]["email_address"][name.to_s] || name.to_s
+    end
+
     # Customize your own error message text.
-    def self.error_messages(hash=nil)
-      @errors = @errors.merge(hash) if hash
-      @errors
+    def self.error_messages(hash = {}, locale = "en", *extra)
+      hash = extra.first if extra.first.is_a? Hash
+
+      @errors[locale] ||= {}
+      @errors[locale]["email_address"] ||= {}
+
+      unless hash.nil? || hash.empty?
+        @errors[locale]["email_address"] = @errors[locale]["email_address"].merge(hash)
+      end
+
+      @errors[locale]["email_address"]
     end
 
     def self.all_settings(*configs)
       config = @config.clone
-      configs.each {|c| config.merge!(c) }
+      configs.each { |c| config.merge!(c) }
       config
     end
+
+    def initialize(overrides = {})
+      @config = Config.all_settings(overrides)
+    end
+
+    def []=(setting, value)
+      @config[setting.to_sym] = value
+    end
+
+    def [](setting)
+      @config[setting.to_sym]
+    end
+
+    def configure(settings)
+      @config = @config.merge(settings)
+    end
+
+    def to_h
+      @config
+    end
   end
 end