Add forward-compatible API for SASL mechanisms

The current #start and #authenticate API can't fully support every SASL
mechanism.  Some SASL mechanisms do not require a +username+
(OAUTHBEARER, EXTERNAL, ANONYMOUS) or a +secret+ (EXTERNAL, ANONYMOUS).
Many SASL mechanisms will need to take extra arguments (e.g: `authzid`
for many mechanisms, `warn_deprecations` for deprecated mechanisms,
`min_iterations` for SCRAM-*, `anonymous_message` for ANONYMOUS), and so
on.  And, although it is convenient to use +username+ as an alias for
+authcid+ or +authzid+ and +secret+ as an alias for +password+ or
+oauth2_token+, it can also be useful to have keyword parameters that
keep stable semantics across many different mechanisms.

A SASL-compatible API must first find the authenticator for the
mechanism and then delegate any arbitrary parameters to that
authenticator.  Practically, that means that the mechanism name must
either be the first positional parameter or a keyword parameter, and
then every other parameter can be forwarded.  `Net::SMTP#auth` does this.
Also, an `auth` keyword parameter has been added to `Net::SMTP#start`,
allowing `start` to pass any arbitrary keyword parameters into `#auth`.

For backward compatibility, when one of the existing Authenticator
classes is selected, it converts keyword args to positional args.  Also
for backward compatibility, `Net::SMTP#authenticate` keeps its v0.4.0
implementation.

lib/net/smtp.rb

@@ -179,13 +179,29 @@ class SMTPUnsupportedCommand < ProtocolError
  # # PLAIN
  # Net::SMTP.start('your.smtp.server', 25,
  # user: 'Your Account', secret: 'Your Password', authtype: :plain)
+ # Net::SMTP.start("your.smtp.server", 25,
+ # auth: {type: :plain,
+ # username: "authentication identity",
+ # password: password})
+ #
  # # LOGIN
  # Net::SMTP.start('your.smtp.server', 25,
  # user: 'Your Account', secret: 'Your Password', authtype: :login)
+ # Net::SMTP.start("your.smtp.server", 25,
+ # auth: {type: :login,
+ # username: "authentication identity",
+ # password: password})
  #
  # # CRAM MD5
  # Net::SMTP.start('your.smtp.server', 25,
  # user: 'Your Account', secret: 'Your Password', authtype: :cram_md5)
+ # Net::SMTP.start("your.smtp.server", 25,
+ # auth: {type: :cram_md5,
+ # username: 'Your Account',
+ # password: 'Your Password'})
+ #
+ # +LOGIN+, and +CRAM-MD5+ are still available for backwards compatibility, but
+ # are deprecated and should be avoided.
  #
  class SMTP < Protocol
  VERSION = "0.4.0"
@@ -452,6 +468,7 @@ def debug_output=(arg)
 
  #
  # :call-seq:
+ # start(address, port = nil, helo: 'localhost', auth: nil, tls: false, starttls: :auto, tls_verify: true, tls_hostname: nil, ssl_context_params: nil) { |smtp| ... }
  # start(address, port = nil, helo: 'localhost', user: nil, secret: nil, authtype: nil, tls: false, starttls: :auto, tls_verify: true, tls_hostname: nil, ssl_context_params: nil) { |smtp| ... }
  # start(address, port = nil, helo = 'localhost', user = nil, secret = nil, authtype = nil) { |smtp| ... }
  #
@@ -517,16 +534,17 @@ def debug_output=(arg)
  # * IOError
  #
  def SMTP.start(address, port = nil, *args, helo: nil,
- user: nil, secret: nil, password: nil, authtype: nil,
+ user: nil, username: nil, secret: nil, password: nil,
+ authtype: nil, auth: nil,
  tls: false, starttls: :auto,
  tls_verify: true, tls_hostname: nil, ssl_context_params: nil,
  &block)
  raise ArgumentError, "wrong number of arguments (given #{args.size + 2}, expected 1..6)" if args.size > 4
  helo ||= args[0] || 'localhost'
- user ||= args[1]
+ user ||= username || args[1]
  secret ||= password || args[2]
  authtype ||= args[3]
- new(address, port, tls: tls, starttls: starttls, tls_verify: tls_verify, tls_hostname: tls_hostname, ssl_context_params: ssl_context_params).start(helo: helo, user: user, secret: secret, authtype: authtype, &block)
+ new(address, port, tls: tls, starttls: starttls, tls_verify: tls_verify, tls_hostname: tls_hostname, ssl_context_params: ssl_context_params).start(helo: helo, user: user, secret: secret, authtype: authtype, auth: auth, &block)
  end
 
  # +true+ if the SMTP session has been started.
@@ -538,6 +556,7 @@ def started?
  # :call-seq:
  # start(helo: 'localhost', user: nil, secret: nil, authtype: nil) { |smtp| ... }
  # start(helo = 'localhost', user = nil, secret = nil, authtype = nil) { |smtp| ... }
+ # start(helo = 'localhost', auth: {type: nil, **auth_kwargs}) { |smtp| ... }
  #
  # Opens a TCP connection and starts the SMTP session.
  #
@@ -546,11 +565,10 @@ def started?
  # +helo+ is the _HELO_ _domain_ that you'll dispatch mails from; see
  # the discussion in the overview notes.
  #
- # If both of +user+ and +secret+ 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 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.
  #
  # === Block Usage
  #
@@ -589,12 +607,15 @@ def started?
  # * Net::ReadTimeout
  # * IOError
  #
- def start(*args, helo: nil, user: nil, secret: nil, password: nil, authtype: nil)
+ def start(*args, helo: nil,
+ user: nil, username: nil, secret: nil, password: nil,
+ authtype: nil, auth: nil)
  raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..4)" if args.size > 4
  helo ||= args[0] || 'localhost'
- user ||= args[1]
- secret ||= password || args[2]
- authtype ||= args[3]
+ auth = merge_auth_params(user || username || args[1],
+ secret || password || args[2],
+ authtype || args[3],
+ auth)
  if defined?(OpenSSL::VERSION)
  ssl_context_params = @ssl_context_params || {}
  unless ssl_context_params.has_key?(:verify_mode)
@@ -609,13 +630,13 @@ def start(*args, helo: nil, user: nil, secret: nil, password: nil, authtype: nil
  end
  if block_given?
  begin
- do_start helo, user, secret, authtype
+ do_start helo, **auth
  return yield(self)
  ensure
  do_finish
  end
  else
- do_start helo, user, secret, authtype
+ do_start helo, **auth
  return self
  end
  end
@@ -633,12 +654,8 @@ def tcp_socket(address, port)
  TCPSocket.open address, port
  end
 
- def do_start(helo_domain, user, secret, authtype)
+ def do_start(helo_domain, **authopts)
  raise IOError, 'SMTP session already started' if @started
- if user or secret
- check_auth_method(authtype || DEFAULT_AUTH_TYPE)
- check_auth_args user, secret
- end
  s = Timeout.timeout(@open_timeout, Net::OpenTimeout) do
  tcp_socket(@address, @port)
  end
@@ -655,7 +672,7 @@ def do_start(helo_domain, user, secret, authtype)
  # helo response may be different after STARTTLS
  do_helo helo_domain
  end
- authenticate user, secret, (authtype || DEFAULT_AUTH_TYPE) if user
+ auth(**authopts) if authopts.any?
  @started = true
  ensure
  unless @started
@@ -833,13 +850,39 @@ def open_message_stream(from_addr, *to_addrs, &block) # :yield: stream
 
  DEFAULT_AUTH_TYPE = :plain
 
+ # Deprecated: use #auth instead.
  def authenticate(user, secret, authtype = DEFAULT_AUTH_TYPE)
+ # warn "DEPRECATED: use Net::SMTP#auth instead"
  check_auth_method authtype
  check_auth_args user, secret
  authenticator = Authenticator.auth_class(authtype).new(self)
  critical { authenticator.auth(user, secret) }
  end
 
+ # call-seq:
+ # auth(mechanism, ...)
+ # auth(type: mechanism, **kwargs, &block)
+ #
+ # All arguments besides +mechanism+ are forwarded directly to the
+ # authenticator. Alternatively, +mechanism+ can be provided by the +type+
+ # keyword parameter. Positional parameters cannot be used with +type+.
+ #
+ # Different authenticators take different options, but common options
+ # include +authcid+ for authentication identity, +authzid+ for authorization
+ # identity, +username+ for either "authentication identity" or
+ # "authorization identity" depending on the +mechanism+, and +password+.
+ 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) }
+ end
+ end
+
  private
 
  def check_auth_method(type)
@@ -857,6 +900,45 @@ def check_auth_args(user, secret, authtype = DEFAULT_AUTH_TYPE)
  end
  end
 
+ # Convert the original +user+, +secret+, +authtype+ with +auth+, and checks
+ # the arguments.
+ def merge_auth_params(user, secret, authtype, auth)
+ auth = Hash.try_convert(auth) || {}
+ if user || secret || authtype
+ args = { type: authtype || DEFAULT_AUTH_TYPE,
+ username: user, secret: secret }
+ auth = args.merge(auth)
+ check_auth_method(auth[:type])
+ check_auth_args(auth[:authcid] || auth[:username],
+ auth[:password] || auth[:secret],
+ auth[:type])
+ elsif auth.any?
+ check_auth_method(auth[:type] || DEFAULT_AUTH_TYPE)
+ # check_auth_args may not be valid, depending on the authtype.
+ end
+ 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
+ raise ArgumentError, 'conflict between "type" keyword argument ' \
+ 'and positional argument'
+ type ||= _type || DEFAULT_AUTH_TYPE
+ check_auth_method(type)
+ auth_class = Authenticator.auth_class(type)
+ if auth_class.is_a?(Class) && auth_class <= Authenticator
+ args[0] ||= authcid || username
+ args[1] ||= password || secret
+ check_auth_args(args[0], args[1], type)
+ end
+ [[type, *args], kwargs]
+ end
+
  #
  # SMTP command dispatcher
  #

test/net/smtp/test_smtp.rb

@@ -110,6 +110,21 @@ def test_auth_plain
  smtp = Net::SMTP.start 'localhost', server.port
  assert smtp.authenticate("account", "password", :plain).success?
  assert_equal "AUTH PLAIN AGFjY291bnQAcGFzc3dvcmQ=\r\n", server.commands.last
+
+ server = FakeServer.start(auth: 'plain')
+ smtp = Net::SMTP.start 'localhost', server.port
+ assert smtp.auth("PLAIN", "account", "password").success?
+ assert_equal "AUTH PLAIN AGFjY291bnQAcGFzc3dvcmQ=\r\n", server.commands.last
+
+ server = FakeServer.start(auth: 'plain')
+ smtp = Net::SMTP.start 'localhost', server.port
+ assert smtp.auth(type: "PLAIN", username: "account", secret: "password").success?
+ assert_equal "AUTH PLAIN AGFjY291bnQAcGFzc3dvcmQ=\r\n", server.commands.last
+
+ server = FakeServer.start(auth: 'plain')
+ smtp = Net::SMTP.start 'localhost', server.port
+ assert smtp.auth("PLAIN", username: "account", password: "password").success?
+ assert_equal "AUTH PLAIN AGFjY291bnQAcGFzc3dvcmQ=\r\n", server.commands.last
  end
 
  def test_unsucessful_auth_plain
@@ -120,10 +135,20 @@ def test_unsucessful_auth_plain
  assert_equal "535", err.response.status
  end
 
+ def test_auth_cram_md5
+ server = FakeServer.start(auth: 'CRAM-MD5')
+ smtp = Net::SMTP.start 'localhost', server.port
+ assert smtp.auth(:cram_md5, "account", password: "password").success?
+ end
+
  def test_auth_login
  server = FakeServer.start(auth: 'login')
  smtp = Net::SMTP.start 'localhost', server.port
  assert smtp.authenticate("account", "password", :login).success?
+
+ server = FakeServer.start(auth: 'login')
+ smtp = Net::SMTP.start 'localhost', server.port
+ assert smtp.auth("LOGIN", username: "account", secret: "password").success?
  end
 
  def test_unsucessful_auth_login
@@ -455,6 +480,15 @@ def test_start_auth_plain
  port = fake_server_start(auth: 'plain')
  Net::SMTP.start('localhost', port, user: 'account', password: 'password', authtype: :plain){}
 
+ port = fake_server_start(auth: 'plain')
+ Net::SMTP.start('localhost', port, authtype: "PLAIN",
+ auth: {username: 'account', password: 'password'}){}
+
+ port = fake_server_start(auth: 'plain')
+ Net::SMTP.start('localhost', port, auth: {username: 'account',
+ password: 'password',
+ type: :plain}){}
+
  port = fake_server_start(auth: 'plain')
  assert_raise Net::SMTPAuthenticationError do
  Net::SMTP.start('localhost', port, user: 'account', password: 'invalid', authtype: :plain){}