@cosmicdrift/kumiko-bundled-features 0.141.0 → 0.142.0

package/src/inbound-mail-foundation/handlers/list-accounts.query.ts

@@ -0,0 +1,44 @@
+// list-accounts — tenant-scoped Liste der verbundenen Postfächer fürs
+// Connect-/Settings-UI. PII (address) wird beim Read decrypted (Muster
+// billing-foundation list-subscriptions).
+//
+// **Scope-Sichtbarkeit (Plan Entscheidung 2):** shared-Postfächer
+// (ownerUserId=null) sieht jeder Berechtigte; persönliche nur der Owner
+// selbst + TenantAdmin/SystemAdmin (Compliance-Sicht). Filter läuft
+// in-memory nach dem tenant-scoped select — Volumen ist die Anzahl
+// verbundener Postfächer eines Tenants (einstellig bis zweistellig).
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { MAIL_ACCOUNT_PII_FIELDS } from "../entities";
+import { mailAccountsProjectionTable } from "../projection";
+import { isVisibleToCaller } from "./scope-visibility";
+
+const listAccountsSchema = z.object({}).strict();
+
+export const listAccountsQuery: QueryHandlerDef = {
+  name: "account:list",
+  schema: listAccountsSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin", "User"] },
+  handler: async (_query, ctx) => {
+    const allRows = await selectMany(ctx.db.raw, mailAccountsProjectionTable, {
+      tenantId: ctx.user.tenantId,
+    });
+    const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));
+    const piiKms = configuredPiiSubjectKms();
+    if (!piiKms) return { rows };
+    const decryptedRows = await Promise.all(
+      rows.map((row) =>
+        decryptPiiFieldValues(row as Record<string, unknown>, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
+          requestId: `inbound-mail-foundation:list-accounts:${ctx.user.tenantId}`,
+        }),
+      ),
+    );
+    return { rows: decryptedRows };
+  },
+};

package/src/inbound-mail-foundation/handlers/list-messages.query.ts

@@ -0,0 +1,58 @@
+// list-messages — tenant-scoped Message-Liste (Inbox-Cockpit).
+// Optionale Filter: accountId (ein Postfach), threadKey (eine
+// Konversation), scope (Folder-Hint). PII (from/to/cc/subject/snippet)
+// wird beim Read decrypted; to/cc bleiben JSON-stringified strings —
+// der Client parsed sie (dokumentiert im Event-Payload).
+//
+// Bewusst KEINE Pagination in V1: die Projection ist tenant-scoped und
+// das Inbox-Cockpit lädt begrenzte Zeiträume; ein `limit`-Feld ist
+// vorwärtskompatibel ergänzbar ohne den QN zu brechen.
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { INBOUND_MESSAGE_PII_FIELDS } from "../entities";
+import { inboundMessagesProjectionTable } from "../projection";
+import { isVisibleToCaller } from "./scope-visibility";
+
+const listMessagesSchema = z
+  .object({
+    accountId: z.uuid().optional(),
+    threadKey: z.string().min(1).max(500).optional(),
+    scope: z.string().min(1).max(200).optional(),
+  })
+  .strict();
+type ListMessagesPayload = z.infer<typeof listMessagesSchema>;
+
+export const listMessagesQuery: QueryHandlerDef = {
+  name: "message:list",
+  schema: listMessagesSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin", "User"] },
+  handler: async (query, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = query.payload as ListMessagesPayload;
+    const filter: Record<string, unknown> = { tenantId: ctx.user.tenantId };
+    if (payload.accountId) filter["accountId"] = payload.accountId;
+    if (payload.threadKey) filter["threadKey"] = payload.threadKey;
+    if (payload.scope) filter["scope"] = payload.scope;
+
+    const allRows = await selectMany(ctx.db.raw, inboundMessagesProjectionTable, filter);
+    // Scope-Sichtbarkeit (Plan Entscheidung 2): Messages persönlicher
+    // Postfächer nur für Owner + TenantAdmin/SystemAdmin.
+    const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));
+    const piiKms = configuredPiiSubjectKms();
+    if (!piiKms) return { rows };
+    const decryptedRows = await Promise.all(
+      rows.map((row) =>
+        decryptPiiFieldValues(row as Record<string, unknown>, INBOUND_MESSAGE_PII_FIELDS, piiKms, {
+          requestId: `inbound-mail-foundation:list-messages:${ctx.user.tenantId}`,
+        }),
+      ),
+    );
+    return { rows: decryptedRows };
+  },
+};

package/src/inbound-mail-foundation/handlers/scope-visibility.ts

@@ -0,0 +1,14 @@
+// Scope-Sichtbarkeit (Plan Entscheidung 2): shared-Rows
+// (ownerUserId=null) sieht jeder Berechtigte; persönliche nur der Owner
+// selbst + TenantAdmin/SystemAdmin (Compliance-Sicht). Gilt identisch
+// für read_mail_accounts und read_inbound_messages (Scope-Vererbung).
+
+export function isVisibleToCaller(
+  row: unknown,
+  user: { readonly id: string; readonly roles: readonly string[] },
+): boolean {
+  const owner = (row as Record<string, unknown>)["ownerUserId"];
+  if (owner == null || owner === "") return true;
+  if (owner === user.id) return true;
+  return user.roles.includes("TenantAdmin") || user.roles.includes("SystemAdmin");
+}

package/src/inbound-mail-foundation/handlers/update-account.write.ts

@@ -0,0 +1,78 @@
+// update-account — Account-Status-Übergänge: Watch-Supervisor meldet
+// error/backoff, OAuth-Refresh scheitert (auth_error), Tenant-Admin
+// re-enabled nach Credential-Fix. Full-snapshot-Event: lädt den letzten
+// Stand, merged die Delta-Felder, appendet den neuen Snapshot.
+
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { InboundMailAccountStatuses } from "../constants";
+import {
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_UPDATED_EVENT_QN,
+  type MailAccountEventHeaders,
+  type MailAccountEventPayload,
+} from "../events";
+import { loadCurrentMailAccountPayload } from "./account-state";
+
+export const updateAccountSchema = z.object({
+  accountId: z.uuid(),
+  status: z
+    .enum([
+      InboundMailAccountStatuses.active,
+      InboundMailAccountStatuses.authError,
+      InboundMailAccountStatuses.degraded,
+    ])
+    .optional(),
+  /** Ops-Signal ("idle", "watching", "backoff:3", ...). */
+  watchState: z.string().max(100).optional(),
+  displayName: z.string().max(200).optional(),
+  /** Audit-Grund für metadata.headers ("watch_supervisor",
+   *  "oauth_refresh", "tenant_admin"). */
+  reason: z.string().min(1).max(100),
+});
+type UpdateAccountPayload = z.infer<typeof updateAccountSchema>;
+
+export const updateAccountHandler: WriteHandlerDef = {
+  name: "update-account",
+  schema: updateAccountSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = event.payload as UpdateAccountPayload;
+
+    const current = await loadCurrentMailAccountPayload(ctx, payload.accountId);
+    if (!current) {
+      return failNotFound("mail-account", payload.accountId);
+    }
+    if (current.status === InboundMailAccountStatuses.disconnected) {
+      // Getrennte Accounts sind final — Re-Enable läuft über einen
+      // frischen connect (neuer Stream, neuer Secret-Slot). Verhindert
+      // dass ein nachzügelnder Supervisor-Tick einen disconnected
+      // Account wieder auf active hebt (Race Disconnect vs. Poll).
+      return failUnprocessable("account_disconnected", { accountId: payload.accountId });
+    }
+
+    // Merge: address/provider/authMethod kommen 1:1 aus dem letzten
+    // Snapshot (address bleibt Ciphertext — nie re-encrypten).
+    const eventPayload: MailAccountEventPayload = {
+      ...current,
+      ...(payload.status !== undefined ? { status: payload.status } : {}),
+      ...(payload.watchState !== undefined ? { watchState: payload.watchState } : {}),
+      ...(payload.displayName !== undefined ? { displayName: payload.displayName } : {}),
+    };
+    const headers: MailAccountEventHeaders = {
+      providerName: current.provider,
+      reason: payload.reason,
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: payload.accountId,
+      aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
+      type: MAIL_ACCOUNT_UPDATED_EVENT_QN,
+      payload: eventPayload,
+      headers,
+    });
+
+    return { isSuccess: true as const, data: { accountId: payload.accountId } };
+  },
+};

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

@@ -0,0 +1,97 @@
+// Public API of the inbound-mail-foundation bundled-feature.
+
+export {
+  inboundMessageAggregateId,
+  mailThreadAggregateId,
+} from "./aggregate-id";
+export {
+  createInboundMailConnectRoutes,
+  type InboundMailConnectRoutes,
+  type InboundMailConnectRoutesDeps,
+} from "./connect-routes";
+export {
+  INBOUND_MAIL_FOUNDATION_FEATURE,
+  INBOUND_MAIL_PROVIDER_EXTENSION,
+  type InboundMailAccountStatus,
+  InboundMailAccountStatuses,
+  type InboundMailAuthMethod,
+  InboundMailAuthMethods,
+  InboundMailFoundationHandlers,
+  InboundMailFoundationQueries,
+  inboundCredentialSecretKey,
+} from "./constants";
+export {
+  INBOUND_MESSAGE_PII_FIELDS,
+  inboundMessageEntity,
+  MAIL_ACCOUNT_PII_FIELDS,
+  MAIL_THREAD_PII_FIELDS,
+  mailAccountEntity,
+  mailThreadEntity,
+  seenMessageEntity,
+  seenMessageTable,
+  syncCursorEntity,
+  syncCursorTable,
+} from "./entities";
+export {
+  INBOUND_MESSAGE_AGGREGATE_TYPE,
+  INBOUND_MESSAGE_RECEIVED_EVENT_QN,
+  INBOUND_MESSAGE_RECEIVED_EVENT_SHORT,
+  type InboundMessageEventHeaders,
+  type InboundMessageEventPayload,
+  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,
+  type MailAccountEventHeaders,
+  type MailAccountEventPayload,
+  type MailThreadEventPayload,
+  mailAccountEventPayloadSchema,
+  mailThreadEventPayloadSchema,
+} from "./events";
+export { inboundMailFoundationFeature } from "./feature";
+export {
+  type OAuthStatePayload,
+  signOAuthState,
+  type VerifyOAuthStateResult,
+  verifyOAuthState,
+} from "./oauth-state";
+export {
+  inboundMessagesProjectionTable,
+  mailAccountsProjectionTable,
+  mailThreadsProjectionTable,
+} from "./projection";
+export {
+  resolveInboundProviderForAccount,
+  resolveInboundProviderForKey,
+} from "./provider-factory";
+export {
+  InboundAuthError,
+  InboundCursorInvalidError,
+  type InboundFetchResult,
+  type InboundMailContext,
+  type InboundMailProviderPlugin,
+  type InboundOAuthFlow,
+  InboundRateLimitError,
+  InboundTransientError,
+  isInboundAuthError,
+  isInboundCursorInvalidError,
+  isInboundMailProviderPlugin,
+  isInboundRateLimitError,
+  isInboundTransientError,
+  type MailAccountRecord,
+  type OAuthTokenSet,
+  type RawInboundMessage,
+  type SyncCursorPayload,
+} from "./types";
+export {
+  createInboundMailSupervisor,
+  type InboundMailSupervisor,
+  type InboundMailSupervisorDeps,
+} from "./watch-supervisor";

package/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/src/inbound-mail-foundation/projection.ts

@@ -0,0 +1,152 @@
+// 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";
+import { inboundMessageEntity, mailAccountEntity, mailThreadEntity } from "./entities";
+import type {
+  InboundMessageEventPayload,
+  MailAccountEventPayload,
+  MailThreadEventPayload,
+} from "./events";
+
+// 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/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";
+import {
+  type InboundMailContext,
+  type InboundMailProviderPlugin,
+  isInboundMailProviderPlugin,
+  type MailAccountRecord,
+} from "./types";
+
+/** 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);
+}