mailsmtp 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dd030bbe1224ef8bce71ca5bc863df0e73285c884c35527202fe2b376cdfb26f
+  data.tar.gz: 9daf7326e361f0d214921171d4dcf4b27c2c18e209e59f8317216e09e0089185
+SHA512:
+  metadata.gz: 8d74cfca2a76a9994cba453cf444e3ba2095baca76c651918b42f4d2464ae02b61cc0dbedc2e729a07fa201387a86f186d3376e98ed924001273d8955fd5a348
+  data.tar.gz: 367b891a056bad4c67fdd3636dddbfe0ab027156d206d3c6e88d163137df1bb46fbb5b1e59afd0ad172ffec5d4f7afa0735122c382b1a66cb32ec52d853e692d

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.2.0
+
+- Fail `MailSmtp::Error` subclasses that omit `status` at definition time, not on `#response`
+- Record `MAIL FROM SIZE=` on `Envelope#declared_size` and include declared/limit sizes in oversize `552`s
+- Default `forbid_bare_newline` to `true`
+
+## 0.1.0
+
+- Added `auth_mechanisms` so EHLO `AUTH` advertisement is subclass-controlled (default PLAIN LOGIN)
+- Added `DataReader` for streaming DATA into `receive(session, io)`
+- Added SIZE enforcement on `max_message_size`, dropping the connection after `552`
+- Added `max_auth_failures` (default 3) and `max_exceptions` (default 20), each closing the session with `421`
+- Added `max_session_duration` (default 30 minutes) and an idle timer
+- Added `handshake_timeout` (default 30 seconds) for STARTTLS
+- Added RFC 2034 `ENHANCEDSTATUSCODES` support
+- Added `forbid_bare_newline` (default on) to reject non-CRLF-terminated DATA lines
+- 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

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Lev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,215 @@
+# mailsmtp
+
+📬 A boring SMTP server for Ruby
+
+**mailsmtp implements the SMTP protocol so you can plug in your own logic.** Receive email in your own app — no Postfix, no ESP required. As the conversation progresses, you decide what AUTH, MAIL FROM, RCPT TO, and DATA mean.
+
+mailsmtp handles:
+
+- the protocol - AUTH, MAIL FROM, RCPT TO, DATA, STARTTLS, PIPELINING
+- streaming - `receive` gets a live `io` into the DATA stream, no buffering the whole message
+- size limits - SIZE is advertised and enforced as DATA arrives
+- smuggling protection - bare LF lines are rejected by default
+- backpressure - concurrent DATA transfers are capped, with a queue and timeout
+- hot reloading - swap the STARTTLS certificate without restarting
+
+Plus:
+
+- subclass-and-override hooks for every verb
+- raise a typed error to choose the SMTP reply
+- multi-listen across any number of host×port pairs
+- injectable logger and live connection/processing counters
+
+
+
+## Contents
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Design](#design)
+  - [Role — server only](#role--server-only)
+  - [Hooks — subclass verbs](#hooks--subclass-verbs)
+  - [DATA — live reader into receive](#data--live-reader-into-receive)
+- [Reference](#reference)
+  - [Hooks](#hooks)
+  - [Options](#options)
+- [History](#history)
+- [Contributing](#contributing)
+- [License](#license)
+
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "mailsmtp"
+```
+
+Requires Ruby >= 3.3.4. Runtime dependencies: `base64`, `logger`.
+
+## Getting Started
+
+Subclass `MailSmtp::Server` and override the hooks you care about.
+
+```ruby
+require "mailsmtp"
+
+class MyServer < MailSmtp::Server
+  def connected(session)
+    session.local_response = "mail.example.com ESMTP"
+    session.helo_response = "mail.example.com"
+  end
+
+  def authenticate(session, username:, password:, authorization_id: "")
+    raise MailSmtp::AuthenticationFailed unless username == "user" && password == "secret"
+    username # becomes session.authorization_id when non-empty
+  end
+
+  def mail_from(session, address)
+    address[/<([^>]*)>/, 1] || address # returned value is stored on the envelope
+  end
+
+  def rcpt_to(session, address)
+    address[/<([^>]*)>/, 1] || address
+  end
+
+  def receive(session, io)
+    # Prefer streaming — io.read materializes the whole message in memory.
+    IO.copy_stream(io, storage_destination)
+  end
+end
+```
+
+And start it:
+
+```ruby
+server = MyServer.new(
+  host: "127.0.0.1",
+  port: 2525,
+  tls: nil,
+  auth: :disabled,
+  starttls: :optional,
+  max_connections: 100,
+  max_processings: 4,
+  max_message_size: 10_485_760,
+  max_recipients: 100,
+  read_timeout: 300,
+  write_timeout: 30,
+  handshake_timeout: 30
+)
+server.start
+```
+
+Hot-swap the STARTTLS certificate without restarting:
+
+```ruby
+server.tls = new_tls_context
+```
+
+Multi-listen: `hosts:` / `ports:` expand to every host×port pair.
+
+## Design
+
+
+
+### Role — server only
+
+mailsmtp is an SMTP **server**. Outbound submission (`Net::SMTP`, your MTA, Action Mailer) stays outside the gem.
+
+### Hooks — subclass verbs
+
+Subclass `MailSmtp::Server` and override methods: `authenticate`, `auth_mechanisms`, `mail_from`, `rcpt_to`, `receive`, plus `build_session` / `process_line` when you need a custom session or command gate.
+
+One server object owns policy; `Session` is connection state (envelope, auth), not a second interface you implement. Raise a `MailSmtp::Error` subclass to choose the SMTP reply.
+
+### DATA — live reader into receive
+
+After `354`, the engine builds a `DataReader` over the socket (dot-unstuffing, SIZE, line limits) and calls `receive(session, io)`. Prefer `IO.copy_stream` (or chunked reads); the engine **drains** through `.` then sends **one** reply — except when SIZE/`MessageTooLarge` (or the drain byte ceiling) forces a close after the error reply (no unbounded drain).
+
+```ruby
+def receive(session, io)
+  IO.copy_stream(io, storage_destination)
+  # or: while (chunk = io.read(8192)); ...; end  — read(len) returns nil at EOF
+end
+```
+
+SIZE / line-length failures raise a `MailSmtp::Error` from `read` / `readpartial` (not a short successful body). Mid-DATA disconnect raises `ServiceUnavailable`. If `receive` ignores the io, the reply still comes from the reader's failure after drain.
+
+## Reference
+
+
+
+### Hooks
+
+Raising a `MailSmtp::Error` subclass sends that SMTP reply to the client. Other exceptions during `receive` become a 451 (`LocalError`). Unexpected errors outside DATA still need cleanup (prefer raising a defined error).
+
+
+| Hook                | Signature                                            | Return / raise                                                                 |
+| ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `connected`         | `(session)`                                          | —                                                                              |
+| `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` |
+| `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                                     |
+| `receiving_started` | `(session)`                                          | once, before `receive`                                                         |
+| `headers_received`  | `(session)`                                          | when the header/body blank line is seen while reading                          |
+| `receive`           | `(session, io)`                                      | read the `DataReader` (or discard); raise to reject                            |
+| `received_header`   | `(session)`                                          | string prefixed onto the reader when `add_received: true`                      |
+| `build_session`     | `()`                                                 | a `Session` (or subclass)                                                      |
+| `process_line`      | `(session, line)`                                    | override for policy; call `super` for dispatch                                 |
+| `unknown_command`   | `(session, line)`                                    | default raises `CommandNotRecognized`                                          |
+| `log`               | `(session, severity, msg, err:)`                     | —                                                                              |
+
+
+
+
+### Options
+
+
+| Option                 | Default             | Notes                                                                                       |
+| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------- |
+| `auth`                 | required arg        | `:disabled` or `:required`                                                                  |
+| `eight_bit_mime`       | `false`             | RFC 6152                                                                                    |
+| `smtputf8`             | `false`             | RFC 6531; when off, non-ASCII envelope addresses are refused                                |
+| `pipelining`           | `false`             | RFC 2920; STARTTLS always drops plaintext buffers                                           |
+| `proxy_hosts`          | `[]`                | PROXY v1 from these IPs/CIDRs                                                               |
+| `add_received`         | `false`             | Prefix `received_header` onto the DATA reader                                               |
+| `forbid_bare_newline`  | `true`              | Reject DATA lines that end with bare LF (SMTP smuggling)                                    |
+| `max_message_size`     | `10485760` (10 MiB) | Advertises SIZE and enforces as DATA arrives; `nil` disables                                |
+| `max_recipients`       | `100`               | Minimum 100 (RFC 5321); enforced at RCPT TO                                                 |
+| `max_processings`      | required arg        | Concurrent DATA transfers; idle sessions do not consume a slot                              |
+| `max_processings_wait` | `30`                | Seconds to wait for a DATA processing slot before 421                                       |
+| `max_auth_failures`    | `3`                 | Failed AUTH attempts before 421; `nil` disables                                             |
+| `max_exceptions`       | `20`                | Protocol errors before 421; `nil` disables                                                  |
+| `read_timeout`         | `300`               | Idle read timeout (seconds); RFC 5321 §4.5.3.2.7; `nil` disables                            |
+| `write_timeout`        | `30`                | Reply write timeout (seconds)                                                               |
+| `handshake_timeout`    | `30`                | STARTTLS handshake timeout (seconds); independent of `read_timeout`; `nil` falls back to 30 |
+| `max_session_duration` | `1800`              | Absolute session ceiling (seconds); `nil` to disable                                        |
+| `logger`               | stdout logger       | Injectable `Logger`                                                                         |
+
+
+`starttls: :required` requires a non-nil `tls` object. Per-IP connection caps are deferred for peers in `proxy_hosts` until PROXY rewrites the client address. Forced `#stop` aborts lingering sockets with RST (`SO_LINGER 0`). Inspect live load with `connections_count` / `processings_count` (and `connections?`).
+
+## History
+
+View the [changelog](CHANGELOG).
+
+## Contributing
+
+Everyone is encouraged to help improve this project:
+
+- [Report bugs](https://github.com/mailpiece/mailsmtp/issues)
+- Fix bugs and submit pull requests
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/mailsmtp/data_reader.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module MailSmtp
+  # IO-like view of an SMTP DATA body. Yields dot-unstuffed bytes as the
+  # underlying connection produces lines; ends at the terminating "." line.
+  # SIZE and per-line limits set +#failure+ and raise on +#read+ / +#readpartial+
+  # (never return a truncated body as success). +#drain+ consumes through "."
+  # without raising so the session can reply once, but still records SIZE/line
+  # failures (and an absolute byte ceiling when SIZE is nil) so a no-op
+  # +receive+ cannot turn an oversize body into 250. Drain always stops once
+  # that ceiling is hit — unbounded drain would let a fast sender burn the link.
+  #
+  # +readpartial+ fills up to +maxlen+ (or the terminating "."), so a mid-DATA
+  # disconnect raises +ServiceUnavailable+ instead of returning a short chunk that
+  # apps treat as end-of-message. +EOFError+ is raised only after the ".".
+  class DataReader
+    # Absolute drain ceiling when the server has no SIZE limit configured.
+    # Keep in sync with Server::DEFAULT_MAX_MESSAGE_SIZE (this file loads first).
+    DRAIN_BYTE_CEILING = 10_485_760
+
+    attr_reader :failure
+
+    def initialize(max_message_size: nil, max_line_length: Server::MAX_TEXT_LINE_LENGTH,
+      on_headers: nil, &read_line)
+      raise ArgumentError, "read_line block required" unless read_line
+
+      @read_line = read_line
+      @max_message_size = max_message_size
+      @max_line_length = max_line_length
+      @on_headers = on_headers
+      @buffer = +"".b
+      @bytes_seen = 0
+      @eof = false
+      @failure = nil
+      @draining = false
+      @headers_seen = false
+      @drain_ceiling_hit = false
+    end
+
+    def read(length = nil, outbuf = nil)
+      raise @failure if @failure && !@draining
+
+      # IO#read(0) returns an empty string without consuming input.
+      if length == 0
+        chunk = +""
+        return outbuf ? outbuf.replace(chunk) : chunk
+      end
+
+      if length
+        fill_until { @buffer.bytesize >= length || @eof || @failure }
+      else
+        fill_until { @eof || @failure }
+      end
+
+      raise @failure if @failure && !@draining
+
+      if @buffer.empty?
+        # IO#read(length) returns nil at EOF; read() with no length returns "".
+        chunk = length ? nil : +""
+      elsif length
+        chunk = @buffer.slice!(0, length)
+      else
+        chunk = @buffer
+        @buffer = +""
+      end
+
+      if outbuf
+        outbuf.replace(chunk || +"")
+        chunk
+      else
+        chunk
+      end
+    end
+
+    def readpartial(maxlen, outbuf = nil)
+      raise ArgumentError, "maxlen must be positive" unless maxlen.positive?
+      raise @failure if @failure && !@draining
+
+      # Fill up to maxlen (not "any bytes") so a peer drop is discovered on this
+      # call — returning the first line alone lets short-read loops treat a
+      # truncated body as complete while the engine later 451s / redelivers.
+      fill_until { @buffer.bytesize >= maxlen || @eof || @failure }
+
+      raise @failure if @failure && !@draining
+      if @buffer.empty?
+        # EOFError only after the terminating "."; a drop mid-DATA must not look
+        # 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"
+      end
+
+      chunk = @buffer.slice!(0, maxlen)
+      outbuf ? outbuf.replace(chunk) : chunk
+    end
+
+    def eof?
+      @eof && @buffer.empty? && (@draining || @failure.nil?)
+    end
+
+    def drain
+      @draining = true
+      @buffer = +""
+      # Stop on SIZE, or on the absolute drain ceiling when SIZE is off / after
+      # LineTooLong — never read forever waiting for ".".
+      fill_until { @drain_ceiling_hit || @failure.is_a?(MessageTooLarge) }
+    end
+
+    def drain_ceiling_hit? = @drain_ceiling_hit
+
+    def binmode = self
+    def close = nil
+    def closed? = false
+
+    private
+      def drain_ceiling
+        @max_message_size || DRAIN_BYTE_CEILING
+      end
+
+      def fill_until
+        loop do
+          return if @eof
+          return if !@draining && @failure
+          return if @draining && @drain_ceiling_hit
+          return if yield
+
+          pull_line
+        end
+      end
+
+      def pull_line
+        line = @read_line.call
+        if line.nil?
+          @eof = true
+          return
+        end
+
+        # Count every network line toward SIZE, including ones we discard after failure.
+        @bytes_seen += line.bytesize
+        line = line.b
+
+        # Record protocol failures before the drain-ceiling stop. Ceiling abort
+        # alone must not leave +failure+ nil — default +receive+ never reads, so
+        # SIZE/line limits are only observed here during +drain+, and a nil
+        # failure would become a spurious 250.
+        if line.bytesize > @max_line_length
+          @failure ||= LineTooLong.new
+        end
+
+        if @max_message_size && @bytes_seen > @max_message_size
+          @failure ||= MessageTooLarge.new
+        end
+
+        if @draining && @bytes_seen > drain_ceiling
+          @drain_ceiling_hit = true
+          # Absolute ceiling (no SIZE configured): still refuse rather than 250.
+          @failure ||= MessageTooLarge.new
+          return
+        end
+
+        if !@draining && !@headers_seen && line == "\r\n".b
+          @headers_seen = true
+          @on_headers&.call
+        end
+
+        return if @draining || @failure
+
+        @buffer << line
+      rescue ServiceUnavailable
+        raise
+      rescue Error => e
+        @failure ||= e
+      end
+  end
+
+  # Prepends a fixed string once, then delegates — used for +add_received+.
+  # Duck-types the same IO surface as +DataReader+.
+  class PrefixedReader
+    def initialize(prefix, inner)
+      @prefix = prefix.to_s.b
+      @inner = inner
+    end
+
+    def read(length = nil, outbuf = nil)
+      # Match DataReader / IO#read(0).
+      if length == 0
+        chunk = +""
+        return outbuf ? outbuf.replace(chunk) : chunk
+      end
+
+      if @prefix
+        if length.nil?
+          chunk = @prefix
+          @prefix = nil
+          rest = @inner.read
+          chunk = rest ? "#{chunk}#{rest}" : chunk
+        elsif length >= @prefix.bytesize
+          chunk = @prefix
+          @prefix = nil
+          rest_len = length - chunk.bytesize
+          rest = rest_len.positive? ? @inner.read(rest_len) : +""
+          chunk = rest ? "#{chunk}#{rest}" : chunk
+        else
+          chunk = @prefix.slice!(0, length)
+        end
+        outbuf ? outbuf.replace(chunk) : chunk
+      else
+        @inner.read(length, outbuf)
+      end
+    end
+
+    def readpartial(maxlen, outbuf = nil)
+      if @prefix && !@prefix.empty?
+        chunk = @prefix.slice!(0, maxlen)
+        @prefix = nil if @prefix.empty?
+        outbuf ? outbuf.replace(chunk) : chunk
+      else
+        @inner.readpartial(maxlen, outbuf)
+      end
+    end
+
+    def drain
+      @prefix = nil
+      @inner.drain
+    end
+
+    def failure = @inner.failure
+    def drain_ceiling_hit? = @inner.drain_ceiling_hit?
+
+    def eof?
+      (@prefix.nil? || @prefix.empty?) && @inner.eof?
+    end
+
+    def binmode = self
+    def close = @inner.close
+    def closed? = @inner.closed?
+  end
+end

data/lib/mailsmtp/error.rb

@@ -0,0 +1,58 @@
+module MailSmtp
+  class Error < RuntimeError
+    class << self
+      # +enhanced+ is an RFC 2034 / 3463 status like "5.3.4".
+      def status(code, text, enhanced:)
+        @code = code
+        @text = text
+        @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
+
+      def assert_status!
+        if code.nil? || text.nil? || enhanced.nil?
+          raise "MailSmtp::Error subclass #{self} must declare status"
+        end
+      end
+
+      def code
+        return @code if instance_variable_defined?(:@code)
+        superclass.code if superclass < Error
+      end
+
+      def text
+        return @text if instance_variable_defined?(:@text)
+        superclass.text if superclass < Error
+      end
+
+      def enhanced
+        return @enhanced if instance_variable_defined?(:@enhanced)
+        superclass.enhanced if superclass < Error
+      end
+    end
+
+    def response
+      self.class.assert_status!
+      "#{self.class.code} #{self.class.enhanced} #{self.class.text}"
+    end
+  end
+end

data/lib/mailsmtp/errors.rb

@@ -0,0 +1,85 @@
+module MailSmtp
+  # Protocol-level SMTP replies the engine and its subclasses raise. Product
+  # policy (relay denied, rate limited, …) stays in the application. Every
+  # reply carries an RFC 2034 enhanced status code.
+
+  # 421 — connection is being dropped: too busy, timed out, or abusing the protocol
+  class ServiceUnavailable < Error
+    status 421, "Service too busy or not available, closing transmission channel", enhanced: "4.3.2"
+  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"
+  end
+
+  # 452 — envelope has more recipients than we allow in one transaction
+  class TooManyRecipients < Error
+    status 452, "Requested action not taken: insufficient system storage", enhanced: "4.5.3"
+  end
+
+  # 500 — command verb not recognized
+  class CommandNotRecognized < Error
+    status 500, "Syntax error, command unrecognised", enhanced: "5.5.1"
+  end
+
+  # 500 — a DATA body line exceeded the RFC 5321 text-line limit
+  class LineTooLong < Error
+    status 500, "Line too long", enhanced: "5.5.2"
+  end
+
+  # 502 — command recognized but not implemented (VRFY's cousins EXPN/HELP)
+  class CommandNotImplemented < Error
+    status 502, "Command not implemented", enhanced: "5.5.1"
+  end
+
+  # 500 — a second command arrived pipelined ahead of its reply, which we don't support
+  class PipeliningNotSupported < Error
+    status 500, "Bad input, PIPELINING is not allowed", enhanced: "5.5.2"
+  end
+
+  # 501 — a command parameter we don't support (e.g. SMTPUTF8)
+  class InvalidParameters < Error
+    status 501, "Syntax error in parameters or arguments", enhanced: "5.5.4"
+  end
+
+  # 503 — command arrived out of the expected HELO/AUTH/MAIL/RCPT/DATA sequence
+  class BadSequence < Error
+    status 503, "Bad sequence of commands", enhanced: "5.5.1"
+  end
+
+  # 504 — an AUTH mechanism we don't offer (RFC 4954 §4); only PLAIN and LOGIN
+  class AuthenticationTypeNotSupported < Error
+    status 504, "Unrecognized authentication type", enhanced: "5.5.4"
+  end
+
+  # 530 — TLS is required and the client hasn't issued STARTTLS yet
+  class EncryptionRequired < Error
+    status 530, "Encryption required, must issue STARTTLS command first", enhanced: "5.7.0"
+  end
+
+  # 530 — AUTH is required and the client hasn't authenticated yet
+  class AuthenticationRequired < Error
+    status 530, "Authentication required", enhanced: "5.7.0"
+  end
+
+  # 535 — AUTH credentials were rejected
+  class AuthenticationFailed < Error
+    status 535, "Authentication credentials invalid", enhanced: "5.7.8"
+  end
+
+  # 550 — DATA contained a bare LF (SMTP smuggling / non-CRLF line endings)
+  class BareNewline < Error
+    status 550, "Bare <LF> disallowed; lines must end with <CRLF>", enhanced: "5.5.2"
+  end
+
+  # 552 — declared or actual message size exceeds the configured limit
+  class MessageTooLarge < Error
+    status 552, "Requested mail action aborted: exceeded storage allocation", enhanced: "5.3.4"
+  end
+
+  # 555 — an ESMTP parameter we don't implement (RFC 1869 §6.1)
+  class ParametersNotRecognized < Error
+    status 555, "MAIL FROM/RCPT TO parameters not recognized or not implemented", enhanced: "5.5.4"
+  end
+end