@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/inbound-provider-imap/__tests__/plugin-mocked.test.ts

@@ -0,0 +1,358 @@
+// Always-on unit coverage for imapInboundMailPlugin.verify/fetch/watch.
+// Greenmail suites skip in CI when the container is down — this file mocks
+// imapflow so the plugin body stays on the coverage badge without Docker.
+
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import { EventEmitter } from "node:events";
+import { createSecret } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  type InboundMailContext,
+  isInboundAuthError,
+  isInboundCursorInvalidError,
+  isInboundTransientError,
+  type MailAccountRecord,
+  type RawInboundMessage,
+} from "../../inbound-mail-foundation";
+
+type FakeMsg = {
+  readonly uid: number;
+  readonly source: Buffer;
+  readonly internalDate: Date;
+};
+
+type FakeState = {
+  connectError?: Error;
+  authFailed?: boolean;
+  uidValidity: string;
+  uidNext: number;
+  messages: FakeMsg[];
+  /** When set, search() returns this list instead of all message uids. */
+  searchUids?: number[];
+};
+
+let state: FakeState;
+let lastIdleClient: FakeImapFlow | undefined;
+
+class FakeImapFlow extends EventEmitter {
+  mailbox: { uidValidity: bigint; uidNext: number } | false = false;
+  private idleReject: ((err: Error) => void) | undefined;
+
+  constructor(_opts: unknown) {
+    super();
+    lastIdleClient = this;
+  }
+
+  async connect(): Promise<void> {
+    if (state.connectError) {
+      const err = state.connectError as Error & { authenticationFailed?: boolean };
+      if (state.authFailed) err.authenticationFailed = true;
+      throw err;
+    }
+  }
+
+  async logout(): Promise<void> {
+    this.idleReject?.(new Error("connection closed"));
+    this.idleReject = undefined;
+  }
+
+  async getMailboxLock(_box: string): Promise<{ release: () => void }> {
+    this.mailbox = {
+      uidValidity: BigInt(state.uidValidity),
+      uidNext: state.uidNext,
+    };
+    return { release: () => {} };
+  }
+
+  async mailboxOpen(_box: string): Promise<{ uidValidity: bigint; uidNext: number }> {
+    this.mailbox = {
+      uidValidity: BigInt(state.uidValidity),
+      uidNext: state.uidNext,
+    };
+    return this.mailbox;
+  }
+
+  async search(_query: unknown, _opts?: unknown): Promise<number[]> {
+    return state.searchUids ?? state.messages.map((m) => m.uid);
+  }
+
+  async *fetch(
+    range: string,
+    _opts?: unknown,
+    _uidOpts?: unknown,
+  ): AsyncGenerator<{
+    uid: number;
+    source: Buffer;
+    internalDate: Date;
+  }> {
+    // Real imapflow is called with either "N,M,…" (explicit uid list) or "N:*".
+    const wanted = new Set<number>();
+    if (range.includes("*")) {
+      const start = Number(range.split(":")[0]);
+      for (const m of state.messages) {
+        if (m.uid >= start) wanted.add(m.uid);
+      }
+    } else {
+      for (const part of range.split(",")) {
+        const n = Number(part.trim());
+        if (Number.isFinite(n)) wanted.add(n);
+      }
+    }
+    for (const m of state.messages) {
+      if (wanted.size > 0 && !wanted.has(m.uid)) continue;
+      yield { uid: m.uid, source: m.source, internalDate: m.internalDate };
+    }
+  }
+
+  async idle(): Promise<void> {
+    await new Promise<void>((_resolve, reject) => {
+      this.idleReject = reject;
+    });
+  }
+}
+
+// Restore hygiene: Bun runs a test-run's files in one process, so a
+// top-level mock.module leaks into every file that runs after this one. The
+// real module is captured before mocking so afterAll can put it back — a
+// later file that needs the real imapflow (or a filtered/reordered run via
+// `-t`) would otherwise silently see FakeImapFlow instead.
+const realImapflow = await import("imapflow");
+mock.module("imapflow", () => ({ ImapFlow: FakeImapFlow }));
+
+const { imapInboundMailPlugin } = await import("../feature");
+
+afterAll(() => {
+  mock.module("imapflow", () => realImapflow);
+});
+
+function mime(subject: string, text: string): Buffer {
+  return Buffer.from(
+    [
+      "From: Sender <sender@example.com>",
+      "To: inbox@example.com",
+      `Subject: ${subject}`,
+      `Message-ID: <${subject}-@example.com>`,
+      "Date: Mon, 01 Jan 2024 12:00:00 +0000",
+      "MIME-Version: 1.0",
+      "Content-Type: text/plain; charset=utf-8",
+      "",
+      text,
+    ].join("\r\n"),
+  );
+}
+
+const account: MailAccountRecord = {
+  id: "00000000-0000-4000-8000-000000001a01",
+  tenantId: "00000000-0000-4000-8000-000000004242",
+  provider: "imap",
+  authMethod: "password",
+  ownerUserId: null,
+  address: "inbox@example.com",
+  displayName: "Mock",
+  status: "active",
+  watchState: "idle",
+};
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
+  const t0 = Date.now();
+  while (!predicate() && Date.now() - t0 < timeoutMs) {
+    await Bun.sleep(5);
+  }
+}
+
+function ctxWithDoc(doc: string | null): InboundMailContext {
+  return {
+    _userId: "imap-plugin-mocked",
+    secrets: {
+      get: async () => (doc === null ? null : createSecret(doc)),
+      has: async () => doc !== null,
+      set: async () => {},
+      delete: async () => {},
+    } as unknown as import("@cosmicdrift/kumiko-framework/secrets").SecretsContext, // @cast-boundary test-double
+  };
+}
+
+const goodDoc = JSON.stringify({
+  host: "imap.example.com",
+  port: 993,
+  secure: true,
+  user: "u@example.com",
+  password: "pw",
+});
+
+beforeEach(() => {
+  lastIdleClient = undefined;
+  state = {
+    uidValidity: "17",
+    uidNext: 3,
+    messages: [
+      {
+        uid: 1,
+        source: mime("one", "hello one"),
+        internalDate: new Date("2024-01-01T12:00:00Z"),
+      },
+      {
+        uid: 2,
+        source: mime("two", "hello two"),
+        internalDate: new Date("2024-01-02T12:00:00Z"),
+      },
+    ],
+  };
+});
+
+describe("imapInboundMailPlugin — mocked imapflow", () => {
+  test("verify: connect+logout happy path", async () => {
+    await expect(
+      imapInboundMailPlugin.verify(ctxWithDoc(goodDoc), account),
+    ).resolves.toBeUndefined();
+  });
+
+  test("verify: auth failure → InboundAuthError", async () => {
+    state.connectError = new Error("Authentication failed");
+    state.authFailed = true;
+    try {
+      await imapInboundMailPlugin.verify(ctxWithDoc(goodDoc), account);
+      expect.unreachable("expected verify to throw");
+    } catch (e) {
+      expect(isInboundAuthError(e)).toBe(true);
+    }
+  });
+
+  test("verify: missing credential secret → InboundAuthError", async () => {
+    try {
+      await imapInboundMailPlugin.verify(ctxWithDoc(null), account);
+      expect.unreachable("expected verify to throw");
+    } catch (e) {
+      expect(isInboundAuthError(e)).toBe(true);
+    }
+  });
+
+  test("verify: malformed credential JSON → InboundAuthError", async () => {
+    try {
+      await imapInboundMailPlugin.verify(ctxWithDoc("not-json"), account);
+      expect.unreachable("expected verify to throw");
+    } catch (e) {
+      expect(isInboundAuthError(e)).toBe(true);
+    }
+  });
+
+  test("fetch: backfill (null cursor) returns messages + nextCursor", async () => {
+    const result = await imapInboundMailPlugin.fetch(ctxWithDoc(goodDoc), account, null, {
+      backfillWindowDays: 7,
+      maxMessages: 50,
+    });
+    expect(result.messages).toHaveLength(2);
+    expect(result.messages[0]?.subject).toBe("one");
+    expect(result.nextCursor).toEqual({ uidValidity: "17", lastUid: 2 });
+    expect(result.hasMore).toBe(false);
+    // Fixtures must carry distinct Message-ID headers — colliding fixtures
+    // would mask a mapping bug where toRawInboundMessage produces a
+    // wrong/constant messageIdHeader per batch (used for the References/
+    // threading chain and the self-heal dedup fallback).
+    expect(new Set(result.messages.map((m) => m.messageIdHeader)).size).toBe(2);
+  });
+
+  test("fetch: incremental cursor filters uid <= lastUid + hasMore via maxMessages", async () => {
+    state.searchUids = [1, 2, 3, 4];
+    state.messages = [
+      {
+        uid: 2,
+        source: mime("two", "x"),
+        internalDate: new Date("2024-01-02T12:00:00Z"),
+      },
+      {
+        uid: 3,
+        source: mime("three", "y"),
+        internalDate: new Date("2024-01-03T12:00:00Z"),
+      },
+      {
+        uid: 4,
+        source: mime("four", "z"),
+        internalDate: new Date("2024-01-04T12:00:00Z"),
+      },
+    ];
+    const result = await imapInboundMailPlugin.fetch(
+      ctxWithDoc(goodDoc),
+      account,
+      { uidValidity: "17", lastUid: 1 },
+      { backfillWindowDays: 7, maxMessages: 2 },
+    );
+    // search returns 2,3,4 (> lastUid=1); maxMessages=2 → hasMore, uid 1
+    // filtered out and only the first 2 of the 3 remaining survive the cap.
+    expect(result.messages.map((m) => m.subject)).toEqual(["two", "three"]);
+    expect(result.hasMore).toBe(true);
+    expect(result.nextCursor).toEqual({ uidValidity: "17", lastUid: 3 });
+  });
+
+  test("fetch: UIDVALIDITY change → InboundCursorInvalidError", async () => {
+    try {
+      await imapInboundMailPlugin.fetch(
+        ctxWithDoc(goodDoc),
+        account,
+        { uidValidity: "16", lastUid: 1 },
+        { backfillWindowDays: 7, maxMessages: 50 },
+      );
+      expect.unreachable("expected fetch to throw");
+    } catch (e) {
+      expect(isInboundCursorInvalidError(e)).toBe(true);
+    }
+  });
+
+  test("fetch: network error → InboundTransientError", async () => {
+    state.connectError = new Error("ECONNREFUSED");
+    try {
+      await imapInboundMailPlugin.fetch(ctxWithDoc(goodDoc), account, null, {
+        backfillWindowDays: 7,
+        maxMessages: 50,
+      });
+      expect.unreachable("expected fetch to throw");
+    } catch (e) {
+      expect(isInboundTransientError(e)).toBe(true);
+    }
+  });
+
+  test("watch: exists → onMessages, stop() tears down", async () => {
+    expect(imapInboundMailPlugin.watch).toBeDefined();
+    const received: RawInboundMessage[][] = [];
+    const stop = await imapInboundMailPlugin.watch!(ctxWithDoc(goodDoc), account, {
+      onMessages: async (msgs) => {
+        received.push([...msgs]);
+      },
+      onError: () => {},
+    });
+
+    // New mail above uidNext-1 (uidNext=3 → nextUid starts at 3)
+    state.messages = [
+      {
+        uid: 3,
+        source: mime("pushed", "idle body"),
+        internalDate: new Date("2024-01-05T12:00:00Z"),
+      },
+    ];
+    lastIdleClient?.emit("exists");
+
+    // drainNew() does MIME-parsing before onMessages fires — a fixed sleep
+    // flakes on a loaded CI runner; poll instead.
+    await waitFor(() => received.some((batch) => batch.some((m) => m.subject === "pushed")));
+    expect(received.some((batch) => batch.some((m) => m.subject === "pushed"))).toBe(true);
+
+    await stop();
+  });
+
+  test("watch: client error → onError once", async () => {
+    let errors = 0;
+    const stop = await imapInboundMailPlugin.watch!(ctxWithDoc(goodDoc), account, {
+      onMessages: async () => {},
+      onError: () => {
+        errors += 1;
+      },
+    });
+    lastIdleClient?.emit("error", new Error("socket hang up"));
+    await waitFor(() => errors >= 1);
+    lastIdleClient?.emit("error", new Error("second"));
+    // Confirms onError stays unsubscribed after the first error — polls the
+    // same bounded window rather than betting on a fixed sleep outlasting it.
+    await waitFor(() => errors >= 2, 100);
+    expect(errors).toBe(1);
+    await stop().catch(() => {});
+  });
+});

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,283 @@
+// 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);
+  let lock: Awaited<ReturnType<typeof client.getMailboxLock>> | undefined;
+  try {
+    await client.connect();
+    lock = await client.getMailboxLock(IMAP_MAILBOX);
+    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);
+});