mailsmtp 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e3b608d7e843c5cc556588340f9cb6446398479fac9fb8b327256388ad5b254
-  data.tar.gz: e84314276f9336f5d0a8dcf91f4c260aa4ee0d4943a87f098a920078511c138d
+  metadata.gz: 57ea364c7b9a8ef21f22f61233d07a6c6f765f097351765d51fe807dea5dd66a
+  data.tar.gz: b5d59eb1ee5152050d0b3f79001263f5ab1632c46acdc8dbd3a6f99489b07ddf
 SHA512:
-  metadata.gz: 240d4561b11ef3d475d8514d8bb220147d3f29fbba4f72a01b0c692907f72b02686e5218561bf1cd41052f7181f3ec9d0791c7f4bbcc5a3d39006873f85b0ab6
-  data.tar.gz: 5e4565c687ee1f6d4835d6fbddcfd213d701656d97e69e66f48ed9b07007fc12bab82d92a127cf8e7367ed60be18d4d5ced1867e7b771265c03b6c78817e1434
+  metadata.gz: f7319c0c6aeaa73664bd5e47317a6f4bdb3ce64667ae417861da5a32983afebee8824cc3256c0e2f8357713788ec18c3444410d10ff76c873691cd2b5e379fb2
+  data.tar.gz: cee5dfc590c8ec1dc0c00661c84bba351bb0acc3dabb47e5965b81c805e19a965145c0344e79e659d4c2a08429fe5956f6bf4cfb9829de7c37281fd963c52921

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0
+
+- Refuse a SASL PLAIN authzid the application did not grant, and reject identities containing CR or LF
+- Only a String or Symbol returned from `authenticate` now sets `session.authorization_id`
+- Neuter non-printables and RFC 5322 header specials in the HELO/EHLO name
+- Added `MailSmtp::ConnectionLost` so a peer hang-up logs as a disconnect, not an error
+- Require the PROXY preamble before any other command from a peer in `proxy_hosts`
+- Read `MAIL FROM SIZE=` as decimal, so `SIZE=08` no longer raises and `SIZE=0100` is not octal
+- Validate `MailSmtp::Error` subclasses missing `status` on `#response`, not at definition
+
 ## 0.2.1
 
 Documentation
@@ -23,4 +33,4 @@ Documentation
 - Added PROXY protocol v1 support
 - Added TLS hot-swap via `#tls=`
 - Added `session.tls_version` and `session.tls_cipher` after STARTTLS
-- Declared `base64` and `logger` as runtime dependencies
+- Declared `base64` and `logger` as runtime dependencies

data/README.md

@@ -63,7 +63,7 @@ class MyServer < MailSmtp::Server
 
   def authenticate(session, username:, password:, authorization_id: "")
     raise MailSmtp::AuthenticationFailed unless username == "user" && password == "secret"
-    username # becomes session.authorization_id when non-empty
+    username # granted as session.authorization_id
   end
 
   def mail_from(session, address)
@@ -146,7 +146,7 @@ Raising a `MailSmtp::Error` subclass sends that SMTP reply to the client. Other
 | `disconnected`      | `(session)`                                          | —                                                                              |
 | `helo`              | `(session, name)`                                    | after STARTTLS, `session.tls_version` / `session.tls_cipher` are set           |
 | `proxy`             | `(session, proxy_data)`                              | hash replaces PROXY data                                                       |
-| `authenticate`      | `(session, username:, password:, authorization_id:)` | value becomes `authorization_id` (else username); raise `AuthenticationFailed` |
+| `authenticate`      | `(session, username:, password:, authorization_id:)` | returned String grants that `authorization_id`, else the username is used; raise `AuthenticationFailed` |
 | `auth_mechanisms`   | `(session)`                                          |                                                                                |
 | `mail_from`         | `(session, address)`                                 | returned string is stored as envelope from                                     |
 | `rcpt_to`           | `(session, address)`                                 | returned string is appended to envelope to                                     |

data/lib/mailsmtp/data_reader.rb

@@ -87,7 +87,7 @@ module MailSmtp
         # like a clean end-of-message (apps that rescue EOFError would accept a
         # truncated body and the engine would map that to LocalError / 451).
         raise EOFError, "end of data" if @eof
-        raise ServiceUnavailable, "Connection lost during DATA"
+        raise ConnectionLost, "Connection lost during DATA"
       end
 
       chunk = @buffer.slice!(0, maxlen)

data/lib/mailsmtp/error.rb

@@ -8,26 +8,11 @@ module MailSmtp
         @enhanced = enhanced
       end
 
-      def inherited(subclass)
-        # +class Foo < Error+ emits TracePoint :end; Class.new(Error) goes through
-        # Class#initialize and only finishes on that method's :c_return (after any block).
-        if caller_locations(1, 1).first&.label == "Class#initialize"
-          TracePoint.trace(:c_return) do |tp|
-            next unless tp.method_id == :initialize &&
-              tp.defined_class == Class &&
-              tp.return_value.equal?(subclass)
-            tp.disable
-            subclass.assert_status!
-          end
-        else
-          TracePoint.trace(:end) do |tp|
-            next unless tp.self.equal?(subclass)
-            tp.disable
-            subclass.assert_status!
-          end
-        end
-      end
-
+      # A missing status is caught by +#response+, the only place the values are
+      # ever needed. Validating it eagerly at definition time instead would mean
+      # enabling a process-global TracePoint on every subclass — which traces
+      # every thread, and is stranded permanently if the class body raises before
+      # the matching event arrives.
       def assert_status!
         if code.nil? || text.nil? || enhanced.nil?
           raise "MailSmtp::Error subclass #{self} must declare status"

data/lib/mailsmtp/errors.rb

@@ -8,6 +8,12 @@ module MailSmtp
     status 421, "Service too busy or not available, closing transmission channel", enhanced: "4.3.2"
   end
 
+  # 421 — the peer is already gone before any reply could reach it, e.g. a
+  # mid-DATA disconnect. Subclasses +ServiceUnavailable+ so existing rescues
+  # still catch it, but the engine logs it as a routine disconnect, not an error.
+  class ConnectionLost < ServiceUnavailable
+  end
+
   # 451 — the app hit an unexpected error handling an otherwise-valid message
   class LocalError < Error
     status 451, "Requested action aborted: local error in processing", enhanced: "4.3.0"

data/lib/mailsmtp/server.rb

@@ -54,6 +54,25 @@ module MailSmtp
     # up to 12288 octets — not the 512-octet SMTP command-line ceiling.
     MAX_AUTH_LINE_LENGTH = 12_288
 
+    # RFC 5322 header specials: parens (comments), backslash/quote (quoted
+    # strings), angle brackets and "@" (addr-spec), ";" (Received date
+    # delimiter), space (token boundary). Postfix neuters exactly this set.
+    HELO_SPECIALS = ' <>()\\";@'.freeze
+    # Everything outside printable US-ASCII, plus HELO_SPECIALS. Not
+    # fixed-encoding, so it applies to a BINARY subject byte by byte.
+    HELO_UNSAFE = /[^\x20-\x7e]|[#{Regexp.escape(HELO_SPECIALS)}]/
+    # For an SMTPUTF8 HELO: well-formed UTF-8 survives except control/format
+    # characters (\p{Cc}\p{Cf} — bidi overrides, zero-width joiners), non-ASCII
+    # spaces and line separators (\p{Zs}\p{Zl}\p{Zp} — could smuggle whitespace
+    # or newlines past the ASCII rule), and unassigned/private-use codepoints
+    # (\p{Cn}\p{Co}).
+    #
+    # Fixed-encoding UTF-8, so unlike HELO_UNSAFE it raises
+    # Encoding::CompatibilityError on a BINARY subject with high bytes — only
+    # apply it to a valid_encoding? UTF-8 string (see +neuter_helo+).
+    HELO_UNSAFE_UTF8 =
+      /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Zs}\p{Cn}\p{Co}]|[#{Regexp.escape(HELO_SPECIALS)}]/
+
     MAX_FAILED_ACCEPTS = 10
     FAILED_ACCEPT_BACKOFF = 0.5
 
@@ -194,7 +213,8 @@ module MailSmtp
     # Override to customize the opt-in Received header (+add_received: true+).
     def received_header(session)
       protocol = session.encrypted? ? (session.authenticated? ? "ESMTPSA" : "ESMTPS") : "ESMTP"
-      helo = session.helo.to_s.empty? ? "unknown" : session.helo
+      helo = session.helo.to_s
+      helo = helo.empty? ? "unknown" : ascii_only_helo(session, helo)
       "Received: from #{helo} (unknown [#{session.remote_ip}]) " \
         "by #{session.helo_response} with #{protocol}; #{Time.now.utc.strftime("%a, %d %b %Y %H:%M:%S +0000")}\r\n"
     end
@@ -233,6 +253,10 @@ module MailSmtp
     def helo(session, name)
     end
 
+    # Verify +username+/+password+ and raise +AuthenticationFailed+ if they do
+    # not check out. +authorization_id+ is the SASL PLAIN authzid — an
+    # unverified claim by the client, safely ignored by default. To honor it,
+    # verify the account may act as it and return that identity.
     def authenticate(session, username:, password:, authorization_id: "")
       raise AuthenticationFailed
     end
@@ -611,8 +635,12 @@ module MailSmtp
           respond(io, session, reply(221, "Service closing transmission channel")) unless session.close_after_reply
         rescue StopConnection, StopService
           raise
-        rescue EOFError => e
-          log(session, Logger::DEBUG, "Connection lost due abort by client! (EOFError)", err: e)
+        # A hang-up (FIN, or an RST from closing without draining our reply) is
+        # routine, not an error — skip the 421. Must precede the
+        # ServiceUnavailable rescue below, which ConnectionLost extends.
+        # ETIMEDOUT is excluded: retransmit exhaustion is a real network fault.
+        rescue EOFError, ConnectionLost, Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED => e
+          log(session, Logger::DEBUG, "Connection lost due abort by client! (#{e.class})", err: e)
         rescue ServiceUnavailable => e
           session.exceptions += 1
           log(session, Logger::ERROR, loggable_error(e), err: e)
@@ -640,6 +668,38 @@ module MailSmtp
         @connections_mutex.synchronize { @connection_ips.values.count(remote_ip) }
       end
 
+      # RFC 5321 §4.1.1.1 constrains a HELO name, but refusing junk outright
+      # rejects too much mail — replace what's unsafe instead. CR/LF are already
+      # stripped (stops header injection); this stops header *forgery*, where an
+      # unbalanced "(" comments out the rest of a generated Received line for
+      # any consumer that parses those comments as data. Substitution is 1:1 so
+      # distinct names never collapse together.
+      def neuter_helo(name)
+        # Non-ASCII survives only when the server offers SMTPUTF8 (server-wide,
+        # since HELO precedes MAIL FROM) and the bytes are valid UTF-8;
+        # otherwise fall back to the ASCII-only rule.
+        if @smtputf8
+          utf8 = name.dup.force_encoding(Encoding::UTF_8)
+          return utf8.gsub(HELO_UNSAFE_UTF8, "?") if utf8.valid_encoding?
+        end
+
+        name.gsub(HELO_UNSAFE, "?")
+      end
+
+      # Header bodies are US-ASCII (RFC 5322 §2.2) unless this particular
+      # message negotiated SMTPUTF8 (RFC 6532) — known only here, with the
+      # envelope in hand. Re-checks the encoding rather than trusting
+      # +session.helo+ to still be what +neuter_helo+ produced, since it's a
+      # public accessor and +received_header+ is an override point.
+      def ascii_only_helo(session, helo)
+        if session.envelope.encoding_utf8
+          utf8 = helo.dup.force_encoding(Encoding::UTF_8)
+          return utf8 if utf8.valid_encoding?
+        end
+
+        helo.b.gsub(HELO_UNSAFE, "?")
+      end
+
       # Message lines lose only their terminator. Bare LF is rejected when
       # +forbid_bare_newline+ is set (default); see +read_data_line!+.
       def strip_line_terminator(line)
@@ -652,8 +712,12 @@ module MailSmtp
       def loggable_command(session, line)
         if auth_value_phase?(session.phase)
           "[redacted credential]"
-        else
+        elsif line.match?(/\AAUTH\s/i)
           line.sub(/\A(AUTH\s+\S+)\s+\S.*\z/i, '\1 [redacted]')
+        else
+          # Every command runs through here whether or not DEBUG is enabled, so
+          # the traffic that carries no credential skips the rewrite entirely.
+          line
         end
       end
 
@@ -688,6 +752,10 @@ module MailSmtp
         end
       rescue Timeout::Error, IO::TimeoutError
         raise ServiceUnavailable, "Write timed out"
+      rescue Errno::EPIPE, Errno::ECONNRESET, Errno::ECONNABORTED
+        # The peer went away mid-reply. Nothing further can be delivered, so do
+        # not let this surface as a server-side error and provoke a second write.
+        raise ConnectionLost, "Connection lost while writing"
       end
 
       # Success and informational replies. Pass +enhanced: nil+ for replies that
@@ -701,6 +769,14 @@ module MailSmtp
       end
 
       def process_command_line(session, line)
+        # An allowlisted peer skips the per-IP cap until PROXY names the real
+        # client, but nothing forces PROXY to actually arrive — require it
+        # before anything else (PROXY v1: a receiver must not guess whether the
+        # header is there), rather than leaving an indefinite exemption.
+        if proxy_allowed?(session.remote_ip) && !session.proxy && !line.match?(/\APROXY(\s+)/i)
+          raise ServiceUnavailable, "Abort connection while PROXY required from #{session.remote_ip}"
+        end
+
         case line
         when /\A(HELO|EHLO)(\s+.*)?\z/i
             process_helo(session, line)
@@ -748,6 +824,7 @@ module MailSmtp
         match = line.match(/\A(HELO|EHLO)(?:\s+(.*))?\z/i)
         name = match[2].to_s.strip
         raise InvalidParameters if name.empty?
+        name = neuter_helo(name)
 
         # RFC 5321 §4.1.4: a later EHLO/HELO resets state exactly as RSET.
         session.reset if session.phase != :helo
@@ -892,7 +969,9 @@ module MailSmtp
       # refused with 555 (RFC 1869 §6.1) — never silently dropped.
       def apply_mail_from_extensions!(session, address)
         if (declared = address[/\sSIZE=(\d+)\b/i, 1])
-          declared = Integer(declared)
+          # Base 10 explicitly: Integer("0100") would otherwise read as octal and
+          # under-report the declared size, and Integer("08") would raise.
+          declared = Integer(declared, 10)
           session.envelope.declared_size = declared
           if @max_message_size && declared > @max_message_size
             raise MessageTooLarge, "Declared #{declared} bytes, limit is #{@max_message_size}"
@@ -966,10 +1045,17 @@ module MailSmtp
         reader = PrefixedReader.new(received_header(session), reader) if @add_received
 
         error = nil
+        aborting = false
         begin
           receiving_started(session)
           receive(session, reader)
+        rescue ConnectionLost
+          # Nothing left to drain toward, and no reply to line up behind the body.
+          aborting = true
+          raise
         rescue ServiceUnavailable
+          # The app is refusing with a 421 — keep draining to the terminating "."
+          # so a sender still writing the body isn't hit with a write-side reset.
           raise
         rescue Error => e
           error = e
@@ -977,7 +1063,7 @@ module MailSmtp
           log(session, Logger::ERROR, loggable_error(e), err: e)
           error = LocalError.new
         ensure
-          reader.drain
+          reader.drain unless aborting
           session.reset
           # RFC 5321 §4.5.3.1.7: after 552 for SIZE, the server may close.
           # Same when drain hit the absolute ceiling with no "." in sight.
@@ -1022,7 +1108,7 @@ module MailSmtp
               IO.select(nil, [ io.to_io ], nil, IO_WAIT_TIMEOUT)
             end
 
-            raise ServiceUnavailable, "Connection lost during DATA" if io.closed?
+            raise ConnectionLost, "Connection lost during DATA" if io.closed?
             raise ServiceUnavailable, "Server shutting down" if shutdown?
             next
           end
@@ -1043,7 +1129,7 @@ module MailSmtp
       rescue BufferOverrun
         raise ServiceUnavailable, "Input buffer overrun"
       rescue EOFError, Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED
-        raise ServiceUnavailable, "Connection lost during DATA"
+        raise ConnectionLost, "Connection lost during DATA"
       end
 
       def monotonic_time
@@ -1109,14 +1195,48 @@ module MailSmtp
         raise InvalidParameters
       end
 
-      def authorize(session, authorization_id, authentication_id, authentication)
-        return_value = authenticate(session,
+      # The SASL PLAIN authzid is a claim by the client, not a fact (RFC 4954
+      # §4): "victim\0attacker\0password" asks us to treat a login as +victim+.
+      # The application grants it by returning that identity from
+      # +authenticate+; any other return (nil, true, a record) falls back to
+      # the account that proved the password. The raw claim stays available as
+      # +session.requested_authorization_id+.
+      def authorize(session, requested_authorization_id, authentication_id, authentication)
+        # base64 can carry bytes the command grammar never allows through;
+        # CR/LF here would forge header lines when an application logs who
+        # authenticated.
+        if [ requested_authorization_id, authentication_id ].any? { |value| value.to_s.match?(/[\r\n]/) }
+          raise InvalidParameters
+        end
+
+        granted = authenticate(session,
           username: authentication_id,
           password: authentication,
-          authorization_id: authorization_id)
-        authorization_id = return_value if return_value
+          authorization_id: requested_authorization_id)
+        # A non-empty String or Symbol is the application naming the identity —
+        # authoritative, and may differ from the client's claim (canonicalized
+        # case, an alias resolved to its primary address).
+        granted = granted.to_s if granted.is_a?(String) || granted.is_a?(Symbol)
+        granted_explicitly = granted.is_a?(String) && !granted.empty?
+        # The grant gets the same CR/LF check as the claim: an
+        # application-assembled identity can carry it just as easily.
+        raise LocalError if granted_explicitly && granted.match?(/[\r\n]/)
+
+        authorization_id = granted_explicitly ? granted : authentication_id
+
+        # Recorded even when the login is about to be refused, so an application
+        # can audit who was impersonated.
+        session.requested_authorization_id = requested_authorization_id
+
+        # Refuse only when the client claimed a different identity and the
+        # application didn't grant one — asking to be yourself is allowed (RFC
+        # 4616 §2). Compared as bytes: both sides came out of base64 as BINARY.
+        requested = requested_authorization_id.to_s
+        if !requested.empty? && !granted_explicitly && requested.b != authentication_id.to_s.b
+          raise AuthenticationFailed
+        end
 
-        session.authorization_id = authorization_id.to_s.empty? ? authentication_id : authorization_id
+        session.authorization_id = authorization_id
         session.authentication_id = authentication_id
         session.authenticated_at = Time.now.utc
         reply(235, "OK", enhanced: "2.7.0")
@@ -1189,9 +1309,12 @@ module MailSmtp
         # already gone
       end
 
-      # DATA always accepts following body lines in the buffer. PROXY may be
-      # followed immediately by HELO/EHLO before the extension finishes negotiating
-      # the real client IP (typical load-balancer / PROXY clients).
+      # Body lines are not covered here: once DATA is accepted, +read_data_line!+
+      # consumes the buffer directly and never consults this. Sending the DATA
+      # verb itself with the body already behind it is still refused, because the
+      # client is required to wait for the 354. PROXY may be followed immediately
+      # by HELO/EHLO before the extension finishes negotiating the real client IP
+      # (typical load-balancer / PROXY clients).
       def pipelining_allowed?(session)
         @pipelining || (proxy_enabled? && session.phase == :helo)
       end

data/lib/mailsmtp/session.rb

@@ -19,7 +19,8 @@ module MailSmtp
     attr_accessor :phase,
       :local_ip, :remote_ip, :helo, :helo_response, :local_response,
       :connected_at, :encrypted_at, :authenticated_at,
-      :authorization_id, :authentication_id, :auth_login_username,
+      :authorization_id, :authentication_id, :requested_authorization_id,
+      :auth_login_username,
       :exceptions, :auth_failures, :proxy, :close_after_reply,
       :tls_version, :tls_cipher
     attr_reader :envelope
@@ -49,6 +50,7 @@ module MailSmtp
       @authenticated_at = nil
       @authorization_id = nil
       @authentication_id = nil
+      @requested_authorization_id = nil
       @auth_login_username = nil
     end
 

data/lib/mailsmtp/version.rb

@@ -1,3 +1,3 @@
 module MailSmtp
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/mailsmtp.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.authors = [ "Simon Lev" ]
 
   spec.summary = "Boring SMTP server for Ruby."
-  spec.description = "Answers one question: how do I receive emails in Ruby? Implements the SMTP protocol so you can plug in your own logic for auth, accepting mail, and storage."
+  spec.description = "Answers one question: how do I receive emails in Ruby? Implements the SMTP protocol so you can plug in your own logic for auth, accepting mail, and storage. An SMTP server library for building an MX or submission listener."
 
   spec.homepage = "https://github.com/mailpiece/mailsmtp"
   spec.license = "MIT"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailsmtp
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Simon Lev
@@ -38,7 +38,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: 'Answers one question: how do I receive emails in Ruby? Implements the
-  SMTP protocol so you can plug in your own logic for auth, accepting mail, and storage.'
+  SMTP protocol so you can plug in your own logic for auth, accepting mail, and storage.
+  An SMTP server library for building an MX or submission listener.'
 executables: []
 extensions: []
 extra_rdoc_files: []