♻️ SASL: Add Authenticator base class w/📚docs [🚧WIP:update w/mechanisms]

* Add many many docs
* Add properties, events, and callbacks
* Add initial_response?
* TODO: add `done?`

Author: nevans

lib/net/imap/sasl/authenticator.rb

@@ -0,0 +1,366 @@
+# 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:
+      #
+      # * +PLAIN+ --- PlainAuthenticator
+      # * +XOAUTH2+ --- TODO: XOauth2Authenticator
+      # * +EXTERNAL+ --- TODO
+      # * +ANONYMOUS+ --- TODO
+      # * +OAUTHBEARER+ --- TODO
+      # * +SCRAM-SHA-*+ --- TODO
+      #
+      # [Deprecated:]
+      #   DIGEST-MD5[rdoc-ref:DigestMD5Authenticator],
+      #   LOGIN[rdoc-ref:LoginAuthenticator], and
+      #   CRAM-MD5[rdoc-ref:CramMD5Authenticator]
+      #
+      # \Authenticators should be created and used internally by a protocol
+      # client's authentication command, e.g. Net::IMAP#authenticate for \IMAP.
+      # Instead of creating the authenticator directly, the protocol client
+      # should call Authenticators#authenticator, which delegates to the
+      # authenticator that has been registered for the requested mechanism.
+      #
+      # == 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
+          # Returns the SASL mechanism name, based on the class name.  If the
+          # class name can't produce the correct mechanism name, override
+          # to return the correct name.
+          def mechanism_name
+            name
+              .split("::").last
+              .delete_suffix("Authenticator")
+              .gsub(/([a-z\d])(?=[A-Z])/) {
+                ($1 || $2) << "-"
+              }
+              .upcase
+          end
+
+          private
+
+          # Adds this authenticator to an Authenticators registry.
+          def register(registrar) # :doc:
+            registrar.add_authenticator mechanism_name, self
+          end
+
+          # 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>
+        #
+        # Protocol clients should not call this method directly, but should use
+        # Authenticators#authenticator, which delegates to the authenticator
+        # that has been registered for the requested mechanism.
+        #
+        # See Authenticator@Properties.
+        #
+        # ==== 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