@ultimat3/mail 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -14,8 +14,21 @@
 | `driver.ts` | `MailDriver` + memory/log/unconfigured + `resultFor` + the `setMailDriver` seam |
 | `driver-env.ts` | `selectMailDriver`: which transport an environment installs, and nothing else |
 | `header-safety.ts` | `assertHeaderSafe`: the CR/LF gate on a `MailMessage`, so every driver refuses the same one |
-| `driver-smtp.ts` | `createSmtpDriver`: `SMTP_URL` parsing, the pool ceiling, one send |
-| `driver-resend.ts` | `createResendDriver`: one `POST /emails`, status → retryable |
+| `driver-smtp.ts` | `smtpMailDriver`: `SMTP_URL` parsing, the pool ceiling, one send |
+| `driver-resend.ts` | `resendMailDriver`: one `POST /emails`, status → retryable |
+| `driver-ses.ts` | `sesMailDriver`: one SES v2 `SendEmail`, raw MIME, signed by core's `signAwsRequest` |
+| `ses-failure.ts` | SES error TYPE → retry verdict + `fix:`; the status is the fallback |
+| `retain-mime.ts` | `retainMime`: the exact MIME a transport handed its provider, capped, + the `onRetained` sink |
+| `delivery-event.ts` | `DeliveryEvent` / `DeliveryOutcome`, the capped body read, the ISO instant |
+| `delivery-event-errors.ts` | the three receiver refusals (`X_MAIL_EVENT_*`) |
+| `sns-signature.ts` | SNS message verification: topic allow-list, pinned cert URL, canonical string, RSA v1/v2 |
+| `sns-certificate-cache.ts` | the downloaded SNS certificates, bounded against forgery floods |
+| `x509-spki.ts` | the public key out of a PEM certificate (Web Crypto imports no certificate) |
+| `ses-event-receiver.ts` | `sesEventReceiver`: body → verify → normalise; SubscriptionConfirmation |
+| `delivery-event-ses.ts` | SES notification JSON (`notificationType` or `eventType`) → events |
+| `resend-signature.ts` | Svix verification: HMAC over `id.timestamp.body`, constant-time, then the window |
+| `resend-event-receiver.ts` | `resendEventReceiver` + the Resend payload → events |
+| `events.ts` | the `@ultimat3/mail/events` subpath: the receivers, kept off the barrel |
 | `smtp-client.ts` | the conversation: greeting → EHLO → STARTTLS → AUTH → envelope → DATA |
 | `smtp-protocol.ts` | pure protocol: reply framing, capabilities, AUTH payloads, dot-stuffing |
 | `smtp-socket.ts` | the one production `SmtpStream`, over `Bun.connect` |
@@ -25,7 +38,7 @@
 | `transform.ts` | `setMailTransform`: the app's outbound hook, run once per `send()` before the key |
 | `idempotency.ts` | `mailIdempotencyKey` — apart from `job.ts` because the transports need it too |
 | `catalog.ts` | English source strings for `mail.*`. Data, not code |
-| `html.ts` | escaping + `safeUrl`. The only place that builds an attribute |
+| `html.ts` | escaping + `safeMailHref`. The only place that builds an attribute |
 
 ## Rules
 
@@ -35,6 +48,20 @@
   result is re-checked by `assertHeaderSafe`; a throw or a malformed result is
   `X_MAIL_TRANSFORM_FAILED` and nothing is sent. None installed ⇒ the same object, byte-identical.
 
+- **`send()` enqueues through `jobsFacade().enqueue(sendMailJob, message)`, never `jobDriver().enqueue`**
+  (`As of 2026-10-02`). The driver call published on the pool, autocommitted, so a handler that
+  rolled back after `send()` still mailed — and under `{ retry }` each re-run could mail again.
+  Through the facade an ambient transaction STAGES the row and the relay publishes it after COMMIT.
+  `send-outbox.job.test.ts` proves a rollback delivers nothing, on the memory pair and on Postgres.
+- **One recipient rule, inline and queued** (`As of 2026-10-02`). `addressRefusal`
+  (`envelope-address.ts`) is `envelopeAddress`'s rule without the throw; `renderMessage` applies it
+  to `to`/`cc`/`bcc`/`replyTo` after the header gate, and `mailMessageSchema` refines with it. It was
+  `t.email` on the queue and nothing inline, so `Jane Doe <jane@x.test>` answered `queued: true` and
+  the worker's parse refused the row. `unsubscribeUrl` is `t.url` on both paths for the same reason.
+- `X_MAIL_HEADER_INVALID` carries `meta.reason` (`line-break` | `non-ascii`) with a cause per
+  reason; the non-ASCII mailbox refusal was raised with the line-break cause until 2026-10-02.
+  `Reply-To` takes the `address` mode in `mime.ts` (encoded phrase, refused non-ASCII mailbox), and
+  an ASCII phrase holding an RFC 5322 special other than `.` is quoted (`"Doe, Jane"`).
 - `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim**, so a `defineMail` file
   imports one package. Never wrap, spread or re-declare it: `t` delegates to `schemaProvider()` on
   every access, and a copy would freeze the provider at import time. `index.test.ts` asserts identity.
@@ -45,7 +72,7 @@
   one `prefers-color-scheme` block keyed on short `data-x` role codes.
 - Never format a date without `options.tz`. The `Date:` header is UTC, stated as `+0000`.
 - **`timeoutMs` is refused at CONSTRUCTION, where `poolSize` already is, and its floor is 1**
-  (`As of 2026-08-26`). `finiteCount('createSmtpDriver'|'createResendDriver', 'timeoutMs', …, 1)`.
+  (`As of 2026-08-26`). `finiteCount('smtpMailDriver'|'resendMailDriver', 'timeoutMs', …, 1)`.
   Zero is not "no deadline" in either driver: the value goes straight to `AbortSignal.timeout` and
   to `setTimeout(fn, timeoutMs)`, both of which fire on the next tick, so `0` and `NaN` are the same
   failure — `setTimeout(fn, NaN)` IS `setTimeout(fn, 0)`. Resend's was the worse half: the signal is
@@ -54,10 +81,10 @@
   endpoint, and the queue retried a config error to the dead-letter table. `bun run finite-bounds`
   is the ratchet; the repair is recognised by the shape of the call.
 
-- **Every "now" in this package comes from a `Clock`, `createMemoryDriver` included** (`As of
+- **Every "now" in this package comes from a `Clock`, `memoryMailDriver` included** (`As of
   2026-08-22`). It stamped `at: new Date()`, and `SentMail.at` is what `outbox()`, `lastTo()` and
   the `/_x` panel ORDER on — so the one fact a test most needs to state was the one it could only
-  observe, and two sends inside one millisecond tied. `createMemoryDriver({ clock })`, the same
+  observe, and two sends inside one millisecond tied. `memoryMailDriver({ clock })`, the same
   options shape `@ultimat3/jobs`' identically-named driver takes; omitted, it is `systemClock`.
 - New block kind: `MailBlock` + `blocks` + `htmlOf` + `textOf`, same commit.
 - A transport failure is `sendFailed({ stage, status, retryable, fix })` — never a bare throw, and
@@ -82,7 +109,7 @@
 - **No credential is answered by the ENVIRONMENT, and outside development it REFUSES** (`As of
   2026-08`). It answered the memory driver everywhere, including production — so a deploy that
   configured no transport reported `accepted` for mail that never left the process, with no error
-  anywhere. `createUnconfiguredDriver` rejects every send with `X_MAIL_CREDENTIAL_MISSING` instead.
+  anywhere. `unconfiguredMailDriver` rejects every send with `X_MAIL_CREDENTIAL_MISSING` instead.
   Three parts of that are decisions, not details. It is a **driver and not a boot refusal**, so an
   app that sends no mail still deploys and one that does fails on the path that needed the
   capability. `staging` refuses too, because staging exists to fail the way production fails —
@@ -163,11 +190,49 @@
   data reaches `Subject`, and a break there injects headers. Refuse it, never strip it.
 - Every ENVELOPE address is checked the same way and separately (`X_MAIL_ADDRESS_INVALID`,
   `envelope-address.ts`, called by `smtpDeliver`). Two wire formats, one gate each: `bcc` is not a
-  header, so the header gate never sees it, and on the inline send path no schema does either — a
-  `bcc` of `ops@x.test\r\nRCPT TO:<evil@y.test>` relayed mail over the app's own authenticated
-  connection. The refused set is control characters plus `<` and `>`; a space is deliberately
-  allowed (quoted local-parts). Non-ASCII in the MAILBOX is refused too, and by this package:
-  SMTPUTF8 (RFC 6531) is what makes a UTF-8 addr-spec legal and `smtp-client.ts` negotiates none.
+  header, so the header gate never sees it, and on the inline send path no schema did either until
+  `renderMessage` took `addressRefusal` (2026-10-02) — a `bcc` of
+  `ops@x.test\r\nRCPT TO:<evil@y.test>` relayed mail over the app's own authenticated connection.
+  The refused set is control characters plus `<` and `>`; a space is deliberately allowed (quoted
+  local-parts). Non-ASCII in the MAILBOX is refused too, and by this package: SMTPUTF8 (RFC 6531)
+  is what makes a UTF-8 addr-spec legal and `smtp-client.ts` negotiates none.
+
+- **SES maps the error TYPE, not the status** (`As of 2026-10-06`, `ses-failure.ts`). `MessageRejected`,
+  `SendingPausedException` and a bad request are all 400: only throttling (`TooManyRequestsException`,
+  `ThrottlingException`, `Throttling`, `LimitExceededException`) is retryable; rejected, paused /
+  suspended, unverified MAIL FROM, every auth failure and a missing configuration set are terminal.
+  An unknown type falls back to core's `isRetryableStatus`. All of it is `X_MAIL_SEND_FAILED`
+  (`driver: 'ses'`) — no SES-specific code. SES has NO idempotency header and rewrites
+  `Message-ID`, so a retry after a timeout SES had accepted is a second email: SMTP's gap, pinned
+  as such. `Destination` is always sent, because `Bcc` is never a header.
+- **`retainMime` is the bytes this process handed the provider, never a truncation** (`As of
+  2026-10-06`). SMTP and SES only — Resend builds MIME on its side, so `selectMailDriver(env,
+  { retainMime })` REFUSES it for Resend rather than keeping nothing. Default cap 256 KiB, ceiling
+  10 MiB; over the cap `kind: 'digest-only'` keeps sha256 + length and drops the bytes. It rides on
+  `SendResult.mime` (the inline caller) AND goes to `onRetained` (the durable half: a queued send's
+  result is the job's return value, which the queue does not persist). A throwing sink is logged,
+  never a send failure — the mail already left, and failing would have the job send it again.
+- **The receivers live behind `@ultimat3/mail/events` (`src/events.ts`), never `src/index.ts`**
+  (`As of 2026-10-06`). Every serving role evaluates the barrel through serve-graph, and only a
+  webhook route needs SNS/Svix verification; the barrel keeps the `DeliveryEvent` types, type-only.
+- **A delivery notification is verified BEFORE it is parsed, and every refusal is coded.**
+  `X_MAIL_EVENT_UNVERIFIED` (401, `meta.reason`), `X_MAIL_EVENT_INVALID` (400, `meta.problem`),
+  `X_MAIL_EVENT_PROVIDER_UNREACHABLE` (503, so SNS redelivers). SNS order: envelope shape → topic
+  in `topicArns` (any AWS account can make SNS sign for ITS topic, so the allow-list is the
+  authentication, and it runs before any fetch) → cert URL exactly `https://sns.<topic region>.amazonaws.com/…pem`
+  → `SignatureVersion` 1 (SHA-1) or 2 (SHA-256) → signature → the clock. Svix: headers → mac
+  (`timingSafeEqual`, every `v1,` entry, no early exit) → window. "stale" therefore always means
+  authentic. A SubscriptionConfirmation's URL is returned and fetched only with
+  `confirmSubscriptions: true`, pinned the same way, never following a redirect.
+- **A pinned certificate URL is reached BEFORE any signature, so its download is bounded**
+  (`As of 2026-10-06`, `sns-certificate-cache.ts`). An allowed topic ARN is no secret, so a forger
+  can name a fresh `SimpleNotificationService-<32 hex>.pem` per request (the only path accepted,
+  as AWS publishes it). LRU of 8 verified certificates (a hit refreshes, so the one in use is never
+  evicted by a flood); a failed URL is answered from memory for 5 min; at most 2 downloads in
+  flight, beyond that `X_MAIL_EVENT_PROVIDER_UNREACHABLE` (503); identical lookups share one promise.
+- The SNS test key and its X.509 certificate are generated per run (`delivery-event-fixture.ts`);
+  no private key is committed. The DER was checked once against openssl (`openssl verify`, and
+  `openssl x509 -pubkey` gave the SPKI `x509-spki.ts` extracts).
 
 ## Commands
 

package/README.md

@@ -20,8 +20,10 @@ export const receiptMail = defineMail({
 await send(receiptMail, { name: user.name, url }, { to: user.email, locale: ctx.locale });
 ```
 
-`send` validates `data` through the mail's schema, renders, then enqueues `mail.send`. It
-delivers inline only when `{ sync: true }` is passed or no job driver is configured.
+`send` validates `data` through the mail's schema, renders, then enqueues `mail.send` through the
+jobs facade — inside a transaction the job is STAGED on it, so a handler that rolls back after
+sending mails nobody. It delivers inline only when `{ sync: true }` is passed or no job driver is
+configured.
 
 ### The outbound transform
 
@@ -58,6 +60,8 @@ setMailTransform(async (rendered, meta) =>
 | Every colour is a token | `MAIL_TOKENS` in `layout.ts` holds light + dark hexes; templates never see a hex |
 | Every date takes an IANA zone | `options.tz`, else `ctx.tz`, else `UTC` |
 | No CR/LF in a header-bound field | checked in `renderMessage` and again in `sendMailJob`, so every driver refuses the same message (`X_MAIL_HEADER_INVALID`). `mime.ts` keeps its own gate for the headers the SMTP transport mints itself |
+| One recipient rule on both paths | `to`, `cc`, `bcc` and `replyTo` are checked in `renderMessage` by the rule the SMTP envelope applies (`addressRefusal`), and the queue schema asks the same — so a display-form `Jane Doe <jane@x.test>` is accepted everywhere, and a control character or a non-ASCII mailbox is `X_MAIL_ADDRESS_INVALID` at the `send()` call site on every driver, never `queued: true` and then a worker's parse failure. `unsubscribeUrl` is `t.url` on both paths for the same reason |
+| Address headers carry 7-bit phrases | `From`, `To`, `Cc` and `Reply-To` encode a non-ASCII display name as an RFC 2047 word and quote an ASCII one holding a special (`Doe, Jane` → `"Doe, Jane"`), so the comma cannot split the list. `List-Unsubscribe` carries the url as the WHATWG serialiser writes it — punycode host, percent-encoded path and query |
 | `unsubscribeUrl` is one-click, and one-click is the supported path | it emits `List-Unsubscribe: <url>` plus `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058), and the footer links the SAME url. Make that url one page that answers both: `GET` renders a confirm button and never unsubscribes (scanners prefetch), and `POST` — the mail client's one-click, or the button's own form — runs the action: `defineRoute({ render: 'ssr', …, post: 'unsubscribe' })` (`@ultimat3/render`) binds it, with the url's query (`?t=<token>`) merged into the input. `unsubscribeOneClick: false` drops the `-Post` line for a url that still cannot take a POST; it is the fallback, not the path |
 | Sending is a job | `retry: { attempts: 5, backoff: 'exponential' }`, idempotency key `mail:<mailId>:<hash(recipients + rendered)>` — 128 bits, ASCII, under Resend's 256-character limit at any recipient count — or `(mailId, your key)` when you pass one (digested if it is not a short ASCII token) — a caller's key is scoped to its mail so two templates cannot dedupe each other away |
 
@@ -68,11 +72,12 @@ setMailTransform(async (rendered, meta) =>
 
 | Driver | Use | Behaviour |
 |---|---|---|
-| `createMemoryDriver({ clock? })` | dev, tests | retains messages; `outbox()` / `lastTo()` feed the `/_x` mail panel, ordered by `SentMail.at` — pass a `frozenClock()` to choose it |
-| `createLogDriver()` | workers without credentials | one structured line per message through core's `logger`; bodies never logged |
-| `createUnconfiguredDriver(env)` | a deploy that configured no transport | refuses every send with `X_MAIL_CREDENTIAL_MISSING`; delivers nothing and claims nothing |
-| `createSmtpDriver({ url, from })` | prod | real ESMTP over `Bun.connect`: STARTTLS, `AUTH PLAIN`/`LOGIN`, quoted-printable MIME |
-| `createResendDriver({ apiKey, from })` | prod | one `POST /emails`, `Idempotency-Key` on every request |
+| `memoryMailDriver({ clock? })` | dev, tests | retains messages; `outbox()` / `lastTo()` feed the `/_x` mail panel, ordered by `SentMail.at` — pass a `frozenClock()` to choose it |
+| `logMailDriver()` | workers without credentials | one structured line per message through core's `logger`; bodies never logged |
+| `unconfiguredMailDriver(env)` | a deploy that configured no transport | refuses every send with `X_MAIL_CREDENTIAL_MISSING`; delivers nothing and claims nothing |
+| `smtpMailDriver({ url, from })` | prod | real ESMTP over `Bun.connect`: STARTTLS, `AUTH PLAIN`/`LOGIN`, quoted-printable MIME |
+| `resendMailDriver({ apiKey, from })` | prod | one `POST /emails`, `Idempotency-Key` on every request |
+| `sesMailDriver({ region, credentials, from })` | prod | one SES v2 `SendEmail` with the raw MIME, SigV4-signed, no SDK |
 
 ### Which one a boot installs
 
@@ -81,10 +86,11 @@ the app changes between environments; the credential does.
 
 | env | driver |
 |---|---|
-| *(nothing set)*, `development` / `test` | `createMemoryDriver()` — caught, never sent |
-| *(nothing set)*, `staging` / `production` | `createUnconfiguredDriver(...)` — every send is `X_MAIL_CREDENTIAL_MISSING` |
-| `SMTP_URL` + `MAIL_FROM` | `createSmtpDriver(...)`, `MAIL_POOL_SIZE` optional |
-| `RESEND_API_KEY` + `MAIL_FROM` | `createResendDriver(...)` |
+| *(nothing set)*, `development` / `test` | `memoryMailDriver()` — caught, never sent |
+| *(nothing set)*, `staging` / `production` | `unconfiguredMailDriver(...)` — every send is `X_MAIL_CREDENTIAL_MISSING` |
+| `SMTP_URL` + `MAIL_FROM` | `smtpMailDriver(...)`, `MAIL_POOL_SIZE` optional |
+| `RESEND_API_KEY` + `MAIL_FROM` | `resendMailDriver(...)` |
+| `SES_REGION` + `SES_ACCESS_KEY_ID` + `SES_SECRET_ACCESS_KEY` + `MAIL_FROM` | `sesMailDriver(...)`; `SES_SESSION_TOKEN`, `SES_ENDPOINT`, `SES_CONFIGURATION_SET` optional |
 
 **No credential outside development is a refusal, not the embedded default.** The memory driver
 there answered `accepted` for mail that never left the process — password resets, receipts and
@@ -121,6 +127,68 @@ mailIdempotencyKey(message)` — a job retry after a timeout hands Resend the id
 that header is what makes it one email. 408/409/425/429 and 5xx are retryable (`isRetryableStatus`, `@ultimat3/core`); every other non-2xx
 is a configuration problem that retrying cannot fix.
 
+### SES
+
+`POST https://email.<region>.amazonaws.com/v2/email/outbound-emails` with `Content.Raw` — the
+MIME `mime.ts` builds — and the envelope in `Destination` (`Bcc` included, never a header).
+
+| SES says | `error.retry` |
+|---|---|
+| `TooManyRequestsException`, `ThrottlingException`, `LimitExceededException` | `retryable` |
+| `MessageRejected`, `SendingPausedException`, `AccountSuspendedException`, `MailFromDomainNotVerifiedException`, any auth failure, `NotFoundException` | `terminal` |
+| anything else | core's `isRetryableStatus(status)` |
+
+All `X_MAIL_SEND_FAILED`, each with its own `aws sesv2 …` fix. SES has no idempotency header: a
+retry after a timeout SES had already accepted is a second email, as over SMTP.
+
+### `retainMime`
+
+```ts
+import { sesMailDriver } from '@ultimat3/mail';
+
+declare const env: Record<string, string>;
+declare function saveAuditRow(row: unknown): Promise<void>;
+
+export const driver = sesMailDriver({
+  region: 'eu-west-1',
+  credentials: { accessKeyId: env['SES_ACCESS_KEY_ID'] ?? '', secretAccessKey: env['SES_SECRET_ACCESS_KEY'] ?? '' },
+  from: 'Postly <no-reply@postly.test>',
+  retainMime: { maxBytes: 262_144, onRetained: (entry) => saveAuditRow(entry) },
+});
+```
+
+SMTP and SES (the transports that build the MIME). The exact bytes handed to the provider, on
+`SendResult.mime` and to `onRetained` — the durable half, because a queued send's result is not
+persisted. Cap: default 256 KiB, at most 10 MiB; **over it only `{ kind: 'digest-only', sha256,
+byteLength }` is kept, never a truncated message.** A throwing `onRetained` is logged
+(`mail.retain_mime.failed`) and does not fail the send. `selectMailDriver(env, { retainMime })`
+refuses it for Resend, which builds the MIME on its own side, and judges the cap BEFORE it picks a
+transport — a cap over the ceiling is `X_CONFIG_INVALID` on every branch, memory included.
+`retainMimeKey` names where the option was written in that refusal (`mail.retainMime` from an
+`app.config.ts`); default `retainMime`.
+
+### Delivery events
+
+Imported from **`@ultimat3/mail/events`**, never the barrel: only a webhook route needs them, and every serving role loads `@ultimat3/mail` to send. One receiver per provider, its `receive(request)` mounted as a plain HTTP route through the `routes` runtime override (`apps/<app>/runtime.ts`) — not an `api/**/route.ts`, which cannot register (Known gaps, awaiting owner decision 1); each verifies, then normalises to
+`DeliveryEvent` — `delivered` · `bounced` (`bounce: 'hard' | 'soft'`) · `complained` · `delayed`,
+with `messageId` (= the sending driver's `SendResult.id`), `recipient`, `at`, `eventId` and `raw`.
+One event per recipient; `(eventId, recipient)` is the dedupe key.
+
+```ts
+import { resendEventReceiver, sesEventReceiver } from '@ultimat3/mail/events';
+
+declare const env: Record<string, string>;
+
+export const ses = sesEventReceiver({ topicArns: [env['SES_EVENTS_TOPIC_ARN'] ?? ''] });
+export const resend = resendEventReceiver({ secret: env['RESEND_WEBHOOK_SECRET'] ?? '' });
+// const outcome = await ses.receive(request);  // { type: 'events' | 'ignored' | 'subscription', … }
+```
+
+| Receiver | Proves |
+|---|---|
+| `sesEventReceiver` | SNS: the topic is in `topicArns`, the cert URL is `https://sns.<topic region>.amazonaws.com/…pem`, `SignatureVersion` 1 (RSA-SHA1) or 2 (RSA-SHA256) over AWS's canonical string, `Timestamp` within `toleranceMs` (1 h). A `SubscriptionConfirmation` returns its `confirmUrl`; it is fetched only with `confirmSubscriptions: true` |
+| `resendEventReceiver` | Svix: HMAC-SHA256 over `svix-id.svix-timestamp.body` under the `whsec_` secret, constant-time, any `v1,` entry, within `toleranceMs` (5 min) |
+
 ## Framework mails
 
 Registered by importing them — the import IS the registration. `FRAMEWORK_MAILS` is the list, and
@@ -146,11 +214,14 @@ Translating them = shipping `mail.*` keys in an app catalog. Never edit a templa
 | `X_MAIL_TEMPLATE_UNKNOWN` | export a `defineMail({ id })` and import it (also raised for an unregistered layout) |
 | `X_MAIL_DUPLICATE` | rename one of two `defineMail({ id })` declarations |
 | `X_MAIL_TEXT_MISSING` | add a text-bearing block to the template |
-| `X_MAIL_DRIVER_UNAVAILABLE` | `setMailDriver(createMemoryDriver())` at boot — a wiring bug |
+| `X_MAIL_DRIVER_UNAVAILABLE` | `setMailDriver(memoryMailDriver())` at boot — a wiring bug |
 | `X_MAIL_CREDENTIAL_MISSING` | set `SMTP_URL` (or `RESEND_API_KEY`) and `MAIL_FROM` in the deployment — an operations one |
 | `X_MAIL_HEADER_INVALID` | strip CR/LF from the interpolated value before it reaches a header |
-| `X_MAIL_ADDRESS_INVALID` | pass a bare `addr-spec` — an envelope address may hold no control character and no `<`/`>` |
+| `X_MAIL_ADDRESS_INVALID` | a recipient may hold no control character, its mailbox no `<`/`>` and no non-ASCII byte (`meta.reason`); `Jane Doe <jane@x.test>` is fine |
 | `X_MAIL_TRANSFORM_FAILED` | the `setMailTransform` hook threw or returned no `{ subject, html, text }` — fix the hook; the mail was not sent |
+| `X_MAIL_EVENT_UNVERIFIED` | a delivery notification failed its signature check — `meta.reason` names which (`unsigned`, `signature`, `stale`, `topic`, `certificate-url`, `signature-version`); answer 401 |
+| `X_MAIL_EVENT_INVALID` | authentic or not, the body is not the provider's notification shape (`meta.problem`); answer 400 |
+| `X_MAIL_EVENT_PROVIDER_UNREACHABLE` | the SNS certificate or confirm URL did not answer; answer 503 so SNS redelivers |
 | `X_MAIL_SEND_FAILED` | the `cause` names the stage, the provider's status and whether a retry can help — and so does `error.retry`, which is what `sendMailJob` acts on: `terminal` dead-letters a 550 or a rejected credential at attempt 1 instead of sending it four more times |
 
 ### Error classes
@@ -160,7 +231,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
-| `MailError` | any `MailErrorCode` — `MAIL_ERROR_CODES` | `src/errors.ts` |
+| `MailError` | any `MailErrorCode` — `MAIL_ERROR_CODES` | `src/errors.ts` (the `X_MAIL_EVENT_*` factories export from `@ultimat3/mail/events`) |
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mail",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Transactional email as data: one template renders HTML and text, sent through a job.",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./events": "./src/events.ts"
   },
   "files": [
     "src",
@@ -25,17 +26,17 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/i18n": "23.0.0",
-    "@ultimat3/jobs": "23.0.0",
-    "@ultimat3/schema": "23.0.0",
-    "@ultimat3/time": "23.0.0"
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/i18n": "25.0.0",
+    "@ultimat3/jobs": "25.0.0",
+    "@ultimat3/schema": "25.0.0",
+    "@ultimat3/time": "25.0.0"
   }
 }

package/src/catalog.ts

@@ -3,14 +3,8 @@
 // are registered after this one and therefore win). Translating a framework mail means
 // shipping `mail.*` in an app catalog — never editing a template.
 
-import {
-  type Catalog,
-  DEFAULT_LOCALE,
-  type Locale,
-  loadCatalog,
-  type NestedCatalog,
-  registerBaseCatalog,
-} from '@ultimat3/i18n';
+import { DEFAULT_LOCALE } from '@ultimat3/core';
+import { type Catalog, loadCatalog, type NestedCatalog, registerBaseCatalog } from '@ultimat3/i18n';
 
 export const MAIL_CATALOG_SOURCE: NestedCatalog = {
   mail: {
@@ -82,9 +76,6 @@ export const MAIL_CATALOG_SOURCE: NestedCatalog = {
 
 export const MAIL_CATALOG: Catalog = loadCatalog(MAIL_CATALOG_SOURCE);
 
-/** The one locale these strings are written in. */
-export const MAIL_CATALOG_LOCALE: Locale = DEFAULT_LOCALE;
-
 // At module scope, and that is the whole point: importing `@ultimat3/mail` is what installs these
 // strings, so no app and no boot can forget them. `registerMailCatalog()` was the alternative and
 // it had **zero** production callers — only this package's own tests — so every `mail.*` string in
@@ -99,4 +90,4 @@ export const MAIL_CATALOG_LOCALE: Locale = DEFAULT_LOCALE;
 // Under the ONE locale these strings are written in. Seating English under `es` made `isMiss` read
 // FALSE for a subject nobody had translated — a fallback locale chain wearing registration as a
 // disguise. A non-`en` app translates the `mail.*` keys it renders into its own catalog.
-registerBaseCatalog(MAIL_CATALOG_LOCALE, MAIL_CATALOG);
+registerBaseCatalog(DEFAULT_LOCALE, MAIL_CATALOG);

package/src/delivery-event-errors.ts

@@ -0,0 +1,148 @@
+// Single responsibility: the refusals a delivery-notification receiver answers with. Three codes,
+// one per audience: an unauthenticated sender (401), a signed payload this package cannot read
+// (400), and a provider endpoint the check itself needed that did not answer (503, so SNS retries).
+// No cause or fix here ever carries a signature, a secret, a body or a sender-chosen value.
+
+import { MailError } from './errors';
+
+export type DeliveryProvider = 'ses' | 'resend';
+
+/**
+ * Why a notification was refused as unauthenticated. One code and a `meta.reason`, like
+ * `X_MAIL_HEADER_INVALID`: the receiver's answer is the same 401 for each, and the operator reads
+ * the reason to learn whether to fix a secret, a topic list or a clock.
+ */
+export type DeliveryRefusal =
+  | 'unsigned'
+  | 'signature'
+  | 'stale'
+  | 'topic'
+  | 'certificate-url'
+  | 'signature-version';
+
+const CAUSES: Readonly<Record<DeliveryRefusal, string>> = {
+  unsigned: 'carries no signature, so nothing proves who sent it',
+  signature: 'carries a signature that does not verify over the bytes that arrived',
+  stale:
+    'is signed correctly and its timestamp is outside the tolerance window — a replay or a skewed clock',
+  topic:
+    'names an SNS topic this receiver was not configured with — any AWS account can sign for its own topic',
+  'certificate-url':
+    'names a signing certificate that is not https://sns.<region>.amazonaws.com for its topic’s region',
+  'signature-version': 'declares a SignatureVersion other than 1 or 2',
+};
+
+/** The three refusals a Svix-signed sender can earn; the other three are SNS envelope rules. */
+export type ResendRefusal = 'unsigned' | 'signature' | 'stale';
+
+const RESEND_FIXES: ReadonlyMap<DeliveryRefusal, string> = new Map<DeliveryRefusal, string>([
+  [
+    'unsigned',
+    "curl -sS https://api.resend.com/webhooks -H 'Authorization: Bearer <RESEND_API_KEY>' — point the Resend webhook at this route; Resend signs every delivery with svix-* headers",
+  ],
+  [
+    'signature',
+    "resendEventReceiver({ secret: env.RESEND_WEBHOOK_SECRET }) — with this endpoint's whsec_ signing secret from https://resend.com/webhooks",
+  ],
+  [
+    'stale',
+    'resendEventReceiver({ secret, toleranceMs: 600_000 }) — or sync this host clock: timedatectl set-ntp true',
+  ],
+]);
+
+const SES_FIXES: ReadonlyMap<DeliveryRefusal, string> = new Map<DeliveryRefusal, string>([
+  [
+    'unsigned',
+    'aws sns subscribe --protocol https --topic-arn <your topic arn> --notification-endpoint <this url> — SNS signs every message it sends',
+  ],
+  [
+    'signature',
+    'aws sns list-subscriptions-by-topic --topic-arn <your topic arn> — and let nothing between SNS and this route re-serialise the JSON body',
+  ],
+  [
+    'stale',
+    'sesEventReceiver({ topicArns, toleranceMs: 7_200_000 }) — or sync this host clock: timedatectl set-ntp true',
+  ],
+  [
+    'topic',
+    'aws sns list-topics — then, only if the topic is yours, sesEventReceiver({ topicArns: [<your topic arn>] })',
+  ],
+  [
+    'certificate-url',
+    'aws sns list-topics — nothing to change if you did not send it: SNS signs only from https://sns.<region>.amazonaws.com',
+  ],
+  [
+    'signature-version',
+    'aws sns set-topic-attributes --topic-arn <your topic arn> --attribute-name SignatureVersion --attribute-value 2',
+  ],
+]);
+
+export function deliveryEventUnverified(provider: 'resend', reason: ResendRefusal): MailError;
+export function deliveryEventUnverified(provider: 'ses', reason: DeliveryRefusal): MailError;
+export function deliveryEventUnverified(
+  provider: DeliveryProvider,
+  reason: DeliveryRefusal,
+): MailError {
+  // The overloads keep an SNS-only reason off a Resend refusal, so the fallback is never reached.
+  // Maps, never object lookups: `reason` is a closed union today, and a table that is not an
+  // object cannot answer `Object.prototype` for a key nobody declared.
+  const table = provider === 'resend' ? RESEND_FIXES : SES_FIXES;
+  const fix = table.get(reason) ?? 'aws sns list-topics — no fix is declared for this reason';
+  return new MailError({
+    code: 'X_MAIL_EVENT_UNVERIFIED',
+    cause: `a ${provider} delivery notification ${CAUSES[reason]}`,
+    fix,
+    meta: { provider, reason },
+  });
+}
+
+/** What could not be read. A closed vocabulary, so a cause never echoes the sender's bytes. */
+export type DeliveryShapeProblem =
+  | 'too-large'
+  | 'not-utf8'
+  | 'not-json'
+  | 'envelope'
+  | 'notification'
+  | 'timestamp';
+
+const SHAPE_CAUSES: Readonly<Record<DeliveryShapeProblem, string>> = {
+  'too-large': 'is larger than the receiver’s maxBytes',
+  'not-utf8': 'is not UTF-8 text',
+  'not-json': 'is not JSON',
+  envelope: 'is missing a field its envelope requires',
+  notification: 'is missing a field its event type requires',
+  timestamp: 'carries a timestamp that is not an ISO-8601 instant',
+};
+
+export const deliveryEventInvalid = (
+  provider: DeliveryProvider,
+  problem: DeliveryShapeProblem,
+): MailError =>
+  new MailError({
+    code: 'X_MAIL_EVENT_INVALID',
+    cause: `a ${provider} delivery notification ${SHAPE_CAUSES[problem]}`,
+    fix:
+      problem === 'too-large'
+        ? provider === 'ses'
+          ? 'sesEventReceiver({ topicArns, maxBytes: 2_097_152 }) — only if SNS really sends more'
+          : 'resendEventReceiver({ secret, maxBytes: 2_097_152 }) — only if Resend really sends more'
+        : provider === 'ses'
+          ? 'aws sns list-subscriptions-by-topic --topic-arn <your topic arn> — only SNS should be posting to this route'
+          : "curl -sS https://api.resend.com/webhooks -H 'Authorization: Bearer <RESEND_API_KEY>' — only Resend should be posting to this route",
+    meta: { provider, problem },
+  });
+
+/** The SNS signing certificate (or a subscription confirm) did not answer — transient, so 503. */
+export const deliveryProviderUnreachable = (
+  what: 'certificate' | 'subscription',
+  detail: string,
+): MailError =>
+  new MailError({
+    code: 'X_MAIL_EVENT_PROVIDER_UNREACHABLE',
+    cause: `the SNS ${what === 'certificate' ? 'signing certificate' : 'subscription confirmation'} request failed: ${detail}`,
+    fix:
+      what === 'certificate'
+        ? 'curl -sS -m 5 -o /dev/null https://sns.us-east-1.amazonaws.com/ — checks egress; SNS redelivers a message this route answered 5xx'
+        : 'aws sns confirm-subscription --topic-arn <your topic arn> --token <the Token from the confirmation>',
+    meta: { provider: 'ses', what },
+  });

package/src/delivery-event-ses.ts

@@ -0,0 +1,101 @@
+// Single responsibility: an Amazon SES notification — the JSON inside a VERIFIED SNS message —
+// becomes `DeliveryEvent`s. Both SES spellings are read: identity notifications
+// (`notificationType`) and configuration-set event publishing (`eventType`). Verification and the
+// HTTP side are `ses-event-receiver.ts`; this file trusts its input and only translates it.
+
+import { t, validate } from '@ultimat3/schema';
+import {
+  type DeliveryEvent,
+  type DeliveryOutcome,
+  deliveryInstant,
+  parseDeliveryJson,
+} from './delivery-event';
+import { deliveryEventInvalid } from './delivery-event-errors';
+
+const recipient = t.object({ emailAddress: t.string });
+
+/** Per event type: the sub-object SES nests it in, its recipient list, and the kind it becomes. */
+const SES_TYPES = {
+  Bounce: t.object({
+    bounce: t.object({
+      bounceType: t.string,
+      bouncedRecipients: t.array(recipient),
+      timestamp: t.string,
+    }),
+  }),
+  Complaint: t.object({
+    complaint: t.object({ complainedRecipients: t.array(recipient), timestamp: t.string }),
+  }),
+  Delivery: t.object({
+    delivery: t.object({ recipients: t.array(t.string), timestamp: t.string }),
+  }),
+  DeliveryDelay: t.object({
+    deliveryDelay: t.object({ delayedRecipients: t.array(recipient), timestamp: t.string }),
+  }),
+} as const;
+
+const notificationHead = t.object({
+  notificationType: t.string.optional(),
+  eventType: t.string.optional(),
+  mail: t.object({ messageId: t.string }).optional(),
+});
+
+type Row = { readonly recipient: string; readonly at: string };
+
+/** SES's notification JSON (the SNS `Message`) → events; a type this does not model is ignored. */
+export function sesDeliveryEvents(message: string, eventId: string): DeliveryOutcome {
+  const raw = parseDeliveryJson('ses', message);
+  const head = validate(notificationHead, raw);
+  if (head.issues !== undefined) throw deliveryEventInvalid('ses', 'notification');
+  const eventType = head.value.notificationType ?? head.value.eventType ?? '';
+  const messageId = head.value.mail?.messageId;
+  const base = (row: Row) => ({
+    provider: 'ses' as const,
+    messageId: messageId ?? '',
+    recipient: row.recipient,
+    at: deliveryInstant('ses', row.at),
+    eventId,
+    raw,
+  });
+  const read = <S extends (typeof SES_TYPES)[keyof typeof SES_TYPES]>(schema: S) => {
+    const parsed = validate(schema, raw);
+    if (parsed.issues !== undefined || messageId === undefined) {
+      throw deliveryEventInvalid('ses', 'notification');
+    }
+    return parsed.value;
+  };
+
+  let events: DeliveryEvent[];
+  if (eventType === 'Bounce') {
+    const { bounce } = read(SES_TYPES.Bounce);
+    // `Undetermined` is soft: suppressing an address on a verdict SES itself could not reach
+    // loses a real recipient, and a hard bounce, if it is one, arrives as `Permanent` next time.
+    const kind = bounce.bounceType === 'Permanent' ? 'hard' : 'soft';
+    events = bounce.bouncedRecipients.map((r) => ({
+      ...base({ recipient: r.emailAddress, at: bounce.timestamp }),
+      kind: 'bounced',
+      bounce: kind,
+    }));
+  } else if (eventType === 'Complaint') {
+    const { complaint } = read(SES_TYPES.Complaint);
+    events = complaint.complainedRecipients.map((r) => ({
+      ...base({ recipient: r.emailAddress, at: complaint.timestamp }),
+      kind: 'complained',
+    }));
+  } else if (eventType === 'Delivery') {
+    const { delivery } = read(SES_TYPES.Delivery);
+    events = delivery.recipients.map((address) => ({
+      ...base({ recipient: address, at: delivery.timestamp }),
+      kind: 'delivered',
+    }));
+  } else if (eventType === 'DeliveryDelay') {
+    const { deliveryDelay } = read(SES_TYPES.DeliveryDelay);
+    events = deliveryDelay.delayedRecipients.map((r) => ({
+      ...base({ recipient: r.emailAddress, at: deliveryDelay.timestamp }),
+      kind: 'delayed',
+    }));
+  } else {
+    return { type: 'ignored', eventType: eventType === '' ? 'unknown' : eventType };
+  }
+  return { type: 'events', events };
+}