@c9up/rover 0.1.3

package/src/transports/SesTransport.ts

@@ -0,0 +1,394 @@
+import { Buffer } from "node:buffer";
+import { createHash, createHmac, randomBytes } from "node:crypto";
+import { RoverError } from "../RoverError.js";
+import {
+	type MailAttachment,
+	type MailMessage,
+	type MailSendOutcome,
+	type MailTransport,
+	registerTransport,
+} from "../Mail.js";
+import { wrapFetchNetworkError } from "./fetchError.js";
+
+const stripCrlf = (v: string): string => v.replace(/[\r\n]/g, "");
+const normalizeConfig = (v: string): string => stripCrlf(v).trim();
+/** RFC 2183: quote `"` and `\` inside filename="..." / name="..." parameters. */
+const mimeQuote = (v: string): string =>
+	stripCrlf(v).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+/**
+ * RFC 2047 encoded-word wrapping for non-ASCII header values.
+ * Returns the input as-is when it contains only ASCII; otherwise returns a
+ * base64 encoded-word (`=?UTF-8?B?...?=`). Safe for Subject, From, To display
+ * names, etc. — raw 8-bit in headers is non-conformant under RFC 5322.
+ */
+function encodeHeaderWord(v: string): string {
+	const stripped = stripCrlf(v);
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: matching non-ASCII explicitly (any byte > 0x7F is non-ASCII)
+	if (!/[^\x00-\x7F]/.test(stripped)) return stripped;
+	const b64 = Buffer.from(stripped, "utf8").toString("base64");
+	return `=?UTF-8?B?${b64}?=`;
+}
+const REGION_RE = /^[a-z0-9-]+$/;
+const MAX_PROVIDER_MESSAGE = 16 * 1024;
+const capMessage = (s: string): string =>
+	s.length <= MAX_PROVIDER_MESSAGE
+		? s
+		: `${s.slice(0, MAX_PROVIDER_MESSAGE)}...[truncated]`;
+/** Redact Basic/Bearer tokens if the upstream echoes our own request headers. */
+const redactSecrets = (s: string): string =>
+	s
+		.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/g, "Bearer [REDACTED]")
+		.replace(
+			/AWS4-HMAC-SHA256\s+Credential=[^,]+/g,
+			"AWS4-HMAC-SHA256 [REDACTED]",
+		);
+
+export class SesTransport implements MailTransport {
+	#accessKeyId: string;
+	#secretAccessKey: string;
+	#region: string;
+	#host: string;
+
+	constructor(config: Record<string, unknown>) {
+		const accessKeyId =
+			typeof config.accessKeyId === "string"
+				? normalizeConfig(config.accessKeyId)
+				: "";
+		const secretAccessKey =
+			typeof config.secretAccessKey === "string"
+				? normalizeConfig(config.secretAccessKey)
+				: "";
+		const rawRegion =
+			typeof config.region === "string"
+				? normalizeConfig(config.region).toLowerCase()
+				: "";
+		if (!accessKeyId || !secretAccessKey || !rawRegion) {
+			throw new RoverError(
+				"MAIL_PROVIDER_CONFIG",
+				"SES transport requires accessKeyId, secretAccessKey, and region",
+				{ hint: "Set all three in your mail config." },
+			);
+		}
+		if (!REGION_RE.test(rawRegion)) {
+			throw new RoverError(
+				"MAIL_PROVIDER_CONFIG",
+				`SES region "${rawRegion}" is not a valid AWS region identifier`,
+				{
+					hint: "Use the lowercase canonical form, e.g. 'us-east-1'. Uppercase breaks the SigV4 signing scope.",
+				},
+			);
+		}
+		this.#accessKeyId = accessKeyId;
+		this.#secretAccessKey = secretAccessKey;
+		this.#region = rawRegion;
+		this.#host = `email.${rawRegion}.amazonaws.com`;
+	}
+
+	async send(message: MailMessage): Promise<MailSendOutcome> {
+		if (
+			message.to.length === 0 &&
+			message.cc.length === 0 &&
+			message.bcc.length === 0
+		) {
+			throw new RoverError(
+				"MAIL_PROVIDER_CONFIG",
+				"Mail message has no recipients",
+				{ hint: "Set at least one `to`, `cc`, or `bcc` before sending." },
+			);
+		}
+
+		// Custom headers are only honoured on the SendRawEmail path (where we
+		// compose the MIME ourselves), so flip to raw whenever the message
+		// carries headers, even without attachments.
+		const useRaw =
+			message.attachments.length > 0 || Object.keys(message.headers).length > 0;
+		const form = useRaw
+			? buildRawEmailForm(message)
+			: buildSendEmailForm(message);
+
+		const url = `https://${this.#host}/`;
+		const headers = this.#signRequest("POST", form);
+		// Same network-error wrap as ResendTransport — see retry.ts for
+		// why undici's `cause.code` matters for retry classification.
+		let res: Response;
+		try {
+			res = await fetch(url, {
+				method: "POST",
+				headers,
+				body: form,
+			});
+		} catch (err) {
+			throw wrapFetchNetworkError("ses", err);
+		}
+		if (!res.ok) {
+			const providerMessage = redactSecrets(capMessage(await res.text()));
+			const retryAfter = res.headers.get("retry-after") ?? undefined;
+			const ctx: Record<string, string> = {
+				provider: "ses",
+				upstreamStatus: String(res.status),
+				providerMessage,
+			};
+			if (retryAfter) ctx.retryAfter = retryAfter;
+			throw new RoverError("MAIL_PROVIDER_ERROR", `SES returned ${res.status}`, {
+				hint: "Inspect `context.upstreamStatus` to decide retry eligibility. `context.retryAfter` (when set) carries the provider's backoff hint in seconds.",
+				context: ctx,
+			});
+		}
+		// SES XML success shape: <SendEmailResponse><SendEmailResult><MessageId>...
+		// or <SendRawEmailResult><MessageId>... — extract via a scoped regex.
+		try {
+			const xml = await res.text();
+			const match = xml.match(/<MessageId>([^<]+)<\/MessageId>/);
+			if (match?.[1]) return { providerId: match[1] };
+		} catch {
+			// Network truncation on success response is rare; fall back to generated id.
+		}
+		return;
+	}
+
+	/** SigV4 header signer, scoped to `ses`. Canonical request: POST / with form body. */
+	#signRequest(method: string, body: string): Record<string, string> {
+		const dateStamp = amzDateNow();
+		const shortDate = dateStamp.slice(0, 8);
+		const service = "ses";
+		const payloadHash = createHash("sha256").update(body).digest("hex");
+
+		const headers: Record<string, string> = {
+			host: this.#host,
+			"x-amz-date": dateStamp,
+			"content-type": "application/x-www-form-urlencoded",
+		};
+		const sortedKeys = Object.keys(headers).sort();
+		const signedHeaders = sortedKeys.join(";");
+		const canonicalHeaders = sortedKeys
+			.map((k) => `${k}:${headers[k]}\n`)
+			.join("");
+		const canonicalRequest = [
+			method,
+			"/",
+			"",
+			canonicalHeaders,
+			signedHeaders,
+			payloadHash,
+		].join("\n");
+
+		const scope = `${shortDate}/${this.#region}/${service}/aws4_request`;
+		const stringToSign = [
+			"AWS4-HMAC-SHA256",
+			dateStamp,
+			scope,
+			createHash("sha256").update(canonicalRequest).digest("hex"),
+		].join("\n");
+
+		const signingKey = deriveSigningKey(
+			this.#secretAccessKey,
+			shortDate,
+			this.#region,
+			service,
+		);
+		const signature = createHmac("sha256", signingKey)
+			.update(stringToSign)
+			.digest("hex");
+
+		headers.authorization = `AWS4-HMAC-SHA256 Credential=${this.#accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+		return headers;
+	}
+}
+
+function buildSendEmailForm(message: MailMessage): string {
+	const params: Array<[string, string]> = [];
+	params.push(["Action", "SendEmail"]);
+	params.push(["Source", stripCrlf(message.from)]);
+	message.to.forEach((addr, i) => {
+		params.push([`Destination.ToAddresses.member.${i + 1}`, stripCrlf(addr)]);
+	});
+	message.cc.forEach((addr, i) => {
+		params.push([`Destination.CcAddresses.member.${i + 1}`, stripCrlf(addr)]);
+	});
+	message.bcc.forEach((addr, i) => {
+		params.push([`Destination.BccAddresses.member.${i + 1}`, stripCrlf(addr)]);
+	});
+	if (message.replyTo) {
+		params.push(["ReplyToAddresses.member.1", stripCrlf(message.replyTo)]);
+	}
+	params.push(["Message.Subject.Data", stripCrlf(message.subject)]);
+	params.push(["Message.Subject.Charset", "UTF-8"]);
+	if (message.html) {
+		params.push(["Message.Body.Html.Data", message.html]);
+		params.push(["Message.Body.Html.Charset", "UTF-8"]);
+	}
+	if (message.text) {
+		params.push(["Message.Body.Text.Data", message.text]);
+		params.push(["Message.Body.Text.Charset", "UTF-8"]);
+	}
+	return params
+		.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+		.join("&");
+}
+
+function buildRawEmailForm(message: MailMessage): string {
+	const raw = buildRawMime(message);
+	const b64 = Buffer.from(raw).toString("base64");
+	// Targeted URL-escape: base64's alphabet is URL-safe *except* for `+` / `/`
+	// and the trailing `=` padding. Replacing only those three avoids walking
+	// the entire string character-by-character the way encodeURIComponent does.
+	const urlEncoded = b64.replace(/[+/=]/g, (c) =>
+		c === "+" ? "%2B" : c === "/" ? "%2F" : "%3D",
+	);
+	return `Action=SendRawEmail&RawMessage.Data=${urlEncoded}`;
+}
+
+function buildRawMime(message: MailMessage): string {
+	const parts: string[] = [];
+	parts.push(`From: ${encodeHeaderWord(message.from)}`);
+	parts.push(`To: ${message.to.map(encodeHeaderWord).join(", ")}`);
+	if (message.cc.length) {
+		parts.push(`Cc: ${message.cc.map(encodeHeaderWord).join(", ")}`);
+	}
+	if (message.replyTo)
+		parts.push(`Reply-To: ${encodeHeaderWord(message.replyTo)}`);
+	parts.push(`Subject: ${encodeHeaderWord(message.subject)}`);
+	parts.push("MIME-Version: 1.0");
+	const reserved = new Set([
+		"from",
+		"to",
+		"cc",
+		"bcc",
+		"subject",
+		"reply-to",
+		"mime-version",
+		"content-type",
+		"content-transfer-encoding",
+		"content-disposition",
+	]);
+	for (const [k, v] of Object.entries(message.headers)) {
+		if (reserved.has(k.toLowerCase())) continue;
+		parts.push(`${stripCrlf(k)}: ${encodeHeaderWord(v)}`);
+	}
+
+	const hasAttachments = message.attachments.length > 0;
+	const mixedBoundary = freshBoundary();
+
+	if (hasAttachments) {
+		parts.push(`Content-Type: multipart/mixed; boundary="${mixedBoundary}"`);
+		parts.push("");
+		parts.push(`--${mixedBoundary}`);
+		appendBodyBlock(parts, message);
+		for (const att of message.attachments) {
+			appendAttachmentPart(parts, mixedBoundary, att);
+		}
+		parts.push(`--${mixedBoundary}--`);
+	} else {
+		appendBodyHeadersInline(parts, message);
+	}
+	return parts.join("\r\n");
+}
+
+/**
+ * Emit the body block for the `multipart/mixed` first part. Handles three cases:
+ *   - both html and text set → `multipart/alternative` wrapping both
+ *   - html only → bare `text/html` part
+ *   - text only → bare `text/plain` part
+ *   - neither → bare `text/plain` empty part (keeps MIME valid when attachments only)
+ */
+function appendBodyBlock(parts: string[], message: MailMessage): void {
+	if (message.html && message.text) {
+		const altBoundary = freshBoundary();
+		parts.push(
+			`Content-Type: multipart/alternative; boundary="${altBoundary}"`,
+		);
+		parts.push("");
+		parts.push(`--${altBoundary}`);
+		parts.push("Content-Type: text/plain; charset=UTF-8");
+		parts.push("");
+		parts.push(message.text);
+		parts.push(`--${altBoundary}`);
+		parts.push("Content-Type: text/html; charset=UTF-8");
+		parts.push("");
+		parts.push(message.html);
+		parts.push(`--${altBoundary}--`);
+	} else if (message.html) {
+		parts.push("Content-Type: text/html; charset=UTF-8");
+		parts.push("");
+		parts.push(message.html);
+	} else if (message.text) {
+		parts.push("Content-Type: text/plain; charset=UTF-8");
+		parts.push("");
+		parts.push(message.text);
+	} else {
+		parts.push("Content-Type: text/plain; charset=UTF-8");
+		parts.push("");
+		parts.push("");
+	}
+}
+
+/** No-attachment variant: pack body headers straight onto the outer message. */
+function appendBodyHeadersInline(parts: string[], message: MailMessage): void {
+	if (message.html && message.text) {
+		const altBoundary = freshBoundary();
+		parts.push(
+			`Content-Type: multipart/alternative; boundary="${altBoundary}"`,
+		);
+		parts.push("");
+		parts.push(`--${altBoundary}`);
+		parts.push("Content-Type: text/plain; charset=UTF-8");
+		parts.push("");
+		parts.push(message.text);
+		parts.push(`--${altBoundary}`);
+		parts.push("Content-Type: text/html; charset=UTF-8");
+		parts.push("");
+		parts.push(message.html);
+		parts.push(`--${altBoundary}--`);
+	} else if (message.html) {
+		parts.push("Content-Type: text/html; charset=UTF-8");
+		parts.push("");
+		parts.push(message.html);
+	} else {
+		parts.push("Content-Type: text/plain; charset=UTF-8");
+		parts.push("");
+		parts.push(message.text ?? "");
+	}
+}
+
+function appendAttachmentPart(
+	parts: string[],
+	boundary: string,
+	att: MailAttachment,
+): void {
+	parts.push(`--${boundary}`);
+	const contentType = stripCrlf(att.contentType ?? "application/octet-stream");
+	const quotedName = mimeQuote(att.filename);
+	parts.push(`Content-Type: ${contentType}; name="${quotedName}"`);
+	parts.push("Content-Transfer-Encoding: base64");
+	parts.push(`Content-Disposition: attachment; filename="${quotedName}"`);
+	parts.push("");
+	const buf = Buffer.from(att.content as Buffer | string);
+	const raw64 = buf.toString("base64");
+	for (let i = 0; i < raw64.length; i += 76) {
+		parts.push(raw64.slice(i, i + 76));
+	}
+}
+
+function freshBoundary(): string {
+	return `----ream_ses_${randomBytes(16).toString("hex")}`;
+}
+
+function amzDateNow(): string {
+	return `${new Date().toISOString().replace(/[-:]/g, "").split(".")[0]}Z`;
+}
+
+function deriveSigningKey(
+	secret: string,
+	shortDate: string,
+	region: string,
+	service: string,
+): Buffer {
+	const kDate = createHmac("sha256", `AWS4${secret}`)
+		.update(shortDate)
+		.digest();
+	const kRegion = createHmac("sha256", kDate).update(region).digest();
+	const kService = createHmac("sha256", kRegion).update(service).digest();
+	return createHmac("sha256", kService).update("aws4_request").digest();
+}
+
+registerTransport("ses", (config) => new SesTransport(config));

package/src/transports/fetchError.ts

@@ -0,0 +1,42 @@
+import { RoverError } from "../RoverError.js";
+
+/**
+ * Wrap a `fetch()` rejection into the uniform `MAIL_PROVIDER_ERROR` shape
+ * so the retry classifier can recognise transient network failures
+ * (ECONNRESET / ENOTFOUND / EAI_AGAIN / ...).
+ *
+ * Node 18+ `fetch` (undici) rejects with `TypeError: fetch failed` and
+ * stashes the original errno on `cause.code` rather than top-level `.code`.
+ * Surface both shapes — older custom HTTP layers and SDK wrappers may set
+ * `code` directly.
+ */
+export function wrapFetchNetworkError(
+	provider: string,
+	err: unknown,
+): RoverError {
+	if (err instanceof RoverError) return err;
+	const top = err as { code?: unknown; cause?: unknown; message?: unknown };
+	const cause = top.cause as { code?: unknown } | undefined;
+	const networkCode =
+		typeof top.code === "string"
+			? top.code
+			: typeof cause?.code === "string"
+				? cause.code
+				: undefined;
+	const message =
+		typeof top.message === "string" ? top.message : "fetch failed";
+	const ctx: Record<string, string> = {
+		provider,
+		upstreamStatus: "0",
+		providerMessage: message,
+	};
+	if (networkCode) ctx.networkCode = networkCode;
+	return new RoverError(
+		"MAIL_PROVIDER_ERROR",
+		`${provider} fetch failed${networkCode ? ` (${networkCode})` : ""}`,
+		{
+			hint: "Inspect `context.networkCode` (ECONNRESET / ENOTFOUND / ...) — the retry classifier treats known transient errnos as retryable.",
+			context: ctx,
+		},
+	);
+}

package/src/webhooks/context.ts

@@ -0,0 +1,41 @@
+/**
+ * Structural HTTP context used by the webhook handlers. Mirrors the
+ * `SignedRouteHttpContext` pattern from `@c9up/archive/signed-route`
+ * so tests can build plain-object mocks without framework coupling.
+ */
+
+export interface WebhookResponse {
+	status(code: number): WebhookResponse;
+	header(name: string, value: string): WebhookResponse;
+	json(data: unknown): void;
+}
+
+export interface WebhookHttpContext {
+	request: {
+		/**
+		 * Header lookup. Adapters MUST be case-insensitive per RFC 7230.
+		 * Providers send headers like `Svix-Id` or `X-Twilio-...` and the
+		 * handler expects to read them via any case.
+		 */
+		header(name: string): string | undefined;
+		/**
+		 * Return the exact bytes the provider signed. This MUST be the
+		 * raw request body before any parsing / re-serialisation — byte-
+		 * for-byte stability is required for Ed25519 / HMAC verification.
+		 * Frameworks that buffer must ensure the returned buffer is the
+		 * original wire bytes, not a re-encoded copy.
+		 */
+		rawBody(): Promise<Buffer> | Buffer;
+		json?(): unknown;
+	};
+	response: WebhookResponse;
+}
+
+export type WebhookMiddleware = (
+	ctx: WebhookHttpContext,
+	next: () => Promise<void>,
+) => Promise<void>;
+
+export interface WebhookEmitter {
+	emit(event: string, data: unknown): void;
+}

package/src/webhooks/mailgun.ts

@@ -0,0 +1,134 @@
+import { Buffer } from "node:buffer";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type {
+	WebhookEmitter,
+	WebhookHttpContext,
+	WebhookMiddleware,
+} from "./context.js";
+
+export interface MailgunWebhookOptions {
+	signingKey: string;
+	emitter: WebhookEmitter;
+	/**
+	 * Maximum age in seconds for a signed payload (default 300 = 5 minutes).
+	 * Protects against replay of a legitimately-signed body captured elsewhere.
+	 * Set to `Number.POSITIVE_INFINITY` to disable (not recommended).
+	 */
+	maxAgeSeconds?: number;
+}
+
+interface MailgunPayload {
+	signature?: { timestamp?: string; token?: string; signature?: string };
+	"event-data"?: {
+		event?: string;
+		recipient?: string;
+		reason?: string;
+		message?: { headers?: { "message-id"?: string } };
+		timestamp?: number;
+	};
+}
+
+const EVENT_MAP: Record<string, string> = {
+	delivered: "mail.delivered",
+	failed: "mail.failed",
+	bounced: "mail.bounced",
+	permanent_fail: "mail.bounced",
+	temporary_fail: "mail.failed",
+};
+
+export function createMailgunWebhookHandler(
+	options: MailgunWebhookOptions,
+): WebhookMiddleware {
+	if (!options.signingKey) {
+		throw new Error(
+			"createMailgunWebhookHandler: signingKey is required for HMAC verification.",
+		);
+	}
+	const signingKey = options.signingKey;
+	const emitter = options.emitter;
+	const maxAgeSeconds = options.maxAgeSeconds ?? 300;
+
+	return async (ctx: WebhookHttpContext, _next): Promise<void> => {
+		const raw = await Promise.resolve(ctx.request.rawBody());
+		let payload: MailgunPayload;
+		try {
+			payload = JSON.parse(raw.toString("utf8")) as MailgunPayload;
+		} catch {
+			// Collapse parse-failure and signature-failure to the same 401 so
+			// the response doesn't leak which branch rejected.
+			ctx.response.status(401).json({ error: "invalid_signature" });
+			return;
+		}
+		const sig = payload.signature;
+		if (!sig?.timestamp || !sig?.token || !sig?.signature) {
+			ctx.response.status(401).json({ error: "invalid_signature" });
+			return;
+		}
+
+		// Enforce a replay-window BEFORE touching the HMAC so a very old
+		// valid signature cannot replay forever.
+		const tsSeconds = Number(sig.timestamp);
+		if (!Number.isFinite(tsSeconds)) {
+			ctx.response.status(401).json({ error: "invalid_signature" });
+			return;
+		}
+		const nowSeconds = Date.now() / 1000;
+		if (Math.abs(nowSeconds - tsSeconds) > maxAgeSeconds) {
+			ctx.response.status(401).json({ error: "stale_signature" });
+			return;
+		}
+
+		const expected = createHmac("sha256", signingKey)
+			.update(`${sig.timestamp}${sig.token}`)
+			.digest("hex");
+		if (!constantTimeEqualHex(expected, sig.signature)) {
+			ctx.response.status(401).json({ error: "invalid_signature" });
+			return;
+		}
+
+		const data = payload["event-data"];
+		if (!data?.event) {
+			ctx.response.status(400).json({ error: "missing_event" });
+			return;
+		}
+		const eventName = EVENT_MAP[data.event];
+		if (eventName) {
+			try {
+				emitter.emit(eventName, {
+					messageId: data.message?.headers?.["message-id"] ?? "",
+					to: data.recipient ?? "",
+					reason: data.reason,
+					// Some Mailgun event types report `timestamp` already in
+					// milliseconds; detect magnitude rather than blindly *1000.
+					timestamp: normaliseTimestamp(data.timestamp),
+				});
+			} catch {
+				// Emitter failure must not fail the webhook response — providers
+				// will retry on non-2xx and flood the bus.
+			}
+		}
+		ctx.response.status(200).json({ ok: true });
+	};
+}
+
+function constantTimeEqualHex(a: string, b: string): boolean {
+	if (a.length !== b.length) return false;
+	const bufA = Buffer.from(a, "hex");
+	const bufB = Buffer.from(b, "hex");
+	if (bufA.length !== bufB.length) return false;
+	return timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Producers sometimes send seconds-since-epoch, sometimes ms. Values larger
+ * than 1e12 are ms (post-2001 in ms); anything smaller is treated as seconds.
+ */
+function normaliseTimestamp(ts: number | undefined): number {
+	// Guard non-finite values (NaN / ±Infinity): a malformed `timestamp`
+	// field in the webhook payload would otherwise multiply into NaN and
+	// leak into the emitted mail.* event, breaking consumers that sort
+	// / persist / compare timestamps numerically.
+	if (ts === undefined || !Number.isFinite(ts)) return Date.now();
+	if (ts > 1e12) return ts;
+	return ts * 1000;
+}