@ultimat3/mail 23.0.0 → 25.0.0

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

package/src/x509-spki.ts

@@ -0,0 +1,67 @@
+// Single responsibility: the public key out of a PEM X.509 certificate, as the SubjectPublicKeyInfo
+// bytes Web Crypto imports (`importKey('spki', …)`). Web Crypto takes no certificate, so this walks
+// just enough DER to find the seventh field of `tbsCertificate` (RFC 5280 §4.1). Malformed input is
+// `undefined`, never a throw: the bytes came off a network.
+
+interface Tlv {
+  readonly tag: number;
+  /** Offset of the tag byte. */
+  readonly start: number;
+  /** Offset of the first content byte. */
+  readonly body: number;
+  /** Offset one past the last content byte. */
+  readonly end: number;
+}
+
+const SEQUENCE = 0x30;
+const VERSION = 0xa0;
+/** `serialNumber`, `signature`, `issuer`, `validity`, `subject` — skipped to reach the key. */
+const FIELDS_BEFORE_KEY = 5;
+
+/** One DER tag-length-value at `at`, bounded by `limit`. Definite lengths only, as DER requires. */
+function readTlv(bytes: Uint8Array, at: number, limit: number): Tlv | undefined {
+  if (at + 2 > limit) return undefined;
+  const tag = bytes[at] ?? 0;
+  const first = bytes[at + 1] ?? 0;
+  let body = at + 2;
+  let length = first;
+  if (first & 0x80) {
+    const count = first & 0x7f;
+    if (count === 0 || count > 4 || body + count > limit) return undefined;
+    length = 0;
+    for (let index = 0; index < count; index += 1)
+      length = length * 256 + (bytes[body + index] ?? 0);
+    body += count;
+  }
+  const end = body + length;
+  return end > limit ? undefined : { tag, start: at, body, end };
+}
+
+/** The DER inside the first `CERTIFICATE` block, or `undefined` for anything else. */
+export function pemCertificateDer(pem: string): Uint8Array | undefined {
+  const match = /-----BEGIN CERTIFICATE-----([A-Za-z0-9+/=\s]+)-----END CERTIFICATE-----/.exec(pem);
+  if (match === null) return undefined;
+  try {
+    const binary = atob((match[1] ?? '').replace(/\s+/g, ''));
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+  } catch {
+    return undefined;
+  }
+}
+
+/** `Certificate → tbsCertificate → subjectPublicKeyInfo`, the whole element, tag included. */
+export function certificateSpki(der: Uint8Array): Uint8Array | undefined {
+  const certificate = readTlv(der, 0, der.byteLength);
+  if (certificate?.tag !== SEQUENCE) return undefined;
+  const tbs = readTlv(der, certificate.body, certificate.end);
+  if (tbs?.tag !== SEQUENCE) return undefined;
+  let field = readTlv(der, tbs.body, tbs.end);
+  // `[0] EXPLICIT version` is absent on a v1 certificate and present on every v3 one.
+  if (field?.tag === VERSION) field = readTlv(der, field.end, tbs.end);
+  for (let skipped = 0; skipped < FIELDS_BEFORE_KEY; skipped += 1) {
+    if (field === undefined) return undefined;
+    field = readTlv(der, field.end, tbs.end);
+  }
+  if (field?.tag !== SEQUENCE) return undefined;
+  return der.slice(field.start, field.end);
+}