net-imap 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 473842922edfdfd112a9cd3fa96df2831efa0d4640a38c0969725d6c04f45dbe
-  data.tar.gz: 7f93b8a1882f2225f404db0d175c29ead931de531f918e17cbb6f8515300b9e9
+  metadata.gz: 2bba73e8db611b37b7c5b9be540d99c2288e9188e7f12620259862b30db47815
+  data.tar.gz: fde1bcda99236beafea397d36768fb9fe185ec20ca2cd5d9c991b48cfdf51bd3
 SHA512:
-  metadata.gz: d9470c52ca3b689a1dd314501a91f5651d1b11fd26cc5628cb6ccf4bf59aeb93ebdcca141ab12d0ec5e69b0e5aa5e29881c85433d9c6dcdeb5902591c1c62aaa
-  data.tar.gz: 6caae2c7cf684d10ca54ac8b53b498acb5c8d210135d2f583d254fa3dbdc41b7e50382c43aeb05438713b723d9d5da7d48980569024e36d55683e9e5b041df8a
+  metadata.gz: 6ee43fab9eaea8c870940e0cc625e3223722e4b722e1055da6f3629707aaf12e580143139abb97ae1294757a99db977428c8aa23bc57d8e9a23ff9ab5eb695cf
+  data.tar.gz: 67a965fdd6b4af0480917241a8efad57c3356c82ec975bcc10373242e477718a1751e78cc9f0e51286b553e6222c26cddca119dbaa9dfef855c9611de6a55a64

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      # This API is *experimental*, and may change.
+      #
+      # TODO: catch exceptions in #process and send #cancel_response.
+      # TODO: raise an error if the command succeeds after being canceled.
+      # TODO: use with more clients, to verify the API can accommodate them.
+      #
+      # Create an AuthenticationExchange from a client adapter and a mechanism
+      # authenticator:
+      #     def authenticate(mechanism, ...)
+      #       authenticator = SASL.authenticator(mechanism, ...)
+      #       SASL::AuthenticationExchange.new(
+      #         sasl_adapter, mechanism, authenticator
+      #       ).authenticate
+      #     end
+      #
+      #     private
+      #
+      #     def sasl_adapter = MyClientAdapter.new(self, &method(:send_command))
+      #
+      # Or delegate creation of the authenticator to ::build:
+      #     def authenticate(...)
+      #       SASL::AuthenticationExchange.build(sasl_adapter, ...)
+      #         .authenticate
+      #     end
+      #
+      # As a convenience, ::authenticate combines ::build and #authenticate:
+      #     def authenticate(...)
+      #       SASL::AuthenticationExchange.authenticate(sasl_adapter, ...)
+      #     end
+      #
+      # Likewise, ClientAdapter#authenticate delegates to #authenticate:
+      #     def authenticate(...) = sasl_adapter.authenticate(...)
+      #
+      class AuthenticationExchange
+        # Convenience method for <tt>build(...).authenticate</tt>
+        def self.authenticate(...) build(...).authenticate end
+
+        # Use +registry+ to override the global Authenticators registry.
+        def self.build(client, mechanism, *args, sasl_ir: true, **kwargs, &block)
+          authenticator = SASL.authenticator(mechanism, *args, **kwargs, &block)
+          new(client, mechanism, authenticator, sasl_ir: sasl_ir)
+        end
+
+        attr_reader :mechanism, :authenticator
+
+        def initialize(client, mechanism, authenticator, sasl_ir: true)
+          @client = client
+          @mechanism = -mechanism.to_s.upcase.tr(?_, ?-)
+          @authenticator = authenticator
+          @sasl_ir = sasl_ir
+          @processed = false
+        end
+
+        # Call #authenticate to execute an authentication exchange for #client
+        # using #authenticator.  Authentication failures will raise an
+        # exception.  Any exceptions other than those in RESPONSE_ERRORS will
+        # drop the connection.
+        def authenticate
+          client.run_command(mechanism, initial_response) { process _1 }
+            .tap { raise AuthenticationIncomplete, _1 unless done? }
+        rescue *client.response_errors
+          raise # but don't drop the connection
+        rescue
+          client.drop_connection
+          raise
+        rescue Exception # rubocop:disable Lint/RescueException
+          client.drop_connection!
+          raise
+        end
+
+        def send_initial_response?
+          @sasl_ir &&
+            authenticator.respond_to?(:initial_response?) &&
+            authenticator.initial_response? &&
+            client.sasl_ir_capable? &&
+            client.auth_capable?(mechanism)
+        end
+
+        def done?
+          authenticator.respond_to?(:done?) ? authenticator.done? : @processed
+        end
+
+        private
+
+        attr_reader :client
+
+        def initial_response
+          return unless send_initial_response?
+          client.encode_ir authenticator.process nil
+        end
+
+        def process(challenge)
+          client.encode authenticator.process client.decode challenge
+        ensure
+          @processed = true
+        end
+
+      end
+    end
+  end
+end

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

@@ -65,7 +65,7 @@ module Net::IMAP::SASL
     # lazily loaded from <tt>Net::IMAP::SASL::#{name}Authenticator</tt> (case is
     # preserved and non-alphanumeric characters are removed..
     def add_authenticator(name, authenticator = nil)
-      key = name.upcase.to_sym
+      key = -name.to_s.upcase.tr(?_, ?-)
       authenticator ||= begin
         class_name = "#{name.gsub(/[^a-zA-Z0-9]/, "")}Authenticator".to_sym
         auth_class = nil
@@ -79,10 +79,15 @@ module Net::IMAP::SASL
 
     # Removes the authenticator registered for +name+
     def remove_authenticator(name)
-      key = name.upcase.to_sym
+      key = -name.to_s.upcase.tr(?_, ?-)
       @authenticators.delete(key)
     end
 
+    def mechanism?(name)
+      key = -name.to_s.upcase.tr(?_, ?-)
+      @authenticators.key?(key)
+    end
+
     # :call-seq:
     #   authenticator(mechanism, ...) -> auth_session
     #
@@ -100,8 +105,9 @@ module Net::IMAP::SASL
     #   only.  Protocol client users should see refer to their client's
     #   documentation, e.g. Net::IMAP#authenticate.
     def authenticator(mechanism, ...)
-      auth = @authenticators.fetch(mechanism.upcase.to_sym) do
-        raise ArgumentError, 'unknown auth type - "%s"' % mechanism
+      key = -mechanism.to_s.upcase.tr(?_, ?-)
+      auth = @authenticators.fetch(key) do
+        raise ArgumentError, 'unknown auth type - "%s"' % key
       end
       auth.respond_to?(:new) ? auth.new(...) : auth.call(...)
     end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      # This API is *experimental*, and may change.
+      #
+      # TODO: use with more clients, to verify the API can accommodate them.
+      #
+      # An abstract base class for implementing a SASL authentication exchange.
+      # Different clients will each have their own adapter subclass, overridden
+      # to match their needs.
+      #
+      # Although the default implementations _may_ be sufficient, subclasses
+      # will probably need to override some methods.  Additionally, subclasses
+      # may need to include a protocol adapter mixin, if the default
+      # ProtocolAdapters::Generic isn't sufficient.
+      class ClientAdapter
+        include ProtocolAdapters::Generic
+
+        attr_reader :client, :command_proc
+
+        # +command_proc+ can used to avoid exposing private methods on #client.
+        # It should run a command with the arguments sent to it, yield each
+        # continuation payload, respond to the server with the result of each
+        # yield, and return the result.  Non-successful results *MUST* raise an
+        # exception.  Exceptions in the block *MUST* cause the command to fail.
+        #
+        # Subclasses that override #run_command may use #command_proc for
+        # other purposes.
+        def initialize(client, &command_proc)
+          @client, @command_proc = client, command_proc
+        end
+
+        # Delegates to AuthenticationExchange.authenticate.
+        def authenticate(...) AuthenticationExchange.authenticate(self, ...) end
+
+        # Do the protocol and server both support an initial response?
+        def sasl_ir_capable?; client.sasl_ir_capable? end
+
+        # Does the server advertise support for the mechanism?
+        def auth_capable?(mechanism); client.auth_capable?(mechanism) end
+
+        # Runs the authenticate command with +mechanism+ and +initial_response+.
+        # When +initial_response+ is nil, an initial response must NOT be sent.
+        #
+        # Yields each continuation payload, responds to the server with the
+        # result of each yield, and returns the result.  Non-successful results
+        # *MUST* raise an exception.  Exceptions in the block *MUST* cause the
+        # command to fail.
+        #
+        # Subclasses that override this may use #command_proc differently.
+        def run_command(mechanism, initial_response = nil, &block)
+          command_proc or raise Error, "initialize with block or override"
+          args = [command_name, mechanism, initial_response].compact
+          command_proc.call(*args, &block)
+        end
+
+        # Returns an array of server responses errors raised by run_command.
+        # Exceptions in this array won't drop the connection.
+        def response_errors; [] end
+
+        # Drop the connection gracefully.
+        def drop_connection;  client.drop_connection end
+
+        # Drop the connection abruptly.
+        def drop_connection!; client.drop_connection! end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      module ProtocolAdapters
+        # This API is experimental, and may change.
+        module Generic
+          def command_name;     "AUTHENTICATE" end
+          def service;          raise "Implement in subclass or module" end
+          def host;             client.host end
+          def port;             client.port end
+          def encode_ir(string) string.empty? ? "=" : encode(string) end
+          def encode(string)    [string].pack("m0") end
+          def decode(string)    string.unpack1("m0") end
+          def cancel_response;  "*" end
+        end
+
+        # See RFC-3501 (IMAP4rev1), RFC-4959 (SASL-IR capability),
+        # and RFC-9051 (IMAP4rev2).
+        module IMAP
+          include Generic
+          def service; "imap" end
+        end
+
+        # See RFC-4954 (AUTH capability).
+        module SMTP
+          include Generic
+          def command_name; "AUTH" end
+          def service; "smtp" end
+        end
+
+        # See RFC-5034 (SASL capability).
+        module POP
+          include Generic
+          def command_name; "AUTH" end
+          def service; "pop" end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/net/imap/sasl.rb

@@ -135,6 +135,10 @@ module Net
       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"
@@ -155,8 +159,10 @@ module Net
       # Returns the default global SASL::Authenticators instance.
       def self.authenticators; @authenticators ||= Authenticators.new end
 
-      # Delegates to ::authenticators.  See Authenticators#authenticator.
-      def self.authenticator(...)     authenticators.authenticator(...) end
+      # Delegates to <tt>registry.new</tt>  See Authenticators#new.
+      def self.authenticator(*args, registry: authenticators, **kwargs, &block)
+        registry.new(*args, **kwargs, &block)
+      end
 
       # Delegates to ::authenticators.  See Authenticators#add_authenticator.
       def self.add_authenticator(...) authenticators.add_authenticator(...) end

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

data/lib/net/imap.rb

@@ -127,7 +127,7 @@ module Net
   #   end
   #
   #   # Support for "UTF8=ACCEPT" implies support for "ENABLE"
-  #   imap.enable :utf8 if imap.auth_capable?("UTF8=ACCEPT")
+  #   imap.enable :utf8 if imap.capable?("UTF8=ACCEPT")
   #
   #   namespaces  = imap.namespace if imap.capable?(:namespace)
   #   mbox_prefix = namespaces&.personal&.first&.prefix || ""
@@ -662,7 +662,7 @@ module Net
   # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.4.0"
+    VERSION = "0.4.1"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -670,8 +670,9 @@ module Net
       "UTF8=ONLY" => "UTF8=ACCEPT",
     }.freeze
 
-    autoload :SASL,       File.expand_path("imap/sasl",       __dir__)
-    autoload :StringPrep, File.expand_path("imap/stringprep", __dir__)
+    autoload :SASL,        File.expand_path("imap/sasl",         __dir__)
+    autoload :SASLAdapter, File.expand_path("imap/sasl_adapter", __dir__)
+    autoload :StringPrep,  File.expand_path("imap/stringprep",   __dir__)
 
     include MonitorMixin
     if defined?(OpenSSL::SSL)
@@ -1142,7 +1143,10 @@ module Net
     end
 
     # :call-seq:
-    #   authenticate(mechanism, *, sasl_ir: true, **, &) -> ok_resp
+    #   authenticate(mechanism, *,
+    #                sasl_ir: true,
+    #                registry: Net::IMAP::SASL.authenticators,
+    #                **, &) -> ok_resp
     #
     # Sends an {AUTHENTICATE command [IMAP4rev1 §6.2.2]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.2]
     # to authenticate the client.  If successful, the connection enters the
@@ -1886,8 +1890,7 @@ module Net
     # +attr+ is a list of attributes to fetch; see the documentation
     # for FetchData for a list of valid attributes.
     #
-    # The return value is an array of FetchData or nil
-    # (instead of an empty array) if there is no matching message.
+    # The return value is an array of FetchData.
     #
     # Related: #uid_search, FetchData
     #
@@ -2747,6 +2750,10 @@ module Net
       end
     end
 
+    def sasl_adapter
+      SASLAdapter.new(self, &method(:send_command_with_continuations))
+    end
+
     #--
     # We could get the saslprep method by extending the SASLprep module
     # directly.  It's done indirectly, so SASLprep can be lazily autoloaded,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Shugo Maeda
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-04 00:00:00.000000000 Z
+date: 2023-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -100,7 +100,9 @@ files:
 - lib/net/imap/response_parser/parser_utils.rb
 - lib/net/imap/sasl.rb
 - lib/net/imap/sasl/anonymous_authenticator.rb
+- lib/net/imap/sasl/authentication_exchange.rb
 - lib/net/imap/sasl/authenticators.rb
+- lib/net/imap/sasl/client_adapter.rb
 - lib/net/imap/sasl/cram_md5_authenticator.rb
 - lib/net/imap/sasl/digest_md5_authenticator.rb
 - lib/net/imap/sasl/external_authenticator.rb
@@ -108,10 +110,12 @@ files:
 - lib/net/imap/sasl/login_authenticator.rb
 - lib/net/imap/sasl/oauthbearer_authenticator.rb
 - lib/net/imap/sasl/plain_authenticator.rb
+- lib/net/imap/sasl/protocol_adapters.rb
 - lib/net/imap/sasl/scram_algorithm.rb
 - lib/net/imap/sasl/scram_authenticator.rb
 - lib/net/imap/sasl/stringprep.rb
 - lib/net/imap/sasl/xoauth2_authenticator.rb
+- lib/net/imap/sasl_adapter.rb
 - lib/net/imap/stringprep.rb
 - lib/net/imap/stringprep/nameprep.rb
 - lib/net/imap/stringprep/saslprep.rb