@k2b/cloud 0.26.0 → 0.27.0

package/src/cli/admin/index.ts

@@ -25,6 +25,7 @@ import { logCommands } from "./logs";
 import { metricsCommands } from "./metrics";
 import { natsCommands } from "./nats";
 import { notificationCommands } from "./notifications";
+import { outgoingMailCommands } from "./outgoing-mail";
 import { syncCommands } from "./sync";
 import { telemetryCommands } from "./telemetry";
 import { webhookCommands } from "./webhooks";
@@ -38,6 +39,7 @@ export default defineCliCommands({
     ai: "Manage AI models, quotas, Skills, and usage.",
     "ai models": "Manage AI model configuration.",
     "ai models pricing": "Manage model reference prices.",
+    "ai models settings": "Manage model thinking levels, extra parameters, and extra headers.",
     "ai quotas background": "Inspect and release the background emergency stop.",
     "ai skills": "Inspect Assistant Skills and trusted templates.",
     "ai usage": "Inspect AI runs and usage facets.",
@@ -55,6 +57,9 @@ export default defineCliCommands({
     "nats consumers": "Inspect NATS consumers.",
     "nats streams": "Find NATS streams and buckets.",
     "notification-batches": "Manage account notification batches.",
+    "outgoing-mail": "Manage outgoing mail sender profiles and application access.",
+    "outgoing-mail profiles": "Manage outgoing mail sender profiles.",
+    "outgoing-mail apps": "Manage application outgoing mail access.",
     notifications: "Inspect and resend email notifications.",
     postgres: "Inspect Postgres diagnostics.",
     redis: "Inspect Valkey diagnostics.",
@@ -96,6 +101,7 @@ export default defineCliCommands({
     ...workflowCommands,
     ...dataCommands,
     ...notificationCommands,
+    ...outgoingMailCommands,
     ...webhookCommands,
     ...metricsCommands,
     ...natsCommands,

package/src/cli/admin/outgoing-mail.ts

@@ -0,0 +1,118 @@
+import { type AdminMailApp, type AdminMailProfile, MailProfileInputSchema } from "../../contracts/outgoing-mail";
+import { arg, type CloudCliContext, command, confirmFlag, flag, readCliInput } from "../index";
+import { apiGet, apiJson, printJsonOrTable } from "./shared";
+
+const root = "/api/admin/core/outgoing-mail";
+const profilePath = (key: string) => `${root}/profiles/${encodeURIComponent(key)}`;
+const keyArgs = { key: arg.required({ valueLabel: "key" }) };
+const print = (ctx: CloudCliContext, value: unknown) => {
+  if (ctx.options.output === "json") ctx.json(value);
+  else ctx.print(JSON.stringify(value, null, 2));
+};
+const confirmed = (yes: boolean) => {
+  if (!yes) throw new Error("Outgoing mail policy changes require --yes.");
+};
+export const outgoingMailCommands = [
+  command("outgoing-mail profiles list", {
+    summary: "List outgoing mail sender profiles",
+    async run({ ctx }) {
+      const result = await apiGet<{ items: AdminMailProfile[] }>(ctx, `${root}/profiles`);
+      printJsonOrTable(
+        ctx,
+        result,
+        result.items.map((p) => ({ key: p.key, name: p.name, from: p.fromAddress, default: p.isDefault, revision: p.revision })),
+        [{ key: "key" }, { key: "name" }, { key: "from" }, { key: "default" }, { key: "revision" }],
+      );
+    },
+  }),
+  command("outgoing-mail profiles get", {
+    summary: "Read one outgoing mail sender profile",
+    args: keyArgs,
+    async run({ ctx, args }) {
+      print(ctx, await apiGet(ctx, profilePath(args.key)));
+    },
+  }),
+  command("outgoing-mail profiles put", {
+    summary: "Create or replace a sender profile with its current revision",
+    args: keyArgs,
+    flags: { config: flag.input({ required: true, description: "Profile JSON; SMTP passwords only via --config-file or --stdin" }) },
+    async run({ ctx, args, flags }) {
+      const input = await readCliInput(flags.config, { label: "outgoing mail profile", required: true });
+      let raw: unknown;
+      try {
+        raw = JSON.parse(input ?? "");
+      } catch {
+        throw new Error("Invalid outgoing mail profile JSON.");
+      }
+      if (flags.config.source === "value" && raw && typeof raw === "object" && "smtpPassword" in raw)
+        throw new Error("Pass smtpPassword only through --config-file or --stdin.");
+      print(ctx, await apiJson(ctx, "PUT", profilePath(args.key), MailProfileInputSchema.parse(raw)));
+    },
+  }),
+  command("outgoing-mail profiles set-default", {
+    summary: "Choose the default outgoing mail sender",
+    args: keyArgs,
+    flags: { yes: confirmFlag("Confirm changing the default sender") },
+    async run({ ctx, args, flags }) {
+      confirmed(flags.yes);
+      print(ctx, await apiJson(ctx, "POST", `${profilePath(args.key)}/default`));
+    },
+  }),
+  command("outgoing-mail profiles delete", {
+    summary: "Delete a sender profile that is not the default",
+    args: keyArgs,
+    flags: { yes: confirmFlag("Confirm deleting the sender profile") },
+    async run({ ctx, args, flags }) {
+      confirmed(flags.yes);
+      const response = await ctx.fetch(profilePath(args.key), { method: "DELETE" });
+      if (!response.ok) await ctx.readJson(response);
+      print(ctx, { deleted: args.key });
+    },
+  }),
+  command("outgoing-mail profiles test", {
+    summary: "Send a test email through a sender profile",
+    args: keyArgs,
+    flags: { to: flag.string({ required: true, description: "Recipient email address" }) },
+    async run({ ctx, args, flags }) {
+      print(ctx, await apiJson(ctx, "POST", `${profilePath(args.key)}/test`, { recipient: flags.to }));
+    },
+  }),
+  command("outgoing-mail apps list", {
+    summary: "List application outgoing mail permissions and profile access",
+    async run({ ctx }) {
+      const result = await apiGet<{ defaultProfile: string | null; items: AdminMailApp[] }>(ctx, `${root}/apps`);
+      printJsonOrTable(
+        ctx,
+        result,
+        result.items.map((app) => ({ ...app, profiles: app.profiles.join(",") })),
+        [{ key: "appId" }, { key: "name" }, { key: "declared" }, { key: "mode" }, { key: "profiles" }],
+      );
+    },
+  }),
+  command("outgoing-mail apps set", {
+    summary: "Set default, selected, or blocked outgoing mail access",
+    args: { app: arg.required({ valueLabel: "app" }) },
+    flags: {
+      default: flag.boolean({ description: "Use the default sender" }),
+      profiles: flag.string({ description: "Comma-separated profile keys" }),
+      none: flag.boolean({ description: "Block sending with an empty selected list" }),
+      yes: confirmFlag("Confirm application outgoing mail access change"),
+    },
+    async run({ ctx, args, flags }) {
+      confirmed(flags.yes);
+      if ([flags.default, flags.none, flags.profiles !== undefined].filter(Boolean).length !== 1)
+        throw new Error("Choose exactly one of --default, --profiles or --none.");
+      const profiles = flags.profiles?.split(",").map((key) => key.trim());
+      if (profiles?.some((key) => !key)) throw new Error("--profiles requires non-empty profile keys; use --none to block sending.");
+      print(
+        ctx,
+        await apiJson(
+          ctx,
+          "PUT",
+          `${root}/apps/${encodeURIComponent(args.app)}`,
+          flags.default ? { mode: "default" } : { mode: "selected", profiles: profiles ?? [] },
+        ),
+      );
+    },
+  }),
+];

package/src/contracts/app.ts

@@ -1,4 +1,5 @@
 import type { Sync } from "@k2b/sync";
+import type { PlatformPermission } from "./outgoing-mail";
 import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation } from "./widgets";
@@ -97,6 +98,7 @@ export type AppPwaPart = {
 };
 
 export type AppMeta = {
+  platformPermissions?: readonly PlatformPermission[];
   id: string;
   name: string;
   icon: string;

package/src/contracts/index.ts

@@ -8,6 +8,7 @@ export * from "./commands";
 export * from "./contact-directory";
 export * from "./file-provider";
 export * from "./notification-types";
+export * from "./outgoing-mail";
 export * from "./posix";
 export * from "./profile";
 export * from "./pwa";

package/src/contracts/outgoing-mail.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+
+export const PlatformPermissionSchema = z.enum(["mail:send"]);
+export type PlatformPermission = z.infer<typeof PlatformPermissionSchema>;
+export const MailProfileKeySchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
+const headerText = z
+  .string()
+  .trim()
+  .min(1)
+  .max(120)
+  .refine((value) => !/[\r\n\0]/.test(value), "Header must not contain control characters");
+export const MailProfileInputSchema = z
+  .object({
+    name: headerText,
+    fromAddress: z.email().max(320),
+    fromName: headerText.nullable(),
+    smtpHost: z
+      .string()
+      .trim()
+      .min(1)
+      .max(253)
+      .refine((value) => !/[\s/@\0]/.test(value), "Use an SMTP hostname"),
+    smtpPort: z.int().min(1).max(65535),
+    smtpSecure: z.boolean(),
+    smtpUser: z.string().max(320).nullable(),
+    smtpPassword: z.string().max(16384).nullable().optional(),
+    pacePerMinute: z.int().min(1).max(6000),
+    dailyRecipientLimit: z.int().min(1).max(2147483647).nullable(),
+    maxAttachmentBytes: z.int().min(1).max(26214400),
+    revision: z.int().min(1).max(2147483647).optional(),
+  })
+  .strict();
+export type MailProfileInput = z.infer<typeof MailProfileInputSchema>;
+export const MailAppAccessSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("default") }).strict(),
+  z.object({ mode: z.literal("selected"), profiles: z.array(MailProfileKeySchema) }).strict(),
+]);
+export type MailAppAccess = z.infer<typeof MailAppAccessSchema>;
+export const MailProfileSchema = z.object({
+  key: MailProfileKeySchema,
+  name: z.string(),
+  from: z.email(),
+  default: z.boolean(),
+  maxAttachmentBytes: z.int(),
+  quota: z.object({ dailyRecipients: z.int().nullable(), usedLast24h: z.int() }),
+});
+export type MailProfile = z.infer<typeof MailProfileSchema>;
+export const MailErrorCodeSchema = z.enum([
+  "mail_unavailable",
+  "mail_not_declared",
+  "profile_unknown",
+  "profile_exists",
+  "profile_is_default",
+  "revision_conflict",
+  "invalid_profile",
+  "smtp_failed",
+]);
+export type MailErrorCode = z.infer<typeof MailErrorCodeSchema>;
+export const AdminMailProfileSchema = MailProfileInputSchema.omit({ smtpPassword: true, revision: true }).extend({
+  key: MailProfileKeySchema,
+  hasPassword: z.boolean(),
+  isDefault: z.boolean(),
+  revision: z.int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  updatedBy: z.string().nullable(),
+  appCount: z.int(),
+});
+export type AdminMailProfile = z.infer<typeof AdminMailProfileSchema>;
+export type AdminMailApp = {
+  appId: string;
+  name: string;
+  registered: boolean;
+  declared: boolean;
+  mode: "default" | "selected";
+  profiles: string[];
+};

package/src/contracts/registry.ts

@@ -1,5 +1,6 @@
 import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog, AppSearchLink } from "./app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
+import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation } from "./widgets";
 
@@ -65,6 +66,7 @@ export type AppRuntimeMetadata = {
 };
 
 export type AppRegistryEntry = {
+  platformPermissions?: readonly PlatformPermission[];
   id: string;
   name: string;
   icon: string;

package/src/services/index.ts

@@ -204,3 +204,6 @@ export { legalConsent } from "./legal-consent";
 export { railShortcuts } from "./rail-shortcuts";
 
 export type { WebVitalsOverview, WebVitalsQuery, WebVitalMetric, WebVitalName } from "./logging/web-vitals";
+
+export { mail } from "./outgoing-mail";
+export type { MailProfile } from "../contracts/outgoing-mail";

package/src/services/notifications/email.ts

@@ -1,24 +1,10 @@
-import { createTransport, type Transporter } from "nodemailer";
 import sanitizeHtml from "sanitize-html";
 import { sanitizeEmailHtml } from "../../shared";
+import { resolveMailCredentials } from "../outgoing-mail/store";
+import { buildMailTransport } from "../outgoing-mail/transport";
 import * as settings from "../settings";
 import { coreSettings } from "../settings/api";
 
-/** Lazily-created transporter — uses current settings on each send. */
-const getTransporter = async (): Promise<Transporter> => {
-  const host = await settings.get<string>("mail.noreply.smtp_host");
-  const port = await settings.get<number>("mail.noreply.smtp_port");
-  const user = await settings.get<string>("mail.noreply.user");
-  const pass = await settings.get<string>("mail.noreply.password");
-
-  return createTransport({
-    host,
-    port,
-    secure: port === 465,
-    auth: { user, pass },
-  });
-};
-
 /** Sanitize plain text content (no HTML allowed). */
 const sanitizeContent = (content: string): string => sanitizeHtml(content, { allowedTags: [], allowedAttributes: {} });
 
@@ -31,7 +17,7 @@ export const sendEmail = async (
   const rawAppUrl = await settings.get<string>("app.url");
   const appUrl = rawAppUrl.startsWith("http") ? rawAppUrl : `https://${rawAppUrl}`;
   const appName = await settings.get<string>("app.name");
-  const emailFrom = await settings.get<string>("mail.noreply.from");
+  const profile = await resolveMailCredentials();
 
   let body = "";
   if (opts.rawHtml) {
@@ -42,16 +28,20 @@ export const sendEmail = async (
   const text = opts.content ? sanitizeContent(opts.content) : undefined;
 
   const html = await buildHtml(appUrl, appName, body);
-  const transporter = await getTransporter();
+  const transporter = buildMailTransport(profile);
 
-  await transporter.sendMail({
-    from: `"${appName}" <${emailFrom}>`,
-    to,
-    subject,
-    ...(opts.messageId ? { messageId: opts.messageId } : {}),
-    html,
-    ...(text ? { text } : {}),
-  });
+  try {
+    await transporter.sendMail({
+      from: { address: profile.fromAddress, name: profile.fromName ?? appName },
+      to,
+      subject,
+      ...(opts.messageId ? { messageId: opts.messageId } : {}),
+      html,
+      ...(text ? { text } : {}),
+    });
+  } finally {
+    transporter.close();
+  }
 };
 
 /**

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

@@ -0,0 +1,19 @@
+import { fail, ok, type Result } from "@k2b/stdlib";
+import { getProcessApplicationId, getProcessPlatformPermissions } from "../../_internal/process-identity";
+import type { MailProfile } from "../../contracts/outgoing-mail";
+import { outgoingMailStore } from "./store";
+
+export const mail = {
+  async profiles(): Promise<Result<MailProfile[]>> {
+    const appId = getProcessApplicationId();
+    if (!appId)
+      return fail({ code: "mail_unavailable", message: "Start the application before reading outgoing mail profiles.", status: 500 });
+    if (!getProcessPlatformPermissions().includes("mail:send"))
+      return fail({ code: "mail_not_declared", message: 'Declare platformPermissions: ["mail:send"].', status: 403 });
+    try {
+      return ok(await outgoingMailStore.profilesForApp(appId));
+    } catch {
+      return fail({ code: "mail_unavailable", message: "Outgoing mail profiles are unavailable.", status: 500 });
+    }
+  },
+};

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

@@ -0,0 +1,286 @@
+import { type SQL, sql } from "bun";
+import { listApps } from "../../_internal/registry";
+import {
+  type AdminMailApp,
+  type AdminMailProfile,
+  type MailAppAccess,
+  MailAppAccessSchema,
+  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;
+  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,
+  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,
+  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 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 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;
+    }[]
+  >`
+    SELECT p.key, p.name, p.from_address, p.is_default, p.max_attachment_bytes, p.daily_recipient_limit
+    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: 0 },
+  }));
+};
+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) => {
+  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` : sql`key = ${keyValue(key)}`}`;
+  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,
+  };
+};