♻️ SASL PLAIN: SASL-IR, refactor, move, document

* ✨ Add `initial_response? => true`
* ♻️  Inherit from Authenticator base class.
* 🚚 Move to sasl directory and SASL namespace.
* 🗑️ Deprecate original constant name.

Author: nevans

lib/net/imap/authenticators/plain.rb

@@ -62,11 +62,12 @@ module SASL
       sasl_dir = File.expand_path("sasl", __dir__)
       autoload :Authenticator,            "#{sasl_dir}/authenticator"
       autoload :Authenticators,           "#{sasl_dir}/authenticators"
+      autoload :PlainAuthenticator,       "#{sasl_dir}/plain_authenticator"
 
       # Authenticators are all lazy loaded
       def self.authenticators
         @authenticators ||= SASL::Authenticators.new.tap do |registry|
-          registry.add_authenticator "Plain",      PlainAuthenticator
+          registry.add_authenticator "Plain"
           registry.add_authenticator "XOauth2",    XOauth2Authenticator
           registry.add_authenticator "Login",      LoginAuthenticator     # deprecated
           registry.add_authenticator "Cram-MD5",   CramMD5Authenticator   # deprecated
@@ -101,7 +102,6 @@ def saslprep(string, **opts)
   end
 end
 
-require_relative "authenticators/plain"
 require_relative "authenticators/login"
 require_relative "authenticators/cram_md5"
 require_relative "authenticators/digest_md5"

lib/net/imap/sasl.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "authenticator"
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # Authenticator for the "+PLAIN+" SASL mechanism, specified in
+      # RFC-4616[https://tools.ietf.org/html/rfc4616].  Use via
+      # Net::IMAP#authenticate.
+      #
+      # +PLAIN+ authentication sends the password in cleartext.
+      # RFC-3501[https://tools.ietf.org/html/rfc3501] encourages servers to
+      # disable cleartext authentication until after TLS has been negotiated.
+      # RFC-8314[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 PlainAuthenticator < Authenticator
+
+        ##
+        # :call-seq:
+        #   new(username, password,  authzid = nil, **)   -> auth_ctx
+        #   new(authcid:, password:, authzid: nil, **)    -> auth_ctx
+        #   new(**) {|propname, auth_ctx| propval }       -> auth_ctx
+        #
+        # Creates an Authenticator for the "+PLAIN+" SASL mechanism.
+        #
+        # Called by Net::IMAP#authenticate and similar methods on other clients.
+        #
+        # === Properties
+        #
+        # * #authcid ― Identity whose #password is used.  Aliased as #username.
+        # * #password ― Password or passphrase associated with this #authcid.
+        # * #authzid ― Alternate identity to act as or on behalf of.  Optional.
+        #
+        # See the documentation on each property method for more details.
+        #
+        # All three properties may be sent as either positional or keyword
+        # arguments.  See Net::IMAP::SASL::Authenticator@Properties for a
+        # detailed description of property assignment, lazy loading, and
+        # callbacks.
+        #
+        def initialize(username_arg = nil, password_arg = nil, authzid_arg = nil,
+                       authcid: nil,   password: nil,      authzid: nil,
+                       username: nil, # alias for authcid
+                       **, &callback)
+          super
+          propinit(:authcid,  authcid,  username, username_arg)
+          propinit(:authzid,  authzid,  authzid_arg)
+          propinit(:password, password, password_arg)
+        end
+
+        # :call-seq:
+        #   initial_response? -> true
+        #
+        # +PLAIN+ can send an initial client response.
+        def initial_response?; true end
+
+        ##
+        # method: authcid
+        # :call-seq: authcid -> string or nil
+        #
+        # Authentication identity: the identity that matches the #password.
+        #
+        # RFC-2831[https://tools.ietf.org/html/rfc2831] uses the term +username+.
+        # "Authentication identity" is the generic term used by
+        # RFC-4422[https://tools.ietf.org/html/rfc4422].
+        # RFC-4616[https://tools.ietf.org/html/rfc4616] and many later RFCs
+        # abbreviate to +authcid+.  #username is available as an alias for
+        # #authcid, but only <tt>:authcid</tt> will be sent to callbacks.
+        property :authcid
+        alias username authcid
+
+        ##
+        # method: password
+        # :call-seq: password -> string or nil
+        #
+        # A password or passphrase that matches the #authcid.
+        property :password
+
+        ##
+        # method: authzid
+        # :call-seq: authzid -> string or nil
+        #
+        # Authorization identity: an identity to act as or on behalf of.  The
+        # identity form is application protocol specific.  If not provided or
+        # left blank, the server derives an authorization identity from the
+        # authentication identity.  The server is responsible for verifying the
+        # client's credentials and verifying that the identity it associates with
+        # the client's authentication identity is allowed to act as (or on behalf
+        # of) the authorization identity.
+        #
+        # For example, an administrator or superuser might take on another role:
+        #
+        #     imap.authenticate "PLAIN", "root", ->{passwd}, authzid: "user"
+        #
+        property :authzid
+
+        ##
+        # Responds with the client's credentials.
+        def process(data) [authzid, authcid, password].join("\0") end
+
+        private
+
+        NULL = -"\0".b
+        private_constant :NULL
+
+        def propset(name, value)
+          case name
+          when :authcid, :password, :authzid
+            raise ArgumentError, "#{name} contains NULL"  if value&.include?(NULL)
+          end
+          super
+        end
+
+      end
+    end
+
+    PlainAuthenticator = SASL::PlainAuthenticator # :nodoc:
+    deprecate_constant :PlainAuthenticator
+
+  end
+end

lib/net/imap/sasl/plain_authenticator.rb

@@ -20,11 +20,13 @@ def plain(*args, **kwargs, &block)
   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_response
     assert_equal("\0authc\0passwd", plain("authc", "passwd").process(nil))
+    assert_equal("authz\0user\0pass",
+                 plain("user", "pass", "authz").process(nil))
     assert_equal("authz\0user\0pass",
                  plain("user", "pass", authzid: "authz").process(nil))
   end