@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

package/packages/bundled-features/src/inbound-provider-imap/feature.ts

@@ -25,33 +25,43 @@
 
 import { mailAllowedPrivateHostsEnvSchema } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
+  assertRolesMatchFoundation,
   INBOUND_MAIL_PROVIDER_EXTENSION,
   type InboundFetchResult,
   type InboundMailContext,
   type InboundMailProviderPlugin,
+  type InboundMailRoleOptions,
   type MailAccountRecord,
   type RawInboundMessage,
+  type RejectedInboundMessage,
+  resolveInboundMailRoles,
+  roleDedupeOptions,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { instantToLegacyDate } from "@cosmicdrift/kumiko-framework/time";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { ImapFlow, MailboxObject } from "imapflow";
-import { connectMailboxHandler } from "./connect-mailbox.ts";
+import { createConnectMailboxHandler } from "./connect-mailbox.ts";
+import { createConnectMyMailboxHandler } from "./connect-my-mailbox.ts";
 import { FEATURE_NAME, IMAP_PROVIDER_KEY } from "./constants.ts";
 import { readCredentialDocument } from "./credential-document.ts";
+import { downloadBatch } from "./download-batch.ts";
+import { fetchMessageContent } from "./fetch-content.ts";
 import { INBOUND_PROVIDER_IMAP_I18N } from "./i18n.ts";
 import {
   assertUidValidity,
-  coerceDate,
+  closeOnAbort,
   connectOnce,
   createImapClient,
   IMAP_MAILBOX,
   imapMailHostGuard,
   mapImapError,
   parseImapCursor,
-  toRawInboundMessage,
 } from "./imap-client.ts";
-import { imapConnectScreen } from "./screens.ts";
+import { buildProviderMessageId, coerceDate, parseOrReject } from "./parse-message.ts";
+import { createReconnectMailboxHandler } from "./reconnect-mailbox.ts";
+import { createReconnectPrefillQuery } from "./reconnect-prefill.query.ts";
+import { createImapScreens } from "./screens.ts";
 import { sendFromImapAccount } from "./send-mail.ts";
 
 export { IMAP_PROVIDER_KEY } from "./constants.ts";
@@ -62,14 +72,31 @@ export { setImapMailHostLookup } from "./imap-client.ts";
 // fetch — inkrementeller UID-Sync
 // =============================================================================
 
+async function unknownUidsOf(
+  uids: readonly number[],
+  uidValidity: string,
+  filterUnknownMessageIds: (ids: readonly string[]) => Promise<ReadonlySet<string>>,
+): Promise<number[]> {
+  const unknownIds = await filterUnknownMessageIds(
+    uids.map((uid) => buildProviderMessageId(uidValidity, uid)),
+  );
+  return uids.filter((uid) => unknownIds.has(buildProviderMessageId(uidValidity, uid)));
+}
+
 async function fetchMessages(
   ctx: InboundMailContext,
   account: MailAccountRecord,
   cursor: Parameters<InboundMailProviderPlugin["fetch"]>[2],
-  opts: { readonly backfillWindowDays: number; readonly maxMessages: number },
+  opts: {
+    readonly backfillWindowDays: number;
+    readonly maxMessages: number;
+    readonly filterUnknownMessageIds?: (ids: readonly string[]) => Promise<ReadonlySet<string>>;
+    readonly signal?: AbortSignal;
+  },
 ): Promise<InboundFetchResult> {
   const doc = await readCredentialDocument(ctx, account);
   const client = await createImapClient(doc, imapMailHostGuard());
+  const stopWatchingAbort = closeOnAbort(client, opts.signal);
   let lock: Awaited<ReturnType<typeof client.getMailboxLock>> | undefined;
   try {
     await client.connect();
@@ -94,38 +121,31 @@ async function fetchMessages(
     }
     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;
-      }
-    }
+    // Known mails (ingested or quarantined) are not downloaded again; the cursor still moves past them.
+    const unknown = opts.filterUnknownMessageIds
+      ? await unknownUidsOf(uids, serverUidValidity, opts.filterUnknownMessageIds)
+      : uids;
+    const batch = unknown.slice(0, opts.maxMessages);
+    const hasMore = unknown.length > batch.length;
+    const { messages, rejected } = await downloadBatch(
+      client,
+      batch,
+      serverUidValidity,
+      account.trustedAuthservId ?? null,
+    );
+    // From the UIDs, not from what was downloaded: a known or skipped mail must not hold the cursor back.
+    const lastUid = Math.max(parsedCursor?.lastUid ?? 0, ...(hasMore ? batch : uids));
 
     return {
       messages,
-      nextCursor: { uidValidity: serverUidValidity, lastUid: maxUid },
+      ...(rejected.length > 0 && { rejected }),
+      nextCursor: { uidValidity: serverUidValidity, lastUid },
       hasMore,
     };
   } catch (err) {
     throw err instanceof Error && "kind" in err ? err : mapImapError(err, doc.host);
   } finally {
+    stopWatchingAbort();
     lock?.release();
     await client.logout().catch(() => {});
   }
@@ -140,7 +160,10 @@ async function watchMailbox(
   ctx: InboundMailContext,
   account: MailAccountRecord,
   handlers: {
-    readonly onMessages: (msgs: readonly RawInboundMessage[]) => Promise<void>;
+    readonly onMessages: (
+      msgs: readonly RawInboundMessage[],
+      rejected?: readonly RejectedInboundMessage[],
+    ) => Promise<void>;
     readonly onError: (err: unknown) => void;
   },
 ): Promise<() => Promise<void>> {
@@ -158,6 +181,7 @@ async function watchMailbox(
 
     const drainNew = async () => {
       const messages: RawInboundMessage[] = [];
+      const rejected: RejectedInboundMessage[] = [];
       let maxSeen = nextUid - 1;
       for await (const msg of client.fetch(
         `${nextUid}:*`,
@@ -166,18 +190,19 @@ async function watchMailbox(
       )) {
         // `N:*` gotcha (see fetch): filter out the previous last message.
         if (msg.uid < nextUid || !msg.source) continue;
-        messages.push(
-          await toRawInboundMessage({
-            source: msg.source,
-            uid: msg.uid,
-            uidValidity,
-            internalDate: coerceDate(msg.internalDate ?? undefined),
-          }),
-        );
+        const parsed = await parseOrReject({
+          source: msg.source,
+          uid: msg.uid,
+          uidValidity,
+          internalDate: coerceDate(msg.internalDate ?? undefined),
+          trustedAuthservId: account.trustedAuthservId ?? null,
+        });
+        if ("message" in parsed) messages.push(parsed.message);
+        else rejected.push(parsed.rejected);
         if (msg.uid > maxSeen) maxSeen = msg.uid;
       }
       nextUid = maxSeen + 1;
-      if (messages.length > 0) await handlers.onMessages(messages);
+      if (messages.length > 0 || rejected.length > 0) await handlers.onMessages(messages, rejected);
     };
 
     client.on("exists", () => {
@@ -236,6 +261,7 @@ export const imapInboundMailPlugin: InboundMailProviderPlugin = {
   verify: async (ctx, account) => connectOnce(await readCredentialDocument(ctx, account), false),
   probe: async (ctx, account) => connectOnce(await readCredentialDocument(ctx, account), true),
   fetch: fetchMessages,
+  fetchContent: fetchMessageContent,
   watch: watchMailbox,
   send: sendFromImapAccount,
   // No oauth block: password authentication runs through the credential
@@ -243,12 +269,13 @@ export const imapInboundMailPlugin: InboundMailProviderPlugin = {
   // the OAuth providers (M365/Gmail).
 };
 
-export function createInboundProviderImapFeature() {
+export function createInboundProviderImapFeature(options: InboundMailRoleOptions = {}) {
+  const roles = resolveInboundMailRoles(options);
   return 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. Tenant admins connect a mailbox through the "Connect mailbox" form on the mail accounts list (`connect-mailbox` checks the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.',
+        '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. Tenant admins connect a shared mailbox through the "Connect mailbox" form on the mail accounts list and members a personal one through the same form on "My mail accounts" (`connect-mailbox` and `connect-my-mailbox` check the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction; `reconnect-mailbox` does the same check for an existing mailbox with a sign-in error and overwrites its credential secret); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.',
       );
       r.uiHints({
         displayLabel: "Inbound Mail · IMAP",
@@ -259,10 +286,14 @@ export function createInboundProviderImapFeature() {
       r.requires({ features: ["secrets"] });
       r.envSchema(mailAllowedPrivateHostsEnvSchema);
       r.useExtension(INBOUND_MAIL_PROVIDER_EXTENSION, IMAP_PROVIDER_KEY, imapInboundMailPlugin);
-      r.writeHandler(connectMailboxHandler);
-      r.screen(imapConnectScreen);
+      r.bootCheck(({ features }) => assertRolesMatchFoundation(FEATURE_NAME, roles, features));
+      r.writeHandler(createConnectMailboxHandler(roles));
+      r.writeHandler(createConnectMyMailboxHandler(roles));
+      r.writeHandler(createReconnectMailboxHandler(roles));
+      r.queryHandler(createReconnectPrefillQuery(roles));
+      for (const screen of createImapScreens(roles)) r.screen(screen);
       r.translations({ keys: INBOUND_PROVIDER_IMAP_I18N });
     },
-    { dedupeOptions: {} },
+    { dedupeOptions: roleDedupeOptions(roles) },
   );
 }

package/packages/bundled-features/src/inbound-provider-imap/fetch-content.ts

@@ -0,0 +1,84 @@
+// Re-downloads already imported mails whose content was stored as snippet only. A provider message
+// id is "<uidValidity>:<uid>"; ids from another UIDVALIDITY or gone from the server are "missing"
+// (nothing to reload, ever), mails the parser cannot read are "rejected".
+
+import type {
+  InboundContentFetchResult,
+  InboundMailContext,
+  MailAccountRecord,
+  RawInboundMessage,
+  RejectedInboundMessage,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { InboundTransientError } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { readCredentialDocument } from "./credential-document.ts";
+import {
+  closeOnAbort,
+  createImapClient,
+  IMAP_MAILBOX,
+  imapMailHostGuard,
+  mapImapError,
+} from "./imap-client.ts";
+import { coerceDate, parseOrReject } from "./parse-message.ts";
+
+function uidOf(providerMessageId: string, serverUidValidity: string): number | null {
+  const separator = providerMessageId.lastIndexOf(":");
+  if (separator < 0 || providerMessageId.slice(0, separator) !== serverUidValidity) return null;
+  const uid = Number(providerMessageId.slice(separator + 1));
+  return Number.isInteger(uid) && uid > 0 ? uid : null;
+}
+
+export async function fetchMessageContent(
+  ctx: InboundMailContext,
+  account: MailAccountRecord,
+  providerMessageIds: readonly string[],
+  opts?: { readonly signal?: AbortSignal },
+): Promise<InboundContentFetchResult> {
+  const doc = await readCredentialDocument(ctx, account);
+  const client = await createImapClient(doc, imapMailHostGuard());
+  const stopWatchingAbort = closeOnAbort(client, opts?.signal);
+  let lock: Awaited<ReturnType<typeof client.getMailboxLock>> | undefined;
+  try {
+    await client.connect();
+    lock = await client.getMailboxLock(IMAP_MAILBOX);
+    const mailbox = client.mailbox;
+    if (typeof mailbox === "boolean") throw new InboundTransientError("mailbox not open");
+    const serverUidValidity = String(mailbox.uidValidity);
+    const idByUid = new Map<number, string>();
+    const missing: string[] = [];
+    for (const id of providerMessageIds) {
+      const uid = uidOf(id, serverUidValidity);
+      if (uid === null) missing.push(id);
+      else idByUid.set(uid, id);
+    }
+    const messages: RawInboundMessage[] = [];
+    const rejected: RejectedInboundMessage[] = [];
+    if (idByUid.size > 0) {
+      for await (const msg of client.fetch(
+        [...idByUid.keys()].join(","),
+        { uid: true, internalDate: true, source: true, envelope: true },
+        { uid: true },
+      )) {
+        if (!msg.source) continue;
+        const parsed = await parseOrReject({
+          source: msg.source,
+          uid: msg.uid,
+          uidValidity: serverUidValidity,
+          internalDate: coerceDate(msg.internalDate ?? undefined),
+          envelope: msg.envelope,
+        });
+        idByUid.delete(msg.uid);
+        if ("message" in parsed) messages.push(parsed.message);
+        else rejected.push(parsed.rejected);
+      }
+    }
+    // What the server did not return is gone (expunged since the import).
+    missing.push(...idByUid.values());
+    return { messages, missing, rejected };
+  } catch (err) {
+    throw err instanceof Error && "kind" in err ? err : mapImapError(err, doc.host);
+  } finally {
+    stopWatchingAbort();
+    lock?.release();
+    await client.logout().catch(() => {});
+  }
+}

package/packages/bundled-features/src/inbound-provider-imap/i18n.ts

@@ -1,13 +1,27 @@
-import { IMAP_CONNECT_SCREEN_ID } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import {
+  IMAP_CONNECT_SCREEN_ID,
+  IMAP_RECONNECT_SCREEN_ID,
+  MY_IMAP_CONNECT_SCREEN_ID,
+  MY_IMAP_RECONNECT_SCREEN_ID,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { ACTION_FORM_ENTITY } from "@cosmicdrift/kumiko-framework/ui-types";
 import { fieldLabelKey } from "@cosmicdrift/kumiko-renderer/headless";
-import { FEATURE_NAME, IMAP_CONNECT_ERRORS, SMTP_CONNECT_ERRORS } from "./constants.ts";
+import {
+  FEATURE_NAME,
+  IMAP_CONNECT_ERRORS,
+  IMAP_RECONNECT_ERRORS,
+  SMTP_CONNECT_ERRORS,
+} from "./constants.ts";
 
 const formFieldKey = (field: string): string =>
   fieldLabelKey(FEATURE_NAME, ACTION_FORM_ENTITY, field);
 
 export const INBOUND_PROVIDER_IMAP_I18N: Readonly<Record<string, { readonly en: string }>> = {
   [`screen:${IMAP_CONNECT_SCREEN_ID}.title`]: { en: "Connect mailbox" },
+  [`screen:${IMAP_RECONNECT_SCREEN_ID}.title`]: { en: "Reconnect mailbox" },
+  [`screen:${MY_IMAP_CONNECT_SCREEN_ID}.title`]: { en: "Connect mailbox" },
+  [`screen:${MY_IMAP_RECONNECT_SCREEN_ID}.title`]: { en: "Reconnect mailbox" },
+  [formFieldKey("accountId")]: { en: "Mailbox" },
   [formFieldKey("displayName")]: { en: "Name" },
   [formFieldKey("address")]: { en: "Email address" },
   [formFieldKey("host")]: { en: "IMAP server" },
@@ -21,7 +35,19 @@ export const INBOUND_PROVIDER_IMAP_I18N: Readonly<Record<string, { readonly en:
   "inboundMail.imap.connect.outgoingHint": {
     en: "Replies go out from this address over your own mail server, with the same user name and password. Leave the field empty if the server is called like the IMAP server, with smtp. instead of imap. Usually 587, even when your provider lists 465/SSL.",
   },
+  [formFieldKey("trustedAuthservId")]: { en: "Mail server ID" },
+  "inboundMail.imap.connect.senderCheck": { en: "Sender check" },
+  "inboundMail.imap.connect.senderCheckHint": {
+    en: "Identifier of the mail server from the Authentication-Results header, for example mx.example.com. Only with it the system checks whether a sender is genuine. Leave empty if unknown.",
+  },
   "inboundMail.imap.connect.submit": { en: "Check and connect" },
+  "inboundMail.imap.reconnect.hint": {
+    en: "The sign-in is checked before saving. Then the system fetches the mail again.",
+  },
+  "inboundMail.imap.reconnect.submit": { en: "Check and reconnect" },
+  [IMAP_RECONNECT_ERRORS.notPasswordImap.i18nKey]: {
+    en: "Only password IMAP mailboxes can be reconnected here.",
+  },
   [IMAP_CONNECT_ERRORS.hostUnreachable.i18nKey]: {
     en: "The IMAP server cannot be reached or is not allowed. Check the server name.",
   },

package/packages/bundled-features/src/inbound-provider-imap/imap-client.ts

@@ -2,6 +2,7 @@
 // Reference implementation: /Users/marc/code/doc-o-mat (HEINZ), but uses an
 // incremental UIDVALIDITY:lastUid cursor instead of a '1:*' full scan.
 
+import { isIP } from "node:net";
 import {
   BlockedHostError,
   type MailHostGuardOptions,
@@ -12,22 +13,24 @@ import {
   InboundAuthError,
   InboundCursorInvalidError,
   InboundTransientError,
-  type RawInboundMessage,
   type SyncCursorPayload,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-import { legacyDateToInstant } from "@cosmicdrift/kumiko-framework/time";
-import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { ImapFlow } from "imapflow";
-import { type AddressObject, type ParsedMail, simpleParser } from "mailparser";
 import type { ImapCredentialDocument } from "./credential-document.ts";
 
 export const IMAP_MAILBOX = "INBOX";
-const SNIPPET_MAX = 300;
 
 const log = createFallbackLogger("inbound-provider-imap");
 
+// Explicit instead of imapflow's defaults (90 s connect, 16 s greeting, 5 min idle socket): a
+// mailbox that stops answering must fail within a poll, not minutes later. The socket timeout
+// stays at the library's value because IDLE connections rely on it between server keep-alives.
+const IMAP_CONNECTION_TIMEOUT_MS = 20_000;
+const IMAP_GREETING_TIMEOUT_MS = 16_000;
+const IMAP_SOCKET_TIMEOUT_MS = 5 * 60 * 1000;
+
 // Tenant-visible for both branches below — must not reveal whether the host
 // was blocked (private/reserved range) or merely failed to resolve, and
 // must never include the host or the underlying error text. Server-side
@@ -80,17 +83,41 @@ export async function createImapClient(
     log.warn("host resolution failed", { host: doc.host, reason });
     throw new InboundTransientError(IMAP_HOST_UNREACHABLE_MESSAGE);
   }
-  return new ImapFlow({
+  return new ImapFlow(imapClientOptions(doc, target));
+}
+
+// For an IP-literal host imapflow itself sets `servername: false`, which Bun's tls.connect rejects
+// ("servername argument must be an string"). Overriding it through `tls` with undefined makes the
+// socket connect without SNI; the certificate is still verified against the IP. Not setting the
+// option at all (as for SMTP, where nodemailer omits a falsy servername) does not help here.
+export function imapClientOptions(
+  doc: ImapCredentialDocument,
+  target: Awaited<ReturnType<typeof resolveMailConnectTarget>>,
+) {
+  return {
     host: target.host,
     port: doc.port,
     secure: doc.secure,
     ...(target.servername && { servername: target.servername }),
+    ...(isIP(target.host) !== 0 && { tls: { servername: undefined } }),
     auth: doc.password
       ? { user: doc.user, pass: doc.password }
       : { user: doc.user, accessToken: doc.accessToken as string },
-    logger: false,
+    connectionTimeout: IMAP_CONNECTION_TIMEOUT_MS,
+    greetingTimeout: IMAP_GREETING_TIMEOUT_MS,
+    socketTimeout: IMAP_SOCKET_TIMEOUT_MS,
+    logger: false as const,
     emitLogs: false,
-  });
+  };
+}
+
+/** Drops the connection when the supervisor abandons the sync, so a hung command does not keep the socket open. */
+export function closeOnAbort(client: ImapFlow, signal: AbortSignal | undefined): () => void {
+  if (!signal) return () => {};
+  const close = () => client.close();
+  if (signal.aborted) close();
+  signal.addEventListener("abort", close, { once: true });
+  return () => signal.removeEventListener("abort", close);
 }
 
 /** Server-Fehler → typisierte Foundation-Fehlerklassen (Plan §2). */
@@ -155,79 +182,3 @@ export function assertUidValidity(cursor: ImapCursor | null, serverUidValidity:
     );
   }
 }
-
-// =============================================================================
-// Message-Normalisierung → RawInboundMessage
-// =============================================================================
-
-function stripAngles(id: string): string {
-  return id.replace(/^<|>$/g, "").trim();
-}
-
-/** Normalizes the References chain: mailparser returns string | string[]
- *  | undefined; when References is missing, In-Reply-To provides the thread
- *  anchor. */
-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 provides internalDate as either a Date or string depending on
- *  the code path. The string form is deliberately discarded (no date parsing
- *  in feature code, no-date-api); toRawInboundMessage then falls back to the
- *  mailparser Date header, which is always a real Date. */
-export function coerceDate(d: Date | string | undefined): Date | undefined {
-  return d instanceof Date ? d : undefined;
-}
-
-/** providerMessageId: a UID is unique only within a UIDVALIDITY; together,
- *  they form the stable 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 from imapflow/mailparser) → Temporal;
-    // when no date exists, Epoch is the honest marker.
-    receivedAtIso: (receivedAt
-      ? legacyDateToInstant(receivedAt)
-      : Temporal.Instant.fromEpochMilliseconds(0)
-    ).toString(),
-    rawMime: args.source,
-    scope: "inbox",
-  };
-}

package/packages/bundled-features/src/inbound-provider-imap/index.ts

@@ -13,9 +13,8 @@ export {
 } from "./feature.ts";
 export {
   assertUidValidity,
-  buildProviderMessageId,
   type ImapCursor,
   mapImapError,
-  normalizeReferences,
   parseImapCursor,
 } from "./imap-client.ts";
+export { buildProviderMessageId, normalizeReferences } from "./parse-message.ts";

package/packages/bundled-features/src/inbound-provider-imap/mime-content.ts

@@ -0,0 +1,85 @@
+// Turns a parsed MIME tree into the content the foundation stores: full text, HTML, real
+// attachments, and the attachments it deliberately leaves out. Pure; the parsing itself stays in
+// imap-client.ts.
+
+import type {
+  RawInboundAttachment,
+  SkippedInboundAttachment,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { type Attachment, type ParsedMail, simpleParser } from "mailparser";
+
+/** A forwarded mail inside a forwarded mail inside a forwarded mail is still read; deeper is skipped. */
+export const MIME_FORWARD_MAX_DEPTH = 3;
+
+const FORWARDED_MESSAGE_MIME = "message/rfc822";
+const FALLBACK_ATTACHMENT_NAME = "attachment";
+const FALLBACK_FORWARDED_NAME = "forwarded.eml";
+
+export type MailContent = {
+  readonly text: string;
+  readonly html: string | null;
+  readonly attachments: readonly RawInboundAttachment[];
+  readonly skipped: readonly SkippedInboundAttachment[];
+};
+
+// Signature logos and tracking pixels travel as inline images; a PDF with a Content-Id (Apple Mail
+// inlines PDFs that way) is a real document and must survive.
+function isInlineImage(attachment: Attachment): boolean {
+  if (!attachment.contentType.toLowerCase().startsWith("image/")) return false;
+  const referencedByBody = attachment.related === true;
+  const inlineWithContentId =
+    attachment.contentDisposition === "inline" && Boolean(attachment.contentId);
+  return referencedByBody || inlineWithContentId;
+}
+
+function forwardedHeader(inner: ParsedMail): string {
+  return `\n\n---------- Forwarded message ----------\nFrom: ${inner.from?.text ?? ""}\nSubject: ${inner.subject ?? ""}\n\n`;
+}
+
+async function readForwardedMail(
+  source: Buffer,
+  depth: number,
+): Promise<{ readonly header: string; readonly content: MailContent } | null> {
+  try {
+    const parsed = await simpleParser(source);
+    return { header: forwardedHeader(parsed), content: await extractMailContent(parsed, depth) };
+  } catch {
+    return null;
+  }
+}
+
+export async function extractMailContent(parsed: ParsedMail, depth = 0): Promise<MailContent> {
+  let text = parsed.text?.trim() ?? "";
+  const attachments: RawInboundAttachment[] = [];
+  const skipped: SkippedInboundAttachment[] = [];
+  for (const attachment of parsed.attachments) {
+    const mimeType = attachment.contentType;
+    if (isInlineImage(attachment)) continue;
+    if (mimeType.toLowerCase() === FORWARDED_MESSAGE_MIME) {
+      if (depth + 1 > MIME_FORWARD_MAX_DEPTH) {
+        skipped.push({ mimeType, size: attachment.size, reason: "nesting_too_deep" });
+        continue;
+      }
+      const inner = await readForwardedMail(attachment.content, depth + 1);
+      if (inner === null) {
+        // A forwarded mail the parser chokes on must not sink the outer mail: keep it as a plain .eml.
+        attachments.push({
+          fileName: attachment.filename ?? FALLBACK_FORWARDED_NAME,
+          mimeType,
+          data: attachment.content,
+        });
+        continue;
+      }
+      text += inner.header + inner.content.text;
+      attachments.push(...inner.content.attachments);
+      skipped.push(...inner.content.skipped);
+      continue;
+    }
+    attachments.push({
+      fileName: attachment.filename ?? FALLBACK_ATTACHMENT_NAME,
+      mimeType,
+      data: attachment.content,
+    });
+  }
+  return { text, html: parsed.html || null, attachments, skipped };
+}