@ultimat3/mail 1.2.0 → 3.0.0

package/CLAUDE.md

@@ -0,0 +1,107 @@
+# @ultimat3/mail — agent notes
+
+**Tier 4** (`scripts/lib/tiers.ts`). May import `core`, `schema`, `i18n`, `time`, `money`, `jobs`; never `auth`, `http`, `ui`, `render`. **Zero external deps** — no nodemailer, no MJML, no CSS library.
+
+## Boundary
+
+| File | Single responsibility |
+|---|---|
+| `mail.ts` | `defineMail`, the registry, `send` / `sendById` / `renderMessage` |
+| `templates/` | the six framework mails, as data |
+| `blocks.ts` | the template vocabulary: `MailBlock`, `blocks`, `MailTemplate`, `TemplateArgs` |
+| `render.ts` | blocks → HTML **and** text, plus the layout call and the footer slots |
+| `layout.ts` | `MAIL_TOKENS` (light + dark), the 600px table shell, layout registry |
+| `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 |
+| `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` |
+| `mime.ts` | `MailMessage` → RFC 5322: header order, RFC 2047, folding, quoted-printable |
+| `base64.ts` | base64 over UTF-8 bytes, shared by RFC 2047 and SMTP AUTH |
+| `job.ts` | `sendMailJob` and the envelope schema |
+| `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 |
+
+## Rules
+
+- `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.
+- `SendOptions.locale` is non-optional in the type. Never relax it, never default it.
+- Text part is derived from blocks and must be non-empty (`X_MAIL_TEXT_MISSING`).
+- No literal user-facing string in `templates/` or `layout.ts` — keys only.
+- No hex outside `MAIL_TOKENS`. Base styling is inlined (clients strip `<style>`); dark mode is
+  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`.
+- New block kind: `MailBlock` + `blocks` + `htmlOf` + `textOf`, same commit.
+- A transport failure is `sendFailed({ stage, status, retryable, fix })` — never a bare throw, and
+  never a `retryable` guess. `stage` is the `SendStage` union in `errors.ts`; a new step goes there
+  first. The transient set is 4xx over SMTP, and 408/409/425/429 + 5xx over HTTP — that HTTP set
+  lives in `RETRYABLE_STATUSES` (`driver-resend.ts`) and is edited there, never restated.
+- A transport is selected from the environment by `selectMailDriver`, never from an `app.config.ts`
+  field — nothing loads that file's contents at runtime, so a `mail:` config block would be a
+  setting no boot could read. Two credentials at once is refused, not resolved: mail leaving by
+  the wrong provider is not a failure anyone sees. The credential never reaches a printed string.
+- **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.
+  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 —
+  which is `isLocal()`'s own rule, read from **core** rather than restated here, so mail and storage
+  cannot disagree about which deploy this is. And it is its **own code**: `X_MAIL_DRIVER_UNAVAILABLE`
+  is a developer who never called `setMailDriver`, this is an operator who set no variable, and one
+  code for two audiences is a `fix:` that is wrong half the time.
+- **The CR/LF header rule is a property of the MESSAGE, checked at `renderMessage` and again in
+  `sendMailJob`** (`As of 2026-08`). `mime.ts` held the only copy, so a subject an SMTP deploy
+  refused was accepted by memory in dev and by Resend in staging — the same app, three answers.
+  `mime.ts` keeps its gate and is not redundant: it also covers `From`, `Date` and `Message-ID`,
+  which the transport mints and no message-level check can see. The job's copy exists because a
+  queue row is not necessarily one this process rendered, and `mailMessageSchema` proves a payload's
+  SHAPE only. A driver reached DIRECTLY through `mailDriver().send(handBuilt)` is off that path —
+  `assertHeaderSafe` is exported for a custom driver that wants the same gate.
+- **The SMTP `Message-ID` is content-derived, so every attempt of one send presents the same one**
+  (`As of 2026-08`). It was a fresh `nanoid` per attempt, and a send that times out after `DATA` is
+  classified retryable — so the retry was a second email to every mailbox that would otherwise have
+  collapsed it, while `SendResult.idempotencyKey` claimed one message on both transports. This
+  narrows the gap and cannot close it: SMTP has no idempotency protocol, so the header is an
+  opportunity for the receiving side and never a guarantee, where Resend's `Idempotency-Key` is
+  enforced by the provider. That asymmetry is a transport DIFFERENCE and is pinned as one.
+  `mailMessageIdToken` is a one-way digest of `mailIdempotencyKey`, never the key itself: the key
+  holds the recipient list, bcc included, and a `Message-ID` is visible to all of them.
+- **`driver-parity.test.ts` asserts every driver's behaviour in ONE test.** Both production drivers
+  run for real — SMTP over a fake `SmtpStream`, Resend over an injected `fetch` — so a case compares
+  what each did rather than a proxy for it, and neither side can move alone. The memory driver joins
+  the cases about the MESSAGE and none about a wire: it dials nothing, maps no status and carries no
+  idempotency header, and that is documented difference, not defect.
+- `Bcc` is an envelope field. It reaches `RCPT TO` and Resend's body, never a header.
+- Recipient addresses stay out of logs and out of error text we write ourselves; the server's own
+  reply is passed through verbatim, and that is where the refused address comes from.
+- Every header value is checked for CR/LF (`X_MAIL_HEADER_INVALID`) before folding — interpolated
+  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) and non-ASCII is SMTPUTF8's question, not this check's.
+
+## Commands
+
+```bash
+bun test packages/mail
+bun run --filter @ultimat3/mail typecheck
+```
+
+Gotchas:
+- The registry erases `I` (`AnyMailDefinition`); `sendById` holds the package's only cast.
+- No job driver configured ⇒ `send` delivers inline rather than dropping the message.
+- Tests must not call `resetMails()` — template registration is module-level and shared.
+- `driver-smtp.test.ts` runs a real `Bun.listen` SMTP server on loopback. The sealed test network
+  covers `fetch` only, so this is allowed — and it is the only proof the socket, the chunk queue
+  and the reply framing agree. Resend tests inject `options.fetch`; never unseal.

package/README.md

@@ -33,7 +33,8 @@ delivers inline only when `{ sync: true }` is passed or no job driver is configu
 | Every string is a key | `mail.<id>.<slot>`; English lives in `src/catalog.ts` and app catalogs override it |
 | 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` |
-| Sending is a job | `retry: { attempts: 5, backoff: 'exponential' }`, idempotency key derived from `(mailId, recipients, hash(rendered))` |
+| 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 |
+| Sending is a job | `retry: { attempts: 5, backoff: 'exponential' }`, idempotency key derived from `(mailId, recipients, hash(rendered))`, or `(mailId, your key)` when you pass one — a caller's key is scoped to its mail so two templates cannot dedupe each other away |
 
 ## Drivers
 
@@ -44,21 +45,29 @@ delivers inline only when `{ sync: true }` is passed or no job driver is configu
 |---|---|---|
 | `createMemoryDriver()` | dev, tests | retains messages; `outbox()` / `lastTo()` feed the `/_x` mail panel |
 | `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 |
 
 ### Which one a boot installs
 
-`selectMailDriver(env)` is the one answer, and `x dev` calls it — an unset variable means the
-embedded default, the same law the database, event bus and storage bindings follow. Nothing about
+`selectMailDriver(env)` is the one answer, and `x dev` and `runRole` both call it. Nothing about
 the app changes between environments; the credential does.
 
 | env | driver |
 |---|---|
-| *(nothing set)* | `createMemoryDriver()` — caught, never sent |
+| *(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(...)` |
 
+**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
+invitations all reported as sent, none delivered, no error anywhere. The refusal lands on the
+**send**, not on the boot, so an app that sends no mail still deploys. Which environment this is
+comes from core's `isLocal()` (`ULTIMATE_ENV`, else `NODE_ENV`, else `development`) — mail does not
+own a second reading of it.
+
 Both credentials at once is `X_CONFIG_INVALID` rather than a winner picked for you, and a
 transport with no `MAIL_FROM` is refused at boot instead of on the first send. A host that is not
 `x dev` calls `selectMailDriver` itself, or constructs a driver directly — `setMailDriver` is the
@@ -76,7 +85,9 @@ with STARTTLS. Credentials are percent-decoded, so a password with `@` or `/` wo
 | Any rejected recipient fails the send | delivering to three of four addresses and reporting success is the one outcome a caller cannot detect |
 | `poolSize` (default 4) caps concurrent connections | a burst of sends queues instead of opening one socket each |
 | `Bcc` never reaches a header | it travels in `RCPT TO` only |
-| The reported `id` is the `Message-ID` | an SMTP `250` carries nothing a caller could correlate. It is not derived from the idempotency key, which holds the recipient list |
+| Every envelope address is gated for CR/LF | `MAIL FROM`/`RCPT TO` are built by interpolation, and `bcc` is the one address no header check ever sees. Refused (`X_MAIL_ADDRESS_INVALID`), never stripped — a rewritten address delivers somewhere else |
+| The reported `id` is the `Message-ID` | an SMTP `250` carries nothing a caller could correlate |
+| The `Message-ID` is stable per message | SMTP has no idempotency protocol, so it is the one identifier a receiving mailbox can collapse a retry on. A fresh token per attempt made a timeout past `DATA` a second email. It is a one-way **digest** of `mailIdempotencyKey`, never the key: the key holds the recipient list, and this header is visible to all of them |
 
 ### Resend
 
@@ -87,7 +98,9 @@ is a configuration problem that retrying cannot fix.
 
 ## Framework mails
 
-Registered by importing them. `FRAMEWORK_MAILS` is the list `x mail list` prints.
+Registered by importing them — the import IS the registration. `FRAMEWORK_MAILS` is the list, and
+`registeredMails()` / `registeredMailIds()` answer for an app's own mails as well. There is no
+`x mail` command; a host that wants to list or preview a mail calls those and `renderMessage()`.
 
 | id | Input |
 |---|---|
@@ -108,8 +121,10 @@ 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 |
+| `X_MAIL_DRIVER_UNAVAILABLE` | `setMailDriver(createMemoryDriver())` 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_SEND_FAILED` | the `cause` names the stage, the provider's status and whether a retry can help |
 
 ## Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mail",
-  "version": "1.2.0",
+  "version": "3.0.0",
   "description": "Transactional email as data: one template renders HTML and text, sent through a job.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/i18n": "1.2.0",
-    "@ultimat3/jobs": "1.2.0",
-    "@ultimat3/schema": "1.2.0",
-    "@ultimat3/time": "1.2.0"
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/i18n": "3.0.0",
+    "@ultimat3/jobs": "3.0.0",
+    "@ultimat3/schema": "3.0.0",
+    "@ultimat3/time": "3.0.0"
   }
 }

package/src/driver-env.ts

@@ -4,12 +4,16 @@
 // this is that something, and it is keyed on env rather than a config field so the same image
 // deploys to every environment.
 
-import { ConfigInvalidError } from '@ultimat3/core';
-import { createMemoryDriver, type MailDriver } from './driver';
+import { ConfigInvalidError, isLocal, resolveEnvironment } from '@ultimat3/core';
+import { createMemoryDriver, createUnconfiguredDriver, type MailDriver } from './driver';
 import { createResendDriver } from './driver-resend';
 import { createSmtpDriver } from './driver-smtp';
 
-/** The keys read here, and nothing else. Named once so docs and tests cannot drift from the code. */
+/**
+ * The MAIL keys read here, and nothing else. Named once so docs and tests cannot drift from the
+ * code. `ULTIMATE_ENV`/`NODE_ENV` are deliberately absent: which deploy this is belongs to core's
+ * one resolver, and restating it as a mail key would make it two settings with one meaning.
+ */
 export const MAIL_ENV_KEYS = ['SMTP_URL', 'RESEND_API_KEY', 'MAIL_FROM', 'MAIL_POOL_SIZE'] as const;
 
 export type MailEnvironment = Readonly<Record<string, string | undefined>>;
@@ -63,9 +67,17 @@ function poolSizeFrom(env: MailEnvironment): number | undefined {
 }
 
 /**
- * A credential selects its transport; no credential catches mail in memory. Two credentials is
- * the one case that cannot be answered by picking a winner — whichever this chose would be the
- * one an operator did not mean half the time, and mail would silently leave by the wrong path.
+ * A credential selects its transport. Two credentials is the one case that cannot be answered by
+ * picking a winner — whichever this chose would be the one an operator did not mean half the time,
+ * and mail would silently leave by the wrong path.
+ *
+ * NO credential is answered by the ENVIRONMENT, and it is the one decision here that is not about
+ * a credential. In development and test it is the memory driver: the `/_x` panel shows what a
+ * template renders in every locale and nothing escapes to a real address. Anywhere else it is a
+ * driver that refuses, because the memory driver in production reports `accepted` for mail that
+ * never left the process — every password reset, receipt and invitation "sent", none delivered,
+ * and no error anywhere to find it by. `isLocal` is core's one reader of that question, so mail
+ * cannot disagree with storage about which deploy this is.
  */
 export function selectMailDriver(env: MailEnvironment): MailSelection {
   const smtpUrl = nonEmpty(env['SMTP_URL']);
@@ -98,8 +110,16 @@ export function selectMailDriver(env: MailEnvironment): MailSelection {
     };
   }
 
+  if (isLocal({ env })) {
+    return {
+      driver: createMemoryDriver(),
+      detail: 'caught in memory — set SMTP_URL or RESEND_API_KEY to deliver',
+    };
+  }
+
+  const environment = resolveEnvironment({ env });
   return {
-    driver: createMemoryDriver(),
-    detail: 'caught in memory — set SMTP_URL or RESEND_API_KEY to deliver',
+    driver: createUnconfiguredDriver(environment),
+    detail: `no transport configured for ${environment} — set SMTP_URL or RESEND_API_KEY`,
   };
 }

package/src/driver-smtp.ts

@@ -12,6 +12,7 @@ import {
 import type { SendResult } from './driver';
 import { envelopeRecipients, type MailDriver, type MailMessage, resultFor } from './driver';
 import { sendFailed } from './errors';
+import { mailMessageIdToken } from './idempotency';
 import { addressDomain, addressSpec, buildMimeMessage } from './mime';
 import {
   type SmtpConnector,
@@ -159,10 +160,15 @@ export function createSmtpDriver(options: SmtpDriverOptions): MailDriver {
 
   async function deliver(message: MailMessage): Promise<SendResult> {
     // The Message-ID is the id the recipient's mailbox shows, so it is also the id we report: an
-    // SMTP `250` carries no identifier a caller could correlate with anything. It is deliberately
-    // NOT derived from the idempotency key — that key holds the recipient list, and a Message-ID
-    // is visible to every recipient, blind ones included.
-    const messageId = `<${message.mailId}.${nanoid(16)}@${addressDomain(options.from)}>`;
+    // SMTP `250` carries no identifier a caller could correlate with anything.
+    //
+    // It is CONTENT-DERIVED, so every attempt of one send presents the same one. A `nanoid` here
+    // made a retry after a timeout past `DATA` a second, unrelated email — the case
+    // `SendResult.idempotencyKey` claims is one message, and the case Resend's `Idempotency-Key`
+    // header has always covered. It is a one-way digest and not the key itself, which is what
+    // answers the objection the key raises: the key holds the recipient list, blind ones included,
+    // and this header is visible to all of them.
+    const messageId = `<${message.mailId}.${mailMessageIdToken(message)}@${addressDomain(options.from)}>`;
     const data = buildMimeMessage(message, {
       from: options.from,
       messageId,

package/src/driver.ts

@@ -4,8 +4,8 @@
 // `driver-resend.ts`; swapping one for the other is an `app.config.ts` line and zero template
 // changes.
 
-import { nanoid, logger as rootLogger } from '@ultimat3/core';
-import { driverUnavailable } from './errors';
+import { type Environment, nanoid, logger as rootLogger } from '@ultimat3/core';
+import { driverUnavailable, mailCredentialMissing } from './errors';
 import { mailIdempotencyKey } from './idempotency';
 
 /** The rendered envelope. Everything a transport needs; nothing it does not. */
@@ -131,6 +131,28 @@ export function isMemoryDriver(driver: MailDriver): driver is MemoryMailDriver {
   );
 }
 
+export const UNCONFIGURED_DRIVER_NAME = 'unconfigured';
+
+/**
+ * What a deployment outside development gets when it configured no transport. It is a driver and
+ * not a boot refusal so an app that sends no mail still deploys; it refuses on the send so an app
+ * that does sends nothing silently. The memory driver in that position answered `accepted` for
+ * every message — a password reset reported as delivered, with no error anywhere to find it by.
+ */
+export function createUnconfiguredDriver(environment: Environment): MailDriver {
+  return {
+    name: UNCONFIGURED_DRIVER_NAME,
+    // Rejected rather than thrown: `send()` and `sendMailJob` both await this, and a synchronous
+    // throw from a method typed as returning a promise escapes the caller's own error path.
+    send: (): Promise<SendResult> => Promise.reject(mailCredentialMissing(environment)),
+  };
+}
+
+/** Whether this process will refuse every send. A host prints a different boot line for it. */
+export function isUnconfiguredDriver(driver: MailDriver): boolean {
+  return driver.name === UNCONFIGURED_DRIVER_NAME;
+}
+
 /**
  * Structured log line per message through core's `logger` — the default for a worker that
  * has no credentials yet. Bodies are never logged; a mail body is user data.

package/src/envelope-address.ts

@@ -0,0 +1,29 @@
+// Single responsibility: what may appear inside an SMTP `MAIL FROM:<>` or `RCPT TO:<>`. One gate
+// for the envelope, exactly as `mime.ts`'s `header()` is the one gate for the message — two wire
+// formats, one check each, at the module that owns the format. Refuses; never rewrites.
+
+import { addressInvalid, type EnvelopeAddressField } from './errors';
+
+/**
+ * Every character that can restructure the command line: C0 controls (CR and LF above all), DEL,
+ * the C1 range, and the angle brackets that delimit the address — a `>` closes the bracket early
+ * and turns whatever follows into ESMTP parameters.
+ *
+ * A space is deliberately NOT refused: RFC 5321 allows one inside a quoted local-part, and with
+ * the brackets already refused it can only produce an address the server itself rejects, never a
+ * second command. Non-ASCII is not refused either — whether a server takes a UTF-8 mailbox is
+ * SMTPUTF8's question and the server's answer, not a decision this check may make on its behalf.
+ */
+function isUnsafe(address: string): boolean {
+  for (let index = 0; index < address.length; index += 1) {
+    const code = address.charCodeAt(index);
+    if (code < 0x20 || (code >= 0x7f && code <= 0x9f)) return true;
+    if (code === 0x3c || code === 0x3e) return true; // '<' and '>'
+  }
+  return false;
+}
+
+/** Throws `X_MAIL_ADDRESS_INVALID` before a single byte of the envelope is written. */
+export function assertEnvelopeAddress(field: EnvelopeAddressField, address: string): void {
+  if (isUnsafe(address)) throw addressInvalid(field);
+}

package/src/errors.ts

@@ -2,7 +2,7 @@
 // Mail fails in production, not in tests — a wrong locale, an empty text part or an
 // unconfigured driver must name the exact call site edit that repairs it.
 
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { type Environment, registerErrorCodes, UltimateError } from '@ultimat3/core';
 
 export const MAIL_ERROR_CODES = [
   'X_MAIL_LOCALE_MISSING',
@@ -10,7 +10,9 @@ export const MAIL_ERROR_CODES = [
   'X_MAIL_DUPLICATE',
   'X_MAIL_TEXT_MISSING',
   'X_MAIL_DRIVER_UNAVAILABLE',
+  'X_MAIL_CREDENTIAL_MISSING',
   'X_MAIL_HEADER_INVALID',
+  'X_MAIL_ADDRESS_INVALID',
   'X_MAIL_SEND_FAILED',
 ] as const;
 
@@ -22,7 +24,9 @@ export const MAIL_ERROR_TITLES: Readonly<Record<MailErrorCode, string>> = {
   X_MAIL_DUPLICATE: 'two mails claim the same id',
   X_MAIL_TEXT_MISSING: 'the rendered mail has no plain-text part',
   X_MAIL_DRIVER_UNAVAILABLE: 'no mail driver is configured',
+  X_MAIL_CREDENTIAL_MISSING: 'this deployment configured no mail transport',
   X_MAIL_HEADER_INVALID: 'a header value carries a line break',
+  X_MAIL_ADDRESS_INVALID: 'an envelope address could restructure the SMTP command line',
   X_MAIL_SEND_FAILED: 'the mail transport refused the message',
 };
 
@@ -66,7 +70,7 @@ export const templateUnknown = (mailId: string, known: readonly string[]): MailE
   new MailError({
     code: 'X_MAIL_TEMPLATE_UNKNOWN',
     cause: `no mail with id "${mailId}" is registered (have: ${known.join(', ') || 'none'})`,
-    fix: `x mail list --json   # then export defineMail({ id: '${mailId}', ... }) and import it`,
+    fix: `export defineMail({ id: '${mailId}', ... }) and import that module at boot — the import IS the registration`,
     meta: { mailId, known },
   });
 
@@ -86,7 +90,7 @@ export const mailDuplicate = (mailId: string): MailError =>
   new MailError({
     code: 'X_MAIL_DUPLICATE',
     cause: `mail id "${mailId}" is already registered by another defineMail() call`,
-    fix: `x mail list --json   # then rename one of the two defineMail({ id }) declarations`,
+    fix: `rename one of the two defineMail({ id: '${mailId}' }) declarations — an id is the key both surfaces address a template by`,
     meta: { mailId },
   });
 
@@ -106,6 +110,28 @@ export const driverUnavailable = (what: string): MailError =>
     meta: { what },
   });
 
+/**
+ * A DEPLOYMENT set neither credential, where `X_MAIL_DRIVER_UNAVAILABLE` is a WIRING bug — one is
+ * fixed by an operator setting a variable, the other by a developer calling `setMailDriver`, so
+ * they are two codes and not one cause string.
+ *
+ * Raised on the send rather than at boot, deliberately: a boot refusal turns a working deploy of an
+ * app that sends no mail into a failing one, while this lands on the exact path that needed the
+ * capability — the alternative being the memory driver reporting `accepted` for a password reset
+ * that never left the process.
+ */
+export const mailCredentialMissing = (environment: Environment): MailError =>
+  new MailError({
+    code: 'X_MAIL_CREDENTIAL_MISSING',
+    cause:
+      `neither SMTP_URL nor RESEND_API_KEY is set in ${environment}, so this process has no ` +
+      'transport — the message was not delivered and was not queued anywhere',
+    fix:
+      'set SMTP_URL="smtps://user:pass@host:465" (or RESEND_API_KEY=re_...) and ' +
+      'MAIL_FROM="App <no-reply@yourdomain.test>" in the deployment environment, then restart',
+    meta: { environment, missing: ['SMTP_URL', 'RESEND_API_KEY'] },
+  });
+
 /**
  * A CR or LF inside a header value ends the header early and lets whatever follows become new
  * headers — the recipient list, a forged `From`. Interpolated data reaches `Subject`, so this is
@@ -121,6 +147,37 @@ export const headerInvalid = (name: string, mailId: string): MailError =>
     meta: { header: name, mailId },
   });
 
+/**
+ * Which half of the SMTP envelope an address belongs to. A closed union, and it lives here rather
+ * than beside the check for the same reason `SendStage` does: the two halves come from two
+ * different places — a config line and a `send()` call — so each needs its own `fix`, and a typo
+ * has to be a compile error instead of a lookup that quietly misses.
+ */
+export type EnvelopeAddressField = 'sender' | 'recipient';
+
+const ADDRESS_FIXES: Readonly<Record<EnvelopeAddressField, string>> = {
+  sender: 'set mail.from in app.config.ts to a bare address, e.g. no-reply@example.test',
+  recipient: "pass bare addresses: send(mail, data, { to: ['ada@example.test'], locale })",
+};
+
+/**
+ * `MAIL FROM:<…>` and `RCPT TO:<…>` are built by interpolation, so a CR or LF in an address ends
+ * the command line and lets the rest of it run as SMTP commands of its own — arbitrary relay over
+ * the app's authenticated connection. Refused rather than stripped, like a header: a stripped
+ * address is a different address, so sanitising silently redirects the mail instead of stopping it.
+ * The value never appears here — an address is recipient data, which this package keeps out of
+ * every string it writes itself.
+ */
+export const addressInvalid = (field: EnvelopeAddressField): MailError =>
+  new MailError({
+    code: 'X_MAIL_ADDRESS_INVALID',
+    cause:
+      `the SMTP envelope ${field} address holds a control character or an angle bracket, ` +
+      'which would end the command line and inject SMTP commands',
+    fix: ADDRESS_FIXES[field],
+    meta: { field },
+  });
+
 /**
  * Every step a send can die at. A closed union rather than a `string`: the stage is keyed on by
  * the transports' `fix` tables and asserted on in tests, so a typo has to be a compile error

package/src/header-safety.ts

@@ -0,0 +1,25 @@
+// Single responsibility: refuse a `MailMessage` whose header-bound fields carry a CR or LF, before
+// any transport sees it. The rule is a property of the MESSAGE and not of a wire format, so it is
+// checked where a message is built rather than once per driver — it shipped only in `mime.ts`, so
+// a subject an SMTP deploy rejected was accepted by memory in dev and by Resend in staging.
+
+import { type MailMessage, messageHeaders } from './driver';
+import { headerInvalid } from './errors';
+
+/** A break ends the header early and everything after it becomes headers of the sender's choosing. */
+const BREAK = /[\r\n]/;
+
+/**
+ * Every field of `message` that becomes a header, through the one function that decides which
+ * headers a message gets — so a header added there is gated here without a second edit.
+ *
+ * `mime.ts` keeps its own per-header gate and is NOT redundant: it also covers `From`, `Date` and
+ * `Message-ID`, which the transport mints and no message-level check can see, and it is the last
+ * thing every present and future caller of `buildMimeMessage` passes through.
+ */
+export function assertHeaderSafe(message: MailMessage): void {
+  if (BREAK.test(message.subject)) throw headerInvalid('Subject', message.mailId);
+  for (const [name, value] of Object.entries(messageHeaders(message))) {
+    if (BREAK.test(value)) throw headerInvalid(name, message.mailId);
+  }
+}

package/src/idempotency.ts

@@ -5,13 +5,19 @@
 import type { MailMessage } from './driver';
 
 /**
- * `(mailId, recipients, hash(rendered payload))`, or the caller's key when supplied.
- * Content-derived on purpose: a retry of the same request produces the same key, while an
- * intentional resend with different content produces a different one.
+ * `(mailId, recipients, hash(rendered payload))`, or `(mailId, the caller's key)` when one is
+ * supplied. Content-derived on purpose: a retry of the same request produces the same key, while
+ * an intentional resend with different content produces a different one.
+ *
+ * The mailId is in BOTH branches, and the explicit one needs it most: a caller's key is a natural
+ * id from its own domain (`signup:42`, an order id), so the welcome mail and the verify-email mail
+ * about one signup would otherwise mint the same key — and the queue dedupes it (`onConflict:
+ * 'dedupe'`) and Resend dedupes it, so the second mail is never delivered and nothing reports it.
+ * Scoping to the template keeps the caller's dedupe where the caller meant it: this send, retried.
  */
 export function mailIdempotencyKey(message: MailMessage): string {
   const explicit = message.idempotencyKey;
-  if (explicit !== undefined && explicit !== '') return `mail:${explicit}`;
+  if (explicit !== undefined && explicit !== '') return `mail:${message.mailId}:${explicit}`;
   const recipients = [...message.to].map((address) => address.toLowerCase()).sort();
   // Every field that reaches the wire is hashed, `replyTo` included: it travels as `Reply-To` and
   // as Resend's `reply_to`, so two mails that differ only there are two mails, and a shared key
@@ -32,6 +38,21 @@ export function mailIdempotencyKey(message: MailMessage): string {
   return `mail:${message.mailId}:${recipients.join(',')}:${digest}`;
 }
 
+/**
+ * The `Message-ID` token for a message, stable across every attempt of the same send.
+ *
+ * SMTP has no idempotency protocol, so this header is the ONE identifier a receiving mailbox can
+ * collapse a duplicate on — and an attempt that times out after `DATA` is retryable, so the job
+ * retry hands the server the identical mail. A fresh random token per attempt made that second copy
+ * a different message to everything downstream.
+ *
+ * A one-way digest of the key, never the key itself: the key holds the recipient list, bcc
+ * included, and a `Message-ID` is visible to every recipient of the mail.
+ */
+export function mailMessageIdToken(message: MailMessage): string {
+  return contentDigest(mailIdempotencyKey(message));
+}
+
 /** Key order is normalised so two structurally equal payloads hash identically. */
 function stableStringify(value: unknown): string {
   if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;

package/src/index.ts

@@ -18,13 +18,16 @@ export type {
 export {
   createLogDriver,
   createMemoryDriver,
+  createUnconfiguredDriver,
   envelopeRecipients,
   isMemoryDriver,
+  isUnconfiguredDriver,
   mailDriver,
   messageHeaders,
   resetMailDriver,
   setMailDriver,
   tryMailDriver,
+  UNCONFIGURED_DRIVER_NAME,
 } from './driver';
 export type { MailEnvironment, MailSelection } from './driver-env';
 export { MAIL_ENV_KEYS, selectMailDriver } from './driver-env';
@@ -32,23 +35,33 @@ export type { MailFetch, ResendDriverOptions } from './driver-resend';
 export { createResendDriver, RESEND_BASE_URL } from './driver-resend';
 export type { SmtpDriverOptions } from './driver-smtp';
 export { createSmtpDriver } from './driver-smtp';
-export type { MailErrorCode, MailErrorInit, SendFailure, SendStage } from './errors';
+export { assertEnvelopeAddress } from './envelope-address';
+export type {
+  EnvelopeAddressField,
+  MailErrorCode,
+  MailErrorInit,
+  SendFailure,
+  SendStage,
+} from './errors';
 export {
+  addressInvalid,
   driverUnavailable,
   layoutUnknown,
   localeMissing,
   MAIL_ERROR_CODES,
   MAIL_ERROR_TITLES,
   MailError,
+  mailCredentialMissing,
   mailDuplicate,
   sendFailed,
   templateUnknown,
   textMissing,
 } from './errors';
+export { assertHeaderSafe } from './header-safety';
 
 export { escapeHtml, safeUrl } from './html';
 
-export { mailIdempotencyKey } from './idempotency';
+export { mailIdempotencyKey, mailMessageIdToken } from './idempotency';
 export { mailMessageSchema, sendMailJob } from './job';
 export type {
   ColorScheme,

package/src/job.ts

@@ -5,6 +5,7 @@
 import { type JobHandle, job } from '@ultimat3/jobs';
 import { type StandardSchemaV1, t } from '@ultimat3/schema';
 import { type MailMessage, mailDriver, type SendResult } from './driver';
+import { assertHeaderSafe } from './header-safety';
 import { mailIdempotencyKey } from './idempotency';
 
 /** The queue payload is the already-rendered envelope: rendering happens once, at send time. */
@@ -31,6 +32,18 @@ export const sendMailJob: JobHandle<MailMessage> = job<MailMessage>({
   name: 'mail.send',
   input: mailMessageSchema,
   idempotencyKey: mailIdempotencyKey,
+  // A send carries a MailMessage — addresses and a rendered body, never an org. The recipient
+  // was resolved by whoever enqueued it, under their own tenant, so this run touches no
+  // tenant-scoped table and has no org to declare.
+  tenant: 'none',
   retry: { attempts: 5, backoff: 'exponential' },
-  run: ({ input }): Promise<SendResult> => mailDriver().send(input),
+  // `async`, so the refusal below is a REJECTED promise: a synchronous throw from a body whose
+  // signature promises one escapes every caller that only awaits it.
+  run: async ({ input }): Promise<SendResult> => {
+    // The second boundary the header rule is checked at, and the one `renderMessage` cannot cover:
+    // a queue row is not necessarily one this process rendered — `mailMessageSchema` proves the
+    // SHAPE of a payload and says nothing about a break inside a string it accepted.
+    assertHeaderSafe(input);
+    return await mailDriver().send(input);
+  },
 });

package/src/mail.ts

@@ -9,6 +9,7 @@ import { parse, type StandardSchemaV1 } from '@ultimat3/schema';
 import type { MailTemplate } from './blocks';
 import { type MailMessage, mailDriver, type SendResult } from './driver';
 import { localeMissing, mailDuplicate, templateUnknown } from './errors';
+import { assertHeaderSafe } from './header-safety';
 import { mailIdempotencyKey } from './idempotency';
 import { sendMailJob } from './job';
 import { BASE_LAYOUT } from './layout';
@@ -94,8 +95,8 @@ export function resetMails(): void {
 
 /**
  * Validate, render, and build the envelope — everything `send` does before it decides
- * between the queue and the transport. Exported so `x mail preview` and tests can render
- * without delivering anything.
+ * between the queue and the transport. Exported so a host or a test can render a mail without
+ * delivering it — the `/_x` mail panel and `mailIdempotencyKey`'s callers both need that.
  */
 export function renderMessage<I>(
   mail: MailDefinition<I>,
@@ -120,7 +121,7 @@ export function renderMessage<I>(
     unsubscribeUrl: options.unsubscribeUrl,
   });
 
-  return {
+  const message: MailMessage = {
     mailId: mail.id,
     to,
     subject: rendered.subject,
@@ -134,6 +135,12 @@ export function renderMessage<I>(
     unsubscribeUrl: options.unsubscribeUrl,
     idempotencyKey: options.idempotencyKey,
   };
+  // Here, not in a driver: interpolated data reaches `Subject`, and whether a break in it injects
+  // headers is a property of the message, not of whichever transport this deploy happens to run.
+  // Checked before the queue too, so the refusal lands on the `send()` call site that made it
+  // rather than on a worker three retries later.
+  assertHeaderSafe(message);
+  return message;
 }
 
 /**

package/src/smtp-client.ts

@@ -3,6 +3,7 @@
 // network. Every refusal becomes `X_MAIL_SEND_FAILED` naming the stage and the server's own reply.
 
 import { base64Utf8 } from './base64';
+import { assertEnvelopeAddress } from './envelope-address';
 import { type MailError, type SendStage, sendFailed } from './errors';
 import {
   authPlain,
@@ -169,6 +170,14 @@ export async function smtpDeliver(
   envelope: SmtpEnvelope,
   options: SmtpSessionOptions,
 ): Promise<SmtpReply> {
+  // Before a single byte: every address below is interpolated into a command line, so one holding
+  // a CR or LF would write commands of its own. `bcc` reaches here having passed through no schema
+  // at all on the inline send path, and the header gate in `mime.ts` never sees it — an envelope
+  // field is not a header. Checked here rather than at either caller, because this is the module
+  // that builds the line, and it is the last place every present and future caller passes through.
+  assertEnvelopeAddress('sender', envelope.from);
+  for (const recipient of envelope.recipients) assertEnvelopeAddress('recipient', recipient);
+
   const talk = new Conversation(stream, options.timeoutMs);
   await talk.expect('greeting', (code) => code === 220);
 

package/src/templates/index.ts

@@ -1,5 +1,7 @@
-// Single responsibility: the framework's own transactional mails, gathered. `FRAMEWORK_MAILS`
-// is what `x mail list` prints and what the i18n audit walks for missing keys.
+// Single responsibility: the framework's own transactional mails, gathered. `FRAMEWORK_MAILS` is
+// the list a host projects them from — there is no `x mail` command, and the header claimed one.
+// `templates.test.ts` holds every entry to a rendered case, so a mail added here and left
+// untranslated is a failing test rather than a template nobody notices.
 
 import type { AnyMailDefinition } from '../mail';
 import { inviteMail } from './invite';