net-smtp 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0af9f3ec513aec9b2c9e9b59c086858e3ab6dfe4b66dced534439f3229661327
-  data.tar.gz: 307cd96a3a772e525294153b4e36d20fc7722cac80855a40cd9a2d0e11a21694
+  metadata.gz: 1fcccbe34b29672c33aa7515de88e88dba31882e26a4b6c0a5fc30c5a4eb697d
+  data.tar.gz: 5c47e6453d2cb69365edc7b4e31b17106b73e254e1bc10258f4b14ea780ba889
 SHA512:
-  metadata.gz: 9cd5a79d90ebb1d94872e25c416a539afebba68f322bec9953826e984f8e13ddd7403216fde5f09c2ef03a2b6a41cc2b5514b1697b7fd10fa7c663f202ed1fb8
-  data.tar.gz: a4d0b4d3749e98173aef3df7bcb2f0a0dd56a8404e801d4af68a38db31f02969f7f94ff659fe50d28b0dcc9f1083f03d0802c3954d9fe87141cf17abdf7777d9
+  metadata.gz: 6576c5b7dc21982576fa6c3a6e08641e973136148d5d5bcb27fe1e17b4e5fdd802c5f5a6f9f116dd15bf4f2a0e5f95f071ca19d47119cf60c7da9230a64d3a4c
+  data.tar.gz: 9b1c54b2d9a48e384d3b1a67f1aa8b8a2614a383dc31b83d49170f3ed93d69a2058f3c310f72d443f54a0947c1066249105087a1a3addc92965c289354c8156a

data/NEWS.md

@@ -1,5 +1,24 @@
 # NEWS
 
+## Version 0.5.0 (2024-03-27)
+
+### Improvements
+
+* Allow case-insensitive strings for SASL mechanism <https://github.com/ruby/net-smtp/pull/64>
+* Make #auth_capable? public <https://github.com/ruby/net-smtp/pull/63>
+* Add XOAUTH2 authenticator <https://github.com/ruby/net-smtp/pull/80>
+
+### Others
+
+* Remove unused private auth_method <https://github.com/ruby/net-smtp/pull/67>
+* Delegate checking auth args to the authenticator <https://github.com/ruby/net-smtp/pull/73>
+* Updated docs, especially TLS and SASL-related <https://github.com/ruby/net-smtp/pull/66>
+* Renew test certificates <https://github.com/ruby/net-smtp/pull/75>
+* Fix version extraction to work with non ASCII characters with any LANG <https://github.com/ruby/net-smtp/pull/76>
+* Replace non-ASCII EM DASH (U+2014) with ASCII hyphen (U+002D) <https://github.com/ruby/net-smtp/pull/78>
+* Use reusing workflow for Ruby versions <https://github.com/ruby/net-smtp/pull/79>
+* Make the test suite compatible with --enable-frozen-string-literal <https://github.com/ruby/net-smtp/pull/81>
+
 ## Version 0.4.0 (2023-09-20)
 
 ### Improvements

data/lib/net/smtp/auth_xoauth2.rb

@@ -0,0 +1,17 @@
+class Net::SMTP
+  class AuthXoauth2 < Net::SMTP::Authenticator
+    auth_type :xoauth2
+
+    def auth(user, secret)
+      token = xoauth2_string(user, secret)
+
+      finish("AUTH XOAUTH2 #{base64_encode(token)}")
+    end
+
+    private
+
+    def xoauth2_string(user, secret)
+      "user=#{user}\1auth=Bearer #{secret}\1\1"
+    end
+  end
+end

data/lib/net/smtp/authenticator.rb

@@ -6,11 +6,22 @@ module Net
       end
 
       def self.auth_type(type)
+        type = type.to_s.upcase.tr(?_, ?-).to_sym
         Authenticator.auth_classes[type] = self
       end
 
       def self.auth_class(type)
-        Authenticator.auth_classes[type.intern]
+        type = type.to_s.upcase.tr(?_, ?-).to_sym
+        Authenticator.auth_classes[type]
+      end
+
+      def self.check_args(user_arg = nil, secret_arg = nil, *, **)
+        unless user_arg
+          raise ArgumentError, 'SMTP-AUTH requested but missing user name'
+        end
+        unless secret_arg
+          raise ArgumentError, 'SMTP-AUTH requested but missing secret phrase'
+        end
       end
 
       attr_reader :smtp

data/lib/net/smtp.rb

@@ -79,13 +79,13 @@ module Net
   # == What is This Library?
   #
   # This library provides functionality to send internet
-  # mail via SMTP, the Simple Mail Transfer Protocol. For details of
-  # SMTP itself, see [RFC5321] (http://www.ietf.org/rfc/rfc5321.txt).
-  # This library also implements SMTP authentication, which is often
+  # mail via \SMTP, the Simple Mail Transfer Protocol. For details of
+  # \SMTP itself, see [RFC5321[https://www.rfc-editor.org/rfc/rfc5321.txt]].
+  # This library also implements \SMTP authentication, which is often
   # necessary for message composers to submit messages to their
-  # outgoing SMTP server, see
-  # [RFC6409](http://www.ietf.org/rfc/rfc6503.txt),
-  # and [SMTPUTF8](http://www.ietf.org/rfc/rfc6531.txt), which is
+  # outgoing \SMTP server, see
+  # [RFC6409[https://www.rfc-editor.org/rfc/rfc6409.html]],
+  # and [SMTPUTF8[https://www.rfc-editor.org/rfc/rfc6531.txt]], which is
   # necessary to send messages to/from addresses containing characters
   # outside the ASCII range.
   #
@@ -93,18 +93,20 @@ module Net
   #
   # This library does NOT provide functions to compose internet mails.
   # You must create them by yourself. If you want better mail support,
-  # try RubyMail or TMail or search for alternatives in
+  # try the mail[https://rubygems.org/gems/mail] or
+  # rmail[https://rubygems.org/gems/rmail] gems, or search for alternatives in
   # {RubyGems.org}[https://rubygems.org/] or {The Ruby
   # Toolbox}[https://www.ruby-toolbox.com/].
   #
-  # FYI: the official specification on internet mail is: [RFC5322] (http://www.ietf.org/rfc/rfc5322.txt).
+  # FYI: the official specification on internet mail is:
+  # [RFC5322[https://www.rfc-editor.org/rfc/rfc5322.txt]].
   #
   # == Examples
   #
   # === Sending Messages
   #
-  # You must open a connection to an SMTP server before sending messages.
-  # The first argument is the address of your SMTP server, and the second
+  # You must open a connection to an \SMTP server before sending messages.
+  # The first argument is the address of your \SMTP server, and the second
   # argument is the port number. Using SMTP.start with a block is the simplest
   # way to do this. This way, the SMTP connection is closed automatically
   # after the block is executed.
@@ -114,7 +116,7 @@ module Net
   #       # Use the SMTP object smtp only in this block.
   #     end
   #
-  # Replace 'your.smtp.server' with your SMTP server. Normally
+  # Replace 'your.smtp.server' with your \SMTP server. Normally
   # your system manager or internet provider supplies a server
   # for you.
   #
@@ -147,7 +149,7 @@ module Net
   #     smtp.send_message msgstr, 'from@address', 'to@address'
   #     smtp.finish
   #
-  # You can also use the block form of SMTP.start/SMTP#start.  This closes
+  # You can also use the block form of SMTP.start or SMTP#start.  This closes
   # the SMTP session automatically:
   #
   #     # using block form of SMTP.start
@@ -160,34 +162,37 @@ module Net
   # === HELO domain
   #
   # In almost all situations, you must provide a third argument
-  # to SMTP.start/SMTP#start. This is the domain name which you are on
+  # to SMTP.start or SMTP#start. This is the domain name which you are on
   # (the host to send mail from). It is called the "HELO domain".
-  # The SMTP server will judge whether it should send or reject
+  # The \SMTP server will judge whether it should send or reject
   # the SMTP session by inspecting the HELO domain.
   #
-  #     Net::SMTP.start('your.smtp.server', 25
-  #                     helo: 'mail.from.domain') { |smtp| ... }
+  #     Net::SMTP.start('your.smtp.server', 25, helo: 'mail.from.domain') do |smtp|
+  #       smtp.send_message msgstr, 'from@address', 'to@address'
+  #     end
   #
-  # === SMTP Authentication
+  # === \SMTP Authentication
   #
-  # The Net::SMTP class supports three authentication schemes;
-  # PLAIN, LOGIN and CRAM MD5.  (SMTP Authentication: [RFC2554])
-  # To use SMTP authentication, pass extra arguments to
-  # SMTP.start/SMTP#start.
+  # The Net::SMTP class supports the \SMTP extension for SASL Authentication
+  # [RFC4954[https://www.rfc-editor.org/rfc/rfc4954.html]] and the following
+  # SASL mechanisms: +PLAIN+, +LOGIN+ _(deprecated)_, and +CRAM-MD5+
+  # _(deprecated)_.
+  #
+  # To use \SMTP authentication, pass extra arguments to
+  # SMTP.start or SMTP#start.
   #
   #     # PLAIN
-  #     Net::SMTP.start('your.smtp.server', 25
+  #     Net::SMTP.start('your.smtp.server', 25,
   #                     user: 'Your Account', secret: 'Your Password', authtype: :plain)
-  #     # LOGIN
-  #     Net::SMTP.start('your.smtp.server', 25
-  #                     user: 'Your Account', secret: 'Your Password', authtype: :login)
   #
-  #     # CRAM MD5
-  #     Net::SMTP.start('your.smtp.server', 25
-  #                     user: 'Your Account', secret: 'Your Password', authtype: :cram_md5)
+  # Support for other SASL mechanisms-such as +EXTERNAL+, +OAUTHBEARER+,
+  # +SCRAM-SHA-256+, and +XOAUTH2+-will be added in a future release.
+  #
+  # The +LOGIN+ and +CRAM-MD5+ mechanisms are still available for backwards
+  # compatibility, but are deprecated and should be avoided.
   #
   class SMTP < Protocol
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
 
     # The default SMTP port number, 25.
     def SMTP.default_port
@@ -229,10 +234,13 @@ module Net
     # If the hostname in the server certificate is different from +address+,
     # it can be specified with +tls_hostname+.
     #
-    # Additional SSLContext params can be added to +ssl_context_params+ hash argument and are passed to
-    # +OpenSSL::SSL::SSLContext#set_params+
+    # Additional SSLContext[https://ruby.github.io/openssl/OpenSSL/SSL/SSLContext.html]
+    # params can be added to the +ssl_context_params+ hash argument and are
+    # passed to {OpenSSL::SSL::SSLContext#set_params}[https://ruby.github.io/openssl/OpenSSL/SSL/SSLContext.html#method-i-set_params].
+    #
+    # <tt>tls_verify: true</tt> is equivalent to <tt>ssl_context_params: {
+    # verify_mode: OpenSSL::SSL::VERIFY_PEER }</tt>.
     #
-    # +tls_verify: true+ is equivalent to +ssl_context_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }+.
     # This method does not open the TCP connection.  You can use
     # SMTP.start instead of SMTP.new if you want to do everything
     # at once.  Otherwise, follow SMTP.new with SMTP#start.
@@ -316,12 +324,13 @@ module Net
       auth_capable?('CRAM-MD5')
     end
 
+    # Returns whether the server advertises support for the authentication type.
+    # You cannot get valid result before opening SMTP session.
     def auth_capable?(type)
       return nil unless @capabilities
       return false unless @capabilities['AUTH']
       @capabilities['AUTH'].include?(type)
     end
-    private :auth_capable?
 
     # Returns supported authentication methods on this server.
     # You cannot get valid value before opening SMTP session.
@@ -338,7 +347,7 @@ module Net
 
     alias ssl? tls?
 
-    # Enables SMTP/TLS (SMTPS: SMTP over direct TLS connection) for
+    # Enables SMTP/TLS (SMTPS: \SMTP over direct TLS connection) for
     # this object.  Must be called before the connection is established
     # to have any effect.  +context+ is a OpenSSL::SSL::SSLContext object.
     def enable_tls(context = nil)
@@ -457,7 +466,10 @@ module Net
     #
     # This method is equivalent to:
     #
-    #   Net::SMTP.new(address, port).start(helo: helo_domain, user: account, secret: password, authtype: authtype, tls_verify: flag, tls_hostname: hostname, ssl_context_params: nil)
+    #   Net::SMTP.new(address, port, tls_verify: flag, tls_hostname: hostname, ssl_context_params: nil)
+    #     .start(helo: helo_domain, user: account, secret: password, authtype: authtype)
+    #
+    # See also: Net::SMTP.new, #start
     #
     # === Example
     #
@@ -482,12 +494,6 @@ module Net
     # +helo+ is the _HELO_ _domain_ provided by the client to the
     # server (see overview comments); it defaults to 'localhost'.
     #
-    # The remaining arguments are used for SMTP authentication, if required
-    # or desired.  +user+ is the account name; +secret+ is your password
-    # or other authentication token; and +authtype+ is the authentication
-    # type, one of :plain, :login, or :cram_md5.  See the discussion of
-    # SMTP Authentication in the overview notes.
-    #
     # If +tls+ is true, enable TLS. The default is false.
     # If +starttls+ is :always, enable STARTTLS, if +:auto+, use STARTTLS when the server supports it,
     # if false, disable STARTTLS.
@@ -496,10 +502,26 @@ module Net
     # If the hostname in the server certificate is different from +address+,
     # it can be specified with +tls_hostname+.
     #
-    # Additional SSLContext params can be added to +ssl_context_params+ hash argument and are passed to
-    # +OpenSSL::SSL::SSLContext#set_params+
+    # Additional SSLContext[https://ruby.github.io/openssl/OpenSSL/SSL/SSLContext.html]
+    # params can be added to the +ssl_context_params+ hash argument and are
+    # passed to {OpenSSL::SSL::SSLContext#set_params}[https://ruby.github.io/openssl/OpenSSL/SSL/SSLContext.html#method-i-set_params].
     #
-    # +tls_verify: true+ is equivalent to +ssl_context_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }+.
+    # <tt>tls_verify: true</tt> is equivalent to <tt>ssl_context_params: {
+    # verify_mode: OpenSSL::SSL::VERIFY_PEER }</tt>.
+    #
+    # The remaining arguments are used for \SMTP authentication, if required or
+    # desired.
+    #
+    # +authtype+ is the SASL authentication mechanism.
+    #
+    # +user+ is the authentication or authorization identity.
+    #
+    # +secret+ or +password+ is your password or other authentication token.
+    #
+    # These will be sent to #authenticate as positional arguments-the exact
+    # semantics are dependent on the +authtype+.
+    #
+    # See the discussion of Net::SMTP@SMTP+Authentication in the overview notes.
     #
     # === Errors
     #
@@ -527,7 +549,7 @@ module Net
       new(address, port, tls: tls, starttls: starttls, tls_verify: tls_verify, tls_hostname: tls_hostname, ssl_context_params: ssl_context_params).start(helo: helo, user: user, secret: secret, authtype: authtype, &block)
     end
 
-    # +true+ if the SMTP session has been started.
+    # +true+ if the \SMTP session has been started.
     def started?
       @started
     end
@@ -544,11 +566,21 @@ module Net
     # +helo+ is the _HELO_ _domain_ that you'll dispatch mails from; see
     # the discussion in the overview notes.
     #
-    # If both of +user+ and +secret+ are given, SMTP authentication
-    # will be attempted using the AUTH command.  +authtype+ specifies
-    # the type of authentication to attempt; it must be one of
-    # :login, :plain, and :cram_md5.  See the notes on SMTP Authentication
-    # in the overview.
+    # The remaining arguments are used for \SMTP authentication, if required or
+    # desired.
+    #
+    # +authtype+ is the SASL authentication mechanism.
+    #
+    # +user+ is the authentication or authorization identity.
+    #
+    # +secret+ or +password+ is your password or other authentication token.
+    #
+    # These will be sent to #authenticate as positional arguments-the exact
+    # semantics are dependent on the +authtype+.
+    #
+    # See the discussion of Net::SMTP@SMTP+Authentication in the overview notes.
+    #
+    # See also: Net::SMTP.start
     #
     # === Block Usage
     #
@@ -633,9 +665,8 @@ module Net
 
     def do_start(helo_domain, user, secret, authtype)
       raise IOError, 'SMTP session already started' if @started
-      if user or secret
-        check_auth_method(authtype || DEFAULT_AUTH_TYPE)
-        check_auth_args user, secret
+      if user || secret || authtype
+        check_auth_args authtype, user, secret
       end
       s = Timeout.timeout(@open_timeout, Net::OpenTimeout) do
         tcp_socket(@address, @port)
@@ -831,32 +862,26 @@ module Net
 
     DEFAULT_AUTH_TYPE = :plain
 
+    # Authenticates with the server, using the "AUTH" command.
+    #
+    # +authtype+ is the name of a SASL authentication mechanism.
+    #
+    # All arguments-other than +authtype+-are forwarded to the authenticator.
+    # Different authenticators may interpret the +user+ and +secret+
+    # arguments differently.
     def authenticate(user, secret, authtype = DEFAULT_AUTH_TYPE)
-      check_auth_method authtype
-      check_auth_args user, secret
+      check_auth_args authtype, user, secret
       authenticator = Authenticator.auth_class(authtype).new(self)
       authenticator.auth(user, secret)
     end
 
     private
 
-    def check_auth_method(type)
-      unless Authenticator.auth_class(type)
+    def check_auth_args(type, *args, **kwargs)
+      type ||= DEFAULT_AUTH_TYPE
+      klass = Authenticator.auth_class(type) or
         raise ArgumentError, "wrong authentication type #{type}"
-      end
-    end
-
-    def auth_method(type)
-      "auth_#{type.to_s.downcase}".intern
-    end
-
-    def check_auth_args(user, secret, authtype = DEFAULT_AUTH_TYPE)
-      unless user
-        raise ArgumentError, 'SMTP-AUTH requested but missing user name'
-      end
-      unless secret
-        raise ArgumentError, 'SMTP-AUTH requested but missing secret phrase'
-      end
+      klass.check_args(*args, **kwargs)
     end
 
     #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: net-smtp
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Yukihiro Matsumoto
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-09-20 00:00:00.000000000 Z
+date: 2024-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -38,6 +38,7 @@ files:
 - lib/net/smtp/auth_cram_md5.rb
 - lib/net/smtp/auth_login.rb
 - lib/net/smtp/auth_plain.rb
+- lib/net/smtp/auth_xoauth2.rb
 - lib/net/smtp/authenticator.rb
 homepage: https://github.com/ruby/net-smtp
 licenses:
@@ -61,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.0.dev
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Simple Mail Transfer Protocol client library for Ruby.