@bumail/smtp 0.2.0 → 0.3.0

package/docs/guide.md

@@ -295,14 +295,19 @@ export interface Path {
 ```
 
 A source route (`<@a.example:b@c.example>`, RFC 5321 Appendix C) is dropped:
-the path is `b@c.example`.
+the path is `b@c.example`. It is taken only as `@domain(,@domain)*:`, each
+hop a valid domain or address literal; any other route — an empty hop, a
+hop without its `@`, a hop that is not a domain — is a `501 5.5.4 Syntax`.
 
 `local` is kept as written, quotes included. `<"v@x.example"@example.com>`
 and `<v%x.example@example.com>` are local parts of `example.com`, and
 passed the relay check as such: code that delivers must take the domain
 after the last `@` — `path.domain` — and never split `address` on its
-first `@`. C1 controls, Unicode format characters (zero-width, bidi, BOM)
-and U+2028/2029 are refused in a path, even under SMTPUTF8.
+first `@`. C0 controls (CR, LF, NUL, tab…), DEL and `>`, C1 controls,
+Unicode format characters (zero-width, bidi, BOM), U+2028/2029 and lone
+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.
 
 ## Session.data
 
@@ -878,8 +883,17 @@ server decides — the idle `timeout`, `maxErrors`, three failed AUTH
 attempts, a refusal from `onConnect`, a local error — it writes its reply
 and closes at once: the connection is counted out of `connections` then and
 there, and replies the client never read are dropped, the connection reset
-if any were still waiting. So a client that pipelines commands and stops
-reading cannot keep a slot of `maxConnections` past its `timeout`.
+if any were still waiting. When the server had stopped reading a client
+that sent more than it could take, any hang-up, `QUIT`'s included, reads
+again first, dropping whatever comes, and half-closes once the client's
+input stops for 20 ms: a half-close does not complete over input left
+unread, and on Linux a close over unread input is a reset that loses the
+last reply. A client whose input went quiet for 20 ms within 500 ms of
+the hang-up then still reads the last reply and the end. It waits 500 ms
+at most: input not quiet for 20 ms by then, a client still sending or one
+that stopped in the last 20 ms, is reset, so its slot is free by then too. So a client that
+pipelines commands and stops reading cannot keep a slot of
+`maxConnections` past its `timeout`.
 
 Every hang-up is bounded, on a clear socket, on implicit TLS and after
 STARTTLS alike. When the server decides, it never waits for the client to
@@ -955,8 +969,27 @@ await sendMail(message, { domain: 'example.org', resolver: nodeResolver(), helo:
 
 `from` is the envelope's reverse-path — `''` for the null sender of a
 bounce — and `to` one recipient or more. Both are checked as RFC 5321 paths
-before anything is sent: an address holding a CR, an LF or a `>` is refused
-with `INVALID_OPTION`, so it cannot inject a command.
+before anything is sent, before the client even connects: an address
+holding a CR, an LF, a NUL, any other control character or a `>`, in any
+part, is refused with `INVALID_OPTION`, so it cannot inject a command. A
+source route (`@a.example,@b.example:x@c.example`) is refused too, valid
+or not: RFC 5321 §4.1.1.3 says a client should not send one, and the
+address is written as it is given.
+
+Code that keeps addresses to send to later — a queue — checks
+each one when it takes it with `isMailbox`, which says yes to exactly the
+addresses `sendMail` takes — it checks with the same predicate: an RFC 5321
+Mailbox with no source route, no control character (C0, DEL or C1), no
+`>`, no U+2028 or U+2029, no Unicode format character (`\p{Cf}`), no
+lone surrogate and no IPv4 literal octet above 255 — so the refusal
+comes back to whoever gave it:
+
+```ts
+import { isMailbox } from '@bumail/smtp/client';
+
+isMailbox('mary@example.net'); // true
+isMailbox('a,b@example.net'); // false: sendMail would refuse it
+```
 
 One call is one destination. With `{ domain }`, every recipient should be
 at that domain: group them by domain first, one `sendMail` each.
@@ -1291,7 +1324,11 @@ console.log(chunk.done, reader.bareLineBreaks);
 
 - `parsePathCommand` and `parsePath` return `undefined` when the syntax is
   wrong. `parsePath` takes UTF-8 addresses; whether a session may use one
-  is SMTPUTF8's question.
+  is SMTPUTF8's question. A control character or a `>` anywhere is wrong.
+  Its third argument says what to do with a source route: `'discard'`, the
+  default and what a server does, drops a valid `@domain(,@domain)*:`;
+  `'refuse'`, what a client does, returns `undefined` for any route:
+  `parsePath('<@a,@b:x@c.com>', false, 'refuse')` is `undefined`.
 - `formatReply` replaces a CR or LF in the text with a space, so a reply
   text cannot start a second reply.
 - `DataReader.write(chunk)` returns the unstuffed bytes, whether the

package/docs/troubleshooting.md

@@ -89,6 +89,7 @@ A reply carries its enhanced status code (`5.7.1`, RFC 3463) only after
 **Sending mail: options**
 
 - [`SmtpError: sendMail(): "…" is not an address (local@domain)`](#smtperror-sendmail--is-not-an-address-localdomain)
+- [`SmtpError: sendMail(): "…" holds a source route (@host:), which RFC 5321 says a client should not send: pass "…" alone`](#smtperror-sendmail--holds-a-source-route-host-which-rfc-5321-says-a-client-should-not-send-pass--alone)
 - [`SmtpError: sendMail(): to must name one recipient or more`](#smtperror-sendmail-to-must-name-one-recipient-or-more)
 - [`SmtpError: sendMail(): helo "…" is not a host name`](#smtperror-sendmail-helo--is-not-a-host-name)
 - [`SmtpError: sendMail(): helo is required for delivery by MX: pass your server's public name, such as helo: 'mail.example.com'`](#smtperror-sendmail-helo-is-required-for-delivery-by-mx-pass-your-servers-public-name-such-as-helo-mailexamplecom)
@@ -737,7 +738,10 @@ base64 response to the challenge — see
 ### `501 Syntax: EHLO hostname`
 
 **When**: `EHLO` with no argument, or with one that is neither a domain nor
-an address literal — an underscore, a space, a bare IP without brackets.
+an address literal — an underscore, a space, a bare IP without brackets,
+an IPv4 literal with an octet above 255 (`[999.1.1.1]`), an IPv6 one
+without its `IPv6:` tag (`[2001:db8::1]`). The tag may be in any case:
+`[ipv6:2001:db8::1]` is accepted.
 `HELO` gets `501 Syntax: HELO hostname`. Before an EHLO was accepted the
 reply has no enhanced code; after one, it is
 `501 5.5.4 Syntax: EHLO hostname`. It counts toward `maxErrors`.
@@ -799,7 +803,10 @@ send `RSET` to start a transaction over.
 
 **When**: a command whose argument is wrong: `MAIL FROM:<address>` without
 the angle brackets or the colon, a path with a space, a control or an
-invisible character (C1, zero-width, bidi, U+2028), `DATA` or `STARTTLS`
+invisible character (NUL, ESC, DEL, C1, zero-width, bidi, U+2028), a source
+route that is not `@domain(,@domain)*:` (`<@a,b:x@foo.com>`,
+`<@a..b:x@foo.com>`; a valid one is accepted and dropped), an IPv4
+address literal with an octet above 255 (`<a@[999.1.1.1]>`), `DATA` or `STARTTLS`
 with an argument, `AUTH` with more than a mechanism and a response,
 `SIZE=` that is not a number. The text after `Syntax:` gives the expected
 form. Each counts toward `maxErrors`.
@@ -1415,8 +1422,15 @@ needs it at `0`.
 ### `SmtpError: sendMail(): "…" is not an address (local@domain)`
 
 **When**: `from` or a recipient in `to` is not an RFC 5321 path: no `@`, a
-display name (`Bob <b@example.org>`), angle brackets, a space, or a CR or
-LF. For `from` the message ends `(local@domain, or '' for a bounce)`.
+display name (`Bob <b@example.org>`), angle brackets, a space outside
+quotes (`a b@c.com`; the quoted `"a b"@c.com` is an address), or a CR, an
+LF, a NUL, any other control character, a `>`, a C1 control, a Unicode
+format character (zero-width, bidi, BOM), U+2028/2029 or a lone surrogate
+(`a\uD800@c.com`) in any part — the local part, quoted or not, the
+domain, or a source route (`@x\r\nRSET\r\nNOOP:a@c.com`) — or an IPv4
+address literal with an octet above 255 (`a@[999.1.1.1]`). A source route whose hops are not each
+`@domain` lands here too. For `from` the message ends `(local@domain, or ''
+for a bounce)`. Nothing is sent: the check runs before the client connects.
 
 **Why**: the address goes into `MAIL FROM:<…>` or `RCPT TO:<…>` as it is;
 anything else could break the command or inject another.
@@ -1429,6 +1443,25 @@ import { sendMail } from '@bumail/smtp/client';
 await sendMail('Subject: hi\r\n\r\nhello\r\n', { host: 'relay.example.net', from: '', to: ['b@example.org'] });
 ```
 
+### `SmtpError: sendMail(): "…" holds a source route (@host:), which RFC 5321 says a client should not send: pass "…" alone`
+
+**When**: `from` or a recipient in `to` starts with a source route, such as
+`@a.example,@b.example:x@c.example` (RFC 5321 Appendix C). The second `"…"`
+is the address without it.
+
+**Why**: RFC 5321 §4.1.1.3 says a client should not send a source route,
+and the client writes the address as it is given. A server accepts and
+drops one, so it never routed anything; refusing it keeps the envelope to
+the plain `local@domain` the client checked.
+
+**Fix**: pass the address the message names, after the colon:
+
+```ts
+import { sendMail } from '@bumail/smtp/client';
+
+await sendMail('Subject: hi\r\n\r\nhello\r\n', { host: 'relay.example.net', from: 'a@example.com', to: 'x@c.example' });
+```
+
 ### `SmtpError: sendMail(): to must name one recipient or more`
 
 **When**: `to` is an empty array, or neither a string nor an array.
@@ -1440,7 +1473,10 @@ await sendMail('Subject: hi\r\n\r\nhello\r\n', { host: 'relay.example.net', from
 ### `SmtpError: sendMail(): helo "…" is not a host name`
 
 **When**: `helo` is not a host name nor an address literal such as
-`[192.0.2.1]`.
+`[192.0.2.1]` or `[IPv6:2001:db8::1]`: an underscore, a space, a bare IP
+without brackets, an IPv4 literal with an octet above 255
+(`[999.1.1.1]`), an IPv6 one without its `IPv6:` tag. The tag may be in
+any case: `[ipv6:2001:db8::1]` is taken.
 
 **Why**: it is the argument of EHLO and HELO (RFC 5321 §4.1.1.1).
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@bumail/smtp",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "An SMTP server on Bun.listen — RFC 5321 with PIPELINING, SIZE, 8BITMIME, SMTPUTF8, STARTTLS and AUTH after TLS, policy hooks, and no open relay — and a client that delivers a message to a smarthost or by MX",
 	"license": "MIT",
 	"type": "module",
@@ -47,9 +47,9 @@
 		]
 	},
 	"devDependencies": {
-		"@bumail/auth": "^0.2.0",
+		"@bumail/auth": "^0.3.0",
 		"@bumail/dns": "^0.1.1",
-		"@bumail/store": "^0.2.0",
+		"@bumail/store": "^0.3.0",
 		"@types/bun": "^1.4.2"
 	},
 	"peerDependencies": {