@bumail/queue 0.13.0 → 0.14.0

package/docs/roadmap.md

@@ -6,13 +6,15 @@ only number on it.
 
 ## Now
 
-Nothing is under way.
+- **MTA-STS (RFC 8461) and TLS-RPT (RFC 8460)** ([#292](https://github.com/softistx/bumail/issues/292)) — a recipient
+  domain's policy fetched with `@bumail/mta-sts`, cached and enforced on MX
+  delivery: the certificate is checked against the policy's MX names. Opt-in
+  in the library, on in `@bumail/server`. An enforce failure defers the
+  message (`4.7.5`) and bounces it only at `giveUpAfter`. TLS reports are
+  recorded and sent opt-in.
 
 ## Next
 
-- **MTA-STS (RFC 8461) and TLS-RPT (RFC 8460)** — a recipient domain's
-  policy fetched, cached and enforced, `mxTls: 'required'` with the
-  certificate checked against the policy's MX names, and the reports.
 - **DANE (RFC 7672)** — TLSA records checked for MX hosts, once a
   resolver that validates DNSSEC can be given to the queue.
 

package/docs/troubleshooting.md

@@ -99,6 +99,12 @@ parts shown as … vary.
 
 **Delivery**
 
+- [A recipient is deferred with `4.7.5`, or fails with `5.7.5`, `MTA-STS policy of … (enforce)`](#a-recipient-is-deferred-with-475-or-fails-with-575-mta-sts-policy-of--enforce)
+- [`MTA-STS discovery took more than N ms`](#mta-sts-discovery-took-more-than-n-ms-a-tls-event-with-tlsresult-sts-policy-fetch-error)
+- [`QueueError: mtaSts must be an object of options…`, `mtaSts.cache must be a PolicyCache with get and set`, `mtaSts.fetch must be a function`](#queueerror-mtasts-must-be-an-object-of-options-mtastscache-must-be-a-policycache-with-get-and-set-mtastsfetch-must-be-a-function)
+- [`QueueError: mtaSts.fetchTimeoutMs must be a number of milliseconds…`, `mtaSts.maxAgeCap must be a whole number of seconds…`, `mtaSts.skip must be a function`](#queueerror-mtastsfetchtimeoutms-must-be-a-number-of-milliseconds-mtastsmaxagecap-must-be-a-whole-number-of-seconds-mtastsskip-must-be-a-function)
+- [`QueueError: mtaSts needs a resolver with txt(name)`](#queueerror-mtasts-needs-a-resolver-with-txtname)
+- [A `tls` event with `sts-policy-fetch-error` and the mail goes out unprotected](#a-tls-event-with-sts-policy-fetch-error-and-the-mail-goes-out-unprotected)
 - [A recipient stays `deferred` with `4.4.1` or `4.4.2`](#a-recipient-stays-deferred-with-441-or-442)
 - [Every delivery fails at once with `5.7.1`, or with a reply naming your IP or EHLO name](#every-delivery-fails-at-once-with-571-or-with-a-reply-naming-your-ip-or-ehlo-name)
 - [A recipient fails with `5.1.3`, `The address is not one SMTP can carry`](#a-recipient-fails-with-513-the-address-is-not-one-smtp-can-carry)
@@ -896,6 +902,49 @@ const clean = text.replaceAll('\0', '').toWellFormed();
 
 ## Delivery
 
+### A recipient is deferred with `4.7.5`, or fails with `5.7.5`, `MTA-STS policy of … (enforce)`
+
+**When:** `mtaSts` is set, the recipient domain publishes a policy in mode `enforce`, and the `deferred` event's `reply.status` is `4.7.5` (or the `failed` one's `5.7.5`) with a text such as `MTA-STS policy of example.com (enforce): No mail host of example.com (mx.other.net) is allowed by the policy's MX names (mail.example.com)`.
+**Why:** a session broke the policy: no MX host of the domain matches the policy's `mx` list (`MX_NOT_ALLOWED`), the MX does not offer STARTTLS, or its certificate does not check out for the MX name. The message is not sent anywhere else, `fallback` included (and under an `enforce` policy a plain connection failure of every MX is deferred too, never sent through the `fallback`). It is deferred with the usual back-off and bounced as `5.7.5` only at `retry.giveUpAfter`, after the policy is fetched once more.
+**Fix:** the `tls` events name the host and the `tlsResult` (`validation-failure` for a name outside the policy, `certificate-host-mismatch`, `certificate-expired`, `certificate-not-trusted`, `starttls-not-supported`). It is the receiving domain's to fix; if its policy is wrong, the message is delivered once the policy is. To send meanwhile, `retryNow(id)` after the domain changed its policy to `testing` or `none` and its record `id`.
+
+### `MTA-STS discovery took more than N ms` (a `tls` event with `tlsResult: 'sts-policy-fetch-error'`)
+
+**When:** `mtaSts` is set and the cache, the `_mta-sts` lookup and the policy fetch together used the whole `fetchTimeoutMs`.
+**Why:** the discovery has one deadline, not one per step, so a slow resolver or cache leaves the fetch less time. The message is sent without the policy (a cached one that has not expired stays in force). A policy fetch that failed is remembered for 5 minutes per domain and record `id`: a remote policy fixed under the same `id` is not fetched again for up to 5 minutes, and each session in between tells the same event. A timeout caused only by a budget the earlier steps had already used is not remembered.
+**Fix:** raise `fetchTimeoutMs`, or fix the slow resolver or cache; the domain's owner publishes a new `id` to have the policy fetched at once, or waits the 5 minutes.
+
+### `QueueError: mtaSts must be an object of options…`, `mtaSts.cache must be a PolicyCache with get and set`, `mtaSts.fetch must be a function`
+
+**Code:** `INVALID`. `mtaSts` is the options object, `cache` an object with `get` and `set` (`createMemoryPolicyCache()` fits), `fetch` a function.
+
+```ts
+mtaSts: { cache: createMemoryPolicyCache(), fetch: globalThis.fetch }
+```
+
+### `QueueError: mtaSts.fetchTimeoutMs must be a number of milliseconds…`, `mtaSts.maxAgeCap must be a whole number of seconds…`, `mtaSts.skip must be a function`
+
+**Code:** `INVALID`. `fetchTimeoutMs` is above 0 and at most 2147483647; `maxAgeCap` is a whole number of seconds from 0 to 31557600 (`MAX_AGE_LIMIT` of `@bumail/mta-sts`); `skip` is a function.
+
+```ts
+mtaSts: { fetchTimeoutMs: 30_000, maxAgeCap: 7 * 86_400 }
+```
+
+### `QueueError: mtaSts needs a resolver with txt(name)`
+
+**Code:** `INVALID`. `mtaSts` reads the `_mta-sts` TXT record, and neither `mtaSts.resolver` nor the queue's `resolver` has `txt`.
+
+```ts
+createQueue({ store, hostname, resolver: nodeResolver(), mtaSts: {} }); // nodeResolver() has txt
+createQueue({ store, hostname, resolver, mtaSts: { resolver: nodeResolver() } });
+```
+
+### A `tls` event with `sts-policy-fetch-error` and the mail goes out unprotected
+
+**When:** `mtaSts` is set, and the `tls` event has no `mxHost` and a `tlsResult` of `sts-policy-fetch-error`, `sts-policy-invalid` or `sts-webpki-invalid`.
+**Why:** the domain has an `_mta-sts` record, but `https://mta-sts.<domain>/.well-known/mta-sts.txt` could not be had (a timeout, a redirect, a status other than 200, a wrong content type, an invalid policy, a certificate the system does not trust). RFC 8461 §5.1 then applies a cached policy that has not expired, and with none sends without a policy: that session is not protected.
+**Fix:** the domain's to fix. Check the policy URL yourself, and that the `fetch` you gave (`mtaSts.fetch`) can reach it.
+
 ### A recipient stays `deferred` with `4.4.1` or `4.4.2`
 
 **When:** the `deferred` event's `reply` has no `code`, a `status` of

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@bumail/queue",
-	"version": "0.13.0",
+	"version": "0.14.0",
 	"description": "The outbound mail queue of a mail server: every recipient's state, retries with back-off, delivery status notifications (RFC 3464), leases for several workers, and a memory, a bun:sqlite, a PostgreSQL (Bun.sql) and a Redis (Bun.redis) store, delivering through @bumail/smtp/client",
 	"license": "MIT",
 	"type": "module",
@@ -73,12 +73,14 @@
 	"devDependencies": {
 		"@bumail/dns": "^0.2.2",
 		"@bumail/mime": "^0.2.0",
-		"@bumail/smtp": "^0.12.0",
+		"@bumail/mta-sts": "^0.1.0",
+		"@bumail/smtp": "^0.13.0",
 		"@types/bun": "^1.4.2"
 	},
 	"peerDependencies": {
 		"@bumail/mime": "^0.2.0",
-		"@bumail/smtp": "^0.12.0",
+		"@bumail/mta-sts": "^0.1.0",
+		"@bumail/smtp": "^0.13.0",
 		"typescript": "^6.0.3 || ^7.0.0"
 	},
 	"peerDependenciesMeta": {