@ultimat3/mail 23.0.0 → 25.0.0

package/src/render.ts

@@ -3,7 +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 { 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
@@ -13,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 { escapeHtml, 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. */
@@ -75,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 };
@@ -92,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}`);
@@ -162,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 };
+}

package/src/ses-event-receiver.ts

@@ -0,0 +1,141 @@
+// Single responsibility: the `api/` route half of SES delivery notifications. Read the capped
+// body, prove SNS signed it for one of this app's topics (`sns-signature.ts`), then hand the
+// notification to `delivery-event-ses.ts`. A SubscriptionConfirmation is answered with its confirm
+// URL, and that URL is fetched only when the receiver was built with `confirmSubscriptions: true`.
+
+import {
+  type Clock,
+  ConfigInvalidError,
+  finiteCount,
+  readWithinLimit,
+  renderThrowable,
+} from '@ultimat3/core';
+import {
+  type DeliveryOutcome,
+  type DeliveryReceiver,
+  parseDeliveryJson,
+  readDeliveryBody,
+  resolveBodyLimit,
+} from './delivery-event';
+import { deliveryEventInvalid, deliveryProviderUnreachable } from './delivery-event-errors';
+import { sesDeliveryEvents } from './delivery-event-ses';
+import type { MailFetch } from './driver-resend';
+import { createSnsCertificateCache } from './sns-certificate-cache';
+import {
+  isPinnedSubscribeUrl,
+  type SnsCertificateFetch,
+  type SnsMessage,
+  snsTopicRegion,
+  verifySnsMessage,
+} from './sns-signature';
+
+/**
+ * One hour, either way. SNS's default HTTP retry policy redelivers within a minute; a custom
+ * delivery policy can stretch that, and `toleranceMs` is the knob for a topic that does.
+ */
+export const DEFAULT_SNS_TOLERANCE_MS = 3_600_000;
+
+const PROVIDER_TIMEOUT_MS = 5_000;
+const CERTIFICATE_MAX_BYTES = 16_384;
+
+export interface SesEventReceiverOptions {
+  /** The topic ARNs this route is subscribed to. Required: SNS signs for ANY account's topic. */
+  readonly topicArns: readonly string[];
+  /** GET the SubscribeURL of a verified SubscriptionConfirmation. Off: the URL is returned. */
+  readonly confirmSubscriptions?: boolean | undefined;
+  /** Default `DEFAULT_SNS_TOLERANCE_MS`. */
+  readonly toleranceMs?: number | undefined;
+  /** Default `DEFAULT_DELIVERY_BODY_LIMIT`. */
+  readonly maxBytes?: number | undefined;
+  readonly clock?: Clock | undefined;
+  /** Certificate download. Default: a GET over pinned https, no redirects, 5 s, 16 KiB. */
+  readonly fetchCertificate?: SnsCertificateFetch | undefined;
+  /** The subscription-confirm GET, and the default certificate download. Default: global fetch. */
+  readonly fetch?: MailFetch | undefined;
+}
+
+/** The default download: pinned https, no redirect (a redirect would leave the pinned host). */
+function defaultCertificateFetch(fetch: MailFetch): SnsCertificateFetch {
+  return async (url) => {
+    const response = await fetch(url, {
+      method: 'GET',
+      redirect: 'error',
+      signal: AbortSignal.timeout(PROVIDER_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw deliveryProviderUnreachable('certificate', `HTTP ${response.status}`);
+    }
+    const read = await readWithinLimit(response.body, CERTIFICATE_MAX_BYTES);
+    if ('over' in read)
+      throw deliveryProviderUnreachable('certificate', 'the answer was too large');
+    return new TextDecoder().decode(read.bytes);
+  };
+}
+
+export function sesEventReceiver(options: SesEventReceiverOptions): DeliveryReceiver {
+  const topicArns = new Set(options.topicArns);
+  if (topicArns.size === 0 || [...topicArns].some((arn) => snsTopicRegion(arn) === undefined)) {
+    throw deliveryEventConfig();
+  }
+  const maxBytes = resolveBodyLimit('sesEventReceiver', options.maxBytes);
+  const toleranceMs = finiteCount(
+    'sesEventReceiver',
+    'toleranceMs',
+    options.toleranceMs ?? DEFAULT_SNS_TOLERANCE_MS,
+    1,
+  );
+  const doFetch: MailFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const verify = {
+    topicArns,
+    toleranceMs,
+    clock: options.clock,
+    certificates: createSnsCertificateCache({
+      fetchCertificate: options.fetchCertificate ?? defaultCertificateFetch(doFetch),
+      clock: options.clock,
+    }),
+  };
+
+  return {
+    async receive(request) {
+      const body = await readDeliveryBody('ses', request, maxBytes);
+      const message = await verifySnsMessage(parseDeliveryJson('ses', body), verify);
+      if (message.Type === 'Notification')
+        return sesDeliveryEvents(message.Message, message.MessageId);
+      if (message.Type === 'UnsubscribeConfirmation') {
+        return { type: 'ignored', eventType: 'UnsubscribeConfirmation' };
+      }
+      return await subscription(message);
+    },
+  };
+
+  async function subscription(message: SnsMessage): Promise<DeliveryOutcome> {
+    const confirmUrl = message.SubscribeURL ?? '';
+    const region = snsTopicRegion(message.TopicArn) ?? '';
+    // Signed, and pinned anyway: the URL is fetched by THIS host when confirming is on.
+    if (!isPinnedSubscribeUrl(confirmUrl, region)) throw deliveryEventInvalid('ses', 'envelope');
+    if (options.confirmSubscriptions !== true) {
+      return { type: 'subscription', topicArn: message.TopicArn, confirmUrl, confirmed: false };
+    }
+    let response: Response;
+    try {
+      response = await doFetch(confirmUrl, {
+        method: 'GET',
+        redirect: 'error',
+        signal: AbortSignal.timeout(PROVIDER_TIMEOUT_MS),
+      });
+    } catch (error) {
+      throw deliveryProviderUnreachable('subscription', renderThrowable(error));
+    }
+    await response.body?.cancel();
+    if (!response.ok) throw deliveryProviderUnreachable('subscription', `HTTP ${response.status}`);
+    return { type: 'subscription', topicArn: message.TopicArn, confirmUrl, confirmed: true };
+  }
+}
+
+function deliveryEventConfig(): ConfigInvalidError {
+  return new ConfigInvalidError({
+    cause: 'sesEventReceiver needs at least one topic ARN, and every one must be an SNS topic ARN',
+    fix: "sesEventReceiver({ topicArns: ['arn:aws:sns:us-east-1:123456789012:ses-events'] }) — the topics this route is subscribed to (aws sns list-topics)",
+  });
+}

package/src/ses-failure.ts

@@ -0,0 +1,114 @@
+// Single responsibility: an SES v2 error response → the retry verdict and the `fix:` line. SES
+// names its failure in a TYPE (`x-amzn-ErrorType`, or `__type` in the body) far more precisely than
+// its status does — `MessageRejected`, `SendingPausedException` and a bad request are all 400 — so
+// the type decides, and core's status table answers only for a type this table does not know.
+
+import { isRetryableStatus } from '@ultimat3/core';
+
+/** What the driver needs to build `sendFailed(...)`: the verdict, the fix, and the text to show. */
+export interface SesFailure {
+  readonly type: string | undefined;
+  readonly retryable: boolean;
+  readonly fix: string;
+  readonly detail: string;
+}
+
+type SesClass =
+  | 'throttled'
+  | 'rejected'
+  | 'invalid'
+  | 'paused'
+  | 'unverified'
+  | 'credentials'
+  | 'missing';
+
+/** Every SES (v1 and v2 spellings) and AWS-auth type this driver distinguishes. */
+const CLASS_OF: ReadonlyMap<string, SesClass> = new Map([
+  ['TooManyRequestsException', 'throttled'],
+  ['ThrottlingException', 'throttled'],
+  ['Throttling', 'throttled'],
+  ['LimitExceededException', 'throttled'],
+  ['MessageRejected', 'rejected'],
+  ['BadRequestException', 'invalid'],
+  ['SendingPausedException', 'paused'],
+  ['AccountSendingPausedException', 'paused'],
+  ['AccountSuspendedException', 'paused'],
+  ['MailFromDomainNotVerifiedException', 'unverified'],
+  ['UnrecognizedClientException', 'credentials'],
+  ['InvalidClientTokenId', 'credentials'],
+  ['InvalidSignatureException', 'credentials'],
+  ['SignatureDoesNotMatch', 'credentials'],
+  ['IncompleteSignature', 'credentials'],
+  ['MissingAuthenticationToken', 'credentials'],
+  ['ExpiredTokenException', 'credentials'],
+  ['ExpiredToken', 'credentials'],
+  ['AccessDeniedException', 'credentials'],
+  ['AccessDenied', 'credentials'],
+  ['NotFoundException', 'missing'],
+]);
+
+/** Only throttling clears by waiting; every other class is the same answer on the next attempt. */
+const RETRYABLE: ReadonlySet<SesClass> = new Set<SesClass>(['throttled']);
+
+const MAX_DETAIL_LENGTH = 200;
+
+function fixFor(kind: SesClass | undefined, region: string): string {
+  switch (kind) {
+    case 'throttled':
+      return `aws sesv2 get-account --region ${region} — the job already retries with backoff; raise the quota if this repeats`;
+    case 'rejected':
+      return `aws sesv2 get-email-identity --region ${region} --email-identity <your sending domain> — verify the From identity, and read SES's reason in the cause`;
+    case 'paused':
+      return `aws sesv2 put-account-sending-attributes --region ${region} --sending-enabled — after fixing why SES paused sending (aws sesv2 get-account)`;
+    case 'unverified':
+      return `aws sesv2 get-email-identity --region ${region} --email-identity <your sending domain> — publish the custom MAIL FROM domain's MX and SPF records it lists`;
+    case 'credentials':
+      return 'aws sts get-caller-identity — then set SES_ACCESS_KEY_ID and SES_SECRET_ACCESS_KEY to a key allowed ses:SendEmail, and sync this host clock if SES said the signature expired';
+    case 'missing':
+      return `aws sesv2 list-configuration-sets --region ${region} — create the set SES_CONFIGURATION_SET names, or unset it`;
+    default:
+      return 'curl -sS https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html — check the request against the SendEmail reference';
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** `MessageRejected:http://internal.amazon.com/…` or `com.amazonaws.ses#MessageRejected` → the name. */
+function typeName(raw: string): string | undefined {
+  const name = (raw.split(':')[0] ?? '').split('#').pop()?.trim() ?? '';
+  return /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name) ? name : undefined;
+}
+
+function bodyField(body: unknown, ...keys: readonly string[]): string | undefined {
+  if (!isRecord(body)) return undefined;
+  for (const key of keys) {
+    const value = body[key];
+    if (typeof value === 'string' && value !== '') return value;
+  }
+  return undefined;
+}
+
+/** Reads the response once; a body that is not JSON still yields a capped, printable detail. */
+export async function sesFailure(response: Response, region: string): Promise<SesFailure> {
+  const text = await response.text().catch(() => '');
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = undefined;
+  }
+  const header = response.headers.get('x-amzn-errortype');
+  const raw = header ?? bodyField(body, '__type', 'code', 'Code');
+  const type = raw === undefined ? undefined : typeName(raw);
+  const kind = type === undefined ? undefined : CLASS_OF.get(type);
+  const message = bodyField(body, 'message', 'Message') ?? (text === '' ? 'an empty body' : text);
+  const said = `${type ?? `HTTP ${response.status}`}: ${message}`;
+  return {
+    type,
+    retryable: kind === undefined ? isRetryableStatus(response.status) : RETRYABLE.has(kind),
+    fix: fixFor(kind, region),
+    detail: said.length > MAX_DETAIL_LENGTH ? `${said.slice(0, MAX_DETAIL_LENGTH)}…` : said,
+  };
+}

package/src/smtp-client.ts

@@ -161,7 +161,7 @@ class Conversation {
             stage,
             detail: `the server sent nothing for ${timeoutMs}ms, so the read deadline expired`,
             retryable: true,
-            fix: 'pass timeoutMs: 60_000 to createSmtpDriver() in app.config.ts',
+            fix: 'pass timeoutMs: 60_000 to smtpMailDriver() in app.config.ts',
           }),
         );
       }, timeoutMs);
@@ -176,7 +176,7 @@ class Conversation {
             'the server closed the connection mid-conversation, which is usually it ' +
             'rate-limiting the sessions it keeps open at once',
           retryable: true,
-          fix: 'pass poolSize: 1 to createSmtpDriver() in app.config.ts',
+          fix: 'pass poolSize: 1 to smtpMailDriver() in app.config.ts',
         });
       }
       return chunk;
@@ -230,7 +230,7 @@ export async function smtpDeliver(
       stage: 'starttls',
       detail:
         'the server does not advertise STARTTLS and the connection is not already TLS; ' +
-        'allowInsecure: true on createSmtpDriver() would send this in the clear instead',
+        'allowInsecure: true on smtpMailDriver() would send this in the clear instead',
       retryable: false,
       fix: FIXES['starttls'] ?? 'set SMTP_URL in .env to smtps://host:465',
     });