email_address 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: da957eceefc70a7dc4a21a1d1f44296e36783021
-  data.tar.gz: fffc1230d4c3080ab56229e34604838543b659e6
+  metadata.gz: 77e8fb26631e827d41da7eee015141495316f430
+  data.tar.gz: 0fa66926ca1dbbdc13154aae789850eec7e1eb75
 SHA512:
-  metadata.gz: e638d9efbba9834cd1857150db91821d82e6bbbbf95ee694bc30287d5c9f69893d87928ee49b044207e9503accf4eefc354295b29e3d5ec44ad6ee5ab2918653
-  data.tar.gz: 90749c6bdbc84c2586208eefb04f8eb208812124d3253170d46471b64df4e23c5ff24bc6967c426285e8cd838f71bcd1fb3b910a7a82690ab3a91da5665e9e40
+  metadata.gz: 5d41c4ca234699c636811187718fc7b73fe52ff55256ebbeb3e32e518d3330c016a72c3185f9632be0cb4d612064e09408517f893927ddd23db9518d0c219066
+  data.tar.gz: 93c7fec757b3a635b39aea3bdc6a259ad5c69b0b5369d4ea48e41cde6009b406a8c2eec94a0bc1e42ed837b220a240d971079135e58455a57d0db5ad1e2df3dd

data/README.md

@@ -1,31 +1,152 @@
 # Email Address
 
-The EmailAddress gem is an _opinionated_ email address handler and
-validator. It does not use RFC standards because they make things worse.
-Email addresses should conform to a few practices that are not
-RFC-Compliant.
-
-Specifically, local parts (left side of the @):
-
-* Should not be case sensitive.
-* Should not contain spaces or anything that would cause quoting.
-* Should not allow Unicode. Addressable items like this need to be
-entered from any keyboard, such as the US ASCII character set. (Domain
-names too, but that can be handled with Punycode.)
-* Should not have comments. Neither should domains.
-* Should not allow unusual symbols (not usually in names and standard
-punctuation).
-* Should not be verified by SMTP connections if possible.
-* Should have spaces stripped automatically if enabled
-* Should be of a reasonable length to identify the recipient.
-* Should be human readable and writable.
-* Should continue allowing for tagging.
-* Should provide mechanism for handling bounce backs and VERP.
-* Should be easily normalized and corrected.
-* Should be canonicalized to identify duplicates if necessary.
-* Should be able to be stored as a digest for privacy proctections.
-
-If you're on board, let's go!
+[![Gem Version](https://badge.fury.io/rb/email_address.svg)](http://rubygems.org/gems/email_address)
+
+The EmailAddress gem provides a structured datatype for email addresses
+and pushes for an _opinionated_ model for which RFC patterns should be
+accepted as a "best practice" and which should not be supported (in the
+name of sanity).
+
+This library provides:
+
+* Email Address Validation
+* Converting between email address forms
+    * **Original:** From the user or data source
+    * **Normalized:** A standardized format for identification
+    * **Canonical:** A format used to identify a unique user
+    * **Redacted:** A format used to store an email address privately
+    * **Reference:** Digest formats for sharing addresses without exposing
+them.
+* Matching addresses to Email/Internet Service Providers. Per-provider
+rules for:
+    * Validation
+    * Address Tag formats
+    * Canonicalization
+    * Unicode Support
+
+## Email Addresses: The Good Parts
+
+Email Addresses are split into two parts: the `local` and `host` part,
+separated by the `@` symbol, or of the generalized format:
+
+    mailbox+tag@subdomain.domain.tld
+
+The **Mailbox** usually identifies the user, role account, or application.
+A **Tag** is any suffix for the mailbox useful for separating and filtering
+incoming email. It is usually preceded by a '+' or other character. Tags are
+not always available for a given ESP or MTA.
+
+Local Parts should consist of lower-case 7-bit ASCII alphanumeric and these characters:
+`-+'.,` It should start with and end with an alphanumeric character and
+no more than one special character should appear together.
+
+Host parts contain a lower-case version of any standard domain name.
+International Domain Names are allowed, and can be converted to 
+[Punycode](http://en.wikipedia.org/wiki/Punycode),
+an encoding system of Unicode strings into the 7-bit ASCII character set.
+Domain names should be configured with MX records in DNS to receive
+email, though this is sometimes mis-configured and the A record can be
+used as a backup.
+
+This is the subset of the RFC Email Address specification that should be
+used.
+
+## Email Addresses: The Bad Parts
+
+Email addresses are defined and redefined in a series of RFC standards.
+Conforming to the full standards is not recommended for easily
+identifying and supporting email addresses. Among these specification,
+we reject are:
+
+* Case-sensitive local parts: `First.Last@example.com`
+* Spaces and Special Characters: `"():;<>@[\\]`
+* Quoting and Escaping Requirements: `"first \"nickname\" last"@example.com`
+* Comment Parts: `(comment)mailbox@example.com`
+* IP and IPv6 addresses as hosts: `mailbox@[127.0.0.1]`
+* Non-ASCII (7-bit) characters in the local part: `Pelé@example.com`
+* Validation by regular expressions like:
+```
+    (?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*
+      |  "(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]
+          |  \\[\x01-\x09\x0b\x0c\x0e-\x7f])*")
+    @ (?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?
+      |  \[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}
+           (?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:
+              (?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]
+              |  \\[\x01-\x09\x0b\x0c\x0e-\x7f])+)
+         \])
+```
+
+## Internationalization
+
+The industry is moving to support Unicode characters in the local part
+of the email address. Currently, SMTP supports only 7-bit ASCII, but a
+new `SMTPUTF8` standard is available, but not yet widely implemented.
+To work properly, global Email systems must be converted to UTF-8
+encoded databases and upgraded to the new email standards.
+
+The problem with i18n email addresses is that support outside of the
+given locale becomes hard to enter addresses on keyboards for another
+locale. Because of this, internationalized local parts are not yet
+supported by default. They are more likely to be erroneous.
+
+Proper personal identity can still be provided using
+[MIME Encoded-Words](http://en.wikipedia.org/wiki/MIME#Encoded-Word)
+in Email headers.
+
+## Email Addresses Forms
+
+* The **original** email address is of the format given by the user.
+* The **Normalized** address has:
+    * Lower-case the local and domain part
+    * Tags are kept as they are important for the user
+    * Remove comments and any "bad parts"
+    * This format is what should be used to identify the account.
+* The **Canonical** form is used to uniquely identify the mailbox.
+    * Domains stored as punycode for IDN
+    * Address Tags removed
+    * Special characters removed (dots in gmail addresses are not
+significant)
+    * Lower cased and "bad parts" removed
+    * Useful for locating a user who forgets registering with a tag or
+with a "Bad part" in the email address.
+* The **Redacted** format is used to store email address fingerprints
+instead of the actual addresses:
+    * Format: sha1(canonical_address)@domain
+    * Given an email address, the record can be found
+    * Useful for treating email addresses as sensitive data and
+complying with requests to remove the address from your database and
+still maintain the state of the account.
+* The **Reference** form allows you to publicly share an address without
+revealing the actual address.
+    * Can be the MD5 or SHA1 of the normalized or canonical address
+    * Useful for "do not email" lists
+    * Useful for cookies that do not reveal the actual account
+
+## Treating Email Addresses as Sensitive Data
+
+Like Social Security and Credit Card Numbers, email addresses are
+becoming more important as a personal identifier on the internet.
+Increasingly, we should treat email addresses as sensitive data. If your
+site/database becomes compromised by hackers, these email addresses can
+be stolen and used to spam your users and to try to gain access to their
+accounts. You should not be storing passwords in plain text; perhaps you
+don't need to store email addresses un-encoded either.
+
+Consider this: upon registration, store the redacted email address for
+the user, and of course, the salted, encrypted password.
+When the user logs in, compute the redacted email address from
+the user-supplied one and look up the record. Store the original address
+in the session for the user, which goes away when the user logs out.
+
+Sometimes, users demand you strike their information from the database.
+Instead of deleting their account, you can "redact" their email
+address, retaining the state of the account to prevent future
+access. Given the original email address again, the redacted account can
+be identified if necessary.
+
+Because of these use cases, the **redact** method on the email address
+instance has been provided.
 
 ## Installation
 
@@ -49,6 +170,9 @@ EmailAddress:
     email = EmailAddress.new("USER+tag@EXAMPLE.com")
     email.normalize     #=> "user+tag@example.com"
     email.canonical     #=> "user@example.com"
+    email.redact        #=> "63a710569261a24b3766275b7000ce8d7b32e2f7@example.com"
+    email.sha1          #=> "63a710569261a24b3766275b7000ce8d7b32e2f7"
+    email.md5           #=> "dea073fb289e438a6d69c5384113454c"
 
 Email Service Provider (ESP) specific edits can be created to provide
 validations and canonical manipulations. A few are given out of the box.
@@ -56,7 +180,7 @@ Providers can be defined bu email domain match rules, or by match rules
 for the MX host names using domains or CIDR addresses.
 
     email = EmailAddress.new("First.Last+Tag@Gmail.Com")
-    email.provider      #=> :gmail
+    email.provider      #=> :google
     email.canonical     #=> "firstlast@gmail.com"
 
 Storing the canonical address with the request address (don't remove
@@ -71,32 +195,36 @@ You can inspect the MX (Mail Exchanger) records
 You can see if it validates as an opinionated address:
 
     email.valid?      # Resonably valid?
+    email.errors      #=> [:mx]
     email.valid_host? # Host name is defined in DNS
     email.strict?     # Strictly valid?
 
-Email addresses should be able to be "archived" or stored in a digest
-format. This allows you to safely keep a record of the address and still
-protect the account's privacy after it has been closed. Given an address
-for inquiry, it can still look up a closed account.
+You can compare email addresses:
 
-    email.md5     #=> "dea073fb289e438a6d69c5384113454c"
-    email.archive #=> "554d32017ab3a7fcf51c88ffce078689003bc521@gmail.com"
+    e1 = EmailAddress.new("First.Last@Gmail.com")
+    e1.to_s           #=> "first.last@gmail.com"
+    e2 = EmailAddress.new("FirstLast+tag@Gmail.com")
+    e3.to_s           #=> "firstlast+tag@gmail.com"
+    e3 = EmailAddress.new(e2.redact)
+    e3.to_s           #=> "554d32017ab3a7fcf51c88ffce078689003bc521@gmail.com"
 
+    e1 == e2          #=> false (Matches by normalized address)
+    e1.same_as?(e2)   #=> true  (Matches as canonical address)
+    e1.same_as?(e3)   #=> true  (Matches as redacted address)
+    e1 < e2           #=> true  (Compares using normalized address)
 
-## Email Address Parts
+## Host Inspection
 
-The Local and Domain Parsing routines divvy the email address into these
-parts from `(comment)mailbox+tag@subdomain.domain.tld`
+The `EmailAddress::Host` can be used to inspect the email domain.
 
-* Local - Everything to the left of the "@"
-* Mailbox - The controlling mailbox name
-* Tag - Anything after the mailbox and tag separator character (usually "+")
-* Comment - To be removed from the normalized form
-* Host Name - Everything to the right of the "@"
-* Subdomains - of the host name, if any.
-* Domain Name - host name without subdomains, with TLD
-* TLD - the rightmost word or set of 2-character domains ("co.uk")
-* Registration Name - host name without subdomain or TLD
+```ruby
+    e1 = EmailAddress.new("First.Last@Gmail.com")
+    e1.host.name                   #=> "gmail.com"
+    e1.host.exchanger.mxers        #=> [["alt4.gmail-smtp-in.l.google.com", "2a00:1450:400c:c01::1b", 30],...]
+    e1.host.exchanger.mx_ips       #=> ["2a00:1450:400c:c01::1b", ...]
+    e1.host.matches?('.com')       #=> true
+    e1.host.txt                    #=> "v=spf1 redirect=_spf.google.com"
+```
 
 ## Domain Matching
 

data/Rakefile

@@ -3,3 +3,21 @@ require "bundler/gem_tasks"
 task :default do
   sh "ruby test/email_address/*"
 end
+require "bundler/gem_tasks"
+require "bundler/setup"
+require 'rake/testtask'
+
+task :default => :test
+
+desc "Run the Test Suite, toot suite"
+task :test do
+  sh "find test -name 'test*rb' -exec ruby {} \\;"
+end
+
+desc "Open and IRB Console with the gem loaded"
+task :console do
+  sh "bundle exec irb  -Ilib -I . -r email_address"
+  #require 'irb'
+  #ARGV.clear
+  #IRB.start
+end

data/email_address.gemspec

@@ -20,6 +20,7 @@ validator.}
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "activemodel", "~> 4.2"
   spec.add_development_dependency "rake"
   spec.add_dependency "simpleidn"
   spec.add_dependency "netaddr"

data/lib/email_address.rb

@@ -5,13 +5,38 @@ require "email_address/domain_parser"
 require "email_address/exchanger"
 require "email_address/host"
 require "email_address/local"
+require "email_address/matcher"
 require "email_address/validator"
 require "email_address/version"
+require "email_address/active_record_validator" if defined?(ActiveModel)
 
 module EmailAddress
 
-  def self.new(address)
-    EmailAddress::Address.new(address)
+  # Creates an instance of this email address.
+  # This is a short-cut to Email::Address::Address.new
+  def self.new(email_address)
+    EmailAddress::Address.new(email_address)
   end
 
+  # Given an email address, this return true if the email validates, false otherwise
+  def self.valid?(email_address, options={})
+    self.new(email_address).valid?(options)
+  end
+
+  # Shortcut to normalize the given email address
+  def self.normal(email_address)
+    EmailAddress::Address.new(email_address).normalize
+  end
+
+  def self.new_normal(email_address)
+    EmailAddress::Address.new(EmailAddress::Address.new(email_address).normalize)
+  end
+
+  def self.canonical(email_address)
+    EmailAddress::Address.new(email_address).normalize
+  end
+
+  def self.new_canonical(email_address)
+    EmailAddress::Address.new(EmailAddress::Address.new(email_address).canonical)
+  end
 end

data/lib/email_address/active_record_validator.rb

@@ -0,0 +1,42 @@
+module EmailAddress
+
+  # ActiveRecord validator class for validating an email
+  # address with this library.
+  # Note the initialization happens once per process.
+  #
+  # Usage:
+  #    validates_with EmailAddress::ActiveRecordValidator, field: :name
+  #
+  # Options:
+  #         field: email,
+  #         fields: [:email1, :email2]
+  # Default field:
+  #         :email or :email_address (first found)
+  #
+  class ActiveRecordValidator < ActiveModel::Validator
+
+    def initialize(options={})
+      @opt = options
+    end
+
+    def validate(r)
+      if @opt[:fields]
+        @opt[:fields].each {|f| validate_email(r, f) }
+      elsif @opt[:field]
+        validate_email(r, opt[:field])
+      elsif r.respond_to? :email
+        validate_email(r, :email)
+      elsif r.respond_to? :email_address
+        validate_email(r, :email_address)
+      end
+    end
+
+    def validate_email(r,f)
+      return if r[f].nil?
+      e = EmailAddress.new(r[f])
+      r.errors[f] << "Email Address Not Valid" unless e.valid?
+    end
+
+  end
+
+end

data/lib/email_address/address.rb

@@ -3,72 +3,159 @@ require 'digest/md5'
 
 module EmailAddress
   class Address
+    include Comparable
 
-    def initialize(address)
-      @address = address
-      parse
-    end
-
-    def parse
-      (_, local, host) = @address.match(/\A(.+)@(.+)/).to_a
-      @host = EmailAddress::Host.new(host)
-      @local = EmailAddress::Local.new(local, @host.provider)
+    # 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)
+      @original     = email_address
+      (local, host) = email_address.split('@', 2)
+      @host         = EmailAddress::Host.new(host)
+      @local        = EmailAddress::Local.new(local||@address, @host)
     end
 
+    # Returns the Email::Address::Host to inspect the host name of the address
     def host
       @host
     end
 
+    # Returns the EmailAddress::local to inspect the data to the left of the @
+    # Use the #left method to access the full string
     def local
       @local
     end
 
+    # Everything to the left of the @ in the address, called the local part.
+    def left
+      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
       @local.mailbox
     end
 
+    # Returns the host name, the part to the right of the @ sign.
     def host_name
       @host.host_name
     end
+    alias :right :host_name
 
+    # Returns the tag part of the local address, or nil if not given.
     def 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
       @local.comment
     end
 
+    # Returns the ESP (Email Service Provider) or ISP name derived
+    # using the provider configuration rules.
     def provider
       @host.provider
     end
 
+    # Returns the string representation of the normalized email address.
     def to_s
       normalize
     end
 
-    def normalize
+    # The original email address in the request (unmodified).
+    def original
+      @original
+    end
+
+    # Returns the normailed email address according to the provider
+    # and system normalization rules. Ususally this downcases the address,
+    # removes spaces and comments, but includes any tags.
+    def normal
       [@local.normalize, @host.normalize].join('@')
     end
+    alias :normalize :normal
 
+    # Returns the canonical email address according to the provider
+    # uniqueness rules. Usually, this downcases the address, removes
+    # spaves and comments and tags, and any extraneous part of the address
+    # not considered a unique account by the provider.
     def canonical
       [@local.canonical, @host.canonical].join('@')
     end
+    alias :uniq :canonical
+    alias :canonicalize :canonical
 
+    # Returns and MD5 of the canonical 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 md5
       Digest::MD5.hexdigest(canonical)
     end
 
+    def canonical_md5
+      Digest::MD5.hexdigest(self.canonical)
+    end
+
+    # This returns the SHA1 digest (in a hex string) of the canonical email
+    # address. See #md5 for more background.
     def sha1
       Digest::SHA1.hexdigest(canonical)
     end
 
-    def archive
+    # 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)
+      normalize == other_email.normalize
+    end
+    alias :eql? :==
+    alias :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)
+      canonical == other_email.canonical ||
+        redact == other_email.canonical || canonical == other_email.redact
+    end
+    alias :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)
+      normalize <=> other_email.normalize
+    end
+
+    # Redact the address for storage. To protect the user's privacy,
+    # use this when you don't want to store a real email, only a fingerprint.
+    # Given the original address, you can match the original with this method.
+    # This returns the SHA1 of the canonical address (no tags, no gmail dots)
+    # at the original host. The host is part of the digest part, but also
+    # retained for verification and domain maintenance.
+    def redact
       [sha1, @host.canonical].join('@')
     end
 
+    def redacted?
+      @local.to_s =~ /\A[0-9a-f]{40}\z/ ? true : false
+    end
+
+    # Returns true if this address is considered valid according to the format
+    # configured for its provider, It test the normalized form.
     def valid?(options={})
       EmailAddress::Validator.validate(self, options)
     end
+
+    # Returns an array of error messages generated from the validation process via
+    # the #valid? method.
+    def errors(options={})
+      v = EmailAddress::Validator.new(self, options)
+      v.valid?
+      v.errors
+    end
   end
 end