@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/inbound-mail-foundation/oauth-state.ts

@@ -0,0 +1,103 @@
+// HMAC-signierter OAuth-`state`-Parameter für den Connect-Flow.
+//
+// Bindet {tenantId, ownerUserId?, providerKey, mailbox, nonce} an den
+// Redirect: der anonyme Callback (außerhalb /api/*) vertraut NUR dem
+// verifizierten state — verhindert CSRF und Fremd-Claiming (ein
+// Angreifer kann den Callback nicht auf einen fremden Tenant/User
+// umbiegen, ohne die Signatur zu brechen).
+//
+// Format: <payload-base64url>.<expiresAtMs>.<hmac-base64url>
+// Muster: auth-email-password/signed-token.ts (HMAC-SHA256, purpose im
+// HMAC-Input, timing-safe compare, Expiry im Klartext-Segment).
+
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { Temporal } from "temporal-polyfill";
+
+const STATE_PURPOSE = "inbound-mail-oauth-connect";
+
+export type OAuthStatePayload = {
+  readonly tenantId: string;
+  /** null = shared-Postfach, sonst persönliches Postfach dieses Users. */
+  readonly ownerUserId: string | null;
+  readonly providerKey: string;
+  /** Postfach-Adresse aus dem Connect-Request — landet nach dem
+   *  Token-Exchange im MailAccount. */
+  readonly mailbox: string;
+  /** Einmal-Nonce — macht jeden state einzigartig (kein Replay über
+   *  zwei parallele Connect-Flows hinweg). */
+  readonly nonce: string;
+};
+
+export type VerifyOAuthStateResult =
+  | { readonly ok: true; readonly payload: OAuthStatePayload }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+function sign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+function hmacInput(payloadB64: string, expiresAtMs: number): string {
+  return `${STATE_PURPOSE}:${payloadB64}.${expiresAtMs}`;
+}
+
+export function signOAuthState(
+  payload: Omit<OAuthStatePayload, "nonce">,
+  ttlMinutes: number,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): string {
+  const full: OAuthStatePayload = { ...payload, nonce: randomUUID() };
+  const payloadB64 = Buffer.from(JSON.stringify(full), "utf8").toString("base64url");
+  const expiresAtMs = now.add({ minutes: ttlMinutes }).epochMilliseconds;
+  const signature = sign(hmacInput(payloadB64, expiresAtMs), secret);
+  return `${payloadB64}.${expiresAtMs}.${signature}`;
+}
+
+export function verifyOAuthState(
+  state: string,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): VerifyOAuthStateResult {
+  const parts = state.split(".");
+  if (parts.length !== 3) return { ok: false, reason: "malformed" };
+  const [payloadB64, expiresAtRaw, providedSig] = parts;
+  if (!payloadB64 || !expiresAtRaw || !providedSig) return { ok: false, reason: "malformed" };
+
+  const expiresAtMs = Number(expiresAtRaw);
+  if (!Number.isFinite(expiresAtMs) || String(expiresAtMs) !== expiresAtRaw) {
+    return { ok: false, reason: "malformed" };
+  }
+
+  const expected = sign(hmacInput(payloadB64, expiresAtMs), secret);
+  const expectedBuf = Buffer.from(expected, "base64url");
+  const providedBuf = Buffer.from(providedSig, "base64url");
+  // Length-check VOR timingSafeEqual — die würde bei Längen-Mismatch
+  // werfen, und der Throw selbst leakt via Timing.
+  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
+  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
+
+  if (Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(expiresAtMs)) > 0) {
+    return { ok: false, reason: "expired" };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  if (!isOAuthStatePayload(parsed)) return { ok: false, reason: "malformed" };
+  return { ok: true, payload: parsed };
+}
+
+function isOAuthStatePayload(v: unknown): v is OAuthStatePayload {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v as Record<string, unknown>;
+  return (
+    typeof o["tenantId"] === "string" &&
+    (o["ownerUserId"] === null || typeof o["ownerUserId"] === "string") &&
+    typeof o["providerKey"] === "string" &&
+    typeof o["mailbox"] === "string" &&
+    typeof o["nonce"] === "string"
+  );
+}

package/packages/bundled-features/src/inbound-mail-foundation/projection.ts

@@ -0,0 +1,155 @@
+// Inline-projections für die drei event-sourced Streams:
+//   mail-account     → read_mail_accounts     (UPSERT, current state)
+//   inbound-message  → read_inbound_messages  (INSERT-ignore, append-only)
+//   mail-thread      → read_mail_threads      (UPSERT, Rollup)
+//
+// Apply läuft in derselben TX wie ctx.unsafeAppendEvent — read-your-
+// own-write ohne dispatcher-tick (Muster billing-foundation).
+//
+// **Production-deployment caveat** (gleich wie billing-foundation):
+// die Tables sind als raw drizzle-pgTable in r.projection registriert,
+// NICHT als r.entity — Apps müssen sie in ihre drizzle/generate.ts
+// aufnehmen (via *-ProjectionTable-Imports). setupTestStack pusht sie
+// automatisch via r.projection.table.
+//
+// **PII:** die Payload-Felder (address/from/to/cc/subject/snippet)
+// kommen bereits als Ciphertext an — encrypted VOR dem append im
+// write-handler. Die applies kopieren nur durch; decrypted wird erst
+// in den list-queries.
+
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  insertIgnoreProjectionRow,
+  upsertProjectionRow,
+} from "./db/queries/inbound-projections.js";
+import { inboundMessageEntity, mailAccountEntity, mailThreadEntity } from "./entities.js";
+import type {
+  InboundMessageEventPayload,
+  MailAccountEventPayload,
+  MailThreadEventPayload,
+} from "./events.js";
+
+// Drizzle-table-instances aus den entity-shapes — geteilt zwischen
+// projection-applies und list-queries (ein column-namespace).
+export const mailAccountsProjectionTable = buildEntityTable("mail-account", mailAccountEntity);
+export const inboundMessagesProjectionTable = buildEntityTable(
+  "inbound-message",
+  inboundMessageEntity,
+);
+export const mailThreadsProjectionTable = buildEntityTable("mail-thread", mailThreadEntity);
+
+function tableNameOf(table: unknown): string {
+  return (table as { tableName: string }).tableName;
+}
+
+// =============================================================================
+// mail-account — connected/updated/disconnected teilen den payload-shape,
+// der event-type taggt was passiert ist. Alle drei UPSERT-full für
+// defensive consistency (rebuild-aus-dem-Nichts, out-of-order).
+// =============================================================================
+
+const ACCOUNT_SET_CLAUSES = [
+  `"provider" = EXCLUDED."provider"`,
+  `"auth_method" = EXCLUDED."auth_method"`,
+  `"owner_user_id" = EXCLUDED."owner_user_id"`,
+  `"display_name" = EXCLUDED."display_name"`,
+  `"address" = EXCLUDED."address"`,
+  `"status" = EXCLUDED."status"`,
+  `"watch_state" = EXCLUDED."watch_state"`,
+  // connected_at bewusst NICHT im SET: der Erst-Connect-Zeitpunkt
+  // bleibt stehen, updated/disconnected überschreiben ihn nicht.
+];
+
+const applyMailAccountUpsert = defineApply<MailAccountEventPayload>(async (event, tx) => {
+  const p = event.payload;
+  const insertCols = {
+    id: event.aggregateId,
+    tenant_id: event.tenantId,
+    provider: p.provider,
+    auth_method: p.authMethod,
+    owner_user_id: p.ownerUserId,
+    display_name: p.displayName,
+    address: p.address,
+    status: p.status,
+    watch_state: p.watchState,
+    // Insert-Pfad = Erst-Connect (bzw. Rebuild: createdAt des ersten
+    // events des Streams — fachlich derselbe Zeitpunkt).
+    connected_at: event.createdAt.toString(),
+  };
+  await upsertProjectionRow(
+    tx,
+    tableNameOf(mailAccountsProjectionTable),
+    insertCols,
+    ACCOUNT_SET_CLAUSES,
+    Object.values(insertCols),
+  );
+});
+
+/** mail-account-connected → UPSERT full. */
+export const applyMailAccountConnected = applyMailAccountUpsert;
+/** mail-account-updated → UPSERT full (status/watchState-Übergänge). */
+export const applyMailAccountUpdated = applyMailAccountUpsert;
+/** mail-account-disconnected → UPSERT full (payload.status=disconnected).
+ *  Row bleibt (Audit-Sicht in der Account-Liste), Stream bleibt. */
+export const applyMailAccountDisconnected = applyMailAccountUpsert;
+
+// =============================================================================
+// inbound-message — genau EIN received-event pro Stream (deterministic
+// aggregateId). INSERT-ignore: Replays no-op'en auf der PK statt zu
+// knallen; es gibt keinen update-Fall.
+// =============================================================================
+
+/** inbound-message-received → INSERT ... ON CONFLICT DO NOTHING. */
+export const applyInboundMessageReceived = defineApply<InboundMessageEventPayload>(
+  async (event, tx) => {
+    const p = event.payload;
+    await insertIgnoreProjectionRow(tx, tableNameOf(inboundMessagesProjectionTable), {
+      id: event.aggregateId,
+      tenant_id: event.tenantId,
+      account_id: p.accountId,
+      owner_user_id: p.ownerUserId,
+      message_id_header: p.messageIdHeader,
+      thread_key: p.threadKey,
+      from: p.from,
+      to: p.to,
+      cc: p.cc,
+      subject: p.subject,
+      snippet: p.snippet,
+      received_at: p.receivedAtIso,
+      body_ref: p.bodyRef,
+      scope: p.scope,
+    });
+  },
+);
+
+// =============================================================================
+// mail-thread — Rollup pro (tenantId, threadKey). Der write-handler
+// berechnet messageCount/lastMessageAt und appendet den updated-event
+// mit dem NEUEN Stand — die apply ist ein dummer UPSERT-full (kein
+// increment in der apply: Replays wären sonst nicht idempotent).
+// =============================================================================
+
+/** mail-thread-updated → UPSERT full mit dem Payload-Snapshot. */
+export const applyMailThreadUpdated = defineApply<MailThreadEventPayload>(async (event, tx) => {
+  const p = event.payload;
+  const insertCols = {
+    id: event.aggregateId,
+    tenant_id: event.tenantId,
+    thread_key: p.threadKey,
+    subject: p.subject,
+    last_message_at: p.lastMessageAtIso,
+    message_count: p.messageCount,
+  };
+  await upsertProjectionRow(
+    tx,
+    tableNameOf(mailThreadsProjectionTable),
+    insertCols,
+    [
+      `"subject" = EXCLUDED."subject"`,
+      `"last_message_at" = EXCLUDED."last_message_at"`,
+      `"message_count" = EXCLUDED."message_count"`,
+    ],
+    Object.values(insertCols),
+  );
+});

package/packages/bundled-features/src/inbound-mail-foundation/provider-factory.ts

@@ -0,0 +1,53 @@
+// Provider-Factory — Mirror von mail-foundation's createTransportForTenant
+// inkl. der drei Fehlerpfade (kein registry / nicht registriert / falsche
+// Plugin-Shape). Abweichung zum Outbound-Muster (Plan §1.3): KEIN
+// per-Tenant-Config-Selector — der Provider steht pro MailAccount
+// (`account.provider`), ein Tenant kann mehrere Provider parallel nutzen.
+
+import { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION } from "./constants.js";
+import {
+  type InboundMailContext,
+  type InboundMailProviderPlugin,
+  isInboundMailProviderPlugin,
+  type MailAccountRecord,
+} from "./types.js";
+
+/** Lookup per Provider-Key ("imap", "m365-graph", ...) — genutzt von den
+ *  OAuth-Connect-Routen, wo noch kein Account existiert. */
+export function resolveInboundProviderForKey(
+  ctx: InboundMailContext,
+  providerKey: string,
+  handlerName = "inbound-mail-foundation:provider-factory",
+): InboundMailProviderPlugin {
+  if (!ctx.registry) {
+    throw new Error(
+      `${handlerName}: ctx.registry is missing — required to look up registered inbound-mail provider plugins`,
+    );
+  }
+  const usages = ctx.registry.getExtensionUsages(INBOUND_MAIL_PROVIDER_EXTENSION);
+  const usage = usages.find((u) => u.entityName === providerKey);
+  if (!usage) {
+    const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+    throw new Error(
+      `${INBOUND_MAIL_FOUNDATION_FEATURE}: provider "${providerKey}" not registered. Known: ${known}. ` +
+        `Mount the matching inbound-provider-${providerKey} feature.`,
+    );
+  }
+  if (!isInboundMailProviderPlugin(usage.options)) {
+    throw new Error(
+      `${INBOUND_MAIL_FOUNDATION_FEATURE}: provider "${providerKey}" registered without verify()/fetch() — ` +
+        `extension options must be an InboundMailProviderPlugin.`,
+    );
+  }
+  return usage.options;
+}
+
+/** Lookup für einen konkreten Account — der Standard-Pfad in Poll-Job
+ *  und Watch-Supervisor. */
+export function resolveInboundProviderForAccount(
+  ctx: InboundMailContext,
+  account: MailAccountRecord,
+  handlerName = "inbound-mail-foundation:provider-factory",
+): InboundMailProviderPlugin {
+  return resolveInboundProviderForKey(ctx, account.provider, handlerName);
+}

package/packages/bundled-features/src/inbound-mail-foundation/retention-sweep.ts

@@ -0,0 +1,168 @@
+// Inbound-mail data-retention (#957). DSGVO Art. 5 (Datenminimierung):
+// ohne Retention wachsen read_inbound_messages + die File-Storage-Bodies
+// unbegrenzt. Zwei Targets, zwei Mechanismen — der Unterschied ist
+// event-sourced vs. unmanaged:
+//
+//   read_inbound_messages (event-sourced, EXPLIZITE r.projection):
+//     pro Row aelter als messageRetentionDays → archiveStream + Row-Delete
+//     (+ bodyRef-Objekt loeschen). archiveStream statt executor.forget, weil
+//     die Projection nur das received-Domain-Event mappt, nicht den
+//     forgotten-Auto-Verb (den registriert nur ImplicitProjection). Ein
+//     forget-Event wuerde beim Rebuild ignoriert und die Row aus dem
+//     received-Event resurrecten (#648-Klasse). Der archivierte Stream macht
+//     loadAggregate leer → received wird gar nicht erst repliziert. Gleiches
+//     Muster wie tenant-destroy-hook, nur per-Row-cutoff statt ganzer Tenant.
+//
+//   store_mail_seen_messages (unmanaged, direct-write, nicht event-sourced):
+//     Dedup-Anker braucht nur das Backfill-/Replay-Fenster → seenAt-cutoff
+//     via plain deleteMany, kein Stream/Archiv. Gescoped direkt über die
+//     tenant_id-Spalte der Tabelle (table-builder-Konvention), kein Account-Join.
+//
+// GRENZE (#957 Teil 2, Plan §3.4): die PII in den Message-Events bleibt
+// unter dem TENANT-Subject-Key entschluesselbar — per-Row-Retention
+// shreddet keinen Key. Echte Art.-17-Erasure der Event-Payloads passiert
+// erst bei tenant-destroy (Key-Erase). Read-Row + Body-File sind nach dem
+// Sweep weg; das Event-Log ist append-only by design.
+
+import {
+  type DbRunner,
+  deleteMany,
+  type EntityTableMeta,
+  selectMany,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
+import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { seenMessageTable } from "./entities.js";
+import { INBOUND_MESSAGE_AGGREGATE_TYPE } from "./events.js";
+import { inboundMessagesProjectionTable } from "./projection.js";
+
+// Temporal.Instant ohne den Caller zwingen es aus globalThis zu ziehen
+// (Muster data-retention/keep-for.ts).
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+export const MESSAGE_RETENTION_DAYS = 365;
+export const SEEN_RETENTION_DAYS = 90;
+const BATCH_LIMIT = 1000;
+const ARCHIVED_BY = "inbound-mail:retention";
+const REASON = "retention_expired";
+
+export interface InboundRetentionArgs {
+  readonly db: DbRunner;
+  readonly tenantId: TenantId;
+  /** Now-Injection — Tests pinnen den Wert ohne Date-Mock (Pattern keep-for.ts). */
+  readonly now: Instant;
+  readonly messageRetentionDays?: number;
+  readonly seenRetentionDays?: number;
+  /** Loescht ein file-storage-Body-Objekt per bodyRef-key. Vom Job lazy
+   *  verdrahtet (createFileProviderForTenant). Fehlt = kein Body-Delete. */
+  readonly deleteBodyObject?: (bodyRef: string) => Promise<void>;
+}
+
+export interface InboundRetentionReport {
+  readonly messagesPurged: number;
+  readonly bodyObjectsDeleted: number;
+  readonly bodyObjectErrors: number;
+  readonly seenPurged: number;
+}
+
+export async function runInboundMailRetention(
+  args: InboundRetentionArgs,
+): Promise<InboundRetentionReport> {
+  const messageDays = args.messageRetentionDays ?? MESSAGE_RETENTION_DAYS;
+  const seenDays = args.seenRetentionDays ?? SEEN_RETENTION_DAYS;
+  const messageCutoff = args.now.subtract({ hours: messageDays * 24 });
+  const seenCutoff = args.now.subtract({ hours: seenDays * 24 });
+
+  const messages = await purgeExpiredMessages(args, messageCutoff);
+  const seenPurged = await purgeExpiredSeenAnchors(args.db, args.tenantId, seenCutoff);
+
+  return { ...messages, seenPurged };
+}
+
+type ExpiredMessageRow = { readonly id: string; readonly bodyRef: string | null };
+
+async function purgeExpiredMessages(
+  args: InboundRetentionArgs,
+  cutoff: Instant,
+): Promise<Omit<InboundRetentionReport, "seenPurged">> {
+  let messagesPurged = 0;
+  let bodyObjectsDeleted = 0;
+  let bodyObjectErrors = 0;
+
+  // Drain-Loop: jede Page loescht die Rows die sie liest, die naechste ist
+  // damit frisch. archiveStream VOR dem Delete (crash dazwischen → naechster
+  // Lauf re-archiviert idempotent + loescht). Delete strikt nach den
+  // archivierten ids, nie per cutoff-WHERE — sonst koennte eine zwischen
+  // select und delete eingegangene Alt-Mail unarchiviert geloescht werden
+  // und beim Rebuild resurrecten.
+  //
+  // Ein Row deren deleteBodyObject fehlschlaegt wird NICHT geloescht — sonst
+  // ginge die einzige Referenz auf das (dann verwaiste) File-Objekt verloren
+  // (kein Retry, kein Dead-Letter). Die Row bleibt fuer den naechsten Sweep
+  // stehen (archiveStream ist idempotent). failedIds verhindert, dass so ein
+  // Row innerhalb DIESES Laufs endlos re-selektiert wird.
+  const failedIds = new Set<string>();
+  for (;;) {
+    const rows = (
+      await selectMany<ExpiredMessageRow>(
+        args.db,
+        inboundMessagesProjectionTable,
+        { receivedAt: { lt: cutoff }, tenantId: args.tenantId },
+        { limit: BATCH_LIMIT },
+      )
+    ).filter((row) => !failedIds.has(row.id));
+    if (rows.length === 0) break;
+
+    const ids: string[] = [];
+    for (const row of rows) {
+      await archiveStream(args.db, {
+        tenantId: args.tenantId,
+        aggregateId: row.id,
+        aggregateType: INBOUND_MESSAGE_AGGREGATE_TYPE,
+        archivedBy: ARCHIVED_BY,
+        reason: REASON,
+      });
+      if (row.bodyRef && args.deleteBodyObject) {
+        try {
+          await args.deleteBodyObject(row.bodyRef);
+          bodyObjectsDeleted++;
+        } catch {
+          bodyObjectErrors++;
+          failedIds.add(row.id);
+          continue;
+        }
+      }
+      ids.push(row.id);
+    }
+    if (ids.length > 0) {
+      await deleteMany(args.db, inboundMessagesProjectionTable as EntityTableMeta, {
+        id: { in: ids },
+      });
+      messagesPurged += ids.length;
+    }
+
+    if (rows.length < BATCH_LIMIT) break;
+  }
+
+  return { messagesPurged, bodyObjectsDeleted, bodyObjectErrors };
+}
+
+async function purgeExpiredSeenAnchors(
+  db: DbRunner,
+  tenantId: TenantId,
+  cutoff: Instant,
+): Promise<number> {
+  // Seen-Anker erben tenantId (table-builder: jede Entity hat tenant_id) →
+  // direkt tenant-scoped, kein Account-Join. Trifft auch Anker, deren Account
+  // schon disconnected/geloescht ist.
+  const where = { tenantId, seenAt: { lt: cutoff } };
+  const expired = await selectMany<{ accountId: string }>(
+    db,
+    seenMessageTable as EntityTableMeta,
+    where,
+  );
+  if (expired.length === 0) return 0;
+  await deleteMany(db, seenMessageTable as EntityTableMeta, where);
+  return expired.length;
+}

package/packages/bundled-features/src/inbound-mail-foundation/tenant-destroy-hook.ts

@@ -0,0 +1,88 @@
+// Tenant-destroy hooks — räumen beim Tenant-Destroy alle Inbound-Mail-
+// Spuren des Tenants ab. Ein Hook PRO tenant-subject-Entity (der
+// gdpr-storage-Boot-Validator prüft die EXT_TENANT_DATA-Registrierung
+// entity-genau), jeweils:
+//
+//   1. Streams archivieren — ein künftiger Projection-Rebuild kann
+//      Gelöschtes nicht resurrecten (Muster billing-foundation #800).
+//      Message-Streams sind viele → Loop über die Projection-Rows
+//      (Row-PK = Stream-ID); tenant-destroy ist ein seltener
+//      Batch-Vorgang, O(n) ist ok.
+//   2. Projection-Rows löschen.
+//   3. Nur mail-account: unmanaged Sync-State (Cursors, Seen-Anchors)
+//      löschen — gekeyt per accountId, deshalb aus den Account-Rows
+//      VOR dem Delete eingesammelt.
+//
+// Die eigentliche PII-Erasure macht crypto-shredding: eraseSubjectKeys
+// löscht den Tenant-Subject-Key, damit werden Event-Log-Payloads UND
+// etwaige Ciphertext-Kopien unlesbar. Diese Hooks entsorgen die Rows.
+
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import { declareEscapeHatch, type TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
+import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
+import { seenMessageTable, syncCursorTable } from "./entities.js";
+import {
+  INBOUND_MESSAGE_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_THREAD_AGGREGATE_TYPE,
+} from "./events.js";
+import {
+  inboundMessagesProjectionTable,
+  mailAccountsProjectionTable,
+  mailThreadsProjectionTable,
+} from "./projection.js";
+
+const ARCHIVED_BY = "tenant-lifecycle:destroy";
+const REASON = "tenant_destroy";
+
+// archiveStream sits outside TenantDb's own methods — needs the escape hatch.
+export const INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON =
+  "tenant-destroy archives each inbound-mail entity's event-streams before the projection rows are deleted";
+
+async function archiveAndDeleteRows(
+  ctx: TenantDataHookCtx,
+  table: EntityTableMeta,
+  aggregateType: string,
+): Promise<readonly string[]> {
+  declareEscapeHatch({ reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON });
+  const rows = await ctx.db.selectMany<{ id: string }>(table, { tenantId: ctx.tenantId });
+  for (const row of rows) {
+    await archiveStream(ctx.db.unsafeRaw(INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON), {
+      tenantId: ctx.tenantId,
+      aggregateId: row.id,
+      aggregateType,
+      archivedBy: ARCHIVED_BY,
+      reason: REASON,
+    });
+  }
+  await ctx.db.deleteMany(table, { tenantId: ctx.tenantId });
+  return rows.map((row) => row.id);
+}
+
+export async function mailAccountTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
+  const accountIds = await archiveAndDeleteRows(
+    ctx,
+    mailAccountsProjectionTable as EntityTableMeta,
+    MAIL_ACCOUNT_AGGREGATE_TYPE,
+  );
+  for (const accountId of accountIds) {
+    await ctx.db.deleteMany(syncCursorTable as EntityTableMeta, { accountId });
+    await ctx.db.deleteMany(seenMessageTable as EntityTableMeta, { accountId });
+  }
+}
+
+export async function inboundMessageTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
+  await archiveAndDeleteRows(
+    ctx,
+    inboundMessagesProjectionTable as EntityTableMeta,
+    INBOUND_MESSAGE_AGGREGATE_TYPE,
+  );
+}
+
+export async function mailThreadTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
+  await archiveAndDeleteRows(
+    ctx,
+    mailThreadsProjectionTable as EntityTableMeta,
+    MAIL_THREAD_AGGREGATE_TYPE,
+  );
+}