email_address 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f7c4c2225713bcb8fa68e8c07aba6de9db62e629
-  data.tar.gz: 8c1f4a244a889254825d1325414536564a12abdf
+SHA256:
+  metadata.gz: f54dab3992bf4e19436dd4771c376b5c4a770b263b6e91704bb8f4b4aa1c33c6
+  data.tar.gz: 64f8de302e904131bcc25be93674d8e976e6f7ee37d6f75b3c4fcaf362054256
 SHA512:
-  metadata.gz: 4927cd30d0302715b8f96a9224f13a85742242c27a1f813ffecdf75eb1896e2954fb36590213cad533d325ba121e096c15f74cb9c416fef191fe2181d668e591
-  data.tar.gz: c5c4426b8749dd1cdd4d8617da291c88d6dbca11040a3bcbb1d729e43b14dabf7a4f4c6bea244fec997bb0d0a21aa47462cf66056fdaf536f181e3702216d5dd
+  metadata.gz: e5f284c688160493c8d30170007b797179ed18c38132e3d9d96d7d1afb390f996ac4f4d68dd3d473706c9a7a8be19cbaa2de2cf64b603032408cc7f3a1d60253
+  data.tar.gz: e78d1280da5668f07bd101f6f83df0e48c8f07a93bfdfe23b8a837632b5c62c57f2e19e309999c3b05c39f9c05a387394efd32bfc6f3ac2cdb28f49d0d4d0cad

data/README.md

@@ -28,8 +28,10 @@ To quickly validate email addresses, use the valid? and error helpers.
 `valid?` returns a boolean, and `error` returns nil if valid, otherwise
 a basic error message.
 
-    EmailAddress.valid? "allen@google.com" #=> true
-    EmailAddress.error "allen@bad-d0main.com" #=> "Invalid Host/Domain Name"
+```ruby
+EmailAddress.valid? "allen@google.com" #=> true
+EmailAddress.error "allen@bad-d0main.com" #=> "Invalid Host/Domain Name"
+```
 
 `EmailAddress` deeply validates your email addresses. It checks:
 
@@ -48,14 +50,17 @@ website on one provider (ISP, Heroku, etc.), and email on a different
 provider (such as Google Apps).  Note that `example.com`, while
 a valid domain name, does not have MX records.
 
-    EmailAddress.valid? "allen@example.com" #=> false
-    EmailAddress.valid? "allen@example.com", host_validation: :syntax #=> true
+```ruby
+EmailAddress.valid? "allen@example.com" #=> false
+EmailAddress.valid? "allen@example.com", host_validation: :syntax #=> true
+```
 
 Most mail servers do not yet support Unicode mailboxes, so the default here is ASCII.
 
-    EmailAddress.error "Pelé@google.com" #=> "Invalid Recipient/Mailbox"
-    EmailAddress.valid? "Pelé@google.com", local_encoding: :unicode #=> true
-
+```ruby
+EmailAddress.error "Pelé@google.com" #=> "Invalid Recipient/Mailbox"
+EmailAddress.valid? "Pelé@google.com", local_encoding: :unicode #=> true
+```
 
 ## Background
 
@@ -89,15 +94,20 @@ introduces terms to distinguish types of email addresses.
 
     madness!."()<>[]:,;@\\\"!#$%&'*+-/=?^_`{}| ~.a(comment )"@example.org
 
+* *Base* - A unique mailbox without tags. For gmail, is uses the incoming
+  punctation, essential when building an MD5 or SHA1 to match services
+  like Gravatar, and email address digest interchange.
+
 * *Canonical* - An unique account address, lower-cased, without the
   tag, and with irrelevant characters stripped.
 
     clark.kent+scoops@gmail.com => clarkkent@gmail.com
 
-* *Reference* - The MD5 of the Canonical format, used to share account
+* *Reference* - The MD5 of the Base format, used to share account
   references without exposing the private email address directly.
 
-    Clark.Kent+scoops@gmail.com => c5be3597c391169a5ad2870f9ca51901
+    Clark.Kent+scoops@gmail.com =>
+    clark.kent@gmail.com => 1429a1dfc797d6e93075fef011c373fb
 
 * *Redacted* - A form of the email address where it is replaced by
   a SHA1-based version to remove the original address from the
@@ -181,8 +191,10 @@ If you are not using Bundler, you need to install the gem yourself.
 
 Require the gem inside your script.
 
-    require 'rubygems'
-    require 'email_address'
+```ruby
+require 'rubygems'
+require 'email_address'
+```
 
 ## Usage
 
@@ -192,41 +204,47 @@ instantiate an object to inspect the address.
 These top-level helpers return edited email addresses and validation
 check.
 
-    address = "Clark.Kent+scoops@gmail.com"
-    EmailAddress.valid?(address)    #=> true
-    EmailAddress.normal(address)    #=> "clark.kent+scoops@gmail.com"
-    EmailAddress.canonical(address) #=> "clarkkent@gmail.com"
-    EmailAddress.reference(address) #=> "c5be3597c391169a5ad2870f9ca51901"
-    EmailAddress.redact(address)    #=> "{bea3f3560a757f8142d38d212a931237b218eb5e}@gmail.com"
-    EmailAddress.munge(address)     #=> "cl*****@gm*****"
-    EmailAddress.matches?(address, 'google') #=> 'google' (true)
-    EmailAddress.error("#bad@example.com") #=> "Invalid Mailbox"
+```ruby
+address = "Clark.Kent+scoops@gmail.com"
+EmailAddress.valid?(address)    #=> true
+EmailAddress.normal(address)    #=> "clark.kent+scoops@gmail.com"
+EmailAddress.canonical(address) #=> "clarkkent@gmail.com"
+EmailAddress.reference(address) #=> "c5be3597c391169a5ad2870f9ca51901"
+EmailAddress.redact(address)    #=> "{bea3f3560a757f8142d38d212a931237b218eb5e}@gmail.com"
+EmailAddress.munge(address)     #=> "cl*****@gm*****"
+EmailAddress.matches?(address, 'google') #=> 'google' (true)
+EmailAddress.error("#bad@example.com") #=> "Invalid Mailbox"
+```
 
 Or you can create an instance of the email address to work with it.
 
-    email = EmailAddress.new(address) #=> #<EmailAddress::Address:0x007fe6ee150540 ...>
-    email.normal        #=> "clark.kent+scoops@gmail.com"
-    email.canonical     #=> "clarkkent@gmail.com"
-    email.original      #=> "Clark.Kent+scoops@gmail.com"
-    email.valid?        #=> true
+```ruby
+email = EmailAddress.new(address) #=> #<EmailAddress::Address:0x007fe6ee150540 ...>
+email.normal        #=> "clark.kent+scoops@gmail.com"
+email.canonical     #=> "clarkkent@gmail.com"
+email.original      #=> "Clark.Kent+scoops@gmail.com"
+email.valid?        #=> true
+```
 
 Here are some other methods that are available.
 
-    email.redact        #=> "{bea3f3560a757f8142d38d212a931237b218eb5e}@gmail.com"
-    email.sha1          #=> "bea3f3560a757f8142d38d212a931237b218eb5e"
-    email.md5           #=> "c5be3597c391169a5ad2870f9ca51901"
-    email.host_name     #=> "gmail.com"
-    email.provider      #=> :google
-    email.mailbox       #=> "clark.kent"
-    email.tag           #=> "scoops"
+```ruby
+email.redact        #=> "{bea3f3560a757f8142d38d212a931237b218eb5e}@gmail.com"
+email.sha1          #=> "bea3f3560a757f8142d38d212a931237b218eb5e"
+email.md5           #=> "c5be3597c391169a5ad2870f9ca51901"
+email.host_name     #=> "gmail.com"
+email.provider      #=> :google
+email.mailbox       #=> "clark.kent"
+email.tag           #=> "scoops"
 
-    email.host.exchanger.first[:ip] #=> "2a00:1450:400b:c02::1a"
-    email.host.txt_hash #=> {:v=>"spf1", :redirect=>"\_spf.google.com"}
+email.host.exchanger.first[:ip] #=> "2a00:1450:400b:c02::1a"
+email.host.txt_hash #=> {:v=>"spf1", :redirect=>"\_spf.google.com"}
 
-    EmailAddress.normal("HIRO@こんにちは世界.com")
-                        #=> "hiro@xn--28j2a3ar1pp75ovm7c.com"
-    EmailAddress.normal("hiro@xn--28j2a3ar1pp75ovm7c.com", host_encoding: :unicode)
-                        #=> "hiro@こんにちは世界.com"
+EmailAddress.normal("HIRO@こんにちは世界.com")
+                    #=> "hiro@xn--28j2a3ar1pp75ovm7c.com"
+EmailAddress.normal("hiro@xn--28j2a3ar1pp75ovm7c.com", host_encoding: :unicode)
+                    #=> "hiro@こんにちは世界.com"
+```
 
 #### Rails Validator
 
@@ -235,9 +253,11 @@ Specify your email address attributes with `field: :user_email`, or
 `fields: [:email1, :email2]`. If neither is given, it assumes to use the
 `email` or `email_address` attribute.
 
-    class User < ActiveRecord::Base
-      validates_with EmailAddress::ActiveRecordValidator, field: :email
-    end
+```ruby
+class User < ActiveRecord::Base
+  validates_with EmailAddress::ActiveRecordValidator, field: :email
+end
+```
 
 #### Rails Email Address Type Attribute
 
@@ -247,9 +267,11 @@ First, you need to register the type in
 `config/initializers/email_address.rb` along with any global
 configurations you want.
 
-    ActiveRecord::Type.register(:email_address, EmailAddress::EmailAddressType)
-    ActiveRecord::Type.register(:canonical_email_address,
-                                EmailAddress::CanonicalEmailAddressType)
+```ruby
+ActiveRecord::Type.register(:email_address, EmailAddress::EmailAddressType)
+ActiveRecord::Type.register(:canonical_email_address,
+                            EmailAddress::CanonicalEmailAddressType)
+```
 
 Assume the Users table contains the columns "email" and "canonical_email".
 We want to normalize the address in "email" and store the canonical/unique
@@ -258,39 +280,42 @@ the email attribute is assigned. With the canonical_email column,
 we can look up the User, even it the given email address didn't exactly
 match the registered version.
 
-    class User < ApplicationRecord
-      attribute :email, :email_address
-      attribute :canonical_email, :canonical_email_address
-
-      validates_with EmailAddress::ActiveRecordValidator,
-                     fields: %i(email canonical_email)
-
-      def email=(email_address)
-        self[:canonical_email] = email_address
-        self[:email] = email_address
-      end
-
-      def self.find_by_email(email)
-        user   = self.find_by(email: EmailAddress.normal(email))
-        user ||= self.find_by(canonical_email: EmailAddress.canonical(email))
-        user ||= self.find_by(canonical_email: EmailAddress.redacted(email))
-        user
-      end
-
-      def redact!
-        self[:canonical_email] = EmailAddress.redact(self.canonical_email)
-        self[:email]           = self[:canonical_email]
-      end
-    end
+```ruby
+class User < ApplicationRecord
+  attribute :email, :email_address
+  attribute :canonical_email, :canonical_email_address
+
+  validates_with EmailAddress::ActiveRecordValidator,
+                 fields: %i(email canonical_email)
+
+  def email=(email_address)
+    self[:canonical_email] = email_address
+    self[:email] = email_address
+  end
+
+  def self.find_by_email(email)
+    user   = self.find_by(email: EmailAddress.normal(email))
+    user ||= self.find_by(canonical_email: EmailAddress.canonical(email))
+    user ||= self.find_by(canonical_email: EmailAddress.redacted(email))
+    user
+  end
+
+  def redact!
+    self[:canonical_email] = EmailAddress.redact(self.canonical_email)
+    self[:email]           = self[:canonical_email]
+  end
+end
+```
 
 Here is how the User model works:
 
-    user = User.create(email:"Pat.Smith+registrations@gmail.com")
-    user.email           #=> "pat.smith+registrations@gmail.com"
-    user.canonical_email #=> "patsmith@gmail.com"
-    User.find_by_email("PAT.SMITH@GMAIL.COM")
-                    #=> #<User email="pat.smith+registrations@gmail.com">
-
+```ruby
+user = User.create(email:"Pat.Smith+registrations@gmail.com")
+user.email           #=> "pat.smith+registrations@gmail.com"
+user.canonical_email #=> "patsmith@gmail.com"
+User.find_by_email("PAT.SMITH@GMAIL.COM")
+                     #=> #<User email="pat.smith+registrations@gmail.com">
+```
 
 The `find_by_email` method looks up a given email address by the
 normalized form (lower case), then by the canonical form, then finally
@@ -313,17 +338,19 @@ which syntax and network validations to perform.
 
 You can compare email addresses:
 
-    e1 = EmailAddress.new("Clark.Kent@Gmail.com")
-    e2 = EmailAddress.new("clark.kent+Superman@Gmail.com")
-    e3 = EmailAddress.new(e2.redact)
-    e1.to_s           #=> "clark.kent@gmail.com"
-    e2.to_s           #=> "clark.kent+superman@gmail.com"
-    e3.to_s           #=> "{bea3f3560a757f8142d38d212a931237b218eb5e}@gmail.com"
+```ruby
+e1 = EmailAddress.new("Clark.Kent@Gmail.com")
+e2 = EmailAddress.new("clark.kent+Superman@Gmail.com")
+e3 = EmailAddress.new(e2.redact)
+e1.to_s           #=> "clark.kent@gmail.com"
+e2.to_s           #=> "clark.kent+superman@gmail.com"
+e3.to_s           #=> "{bea3f3560a757f8142d38d212a931237b218eb5e}@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)
+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)
+```
 
 #### Matching
 
@@ -340,13 +367,15 @@ Matching addresses by simple patterns:
 
 Usage:
 
-    e = EmailAddress.new("Clark.Kent@Gmail.com")
-    e.matches?("gmail.com") #=> true
-    e.matches?("google")    #=> true
-    e.matches?(".org")      #=> false
-    e.matches?("g*com")     #=> true
-    e.matches?("gmail.")    #=> true
-    e.matches?("*kent*@")   #=> true
+```ruby
+e = EmailAddress.new("Clark.Kent@Gmail.com")
+e.matches?("gmail.com") #=> true
+e.matches?("google")    #=> true
+e.matches?(".org")      #=> false
+e.matches?("g*com")     #=> true
+e.matches?("gmail.")    #=> true
+e.matches?("*kent*@")   #=> true
+```
 
 ### Configuration
 
@@ -354,26 +383,34 @@ You can pass an options hash on the `.new()` and helper class methods to
 control how the library treats that address. These can also be
 configured during initialization by provider and default (see below).
 
-    EmailAddress.new("clark.kent@gmail.com",
-                     host_validation: :syntax, host_encoding: :unicode)
+```ruby
+EmailAddress.new("clark.kent@gmail.com",
+                 host_validation: :syntax, host_encoding: :unicode)
+```
 
 Globally, you can change and query configuration options:
 
-    EmailAddress::Config.setting(:host_validation, :mx)
-    EmailAddress::Config.setting(:host_validation) #=> :mx
+```ruby
+EmailAddress::Config.setting(:host_validation, :mx)
+EmailAddress::Config.setting(:host_validation) #=> :mx
+```
 
 Or set multiple settings at once:
 
-    EmailAddress::Config.configure(local_downcase:false, host_validation: :syntax)
+```ruby
+EmailAddress::Config.configure(local_downcase: false, host_validation: :syntax)
+```
 
 You can add special rules by domain or provider. It takes the options
 above and adds the :domain_match and :exchanger_match rules.
 
-    EmailAddress.define_provider('google',
-      domain_match:      %w(gmail.com googlemail.com),
-      exchanger_match:   %w(google.com), # Requires host_validation==:mx
-      local_size:        5..64,
-      mailbox_canonical: ->(m) {m.gsub('.','')})
+```ruby
+EmailAddress.define_provider('google',
+  domain_match:      %w(gmail.com googlemail.com),
+  exchanger_match:   %w(google.com), # Requires host_validation==:mx
+  local_size:        5..64,
+  mailbox_canonical: ->(m) {m.gsub('.','')})
+```
 
 The library ships with the most common set of provider rules. It is not meant
 to house a database of all providers, but a separate `email_address-providers`
@@ -391,26 +428,29 @@ DNS. If you specify an exchanger pattern, but requires a DNS MX lookup.
 For Rails application, create an initializer file with your default
 configuration options:
 
-    # ./config/initializers/email_address.rb
-    EmailAddress::Config.setting( local_format: :relaxed )
-    EmailAddress::Config.provider(:github,
-           host_match: %w(github.com), local_format: :standard)
+```ruby
+# ./config/initializers/email_address.rb
+EmailAddress::Config.setting( local_format: :relaxed )
+EmailAddress::Config.provider(:github,
+       host_match: %w(github.com), local_format: :standard)
+```
 
 #### Override Error Messaegs
 
 You can override the default error messages as follows:
 
-    EmailAddress::Config.error_messages(
-      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")
+```ruby
+EmailAddress::Config.error_messages(
+  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")
+```
 
 Full translation support would be ideal though.
 
-
 ### Available Configuration Settings
 
 * sha1_secret -
@@ -513,7 +553,6 @@ Proper personal identity can still be provided using
 [MIME Encoded-Words](http://en.wikipedia.org/wiki/MIME#Encoded-Word)
 in Email headers.
 
-
 #### Email Addresses as Sensitive Data
 
 Like Social Security and Credit Card Numbers, email addresses are

data/email_address.gemspec

@@ -31,5 +31,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "codeclimate-test-reporter"
 
   spec.add_dependency "simpleidn"
-  spec.add_dependency "netaddr"
+  spec.add_dependency "netaddr", "~> 1.5.1"
 end

data/lib/email_address.rb

@@ -5,6 +5,7 @@ module EmailAddress
   require "email_address/exchanger"
   require "email_address/host"
   require "email_address/local"
+  require "email_address/rewriter"
   require "email_address/address"
   require "email_address/version"
   require "email_address/active_record_validator" if defined?(ActiveModel)
@@ -13,22 +14,29 @@ module EmailAddress
     require "email_address/canonical_email_address_type"
   end
 
-  # @!method self.valid?(options={})
+  # @!method self.valid?(email_address, options={})
   #   Proxy method to {EmailAddress::Address#valid?}
-  # @!method self.error
+  # @!method self.error(email_address)
   #   Proxy method to {EmailAddress::Address#error}
-  # @!method self.normal
+  # @!method self.normal(email_address)
   #   Proxy method to {EmailAddress::Address#normal}
-  # @!method self.redact(digest=:sha1)
+  # @!method self.redact(email_address, options={})
   #   Proxy method to {EmailAddress::Address#redact}
-  # @!method self.munge
+  # @!method self.munge(email_address, options={})
   #   Proxy method to {EmailAddress::Address#munge}
-  # @!method self.canonical
+  # @!method self.base(email_address, options{})
+  #   Returns the base form of the email address, the mailbox
+  #   without optional puncuation removed, no tag, and the host name.
+  # @!method self.canonical(email_address, options{})
   #   Proxy method to {EmailAddress::Address#canonical}
-  # @!method self.reference
-  #   Proxy method to {EmailAddress::Address#reference}
+  # @!method self.reference(email_address, form=:base, options={})
+  #   Returns the reference form of the email address, by default
+  #   the MD5 digest of the Base Form the the address.
+  # @!method self.srs(email_address, sending_domain, options={})
+  #   Returns the address encoded for SRS forwarding. Pass a local
+  #   secret to use in options[:secret]
   class << self
-    (%i[valid? error normal redact munge canonical reference] &
+    (%i[valid? error normal redact munge canonical reference base srs] &
      EmailAddress::Address.public_instance_methods
     ).each do |proxy_method|
       define_method(proxy_method) do |*args, &block|

data/lib/email_address/address.rb

@@ -6,6 +6,8 @@ module EmailAddress
   # (EmailAddress::Local) and Host (Email::AddressHost) parts.
   class Address
     include Comparable
+    include EmailAddress::Rewriter
+
     attr_accessor :original, :local, :host, :config, :reason
 
     CONVENTIONAL_REGEX = /\A#{::EmailAddress::Local::CONVENTIONAL_MAILBOX_WITHIN}
@@ -19,19 +21,26 @@ module EmailAddress
     # 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
+      @config        = config # This needs refactoring!
+      email_address  = (email_address || "").strip
       @original      = email_address
-      email_address||= ""
-      if lh = email_address.match(/(.+)@(.+)/)
-        (_, local, host) = lh.to_a
-      else
-        (local, host)    = [email_address, '']
-      end
+      email_address  = parse_rewritten(email_address) unless config[:skip_rewrite]
+      local, host    = EmailAddress::Address.split_local_host(email_address)
+
       @host         = EmailAddress::Host.new(host, config)
       @config       = @host.config
       @local        = EmailAddress::Local.new(local, @config, @host)
     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
+        [email, '']
+      end
+    end
+
     ############################################################################
     # Local Part (left of @) access
     # * local: Access full local part instance
@@ -121,6 +130,11 @@ module EmailAddress
       self.canonical == self.to_s
     end
 
+    # The base address is the mailbox, without tags, and host.
+    def base
+      self.mailbox + "@" + self.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
@@ -147,15 +161,15 @@ module EmailAddress
     # 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(self.send(form))
     end
     alias :md5 :reference
 
     # 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||"") + (@config[:sha1_secret]||""))
+    def sha1(form=:base)
+      Digest::SHA1.hexdigest((self.send(form)||"") + (@config[:sha1_secret]||""))
     end
 
     #---------------------------------------------------------------------------

data/lib/email_address/rewriter.rb

@@ -0,0 +1,145 @@
+require 'base64'
+
+module EmailAddress::Rewriter
+
+  SRS_FORMAT_REGEX   = /\ASRS0=(....)=(\w\w)=(.+?)=(.+?)@(.+)\z/
+
+  def parse_rewritten(e)
+    @rewrite_scheme = nil
+    @rewrite_error  = nil
+    e = parse_srs(e)
+    # e = parse_batv(e)
+    e
+  end
+
+  #---------------------------------------------------------------------------
+  # SRS (Sender Rewriting Scheme) allows an address to be forwarded from the
+  # original owner and encoded to be used with the domain name of the MTA (Mail
+  # Transport Agent). It encodes the original address within the local part of the
+  # sending email address and respects VERP. If example.com needs to forward a
+  # message from "sender@gmail.com", the SMTP envelope sender is used at this
+  # address. These methods respect DMARC and prevent spoofing email send using
+  # a different domain.
+  # Format: SRS0=HHH=TT=domain=local@sending-domain.com
+  #---------------------------------------------------------------------------
+  def srs(sending_domain, options={}, &block)
+    tt = srs_tt()
+    a = [tt, self.hostname, self.local.to_s].join("=") + "@" + sending_domain
+    hhh = srs_hash(a, options, &block)
+
+    ["SRS0", hhh, a].join("=")
+  end
+
+  def srs?(email)
+    email.match(SRS_FORMAT_REGEX) ? true : false
+  end
+
+  def parse_srs(email, options={}, &block)
+    if email && email.match(SRS_FORMAT_REGEX)
+      @rewrite_scheme = :srs
+      hhh, tt, domain, local, sending_domain = [$1, $2, $3, $4, $5]
+      hhh = tt = sending_domain if false && hhh # Hide warnings for now :-)
+      a = [tt, domain, local].join("=") + "@" + sending_domain
+      unless srs_hash(a, options, &block) === hhh
+        @rewrite_error = "Invalid SRS Email Address: Possibly altered"
+      end
+      unless tt == srs_tt
+        @rewrite_error = "Invalid SRS Email Address: Too old"
+      end
+      [local, domain].join("@")
+    else
+      email
+    end
+  end
+
+  # SRS Timeout Token
+  # Returns a 2-character code for the day. After a few days the code will roll.
+  # TT has a one-day resolution in order to make the address invalid after a few days.
+  # The cycle period is 3.5 years. Used to control late bounces and harvesting.
+  def srs_tt(t=Time.now.utc)
+    Base64.encode64((t.to_i / (60*60*24) %  210).to_s)[0,2]
+  end
+
+  def srs_hash(email, options={}, &block)
+    key = options[:key] || @config[:key] || email.reverse
+    if block_given?
+      block.call(email)[0,4]
+    else
+      Base64.encode64(Digest::SHA1.digest(email + key))[0,4]
+    end
+  end
+
+  #---------------------------------------------------------------------------
+  # Returns a BATV form email address with "Private Signature" (prvs).
+  # Options: key: 0-9 key digit to use
+  #          key_0..key_9: secret key used to sign/verify
+  #          prvs_days: number of days before address "expires"
+  #
+  # BATV - Bounce Address Tag Validation
+  # PRVS - Simple Private Signature
+  # Ex:    prvs=KDDDSSSS=user@example.com
+  #        * K: Digit for Key rotation
+  #        * DDD: Expiry date, since 1970, low 3 digits
+  #        * SSSSSS: sha1( KDDD + orig-mailfrom + key)[0,6]
+  # See:   https://tools.ietf.org/html/draft-levine-smtp-batv-01
+  #---------------------------------------------------------------------------
+  def batv_prvs(options={})
+    k = options[:prvs_key_id] || "0"
+    prvs_days = options[:prvs_days] || @config[:prvs_days] || 30
+    ddd = prvs_day(prvs_days)
+    ssssss = prvs_sign(k, ddd, self.to_s, options={})
+    ["prvs=", k, ddd, ssssss, '=', self.to_s].join('')
+  end
+
+  PRVS_REGEX = /\Aprvs=(\d)(\d{3})(\w{6})=(.+)\z/
+
+  def parse_prvs(email, options={})
+    if email.match(PRVS_REGEX)
+      @rewrite_scheme = :prvs
+      k, ddd, ssssss, email = [$1, $2, $3, $4]
+
+      unless ssssss == prvs_sign(k, ddd, email, options)
+        @rewrite_error = "Invalid BATV Address: Signature unverified"
+      end
+      exp = ddd.to_i
+      roll = 1000 - exp # rolling 1000 day window
+      today = prvs_day(0)
+      # I'm sure this is wrong
+      if exp > today && exp < roll
+        @rewrite_error = "Invalid SRS Email Address: Address expired"
+      elsif exp < today && (today - exp) > 0
+        @rewrite_error = "Invalid SRS Email Address: Address expired"
+      end
+      [local, domain].join("@")
+    else
+      email
+    end
+  end
+
+  def prvs_day(days)
+    ((Time.now.to_i + (days*24*60*60)) / (24*60*60)).to_s[-3,3]
+  end
+
+  def prvs_sign(k, ddd, email, options={})
+    str = [ddd, ssssss, '=', self.to_s].join('')
+    key = options["key_#{k}".to_i] || @config["key_#{k}".to_i] || str.reverse
+    Digest::SHA1.hexdigest([k,ddd, email, key].join(''))[0,6]
+  end
+
+  #---------------------------------------------------------------------------
+  # VERP Embeds a recipient email address into the bounce address
+  #   Bounce Address:  message-id@example.net
+  #   Recipient Email: recipient@example.org
+  #   VERP :           message-id+recipient=example.org@example.net
+  # To handle incoming verp, the "tag" is the recipient email address,
+  # remember to convert the last '=' into a '@' to reconstruct it.
+  #---------------------------------------------------------------------------
+  def verp(recipient, split_char='+')
+    self.local.to_s +
+      split_char + recipient.gsub("@","=") +
+      "@" + self.hostname
+  end
+
+  # NEXT: DMARC, SPF Validation
+
+end

data/lib/email_address/version.rb

@@ -1,3 +1,3 @@
 module EmailAddress
-  VERSION = "0.1.7"
+  VERSION = "0.1.8"
 end

data/test/email_address/test_address.rb

@@ -29,10 +29,12 @@ class TestAddress < Minitest::Test
   def test_forms
     a = EmailAddress.new("User+tag@example.com")
     assert_equal "user+tag@example.com", a.to_s
+    assert_equal "user@example.com", a.base
     assert_equal "user@example.com", a.canonical
     assert_equal "{63a710569261a24b3766275b7000ce8d7b32e2f7}@example.com", a.redact
     assert_equal "{b58996c504c5638798eb6b511e6f49af}@example.com", a.redact(:md5)
     assert_equal "b58996c504c5638798eb6b511e6f49af", a.reference
+    assert_equal "6bdd00c53645790ad9bbcb50caa93880",  EmailAddress.reference("Gmail.User+tag@gmail.com")
   end
 
   # COMPARISON & MATCHING
@@ -58,10 +60,10 @@ class TestAddress < Minitest::Test
 
   def test_empty_address
     a = EmailAddress.new("")
-    assert_equal "{da39a3ee5e6b4b0d3255bfef95601890afd80709}", a.redact
+    assert_equal "{9a78211436f6d425ec38f5c4e02270801f3524f8}", a.redact
     assert_equal "", a.to_s
     assert_equal "", a.canonical
-    assert_equal "d41d8cd98f00b204e9800998ecf8427e", a.reference
+    assert_equal "518ed29525738cebdac49c49e60ea9d3", a.reference
   end
 
   # VALIDATION
@@ -89,6 +91,14 @@ class TestAddress < Minitest::Test
     assert "aasdf-34-.z@example.com".match(EmailAddress::Address::RELAXED_REGEX)
   end
 
+  def test_srs
+    ea= "first.LAST+tag@gmail.com"
+    e = EmailAddress.new(ea)
+    s = e.srs("example.com")
+    assert s.match(EmailAddress::Address::SRS_FORMAT_REGEX)
+    assert EmailAddress.new(s).to_s == e.to_s
+  end
+
   # Quick Regression tests for addresses that should have been valid (but fixed)
   def test_issues
     assert true, EmailAddress.valid?('test@jiff.com', dns_lookup: :mx) # #7

data/test/email_address/test_rewriter.rb

@@ -0,0 +1,14 @@
+#encoding: utf-8
+require_relative '../test_helper'
+
+class TestRewriter < Minitest::Test
+
+  def test_srs
+    ea= "first.LAST+tag@gmail.com"
+    e = EmailAddress.new(ea)
+    s = e.srs("example.com")
+    assert s.match(EmailAddress::Address::SRS_FORMAT_REGEX)
+    assert EmailAddress.new(s).to_s == e.to_s
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: email_address
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Allen Fair
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-06 00:00:00.000000000 Z
+date: 2018-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -112,16 +112,16 @@ dependencies:
   name: netaddr
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.5.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.5.1
 description: The EmailAddress Gem to work with and validate email addresses.
 email:
 - allen.fair@gmail.com
@@ -145,6 +145,7 @@ files:
 - lib/email_address/exchanger.rb
 - lib/email_address/host.rb
 - lib/email_address/local.rb
+- lib/email_address/rewriter.rb
 - lib/email_address/version.rb
 - test/activerecord/test_ar.rb
 - test/activerecord/user.rb
@@ -153,6 +154,7 @@ files:
 - test/email_address/test_exchanger.rb
 - test/email_address/test_host.rb
 - test/email_address/test_local.rb
+- test/email_address/test_rewriter.rb
 - test/test_email_address.rb
 - test/test_helper.rb
 homepage: https://github.com/afair/email_address
@@ -175,7 +177,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: This gem provides a ruby language library for working with and validating
@@ -190,5 +192,6 @@ test_files:
 - test/email_address/test_exchanger.rb
 - test/email_address/test_host.rb
 - test/email_address/test_local.rb
+- test/email_address/test_rewriter.rb
 - test/test_email_address.rb
 - test/test_helper.rb