@k2b/cloud 0.26.0 → 0.28.0

package/src/services/outgoing-mail/store.ts

@@ -0,0 +1,397 @@
+import { type SQL, sql } from "bun";
+import { listApps } from "../../_internal/registry";
+import {
+  type AdminMailApp,
+  type AdminMailProfile,
+  AdminMailProfileSchema,
+  type MailAppAccess,
+  MailAppAccessSchema,
+  type MailBounceErrorCode,
+  type MailErrorCode,
+  type MailProfile,
+  type MailProfileInput,
+  MailProfileInputSchema,
+  MailProfileKeySchema,
+} from "../../contracts/outgoing-mail";
+import type { AppRegistryEntry } from "../../contracts/registry";
+import { type AuditActor, audit } from "../audit";
+import { toPgTextArray } from "../postgres";
+import { decryptValue, encryptValue } from "../settings/crypto";
+
+export class OutgoingMailError extends Error {
+  constructor(
+    public readonly code: MailErrorCode,
+    message: string,
+    public readonly status: 400 | 404 | 409 | 502 = 400,
+  ) {
+    super(message);
+  }
+}
+export type MailAuditContext = { actor: AuditActor; requestId?: string };
+type ProfileRow = {
+  id: string;
+  key: string;
+  name: string;
+  from_address: string;
+  from_name: string | null;
+  smtp_host: string;
+  smtp_port: number;
+  smtp_secure: boolean;
+  smtp_user: string | null;
+  has_password: boolean;
+  imap_host: string | null;
+  imap_port: number | null;
+  imap_secure: boolean | null;
+  imap_user: string | null;
+  imap_folder: string | null;
+  imap_has_password: boolean;
+  imap_checked_at: Date | string | null;
+  imap_error: MailBounceErrorCode | null;
+  pace_per_minute: number;
+  daily_recipient_limit: number | null;
+  max_attachment_bytes: number;
+  is_default: boolean;
+  revision: number;
+  created_at: Date | string;
+  updated_at: Date | string;
+  updated_by: string | null;
+};
+const columns = (db: SQL) => db`id, key, name, from_address, from_name, smtp_host, smtp_port, smtp_secure, smtp_user,
+  (smtp_password_encrypted IS NOT NULL) AS has_password, pace_per_minute, daily_recipient_limit, max_attachment_bytes,
+  imap_host, imap_port, imap_secure, imap_user, imap_folder,
+  (imap_password_encrypted IS NOT NULL) AS imap_has_password, imap_checked_at, imap_error,
+  is_default, revision, created_at, updated_at, updated_by`;
+const timestamp = (value: Date | string) => new Date(value).toISOString();
+const keyValue = (key: string) => {
+  const result = MailProfileKeySchema.safeParse(key);
+  if (!result.success) throw new OutgoingMailError("invalid_profile", "Invalid profile key.");
+  return result.data;
+};
+const unknown = (): never => {
+  throw new OutgoingMailError("profile_unknown", "Outgoing mail profile does not exist.", 404);
+};
+const locked = async <T>(run: (tx: SQL) => Promise<T>): Promise<T> =>
+  sql.begin(async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(hashtextextended('outgoing_mail.policy', 0))`;
+    return run(tx);
+  });
+const record = (db: SQL, context: MailAuditContext, action: string, target: string) =>
+  audit.record(
+    {
+      ...context,
+      action: `outgoing_mail.${action}`,
+      outcome: "allowed",
+      target: { type: action.startsWith("profile.") ? "outgoing_mail_profile" : "outgoing_mail_app", id: target },
+    },
+    db,
+  );
+const accessRows = async (db: SQL) => {
+  const access = await db<{ app_id: string; mode: "default" | "selected" }[]>`SELECT app_id, mode FROM outgoing_mail.app_access`;
+  const grants = await db<
+    { app_id: string; key: string }[]
+  >`SELECT ap.app_id, p.key FROM outgoing_mail.app_profiles ap JOIN outgoing_mail.profiles p ON p.id = ap.profile_id ORDER BY p.key`;
+  return { access, grants };
+};
+const mapProfile = (row: ProfileRow, appCount: number): AdminMailProfile => ({
+  key: row.key,
+  name: row.name,
+  fromAddress: row.from_address,
+  fromName: row.from_name,
+  smtpHost: row.smtp_host,
+  smtpPort: row.smtp_port,
+  smtpSecure: row.smtp_secure,
+  smtpUser: row.smtp_user,
+  hasPassword: row.has_password,
+  imap:
+    row.imap_host === null
+      ? null
+      : AdminMailProfileSchema.shape.imap.parse({
+          host: row.imap_host,
+          port: row.imap_port,
+          secure: row.imap_secure,
+          user: row.imap_user,
+          folder: row.imap_folder,
+          hasPassword: row.imap_has_password,
+        }),
+  bounces:
+    row.imap_host === null
+      ? null
+      : {
+          checkedAt: row.imap_checked_at === null ? null : timestamp(row.imap_checked_at),
+          error: row.imap_error,
+        },
+  pacePerMinute: row.pace_per_minute,
+  dailyRecipientLimit: row.daily_recipient_limit,
+  maxAttachmentBytes: row.max_attachment_bytes,
+  isDefault: row.is_default,
+  revision: row.revision,
+  createdAt: timestamp(row.created_at),
+  updatedAt: timestamp(row.updated_at),
+  updatedBy: row.updated_by,
+  appCount,
+});
+const list = async (db: SQL = sql, registeredApps?: readonly AppRegistryEntry[]): Promise<AdminMailProfile[]> => {
+  const apps = registeredApps ?? (await listApps());
+  const rows = await db<ProfileRow[]>`SELECT ${columns(db)} FROM outgoing_mail.profiles ORDER BY is_default DESC, name, key`;
+  const { access, grants } = await accessRows(db);
+  const selected = new Set(access.filter((a) => a.mode === "selected").map((a) => a.app_id));
+  const defaults = apps.filter((app) => app.platformPermissions?.includes("mail:send") && !selected.has(app.id));
+  return rows.map((row) =>
+    mapProfile(row, grants.filter((g) => g.key === row.key && selected.has(g.app_id)).length + (row.is_default ? defaults.length : 0)),
+  );
+};
+const get = async (key: string): Promise<AdminMailProfile> => {
+  keyValue(key);
+  return (await list()).find((profile) => profile.key === key) ?? unknown();
+};
+const put = async (
+  key: string,
+  value: MailProfileInput,
+  context: MailAuditContext,
+): Promise<{ profile: AdminMailProfile; created: boolean }> => {
+  keyValue(key);
+  const parsed = MailProfileInputSchema.safeParse(value);
+  if (!parsed.success) throw new OutgoingMailError("invalid_profile", "Invalid outgoing mail profile configuration.");
+  const input = parsed.data;
+  const apps = await listApps();
+  return locked(async (tx) => {
+    const [before] = await tx<ProfileRow[]>`SELECT ${columns(tx)} FROM outgoing_mail.profiles WHERE key = ${key}`;
+    if (before && input.revision === undefined)
+      throw new OutgoingMailError("profile_exists", "Profile exists; provide its current revision.", 409);
+    if (input.revision !== undefined && (!before || input.revision !== before.revision))
+      throw new OutgoingMailError("revision_conflict", "Profile revision changed; reload before replacing it.", 409);
+    if (
+      before?.has_password &&
+      input.smtpPassword === undefined &&
+      before.smtp_host.trim().toLowerCase() !== input.smtpHost.trim().toLowerCase()
+    )
+      throw new OutgoingMailError("invalid_profile", "Enter the SMTP password again, or remove it, when you change the SMTP host.");
+    const imap = input.imap ?? null;
+    if (
+      before?.imap_has_password &&
+      imap &&
+      imap.password === undefined &&
+      before.imap_host?.trim().toLowerCase() !== imap.host.trim().toLowerCase()
+    )
+      throw new OutgoingMailError("invalid_profile", "Enter the IMAP password again, or remove it, when you change the IMAP host.");
+    const imapPassword =
+      !imap || imap.password === null ? null : imap.password === undefined ? undefined : await encryptValue(imap.password);
+    const resetImap =
+      !imap ||
+      !before ||
+      before.imap_host?.toLowerCase() !== imap.host.toLowerCase() ||
+      before.imap_port !== imap.port ||
+      before.imap_user !== imap.user ||
+      before.imap_folder !== imap.folder;
+    const password =
+      input.smtpPassword === undefined ? undefined : input.smtpPassword === null ? null : await encryptValue(input.smtpPassword);
+    if (before) {
+      await tx`UPDATE outgoing_mail.profiles SET name = ${input.name}, from_address = ${input.fromAddress}, from_name = ${input.fromName},
+        smtp_host = ${input.smtpHost}, smtp_port = ${input.smtpPort}, smtp_secure = ${input.smtpSecure}, smtp_user = ${input.smtpUser},
+        smtp_password_encrypted = CASE WHEN ${password !== undefined} THEN ${password ?? null} ELSE smtp_password_encrypted END,
+        pace_per_minute = ${input.pacePerMinute}, daily_recipient_limit = ${input.dailyRecipientLimit}, max_attachment_bytes = ${input.maxAttachmentBytes},
+        revision = revision + 1, updated_at = now(), updated_by = ${context.actor.userId ?? null} WHERE key = ${key}`;
+    } else {
+      await tx`INSERT INTO outgoing_mail.profiles(id, key, name, from_address, from_name, smtp_host, smtp_port, smtp_secure, smtp_user,
+        smtp_password_encrypted, pace_per_minute, daily_recipient_limit, max_attachment_bytes, is_default, updated_by)
+        VALUES (${crypto.randomUUID()}::uuid, ${key}, ${input.name}, ${input.fromAddress}, ${input.fromName}, ${input.smtpHost}, ${input.smtpPort},
+          ${input.smtpSecure}, ${input.smtpUser}, ${password ?? null}, ${input.pacePerMinute}, ${input.dailyRecipientLimit}, ${input.maxAttachmentBytes},
+          NOT EXISTS(SELECT 1 FROM outgoing_mail.profiles), ${context.actor.userId ?? null})`;
+    }
+    await tx`UPDATE outgoing_mail.profiles SET
+      imap_host = ${imap?.host ?? null}, imap_port = ${imap?.port ?? null}, imap_secure = ${imap?.secure ?? null},
+      imap_user = ${imap?.user ?? null}, imap_folder = ${imap?.folder ?? null},
+      imap_password_encrypted = CASE WHEN ${imapPassword !== undefined} THEN ${imapPassword ?? null} ELSE imap_password_encrypted END,
+      imap_uid_validity = CASE WHEN ${resetImap} THEN NULL ELSE imap_uid_validity END,
+      imap_last_uid = CASE WHEN ${resetImap} THEN NULL ELSE imap_last_uid END,
+      imap_error = CASE WHEN ${resetImap} THEN NULL ELSE imap_error END,
+      imap_checked_at = CASE WHEN ${resetImap} THEN NULL ELSE imap_checked_at END
+      WHERE key = ${key}`;
+    await record(tx, context, before ? "profile.update" : "profile.create", key);
+    return { profile: (await list(tx, apps)).find((p) => p.key === key)!, created: !before };
+  });
+};
+const setDefault = async (key: string, context: MailAuditContext): Promise<AdminMailProfile> => {
+  keyValue(key);
+  const apps = await listApps();
+  return locked(async (tx) => {
+    const [target] = await tx<{ key: string }[]>`SELECT key FROM outgoing_mail.profiles WHERE key = ${key}`;
+    if (!target) unknown();
+    await tx`UPDATE outgoing_mail.profiles SET is_default = false, revision = revision + 1, updated_at = now(), updated_by = ${context.actor.userId ?? null} WHERE is_default AND key <> ${key}`;
+    await tx`UPDATE outgoing_mail.profiles SET is_default = true, revision = revision + 1, updated_at = now(), updated_by = ${context.actor.userId ?? null} WHERE key = ${key} AND NOT is_default`;
+    await record(tx, context, "profile.set_default", key);
+    return (await list(tx, apps)).find((p) => p.key === key)!;
+  });
+};
+const remove = async (key: string, context: MailAuditContext): Promise<void> => {
+  keyValue(key);
+  await locked(async (tx) => {
+    const [before] = await tx<{ is_default: boolean }[]>`SELECT is_default FROM outgoing_mail.profiles WHERE key = ${key}`;
+    if (!before) return unknown();
+    if (before.is_default)
+      throw new OutgoingMailError("profile_is_default", "Choose another default profile before deleting this one.", 409);
+    await tx`DELETE FROM outgoing_mail.profiles WHERE key = ${key}`;
+    await record(tx, context, "profile.delete", key);
+  });
+};
+const appsState = async (
+  db: SQL = sql,
+  registeredApps?: readonly AppRegistryEntry[],
+): Promise<{ defaultProfile: string | null; items: AdminMailApp[] }> => {
+  const registered = registeredApps ?? (await listApps());
+  const { access, grants } = await accessRows(db);
+  const [profile] = await db<{ key: string }[]>`SELECT key FROM outgoing_mail.profiles WHERE is_default`;
+  const ids = new Set([...registered.map((app) => app.id), ...access.map((a) => a.app_id)]);
+  const items = [...ids]
+    .map((appId): AdminMailApp => {
+      const app = registered.find((a) => a.id === appId);
+      const mode = access.find((a) => a.app_id === appId)?.mode ?? "default";
+      return {
+        appId,
+        name: app?.name ?? appId,
+        registered: !!app,
+        declared: !!app?.platformPermissions?.includes("mail:send"),
+        mode,
+        profiles: mode === "selected" ? grants.filter((g) => g.app_id === appId).map((g) => g.key) : [],
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name) || a.appId.localeCompare(b.appId));
+  return { defaultProfile: profile?.key ?? null, items };
+};
+const setAppAccess = async (appId: string, value: MailAppAccess, context: MailAuditContext): Promise<AdminMailApp> => {
+  if (appId === "core") throw new OutgoingMailError("invalid_profile", "Core's system email always uses the default profile.");
+  if (!appId.trim()) throw new OutgoingMailError("invalid_profile", "Application id is required.");
+  const parsed = MailAppAccessSchema.safeParse(value);
+  if (!parsed.success) throw new OutgoingMailError("invalid_profile", "Invalid application access policy.");
+  const input = parsed.data;
+  const registered = await listApps();
+  return locked(async (tx) => {
+    const keys = input.mode === "selected" ? [...new Set(input.profiles)] : [];
+    const rows = await tx<
+      { id: string; key: string }[]
+    >`SELECT id, key FROM outgoing_mail.profiles WHERE key = ANY(${toPgTextArray(keys)}::text[])`;
+    if (rows.length !== keys.length) throw new OutgoingMailError("profile_unknown", "An outgoing mail profile does not exist.");
+    await tx`DELETE FROM outgoing_mail.app_profiles WHERE app_id = ${appId}`;
+    if (input.mode === "default") await tx`DELETE FROM outgoing_mail.app_access WHERE app_id = ${appId}`;
+    else {
+      await tx`INSERT INTO outgoing_mail.app_access(app_id, mode, updated_by) VALUES (${appId}, 'selected', ${context.actor.userId ?? null})
+        ON CONFLICT(app_id) DO UPDATE SET mode = 'selected', updated_at = now(), updated_by = EXCLUDED.updated_by`;
+      for (const row of rows) await tx`INSERT INTO outgoing_mail.app_profiles(app_id, profile_id) VALUES (${appId}, ${row.id}::uuid)`;
+    }
+    await record(tx, context, "app_access.update", appId);
+    return (
+      (await appsState(tx, registered)).items.find((app) => app.appId === appId) ?? {
+        appId,
+        name: appId,
+        registered: false,
+        declared: false,
+        mode: "default",
+        profiles: [],
+      }
+    );
+  });
+};
+const profilesForApp = async (appId: string): Promise<MailProfile[]> => {
+  const rows = await sql<
+    {
+      key: string;
+      name: string;
+      from_address: string;
+      is_default: boolean;
+      max_attachment_bytes: number;
+      daily_recipient_limit: number | null;
+      used: number;
+    }[]
+  >`
+    SELECT p.key, p.name, p.from_address, p.is_default, p.max_attachment_bytes, p.daily_recipient_limit,
+      (SELECT COALESCE(sum(m.recipient_count), 0)::int FROM outgoing_mail.messages m WHERE m.app_id = ${appId}
+        AND m.profile_id = p.id AND m.status <> 'cancelled' AND m.created_at > now() - INTERVAL '24 hours') AS used
+    FROM outgoing_mail.profiles p WHERE
+      CASE WHEN EXISTS(SELECT 1 FROM outgoing_mail.app_access WHERE app_id = ${appId} AND mode = 'selected')
+      THEN EXISTS(SELECT 1 FROM outgoing_mail.app_profiles WHERE app_id = ${appId} AND profile_id = p.id)
+      ELSE p.is_default END ORDER BY p.is_default DESC, p.name, p.key`;
+  return rows.map((row) => ({
+    key: row.key,
+    name: row.name,
+    from: row.from_address,
+    default: row.is_default,
+    maxAttachmentBytes: row.max_attachment_bytes,
+    quota: { dailyRecipients: row.daily_recipient_limit, usedLast24h: row.used },
+  }));
+};
+export const outgoingMailStore = { list, get, put, setDefault, delete: remove, apps: appsState, setAppAccess, profilesForApp };
+
+/** Platform email send path only. Never use this helper to shape API or CLI responses. */
+export const resolveMailCredentials = async (key?: string | { id: string }) => {
+  const [row] = await sql<(ProfileRow & { smtp_password_encrypted: string | null })[]>`
+    SELECT ${columns(sql)}, smtp_password_encrypted FROM outgoing_mail.profiles WHERE ${
+      key === undefined ? sql`is_default` : typeof key === "string" ? sql`key = ${keyValue(key)}` : sql`id = ${key.id}::uuid`
+    }`;
+  if (!row)
+    throw new OutgoingMailError(
+      "profile_unknown",
+      key ? "Outgoing mail profile does not exist." : "Configure a default outgoing mail profile before sending email.",
+      404,
+    );
+  const password = row.smtp_password_encrypted === null ? null : await decryptValue(row.smtp_password_encrypted);
+  if (password !== null && typeof password !== "string") throw new Error("Outgoing mail SMTP password is invalid.");
+  return {
+    fromAddress: row.from_address,
+    fromName: row.from_name,
+    smtpHost: row.smtp_host,
+    smtpPort: row.smtp_port,
+    smtpSecure: row.smtp_secure,
+    smtpUser: row.smtp_user,
+    smtpPassword: password,
+  };
+};
+
+export type ImapMailProfile = {
+  id: string;
+  key: string;
+  revision: number;
+  fromAddress: string;
+  imap: NonNullable<AdminMailProfile["imap"]>;
+  uidValidity: string | null;
+  lastUid: number | null;
+};
+/** Core's bounce poller only; listing profiles does not decrypt credentials. */
+export const listImapMailProfiles = async (): Promise<ImapMailProfile[]> => {
+  const rows = await sql<(ProfileRow & { uid_validity: string | null; last_uid: string | null })[]>`
+    SELECT ${columns(sql)}, imap_uid_validity::text AS uid_validity, imap_last_uid::text AS last_uid
+    FROM outgoing_mail.profiles WHERE imap_host IS NOT NULL ORDER BY imap_checked_at NULLS FIRST, key`;
+  return rows.map((row) => {
+    const imap = mapProfile(row, 0).imap;
+    if (!imap) throw new Error("Outgoing mail IMAP configuration is invalid.");
+    return {
+      id: row.id,
+      key: row.key,
+      revision: row.revision,
+      fromAddress: row.from_address,
+      imap,
+      uidValidity: row.uid_validity,
+      lastUid: row.last_uid === null ? null : Number(row.last_uid),
+    };
+  });
+};
+export const resolveImapMailCredentials = async (profile: ImapMailProfile) => {
+  const [row] = await sql<{ imap_password_encrypted: string | null }[]>`
+    SELECT imap_password_encrypted FROM outgoing_mail.profiles
+    WHERE id = ${profile.id}::uuid AND revision = ${profile.revision} AND imap_host IS NOT NULL`;
+  if (!row) throw new Error("Outgoing mail IMAP profile changed.");
+  const password = row.imap_password_encrypted === null ? null : await decryptValue(row.imap_password_encrypted);
+  if (password !== null && typeof password !== "string") throw new Error("Outgoing mail IMAP password is invalid.");
+  return password;
+};
+export const saveImapMailCheck = async (
+  profile: ImapMailProfile,
+  result: { uidValidity: string; lastUid: number | null; error?: MailBounceErrorCode } | { error: MailBounceErrorCode },
+) => {
+  await sql`UPDATE outgoing_mail.profiles SET imap_checked_at = now(),
+    imap_error = ${result.error ?? null},
+    imap_uid_validity = ${"uidValidity" in result ? result.uidValidity : profile.uidValidity}::bigint,
+    imap_last_uid = ${"lastUid" in result ? result.lastUid : profile.lastUid}::bigint
+    WHERE id = ${profile.id}::uuid AND revision = ${profile.revision} AND imap_host IS NOT NULL
+      AND imap_uid_validity IS NOT DISTINCT FROM ${profile.uidValidity}::bigint
+      AND imap_last_uid IS NOT DISTINCT FROM ${profile.lastUid}::bigint`;
+};

package/src/services/outgoing-mail/sync.ts

@@ -0,0 +1,39 @@
+import { lazySync } from "../../_internal/process-sync";
+
+export const mailAttachments = lazySync((sync) =>
+  sync.objectStore({
+    id: "cloud-outgoing-mail-attachments",
+    owner: "core",
+    maxObjectBytes: 25 * 1024 * 1024,
+    retention: { maxAgeMs: 48 * 60 * 60_000, maxBytes: 2 * 1024 * 1024 * 1024 },
+  }),
+);
+export const mailSendJob = lazySync((sync) =>
+  sync.job<{ id: string }>({
+    id: "cloud-outgoing-mail-send",
+    owner: "core",
+    delivery: { ackWaitMs: 120_000, maxAttempts: 3, backoffMs: [5000, 30000] },
+  }),
+);
+export const mailSettled = lazySync((sync) =>
+  sync.topic<string>({
+    id: "cloud-outgoing-mail-settled",
+    owner: "core",
+    // 256 minimal wakeups per worker in flight, following Sync's default queue budget.
+    maxPayloadBytes: 1024,
+    retention: { maxAgeMs: 5 * 60_000, maxBytes: 8 * 256 * 1024 },
+  }),
+);
+export const mailDrainJob = lazySync((sync) =>
+  sync.job<{ profileId: string }>({
+    id: "cloud-outgoing-mail-drain",
+    owner: "core",
+    delivery: { ackWaitMs: 120_000, maxAttempts: 3, backoffMs: [5000, 30000] },
+  }),
+);
+export const submitMailDrain = async (profileId: string): Promise<void> => {
+  await mailDrainJob().submit({ key: `profile:${profileId}`, input: { profileId }, coalesce: true });
+};
+export const submitMail = async (id: string): Promise<void> => {
+  await mailSendJob().submit({ key: id, input: { id }, coalesce: true });
+};

package/src/services/outgoing-mail/test-send.ts

@@ -0,0 +1,40 @@
+import { audit } from "../audit";
+import { get } from "../settings";
+import { type MailAuditContext, OutgoingMailError, resolveMailCredentials } from "./store";
+import { buildMailTransport } from "./transport";
+
+export const smtpFailureMessage = (error: unknown, secrets: readonly (string | null)[]): string => {
+  let message = error instanceof Error ? error.message : "SMTP delivery failed.";
+  for (const secret of secrets.filter((s): s is string => !!s)) {
+    for (const representation of [secret, Buffer.from(secret).toString("base64")])
+      message = message.split(representation).join("[REDACTED]");
+  }
+  return message;
+};
+export const outgoingMailTest = {
+  async send(key: string, recipient: string, context: MailAuditContext): Promise<void> {
+    const profile = await resolveMailCredentials(key);
+    const event = { ...context, action: "outgoing_mail.profile.test", target: { type: "outgoing_mail_profile", id: key } };
+    // Fail before the external effect if audit storage is unavailable.
+    await audit.record({ ...event, outcome: "allowed" });
+    const transport = buildMailTransport(profile);
+    try {
+      await transport.sendMail({
+        from: { address: profile.fromAddress, name: profile.fromName ?? (await get<string>("app.name")) },
+        to: recipient,
+        subject: "Cloud test email",
+        text: "This is a test email from Cloud. SMTP delivery is configured correctly if you received it.",
+      });
+    } catch (error) {
+      const message = smtpFailureMessage(error, [
+        profile.smtpPassword,
+        profile.smtpUser,
+        profile.smtpUser ? `\0${profile.smtpUser}\0${profile.smtpPassword ?? ""}` : null,
+      ]);
+      await audit.recordResultAfterSideEffect({ ...event, result: { ok: false, error: { code: "smtp_failed", message, status: 500 } } });
+      throw new OutgoingMailError("smtp_failed", message, 502);
+    } finally {
+      transport.close();
+    }
+  },
+};

package/src/services/outgoing-mail/transport.ts

@@ -0,0 +1,17 @@
+import type { Socket } from "node:net";
+import { createTransport } from "nodemailer";
+import type { resolveMailCredentials } from "./store";
+
+export const buildMailTransport = (profile: Awaited<ReturnType<typeof resolveMailCredentials>>, socket?: Socket) =>
+  createTransport({
+    // Workers own the raw socket so timeout/shutdown can destroy it. Nodemailer
+    // still owns SMTP and upgrades this socket for implicit TLS or STARTTLS.
+    ...(socket ? { socket } : {}),
+    host: profile.smtpHost,
+    port: profile.smtpPort,
+    secure: profile.smtpSecure,
+    ...(profile.smtpUser ? { auth: { user: profile.smtpUser, pass: profile.smtpPassword ?? "" } } : {}),
+    connectionTimeout: 10000,
+    greetingTimeout: 10000,
+    socketTimeout: 60000,
+  });

package/src/services/pdf/markdown.ts

@@ -1,4 +1,4 @@
-import { markdownInfoBlocks } from "@k2b/ui";
+import { markdownInfoBlocks, markdownLinkReference, renderMarkdownLink } from "@k2b/ui";
 import { Marked, Renderer, type Tokens } from "marked";
 import postcss from "postcss";
 import {
@@ -70,6 +70,7 @@ h1, h2, h3, h4, h5, h6 { color: #111827; line-height: 1.2; margin: 1.4em 0 .55em
 h1 { margin-top: 0; font-size: 2em; } h2 { font-size: 1.5em; } h3 { font-size: 1.2em; }
 p, ul, ol, blockquote, pre, table { margin: 0 0 1em; }
 a { color: #2563eb; text-decoration: underline; }
+:root { --link-accent: #2563eb; }
 blockquote { margin-left: 0; padding-left: 1em; border-left: 3px solid #cbd5e1; color: #475569; }
 code { border-radius: 3px; background: #f1f5f9; padding: .08em .28em; font: .9em/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; }
 pre { overflow-wrap: anywhere; white-space: pre-wrap; break-inside: avoid; border-radius: 6px; background: #f8fafc; padding: 1em; }
@@ -91,6 +92,7 @@ h2 { margin: 1.6em 0 .6em; padding-bottom: .2em; border-bottom: 1px solid #b8c7d
 h3 { margin: 1.35em 0 .5em; font-size: 1.15em; }
 p, ul, ol, blockquote, pre, table { margin: 0 0 1em; }
 a { color: #245a86; }
+:root { --link-accent: #245a86; }
 blockquote { margin-left: 0; padding: .7em 1em; border-left: 4px solid #4f799d; background: #f4f7fa; color: #41566c; }
 code { border-radius: 3px; background: #edf2f7; padding: .08em .28em; font: .88em/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; }
 pre { overflow-wrap: anywhere; white-space: pre-wrap; break-inside: avoid; background: #f4f7fa; padding: 1em; }
@@ -111,6 +113,7 @@ h1 { margin-top: 0; font-size: 1.65em; } h2 { font-size: 1.3em; } h3 { font-size
 p, ul, ol, blockquote, pre, table { margin: 0 0 .58em; }
 ul, ol { padding-left: 1.5em; }
 a { color: #1d4ed8; }
+:root { --link-accent: #1d4ed8; }
 blockquote { margin-left: 0; padding-left: .7em; border-left: 2px solid #9ca3af; color: #4b5563; }
 code { background: #f3f4f6; padding: .05em .2em; font: .88em/1.35 ui-monospace, SFMono-Regular, Menlo, monospace; }
 pre { overflow-wrap: anywhere; white-space: pre-wrap; break-inside: avoid; background: #f7f7f8; padding: .65em; }
@@ -142,6 +145,22 @@ const INFO_BLOCK_PRINT_CSS = `
 .k2b-notice-card__body > :last-child { margin-bottom: 0; }
 `;
 
+/**
+ * Links print as Cloud's calm links: a web link is text with a thin underline
+ * in the preset's link colour and a small ↗, a mail link has no arrow, and a
+ * reference to Cloud content is a light grey pill with text in the preset's
+ * colour. Print has no hover, and PDFs load no icon font, so the type icons
+ * and the screen arrow give way to the printed ↗.
+ */
+const LINK_PRINT_CSS = `
+a.k2b-text-link { color: inherit; text-decoration: underline; text-decoration-thickness: .06em; text-underline-offset: .2em; text-decoration-color: var(--link-accent, #2563eb); }
+a.k2b-text-link[data-link="web"]::after { content: "\\2197"; display: inline-block; margin-left: .12em; color: var(--link-accent, #2563eb); font-size: .75em; text-decoration: none; }
+a.k2b-reference { padding: .05em .3em; border-radius: .3em; background: #eeeff2; color: inherit; font-weight: 500; text-decoration: none; box-decoration-break: clone; -webkit-box-decoration-break: clone; print-color-adjust: exact; -webkit-print-color-adjust: exact; }
+.k2b-reference__document, .k2b-reference__size { color: #555c68; font-weight: 400; }
+.k2b-reference__size { margin-left: .35em; font-size: .85em; }
+.k2b-reference__icon, .k2b-text-link__external { display: none; }
+`;
+
 const byteLength = (value: string): number => new TextEncoder().encode(value).byteLength;
 
 const escapeHtml = (value: string): string =>
@@ -172,8 +191,7 @@ const renderMarkdown = (source: string): string => {
     const body = this.parser.parseInline(tokens);
     const safeHref = safeLink(href);
     if (!safeHref) return body;
-    const titleAttribute = title ? ` title="${escapeHtml(title)}"` : "";
-    return `<a href="${escapeHtml(safeHref)}"${titleAttribute}>${body}</a>`;
+    return renderMarkdownLink({ href: safeHref, html: body, title: title ?? undefined, reference: markdownLinkReference(safeHref) });
   };
 
   const parser = new Marked({ breaks: true, gfm: true, renderer }, markdownInfoBlocks());
@@ -236,7 +254,7 @@ export const buildPresetPdfHtml = (input: BuildPresetPdfHtmlInput): string => {
   const suppliedCustomCss = input.customCss?.trim() ?? "";
   const customCss = suppliedCustomCss ? validateCustomCss(input.customCss ?? "") : "";
   const presetCss = templateId ? TEMPLATE_CSS[templateId] : customCss ? "" : TEMPLATE_CSS.document;
-  const baseCss = [presetCss, INFO_BLOCK_PRINT_CSS, input.css ? styleText(input.css) : ""].filter(Boolean).join("\n");
+  const baseCss = [presetCss, INFO_BLOCK_PRINT_CSS, LINK_PRINT_CSS, input.css ? styleText(input.css) : ""].filter(Boolean).join("\n");
   const stylesheet = `${baseCss}${baseCss && customCss ? `\n/* Custom CSS overrides */\n` : ""}${customCss}`;
   return `<!doctype html>
 <html lang="en">

package/src/services/postgres.ts

@@ -1,3 +1,18 @@
+import type { TransactionSQL } from "bun";
+
+/**
+ * Call inside the migration transaction directly after its advisory lock, as
+ * its first statement reading pg_namespace (including through views like pg_tables).
+ * The fresh relation lock applies catalog invalidations the advisory lock does not,
+ * so this check and all later DDL see schemas other migrators committed while it waited.
+ * The schema name must be a code constant and a plain lowercase Postgres identifier.
+ */
+export const ensureSchema = async (db: TransactionSQL, name: string): Promise<void> => {
+  if (!/^[a-z_][a-z0-9_]{0,62}$/.test(name)) throw new Error("Schema name must be a plain lowercase Postgres identifier");
+  const [schema] = await db<{ exists: boolean }[]>`SELECT EXISTS(SELECT FROM pg_namespace WHERE nspname = ${name}) AS exists`;
+  if (!schema?.exists) await db.unsafe(`CREATE SCHEMA ${name}`).simple();
+};
+
 /** Convert a JS string array to a Postgres TEXT[] literal (Bun sql can't serialize empty arrays). */
 export const toPgTextArray = (values: string[] | null | undefined): string => {
   if (!Array.isArray(values) || values.length === 0) return "{}";

package/src/services/settings/core-settings.ts

@@ -29,6 +29,24 @@ const IPA_ACCOUNT_TRANSITION_OPTIONS = [
 ] as const;
 
 export const CORE_SETTINGS = {
+  "outgoing_mail.content_retention_days": {
+    kind: "number",
+    label: "Mail content retention (days)",
+    description: "Purge message bodies and custom headers after this many days.",
+    default: 90,
+    min: 1,
+    max: 36500,
+    integer: true,
+  },
+  "outgoing_mail.record_retention_days": {
+    kind: "number",
+    label: "Mail record retention (days)",
+    description: "Delete send log records after this many days.",
+    default: 365,
+    min: 1,
+    max: 36500,
+    integer: true,
+  },
   "observability.web_vitals.enabled": {
     kind: "boolean",
     label: "Record browser page performance",
@@ -292,7 +310,7 @@ export const CORE_SETTINGS = {
     default: 30,
     min: 0,
     description:
-      "Maximum running time per AI turn. Zero or an empty field disables this limit. Existing turns keep their original budget; request and tool timeouts still apply.",
+      "Maximum running time per AI turn. In the last tenth, the Assistant stops using tools and answers. Zero or an empty field disables this limit. Existing turns keep their original budget; request and tool timeouts still apply.",
   },
   "ai.max_tool_result_chars": {
     kind: "number",
@@ -672,43 +690,6 @@ export const CORE_SETTINGS = {
     description: "Account request denial email template (HTML). Subject: Account Request Update",
     templateVars: ["FIRST_NAME", "REASON", "CONTACT_EMAIL", "APP_NAME"] as readonly string[],
   },
-  "mail.noreply.smtp_host": {
-    kind: "string",
-    label: "SMTP Host",
-    default: "",
-    description: "SMTP server hostname",
-    placeholder: "e.g. smtp.example.org",
-  },
-  "mail.noreply.smtp_port": {
-    kind: "number",
-    label: "SMTP Port",
-    default: 587,
-    min: 1,
-    max: 65535,
-    description: "SMTP server port (587 for STARTTLS, 465 for SSL)",
-  },
-  "mail.noreply.from": {
-    kind: "email",
-    label: "From Address",
-    default: "",
-    description: "From email address",
-    placeholder: "e.g. noreply@example.org",
-  },
-  "mail.noreply.user": {
-    kind: "string",
-    label: "SMTP User",
-    default: "",
-    description: "SMTP username",
-    placeholder: "e.g. noreply@example.org",
-  },
-  "mail.noreply.password": {
-    kind: "secret",
-    label: "SMTP Password",
-    default: "",
-    description: "SMTP password",
-    placeholder: "SMTP password",
-  },
-
   // ── Security ────────────────────────────────────────────────────────────
   "security.rate_limit_per_second": {
     kind: "number",