@q32/core 0.1.28 → 0.1.29

package/dist/ses.js

@@ -0,0 +1,125 @@
+import { awsFetch, createAwsConfigFromEnv } from "./aws.js";
+import { buildRawMimeMessage, formatEmailAddress } from "./email.js";
+export class NoopSesMailer {
+    enabled = false;
+    async send() {
+        throw new Error("SES mailer is not configured.");
+    }
+}
+export class WorkerSesMailer {
+    config;
+    defaults;
+    enabled = true;
+    constructor(config, defaults) {
+        this.config = config;
+        this.defaults = defaults;
+    }
+    send(input) {
+        return sendSesEmail(this.config, {
+            ...input,
+            from: input.from ?? this.defaults.from,
+            replyTo: input.replyTo ?? this.defaults.replyTo,
+        }, { fetcher: this.defaults.fetcher });
+    }
+}
+export function createSesMailerFromEnv(env, options = {}) {
+    const config = createAwsConfigFromEnv(env);
+    const fromEmail = options.fromEmail ?? env.FROM_EMAIL ?? env.EMAIL_FROM ?? env.NOTIFICATION_FROM_EMAIL ?? env.POSTMARK_FROM_EMAIL ?? env.SES_FROM_EMAIL;
+    if (!config || !fromEmail)
+        return new NoopSesMailer();
+    const replyTo = options.replyTo ?? env.NOTIFICATION_REPLY_TO ?? env.EMAIL_REPLY_TO;
+    return new WorkerSesMailer(config, {
+        from: { email: fromEmail, name: options.fromName },
+        replyTo: typeof replyTo === "string"
+            ? [{ email: replyTo }]
+            : Array.isArray(replyTo)
+                ? replyTo.map((email) => ({ email }))
+                : undefined,
+        fetcher: options.fetcher,
+    });
+}
+export async function sendSesEmail(config, input, options = {}) {
+    const hasRawFeatures = Boolean(input.headers && Object.keys(input.headers).length > 0) || Boolean(input.attachments?.length);
+    const body = hasRawFeatures ? rawSesBody(input) : simpleSesBody(input);
+    const response = await awsFetch(config, `https://email.${config.region}.amazonaws.com/v2/email/outbound-emails`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    }, { service: "ses", fetcher: options.fetcher });
+    const text = await response.text();
+    if (!response.ok)
+        throw new Error(`SES send failed: ${response.status} ${text.slice(0, 300)}`);
+    const payload = parseJsonObject(text);
+    const messageId = stringValue(payload.MessageId) ?? stringValue(payload.messageId) ?? "";
+    return { provider: "ses", messageId };
+}
+export async function sesQuery(config, params, options = {}) {
+    const body = new URLSearchParams({ Version: "2010-12-01", ...params }).toString();
+    const response = await awsFetch(config, `https://email.${config.region}.amazonaws.com/`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body,
+    }, { service: "ses", fetcher: options.fetcher });
+    const text = await response.text();
+    if (!response.ok)
+        throw new Error(`SES ${params.Action ?? "query"} failed: ${response.status} ${text.slice(0, 300)}`);
+    return text;
+}
+export function inboundSesMxHost(region = "us-east-1") {
+    return `inbound-smtp.${region}.amazonaws.com`;
+}
+function simpleSesBody(input) {
+    return {
+        FromEmailAddress: formatEmailAddress(input.from),
+        Destination: {
+            ToAddresses: input.to.map(formatEmailAddress),
+            ...(input.cc?.length ? { CcAddresses: input.cc.map(formatEmailAddress) } : {}),
+            ...(input.bcc?.length ? { BccAddresses: input.bcc.map(formatEmailAddress) } : {}),
+        },
+        ...(input.replyTo?.length ? { ReplyToAddresses: input.replyTo.map(formatEmailAddress) } : {}),
+        Content: {
+            Simple: {
+                Subject: { Data: input.subject, Charset: "UTF-8" },
+                Body: {
+                    ...(input.text ? { Text: { Data: input.text, Charset: "UTF-8" } } : {}),
+                    ...(input.html ? { Html: { Data: input.html, Charset: "UTF-8" } } : {}),
+                },
+            },
+        },
+    };
+}
+function rawSesBody(input) {
+    return {
+        FromEmailAddress: formatEmailAddress(input.from),
+        Destination: {
+            ToAddresses: input.to.map(formatEmailAddress),
+            ...(input.cc?.length ? { CcAddresses: input.cc.map(formatEmailAddress) } : {}),
+            ...(input.bcc?.length ? { BccAddresses: input.bcc.map(formatEmailAddress) } : {}),
+        },
+        Content: {
+            Raw: {
+                Data: textToBase64(buildRawMimeMessage(input)),
+            },
+        },
+    };
+}
+function textToBase64(value) {
+    const bytes = new TextEncoder().encode(value);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function parseJsonObject(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : null;
+}
+//# sourceMappingURL=ses.js.map

package/dist/ses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ses.js","sourceRoot":"","sources":["../src/ses.ts"],"names":[],"mappings":"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"}

package/docs/ses-sns-helper-survey.md

@@ -0,0 +1,235 @@
+# SES And SNS Helper Survey
+
+Survey date: 2026-06-12.
+
+This survey covers the current hand-rolled SES/SNS shapes across the maintained
+Worker sites that were explicitly named or surfaced by source search:
+
+- `/home/erik/ipogrid`
+- `/home/erik/relin`
+- `/home/erik/domains/bce.email`
+- `/home/erik/domains/theinvestornet.com`
+- `/home/erik/dirtsignal`
+- `/home/erik/getflight`
+- `/home/erik/onwardtravel`
+- `/home/erik/adgiro`
+
+`onwardtravel` and `adgiro` did not currently expose SES source usage in the
+searched app code, despite likely operational SES use or future need.
+
+## Current Shapes
+
+### Simple Outbound SES
+
+`ipogrid`, `relin`, and `getflight` each have a small SESv2 simple-email sender:
+
+- build a client from `AWS_ACCESS_KEY` / `AWS_SECRET_KEY` / `AWS_REGION`
+- require a configured from address
+- accept `to`, `subject`, `text`, `html`, and optional reply-to
+- call `SendEmailCommand` using `Content.Simple`
+- either throw on SES failure or return `{ sent: false, reason }`
+
+`ipogrid` and `relin` also wrap this in `NotificationMailer` classes with
+`enabled`, `NoopNotificationMailer`, and `SesNotificationMailer`.
+
+### Rich Outbound SES
+
+`dirtsignal` has the most complete outbound helper:
+
+- supports simple SESv2 send when no special envelope behavior is needed
+- switches to raw MIME for attachments or custom RFC 5322 headers
+- supports one-click unsubscribe headers
+- base64 encodes UTF-8 body parts and attachments
+- sanitizes custom header values by removing CR/LF
+- returns `{ sent, reason, message_id }` instead of throwing
+
+This is the best starting point for the outbound helper because it covers the
+behavior the simpler sites can use and the richer newsletter use case that SES
+Simple mode cannot handle.
+
+### Worker-Native AWS Fetch
+
+`bce.email` and `theinvestornet.com` avoid the AWS SDK for some Worker paths:
+
+- `bce.email` signs SES Query API and SESv2 HTTP calls directly through a local
+  SigV4 `awsFetch`.
+- `theinvestornet.com` uses `aws4fetch` to send SESv2 email and fetch inbound
+  S3 objects.
+
+This points toward a `q32-core` helper that uses `fetch` plus SigV4 rather than
+depending on `@aws-sdk/client-sesv2`, or offers the SDK client only as an
+adapter. Keeping the core helper Worker-native avoids pulling the AWS SDK into
+small Workers.
+
+### SNS Feedback Webhooks
+
+`ipogrid` and `dirtsignal` duplicate the same SES feedback flow:
+
+- authenticate a URL token
+- parse an SNS envelope
+- confirm `SubscriptionConfirmation` by fetching a trusted `SubscribeURL`
+- ignore unsupported SNS types
+- parse `Notification.Message`
+- normalize `eventType` or `notificationType`
+- extract bounce or complaint recipient emails
+- call app-specific suppression/unsubscribe logic
+
+`dirtsignal` is stricter and more reusable here because it validates the SNS
+hostname before confirming subscriptions and falls back to `mail.destination`
+when bounce/complaint recipient arrays are missing.
+
+### Inbound SES Receipt/SNS
+
+`bce.email` and `theinvestornet.com` handle inbound SES receipt notifications:
+
+- confirm SNS subscription
+- parse receipt notifications from `Message`
+- read `mail.messageId`, `mail.source`, common headers, and `receipt.recipients`
+- fetch raw email from S3 or forward based on the message id
+- route recipients through app-specific domain/workspace rules
+
+The shared helper should parse and validate the envelope, but should not own
+route resolution, raw email parsing, forwarding, R2 storage, D1 writes, or app
+workflow creation.
+
+### SES Domain And Receipt Rule Management
+
+`bce.email` has the only substantial SES management surface:
+
+- `VerifyDomainIdentity`
+- `GetIdentityVerificationAttributes`
+- `GetIdentityDkimAttributes`
+- `DeleteIdentity`
+- `DescribeActiveReceiptRuleSet`
+- `UpdateReceiptRule` with S3 action and optional SNS action
+- DNS record generation for SES TXT, DKIM CNAMEs, and inbound MX
+
+This deserves a separate helper area from outbound mail. It is useful, but it is
+not the first extraction target because it is more product-specific and bound to
+customer-domain provisioning workflows.
+
+## Recommended `q32-core` Shape
+
+Add three layers, keeping app policy outside the package.
+
+### `@q32/core/email`
+
+Extend the existing generic email types:
+
+- normalize and format addresses
+- build MIME-safe headers
+- build simple text/html messages
+- build raw MIME messages with:
+  - multipart alternative text/html
+  - attachments
+  - custom headers
+  - CR/LF header-value sanitization
+  - UTF-8/base64 transfer encoding
+- generate `List-Unsubscribe` and `List-Unsubscribe-Post` header pairs from a
+  caller-provided URL
+
+### `@q32/core/aws`
+
+Add Worker-native AWS/SigV4 helpers:
+
+- `awsFetch(config, url, init, { service, region })`
+- `createAwsConfigFromEnv(env, aliases?)`
+- support both env naming families:
+  - `AWS_ACCESS_KEY` / `AWS_SECRET_KEY`
+  - `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`
+- default region to `us-east-1`
+
+This keeps SES and S3 helpers small without importing the AWS SDK.
+
+### `@q32/core/ses`
+
+Add SES-specific helpers on top of `awsFetch`:
+
+- `sendSesEmail(config, input)` using SESv2 HTTP API
+- `sendSesRawEmail(config, input)` using SESv2 raw content
+- `createSesMailerFromEnv(env, options)` returning a small provider with
+  `enabled` and `send`
+- `sesQuery(config, params)` for legacy SES Query API calls
+- `inboundSesMxHost(region)`
+- `sesDomainDnsRecords(identityAttributes, region)` for verification, DKIM, and
+  inbound MX record description
+- receipt-rule update helpers only after `bce.email` is ready to migrate
+
+The first extraction should include outbound send plus raw MIME. Domain
+provisioning can come after that so the API is not shaped by one app too early.
+
+### `@q32/core/ses-sns`
+
+Add SNS envelope and SES notification parsing:
+
+- `parseSnsEnvelope(body)`
+- `isTrustedSnsSubscribeUrl(url)`
+- `confirmSnsSubscription(envelope, fetcher?)`
+- `parseSesFeedbackNotification(envelope)`
+- `extractSesFeedbackRecipients(message)`
+- `handleSesFeedbackWebhook(input)` that returns structured action data but
+  accepts an app callback for suppression/unsubscribe side effects
+- `parseSesReceiptNotification(envelope)` for inbound receipt flows
+
+The helper should return data like:
+
+```ts
+type SesFeedbackEvent = {
+  eventType: "Bounce" | "Complaint" | string;
+  emails: string[];
+  messageId?: string;
+  topicArn?: string;
+};
+
+type SesReceiptEvent = {
+  messageId: string;
+  source?: string;
+  subject?: string;
+  recipients: string[];
+};
+```
+
+Apps still decide whether a bounce disables newsletters, login emails,
+workspace senders, or all notification surfaces.
+
+## Migration Order
+
+1. Extract pure utilities first: address normalization, raw MIME builder,
+   trusted SNS URL check, SNS envelope parsing, and SES feedback recipient
+   extraction.
+2. Migrate `dirtsignal` and `ipogrid` SNS feedback handlers to shared parsing
+   while keeping their app-specific unsubscribe callbacks local.
+3. Migrate `getflight`, `relin`, and `ipogrid` simple outbound senders to a
+   shared SES mailer.
+4. Migrate `dirtsignal` outbound mail once raw MIME behavior is covered by
+   focused tests for custom headers and attachments.
+5. Consider `theinvestornet.com` AWS client extraction for shared SES/S3 fetch.
+6. Only then extract `bce.email` domain identity and receipt-rule management.
+
+## Test Coverage To Carry Into Core
+
+Core should have focused tests for:
+
+- simple text/html SESv2 request shape
+- raw MIME text/html alternative body
+- raw MIME attachments
+- raw MIME custom headers with CR/LF stripped
+- UTF-8 subject encoding
+- trusted and untrusted SNS subscription URLs
+- SNS `SubscriptionConfirmation`
+- SNS unsupported type handling
+- SES feedback `Bounce` and `Complaint` extraction
+- fallback extraction from `mail.destination`
+- SES receipt notification extraction with missing-message-data rejection
+
+## What Should Stay App-Local
+
+- D1 repository updates
+- unsubscribe and suppression policy
+- notification preference semantics
+- workspace sender selection
+- per-product audit/ops event recording
+- R2/S3 object retention policy
+- raw inbound email parsing and attachment handling
+- customer-domain provisioning job orchestration
+- Domain Connect and DNS-provider UX

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q32/core",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "Shared TypeScript primitives for Q32 Cloudflare Worker projects.",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,10 @@
       "types": "./dist/auth.d.ts",
       "default": "./dist/auth.js"
     },
+    "./aws": {
+      "types": "./dist/aws.d.ts",
+      "default": "./dist/aws.js"
+    },
     "./billing": {
       "types": "./dist/billing.d.ts",
       "default": "./dist/billing.js"
@@ -120,6 +124,14 @@
       "types": "./dist/session.d.ts",
       "default": "./dist/session.js"
     },
+    "./ses": {
+      "types": "./dist/ses.d.ts",
+      "default": "./dist/ses.js"
+    },
+    "./ses-sns": {
+      "types": "./dist/ses-sns.d.ts",
+      "default": "./dist/ses-sns.js"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "default": "./dist/testing.js"

package/src/aws.ts

@@ -0,0 +1,152 @@
+export type AwsCredentials = {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+};
+
+export type AwsConfig = AwsCredentials & {
+  region: string;
+};
+
+export type AwsEnv = {
+  AWS_ACCESS_KEY?: string;
+  AWS_SECRET_KEY?: string;
+  AWS_ACCESS_KEY_ID?: string;
+  AWS_SECRET_ACCESS_KEY?: string;
+  AWS_SESSION_TOKEN?: string;
+  AWS_REGION?: string;
+};
+
+export function createAwsConfigFromEnv(env: AwsEnv, defaultRegion = "us-east-1"): AwsConfig | null {
+  const accessKeyId = env.AWS_ACCESS_KEY_ID ?? env.AWS_ACCESS_KEY;
+  const secretAccessKey = env.AWS_SECRET_ACCESS_KEY ?? env.AWS_SECRET_KEY;
+  if (!accessKeyId || !secretAccessKey) return null;
+  return {
+    accessKeyId,
+    secretAccessKey,
+    sessionToken: env.AWS_SESSION_TOKEN,
+    region: env.AWS_REGION ?? defaultRegion,
+  };
+}
+
+export type AwsFetchOptions = {
+  service: string;
+  region?: string;
+  fetcher?: typeof fetch;
+};
+
+export async function awsFetch(
+  config: AwsConfig,
+  input: string | URL,
+  init: RequestInit,
+  options: AwsFetchOptions,
+): Promise<Response> {
+  const url = new URL(input.toString());
+  const region = options.region ?? config.region;
+  const method = (init.method ?? "GET").toUpperCase();
+  const body = bodyToString(init.body);
+  const payloadHash = await sha256Hex(body);
+  const headers = new Headers(init.headers);
+  headers.set("host", url.host);
+  headers.set("x-amz-content-sha256", payloadHash);
+  const now = new Date();
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+  const dateStamp = amzDate.slice(0, 8);
+  headers.set("x-amz-date", amzDate);
+  if (config.sessionToken) headers.set("x-amz-security-token", config.sessionToken);
+
+  const signedHeaderNames = headerNames(headers).map((key) => key.toLowerCase()).sort();
+  const canonicalHeaders = signedHeaderNames.map((key) => `${key}:${normalizeHeaderValue(headers.get(key) ?? "")}\n`).join("");
+  const canonicalRequest = [
+    method,
+    canonicalPath(url),
+    canonicalQuery(url),
+    canonicalHeaders,
+    signedHeaderNames.join(";"),
+    payloadHash,
+  ].join("\n");
+  const credentialScope = `${dateStamp}/${region}/${options.service}/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    credentialScope,
+    await sha256Hex(canonicalRequest),
+  ].join("\n");
+  const signature = await hmacHex(await signingKey(config.secretAccessKey, dateStamp, region, options.service), stringToSign);
+  headers.set(
+    "authorization",
+    `AWS4-HMAC-SHA256 Credential=${config.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaderNames.join(";")}, Signature=${signature}`,
+  );
+
+  return (options.fetcher ?? fetch)(url, {
+    ...init,
+    method,
+    headers,
+    body: init.body,
+  });
+}
+
+function bodyToString(body: BodyInit | null | undefined): string {
+  if (!body) return "";
+  if (typeof body === "string") return body;
+  throw new Error("awsFetch currently supports string request bodies.");
+}
+
+function canonicalPath(url: URL): string {
+  return url.pathname
+    .split("/")
+    .map((part) => encodeURIComponent(decodeURIComponent(part)).replace(/[!'()*]/g, pctEncode))
+    .join("/");
+}
+
+function canonicalQuery(url: URL): string {
+  const entries: Array<[string, string]> = [];
+  url.searchParams.forEach((value, key) => entries.push([key, value]));
+  return entries
+    .map(([key, value]) => [encodeRfc3986(key), encodeRfc3986(value)] as const)
+    .sort(([leftKey, leftValue], [rightKey, rightValue]) => leftKey.localeCompare(rightKey) || leftValue.localeCompare(rightValue))
+    .map(([key, value]) => `${key}=${value}`)
+    .join("&");
+}
+
+function headerNames(headers: Headers): string[] {
+  const names: string[] = [];
+  headers.forEach((_value, key) => names.push(key));
+  return names;
+}
+
+function normalizeHeaderValue(value: string): string {
+  return value.trim().replace(/\s+/g, " ");
+}
+
+function encodeRfc3986(value: string): string {
+  return encodeURIComponent(value).replace(/[!'()*]/g, pctEncode);
+}
+
+function pctEncode(char: string): string {
+  return `%${char.charCodeAt(0).toString(16).toUpperCase()}`;
+}
+
+async function signingKey(secret: string, date: string, region: string, service: string): Promise<ArrayBuffer> {
+  const kDate = await hmacRaw(new TextEncoder().encode(`AWS4${secret}`), date);
+  const kRegion = await hmacRaw(kDate, region);
+  const kService = await hmacRaw(kRegion, service);
+  return hmacRaw(kService, "aws4_request");
+}
+
+async function hmacRaw(key: BufferSource, value: string): Promise<ArrayBuffer> {
+  const cryptoKey = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(value));
+}
+
+async function hmacHex(key: BufferSource, value: string): Promise<string> {
+  return bytesToHex(new Uint8Array(await hmacRaw(key, value)));
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  return bytesToHex(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value))));
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/src/email.ts

@@ -47,3 +47,102 @@ export function normalizeEmailAddress(email: string): string {
 export function appendUnsubscribeFooter(text: string, unsubscribeUrl: string): string {
   return `${text.trim()}\n\nUnsubscribe: ${unsubscribeUrl}\n`;
 }
+
+export function sanitizeEmailHeaderValue(value: string): string {
+  return value.replace(/[\r\n]+/g, " ").trim();
+}
+
+export function encodeMimeHeader(value: string): string {
+  if (/^[\x20-\x7e]*$/.test(value)) return sanitizeEmailHeaderValue(value);
+  return `=?UTF-8?B?${base64Utf8(value)}?=`;
+}
+
+export function buildListUnsubscribeHeaders(url: string): Record<string, string> {
+  return {
+    "List-Unsubscribe": `<${sanitizeEmailHeaderValue(url)}>`,
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+  };
+}
+
+export type RawMimeMessageInput = Omit<SendEmailInput, "tags"> & {
+  headers?: Record<string, string>;
+  boundaryPrefix?: string;
+};
+
+export function buildRawMimeMessage(input: RawMimeMessageInput): string {
+  const mixedBoundary = `${input.boundaryPrefix ?? "q32"}-mixed-${crypto.randomUUID()}`;
+  const bodyBoundary = `${input.boundaryPrefix ?? "q32"}-body-${crypto.randomUUID()}`;
+  const attachments = input.attachments ?? [];
+  const headers = [
+    `From: ${formatEmailAddress(input.from)}`,
+    `To: ${input.to.map(formatEmailAddress).join(", ")}`,
+    ...(input.cc?.length ? [`Cc: ${input.cc.map(formatEmailAddress).join(", ")}`] : []),
+    `Subject: ${encodeMimeHeader(input.subject)}`,
+    "MIME-Version: 1.0",
+    ...(input.replyTo?.length ? [`Reply-To: ${input.replyTo.map(formatEmailAddress).join(", ")}`] : []),
+  ];
+
+  for (const [name, value] of Object.entries(input.headers ?? {})) {
+    const headerName = sanitizeHeaderName(name);
+    const headerValue = sanitizeEmailHeaderValue(value);
+    if (headerName && headerValue) headers.push(`${headerName}: ${headerValue}`);
+  }
+
+  const parts = [...headers, `Content-Type: multipart/mixed; boundary="${mixedBoundary}"`, ""];
+  parts.push(`--${mixedBoundary}`);
+
+  if (input.text && input.html) {
+    parts.push(`Content-Type: multipart/alternative; boundary="${bodyBoundary}"`, "");
+    parts.push(`--${bodyBoundary}`);
+    parts.push("Content-Type: text/plain; charset=UTF-8");
+    parts.push("Content-Transfer-Encoding: base64", "", wrapBase64(base64Utf8(input.text)), "");
+    parts.push(`--${bodyBoundary}`);
+    parts.push("Content-Type: text/html; charset=UTF-8");
+    parts.push("Content-Transfer-Encoding: base64", "", wrapBase64(base64Utf8(input.html)), "");
+    parts.push(`--${bodyBoundary}--`, "");
+  } else if (input.html) {
+    parts.push("Content-Type: text/html; charset=UTF-8");
+    parts.push("Content-Transfer-Encoding: base64", "", wrapBase64(base64Utf8(input.html)), "");
+  } else {
+    parts.push("Content-Type: text/plain; charset=UTF-8");
+    parts.push("Content-Transfer-Encoding: base64", "", wrapBase64(base64Utf8(input.text ?? "")), "");
+  }
+
+  for (const attachment of attachments) {
+    parts.push(`--${mixedBoundary}`);
+    parts.push(`Content-Type: ${sanitizeEmailHeaderValue(attachment.contentType)}; name=${quoteHeaderParam(attachment.filename)}`);
+    parts.push("Content-Transfer-Encoding: base64");
+    parts.push(`Content-Disposition: attachment; filename=${quoteHeaderParam(attachment.filename)}`);
+    parts.push("", wrapBase64(attachmentDataToBase64(attachment.data)), "");
+  }
+
+  parts.push(`--${mixedBoundary}--`, "");
+  return parts.join("\r\n");
+}
+
+function sanitizeHeaderName(value: string): string {
+  const name = value.trim();
+  return /^[A-Za-z0-9-]+$/.test(name) ? name : "";
+}
+
+function quoteHeaderParam(value: string): string {
+  return `"${sanitizeEmailHeaderValue(value).replace(/(["\\])/g, "\\$1")}"`;
+}
+
+function attachmentDataToBase64(value: Uint8Array | string): string {
+  if (typeof value === "string") return base64Utf8(value);
+  let binary = "";
+  for (const byte of value) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function base64Utf8(value: string): string {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function wrapBase64(value: string): string {
+  return value.replace(/.{1,76}/g, "$&\r\n").trimEnd();
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./api.js";
 export * from "./ai.js";
 export * from "./auth.js";
+export * from "./aws.js";
 export * from "./billing.js";
 export * from "./cloudflare.js";
 export * from "./crypto.js";
@@ -21,5 +22,7 @@ export * from "./rate-limit.js";
 export * from "./react-router.js";
 export * from "./seo.js";
 export * from "./session.js";
+export * from "./ses.js";
+export * from "./ses-sns.js";
 export * from "./testing.js";
 export * from "./time.js";