@bumail/smtp 0.3.0 → 0.5.0

package/docs/guide.md

@@ -1,19 +1,22 @@
 # Guide
 
 How to run `@bumail/smtp` and what it does on the wire: the session and its
-replies, the hooks, what a delivered message looks like, TLS, sending mail
-with the client, and the RFCs behind each behaviour.
+replies, the hooks, what a delivered message looks like, TLS, running
+behind a TCP proxy, sending mail with the client, and the RFCs behind each
+behaviour.
 
 - [The smallest server](#the-smallest-server)
 - [Options](#options)
 - [The session, and what each reply means](#the-session-and-what-each-reply-means)
 - [Hooks, and their order](#hooks-and-their-order)
+- [`RCPT TO:<postmaster>`](#rcpt-topostmaster)
 - [Session.data](#sessiondata)
 - [What onData receives](#what-ondata-receives)
 - [Delivering into @bumail/store](#delivering-into-bumailstore)
 - [Authentication](#authentication)
 - [TLS](#tls)
 - [Limits](#limits)
+- [Running behind a TCP proxy](#running-behind-a-tcp-proxy)
 - [Sending mail: the client](#sending-mail-the-client)
 - [Protocol helpers](#protocol-helpers)
 - [The RFCs implemented](#the-rfcs-implemented)
@@ -67,6 +70,9 @@ export interface SmtpServer {
 | `maxMessageSize` | `number` | 25 MiB | bytes; announced with SIZE |
 | `maxRecipients` | `number` | `100` | recipients per message |
 | `maxConnections` | `number` | `1000` | open connections at once |
+| `maxConnectionsPerClient` | `number` | `10` | open connections at once from one client: an IPv4 address, or an IPv6 /64; see [Limits](#limits) |
+| `handshakeTimeout` | `number` | `10` | seconds a client on implicit TLS has to complete its handshake, from the TCP connection on; past it, the socket is closed. See [TLS](#tls). With `proxyProtocol`, also the seconds a trusted proxy has to send its PROXY header; see [Running behind a TCP proxy](#running-behind-a-tcp-proxy) |
+| `proxyProtocol` | `{ trusted: string[] }` | none, off | reads the PROXY protocol, v1 and v2, from the peers `trusted` lists (IPv4 and IPv6 addresses and CIDRs), so the client's address replaces the proxy's; see [Running behind a TCP proxy](#running-behind-a-tcp-proxy) |
 | `maxErrors` | `number` | `10` | failed commands before the server hangs up |
 | `timeout` | `number` | `300` | seconds since the client's last byte, or since the 220, before the server hangs up |
 | `hookTimeout` | `number` | `60` | seconds a hook, `authenticate` or `localDomains` has to settle, and `onData` to read on; past it, `451 4.3.0`. At most 2 147 483, what a timer can wait |
@@ -112,9 +118,16 @@ await server.listen({ port: 25 });
 | `createSmtpServer(): hookTimeout must be at most 2147483 seconds, not <value>` | `hookTimeout` past what `setTimeout` can wait (about 24.8 days) |
 | `createSmtpServer(): greetingDelay must be a number of seconds, 0 or more, not <value>` | `greetingDelay` negative, `NaN` or `Infinity` |
 | `createSmtpServer(): greetingDelay (<n> s) must be shorter than timeout (<n> s), or every client times out before the greeting` | `greetingDelay` as long as `timeout`, or longer |
+| `createSmtpServer(): proxyProtocol.trusted must list the addresses or CIDRs of the proxies, at least one` | `proxyProtocol` without `trusted`, with an empty one, or one that is not an array |
+| `createSmtpServer(): proxyProtocol.trusted: "<entry>" is neither an IP address nor a CIDR` | an entry that is a host name, a malformed address, an address with a zone (`fe80::1%eth0`), or has more than one `/` |
+| `createSmtpServer(): proxyProtocol.trusted: "<entry>" has a prefix length out of range` | a prefix past 32 for IPv4 or 128 for IPv6, not a number, or below 96 for an IPv4-mapped address (`::ffff:10.0.0.0/8`) |
+| `createSmtpServer(): proxyProtocol.trusted: "<entry>" has a prefix length of 0, which trusts every peer` | `0.0.0.0/0`, `::/0`, `::ffff:0.0.0.0/96`: the option would trust anyone |
+| `createSmtpServer(): proxyProtocol.trusted: <value> is not a string` | an entry that is a number, `null`, an object |
 
 `listen` a second time throws an `SmtpError` with `code:
-'ALREADY_LISTENING'`: create another server for another port.
+'ALREADY_LISTENING'`: create another server for another port. A `stop()`
+called before `listen` resolved makes that `listen` reject with
+`code: 'STOPPED'`, and nothing is left listening.
 
 What to do about each is in [Troubleshooting](troubleshooting.md).
 
@@ -166,7 +179,7 @@ Every reply the server sends of its own:
 | `250 <hostname> greets <name>` | EHLO or HELO accepted; either one also ends a transaction in progress |
 | `501 Syntax: EHLO hostname` / `501 Syntax: HELO hostname` | the EHLO or HELO argument is missing, or is not a domain or an address literal; no enhanced code before an EHLO was accepted, `501 5.5.4 Syntax: EHLO hostname` after one |
 | `250 2.1.0 OK` | MAIL FROM accepted |
-| `250 2.1.5 OK` | RCPT TO accepted |
+| `250 2.1.5 OK` | RCPT TO accepted; `RCPT TO:<postmaster>` with no domain is accepted without AUTH (see [below](#rcpt-topostmaster)) |
 | `354 End data with <CR><LF>.<CR><LF>` | DATA: send the message |
 | `250 2.0.0 OK queued as <id>` | the message was taken: `onData` read its content stream to the clean end and resolved without refusing |
 | `250 2.0.0 OK` | RSET (the transaction is forgotten) or NOOP |
@@ -193,6 +206,7 @@ Every reply the server sends of its own:
 | `500 5.5.2 Command unrecognized` | an unknown verb — EXPN, BDAT and the rest |
 | `500 5.5.6 Line too long` | a command line over 2048 bytes; the rest of it is skipped |
 | `421 4.3.2 <hostname> Too many connections, try later` | a connection past `maxConnections`, then the server hangs up |
+| `421 4.7.0 <hostname> Too many connections from your address, try later` | a connection past `maxConnectionsPerClient` from one client, then the server hangs up |
 | `421 4.4.2 <hostname> Idle too long, closing` | nothing for `timeout` seconds |
 | `421 4.7.0 <hostname> Too many errors, closing` | `maxErrors` failed commands |
 | `421 4.3.0 Local error, closing` | the server failed itself |
@@ -234,7 +248,7 @@ In the order a session meets them:
 
 | Hook | Runs | After the server checked | A refusal |
 | --- | --- | --- | --- |
-| `onConnect` | when a client connects, before the greeting | the connection count | replaces the greeting, at once even with `greetingDelay`; then the server hangs up. When `onConnect` accepts, a client that talked before the greeting is refused with `554` |
+| `onConnect` | when a client connects, before the greeting | the connection counts: `maxConnections`, then `maxConnectionsPerClient` | replaces the greeting, at once even with `greetingDelay`; then the server hangs up. When `onConnect` accepts, a client that talked before the greeting is refused with `554` |
 | `authenticate` | at AUTH | TLS, EHLO, no transaction in progress | see [Authentication](#authentication) |
 | `onMailFrom` | at each MAIL FROM | EHLO, AUTH in `submission`, syntax, parameters, SIZE, SMTPUTF8 | refuses the sender; the client may try another MAIL |
 | `onRcptTo` | at each RCPT TO | MAIL, syntax, SMTPUTF8, `maxRecipients`, **relaying** | refuses that recipient; the others stand |
@@ -285,12 +299,14 @@ await server.listen({ port: 25 });
 
 ```ts
 export interface Path {
-	/** `local@domain`; `''` for the null reverse-path `<>`: a bounce. */
+	/** `local@domain`; `''` for the null reverse-path `<>`: a bounce; `'postmaster'` for `RCPT TO:<postmaster>`. */
 	readonly address: string;
 	/** As sent: case is kept. */
 	readonly local: string;
-	/** Lower case. */
+	/** Lower case; `''` for `<>` and `<postmaster>`. */
 	readonly domain: string;
+	/** `true` for `RCPT TO:<postmaster>` with no domain; absent otherwise. */
+	readonly postmaster?: true;
 }
 ```
 
@@ -309,6 +325,49 @@ surrogates are refused anywhere in a path — the route, the local part
 quoted or not, the domain — even under SMTPUTF8. An IPv4 address literal
 takes octets up to 255: `[999.1.1.1]` is not one.
 
+## `RCPT TO:<postmaster>`
+
+RFC 5321 §4.5.1 says every server that delivers mail must take mail for
+`postmaster`, and §4.1.1.3 lets RCPT TO name it with no domain at all:
+`RCPT TO:<Postmaster>`. The server takes it, in any case, as the
+postmaster of this server, whatever domains it hosts:
+
+- it is not relaying, so it needs no AUTH, and `localDomains` is not asked;
+- `onRcptTo` is asked, as for any recipient, with the `Path`
+  `{ address: 'postmaster', local: 'postmaster', domain: '', postmaster: true }`,
+  so it can still refuse;
+- `envelope.to` lists it as `'postmaster'`, with no `@`, and the Received
+  field says `for <postmaster>` when it is the only recipient.
+
+`<postmaster@example.com>` is an ordinary path: it is checked against
+`localDomains` like any other, and has no `postmaster` field. A path the
+grammar would otherwise refuse stays refused: `<postmaster@>`,
+`<"postmaster">` and `MAIL FROM:<postmaster>` get `501 5.5.4`.
+
+Route it to a mailbox you keep: by `path.postmaster` in `onRcptTo`, by the
+bare `'postmaster'` in `onData`.
+
+```ts
+import { createSmtpServer, reply } from '@bumail/smtp';
+
+const mailboxes = new Set(['alice@example.com', 'postmaster@example.com']);
+const postmaster = 'postmaster@example.com';
+
+const server = createSmtpServer({
+	hostname: 'mx.example.com',
+	localDomains: ['example.com'],
+	onRcptTo: (path) =>
+		path.postmaster || mailboxes.has(path.address.toLowerCase())
+			? undefined
+			: reply(550, '5.1.1', 'No such user here'),
+	async onData(message) {
+		const recipients = message.envelope.to.map((to) => (to === 'postmaster' ? postmaster : to));
+		const bytes = await new Response(message.content).bytes();
+		for (const to of recipients) await Bun.write(`spool/${to}/${message.id}.eml`, bytes);
+	},
+});
+```
+
 ## Session.data
 
 Every hook, and `authenticate`, receives the `Session`:
@@ -396,6 +455,7 @@ export interface ReceivedMessage {
 export interface Envelope {
 	/** `''` for the null reverse-path `<>`: a bounce. */
 	readonly from: string;
+	/** `local@domain` each; `'postmaster'`, with no domain, for `RCPT TO:<postmaster>`. */
 	readonly to: readonly string[];
 	/** The client asked for SMTPUTF8 (RFC 6531). */
 	readonly smtputf8: boolean;
@@ -406,8 +466,9 @@ export interface Envelope {
 
 The **envelope** is what MAIL FROM and RCPT TO said — not the `From:` and
 `To:` of the message, which may differ (Bcc, mailing lists, forwarding).
-`to` holds only the recipients the server and `onRcptTo` accepted. Deliver
-to the envelope.
+`to` holds only the recipients the server and `onRcptTo` accepted, each
+`local@domain`, or `'postmaster'` for [`RCPT TO:<postmaster>`](#rcpt-topostmaster).
+Deliver to the envelope.
 
 The **content** is the message as the client sent it, with the leading dot
 of each stuffed line removed (RFC 5321 §4.5.2), the terminating `.` line
@@ -423,7 +484,8 @@ Subject: hi
 body
 ```
 
-- `from` is the EHLO or HELO name, then the client's address in brackets.
+- `from` is the EHLO or HELO name, then the client's address in brackets:
+  an IPv6 address is the literal of RFC 5321 §4.1.3, `([IPv6:2001:db8::7])`.
   Any character of the name that is not printable ASCII is written `?`.
 - `with` is the protocol of RFC 3848: `SMTP` after HELO; `ESMTP` after EHLO,
   `ESMTPS` with TLS, `ESMTPA` with AUTH, `ESMTPSA` with both.
@@ -767,6 +829,26 @@ STARTTLS, in clear, are dropped and never answered. The STARTTLS replies:
 with `tls`, usually on 465. STARTTLS is not offered there — the connection
 is already secure — and AUTH is offered at once.
 
+On implicit TLS the server counts a socket from the TCP connection on, not
+from the end of its handshake: a socket that has not finished its handshake
+holds a slot of `maxConnections` and of `maxConnectionsPerClient`, and is
+closed, without a reply, `handshakeTimeout` seconds (default 10) after it
+connected, so clients that open TCP connections and never send a
+ClientHello cannot fill the server. A refusal by a limit, `onConnect`, the
+greeting and `greetingDelay` all wait for the handshake, so the client
+reads them over TLS and `session.secure` is already `true`. A handshake
+that fails is closed by Bun at once and counted out. A STARTTLS handshake
+is bounded by the idle `timeout`, the connection already counted.
+
+Bun 1.4.2 calls a TLS listener's `open` only once the handshake completed
+unless the listener has a `handshake` handler; with one, `open` comes at
+the TCP connection and the socket's timer runs during the handshake. The
+server sets one for that reason.
+
+Behind a TCP proxy that sends the PROXY protocol, implicit TLS starts after
+the proxy's header, and runs differently: see
+[Running behind a TCP proxy](#running-behind-a-tcp-proxy).
+
 An MX takes mail in clear as well as encrypted: senders on the Internet that
 cannot do TLS still deliver. Whether to refuse them is policy — check
 `session.secure` in a hook:
@@ -837,6 +919,8 @@ await createSmtpServer({ ...submission, implicitTls: true }).listen({ port: 465
 | `maxMessageSize` | 25 MiB | `552 5.3.4` at MAIL when `SIZE=` says more; during DATA once the message is more — the content stream errors with `MESSAGE_TOO_BIG`, the rest is read and dropped, and the session goes on |
 | `maxRecipients` | 100, the least RFC 5321 §4.5.3.1.8 asks a server to take | `452 4.5.3` for each extra recipient (RFC 5321 §4.5.3.1.10); the client sends the rest in another transaction |
 | `maxConnections` | 1000 | `421 4.3.2` and the server hangs up, before the greeting and before `onConnect` |
+| `maxConnectionsPerClient` | 10 | `421 4.7.0 <hostname> Too many connections from your address, try later` and the server hangs up, before the greeting and before `onConnect` |
+| `handshakeTimeout` | 10 seconds, on implicit TLS; ticks of about 4 s, as `timeout`. For a trusted proxy's PROXY header, to the millisecond | the socket is closed without a reply: there is no TLS to write one on, and a proxy's socket has no client yet |
 | `maxErrors` | 10 | `421 4.7.0` and the server hangs up |
 | `timeout` | 300 seconds, RFC 5321 §4.5.3.2.7's, counted from the client's last byte, or from the 220; Bun's socket timer ticks in steps of about 4 s, so the hang-up comes up to that much later | `421 4.4.2` and the server hangs up |
 | `hookTimeout` | 60 seconds | `451 4.3.0` for that command; `onError` gets an `SmtpError` `HOOK_TIMEOUT` |
@@ -869,6 +953,50 @@ const server = createSmtpServer({
 await server.listen({ port: 25 });
 ```
 
+`maxConnectionsPerClient` keeps one host from taking every slot of
+`maxConnections`. A client is counted by `clientKey(session.remoteAddress)`:
+
+| Remote address | Counted as |
+| --- | --- |
+| `192.0.2.1` | `192.0.2.1` |
+| `::ffff:192.0.2.1`, `::ffff:c000:201` (IPv4-mapped, as a listener on `::` sees an IPv4 client) | `192.0.2.1` |
+| `64:ff9b::c000:201` (NAT64) | `192.0.2.1` |
+| `2001:db8:1:2::9`, `2001:db8:1:2:ffff::1` | `2001:db8:1:2::/64` |
+| `2001:db8::1`, `2001:0db8:0000::ffff` | `2001:db8:0:0::/64` |
+| anything else (a Unix socket) | not limited |
+
+An IPv6 key is always the first four groups in lower-case hex, without
+leading zeros, every group written out — zeros too — then `::/64`:
+`2001:db8::1` is `2001:db8:0:0::/64`, never `2001:db8::/64`. Write the
+keys you compare with it that way.
+
+An IPv6 host usually holds a whole /64, so counting each address apart
+would let it open as many connections as it likes. Every close frees the
+slot as it frees one of `maxConnections`: QUIT, the client hanging up, a
+socket error, the idle `timeout`, `maxErrors`, a refusal from `onConnect`,
+and `stop(true)`. The count lives in the server's memory, for that one
+server. For a policy of your own — a list, a per-network budget — use
+`onConnect` with `clientKey`:
+
+```ts
+import { clientKey, createSmtpServer, reply } from '@bumail/smtp';
+
+// As clientKey writes them: '2001:db8:0:0::/64', not '2001:db8::/64'.
+const blocked = new Set(['203.0.113.7', '2001:db8:0:0::/64', '2001:db8:dead:beef::/64']);
+
+const server = createSmtpServer({
+	hostname: 'mx.example.com',
+	localDomains: ['example.com'],
+	maxConnections: 500,
+	maxConnectionsPerClient: 5,
+	onConnect: (session) =>
+		blocked.has(clientKey(session.remoteAddress) ?? '') ? reply(554, '5.7.1', 'Go away') : undefined,
+	onData: async (message) => {
+		await new Response(message.content).bytes();
+	},
+});
+```
+
 Some limits are fixed: a command line is at most 2048 bytes (RFC 5321
 §4.5.3.1.4 asks for 512 at least); a session gets three AUTH attempts; and
 the server holds at most 64 KiB of a client's unread input, and of a
@@ -910,8 +1038,11 @@ TLS buffer. So a `221` behind replies that are never read holds the slot
 5 seconds, not until the `timeout`.
 
 Stop a server with `stop()`; `stop(true)` also hangs up on every client,
-those moved to TLS by STARTTLS included, as the idle timeout does.
-`connections` counts the clients currently connected:
+those moved to TLS by STARTTLS included, as the idle timeout does; a
+socket still in its implicit TLS handshake is reset, with no 421, having
+no TLS to write one on, and so is a socket still awaiting a proxy's PROXY
+header, nothing written and nothing passed to `onError`. `connections`
+counts the clients currently connected:
 
 ```ts
 import { createSmtpServer } from '@bumail/smtp';
@@ -931,6 +1062,326 @@ process.on('SIGTERM', () => {
 });
 ```
 
+## Running behind a TCP proxy
+
+`proxyProtocol` lets the server sit behind a TCP proxy — a Traefik TCP
+router, HAProxy, a cloud load balancer — and still see each client's own
+address, as the proxy reports it with the PROXY protocol (HAProxy's
+`proxy-protocol.txt`, versions 1 and 2):
+
+```ts
+import { createSmtpServer } from '@bumail/smtp';
+
+const server = createSmtpServer({
+	hostname: 'mx.example.com',
+	localDomains: ['example.com'],
+	proxyProtocol: { trusted: ['10.0.0.5'] },
+	onConnect: (session) => console.log('client', session.remoteAddress), // the client's, not 10.0.0.5
+	async onData(message) {
+		await Bun.write(`spool/${message.id}.eml`, await new Response(message.content).bytes());
+	},
+});
+
+await server.listen({ port: 25 });
+```
+
+```ts
+export interface ProxyProtocolOptions {
+	/** The proxies' addresses or CIDRs, IPv4 or IPv6: `['10.0.0.5', '172.16.0.0/12']`. */
+	readonly trusted: readonly string[];
+}
+
+export interface SmtpServerOptions {
+	// …
+	readonly proxyProtocol?: ProxyProtocolOptions; // off by default
+	readonly handshakeTimeout?: number; // also bounds a trusted proxy's header; default 10
+}
+```
+
+- [Who is trusted](#who-is-trusted)
+- [The header, and `handshakeTimeout`](#the-header-and-handshaketimeout)
+- [Which address the client gets](#which-address-the-client-gets)
+- [STARTTLS on 25 and 587](#starttls-on-25-and-587)
+- [Implicit TLS on 465, behind a proxy](#implicit-tls-on-465-behind-a-proxy)
+- [With Traefik](#with-traefik)
+
+### Who is trusted
+
+`trusted` lists the peers whose header is read: IPv4 and IPv6 addresses,
+and CIDRs of either. A peer is the TCP address the connection comes from,
+the proxy's.
+
+| Entry | Trusts |
+| --- | --- |
+| `'10.0.0.5'`, `'2001:db8::5'` | that address alone |
+| `'172.20.0.0/16'`, `'2001:db8:1::/48'` | every address in the network |
+| `'::ffff:10.0.0.5'` | `10.0.0.5`: an IPv4-mapped entry is its IPv4 address |
+| `'::ffff:10.0.0.0/104'` | `10.0.0.0/8`: a mapped CIDR counts its prefix over the whole IPv6 address, so 96 and up |
+
+A peer reported IPv4-mapped (`::ffff:10.0.0.5`), as a listener on `::`
+sees an IPv4 client, matches as its IPv4 address, so `'10.0.0.5'` covers
+both. An address with a zone (`fe80::1%eth0`) is refused, as an entry and as a
+peer: a zone names an interface of this host, not a client. A prefix of 0
+(`0.0.0.0/0`, `::/0`) is refused too, since it trusts every peer. A bad entry throws an
+`SmtpError` (`INVALID_OPTION`) from `createSmtpServer`; the messages are in
+[Options](#options).
+
+**List the proxies' own addresses, and nothing else.** A trusted peer can
+claim any client address it likes, and every check that uses the address
+— `maxConnectionsPerClient`, your `onConnect` policy, the Received field —
+believes it. Never list a range clients connect from, and never
+`0.0.0.0/0` or `::/0` on a port the Internet reaches. A container network
+is safe to list only when nothing but the proxy reaches the server
+through it.
+
+A peer not listed is served exactly as without the option. A PROXY header
+it sends is just bad input and never sets an address: after the greeting,
+`PROXY …` is a command the server does not know (`500`); before it, the
+client talked first (`554 <hostname> Talked before the greeting`). On
+implicit TLS the header is not a ClientHello: the handshake fails and the
+socket is closed.
+
+### The header, and `handshakeTimeout`
+
+A trusted peer must send a valid header first, before any byte of the
+client's, and all of it within `handshakeTimeout` seconds (default 10) of
+the TCP connection. That bound is a timer of its own, to the millisecond,
+not Bun's socket timer with its 4-second ticks; a header trickled a byte at
+a time does not stretch it. Past it, or on a header that is not valid, the
+socket is reset:
+
+- nothing is written to it, not even a `421`;
+- `onConnect` is never called, and `onError` is told nothing;
+- the proxy's address is never taken for a client's.
+
+While it waits for its header, a socket holds no slot of `maxConnections`
+nor of `maxConnectionsPerClient`: it is counted, by the client's address,
+once the header named it. `stop(true)` resets the sockets still awaiting
+their header, writing nothing and calling no `onError`.
+
+What is read, and what is refused:
+
+| Header | Refused when |
+| --- | --- |
+| v1, `PROXY TCP4 …`, `PROXY TCP6 …`, `PROXY UNKNOWN …` | the line, CRLF included, is longer than 107 bytes; it does not end in CRLF; it holds a byte that is not printable ASCII; the protocol is none of the three; an address or a port is malformed, or of the other family than `TCP4` or `TCP6` says |
+| v2, the 12-byte signature, then version 2 | the TLVs (the extensions after the addresses) announce more than 2048 bytes — refused from the first 16 bytes, before any of it is waited for; a TLV runs past the end of the block; the command, family or transport is unknown; the address block is shorter than its family needs |
+
+TLVs are checked for their shape, then skipped: the server reads none,
+SSL and authority included.
+
+What the client sent in the same segment as the header, behind it, is the
+client's own. On a clear port that is bytes sent before the greeting, so
+the client is refused with `554 <hostname> Talked before the greeting`, as
+it would be without a proxy.
+
+### Which address the client gets
+
+| The proxy sends | `session.remoteAddress` is |
+| --- | --- |
+| v1 `PROXY TCP4` or `PROXY TCP6` | the source address |
+| v2 `PROXY`, over TCP (STREAM), IPv4 or IPv6 | the source address |
+| v2 `LOCAL`: the proxy's own connection, a health check | the peer's, the proxy's |
+| v2 `PROXY` with an UNSPEC or UNIX address, or over UDP (DGRAM) | the peer's |
+| v1 `PROXY UNKNOWN` | the peer's |
+
+An IPv6 source is written in RFC 5952's form — lower case, no leading
+zeros, the longest run of zeros as `::` — and an IPv4-mapped source as its
+plain IPv4 address: `::FFFF:C633:6407` reaches your code as
+`198.51.100.7`.
+
+That address is the client's everywhere the server uses one:
+`session.remoteAddress` in `onConnect`, in every hook, in `authenticate`
+and in `onError`; the Received field (`from client.example
+([198.51.100.7])`); and `maxConnectionsPerClient`, which counts it by
+`clientKey` as any other. So a policy written for a server without a proxy
+works unchanged behind one:
+
+```ts
+import { clientKey, createSmtpServer, reply } from '@bumail/smtp';
+
+const blocked = new Set(['203.0.113.7', '2001:db8:0:0::/64']);
+
+const server = createSmtpServer({
+	hostname: 'mx.example.com',
+	localDomains: ['example.com'],
+	proxyProtocol: { trusted: ['10.0.0.5', 'fd00::5'] },
+	maxConnectionsPerClient: 5, // per client behind the proxy, not for the proxy
+	onConnect: (session) =>
+		blocked.has(clientKey(session.remoteAddress) ?? '') ? reply(554, '5.7.1', 'Go away') : undefined,
+	onData: async (message) => {
+		await new Response(message.content).bytes();
+	},
+});
+
+await server.listen({ port: 25 });
+```
+
+### STARTTLS on 25 and 587
+
+Nothing changes for STARTTLS. The header is read before the greeting; the
+session then runs in clear, `STARTTLS` upgrades it as usual, and the
+client's address carries over to the encrypted session. The proxy passes
+the TLS records through untouched: it must not terminate TLS itself.
+
+### Implicit TLS on 465, behind a proxy
+
+On an `implicitTls` port the proxy's header comes first, then the client's
+ClientHello. A Bun TLS listener would take the header for a broken
+ClientHello, and Bun's `socket.upgradeTLS` reads only bytes that arrive
+after it is called, while a proxy often sends the ClientHello in the same
+TCP segment as the header (with Bun 1.4.2, the handshake then never
+completes).
+
+So with `proxyProtocol` and `implicitTls` together, the port listens in
+clear, and every connection's TLS runs through `node:tls` over the raw
+socket: after the header from a trusted proxy, from the first byte from
+anyone else. For you, it changes little:
+
+- `tls.key` and `tls.cert` still take a string, bytes or a `BunFile`; they
+  are read when `listen()` is called.
+- Behind the header, the TLS handshake has `handshakeTimeout` again, on
+  Bun's socket timer, as on implicit TLS without a proxy; meanwhile the
+  socket holds its slot, counted by the client's address.
+- A refusal by a limit, `onConnect`, the greeting and `greetingDelay` wait
+  for the handshake, so the client reads them over TLS and
+  `session.secure` is `true`.
+
+```ts
+import { createSmtpServer } from '@bumail/smtp';
+
+const server = createSmtpServer({
+	hostname: 'smtp.example.com',
+	mode: 'submission',
+	implicitTls: true,
+	localDomains: ['example.com'],
+	tls: {
+		key: Bun.file('/etc/ssl/smtp.example.com.key'),
+		cert: Bun.file('/etc/ssl/smtp.example.com.crt'),
+	},
+	proxyProtocol: { trusted: ['10.0.0.5'] },
+	authenticate: ({ username, password }) => username === 'alice' && password === Bun.env['ALICE_PASSWORD'],
+	async onData(message) {
+		await Bun.write(`queue/${message.id}.eml`, await new Response(message.content).bytes());
+	},
+});
+
+await server.listen({ port: 465 });
+```
+
+### With Traefik
+
+Traefik's TCP routers pass a connection through and, with a
+`serversTransport` whose `proxyProtocol.version` is 2, send a v2 header
+first. One entry
+point per port, in the static configuration:
+
+```yaml
+# traefik.yml
+entryPoints:
+  smtp:
+    address: ':25'
+  submission:
+    address: ':587'
+  submissions:
+    address: ':465'
+```
+
+Then, in the dynamic configuration, one router and one service each.
+``HostSNI(`*`)`` with no `tls` section matches every connection without
+terminating TLS, so STARTTLS on 25 and 587, and the TLS of 465, pass
+through to the server, which holds the certificate:
+
+```yaml
+# dynamic.yml
+tcp:
+  routers:
+    smtp:
+      entryPoints: [smtp]
+      rule: 'HostSNI(`*`)'
+      service: smtp
+    submission:
+      entryPoints: [submission]
+      rule: 'HostSNI(`*`)'
+      service: submission
+    submissions:
+      entryPoints: [submissions]
+      rule: 'HostSNI(`*`)'
+      service: submissions
+  serversTransports:
+    proxy-v2:
+      proxyProtocol:
+        version: 2
+  services:
+    smtp:
+      loadBalancer:
+        serversTransport: proxy-v2
+        servers:
+          - address: 'mail:25'
+    submission:
+      loadBalancer:
+        serversTransport: proxy-v2
+        servers:
+          - address: 'mail:587'
+    submissions:
+      loadBalancer:
+        serversTransport: proxy-v2
+        servers:
+          - address: 'mail:465'
+```
+
+This was run against Traefik v3.7 in Docker, a client reaching it with
+`openssl s_client` on 465 and with `-starttls smtp` on 25 and 587: the
+server saw the client's address in `onConnect` and every hook, Traefik's
+nowhere. Older v3 releases take the version on the service instead —
+`loadBalancer.proxyProtocol: { version: 2 }` beside `servers` — which
+v3.7 still honours, with a warning that it is deprecated in favour of the
+`serversTransport` above; the header sent is the same.
+
+The matching servers, trusting Traefik's address on the network it shares
+with the mail server (`172.20.0.2` here; give the proxy a fixed address
+there):
+
+```ts
+import { createSmtpServer, type ReceivedMessage, type SmtpServerOptions } from '@bumail/smtp';
+
+const tls = {
+	key: await Bun.file('/etc/ssl/mail.example.com.key').text(),
+	cert: await Bun.file('/etc/ssl/mail.example.com.crt').text(),
+};
+const users = new Map([['alice', await Bun.password.hash('correct horse')]]);
+
+async function deliver(message: ReceivedMessage): Promise<void> {
+	await Bun.write(`spool/${message.id}.eml`, await new Response(message.content).bytes());
+}
+
+const shared = {
+	hostname: 'mail.example.com',
+	localDomains: ['example.com'],
+	tls,
+	// Traefik alone: never the network's whole range if anything else on it is not yours.
+	proxyProtocol: { trusted: ['172.20.0.2'] },
+	onData: deliver,
+} satisfies SmtpServerOptions;
+
+const submission = {
+	...shared,
+	mode: 'submission',
+	async authenticate({ username, password }) {
+		const hash = users.get(username);
+		return hash !== undefined && (await Bun.password.verify(password, hash));
+	},
+} satisfies SmtpServerOptions;
+
+await createSmtpServer(shared).listen({ port: 25 });
+await createSmtpServer(submission).listen({ port: 587 });
+await createSmtpServer({ ...submission, implicitTls: true }).listen({ port: 465 });
+```
+
+Traefik's health checks, and any connection it opens on its own, come as
+v2 `LOCAL`: they keep the proxy's address, by design. A client that
+reaches the server without Traefik, on another network, is a peer not
+listed and is served as such.
+
 ## Sending mail: the client
 
 `@bumail/smtp/client` is the other side of the conversation: `sendMail`
@@ -1291,6 +1742,7 @@ a server of your own.
 
 ```ts
 import {
+	clientKey,
 	DataReader,
 	decodePlain,
 	formatReply,
@@ -1310,6 +1762,12 @@ parsePath('<Joe.Bloggs@EXAMPLE.Org>', false)?.address; // 'Joe.Bloggs@example.or
 parsePath('<>', true); // { address: '', local: '', domain: '' }: the null path, where allowed
 parsePath('<>', false); // undefined
 
+parsePathCommand('TO:<Postmaster>', 'TO')?.path;
+// { address: 'postmaster', local: 'postmaster', domain: '', postmaster: true }
+
+clientKey('::ffff:192.0.2.1'); // '192.0.2.1'
+clientKey('2001:db8:1:2::9'); // '2001:db8:1:2::/64'
+
 formatReply(reply(550, '5.7.1', ['a', 'b'])); // '550-5.7.1 a\r\n550 5.7.1 b\r\n'
 formatReply(reply(250, '2.0.0', 'OK'), false); // '250 OK\r\n': no enhanced status
 
@@ -1343,6 +1801,7 @@ console.log(chunk.done, reader.bareLineBreaks);
 | Behaviour | RFC |
 | --- | --- |
 | the session, commands, replies, paths, the Received field | RFC 5321 |
+| `RCPT TO:<postmaster>` with no domain | RFC 5321 §4.1.1.3, §4.5.1 |
 | SIZE | RFC 1870 |
 | PIPELINING | RFC 2920 |
 | 8BITMIME | RFC 6152 |
@@ -1350,6 +1809,7 @@ console.log(chunk.done, reader.bareLineBreaks);
 | ENHANCEDSTATUSCODES and the codes themselves | RFC 2034, RFC 3463 |
 | STARTTLS | RFC 3207 |
 | implicit TLS | RFC 8314 |
+| the PROXY protocol, v1 and v2 | not an RFC: HAProxy's `proxy-protocol.txt` |
 | AUTH | RFC 4954 |
 | SASL PLAIN | RFC 4616 |
 | submission mode | RFC 6409 |