@bumail/smtp 0.5.0 → 0.7.0

package/dist/server/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/server/settings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGnD,qDAAqD;AACrD,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD;AAkED,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,QAAQ,CA4D/D"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/server/settings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,qDAAqD;AACrD,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC;IACzB,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD;AAkED,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,QAAQ,CA6D/D"}

package/dist/server/tls-context.d.ts

@@ -1,16 +1,46 @@
 import { type SecureContext } from 'node:tls';
 /** `key` or `cert` as `Bun.listen` takes them: text, bytes or a file. */
 type TlsMaterial = string | Uint8Array | Bun.BunFile;
+/** A key and certificate pair, as `Bun.listen` takes it. */
+interface TlsPair {
+    readonly key: TlsMaterial;
+    readonly cert: TlsMaterial;
+}
+/** `tls` read whole, with the `node:tls` context made from it. */
+interface ReadTls {
+    readonly key: string | Buffer;
+    readonly cert: string | Buffer;
+    readonly context: SecureContext;
+}
 /**
  * `tls` read whole — a file included — and checked as a `node:tls` context:
  * what implicit TLS behind a proxy runs on, and, without a proxy, the check
  * that makes a key or certificate that cannot be read or used fail
- * `listen()` the same way. `fail` turns the reason into the package's own
- * error, the `node:tls` or file error as its `cause`.
+ * `listen()` and `setTls()` the same way. `fail` turns the reason into the
+ * package's own error, the `node:tls` or file error as its `cause`.
  */
-export declare function tlsContext(tls: {
-    readonly key: TlsMaterial;
-    readonly cert: TlsMaterial;
-}, fail: (message: string, cause: unknown) => Error): Promise<SecureContext>;
+export declare function readTls(tls: TlsPair, fail: (message: string, cause: unknown) => Error, caller: string): Promise<ReadTls>;
+/**
+ * The key and certificate the server uses now. What `listen()` or `setTls()`
+ * read replaces it whole, and only once checked, so a pair that cannot be
+ * used leaves the one in use. A STARTTLS server that has read nothing yet
+ * serves `tls` as it was given.
+ */
+export declare class TlsHolder {
+    #private;
+    constructor(given: TlsPair);
+    /** What an upgrade to TLS, or a native listener, is given. */
+    get options(): TlsPair;
+    /** The `node:tls` context of the pair in use: only once `load` or `replace` read one. */
+    get context(): SecureContext;
+    /** Reads and checks the pair given, unless a read already replaced it. */
+    load(fail: (message: string, cause: unknown) => Error, caller: string): Promise<SecureContext>;
+    /**
+     * Checks `tls`, then uses it from the next connection on. Calls apply in
+     * the order they were made, however long each read takes; one that fails
+     * does not hold the next.
+     */
+    replace(tls: TlsPair, fail: (message: string, cause: unknown) => Error, caller: string): Promise<void>;
+}
 export {};
 //# sourceMappingURL=tls-context.d.ts.map

package/dist/server/tls-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tls-context.d.ts","sourceRoot":"","sources":["../../src/server/tls-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAEnE,yEAAyE;AACzE,KAAK,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC;AAErD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC/B,GAAG,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,EAC9D,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,KAAK,GAC9C,OAAO,CAAC,aAAa,CAAC,CAcxB"}
+{"version":3,"file":"tls-context.d.ts","sourceRoot":"","sources":["../../src/server/tls-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAEnE,yEAAyE;AACzE,KAAK,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC;AAErD,4DAA4D;AAC5D,UAAU,OAAO;IAChB,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC3B;AAED,kEAAkE;AAClE,UAAU,OAAO;IAChB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CAChC;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC5B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,KAAK,EAChD,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAED;;;;;GAKG;AACH,qBAAa,SAAS;;gBAMT,KAAK,EAAE,OAAO;IAI1B,8DAA8D;IAC9D,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,yFAAyF;IACzF,IAAI,OAAO,IAAI,aAAa,CAG3B;IAED,0EAA0E;IACpE,IAAI,CACT,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,KAAK,EAChD,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,CAAC;IAOzB;;;;OAIG;IACH,OAAO,CACN,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,KAAK,EAChD,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC;CAOhB"}

package/docs/guide.md

@@ -15,6 +15,7 @@ behaviour.
 - [Delivering into @bumail/store](#delivering-into-bumailstore)
 - [Authentication](#authentication)
 - [TLS](#tls)
+  - [Renewing the certificate without a restart](#renewing-the-certificate-without-a-restart)
 - [Limits](#limits)
 - [Running behind a TCP proxy](#running-behind-a-tcp-proxy)
 - [Sending mail: the client](#sending-mail-the-client)
@@ -781,9 +782,10 @@ export interface TlsOptions {
 }
 ```
 
-`key` and `cert` are PEM, as `Bun.listen` takes them. Read them once, at
+`key` and `cert` are PEM, as `Bun.listen` takes them. Read them at
 start-up, with `Bun.file().text()`; a missing file then fails before the
-server listens, not at a client's first STARTTLS:
+server listens, not at a client's first STARTTLS. A renewed pair is
+applied with `setTls`, [below](#renewing-the-certificate-without-a-restart):
 
 ```ts
 import { createSmtpServer } from '@bumail/smtp';
@@ -840,10 +842,13 @@ 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.
+The listener of an implicit TLS port is a clear one, and each socket is
+upgraded to TLS (`socket.upgradeTLS`) as it opens, with the pair in use
+at that moment: that is what lets `setTls` apply to the next connection
+(see [below](#renewing-the-certificate-without-a-restart)). The upgraded
+socket calls `open` at the TCP connection, with the socket's timer
+running during the handshake, which is how a stuck handshake is counted
+and closed.
 
 Behind a TCP proxy that sends the PROXY protocol, implicit TLS starts after
 the proxy's header, and runs differently: see
@@ -912,6 +917,67 @@ await createSmtpServer(submission).listen({ port: 587 });
 await createSmtpServer({ ...submission, implicitTls: true }).listen({ port: 465 });
 ```
 
+### Renewing the certificate without a restart
+
+A certificate that is renewed — by certbot, by Traefik's dump, by an ACME
+client — should take effect without a restart, and without dropping the
+sessions open. `setTls({ key, cert })` does that:
+
+```ts
+const mx = createSmtpServer({ hostname: 'mx.example.com', localDomains: ['example.com'], tls, onData });
+await mx.listen({ port: 25 });
+
+// Later, once the files changed:
+await mx.setTls({
+	key: await Bun.file('/etc/ssl/mx.example.com.key').text(),
+	cert: await Bun.file('/etc/ssl/mx.example.com.crt').text(),
+});
+```
+
+- **What changes**: the next STARTTLS upgrade, and on implicit TLS the next
+  connection, use the new pair. A session already encrypted keeps the TLS
+  it has until it ends, and goes on working; a handshake that began
+  before the call may still finish on the old pair.
+- **It is checked first.** `setTls` reads both (a `Bun.file` included) and
+  makes a TLS context of them, as `listen()` does on implicit TLS. A pair
+  that cannot be read, is not PEM or is a key for another certificate
+  rejects with an `SmtpError`, `INVALID_OPTION`, message `setTls(): tls:
+  { key, cert } cannot be used: …`, the reason as its `cause`; the old
+  pair stays in use. It does not check that the certificate has not
+  expired or names the host: that is the caller's.
+- **One call per server.** The MX on 25, submission on 587 and the
+  implicit TLS server on 465 are three servers, each with its own
+  `setTls`. Call it on all of them with the same pair.
+- **Calls apply in order.** Two `setTls` in flight, the first reading
+  files, end on the second's pair: the later call wins. A key or
+  certificate that is empty is refused like any pair that cannot be used.
+- **Before `listen()` too**: the pair set is the one served. A server made
+  without `tls` has none to replace: `setTls` rejects with
+  `INVALID_OPTION`.
+- **A file read at `setTls`, not at each connection.** Passing a
+  `Bun.file` reads it once, when `setTls` runs: to take a later change,
+  call `setTls` again.
+
+How it works on each kind of port, measured on Bun 1.4.2:
+
+- **STARTTLS**: the options of `socket.upgradeTLS` are read for each
+  upgrade, so the server swaps the pair it keeps.
+- **Native implicit TLS**: a `Bun.listen` TLS listener keeps the TLS
+  context it was created with. `listener.reload()` takes handlers only,
+  and a `tls` given to it is ignored (a new connection still got the old
+  certificate). The port listens in clear instead, and every socket is
+  upgraded with `socket.upgradeTLS` as it opens, with the pair in use
+  then, which is the STARTTLS mechanism from the first byte. The
+  encrypted bytes also pass through the clear socket's handler, which
+  drops them.
+- **Implicit TLS behind `proxyProtocol`** already runs on `node:tls`: the
+  server swaps the secure context its new sockets are given.
+- **A second listener on the same port** was not used: `Bun.listen` takes
+  `reusePort`, so a new listener could bind beside the old one and the old
+  one stop, but both must have opted in from the start, and a
+  connection waiting to be accepted by the old one when it stops is reset.
+  Upgrading in `open` has neither cost.
+
 ## Limits
 
 | Limit | Default | Past it |
@@ -1584,6 +1650,19 @@ is not. Every other outcome rejects with an `SmtpError`: its `code`, its
 `temporary`, and, when a reply caused it, `reply` with its enhanced status
 code (RFC 3463).
 
+`afterData` is `true` when the final dot was written and no reply to it came
+(a `TIMEOUT`, a `CONNECTION_LOST` or a `BAD_REPLY`): the server may already
+have taken the message (RFC 5321 §4.1.5), so sending it again, or by another
+route, can duplicate it. It is absent for a failure before the dot, which
+the server drops, and for a `REFUSED` to the dot, a 4xx or 5xx that says the
+message was not taken.
+
+```ts
+if (error.temporary && error.afterData) {
+	// the message may be there already: retry the same host, not another route
+}
+```
+
 | `code` | when | `temporary` |
 | --- | --- | --- |
 | `INVALID_OPTION` | an option, an address or the message cannot be used | no |

package/docs/roadmap.md

@@ -34,6 +34,12 @@ Nothing in progress.
 
 ### Unreleased — merged, not yet published
 
+- **A renewed certificate without a restart**, `server.setTls({ key, cert
+  })`: the next STARTTLS upgrade and the next implicit TLS connection use
+  it, the sessions open keep their TLS, and a pair that cannot be used
+  throws `INVALID_OPTION` and leaves the old one. Implicit TLS without a
+  proxy now listens in clear and upgrades each socket as it opens, since
+  a native Bun TLS listener cannot swap its certificate.
 - **Behind a TCP proxy, the client's own address**, with `proxyProtocol:
   { trusted: [...] }`: the server reads the PROXY protocol, versions 1 and
   2, from the proxies listed — a Traefik TCP router, HAProxy — so

package/docs/troubleshooting.md

@@ -32,6 +32,8 @@ A reply carries its enhanced status code (`5.7.1`, RFC 3463) only after
 - [`SmtpError: listen(): the server is already listening on …`](#smtperror-listen-the-server-is-already-listening-on-)
 - [`SmtpError: listen(): the server is already starting to listen`](#smtperror-listen-the-server-is-already-starting-to-listen)
 - [`SmtpError: listen(): tls: { key, cert } cannot be used: …`](#smtperror-listen-tls--key-cert--cannot-be-used-)
+- [`SmtpError: setTls(): tls: { key, cert } cannot be used: …`](#smtperror-settls-tls--key-cert--cannot-be-used-)
+- [`SmtpError: setTls(): the server was made without tls, so it has none to replace`](#smtperror-settls-the-server-was-made-without-tls-so-it-has-none-to-replace)
 - [`SmtpError: listen(): stop() was called before the server bound its port`](#smtperror-listen-stop-was-called-before-the-server-bound-its-port)
 
 **Relaying and authentication**
@@ -625,6 +627,50 @@ try {
 }
 ```
 
+### `SmtpError: setTls(): tls: { key, cert } cannot be used: …`
+
+**When**: `setTls` was given a renewed pair whose `key` or `cert` cannot
+be read — a `Bun.file` that does not exist, or one caught half-written —
+or is empty (`… the key is empty`, `… the cert is empty`), or is not a
+PEM key or certificate, or a key that is not the certificate's. Its `code` is `INVALID_OPTION`; the rest of the message,
+and its `cause`, are the reason from the file system or `node:tls`
+(`ENOENT: no such file or directory, open '…'`, `…PEM routines…`,
+`key values mismatch`). The pair in use stays, for new connections too.
+
+**Why**: `setTls` reads both and checks them as a TLS context before it
+swaps anything, so a bad pair never reaches a client.
+
+**Fix**: write both files before calling it — a renewal that writes the key
+first and the certificate after fails here, which is the right answer —
+and retry:
+
+```ts
+try {
+	await server.setTls({
+		key: Bun.file('/etc/bumail/tls/privkey.pem'),
+		cert: Bun.file('/etc/bumail/tls/fullchain.pem'),
+	});
+} catch (error) {
+	console.error(error, (error as Error).cause); // the old pair is still served
+}
+```
+
+### `SmtpError: setTls(): the server was made without tls, so it has none to replace`
+
+**When**: `setTls` on a server created without the `tls` option. Its `code`
+is `INVALID_OPTION`.
+
+**Why**: TLS is what turns on STARTTLS, AUTH and implicit TLS, and each
+changes what the server says: `setTls` replaces a pair, it does not turn
+TLS on.
+
+**Fix**: create the server with `tls`, the pair it starts with:
+
+```ts
+const server = createSmtpServer({ ...options, tls: { key, cert } });
+await server.setTls({ key: renewedKey, cert: renewedCert });
+```
+
 ## Relaying and authentication
 
 ### `554 5.7.1 Relay access denied`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@bumail/smtp",
-	"version": "0.5.0",
+	"version": "0.7.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.3.0",
-		"@bumail/dns": "^0.1.1",
-		"@bumail/store": "^0.4.0",
+		"@bumail/auth": "^0.4.1",
+		"@bumail/dns": "^0.2.1",
+		"@bumail/store": "^0.4.1",
 		"@types/bun": "^1.4.2"
 	},
 	"peerDependencies": {