mailsmtp 0.2.0

data/lib/mailsmtp/server.rb

@@ -0,0 +1,1199 @@
+require "socket"
+require "openssl"
+require "base64"
+require "logger"
+require "ipaddr"
+require "timeout"
+
+module MailSmtp
+  # A thread-per-connection SMTP *server* (no client). Handles the RFC 5321
+  # command sequence (HELO/EHLO, AUTH PLAIN/LOGIN, MAIL FROM, RCPT TO, DATA,
+  # STARTTLS, RSET, NOOP, QUIT, VRFY), leaving domain policy to subclass hooks.
+  # SIZE is advertised and enforced when +max_message_size+ is set; 8BITMIME,
+  # SMTPUTF8, PIPELINING, PROXY, and multi-listen are optional.
+  # STARTTLS always drops any plaintext still buffered after the handshake
+  # (CVE-2011-0411). Implicit TLS (port 465) is not supported yet.
+  #
+  # Policy is subclass verbs (+authenticate+, +mail_from+, +rcpt_to+, +receive+).
+  # During DATA the engine passes a live +DataReader+ into +receive(session, io)+
+  # (dot-unstuffed socket bytes); the app reads or discards, then the engine
+  # drains to "." and replies once.
+  #
+  # +tls+ is any object that responds to +#start(io)+ and returns an SSL socket,
+  # or +nil+ to disable STARTTLS. Reassign +tls+ to hot-swap certificates.
+  class Server
+    AUTH_MODES = %i[ disabled required ].freeze
+    STARTTLS_MODES = %i[ optional required ].freeze
+
+    # RFC 4954 §4: AUTH LOGIN prompts with base64 "Username:" then "Password:".
+    AUTH_LOGIN_USERNAME_PROMPT = "334 #{Base64.strict_encode64("Username:")}".freeze
+    AUTH_LOGIN_PASSWORD_PROMPT = "334 #{Base64.strict_encode64("Password:")}".freeze
+
+    IO_BUFFER_CHUNK_SIZE = 4 * 1024
+    IO_WAIT_TIMEOUT = 1
+    DEFAULT_IO_BUFFER_MAX_SIZE = 1 * 1024 * 1024
+    # RFC 5321 §4.5.3.2.7: servers should wait at least 5 minutes for the next
+    # client command. (The earlier §4.5.3.2.1–.6 times are client-side.)
+    DEFAULT_READ_TIMEOUT = 300
+    DEFAULT_WRITE_TIMEOUT = 30
+    DEFAULT_HANDSHAKE_TIMEOUT = 30
+    DEFAULT_MAX_PROCESSINGS_WAIT = 30
+    DEFAULT_MAX_RECIPIENTS = 100
+    DEFAULT_MAX_MESSAGE_SIZE = 10_485_760 # 10 MiB
+    # Absolute ceiling so idle resets on each line cannot stretch a session forever.
+    DEFAULT_MAX_SESSION_DURATION = 1800
+    DEFAULT_MAX_AUTH_FAILURES = 3
+    DEFAULT_MAX_EXCEPTIONS = 20
+    # Short write budget for a 421 abort after a normal write already timed out,
+    # so we do not stack another full +write_timeout+ before dropping the socket.
+    ABORT_REPLY_WRITE_TIMEOUT = 2
+    # RFC 5321 §4.5.3.1.4 / §4.5.3.1.6 (octets, including the CRLF).
+    MAX_COMMAND_LINE_LENGTH = 512
+    MAX_TEXT_LINE_LENGTH = 1000
+    # RFC 4954 §4: AUTH base64 responses (commands and continuations) may be
+    # up to 12288 octets — not the 512-octet SMTP command-line ceiling.
+    MAX_AUTH_LINE_LENGTH = 12_288
+
+    MAX_FAILED_ACCEPTS = 10
+    FAILED_ACCEPT_BACKOFF = 0.5
+
+    StopService = Class.new(RuntimeError)
+    StopConnection = Class.new(RuntimeError)
+    BufferOverrun = Class.new(RuntimeError)
+    private_constant :StopService, :StopConnection, :BufferOverrun
+
+    attr_reader :max_connections, :max_connections_per_ip, :max_processings
+    # Reassign between STARTTLS negotiations to hot-swap certificates (e.g. ACME).
+    # Engine paths call +#tls+ (not +@tls+) so an overridden reader is honored.
+    attr_accessor :tls
+
+    # +host+/+port+ bind a single address. +hosts+/+ports+ (arrays or
+    # comma-separated strings) expand to every host×port pair (multi-listen).
+    # +proxy_hosts+ non-empty enables PROXY from those IPs or CIDRs.
+    # +add_received+ prepends {#received_header} onto the DATA reader.
+    #
+    # +max_message_size+ is enforced while DATA lines are accepted from the
+    # client (before they are offered to +receive+). After +receive+ returns or
+    # raises, +drain+ discards remaining bytes through "." without re-applying
+    # SIZE — one reply after the body (or a size-ceiling abort).
+    #
+    # When +proxy_hosts+ allowlists a peer, the per-IP connection cap is deferred
+    # until PROXY rewrites the client address — otherwise a load balancer's
+    # shared peer IP would cap the whole listener.
+    def initialize(tls:, max_connections:, max_processings:, auth:, starttls:,
+      host: nil, port: nil, hosts: nil, ports: nil,
+      max_connections_per_ip: nil, eight_bit_mime: false, smtputf8: false,
+      pipelining: false, proxy_hosts: [], add_received: false,
+      forbid_bare_newline: true,
+      max_message_size: DEFAULT_MAX_MESSAGE_SIZE, max_recipients: DEFAULT_MAX_RECIPIENTS,
+      max_processings_wait: DEFAULT_MAX_PROCESSINGS_WAIT,
+      read_timeout: DEFAULT_READ_TIMEOUT, write_timeout: DEFAULT_WRITE_TIMEOUT,
+      handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT,
+      max_session_duration: DEFAULT_MAX_SESSION_DURATION,
+      max_auth_failures: DEFAULT_MAX_AUTH_FAILURES,
+      max_exceptions: DEFAULT_MAX_EXCEPTIONS,
+      io_buffer_max_size: DEFAULT_IO_BUFFER_MAX_SIZE,
+      logger: nil, logger_severity: Logger::INFO)
+      raise ArgumentError, "Unknown auth mode #{auth.inspect}" unless AUTH_MODES.include?(auth)
+      raise ArgumentError, "Unknown starttls mode #{starttls.inspect}" unless STARTTLS_MODES.include?(starttls)
+      raise ArgumentError, "max_recipients must be at least 100 (RFC 5321 §4.5.3.1)" if max_recipients < 100
+      raise ArgumentError, "starttls: :required requires a tls object" if starttls == :required && tls.nil?
+      raise ArgumentError, "max_connections must be an Integer >= 1" unless max_connections.is_a?(Integer) && max_connections >= 1
+      raise ArgumentError, "max_processings must be an Integer >= 1" unless max_processings.is_a?(Integer) && max_processings >= 1
+      unless max_connections_per_ip.nil? || (max_connections_per_ip.is_a?(Integer) && max_connections_per_ip >= 1)
+        raise ArgumentError, "max_connections_per_ip must be nil or an Integer >= 1"
+      end
+      unless max_auth_failures.nil? || (max_auth_failures.is_a?(Integer) && max_auth_failures >= 1)
+        raise ArgumentError, "max_auth_failures must be nil or an Integer >= 1"
+      end
+      unless max_exceptions.nil? || (max_exceptions.is_a?(Integer) && max_exceptions >= 1)
+        raise ArgumentError, "max_exceptions must be nil or an Integer >= 1"
+      end
+
+      @addresses = expand_addresses(hosts || host, ports || port)
+      raise ArgumentError, "host and port (or hosts and ports) are required" if @addresses.empty?
+
+      @tls = tls
+      @max_connections = max_connections
+      @max_connections_per_ip = max_connections_per_ip
+      @max_processings = max_processings
+      @max_processings_wait = max_processings_wait
+      @auth = auth
+      @starttls = starttls
+      @eight_bit_mime = eight_bit_mime
+      @smtputf8 = smtputf8
+      @pipelining = pipelining
+      @forbid_bare_newline = forbid_bare_newline
+      @proxy_hosts = Array(proxy_hosts).map { |entry| IPAddr.new(entry) }
+      @add_received = add_received
+      @max_message_size = max_message_size
+      @max_recipients = max_recipients
+      @read_timeout = read_timeout
+      @write_timeout = write_timeout
+      # STARTTLS budget is independent of +read_timeout+ (which may be nil to
+      # disable idle timeouts). Always apply a finite handshake ceiling —
+      # +Timeout+ alone cannot interrupt OpenSSL's blocking accept, so we also
+      # set +IO#timeout+ around the handshake when the socket supports it.
+      @handshake_timeout = handshake_timeout || DEFAULT_HANDSHAKE_TIMEOUT
+      @max_session_duration = max_session_duration
+      @max_auth_failures = max_auth_failures
+      @max_exceptions = max_exceptions
+      @io_buffer_max_size = io_buffer_max_size
+
+      @stdout_logger = logger || build_default_logger(logger_severity)
+
+      @connections = []
+      @connection_ips = {}
+      @processings = []
+      @connections_mutex = Mutex.new
+      @connections_cv = ConditionVariable.new
+      @shutdown = false
+      @tcp_servers = []
+      @acceptor_threads = []
+    end
+
+    def start
+      raise "Service was already started" unless stopped?
+
+      @shutdown = false
+      @tcp_servers = @addresses.map { |host, port| TCPServer.new(host, port) }
+      attach_acceptors
+    end
+
+    def stop(wait_seconds_before_close: 2)
+      @shutdown = true
+
+      acceptors = @acceptor_threads.dup
+      @connections_mutex.synchronize do
+        acceptors.each { |thread| thread.raise(StopService) }
+      end
+      acceptors.each(&:join)
+      drain_connections(wait_seconds_before_close)
+    end
+
+    def stopped?
+      @acceptor_threads.empty?
+    end
+
+    def connections_count
+      @connections.size
+    end
+
+    def connections?
+      connections_count.positive?
+    end
+
+    def processings_count
+      @processings.size
+    end
+
+    def addresses
+      @addresses.map { |host, port| "#{host}:#{port}" }
+    end
+
+    # 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
+      "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
+
+    # Optional: inspect or replace PROXY data after a valid PROXY line.
+    def proxy(session, proxy_data)
+      proxy_data
+    end
+
+    def log(session, severity, msg, err: nil)
+      if session.respond_to?(:remote_ip) && session.remote_ip
+        msg = "[#{session.remote_ip}] #{msg}"
+      end
+
+      case severity
+      when Logger::FATAL
+          @stdout_logger.fatal(msg)
+          Array(err&.backtrace).each { |line| @stdout_logger.fatal(line) }
+      when Logger::ERROR
+          @stdout_logger.error(msg)
+      when Logger::WARN
+          @stdout_logger.warn(msg)
+      when Logger::INFO
+          @stdout_logger.info(msg)
+      else
+          @stdout_logger.debug(msg)
+      end
+    end
+
+    def connected(session)
+    end
+
+    def disconnected(session)
+    end
+
+    def helo(session, name)
+    end
+
+    def authenticate(session, username:, password:, authorization_id: "")
+      raise AuthenticationFailed
+    end
+
+    # SASL mechanism names advertised on EHLO (`250-AUTH …`) and accepted by
+    # +AUTH+. Default is PLAIN and LOGIN; override to narrow the list or to
+    # advertise additional names before their handlers exist (unknown names
+    # still reply 504 until the engine learns them).
+    def auth_mechanisms(_session)
+      %w[ PLAIN LOGIN ]
+    end
+
+    def mail_from(session, address)
+    end
+
+    def rcpt_to(session, address)
+    end
+
+    def receiving_started(session)
+    end
+
+    def headers_received(session)
+    end
+
+    # +io+ is a +DataReader+ (or +PrefixedReader+) of dot-unstuffed message bytes.
+    # Prefer +IO.copy_stream+ (or chunked +read+) over +io.read+ so large mail
+    # does not become one String. A SIZE or line-length failure raises a
+    # +MailSmtp::Error+ from +read+ — do not treat a short body as success.
+    # The engine drains unread data through "." before replying, except after
+    # +MessageTooLarge+, when it replies 552 and drops the connection.
+    def receive(session, io)
+    end
+
+    def unknown_command(_session, _line)
+      raise CommandNotRecognized
+    end
+
+    # Override to supply a Session subclass.
+    def build_session
+      Session.new
+    end
+
+    # Override for per-command policy (rate limits, session expiry, …). Call
+    # +super+ to keep the engine's command dispatch.
+    def process_line(session, line)
+      case session.phase
+      when :auth_plain
+          process_auth_plain(session, line)
+      when :auth_login_user
+          process_auth_login_username(session, line)
+      when :auth_login_pass
+          process_auth_login_password(session, line)
+      else
+          process_command_line(session, line)
+      end
+    end
+
+    def shutdown?
+      @shutdown
+    end
+
+    private
+      def build_default_logger(severity)
+        Logger.new($stdout).tap do |logger|
+          logger.level = severity
+          logger.datetime_format = "%Y-%m-%d %H:%M:%S"
+          logger.formatter = proc { |sev, datetime, _progname, msg| "#{datetime}: [#{sev}] #{msg.to_s.chomp}\n" }
+        end
+      end
+
+      def expand_addresses(hosts, ports)
+        host_list = Array(hosts).flat_map { |value| value.to_s.split(/[,\s]+/) }.map(&:strip).reject(&:empty?)
+        port_list = Array(ports).flat_map { |value| value.to_s.split(/[,\s:]+/) }.map(&:strip).reject(&:empty?).map { |port| Integer(port) }
+        host_list.product(port_list)
+      end
+
+      def attach_acceptors
+        @acceptor_threads = @tcp_servers.map do |tcp_server|
+          Thread.new { accept_loop(tcp_server) }
+        end
+      end
+
+      def proxy_enabled?
+        @proxy_hosts.any?
+      end
+
+      def proxy_allowed?(remote_ip)
+        return false unless proxy_enabled?
+        return false if remote_ip.nil?
+
+        @proxy_hosts.any? { |allowed| allowed.include?(remote_ip) }
+      end
+
+      # A failed accept is usually the machine's problem, not ours — a client that
+      # vanished mid-handshake, or no file descriptors left for a moment — so we
+      # log it and keep listening. Only a run of failures long enough to look
+      # permanent takes the listener down, and then the supervisor restarts it.
+      def accept_loop(tcp_server)
+        failed_accepts = 0
+
+        until shutdown?
+          begin
+            client = tcp_server.accept
+            failed_accepts = 0
+            Thread.new(client) { |io| handle_connection(io) }
+          rescue StopService
+            raise
+          rescue StandardError => e
+            failed_accepts += 1
+            raise if failed_accepts > MAX_FAILED_ACCEPTS
+
+            log(nil, Logger::ERROR, "Can't accept a connection (#{failed_accepts}/#{MAX_FAILED_ACCEPTS}): #{loggable_error(e)}")
+            sleep FAILED_ACCEPT_BACKOFF
+          end
+        end
+      rescue StopService
+        # signaled by #stop, not an error
+      rescue StandardError => e
+        log(nil, Logger::FATAL, loggable_error(e), err: e)
+      ensure
+        close_tcp_server(tcp_server)
+        @acceptor_threads.delete(Thread.current)
+      end
+
+      # Give in-flight connections a bounded moment to finish on their own (a
+      # delivery is a quick DB transaction), then force any stragglers and wait
+      # for them to unwind, so we never exit the process mid-message.
+      def drain_connections(grace_seconds)
+        deadline = monotonic_time + grace_seconds
+        sleep 0.05 while connections? && monotonic_time < deadline
+
+        stragglers = @connections.dup
+        stragglers.each { |thread| thread.raise(StopConnection) }
+        stragglers.each(&:join)
+      end
+
+      def close_tcp_server(tcp_server)
+        tcp_server.close
+      rescue StandardError
+        # already gone
+      end
+
+      # Keyed by thread so a slot is released exactly where the connection is: a
+      # count that drifted upward would leave the listener refusing everyone.
+      def handle_connection(io)
+        begin
+          session = build_session
+          io = serve_client(session, io)
+        rescue StopConnection
+          # Forced stop after the grace window — RST so the peer does not sit
+          # half-open waiting on a bare FIN.
+          abort_socket!(io)
+          io = nil
+        rescue StandardError => e
+          log(nil, Logger::FATAL, loggable_error(e), err: e)
+        ensure
+          begin
+            if io
+              abort_socket!(io) if shutdown?
+              io.close unless io.closed?
+            end
+          rescue StandardError
+            # already gone
+          end
+
+          release_connection_slot!
+        end
+      end
+
+      # Register this thread under +remote_ip+ and enforce global / per-IP caps in
+      # the same critical section. Re-calling with a new IP (PROXY) updates the
+      # identity and re-checks the per-IP cap against the rewritten address.
+      # Pass +enforce_per_ip: false+ for an allowlisted PROXY peer before the
+      # PROXY line rewrites the client — the load balancer IP must not consume
+      # the per-IP budget for every tenant behind it.
+      def claim_connection_slot!(remote_ip, enforce_per_ip: true)
+        @connections_mutex.synchronize do
+          if @connections.include?(Thread.current)
+            old_ip = @connection_ips[Thread.current]
+            if old_ip != remote_ip
+              if enforce_per_ip && max_connections_per_ip && remote_ip &&
+                  @connection_ips.values.count(remote_ip) >= max_connections_per_ip
+                raise ServiceUnavailable, "Too many connections from #{remote_ip}"
+              end
+              @connection_ips[Thread.current] = remote_ip
+            end
+          else
+            if max_connections && @connections.size >= max_connections
+              raise ServiceUnavailable, "Abort connection while too busy, exceeding max_connections!"
+            end
+            if enforce_per_ip && max_connections_per_ip && remote_ip &&
+                @connection_ips.values.count(remote_ip) >= max_connections_per_ip
+              raise ServiceUnavailable, "Too many connections from #{remote_ip}"
+            end
+            @connections << Thread.current
+            @connection_ips[Thread.current] = remote_ip
+          end
+        end
+      end
+
+      def release_connection_slot!
+        @connections_mutex.synchronize do
+          @connections.delete(Thread.current)
+          @connection_ips.delete(Thread.current)
+          # Safety: a mid-DATA abort must not leave a processing slot stuck.
+          @processings.delete(Thread.current)
+          @connections_cv.signal
+        end
+      end
+
+      # Processing slots gate concurrent DATA transfers only — idle/envelope
+      # sessions do not consume one.
+      def claim_processing_slot!
+        @connections_mutex.synchronize do
+          deadline = monotonic_time + @max_processings_wait
+          until processings_count < max_processings
+            remaining = deadline - monotonic_time
+            raise ServiceUnavailable, "Abort connection while too busy, exceeding max_processings!" if remaining <= 0
+
+            @connections_cv.wait(@connections_mutex, remaining)
+          end
+          @processings << Thread.current
+        end
+      end
+
+      def release_processing_slot!
+        @connections_mutex.synchronize do
+          @processings.delete(Thread.current)
+          @connections_cv.signal
+        end
+      end
+
+      # A socket the client has already abandoned has no peer to name; claim under
+      # a nil IP (counts only against the global cap).
+      def serve_client(session, io)
+        notified_connected = false
+        begin
+          session.local_ip = io.addr(:numeric)[3]
+          session.remote_ip = io.peeraddr(:numeric)[3]
+          session.connected_at = Time.now.utc
+          session.local_response = "#{session.local_ip} ESMTP"
+          session.helo_response = session.local_ip
+
+          claim_connection_slot!(session.remote_ip, enforce_per_ip: !proxy_allowed?(session.remote_ip))
+          connected(session)
+          notified_connected = true
+
+          # Greeting is before EHLO advertises ENHANCEDSTATUSCODES — plain 220.
+          respond(io, session, reply(220, session.local_response.to_s.strip, enhanced: nil))
+
+          io_buffer = +""
+          io_buffer_line_lf = nil
+          idle_since = monotonic_time
+          session_deadline = @max_session_duration && (idle_since + @max_session_duration)
+
+          loop do
+            if session.phase == :starttls
+              begin
+                io = with_handshake_timeout(io) { tls.start(io) }
+              rescue Timeout::Error, IO::TimeoutError
+                raise ServiceUnavailable, "STARTTLS timed out"
+              rescue StandardError => e
+                log(session, Logger::ERROR, loggable_error(e), err: e)
+                return io
+              end
+
+              # RFC 3207 §4.2: after the handshake, discard everything the client
+              # told us in plaintext (HELO, envelope, AUTH) and require a fresh HELO.
+              session.reset
+              session.reset_authentication
+              session.helo = nil
+              session.encrypted_at = Time.now.utc
+              record_tls_details!(session, io)
+              session.phase = :helo
+              idle_since = monotonic_time
+
+              # Bytes still buffered here arrived in the clear behind STARTTLS, so
+              # a MITM could have written them. Drop them rather than let them be
+              # read back as commands from inside the TLS session (CVE-2011-0411).
+              io_buffer.clear
+              io_buffer_line_lf = nil
+            end
+
+            begin
+              unless io_buffer_line_lf
+                raise_if_session_expired!(session_deadline)
+                raise_if_idle_timeout!(idle_since)
+                io_buffer << io.read_nonblock(IO_BUFFER_CHUNK_SIZE)
+                raise BufferOverrun if @io_buffer_max_size && io_buffer.length > @io_buffer_max_size
+                io_buffer_line_lf = io_buffer.index("\n")
+              end
+            # No data ready: block on the socket instead of busy-polling. We only
+            # get here once read_nonblock has drained any bytes SSLSocket buffered
+            # internally, so waiting on the raw fd is safe. A TLS renegotiation can
+            # ask to write mid-read, hence the WaitWritable arm.
+            rescue IO::WaitReadable
+              raise_if_session_expired!(session_deadline)
+              raise_if_idle_timeout!(idle_since)
+              IO.select([ io.to_io ], nil, nil, IO_WAIT_TIMEOUT)
+            rescue IO::WaitWritable
+              raise_if_session_expired!(session_deadline)
+              raise_if_idle_timeout!(idle_since)
+              IO.select(nil, [ io.to_io ], nil, IO_WAIT_TIMEOUT)
+            end
+
+            while io_buffer_line_lf
+              line = io_buffer.slice!(0, io_buffer_line_lf + 1)
+              io_buffer_line_lf = io_buffer.index("\n")
+              command_ok = false
+
+              begin
+                raise_if_session_expired!(session_deadline)
+                raise_if_idle_timeout!(idle_since)
+                raise PipeliningNotSupported if io_buffer_line_lf && !pipelining_allowed?(session)
+
+                # Commands get every CR and LF removed, not just the terminator,
+                # so a bare CR can't ride inside an address into the envelope.
+                line.delete!("\r\n")
+                max_line = auth_line_length?(session, line) ? MAX_AUTH_LINE_LENGTH : MAX_COMMAND_LINE_LENGTH
+                raise InvalidParameters, "Command line too long" if line.bytesize + 2 > max_line
+                log(session, Logger::DEBUG, "<<< #{loggable_command(session, line)}\n")
+
+                output = process_line(session, line)
+
+                # After 354, pull the body with a live reader into +receive+, then
+                # one final reply — no SMTP responses mid-DATA.
+                if session.phase == :data
+                  respond(io, session, output) if output && !output.empty?
+                  output = transfer_data(session, io, io_buffer, session_deadline: session_deadline)
+                  io_buffer_line_lf = io_buffer.index("\n")
+                end
+
+                respond(io, session, output) if output && !output.empty?
+                command_ok = true
+                break if session.close_after_reply
+              rescue ServiceUnavailable
+                # 421 aborts the connection: re-raise past the command loop so the
+                # outer handler sends a single closing reply and drops the socket.
+                raise
+              rescue PipeliningNotSupported => e
+                session.exceptions += 1
+                log(session, Logger::ERROR, loggable_error(e), err: e)
+                respond(io, session, e.response)
+                # Drop the pipelined continuation still buffered (e.g. an AUTH
+                # credential) so it isn't re-read, logged unredacted, and run out
+                # of sequence. Same reasoning as the STARTTLS buffer drop above.
+                io_buffer.clear
+                io_buffer_line_lf = nil
+                raise_if_exception_caps!(session, e)
+              rescue Error => e
+                session.exceptions += 1
+                session.auth_failures += 1 if e.is_a?(AuthenticationFailed)
+                log(session, Logger::ERROR, loggable_error(e), err: e)
+                respond(io, session, e.response)
+                raise_if_exception_caps!(session, e)
+              rescue StandardError => e
+                session.exceptions += 1
+                log(session, Logger::ERROR, loggable_error(e), err: e)
+                respond(io, session, LocalError.new.response)
+                raise_if_exception_caps!(session, e)
+              end
+
+              # Idle timer advances only on a fully successful command — errors and
+              # probes must not keep a slowloris session alive forever by themselves.
+              idle_since = monotonic_time if command_ok
+
+              # STARTTLS and QUIT end the plaintext conversation, so anything the
+              # client pipelined behind them must not be run as if it belonged to
+              # the session that follows. Hand back to the outer loop instead.
+              break if %i[ starttls quit ].include?(session.phase)
+            end
+
+            break if session.phase == :quit || session.close_after_reply || io.closed? || shutdown?
+          end
+
+          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)
+        rescue ServiceUnavailable => e
+          session.exceptions += 1
+          log(session, Logger::ERROR, loggable_error(e), err: e)
+          begin
+            respond(io, session, e.response, abort_reply: true)
+          rescue ServiceUnavailable, StandardError => send_error
+            log(session, Logger::DEBUG, "Can't send 421 abort code! (#{send_error.class})", err: send_error)
+          end
+        rescue StandardError => e
+          session.exceptions += 1
+          log(session, Logger::ERROR, loggable_error(e), err: e)
+          begin
+            respond(io, session, ServiceUnavailable.new.response, abort_reply: true)
+          rescue ServiceUnavailable, StandardError => send_error
+            log(session, Logger::DEBUG, "Can't send 421 abort code! (#{send_error.class})", err: send_error)
+          end
+        ensure
+          disconnected(session) if notified_connected
+        end
+
+        io
+      end
+
+      def connections_from(remote_ip)
+        @connections_mutex.synchronize { @connection_ips.values.count(remote_ip) }
+      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)
+        line.sub!(/\r?\n\z/, "")
+      end
+
+      # Mask credentials before they reach the DEBUG log: an AUTH value-state line
+      # is the secret itself, and an inline "AUTH PLAIN/LOGIN <arg>" carries it in
+      # the argument. Everything else logs verbatim.
+      def loggable_command(session, line)
+        if auth_value_phase?(session.phase)
+          "[redacted credential]"
+        else
+          line.sub(/\A(AUTH\s+\S+)\s+\S.*\z/i, '\1 [redacted]')
+        end
+      end
+
+      def auth_value_phase?(phase)
+        %i[ auth_plain auth_login_user auth_login_pass ].include?(phase)
+      end
+
+      # Most protocol errors are raised bare, because the class is the whole
+      # explanation — and a bare exception's message *is* its class name, so the
+      # usual "message (Class)" form prints it twice. Name the class once when
+      # that is all there is to say. The remote IP is left to +log+, which
+      # prefixes every line with it.
+      def loggable_error(error)
+        message = error.message.to_s
+        message == error.class.name ? message : "#{message} (#{error.class})"
+      end
+
+      def respond(io, session, output, abort_reply: false)
+        log(session, Logger::DEBUG, ">>> #{output}")
+        return if io.closed?
+
+        write_timeout = if abort_reply
+          [ @write_timeout, ABORT_REPLY_WRITE_TIMEOUT ].compact.min
+        else
+          @write_timeout
+        end
+
+        if write_timeout
+          Timeout.timeout(write_timeout) { io.print("#{output}\r\n") }
+        else
+          io.print("#{output}\r\n")
+        end
+      rescue Timeout::Error, IO::TimeoutError
+        raise ServiceUnavailable, "Write timed out"
+      end
+
+      # Success and informational replies. Pass +enhanced: nil+ for replies that
+      # omit the RFC 2034 status (greeting, EHLO multilines, 354, AUTH 334).
+      def reply(code, text, enhanced: "2.0.0")
+        if enhanced.nil?
+          "#{code} #{text}"
+        else
+          "#{code} #{enhanced} #{text}"
+        end
+      end
+
+      def process_command_line(session, line)
+        case line
+        when /\A(HELO|EHLO)(\s+.*)?\z/i
+            process_helo(session, line)
+        when /\APROXY(\s+)/i
+            process_proxy(session, line)
+        when /\ASTARTTLS\s*\z/i
+            process_starttls(session)
+        # The initial response is framed loosely and validated where it is
+        # decoded: the continuation form arrives on a bare line no regex guards,
+        # so decode_base64 is already the one gate on that path, and keeping a
+        # second copy of the base64 alphabet here would only let the two drift.
+        when /\AAUTH(\s+)(\S+)(\s+\S+)?\s*\z/i
+            process_auth(session, line)
+        when /\ANOOP(\s+.*)?\z/i
+            reply(250, "OK")
+        when /\AVRFY(\s+.*)?\z/i
+            # RFC 5321 §3.5 / §4.5.1: always implement VRFY; 252 is the safe
+            # answer when we will not confirm mailbox existence.
+            reply(252, "Cannot VRFY user, but will accept message and attempt delivery", enhanced: "2.5.0")
+        when /\AEXPN(\s+.*)?\z/i
+            raise CommandNotImplemented
+        when /\AHELP(\s+.*)?\z/i
+            raise CommandNotImplemented
+        when /\ARSET\s*\z/i
+            process_rset(session)
+        when /\AQUIT\s*\z/i
+            session.phase = :quit
+            ""
+        when /\AMAIL FROM:/i
+            process_mail_from(session, line)
+        when /\ARCPT TO:/i
+            process_rcpt_to(session, line)
+        when /\ADATA\s*\z/i
+            process_data_start(session)
+        else
+            unknown_command(session, line)
+        end
+      end
+
+      def process_helo(session, line)
+        # Mid-AUTH / mid-DATA are not a fresh greeting opportunity.
+        raise BadSequence if auth_value_phase?(session.phase) || session.phase == :data
+
+        # Bare HELO/EHLO (no argument) must not treat the verb as the hostname.
+        match = line.match(/\A(HELO|EHLO)(?:\s+(.*))?\z/i)
+        name = match[2].to_s.strip
+        raise InvalidParameters if name.empty?
+
+        # RFC 5321 §4.1.4: a later EHLO/HELO resets state exactly as RSET.
+        session.reset if session.phase != :helo
+
+        helo(session, name)
+        session.helo = name
+        session.phase = :ready
+
+        if line.match?(/\AEHLO/i)
+          [
+            "250-#{session.helo_response.to_s.strip}",
+            "250-ENHANCEDSTATUSCODES",
+            (@max_message_size ? "250-SIZE #{@max_message_size}" : nil),
+            (@eight_bit_mime ? "250-8BITMIME" : nil),
+            (@smtputf8 ? "250-SMTPUTF8" : nil),
+            (@pipelining ? "250-PIPELINING" : nil),
+            (auth_ehlo_line(session)),
+            (starttls_available?(session) ? "250-STARTTLS" : nil),
+            # EHLO multilines omit enhanced codes.
+            reply(250, "OK", enhanced: nil)
+          ].compact.join("\r\n")
+        else
+          reply(250, session.helo_response.to_s.strip)
+        end
+      end
+
+      def process_proxy(session, line)
+        raise CommandNotRecognized unless proxy_enabled?
+        raise BadSequence if session.phase != :helo
+        raise ServiceUnavailable, "Abort connection while PROXY not allowed from #{session.remote_ip}" unless proxy_allowed?(session.remote_ip)
+        raise ServiceUnavailable, "Abort connection while PROXY already set!" if session.proxy
+        raise ServiceUnavailable, "Abort connection while illegal PROXY command!" unless line.match?(
+          /\APROXY(\s+)(UNKNOWN(|(\s+).*)|TCP(4|6)(\s+)([0-9a-f.:]+)(\s+)([0-9a-f.:]+)(\s+)([0-9]+)(\s+)([0-9]+)\s*)\z/i
+        )
+
+        parts = line.sub(/\APROXY\s+/i, "").strip.split(/\s+/)
+        proxy_data = { proto: parts[0].upcase, source_ip: nil, source_port: nil, dest_ip: nil, dest_port: nil }
+
+        unless proxy_data[:proto] == "UNKNOWN"
+          begin
+            proxy_data[:source_ip] = IPAddr.new(parts[1])
+            proxy_data[:dest_ip] = IPAddr.new(parts[2])
+            proxy_data[:source_port] = Integer(parts[3])
+            proxy_data[:dest_port] = Integer(parts[4])
+            raise unless proxy_data[:source_port].between?(1, 65_535)
+            raise unless proxy_data[:dest_port].between?(1, 65_535)
+
+            if proxy_data[:proto] == "TCP4"
+              raise unless proxy_data[:source_ip].ipv4? && proxy_data[:dest_ip].ipv4?
+            else
+              raise unless proxy_data[:source_ip].ipv6? && proxy_data[:dest_ip].ipv6?
+            end
+
+            proxy_data[:source_ip] = proxy_data[:source_ip].to_s
+            proxy_data[:dest_ip] = proxy_data[:dest_ip].to_s
+          rescue StandardError
+            raise ServiceUnavailable, "Abort connection for unsupported PROXY parameters!"
+          end
+        end
+
+        proxy_data = proxy(session, proxy_data) || proxy_data
+        session.proxy = proxy_data
+        if proxy_data[:source_ip]
+          claim_connection_slot!(proxy_data[:source_ip], enforce_per_ip: true)
+          session.remote_ip = proxy_data[:source_ip]
+        end
+
+        # No SMTP reply — PROXY is a preamble, not a command the client awaits.
+        ""
+      end
+
+      def process_starttls(session)
+        raise CommandNotRecognized unless tls
+        raise BadSequence unless session.phase == :ready
+        raise BadSequence if session.encrypted?
+
+        session.phase = :starttls
+        reply(220, "Ready to start TLS")
+      end
+
+      def process_auth(session, line)
+        raise CommandNotRecognized if @auth == :disabled
+        raise BadSequence if session.phase != :ready || session.authenticated?
+        raise EncryptionRequired if encryption_required? && !session.encrypted?
+
+        auth_data = line.sub(/\AAUTH\s/i, "").strip.split(/\s+/)
+        mechanism = auth_data[0].to_s.upcase
+        raise AuthenticationTypeNotSupported unless auth_mechanism_offered?(session, mechanism)
+
+        # PLAIN and LOGIN both send the same secret over the required TLS, just in
+        # one response vs. across two prompts. Other advertised names need an
+        # engine handler before AUTH can succeed (504 until then).
+        case mechanism
+        when "PLAIN"
+            if auth_data.length == 1
+              session.phase = :auth_plain
+              "334 "
+            else
+              process_auth_plain(session, auth_data[1])
+            end
+        when "LOGIN"
+            if auth_data.length == 1
+              session.phase = :auth_login_user
+              AUTH_LOGIN_USERNAME_PROMPT
+            else
+              process_auth_login_username(session, auth_data[1])
+            end
+        else
+            raise AuthenticationTypeNotSupported
+        end
+      end
+
+      def process_rset(session)
+        raise BadSequence if auth_value_phase?(session.phase) || session.phase == :data
+        raise EncryptionRequired if session.phase != :helo && encryption_required? && !session.encrypted?
+
+        # Before HELO there is no transaction to clear; still answer 250 (RFC 5321).
+        session.reset unless session.phase == :helo
+        reply(250, "OK")
+      end
+
+      def process_mail_from(session, line)
+        raise BadSequence if session.phase != :ready
+        raise EncryptionRequired if encryption_required? && !session.encrypted?
+        raise AuthenticationRequired if @auth == :required && !session.authenticated?
+
+        address = line.sub(/\AMAIL FROM:/i, "").strip
+        raise InvalidParameters if address.include?("\0")
+        address = apply_mail_from_extensions!(session, address)
+
+        address = mail_from(session, address) || address
+        session.envelope.from = address
+        session.phase = :mail
+        reply(250, "OK")
+      end
+
+      # BODY is the 8BITMIME parameter (RFC 6152). SMTPUTF8 (RFC 6531) marks an
+      # internationalized envelope. SIZE= (RFC 1870) is checked against
+      # +max_message_size+ when set. Unknown BODY= values are always refused;
+      # BODY=/SMTPUTF8 themselves require the matching extension to be on.
+      # Remaining KEY=VALUE ESMTP parameters after known ones are stripped are
+      # 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)
+          session.envelope.declared_size = declared
+          if @max_message_size && declared > @max_message_size
+            raise MessageTooLarge, "Declared #{declared} bytes, limit is #{@max_message_size}"
+          end
+        end
+
+        if address.match?(/\sBODY=7BIT\b/i)
+          raise InvalidParameters unless @eight_bit_mime
+          session.envelope.encoding_body = "7bit"
+        elsif address.match?(/\sBODY=8BITMIME\b/i)
+          raise InvalidParameters unless @eight_bit_mime
+          session.envelope.encoding_body = "8bitmime"
+        elsif address.match?(/\sBODY=\S+/i)
+          raise InvalidParameters
+        end
+
+        if address.match?(/\sSMTPUTF8\b/i)
+          raise InvalidParameters unless @smtputf8
+          session.envelope.encoding_utf8 = "utf8"
+        end
+
+        raise InvalidParameters if !@smtputf8 && !address.ascii_only?
+
+        address = address
+          .gsub(/\sSIZE=\d+\b/i, "")
+          .gsub(/\sBODY=(?:7BIT|8BITMIME)\b/i, "")
+          .gsub(/\sSMTPUTF8\b/i, "")
+          .strip
+
+        raise ParametersNotRecognized if address.match?(/\s+\S+=\S+/)
+        address
+      end
+
+      def process_rcpt_to(session, line)
+        raise BadSequence unless %i[ mail rcpt ].include?(session.phase)
+        raise EncryptionRequired if encryption_required? && !session.encrypted?
+        raise AuthenticationRequired if @auth == :required && !session.authenticated?
+        raise TooManyRecipients if session.envelope.to.size >= @max_recipients
+
+        address = line.sub(/\ARCPT TO:/i, "").strip
+        raise InvalidParameters if address.include?("\0")
+        raise InvalidParameters if !@smtputf8 && !address.ascii_only?
+        # RCPT TO advertises no ESMTP parameters — refuse any KEY=VALUE trail.
+        raise ParametersNotRecognized if address.match?(/\s+\S+=\S+/)
+
+        address = rcpt_to(session, address) || address
+        session.envelope.to << address
+        session.phase = :rcpt
+        reply(250, "OK")
+      end
+
+      def process_data_start(session)
+        raise BadSequence if session.phase != :rcpt
+        raise EncryptionRequired if encryption_required? && !session.encrypted?
+        raise AuthenticationRequired if @auth == :required && !session.authenticated?
+
+        session.phase = :data
+        reply(354, "Enter message, ending with \".\" on a line by itself", enhanced: nil)
+      end
+
+      # Send no SMTP replies until the terminating "." — then one success or error.
+      def transfer_data(session, io, io_buffer, session_deadline: nil)
+        claim_processing_slot!
+        idle_since = [ monotonic_time ]
+        reader = DataReader.new(
+          max_message_size: @max_message_size,
+          max_line_length: MAX_TEXT_LINE_LENGTH,
+          on_headers: -> { headers_received(session) }
+        ) { read_data_line!(io, io_buffer, idle_since, session_deadline) }
+
+        reader = PrefixedReader.new(received_header(session), reader) if @add_received
+
+        error = nil
+        begin
+          receiving_started(session)
+          receive(session, reader)
+        rescue ServiceUnavailable
+          raise
+        rescue Error => e
+          error = e
+        rescue StandardError => e
+          log(session, Logger::ERROR, loggable_error(e), err: e)
+          error = LocalError.new
+        ensure
+          reader.drain
+          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.
+          if (error || reader.failure).is_a?(MessageTooLarge) || reader.drain_ceiling_hit?
+            session.close_after_reply = true
+          end
+        end
+
+        error ||= reader.failure
+        if error
+          session.exceptions += 1
+          log(session, Logger::ERROR, loggable_error(error), err: error)
+          error.response
+        else
+          reply(250, "Requested mail action okay, completed")
+        end
+      ensure
+        release_processing_slot!
+      end
+
+      # Next DATA line as dot-unstuffed bytes plus CRLF, or +nil+ at the terminator.
+      # The terminating "." counts only when it arrived as CRLF-terminated
+      # (RFC 5321 / CVE-2023-51764 class SMTP smuggling). A bare-LF "." is body.
+      def read_data_line!(io, io_buffer, idle_since, session_deadline)
+        loop do
+          raise_if_session_expired!(session_deadline)
+
+          lf = io_buffer.index("\n")
+          unless lf
+            raise_if_idle_timeout!(idle_since[0])
+
+            begin
+              io_buffer << io.read_nonblock(IO_BUFFER_CHUNK_SIZE)
+              raise BufferOverrun if @io_buffer_max_size && io_buffer.length > @io_buffer_max_size
+            rescue IO::WaitReadable
+              raise_if_session_expired!(session_deadline)
+              raise_if_idle_timeout!(idle_since[0])
+              IO.select([ io.to_io ], nil, nil, IO_WAIT_TIMEOUT)
+            rescue IO::WaitWritable
+              raise_if_session_expired!(session_deadline)
+              raise_if_idle_timeout!(idle_since[0])
+              IO.select(nil, [ io.to_io ], nil, IO_WAIT_TIMEOUT)
+            end
+
+            raise ServiceUnavailable, "Connection lost during DATA" if io.closed?
+            raise ServiceUnavailable, "Server shutting down" if shutdown?
+            next
+          end
+
+          line = io_buffer.slice!(0, lf + 1)
+          crlf = line.end_with?("\r\n")
+          raise BareNewline if @forbid_bare_newline && !crlf
+
+          strip_line_terminator(line)
+          idle_since[0] = monotonic_time
+
+          # End-of-data is only <CRLF>.<CRLF> — never a bare-LF dot.
+          return nil if line == "." && crlf
+
+          line.slice!(0) if line[0] == "."
+          return "#{line}\r\n"
+        end
+      rescue BufferOverrun
+        raise ServiceUnavailable, "Input buffer overrun"
+      rescue EOFError, Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED
+        raise ServiceUnavailable, "Connection lost during DATA"
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # Apply +@handshake_timeout+ even when +read_timeout+ is nil. Prefer the
+      # socket's own timeout (interrupts OpenSSL accept); wrap with Timeout as a
+      # fallback for pure-Ruby +tls+ objects (test doubles, sleep-based stubs).
+      def with_handshake_timeout(io)
+        previous = io.respond_to?(:timeout) ? io.timeout : :unset
+        io.timeout = @handshake_timeout if io.respond_to?(:timeout=)
+        Timeout.timeout(@handshake_timeout) { yield }
+      ensure
+        if previous != :unset && io.respond_to?(:timeout=)
+          io.timeout = previous
+        end
+      end
+
+      def raise_if_idle_timeout!(idle_since)
+        return unless @read_timeout
+        raise ServiceUnavailable, "Read timed out" if monotonic_time - idle_since > @read_timeout
+      end
+
+      def raise_if_session_expired!(session_deadline)
+        return unless session_deadline
+        raise ServiceUnavailable, "Session time limit exceeded" if monotonic_time > session_deadline
+      end
+
+      def process_auth_plain(session, encoded_auth_response)
+        auth_values = decode_base64(encoded_auth_response).split("\x00")
+        raise InvalidParameters unless auth_values.length == 3
+
+        authorize(session, *auth_values)
+      ensure
+        session.phase = :ready
+      end
+
+      # LOGIN sends the username and secret on separate base64 lines; hold the
+      # username between turns, then run the same authorize path PLAIN does.
+      def process_auth_login_username(session, encoded_username)
+        session.auth_login_username = decode_base64(encoded_username)
+        session.phase = :auth_login_pass
+        AUTH_LOGIN_PASSWORD_PROMPT
+      rescue Error
+        session.phase = :ready
+        raise
+      end
+
+      def process_auth_login_password(session, encoded_password)
+        authorize(session, "", session.auth_login_username, decode_base64(encoded_password))
+      ensure
+        session.auth_login_username = nil
+        session.phase = :ready
+      end
+
+      # Strictly, so that a mangled credential is refused outright: Base64.decode64
+      # silently discards anything outside the alphabet, which would turn a typo or
+      # a smuggled byte into a different, perfectly plausible credential.
+      def decode_base64(encoded_auth_response)
+        Base64.strict_decode64(encoded_auth_response)
+      rescue ArgumentError
+        raise InvalidParameters
+      end
+
+      def authorize(session, authorization_id, authentication_id, authentication)
+        return_value = authenticate(session,
+          username: authentication_id,
+          password: authentication,
+          authorization_id: authorization_id)
+        authorization_id = return_value if return_value
+
+        session.authorization_id = authorization_id.to_s.empty? ? authentication_id : authorization_id
+        session.authentication_id = authentication_id
+        session.authenticated_at = Time.now.utc
+        reply(235, "OK", enhanced: "2.7.0")
+      end
+
+      def starttls_available?(session)
+        tls && !session.encrypted?
+      end
+
+      # Copy cipher metadata off the SSL socket after STARTTLS. OpenSSL returns
+      # cipher as [name, version, bits, alg_bits]; we keep the name string.
+      def record_tls_details!(session, io)
+        session.tls_version = io.ssl_version if io.respond_to?(:ssl_version)
+        return unless io.respond_to?(:cipher)
+
+        cipher = io.cipher
+        session.tls_cipher = cipher.is_a?(Array) ? cipher[0] : cipher
+      end
+
+      def auth_available?(session)
+        return false if @auth == :disabled
+        # When STARTTLS is required, do not advertise AUTH until the session is encrypted.
+        return false if encryption_required? && !session.encrypted?
+        return false if auth_mechanisms(session).empty?
+
+        true
+      end
+
+      def auth_ehlo_line(session)
+        return unless auth_available?(session)
+
+        mechanisms = auth_mechanisms(session).map { |name| name.to_s.upcase }.uniq
+        return if mechanisms.empty?
+
+        "250-AUTH #{mechanisms.join(" ")}"
+      end
+
+      def auth_mechanism_offered?(session, mechanism)
+        auth_mechanisms(session).any? { |name| name.to_s.casecmp?(mechanism) }
+      end
+
+      def encryption_required?
+        @starttls == :required
+      end
+
+      def auth_line_length?(session, line)
+        auth_value_phase?(session.phase) || line.match?(/\AAUTH\s/i)
+      end
+
+      # After the SMTP error reply, drop the session when AUTH or general error
+      # budgets are exhausted. +nil+ disables either ceiling.
+      def raise_if_exception_caps!(session, error)
+        if error.is_a?(AuthenticationFailed) && @max_auth_failures &&
+            session.auth_failures >= @max_auth_failures
+          raise ServiceUnavailable, "Too many authentication failures"
+        end
+        if @max_exceptions && session.exceptions >= @max_exceptions
+          raise ServiceUnavailable, "Too many protocol errors"
+        end
+      end
+
+      # SO_LINGER with timeout 0 yields RST on close — used on forced stop so
+      # clients do not linger on a half-closed FIN.
+      def abort_socket!(io)
+        return unless io && !io.closed?
+
+        io.setsockopt(Socket::SOL_SOCKET, Socket::SO_LINGER, [ 1, 0 ].pack("ii"))
+        io.close
+      rescue StandardError
+        # 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).
+      def pipelining_allowed?(session)
+        @pipelining || (proxy_enabled? && session.phase == :helo)
+      end
+  end
+end