@cosmicdrift/kumiko-bundled-features 0.88.0 → 0.90.0

package/src/user-data-rights/handlers/request-deletion.write.ts

@@ -1,7 +1,13 @@
+import { createTransportForTenant } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { USER_STATUS } from "../../user";
+import {
+  type GdprMailDefaults,
+  isMailTransportAvailable,
+  makeDefaultDeletionRequestedEmail,
+} from "../lib/default-mailers";
 import { startDeletionGracePeriod } from "./deletion-grace-period";
 
 // Atom 5b — Email-Notification beim deletion-requested-flip. Pattern:
@@ -14,12 +20,18 @@ import { startDeletionGracePeriod } from "./deletion-grace-period";
 export type SendDeletionRequestedEmailFn = (args: {
   readonly userId: string;
   readonly userEmail: string;
+  /** Stored user.locale (free-form) — lets the default mailer render in the
+   *  recipient's language. */
+  readonly userLocale: string | null;
   readonly tenantId: string;
   readonly gracePeriodEnd: string;
 }) => Promise<void>;
 
 export type RequestDeletionOptions = {
   readonly sendDeletionRequestedEmail?: SendDeletionRequestedEmailFn;
+  /** Branding fuer die Default-Mail wenn kein sendDeletionRequestedEmail
+   *  gesetzt ist + mail-foundation gemountet ist. */
+  readonly mailDefaults?: GdprMailDefaults;
 };
 
 // POST /api/user/request-deletion (S2.U5a) — DSGVO Art. 17 Forget-Antrag.
@@ -35,15 +47,29 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
     handler: async (event, ctx) => {
       const res = await startDeletionGracePeriod(ctx, event.user.id, event.user.tenantId);
       if (!res.ok) return writeFailure(res.error);
-      const { gracePeriodEnd, userEmail } = res;
+      const { gracePeriodEnd, userEmail, userLocale } = res;
+
+      // App-Callback hat Vorrang; sonst greift die mail-foundation-Default-Mail
+      // (Request-Lane → ctx.config vorhanden, createTransportForTenant direkt).
+      // Ohne gemounteten mail-transport bleibt send undefined → keine Mail.
+      const send =
+        opts.sendDeletionRequestedEmail ??
+        (isMailTransportAvailable(ctx.registry)
+          ? makeDefaultDeletionRequestedEmail(
+              (tenantId) =>
+                createTransportForTenant(ctx, tenantId, "user-data-rights:request-deletion"),
+              opts.mailDefaults,
+            )
+          : undefined);
 
       // Best-effort Email-Notification. Send-Failure darf das Write nicht
       // killen — siehe Type-Doc oben.
-      if (opts.sendDeletionRequestedEmail && userEmail.length > 0) {
+      if (send && userEmail.length > 0) {
         try {
-          await opts.sendDeletionRequestedEmail({
+          await send({
             userId: event.user.id,
             userEmail,
+            userLocale,
             tenantId: event.user.tenantId,
             gracePeriodEnd: gracePeriodEnd.toString(),
           });

package/src/user-data-rights/lib/default-mailers.ts

@@ -0,0 +1,116 @@
+// Default send*Email-Callbacks fuer die GDPR-Notifications, backed by einem
+// mail-transport (mail-foundation). Damit muss eine App keinen Callback-Code
+// schreiben: sie mountet mail-foundation + einen mail-transport-* und setzt
+// fuer Export-Mails appExportDownloadUrl — fertig. Uebergibt sie eigene
+// send*Email-Opts, greifen diese Defaults nicht (Opt-Override im feature.ts).
+//
+// Jeder Callback rendert das Template (email-templates.ts) und versendet ueber
+// den per-Tenant aufgeloesten EmailTransport. `resolveTransport` kommt im Job-
+// Lane aus makeTenantMailTransportResolver, im Request-Lane direkt aus
+// createTransportForTenant(ctx, ...).
+
+import type { EmailTransport } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type GdprMailLocale,
+  normalizeGdprMailLocale,
+  renderDeletionExecutedEmail,
+  renderDeletionRequestedEmail,
+  renderExportFailedEmail,
+  renderExportReadyEmail,
+} from "../email-templates";
+import type { SendDeletionRequestedEmailFn } from "../handlers/request-deletion.write";
+import type { SendExportFailedEmailFn, SendExportReadyEmailFn } from "../run-export-jobs";
+import type { SendDeletionExecutedEmailFn } from "../run-forget-cleanup";
+
+export type GdprMailDefaults = {
+  readonly locale?: GdprMailLocale;
+  readonly appName?: string;
+};
+
+// mail-foundation ist eine Soft-Dep von user-data-rights. Die Default-Mailer
+// greifen nur wenn mindestens ein mail-transport-* registriert ist — sonst
+// kann ohnehin nichts versendet werden und die App bleibt beim bisherigen
+// "kein Callback → keine Email"-Verhalten.
+export function isMailTransportAvailable(registry: Registry): boolean {
+  return registry.getExtensionUsages("mailTransport").length > 0;
+}
+
+type TransportResolver = (tenantId: string) => Promise<EmailTransport>;
+
+// Per-recipient locale wins (user.locale); mailDefaults.locale is the fallback
+// for unknown/unsupported user.locale values; the template itself defaults to en.
+function localeFor(
+  userLocale: string | null,
+  defaults: GdprMailDefaults,
+): GdprMailLocale | undefined {
+  return normalizeGdprMailLocale(userLocale) ?? defaults.locale;
+}
+
+export function makeDefaultExportReadyEmail(
+  resolveTransport: TransportResolver,
+  defaults: GdprMailDefaults = {},
+): SendExportReadyEmailFn {
+  return async (args) => {
+    const transport = await resolveTransport(args.tenantId);
+    const { subject, html } = renderExportReadyEmail({
+      downloadUrl: args.downloadUrl,
+      expiresAt: args.expiresAt,
+      locale: localeFor(args.userLocale, defaults),
+      appName: defaults.appName,
+    });
+    await transport.send({ to: args.userEmail, subject, html });
+  };
+}
+
+export function makeDefaultExportFailedEmail(
+  resolveTransport: TransportResolver,
+  defaults: GdprMailDefaults = {},
+): SendExportFailedEmailFn {
+  return async (args) => {
+    const transport = await resolveTransport(args.tenantId);
+    const { subject, html } = renderExportFailedEmail({
+      locale: localeFor(args.userLocale, defaults),
+      appName: defaults.appName,
+    });
+    await transport.send({ to: args.userEmail, subject, html });
+  };
+}
+
+export function makeDefaultDeletionRequestedEmail(
+  resolveTransport: TransportResolver,
+  defaults: GdprMailDefaults = {},
+): SendDeletionRequestedEmailFn {
+  return async (args) => {
+    const transport = await resolveTransport(args.tenantId);
+    const { subject, html } = renderDeletionRequestedEmail({
+      gracePeriodEnd: args.gracePeriodEnd,
+      locale: localeFor(args.userLocale, defaults),
+      appName: defaults.appName,
+    });
+    await transport.send({ to: args.userEmail, subject, html });
+  };
+}
+
+export function makeDefaultDeletionExecutedEmail(
+  resolveTransport: TransportResolver,
+  defaults: GdprMailDefaults = {},
+): SendDeletionExecutedEmailFn {
+  return async (args) => {
+    // Der User ist global, der Mail-Transport per-Tenant — wir senden ueber den
+    // Transport des ersten Memberships. Orphan-User (0 Memberships) liefert
+    // keine Tenant-Identitaet → kein Transport aufloesbar, Mail entfaellt.
+    const tenantId = args.tenantIds[0];
+    if (tenantId === undefined) {
+      // skip: orphan user has no tenant whose transport could send the mail
+      return;
+    }
+    const transport = await resolveTransport(tenantId);
+    const { subject, html } = renderDeletionExecutedEmail({
+      executedAt: args.executedAt,
+      locale: localeFor(args.userLocale, defaults),
+      appName: defaults.appName,
+    });
+    await transport.send({ to: args.userEmail, subject, html });
+  };
+}

package/src/user-data-rights/lib/mail-transport-resolver.ts

@@ -0,0 +1,50 @@
+// Builds a per-tenant mail-transport resolver from a job/handler context, so
+// the GDPR notification crons reach the SAME mounted mail-foundation transport
+// the request path uses. Mirrors makeTenantStorageProviderResolver — the cron
+// ctx carries `configResolver` (the per-request ConfigAccessor exists only in
+// the HTTP dispatcher), so the resolver builds a per-tenant accessor from it.
+// Without that bridge createTransportForTenant throws "ctx.config is missing"
+// in the worker lane (the prod-bug class the file-provider resolver already fixed).
+
+import type { EmailTransport } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { createTransportForTenant } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { ConfigResolver, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { createConfigAccessor } from "../../config";
+
+export interface TenantMailResolverCtx {
+  readonly registry: Registry;
+  // Job-context carries configResolver (per-request ConfigAccessor exists only
+  // in the HTTP dispatcher); the resolver builds a per-tenant accessor from it.
+  // Undefined → the returned resolver throws (callers gate on mail-availability).
+  readonly configResolver: ConfigResolver | undefined;
+  readonly secrets: SecretsContext | undefined;
+  readonly db: DbConnection;
+  readonly userId: string;
+  readonly handlerName: string;
+}
+
+export function makeTenantMailTransportResolver(
+  ctx: TenantMailResolverCtx,
+): (tenantId: string) => Promise<EmailTransport> {
+  return async (tenantId) => {
+    if (!ctx.configResolver) {
+      throw new Error(
+        `${ctx.handlerName}: ctx.configResolver missing — cannot resolve the mail transport for tenant ${tenantId}`,
+      );
+    }
+    const config = createConfigAccessor(
+      ctx.registry,
+      ctx.configResolver,
+      tenantId as Parameters<typeof createConfigAccessor>[2], // @cast-boundary engine-payload: TenantId brand
+      ctx.userId,
+      ctx.db,
+    );
+    return createTransportForTenant(
+      { config, registry: ctx.registry, secrets: ctx.secrets, _userId: ctx.userId },
+      tenantId,
+      ctx.handlerName,
+    );
+  };
+}

package/src/user-data-rights/run-export-jobs.ts

@@ -110,6 +110,9 @@ export const tokenCrud = createEventStoreExecutor(
 export type SendExportReadyEmailFn = (args: {
   readonly userId: string;
   readonly userEmail: string;
+  /** Stored user.locale (free-form, e.g. "de"/"en"/"de-DE"/null) — lets the
+   *  default mailer render in the recipient's language. */
+  readonly userLocale: string | null;
   readonly tenantId: TenantId;
   readonly jobId: string;
   readonly downloadUrl: string;
@@ -120,6 +123,7 @@ export type SendExportReadyEmailFn = (args: {
 export type SendExportFailedEmailFn = (args: {
   readonly userId: string;
   readonly userEmail: string;
+  readonly userLocale: string | null;
   readonly tenantId: TenantId;
   readonly jobId: string;
   readonly errorMessage: string;
@@ -753,12 +757,17 @@ function countingStream(source: AsyncIterable<Uint8Array>): {
 // (Alice in Tenant A+B) hat trotzdem nur 1 user-Row mit ihrer
 // Heim-Tenant als tenantId. Lookup ohne tenantId-filter findet sie
 // aus jedem Worker-Tenant-Context.
-async function lookupUserEmail(db: DbConnection, userId: string): Promise<string | null> {
+async function lookupUserContact(
+  db: DbConnection,
+  userId: string,
+): Promise<{ email: string; locale: string | null } | null> {
   // @cast-boundary db-row.
   const row = (await fetchOne(db, userTable, { id: userId })) as {
     email: string | null;
+    locale: string | null;
   } | null;
-  return row?.email ?? null;
+  if (!row?.email) return null;
+  return { email: row.email, locale: row.locale ?? null };
 }
 
 // Atom 5 — Email-Notification beim done-flip. Best-effort:
@@ -776,8 +785,8 @@ async function fireExportReadyCallback(args: {
   readonly appExportDownloadUrl: string | undefined;
   readonly send: SendExportReadyEmailFn;
 }): Promise<void> {
-  const userEmail = await lookupUserEmail(args.db, args.job.userId);
-  if (!userEmail) {
+  const contact = await lookupUserContact(args.db, args.job.userId);
+  if (!contact) {
     // User-Row fehlt (z.B. forget-Pfad mid-export). Skip-Notification mit
     // Operator-Alert via job-run-Log statt Throw — Job bleibt done, User
     // hat ja seinen Token via export-status.query erreichbar (UI-Pfad).
@@ -802,7 +811,8 @@ async function fireExportReadyCallback(args: {
   const downloadUrl = `${baseUrl}?token=${encodeURIComponent(args.plainToken)}`;
   await args.send({
     userId: args.job.userId,
-    userEmail,
+    userEmail: contact.email,
+    userLocale: contact.locale,
     tenantId: args.job.requestedFromTenantId,
     jobId: args.job.id,
     downloadUrl,
@@ -818,8 +828,8 @@ async function fireExportFailedCallback(args: {
   readonly errorMessage: string;
   readonly send: SendExportFailedEmailFn;
 }): Promise<void> {
-  const userEmail = await lookupUserEmail(args.db, args.job.userId);
-  if (!userEmail) {
+  const contact = await lookupUserContact(args.db, args.job.userId);
+  if (!contact) {
     // biome-ignore lint/suspicious/noConsole: operator-visibility
     console.warn(
       `[user-data-rights:run-export-jobs] userId=${args.job.userId} hat kein userEmail — sendExportFailedEmail skipped`,
@@ -829,7 +839,8 @@ async function fireExportFailedCallback(args: {
   }
   await args.send({
     userId: args.job.userId,
-    userEmail,
+    userEmail: contact.email,
+    userLocale: contact.locale,
     tenantId: args.job.requestedFromTenantId,
     jobId: args.job.id,
     errorMessage: args.errorMessage,

package/src/user-data-rights/run-forget-cleanup.ts

@@ -70,6 +70,9 @@ type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 export type SendDeletionExecutedEmailFn = (args: {
   readonly userId: string;
   readonly userEmail: string;
+  /** Stored user.locale (free-form, cached PRE-tx alongside the email) — lets
+   *  the default mailer render in the recipient's language. */
+  readonly userLocale: string | null;
   readonly tenantIds: readonly TenantId[];
   readonly executedAt: string;
 }) => Promise<void>;
@@ -207,6 +210,7 @@ export async function runForgetCleanup(
           await sendDeletionExecutedEmail({
             userId: user.id,
             userEmail: userResult.userEmailBeforeDelete,
+            userLocale: userResult.userLocaleBeforeDelete,
             tenantIds: userResult.tenantIdsBeforeDelete,
             executedAt: now.toString(),
           });
@@ -231,6 +235,8 @@ interface ProcessUserResult {
    *  null wenn user-Row beim Pre-Tx-Lookup nicht (mehr) existiert oder
    *  email leer ist. */
   readonly userEmailBeforeDelete: string | null;
+  /** user.locale VOR Tx gecacht — Default-Mailer rendert in Empfaenger-Sprache. */
+  readonly userLocaleBeforeDelete: string | null;
   /** Tenant-Memberships VOR Tx — Email-Template kann das nutzen. */
   readonly tenantIdsBeforeDelete: readonly TenantId[];
 }
@@ -252,9 +258,12 @@ async function processUser(args: {
   // Nach der Tx ist email = "deleted-{id}@{tenant}.example" oder NULL.
   // Memory-cache laesst Atom-5b-Callback nach success-flip den
   // ORIGINAL-email an App-Author-Callback geben.
-  const userPreTx = await fetchOne<{ email: string | null }>(db, userTable, { id: userId });
+  const userPreTx = await fetchOne<{ email: string | null; locale: string | null }>(db, userTable, {
+    id: userId,
+  });
   const userEmailBeforeDelete =
     userPreTx?.email && userPreTx.email.length > 0 ? userPreTx.email : null;
+  const userLocaleBeforeDelete = userPreTx?.locale ?? null;
 
   // Memberships fuer diesen User holen — alle Tenants in denen er Mitglied ist.
   const memberships = await selectMany<{ tenantId: TenantId }>(db, tenantMembershipsTable, {
@@ -335,6 +344,7 @@ async function processUser(args: {
     hookCallsAttempted,
     errors,
     userEmailBeforeDelete,
+    userLocaleBeforeDelete,
     tenantIdsBeforeDelete,
   };
 }