Use net-imap's SASL implementation 🚧[WIP]🚧

This commit converts `#authenticate` to use `net-imap` as a generic
fallback for mechanisms that haven't otherwise been added (as subclasses
of `Authenticator`).  In this commit, the original implementation is
still used by `#authenticate` for the `PLAIN`, `LOGIN`, and `CRAM-MD5`
mechanisms.  Every other mechanism supported by `net-imap` v0.4.0 is
added here:
* `ANONYMOUS`
* `DIGEST-MD5` _(deprecated)_
* `EXTERNAL`
* `OAUTHBEARER`
* `SCRAM-SHA-1` and `SCRAM-SHA-256`
* `XOAUTH`

**TODO:** Ideally, `net-smtp` and `net-imap` should both depend on a
shared `sasl` or `net-sasl` gem, rather than keep the SASL
implementation inside one or the other.  See
ruby/net-imap#23.

**TODO:** since we already know the authenticator arguments up-front, we
can validate authenticator arguments by simply creating the
authenticator object and rely on the its initializer to raise
ArgumentError for missing args.

.github/workflows/test.yml

@@ -19,4 +19,4 @@ jobs:
  - name: Install dependencies
  run: bundle install
  - name: Run test
- run: rake test
+ run: bundle exec rake test

lib/net/smtp.rb

@@ -171,8 +171,11 @@ class SMTPUnsupportedCommand < ProtocolError
  #
  # === SMTP Authentication
  #
- # The Net::SMTP class supports three authentication schemes;
- # PLAIN, LOGIN and CRAM MD5. (SMTP Authentication: [RFC2554])
+ # The Net::SMTP class supports several authentication schemes;
+ # ({SMTP Authentication: [RFC4956]}[https://www.rfc-editor.org/rfc/rfc4954.html])
+ # +ANONYMOUS+, +EXTERNAL+, +OAUTHBEARER+, +PLAIN+, +SCRAM-SHA-1+,
+ # +SCRAM-SHA-256+, and +XOAUTH2+.
+ #
  # To use SMTP authentication, pass extra arguments to
  # SMTP.start or SMTP#start.
  #
@@ -182,26 +185,43 @@ class SMTPUnsupportedCommand < ProtocolError
  # Net::SMTP.start("your.smtp.server", 25,
  # auth: {type: :plain,
  # username: "authentication identity",
- # password: password})
+ # password: password,
+ # authzid: "authorization identity"}) # optional
  #
- # # LOGIN
- # Net::SMTP.start('your.smtp.server', 25,
- # user: 'Your Account', secret: 'Your Password', authtype: :login)
+ # # SCRAM-SHA-256
  # Net::SMTP.start("your.smtp.server", 25,
- # auth: {type: :login,
+ # user: "authentication identity", secret: password,
+ # authtype: :scram_sha_256)
+ # Net::SMTP.start("your.smtp.server", 25,
+ # auth: {type: :scram_sha_256,
  # username: "authentication identity",
- # password: password})
+ # password: password,
+ # authzid: "authorization identity"}) # optional
  #
- # # CRAM MD5
- # Net::SMTP.start('your.smtp.server', 25,
- # user: 'Your Account', secret: 'Your Password', authtype: :cram_md5)
+ # # OAUTHBEARER
+ # Net::SMTP.start("your.smtp.server", 25,
+ # auth: {type: :oauthbearer,
+ # oauth2_token: oauth2_access_token,
+ # authzid: "authorization identity", # optional
+ # host: "your.smtp.server", # optional
+ # port: 25}) # optional
+ #
+ # # XOAUTH2
+ # Net::SMTP.start("your.smtp.server", 25,
+ # user: "username", secret: oauth2_access_token, authtype: :xoauth2)
  # Net::SMTP.start("your.smtp.server", 25,
- # auth: {type: :cram_md5,
- # username: 'Your Account',
- # password: 'Your Password'})
+ # auth: {type:  :xoauth2,
+ # username:  "username",
+ # oauth2_token: oauth2_token})
  #
- # +LOGIN+, and +CRAM-MD5+ are still available for backwards compatibility, but
- # are deprecated and should be avoided.
+ # # EXTERNAL
+ # Net::SMTP.start("your.smtp.server", 587,
+ # starttls: :always, ssl_context_params: ssl_ctx_params,
+ # authtype: "external")
+ #
+ # +DIGEST-MD5+, +LOGIN+, and +CRAM-MD5+ are still available for backwards
+ # compatibility, but are deprecated and should be avoided. <em>Using a
+ # deprecated authentication mechanisms will print a warning.</em>
  #
  class SMTP < Protocol
  VERSION = "0.4.0"
@@ -501,12 +521,6 @@ def debug_output=(arg)
  # +helo+ is the _HELO_ _domain_ provided by the client to the
  # server (see overview comments); it defaults to 'localhost'.
  #
- # The remaining arguments are used for SMTP authentication, if required
- # or desired. +user+ is the account name; +secret+ is your password
- # or other authentication token; and +authtype+ is the authentication
- # type, one of :plain, :login, or :cram_md5. See the discussion of
- # SMTP Authentication in the overview notes.
- #
  # If +tls+ is true, enable TLS. The default is false.
  # If +starttls+ is :always, enable STARTTLS, if +:auto+, use STARTTLS when the server supports it,
  # if false, disable STARTTLS.
@@ -520,6 +534,13 @@ def debug_output=(arg)
  #
  # +tls_verify: true+ is equivalent to +ssl_context_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }+.
  #
+ # The remaining arguments are used for SMTP authentication, if required or
+ # desired. +user+ or +username+ is the authentication or authorization
+ # identity (depending on +authtype+); +secret+ or +password+ is your
+ # password or other authentication token; and +authtype+ is the
+ # authentication type. +auth+ is a hash of arbitrary keyword parameters for
+ # #auth. See the discussion of SMTP Authentication in the overview notes.
+ #
  # === Errors
  #
  # This method may raise:
@@ -565,10 +586,13 @@ def started?
  # +helo+ is the _HELO_ _domain_ that you'll dispatch mails from; see
  # the discussion in the overview notes.
  #
- # If either +auth+ or +user+ are given, SMTP authentication will be
- # attempted using the AUTH command. +authtype+ specifies the type of
- # authentication to attempt; it must be one of :login, :plain, and
- # :cram_md5. See the notes on SMTP Authentication in the overview.
+ # If +user+, +username+, +secret+, +password+, +authtype+, or +auth+ given,
+ # SMTP authentication will be attempted using the #auth command. +authtype+
+ # specifies the SASL mechanism to attempt; +user+ or +username+ is the
+ # authentication or authorization identity (depending on +authtype+);
+ # +secret+ or +password+ is your password or other authentication token;
+ # +auth+ is a hash of arbitrary keyword parameters for #auth. See the
+ # discussion of SMTP Authentication in the overview notes.
  #
  # === Block Usage
  #
@@ -871,15 +895,16 @@ def authenticate(user, secret, authtype = DEFAULT_AUTH_TYPE)
  # include +authcid+ for authentication identity, +authzid+ for authorization
  # identity, +username+ for either "authentication identity" or
  # "authorization identity" depending on the +mechanism+, and +password+.
+ # Keyword arguments that do not apply to the +mechanism+ may be silently
+ # ignored.
  def auth(*args, **kwargs, &blk)
  args, kwargs = backward_compatible_auth_args(*args, **kwargs)
- authtype, *args = args
- authenticator = Authenticator.auth_class(authtype).new(self)
- if kwargs.empty?
- # TODO: remove this, unless it is needed for 2.6/2.7/3.0 compatibility
- critical { authenticator.auth(*args, &blk) }
- else
- critical { authenticator.auth(*args, **kwargs, &blk) }
+ critical do
+ Authenticator::SASLAdapter.new(self).authenticate(*args, **kwargs, &blk)
+ rescue SMTPServerBusy, SMTPSyntaxError, SMTPFatalError => error
+ raise SMTPAuthenticationError.new(error.response)
+ rescue SASL::AuthenticationIncomplete => error
+ raise error.response.exception_class.new(error.response)
  end
  end
 
@@ -919,21 +944,28 @@ def merge_auth_params(user, secret, authtype, auth)
  auth
  end
 
- # Convert +type+, +username+, +secret+ (etc) kwargs to positional args, for
- # compatibility with existing authenticators.
- def backward_compatible_auth_args(_type = nil, *args, type: nil,
- username: nil, authcid: nil,
- secret: nil, password: nil,
- **kwargs)
- type && _type and
+ def backward_compatible_auth_args(authtype = nil, *args,
+ type: nil, secret: nil, **kwargs)
+ type && authtype and
  raise ArgumentError, 'conflict between "type" keyword argument ' \
  'and positional argument'
- type ||= _type || DEFAULT_AUTH_TYPE
+ type ||= authtype || DEFAULT_AUTH_TYPE
  check_auth_method(type)
+ if secret
+ secret_type = type.match?(/\AX?OAUTH/i) ? :oauth2_token : :password
+ kwargs.key?(secret_type) and
+ raise ArgumentError 'conflict between "secret" and %p keyword args' % [
+ secret_type.to_s
+ ]
+ kwargs[secret_type] = secret
+ end
  auth_class = Authenticator.auth_class(type)
- if auth_class.is_a?(Class) && auth_class <= Authenticator
- args[0] ||= authcid || username
- args[1] ||= password || secret
+ if auth_class.is_a?(Class) && auth_class <= Authenticator ||
+ type.match?(/\A(?:LOGIN|CRAM[-_]MD5)\z/i)
+ usernames = [kwargs.delete(:authcid), kwargs.delete(:username)]
+ secrets = [kwargs.delete(:password)]
+ args[0] ||= usernames.compact.first
+ args[1] ||= secrets.compact.first
  check_auth_args(args[0], args[1], type)
  end
  [[type, *args], kwargs]
@@ -1047,6 +1079,27 @@ def get_response(reqline)
  recv_response()
  end
 
+ # Returns a successful Response.
+ #
+ # Yields continuation data.
+ #
+ # This method may raise:
+ #
+ # * Net::SMTPAuthenticationError
+ # * Net::SMTPServerBusy
+ # * Net::SMTPSyntaxError
+ # * Net::SMTPFatalError
+ # * Net::SMTPUnknownError
+ def send_command_with_continuations(*args)
+ server_resp = get_response args.join(" ")
+ while server_resp.continue?
+ client_resp = yield server_resp.string.strip.split(nil, 2).last
+ server_resp = get_response client_resp
+ end
+ server_resp.success? or raise server_resp.exception_class.new(server_resp)
+ server_resp
+ end
+
  private
 
  def validate_line(line)

lib/net/smtp/auth_sasl_adapter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "net/imap"
+
+module Net
+ class SMTP
+ SASL = Net::IMAP::SASL
+
+ class Authenticator
+
+ # Experimental
+ #
+ # Initialize with a block that runs a command, yielding for continuations.
+ class SASLAdapter < SASL::ClientAdapter
+ include SASL::ProtocolAdapters::SMTP
+
+ RESPONSE_ERRORS = [
+ SMTPAuthenticationError,
+ SMTPServerBusy,
+ SMTPSyntaxError,
+ SMTPFatalError,
+ ].freeze
+
+ def initialize(...)
+ super
+ @command_proc ||= client.method(:send_command_with_continuations)
+ end
+
+ def host; client.address end
+ def response_errors; RESPONSE_ERRORS end
+ def sasl_ir_capable?; true end # TODO
+ def auth_capable?(mechanism); client.auth_capable?(mechanism) end
+ def drop_connection; client.finish end
+ def drop_connection!; client.finish end # TODO
+ end
+
+ end
+ end
+end

lib/net/smtp/auth_sasl_compatibility_adapter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Net
+ class SMTP
+
+ # Curries arguments to SMTP#auth, using the Authenticator API.
+ #
+ # Net::SMTP#authenticate still supports the v0.4.0 Authenticator API, so
+ # Authenticator subclasses can still be added and used with it. This class
+ # will be used as the default, when no matching Authenticator subclass
+ # exists.
+ class CompatibilityAdapter
+ def initialize(mechanism) @mechanism = mechanism end
+ def new(smtp) @smtp = smtp; self end
+ def auth(*args, **kwargs, &block)
+ args.pop while args.any? && args.last.nil?
+ @smtp.auth(@mechanism, *args, **kwargs, &block)
+ end
+ end
+
+ Authenticator.auth_classes.default_proc = ->_, mechanism {
+ CompatibilityAdapter.new(mechanism)
+ }
+
+ end
+end

net-smtp.gemspec

@@ -26,4 +26,5 @@ Gem::Specification.new do |spec|
  spec.require_paths = ["lib"]
 
  spec.add_dependency "net-protocol"
+ spec.add_dependency "net-imap", ">= 0.4.1" # experimental SASL support
 end