@cosmicdrift/kumiko-bundled-features 0.88.0 → 0.90.0

package/src/folders-user-data/hooks.ts

@@ -0,0 +1,58 @@
+// EXT_USER_DATA hooks for the folder + folder-assignment entities (GDPR Art. 20
+// export / Art. 17 erasure). Lives apart from the folders feature so folders
+// consumers without the user-data-rights pipeline don't pull a hard dependency.
+// Mirrors credit-user-data — standard tenant-scoped pattern, no name-stripping
+// (a folder name is tenant data, not per-user PII).
+
+import { deleteMany, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEntityExecutor,
+  type UserDataDeleteHook,
+  type UserDataExportHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { folderAssignmentEntity, folderEntity } from "../folders";
+
+const { table: folderTable } = createEntityExecutor("folder", folderEntity);
+const { table: folderAssignmentTable } = createEntityExecutor(
+  "folder-assignment",
+  folderAssignmentEntity,
+);
+
+// Folders are tenant-scoped (no per-user owner column). Every tenant user reads
+// all tenant folders in-app, so bundling them into the user's export is no new
+// exposure — it gives the data subject the organisation of the loans they work with.
+export const folderExportHook: UserDataExportHook = async (ctx) => {
+  const rows = await selectMany<Record<string, unknown>>(ctx.db, folderTable, {
+    tenantId: ctx.tenantId,
+  });
+  if (rows.length === 0) return null;
+  return { entity: "folder", rows };
+};
+
+export const folderAssignmentExportHook: UserDataExportHook = async (ctx) => {
+  const rows = await selectMany<Record<string, unknown>>(ctx.db, folderAssignmentTable, {
+    tenantId: ctx.tenantId,
+  });
+  if (rows.length === 0) return null;
+  return { entity: "folder-assignment", rows };
+};
+
+// Tenant-scoped erasure is only safe when the tenant is effectively single-user
+// (set by the forget orchestrator from the app's tenantModel + a runtime
+// sole-member check). In a multi-user tenant this stays a no-op: deleting by
+// tenant would destroy co-members' folders. anonymize is also a no-op — folder
+// rows carry no person-link to strip (name is tenant data, not PII), so a
+// retention hold simply keeps them.
+function tenantScopedDelete(table: typeof folderTable): UserDataDeleteHook {
+  return async (ctx, strategy) => {
+    // skip: multi-user tenant — a tenant-wide delete would destroy co-members' folders
+    if (ctx.tenantModel !== "single-user") return;
+    // skip: anonymize is a no-op — folder rows carry no per-user PII to strip
+    if (strategy === "anonymize") return;
+    await deleteMany(ctx.db, table, { tenantId: ctx.tenantId });
+  };
+}
+
+export const folderDeleteHook: UserDataDeleteHook = tenantScopedDelete(folderTable);
+export const folderAssignmentDeleteHook: UserDataDeleteHook =
+  tenantScopedDelete(folderAssignmentTable);

package/src/folders-user-data/index.ts

@@ -0,0 +1,33 @@
+// Provides the EXT_USER_DATA export/delete hooks for the folder + folder-assignment
+// entities as a standalone feature — mount it alongside the folders feature +
+// user-data-rights when an app needs folders in its GDPR export/forget pipeline.
+// Kept separate from the folders feature (which only requires "tenant") so
+// folders stays usable without the user-data-rights stack. Mirrors credit-user-data.
+
+import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  folderAssignmentDeleteHook,
+  folderAssignmentExportHook,
+  folderDeleteHook,
+  folderExportHook,
+} from "./hooks";
+
+export const foldersUserDataFeature = defineFeature("folders-user-data", (r) => {
+  r.describe(
+    "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `folders` feature's `folder` + `folder-assignment` entities. Mounts the EXT_USER_DATA export + delete hooks so a tenant's folder tree and its entity-to-folder assignments are included in the user-data export bundle and erased on a tenant-scoped forget (single-user tenants only; multi-user + anonymize are no-ops since folder rows carry no per-user PII). Kept separate from `folders` so folder consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `folders`.",
+  );
+  // user-data-rights ist die harte Abhängigkeit (EXT_USER_DATA-Host). `folders` ist
+  // OPTIONAL: ist es toggleable(default=false) gemountet (z.B. per-Tenant via Tier),
+  // würde ein hartes r.requires eine „effectively disabled"-Boot-Warnung werfen,
+  // obwohl die folder-Entities existieren und die Hooks korrekt greifen.
+  r.requires("user-data-rights");
+  r.optionalRequires("folders");
+  r.useExtension(EXT_USER_DATA, "folder", {
+    export: folderExportHook,
+    delete: folderDeleteHook,
+  });
+  r.useExtension(EXT_USER_DATA, "folder-assignment", {
+    export: folderAssignmentExportHook,
+    delete: folderAssignmentDeleteHook,
+  });
+});

package/src/legal-pages/__tests__/legal-pages.integration.test.ts

@@ -163,7 +163,7 @@ describe("legal-pages :: edge-cases", () => {
 describe("legal-pages :: cache-control", () => {
   test("sets revalidate cache header + etag", async () => {
     const res = await stack.app.request("/legal/impressum");
-    expect(res.headers.get("cache-control")).toBe("public, max-age=0, must-revalidate");
+    expect(res.headers.get("cache-control")).toBe("public, max-age=60, must-revalidate");
     expect(res.headers.get("etag")).toBeTruthy();
   });
 
@@ -176,6 +176,13 @@ describe("legal-pages :: cache-control", () => {
     });
     expect(second.status).toBe(304);
   });
+
+  test("HEAD → 200 without body, etag present", async () => {
+    const res = await stack.app.request("/legal/impressum", { method: "HEAD" });
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("");
+    expect(res.headers.get("etag")).toBeTruthy();
+  });
 });
 
 describe("legal-pages :: security headers", () => {

package/src/legal-pages/feature.ts

@@ -2,7 +2,7 @@ import {
   requireTextContent,
   type TextContentApi,
 } from "@cosmicdrift/kumiko-bundled-features/text-content";
-import { computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
+import { computeRevisionEtag, etagMatches } from "@cosmicdrift/kumiko-framework/api";
 import {
   defineFeature,
   type FeatureDefinition,
@@ -26,6 +26,11 @@ type ByslugQueryBody = {
   data: { title: string; body: string | null; updatedAt: string } | null;
 };
 
+// Legal-Content ändert sich selten — ein 60s-Shared-Cache-Fenster spart den
+// Origin-Revalidate-Roundtrip (jeder 304 re-runt sonst die Content-Query),
+// ohne dass Edits spürbar stale wirken.
+const PUBLIC_PAGE_CACHE = { kind: "revalidate", maxAgeSeconds: 60 } as const;
+
 // legal-pages — Opt-in-Wrapper um text-content für DACH-Compliance.
 // Liefert vier feste Public-HTML-Routes (/legal/impressum,
 // /legal/datenschutz, /legal/imprint, /legal/privacy) mit
@@ -120,13 +125,20 @@ export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDe
             route.lang,
             data.updatedAt,
           ]);
-          const notModified = cachedSecurePageResponse(c.req.raw, {
-            body: null,
-            etag,
-            cache: { kind: "revalidate" },
-            extra: { "content-type": "text/html; charset=utf-8" },
-          });
-          if (notModified.status === 304) return notModified;
+          const extra = { "content-type": "text/html; charset=utf-8" };
+          // 304 (Revision unverändert) und HEAD überspringen beide das
+          // Markdown-Rendern — der Body wird ohnehin verworfen.
+          if (
+            etagMatches(c.req.raw.headers.get("if-none-match"), etag) ||
+            c.req.method === "HEAD"
+          ) {
+            return cachedSecurePageResponse(c.req.raw, {
+              body: null,
+              etag,
+              cache: PUBLIC_PAGE_CACHE,
+              extra,
+            });
+          }
 
           const html = wrapLayout({
             title: data.title || route.titleFallback,
@@ -137,8 +149,8 @@ export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDe
           return cachedSecurePageResponse(c.req.raw, {
             body: html,
             etag,
-            cache: { kind: "revalidate" },
-            extra: { "content-type": "text/html; charset=utf-8" },
+            cache: PUBLIC_PAGE_CACHE,
+            extra,
           });
         },
       });

package/src/mail-foundation/feature.ts

@@ -35,9 +35,10 @@ import type { EmailTransport } from "@cosmicdrift/kumiko-bundled-features/channe
 import { requireDefined } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
   access,
+  type ConfigAccessor,
   createTenantConfig,
   defineFeature,
-  type HandlerContext,
+  type Registry,
 } from "@cosmicdrift/kumiko-framework/engine";
 
 const FEATURE_NAME = "mail-foundation";
@@ -46,6 +47,37 @@ const FEATURE_NAME = "mail-foundation";
 // Plugin-Interface — what a Provider-Plugin must implement
 // =============================================================================
 
+/**
+ * Schmaler Surface-Type fuer Transport-Plugins — gespiegelt von
+ * file-foundation's FileProviderContext. HandlerContext ist zu fett
+ * (haelt tx, actor, signal etc.); Plugins beschraenken sich auf die
+ * read-Felder die fuer Tenant-Config + Secret-Lookup noetig sind.
+ *
+ * **Warum nicht voller HandlerContext?** Im Worker-Pfad (r.job-getriggerte
+ * Transport-Builds, z.B. der user-data-rights forget/export-Cron) gibt es
+ * keinen per-request `config`/`tx`/`actor` — der Wrapper baut den per-Tenant-
+ * ConfigAccessor aus `ctx.configResolver`. Ein Plugin das `ctx.tx` oder
+ * andere request-only-Felder liest, wuerde den Worker-Pfad zur Runtime
+ * brechen — und das fiele NUR mit echtem SMTP und nur in production auf.
+ * Cast `ctx as unknown as HandlerContext` macht den Compiler happy, fliegt
+ * aber zur Runtime im Worker. Plugin das mehr braucht: MailTransportContext
+ * explizit erweitern (sichtbarer breaking change) statt ctx-cast.
+ *
+ * **Felder:**
+ *   config   — tenant-config-reads (host/port/from/... der Plugins)
+ *   registry — extension-Lookup in der Factory (nicht plugin-intern)
+ *   secrets  — tenant-secret-reads (smtp.password)
+ *   _userId  — Audit-Identity fuer secret-reads. Handler-Pfad: dispatcher
+ *              setzt Caller-User-ID; Worker-Pfad: r.job-Wrap setzt eine
+ *              System-Identity.
+ */
+export type MailTransportContext = {
+  readonly config?: ConfigAccessor;
+  readonly registry?: Registry;
+  readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
+  readonly _userId?: string | undefined;
+};
+
 /**
  * Mail-Transport-Plugin contract. Each provider-feature (mail-transport-
  * smtp, mail-transport-brevo-api, ...) registers an implementation via
@@ -55,11 +87,20 @@ const FEATURE_NAME = "mail-foundation";
  * (the plugin owns its provider-specific config schema) and constructs
  * an EmailTransport. Per-call construction so a tenant editing config
  * sees the change on the next mail.
+ *
+ * **Plugin-Author-Warnung:** `ctx` ist EXPLIZIT ein MailTransportContext,
+ * nicht ein voller HandlerContext (siehe MailTransportContext-Doc).
  */
 export type MailTransportPlugin = {
-  readonly build: (ctx: HandlerContext, tenantId: string) => Promise<EmailTransport>;
+  readonly build: (ctx: MailTransportContext, tenantId: string) => Promise<EmailTransport>;
 };
 
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind. Mirrors file-foundation's isFileProviderPlugin.
+export function isMailTransportPlugin(o: unknown): o is MailTransportPlugin {
+  return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
+}
+
 // =============================================================================
 // Feature-definition
 // =============================================================================
@@ -129,7 +170,7 @@ export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
  *   await transport.send({ to, subject, html });
  */
 export async function createTransportForTenant(
-  ctx: HandlerContext,
+  ctx: MailTransportContext,
   tenantId: string,
   handlerName = "mail-foundation:transport-factory",
 ): Promise<EmailTransport> {
@@ -169,7 +210,11 @@ export async function createTransportForTenant(
     );
   }
 
-  // @cast-boundary engine-payload — extension-usage carries unknown options
-  const plugin = usage.options as MailTransportPlugin;
-  return plugin.build(ctx, tenantId);
+  if (!isMailTransportPlugin(usage.options)) {
+    throw new Error(
+      `${FEATURE_NAME}: provider "${provider}" registered without a build() — ` +
+        `extension options must be a MailTransportPlugin.`,
+    );
+  }
+  return usage.options.build(ctx, tenantId);
 }

package/src/mail-foundation/index.ts

@@ -9,6 +9,8 @@
 
 export {
   createTransportForTenant,
+  isMailTransportPlugin,
+  type MailTransportContext,
   type MailTransportPlugin,
   mailFoundationFeature,
 } from "./feature";

package/src/mail-transport-inmemory/feature.ts

@@ -26,8 +26,11 @@ import type {
   EmailTransport,
 } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import { createInMemoryTransport } from "@cosmicdrift/kumiko-bundled-features/channel-email";
-import type { MailTransportPlugin } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
-import { defineFeature, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  MailTransportContext,
+  MailTransportPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 
 const FEATURE_NAME = "mail-transport-inmemory";
 
@@ -83,7 +86,7 @@ export const mailTransportInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
   r.requires("mail-foundation");
 
   const plugin: MailTransportPlugin = {
-    build: async (_ctx: HandlerContext, tenantId: string): Promise<EmailTransport> => {
+    build: async (_ctx: MailTransportContext, tenantId: string): Promise<EmailTransport> => {
       // Returnt den per-tenant Buffer. Identitätsstabil zwischen calls
       // damit die Demo-Inbox accumulated bleibt.
       return getOrCreateTransportForTenant(tenantId);

package/src/mail-transport-smtp/feature.ts

@@ -34,14 +34,12 @@ import {
   requireNonEmpty,
   requireSecretSet,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
-import type { MailTransportPlugin } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import type {
+  MailTransportContext,
+  MailTransportPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
-import {
-  access,
-  createTenantConfig,
-  defineFeature,
-  type HandlerContext,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 
 const FEATURE_NAME = "mail-transport-smtp";
 
@@ -115,7 +113,7 @@ export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
   // `entityName` "smtp" is what tenants set in mail-foundation's
   // `provider` config-key to pick this transport.
   const plugin: MailTransportPlugin = {
-    build: async (ctx: HandlerContext, tenantId: string) => buildSmtpTransport(ctx, tenantId), // @wrapper-known semantic-alias
+    build: async (ctx: MailTransportContext, tenantId: string) => buildSmtpTransport(ctx, tenantId), // @wrapper-known semantic-alias
   };
   r.useExtension("mailTransport", "smtp", plugin);
 
@@ -136,7 +134,10 @@ export const SMTP_PASSWORD = mailTransportSmtpFeature.exports.password;
 // Internal: build the EmailTransport from tenant config + secret
 // =============================================================================
 
-async function buildSmtpTransport(ctx: HandlerContext, tenantId: string): Promise<EmailTransport> {
+async function buildSmtpTransport(
+  ctx: MailTransportContext,
+  tenantId: string,
+): Promise<EmailTransport> {
   const ctxConfig = ctx.config;
   if (!ctxConfig) {
     throw new Error(
@@ -185,7 +186,7 @@ async function buildSmtpTransport(ctx: HandlerContext, tenantId: string): Promis
   });
 }
 
-async function readPassword(ctx: HandlerContext, tenantId: string): Promise<string> {
+async function readPassword(ctx: MailTransportContext, tenantId: string): Promise<string> {
   const secrets = requireSecretsContext(ctx, FEATURE_NAME);
   const branded = await secrets.get(tenantId, SMTP_PASSWORD);
   return requireSecretSet(branded, FEATURE_NAME, SMTP_PASSWORD.name).reveal();

package/src/managed-pages/__tests__/managed-pages.integration.test.ts

@@ -145,7 +145,7 @@ describe("managed-pages :: Cache + Security-Header", () => {
   test("Vary: Host + CSP/Hardening-Header + revalidate cache", async () => {
     const res = await stack.app.request("http://a.example.com/p/about");
     expect(res.headers.get("vary")).toBe("Host");
-    expect(res.headers.get("cache-control")).toBe("public, max-age=0, must-revalidate");
+    expect(res.headers.get("cache-control")).toBe("public, max-age=60, must-revalidate");
     expect(res.headers.get("etag")).toBeTruthy();
     expect(res.headers.get("content-security-policy")).toContain("script-src 'none'");
     expect(res.headers.get("x-content-type-options")).toBe("nosniff");

package/src/managed-pages/feature.ts

@@ -1,4 +1,4 @@
-import { computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
+import { computeRevisionEtag, etagMatches } from "@cosmicdrift/kumiko-framework/api";
 import {
   defineEntityCreateHandler,
   defineEntityDeleteHandler,
@@ -28,6 +28,11 @@ import { pageEntity } from "./table";
 // Alias (publicstatus = "Admin") müssen TenantAdmin granten/mappen.
 const ADMIN_ACCESS = { roles: ["TenantAdmin", "SystemAdmin"] } as const;
 
+// Published CMS-Content ändert sich selten — ein 60s-Shared-Cache-Fenster
+// spart den Origin-Revalidate-Roundtrip (jeder 304 re-runt sonst Page- +
+// Branding-Query), Edits sind nach spätestens 60s live.
+const PUBLIC_PAGE_CACHE = { kind: "revalidate", maxAgeSeconds: 60 } as const;
+
 // QN-Konstante als dokumentierter Public-Contract — der Render-Pfad ruft
 // die by-slug-Query via internem app.fetch (kein Code-Import des Handlers,
 // symmetrisch zum legal-pages-Muster).
@@ -248,13 +253,16 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
           "content-type": "text/html; charset=utf-8",
           vary: "Host",
         } as const;
-        const notModified = cachedSecurePageResponse(c.req.raw, {
-          body: null,
-          etag,
-          cache: { kind: "revalidate" },
-          extra: pageHeaders,
-        });
-        if (notModified.status === 304) return notModified;
+        // 304 (Revision unverändert) und HEAD überspringen beide das
+        // Markdown-Rendern — der Body wird ohnehin verworfen.
+        if (etagMatches(c.req.raw.headers.get("if-none-match"), etag) || c.req.method === "HEAD") {
+          return cachedSecurePageResponse(c.req.raw, {
+            body: null,
+            etag,
+            cache: PUBLIC_PAGE_CACHE,
+            extra: pageHeaders,
+          });
+        }
 
         const html = wrapLayout({
           title: data.title,
@@ -269,7 +277,7 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
         return cachedSecurePageResponse(c.req.raw, {
           body: html,
           etag,
-          cache: { kind: "revalidate" },
+          cache: PUBLIC_PAGE_CACHE,
           extra: pageHeaders,
         });
       },

package/src/user-data-rights/__tests__/default-mailers.test.ts

@@ -0,0 +1,135 @@
+// Unit-Tests fuer die Dispatch-Logik der Default-Mailer: rendert das richtige
+// Template + sendet ueber den aufgeloesten Transport an die User-Email. Die
+// echte Job-Lane-Bruecke (configResolver → Transport) wird NICHT hier, sondern
+// in mail-default-bridge.integration.test.ts gegen den echten Cron bewiesen —
+// ein Fake-Resolver wuerde genau diese Naht ueberspringen.
+
+import { describe, expect, test } from "bun:test";
+import type {
+  EmailMessage,
+  EmailTransport,
+} from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  makeDefaultDeletionExecutedEmail,
+  makeDefaultExportReadyEmail,
+} from "../lib/default-mailers";
+
+function capturingTransport(): { transport: EmailTransport; sent: EmailMessage[] } {
+  const sent: EmailMessage[] = [];
+  const transport: EmailTransport = {
+    send: async (m) => {
+      sent.push(m);
+    },
+  };
+  return { transport, sent };
+}
+
+const TENANT_A = "00000000-0000-4000-8000-00000000000a" as TenantId;
+
+describe("default-mailers dispatch", () => {
+  test("export-ready: rendert Template + sendet an userEmail ueber tenant-transport", async () => {
+    const cap = capturingTransport();
+    const resolved: string[] = [];
+    // Kein defaults.locale → die per-User-Locale (user.locale="de") muss die
+    // Sprache bestimmen. Das ist der Advisor-Befund: en-Default an de-User.
+    const send = makeDefaultExportReadyEmail(
+      async (tenantId) => {
+        resolved.push(tenantId);
+        return cap.transport;
+      },
+      { appName: "Acme" },
+    );
+
+    await send({
+      userId: "u1",
+      userEmail: "u1@example.com",
+      userLocale: "de",
+      tenantId: TENANT_A,
+      jobId: "j1",
+      downloadUrl: "https://app.test/x?token=tok",
+      expiresAt: "2026-07-01T13:45:00Z",
+      bytesWritten: 1234,
+    });
+
+    expect(resolved).toEqual([TENANT_A]);
+    expect(cap.sent).toHaveLength(1);
+    expect(cap.sent[0]?.to).toBe("u1@example.com");
+    // user.locale="de" → deutsches Subject, obwohl kein defaults.locale gesetzt.
+    expect(cap.sent[0]?.subject).toBe("Acme — Dein Datenexport ist bereit");
+    expect(cap.sent[0]?.html).toContain("https://app.test/x?token=tok");
+  });
+
+  test("locale precedence: user.locale wins, mailDefaults is fallback for unknown", async () => {
+    const cap = capturingTransport();
+    const resolve = async () => cap.transport;
+
+    // null user.locale + defaults.locale "en" → English fallback.
+    await makeDefaultExportReadyEmail(resolve, { locale: "en", appName: "Acme" })({
+      userId: "u1",
+      userEmail: "u1@example.com",
+      userLocale: null,
+      tenantId: TENANT_A,
+      jobId: "j1",
+      downloadUrl: "u",
+      expiresAt: "x",
+      bytesWritten: null,
+    });
+    expect(cap.sent[0]?.subject).toBe("Acme — Your data export is ready");
+
+    // unsupported user.locale "fr" + defaults.locale "de" → falls back to de.
+    await makeDefaultExportReadyEmail(resolve, { locale: "de", appName: "Acme" })({
+      userId: "u2",
+      userEmail: "u2@example.com",
+      userLocale: "fr",
+      tenantId: TENANT_A,
+      jobId: "j2",
+      downloadUrl: "u",
+      expiresAt: "x",
+      bytesWritten: null,
+    });
+    expect(cap.sent[1]?.subject).toBe("Acme — Dein Datenexport ist bereit");
+  });
+
+  test("deletion-executed: sendet ueber den ersten Membership-Tenant", async () => {
+    const cap = capturingTransport();
+    const resolved: string[] = [];
+    const send = makeDefaultDeletionExecutedEmail(async (tenantId) => {
+      resolved.push(tenantId);
+      return cap.transport;
+    });
+
+    await send({
+      userId: "u1",
+      userEmail: "u1@example.com",
+      userLocale: "de",
+      tenantIds: [TENANT_A, "00000000-0000-4000-8000-00000000000b" as TenantId],
+      executedAt: "2026-07-30T09:05:00Z",
+    });
+
+    expect(resolved).toEqual([TENANT_A]);
+    expect(cap.sent).toHaveLength(1);
+    expect(cap.sent[0]?.to).toBe("u1@example.com");
+    expect(cap.sent[0]?.subject).toBe("Konto — Dein Konto wurde geloescht");
+  });
+
+  test("deletion-executed orphan (0 Memberships): kein Transport aufgeloest, keine Mail", async () => {
+    const cap = capturingTransport();
+    let resolverCalled = false;
+    const send = makeDefaultDeletionExecutedEmail(async () => {
+      resolverCalled = true;
+      return cap.transport;
+    });
+
+    await send({
+      userId: "u1",
+      userEmail: "u1@example.com",
+      userLocale: null,
+      tenantIds: [],
+      executedAt: "2026-07-30T09:05:00Z",
+    });
+
+    expect(resolverCalled).toBe(false);
+    expect(cap.sent).toHaveLength(0);
+  });
+});

package/src/user-data-rights/__tests__/email-templates.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import {
+  renderDeletionExecutedEmail,
+  renderDeletionRequestedEmail,
+  renderExportFailedEmail,
+  renderExportReadyEmail,
+} from "../email-templates";
+
+describe("gdpr email-templates", () => {
+  test("export-ready: subject + download-button + formatted expiry, de/en differ", () => {
+    const en = renderExportReadyEmail({
+      downloadUrl: "https://app.test/export/by-token?token=abc123",
+      expiresAt: "2026-07-01T13:45:00Z",
+      locale: "en",
+      appName: "Acme",
+    });
+    expect(en.subject).toBe("Acme — Your data export is ready");
+    expect(en.html).toContain("https://app.test/export/by-token?token=abc123");
+    // Button label present.
+    expect(en.html).toContain("Download data export");
+    // Instant formatted to UTC, not the raw ISO.
+    expect(en.html).toContain("2026-07-01 13:45 UTC");
+
+    const de = renderExportReadyEmail({
+      downloadUrl: "https://app.test/x?token=abc",
+      expiresAt: "2026-07-01T13:45:00Z",
+      locale: "de",
+      appName: "Acme",
+    });
+    expect(de.subject).toBe("Acme — Dein Datenexport ist bereit");
+    expect(de.subject).not.toBe(en.subject);
+  });
+
+  test("export-ready: ampersand in download url is escaped in the href attr", () => {
+    const r = renderExportReadyEmail({
+      downloadUrl: "https://app.test/x?token=a&next=b",
+      expiresAt: "2026-07-01T13:45:00Z",
+    });
+    // escapeHtmlAttr turns & into & — no raw unescaped attribute break.
+    expect(r.html).toContain("token=a&next=b");
+    expect(r.html).not.toContain('token=a&next="');
+  });
+
+  test("export-ready: default appName when omitted (Account/Konto)", () => {
+    expect(
+      renderExportReadyEmail({ downloadUrl: "u", expiresAt: "x", locale: "en" }).subject,
+    ).toContain("Account");
+    expect(
+      renderExportReadyEmail({ downloadUrl: "u", expiresAt: "x", locale: "de" }).subject,
+    ).toContain("Konto");
+  });
+
+  test("export-failed: informational, no download button", () => {
+    const r = renderExportFailedEmail({ locale: "en", appName: "Acme" });
+    expect(r.subject).toBe("Acme — Your data export failed");
+    expect(r.html).not.toContain("<a ");
+    expect(r.html).toContain("request the export again");
+  });
+
+  test("deletion-requested: grace deadline formatted + cancel hint", () => {
+    const r = renderDeletionRequestedEmail({
+      gracePeriodEnd: "2026-07-30T09:00:00Z",
+      locale: "en",
+      appName: "Acme",
+    });
+    expect(r.subject).toBe("Acme — Account deletion requested");
+    expect(r.html).toContain("2026-07-30 09:00 UTC");
+    expect(r.html).toContain("cancel the deletion");
+  });
+
+  test("deletion-executed: execution timestamp formatted", () => {
+    const r = renderDeletionExecutedEmail({
+      executedAt: "2026-07-30T09:05:00Z",
+      locale: "de",
+      appName: "Acme",
+    });
+    expect(r.subject).toBe("Acme — Dein Konto wurde geloescht");
+    expect(r.html).toContain("2026-07-30 09:05 UTC");
+  });
+
+  test("un-parsable timestamp falls back to the raw string", () => {
+    const r = renderDeletionExecutedEmail({ executedAt: "not-a-date" });
+    expect(r.html).toContain("not-a-date");
+  });
+});