♻️ SASL: Add Authenticator base class w/📚docs [🚧TODO: test base class]

* Add many many docs
* Add properties, events, and callbacks
* Add initial_response?
* Add AuthenticationFailure for failures detected by the SASL mechanism.
  This is different from failures detected by the application protocol,
  such as when the IMAP server responds with "NO" or "BAD".

Currently unused, but existing authenticators will be refactored based
on this, and new authenticators will be writte on it.

Author: nevans

lib/net/imap/sasl.rb

@@ -60,6 +60,7 @@ module SASL
       autoload :BidiStringError,     stringprep_path
 
       sasl_dir = File.expand_path("sasl", __dir__)
+      autoload :Authenticator,            "#{sasl_dir}/authenticator"
       autoload :Authenticators,           "#{sasl_dir}/authenticators"
 
       # Authenticators are all lazy loaded
@@ -79,6 +80,16 @@ def self.authenticator(...)     authenticators.authenticator(...) end
       # See SASL::add_authenticator
       def self.add_authenticator(...) authenticators.add_authenticator(...) end
 
+      # Error raised when the client SASL::Authenticator determines that it
+      # cannot complete successfully during a call to Authenticator#process.
+      #
+      # Note that most \SASL mechanisms cannot detect or report errors until the
+      # protocol-specific outcome message, e.g. a tagged response in \IMAP.
+      # Those authentication errors will be handled or raised by the protocol
+      # client, e.g. a Net::IMAP::NoResponseError.
+      class AuthenticationFailure < Error
+      end
+
       module_function
 
       # See Net::IMAP::StringPrep::SASLprep#saslprep.

lib/net/imap/sasl/authenticator.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # A base class for authentication exchange sessions by a SASL client.  A new
+      # authenticator session object must be created for every authentication
+      # attempt.  Specific SASL mechanisms are implemented by subclasses.
+      # Although it isn't necessary to inherit from this base class, it enables
+      # useful functionality that is common to all authenticators, e.g. property
+      # callbacks.
+      #
+      # Each mechanism requires and allows different properties and callbacks;
+      # please consult the documentation for the specific mechanisms you are
+      # using.  See the SASL module documentation for the list of mechanism
+      # subclasses.
+      #
+      # == Properties
+      #
+      # When inheriting classes use rdoc-ref:Authenticator.property and
+      # #propinit, every property will be configurable by calling
+      # new[rdoc-ref:.new] with the matching keyword argument.  Common
+      # properties might also allowed as positional arguments.  See
+      # Authenticator@Typical+properties and the documentation on each
+      # authenticator subclass.
+      #
+      # Assigning a Proc or Method will set a callback to lazy load the property
+      # value the first time it is used.  A block sent to new[rdoc-ref:.new]
+      # will be the default callback for all unassigned properties.  See
+      # Authenticator@Callbacks.
+      #
+      # As a special type of "property", some authenticators may support event
+      # callbacks.  These might be assigned by a keyword parameter with the same
+      # name, or they might only be sent to the default callback.  Unlike
+      # properties, the callback might be called more than once.  Authenticator
+      # implementations should also document all events that are sent.
+      #
+      # === Typical properties
+      #
+      # The following is not an exhaustive list of properties, and each \SASL
+      # mechanism only uses a few of these.  More detailed descriptions may be
+      # found in the specific authenticators' documentation.  <em>Some of the
+      # mechanisms that use these properties are not implemented yet.</em>
+      #
+      # ==== Auth identity properties
+      # * +authcid+ --- authentication identity, owner of the credentials;
+      #   sometimes aliased as +username+
+      # * +authzid+ --- authorization identity, to act as or on behalf of;
+      #   often identical to +authcid+ or inferred from credentials
+      # * +realm+ --- namespace for identities, e.g. a domain name
+      # * +anonymous_message+ --- optional token for the +ANONYMOUS+ mechanism
+      #
+      # ==== Credentials properties
+      #
+      # * +password+ --- password or passphrase, used by many mechanisms
+      # * +oauth2_token+ --- OAuth2.0 access token, used by +XOAUTH2+ and
+      #   +OAUTHBEARER+
+      # * +scram_sha1_salted_passwords+, +scram_sha256_salted_password+ ---
+      #   Salted password(s) (with salt and iteration count) for the +SCRAM-*+
+      #   mechanism family.  <tt>[salt, iterations, pbkdf2_hmac]</tt> tuple.
+      #   <em>(not implemented yet...)</em>
+      # * +passcode+ --- passcode for SecurID 2FA <em>(not implemented)</em>
+      # * +pin+ --- Personal Identification number, e.g. for SecurID 2FA
+      #   <em>(not implemented)</em>
+      #
+      # ==== Requested service properties
+      #
+      # Some mechanisms need to know more about the service that the
+      # authentication is for.
+      #
+      # * +service+ --- {registered GSSAPI service
+      #   name}[https://www.iana.org/assignments/gssapi-service-names/gssapi-service-names.xhtml],
+      #   e.g. "imap", "smtp", "ldap", "xmpp"
+      # * +host+ --- FQDN used to access the requested service
+      # * +port+ --- port number used to access the requested service
+      #
+      #--
+      # TODO: Authenticators#authenticator should:
+      # * use #sasl_service, #host, and #port (maybe make these configurable,
+      #   e.g. #hostname vs #host) to automatically fill in the correct values,
+      #   per connection.
+      # * inspect the authenticator's parameters and automatically send these
+      #   parameters IFF they are explicit keyword arguments.
+      #++
+      #
+      # === Callbacks
+      #
+      # Callback procs might be used for interactivity, e.g. to present the user
+      # with a choice from a server-provided list of realms, or to ask the user
+      # for a password interactively only after securely connecting to the
+      # server and selecting a password-based mechanism.  It might also be used
+      # to fetch credentials from a KMS only when necessary, or to audit every
+      # use of a secret.
+      #
+      # Callbacks must return +nil+ for unhandled properties or events.
+      #
+      # ==== Example: Interactive password from password manager
+      #     service = { service: "imap", host: "imap.example.com", port: 993 }
+      #     auth = authenticator("DIGEST-MD5", "user", **service) {|ctx, attr|
+      #       case attr
+      #       when :password then password_manager.prompt(**service)
+      #       else
+      #         # etc...
+      #       end
+      #     }
+      #
+      # ==== Example: Log every time sensitive fields are accessed
+      #     auth = authenticator(mechanism, **nonsecret_attrs) do |attr, ctx|
+      #       case attr
+      #       when :password, :pin, :oauth2_token, :passphrase,
+      #            :scram_salted_password
+      #         log_sensitive ctx.authcid, attr
+      #         secrets_for(ctx.authcid).fetch(attr)
+      #       end
+      #       nil
+      #     end
+      #
+      # ==== Example: some mechanisms need event handlers to finish the exchange
+      #     auth = authenticator("OPENID20", **user_auth_attrs) do |attr, ctx|
+      #       case attr
+      #       when :openid20_authenticate_in_browser
+      #         # an OPENID20 mechanism (not implemented yet) would need to
+      #         # update ctx with values sent by the server challenge:
+      #         browser.open ctx.openid20_redirect_url
+      #         wait_for browser_auth_completion
+      #       end
+      #     end
+      #
+      # == Initial Response
+      #
+      # Some protocols and some mechanisms support sending an "initial response"
+      # from the client, before any server challenge.  When both the protocol
+      # client and the authenticator agree to an initial response, the
+      # authenticator should be called the first time with +nil+ as the "server
+      # challenge".  See rdoc-ref:Authenticator.initial_response?,
+      # #initial_response?, and #process for more details.
+      #
+      class Authenticator
+
+        class << self
+          private
+
+          # Defines an authenticator "property"
+          def property(name) # :doc:
+            class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{name}                  # def password
+                propget(:#{name})          #   propget(:password)
+              end                          # end
+
+              def #{name}=(value)          # def password=(value)
+                propset(:#{name}, value)   #   propset(:password, value)
+              end                          # end
+            RUBY
+          end
+        end
+
+        # A Hash containing all _resolved_ properties for an Authenticator.
+        # Lazy loaded properties will have an entry in #callbacks.  Use the
+        # named property method to load that property using #callbacks.
+        attr_reader :properties
+
+        # A Hash of callback procs to lazy-load properties or handle events.
+        # The hash's default value is #callback.
+        #
+        # Callbacks are sent the property (or event) name and the authenticator
+        # object.  The authenticator can use itself to pass more information to
+        # event handlers (e.g. a list of server-sent realms or an authentication
+        # URL).
+        attr_reader :callbacks
+
+        # The generic callback, called for otherwise unconfigured properties and
+        # events.  Used as the default value for #callbacks.
+        attr_reader :callback
+
+        # :call-seq:
+        #   new                                             -> authenticator
+        #   new(username, password)                         -> authenticator
+        #   new(authcid, secret, authzid)                   -> authenticator
+        #   new(*credentials)                               -> authenticator
+        #   new(**properties, **callbacks)                  -> authenticator
+        #   new {|name, authenticator| prop_value }         -> authenticator
+        #   new(*creds, **props) {|name, authenticator| v } -> authenticator
+        #
+        # Creates a new SASL client authenticator.  The call signatures listed
+        # here are the _recommended_ styles, but each mechanism requires and
+        # allows different arguments.  <em>Each authenticator class must
+        # document its specific properties and callbacks.</em>  See
+        # Authenticator@Properties for generic property descriptions.
+        #
+        # Client users should not create authenticators directly, but should
+        # instead use their client's authentication command, e.g.
+        # Net::IMAP#authenticate for Net::IMAP.
+        #
+        # Client authors should not create authenticators directly, but should
+        # instead use Authenticators#authenticator, which delegates to the
+        # authenticator that has been registered for the requested mechanism.
+        #
+        # ==== Inheriting
+        #
+        # <em>Each authenticator class must document its specific properties and
+        # callbacks.</em>
+        #
+        # Inheriting classes must call +super+ before initializing or using
+        # properties.  \Authenticators should have a keyword parameter for every
+        # accepted property or callback and should ignore any unused keyword
+        # parameters.  \Authenticators may also have one or more positional
+        # parameters for the most common properties---especially credentials
+        # like username and password.  \Authenticators should raise an
+        # ArgumentError for unhandled positional arguments or when a property is
+        # set through multiple arguments.
+        #
+        def initialize(*, **, &callback)
+          @callback   = callback
+          @callbacks  = Hash.new { @callback }
+          @properties = {}
+        end
+
+        # :call-seq:
+        #   obj.process(nil)                     -> initial_response_string
+        #   obj.process(server_challenge_string) -> client_response_string
+        #
+        # Generates a \SASL client reply to a server challenge, as part of a
+        # \SASL authentication exchange.  Protocol clients will call +#process+
+        # with every server challenge and send the result back to the server,
+        # until the \SASL exchange is done.
+        #
+        # If the protocol client supports an initial client response, it will
+        # check if the authenticator responds to +initial_response?+ with
+        # +true+.  When the mechanism and the protocol both support an initial
+        # client response, the client should send +nil+ as the first "server
+        # challenge".
+        #
+        # The protocol client is responsible for protocol-specific decoding of the
+        # +server_challenge_string+ sent from the server and encoding of the
+        # +client_response_string+ sent to the server.  E.g. \IMAP uses Base64.
+        #
+        # If a failed exchange can be detected from the server challenge,
+        # +#process+ should raise an exception.  The Authenticator alone cannot
+        # determine if an exchange was successful.  The protocol client must be
+        # responsible for handling protocol-level errors (e.g. a +NO+ or +BAD+
+        # response in IMAP).  The \SASL exchange is unsuccessful if _either_ the
+        # Authenticator or the protocol client report an error.
+        #
+        # See PlainAuthenticator or DigestMD5Authenticator for example
+        # authenticator implementations.
+        def process(server_challenge_string)
+          raise NotImplementedError, "#{__method__} is defined by subclasses"
+        end
+
+        # :call-seq:
+        #   initial_response? -> true or false
+        #
+        # Returns +true+ when the authenticator supports an "initial response"
+        # from the client.  If this is +true+ and the protocol client also
+        # supports an initial response, then #process should be called with
+        # +nil+ the first time.
+        #
+        # Automatically returns +true+ when the object responds to
+        # +initial_client_response+.
+        #
+        # Note::
+        #   Implementing #initial_response? or #initial_client_response or
+        #   inheriting from Authenticator are all optional.  Clients should
+        #   check that the authenticator responds to +initial_response?+ before
+        #   calling it.
+        def initial_response?; respond_to?(:initial_client_response) end
+
+        private
+
+        # Use this instead of #propset when a property may be set by multiple
+        # sources, e.g. a positional parameter or a keyword parameter or a
+        # keyword alias, etc.
+        #
+        # If +values+ has multiple non-nil members then an ArgumentError will be
+        # raised, so the order is not semantically significant.  With no non-nil
+        # members, the property will be left unset.
+        #
+        # Send +required: true+ to raise an ArgumentError when all of the
+        # +values+ are +nil+.
+        def propinit(name, *values, required: false) # :doc:
+          values.compact!
+          if values.length > 1
+            raise ArgumentError, "multiple conflicting arguments for #{name}"
+          elsif !values.empty?
+            send :"#{name}=", values.first
+          elsif required && !callback
+            raise ArgumentError, "%s needs %s" % [self.class, name]
+          end
+        end
+
+        # Used internally to assign properties.  The autogenerated property
+        # writers use #propset.
+        #
+        # Subclasses can override this to add validation, coercion, etc
+        def propset(name, val) # :doc:
+          case val
+          when nil          then properties.delete name; callbacks.delete name
+          when Proc, Method then properties.delete name; callbacks[name]  = val
+          else                   callbacks.delete  name; properties[name] = val
+          end
+          val
+        end
+
+        # Returns whether the property has been set, either to a value or a
+        # callback.
+        def propset?(name) # :doc:
+          properties.key?(name) || callbacks.key?(name)
+        end
+
+        # Used internally to fetch or lazy load properties, using #event and
+        # #propset.  The autogenerated property readers use #propget.
+        def propget(name, &default) # :doc:
+          properties.fetch(name) {
+            val = event(name)
+            propset(name, val.nil? ? default&.call : val)
+          }
+        end
+
+        # Use #event to trigger a specific callback, without updating the
+        # authenticator's state.  Accepts no other arguments, but "event
+        # parameters" can be passed via authenticator attributes or properties.
+        #
+        # #propget uses #event internally for lazy-loaded properties, and then
+        # assigns the return value to the property with that +name+.
+        def event(name) # :doc:
+          callbacks[name]&.call(name, self)
+        end
+
+      end
+    end
+
+  end
+end