🚚 Move and rename SASL authenticators

The original constants for the `PLAIN` and `XOAUTH2` authenticators are
now deprecated aliases.

The constants for deprecated mechanisms were simply moved, with no
regard for backward compatibility.

Author: nevans

lib/net/imap.rb

@@ -1015,7 +1015,7 @@ def starttls(options = {}, verify = true)
     # +PLAIN+::     See PlainAuthenticator.
     #               Login using clear-text username and password.
     #
-    # +XOAUTH2+::   See XOauth2Authenticator.
+    # +XOAUTH2+::   See XOAuth2Authenticator.
     #               Login using a username and OAuth2 access token.
     #               Non-standard and obsoleted by +OAUTHBEARER+, but widely
     #               supported.

lib/net/imap/authenticators.rb

@@ -12,7 +12,7 @@ module Net::IMAP::Authenticators
   # The authenticator session must respond to +#process+, receiving the server's
   # challenge and returning the client's response.
   #
-  # See PlainAuthenticator, XOauth2Authenticator, and DigestMD5Authenticator for
+  # See PlainAuthenticator, XOAuth2Authenticator, and DigestMD5Authenticator for
   # examples.
   def add_authenticator(auth_type, authenticator)
     authenticators[auth_type] = authenticator
@@ -54,11 +54,20 @@ def authenticators
 
 end
 
-Net::IMAP.extend Net::IMAP::Authenticators
+class Net::IMAP
+  extend Authenticators
+  add_authenticator "PLAIN",      SASL::PlainAuthenticator
+  add_authenticator "XOAUTH2",    SASL::XOAuth2Authenticator
 
-require_relative "authenticators/plain"
+  add_authenticator "CRAM-MD5",   SASL::CramMD5Authenticator   # deprecated
+  add_authenticator "LOGIN",      SASL::LoginAuthenticator     # deprecated
+  add_authenticator "DIGEST-MD5", SASL::DigestMD5Authenticator # deprecated
+end
+
+class Net::IMAP
+  PlainAuthenticator = SASL::PlainAuthenticator # :nodoc:
+  deprecate_constant :PlainAuthenticator
 
-require_relative "authenticators/login"
-require_relative "authenticators/cram_md5"
-require_relative "authenticators/digest_md5"
-require_relative "authenticators/xoauth2"
+  XOauth2Authenticator = SASL::XOAuth2Authenticator # :nodoc:
+  deprecate_constant :XOauth2Authenticator
+end

lib/net/imap/sasl.rb

@@ -32,6 +32,14 @@ module SASL
       autoload :ProhibitedCodepoint, sasl_stringprep_rb
       autoload :BidiStringError,     sasl_stringprep_rb
 
+      sasl_dir = File.expand_path("sasl", __dir__)
+      autoload :PlainAuthenticator,       "#{sasl_dir}/plain_authenticator"
+      autoload :XOAuth2Authenticator,     "#{sasl_dir}/xoauth2_authenticator"
+
+      autoload :CramMD5Authenticator,     "#{sasl_dir}/cram_md5_authenticator"
+      autoload :DigestMD5Authenticator,   "#{sasl_dir}/digest_md5_authenticator"
+      autoload :LoginAuthenticator,       "#{sasl_dir}/login_authenticator"
+
       module_function
 
       # See Net::IMAP::StringPrep::SASLprep#saslprep.

lib/net/imap/authenticators/cram_md5.rb renamed to lib/net/imap/sasl/cram_md5_authenticator.rb

@@ -13,7 +13,7 @@
 # Additionally, RFC8314[https://tools.ietf.org/html/rfc8314] discourage the use
 # of cleartext and recommends TLS version 1.2 or greater be used for all
 # traffic.  With TLS +CRAM-MD5+ is okay, but so is +PLAIN+
-class Net::IMAP::CramMD5Authenticator
+class Net::IMAP::SASL::CramMD5Authenticator
   def process(challenge)
     digest = hmac_md5(challenge, @password)
     return @user + " " + digest
@@ -47,5 +47,4 @@ def hmac_md5(text, key)
     return Digest::MD5.hexdigest(k_opad + digest)
   end
 
-  Net::IMAP.add_authenticator "CRAM-MD5", self
 end

lib/net/imap/authenticators/digest_md5.rb renamed to lib/net/imap/sasl/digest_md5_authenticator.rb

@@ -8,7 +8,7 @@
 # "+DIGEST-MD5+" has been deprecated by
 # {RFC6331}[https://tools.ietf.org/html/rfc6331] and should not be relied on for
 # security.  It is included for compatibility with existing servers.
-class Net::IMAP::DigestMD5Authenticator
+class Net::IMAP::SASL::DigestMD5Authenticator
   def process(challenge)
     case @stage
     when STAGE_ONE
@@ -111,5 +111,4 @@ def qdval(k, v)
     end
   end
 
-  Net::IMAP.add_authenticator "DIGEST-MD5", self
 end

lib/net/imap/authenticators/login.rb renamed to lib/net/imap/sasl/login_authenticator.rb

@@ -17,7 +17,7 @@
 # compatibility with existing servers.  See
 # {draft-murchison-sasl-login}[https://www.iana.org/go/draft-murchison-sasl-login]
 # for both specification and deprecation.
-class Net::IMAP::LoginAuthenticator
+class Net::IMAP::SASL::LoginAuthenticator
   def process(data)
     case @state
     when STATE_USER
@@ -42,5 +42,4 @@ def initialize(user, password, warn_deprecation: true, **_ignored)
     @state = STATE_USER
   end
 
-  Net::IMAP.add_authenticator "LOGIN", self
 end

lib/net/imap/authenticators/plain.rb renamed to lib/net/imap/sasl/plain_authenticator.rb

@@ -9,7 +9,7 @@
 # RFC8314[https://tools.ietf.org/html/rfc8314] recommends TLS version 1.2 or
 # greater be used for all traffic, and deprecate cleartext access ASAP.  +PLAIN+
 # can be secured by TLS encryption.
-class Net::IMAP::PlainAuthenticator
+class Net::IMAP::SASL::PlainAuthenticator
 
   def initial_response?; true end
 
@@ -39,5 +39,4 @@ def initialize(username, password, authzid: nil)
     @authzid  = authzid
   end
 
-  Net::IMAP.add_authenticator "PLAIN", self
 end

lib/net/imap/authenticators/xoauth2.rb renamed to lib/net/imap/sasl/xoauth2_authenticator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Net::IMAP::XOauth2Authenticator
+class Net::IMAP::SASL::XOAuth2Authenticator
 
   def initial_response?; true end
 
@@ -19,5 +19,4 @@ def build_oauth2_string(user, oauth2_token)
     format("user=%s\1auth=Bearer %s\1\1", user, oauth2_token)
   end
 
-  Net::IMAP.add_authenticator 'XOAUTH2', self
 end

test/net/imap/test_imap_authenticators.rb

@@ -12,7 +12,7 @@ class IMAPAuthenticatorsTest < Test::Unit::TestCase
   def plain(...) Net::IMAP.authenticator("PLAIN", ...) end
 
   def test_plain_authenticator_matches_mechanism
-    assert_kind_of(Net::IMAP::PlainAuthenticator, plain("user", "pass"))
+    assert_kind_of(Net::IMAP::SASL::PlainAuthenticator, plain("user", "pass"))
   end
 
   def test_plain_supports_initial_response
@@ -39,7 +39,7 @@ def test_plain_no_null_chars
   def xoauth2(...) Net::IMAP.authenticator("XOAUTH2", ...) end
 
   def test_xoauth2_authenticator_matches_mechanism
-    assert_kind_of(Net::IMAP::XOauth2Authenticator, xoauth2("user", "pass"))
+    assert_kind_of(Net::IMAP::SASL::XOAuth2Authenticator, xoauth2("user", "tok"))
   end
 
   def test_xoauth2
@@ -65,7 +65,7 @@ def login(*args, warn_deprecation: false, **kwargs, &block)
   end
 
   def test_login_authenticator_matches_mechanism
-    assert_kind_of(Net::IMAP::LoginAuthenticator, login("n", "p"))
+    assert_kind_of(Net::IMAP::SASL::LoginAuthenticator, login("n", "p"))
   end
 
   def test_login_does_not_support_initial_response
@@ -95,7 +95,7 @@ def cram_md5(*args, warn_deprecation: false, **kwargs, &block)
   end
 
   def test_cram_md5_authenticator_matches_mechanism
-    assert_kind_of(Net::IMAP::CramMD5Authenticator, cram_md5("n", "p"))
+    assert_kind_of(Net::IMAP::SASL::CramMD5Authenticator, cram_md5("n", "p"))
   end
 
   def test_cram_md5_does_not_support_initial_response
@@ -125,7 +125,8 @@ def digest_md5(*args, warn_deprecation: false, **kwargs, &block)
   end
 
   def test_digest_md5_authenticator_matches_mechanism
-    assert_kind_of(Net::IMAP::DigestMD5Authenticator, digest_md5("n", "p", "z"))
+    assert_kind_of(Net::IMAP::SASL::DigestMD5Authenticator,
+                   digest_md5("n", "p", "z"))
   end
 
   def test_digest_md5_authenticator_deprecated

test/net/imap/test_regexps.rb

@@ -25,7 +25,11 @@ class IMAPRegexpsTest < Test::Unit::TestCase
     RegexpCollector.new(
       Net::IMAP,
       exclude_map: {
-        Net::IMAP => %i[BodyTypeAttachment BodyTypeExtension], # deprecated
+        Net::IMAP => %i[
+          BodyTypeAttachment BodyTypeExtension
+          PlainAuthenticator
+          XOauth2Authenticator
+        ], # deprecated
       },
     ).to_h
   )