@ultimat3/mail 24.0.0 → 25.1.0

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',
     });

package/src/smtp-socket.ts

@@ -204,7 +204,7 @@ export function smtpStreamOver(runtime: BunConnect, target: SmtpTarget): Promise
               stage: 'data',
               detail: `the socket stopped accepting bytes for ${target.timeoutMs}ms`,
               retryable: true,
-              fix: 'pass timeoutMs: 60_000 to createSmtpDriver() in app.config.ts',
+              fix: 'pass timeoutMs: 60_000 to smtpMailDriver() in app.config.ts',
             }),
           );
         }, target.timeoutMs);

package/src/sns-certificate-cache.ts

@@ -0,0 +1,111 @@
+// Single responsibility: the SNS signing certificates a receiver has downloaded, bounded against a
+// sender who forges messages. Any pinned URL reaches the download BEFORE a signature is checked,
+// and an allowed topic ARN is not a secret, so a forger can name a fresh path per request. Four
+// bounds hold that to a fixed cost: LRU positives, a negative TTL, an in-flight cap, coalescing.
+
+import { type Clock, isUltimateError, renderThrowable, systemClock } from '@ultimat3/core';
+import { deliveryProviderUnreachable } from './delivery-event-errors';
+import { certificateSpki, pemCertificateDer } from './x509-spki';
+
+/** PEM text for a certificate URL. Injected in tests; production GETs it over pinned https. */
+export type SnsCertificateFetch = (url: string) => Promise<string>;
+
+/** SNS uses a handful of certificates per region; eight keeps every live one with room to rotate. */
+const MAX_CERTIFICATES = 8;
+/** Downloads at once. A flood waits on nothing: past this it is refused with a 503 SNS retries. */
+const MAX_IN_FLIGHT = 2;
+/** How long a URL that failed to download is answered from memory instead of fetched again. */
+const NEGATIVE_TTL_MS = 300_000;
+/** Remembered failures. Bounded too, or the negative cache is the next thing to flood. */
+const MAX_FAILURES = 256;
+
+export interface SnsCertificateCache {
+  /** The SPKI for a pinned certificate URL — cached, coalesced, or refused. */
+  spkiFor(url: string): Promise<Uint8Array<ArrayBuffer>>;
+}
+
+export interface SnsCertificateCacheOptions {
+  readonly fetchCertificate: SnsCertificateFetch;
+  readonly clock?: Clock | undefined;
+}
+
+export function createSnsCertificateCache(
+  options: SnsCertificateCacheOptions,
+): SnsCertificateCache {
+  const clock = options.clock ?? systemClock;
+  // Insertion order is recency order: a hit is deleted and re-set, so the first key is the LRU.
+  const verified = new Map<string, Uint8Array<ArrayBuffer>>();
+  const failedUntil = new Map<string, number>();
+  const inFlight = new Map<string, Promise<Uint8Array<ArrayBuffer>>>();
+
+  const remember = <V>(map: Map<string, V>, key: string, value: V, max: number): void => {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > max) {
+      const oldest = map.keys().next().value;
+      if (oldest !== undefined) map.delete(oldest);
+    }
+  };
+
+  async function download(url: string): Promise<Uint8Array<ArrayBuffer>> {
+    let pem: string;
+    try {
+      pem = await options.fetchCertificate(url);
+    } catch (error) {
+      // The default download already names its failure; an injected one may throw anything.
+      if (isUltimateError(error)) throw error;
+      throw deliveryProviderUnreachable('certificate', renderThrowable(error));
+    }
+    const der = pemCertificateDer(pem);
+    const spki = der === undefined ? undefined : certificateSpki(der);
+    if (spki === undefined) {
+      throw deliveryProviderUnreachable(
+        'certificate',
+        'the answer was not a PEM X.509 certificate',
+      );
+    }
+    return new Uint8Array(spki);
+  }
+
+  return {
+    spkiFor(url) {
+      const hit = verified.get(url);
+      if (hit !== undefined) {
+        remember(verified, url, hit, MAX_CERTIFICATES);
+        return Promise.resolve(hit);
+      }
+      const pending = inFlight.get(url);
+      if (pending !== undefined) return pending;
+      const now = clock.monotonic();
+      const until = failedUntil.get(url);
+      if (until !== undefined && now < until) {
+        return Promise.reject(
+          deliveryProviderUnreachable('certificate', 'this URL failed to download moments ago'),
+        );
+      }
+      if (inFlight.size >= MAX_IN_FLIGHT) {
+        return Promise.reject(
+          deliveryProviderUnreachable('certificate', 'too many certificate downloads in flight'),
+        );
+      }
+      const started = download(url).then(
+        (spki) => {
+          failedUntil.delete(url);
+          remember(verified, url, spki, MAX_CERTIFICATES);
+          return spki;
+        },
+        (error: unknown) => {
+          remember(failedUntil, url, clock.monotonic() + NEGATIVE_TTL_MS, MAX_FAILURES);
+          throw error;
+        },
+      );
+      inFlight.set(url, started);
+      // `finally` on a branch whose rejection is observed by the caller, never left unhandled.
+      started.then(
+        () => inFlight.delete(url),
+        () => inFlight.delete(url),
+      );
+      return started;
+    },
+  };
+}

package/src/sns-signature.ts

@@ -0,0 +1,187 @@
+// Single responsibility: prove an Amazon SNS HTTP(S) message was signed by SNS for a topic this
+// app owns. The AWS-documented procedure: the topic first (any AWS account can make SNS sign for
+// ITS topic), the certificate URL pinned to `https://sns.<topic region>.amazonaws.com`, the
+// canonical string per message type, RSA-SHA1 (v1) or RSA-SHA256 (v2) through Web Crypto.
+
+import { type Clock, systemClock } from '@ultimat3/core';
+import { t, validate } from '@ultimat3/schema';
+import { deliveryInstant } from './delivery-event';
+import { deliveryEventInvalid, deliveryEventUnverified } from './delivery-event-errors';
+import type { SnsCertificateCache } from './sns-certificate-cache';
+
+/** The envelope fields the signature covers, plus the three that say how it was signed. */
+export interface SnsMessage {
+  readonly Type: 'Notification' | 'SubscriptionConfirmation' | 'UnsubscribeConfirmation';
+  readonly MessageId: string;
+  readonly TopicArn: string;
+  readonly Message: string;
+  readonly Timestamp: string;
+  readonly Subject?: string | undefined;
+  readonly SubscribeURL?: string | undefined;
+  readonly Token?: string | undefined;
+  readonly SignatureVersion: string;
+  readonly Signature: string;
+  readonly SigningCertURL: string;
+}
+
+export type { SnsCertificateFetch } from './sns-certificate-cache';
+
+const envelope = t.object({
+  Type: t.enum(['Notification', 'SubscriptionConfirmation', 'UnsubscribeConfirmation']),
+  MessageId: t.string,
+  TopicArn: t.string,
+  Message: t.string,
+  Timestamp: t.string,
+  Subject: t.string.optional(),
+  SubscribeURL: t.string.optional(),
+  Token: t.string.optional(),
+  SignatureVersion: t.string.optional(),
+  Signature: t.string.optional(),
+  SigningCertURL: t.string.optional(),
+});
+
+/** `arn:aws:sns:<region>:<account>:<name>` — the region is what the certificate host is pinned to. */
+const TOPIC_ARN =
+  /^arn:aws(?:-us-gov)?:sns:([a-z]{2}(?:-[a-z]+)+-\d{1,2}):\d{12}:[A-Za-z0-9_-]{1,256}(?:\.fifo)?$/;
+
+/** AWS's documented key order, per message type. `Subject` is signed only when present. */
+const CONFIRMATION_KEYS: readonly (keyof SnsMessage)[] = [
+  'Message',
+  'MessageId',
+  'SubscribeURL',
+  'Timestamp',
+  'Token',
+  'TopicArn',
+  'Type',
+];
+/** A Map: `Type` came off the wire, and an object table answers `constructor` from its prototype. */
+const SIGNED_KEYS: ReadonlyMap<SnsMessage['Type'], readonly (keyof SnsMessage)[]> = new Map([
+  ['Notification', ['Message', 'MessageId', 'Subject', 'Timestamp', 'TopicArn', 'Type']],
+  ['SubscriptionConfirmation', CONFIRMATION_KEYS],
+  ['UnsubscribeConfirmation', CONFIRMATION_KEYS],
+]);
+
+/** `SignatureVersion` is a wire value: `"constructor"` must find nothing here. */
+const HASH_OF: ReadonlyMap<string, 'SHA-1' | 'SHA-256'> = new Map([
+  ['1', 'SHA-1'],
+  ['2', 'SHA-256'],
+]);
+
+/** `"Key\nValue\n"` for each signed key present, in the documented order. */
+export function snsCanonicalString(message: SnsMessage): string {
+  let canonical = '';
+  for (const key of SIGNED_KEYS.get(message.Type) ?? []) {
+    const value = message[key];
+    if (value !== undefined) canonical += `${key}\n${value}\n`;
+  }
+  return canonical;
+}
+
+/** The region of an ARN this module accepts, or `undefined` for one it does not. */
+export function snsTopicRegion(topicArn: string): string | undefined {
+  return TOPIC_ARN.exec(topicArn)?.[1];
+}
+
+/** The only path SNS serves a signing certificate from. */
+/** `SimpleNotificationService-<32 lower-case hex>.pem` — the form every published SigningCertURL takes. */
+const CERT_PATH = /^\/SimpleNotificationService-[0-9a-f]{32}\.pem$/;
+
+/**
+ * A signing-certificate URL in its ONE spelling: `https://sns.<region>.amazonaws.com/SimpleNotificationService-<hex>.pem`,
+ * compared as a string against what the parse normalises it to. Every alias of one URL — a
+ * fragment, `:443`, a bare `?`, `\` for `/`, an upper-case or full-width host — is refused rather
+ * than normalised, so one certificate has one cache key. That does NOT stop a forger who knows an
+ * allowed topic from naming a new `<hex>` per request — every one passes here and reaches the
+ * download before any signature is checked. `sns-certificate-cache.ts` is what bounds that cost.
+ */
+export function isPinnedCertificateUrl(raw: string, region: string): boolean {
+  const url = URL.parse(raw);
+  if (url === null || !CERT_PATH.test(url.pathname)) return false;
+  return raw === `https://sns.${region}.amazonaws.com${url.pathname}`;
+}
+
+/** A SubscribeURL: the pinned origin, path `/`, a query, no fragment, no userinfo, no port. */
+export function isPinnedSubscribeUrl(raw: string, region: string): boolean {
+  const url = URL.parse(raw);
+  if (url === null || url.hash !== '' || url.pathname !== '/' || url.search === '') return false;
+  return raw.startsWith(`https://sns.${region}.amazonaws.com/?`);
+}
+
+function base64Bytes(text: string): Uint8Array<ArrayBuffer> | undefined {
+  try {
+    return Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+  } catch {
+    return undefined;
+  }
+}
+
+export interface SnsVerifyOptions {
+  /** Every topic this app subscribed this route to. Anything else is refused before any fetch. */
+  readonly topicArns: ReadonlySet<string>;
+  readonly toleranceMs: number;
+  readonly clock?: Clock | undefined;
+  /** Downloaded certificates, bounded against forgery floods. The receiver owns one. */
+  readonly certificates: SnsCertificateCache;
+}
+
+/** Parse, pin, fetch, verify, then check the clock — and answer the message that was signed. */
+export async function verifySnsMessage(
+  parsed: unknown,
+  options: SnsVerifyOptions,
+): Promise<SnsMessage> {
+  const result = validate(envelope, parsed);
+  if (result.issues !== undefined) throw deliveryEventInvalid('ses', 'envelope');
+  const fields = result.value;
+  const { Signature: signature, SigningCertURL: certUrl, SignatureVersion: version } = fields;
+  if (signature === undefined || certUrl === undefined || version === undefined) {
+    throw deliveryEventUnverified('ses', 'unsigned');
+  }
+  if (!options.topicArns.has(fields.TopicArn)) throw deliveryEventUnverified('ses', 'topic');
+  const region = snsTopicRegion(fields.TopicArn);
+  if (region === undefined || !isPinnedCertificateUrl(certUrl, region)) {
+    throw deliveryEventUnverified('ses', 'certificate-url');
+  }
+  const hash = HASH_OF.get(version);
+  if (hash === undefined) throw deliveryEventUnverified('ses', 'signature-version');
+  const message: SnsMessage = {
+    ...fields,
+    SignatureVersion: version,
+    Signature: signature,
+    SigningCertURL: certUrl,
+  };
+
+  const signatureBytes = base64Bytes(signature);
+  const spki = await options.certificates.spkiFor(certUrl);
+  if (signatureBytes === undefined || !(await rsaVerifies(spki, hash, signatureBytes, message))) {
+    throw deliveryEventUnverified('ses', 'signature');
+  }
+  // After the signature, like `@ultimat3/http`'s receiver: "stale" then always means authentic.
+  const sentAt = deliveryInstant('ses', fields.Timestamp).getTime();
+  const now = (options.clock ?? systemClock).now().getTime();
+  if (Math.abs(now - sentAt) > options.toleranceMs) {
+    throw deliveryEventUnverified('ses', 'stale');
+  }
+  return message;
+}
+
+async function rsaVerifies(
+  spki: Uint8Array<ArrayBuffer>,
+  hash: 'SHA-1' | 'SHA-256',
+  signature: Uint8Array<ArrayBuffer>,
+  message: SnsMessage,
+): Promise<boolean> {
+  try {
+    const key = await crypto.subtle.importKey(
+      'spki',
+      spki,
+      { name: 'RSASSA-PKCS1-v1_5', hash },
+      false,
+      ['verify'],
+    );
+    const canonical = new TextEncoder().encode(snsCanonicalString(message));
+    return await crypto.subtle.verify('RSASSA-PKCS1-v1_5', key, signature, canonical);
+  } catch {
+    // A key Web Crypto will not import (not RSA) verifies nothing.
+    return false;
+  }
+}

package/src/transform.ts

@@ -3,6 +3,7 @@
 // every retry all carry the transformed bytes. An app adds an open pixel or rewrites its own links
 // here; the framework only guarantees WHEN it runs, what it sees, and that a failure never ships.
 
+import { stringField } from '@ultimat3/core';
 import type { MailMessage } from './driver';
 import { transformFailed } from './errors';
 import { assertHeaderSafe } from './header-safety';
@@ -98,11 +99,20 @@ function asRendered(value: unknown): MailRendered | undefined {
 
 /**
  * What KIND of value was thrown, from a closed list — never its message and never its `name`,
- * which are the app's strings and may carry a recipient address.
+ * which are the app's strings and may carry a recipient address. TOTAL, because it runs inside the
+ * catch that codes the failure: `instanceof` runs a `Proxy`'s `getPrototypeOf` trap and `.name` is a
+ * getter, and either throwing there escaped `send()` uncoded. `typeof` alone cannot throw.
  */
 const KNOWN_ERRORS = new Set(['Error', 'TypeError', 'RangeError', 'SyntaxError', 'ReferenceError']);
 
 function describe(error: unknown): string {
-  if (error instanceof Error) return KNOWN_ERRORS.has(error.name) ? error.name : 'an Error';
-  return typeof error;
+  let isError: boolean;
+  try {
+    isError = error instanceof Error;
+  } catch {
+    return typeof error;
+  }
+  if (!isError) return typeof error;
+  const name = stringField(error, 'name');
+  return name !== undefined && KNOWN_ERRORS.has(name) ? name : 'an Error';
 }