@bygghammar/cms-platform 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.37.0
+
+- Added `server/forms-delivery-core` — the full form submission delivery stack
+  (email provider resolution, smart-tag template rendering, admin notification,
+  autoreply, email logging, Google Sheets append and signed outbound webhook) is
+  now shared. A site keeps only a thin adapter that supplies its privileged
+  database client.
+
+## 0.36.0
+
+- New server cores: `server/provider-secrets`, `server/smtp` and
+  `server/email-send-core`. Provider credential resolution, the raw-socket
+  STARTTLS SMTP client and all provider transports (Mailgun, Amazon SES, HTTP
+  endpoint, SMTP) are now shared, so a site keeps only re-export adapters.
+
 ## 0.35.0
 
 - Added `tracking/injections` — the pure "Code & tracking" helpers (profile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.35.0",
+  "version": "0.37.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,11 @@
     "./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",
+    "./server/forms-delivery-core": "./src/server/forms-delivery-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/forms-delivery-core.ts

@@ -0,0 +1,504 @@
+/**
+ * Host-agnostic delivery side effects for form submissions: admin
+ * notification email, autoreply to the submitter, Google Sheets append and
+ * outbound webhook.
+ *
+ * Never throws — every function reports failure back so the submission itself
+ * is always kept (submissions are append-only, customer data first).
+ *
+ * The host injects a privileged database client; everything else (provider
+ * resolution, template rendering, email logging) is shared.
+ *
+ * Server-only. Never import from client code.
+ */
+
+import type { FormFieldDef } from "../forms/field-sets";
+import { sendViaProvider } from "./email-send-core";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/** Structural subset of a Supabase-shaped privileged client. */
+export type DeliveryDb = { from: (table: string) => any };
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+export type DeliveryResult = { ok: boolean; error?: string };
+
+type ResolvedProvider = {
+  id: string;
+  name: string;
+  kind: string;
+  fromName: string | null;
+  fromEmail: string;
+  replyTo: string | null;
+};
+
+type ProviderRow = {
+  id: string;
+  name: string;
+  kind: string;
+  from_name: string | null;
+  from_email: string | null;
+  reply_to: string | null;
+  config: Record<string, unknown> | null;
+  secret_ref_name: string | null;
+  is_active?: boolean | null;
+  sort_order?: number | null;
+};
+
+/** Resolve the default (or first active) email provider plus sender identity. */
+export async function resolveDeliveryProvider(
+  db: DeliveryDb,
+): Promise<
+  { ok: true; provider: ResolvedProvider; raw: ProviderRow } | { ok: false; error: string }
+> {
+  const { data: settings } = await db
+    .from("email_settings")
+    .select("*")
+    .eq("id", true)
+    .maybeSingle();
+
+  let raw: ProviderRow | null = null;
+  if (settings?.default_provider_id) {
+    const { data } = await db
+      .from("email_providers")
+      .select("*")
+      .eq("id", settings.default_provider_id)
+      .maybeSingle();
+    raw = (data ?? null) as ProviderRow | null;
+  }
+  if (!raw) {
+    const { data } = await db
+      .from("email_providers")
+      .select("*")
+      .eq("is_active", true)
+      .order("sort_order", { ascending: true })
+      .limit(1);
+    raw = ((data as ProviderRow[] | null)?.[0] ?? null) as ProviderRow | null;
+  }
+  if (!raw) return { ok: false, error: "No active email provider configured." };
+
+  const fromEmail = raw.from_email ?? settings?.primary_from_email ?? null;
+  if (!fromEmail) return { ok: false, error: "No from address configured." };
+
+  return {
+    ok: true,
+    raw,
+    provider: {
+      id: raw.id,
+      name: raw.name,
+      kind: raw.kind,
+      fromName: raw.from_name ?? settings?.primary_from_name ?? null,
+      fromEmail,
+      replyTo: raw.reply_to ?? settings?.reply_to ?? null,
+    },
+  };
+}
+
+type SenderOverride = {
+  fromName?: string | null;
+  fromEmail?: string | null;
+  replyTo?: string | null;
+};
+
+async function dispatch(
+  db: DeliveryDb,
+  raw: ProviderRow,
+  provider: ResolvedProvider,
+  msg: { to: string; subject: string; html: string; text: string; replyTo: string | null },
+  meta: Record<string, unknown>,
+  from: SenderOverride = {},
+): Promise<DeliveryResult> {
+  const fromName = (from.fromName ?? "").trim() || provider.fromName;
+  const fromEmail = (from.fromEmail ?? "").trim() || provider.fromEmail;
+
+  const result = await sendViaProvider(
+    {
+      id: provider.id,
+      name: provider.name,
+      kind: provider.kind,
+      from_name: fromName,
+      from_email: fromEmail,
+      reply_to: msg.replyTo,
+      config: (raw.config ?? {}) as Record<string, unknown>,
+      secret_ref_name: raw.secret_ref_name,
+    },
+    {
+      to: msg.to,
+      subject: msg.subject,
+      html: msg.html,
+      text: msg.text,
+      fromName,
+      fromEmail,
+      replyTo: msg.replyTo,
+    },
+  );
+
+  await db.from("email_logs").insert({
+    to_address: msg.to,
+    from_address: fromEmail,
+    reply_to: msg.replyTo,
+    subject: msg.subject,
+    body_preview: msg.text.slice(0, 200),
+    provider: provider.name,
+    status: result.ok ? "sent" : "failed",
+    error: result.ok ? null : result.error,
+    meta: { ...meta, kind: provider.kind },
+  });
+
+  return result.ok ? { ok: true } : { ok: false, error: result.error };
+}
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const labelOf = (fld: FormFieldDef) => fld.label.sv ?? fld.label.en ?? fld.key;
+
+/** Replace {{field_key}} placeholders with submitted values. */
+export function renderTemplate(
+  input: string,
+  payload: Record<string, string>,
+  extra: Record<string, string> = {},
+): string {
+  const all = { ...payload, ...extra };
+  return input.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (_m, key: string) => all[key] ?? "");
+}
+
+/** Context tokens available to every notification/autoreply template. */
+export type TokenContext = {
+  formName: string;
+  formKey: string;
+  locale?: string;
+  pagePath?: string | null;
+  submissionId?: string | null;
+  ip?: string | null;
+  userAgent?: string | null;
+  referrer?: string | null;
+  /** Absolute origin of the site, used to build page_url / admin_url. */
+  siteUrl?: string | null;
+  /** Backoffice base path, defaults to `/kontoret`. */
+  backofficePath?: string;
+};
+
+/** Tokens every notification/autoreply template can use besides field keys. */
+export function templateTokens(opts: TokenContext): Record<string, string> {
+  const origin = (opts.siteUrl ?? "").replace(/\/+$/, "");
+  const path = opts.pagePath ?? "";
+  const base = (opts.backofficePath ?? "/kontoret").replace(/\/+$/, "");
+  const adminUrl = origin
+    ? `${origin}${base}/forms/submissions?form=${encodeURIComponent(opts.formKey)}${
+        opts.submissionId ? `&q=${encodeURIComponent(opts.submissionId)}` : ""
+      }`
+    : "";
+  return {
+    form: opts.formName,
+    form_name: opts.formName,
+    form_key: opts.formKey,
+    locale: opts.locale ?? "",
+    page: path,
+    page_url: origin && path ? `${origin}${path.startsWith("/") ? "" : "/"}${path}` : "",
+    admin_url: adminUrl,
+    ip: opts.ip ?? "",
+    user_agent: opts.userAgent ?? "",
+    referrer: opts.referrer ?? "",
+    date: new Date().toLocaleString("sv-SE"),
+    submission_id: opts.submissionId ?? "",
+  };
+}
+
+const EMAIL_TOKEN_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+/** Render smart tags inside a single-line header value (sender name, reply-to). */
+export function renderHeader(
+  input: string | undefined,
+  payload: Record<string, string>,
+  tokens: Record<string, string>,
+): string {
+  return renderTemplate((input ?? "").trim(), payload, tokens)
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const TABLE_TOKEN = "\u0000FIELDS_TABLE\u0000";
+
+/** Every alias that expands to the full answer table. */
+const tableTokens = (value: string): Record<string, string> => ({
+  fields_table: value,
+  all_fields: value,
+  all_answers: value,
+});
+
+function answerRows(fields: FormFieldDef[], payload: Record<string, string>) {
+  return fields
+    .filter((fl) => fl.enabled)
+    .map((fl) => [labelOf(fl), payload[fl.key] ?? ""] as const)
+    .filter(([, v]) => v !== "");
+}
+
+function tableHtml(rows: readonly (readonly [string, string])[]) {
+  return `<table style="font-family:Arial,sans-serif;border-collapse:collapse">
+${rows
+  .map(
+    ([k, v]) =>
+      `<tr><td style="padding:4px 12px 4px 0;color:#666;vertical-align:top">${esc(k)}</td><td style="padding:4px 0">${esc(v).replace(/\n/g, "<br>")}</td></tr>`,
+  )
+  .join("")}
+</table>`;
+}
+
+export type NotifyOptions = TokenContext & {
+  to: string;
+  locale: string;
+  fields: FormFieldDef[];
+  payload: Record<string, string>;
+  /** Optional custom templates; empty falls back to the standard layout. */
+  subject?: string;
+  body?: string;
+  fromName?: string;
+  fromEmail?: string;
+  replyTo?: string;
+};
+
+/** Admin notification email for a new submission (one mail per recipient). */
+export async function notifySubmissionCore(
+  db: DeliveryDb,
+  opts: NotifyOptions,
+): Promise<DeliveryResult> {
+  const recipients = Array.from(
+    new Set(
+      opts.to
+        .split(/[,;\s]+/)
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.includes("@")),
+    ),
+  );
+  if (recipients.length === 0) return { ok: true };
+
+  const resolved = await resolveDeliveryProvider(db);
+  if (!resolved.ok) return { ok: false, error: resolved.error };
+
+  const rows = answerRows(opts.fields, opts.payload);
+  const tokens = templateTokens(opts);
+  const plainTable = rows.map(([k, v]) => `${k}: ${v}`).join("\n");
+  const escapedPayload = Object.fromEntries(
+    Object.entries(opts.payload).map(([k, v]) => [k, esc(v)]),
+  );
+
+  // Smart tags are allowed in the sender name and reply-to; an unusable
+  // reply-to falls back to the submitter's address, then the provider default.
+  const renderedReplyTo = renderHeader(opts.replyTo, opts.payload, tokens);
+  const replyTo = EMAIL_TOKEN_RE.test(renderedReplyTo)
+    ? renderedReplyTo
+    : opts.payload.email?.includes("@")
+      ? opts.payload.email
+      : resolved.provider.replyTo;
+  const fromName = renderHeader(opts.fromName, opts.payload, tokens) || undefined;
+
+  const subjectTpl = (opts.subject ?? "").trim();
+  const subject = subjectTpl
+    ? renderTemplate(subjectTpl, opts.payload, { ...tokens, ...tableTokens(plainTable) }).trim() ||
+      `${opts.formName}: new submission`
+    : `${opts.formName}: new submission`;
+
+  const bodyTpl = (opts.body ?? "").trim();
+  let text: string;
+  let html: string;
+
+  if (bodyTpl) {
+    text = renderTemplate(bodyTpl, opts.payload, { ...tokens, ...tableTokens(plainTable) });
+    const htmlSource = renderTemplate(esc(bodyTpl), escapedPayload, {
+      ...Object.fromEntries(Object.entries(tokens).map(([k, v]) => [k, esc(v)])),
+      ...tableTokens(TABLE_TOKEN),
+    });
+    html = `<div style="font-family:Arial,sans-serif;font-size:15px;line-height:1.6;color:#111">${htmlSource
+      .replace(/\n/g, "<br>")
+      .replace(TABLE_TOKEN, tableHtml(rows))}</div>`;
+  } else {
+    text = [
+      `Form: ${opts.formName} (${opts.formKey})`,
+      `Language: ${opts.locale}`,
+      opts.pagePath ? `Page: ${opts.pagePath}` : "",
+      "",
+      plainTable,
+    ]
+      .filter(Boolean)
+      .join("\n");
+    html = `<h2 style="font-family:Arial,sans-serif">${esc(opts.formName)}</h2>
+${tableHtml(rows)}
+<p style="font-family:Arial,sans-serif;color:#888;font-size:12px">${esc(opts.formKey)} · ${esc(opts.locale)}${opts.pagePath ? ` · ${esc(opts.pagePath)}` : ""}</p>`;
+  }
+
+  let lastError: string | undefined;
+  let anyOk = false;
+  for (const to of recipients) {
+    const res = await dispatch(
+      db,
+      resolved.raw,
+      resolved.provider,
+      { to, subject, html, text, replyTo },
+      { form_key: opts.formKey, purpose: "form_notification" },
+      { fromName, fromEmail: opts.fromEmail },
+    );
+    if (res.ok) anyOk = true;
+    else lastError = res.error;
+  }
+  return anyOk ? { ok: true } : { ok: false, error: lastError };
+}
+
+export type AutoreplyOptions = TokenContext & {
+  to: string;
+  subject: string;
+  body: string;
+  payload: Record<string, string>;
+  /** Optional — enables the {{all_fields}} answer table. */
+  fields?: FormFieldDef[];
+  fromName?: string;
+  fromEmail?: string;
+  replyTo?: string;
+};
+
+/** Confirmation email back to the person who submitted the form. */
+export async function sendAutoreplyCore(
+  db: DeliveryDb,
+  opts: AutoreplyOptions,
+): Promise<DeliveryResult> {
+  const to = opts.to.trim();
+  if (!to || !EMAIL_TOKEN_RE.test(to)) {
+    return { ok: false, error: "No valid email address in the submission." };
+  }
+  const rows = answerRows(opts.fields ?? [], opts.payload);
+  const plainTable = rows.map(([k, v]) => `${k}: ${v}`).join("\n");
+  const tokens = { ...templateTokens(opts), ...tableTokens(plainTable) };
+  const subject = renderTemplate(opts.subject, opts.payload, tokens).trim();
+  const body = renderTemplate(opts.body, opts.payload, tokens).trim();
+  if (!subject || !body) return { ok: false, error: "Autoreply subject or body is empty." };
+
+  const resolved = await resolveDeliveryProvider(db);
+  if (!resolved.ok) return { ok: false, error: resolved.error };
+
+  const html = `<div style="font-family:Arial,sans-serif;font-size:15px;line-height:1.6;color:#111">${esc(
+    body,
+  ).replace(/\n/g, "<br>")}</div>`;
+
+  const renderedReplyTo = renderHeader(opts.replyTo, opts.payload, tokens);
+  const fromName = renderHeader(opts.fromName, opts.payload, tokens) || undefined;
+
+  return dispatch(
+    db,
+    resolved.raw,
+    resolved.provider,
+    {
+      to,
+      subject,
+      html,
+      text: body,
+      replyTo: EMAIL_TOKEN_RE.test(renderedReplyTo) ? renderedReplyTo : resolved.provider.replyTo,
+    },
+    { form_key: opts.formKey, purpose: "form_autoreply" },
+    { fromName, fromEmail: opts.fromEmail },
+  );
+}
+
+const GATEWAY = "https://connector-gateway.lovable.dev/google_sheets/v4";
+
+/** Append one submission row to a Google Sheet via the connector gateway. */
+export async function appendToSheetCore(opts: {
+  sheetId: string;
+  tab: string;
+  values: string[];
+}): Promise<DeliveryResult> {
+  const lovableKey = process.env['LOVABLE_API_KEY'];
+  const connKey = process.env['GOOGLE_SHEETS_API_KEY'];
+  if (!opts.sheetId) return { ok: false, error: "No Google Sheet configured." };
+  if (!lovableKey || !connKey)
+    return { ok: false, error: "Google Sheets is not connected for this project." };
+
+  const tab = opts.tab?.trim() || "Sheet1";
+  const range = `${tab}!A:Z`;
+  const res = await fetch(
+    `${GATEWAY}/spreadsheets/${opts.sheetId}/values/${range}:append?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${lovableKey}`,
+        "X-Connection-Api-Key": connKey,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ values: [opts.values] }),
+    },
+  );
+  if (!res.ok) {
+    const body = await res.text();
+    console.error(`[forms] sheets append failed [${res.status}]: ${body}`);
+    return { ok: false, error: `Google Sheets [${res.status}]: ${body.slice(0, 300)}` };
+  }
+  return { ok: true };
+}
+
+/**
+ * POST one submission to an external endpoint (CRM, Zapier, Make…).
+ * Signed with an optional shared secret so the receiver can verify origin.
+ * Never throws: the submission is already stored and must never be lost.
+ */
+export async function postWebhookCore(opts: {
+  url: string;
+  secret?: string | null;
+  formKey: string;
+  formName: string;
+  submissionId: string;
+  locale: string;
+  pagePath?: string | null;
+  createdAt: string;
+  payload: Record<string, string>;
+  timeoutMs?: number;
+}): Promise<DeliveryResult & { status?: number }> {
+  const url = (opts.url ?? "").trim();
+  if (!url) return { ok: false, error: "No webhook URL configured." };
+  if (!/^https:\/\//i.test(url))
+    return { ok: false, error: "Webhook URL must start with https://" };
+
+  const body = JSON.stringify({
+    event: "form.submission",
+    form: { key: opts.formKey, name: opts.formName },
+    submission: {
+      id: opts.submissionId,
+      locale: opts.locale,
+      page_path: opts.pagePath ?? null,
+      created_at: opts.createdAt,
+      payload: opts.payload,
+    },
+  });
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-Form-Key": opts.formKey,
+    "X-Submission-Id": opts.submissionId,
+  };
+  const secret = (opts.secret ?? "").trim();
+  if (secret) {
+    try {
+      const { createHmac } = await import("crypto");
+      headers["X-Signature"] = createHmac("sha256", secret).update(body).digest("hex");
+    } catch {
+      /* signing unavailable — send unsigned rather than dropping the delivery */
+    }
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 10_000);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      const text = (await res.text().catch(() => "")).slice(0, 300);
+      return { ok: false, status: res.status, error: `Webhook [${res.status}]: ${text}` };
+    }
+    return { ok: true, status: res.status };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, error: msg === "The operation was aborted." ? "Webhook timed out." : msg };
+  } finally {
+    clearTimeout(timer);
+  }
+}

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}` };
+  }
+}