♻️ 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.rb

@@ -988,7 +988,7 @@ def starttls(options = {}, verify = true)
     # n.b. the following table is copied from Net::IMAP::SASL::Authenticator.
     #++
     #
-    # +PLAIN+::     See PlainAuthenticator.
+    # +PLAIN+::     See SASL::PlainAuthenticator.
     #               Login using clear-text username and password.
     #
     # +XOAUTH2+::   See XOauth2Authenticator.

lib/net/imap/authenticators.rb

@@ -56,7 +56,7 @@ def authenticators
 
 Net::IMAP.extend Net::IMAP::Authenticators
 
-require_relative "authenticators/plain"
+require_relative "sasl/plain_authenticator"
 
 require_relative "authenticators/login"
 require_relative "authenticators/cram_md5"

lib/net/imap/authenticators/plain.rb

@@ -19,7 +19,7 @@ module SASL
       # n.b. the following table is copied to Net::IMAP#authenticate.
       #++
       #
-      # +PLAIN+::     See PlainAuthenticator.
+      # +PLAIN+::     See SASL::PlainAuthenticator.
       #               Login using clear-text username and password.
       #
       # +XOAUTH2+::   See XOauth2Authenticator.

lib/net/imap/sasl/authenticator.rb

@@ -0,0 +1,125 @@
+# 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
+        register Net::IMAP
+
+        ##
+        # :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

@@ -14,11 +14,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