@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/inbound-mail-foundation/entities.js

@@ -0,0 +1,207 @@
+import { collectPiiSubjectFields } from "@cosmicdrift/kumiko-framework/crypto";
+import { deriveEntityTableMeta } 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 convention:** `personal: "tenant"` (not `encrypted`): fields must
+// crypto-shred when eraseSubjectKeys deletes the tenant subject key on
+// tenant-destroy (#800 pattern from 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,
+            personal: false,
+            reason: "technical_reference",
+        }),
+        authMethod: createTextField({
+            required: true,
+            maxLength: 30,
+            personal: false,
+            reason: "technical_reference",
+        }),
+        // 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, personal: false, reason: "pseudonymous_fk" }),
+        // Tenant-authored mailbox label, not a person's name.
+        displayName: createTextField({
+            maxLength: 200,
+            personal: false,
+            reason: "tenant_config_not_personal",
+        }),
+        // Postfach-Adresse — PII des Tenants.
+        address: createTextField({ required: true, maxLength: 1000, personal: "tenant", find: "none" }),
+        status: createTextField({
+            required: true,
+            maxLength: 30,
+            personal: false,
+            reason: "technical_reference",
+        }),
+        watchState: createTextField({ maxLength: 100, personal: false, reason: "technical_reference" }),
+        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,
+            personal: false,
+            reason: "technical_reference",
+        }),
+        // 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, personal: false, reason: "pseudonymous_fk" }),
+        messageIdHeader: createTextField({
+            required: true,
+            maxLength: 500,
+            personal: false,
+            reason: "technical_reference",
+        }),
+        threadKey: createTextField({
+            required: true,
+            maxLength: 500,
+            personal: false,
+            reason: "technical_reference",
+        }),
+        from: createTextField({ required: true, maxLength: 2000, personal: "tenant", find: "none" }),
+        // JSON-stringified string[] — als Ganzes encrypted.
+        to: createTextField({ maxLength: 8000, personal: "tenant", find: "none" }),
+        cc: createTextField({ maxLength: 8000, personal: "tenant", find: "none" }),
+        subject: createTextField({ maxLength: 4000, personal: "tenant", find: "none" }),
+        snippet: createTextField({ maxLength: 4000, personal: "tenant", find: "none" }),
+        receivedAt: createTimestampField({ required: true }),
+        bodyRef: createTextField({ maxLength: 500, personal: false, reason: "technical_reference" }),
+        scope: createTextField({ maxLength: 200, personal: false, reason: "technical_reference" }),
+    },
+});
+/** Thread-Rollup. PK = aggregateId = mailThreadAggregateId(tenantId,
+ *  threadKey). */
+export const mailThreadEntity = createEntity({
+    table: "read_mail_threads",
+    fields: {
+        threadKey: createTextField({
+            required: true,
+            maxLength: 500,
+            personal: false,
+            reason: "technical_reference",
+        }),
+        subject: createTextField({ maxLength: 4000, personal: "tenant", find: "none" }),
+        lastMessageAt: createTimestampField({ required: true }),
+        messageCount: createNumberField({ required: true, integer: 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: "store_mail_sync_cursors",
+    softDelete: false,
+    fields: {
+        accountId: createTextField({
+            required: true,
+            maxLength: 36,
+            access: { write: access.privileged },
+            personal: false,
+            reason: "technical_reference",
+        }),
+        scope: createTextField({
+            required: true,
+            maxLength: 200,
+            access: { write: access.privileged },
+            personal: false,
+            reason: "technical_reference",
+        }),
+        cursor: createTextField({
+            required: true,
+            maxLength: 2000,
+            access: { write: access.privileged },
+            personal: false,
+            reason: "technical_reference",
+        }),
+        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: "store_mail_seen_messages",
+    softDelete: false,
+    fields: {
+        accountId: createTextField({
+            required: true,
+            maxLength: 36,
+            access: { write: access.privileged },
+            personal: false,
+            reason: "technical_reference",
+        }),
+        providerMessageId: createTextField({
+            required: true,
+            maxLength: 500,
+            access: { write: access.privileged },
+            personal: false,
+            reason: "technical_reference",
+        }),
+        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 = deriveEntityTableMeta("mail-sync-cursor", syncCursorEntity, {
+    source: "unmanaged",
+});
+export const seenMessageTable = deriveEntityTableMeta("mail-seen-message", seenMessageEntity, {
+    source: "unmanaged",
+});

package/dist/inbound-mail-foundation/events.d.ts

@@ -0,0 +1,64 @@
+import * as z from "zod";
+export declare const MAIL_ACCOUNT_AGGREGATE_TYPE: "mail-account";
+export declare const INBOUND_MESSAGE_AGGREGATE_TYPE: "inbound-message";
+export declare const MAIL_THREAD_AGGREGATE_TYPE: "mail-thread";
+export declare const MAIL_ACCOUNT_CONNECTED_EVENT_SHORT: "mail-account-connected";
+export declare const MAIL_ACCOUNT_UPDATED_EVENT_SHORT: "mail-account-updated";
+export declare const MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT: "mail-account-disconnected";
+export declare const INBOUND_MESSAGE_RECEIVED_EVENT_SHORT: "inbound-message-received";
+export declare const MAIL_THREAD_UPDATED_EVENT_SHORT: "mail-thread-updated";
+export declare const MAIL_ACCOUNT_CONNECTED_EVENT_QN: "inbound-mail-foundation:event:mail-account-connected";
+export declare const MAIL_ACCOUNT_UPDATED_EVENT_QN: "inbound-mail-foundation:event:mail-account-updated";
+export declare const MAIL_ACCOUNT_DISCONNECTED_EVENT_QN: "inbound-mail-foundation:event:mail-account-disconnected";
+export declare const INBOUND_MESSAGE_RECEIVED_EVENT_QN: "inbound-mail-foundation:event:inbound-message-received";
+export declare const MAIL_THREAD_UPDATED_EVENT_QN: "inbound-mail-foundation:event:mail-thread-updated";
+export declare const mailAccountEventPayloadSchema: z.ZodObject<{
+    provider: z.ZodString;
+    authMethod: z.ZodString;
+    ownerUserId: z.ZodNullable<z.ZodString>;
+    displayName: z.ZodString;
+    address: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        auth_error: "auth_error";
+        degraded: "degraded";
+        disconnected: "disconnected";
+    }>;
+    watchState: z.ZodString;
+}, z.core.$strip>;
+export type MailAccountEventPayload = z.infer<typeof mailAccountEventPayloadSchema>;
+export declare const inboundMessageEventPayloadSchema: z.ZodObject<{
+    accountId: z.ZodUUID;
+    ownerUserId: z.ZodNullable<z.ZodString>;
+    messageIdHeader: z.ZodString;
+    threadKey: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    cc: z.ZodString;
+    subject: z.ZodString;
+    snippet: z.ZodString;
+    receivedAtIso: z.ZodString;
+    bodyRef: z.ZodString;
+    scope: z.ZodString;
+}, z.core.$strip>;
+export type InboundMessageEventPayload = z.infer<typeof inboundMessageEventPayloadSchema>;
+export declare const mailThreadEventPayloadSchema: z.ZodObject<{
+    threadKey: z.ZodString;
+    subject: z.ZodString;
+    lastMessageAtIso: z.ZodString;
+    messageCount: z.ZodNumber;
+}, z.core.$strip>;
+export type MailThreadEventPayload = z.infer<typeof mailThreadEventPayloadSchema>;
+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/dist/inbound-mail-foundation/events.js

@@ -0,0 +1,112 @@
+// 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";
+export const INBOUND_MESSAGE_AGGREGATE_TYPE = "inbound-message";
+export const MAIL_THREAD_AGGREGATE_TYPE = "mail-thread";
+// 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";
+export const MAIL_ACCOUNT_UPDATED_EVENT_SHORT = "mail-account-updated";
+export const MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT = "mail-account-disconnected";
+export const INBOUND_MESSAGE_RECEIVED_EVENT_SHORT = "inbound-message-received";
+export const MAIL_THREAD_UPDATED_EVENT_SHORT = "mail-thread-updated";
+export const MAIL_ACCOUNT_CONNECTED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_CONNECTED_EVENT_SHORT}`;
+export const MAIL_ACCOUNT_UPDATED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_UPDATED_EVENT_SHORT}`;
+export const MAIL_ACCOUNT_DISCONNECTED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT}`;
+export const INBOUND_MESSAGE_RECEIVED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${INBOUND_MESSAGE_RECEIVED_EVENT_SHORT}`;
+export const MAIL_THREAD_UPDATED_EVENT_QN = `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_THREAD_UPDATED_EVENT_SHORT}`;
+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),
+});
+// ============================================================================
+// 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),
+});
+// ============================================================================
+// 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),
+});

package/dist/inbound-mail-foundation/feature.d.ts

@@ -0,0 +1,3 @@
+export declare const inboundMailFoundationFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};

package/dist/inbound-mail-foundation/feature.js

@@ -0,0 +1,204 @@
+// 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 { defineFeature, EXT_TENANT_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import { createFileProviderForTenant, } 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` (#2776).
+    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); // @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 = null;
+            const deleteBodyObject = async (bodyRef) => {
+                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/dist/inbound-mail-foundation/handlers/account-state.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { MailAccountEventPayload } from "../events.js";
+export declare function loadCurrentMailAccountPayload(ctx: Pick<HandlerContext, "loadAggregate">, accountId: string): Promise<MailAccountEventPayload | undefined>;

package/dist/inbound-mail-foundation/handlers/account-state.js

@@ -0,0 +1,16 @@
+// 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).
+export async function loadCurrentMailAccountPayload(ctx, accountId) {
+    const events = await ctx.loadAggregate(accountId);
+    const last = events[events.length - 1];
+    // @cast-boundary engine-payload — eigene events, shape via defineEvent
+    return last?.payload;
+}

package/dist/inbound-mail-foundation/handlers/connect-account.write.d.ts

@@ -0,0 +1,18 @@
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+export declare const connectAccountSchema: z.ZodObject<{
+    provider: z.ZodString;
+    authMethod: z.ZodEnum<{
+        oauth: "oauth";
+        password: "password";
+        xoauth2: "xoauth2";
+    }>;
+    displayName: z.ZodString;
+    address: z.ZodString;
+    scope: z.ZodEnum<{
+        shared: "shared";
+        user: "user";
+    }>;
+    ownerUserIdOverride: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const connectAccountHandler: WriteHandlerDef;