@ultimat3/mail 21.0.0 → 22.0.0

package/README.md

@@ -34,7 +34,7 @@ delivers inline only when `{ sync: true }` is passed or no job driver is configu
 | 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 |
-| 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 |
+| 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 |
 
 ## Drivers
 
@@ -127,6 +127,15 @@ Translating them = shipping `mail.*` keys in an app catalog. Never edit a templa
 | `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 — 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
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `MailError` | any `MailErrorCode` — `MAIL_ERROR_CODES` | `src/errors.ts` |
+
 ## Commands
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mail",
-  "version": "21.0.0",
+  "version": "22.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": "21.0.0",
-    "@ultimat3/i18n": "21.0.0",
-    "@ultimat3/jobs": "21.0.0",
-    "@ultimat3/schema": "21.0.0",
-    "@ultimat3/time": "21.0.0"
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/i18n": "22.0.0",
+    "@ultimat3/jobs": "22.0.0",
+    "@ultimat3/schema": "22.0.0",
+    "@ultimat3/time": "22.0.0"
   }
 }

package/src/idempotency.ts

@@ -2,10 +2,13 @@
 // apart from `job.ts` because the transports need it too: a job retry after a timeout hands the
 // same envelope to the provider again, and without this key on the wire that is a second email.
 
+// Core's canonical form, never a private copy: it is the one injective serializer, and a second
+// one is where two spellings of one payload would start hashing differently.
+import { canonicalJson } from '@ultimat3/core';
 import type { MailMessage } from './driver';
 
 /**
- * `(mailId, recipients, hash(rendered payload))`, or `(mailId, the caller's key)` when one is
+ * `(mailId, hash(recipients + 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.
  *
@@ -17,13 +20,19 @@ import type { MailMessage } from './driver';
  */
 export function mailIdempotencyKey(message: MailMessage): string {
   const explicit = message.idempotencyKey;
-  if (explicit !== undefined && explicit !== '') return `mail:${message.mailId}:${explicit}`;
+  if (explicit !== undefined && explicit !== '') {
+    // Sent as written when it is a header-safe ASCII token that fits; digested otherwise, because
+    // a raw non-ASCII or over-long key is a `TypeError` out of `Headers` or a 400 from Resend.
+    return `mail:${message.mailId}:${HEADER_SAFE.test(explicit) ? explicit : contentDigest(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
-  // would have the provider drop the second one as a duplicate.
+  // The RECIPIENTS are hashed with the payload, never spelled out in the key: fifty addresses made
+  // a 2 kB `Idempotency-Key` Resend refuses (its limit is 256) — a dead letter — and one non-ASCII
+  // address made `Headers` throw, which the job retried as egress until it gave up. Every field
+  // that reaches the wire is hashed, `replyTo` included: two mails differing only there are two.
   const digest = contentDigest(
-    stableStringify({
+    canonicalJson({
+      recipients,
       subject: message.subject,
       html: message.html,
       text: message.text,
@@ -35,9 +44,12 @@ export function mailIdempotencyKey(message: MailMessage): string {
       unsubscribeUrl: message.unsubscribeUrl ?? '',
     }),
   );
-  return `mail:${message.mailId}:${recipients.join(',')}:${digest}`;
+  return `mail:${message.mailId}:${digest}`;
 }
 
+/** Visible ASCII, bounded well under Resend's 256 so the `mail:<id>:` prefix still fits. */
+const HEADER_SAFE = /^[\x21-\x7e]{1,200}$/;
+
 /**
  * The `Message-ID` token for a message, stable across every attempt of the same send.
  *
@@ -53,20 +65,6 @@ 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(',')}]`;
-  if (value !== null && typeof value === 'object') {
-    const entries = Object.entries(value as Record<string, unknown>)
-      .filter(([, entry]) => entry !== undefined)
-      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-      .map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`);
-    return `{${entries.join(',')}}`;
-  }
-  if (value === undefined) return 'null';
-  return JSON.stringify(value);
-}
-
 /** 128 bits of hex: no collision at any volume a mailer reaches, and short enough for a header. */
 const DIGEST_HEX_CHARS = 32;
 

package/src/index.ts

@@ -7,7 +7,7 @@ export { t } from '@ultimat3/schema';
 export type { CalloutTone, MailBlock, MailTemplate, TemplateArgs } from './blocks';
 export { blocks } from './blocks';
 
-export { MAIL_CATALOG, MAIL_CATALOG_LOCALE, MAIL_CATALOG_SOURCE } from './catalog';
+export { MAIL_CATALOG, MAIL_CATALOG_LOCALE } from './catalog';
 export type {
   MailDriver,
   MailMessage,
@@ -20,7 +20,6 @@ export {
   createLogDriver,
   createMemoryDriver,
   createUnconfiguredDriver,
-  envelopeRecipients,
   isMemoryDriver,
   isUnconfiguredDriver,
   mailDriver,
@@ -28,12 +27,11 @@ export {
   resetMailDriver,
   setMailDriver,
   tryMailDriver,
-  UNCONFIGURED_DRIVER_NAME,
 } from './driver';
 export type { MailEnvironment, MailSelection } from './driver-env';
-export { MAIL_ENV_KEYS, selectMailDriver } from './driver-env';
+export { selectMailDriver } from './driver-env';
 export type { MailFetch, ResendDriverOptions } from './driver-resend';
-export { createResendDriver, RESEND_BASE_URL } from './driver-resend';
+export { createResendDriver } from './driver-resend';
 export type { SmtpDriverOptions } from './driver-smtp';
 export { createSmtpDriver } from './driver-smtp';
 export { assertEnvelopeAddress } from './envelope-address';
@@ -78,12 +76,8 @@ export type {
 export {
   BASE_LAYOUT,
   baseLayout,
-  DARK_RULES,
-  darkModeCss,
   layoutFor,
-  MAIL_FONT_STACK,
   MAIL_TOKENS,
-  MAIL_WIDTH_PX,
   registeredLayouts,
   registerLayout,
   token,
@@ -100,7 +94,7 @@ export {
   sendById,
 } from './mail';
 export type { RenderableMail, RenderedMail, RenderOptions } from './render';
-export { FOOTER_KEYS, renderMail, textOf, UNSUBSCRIBE_KEY } from './render';
+export { renderMail, textOf } from './render';
 export type { SmtpConnector, SmtpStream } from './smtp-client';
 
 export {

package/src/smtp-client.ts

@@ -24,6 +24,11 @@ export interface SmtpStream {
   write(data: string): Promise<void>;
   /** STARTTLS: negotiate TLS in place. Everything read or written after this is encrypted. */
   startTls(): Promise<void>;
+  /**
+   * True when the server sent bytes the client has not read yet. Asked once, after the STARTTLS
+   * `220`: anything already waiting there is plaintext a man-in-the-middle can have appended.
+   */
+  buffered?(): boolean;
   close(): void;
 }
 
@@ -88,7 +93,7 @@ const refused = (stage: SendStage, reply: SmtpReply): MailError =>
 
 /** Reads whole replies off a chunked stream, with a deadline on every one of them. */
 class Conversation {
-  private readonly parser = createReplyParser();
+  private parser = createReplyParser();
   private readonly pending: SmtpReply[] = [];
 
   constructor(
@@ -96,6 +101,26 @@ class Conversation {
     private readonly timeoutMs: number,
   ) {}
 
+  /**
+   * RFC 3207 §4.2, both halves: nothing may be buffered after the STARTTLS `220` — any byte there
+   * arrived in PLAINTEXT and would be read as the TLS side's EHLO reply, so an injected
+   * `250 AUTH …` chose how credentials were sent — and the reader starts over on the TLS side.
+   */
+  assertNothingAfterStarttls(): void {
+    if (this.pending.length > 0 || this.parser.hasPending() || this.stream.buffered?.() === true) {
+      throw sendFailed({
+        driver: 'smtp',
+        stage: 'starttls',
+        detail:
+          'the server sent bytes after its STARTTLS 220 and before the TLS handshake — plaintext a ' +
+          'man-in-the-middle can append (RFC 3207 §4.2), so the session is refused before any credential',
+        retryable: false,
+        fix: FIXES['starttls'] ?? 'set SMTP_URL in .env to smtps://host:465',
+      });
+    }
+    this.parser = createReplyParser();
+  }
+
   /** Sends one command line and reads the reply it expects. The line is never logged. */
   async say(stage: SendStage, line: string, wanted: (code: number) => boolean): Promise<SmtpReply> {
     await this.stream.write(`${line}\r\n`);
@@ -191,6 +216,7 @@ export async function smtpDeliver(
 
   if (!secure && capabilities.starttls) {
     await talk.say('starttls', 'STARTTLS', (code) => code === 220);
+    talk.assertNothingAfterStarttls();
     await stream.startTls();
     // Capabilities before TLS are not the capabilities after it: most servers only advertise AUTH
     // once the channel is encrypted, and a cleartext EHLO can be stripped in flight anyway.

package/src/smtp-socket.ts

@@ -66,6 +66,11 @@ class ChunkQueue {
     this.take()?.reject(error);
   }
 
+  /** Chunks received and not yet read — what `buffered()` reports after a STARTTLS 220. */
+  get size(): number {
+    return this.chunks.length;
+  }
+
   read(): Promise<string | undefined> {
     const next = this.chunks.shift();
     if (next !== undefined) return Promise.resolve(next);
@@ -233,6 +238,7 @@ export function smtpStreamOver(runtime: BunConnect, target: SmtpTarget): Promise
 
     return {
       read: () => queue.read(),
+      buffered: () => queue.size > 0,
       write: (data: string) => flush(encoder.encode(data)),
       startTls: () => {
         // Bun hands back `[raw, tls]`; every later read and write goes through the second one, and