@cosmicdrift/kumiko-bundled-features 0.141.0 → 0.142.0

package/src/inbound-mail-foundation/connect-routes.ts

@@ -0,0 +1,230 @@
+// createInboundMailConnectRoutes — Hono-Route-Factory die der App-Owner
+// via `extraRoutes` in seinem bin/server.ts mountet (Muster
+// billing-foundation/webhook-handler.ts).
+//
+//   GET /inbound-mail/connect          (auth-gated — im authed Bereich mounten)
+//   GET /inbound-mail/oauth/callback   (anonymous — MUSS außerhalb /api/*
+//                                       liegen, /api ist auth-gated;
+//                                       verifiziert user-data-rights §5)
+//
+// Beispiel bin/server.ts:
+//
+//   const routes = createInboundMailConnectRoutes({
+//     providerCtx: { registry: deps.registry, secrets, config: undefined },
+//     dispatchWrite: ({ handlerQn, payload, tenantId }) =>
+//       deps.dispatchSystemWrite({ handlerQn, payload, tenantId: tenantId as TenantId }),
+//     secrets,
+//     stateSecret: env.INBOUND_MAIL_STATE_SECRET,
+//     callbackUrl: `${env.PUBLIC_BASE_URL}/inbound-mail/oauth/callback`,
+//   });
+//   app.get("/api/inbound-mail/connect", routes.connect);      // auth-gated
+//   app.get("/inbound-mail/oauth/callback", routes.callback);  // anonymous
+//
+// Provider registrieren KEINE eigenen Routen — ihr oauth-Block wird über
+// resolveInboundProviderForKey aufgelöst. Der Callback vertraut NUR dem
+// HMAC-verifizierten state (CSRF-/Fremd-Claiming-Sperre, oauth-state.ts).
+
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { Context } from "hono";
+import {
+  INBOUND_MAIL_FOUNDATION_FEATURE,
+  InboundMailAuthMethods,
+  InboundMailFoundationHandlers,
+  inboundCredentialSecretKey,
+} from "./constants";
+import { signOAuthState, verifyOAuthState } from "./oauth-state";
+import { resolveInboundProviderForKey } from "./provider-factory";
+import type { InboundMailContext } from "./types";
+
+const DEFAULT_STATE_TTL_MINUTES = 15;
+
+export type InboundMailConnectRoutesDeps = {
+  /** Slim-Context für Provider-Lookups + oauth-Calls (registry Pflicht). */
+  readonly providerCtx: InboundMailContext;
+  /** Schreibt durch den Standard-Dispatcher mit auto-konstruiertem
+   *  SystemUser — muss connect-account als SystemAdmin durchlassen. */
+  readonly dispatchWrite: (args: {
+    readonly handlerQn: string;
+    readonly payload: unknown;
+    readonly tenantId: string;
+  }) => Promise<{
+    readonly isSuccess: boolean;
+    readonly data?: unknown;
+    readonly error?: unknown;
+  }>;
+  /** Tenant-Secret-Write für den Refresh-Token (Slot = accountId). */
+  readonly secrets: SecretsContext;
+  /** HMAC-Secret für den state-Parameter (Deploy-Config aus env —
+   *  `scope:"system"`-Secrets existieren in secrets-v1 nicht). */
+  readonly stateSecret: string;
+  /** Absolute Callback-URL — exakt so beim OAuth-Provider registriert. */
+  readonly callbackUrl: string;
+  /** Wohin der Browser nach erfolgreichem Connect redirected wird.
+   *  Fehlt sie, antwortet der Callback mit JSON (API-/Test-Modus). */
+  readonly successRedirectUrl?: string;
+  readonly stateTtlMinutes?: number;
+};
+
+function errorJson(c: Context, status: 400 | 401 | 404 | 502, code: string, message: string) {
+  return c.json({ error: { code, message } }, status);
+}
+
+/** Session-User aus dem Hono-Context — vom Auth-Middleware gesetzt. */
+function sessionUserOf(c: Context): { id: string; tenantId: string } | undefined {
+  const user = c.get("user") as { id?: unknown; tenantId?: unknown } | undefined;
+  if (!user || typeof user.id !== "string" || typeof user.tenantId !== "string") return undefined;
+  return { id: user.id, tenantId: user.tenantId };
+}
+
+export function createInboundMailConnectRoutes(deps: InboundMailConnectRoutesDeps) {
+  const ttl = deps.stateTtlMinutes ?? DEFAULT_STATE_TTL_MINUTES;
+
+  const connect = async (c: Context): Promise<Response> => {
+    const user = sessionUserOf(c);
+    if (!user) {
+      return errorJson(c, 401, "unauthenticated", "connect requires a signed-in user");
+    }
+    const providerKey = c.req.query("provider") ?? "";
+    const scope = c.req.query("scope") ?? "";
+    const mailbox = c.req.query("mailbox") ?? "";
+    if (!providerKey || (scope !== "user" && scope !== "shared") || !mailbox) {
+      return errorJson(
+        c,
+        400,
+        "invalid_connect_request",
+        `${INBOUND_MAIL_FOUNDATION_FEATURE}: expected ?provider=<key>&scope=user|shared&mailbox=<address>`,
+      );
+    }
+
+    let plugin: ReturnType<typeof resolveInboundProviderForKey>;
+    try {
+      plugin = resolveInboundProviderForKey(deps.providerCtx, providerKey);
+    } catch (e) {
+      return errorJson(
+        c,
+        404,
+        "provider_not_registered",
+        e instanceof Error ? e.message : String(e),
+      );
+    }
+    if (!plugin.oauth) {
+      return errorJson(
+        c,
+        400,
+        "provider_has_no_oauth_flow",
+        `provider "${providerKey}" connects via credentials form (connect-account write-handler), not OAuth`,
+      );
+    }
+
+    const state = signOAuthState(
+      {
+        tenantId: user.tenantId,
+        ownerUserId: scope === "user" ? user.id : null,
+        providerKey,
+        mailbox,
+      },
+      ttl,
+      deps.stateSecret,
+    );
+    const authorizeUrl = await plugin.oauth.buildAuthorizeUrl(deps.providerCtx, {
+      state,
+      redirectUri: deps.callbackUrl,
+    });
+    return c.redirect(authorizeUrl, 302);
+  };
+
+  const callback = async (c: Context): Promise<Response> => {
+    const code = c.req.query("code") ?? "";
+    const rawState = c.req.query("state") ?? "";
+    if (!code || !rawState) {
+      return errorJson(c, 400, "invalid_callback", "missing code or state");
+    }
+    const verified = verifyOAuthState(rawState, deps.stateSecret);
+    if (!verified.ok) {
+      return errorJson(c, 400, "invalid_state", `state rejected: ${verified.reason}`);
+    }
+    const state = verified.payload;
+
+    let plugin: ReturnType<typeof resolveInboundProviderForKey>;
+    try {
+      plugin = resolveInboundProviderForKey(deps.providerCtx, state.providerKey);
+    } catch (e) {
+      return errorJson(
+        c,
+        404,
+        "provider_not_registered",
+        e instanceof Error ? e.message : String(e),
+      );
+    }
+    if (!plugin.oauth) {
+      return errorJson(c, 400, "provider_has_no_oauth_flow", state.providerKey);
+    }
+
+    let tokens: Awaited<ReturnType<NonNullable<typeof plugin.oauth>["exchangeCode"]>>;
+    try {
+      tokens = await plugin.oauth.exchangeCode(deps.providerCtx, {
+        code,
+        redirectUri: deps.callbackUrl,
+      });
+    } catch (e) {
+      return errorJson(c, 502, "token_exchange_failed", e instanceof Error ? e.message : String(e));
+    }
+    if (!tokens.refreshToken) {
+      // Ohne Refresh-Token kein Server-Sync — Consent muss offline_access
+      // (bzw. access_type=offline) anfordern; der Provider-oauth-Block
+      // besitzt die Scopes.
+      return errorJson(
+        c,
+        502,
+        "no_refresh_token",
+        `provider "${state.providerKey}" returned no refresh token — check the offline-access scope in the provider's oauth.scopes`,
+      );
+    }
+
+    // Account anlegen (programmatic SystemUser; echter Owner kommt aus
+    // dem HMAC-verifizierten state → ownerUserIdOverride).
+    const dispatched = await deps.dispatchWrite({
+      handlerQn: InboundMailFoundationHandlers.connectAccount,
+      tenantId: state.tenantId,
+      payload: {
+        provider: state.providerKey,
+        authMethod: InboundMailAuthMethods.oauth,
+        displayName: state.mailbox,
+        address: state.mailbox,
+        scope: state.ownerUserId ? "user" : "shared",
+        ownerUserIdOverride: state.ownerUserId,
+      },
+    });
+    if (!dispatched.isSuccess) {
+      return errorJson(c, 502, "account_create_failed", JSON.stringify(dispatched.error ?? {}));
+    }
+    const accountId = (dispatched.data as { accountId?: unknown } | undefined)?.accountId;
+    if (typeof accountId !== "string") {
+      return errorJson(c, 502, "account_create_failed", "connect-account returned no accountId");
+    }
+
+    // Refresh-Token in den per-Account-Secret-Slot (Request-Pfad =
+    // voller SecretsContext). Access-Tokens (~1h) werden NIE persistiert
+    // — refresh-before-poll im Sync-Pfad.
+    await deps.secrets.set(
+      state.tenantId,
+      inboundCredentialSecretKey(accountId),
+      tokens.refreshToken,
+      {
+        redact: (plaintext) => `${plaintext.slice(0, 4)}…`,
+        hint: `OAuth refresh token for inbound mail account ${accountId}`,
+      },
+    );
+
+    if (deps.successRedirectUrl) {
+      const target = new URL(deps.successRedirectUrl);
+      target.searchParams.set("accountId", accountId);
+      return c.redirect(target.toString(), 302);
+    }
+    return c.json({ connected: true, accountId }, 200);
+  };
+
+  return { connect, callback };
+}
+
+export type InboundMailConnectRoutes = ReturnType<typeof createInboundMailConnectRoutes>;

package/src/inbound-mail-foundation/constants.ts

@@ -0,0 +1,80 @@
+// Feature name
+export const INBOUND_MAIL_FOUNDATION_FEATURE = "inbound-mail-foundation" as const;
+
+// Extension-point name für Provider-Plugins (inbound-provider-imap,
+// inbound-provider-m365-graph, inbound-provider-gmail-rest, ...).
+export const INBOUND_MAIL_PROVIDER_EXTENSION = "inboundMailProvider" as const;
+
+// Qualified write handler names (QN format: scope:type:name).
+export const InboundMailFoundationHandlers = {
+  /** Programmatic entry-point für Provider-Plugins (watch-callback +
+   *  fetchSince-Sync): normalisierte Message rein, Idempotency +
+   *  PII-encrypt + event-append + Thread-Update atomic. */
+  ingestMessage: "inbound-mail-foundation:write:ingest-message",
+  /** Tenant-Admin verbindet ein Postfach (IMAP-Credentials via secrets
+   *  oder OAuth-Redirect via oauth-routes). Legt den mail-account-Stream
+   *  an. */
+  connectAccount: "inbound-mail-foundation:write:connect-account",
+  /** Account-Status-Übergänge (watch error/backoff, oauth-refresh
+   *  failed, re-enabled). */
+  updateAccount: "inbound-mail-foundation:write:update-account",
+  /** Tenant-Admin trennt ein Postfach. Stream bleibt (Audit), Status
+   *  wird disconnected, Watch stoppt. */
+  disconnectAccount: "inbound-mail-foundation:write:disconnect-account",
+} as const;
+
+// Qualified query handler names.
+export const InboundMailFoundationQueries = {
+  /** Tenant-scoped Liste der verbundenen Postfächer. */
+  listAccounts: "inbound-mail-foundation:query:account:list",
+  /** Tenant-scoped Message-Liste (Inbox-Cockpit). PII wird beim Read
+   *  decrypted. */
+  listMessages: "inbound-mail-foundation:query:message:list",
+} as const;
+
+// Normalized account status values — provider-agnostic.
+export const InboundMailAccountStatuses = {
+  /** Verbunden, Watch/Sync läuft (oder ist startbereit). */
+  active: "active",
+  /** Credentials/Token ungültig — Tenant-Admin muss re-connecten. */
+  authError: "auth_error",
+  /** Transienter Fehler, Supervisor backoff-retried. */
+  degraded: "degraded",
+  /** Vom Tenant-Admin getrennt. Keine Syncs mehr. */
+  disconnected: "disconnected",
+} as const;
+export type InboundMailAccountStatus =
+  (typeof InboundMailAccountStatuses)[keyof typeof InboundMailAccountStatuses];
+
+/**
+ * Tenant-Secret-Slot eines Accounts: IMAP-App-Passwort ODER OAuth-
+ * Refresh-Token — der Provider interpretiert den Inhalt gemäß
+ * `authMethod` (Plan §4). Dynamisches Keying pro Account ist vom
+ * secrets-Feature gedeckt: SecretsContext.get/set nehmen beliebige
+ * String-Keys (resolveKey in secrets-context.ts) — Plan-Risiko 4
+ * verifiziert, kein Framework-Gap.
+ */
+export function inboundCredentialSecretKey(accountId: string): string {
+  return `${INBOUND_MAIL_FOUNDATION_FEATURE}:inbound.credential.${accountId}`;
+}
+
+// Auth-Methode eines Accounts — vom connect-Flow gesetzt, von Providern
+// gelesen (imap unterscheidet hierüber Passwort-Formular vs. XOAUTH2-
+// Fallback, Plan §2).
+export const InboundMailAuthMethods = {
+  /** Formular-Connect: Config (host/port/secure) + Tenant-Secret. */
+  password: "password",
+  /** SASL XOAUTH2 über IMAP — Fallback für M365/Gmail-Konten ohne
+   *  gemounteten Enterprise-Provider (gleicher Secret-Slot). */
+  xoauth2: "xoauth2",
+  /** Nativer OAuth-Provider (m365-graph, gmail-rest). */
+  oauth: "oauth",
+} as const;
+export type InboundMailAuthMethod =
+  (typeof InboundMailAuthMethods)[keyof typeof InboundMailAuthMethods];
+
+// **Multi-Provider von Tag 1:** KEIN globaler `provider`-config-key
+// (anders als mail-foundation, gleich wie billing-foundation). Ein Tenant
+// kann parallel ein IMAP-Postfach UND ein M365-Postfach verbinden — der
+// Provider steht pro MailAccount-Row (`provider`-Feld), gesetzt beim
+// connect-Flow.

package/src/inbound-mail-foundation/db/queries/inbound-projections.ts

@@ -0,0 +1,38 @@
+// Raw-SQL-Helper für die inline projections — Muster
+// billing-foundation/db/queries/subscription-projection.ts.
+//
+// Warum raw statt drizzle-insert: die apply-fns laufen in der event-TX
+// mit einem DbRunner, und die ON-CONFLICT-Semantik (UPSERT vs.
+// DO NOTHING) ist der fachliche Kern — explizit hingeschrieben statt
+// hinter einem ORM-Builder versteckt.
+
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+/** INSERT ... ON CONFLICT ("id") DO UPDATE SET <setClauses>. */
+export async function upsertProjectionRow(
+  tx: DbRunner,
+  tableName: string,
+  insertCols: Record<string, unknown>,
+  setClauses: readonly string[],
+  params: readonly unknown[],
+): Promise<void> {
+  const insertKeys = Object.keys(insertCols);
+  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
+  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO UPDATE SET ${setClauses.join(", ")}`;
+  await asRawClient(tx).unsafe(sqlText, params);
+}
+
+/** INSERT ... ON CONFLICT ("id") DO NOTHING — für append-only-Rows
+ *  (inbound-message: genau EIN received-event pro Stream, Replays
+ *  no-op'en auf der PK). */
+export async function insertIgnoreProjectionRow(
+  tx: DbRunner,
+  tableName: string,
+  insertCols: Record<string, unknown>,
+): Promise<void> {
+  const insertKeys = Object.keys(insertCols);
+  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
+  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO NOTHING`;
+  await asRawClient(tx).unsafe(sqlText, Object.values(insertCols));
+}

package/src/inbound-mail-foundation/entities.ts

@@ -0,0 +1,168 @@
+import { collectPiiSubjectFields } from "@cosmicdrift/kumiko-framework/crypto";
+import { buildEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createEntity,
+  createNumberField,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// ============================================================================
+// Read-Models der drei event-sourced Aggregates
+// ============================================================================
+//
+// Inline-Projection-Targets. Geschrieben AUSSCHLIESSLICH von den
+// projection-applies (siehe feature.ts), nie direkt vom handler.
+// Source-of-truth sind die event-store-Streams `mail-account` /
+// `inbound-message` / `mail-thread` — die Tabellen sind rebuild-fähig.
+//
+// **PII-Konvention:** tenantOwned (nicht `encrypted`): Felder müssen
+// crypto-shredden wenn eraseSubjectKeys den Tenant-Subject-Key beim
+// tenant-destroy löscht (#800-Muster aus billing-foundation).
+// maxLength jeweils Ciphertext-budgetiert (`kumiko-pii:v1:<subject>:
+// <blob>` — Plaintext×~2.3 + Envelope-Overhead).
+//
+// **Offene Design-Frage aus dem Plan (§3.4):** PII-Subject einer
+// Inbound-Mail ist vorerst der TENANT (Postfach-Inhaber), nicht der
+// externe Absender — ein Absender-Forget-Flow bräuchte per-Sender-Keys
+// und ist bewusst NICHT Teil von Phase 1 (dokumentierte Entscheidung,
+// Erasure-Pfad ist tenant-destroy).
+
+/** Ein verbundenes Postfach. Eine Row pro Account, PK = aggregateId
+ *  (= accountId, random uuid beim connect). */
+export const mailAccountEntity = createEntity({
+  table: "read_mail_accounts",
+  fields: {
+    provider: createTextField({ required: true, maxLength: 50 }),
+    authMethod: createTextField({ required: true, maxLength: 30 }),
+    // null = tenant-geteiltes Postfach (info@), gesetzt = persönliches
+    // Postfach dieses Users. Sichtbarkeits-Filter in den list-queries:
+    // Owner + TenantAdmin (Compliance); KEIN Crypto-Subject-Wechsel in
+    // V1 (Subject bleibt Tenant, siehe Header).
+    ownerUserId: createTextField({ maxLength: 36 }),
+    displayName: createTextField({ maxLength: 200 }),
+    // Postfach-Adresse — PII des Tenants.
+    address: createTextField({ required: true, maxLength: 1000, tenantOwned: true }),
+    status: createTextField({ required: true, maxLength: 30 }),
+    watchState: createTextField({ maxLength: 100 }),
+    connectedAt: createTimestampField({ required: true }),
+  },
+});
+
+/** Eine eingegangene Mail (Envelope + Snippet, KEIN Body — bodyRef
+ *  zeigt auf file-foundation). PK = aggregateId =
+ *  inboundMessageAggregateId(accountId, providerMessageId). */
+export const inboundMessageEntity = createEntity({
+  table: "read_inbound_messages",
+  fields: {
+    accountId: createTextField({ required: true, maxLength: 36 }),
+    // Scope-Vererbung vom Account zum Ingest-Zeitpunkt — Messages eines
+    // persönlichen Postfachs sind nur für den Owner (+ TenantAdmin)
+    // sichtbar, ohne Join auf read_mail_accounts.
+    ownerUserId: createTextField({ maxLength: 36 }),
+    messageIdHeader: createTextField({ required: true, maxLength: 500 }),
+    threadKey: createTextField({ required: true, maxLength: 500 }),
+    from: createTextField({ required: true, maxLength: 2000, tenantOwned: true }),
+    // JSON-stringified string[] — als Ganzes encrypted.
+    to: createTextField({ maxLength: 8000, tenantOwned: true }),
+    cc: createTextField({ maxLength: 8000, tenantOwned: true }),
+    subject: createTextField({ maxLength: 4000, tenantOwned: true }),
+    snippet: createTextField({ maxLength: 4000, tenantOwned: true }),
+    receivedAt: createTimestampField({ required: true }),
+    bodyRef: createTextField({ maxLength: 500 }),
+    scope: createTextField({ maxLength: 200 }),
+  },
+});
+
+/** Thread-Rollup. PK = aggregateId = mailThreadAggregateId(tenantId,
+ *  threadKey). */
+export const mailThreadEntity = createEntity({
+  table: "read_mail_threads",
+  fields: {
+    threadKey: createTextField({ required: true, maxLength: 500 }),
+    subject: createTextField({ maxLength: 4000, tenantOwned: true }),
+    lastMessageAt: createTimestampField({ required: true }),
+    messageCount: createNumberField({ required: true }),
+  },
+});
+
+// Single source of truth für die PII-Feld-Listen — encrypt (ingest/
+// connect-handler) und decrypt (list-queries) teilen dieselbe Liste,
+// damit ein künftiges weiteres tenantOwned-Feld nicht an einer der
+// Stellen vergessen wird (Muster billing-foundation entities.ts).
+export const MAIL_ACCOUNT_PII_FIELDS = collectPiiSubjectFields(mailAccountEntity);
+export const INBOUND_MESSAGE_PII_FIELDS = collectPiiSubjectFields(inboundMessageEntity);
+export const MAIL_THREAD_PII_FIELDS = collectPiiSubjectFields(mailThreadEntity);
+
+// ============================================================================
+// Unmanaged Direct-Write-Stores — Sync-Maschinerie, NICHT event-sourced
+// ============================================================================
+//
+// SyncCursor + SeenMessage sind technischer Tick-State des Watch/Sync-
+// Loops: hochfrequente Writes ohne Business-Fakt-Charakter. Als r.entity
+// würden sie (a) das Event-Log fluten und (b) beim Projection-Rebuild
+// gewischt (Direct-Write ohne Event → Rebuild findet nichts, #494/#498-
+// Klasse). Deshalb r.unmanagedTable — Migration-DDL ja, Rebuild-Target
+// nein (Muster sessions/feature.ts).
+
+/** Provider-Cursor pro Account ("wo war ich?"): IMAP UIDVALIDITY:UIDNEXT,
+ *  Graph deltaLink, Gmail historyId. Eine Row pro (accountId, scope).
+ *  Write-locked auf privileged — nur Foundation-Handler/Supervisor
+ *  schreiben, kein Tenant-Request. */
+export const syncCursorEntity = createEntity({
+  table: "read_mail_sync_cursors",
+  softDelete: false,
+  fields: {
+    accountId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+    }),
+    scope: createTextField({
+      required: true,
+      maxLength: 200,
+      access: { write: access.privileged },
+    }),
+    cursor: createTextField({
+      required: true,
+      maxLength: 2000,
+      access: { write: access.privileged },
+    }),
+    updatedAt: createTimestampField({
+      required: true,
+      access: { write: access.privileged },
+    }),
+  },
+});
+
+/** Dedup-Anchor für O(1)-Idempotency ohne Stream-Scan bei sehr langen
+ *  Message-Historien: (accountId, providerMessageId) UNIQUE. Der
+ *  ingest-handler prüft zuerst hier (cheap), der Stream-Scan bleibt
+ *  Defense-in-depth. */
+export const seenMessageEntity = createEntity({
+  table: "read_mail_seen_messages",
+  softDelete: false,
+  fields: {
+    accountId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+    }),
+    providerMessageId: createTextField({
+      required: true,
+      maxLength: 500,
+      access: { write: access.privileged },
+    }),
+    seenAt: createTimestampField({
+      required: true,
+      access: { write: access.privileged },
+    }),
+  },
+});
+
+// Plain EntityTableMeta (kein branded EntityTable) — unmanaged Direct-
+// Write-Stores, Handler schreiben via ctx.db (siehe user-session.ts-
+// Rationale).
+export const syncCursorTable = buildEntityTableMeta("mail-sync-cursor", syncCursorEntity);
+export const seenMessageTable = buildEntityTableMeta("mail-seen-message", seenMessageEntity);

package/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 { z } from "zod";
+import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAccountStatuses } from "./constants";
+
+// 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;
+};