@ultimat3/mail 19.1.3 → 19.3.1

package/CLAUDE.md

@@ -122,6 +122,34 @@
 - `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.
+- **The envelope gate NORMALISES one thing, and the order is the security property** (`As of
+  2026-09`). `Jane Doe <jane@x.test>` is the ordinary RFC 5322 display form — the `To:` header
+  carries it verbatim and the resend, memory and log drivers accept it — while `RCPT TO:` takes an
+  addr-spec, so SMTP alone refused it `X_MAIL_ADDRESS_INVALID` for the angle brackets the display
+  form is made of. `envelopeAddress(field, address)` in `envelope-address.ts` is the one repair,
+  called by `smtpDeliver` for BOTH halves (never a second copy in `driver-smtp.ts`): control
+  characters are refused on the RAW value **before** the phrase is stripped, because
+  `ops@x.test\r\nRCPT TO:<attacker@evil.test>` strips down to a clean-looking mailbox — a
+  strip-then-check turns the injection into a delivery to the attacker.
+- **`From`, `To` and `Cc` encode the display PHRASE, never the list** (`As of 2026-09`). `Subject`
+  was RFC 2047 encoded and the address headers were not, so `José Muñoz <jose@x.test>` went on the
+  wire as 8-bit UTF-8 in a session `smtp-protocol.ts` never negotiates SMTPUTF8 for. `mime.ts`'s
+  `encodeAddressPhrase` splits on the trailing `<addr-spec>` — the same regex `addressSpec` uses —
+  encodes the phrase and copies the mailbox through: encoding the whole list would base64 the
+  commas and brackets that make it an address list. The `header()` gate still runs on the RAW
+  value, and an ARRAY is checked element by element before it is joined, so a CRLF in a display
+  name is still `X_MAIL_HEADER_INVALID` rather than hidden inside an encoded word. An ASCII list is
+  byte-identical to before.
+- **A non-ASCII MAILBOX is refused, at both gates** (`As of 2026-09-06`). RFC 2047 encoded words
+  are legal in a display phrase and nowhere else, so `encodeAddressPhrase` has no encoding for the
+  addr-spec — and SMTPUTF8 (RFC 6531), which is what makes a raw UTF-8 mailbox legal, is negotiated
+  by nothing in this package. Sending it anyway writes 8-bit octets into `To:` and into
+  `MAIL FROM:<…>` beside it, and reports the server's rejection as a TRANSPORT failure after the
+  envelope is half written. `hasNonAsciiAddrSpec` (`mime.ts`, the module that owns the addr-spec)
+  is the one predicate; `buildMimeMessage` raises `X_MAIL_HEADER_INVALID` and `envelopeAddress`
+  raises `X_MAIL_ADDRESS_INVALID` with `meta.reason: 'non-ascii'` — two wire formats, one check
+  each, and two reasons on one code so a `cause` is never wrong half the time. The PHRASE still
+  travels: `José Muñoz <jose@x.test>` is unchanged.
 - 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
@@ -131,7 +159,8 @@
   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.
+  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.
 
 ## Commands
 

package/package.json

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

package/src/driver-smtp.ts

@@ -15,7 +15,7 @@ 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 { addressDomain, buildMimeMessage } from './mime';
 import {
   type SmtpConnector,
   type SmtpSessionOptions,
@@ -200,7 +200,9 @@ export function createSmtpDriver(options: SmtpDriverOptions): MailDriver {
     try {
       await smtpDeliver(
         stream,
-        { from: addressSpec(options.from), recipients: envelopeRecipients(message), data },
+        // Display forms in either half are normalised by `smtpDeliver` itself, which is the module
+        // that writes the command line — never here, where a second copy of the rule would drift.
+        { from: options.from, recipients: envelopeRecipients(message), data },
         session,
       );
       return resultFor('smtp', message, messageId);

package/src/envelope-address.ts

@@ -1,8 +1,11 @@
 // 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.
+// formats, one check each, at the module that owns the format. It refuses, and it normalises one
+// thing only — the RFC 5322 display form down to the mailbox `RCPT TO:` can carry, always after
+// the control-character check, never before it.
 
 import { addressInvalid, type EnvelopeAddressField } from './errors';
+import { addressSpec, hasNonAsciiAddrSpec } from './mime';
 
 /**
  * Every character that can restructure the command line: C0 controls (CR and LF above all), DEL,
@@ -11,19 +14,54 @@ import { addressInvalid, type EnvelopeAddressField } from './errors';
  *
  * 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.
+ * second command.
+ *
+ * Non-ASCII IS refused, and by this package rather than by the server: SMTPUTF8 (RFC 6531) is what
+ * makes a UTF-8 mailbox legal and `smtp-client.ts` negotiates none, so the alternative is writing
+ * raw 8-bit octets into `MAIL FROM:<…>` and hoping. That reports as a transport failure at the
+ * command, after the envelope is half-written — where a refusal here names the address and runs
+ * before a byte is sent. `mime.ts` holds the predicate, at the module that owns the addr-spec.
  */
 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 hasControlCharacter(address);
+}
+
+/** C0 controls (CR and LF above all), DEL and the C1 range — everything that ends a command line. */
+function hasControlCharacter(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;
+  }
   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);
+  if (isUnsafe(address)) throw addressInvalid(field, 'injection');
+  // Two reasons, two `meta.reason`s, checked in this order: an injection is the dangerous one and
+  // an address carrying both should say so. The addr-spec, never the phrase — `mime.ts` has an
+  // RFC 2047 encoding for a display name and none for a mailbox.
+  if (hasNonAsciiAddrSpec(address)) throw addressInvalid(field, 'non-ascii');
+}
+
+/**
+ * The addr-spec an envelope command may carry, from whatever form the caller wrote. `Jane Doe
+ * <jane@x.test>` is the ordinary RFC 5322 display form — the `To:` header carries it verbatim and
+ * the resend, memory and log drivers all accept it — but `RCPT TO:` takes a mailbox, so it is
+ * stripped here and the gate above runs on what is left.
+ *
+ * The control-character half runs on the RAW value, BEFORE the strip, and the order is the whole
+ * point: `ops@x.test\r\nRCPT TO:<attacker@evil.test>` strips down to a clean-looking mailbox that
+ * every later check waves through, so a strip-then-check would have turned the injection into a
+ * delivery to the attacker instead of a refusal.
+ */
+export function envelopeAddress(field: EnvelopeAddressField, address: string): string {
+  if (hasControlCharacter(address)) throw addressInvalid(field, 'injection');
+  const spec = addressSpec(address);
+  assertEnvelopeAddress(field, spec);
+  return spec;
 }

package/src/errors.ts

@@ -211,6 +211,20 @@ const ADDRESS_FIXES: Readonly<Record<EnvelopeAddressField, string>> = {
   recipient: "pass bare addresses: send(mail, data, { to: ['ada@example.test'], locale })",
 };
 
+/**
+ * Why an envelope address was refused. Two reasons, one code: the value is recipient data either
+ * way, so a caller reading `meta.reason` is the only way to tell them apart — and a `cause` naming
+ * both would be wrong half the time, which is the misdirection axiom 4 refuses.
+ */
+export type AddressRefusal = 'injection' | 'non-ascii';
+
+const ADDRESS_CAUSES: Readonly<Record<AddressRefusal, string>> = {
+  injection:
+    'holds a control character or an angle bracket, which would end the command line and inject SMTP commands',
+  'non-ascii':
+    'holds a non-ASCII byte in its mailbox, and this package negotiates no SMTPUTF8, so it cannot be written to the command line at all',
+};
+
 /**
  * `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
@@ -219,14 +233,15 @@ const ADDRESS_FIXES: Readonly<Record<EnvelopeAddressField, string>> = {
  * 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 =>
+export const addressInvalid = (
+  field: EnvelopeAddressField,
+  reason: AddressRefusal = 'injection',
+): 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',
+    cause: `the SMTP envelope ${field} address ${ADDRESS_CAUSES[reason]}`,
     fix: ADDRESS_FIXES[field],
-    meta: { field },
+    meta: { field, reason },
   });
 
 /**

package/src/index.ts

@@ -38,6 +38,7 @@ export type { SmtpDriverOptions } from './driver-smtp';
 export { createSmtpDriver } from './driver-smtp';
 export { assertEnvelopeAddress } from './envelope-address';
 export type {
+  AddressRefusal,
   EnvelopeAddressField,
   MailErrorCode,
   MailErrorInit,

package/src/mime.ts

@@ -53,15 +53,29 @@ export function buildMimeMessage(message: MailMessage, options: MimeOptions): st
   // whichever header is added next. The check runs on the RAW value: encoding first would let a
   // non-ASCII subject hide a line break inside an encoded word instead of refusing it, so the
   // same input would be accepted or rejected depending on whether it happened to be ASCII.
-  const header = (name: string, value: string, encode = false): void => {
-    if (value.includes('\r') || value.includes('\n')) throw headerInvalid(name, message.mailId);
-    headerLines.push(foldHeaderLine(name, encode ? encodeHeaderValue(value) : value));
+  const header = (
+    name: string,
+    value: string | readonly string[],
+    mode: HeaderMode = 'verbatim',
+  ): void => {
+    // An ARRAY is checked element by element and joined here, never joined by the caller: the
+    // check has to see the raw address, and `', '` introduces no line break of its own.
+    const parts = typeof value === 'string' ? [value] : value;
+    for (const part of parts) {
+      if (part.includes('\r') || part.includes('\n')) throw headerInvalid(name, message.mailId);
+      // The MAILBOX, not the phrase: `encodeAs` has an RFC 2047 encoding for the display name and
+      // none for the addr-spec, and this package negotiates no SMTPUTF8 — so a UTF-8 mailbox would
+      // go out as raw 8-bit octets in a header AND in the envelope beside it.
+      if (mode === 'address' && hasNonAsciiAddrSpec(part))
+        throw headerInvalid(name, message.mailId);
+    }
+    headerLines.push(foldHeaderLine(name, parts.map((part) => encodeAs(mode, part)).join(', ')));
   };
 
-  header('From', options.from);
-  header('To', message.to.join(', '));
-  if (message.cc !== undefined && message.cc.length > 0) header('Cc', message.cc.join(', '));
-  header('Subject', message.subject, true);
+  header('From', options.from, 'address');
+  header('To', message.to, 'address');
+  if (message.cc !== undefined && message.cc.length > 0) header('Cc', message.cc, 'address');
+  header('Subject', message.subject, 'value');
   header('Date', rfc5322Date(options.date));
   header('Message-ID', options.messageId);
   header('MIME-Version', '1.0');
@@ -93,9 +107,60 @@ function bodyPart(contentType: string, text: string): string {
   );
 }
 
+/**
+ * How a header VALUE reaches the wire. `verbatim` is a value that is 7-bit by construction (a
+ * date, a boundary, a message id); `value` is RFC 2047 over the whole string; `address` encodes
+ * only the display phrase, because the commas, angle brackets and addr-specs around it are what
+ * make the line an address list and a base64 blob is none of those.
+ */
+type HeaderMode = 'verbatim' | 'value' | 'address';
+
+function encodeAs(mode: HeaderMode, value: string): string {
+  if (mode === 'verbatim') return value;
+  if (mode === 'value') return encodeHeaderValue(value);
+  return encodeAddressPhrase(value);
+}
+
+/**
+ * `José Muñoz <jose@x.test>` -> `=?UTF-8?B?…?= <jose@x.test>`. Non-ASCII in an unencoded header is
+ * an 8-bit octet on a wire this package never negotiates SMTPUTF8 for, so it is the display name
+ * that gets encoded — the addr-spec is copied through untouched, because a mailbox is the
+ * server's to parse and an encoded word is not one. An address with no phrase, or an ASCII
+ * phrase, comes back byte-identical.
+ *
+ * The MAILBOX is a different question and `hasNonAsciiAddrSpec` is where it is asked: RFC 2047
+ * encoded words are legal in a phrase and nowhere else, so there is no encoding this function
+ * could apply to it. `buildMimeMessage` refuses one before it reaches this line.
+ */
+export function encodeAddressPhrase(address: string): string {
+  const match = ADDRESS_SPEC.exec(address);
+  if (match === null) return address;
+  const phrase = address.slice(0, match.index).trim();
+  if (phrase === '' || isPureAscii(phrase)) return address;
+  return `${encodeHeaderValue(phrase)} <${match[1] ?? ''}>`;
+}
+
+/**
+ * Whether the MAILBOX half of an address carries a byte this package cannot put on the wire.
+ *
+ * SMTPUTF8 (RFC 6531) is what makes a non-ASCII addr-spec legal, and `smtp-client.ts` negotiates
+ * no such thing — so a UTF-8 mailbox reaches `MAIL FROM:<…>` and `RCPT TO:<…>` as raw 8-bit
+ * octets, which a conforming server MAY reject. Refused rather than sent, and refused at both
+ * gates: the message gate (`buildMimeMessage`) and the envelope gate (`envelopeAddress`), because
+ * the two write different wire formats and a check on one says nothing about the other. The
+ * PHRASE is untouched — `encodeAddressPhrase` has an encoding for that half and this is the half
+ * it has none for.
+ */
+export function hasNonAsciiAddrSpec(address: string): boolean {
+  return !isPureAscii(addressSpec(address));
+}
+
+/** The trailing `<addr-spec>` of an address, which is the boundary between phrase and mailbox. */
+const ADDRESS_SPEC = /<([^<>]+)>\s*$/;
+
 /** `Postly <no-reply@postly.test>` -> `no-reply@postly.test`. A bare address is returned as-is. */
 export function addressSpec(address: string): string {
-  const match = /<([^<>]+)>\s*$/.exec(address);
+  const match = ADDRESS_SPEC.exec(address);
   return match?.[1] ?? address;
 }
 

package/src/smtp-client.ts

@@ -3,7 +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 { envelopeAddress } from './envelope-address';
 import { type MailError, type SendStage, sendFailed } from './errors';
 import {
   authPlain,
@@ -175,8 +175,10 @@ export async function smtpDeliver(
   // 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 from = envelopeAddress('sender', envelope.from);
+  const recipients = envelope.recipients.map((recipient) =>
+    envelopeAddress('recipient', recipient),
+  );
 
   const talk = new Conversation(stream, options.timeoutMs);
   await talk.expect('greeting', (code) => code === 220);
@@ -210,8 +212,8 @@ export async function smtpDeliver(
 
   if (options.user !== undefined) await authenticate(talk, capabilities, options);
 
-  await talk.say('from', `MAIL FROM:<${envelope.from}>`, isPositive);
-  for (const recipient of envelope.recipients) {
+  await talk.say('from', `MAIL FROM:<${from}>`, isPositive);
+  for (const recipient of recipients) {
     // Fail closed on any refusal: delivering to three of four addresses and reporting success is
     // the one outcome the caller cannot detect.
     await talk.say('recipient', `RCPT TO:<${recipient}>`, isPositive);