📚 Update SASL XOAUTH2 docs and add attr_readers

This also renames `@user` to `@username`, to match other
authenticators.  However, the spec is unclearly worded.   It arguably
_should_ be renamed to (or aliased as) `authzid`. 🤷

Author: nevans

lib/net/imap/sasl/xoauth2_authenticator.rb

@@ -1,22 +1,73 @@
 # 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
 
-  def initialize(user, oauth2_token)
-    @user = user
+  # 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:
+  # :call-seq:
+  #   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(username, oauth2_token)
+    @username = username
     @oauth2_token = oauth2_token
   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(@user, @oauth2_token)
+    build_oauth2_string(@username, @oauth2_token)
   end
 
   private
 
-  def build_oauth2_string(user, oauth2_token)
-    format("user=%s\1auth=Bearer %s\1\1", user, oauth2_token)
+  def build_oauth2_string(username, oauth2_token)
+    format("user=%s\1auth=Bearer %s\1\1", username, oauth2_token)
   end
 
 end

test/net/imap/test_imap_authenticators.rb

@@ -88,7 +88,7 @@ def test_xoauth2_authenticator_matches_mechanism
     assert_kind_of(Net::IMAP::SASL::XOAuth2Authenticator, xoauth2("user", "tok"))
   end
 
-  def test_xoauth2
+  def test_xoauth2_response
     assert_equal(
       "user=username\1auth=Bearer token\1\1",
       xoauth2("username", "token").process(nil)