@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,147 @@
+// Domain-events für inbound-mail-foundation.
+//
+// **Pattern:** event-sourced — jede eingehende Mail und jeder Account-
+// Lifecycle-Übergang wird zu einem domain-event. Read-models =
+// inline projections (read_mail_accounts / read_inbound_messages /
+// read_mail_threads). Future-consumer (Business-Prozesse: Ticket-
+// Anlage, Beleg-Erkennung, Auto-Antwort) listenen direkt auf
+// `inbound-message-received` und können via extendEntityProjection
+// die KOMPLETTE Historie rückwirkend replayen.
+//
+// **Payload-Disziplin (Events sind forever):**
+//   - domain-clean + generisch: keine App-Begriffe (kein solon), keine
+//     provider-raw-Strukturen im payload — raw lebt in metadata.headers.
+//   - KEINE Bodies: bodyRef zeigt auf file-foundation-Storage. Der
+//     Event-Store ist kein Blob-Store.
+//   - PII (address/from/to/cc/subject/snippet) steht als Ciphertext im
+//     payload (`kumiko-pii:v1:...`), encrypted VOR dem append im
+//     write-handler — Subject-Key ist der Tenant, tenant-destroy's
+//     eraseSubjectKeys macht Event-Log UND Projection unlesbar
+//     (crypto-shredding, Muster billing-foundation #800).
+
+import * as z from "zod";
+import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAccountStatuses } from "./constants.js";
+
+// Aggregate-types für den event-store.
+export const MAIL_ACCOUNT_AGGREGATE_TYPE = "mail-account" as const;
+export const INBOUND_MESSAGE_AGGREGATE_TYPE = "inbound-message" as const;
+export const MAIL_THREAD_AGGREGATE_TYPE = "mail-thread" as const;
+
+// Event-name-Konstanten — short-form (für r.defineEvent) + qualifizierte
+// FQN (für ctx.unsafeAppendEvent + projection-apply-keys).
+export const MAIL_ACCOUNT_CONNECTED_EVENT_SHORT = "mail-account-connected" as const;
+export const MAIL_ACCOUNT_UPDATED_EVENT_SHORT = "mail-account-updated" as const;
+export const MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT = "mail-account-disconnected" as const;
+export const INBOUND_MESSAGE_RECEIVED_EVENT_SHORT = "inbound-message-received" as const;
+export const MAIL_THREAD_UPDATED_EVENT_SHORT = "mail-thread-updated" as const;
+
+export const MAIL_ACCOUNT_CONNECTED_EVENT_QN =
+  `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_CONNECTED_EVENT_SHORT}` as const;
+export const MAIL_ACCOUNT_UPDATED_EVENT_QN =
+  `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_UPDATED_EVENT_SHORT}` as const;
+export const MAIL_ACCOUNT_DISCONNECTED_EVENT_QN =
+  `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT}` as const;
+export const INBOUND_MESSAGE_RECEIVED_EVENT_QN =
+  `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${INBOUND_MESSAGE_RECEIVED_EVENT_SHORT}` as const;
+export const MAIL_THREAD_UPDATED_EVENT_QN =
+  `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_THREAD_UPDATED_EVENT_SHORT}` as const;
+
+const accountStatusEnum = z.enum([
+  InboundMailAccountStatuses.active,
+  InboundMailAccountStatuses.authError,
+  InboundMailAccountStatuses.degraded,
+  InboundMailAccountStatuses.disconnected,
+]);
+
+// ============================================================================
+// mail-account-Stream — connected / updated / disconnected
+// ============================================================================
+//
+// Ein Stream pro Postfach (aggregateId = accountId, random uuid beim
+// connect). address ist PII → maxLength 1000 wegen Ciphertext-Blowup
+// (ein 200-char-Plaintext wird ~460+ chars JSON-envelope, siehe
+// billing-foundation events.ts).
+export const mailAccountEventPayloadSchema = z.object({
+  provider: z.string().min(1).max(50),
+  /** "password" | "xoauth2" | "oauth" (InboundMailAuthMethods) — bewusst
+   *  string statt enum: neue Auth-Methoden ohne Event-Upcaster. */
+  authMethod: z.string().min(1).max(30),
+  /** null = tenant-geteilt, sonst persönliches Postfach dieses Users. */
+  ownerUserId: z.string().max(36).nullable(),
+  displayName: z.string().max(200),
+  address: z.string().min(1).max(1000),
+  status: accountStatusEnum,
+  /** Provider-agnostischer Watch-Zustand ("idle", "watching",
+   *  "backoff:3", ...) — reines Ops-Signal, kein PII. */
+  watchState: z.string().max(100),
+});
+export type MailAccountEventPayload = z.infer<typeof mailAccountEventPayloadSchema>;
+
+// ============================================================================
+// inbound-message-Stream — genau EIN received-Event pro Message
+// ============================================================================
+//
+// aggregateId = inboundMessageAggregateId(accountId, providerMessageId)
+// → deterministic, Provider-Replays kollidieren auf demselben Stream.
+//
+// PII-Felder (from/to/cc/subject/snippet): Ciphertext, maxLength großzügig.
+// to/cc als JSON-stringified string[] VOR encryption — im Payload steht
+// der Ciphertext-String, nicht das Array (primitives only, upcaster-safe).
+export const inboundMessageEventPayloadSchema = z.object({
+  accountId: z.uuid(),
+  /** Scope-Vererbung vom Account (Ingest-Zeitpunkt). */
+  ownerUserId: z.string().max(36).nullable(),
+  /** RFC-5322 Message-ID-Header (normalisiert, ohne <>) — NICHT PII-
+   *  encrypted: Idempotency/Threading-Anchor, opaque technical id. */
+  messageIdHeader: z.string().min(1).max(500),
+  /** Normalisierter Thread-Schlüssel (References-Chain-Root bzw.
+   *  Provider-Thread-ID, provider-präfixed). */
+  threadKey: z.string().min(1).max(500),
+  from: z.string().min(1).max(2000),
+  /** JSON-stringified string[], dann PII-encrypted. */
+  to: z.string().max(8000),
+  /** JSON-stringified string[], dann PII-encrypted. */
+  cc: z.string().max(8000),
+  subject: z.string().max(4000),
+  snippet: z.string().max(4000),
+  /** ISO-Instant — Empfangszeit laut Provider (INTERNALDATE bzw.
+   *  receivedDateTime), nicht Ingest-Zeit. */
+  receivedAtIso: z.string().min(1),
+  /** file-foundation-Referenz auf den raw-Body (MIME). Leer wenn die
+   *  App ohne Body-Persistenz mounted (snippet-only-Mode). */
+  bodyRef: z.string().max(500),
+  /** Fachlicher Scope-Hint für nachgelagerte Business-Prozesse —
+   *  generisch ("inbox", Folder-Name), KEINE App-Semantik. */
+  scope: z.string().max(200),
+});
+export type InboundMessageEventPayload = z.infer<typeof inboundMessageEventPayloadSchema>;
+
+// ============================================================================
+// mail-thread-Stream — Thread-Rollup pro (tenantId, threadKey)
+// ============================================================================
+export const mailThreadEventPayloadSchema = z.object({
+  threadKey: z.string().min(1).max(500),
+  subject: z.string().max(4000),
+  lastMessageAtIso: z.string().min(1),
+  messageCount: z.number().int().min(1),
+});
+export type MailThreadEventPayload = z.infer<typeof mailThreadEventPayloadSchema>;
+
+// ============================================================================
+// Headers-Shapes — event.metadata.headers (open-shape jsonb, primitives
+// only). Idempotency-Anchor: (providerName, providerMessageId).
+// ============================================================================
+export type InboundMessageEventHeaders = {
+  readonly providerMessageId: string;
+  readonly providerName: string;
+  /** Provider-Cursor-Snapshot zum Ingest-Zeitpunkt (UIDVALIDITY:UID,
+   *  deltaLink, historyId ...) — Debug/Replay-Hilfe, kein Payload. */
+  readonly providerCursor: string;
+};
+
+export type MailAccountEventHeaders = {
+  readonly providerName: string;
+  /** Was den Übergang ausgelöst hat ("connect_flow", "watch_supervisor",
+   *  "oauth_refresh", "tenant_admin"). */
+  readonly reason: string;
+};

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

@@ -0,0 +1,265 @@
+// kumiko-feature-version: 1
+//
+// inbound-mail-foundation — Plugin-Host für eingehende E-Mail
+// (Inbox-Föderation). Gegenstück zu mail-foundation (outbound): getrennte
+// Extension-Points, getrennter State — Architektur-Vorbild ist
+// file-foundation (Foundation besitzt State), nicht mail-transport.
+//
+// **Multi-Provider von Tag 1** (wie billing-foundation): KEIN globaler
+// `provider`-config-key. Ein Tenant verbindet parallel IMAP- und (später)
+// M365-/Gmail-Postfächer; der Provider steht pro MailAccount.
+//
+// **Was diese Foundation liefert:**
+//   1. **Plugin-API** für Inbound-Provider via r.extendsRegistrar
+//      ("inboundMailProvider"): verify/fetch/oauth?/watch? (types.ts).
+//   2. **3 event-sourced Streams** — mail-account (Lifecycle),
+//      inbound-message (genau EIN received-Event pro Mail, deterministic
+//      aggregateId ⇒ exactly-once trotz at-least-once-Ingest),
+//      mail-thread (Rollup). Volle Historie replay-fähig für spätere
+//      Consumer (Business-Prozesse: Ticket, Beleg, Auto-Antwort).
+//   3. **Inline-Projections** auf read_mail_accounts /
+//      read_inbound_messages / read_mail_threads (read-your-own-write).
+//   4. **Write-/Query-Handler**: connect/update/disconnect-account,
+//      ingest-message (programmatic, SystemAdmin), account:list +
+//      message:list (PII-decrypted, scope-gefiltert).
+//   5. **createInboundMailConnectRoutes**: OAuth-Connect + anonymer
+//      Callback (außerhalb /api/*), state HMAC-signiert.
+//   6. **createInboundMailSupervisor**: app-verdrahteter Watch-(IDLE)-
+//      Supervisor mit Backoff + Reconciliation-Poll.
+//
+// **Was diese Foundation NICHT macht:**
+//   - Keine Business-Semantik (Intent, Ticket, Zuweisung, gelesen/
+//     erledigt) — das gehört dem App-Consumer (z.B. via Event-Job auf
+//     inbound-message-received + eigener Projection).
+//   - Kein Body-Blob im Event-Store: rawMime → file-foundation via
+//     Supervisor-storeBody-Hook, Event trägt nur bodyRef.
+//   - Kein IMAP-Flag-Write-back (V1) — Inbox-Status lebt beim Consumer.
+//
+// **PII/GDPR:** address/from/to/cc/subject/snippet are `personal: "tenant"`
+// — encrypted BEFORE every event append (the only write path), event log AND
+// projections carry ciphertext; tenant-destroy shreds the subject key
+// (crypto-shredding, same pattern as billing-foundation #800). The destroy
+// hook additionally archives all streams + deletes the rows.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature, EXT_TENANT_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createFileProviderForTenant,
+  type FileStorageProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION } from "./constants.js";
+import {
+  inboundMessageEntity,
+  mailAccountEntity,
+  mailThreadEntity,
+  seenMessageTable,
+  syncCursorTable,
+} from "./entities.js";
+import {
+  INBOUND_MESSAGE_AGGREGATE_TYPE,
+  INBOUND_MESSAGE_RECEIVED_EVENT_QN,
+  INBOUND_MESSAGE_RECEIVED_EVENT_SHORT,
+  inboundMessageEventPayloadSchema,
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_CONNECTED_EVENT_QN,
+  MAIL_ACCOUNT_CONNECTED_EVENT_SHORT,
+  MAIL_ACCOUNT_DISCONNECTED_EVENT_QN,
+  MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT,
+  MAIL_ACCOUNT_UPDATED_EVENT_QN,
+  MAIL_ACCOUNT_UPDATED_EVENT_SHORT,
+  MAIL_THREAD_AGGREGATE_TYPE,
+  MAIL_THREAD_UPDATED_EVENT_QN,
+  MAIL_THREAD_UPDATED_EVENT_SHORT,
+  mailAccountEventPayloadSchema,
+  mailThreadEventPayloadSchema,
+} from "./events.js";
+import { connectAccountHandler } from "./handlers/connect-account.write.js";
+import { disconnectAccountHandler } from "./handlers/disconnect-account.write.js";
+import { ingestMessageHandler } from "./handlers/ingest-message.write.js";
+import { listAccountsQuery } from "./handlers/list-accounts.query.js";
+import { listMessagesQuery } from "./handlers/list-messages.query.js";
+import { updateAccountHandler } from "./handlers/update-account.write.js";
+import {
+  applyInboundMessageReceived,
+  applyMailAccountConnected,
+  applyMailAccountDisconnected,
+  applyMailAccountUpdated,
+  applyMailThreadUpdated,
+  inboundMessagesProjectionTable,
+  mailAccountsProjectionTable,
+  mailThreadsProjectionTable,
+} from "./projection.js";
+import { runInboundMailRetention } from "./retention-sweep.js";
+import {
+  INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON,
+  inboundMessageTenantDestroyHook,
+  mailAccountTenantDestroyHook,
+  mailThreadTenantDestroyHook,
+} from "./tenant-destroy-hook.js";
+
+export const inboundMailFoundationFeature = defineFeature(INBOUND_MAIL_FOUNDATION_FEATURE, (r) => {
+  r.describe(
+    "Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.",
+  );
+  r.uiHints({
+    displayLabel: "Inbound Mail · Foundation",
+    category: "notifications",
+    recommended: false,
+  });
+  // EXT_TENANT_DATA-Hook braucht den tenant-lifecycle-Host.
+  r.requires("tenant-lifecycle");
+
+  // 5 fine-grained domain-events (Payload-Schemas: events.ts).
+  // piiFields: "none" — address/subject/snippet are already ciphertext under the tenant subject key before append (see events.ts).
+  // "displayName" stays plaintext (often the mailbox owner's real name for
+  // personal accounts); encrypting it would break the entity-projection read
+  // path that carries it as `personal: false`.
+  r.defineEvent(MAIL_ACCOUNT_CONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema, {
+    piiFields: "none",
+  });
+  r.defineEvent(MAIL_ACCOUNT_UPDATED_EVENT_SHORT, mailAccountEventPayloadSchema, {
+    piiFields: "none",
+  });
+  r.defineEvent(MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema, {
+    piiFields: "none",
+  });
+  r.defineEvent(INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, inboundMessageEventPayloadSchema, {
+    piiFields: "none",
+  });
+  r.defineEvent(MAIL_THREAD_UPDATED_EVENT_SHORT, mailThreadEventPayloadSchema, {
+    piiFields: "none",
+  });
+
+  // Inline projections — apply in derselben TX wie der Append.
+  r.projection({
+    name: "mail-account",
+    source: MAIL_ACCOUNT_AGGREGATE_TYPE,
+    table: mailAccountsProjectionTable,
+    entity: mailAccountEntity,
+    apply: {
+      [MAIL_ACCOUNT_CONNECTED_EVENT_QN]: applyMailAccountConnected,
+      [MAIL_ACCOUNT_UPDATED_EVENT_QN]: applyMailAccountUpdated,
+      [MAIL_ACCOUNT_DISCONNECTED_EVENT_QN]: applyMailAccountDisconnected,
+    },
+  });
+  r.projection({
+    name: "inbound-message",
+    source: INBOUND_MESSAGE_AGGREGATE_TYPE,
+    table: inboundMessagesProjectionTable,
+    entity: inboundMessageEntity,
+    apply: {
+      [INBOUND_MESSAGE_RECEIVED_EVENT_QN]: applyInboundMessageReceived,
+    },
+  });
+  r.projection({
+    name: "mail-thread",
+    source: MAIL_THREAD_AGGREGATE_TYPE,
+    table: mailThreadsProjectionTable,
+    entity: mailThreadEntity,
+    apply: {
+      [MAIL_THREAD_UPDATED_EVENT_QN]: applyMailThreadUpdated,
+    },
+  });
+
+  // Plugin extension-point — Provider registrieren sich via
+  // r.useExtension("inboundMailProvider", "<key>", plugin).
+  r.extendsRegistrar(INBOUND_MAIL_PROVIDER_EXTENSION, {
+    onRegister: () => {
+      // No side-effects at register-time — Lookup läuft zur Laufzeit
+      // über resolveInboundProviderForKey/-Account.
+    },
+  });
+
+  // Sync-Maschinerie: hochfrequenter Tick-State, bewusst NICHT
+  // event-sourced — r.storeTable hält die Migration-DDL, nimmt die
+  // Tabellen aber aus dem Projection-Rebuild (#494/#498-Klasse).
+  r.storeTable(syncCursorTable, {
+    reason: "read_side.mail_sync_cursors_direct_write",
+  });
+  r.storeTable(seenMessageTable, {
+    reason: "read_side.mail_seen_messages_direct_write",
+  });
+
+  // Write-Handler:
+  //   - ingest-message: programmatic (Supervisor/Poll, SystemAdmin)
+  //   - connect/update/disconnect-account: Lifecycle
+  r.writeHandler(ingestMessageHandler);
+  r.writeHandler(connectAccountHandler);
+  r.writeHandler(updateAccountHandler);
+  r.writeHandler(disconnectAccountHandler);
+
+  // List-Queries (PII-decrypted, scope-gefiltert).
+  r.queryHandler(listAccountsQuery);
+  r.queryHandler(listMessagesQuery);
+
+  // Entity-genaue GDPR-Destroy-Hooks — der gdpr-storage-Boot-Validator
+  // prueft die EXT_TENANT_DATA-Registrierung pro tenant-subject-Entity.
+  r.useExtension(EXT_TENANT_DATA, "mail-account", {
+    destroy: mailAccountTenantDestroyHook,
+    escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
+  });
+  r.useExtension(EXT_TENANT_DATA, "inbound-message", {
+    destroy: inboundMessageTenantDestroyHook,
+    escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
+  });
+  r.useExtension(EXT_TENANT_DATA, "mail-thread", {
+    destroy: mailThreadTenantDestroyHook,
+    escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
+  });
+
+  // Data-Retention (#957) — perTenant fan-out (one run per tenant, like
+  // data-retention:retention-cleanup): runInboundMailRetention's raw query
+  // helpers need the unfiltered runner, so the handler declares escapeHatch
+  // and reaches for ctx.db.unsafeRaw(). Without this cron, read_inbound_messages
+  // + the bodies grow unbounded (GDPR Art. 5).
+  const INBOUND_MAIL_RETENTION_REASON =
+    "inbound-mail retention runs raw deletes; every statement filters by this run's tenantId";
+  r.job({
+    name: "inbound-mail-retention",
+    trigger: { cron: "0 3 * * *" },
+    perTenant: true,
+    concurrency: "skip",
+    escapeHatch: { reason: INBOUND_MAIL_RETENTION_REASON },
+    handler: async (_payload, ctx) => {
+      if (!ctx.registry) {
+        throw new Error("inbound-mail-retention: ctx.registry required (JobContext incomplete)");
+      }
+      const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+      if (tenantId === undefined) {
+        // skip: cron fired without a perTenant fan-out tenant — nothing scoped
+        return;
+      }
+      const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
+      const retentionDb = ctx.db.unsafeRaw(INBOUND_MAIL_RETENTION_REASON) as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+
+      // Body-Objekte liegen in file-foundation. Provider lazy + memoized —
+      // heute schreibt der Ingest kein bodyRef (storeBody-Hook ungebunden),
+      // der Provider wird also nie gebaut. Sobald storeBody wired ist, raeumt
+      // die Retention die Bodies mit ab.
+      let providerPromise: Promise<FileStorageProvider> | null = null;
+      const deleteBodyObject = async (bodyRef: string): Promise<void> => {
+        if (!providerPromise) {
+          providerPromise = createFileProviderForTenant(
+            { config: ctx.config, registry: ctx.registry },
+            tenantId,
+          );
+        }
+        const provider = await providerPromise;
+        await provider.delete(bodyRef);
+      };
+
+      const report = await runInboundMailRetention({
+        db: retentionDb,
+        tenantId,
+        now: T.Now.instant(),
+        deleteBodyObject,
+      });
+      if (report.bodyObjectErrors > 0) {
+        // biome-ignore lint/suspicious/noConsole: operator-visibility for failed body deletes
+        console.warn(
+          `[inbound-mail-foundation:inbound-mail-retention] tenant=${tenantId} bodyObjectErrors=${report.bodyObjectErrors}`,
+        );
+      }
+    },
+  });
+});

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

@@ -0,0 +1,23 @@
+// Geteilter State-Loader für update-account / disconnect-account.
+//
+// Die mail-account-Events sind full-snapshots (Muster billing-foundation:
+// "Alle nutzen denselben payload-shape, der event-type taggt was
+// passiert ist") — ein Übergangs-Handler lädt den letzten Snapshot,
+// merged seine Delta-Felder rein und appendet den neuen Snapshot.
+//
+// **PII-Disziplin:** `address` steht im geladenen Payload bereits als
+// Ciphertext und wird 1:1 durchkopiert — NIE re-encrypten (würde bei
+// fehlendem KMS decrypt erzwingen bzw. Double-Encryption produzieren).
+
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { MailAccountEventPayload } from "../events.js";
+
+export async function loadCurrentMailAccountPayload(
+  ctx: Pick<HandlerContext, "loadAggregate">,
+  accountId: string,
+): Promise<MailAccountEventPayload | undefined> {
+  const events = await ctx.loadAggregate(accountId);
+  const last = events[events.length - 1];
+  // @cast-boundary engine-payload — eigene events, shape via defineEvent
+  return last?.payload as MailAccountEventPayload | undefined;
+}

package/packages/bundled-features/src/inbound-mail-foundation/handlers/connect-account.write.ts

@@ -0,0 +1,118 @@
+// connect-account — Tenant-Admin verbindet ein Postfach. Legt den
+// mail-account-Stream an (aggregateId = random uuid = accountId =
+// Secret-Slot-Key für IMAP-Passwort/OAuth-Refresh-Token).
+//
+// **Was hier NICHT passiert:**
+//   - Kein Secret-Write: IMAP-Credentials laufen über den secrets-Pfad,
+//     OAuth-Tokens über die generischen /inbound-mail/oauth-Routen —
+//     beides VOR bzw. NACH diesem Call, nie durch den Handler-Payload
+//     (Plain-Passwörter gehören nicht in einen Write-Payload, der im
+//     Dispatcher-Log landen kann).
+//   - Kein Verbindungs-Test: der Watch-Supervisor probiert den ersten
+//     fetch und schaltet bei Fehler via update-account auf auth_error —
+//     der Connect bleibt schnell und offline-fähig (Test-Ergebnis kommt
+//     asynchron als Status-Übergang).
+
+import {
+  configuredPiiSubjectKms,
+  encryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { InboundMailAccountStatuses, InboundMailAuthMethods } from "../constants.js";
+import { MAIL_ACCOUNT_PII_FIELDS, mailAccountEntity } from "../entities.js";
+import {
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_CONNECTED_EVENT_QN,
+  type MailAccountEventHeaders,
+  type MailAccountEventPayload,
+} from "../events.js";
+
+export const connectAccountSchema = z.object({
+  /** Provider-Key wie an der Extension registriert ("imap",
+   *  "m365-graph", "gmail-rest"). */
+  provider: z.string().min(1).max(50),
+  authMethod: z.enum([
+    InboundMailAuthMethods.password,
+    InboundMailAuthMethods.xoauth2,
+    InboundMailAuthMethods.oauth,
+  ]),
+  displayName: z.string().max(200),
+  /** Postfach-Adresse, Plaintext — wird hier encrypted. */
+  address: z.string().min(1).max(320),
+  /** "shared" = tenant-geteilt (info@) · "user" = persönliches Postfach
+   *  des Callers (ownerUserId wird aus der Session gezogen, nie aus dem
+   *  Payload — kein Fremd-Claiming). */
+  scope: z.enum(["shared", "user"]),
+  /** NUR für den programmatic OAuth-Callback-Pfad (SystemAdmin): dort
+   *  ist der Dispatcher-User ein SystemUser, der echte Owner steht im
+   *  HMAC-verifizierten state. Tenant-Caller dürfen das Feld nicht
+   *  setzen (Fremd-Claiming-Sperre im Handler). */
+  ownerUserIdOverride: z.string().max(36).nullable().optional(),
+});
+type ConnectAccountPayload = z.infer<typeof connectAccountSchema>;
+
+export const connectAccountHandler: WriteHandlerDef = {
+  name: "connect-account",
+  schema: connectAccountSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  description:
+    "Registers a mailbox for the tenant (provider, auth method, display name, encrypted address, shared or personal) and returns the new accountId that also keys its credential slot; use it to start a mail connection, credentials and the first connection test happen outside this call.",
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = event.payload as ConnectAccountPayload;
+    const tenantId = event.user.tenantId;
+    const accountId = crypto.randomUUID();
+
+    if (payload.ownerUserIdOverride !== undefined && !event.user.roles.includes("SystemAdmin")) {
+      return failUnprocessable("owner_override_requires_system_admin");
+    }
+    const ownerUserId =
+      payload.ownerUserIdOverride !== undefined
+        ? payload.ownerUserIdOverride
+        : payload.scope === "user"
+          ? event.user.id
+          : null;
+
+    // PII-Encrypt der Adresse vor dem append — einziger Write-Pfad auf
+    // den Stream, deckt Event-Log UND Projection ab (#800-Muster).
+    const piiKms = configuredPiiSubjectKms();
+    const plainPii = { tenantId, address: payload.address };
+    const encryptedFields = piiKms
+      ? await encryptPiiFieldValues(
+          plainPii,
+          mailAccountEntity,
+          MAIL_ACCOUNT_PII_FIELDS,
+          piiKms,
+          { requestId: `inbound-mail-foundation:connect-account:${accountId}`, tenantId },
+          { tenantId, entityName: MAIL_ACCOUNT_AGGREGATE_TYPE },
+        )
+      : plainPii;
+
+    const eventPayload: MailAccountEventPayload = {
+      provider: payload.provider,
+      authMethod: payload.authMethod,
+      ownerUserId,
+      displayName: payload.displayName,
+      address: encryptedFields["address"] as string,
+      // active ab Connect — der Supervisor greift den Account beim
+      // nächsten Tick auf und degradiert ihn bei Credential-Fehlern.
+      status: InboundMailAccountStatuses.active,
+      watchState: "idle",
+    };
+    const headers: MailAccountEventHeaders = {
+      providerName: payload.provider,
+      reason: "connect_flow",
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: accountId,
+      aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
+      type: MAIL_ACCOUNT_CONNECTED_EVENT_QN,
+      payload: eventPayload,
+      headers,
+    });
+
+    return { isSuccess: true as const, data: { accountId } };
+  },
+};

package/packages/bundled-features/src/inbound-mail-foundation/handlers/disconnect-account.write.ts

@@ -0,0 +1,72 @@
+// disconnect-account — Tenant-Admin trennt ein Postfach. Stream bleibt
+// (Audit-Historie), Status wird disconnected, der Watch-Supervisor
+// überspringt den Account ab dem nächsten Tick. Secret-Cleanup (IMAP-
+// Passwort/Refresh-Token im Slot accountId) macht der Aufrufer-Flow —
+// der Handler fasst den secrets-Pfad nicht an.
+//
+// Idempotent: disconnect auf bereits disconnected Account ist ein
+// success-no-op (kein zweites Event) — Doppelklick-/Retry-freundlich.
+
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { InboundMailAccountStatuses } from "../constants.js";
+import {
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_DISCONNECTED_EVENT_QN,
+  type MailAccountEventHeaders,
+  type MailAccountEventPayload,
+} from "../events.js";
+import { loadCurrentMailAccountPayload } from "./account-state.js";
+
+export const disconnectAccountSchema = z.object({
+  accountId: z.uuid(),
+  reason: z.string().min(1).max(100).default("tenant_admin"),
+});
+type DisconnectAccountPayload = z.infer<typeof disconnectAccountSchema>;
+
+export const disconnectAccountHandler: WriteHandlerDef = {
+  name: "disconnect-account",
+  schema: disconnectAccountSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  description:
+    "Puts a connected mailbox into the final disconnected state so the watch supervisor stops fetching it, keeping the stream for audit and requiring a fresh connect to resume; use it to stop mail ingestion for one mailbox.",
+  agent: { risk: "high" },
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = event.payload as DisconnectAccountPayload;
+
+    const current = await loadCurrentMailAccountPayload(ctx, payload.accountId);
+    if (!current) {
+      return failNotFound("mail-account", payload.accountId);
+    }
+    if (current.status === InboundMailAccountStatuses.disconnected) {
+      return {
+        isSuccess: true as const,
+        data: { accountId: payload.accountId, alreadyDisconnected: true as const },
+      };
+    }
+
+    const eventPayload: MailAccountEventPayload = {
+      ...current,
+      status: InboundMailAccountStatuses.disconnected,
+      watchState: "idle",
+    };
+    const headers: MailAccountEventHeaders = {
+      providerName: current.provider,
+      reason: payload.reason,
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: payload.accountId,
+      aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
+      type: MAIL_ACCOUNT_DISCONNECTED_EVENT_QN,
+      payload: eventPayload,
+      headers,
+    });
+
+    return {
+      isSuccess: true as const,
+      data: { accountId: payload.accountId, alreadyDisconnected: false as const },
+    };
+  },
+};