@ultimat3/mail 9.0.0 → 10.0.0

package/CLAUDE.md

@@ -90,7 +90,23 @@
   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.
+- **`assertHeaderSafe` gates the ADDRESS LISTS too — `to` and `cc`** (`As of 2026-08-23`). It
+  checked `subject` and `Object.entries(messageHeaders(message))`, and `messageHeaders` emits only
+  `Auto-Submitted`, `Reply-To` and the two `List-Unsubscribe` lines — while `to` and `cc` become
+  `To:` and `Cc:` in `mime.ts` and went through neither gate. `renderMessage` ACCEPTED
+  `to: ['victim@x.test\r\nBcc: attacker@evil.test']` and `SendResult.accepted` handed it back;
+  SMTP refuses it one layer down (`envelope-address.ts`), the memory driver and Resend do not.
+  Exactly the three-answers split this rule was lifted out of `mime.ts` to close.
+- **`registerLayout` refuses a second claim on a name** (`X_MAIL_DUPLICATE`, `mailLayoutDuplicate`).
+  `layouts.set` answered whichever registration ran LAST, `base` included, so a dependency that
+  registered `base` silently re-shelled every framework mail with no error anywhere and nothing to
+  grep for. `defineMail` refuses a duplicate id one file over for the identical reason, and
+  `@ultimat3/mcp`'s `ResourceRegistry.register` states the general rule. **Breaking for an app that
+  registered one name twice** — the old behaviour was pinned by a test called "last writer wins",
+  which is what kept it.
+- `Bcc` is an envelope field. It reaches `RCPT TO` and Resend's body, never a header — so
+  `assertHeaderSafe` deliberately does NOT check it and `envelope-address.ts` does. Two wire
+  formats, one gate each; naming a `Bcc` header in a refusal would name one no message has.
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mail",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "Transactional email as data: one template renders HTML and text, sent through a job.",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "9.0.0",
-    "@ultimat3/i18n": "9.0.0",
-    "@ultimat3/jobs": "9.0.0",
-    "@ultimat3/schema": "9.0.0",
-    "@ultimat3/time": "9.0.0"
+    "@ultimat3/core": "10.0.0",
+    "@ultimat3/i18n": "10.0.0",
+    "@ultimat3/jobs": "10.0.0",
+    "@ultimat3/schema": "10.0.0",
+    "@ultimat3/time": "10.0.0"
   }
 }

package/src/errors.ts

@@ -77,12 +77,16 @@ export interface MailErrorInit {
 export class MailError extends UltimateError {
   override readonly name = 'MailError';
 
+  // No `docs:`. `UltimateError` fills it from `describeErrorCode(code).docs`, which is
+  // `@ultimat3/core`'s `ERROR_DOCS_URL` — one page for every code, never one per code, because
+  // `wiki/` is the framework's only public documentation surface and a code lives there in a TABLE
+  // ROW, which has no anchor. The `https://ultimate.dev/errors/<code>` link this class built until
+  // 9.x answered 404, host included, on every error mail has ever thrown.
   constructor(init: MailErrorInit) {
     super({
       code: init.code,
       cause: init.cause,
       fix: init.fix,
-      docs: `https://ultimate.dev/errors/${init.code}`,
       meta: init.meta,
       ...(init.retry === undefined ? {} : { retry: init.retry }),
     });
@@ -125,6 +129,22 @@ export const mailDuplicate = (mailId: string): MailError =>
     meta: { mailId },
   });
 
+/**
+ * A layout name claimed twice. Same code as a duplicate mail id, because it is the same failure —
+ * a name this package addresses something by, taken by two declarations — and the cause names
+ * which of the two spellings the reader is looking at.
+ *
+ * `layouts.set(name, layout)` used to answer whichever registration ran LAST: a package
+ * registering `base` silently re-shelled every framework mail with nothing reported anywhere.
+ */
+export const mailLayoutDuplicate = (name: string): MailError =>
+  new MailError({
+    code: 'X_MAIL_DUPLICATE',
+    cause: `mail layout "${name}" is already registered, so a second registerLayout() would replace it`,
+    fix: `pick a name of your own: registerLayout('${name}-custom', myLayout) — a layout name is the key defineMail({ layout }) addresses a shell by`,
+    meta: { layout: name },
+  });
+
 export const textMissing = (mailId: string): MailError =>
   new MailError({
     code: 'X_MAIL_TEXT_MISSING',

package/src/header-safety.ts

@@ -19,6 +19,24 @@ const BREAK = /[\r\n]/;
  */
 export function assertHeaderSafe(message: MailMessage): void {
   if (BREAK.test(message.subject)) throw headerInvalid('Subject', message.mailId);
+  // The ADDRESS LISTS, which went through no gate at all: `messageHeaders` emits `Auto-Submitted`,
+  // `Reply-To` and the two `List-Unsubscribe` lines and nothing else, while `to` and `cc` become
+  // `To:` and `Cc:` in `mime.ts`. A recipient carrying `\r\nBcc: attacker@evil.test` was accepted
+  // by `renderMessage` and came back in `SendResult.accepted`; SMTP refuses it one layer down, the
+  // memory driver and Resend do not — the exact split this rule was lifted out of `mime.ts` to
+  // close.
+  //
+  // `bcc` is deliberately NOT here: it is an envelope field and never a header, so it is gated by
+  // `envelope-address.ts` on the wire that carries it (`X_MAIL_ADDRESS_INVALID`) — two wire
+  // formats, one gate each. Naming it here would report a `Bcc` header that no message has.
+  for (const [header, addresses] of [
+    ['To', message.to],
+    ['Cc', message.cc],
+  ] as const) {
+    for (const address of addresses ?? []) {
+      if (BREAK.test(address)) throw headerInvalid(header, message.mailId);
+    }
+  }
   for (const [name, value] of Object.entries(messageHeaders(message))) {
     if (BREAK.test(value)) throw headerInvalid(name, message.mailId);
   }

package/src/index.ts

@@ -55,6 +55,7 @@ export {
   MailError,
   mailCredentialMissing,
   mailDuplicate,
+  mailLayoutDuplicate,
   sendFailed,
   templateUnknown,
   textMissing,

package/src/layout.ts

@@ -3,6 +3,7 @@
 // renderer, because email clients drop <style> and templates must never carry a raw hex.
 // Table-based and 600px wide: Outlook still renders with Word's HTML engine.
 
+import { mailLayoutDuplicate } from './errors';
 import { escapeHtml, safeUrl, styleAttr } from './html';
 
 export type ColorScheme = 'light' | 'dark';
@@ -207,7 +208,15 @@ function footerHtml(input: LayoutInput): string {
 
 const layouts = new Map<string, MailLayout>([[BASE_LAYOUT, baseLayout]]);
 
+/**
+ * Claim a layout name. Once, ever — a second claim is refused rather than resolved.
+ *
+ * `layouts.set` answered whichever registration ran last, `base` included, so a dependency that
+ * registered `base` re-shelled every framework mail with no error anywhere and nothing to grep
+ * for. `defineMail` refuses a duplicate id one file over for the identical reason.
+ */
 export function registerLayout(name: string, layout: MailLayout): void {
+  if (layouts.has(name)) throw mailLayoutDuplicate(name);
   layouts.set(name, layout);
 }