♻️ SASL XOAUTH2: inherit, move, test, document

* ♻️  Inherit from Authenticator base class
* 🚚 Move to SASL module and rename file
* ✅ Add new tests
* 📖 Add many many docs
* ✨ Add `initial_response? => true`

Author: nevans

lib/net/imap.rb

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

lib/net/imap/authenticators.rb

@@ -68,8 +68,9 @@ def authenticators
 Net::IMAP.extend Net::IMAP::Authenticators
 
 require_relative "sasl/plain_authenticator"
+require_relative "sasl/xoauth2_authenticator"
 
+# deprecated
 require_relative "authenticators/login"
 require_relative "authenticators/cram_md5"
 require_relative "authenticators/digest_md5"
-require_relative "authenticators/xoauth2"

lib/net/imap/authenticators/xoauth2.rb

@@ -22,7 +22,7 @@ module SASL
       # +PLAIN+::     See SASL::PlainAuthenticator.
       #               Login using clear-text username and password.
       #
-      # +XOAUTH2+::   See XOauth2Authenticator.
+      # +XOAUTH2+::   See SASL::XOAuth2Authenticator.
       #               Login using a username and OAuth2 access token.
       #               Non-standard and obsoleted by +OAUTHBEARER+, but widely
       #               supported.

lib/net/imap/sasl/authenticator.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "authenticator"
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # 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],
+      # 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].
+      #
+      # 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.
+      class XOAuth2Authenticator < Authenticator
+        register Net::IMAP
+
+        ##
+        # :call-seq:
+        #   new(username,  oauth2_token,  **)       -> auth_ctx
+        #   new(authcid:,  oauth2_token:, **)       -> auth_ctx
+        #   new(**) {|propname, auth_ctx| propval } -> auth_ctx
+        #
+        # Creates an Authenticator for the "+XOAUTH2+" SASL mechanism, as
+        # specified by
+        # Google[https://developers.google.com/gmail/imap/xoauth2-protocol], and
+        # also documented by
+        # 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].  To use
+        # this, see Net::IMAP#authenticate or your client's authentication
+        # method.
+        #
+        # === Properties
+        #
+        # Both properties may be sent either as positional arguments or as
+        # keyword arguments.  If the same property is sent as both a positional
+        # arg and a keyword arg, an ArgumentError is raised.
+        #
+        # * #authcid, #username --- the identity whose #password is used.
+        #   Only <tt>:authcid</tt> will be sent to callbacks.
+        # * #oauth2_token --- An OAuth2.0 access token assigned to #username,
+        #   authorized to access IMAP.
+        #
+        # See the documentation for each property method for more details.
+        #
+        # See Net::IMAP::SASL::Authenticator@Properties for a detailed description
+        # of property assignment, lazy loading, and callbacks.
+        #
+        def initialize(username_arg = nil, oauth2_token_arg = nil,
+                       username: nil, authcid: nil, oauth2_token: nil,
+                       **, &callback)
+          super
+          propinit :authcid, authcid, username, username_arg,     required: true
+          propinit :oauth2_token, oauth2_token, oauth2_token_arg, required: true
+        end
+
+        ##
+        # method: authcid
+        # :call-seq: authcid -> string
+        #
+        # Authentication identity: the identity that matches the #oauth2_token.
+        #
+        # 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: oauth2_token
+        # :call-seq: oauth2_token -> string
+        #
+        # An OAuth2 access token for #authcid, which has been authorized with
+        # appropriate OAuth2 scopes to access IMAP.
+        property :oauth2_token
+
+        # Returns the XOAUTH2 formatted response, which combines the +authcid+
+        # with the +oauth2_token+.
+        #
+        # [Note]
+        #   For simplicity, the same response is always generated, even when the
+        #   server sends error data in its challenge.  However, the \SASL
+        #   specification requires an empty response to acknowledge the error.
+        #   This has little effect in practice, any response to the error results
+        #   in an tagged error response: generally +NO+, but potentially +BAD+.
+        def process(data)
+          @last_server_response = data
+          "user=%s\1auth=Bearer %s\1\1" % [username, oauth2_token]
+        end
+
+        # Stores the most recent server "challenge".  When authentication fails,
+        # this may hold information about the failure reason, as JSON.
+        attr_reader :last_server_response
+
+      end
+    end
+
+    XOauth2Authenticator = SASL::XOAuth2Authenticator # :nodoc:
+    deprecate_constant :XOauth2Authenticator
+
+  end
+end

lib/net/imap/sasl/xoauth2_authenticator.rb

@@ -35,10 +35,48 @@ def test_plain_no_null_chars
   # XOAUTH2
   # ----------------------
 
-  def test_xoauth2
+  def test_xoauth2_authenticator_matches_mechanism
+    assert_kind_of(Net::IMAP::SASL::XOAuth2Authenticator,
+                   Net::IMAP.authenticator("XOAUTH2", "user", "tok"))
+  end
+
+  def xoauth2(*args, **kwargs, &block)
+    Net::IMAP.authenticator("XOAUTH2", *args, **kwargs, &block)
+  end
+
+  def test_xoauth2_response
     assert_equal(
       "user=username\1auth=Bearer token\1\1",
-      Net::IMAP::XOauth2Authenticator.new("username", "token").process(nil)
+      xoauth2("username", "token").process(nil)
+    )
+  end
+
+  def test_xoauth2_kwargs
+    assert_equal(
+      "user=arg\1auth=Bearer kwarg\1\1",
+      xoauth2("arg", oauth2_token: "kwarg").process(nil)
+    )
+    assert_equal(
+      "user=authc\1auth=Bearer kwarg\1\1",
+      xoauth2(authcid: "authc", oauth2_token: "kwarg").process(nil)
+    )
+    assert_equal(
+      "user=user\1auth=Bearer kwarg\1\1",
+      xoauth2(username: "user", oauth2_token: "kwarg").process(nil)
+    )
+  end
+
+  def test_xoauth2_callbacks
+    assert_equal(
+      "user=authc ID\1auth=Bearer lazy\1\1",
+      xoauth2(authcid: "authc ID", oauth2_token: proc{ "lazy" }).process(nil)
+    )
+    assert_equal(
+      "user=u\1auth=Bearer t\1\1",
+      xoauth2 {|prop, authctx|
+        assert_kind_of(Net::IMAP::SASL::XOAuth2Authenticator, authctx)
+        case prop when :authcid then "u" when :oauth2_token then "t" end
+      }.process(nil)
     )
   end