@cosmicdrift/kumiko-bundled-features 0.141.0 → 0.143.0

package/src/inbound-provider-imap/__tests__/imap-live.integration.test.ts

@@ -0,0 +1,194 @@
+// Live-IMAP-Test gegen greenmail (Plan §6 Phase 2, opt-in):
+//   docker run -d --name cdgs-greenmail -p 3025:3025 -p 3143:3143 \
+//     -e GREENMAIL_OPTS="-Dgreenmail.setup.test.all -Dgreenmail.users=testuser:testpass@example.com" \
+//     greenmail/standalone:2.1.0
+//
+// Läuft NUR wenn der Server erreichbar ist (top-level Probe) — sonst
+// skippen alle Tests sichtbar statt rot zu sein. Verifiziert die
+// Plan-Pflichten: fetch-Backfill + inkrementeller Cursor, IDLE-Push
+// < 5 s, Auth-Fehler → InboundAuthError.
+//
+// **Provider-Level-Test:** getestet wird das imapflow-Wiring des
+// Plugins gegen einen echten IMAP-Server. Der ctx ist der schmale
+// InboundMailContext des Provider-Contracts (kein HandlerContext);
+// das Secret-Slot-Read wird mit einem minimalen SecretsContext bedient
+// — der volle Dispatcher-Pfad ist in
+// inbound-mail-foundation.integration.test.ts abgedeckt.
+
+import { describe, expect, test } from "bun:test";
+import { connect } from "node:net";
+import { createSecret } from "@cosmicdrift/kumiko-framework/secrets";
+import { createTransport } from "nodemailer";
+import {
+  type InboundMailContext,
+  isInboundAuthError,
+  type MailAccountRecord,
+  type RawInboundMessage,
+} from "../../inbound-mail-foundation";
+import { imapInboundMailPlugin } from "../feature";
+
+const HOST = process.env["IMAP_LIVE_HOST"] ?? "127.0.0.1";
+const IMAP_PORT = Number(process.env["IMAP_LIVE_PORT"] ?? 3143);
+const SMTP_PORT = Number(process.env["IMAP_LIVE_SMTP_PORT"] ?? 3025);
+const USER = "testuser";
+const PASSWORD = "testpass";
+const ADDRESS = "testuser@example.com";
+
+function probe(host: string, port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host, port, timeout: 1500 });
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => resolve(false));
+    socket.once("timeout", () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
+
+const available = await probe(HOST, IMAP_PORT);
+const liveTest = available ? test : test.skip;
+if (!available) {
+  console.warn(
+    `imap-live: kein IMAP-Server auf ${HOST}:${IMAP_PORT} — Live-Tests werden geskippt (greenmail starten, siehe Header)`,
+  );
+}
+
+function credentialDoc(password: string): string {
+  return JSON.stringify({
+    host: HOST,
+    port: IMAP_PORT,
+    secure: false,
+    user: USER,
+    password,
+  });
+}
+
+/** Minimaler SecretsContext für den Provider-Contract-ctx — liefert das
+ *  Credential-Dokument aus einer Map statt aus der DB. */
+function ctxWithCredentials(doc: string): InboundMailContext {
+  return {
+    // Worker-Identity fürs Secret-Read-Audit (requireSecretsContext).
+    _userId: "imap-live-test",
+    secrets: {
+      get: async () => createSecret(doc),
+      has: async () => true,
+      set: async () => {},
+      delete: async () => {},
+    } as unknown as import("@cosmicdrift/kumiko-framework/secrets").SecretsContext, // @cast-boundary test-double, nur get()/has() werden gelesen
+  };
+}
+
+const account: MailAccountRecord = {
+  id: "00000000-0000-4000-8000-000000001a01",
+  tenantId: "00000000-0000-4000-8000-000000004242",
+  provider: "imap",
+  authMethod: "password",
+  ownerUserId: null,
+  address: ADDRESS,
+  displayName: "Live-Test",
+  status: "active",
+  watchState: "idle",
+};
+
+async function sendTestMail(subject: string, text: string): Promise<void> {
+  const transport = createTransport({ host: HOST, port: SMTP_PORT, secure: false });
+  await transport.sendMail({
+    from: "Sender <sender@example.com>",
+    to: ADDRESS,
+    subject,
+    text,
+  });
+  transport.close();
+}
+
+describe("imap-live — echter Server (greenmail)", () => {
+  liveTest(
+    "verify: korrekte Credentials ok, falsches Passwort → InboundAuthError",
+    async () => {
+      await imapInboundMailPlugin.verify(ctxWithCredentials(credentialDoc(PASSWORD)), account);
+
+      try {
+        await imapInboundMailPlugin.verify(
+          ctxWithCredentials(credentialDoc("wrong-pass")),
+          account,
+        );
+        throw new Error("expected verify to throw");
+      } catch (e) {
+        expect(isInboundAuthError(e)).toBe(true);
+      }
+    },
+    20_000,
+  );
+
+  liveTest(
+    "fetch: Backfill liefert die Mail, inkrementeller Cursor liefert danach nichts Neues",
+    async () => {
+      const ctx = ctxWithCredentials(credentialDoc(PASSWORD));
+      const subject = `backfill-${crypto.randomUUID()}`;
+      await sendTestMail(subject, "Hallo aus dem Live-Test");
+
+      const first = await imapInboundMailPlugin.fetch(ctx, account, null, {
+        backfillWindowDays: 1,
+        maxMessages: 50,
+      });
+      const match = first.messages.find((m) => m.subject === subject);
+      expect(match).toBeDefined();
+      expect(match?.from).toContain("sender@example.com");
+      expect(match?.snippet).toContain("Hallo aus dem Live-Test");
+      expect(match?.rawMime).not.toBeNull();
+      expect(typeof first.nextCursor["uidValidity"]).toBe("string");
+      expect(typeof first.nextCursor["lastUid"]).toBe("number");
+
+      // Inkrementell ab Cursor: nichts Neues.
+      const second = await imapInboundMailPlugin.fetch(ctx, account, first.nextCursor, {
+        backfillWindowDays: 1,
+        maxMessages: 50,
+      });
+      expect(second.messages).toHaveLength(0);
+      expect(second.nextCursor["lastUid"]).toBe(first.nextCursor["lastUid"]);
+    },
+    30_000,
+  );
+
+  liveTest(
+    "watch (IDLE): neue Mail wird in < 5 s gepusht",
+    async () => {
+      const ctx = ctxWithCredentials(credentialDoc(PASSWORD));
+      const subject = `idle-${crypto.randomUUID()}`;
+
+      const pushed = new Promise<readonly RawInboundMessage[]>((resolve, reject) => {
+        const timer = setTimeout(
+          () => reject(new Error("IDLE push not received within 5s")),
+          5_000,
+        );
+        void imapInboundMailPlugin
+          .watch?.(ctx, account, {
+            onMessages: async (msgs) => {
+              if (msgs.some((m) => m.subject === subject)) {
+                clearTimeout(timer);
+                resolve(msgs);
+              }
+            },
+            onError: (err) => {
+              clearTimeout(timer);
+              reject(err instanceof Error ? err : new Error(String(err)));
+            },
+          })
+          .then((stop) => {
+            // Nach Aufbau der IDLE-Verbindung die Mail schicken.
+            void sendTestMail(subject, "IDLE push").catch(reject);
+            // stop() nach Auflösung — pushed-Promise cleanup.
+            void pushed.finally(() => void stop().catch(() => {}));
+          }, reject);
+      });
+
+      const msgs = await pushed;
+      expect(msgs.some((m) => m.subject === subject)).toBe(true);
+    },
+    20_000,
+  );
+});

package/src/inbound-provider-imap/credential-document.ts

@@ -0,0 +1,51 @@
+// Connection-Dokument im per-Account-Secret-Slot
+// (inboundCredentialSecretKey(accountId), Plan §4).
+//
+// **Warum JSON im Secret statt Tenant-Config-Keys:** anders als
+// mail-transport-smtp (EIN SMTP pro Tenant) hat Inbound MEHRERE
+// Accounts pro Tenant mit verschiedenen Hosts — per-Tenant-Config-Keys
+// können das nicht tragen. Host/Port/User sind zusammen mit dem
+// Passwort ein zusammengehöriges Verbindungs-Dokument; der Slot ist
+// ohnehin encrypted-at-rest.
+//
+// authMethod des Accounts bestimmt die Interpretation:
+//   password → { host, port, secure, user, password }
+//   xoauth2  → { host, port, secure, user, accessToken } — V1-Fallback:
+//              Token-Beschaffung/-Refresh gehört den OAuth-Providern
+//              (M365/Gmail, Phase 4/5); der imap-Provider konsumiert
+//              nur einen gültigen Access-Token aus dem Slot.
+
+import { z } from "zod";
+
+export const imapCredentialDocumentSchema = z.object({
+  host: z.string().min(1).max(255),
+  port: z.number().int().min(1).max(65535).default(993),
+  secure: z.boolean().default(true),
+  user: z.string().min(1).max(320),
+  password: z.string().min(1).optional(),
+  accessToken: z.string().min(1).optional(),
+});
+export type ImapCredentialDocument = z.infer<typeof imapCredentialDocumentSchema>;
+
+export type ImapCredentialRejection = "not_json" | "invalid_schema" | "missing_credentials";
+
+export type ParseCredentialResult =
+  | { readonly ok: true; readonly doc: ImapCredentialDocument }
+  | { readonly ok: false; readonly reason: ImapCredentialRejection; readonly detail?: string };
+
+export function parseImapCredentialDocument(raw: string): ParseCredentialResult {
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: "not_json" };
+  }
+  const parsed = imapCredentialDocumentSchema.safeParse(json);
+  if (!parsed.success) {
+    return { ok: false, reason: "invalid_schema", detail: parsed.error.message };
+  }
+  if (!parsed.data.password && !parsed.data.accessToken) {
+    return { ok: false, reason: "missing_credentials", detail: "needs password or accessToken" };
+  }
+  return { ok: true, doc: parsed.data };
+}

package/src/inbound-provider-imap/feature.ts

@@ -0,0 +1,287 @@
+// kumiko-feature-version: 1
+//
+// inbound-provider-imap — IMAP-Implementierung der inbound-mail-
+// foundation Plugin-API. Deckt den DACH-Long-Tail (IONOS, Telekom,
+// Strato, GMX/Web.de, mailbox.org, Hetzner, all-inkl) via Passwort/
+// App-Passwort ab — komplett OHNE OAuth. XOAUTH2 als Fallback für
+// M365-/Gmail-Konten (Access-Token aus dem Secret-Slot; Token-Refresh
+// gehört den OAuth-Providern, Phase 4/5).
+//
+// **Was diese Feature liefert:**
+//   1. Plugin-Registration via r.useExtension("inboundMailProvider",
+//      "imap", { verify, fetch, watch }).
+//   2. verify: connect+logout mit typisiertem Fehler-Mapping.
+//   3. fetch: inkrementeller Sync über UIDVALIDITY:lastUid-Cursor —
+//      UIDVALIDITY-Wechsel wirft InboundCursorInvalidError (Foundation
+//      resettet + resynct im Backfill-Fenster). Erst-Befüllung via
+//      SEARCH since=backfillWindowDays.
+//   4. watch: IMAP IDLE via imapflow — 'exists'-Event → neue UIDs
+//      fetchen → onMessages; Verbindungs-Tod → onError (Supervisor
+//      restartet mit Backoff, der Provider reconnected NICHT selbst).
+//
+// Credentials: JSON-Dokument im per-Account-Secret-Slot
+// (credential-document.ts) — kein Tenant-Config, weil mehrere Accounts
+// pro Tenant verschiedene Hosts haben.
+
+import {
+  INBOUND_MAIL_PROVIDER_EXTENSION,
+  InboundAuthError,
+  type InboundFetchResult,
+  type InboundMailContext,
+  type InboundMailProviderPlugin,
+  inboundCredentialSecretKey,
+  type MailAccountRecord,
+  type RawInboundMessage,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { instantToLegacyDate } from "@cosmicdrift/kumiko-framework/time";
+import type { ImapFlow, MailboxObject } from "imapflow";
+import { Temporal } from "temporal-polyfill";
+import { type ImapCredentialDocument, parseImapCredentialDocument } from "./credential-document";
+import {
+  assertUidValidity,
+  coerceDate,
+  createImapClient,
+  IMAP_MAILBOX,
+  mapImapError,
+  parseImapCursor,
+  toRawInboundMessage,
+} from "./imap-client";
+
+const FEATURE_NAME = "inbound-provider-imap";
+export const IMAP_PROVIDER_KEY = "imap";
+
+// =============================================================================
+// Credential-Read — per-Account-Slot, Worker-tauglich (slim ctx).
+// =============================================================================
+
+async function readCredentialDocument(
+  ctx: InboundMailContext,
+  account: MailAccountRecord,
+): Promise<ImapCredentialDocument> {
+  const secrets = requireSecretsContext(ctx, FEATURE_NAME);
+  const secret = await secrets.get(account.tenantId, inboundCredentialSecretKey(account.id));
+  if (!secret) {
+    throw new InboundAuthError(
+      `${FEATURE_NAME}: no credential document in secret slot for account ${account.id} — ` +
+        `store the IMAP connection JSON under ${inboundCredentialSecretKey(account.id)} first`,
+    );
+  }
+  const parsed = parseImapCredentialDocument(secret.reveal());
+  if (!parsed.ok) {
+    throw new InboundAuthError(
+      `${FEATURE_NAME}: account ${account.id}: ${parsed.reason}${parsed.detail ? `: ${parsed.detail}` : ""}`,
+    );
+  }
+  return parsed.doc;
+}
+
+// =============================================================================
+// fetch — inkrementeller UID-Sync
+// =============================================================================
+
+async function fetchMessages(
+  ctx: InboundMailContext,
+  account: MailAccountRecord,
+  cursor: Parameters<InboundMailProviderPlugin["fetch"]>[2],
+  opts: { readonly backfillWindowDays: number; readonly maxMessages: number },
+): Promise<InboundFetchResult> {
+  const doc = await readCredentialDocument(ctx, account);
+  const client = createImapClient(doc);
+  try {
+    await client.connect();
+  } catch (err) {
+    throw mapImapError(err, doc.host);
+  }
+
+  const lock = await client.getMailboxLock(IMAP_MAILBOX);
+  try {
+    const mailbox = client.mailbox as MailboxObject;
+    const serverUidValidity = String(mailbox.uidValidity);
+    const parsedCursor = parseImapCursor(cursor);
+    assertUidValidity(parsedCursor, serverUidValidity);
+
+    // UID-Menge bestimmen: inkrementell ab lastUid+1, sonst Backfill
+    // über SEARCH since (Fenster begrenzt die Erst-Befüllung).
+    let uids: number[];
+    if (parsedCursor) {
+      const found = await client.search({ uid: `${parsedCursor.lastUid + 1}:*` }, { uid: true });
+      // `N:*`-Gotcha: liegt N über der höchsten UID, liefert IMAP
+      // trotzdem die letzte Message — rausfiltern.
+      uids = (found || []).filter((uid) => uid > parsedCursor.lastUid);
+    } else {
+      const since = Temporal.Now.instant().subtract({ hours: opts.backfillWindowDays * 24 });
+      // imapflow-API-Boundary: search() verlangt ein JS-Date.
+      uids = (await client.search({ since: instantToLegacyDate(since) }, { uid: true })) || [];
+    }
+    uids.sort((a, b) => a - b);
+
+    const batch = uids.slice(0, opts.maxMessages);
+    const hasMore = uids.length > batch.length;
+    const messages: RawInboundMessage[] = [];
+    let maxUid = parsedCursor?.lastUid ?? 0;
+
+    if (batch.length > 0) {
+      for await (const msg of client.fetch(
+        batch.join(","),
+        { uid: true, internalDate: true, source: true },
+        { uid: true },
+      )) {
+        if (!msg.source) continue;
+        messages.push(
+          await toRawInboundMessage({
+            source: msg.source,
+            uid: msg.uid,
+            uidValidity: serverUidValidity,
+            internalDate: coerceDate(msg.internalDate ?? undefined),
+          }),
+        );
+        if (msg.uid > maxUid) maxUid = msg.uid;
+      }
+    }
+
+    return {
+      messages,
+      nextCursor: { uidValidity: serverUidValidity, lastUid: maxUid },
+      hasMore,
+    };
+  } catch (err) {
+    throw err instanceof Error && "kind" in err ? err : mapImapError(err, doc.host);
+  } finally {
+    lock.release();
+    await client.logout().catch(() => {});
+  }
+}
+
+// =============================================================================
+// watch — IMAP IDLE (imapflow idlet automatisch bei offener Mailbox und
+// emittet 'exists' bei neuen Messages).
+// =============================================================================
+
+async function watchMailbox(
+  ctx: InboundMailContext,
+  account: MailAccountRecord,
+  handlers: {
+    readonly onMessages: (msgs: readonly RawInboundMessage[]) => Promise<void>;
+    readonly onError: (err: unknown) => void;
+  },
+): Promise<() => Promise<void>> {
+  const doc = await readCredentialDocument(ctx, account);
+  const client: ImapFlow = createImapClient(doc);
+  let stopped = false;
+
+  try {
+    await client.connect();
+    const mailbox = (await client.mailboxOpen(IMAP_MAILBOX)) as MailboxObject;
+    const uidValidity = String(mailbox.uidValidity);
+    // uidNext = nächste zu vergebende UID — alles ab hier ist "neu".
+    let nextUid = Number(mailbox.uidNext ?? 1);
+
+    const drainNew = async () => {
+      const messages: RawInboundMessage[] = [];
+      let maxSeen = nextUid - 1;
+      for await (const msg of client.fetch(
+        `${nextUid}:*`,
+        { uid: true, internalDate: true, source: true },
+        { uid: true },
+      )) {
+        // `N:*`-Gotcha (siehe fetch): alte letzte Message rausfiltern.
+        if (msg.uid < nextUid || !msg.source) continue;
+        messages.push(
+          await toRawInboundMessage({
+            source: msg.source,
+            uid: msg.uid,
+            uidValidity,
+            internalDate: coerceDate(msg.internalDate ?? undefined),
+          }),
+        );
+        if (msg.uid > maxSeen) maxSeen = msg.uid;
+      }
+      nextUid = maxSeen + 1;
+      if (messages.length > 0) await handlers.onMessages(messages);
+    };
+
+    client.on("exists", () => {
+      // skip: Watcher gestoppt — exists-Nachzügler ignorieren.
+      if (stopped) return;
+      void drainNew().catch((err) => {
+        if (!stopped) handlers.onError(mapImapError(err, doc.host));
+      });
+    });
+    const die = (err: unknown) => {
+      // skip: bereits gestoppt/gestorben — onError nur einmal feuern.
+      if (stopped) return;
+      stopped = true;
+      handlers.onError(mapImapError(err, doc.host));
+    };
+    client.on("error", die);
+    client.on("close", () => die(new Error("connection closed")));
+
+    // IDLE-Loop: 'exists' feuert NUR während client.idle() läuft
+    // (empirisch gegen greenmail verifiziert). Jedes zwischengeschobene
+    // Kommando (drainNew-fetch) beendet idle() — die Loop re-idlet,
+    // bis stop() die Verbindung schließt.
+    void (async () => {
+      while (!stopped) {
+        try {
+          await client.idle();
+        } catch (err) {
+          if (!stopped) die(err);
+          // skip: idle-Loop endet — die() hat den Supervisor informiert (bzw. stop() war die Ursache).
+          return;
+        }
+      }
+    })();
+
+    return async () => {
+      stopped = true;
+      client.removeAllListeners("exists");
+      client.removeAllListeners("error");
+      client.removeAllListeners("close");
+      await client.logout().catch(() => {});
+    };
+  } catch (err) {
+    await client.logout().catch(() => {});
+    throw mapImapError(err, doc.host);
+  }
+}
+
+// =============================================================================
+// Plugin + Feature-definition
+// =============================================================================
+
+/** Exportiert für den Live-Test (imap-live.integration.test.ts) —
+ *  Apps nutzen das Feature, nie das Plugin direkt. */
+export const imapInboundMailPlugin: InboundMailProviderPlugin = {
+  verify: async (ctx, account) => {
+    const doc = await readCredentialDocument(ctx, account);
+    const client = createImapClient(doc);
+    try {
+      await client.connect();
+    } catch (err) {
+      throw mapImapError(err, doc.host);
+    } finally {
+      await client.logout().catch(() => {});
+    }
+  },
+  fetch: fetchMessages,
+  watch: watchMailbox,
+  // Kein oauth-Block: Passwort-Connect läuft über das Credential-
+  // Formular (connect-account + Secret-Write); XOAUTH2-Token-Flows
+  // gehören den OAuth-Providern (M365/Gmail).
+};
+
+export const inboundProviderImapFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    'Registers the `"imap"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Store the per-account connection JSON (host/port/secure/user/password) in the account credential secret slot before the first sync.',
+  );
+  r.uiHints({
+    displayLabel: "Inbound Mail · IMAP",
+    category: "notifications",
+    recommended: false,
+  });
+  r.requires("inbound-mail-foundation");
+  r.requires("secrets");
+  r.useExtension(INBOUND_MAIL_PROVIDER_EXTENSION, IMAP_PROVIDER_KEY, imapInboundMailPlugin);
+});

package/src/inbound-provider-imap/imap-client.ts

@@ -0,0 +1,158 @@
+// imapflow-Wiring + pure Helpers des IMAP-Providers.
+// Referenz-Impl: /Users/marc/code/doc-o-mat (HEINZ) — aber inkrementeller
+// UIDVALIDITY:lastUid-Cursor statt '1:*'-Vollscan.
+
+import {
+  InboundAuthError,
+  InboundCursorInvalidError,
+  InboundTransientError,
+  type RawInboundMessage,
+  type SyncCursorPayload,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { legacyDateToInstant } from "@cosmicdrift/kumiko-framework/time";
+import { ImapFlow } from "imapflow";
+import { type AddressObject, type ParsedMail, simpleParser } from "mailparser";
+import { Temporal } from "temporal-polyfill";
+import type { ImapCredentialDocument } from "./credential-document";
+
+export const IMAP_MAILBOX = "INBOX";
+const SNIPPET_MAX = 300;
+
+// =============================================================================
+// Client-Factory + Fehler-Mapping
+// =============================================================================
+
+export function createImapClient(doc: ImapCredentialDocument): ImapFlow {
+  return new ImapFlow({
+    host: doc.host,
+    port: doc.port,
+    secure: doc.secure,
+    auth: doc.password
+      ? { user: doc.user, pass: doc.password }
+      : { user: doc.user, accessToken: doc.accessToken as string },
+    logger: false,
+    emitLogs: false,
+  });
+}
+
+/** Server-Fehler → typisierte Foundation-Fehlerklassen (Plan §2). */
+export function mapImapError(err: unknown, host: string): Error {
+  // imapflow-Fehler tragen die Server-Antwort in responseText, die
+  // message ist nur "Command failed" — beides in den Match einbeziehen;
+  // authenticationFailed ist das verlässliche Flag.
+  const carrier = err as { authenticationFailed?: unknown; responseText?: unknown };
+  const responseText = typeof carrier?.responseText === "string" ? carrier.responseText : "";
+  const msg = `${err instanceof Error ? err.message : String(err)} ${responseText}`.trim();
+  if (
+    carrier?.authenticationFailed === true ||
+    /auth(entication)? failed|invalid credentials|invalid login|LOGIN failed|AUTHENTICATIONFAILED/i.test(
+      msg,
+    )
+  ) {
+    return new InboundAuthError(`IMAP auth failed at ${host}: ${msg}`);
+  }
+  if (/ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|ECONNRESET|socket|closed/i.test(msg)) {
+    return new InboundTransientError(`IMAP ${host} unreachable: ${msg}`);
+  }
+  return new InboundTransientError(`IMAP ${host}: ${msg}`);
+}
+
+// =============================================================================
+// Cursor — { uidValidity: string, lastUid: number }
+// =============================================================================
+
+export type ImapCursor = { readonly uidValidity: string; readonly lastUid: number };
+
+export function parseImapCursor(cursor: SyncCursorPayload | null): ImapCursor | null {
+  if (!cursor) return null;
+  const uidValidity = cursor["uidValidity"];
+  const lastUid = cursor["lastUid"];
+  if (typeof uidValidity !== "string" || typeof lastUid !== "number") return null;
+  return { uidValidity, lastUid };
+}
+
+/** Wirft InboundCursorInvalidError bei UIDVALIDITY-Wechsel — die
+ *  Foundation resettet den Cursor und macht einen Voll-Resync im
+ *  Backfill-Fenster (Dedup fängt Dubletten). */
+export function assertUidValidity(cursor: ImapCursor | null, serverUidValidity: string): void {
+  if (cursor && cursor.uidValidity !== serverUidValidity) {
+    throw new InboundCursorInvalidError(
+      `UIDVALIDITY changed (${cursor.uidValidity} → ${serverUidValidity}) — full resync required`,
+    );
+  }
+}
+
+// =============================================================================
+// Message-Normalisierung → RawInboundMessage
+// =============================================================================
+
+function stripAngles(id: string): string {
+  return id.replace(/^<|>$/g, "").trim();
+}
+
+/** References-Chain normalisieren: mailparser liefert string | string[]
+ *  | undefined; fehlt References, trägt In-Reply-To den Thread-Anker. */
+export function normalizeReferences(parsed: {
+  references?: string | string[];
+  inReplyTo?: string;
+}): string[] {
+  const raw = parsed.references;
+  const list = raw === undefined ? [] : Array.isArray(raw) ? raw : raw.split(/\s+/);
+  const refs = list.map(stripAngles).filter((r) => r.length > 0);
+  if (refs.length === 0 && parsed.inReplyTo) {
+    const inReplyTo = stripAngles(parsed.inReplyTo);
+    if (inReplyTo) return [inReplyTo];
+  }
+  return refs;
+}
+
+function addressList(a: AddressObject | AddressObject[] | undefined): string[] {
+  if (!a) return [];
+  const arr = Array.isArray(a) ? a : [a];
+  return arr.map((x) => x.text).filter((t): t is string => Boolean(t));
+}
+
+/** imapflow liefert internalDate je nach Codepfad als Date ODER string.
+ *  String-Form verwerfen wir bewusst (kein Date-Parsing im Feature-Code,
+ *  no-date-api) — toRawInboundMessage fällt dann auf mailparsers
+ *  Date-Header zurück, der immer als echtes Date kommt. */
+export function coerceDate(d: Date | string | undefined): Date | undefined {
+  return d instanceof Date ? d : undefined;
+}
+
+/** providerMessageId: UID ist nur innerhalb einer UIDVALIDITY eindeutig
+ *  — beides zusammen ist der stabile Idempotency-Anchor. */
+export function buildProviderMessageId(uidValidity: string, uid: number): string {
+  return `${uidValidity}:${uid}`;
+}
+
+export async function toRawInboundMessage(args: {
+  readonly source: Uint8Array;
+  readonly uid: number;
+  readonly uidValidity: string;
+  readonly internalDate: Date | undefined;
+}): Promise<RawInboundMessage> {
+  const parsed: ParsedMail = await simpleParser(Buffer.from(args.source));
+  const messageIdHeader = parsed.messageId ? stripAngles(parsed.messageId) : null;
+  const receivedAt = args.internalDate ?? parsed.date;
+  const text = parsed.text?.trim() ?? "";
+  return {
+    providerMessageId: buildProviderMessageId(args.uidValidity, args.uid),
+    messageIdHeader: messageIdHeader && messageIdHeader.length > 0 ? messageIdHeader : null,
+    providerThreadId: null,
+    references: normalizeReferences(parsed),
+    from: parsed.from?.text ?? "",
+    to: addressList(parsed.to),
+    cc: addressList(parsed.cc),
+    subject: parsed.subject ?? "",
+    snippet: text.slice(0, SNIPPET_MAX),
+    // Lib-Boundary-Bridge (Date von imapflow/mailparser) → Temporal;
+    // fehlt jedes Datum, ist Epoch der ehrliche Marker.
+    receivedAtIso: (receivedAt
+      ? legacyDateToInstant(receivedAt)
+      : Temporal.Instant.fromEpochMilliseconds(0)
+    ).toString(),
+    rawMime: args.source,
+    scope: "inbox",
+  };
+}