@bygghammar/cms-platform 0.35.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Shared CMS platform: blocks, block types, i18n core, UI primitives and design-token contract used by every Bygghammar/Voyara site.",
   "type": "module",
   "sideEffects": false,
@@ -148,7 +148,10 @@
     "./server/translate-db-core": "./src/server/translate-db-core.ts",
     "./tracking/injections": "./src/tracking/injections.ts",
     "./server/injections-core": "./src/server/injections-core.ts",
-    "./server/domains-core": "./src/server/domains-core.ts"
+    "./server/domains-core": "./src/server/domains-core.ts",
+    "./server/provider-secrets": "./src/server/provider-secrets.ts",
+    "./server/smtp": "./src/server/smtp.ts",
+    "./server/email-send-core": "./src/server/email-send-core.ts"
   },
   "dependencies": {
     "fflate": "^0.8.3"

package/src/server/email-send-core.ts

@@ -0,0 +1,266 @@
+/**
+ * Host-agnostic email dispatch for rows in `public.email_providers`.
+ *
+ * Each provider is dispatched by its `kind` (mailgun, ses, http, smtp). The
+ * credential is always resolved through the provider's preserved
+ * `secret_ref_name` environment variable — values are never read from the
+ * database and never appear in an error message.
+ *
+ * Server-only. Never import from client code.
+ */
+
+import { resolveProviderSecret, type Env } from "./provider-secrets";
+import { sendSmtp } from "./smtp";
+
+export type SendableProvider = {
+  id: string;
+  name: string;
+  kind: string;
+  from_name: string | null;
+  from_email: string | null;
+  reply_to: string | null;
+  config: Record<string, unknown>;
+  secret_ref_name: string | null;
+};
+
+export type SendResult = { ok: true } | { ok: false; error: string };
+
+export type SendPayload = {
+  to: string;
+  subject: string;
+  html: string;
+  text: string;
+  fromName: string | null;
+  fromEmail: string;
+  replyTo: string | null;
+};
+
+export type SendOptions = {
+  /** Environment used for credential lookup. Defaults to `process.env`. */
+  env?: Env;
+};
+
+function envOf(options?: SendOptions): Env {
+  return options?.env ?? (process.env as Env);
+}
+
+function secretOf(provider: SendableProvider, env: Env): string | undefined {
+  const res = resolveProviderSecret(provider, env);
+  return res.ok ? res.value : undefined;
+}
+
+/** Value-free explanation of why a provider credential is unavailable. */
+function secretProblem(provider: SendableProvider, env: Env): string {
+  const res = resolveProviderSecret(provider, env);
+  return res.ok ? "" : res.error;
+}
+
+function str(config: Record<string, unknown>, key: string): string | undefined {
+  const v = config?.[key];
+  return typeof v === "string" && v.trim() ? v.trim() : undefined;
+}
+
+function formatFrom(payload: SendPayload) {
+  return payload.fromName ? `${payload.fromName} <${payload.fromEmail}>` : payload.fromEmail;
+}
+
+/* ---------------- Mailgun ---------------- */
+async function sendMailgun(
+  p: SendableProvider,
+  payload: SendPayload,
+  env: Env,
+): Promise<SendResult> {
+  const domain = str(p.config, "domain");
+  const key = secretOf(p, env);
+  if (!domain) return { ok: false, error: "Mailgun domain is missing in the provider config." };
+  if (!key) return { ok: false, error: secretProblem(p, env) };
+  const region = (str(p.config, "region") ?? "us").toLowerCase();
+  const base =
+    str(p.config, "base_url") ??
+    (region.startsWith("eu") ? "https://api.eu.mailgun.net/v3" : "https://api.mailgun.net/v3");
+  const body = new URLSearchParams({
+    from: formatFrom(payload),
+    to: payload.to,
+    subject: payload.subject,
+    text: payload.text,
+    html: payload.html,
+  });
+  if (payload.replyTo) body.set("h:Reply-To", payload.replyTo);
+
+  const res = await fetch(`${base.replace(/\/$/, "")}/${domain}/messages`, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${btoa(`api:${key}`)}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body,
+  });
+  if (!res.ok) return { ok: false, error: `Mailgun [${res.status}]: ${await res.text()}` };
+  return { ok: true };
+}
+
+/* ---------------- Amazon SES (v2 HTTPS API, SigV4) ---------------- */
+const enc = new TextEncoder();
+
+async function hmac(key: ArrayBuffer | Uint8Array, data: string): Promise<ArrayBuffer> {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key as BufferSource,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  return crypto.subtle.sign("HMAC", cryptoKey, enc.encode(data));
+}
+
+function hex(buf: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buf))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+async function sha256Hex(data: string): Promise<string> {
+  return hex(await crypto.subtle.digest("SHA-256", enc.encode(data)));
+}
+
+async function sendSes(p: SendableProvider, payload: SendPayload, env: Env): Promise<SendResult> {
+  const region = str(p.config, "region");
+  const accessKeyId = str(p.config, "access_key_id");
+  const secretAccessKey = secretOf(p, env);
+  if (!region) return { ok: false, error: "SES region is missing in the provider config." };
+  if (!accessKeyId)
+    return { ok: false, error: "SES access key id is missing in the provider config." };
+  if (!secretAccessKey) return { ok: false, error: secretProblem(p, env) };
+
+  const host = `email.${region}.amazonaws.com`;
+  const path = "/v2/email/outbound-emails";
+  const body = JSON.stringify({
+    FromEmailAddress: formatFrom(payload),
+    Destination: { ToAddresses: [payload.to] },
+    ...(payload.replyTo ? { ReplyToAddresses: [payload.replyTo] } : {}),
+    Content: {
+      Simple: {
+        Subject: { Data: payload.subject, Charset: "UTF-8" },
+        Body: {
+          Text: { Data: payload.text, Charset: "UTF-8" },
+          Html: { Data: payload.html, Charset: "UTF-8" },
+        },
+      },
+    },
+  });
+
+  const now = new Date();
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+  const dateStamp = amzDate.slice(0, 8);
+  const payloadHash = await sha256Hex(body);
+  const canonicalHeaders = `content-type:application/json\nhost:${host}\nx-amz-content-sha256:${payloadHash}\nx-amz-date:${amzDate}\n`;
+  const signedHeaders = "content-type;host;x-amz-content-sha256;x-amz-date";
+  const canonicalRequest = `POST\n${path}\n\n${canonicalHeaders}\n${signedHeaders}\n${payloadHash}`;
+  const scope = `${dateStamp}/${region}/ses/aws4_request`;
+  const stringToSign = `AWS4-HMAC-SHA256\n${amzDate}\n${scope}\n${await sha256Hex(canonicalRequest)}`;
+
+  let signingKey: ArrayBuffer | Uint8Array = enc.encode(`AWS4${secretAccessKey}`);
+  for (const part of [dateStamp, region, "ses", "aws4_request"]) {
+    signingKey = await hmac(signingKey, part);
+  }
+  const signature = hex(await hmac(signingKey, stringToSign));
+
+  const res = await fetch(`https://${host}${path}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Amz-Date": amzDate,
+      "x-amz-content-sha256": payloadHash,
+      Authorization: `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+    },
+    body,
+  });
+  if (!res.ok) return { ok: false, error: `SES [${res.status}]: ${await res.text()}` };
+  return { ok: true };
+}
+
+/* ---------------- Generic HTTP / webhook ---------------- */
+async function sendHttp(p: SendableProvider, payload: SendPayload, env: Env): Promise<SendResult> {
+  const url = str(p.config, "endpoint") ?? str(p.config, "url");
+  if (!url) return { ok: false, error: "Endpoint URL is missing in the provider config." };
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  const secret = secretOf(p, env);
+  if (secret) {
+    const headerName = str(p.config, "auth_header") ?? "Authorization";
+    const scheme = str(p.config, "auth_scheme");
+    headers[headerName] = scheme ? `${scheme} ${secret}` : secret;
+  }
+  const res = await fetch(url, {
+    method: (str(p.config, "method") ?? "POST").toUpperCase(),
+    headers,
+    body: JSON.stringify({
+      from: formatFrom(payload),
+      from_email: payload.fromEmail,
+      from_name: payload.fromName,
+      reply_to: payload.replyTo,
+      to: payload.to,
+      subject: payload.subject,
+      html: payload.html,
+      text: payload.text,
+    }),
+  });
+  if (!res.ok) return { ok: false, error: `Endpoint [${res.status}]: ${await res.text()}` };
+  return { ok: true };
+}
+
+/* ---------------- SMTP (raw socket, STARTTLS) ---------------- */
+async function sendSmtpProvider(
+  p: SendableProvider,
+  payload: SendPayload,
+  env: Env,
+): Promise<SendResult> {
+  const host = str(p.config, "host");
+  if (!host) return { ok: false, error: "SMTP host is missing in the provider config." };
+  const secret = resolveProviderSecret(p, env);
+  if (!secret.ok) return { ok: false, error: secret.error };
+  const rawPort = p.config?.port;
+  const port = Number(typeof rawPort === "string" ? rawPort.trim() : rawPort) || 587;
+  return sendSmtp(
+    { host, port, username: str(p.config, "username"), password: secret.value },
+    {
+      to: payload.to,
+      fromEmail: payload.fromEmail,
+      fromName: payload.fromName,
+      replyTo: payload.replyTo,
+      subject: payload.subject,
+      text: payload.text,
+      html: payload.html,
+    },
+  );
+}
+
+/** Dispatch one message through the provider's own transport. Never throws. */
+export async function sendViaProvider(
+  provider: SendableProvider,
+  payload: SendPayload,
+  options?: SendOptions,
+): Promise<SendResult> {
+  const env = envOf(options);
+  try {
+    switch (provider.kind) {
+      case "mailgun":
+        return await sendMailgun(provider, payload, env);
+      case "ses":
+        return await sendSes(provider, payload, env);
+      case "http":
+        return await sendHttp(provider, payload, env);
+      case "smtp":
+        return await sendSmtpProvider(provider, payload, env);
+      case "lovable":
+        return {
+          ok: false,
+          error:
+            "Lovable Emails sending is not wired up yet — set up the email domain first, or test another provider.",
+        };
+      default:
+        return { ok: false, error: `Unknown provider kind "${provider.kind}".` };
+    }
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : "Unknown send error" };
+  }
+}

package/src/server/provider-secrets.ts

@@ -0,0 +1,170 @@
+/**
+ * Multi-provider secret handling.
+ *
+ * Every row in `public.email_providers` names the environment variable that
+ * holds its credential (`secret_ref_name`). The value itself lives only in the
+ * server's environment — never in PostgreSQL, never in a migration package,
+ * never in a log line.
+ *
+ * This is deliberately separate from the system-mail path: `SMTP_PASSWORD`
+ * powers self-hosted account/password emails, while provider credentials are
+ * resolved per provider through the preserved `secret_ref_name`.
+ */
+
+/** Only plain, safe environment-variable names are accepted. */
+export const SECRET_REF_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Environment variable used by the self-hosted system-mail path. */
+export const SYSTEM_SMTP_SECRET_NAME = "SMTP_PASSWORD";
+
+export type ProviderSecretRow = {
+  id?: string | null;
+  name?: string | null;
+  kind?: string | null;
+  is_active?: boolean | null;
+  secret_ref_name?: string | null;
+};
+
+export type Env = Record<string, string | undefined>;
+
+export function isValidSecretRefName(value: unknown): value is string {
+  return typeof value === "string" && SECRET_REF_NAME_RE.test(value);
+}
+
+function label(provider: ProviderSecretRow): string {
+  return provider.name?.trim() || provider.kind?.trim() || provider.id || "provider";
+}
+
+export type SecretResolution =
+  { ok: true; name: string; value: string } | { ok: false; name: string | null; error: string };
+
+/**
+ * Resolve one provider's credential. Errors mention only the variable name,
+ * never a value.
+ */
+export function resolveProviderSecret(
+  provider: ProviderSecretRow,
+  env: Env = process.env,
+): SecretResolution {
+  const raw = provider.secret_ref_name;
+  const who = label(provider);
+  if (raw == null || String(raw).trim() === "") {
+    return {
+      ok: false,
+      name: null,
+      error: `Provider "${who}" has no secret reference name configured.`,
+    };
+  }
+  const name = String(raw).trim();
+  if (!isValidSecretRefName(name)) {
+    return {
+      ok: false,
+      name: null,
+      error:
+        `Provider "${who}" has an invalid secret reference name — ` +
+        `it must match ${SECRET_REF_NAME_RE.source}.`,
+    };
+  }
+  const value = env[name];
+  if (value == null || value === "") {
+    return {
+      ok: false,
+      name,
+      error: `Environment variable "${name}" is not set on the server (provider "${who}").`,
+    };
+  }
+  return { ok: true, name, value };
+}
+
+export type ProviderSecretRequirement = {
+  provider: string;
+  kind: string | null;
+  name: string | null;
+  valid: boolean;
+  present: boolean;
+};
+
+/** Every active provider's required variable name — values are never read out. */
+export function requiredProviderSecrets(
+  providers: ProviderSecretRow[],
+  env: Env = process.env,
+): ProviderSecretRequirement[] {
+  return providers
+    .filter((p) => p.is_active !== false)
+    .map((p) => {
+      const res = resolveProviderSecret(p, env);
+      const name = res.ok ? res.name : res.name;
+      return {
+        provider: label(p),
+        kind: p.kind ?? null,
+        name,
+        valid: name !== null,
+        present: res.ok,
+      };
+    });
+}
+
+/** Distinct, valid variable names that must be configured. */
+export function requiredSecretNames(providers: ProviderSecretRow[]): string[] {
+  const out = new Set<string>();
+  for (const p of providers) {
+    if (p.is_active === false) continue;
+    const raw = typeof p.secret_ref_name === "string" ? p.secret_ref_name.trim() : "";
+    if (isValidSecretRefName(raw)) out.add(raw);
+  }
+  return [...out].sort();
+}
+
+/**
+ * Providers whose secret reference name is present but unsafe. A hard error:
+ * such a name can never be resolved to an environment variable.
+ */
+export function invalidSecretProviders(providers: ProviderSecretRow[]): string[] {
+  return providers
+    .filter((p) => p.is_active !== false)
+    .filter((p) => {
+      const raw = typeof p.secret_ref_name === "string" ? p.secret_ref_name.trim() : "";
+      return raw !== "" && !isValidSecretRefName(raw);
+    })
+    .map((p) => `${label(p)}: invalid secret reference name`);
+}
+
+/** Active providers that name no secret at all — a hard error. */
+export function providersWithoutSecretRef(providers: ProviderSecretRow[]): string[] {
+  return providers
+    .filter((p) => p.is_active !== false)
+    .filter((p) => (typeof p.secret_ref_name === "string" ? p.secret_ref_name.trim() : "") === "")
+    .map((p) => `${label(p)}: no secret reference name configured`);
+}
+
+/**
+ * Every hard problem with provider secret references: unsafe names and
+ * missing/blank names on active providers. Inactive providers are ignored.
+ * Values are never inspected or printed.
+ */
+export function secretRefProblems(providers: ProviderSecretRow[]): string[] {
+  return [...invalidSecretProviders(providers), ...providersWithoutSecretRef(providers)];
+}
+
+/**
+ * Operator-facing, value-free report of what must go into
+ * `deploy/provider-secrets.env`.
+ */
+export function formatProviderSecretReport(
+  providers: ProviderSecretRow[],
+  env: Env = process.env,
+): string {
+  const reqs = requiredProviderSecrets(providers, env);
+  if (reqs.length === 0) return "No active email providers — no provider secrets are required.";
+  const lines = [
+    "Provider secrets to configure in deploy/provider-secrets.env (names only):",
+    ...reqs.map((r) => {
+      const state = !r.valid ? "INVALID/MISSING NAME" : r.present ? "set" : "NOT SET";
+      return `  ${(r.name ?? "(none)").padEnd(28)} ${state.padEnd(20)} ${r.provider}${r.kind ? ` (${r.kind})` : ""}`;
+    }),
+    "",
+    `System mail (account/password emails) uses ${SYSTEM_SMTP_SECRET_NAME} and is configured separately in .env.`,
+    "Never paste secret values into chat, logs, PostgreSQL, Git or the migration package.",
+  ];
+  return lines.join("\n");
+}

package/src/server/smtp.ts

@@ -0,0 +1,416 @@
+/**
+ * Minimal SMTP client for the serverless runtime.
+ *
+ * Node mail libraries (nodemailer & co.) cannot run here, but the runtime does
+ * expose raw TCP sockets, so we speak SMTP directly:
+ *
+ *   greeting -> EHLO -> STARTTLS -> TLS upgrade -> EHLO -> AUTH -> MAIL FROM
+ *   -> RCPT TO -> DATA -> message -> QUIT
+ *
+ * Only explicit-TLS-on-connect (port 465) is out of reach: the socket API can
+ * upgrade a plain connection to TLS but cannot open an encrypted one. Use the
+ * submission port (587) instead.
+ *
+ * Server-only. Never import from client code.
+ */
+
+export type SmtpConfig = {
+  host: string;
+  port: number;
+  username?: string;
+  password?: string;
+};
+
+export type SmtpMessage = {
+  to: string;
+  fromEmail: string;
+  fromName?: string | null;
+  replyTo?: string | null;
+  subject: string;
+  text: string;
+  html: string;
+};
+
+export type SmtpResult = { ok: true } | { ok: false; error: string };
+
+const CONNECT_TIMEOUT_MS = 15_000;
+const HOST_RE =
+  /^(?=.{1,253}$)[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+const BLOCKED_HOSTS = new Set([
+  "localhost",
+  "localhost.localdomain",
+  "127.0.0.1",
+  "0.0.0.0",
+  "::1",
+]);
+
+/** Ports we allow outbound. 465 is deliberately excluded (implicit TLS). */
+export const ALLOWED_SMTP_PORTS = [25, 587, 2525] as const;
+
+export function validateSmtpTarget(host: string, port: number): string | null {
+  const h = host.trim().toLowerCase();
+  if (!h) return "SMTP host is missing in the provider config.";
+  if (BLOCKED_HOSTS.has(h)) return "Connections to localhost are not allowed.";
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(h)) {
+    const [a, b] = h.split(".").map(Number);
+    if (
+      a === 10 ||
+      a === 127 ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && b === 168) ||
+      (a === 169 && b === 254)
+    ) {
+      return "Connections to private network addresses are not allowed.";
+    }
+  } else if (!HOST_RE.test(h)) {
+    return `"${host}" is not a valid SMTP host name.`;
+  }
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return "SMTP port is invalid.";
+  if (port === 465) {
+    return "Port 465 (implicit TLS) is not supported by this runtime. Use port 587 with STARTTLS instead.";
+  }
+  if (!(ALLOWED_SMTP_PORTS as readonly number[]).includes(port)) {
+    return `Port ${port} is not allowed. Use 587 (recommended), 2525 or 25.`;
+  }
+  return null;
+}
+
+/* ---------------- reply parsing ---------------- */
+
+export type SmtpReply = { code: number; lines: string[]; text: string };
+
+/** True when `buf` holds a complete SMTP reply (last line uses "NNN " not "NNN-"). */
+export function isCompleteReply(buf: string): boolean {
+  const lines = buf.split(/\r?\n/).filter((l) => l.length > 0);
+  if (!lines.length) return false;
+  const last = lines[lines.length - 1];
+  return /^\d{3}(\s|$)/.test(last);
+}
+
+export function parseReply(buf: string): SmtpReply {
+  const lines = buf.split(/\r?\n/).filter((l) => l.length > 0);
+  const code = Number(lines[lines.length - 1]?.slice(0, 3)) || 0;
+  const text = lines
+    .map((l) => l.slice(4))
+    .join(" ")
+    .trim();
+  return { code, lines, text };
+}
+
+/* ---------------- MIME message ---------------- */
+
+function encodeHeaderWord(value: string): string {
+  // RFC 2047 for any non-ASCII header content.
+  if (/^[\x20-\x7e]*$/.test(value)) return value;
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return `=?UTF-8?B?${btoa(binary)}?=`;
+}
+
+function addressHeader(email: string, name?: string | null): string {
+  return name ? `${encodeHeaderWord(name)} <${email}>` : email;
+}
+
+/** Escapes leading dots so message content cannot terminate the DATA stage. */
+function dotStuff(body: string): string {
+  return body.replace(/\r?\n/g, "\r\n").replace(/^\./gm, "..");
+}
+
+export function buildMimeMessage(msg: SmtpMessage, domain: string): string {
+  const boundary = `sba-${crypto.randomUUID()}`;
+  const headers = [
+    `From: ${addressHeader(msg.fromEmail, msg.fromName)}`,
+    `To: ${msg.to}`,
+    ...(msg.replyTo ? [`Reply-To: ${msg.replyTo}`] : []),
+    `Subject: ${encodeHeaderWord(msg.subject)}`,
+    `Date: ${new Date().toUTCString()}`,
+    `Message-ID: <${crypto.randomUUID()}@${domain}>`,
+    "MIME-Version: 1.0",
+    `Content-Type: multipart/alternative; boundary="${boundary}"`,
+  ];
+  const body = [
+    `--${boundary}`,
+    'Content-Type: text/plain; charset="UTF-8"',
+    "Content-Transfer-Encoding: 8bit",
+    "",
+    dotStuff(msg.text),
+    `--${boundary}`,
+    'Content-Type: text/html; charset="UTF-8"',
+    "Content-Transfer-Encoding: 8bit",
+    "",
+    dotStuff(msg.html),
+    `--${boundary}--`,
+  ].join("\r\n");
+  return `${headers.join("\r\n")}\r\n\r\n${body}`;
+}
+
+/* ---------------- connection ---------------- */
+
+type AnySocket = {
+  readable: ReadableStream<Uint8Array>;
+  writable: WritableStream<Uint8Array>;
+  close: () => Promise<void> | void;
+  startTls: () => AnySocket;
+};
+
+/**
+ * Node fallback (vite dev / any Node host): wrap a `node:net` socket in the
+ * same web-stream shape the Workers socket API exposes, with `startTls()`
+ * upgrading the live connection via `node:tls`.
+ */
+type NodeRawSocket = {
+  on(event: "data", cb: (chunk: Buffer) => void): void;
+  once(event: string, cb: (...args: never[]) => void): void;
+  off(event: "data", cb: (chunk: Buffer) => void): void;
+  removeAllListeners(event: string): void;
+  write(chunk: Buffer, cb: (err?: Error | null) => void): void;
+  destroy(): void;
+  __smtpHost?: string;
+};
+
+type NodeNetModule = { connect: (opts: { host: string; port: number }) => NodeRawSocket };
+type NodeTlsModule = {
+  connect: (opts: {
+    socket: NodeRawSocket;
+    servername?: string;
+    rejectUnauthorized: boolean;
+  }) => NodeRawSocket;
+};
+type WorkerSocketsModule = {
+  connect: (
+    address: { hostname: string; port: number },
+    options: { allowHalfOpen: boolean; secureTransport: string },
+  ) => AnySocket;
+};
+
+function wrapNodeSocket(raw: NodeRawSocket): AnySocket {
+  let onData: ((chunk: Buffer) => void) | null = null;
+  const readable = new ReadableStream<Uint8Array>({
+    start(controller) {
+      onData = (chunk) => controller.enqueue(new Uint8Array(chunk));
+      raw.on("data", onData);
+      raw.once("end", () => {
+        try {
+          controller.close();
+        } catch {
+          /* closed */
+        }
+      });
+      raw.once("error", (e: Error) => {
+        try {
+          controller.error(e);
+        } catch {
+          /* closed */
+        }
+      });
+    },
+    cancel() {
+      if (onData) raw.off("data", onData);
+    },
+  });
+  const writable = new WritableStream<Uint8Array>({
+    write(chunk) {
+      return new Promise<void>((resolve, reject) =>
+        raw.write(Buffer.from(chunk), (err?: Error | null) => (err ? reject(err) : resolve())),
+      );
+    },
+  });
+  return {
+    readable,
+    writable,
+    close: () => {
+      raw.destroy();
+    },
+    startTls: () => {
+      if (onData) raw.off("data", onData);
+      raw.removeAllListeners("end");
+      raw.removeAllListeners("error");
+
+      const tls = (globalThis as unknown as { __smtpTls: NodeTlsModule }).__smtpTls;
+      const secure = tls.connect({
+        socket: raw,
+        servername: raw.__smtpHost,
+        rejectUnauthorized: true,
+      });
+      secure.__smtpHost = raw.__smtpHost;
+      return wrapNodeSocket(secure);
+    },
+  };
+}
+
+async function openNodeSocket(host: string, port: number): Promise<AnySocket | null> {
+  try {
+    const net = (await import(/* @vite-ignore */ "node:net" as string)) as unknown as NodeNetModule;
+    const tls = (await import(/* @vite-ignore */ "node:tls" as string)) as unknown as NodeTlsModule;
+    if (!net?.connect) return null;
+    (globalThis as unknown as { __smtpTls: NodeTlsModule }).__smtpTls = tls;
+    const raw = await new Promise<NodeRawSocket>((resolve, reject) => {
+      const sock = net.connect({ host, port });
+      sock.once("connect", () => resolve(sock));
+      sock.once("error", reject);
+    });
+    raw.__smtpHost = host;
+    return wrapNodeSocket(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function openSocket(host: string, port: number): Promise<AnySocket> {
+  const specifier = "cloudflare:sockets";
+  const mod = (await import(/* @vite-ignore */ specifier).catch(
+    () => null,
+  )) as WorkerSocketsModule | null;
+  if (mod?.connect) {
+    return mod.connect(
+      { hostname: host, port },
+      { allowHalfOpen: false, secureTransport: "starttls" },
+    );
+  }
+  const node = await openNodeSocket(host, port);
+  if (node) return node;
+  throw new Error("Raw TCP sockets are unavailable in this runtime, so SMTP cannot be used here.");
+}
+
+class SmtpSession {
+  private reader: ReadableStreamDefaultReader<Uint8Array>;
+  private writer: WritableStreamDefaultWriter<Uint8Array>;
+  private decoder = new TextDecoder();
+  private encoder = new TextEncoder();
+  private buffer = "";
+
+  constructor(private socket: AnySocket) {
+    this.reader = socket.readable.getReader();
+    this.writer = socket.writable.getWriter();
+  }
+
+  static async open(host: string, port: number) {
+    return new SmtpSession(await openSocket(host, port));
+  }
+
+  async read(): Promise<SmtpReply> {
+    while (!isCompleteReply(this.buffer)) {
+      const { value, done } = await this.reader.read();
+      if (done) break;
+      if (value) this.buffer += this.decoder.decode(value, { stream: true });
+    }
+    const reply = parseReply(this.buffer);
+    this.buffer = "";
+    if (!reply.code) throw new Error("The mail server closed the connection unexpectedly.");
+    return reply;
+  }
+
+  async send(line: string): Promise<SmtpReply> {
+    await this.writer.write(this.encoder.encode(`${line}\r\n`));
+    return this.read();
+  }
+
+  async sendRaw(data: string): Promise<void> {
+    await this.writer.write(this.encoder.encode(data));
+  }
+
+  /** Upgrade to TLS after a 220 STARTTLS reply, replacing the reader/writer. */
+  async upgrade(): Promise<void> {
+    this.reader.releaseLock();
+    this.writer.releaseLock();
+    this.socket = this.socket.startTls();
+    this.reader = this.socket.readable.getReader();
+    this.writer = this.socket.writable.getWriter();
+    this.buffer = "";
+  }
+
+  async close(): Promise<void> {
+    try {
+      this.reader.releaseLock();
+      this.writer.releaseLock();
+      await this.socket.close();
+    } catch {
+      /* already closed */
+    }
+  }
+}
+
+function expect(reply: SmtpReply, ok: number[], stage: string): void {
+  if (!ok.includes(reply.code)) {
+    throw new Error(`${stage} failed — server said ${reply.code} ${reply.text}`);
+  }
+}
+
+function b64(value: string): string {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+
+async function deliver(config: SmtpConfig, msg: SmtpMessage): Promise<void> {
+  const clientDomain = msg.fromEmail.split("@")[1] || "localhost";
+  const session = await SmtpSession.open(config.host, config.port);
+  try {
+    expect(await session.read(), [220], "Connection");
+
+    let ehlo = await session.send(`EHLO ${clientDomain}`);
+    expect(ehlo, [250], "EHLO");
+
+    const supportsStartTls = ehlo.lines.some((l) => /STARTTLS/i.test(l));
+    if (supportsStartTls) {
+      expect(await session.send("STARTTLS"), [220], "STARTTLS");
+      await session.upgrade();
+      ehlo = await session.send(`EHLO ${clientDomain}`);
+      expect(ehlo, [250], "EHLO after STARTTLS");
+    } else if (config.port !== 25) {
+      throw new Error(
+        "The mail server does not advertise STARTTLS, so credentials cannot be sent securely.",
+      );
+    }
+
+    if (config.username && config.password) {
+      const authLine = ehlo.lines.find((l) => /AUTH\s/i.test(l)) ?? "";
+      if (/PLAIN/i.test(authLine) && !/LOGIN/i.test(authLine)) {
+        const token = b64(`\0${config.username}\0${config.password}`);
+        expect(await session.send(`AUTH PLAIN ${token}`), [235], "Authentication");
+      } else {
+        expect(await session.send("AUTH LOGIN"), [334], "Authentication");
+        expect(await session.send(b64(config.username)), [334], "Authentication (username)");
+        expect(await session.send(b64(config.password)), [235], "Authentication (password)");
+      }
+    }
+
+    expect(await session.send(`MAIL FROM:<${msg.fromEmail}>`), [250], "MAIL FROM");
+    expect(await session.send(`RCPT TO:<${msg.to}>`), [250, 251], "RCPT TO");
+    expect(await session.send("DATA"), [354], "DATA");
+    await session.sendRaw(`${buildMimeMessage(msg, clientDomain)}\r\n.\r\n`);
+    expect(await session.read(), [250], "Message delivery");
+
+    await session.send("QUIT").catch(() => undefined);
+  } finally {
+    await session.close();
+  }
+}
+
+export async function sendSmtp(config: SmtpConfig, msg: SmtpMessage): Promise<SmtpResult> {
+  const invalid = validateSmtpTarget(config.host, config.port);
+  if (invalid) return { ok: false, error: invalid };
+  if (config.username && !config.password) {
+    return { ok: false, error: "SMTP password secret is not available on the server." };
+  }
+  try {
+    await Promise.race([
+      deliver(config, msg),
+      new Promise<never>((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`No response from ${config.host}:${config.port} within 15s.`)),
+          CONNECT_TIMEOUT_MS,
+        ),
+      ),
+    ]);
+    return { ok: true };
+  } catch (err) {
+    const base = err instanceof Error ? err.message : String(err);
+    const hint = /unavailable in this runtime|refused|not allowed|within 15s/i.test(base)
+      ? " If your host blocks outbound SMTP, use the Mailgun, Amazon SES or HTTP endpoint provider instead."
+      : "";
+    return { ok: false, error: `${base}${hint}` };
+  }
+}