feat: add durable SMTP transactional mail subsystem

.env.example

@@ -5,11 +5,22 @@ APP_VERSION=dev
 APP_URL=http://localhost:3000
 AUTH_SECRET=replace-with-at-least-32-random-characters
 SIGNUPS_ENABLED=true
-# HTTPS webhook used for verification-email delivery in staging/production.
-# Receives JSON: { type, to, from, subject, text, verificationUrl }.
-AUTH_EMAIL_WEBHOOK_URL=
-AUTH_EMAIL_WEBHOOK_BEARER_TOKEN=
-AUTH_EMAIL_FROM=Aiwa Creators <no-reply@example.com>
+# Transactional email. Production uses implicit TLS SMTP (port 465).
+# Web and worker services must load the same SMTP and sender settings.
+# Never expose SMTP credentials through NEXT_PUBLIC_* variables.
+MAIL_ENABLED=true
+SMTP_HOST=
+SMTP_PORT=465
+SMTP_USER=
+SMTP_PASSWORD=
+SMTP_EHLO_NAME=creator.aiwamediagroup.com
+SMTP_POOL_MAX_CONNECTIONS=3
+SMTP_POOL_MAX_MESSAGES=100
+SMTP_CONNECTION_TIMEOUT_MS=10000
+SMTP_GREETING_TIMEOUT_MS=10000
+SMTP_SOCKET_TIMEOUT_MS=30000
+MAIL_SECURITY_FROM_ADDRESS=security@aiwamediagroup.com
+MAIL_ROUTINE_FROM_ADDRESS=creator-tool@aiwamediagroup.com
 
 # MariaDB. Credentials below are for local Compose only.
 MARIADB_DATABASE=creator_platform

README.md

@@ -436,3 +436,11 @@ Studio supports queued BytePlus image generation with wallet reservation,
 persistent PNG assets and authenticated downloads. See
 [the image-generation runbook](docs/image-generation.md) for deployment,
 recovery behavior and the live acceptance check.
+
+
+## Transactional email
+
+Authentication, billing, membership, generation and report notifications use a
+durable MariaDB outbox with BullMQ delivery and pooled TLS SMTP. See
+[the transactional-email operations runbook](docs/operations/transactional-email.md)
+for production configuration, sender identities, retry behavior and diagnostics.

apps/web/package.json

@@ -18,6 +18,7 @@
     "@aiwa/credits": "workspace:*",
     "@aiwa/db": "workspace:*",
     "@aiwa/generation": "workspace:*",
+    "@aiwa/mail": "workspace:*",
     "@aiwa/organizations": "workspace:*",
     "@aiwa/payments": "workspace:*",
     "@aiwa/providers": "workspace:*",

apps/web/src/app/admin/email/page.tsx

@@ -0,0 +1,195 @@
+import { db } from "@aiwa/db";
+import { MailRetryButton } from "@/components/admin/mail-retry-button";
+import { MailVerifyButton } from "@/components/admin/mail-verify-button";
+import { StatusBadge } from "@/components/admin/primitives";
+import { Eyebrow } from "@/components/ui/creative";
+import { requirePlatformPermission } from "@/lib/request-auth";
+
+function maskEmail(email: string): string {
+  const [local = "", domain] = email.split("@");
+  if (!domain) return "••••";
+  const visible = local.length <= 2 ? local.slice(0, 1) : local.slice(0, 2);
+  return `${visible}••••@${domain}`;
+}
+
+function statusTone(
+  status: string,
+): "success" | "warning" | "danger" | "neutral" {
+  if (status === "SENT") return "success";
+  if (status === "FAILED") return "danger";
+  if (status === "RETRY" || status === "SENDING") return "warning";
+  return "neutral";
+}
+
+export default async function AdminEmailPage() {
+  await requirePlatformPermission("audit:read");
+
+  const [pending, retrying, failed, sent, recent] = await Promise.all([
+    db.mailMessage.count({
+      where: { status: { in: ["PENDING", "QUEUED", "SENDING"] } },
+    }),
+    db.mailMessage.count({ where: { status: "RETRY" } }),
+    db.mailMessage.count({ where: { status: "FAILED" } }),
+    db.mailMessage.count({ where: { status: "SENT" } }),
+    db.mailMessage.findMany({
+      orderBy: { createdAt: "desc" },
+      take: 50,
+      select: {
+        id: true,
+        kind: true,
+        priority: true,
+        status: true,
+        template: true,
+        recipient: true,
+        attemptCount: true,
+        lastErrorCode: true,
+        lastErrorMessage: true,
+        createdAt: true,
+        sentAt: true,
+        nextAttemptAt: true,
+      },
+    }),
+  ]);
+
+  const cards = [
+    ["Queued", pending],
+    ["Retrying", retrying],
+    ["Failed", failed],
+    ["Sent", sent],
+  ] as const;
+
+  return (
+    <div className="px-4 py-7 sm:px-7 lg:px-9 lg:py-9">
+      <Eyebrow>Operations</Eyebrow>
+      <div className="mt-3">
+        <h1 className="font-display text-4xl font-semibold tracking-tight">
+          Email delivery
+        </h1>
+        <p className="mt-1 max-w-3xl text-sm text-muted-foreground">
+          Durable transactional-mail outbox and delivery diagnostics. Security
+          content is never displayed here.
+        </p>
+        <div className="mt-4">
+          <MailVerifyButton />
+        </div>
+      </div>
+
+      <div className="mt-6 grid gap-3 sm:grid-cols-2 xl:grid-cols-4">
+        {cards.map(([label, value]) => (
+          <div
+            key={label}
+            className="rounded-2xl border border-border bg-card p-5 shadow-sm"
+          >
+            <p className="text-[10px] font-bold uppercase tracking-[0.12em] text-muted-foreground">
+              {label}
+            </p>
+            <p className="mt-2 font-display text-3xl font-semibold tabular-nums">
+              {value.toLocaleString("en-US")}
+            </p>
+          </div>
+        ))}
+      </div>
+
+      <div className="mt-6 overflow-hidden rounded-3xl border border-border bg-card shadow-sm">
+        <div className="border-b border-border px-5 py-4 sm:px-6">
+          <h2 className="font-display text-xl font-semibold">
+            Recent deliveries
+          </h2>
+          <p className="mt-1 text-xs text-muted-foreground">
+            Latest 50 messages. Recipients are masked and mail bodies are
+            excluded.
+          </p>
+        </div>
+        <div className="overflow-x-auto">
+          <table className="w-full min-w-[980px] text-left">
+            <thead>
+              <tr className="border-b border-border text-[10px] font-bold uppercase tracking-[0.12em] text-muted-foreground">
+                <th className="px-5 py-3">Created</th>
+                <th className="px-3 py-3">Recipient</th>
+                <th className="px-3 py-3">Channel</th>
+                <th className="px-3 py-3">Template</th>
+                <th className="px-3 py-3">Status</th>
+                <th className="px-3 py-3 text-center">Attempts</th>
+                <th className="px-3 py-3">Next / sent</th>
+                <th className="px-3 py-3">Last error</th>
+                <th className="px-5 py-3 text-right">Action</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-border">
+              {recent.map((mail) => (
+                <tr key={mail.id} className="align-top text-xs">
+                  <td className="px-5 py-4 font-mono text-[10px] text-muted-foreground">
+                    {mail.createdAt.toLocaleString("en-OM")}
+                  </td>
+                  <td className="px-3 py-4 font-mono text-[10px]">
+                    {maskEmail(mail.recipient)}
+                  </td>
+                  <td className="px-3 py-4">
+                    <span className="rounded-lg border border-border bg-muted/60 px-2 py-1 font-mono text-[10px]">
+                      {mail.kind}
+                    </span>
+                    <span className="ml-1 text-[10px] text-muted-foreground">
+                      {mail.priority}
+                    </span>
+                  </td>
+                  <td className="px-3 py-4 font-mono text-[10px] text-muted-foreground">
+                    {mail.template}
+                  </td>
+                  <td className="px-3 py-4">
+                    <StatusBadge tone={statusTone(mail.status)}>
+                      {mail.status}
+                    </StatusBadge>
+                  </td>
+                  <td className="px-3 py-4 text-center font-mono tabular-nums">
+                    {mail.attemptCount}
+                  </td>
+                  <td className="px-3 py-4 font-mono text-[10px] text-muted-foreground">
+                    {(mail.sentAt ?? mail.nextAttemptAt)?.toLocaleString(
+                      "en-OM",
+                    ) ?? "—"}
+                  </td>
+                  <td className="max-w-72 px-3 py-4 text-[10px] text-muted-foreground">
+                    {mail.lastErrorCode ? (
+                      <>
+                        <span className="font-mono font-semibold text-foreground">
+                          {mail.lastErrorCode}
+                        </span>
+                        {mail.lastErrorMessage ? (
+                          <span className="mt-1 block line-clamp-2">
+                            {mail.lastErrorMessage}
+                          </span>
+                        ) : null}
+                      </>
+                    ) : (
+                      "—"
+                    )}
+                  </td>
+                  <td className="px-5 py-4 text-right">
+                    {mail.kind === "ROUTINE" &&
+                    ["FAILED", "RETRY"].includes(mail.status) ? (
+                      <MailRetryButton mailId={mail.id} />
+                    ) : (
+                      <span className="text-[10px] text-muted-foreground">
+                        —
+                      </span>
+                    )}
+                  </td>
+                </tr>
+              ))}
+              {recent.length === 0 ? (
+                <tr>
+                  <td
+                    colSpan={9}
+                    className="px-5 py-12 text-center text-sm text-muted-foreground"
+                  >
+                    No transactional mail has been queued yet.
+                  </td>
+                </tr>
+              ) : null}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  );
+}

apps/web/src/app/admin/layout.tsx

@@ -55,6 +55,12 @@ const navigation: readonly (AdminNavigationItem & {
     icon: "assets",
     permission: "audit:read",
   },
+  {
+    href: "/admin/email",
+    label: "Email delivery",
+    icon: "activity",
+    permission: "audit:read",
+  },
 ];
 
 export default async function AdminLayout({

apps/web/src/app/api/account/notification-preferences/route.ts

@@ -0,0 +1,83 @@
+import { db } from "@aiwa/db";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { getRequestSession } from "@/lib/request-auth";
+import { hasTrustedMutationOrigin } from "@/lib/request-security";
+
+const schema = z.object({
+  generationCompleted: z.boolean(),
+  generationFailed: z.boolean(),
+  reports: z.boolean(),
+});
+
+export async function GET(request: Request) {
+  const session = await getRequestSession(request.headers);
+  if (!session) {
+    return NextResponse.json(
+      { error: "Authentication required." },
+      { status: 401 },
+    );
+  }
+
+  const preference = await db.notificationPreference.findUnique({
+    where: { userId: session.user.id },
+    select: {
+      generationCompleted: true,
+      generationFailed: true,
+      reports: true,
+    },
+  });
+
+  return NextResponse.json(
+    preference ?? {
+      generationCompleted: true,
+      generationFailed: true,
+      reports: true,
+    },
+  );
+}
+
+export async function PATCH(request: Request) {
+  if (!hasTrustedMutationOrigin(request)) {
+    return NextResponse.json({ error: "Origin not allowed." }, { status: 403 });
+  }
+
+  const session = await getRequestSession(request.headers);
+  if (!session) {
+    return NextResponse.json(
+      { error: "Authentication required." },
+      { status: 401 },
+    );
+  }
+
+  const parsed = schema.safeParse(await request.json().catch(() => null));
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid notification preferences." },
+      { status: 400 },
+    );
+  }
+
+  const preference = await db.notificationPreference.upsert({
+    where: { userId: session.user.id },
+    create: { userId: session.user.id, ...parsed.data },
+    update: parsed.data,
+    select: {
+      generationCompleted: true,
+      generationFailed: true,
+      reports: true,
+    },
+  });
+
+  await db.auditEvent.create({
+    data: {
+      actorUserId: session.user.id,
+      action: "user.notification_preferences_updated",
+      targetType: "User",
+      targetId: session.user.id,
+      metadata: preference,
+    },
+  });
+
+  return NextResponse.json(preference);
+}