net-imap 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 473842922edfdfd112a9cd3fa96df2831efa0d4640a38c0969725d6c04f45dbe
-  data.tar.gz: 7f93b8a1882f2225f404db0d175c29ead931de531f918e17cbb6f8515300b9e9
+  metadata.gz: 90ea9e3ff227103752eda7658da755be8f4aabda8fdf60f33379f95c27a1a69c
+  data.tar.gz: b7878cec3bdd9216ee1eda01fe8276c1753f01de6bd875988415665150b5fb00
 SHA512:
-  metadata.gz: d9470c52ca3b689a1dd314501a91f5651d1b11fd26cc5628cb6ccf4bf59aeb93ebdcca141ab12d0ec5e69b0e5aa5e29881c85433d9c6dcdeb5902591c1c62aaa
-  data.tar.gz: 6caae2c7cf684d10ca54ac8b53b498acb5c8d210135d2f583d254fa3dbdc41b7e50382c43aeb05438713b723d9d5da7d48980569024e36d55683e9e5b041df8a
+  metadata.gz: df018d07e090469ff814af057d94ee4c8b9327071bc173f6f10aa106385071bd39076c334e195f163a670c756b3379a38ffcb00b46248a06b80b3d4aa3ed04c1
+  data.tar.gz: b6215f30153f034d04bfe6d0006da68cb0beee20ec15c2664283d2c766b5a37b9fddfaec82a0fa94a36233e175e81a492829a7094fda4581dc847573e572f0e9

data/lib/net/imap/sasl/anonymous_authenticator.rb

@@ -29,8 +29,9 @@ module Net
         # this, see Net::IMAP#authenticate or your client's authentication
         # method.
         #
-        # #anonymous_message is an optional message which is sent to the server.
-        # It may be sent as a positional argument or as a keyword argument.
+        # ==== Parameters
+        #
+        # * _optional_ #anonymous_message — a message to send to the server.
         #
         # Any other keyword arguments are silently ignored.
         def initialize(anon_msg = nil, anonymous_message: nil, **)

data/lib/net/imap/sasl/authentication_exchange.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      # This API is *experimental*, and may change.
+      #
+      # TODO: catch exceptions in #process and send #cancel_response.
+      # TODO: raise an error if the command succeeds after being canceled.
+      # TODO: use with more clients, to verify the API can accommodate them.
+      #
+      # Create an AuthenticationExchange from a client adapter and a mechanism
+      # authenticator:
+      #     def authenticate(mechanism, ...)
+      #       authenticator = SASL.authenticator(mechanism, ...)
+      #       SASL::AuthenticationExchange.new(
+      #         sasl_adapter, mechanism, authenticator
+      #       ).authenticate
+      #     end
+      #
+      #     private
+      #
+      #     def sasl_adapter = MyClientAdapter.new(self, &method(:send_command))
+      #
+      # Or delegate creation of the authenticator to ::build:
+      #     def authenticate(...)
+      #       SASL::AuthenticationExchange.build(sasl_adapter, ...)
+      #         .authenticate
+      #     end
+      #
+      # As a convenience, ::authenticate combines ::build and #authenticate:
+      #     def authenticate(...)
+      #       SASL::AuthenticationExchange.authenticate(sasl_adapter, ...)
+      #     end
+      #
+      # Likewise, ClientAdapter#authenticate delegates to #authenticate:
+      #     def authenticate(...) = sasl_adapter.authenticate(...)
+      #
+      class AuthenticationExchange
+        # Convenience method for <tt>build(...).authenticate</tt>
+        def self.authenticate(...) build(...).authenticate end
+
+        # Use +registry+ to override the global Authenticators registry.
+        def self.build(client, mechanism, *args, sasl_ir: true, **kwargs, &block)
+          authenticator = SASL.authenticator(mechanism, *args, **kwargs, &block)
+          new(client, mechanism, authenticator, sasl_ir: sasl_ir)
+        end
+
+        attr_reader :mechanism, :authenticator
+
+        def initialize(client, mechanism, authenticator, sasl_ir: true)
+          @client = client
+          @mechanism = -mechanism.to_s.upcase.tr(?_, ?-)
+          @authenticator = authenticator
+          @sasl_ir = sasl_ir
+          @processed = false
+        end
+
+        # Call #authenticate to execute an authentication exchange for #client
+        # using #authenticator.  Authentication failures will raise an
+        # exception.  Any exceptions other than those in RESPONSE_ERRORS will
+        # drop the connection.
+        def authenticate
+          client.run_command(mechanism, initial_response) { process _1 }
+            .tap { raise AuthenticationIncomplete, _1 unless done? }
+        rescue *client.response_errors
+          raise # but don't drop the connection
+        rescue
+          client.drop_connection
+          raise
+        rescue Exception # rubocop:disable Lint/RescueException
+          client.drop_connection!
+          raise
+        end
+
+        def send_initial_response?
+          @sasl_ir &&
+            authenticator.respond_to?(:initial_response?) &&
+            authenticator.initial_response? &&
+            client.sasl_ir_capable? &&
+            client.auth_capable?(mechanism)
+        end
+
+        def done?
+          authenticator.respond_to?(:done?) ? authenticator.done? : @processed
+        end
+
+        private
+
+        attr_reader :client
+
+        def initial_response
+          return unless send_initial_response?
+          client.encode_ir authenticator.process nil
+        end
+
+        def process(challenge)
+          client.encode authenticator.process client.decode challenge
+        ensure
+          @processed = true
+        end
+
+      end
+    end
+  end
+end

data/lib/net/imap/sasl/authenticators.rb

@@ -65,7 +65,7 @@ module Net::IMAP::SASL
     # lazily loaded from <tt>Net::IMAP::SASL::#{name}Authenticator</tt> (case is
     # preserved and non-alphanumeric characters are removed..
     def add_authenticator(name, authenticator = nil)
-      key = name.upcase.to_sym
+      key = -name.to_s.upcase.tr(?_, ?-)
       authenticator ||= begin
         class_name = "#{name.gsub(/[^a-zA-Z0-9]/, "")}Authenticator".to_sym
         auth_class = nil
@@ -79,10 +79,15 @@ module Net::IMAP::SASL
 
     # Removes the authenticator registered for +name+
     def remove_authenticator(name)
-      key = name.upcase.to_sym
+      key = -name.to_s.upcase.tr(?_, ?-)
       @authenticators.delete(key)
     end
 
+    def mechanism?(name)
+      key = -name.to_s.upcase.tr(?_, ?-)
+      @authenticators.key?(key)
+    end
+
     # :call-seq:
     #   authenticator(mechanism, ...) -> auth_session
     #
@@ -100,8 +105,9 @@ module Net::IMAP::SASL
     #   only.  Protocol client users should see refer to their client's
     #   documentation, e.g. Net::IMAP#authenticate.
     def authenticator(mechanism, ...)
-      auth = @authenticators.fetch(mechanism.upcase.to_sym) do
-        raise ArgumentError, 'unknown auth type - "%s"' % mechanism
+      key = -mechanism.to_s.upcase.tr(?_, ?-)
+      auth = @authenticators.fetch(key) do
+        raise ArgumentError, 'unknown auth type - "%s"' % key
       end
       auth.respond_to?(:new) ? auth.new(...) : auth.call(...)
     end

data/lib/net/imap/sasl/client_adapter.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      # This API is *experimental*, and may change.
+      #
+      # TODO: use with more clients, to verify the API can accommodate them.
+      #
+      # An abstract base class for implementing a SASL authentication exchange.
+      # Different clients will each have their own adapter subclass, overridden
+      # to match their needs.
+      #
+      # Although the default implementations _may_ be sufficient, subclasses
+      # will probably need to override some methods.  Additionally, subclasses
+      # may need to include a protocol adapter mixin, if the default
+      # ProtocolAdapters::Generic isn't sufficient.
+      class ClientAdapter
+        include ProtocolAdapters::Generic
+
+        attr_reader :client, :command_proc
+
+        # +command_proc+ can used to avoid exposing private methods on #client.
+        # It should run a command with the arguments sent to it, yield each
+        # continuation payload, respond to the server with the result of each
+        # yield, and return the result.  Non-successful results *MUST* raise an
+        # exception.  Exceptions in the block *MUST* cause the command to fail.
+        #
+        # Subclasses that override #run_command may use #command_proc for
+        # other purposes.
+        def initialize(client, &command_proc)
+          @client, @command_proc = client, command_proc
+        end
+
+        # Delegates to AuthenticationExchange.authenticate.
+        def authenticate(...) AuthenticationExchange.authenticate(self, ...) end
+
+        # Do the protocol and server both support an initial response?
+        def sasl_ir_capable?; client.sasl_ir_capable? end
+
+        # Does the server advertise support for the mechanism?
+        def auth_capable?(mechanism); client.auth_capable?(mechanism) end
+
+        # Runs the authenticate command with +mechanism+ and +initial_response+.
+        # When +initial_response+ is nil, an initial response must NOT be sent.
+        #
+        # Yields each continuation payload, responds to the server with the
+        # result of each yield, and returns the result.  Non-successful results
+        # *MUST* raise an exception.  Exceptions in the block *MUST* cause the
+        # command to fail.
+        #
+        # Subclasses that override this may use #command_proc differently.
+        def run_command(mechanism, initial_response = nil, &block)
+          command_proc or raise Error, "initialize with block or override"
+          args = [command_name, mechanism, initial_response].compact
+          command_proc.call(*args, &block)
+        end
+
+        # Returns an array of server responses errors raised by run_command.
+        # Exceptions in this array won't drop the connection.
+        def response_errors; [] end
+
+        # Drop the connection gracefully.
+        def drop_connection;  client.drop_connection end
+
+        # Drop the connection abruptly.
+        def drop_connection!; client.drop_connection! end
+      end
+    end
+  end
+end

data/lib/net/imap/sasl/cram_md5_authenticator.rb

@@ -14,13 +14,17 @@
 # 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::SASL::CramMD5Authenticator
-  def initialize(user, password, warn_deprecation: true, **_ignored)
+  def initialize(user = nil, pass = nil,
+                 authcid: nil, username: nil,
+                 password: nil, secret: nil,
+                 warn_deprecation: true,
+                 **)
     if warn_deprecation
       warn "WARNING: CRAM-MD5 mechanism is deprecated." # TODO: recommend SCRAM
     end
     require "digest/md5"
-    @user = user
-    @password = password
+    @user = authcid || username || user
+    @password = password || secret || pass
     @done = false
   end
 

data/lib/net/imap/sasl/digest_md5_authenticator.rb

@@ -20,8 +20,9 @@ class Net::IMAP::SASL::DigestMD5Authenticator
   # "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
-  # that to +authcid+.  So +authcid+ is available as an alias for #username.
+  # this to +authcid+.
   attr_reader :username
+  alias authcid username
 
   # A password or passphrase that matches the #username.
   #
@@ -44,6 +45,7 @@ class Net::IMAP::SASL::DigestMD5Authenticator
   # :call-seq:
   #   new(username,  password,  authzid = nil, **options) -> authenticator
   #   new(username:, password:, authzid:  nil, **options) -> authenticator
+  #   new(authcid:,  password:, authzid:  nil, **options) -> authenticator
   #
   # Creates an Authenticator for the "+DIGEST-MD5+" SASL mechanism.
   #
@@ -51,17 +53,27 @@ class Net::IMAP::SASL::DigestMD5Authenticator
   #
   # ==== Parameters
   #
-  # * #username — Identity whose #password is used.
-  # * #password — A password or passphrase associated with this #username.
-  # * #authzid ― Alternate identity to act as or on behalf of.  Optional.
-  # * +warn_deprecation+ — Set to +false+ to silence the warning.
+  # * #authcid  ― Authentication identity that is associated with #password.
   #
-  # See the documentation for each attribute for more details.
+  #   #username ― An alias for +authcid+.
+  #
+  # * #password ― A password or passphrase associated with this #authcid.
+  #
+  # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+  #
+  #   When +authzid+ is not set, the server should derive the authorization
+  #   identity from the authentication identity.
+  #
+  # * _optional_ +warn_deprecation+ — Set to +false+ to silence the warning.
+  #
+  # Any other keyword arguments are silently ignored.
   def initialize(user = nil, pass = nil, authz = nil,
                  username: nil, password: nil, authzid: nil,
+                 authcid: nil, secret: nil,
                  warn_deprecation: true, **)
-    username ||= user or raise ArgumentError, "missing username"
-    password ||= pass or raise ArgumentError, "missing password"
+    username = authcid || username || user or
+      raise ArgumentError, "missing username (authcid)"
+    password ||= secret || pass or raise ArgumentError, "missing password"
     authzid  ||= authz
     if warn_deprecation
       warn "WARNING: DIGEST-MD5 SASL mechanism was deprecated by RFC6331."

data/lib/net/imap/sasl/external_authenticator.rb

@@ -12,24 +12,45 @@ module Net
       # established external to SASL, for example by TLS certificate or IPsec.
       class ExternalAuthenticator
 
-        # Authorization identity: an identity to act as or on behalf of.
+        # 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"
         #
-        # If not explicitly provided, the server defaults to using the identity
-        # that was authenticated by the external credentials.
         attr_reader :authzid
+        alias username authzid
 
         # :call-seq:
         #   new(authzid: nil, **) -> authenticator
+        #   new(username: nil, **) -> authenticator
+        #   new(username = nil, **) -> authenticator
         #
         # Creates an Authenticator for the "+EXTERNAL+" SASL mechanism, as
         # specified in RFC-4422[https://tools.ietf.org/html/rfc4422].  To use
         # this, see Net::IMAP#authenticate or your client's authentication
         # method.
         #
-        # #authzid is an optional identity to act as or on behalf of.
+        # ==== Parameters
+        #
+        # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+        #
+        #   _optional_ #username ― An alias for #authzid.
+        #
+        #   Note that, unlike some other authenticators, +username+ sets the
+        #   _authorization_ identity and not the _authentication_ identity.  The
+        #   authentication identity is established for the client by the
+        #   external credentials.
         #
         # Any other keyword parameters are quietly ignored.
-        def initialize(authzid: nil, **)
+        def initialize(user = nil, authzid: nil, username: nil, **)
+          authzid ||= username || user
           @authzid = authzid&.to_str&.encode "UTF-8"
           if @authzid&.match?(/\u0000/u) # also validates UTF8 encoding
             raise ArgumentError, "contains NULL"

data/lib/net/imap/sasl/login_authenticator.rb

@@ -23,12 +23,16 @@ class Net::IMAP::SASL::LoginAuthenticator
   STATE_DONE = :DONE
   private_constant :STATE_USER, :STATE_PASSWORD, :STATE_DONE
 
-  def initialize(user, password, warn_deprecation: true, **_ignored)
+  def initialize(user = nil, pass = nil,
+                 authcid: nil, username: nil,
+                 password: nil, secret: nil,
+                 warn_deprecation: true,
+                 **)
     if warn_deprecation
       warn "WARNING: LOGIN SASL mechanism is deprecated. Use PLAIN instead."
     end
-    @user = user
-    @password = password
+    @user = authcid || username || user
+    @password = password || secret || pass
     @state = STATE_USER
   end
 

data/lib/net/imap/sasl/oauthbearer_authenticator.rb

@@ -14,18 +14,25 @@ module Net
       class OAuthAuthenticator
         include GS2Header
 
-        # Authorization identity: an identity to act as or on behalf of.
+        # 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"
         #
-        # If no explicit authorization identity is provided, it is usually
-        # derived from the authentication identity.  For the OAuth-based
-        # mechanisms, the authentication identity is the identity established by
-        # the OAuth credential.
         attr_reader :authzid
+        alias username authzid
 
-        # Hostname to which the client connected.
+        # Hostname to which the client connected.  (optional)
         attr_reader :host
 
-        # Service port to which the client connected.
+        # Service port to which the client connected.  (optional)
         attr_reader :port
 
         # HTTP method.  (optional)
@@ -39,6 +46,7 @@ module Net
 
         # The query string.  (optional)
         attr_reader :qs
+        alias query qs
 
         # Stores the most recent server "challenge".  When authentication fails,
         # this may hold information about the failure reason, as JSON.
@@ -47,29 +55,42 @@ module Net
         # Creates an RFC7628[https://tools.ietf.org/html/rfc7628] OAuth
         # authenticator.
         #
-        # === Options
+        # ==== Parameters
+        #
+        # See child classes for required parameter(s).  The following parameters
+        # are all optional, but it is worth noting that <b>application protocols
+        # are allowed to require</b> #authzid (or other parameters, such as
+        # #host or #port) <b>as are specific server implementations</b>.
+        #
+        # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+        #
+        #   _optional_ #username — An alias for #authzid.
         #
-        # See child classes for required configuration parameter(s).  The
-        # following parameters are all optional, but protocols or servers may
-        # add requirements for #authzid, #host, #port, or any other parameter.
+        #   Note that, unlike some other authenticators, +username+ sets the
+        #   _authorization_ identity and not the _authentication_ identity.  The
+        #   authentication identity is established for the client by the OAuth
+        #   token.
         #
-        # * #authzid ― Identity to act as or on behalf of.
-        # * #host — Hostname to which the client connected.
-        # * #port — Service port to which the client connected.
-        # * #mthd — HTTP method
-        # * #path — HTTP path data
-        # * #post — HTTP post data
-        # * #qs   — HTTP query string
+        # * _optional_ #host — Hostname to which the client connected.
+        # * _optional_ #port — Service port to which the client connected.
+        # * _optional_ #mthd — HTTP method
+        # * _optional_ #path — HTTP path data
+        # * _optional_ #post — HTTP post data
+        # * _optional_ #qs   — HTTP query string
         #
+        #   _optional_ #query — An alias for #qs
+        #
+        # Any other keyword parameters are quietly ignored.
         def initialize(authzid: nil, host: nil, port: nil,
+                       username: nil, query: nil,
                        mthd: nil, path: nil, post: nil, qs: nil, **)
-          @authzid = authzid
+          @authzid = authzid || username
           @host    = host
           @port    = port
           @mthd    = mthd
           @path    = path
           @post    = post
-          @qs      = qs
+          @qs      = qs || query
           @done    = false
         end
 
@@ -116,35 +137,49 @@ module Net
       # the bearer token.
       class OAuthBearerAuthenticator < OAuthAuthenticator
 
-        # An OAuth2 bearer token, generally the access token.
+        # An OAuth 2.0 bearer token.  See {RFC-6750}[https://www.rfc-editor.org/rfc/rfc6750]
         attr_reader :oauth2_token
+        alias secret oauth2_token
 
         # :call-seq:
-        #   new(oauth2_token,  **options) -> authenticator
-        #   new(oauth2_token:, **options) -> authenticator
+        #   new(oauth2_token,          **options) -> authenticator
+        #   new(authzid, oauth2_token, **options) -> authenticator
+        #   new(oauth2_token:,         **options) -> authenticator
         #
         # Creates an Authenticator for the "+OAUTHBEARER+" SASL mechanism.
         #
         # Called by Net::IMAP#authenticate and similar methods on other clients.
         #
-        # === Options
+        # ==== Parameters
+        #
+        # * #oauth2_token — An OAuth2 bearer token
+        #
+        # All other keyword parameters are passed to
+        # {super}[rdoc-ref:OAuthAuthenticator::new] (see OAuthAuthenticator).
+        # The most common ones are:
+        #
+        # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+        #
+        #   _optional_ #username — An alias for #authzid.
         #
-        # Only +oauth2_token+ is required by the mechanism, however protocols
-        # and servers may add requirements for #authzid, #host, #port, or any
-        # other parameter.
+        #   Note that, unlike some other authenticators, +username+ sets the
+        #   _authorization_ identity and not the _authentication_ identity.  The
+        #   authentication identity is established for the client by
+        #   #oauth2_token.
         #
-        # * #oauth2_token — An OAuth2 bearer token or access token. *Required.*
-        #   May be provided as either regular or keyword argument.
-        # * #authzid ― Identity to act as or on behalf of.
-        # * #host — Hostname to which the client connected.
-        # * #port — Service port to which the client connected.
-        # * See OAuthAuthenticator documentation for less common parameters.
+        # * _optional_ #host — Hostname to which the client connected.
+        # * _optional_ #port — Service port to which the client connected.
         #
-        def initialize(oauth2_token_arg = nil, oauth2_token: nil, **args, &blk)
-          super(**args, &blk) # handles authzid, host, port, etc
-          oauth2_token && oauth2_token_arg and
-            raise ArgumentError, "conflicting values for oauth2_token"
-          @oauth2_token = oauth2_token || oauth2_token_arg or
+        # Although only oauth2_token is required by this mechanism, it is worth
+        # noting that <b><em>application protocols are allowed to
+        # require</em></b> #authzid (<em>or other parameters, such as</em> #host
+        # _or_ #port) <b><em>as are specific server implementations</em></b>.
+        def initialize(arg1 = nil, arg2 = nil,
+                       oauth2_token: nil, secret: nil,
+                       **args, &blk)
+          username, oauth2_token_arg = arg2.nil? ? [nil, arg1] : [arg1, arg2]
+          super(username: username, **args, &blk)
+          @oauth2_token = oauth2_token || secret || oauth2_token_arg or
             raise ArgumentError, "missing oauth2_token"
         end
 

data/lib/net/imap/sasl/plain_authenticator.rb

@@ -22,9 +22,11 @@ class Net::IMAP::SASL::PlainAuthenticator
   # RFC-4616[https://tools.ietf.org/html/rfc4616] and many later RFCs abbreviate
   # this to +authcid+.
   attr_reader :username
+  alias authcid username
 
   # A password or passphrase that matches the #username.
   attr_reader :password
+  alias secret password
 
   # 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
@@ -42,26 +44,32 @@ class Net::IMAP::SASL::PlainAuthenticator
   # :call-seq:
   #   new(username,  password,  authzid: nil, **) -> authenticator
   #   new(username:, password:, authzid: nil, **) -> authenticator
+  #   new(authcid:,  password:, authzid: nil, **) -> authenticator
   #
   # Creates an Authenticator for the "+PLAIN+" SASL mechanism.
   #
   # Called by Net::IMAP#authenticate and similar methods on other clients.
   #
-  # === Parameters
+  # ==== Parameters
   #
-  # * #username ― Identity whose +password+ is used.
-  # * #password ― Password or passphrase associated with this username+.
-  # * #authzid ― Alternate identity to act as or on behalf of.  Optional.
+  # * #authcid ― Authentication identity that is associated with #password.
   #
-  # See attribute documentation for more details.
+  #   #username ― An alias for #authcid.
+  #
+  # * #password ― A password or passphrase associated with the #authcid.
+  #
+  # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+  #
+  #   When +authzid+ is not set, the server should derive the authorization
+  #   identity from the authentication identity.
+  #
+  # Any other keyword parameters are quietly ignored.
   def initialize(user = nil, pass = nil,
+                 authcid: nil, secret: nil,
                  username: nil, password: nil, authzid: nil, **)
-    [username, user].compact.count == 1 or
-      raise ArgumentError, "conflicting values for username"
-    [password, pass].compact.count == 1 or
-      raise ArgumentError, "conflicting values for password"
-    username ||= user or raise ArgumentError, "missing username"
-    password ||= pass or raise ArgumentError, "missing password"
+    username ||= authcid || user or
+      raise ArgumentError, "missing username (authcid)"
+    password ||= secret || pass or raise ArgumentError, "missing password"
     raise ArgumentError, "username contains NULL" if username.include?(NULL)
     raise ArgumentError, "password contains NULL" if password.include?(NULL)
     raise ArgumentError, "authzid contains NULL"  if authzid&.include?(NULL)

data/lib/net/imap/sasl/protocol_adapters.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      module ProtocolAdapters
+        # This API is experimental, and may change.
+        module Generic
+          def command_name;     "AUTHENTICATE" end
+          def service;          raise "Implement in subclass or module" end
+          def host;             client.host end
+          def port;             client.port end
+          def encode_ir(string) string.empty? ? "=" : encode(string) end
+          def encode(string)    [string].pack("m0") end
+          def decode(string)    string.unpack1("m0") end
+          def cancel_response;  "*" end
+        end
+
+        # See RFC-3501 (IMAP4rev1), RFC-4959 (SASL-IR capability),
+        # and RFC-9051 (IMAP4rev2).
+        module IMAP
+          include Generic
+          def service; "imap" end
+        end
+
+        # See RFC-4954 (AUTH capability).
+        module SMTP
+          include Generic
+          def command_name; "AUTH" end
+          def service; "smtp" end
+        end
+
+        # See RFC-5034 (SASL capability).
+        module POP
+          include Generic
+          def command_name; "AUTH" end
+          def service; "pop" end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/net/imap/sasl/scram_authenticator.rb

@@ -60,6 +60,7 @@ module Net
         # :call-seq:
         #   new(username,  password,  **options) -> auth_ctx
         #   new(username:, password:, **options) -> auth_ctx
+        #   new(authcid:,  password:, **options) -> auth_ctx
         #
         # Creates an authenticator for one of the "+SCRAM-*+" SASL mechanisms.
         # Each subclass defines #digest to match a specific mechanism.
@@ -68,39 +69,47 @@ module Net
         #
         # === Parameters
         #
-        # * #username ― Identity whose #password is used.  Aliased as #authcid.
+        # * #authcid  ― Identity whose #password is used.
+        #
+        #   #username - An alias for #authcid.
         # * #password ― Password or passphrase associated with this #username.
-        # * #authzid ― Alternate identity to act as or on behalf of.  Optional.
-        # * #min_iterations - Overrides the default value (4096).  Optional.
+        # * _optional_ #authzid ― Alternate identity to act as or on behalf of.
+        # * _optional_ #min_iterations - Overrides the default value (4096).
         #
-        # See the documentation on the corresponding attributes for more.
+        # Any other keyword parameters are quietly ignored.
         def initialize(username_arg = nil, password_arg = nil,
-                       username: nil, password: nil, authcid: nil, authzid: nil,
+                       authcid: nil, username: nil,
+                       authzid: nil,
+                       password: nil, secret: nil,
                        min_iterations: 4096, # see both RFC5802 and RFC7677
                        cnonce: nil, # must only be set in tests
                        **options)
           @username = username || username_arg || authcid or
             raise ArgumentError, "missing username (authcid)"
-          [username, username_arg, authcid].compact.count == 1 or
-            raise ArgumentError, "conflicting values for username (authcid)"
-          @password = password || password_arg or
+          @password = password || secret || password_arg or
             raise ArgumentError, "missing password"
-          [password, password_arg].compact.count == 1 or
-            raise ArgumentError, "conflicting values for password"
           @authzid = authzid
 
           @min_iterations = Integer min_iterations
           @min_iterations.positive? or
             raise ArgumentError, "min_iterations must be positive"
+
           @cnonce = cnonce || SecureRandom.base64(32)
         end
 
         # 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
+        # this to +authcid+.
         attr_reader :username
         alias authcid username
 
         # A password or passphrase that matches the #username.
         attr_reader :password
+        alias secret password
 
         # Authorization identity: an identity to act as or on behalf of.  The
         # identity form is application protocol specific.  If not provided or

data/lib/net/imap/sasl/xoauth2_authenticator.rb

@@ -6,9 +6,10 @@
 # Google[https://developers.google.com/gmail/imap/xoauth2-protocol] and
 # Microsoft[https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth].
 #
-# This mechanism requires an OAuth2 +access_token+ which has been authorized
-# with the appropriate OAuth2 scopes to access IMAP.  These scopes are not
-# standardized---consult each email service provider's documentation.
+# This mechanism requires an OAuth2 access token which has been authorized
+# with the appropriate OAuth2 scopes to access the user's services.  Most of
+# these scopes are not standardized---consult each service provider's
+# documentation for their scopes.
 #
 # Although this mechanism was never standardized and has been obsoleted by
 # "+OAUTHBEARER+", it is still very widely supported.
@@ -19,21 +20,34 @@ class Net::IMAP::SASL::XOAuth2Authenticator
   # It is unclear from {Google's original XOAUTH2
   # documentation}[https://developers.google.com/gmail/imap/xoauth2-protocol],
   # whether "User" refers to the authentication identity (+authcid+) or the
-  # authorization identity (+authzid+).  It appears to behave as +authzid+.
+  # authorization identity (+authzid+).  The authentication identity is
+  # established for the client by the OAuth token, so it seems that +username+
+  # must be the authorization identity.
   #
   # {Microsoft's documentation for shared
   # mailboxes}[https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#sasl-xoauth2-authentication-for-shared-mailboxes-in-office-365]
-  # clearly indicate that the Office 365 server interprets it as the
+  # _clearly_ indicates that the Office 365 server interprets it as the
   # authorization identity.
+  #
+  # Although they _should_ validate that the token has been authorized to access
+  # the service for +username+, _some_ servers appear to ignore this field,
+  # relying only the identity and scope authorized by the token.
   attr_reader :username
 
+  # Note that, unlike most other authenticators, #username is an alias for the
+  # authorization identity and not the authentication identity.  The
+  # authenticated identity is established for the client by the #oauth2_token.
+  alias authzid username
+
   # An OAuth2 access token which has been authorized with the appropriate OAuth2
   # scopes to use the service for #username.
   attr_reader :oauth2_token
+  alias secret oauth2_token
 
   # :call-seq:
   #   new(username,  oauth2_token,  **) -> authenticator
   #   new(username:, oauth2_token:, **) -> authenticator
+  #   new(authzid:,  oauth2_token:, **) -> authenticator
   #
   # Creates an Authenticator for the "+XOAUTH2+" SASL mechanism, as specified by
   # Google[https://developers.google.com/gmail/imap/xoauth2-protocol],
@@ -43,26 +57,30 @@ class Net::IMAP::SASL::XOAuth2Authenticator
   # === Properties
   #
   # * #username --- the username for the account being accessed.
+  #
+  #   #authzid  --- an alias for #username.
+  #
+  #   Note that, unlike some other authenticators, +username+ sets the
+  #   _authorization_ identity and not the _authentication_ identity.  The
+  #   authenticated identity is established for the client with the OAuth token.
+  #
   # * #oauth2_token --- An OAuth2.0 access token which is authorized to access
   #   the service for #username.
   #
-  # See the documentation for each attribute for more details.
-  def initialize(user = nil, token = nil, username: nil, oauth2_token: nil, **)
-    @username = username || user or
-      raise ArgumentError, "missing username"
-    @oauth2_token = oauth2_token || token or
+  # Any other keyword parameters are quietly ignored.
+  def initialize(user = nil, token = nil, username: nil, oauth2_token: nil,
+                 authzid: nil, secret: nil, **)
+    @username = authzid || username || user or
+      raise ArgumentError, "missing username (authzid)"
+    @oauth2_token = oauth2_token || secret || token or
       raise ArgumentError, "missing oauth2_token"
-    [username, user].compact.count == 1 or
-      raise ArgumentError, "conflicting values for username"
-    [oauth2_token, token].compact.count == 1 or
-      raise ArgumentError, "conflicting values for oauth2_token"
     @done = false
   end
 
   # :call-seq:
   #   initial_response? -> true
   #
-  # +PLAIN+ can send an initial client response.
+  # +XOAUTH2+ can send an initial client response.
   def initial_response?; true end
 
   # Returns the XOAUTH2 formatted response, which combines the +username+

data/lib/net/imap/sasl.rb

@@ -135,6 +135,10 @@ module Net
       autoload :BidiStringError,     sasl_stringprep_rb
 
       sasl_dir = File.expand_path("sasl", __dir__)
+      autoload :AuthenticationExchange,   "#{sasl_dir}/authentication_exchange"
+      autoload :ClientAdapter,            "#{sasl_dir}/client_adapter"
+      autoload :ProtocolAdapters,         "#{sasl_dir}/protocol_adapters"
+
       autoload :Authenticators,           "#{sasl_dir}/authenticators"
       autoload :GS2Header,                "#{sasl_dir}/gs2_header"
       autoload :ScramAlgorithm,           "#{sasl_dir}/scram_algorithm"
@@ -155,8 +159,10 @@ module Net
       # Returns the default global SASL::Authenticators instance.
       def self.authenticators; @authenticators ||= Authenticators.new end
 
-      # Delegates to ::authenticators.  See Authenticators#authenticator.
-      def self.authenticator(...)     authenticators.authenticator(...) end
+      # Delegates to <tt>registry.new</tt>  See Authenticators#new.
+      def self.authenticator(*args, registry: authenticators, **kwargs, &block)
+        registry.new(*args, **kwargs, &block)
+      end
 
       # Delegates to ::authenticators.  See Authenticators#add_authenticator.
       def self.add_authenticator(...) authenticators.add_authenticator(...) end

data/lib/net/imap/sasl_adapter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+
+    # Experimental
+    class SASLAdapter < SASL::ClientAdapter
+      include SASL::ProtocolAdapters::IMAP
+
+      RESPONSE_ERRORS = [NoResponseError, BadResponseError, ByeResponseError]
+        .freeze
+
+      def response_errors;          RESPONSE_ERRORS                 end
+      def sasl_ir_capable?;         client.capable?("SASL-IR")      end
+      def auth_capable?(mechanism); client.auth_capable?(mechanism) end
+      def drop_connection;          client.logout!                  end
+      def drop_connection!;         client.disconnect               end
+    end
+
+  end
+end

data/lib/net/imap.rb

@@ -127,7 +127,7 @@ module Net
   #   end
   #
   #   # Support for "UTF8=ACCEPT" implies support for "ENABLE"
-  #   imap.enable :utf8 if imap.auth_capable?("UTF8=ACCEPT")
+  #   imap.enable :utf8 if imap.capable?("UTF8=ACCEPT")
   #
   #   namespaces  = imap.namespace if imap.capable?(:namespace)
   #   mbox_prefix = namespaces&.personal&.first&.prefix || ""
@@ -662,7 +662,7 @@ module Net
   # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.4.0"
+    VERSION = "0.4.2"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -670,8 +670,9 @@ module Net
       "UTF8=ONLY" => "UTF8=ACCEPT",
     }.freeze
 
-    autoload :SASL,       File.expand_path("imap/sasl",       __dir__)
-    autoload :StringPrep, File.expand_path("imap/stringprep", __dir__)
+    autoload :SASL,        File.expand_path("imap/sasl",         __dir__)
+    autoload :SASLAdapter, File.expand_path("imap/sasl_adapter", __dir__)
+    autoload :StringPrep,  File.expand_path("imap/stringprep",   __dir__)
 
     include MonitorMixin
     if defined?(OpenSSL::SSL)
@@ -1142,7 +1143,10 @@ module Net
     end
 
     # :call-seq:
-    #   authenticate(mechanism, *, sasl_ir: true, **, &) -> ok_resp
+    #   authenticate(mechanism, *,
+    #                sasl_ir: true,
+    #                registry: Net::IMAP::SASL.authenticators,
+    #                **, &) -> ok_resp
     #
     # Sends an {AUTHENTICATE command [IMAP4rev1 §6.2.2]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.2]
     # to authenticate the client.  If successful, the connection enters the
@@ -1886,8 +1890,7 @@ module Net
     # +attr+ is a list of attributes to fetch; see the documentation
     # for FetchData for a list of valid attributes.
     #
-    # The return value is an array of FetchData or nil
-    # (instead of an empty array) if there is no matching message.
+    # The return value is an array of FetchData.
     #
     # Related: #uid_search, FetchData
     #
@@ -2747,6 +2750,10 @@ module Net
       end
     end
 
+    def sasl_adapter
+      SASLAdapter.new(self, &method(:send_command_with_continuations))
+    end
+
     #--
     # We could get the saslprep method by extending the SASLprep module
     # directly.  It's done indirectly, so SASLprep can be lazily autoloaded,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Shugo Maeda
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-04 00:00:00.000000000 Z
+date: 2023-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -100,7 +100,9 @@ files:
 - lib/net/imap/response_parser/parser_utils.rb
 - lib/net/imap/sasl.rb
 - lib/net/imap/sasl/anonymous_authenticator.rb
+- lib/net/imap/sasl/authentication_exchange.rb
 - lib/net/imap/sasl/authenticators.rb
+- lib/net/imap/sasl/client_adapter.rb
 - lib/net/imap/sasl/cram_md5_authenticator.rb
 - lib/net/imap/sasl/digest_md5_authenticator.rb
 - lib/net/imap/sasl/external_authenticator.rb
@@ -108,10 +110,12 @@ files:
 - lib/net/imap/sasl/login_authenticator.rb
 - lib/net/imap/sasl/oauthbearer_authenticator.rb
 - lib/net/imap/sasl/plain_authenticator.rb
+- lib/net/imap/sasl/protocol_adapters.rb
 - lib/net/imap/sasl/scram_algorithm.rb
 - lib/net/imap/sasl/scram_authenticator.rb
 - lib/net/imap/sasl/stringprep.rb
 - lib/net/imap/sasl/xoauth2_authenticator.rb
+- lib/net/imap/sasl_adapter.rb
 - lib/net/imap/stringprep.rb
 - lib/net/imap/stringprep/nameprep.rb
 - lib/net/imap/stringprep/saslprep.rb