@ultimat3/mail 24.0.0 → 25.1.0

package/src/errors.ts

@@ -21,6 +21,9 @@ export const MAIL_ERROR_CODES = [
   'X_MAIL_ADDRESS_INVALID',
   'X_MAIL_SEND_FAILED',
   'X_MAIL_TRANSFORM_FAILED',
+  'X_MAIL_EVENT_UNVERIFIED',
+  'X_MAIL_EVENT_INVALID',
+  'X_MAIL_EVENT_PROVIDER_UNREACHABLE',
 ] as const;
 
 export type MailErrorCode = (typeof MAIL_ERROR_CODES)[number];
@@ -36,6 +39,9 @@ export const MAIL_ERROR_TITLES: Readonly<Record<MailErrorCode, string>> = {
   X_MAIL_ADDRESS_INVALID: 'an envelope address could restructure the SMTP command line',
   X_MAIL_SEND_FAILED: 'the mail transport refused the message',
   X_MAIL_TRANSFORM_FAILED: 'the app mail transform threw or returned no message',
+  X_MAIL_EVENT_UNVERIFIED: 'a delivery notification is not signed by its provider',
+  X_MAIL_EVENT_INVALID: 'a delivery notification is not a shape this receiver reads',
+  X_MAIL_EVENT_PROVIDER_UNREACHABLE: 'an SNS endpoint the receiver needed did not answer',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -159,7 +165,7 @@ export const driverUnavailable = (what: string): MailError =>
   new MailError({
     code: 'X_MAIL_DRIVER_UNAVAILABLE',
     cause: `${what} — nothing can deliver the message`,
-    fix: 'setMailDriver(createMemoryDriver()) in dev, createSmtpDriver({ url: env.SMTP_URL }) live',
+    fix: 'setMailDriver(memoryMailDriver()) in dev, smtpMailDriver({ url: env.SMTP_URL }) live',
     meta: { what },
   });
 
@@ -177,12 +183,13 @@ 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',
+      `none of SMTP_URL, RESEND_API_KEY or SES_REGION 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 ' +
+      'set SMTP_URL="smtps://user:pass@host:465" (or RESEND_API_KEY=re_..., or SES_REGION with ' +
+      'SES_ACCESS_KEY_ID and SES_SECRET_ACCESS_KEY) and ' +
       'MAIL_FROM="App <no-reply@yourdomain.test>" in the deployment environment, then restart',
-    meta: { environment, missing: ['SMTP_URL', 'RESEND_API_KEY'] },
+    meta: { environment, missing: ['SMTP_URL', 'RESEND_API_KEY', 'SES_REGION'] },
   });
 
 /**
@@ -309,7 +316,7 @@ export type SendStage =
  * code or an HTTP status — because "mail failed" without either is not a diagnosis.
  */
 export interface SendFailure {
-  readonly driver: 'smtp' | 'resend';
+  readonly driver: 'smtp' | 'resend' | 'ses';
   readonly stage: SendStage;
   readonly detail: string;
   /** SMTP reply code (4xx/5xx) or HTTP status. Absent when the socket never answered. */

package/src/events.ts

@@ -0,0 +1,28 @@
+// Single responsibility: the public API of `@ultimat3/mail/events` — the delivery-notification
+// receivers and their verification. A subpath and not the barrel because only an app's webhook
+// route uses them, and every serving role (worker, scheduler, migrate) loads the barrel to send.
+
+export type {
+  DeliveryEvent,
+  DeliveryEventKind,
+  DeliveryOutcome,
+  DeliveryReceiver,
+} from './delivery-event';
+export { DEFAULT_DELIVERY_BODY_LIMIT } from './delivery-event';
+export type {
+  DeliveryProvider,
+  DeliveryRefusal,
+  DeliveryShapeProblem,
+  ResendRefusal,
+} from './delivery-event-errors';
+export {
+  deliveryEventInvalid,
+  deliveryEventUnverified,
+  deliveryProviderUnreachable,
+} from './delivery-event-errors';
+export type { ResendEventReceiverOptions } from './resend-event-receiver';
+export { resendEventReceiver } from './resend-event-receiver';
+export { DEFAULT_SVIX_TOLERANCE_MS } from './resend-signature';
+export type { SesEventReceiverOptions } from './ses-event-receiver';
+export { DEFAULT_SNS_TOLERANCE_MS, sesEventReceiver } from './ses-event-receiver';
+export type { SnsCertificateFetch } from './sns-certificate-cache';

package/src/html.ts

@@ -10,7 +10,7 @@ const SAFE_PROTOCOLS: readonly string[] = ['http:', 'https:', 'mailto:'];
  * `javascript:` and `data:` hrefs are stripped rather than escaped: some clients still
  * follow them, and a link the recipient cannot trust is worse than a dead one.
  */
-export function safeUrl(value: string): string {
+export function safeMailHref(value: string): string {
   let parsed: URL;
   try {
     parsed = new URL(value);

package/src/index.ts

@@ -1,13 +1,20 @@
 // Single responsibility: the public API of @ultimat3/mail. Explicit named exports only —
 // other packages call `defineMail`, `send` and the driver seam, and nothing else.
 
-export { escapeHtml } from '@ultimat3/core';
 /** Re-exported so a `defineMail` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
 export type { CalloutTone, MailBlock, MailTemplate, TemplateArgs } from './blocks';
 export { blocks } from './blocks';
-export { MAIL_CATALOG, MAIL_CATALOG_LOCALE } from './catalog';
+export { MAIL_CATALOG } from './catalog';
+// Type-only, so a sender can name an event without loading a receiver; the receivers are
+// `@ultimat3/mail/events`, kept off the barrel every serving role evaluates.
+export type {
+  DeliveryEvent,
+  DeliveryEventKind,
+  DeliveryOutcome,
+  DeliveryReceiver,
+} from './delivery-event';
 export type {
   MailDriver,
   MailMessage,
@@ -17,23 +24,25 @@ export type {
   SentMail,
 } from './driver';
 export {
-  createLogDriver,
-  createMemoryDriver,
-  createUnconfiguredDriver,
   isMemoryDriver,
   isUnconfiguredDriver,
+  logMailDriver,
   mailDriver,
+  memoryMailDriver,
   messageHeaders,
   resetMailDriver,
   setMailDriver,
   tryMailDriver,
+  unconfiguredMailDriver,
 } from './driver';
-export type { MailEnvironment, MailSelection } from './driver-env';
+export type { MailEnvironment, MailSelection, MailSelectOptions } from './driver-env';
 export { selectMailDriver } from './driver-env';
 export type { MailFetch, ResendDriverOptions } from './driver-resend';
-export { createResendDriver } from './driver-resend';
+export { resendMailDriver } from './driver-resend';
+export type { SesDriverOptions } from './driver-ses';
+export { sesEndpoint, sesMailDriver } from './driver-ses';
 export type { SmtpDriverOptions } from './driver-smtp';
-export { createSmtpDriver } from './driver-smtp';
+export { smtpMailDriver } from './driver-smtp';
 export { assertEnvelopeAddress } from './envelope-address';
 export type {
   AddressRefusal,
@@ -61,7 +70,7 @@ export {
   transformFailed,
 } from './errors';
 export { assertHeaderSafe } from './header-safety';
-export { safeUrl } from './html';
+export { safeMailHref } from './html';
 
 export { mailIdempotencyKey, mailMessageIdToken } from './idempotency';
 export { mailMessageSchema, sendMailJob } from './job';
@@ -95,6 +104,8 @@ export {
 } from './mail';
 export type { RenderableMail, RenderedMail, RenderOptions } from './render';
 export { renderMail, textOf } from './render';
+export type { RetainedMime, RetainedMimeEntry, RetainMimeOptions } from './retain-mime';
+export { DEFAULT_RETAIN_MIME_MAX_BYTES, RETAIN_MIME_CEILING_BYTES } from './retain-mime';
 export type { SmtpConnector, SmtpStream } from './smtp-client';
 export {
   FRAMEWORK_MAILS,

package/src/layout.ts

@@ -5,7 +5,7 @@
 
 import { escapeHtml } from '@ultimat3/core';
 import { mailLayoutDuplicate } from './errors';
-import { safeUrl, styleAttr } from './html';
+import { safeMailHref, styleAttr } from './html';
 
 export type ColorScheme = 'light' | 'dark';
 
@@ -200,7 +200,7 @@ function footerHtml(input: LayoutInput): string {
   const lines = input.footer.map((line) => `<div>${escapeHtml(line)}</div>`);
   const slot = input.unsubscribe;
   if (slot !== undefined) {
-    const href = escapeHtml(safeUrl(slot.url));
+    const href = escapeHtml(safeMailHref(slot.url));
     const label = escapeHtml(slot.label);
     lines.push(`<div><a data-x="a" href="${href}" ${UNSUBSCRIBE_STYLE}>${label}</a></div>`);
   }

package/src/render.ts

@@ -3,8 +3,8 @@
 // out of the HTML, so it never rots. Styling is inlined from the layout's tokens because most
 // clients drop <style>; the dark-mode block is the one exception, for clients that honour it.
 
-import { escapeHtml } from '@ultimat3/core';
-import { directionOf, type TranslateVars, type Translator, translatorFor } from '@ultimat3/i18n';
+import { directionOf, escapeHtml } from '@ultimat3/core';
+import { type TranslateVars, type Translator, translatorFor } from '@ultimat3/i18n';
 import type { CalloutTone, MailBlock, MailTemplate } from './blocks';
 // The renderer depends on the strings it renders. This is the only module that resolves a `mail.*`
 // key, and `catalog.ts` installs them at ITS module scope — so importing it here is what makes
@@ -14,7 +14,7 @@ import type { CalloutTone, MailBlock, MailTemplate } from './blocks';
 // `registerMailCatalog()` themselves — the exact shape of issue #249.
 import './catalog';
 import { layoutUnknown, textMissing } from './errors';
-import { safeUrl, styleAttr } from './html';
+import { safeMailHref, styleAttr } from './html';
 import { layoutFor, registeredLayouts, token } from './layout';
 
 /** What the renderer needs from a mail. `MailDefinition` adds the input schema on top. */
@@ -76,7 +76,8 @@ export function renderMail<I>(
   });
 
   const tail = [...footer];
-  if (unsubscribe !== undefined) tail.push(`${unsubscribe.label}: ${safeUrl(unsubscribe.url)}`);
+  if (unsubscribe !== undefined)
+    tail.push(`${unsubscribe.label}: ${safeMailHref(unsubscribe.url)}`);
   const text = tail.length === 0 ? bodyText : `${bodyText}\n\n--\n${tail.join('\n')}`;
 
   return { subject, preheader, html, text };
@@ -93,7 +94,7 @@ export function textOf(list: readonly MailBlock[], t: Translator): string {
         lines.push(t(block.key, block.vars));
         break;
       case 'button':
-        lines.push(`${t(block.key, block.vars)}: ${safeUrl(block.href)}`);
+        lines.push(`${t(block.key, block.vars)}: ${safeMailHref(block.href)}`);
         break;
       case 'detail':
         lines.push(`${t(block.key)}: ${block.value}`);
@@ -163,7 +164,7 @@ function htmlOf(block: MailBlock, t: Translator): string {
     case 'paragraph':
       return `<p data-x="p" ${PARAGRAPH_STYLE}>${escapeHtml(t(block.key, block.vars))}</p>`;
     case 'button': {
-      const href = escapeHtml(safeUrl(block.href));
+      const href = escapeHtml(safeMailHref(block.href));
       const label = escapeHtml(t(block.key, block.vars));
       const anchor = `<a data-x="btn" href="${href}" ${BUTTON_LINK_STYLE}>${label}</a>`;
       return `<table ${TABLE_ATTRS}><tr><td>${anchor}</td></tr></table>`;

package/src/resend-event-receiver.ts

@@ -0,0 +1,111 @@
+// Single responsibility: a Resend webhook, received by an `api/` route, becomes `DeliveryEvent`s.
+// The Svix signature is proven first (`resend-signature.ts`) over the exact bytes that arrived;
+// only then is the body parsed. `email.delivered`, `email.bounced`, `email.complained` and
+// `email.delivery_delayed` are modelled; every other type is authentic and `ignored`.
+
+import { type Clock, finiteCount } from '@ultimat3/core';
+import { t, validate } from '@ultimat3/schema';
+import {
+  type DeliveryEvent,
+  type DeliveryOutcome,
+  type DeliveryReceiver,
+  deliveryInstant,
+  parseDeliveryJson,
+  readDeliveryBody,
+  resolveBodyLimit,
+} from './delivery-event';
+import { deliveryEventInvalid } from './delivery-event-errors';
+import {
+  DEFAULT_SVIX_TOLERANCE_MS,
+  svixKey,
+  svixSecretBytes,
+  verifySvix,
+} from './resend-signature';
+
+export interface ResendEventReceiverOptions {
+  /** The endpoint's `whsec_…` signing secret, from `RESEND_WEBHOOK_SECRET`. Never logged. */
+  readonly secret: string;
+  /** Default `DEFAULT_SVIX_TOLERANCE_MS`. */
+  readonly toleranceMs?: number | undefined;
+  /** Default `DEFAULT_DELIVERY_BODY_LIMIT`. */
+  readonly maxBytes?: number | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+const payload = t.object({
+  type: t.string,
+  created_at: t.string,
+  data: t.object({
+    email_id: t.string,
+    to: t.array(t.string),
+    bounce: t.object({ type: t.string.optional() }).optional(),
+  }),
+});
+
+/** A Map: `type` is the webhook body's, and `{ type: 'constructor' }` must be ignored, not mapped. */
+const KINDS: ReadonlyMap<string, DeliveryEvent['kind']> = new Map<string, DeliveryEvent['kind']>([
+  ['email.delivered', 'delivered'],
+  ['email.bounced', 'bounced'],
+  ['email.complained', 'complained'],
+  ['email.delivery_delayed', 'delayed'],
+]);
+
+/**
+ * A verified Resend payload → events. Resend names no single bounced address, so a multi-recipient
+ * email's bounce is one event per `to` — send one recipient per email to know which one it was.
+ */
+export function resendDeliveryEvents(raw: unknown, eventId: string): DeliveryOutcome {
+  const head = validate(t.object({ type: t.string }), raw);
+  if (head.issues !== undefined) throw deliveryEventInvalid('resend', 'envelope');
+  const kind = KINDS.get(head.value.type);
+  if (kind === undefined) return { type: 'ignored', eventType: head.value.type };
+  const parsed = validate(payload, raw);
+  if (parsed.issues !== undefined) throw deliveryEventInvalid('resend', 'notification');
+  const { data } = parsed.value;
+  const at = deliveryInstant('resend', parsed.value.created_at);
+  // Resend relays SES's verdict: `Permanent` is hard; `Transient` and `Undetermined` are soft.
+  const bounce = data.bounce?.type === 'Permanent' ? 'hard' : 'soft';
+  const events = data.to.map((recipient): DeliveryEvent => {
+    const base = {
+      provider: 'resend' as const,
+      messageId: data.email_id,
+      recipient,
+      at,
+      eventId,
+      raw,
+    };
+    return kind === 'bounced' ? { ...base, kind, bounce } : { ...base, kind };
+  });
+  return { type: 'events', events };
+}
+
+export function resendEventReceiver(options: ResendEventReceiverOptions): DeliveryReceiver {
+  // The shape is refused HERE, at boot; only the Web Crypto import waits for the first delivery.
+  const secret = svixSecretBytes(options.secret);
+  let key: Promise<CryptoKey> | undefined;
+  const maxBytes = resolveBodyLimit('resendEventReceiver', options.maxBytes);
+  const toleranceMs = finiteCount(
+    'resendEventReceiver',
+    'toleranceMs',
+    options.toleranceMs ?? DEFAULT_SVIX_TOLERANCE_MS,
+    1,
+  );
+
+  return {
+    async receive(request) {
+      const body = await readDeliveryBody('resend', request, maxBytes);
+      const headers = {
+        id: request.headers.get('svix-id'),
+        timestamp: request.headers.get('svix-timestamp'),
+        signature: request.headers.get('svix-signature'),
+      };
+      key ??= svixKey(secret);
+      const { eventId } = await verifySvix(headers, body, {
+        key: await key,
+        toleranceMs,
+        clock: options.clock,
+      });
+      return resendDeliveryEvents(parseDeliveryJson('resend', body), eventId);
+    },
+  };
+}

package/src/resend-signature.ts

@@ -0,0 +1,93 @@
+// Single responsibility: prove a Resend webhook came from Resend. Resend signs with Svix: HMAC-SHA256
+// over `<svix-id>.<svix-timestamp>.<body>` under the endpoint's `whsec_` secret, base64, sent as one
+// or more `v1,<mac>` entries in `svix-signature` (more than one while a secret rotates). The mac is
+// compared in constant time, and checked BEFORE the window, so "stale" always means authentic.
+
+import { type Clock, ConfigInvalidError, systemClock, timingSafeEqual } from '@ultimat3/core';
+import { deliveryEventUnverified } from './delivery-event-errors';
+
+/** Svix's own default, and the replay bound every Svix sender already assumes. */
+export const DEFAULT_SVIX_TOLERANCE_MS = 300_000;
+
+/** Svix's `whsec_` prefix. Stripped by pattern: the prefix is public, the rest is the key. */
+const SECRET_PREFIX = /^whsec_/;
+/** Svix ids are `msg_<base62>`; a bound keeps a pathological header out of the mac input. */
+const SVIX_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const SVIX_TIMESTAMP = /^\d{1,12}$/;
+
+export interface SvixHeaders {
+  readonly id: string | null;
+  readonly timestamp: string | null;
+  readonly signature: string | null;
+}
+
+/** The key bytes of a `whsec_<base64>` secret — synchronous, so a bad one is refused at construction. */
+export function svixSecretBytes(secret: string): Uint8Array<ArrayBuffer> {
+  const encoded = secret.replace(SECRET_PREFIX, '');
+  let bytes: Uint8Array<ArrayBuffer> | undefined;
+  try {
+    bytes = Uint8Array.from(atob(encoded), (char) => char.charCodeAt(0));
+  } catch {
+    bytes = undefined;
+  }
+  if (bytes === undefined || bytes.byteLength < 16) {
+    throw new ConfigInvalidError({
+      cause:
+        'the Resend webhook secret is not a whsec_<base64> signing secret of at least 16 bytes',
+      fix: "resendEventReceiver({ secret: env.RESEND_WEBHOOK_SECRET }) — with the endpoint's whsec_ signing secret from https://resend.com/webhooks",
+    });
+  }
+  return bytes;
+}
+
+export function svixKey(bytes: Uint8Array<ArrayBuffer>): Promise<CryptoKey> {
+  return crypto.subtle.importKey('raw', bytes, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+}
+
+function base64(bytes: ArrayBuffer): string {
+  let binary = '';
+  for (const byte of new Uint8Array(bytes)) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** Every `v1` mac in the header. Other versions are skipped, as Svix's own verifier does. */
+function v1Signatures(header: string): readonly string[] {
+  return header
+    .split(' ')
+    .filter((entry) => entry.startsWith('v1,'))
+    .map((entry) => entry.slice(3));
+}
+
+export interface SvixVerifyOptions {
+  readonly key: CryptoKey;
+  readonly toleranceMs: number;
+  readonly clock?: Clock | undefined;
+}
+
+/** Resolves when the delivery is authentic and fresh; rejects `X_MAIL_EVENT_UNVERIFIED` otherwise. */
+export async function verifySvix(
+  headers: SvixHeaders,
+  body: string,
+  options: SvixVerifyOptions,
+): Promise<{ readonly eventId: string }> {
+  const { id, timestamp, signature } = headers;
+  if (id === null || timestamp === null || signature === null) {
+    throw deliveryEventUnverified('resend', 'unsigned');
+  }
+  if (!SVIX_ID.test(id) || !SVIX_TIMESTAMP.test(timestamp)) {
+    throw deliveryEventUnverified('resend', 'signature');
+  }
+  const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
+  const expected = base64(await crypto.subtle.sign('HMAC', options.key, signed));
+  // Every entry is compared, with no early exit, so the position of the match leaks nothing.
+  let matched = false;
+  for (const candidate of v1Signatures(signature)) {
+    if (timingSafeEqual(candidate, expected)) matched = true;
+  }
+  if (!matched) throw deliveryEventUnverified('resend', 'signature');
+  const now = (options.clock ?? systemClock).now().getTime();
+  if (Math.abs(now - Number(timestamp) * 1000) > options.toleranceMs) {
+    throw deliveryEventUnverified('resend', 'stale');
+  }
+  return { eventId: id };
+}

package/src/retain-mime.ts

@@ -0,0 +1,142 @@
+// Single responsibility: keeping the exact MIME bytes a transport handed its provider, bounded. The
+// two transports that BUILD the message (SMTP, SES) call this once per accepted send; Resend builds
+// the MIME on its own side, so there are no bytes here to keep and its driver takes no such option.
+
+import { ConfigInvalidError, finiteCount, logger, renderThrowable } from '@ultimat3/core';
+import type { SendResult } from './driver';
+
+/**
+ * 256 KiB: a transactional mail with both parts is 5–60 KiB, so this keeps every message this
+ * package can render with room to spare, and a process holding a thousand results stays bounded.
+ */
+export const DEFAULT_RETAIN_MIME_MAX_BYTES = 262_144;
+
+/** The largest cap accepted. Above it a retained message is a memory decision, not an audit one. */
+export const RETAIN_MIME_CEILING_BYTES = 10_485_760;
+
+/**
+ * What was kept. Over the cap the bytes are DROPPED, never truncated — a truncated message is not
+ * the message that was sent, and an audit row claiming otherwise is worse than none. The digest and
+ * the length survive either way, so a copy recovered elsewhere can still be proven to be this one.
+ */
+export type RetainedMime =
+  | {
+      readonly kind: 'kept';
+      /** The RFC 5322 message before SMTP dot-stuffing and before any transfer encoding. */
+      readonly raw: string;
+      readonly byteLength: number;
+      readonly sha256: string;
+    }
+  | {
+      readonly kind: 'digest-only';
+      readonly byteLength: number;
+      readonly sha256: string;
+      /** The cap it exceeded. */
+      readonly maxBytes: number;
+    };
+
+/** One accepted send's retained bytes, with the ids an audit row is keyed on. */
+export interface RetainedMimeEntry {
+  readonly mailId: string;
+  /** `SendResult.id` — the provider's id, which is what a `DeliveryEvent.messageId` carries. */
+  readonly id: string;
+  readonly driver: string;
+  readonly idempotencyKey: string;
+  readonly mime: RetainedMime;
+}
+
+export interface RetainMimeOptions {
+  /** Default `DEFAULT_RETAIN_MIME_MAX_BYTES`; 1 to `RETAIN_MIME_CEILING_BYTES`. */
+  readonly maxBytes?: number | undefined;
+  /**
+   * The durable half. `SendResult.mime` reaches an inline caller only — a QUEUED send's result is
+   * the job run's return value, which the queue does not persist — so the row an auditor reads is
+   * written here. Called and NOT awaited; a throw is logged (`mail.retain_mime.failed`) and does
+   * NOT fail the send: the message already left, and failing it would have the job send it again.
+   */
+  readonly onRetained?: ((entry: RetainedMimeEntry) => void | Promise<void>) | undefined;
+}
+
+/**
+ * Refused at construction, where every other driver option is, and never on the first send — and
+ * by `selectMailDriver` before it picks a transport, so the ceiling is one verdict whatever env
+ * selects. `key` is where the option was written, named in the refusal: `retainMime` for a call,
+ * `mail.retainMime` when a boot read it from `app.config.ts`.
+ */
+export function resolveRetainMime(
+  driver: string,
+  options: RetainMimeOptions | undefined,
+  key = 'retainMime',
+): RetainMimeOptions | undefined {
+  if (options === undefined) return undefined;
+  const maxBytes = finiteCount(
+    driver,
+    `${key}.maxBytes`,
+    options.maxBytes ?? DEFAULT_RETAIN_MIME_MAX_BYTES,
+    1,
+  );
+  if (maxBytes > RETAIN_MIME_CEILING_BYTES) {
+    throw new ConfigInvalidError({
+      cause: `${driver} ${key}.maxBytes is ${maxBytes}, above the ${RETAIN_MIME_CEILING_BYTES}-byte ceiling a retained message may hold`,
+      fix: `${key}: { maxBytes: ${DEFAULT_RETAIN_MIME_MAX_BYTES} } — or drop maxBytes for that default`,
+      meta: { driver, key: `${key}.maxBytes` },
+    });
+  }
+  return { maxBytes, onRetained: options.onRetained };
+}
+
+const encoder = new TextEncoder();
+
+/** The bytes as kept, or their digest alone when they exceed the cap. */
+export function retainedMime(raw: string, maxBytes: number): RetainedMime {
+  const bytes = encoder.encode(raw);
+  const sha256 = new Bun.CryptoHasher('sha256').update(bytes).digest('hex');
+  return bytes.byteLength <= maxBytes
+    ? { kind: 'kept', raw, byteLength: bytes.byteLength, sha256 }
+    : { kind: 'digest-only', byteLength: bytes.byteLength, sha256, maxBytes };
+}
+
+/**
+ * Retain, hand the entry to the sink WITHOUT awaiting it, and answer what goes on `SendResult.mime`.
+ * Fire-and-forget, as `@ultimat3/mcp`'s audit hook is: the provider already accepted the message,
+ * and a sink that never settles would hold the job unsettled until its lease was reclaimed and the
+ * mail sent again. A throw, synchronous or rejected, is logged and never reaches the send.
+ */
+export function keepMime(
+  options: RetainMimeOptions,
+  raw: string,
+  entry: Omit<RetainedMimeEntry, 'mime'>,
+): RetainedMime {
+  const mime = retainedMime(raw, options.maxBytes ?? DEFAULT_RETAIN_MIME_MAX_BYTES);
+  const sink = options.onRetained;
+  if (sink !== undefined) {
+    Promise.resolve()
+      .then(() => sink({ ...entry, mime }))
+      .catch((error: unknown) => {
+        logger.warn('mail.retain_mime.failed', {
+          mailId: entry.mailId,
+          driver: entry.driver,
+          id: entry.id,
+          reason: renderThrowable(error),
+        });
+      });
+  }
+  return mime;
+}
+
+/** `result` with `mime` attached when retention is on; the same object when it is off. */
+export function withRetainedMime(
+  options: RetainMimeOptions | undefined,
+  result: SendResult,
+  mailId: string,
+  raw: string,
+): SendResult {
+  if (options === undefined) return result;
+  const mime = keepMime(options, raw, {
+    mailId,
+    id: result.id,
+    driver: result.driver,
+    idempotencyKey: result.idempotencyKey,
+  });
+  return { ...result, mime };
+}