net-imap 0.3.4 → 0.4.1

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

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+require_relative "gs2_header"
+require_relative "scram_algorithm"
+
+module Net
+  class IMAP
+    module SASL
+
+      # Abstract base class for the "+SCRAM-*+" family of SASL mechanisms,
+      # defined in RFC5802[https://tools.ietf.org/html/rfc5802].  Use via
+      # Net::IMAP#authenticate.
+      #
+      # Directly supported:
+      # * +SCRAM-SHA-1+   --- ScramSHA1Authenticator
+      # * +SCRAM-SHA-256+ --- ScramSHA256Authenticator
+      #
+      # New +SCRAM-*+ mechanisms can easily be added for any hash algorithm
+      # supported by
+      # OpenSSL::Digest[https://ruby.github.io/openssl/OpenSSL/Digest.html].
+      # Subclasses need only set an appropriate +DIGEST_NAME+ constant.
+      #
+      # === SCRAM algorithm
+      #
+      # See the documentation and method definitions on ScramAlgorithm for an
+      # overview of the algorithm.  The different mechanisms differ only by
+      # which hash function that is used (or by support for channel binding with
+      # +-PLUS+).
+      #
+      # See also the methods on GS2Header.
+      #
+      # ==== Server messages
+      #
+      # As server messages are received, they are validated and loaded into
+      # the various attributes, e.g: #snonce, #salt, #iterations, #verifier,
+      # #server_error, etc.
+      #
+      # Unlike many other SASL mechanisms, the +SCRAM-*+ family supports mutual
+      # authentication and can return server error data in the server messages.
+      # If #process raises an Error for the server-final-message, then
+      # server_error may contain error details.
+      #
+      # === TLS Channel binding
+      #
+      # <em>The <tt>SCRAM-*-PLUS</tt> mechanisms and channel binding are not
+      # supported yet.</em>
+      #
+      # === Caching SCRAM secrets
+      #
+      # <em>Caching of salted_password, client_key, stored_key, and server_key
+      # is not supported yet.</em>
+      #
+      class ScramAuthenticator
+        include GS2Header
+        include ScramAlgorithm
+
+        # :call-seq:
+        #   new(username,  password,  **options) -> auth_ctx
+        #   new(username:, password:, **options) -> auth_ctx
+        #
+        # Creates an authenticator for one of the "+SCRAM-*+" SASL mechanisms.
+        # Each subclass defines #digest to match a specific mechanism.
+        #
+        # Called by Net::IMAP#authenticate and similar methods on other clients.
+        #
+        # === Parameters
+        #
+        # * #username ― Identity whose #password is used.  Aliased as #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.
+        #
+        # See the documentation on the corresponding attributes for more.
+        def initialize(username_arg = nil, password_arg = nil,
+                       username: nil, password: nil, authcid: nil, authzid: 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
+            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.
+        attr_reader :username
+        alias authcid username
+
+        # A password or passphrase that matches the #username.
+        attr_reader :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 server derives an authorization identity from the
+        # authentication identity.  For example, an administrator or superuser
+        # might take on another role:
+        #
+        #     imap.authenticate "SCRAM-SHA-256", "root", passwd, authzid: "user"
+        #
+        # 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.
+        attr_reader :authzid
+
+        # The minimal allowed iteration count.  Lower #iterations will raise an
+        # Error.
+        attr_reader :min_iterations
+
+        # The client nonce, generated by SecureRandom
+        attr_reader :cnonce
+
+        # The server nonce, which must start with #cnonce
+        attr_reader :snonce
+
+        # The salt used by the server for this user
+        attr_reader :salt
+
+        # The iteration count for the selected hash function and user
+        attr_reader :iterations
+
+        # An error reported by the server during the \SASL exchange.
+        #
+        # Does not include errors reported by the protocol, e.g.
+        # Net::IMAP::NoResponseError.
+        attr_reader :server_error
+
+        # Returns a new OpenSSL::Digest object, set to the appropriate hash
+        # function for the chosen mechanism.
+        #
+        # <em>The class's +DIGEST_NAME+ constant must be set to the name of an
+        # algorithm supported by OpenSSL::Digest.</em>
+        def digest; OpenSSL::Digest.new self.class::DIGEST_NAME end
+
+        # See {RFC5802 §7}[https://www.rfc-editor.org/rfc/rfc5802#section-7]
+        # +client-first-message+.
+        def initial_client_response
+          "#{gs2_header}#{client_first_message_bare}"
+        end
+
+        # responds to the server's challenges
+        def process(challenge)
+          case (@state ||= :initial_client_response)
+          when :initial_client_response
+            initial_client_response.tap { @state = :server_first_message }
+          when :server_first_message
+            recv_server_first_message challenge
+            final_message_with_proof.tap { @state = :server_final_message }
+          when :server_final_message
+            recv_server_final_message challenge
+            "".tap { @state = :done }
+          else
+            raise Error, "server sent after complete, %p" % [challenge]
+          end
+        rescue Exception => ex
+          @state = ex
+          raise
+        end
+
+        # Is the authentication exchange complete?
+        #
+        # If false, another server continuation is required.
+        def done?; @state == :done end
+
+        private
+
+        # Need to store this for auth_message
+        attr_reader :server_first_message
+
+        def format_message(hash) hash.map { _1.join("=") }.join(",") end
+
+        def recv_server_first_message(server_first_message)
+          @server_first_message = server_first_message
+          sparams = parse_challenge server_first_message
+          @snonce = sparams["r"] or
+            raise Error, "server did not send nonce"
+          @salt = sparams["s"]&.unpack1("m") or
+            raise Error, "server did not send salt"
+          @iterations = sparams["i"]&.then {|i| Integer i } or
+            raise Error, "server did not send iteration count"
+          min_iterations <= iterations or
+            raise Error, "too few iterations: %d" % [iterations]
+          mext = sparams["m"] and
+            raise Error, "mandatory extension: %p" % [mext]
+          snonce.start_with? cnonce or
+            raise Error, "invalid server nonce"
+        end
+
+        def recv_server_final_message(server_final_message)
+          sparams = parse_challenge server_final_message
+          @server_error = sparams["e"] and
+            raise Error, "server error: %s" % [server_error]
+          verifier = sparams["v"].unpack1("m") or
+            raise Error, "server did not send verifier"
+          verifier == server_signature or
+            raise Error, "server verify failed: %p != %p" % [
+              server_signature, verifier
+            ]
+        end
+
+        # See {RFC5802 §7}[https://www.rfc-editor.org/rfc/rfc5802#section-7]
+        # +client-first-message-bare+.
+        def client_first_message_bare
+          @client_first_message_bare ||=
+            format_message(n: gs2_saslname_encode(SASL.saslprep(username)),
+                           r: cnonce)
+        end
+
+        # See {RFC5802 §7}[https://www.rfc-editor.org/rfc/rfc5802#section-7]
+        # +client-final-message+.
+        def final_message_with_proof
+          proof = [client_proof].pack("m0")
+          "#{client_final_message_without_proof},p=#{proof}"
+        end
+
+        # See {RFC5802 §7}[https://www.rfc-editor.org/rfc/rfc5802#section-7]
+        # +client-final-message-without-proof+.
+        def client_final_message_without_proof
+          @client_final_message_without_proof ||=
+            format_message(c: [cbind_input].pack("m0"), # channel-binding
+                           r: snonce)                   # nonce
+        end
+
+        # See {RFC5802 §7}[https://www.rfc-editor.org/rfc/rfc5802#section-7]
+        # +cbind-input+.
+        #
+        # >>>
+        #   *TODO:* implement channel binding, appending +cbind-data+ here.
+        alias cbind_input gs2_header
+
+        # RFC5802 specifies "that the order of attributes in client or server
+        # messages is fixed, with the exception of extension attributes", but
+        # this parses it simply as a hash, without respect to order.  Note that
+        # repeated keys (violating the spec) will use the last value.
+        def parse_challenge(challenge)
+          challenge.split(/,/).to_h {|pair| pair.split(/=/, 2) }
+        rescue ArgumentError
+          raise Error, "unparsable challenge: %p" % [challenge]
+        end
+
+      end
+
+      # Authenticator for the "+SCRAM-SHA-1+" SASL mechanism, defined in
+      # RFC5802[https://tools.ietf.org/html/rfc5802].
+      #
+      # Uses the "SHA-1" digest algorithm from OpenSSL::Digest.
+      #
+      # See ScramAuthenticator.
+      class ScramSHA1Authenticator < ScramAuthenticator
+        DIGEST_NAME = "SHA1"
+      end
+
+      # Authenticator for the "+SCRAM-SHA-256+" SASL mechanism, defined in
+      # RFC7677[https://tools.ietf.org/html/rfc7677].
+      #
+      # Uses the "SHA-256" digest algorithm from OpenSSL::Digest.
+      #
+      # See ScramAuthenticator.
+      class ScramSHA256Authenticator < ScramAuthenticator
+        DIGEST_NAME = "SHA256"
+      end
+
+    end
+  end
+end

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

@@ -1,72 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "stringprep_tables"
-
 module Net::IMAP::SASL
 
-  # Regexps and utility methods for implementing stringprep profiles.  The
-  # \StringPrep algorithm is defined by
-  # {RFC-3454}[https://www.rfc-editor.org/rfc/rfc3454.html].  Each
-  # codepoint table defined in the RFC-3454 appendices is matched by a Regexp
-  # defined in this module.
-  #--
-  # TODO: generic StringPrep mapping (not needed for SASLprep implementation)
-  #++
-  module StringPrep
-
-    # Returns a Regexp matching the given +table+ name.
-    def self.[](table)
-      TABLE_REGEXPS.fetch(table)
-    end
-
-    module_function
-
-    # Checks +string+ for any codepoint in +tables+. Raises a
-    # ProhibitedCodepoint describing the first matching table.
-    #
-    # Also checks bidirectional characters, when <tt>bidi: true</tt>, which may
-    # raise a BidiStringError.
-    #
-    # +profile+ is an optional string which will be added to any exception that
-    # is raised (it does not affect behavior).
-    def check_prohibited!(string, *tables, bidi: false, profile: nil)
-      tables = TABLE_TITLES.keys.grep(/^C/) if tables.empty?
-      tables |= %w[C.8] if bidi
-      table = tables.find {|t| TABLE_REGEXPS[t].match?(string) }
-      raise ProhibitedCodepoint.new(
-        table, string: string, profile: nil
-      ) if table
-      check_bidi!(string, profile: profile) if bidi
-    end
-
-    # Checks that +string+ obeys all of the "Bidirectional Characters"
-    # requirements in RFC-3454, §6:
-    #
-    # * The characters in \StringPrep\[\"C.8\"] MUST be prohibited
-    # * If a string contains any RandALCat character, the string MUST NOT
-    #   contain any LCat character.
-    # * If a string contains any RandALCat character, a RandALCat
-    #   character MUST be the first character of the string, and a
-    #   RandALCat character MUST be the last character of the string.
-    #
-    # This is usually combined with #check_prohibited!, so table "C.8" is only
-    # checked when <tt>c_8: true</tt>.
-    #
-    # Raises either ProhibitedCodepoint or BidiStringError unless all
-    # requirements are met.  +profile+ is an optional string which will be
-    # added to any exception that is raised (it does not affect behavior).
-    def check_bidi!(string, c_8: false, profile: nil)
-      check_prohibited!(string, "C.8", profile: profile) if c_8
-      if BIDI_FAILS_REQ2.match?(string)
-        raise BidiStringError.new(
-          BIDI_DESC_REQ2, string: string, profile: profile,
-        )
-      elsif BIDI_FAILS_REQ3.match?(string)
-        raise BidiStringError.new(
-          BIDI_DESC_REQ3, string: string, profile: profile,
-        )
-      end
-    end
+  # Alias for Net::IMAP::StringPrep::SASLprep.
+  SASLprep            = Net::IMAP::StringPrep::SASLprep
+  StringPrep          = Net::IMAP::StringPrep                      # :nodoc:
+  BidiStringError     = Net::IMAP::StringPrep::BidiStringError     # :nodoc:
+  ProhibitedCodepoint = Net::IMAP::StringPrep::ProhibitedCodepoint # :nodoc:
+  StringPrepError     = Net::IMAP::StringPrep::StringPrepError     # :nodoc:
 
-  end
 end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Authenticator for the "+XOAUTH2+" SASL mechanism.  This mechanism was
+# originally created for GMail and widely adopted by hosted email providers.
+# +XOAUTH2+ has been documented by
+# 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.
+#
+# Although this mechanism was never standardized and has been obsoleted by
+# "+OAUTHBEARER+", it is still very widely supported.
+#
+# See Net::IMAP::SASL:: OAuthBearerAuthenticator.
+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+.
+  #
+  # {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
+  # authorization identity.
+  attr_reader :username
+
+  # An OAuth2 access token which has been authorized with the appropriate OAuth2
+  # scopes to use the service for #username.
+  attr_reader :oauth2_token
+
+  # :call-seq:
+  #   new(username,  oauth2_token,  **) -> authenticator
+  #   new(username:, oauth2_token:, **) -> authenticator
+  #
+  # Creates an Authenticator for the "+XOAUTH2+" SASL mechanism, as specified by
+  # Google[https://developers.google.com/gmail/imap/xoauth2-protocol],
+  # Microsoft[https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth]
+  # and Yahoo[https://senders.yahooinc.com/developer/documentation].
+  #
+  # === Properties
+  #
+  # * #username --- the username for the account being accessed.
+  # * #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
+      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.
+  def initial_response?; true end
+
+  # Returns the XOAUTH2 formatted response, which combines the +username+
+  # with the +oauth2_token+.
+  def process(_data)
+    build_oauth2_string(@username, @oauth2_token)
+  ensure
+    @done = true
+  end
+
+  # Returns true when the initial client response was sent.
+  #
+  # The authentication should not succeed unless this returns true, but it
+  # does *not* indicate success.
+  def done?; @done end
+
+  private
+
+  def build_oauth2_string(username, oauth2_token)
+    format("user=%s\1auth=Bearer %s\1\1", username, oauth2_token)
+  end
+
+end

data/lib/net/imap/sasl.rb

@@ -6,12 +6,11 @@ module Net
     # Pluggable authentication mechanisms for protocols which support SASL
     # (Simple Authentication and Security Layer), such as IMAP4, SMTP, LDAP, and
     # XMPP.  {RFC-4422}[https://tools.ietf.org/html/rfc4422] specifies the
-    # common SASL framework and the +EXTERNAL+ mechanism, and the
-    # {SASL mechanism registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
-    # lists the specification for others.
-    #
-    # "SASL is conceptually a framework that provides an abstraction layer
-    # between protocols and mechanisms as illustrated in the following diagram."
+    # common \SASL framework:
+    # >>>
+    #   SASL is conceptually a framework that provides an abstraction layer
+    #   between protocols and mechanisms as illustrated in the following
+    #   diagram.
     #
     #               SMTP    LDAP    XMPP   Other protocols ...
     #                  \       |    |      /
@@ -21,58 +20,160 @@ module Net
     #                  /       |    |      \
     #           EXTERNAL   GSSAPI  PLAIN   Other mechanisms ...
     #
+    # Net::IMAP uses SASL via the Net::IMAP#authenticate method.
+    #
+    # == Mechanisms
+    #
+    # Each mechanism has different properties and requirements.  Please consult
+    # the documentation for the specific mechanisms you are using:
+    #
+    # +ANONYMOUS+::
+    #     See AnonymousAuthenticator.
+    #
+    #     Allows the user to gain access to public services or resources without
+    #     authenticating or disclosing an identity.
+    #
+    # +EXTERNAL+::
+    #     See ExternalAuthenticator.
+    #
+    #     Authenticates using already established credentials, such as a TLS
+    #     certificate or IPsec.
+    #
+    # +OAUTHBEARER+::
+    #     See OAuthBearerAuthenticator.
+    #
+    #     Login using an OAuth2 Bearer token.  This is the standard mechanism
+    #     for using OAuth2 with \SASL, but it is not yet deployed as widely as
+    #     +XOAUTH2+.
+    #
+    # +PLAIN+::
+    #     See PlainAuthenticator.
+    #
+    #     Login using clear-text username and password.
+    #
+    # +SCRAM-SHA-1+::
+    # +SCRAM-SHA-256+::
+    #     See ScramAuthenticator.
+    #
+    #     Login by username and password.  The password is not sent to the
+    #     server but is used in a salted challenge/response exchange.
+    #     +SCRAM-SHA-1+ and +SCRAM-SHA-256+ are directly supported by
+    #     Net::IMAP::SASL.  New authenticators can easily be added for any other
+    #     <tt>SCRAM-*</tt> mechanism if the digest algorithm is supported by
+    #     OpenSSL::Digest.
+    #
+    # +XOAUTH2+::
+    #     See XOAuth2Authenticator.
+    #
+    #     Login using a username and an OAuth2 access token.  Non-standard and
+    #     obsoleted by +OAUTHBEARER+, but widely supported.
+    #
+    # See the {SASL mechanism
+    # registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
+    # for a list of all SASL mechanisms and their specifications.  To register
+    # new authenticators, see Authenticators.
+    #
+    # === Deprecated mechanisms
+    #
+    # <em>Obsolete mechanisms should be avoided, but are still available for
+    # backwards compatibility.</em>
+    #
+    # >>>
+    #   For +DIGEST-MD5+ see DigestMD5Authenticator.
+    #
+    #   For +LOGIN+, see LoginAuthenticator.
+    #
+    #   For +CRAM-MD5+, see CramMD5Authenticator.
+    #
+    # <em>Using a deprecated mechanism will print a warning.</em>
+    #
     module SASL
+      # Exception class for any client error detected during the authentication
+      # exchange.
+      #
+      # When the _server_ reports an authentication failure, it will respond
+      # with a protocol specific error instead, e.g: +BAD+ or +NO+ in IMAP.
+      #
+      # When the client encounters any error, it *must* consider the
+      # authentication exchange to be unsuccessful and it might need to drop the
+      # connection.  For example, if the server reports that the authentication
+      # exchange was successful or the protocol does not allow additional
+      # authentication attempts.
+      Error = Class.new(StandardError)
 
-      # autoloading to avoid loading all of the regexps when they aren't used.
+      # Indicates an authentication exchange that will be or has been canceled
+      # by the client, not due to any error or failure during processing.
+      AuthenticationCanceled = Class.new(Error)
 
-      autoload :StringPrep, File.expand_path("sasl/stringprep", __dir__)
-      autoload :SASLprep, File.expand_path("#{__dir__}/sasl/saslprep", __dir__)
+      # Indicates an error when processing a server challenge, e.g: an invalid
+      # or unparsable challenge.  An underlying exception may be available as
+      # the exception's #cause.
+      AuthenticationError = Class.new(Error)
 
-      # ArgumentError raised when +string+ is invalid for the stringprep
-      # +profile+.
-      class StringPrepError < ArgumentError
-        attr_reader :string, :profile
+      # Indicates that authentication cannot proceed because one of the server's
+      # messages has not passed integrity checks.
+      AuthenticationFailed = Class.new(Error)
 
-        def initialize(*args, string: nil, profile: nil)
-          @string  = -string.to_str  unless string.nil?
-          @profile = -profile.to_str unless profile.nil?
-          super(*args)
-        end
-      end
+      # Indicates that authentication cannot proceed because one of the server's
+      # ended authentication prematurely.
+      class AuthenticationIncomplete < AuthenticationFailed
+        # The success response from the server
+        attr_reader :response
 
-      # StringPrepError raised when +string+ contains a codepoint prohibited by
-      # +table+.
-      class ProhibitedCodepoint < StringPrepError
-        attr_reader :table
-
-        def initialize(table, *args, **kwargs)
-          @table = -table.to_str
-          details = (title = StringPrep::TABLE_TITLES[table]) ?
-            "%s [%s]" % [title, table] : table
-          message = "String contains a prohibited codepoint: %s" % [details]
-          super(message, *args, **kwargs)
+        def initialize(response, message = "authentication ended prematurely")
+          super(message)
+          @response = response
         end
       end
 
-      # StringPrepError raised when +string+ contains bidirectional characters
-      # which violate the StringPrep requirements.
-      class BidiStringError < StringPrepError
+      # autoloading to avoid loading all of the regexps when they aren't used.
+      sasl_stringprep_rb = File.expand_path("sasl/stringprep", __dir__)
+      autoload :StringPrep,          sasl_stringprep_rb
+      autoload :SASLprep,            sasl_stringprep_rb
+      autoload :StringPrepError,     sasl_stringprep_rb
+      autoload :ProhibitedCodepoint, sasl_stringprep_rb
+      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"
+
+      autoload :AnonymousAuthenticator,   "#{sasl_dir}/anonymous_authenticator"
+      autoload :ExternalAuthenticator,    "#{sasl_dir}/external_authenticator"
+      autoload :OAuthBearerAuthenticator, "#{sasl_dir}/oauthbearer_authenticator"
+      autoload :PlainAuthenticator,       "#{sasl_dir}/plain_authenticator"
+      autoload :ScramAuthenticator,       "#{sasl_dir}/scram_authenticator"
+      autoload :ScramSHA1Authenticator,   "#{sasl_dir}/scram_authenticator"
+      autoload :ScramSHA256Authenticator, "#{sasl_dir}/scram_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"
+
+      # Returns the default global SASL::Authenticators instance.
+      def self.authenticators; @authenticators ||= Authenticators.new end
+
+      # Delegates to <tt>registry.new</tt>  See Authenticators#new.
+      def self.authenticator(*args, registry: authenticators, **kwargs, &block)
+        registry.new(*args, **kwargs, &block)
       end
 
-      #--
-      # We could just extend SASLprep module directly.  It's done this way so
-      # SASLprep can be lazily autoloaded.  Most users won't need it.
-      #++
-      extend self
+      # Delegates to ::authenticators.  See Authenticators#add_authenticator.
+      def self.add_authenticator(...) authenticators.add_authenticator(...) end
+
+      module_function
 
-      # See SASLprep#saslprep.
+      # See Net::IMAP::StringPrep::SASLprep#saslprep.
       def saslprep(string, **opts)
-        SASLprep.saslprep(string, **opts)
+        Net::IMAP::StringPrep::SASLprep.saslprep(string, **opts)
       end
 
     end
   end
-
 end
-
-Net::IMAP.extend Net::IMAP::SASL

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