mail_xoauth2 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 27a0ef9770c2172e574541dbb950bc4f7b074163a42903acfeadf2570c95609c
+  data.tar.gz: 499e917ef4edf4e6f4f3a3f8f51f5305f60c1d67bd6706ce94f8644ef331a2ff
+SHA512:
+  metadata.gz: b0dcd0f7f2c8fbd565b680866e7a29e72e9c8acb3891be7a36e521913dd53ff392a9490d5c3ef94354324f127efe0e78c881ddc9294ecd65cadf56529c7c0ba0
+  data.tar.gz: 9a4f954d7350be1d603de16aa1cd813c2046d1516ffe99cb7b4ee13b5e4bece972a0fcd9b778777f166e39a44fc71a5049f755bd1acaecf1a201b6db66518d14

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Mailbutler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.markdown

@@ -0,0 +1,30 @@
+# mail_xoauth2 
+Get access to IMAP and STMP via OAuth2, using the standard Ruby Net libraries.
+
+This gem is based on and inspired by [gmail_xoauth](https://github.com/nfo/gmail_xoauth).
+
+## Usage
+
+### IMAP OAuth 2.0
+
+```ruby
+require 'mail_xoauth2'
+imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
+imap.authenticate('XOAUTH2', 'myemail@gmail.com', my_oauth2_token)
+messages_count = imap.status('INBOX', ['MESSAGES'])['MESSAGES']
+puts "Seeing #{messages_count} messages in INBOX"
+```
+
+### SMTP OAuth 2.0
+
+```ruby
+require 'mail_xoauth2'
+smtp = Net::SMTP.new('smtp.gmail.com', 587)
+smtp.enable_starttls_auto
+smtp.start('gmail.com', 'myemail@gmail.com', my_oauth2_token, :xoauth2)
+smtp.finish
+```
+
+## License
+
+See LICENSE for details.

data/lib/mail_xoauth2/imap_xoauth2_authenticator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'net/imap'
+
+module MailXoauth2
+  class ImapXoauth2Authenticator
+    def process(_data)
+      build_oauth2_string(@user, @oauth2_token, true)
+    end
+
+    private
+
+    # +user+ is an email address: roger@gmail.com
+    # +oauth2_token+ is the OAuth2 token
+    def initialize(user, oauth2_token)
+      @user = user
+      @oauth2_token = oauth2_token
+    end
+
+    include Oauth2String
+  end
+end
+
+Net::IMAP.add_authenticator('XOAUTH2', MailXoauth2::ImapXoauth2Authenticator)

data/lib/mail_xoauth2/oauth2_string.rb

@@ -0,0 +1,17 @@
+module MailXoauth2
+  module Oauth2String
+    private
+
+    #
+    # Builds the "oauth2 protocol authentication string". See https://developers.google.com/google-apps/gmail/xoauth2_protocol
+    #
+    #   +user+ is an email address: roger@gmail.com
+    #   +oauth2_token+ is the oauth2 token
+    def build_oauth2_string(user, oauth2_token, encode_base64 = false)
+      oauth2_string = format("user=%<user>s\1auth=Bearer %<token>s\1\1".encode('us-ascii'), user: user, token: oauth2_token)
+      oauth2_string = Base64.strict_encode64(oauth2_string) if encode_base64
+
+      oauth2_string
+    end
+  end
+end

data/lib/mail_xoauth2/smtp_xoauth2_authenticator.rb

@@ -0,0 +1,38 @@
+require 'net/smtp'
+require 'base64'
+
+module MailXoauth2
+  module SmtpXoauth2Authenticator
+    def send_xoauth2(auth_token)
+      critical do
+        get_response("AUTH XOAUTH2 #{auth_token}")
+      end
+    end
+    private :send_xoauth2
+
+    def get_final_status
+      critical do
+        get_response('')
+      end
+    end
+    private :get_final_status
+
+    def auth_xoauth2(user, oauth2_token)
+      check_auth_args user, oauth2_token
+
+      auth_string = build_oauth2_string(user, oauth2_token, true)
+      res = send_xoauth2(auth_string)
+
+      # See note about SMTP protocol exchange in https://developers.google.com/gmail/xoauth2_protocol
+      res = get_final_status if res.continue?
+
+      check_auth_response res
+      res
+    end
+
+    include Oauth2String
+  end
+end
+
+# Not pretty, right ?
+Net::SMTP.__send__('include', MailXoauth2::SmtpXoauth2Authenticator)

data/lib/mail_xoauth2/version.rb

@@ -0,0 +1,3 @@
+module MailXoauth2
+  VERSION = '1.0'.freeze
+end

data/lib/mail_xoauth2.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'mail_xoauth2/oauth2_string'
+require 'mail_xoauth2/imap_xoauth2_authenticator'
+require 'mail_xoauth2/smtp_xoauth2_authenticator'

data/test/helper.rb

@@ -0,0 +1,46 @@
+require 'yaml'
+
+require 'rubygems'
+require 'test/unit'
+require 'mocha/test_unit'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'mail_xoauth2'
+
+# Wanna debug ? Activate the IMAP debug mode, it will show the client/server conversation
+# Net::IMAP.debug = true
+
+# SMTP debugging can only be enabled on Net::SMTP instances
+# Net::SMTP.class_eval do
+#   def initialize_with_debug(*args)
+#     initialize_without_debug(*args)
+#     @debug_output = STDERR
+#   end
+#   alias_method :initialize_without_debug, :initialize
+#   alias_method :initialize, :initialize_with_debug
+# end
+
+VALID_CREDENTIALS = begin
+  YAML.load_file(File.join(File.dirname(__FILE__), 'valid_credentials.yml'))
+rescue Errno::ENOENT
+  STDERR.puts '
+Warning: some tests are disabled because they require valid credentials.
+To enable them, create a file "test/valid_credentials.yml".
+It should also ontain a valid OAuth2 access token.
+Of course, this file is .gitignored. Template:
+
+---
+:email: someuser@gmail.com
+:consumer_key: anonymous # "anonymous" is a valid value for testing
+:consumer_secret: anonymous # "anonymous" is a valid value for testing
+:token: 1/nE2xBCDOU0429bTeJySE11kRE95qzKQNlfTaaBcDeFg
+:token_secret: 123Z/bMsi9fFhN6qHFWOabcd
+:oauth2_token: ya29.AHES6ZTIpsLuSyMwnh-3C40WWcuiOe4N7he0a8xnkvDk_6Q_6yUg7E
+
+'
+  false
+end
+
+class Test::Unit::TestCase
+end

data/test/test_imap_xoauth2_authenticator.rb

@@ -0,0 +1,30 @@
+require 'helper'
+
+class TestImapXoauth2Authenticator < Test::Unit::TestCase
+  def setup; end
+
+  def test_xoauth2_authenticator_is_enabled
+    authenticators = Net::IMAP.__send__('class_variable_get', '@@authenticators')
+    assert_not_nil authenticators['XOAUTH2']
+    assert_equal authenticators['XOAUTH2'], GmailXoauth::ImapXoauth2Authenticator
+  end
+
+  def test_authenticate_with_invalid_credentials
+    imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
+    assert_raise(Net::IMAP::NoResponseError) do
+      imap.authenticate('XOAUTH2', 'roger@moore.com', 'a')
+    end
+  end
+
+  def test_authenticate_with_valid_credentials
+    return unless VALID_CREDENTIALS
+
+    imap = Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false)
+    imap.authenticate('XOAUTH2', VALID_CREDENTIALS[:email], VALID_CREDENTIALS[:oauth2_token])
+    mailboxes = imap.list('', '*')
+    assert_instance_of Array, mailboxes
+    assert_instance_of Net::IMAP::MailboxList, mailboxes.first
+  ensure
+    imap.disconnect if imap
+  end
+end

data/test/test_oauth2_string.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'helper'
+
+class TestOauth2String < Test::Unit::TestCase
+  def setup; end
+
+  def test_build_oauth2_string
+    user = 'somebody@gmail.com'
+    oauth2_access_token = SecureRandom.urlsafe_base64
+
+    oauth2_string = SomeNetClass.new.__send__('build_oauth2_string', user, oauth2_access_token)
+
+    assert_equal(
+      "user=#{user}\1auth=Bearer #{oauth2_access_token}\1\1",
+      oauth2_string
+    )
+  end
+
+  def test_build_encoded_oauth2_string
+    user = 'somebody@gmail.com'
+    oauth2_access_token = SecureRandom.urlsafe_base64
+
+    oauth2_string = SomeNetClass.new.__send__('build_oauth2_string', user, oauth2_access_token, true)
+
+    assert_equal(
+      Base64.strict_encode64("user=#{user}\1auth=Bearer #{oauth2_access_token}\1\1"),
+      oauth2_string
+    )
+  end
+end
+
+class SomeNetClass
+  include MailXoauth2::Oauth2String
+end

data/test/test_smtp_xoauth2_authenticator.rb

@@ -0,0 +1,56 @@
+require 'helper'
+
+class TestSmtpXoauth2Authenticator < Test::Unit::TestCase
+  def setup; end
+
+  def test_smtp_authenticator_is_enabled
+    assert Net::SMTP.new(nil).respond_to?(:auth_xoauth2), 'The Net::SMTP class should define the method :auth_xoauth2'
+  end
+
+  def test_authenticate_with_invalid_credentials
+    smtp = Net::SMTP.new('smtp.gmail.com', 587)
+    smtp.enable_starttls_auto
+    assert_raise(Net::SMTPAuthenticationError) do
+      smtp.start('gmail.com', 'roger@moore.com', 'a', :xoauth2)
+    end
+  end
+
+  def test_authenticate_with_valid_credentials
+    return unless VALID_CREDENTIALS
+
+    smtp = Net::SMTP.new('smtp.gmail.com', 587)
+    smtp.enable_starttls_auto
+
+    assert_nothing_raised do
+      smtp.start('gmail.com', VALID_CREDENTIALS[:email], VALID_CREDENTIALS[:oauth2_token], :xoauth2)
+    end
+  ensure
+    smtp.finish if smtp&.started?
+  end
+
+  # Test the handling of 3xx response to an "AUTH XOAUTH2" request... client
+  # should send a "\r\n" to get the actual error that occurred.
+  #
+  # See note about SMTP protocol exchange in https://developers.google.com/
+  # gmail/xoauth2_protocol
+  #
+  def test_authenticate_with_continuation
+    smtp = Net::SMTP.new('smtp.gmail.com', 587)
+
+    # Stub return from initial "AUTH XOAUTH2" request as well as the empty line sent to get final error
+    smtp.stubs(:send_xoauth2).returns(Net::SMTP::Response.parse('334 eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUiOiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ=='))
+    smtp.stubs(:get_final_status).returns(Net::SMTP::Response.parse('454 4.7.0 Too many login attempts, please try again later. j63sm3521185itj.19 - gsmtp'))
+
+    smtp.enable_starttls_auto
+
+    # Validate an error is still raised
+    ex = assert_raise(Net::SMTPAuthenticationError) do
+      smtp.start('gmail.com', 'roger@moore.com', 'a', :xoauth2)
+    end
+
+    # ...and that the 334 is not passed back to the caller.
+    assert_equal('454 4.7.0 Too many login attempts, please try again later. j63sm3521185itj.19 - gsmtp', ex.message)
+  ensure
+    smtp.finish if smtp&.started?
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: mail_xoauth2
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Fabian Jäger
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-06-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Get access to IMAP and STMP via OAuth2, using the standard Ruby Net libraries
+email:
+- fabian@mailbutler.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.markdown
+- lib/mail_xoauth2.rb
+- lib/mail_xoauth2/imap_xoauth2_authenticator.rb
+- lib/mail_xoauth2/oauth2_string.rb
+- lib/mail_xoauth2/smtp_xoauth2_authenticator.rb
+- lib/mail_xoauth2/version.rb
+- test/helper.rb
+- test/test_imap_xoauth2_authenticator.rb
+- test/test_oauth2_string.rb
+- test/test_smtp_xoauth2_authenticator.rb
+homepage: https://github.com/Mailbutler/mail_xoauth2
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--charset=UTF-8"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Get access to IMAP and STMP via OAuth2, using the standard Ruby Net libraries
+test_files: []