@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

package/dist/inbound-provider-imap/i18n.js

@@ -1,10 +1,14 @@
-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.js";
+import { FEATURE_NAME, IMAP_CONNECT_ERRORS, IMAP_RECONNECT_ERRORS, SMTP_CONNECT_ERRORS, } from "./constants.js";
 const formFieldKey = (field) => fieldLabelKey(FEATURE_NAME, ACTION_FORM_ENTITY, field);
 export const INBOUND_PROVIDER_IMAP_I18N = {
     [`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" },
@@ -18,7 +22,19 @@ export const INBOUND_PROVIDER_IMAP_I18N = {
     "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/dist/inbound-provider-imap/imap-client.d.ts

@@ -1,5 +1,5 @@
-import { type MailHostGuardOptions } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
-import { type RawInboundMessage, type SyncCursorPayload } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { type MailHostGuardOptions, resolveMailConnectTarget } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import { type SyncCursorPayload } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { ImapFlow } from "imapflow";
 import type { ImapCredentialDocument } from "./credential-document.ts";
 export declare const IMAP_MAILBOX = "INBOX";
@@ -7,6 +7,31 @@ export declare const IMAP_HOST_UNREACHABLE_MESSAGE = "IMAP host is not reachable
 export declare function setImapMailHostLookup(fn: MailHostGuardOptions["lookupFn"]): void;
 export declare function imapMailHostGuard(): MailHostGuardOptions;
 export declare function createImapClient(doc: ImapCredentialDocument, hostGuard?: MailHostGuardOptions): Promise<ImapFlow>;
+export declare function imapClientOptions(doc: ImapCredentialDocument, target: Awaited<ReturnType<typeof resolveMailConnectTarget>>): {
+    host: string;
+    port: number;
+    secure: boolean;
+    servername?: string | undefined;
+    tls?: {
+        servername: undefined;
+    } | undefined;
+    auth: {
+        user: string;
+        pass: string;
+        accessToken?: undefined;
+    } | {
+        pass?: undefined;
+        user: string;
+        accessToken: string;
+    };
+    connectionTimeout: number;
+    greetingTimeout: number;
+    socketTimeout: number;
+    logger: false;
+    emitLogs: boolean;
+};
+/** Drops the connection when the supervisor abandons the sync, so a hung command does not keep the socket open. */
+export declare function closeOnAbort(client: ImapFlow, signal: AbortSignal | undefined): () => void;
 /** Server-Fehler → typisierte Foundation-Fehlerklassen (Plan §2). */
 export declare function connectOnce(doc: ImapCredentialDocument, examineInbox: boolean): Promise<void>;
 export declare function mapImapError(err: unknown, host: string): Error;
@@ -19,24 +44,3 @@ export declare function parseImapCursor(cursor: SyncCursorPayload | null): ImapC
  *  foundation resets the cursor and performs a full resync within the
  *  backfill window (deduplication catches duplicates). */
 export declare function assertUidValidity(cursor: ImapCursor | null, serverUidValidity: string): void;
-/** Normalizes the References chain: mailparser returns string | string[]
- *  | undefined; when References is missing, In-Reply-To provides the thread
- *  anchor. */
-export declare function normalizeReferences(parsed: {
-    references?: string | string[];
-    inReplyTo?: string;
-}): string[];
-/** 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 declare function coerceDate(d: Date | string | undefined): Date | undefined;
-/** providerMessageId: a UID is unique only within a UIDVALIDITY; together,
- *  they form the stable idempotency anchor. */
-export declare function buildProviderMessageId(uidValidity: string, uid: number): string;
-export declare function toRawInboundMessage(args: {
-    readonly source: Uint8Array;
-    readonly uid: number;
-    readonly uidValidity: string;
-    readonly internalDate: Date | undefined;
-}): Promise<RawInboundMessage>;

package/dist/inbound-provider-imap/imap-client.js

@@ -1,17 +1,20 @@
 // imapflow wiring and pure helpers for IMAP providers.
 // 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, readAllowedPrivateMailHostsFromEnv, resolveMailConnectTarget, } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { InboundAuthError, InboundCursorInvalidError, InboundTransientError, } 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 { simpleParser } from "mailparser";
 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
@@ -57,17 +60,38 @@ export async function createImapClient(doc, hostGuard = {}) {
         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, target) {
+    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 },
+        connectionTimeout: IMAP_CONNECTION_TIMEOUT_MS,
+        greetingTimeout: IMAP_GREETING_TIMEOUT_MS,
+        socketTimeout: IMAP_SOCKET_TIMEOUT_MS,
         logger: false,
         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, signal) {
+    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). */
 // examineInbox opens INBOX with EXAMINE instead of SELECT, so the system check never touches \Recent or flags.
@@ -118,65 +142,3 @@ export function assertUidValidity(cursor, serverUidValidity) {
         throw new InboundCursorInvalidError(`UIDVALIDITY changed (${cursor.uidValidity} → ${serverUidValidity}) — full resync required`);
     }
 }
-// =============================================================================
-// Message-Normalisierung → RawInboundMessage
-// =============================================================================
-function stripAngles(id) {
-    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) {
-    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) {
-    if (!a)
-        return [];
-    const arr = Array.isArray(a) ? a : [a];
-    return arr.map((x) => x.text).filter((t) => 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) {
-    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, uid) {
-    return `${uidValidity}:${uid}`;
-}
-export async function toRawInboundMessage(args) {
-    const parsed = 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/dist/inbound-provider-imap/index.d.ts

@@ -1,3 +1,4 @@
 export { type ImapCredentialDocument, imapCredentialDocumentSchema, type ParseCredentialResult, parseImapCredentialDocument, } from "./credential-document.ts";
 export { createInboundProviderImapFeature, IMAP_PROVIDER_KEY, setImapMailHostLookup, } from "./feature.ts";
-export { assertUidValidity, buildProviderMessageId, type ImapCursor, mapImapError, normalizeReferences, parseImapCursor, } from "./imap-client.ts";
+export { assertUidValidity, type ImapCursor, mapImapError, parseImapCursor, } from "./imap-client.ts";
+export { buildProviderMessageId, normalizeReferences } from "./parse-message.ts";

package/dist/inbound-provider-imap/index.js

@@ -1,4 +1,5 @@
 // Public API of the inbound-provider-imap bundled-feature.
 export { imapCredentialDocumentSchema, parseImapCredentialDocument, } from "./credential-document.js";
 export { createInboundProviderImapFeature, IMAP_PROVIDER_KEY, setImapMailHostLookup, } from "./feature.js";
-export { assertUidValidity, buildProviderMessageId, mapImapError, normalizeReferences, parseImapCursor, } from "./imap-client.js";
+export { assertUidValidity, mapImapError, parseImapCursor, } from "./imap-client.js";
+export { buildProviderMessageId, normalizeReferences } from "./parse-message.js";

package/dist/inbound-provider-imap/mime-content.d.ts

@@ -0,0 +1,11 @@
+import type { RawInboundAttachment, SkippedInboundAttachment } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { type ParsedMail } from "mailparser";
+/** A forwarded mail inside a forwarded mail inside a forwarded mail is still read; deeper is skipped. */
+export declare const MIME_FORWARD_MAX_DEPTH = 3;
+export type MailContent = {
+    readonly text: string;
+    readonly html: string | null;
+    readonly attachments: readonly RawInboundAttachment[];
+    readonly skipped: readonly SkippedInboundAttachment[];
+};
+export declare function extractMailContent(parsed: ParsedMail, depth?: number): Promise<MailContent>;

package/dist/inbound-provider-imap/mime-content.js

@@ -0,0 +1,66 @@
+// 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 { 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";
+// 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) {
+    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) {
+    return `\n\n---------- Forwarded message ----------\nFrom: ${inner.from?.text ?? ""}\nSubject: ${inner.subject ?? ""}\n\n`;
+}
+async function readForwardedMail(source, depth) {
+    try {
+        const parsed = await simpleParser(source);
+        return { header: forwardedHeader(parsed), content: await extractMailContent(parsed, depth) };
+    }
+    catch {
+        return null;
+    }
+}
+export async function extractMailContent(parsed, depth = 0) {
+    let text = parsed.text?.trim() ?? "";
+    const attachments = [];
+    const skipped = [];
+    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 };
+}

package/dist/inbound-provider-imap/parse-message.d.ts

@@ -0,0 +1,35 @@
+import type { RawInboundMessage, RejectedInboundMessage } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import type { MessageEnvelopeObject } from "imapflow";
+/** Normalizes the References chain: mailparser returns string | string[]
+ *  | undefined; when References is missing, In-Reply-To provides the thread
+ *  anchor. */
+export declare function normalizeReferences(parsed: {
+    references?: string | string[];
+    inReplyTo?: string;
+}): string[];
+/** 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 declare function coerceDate(d: Date | string | undefined): Date | undefined;
+/** providerMessageId: a UID is unique only within a UIDVALIDITY; together,
+ *  they form the stable idempotency anchor. */
+export declare function buildProviderMessageId(uidValidity: string, uid: number): string;
+export declare function toRawInboundMessage(args: {
+    readonly source: Uint8Array;
+    readonly uid: number;
+    readonly uidValidity: string;
+    readonly internalDate: Date | undefined;
+    /** IMAP envelope; lets a mail that cannot be parsed still show sender and subject. */
+    readonly envelope?: MessageEnvelopeObject | undefined;
+    /** authserv-id of the mailbox's own server; without it senderAuthentication is null. */
+    readonly trustedAuthservId?: string | null;
+}): Promise<RawInboundMessage>;
+export type ParsedOrRejected = {
+    readonly message: RawInboundMessage;
+} | {
+    readonly rejected: RejectedInboundMessage;
+};
+/** A mail the MIME parser cannot handle must not stop the mailbox: it is reported as rejected so the
+ *  foundation quarantines it and the cursor moves on. */
+export declare function parseOrReject(args: Parameters<typeof toRawInboundMessage>[0]): Promise<ParsedOrRejected>;

package/dist/inbound-provider-imap/parse-message.js

@@ -0,0 +1,113 @@
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { legacyDateToInstant } from "@cosmicdrift/kumiko-framework/time";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { simpleParser } from "mailparser";
+import { extractMailContent } from "./mime-content.js";
+import { senderAuthenticationOf } from "./sender-auth-headers.js";
+const SNIPPET_MAX = 300;
+const log = createFallbackLogger("inbound-provider-imap");
+// =============================================================================
+// Message-Normalisierung → RawInboundMessage
+// =============================================================================
+function stripAngles(id) {
+    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) {
+    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) {
+    if (!a)
+        return [];
+    const arr = Array.isArray(a) ? a : [a];
+    return arr.map((x) => x.text).filter((t) => 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) {
+    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, uid) {
+    return `${uidValidity}:${uid}`;
+}
+export async function toRawInboundMessage(args) {
+    const parsed = await simpleParser(Buffer.from(args.source));
+    const messageIdHeader = parsed.messageId ? stripAngles(parsed.messageId) : null;
+    const receivedAt = args.internalDate ?? parsed.date;
+    const content = await extractMailContent(parsed);
+    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(),
+        text: content.text,
+        ...(content.html !== null && { html: content.html }),
+        attachments: content.attachments,
+        skippedAttachments: content.skipped,
+        senderAuthentication: senderAuthenticationOf(parsed, args.trustedAuthservId ?? null),
+        rawMime: args.source,
+        scope: "inbox",
+    };
+}
+function envelopeAddresses(list) {
+    return (list ?? []).map((a) => a.address ?? "").filter((a) => a !== "");
+}
+function headersOfEnvelope(envelope, internalDate) {
+    const sender = envelope.from?.[0];
+    const receivedAt = internalDate ?? coerceDate(envelope.date);
+    return {
+        from: sender?.address ?? "",
+        to: envelopeAddresses(envelope.to),
+        cc: envelopeAddresses(envelope.cc),
+        subject: envelope.subject ?? "",
+        messageIdHeader: envelope.messageId ? stripAngles(envelope.messageId) : null,
+        receivedAtIso: receivedAt ? legacyDateToInstant(receivedAt).toString() : "",
+    };
+}
+/** A mail the MIME parser cannot handle must not stop the mailbox: it is reported as rejected so the
+ *  foundation quarantines it and the cursor moves on. */
+export async function parseOrReject(args) {
+    try {
+        return { message: await toRawInboundMessage(args) };
+    }
+    catch (err) {
+        // Class name only: parser messages can quote header content.
+        log.warn("mail could not be parsed", {
+            uid: args.uid,
+            error: err instanceof Error ? err.name : typeof err,
+        });
+        return {
+            rejected: {
+                providerMessageId: buildProviderMessageId(args.uidValidity, args.uid),
+                reason: "unparseable",
+                rawMime: args.source,
+                ...(args.envelope && { headers: headersOfEnvelope(args.envelope, args.internalDate) }),
+            },
+        };
+    }
+}

package/dist/inbound-provider-imap/reconnect-account.d.ts

@@ -0,0 +1,17 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { type WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
+type ReconnectAccountRow = {
+    readonly id: string;
+    readonly provider: string;
+    readonly authMethod: string;
+    readonly displayName: string | null;
+    readonly ownerUserId: string | null;
+    readonly status: string | null;
+    readonly trustedAuthservId: string | null;
+};
+export type ReconnectAccountLookup = {
+    readonly isSuccess: true;
+    readonly row: ReconnectAccountRow;
+} | WriteFailure;
+export declare function findReconnectableAccount(db: Pick<TenantDb, "fetchOne">, accountId: string): Promise<ReconnectAccountLookup>;
+export {};

package/dist/inbound-provider-imap/reconnect-account.js

@@ -0,0 +1,18 @@
+// Loads the mailbox a reconnect targets. The db is tenant-scoped, so another tenant's account id
+// finds nothing. A disconnected mailbox is reconnectable on purpose: it keeps its id, threads and
+// sync cursor, so reconnecting never re-imports history.
+import { InboundMailAuthMethods, mailAccountsProjectionTable, } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { failNotFound, UnprocessableError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import { IMAP_PROVIDER_KEY, IMAP_RECONNECT_ERRORS } from "./constants.js";
+export async function findReconnectableAccount(db, accountId) {
+    const row = await db.fetchOne(mailAccountsProjectionTable, {
+        id: accountId,
+    });
+    if (!row)
+        return failNotFound("mail-account", accountId);
+    if (row.provider !== IMAP_PROVIDER_KEY || row.authMethod !== InboundMailAuthMethods.password) {
+        const { reason, i18nKey } = IMAP_RECONNECT_ERRORS.notPasswordImap;
+        return writeFailure(new UnprocessableError(reason, { i18nKey, details: { accountId } }));
+    }
+    return { isSuccess: true, row };
+}

package/dist/inbound-provider-imap/reconnect-mailbox.d.ts

@@ -0,0 +1,14 @@
+import { type InboundMailRoles } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import * as z from "zod";
+export declare const createReconnectMailboxHandler: ({ memberRoles, adminRoles }: InboundMailRoles) => import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"reconnect-mailbox", z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodDefault<z.ZodNumber>;
+    user: z.ZodString;
+    password: z.ZodString;
+    smtpHost: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
+    smtpPort: z.ZodNumber;
+    trustedAuthservId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    accountId: z.ZodUUID;
+}, z.core.$strip>, {
+    accountId: string;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, null, undefined>;

package/dist/inbound-provider-imap/reconnect-mailbox.js

@@ -0,0 +1,71 @@
+// reconnect-mailbox: new credentials for an existing password IMAP mailbox, typically after the
+// account went to auth_error. The login is checked before the transaction opens; only then the
+// credential secret of the same account is overwritten and the account goes back to active (also from disconnected), both
+// on the request transaction, so a failure leaves status and secret as they were.
+import { InboundMailFoundationHandlers, inboundCredentialSecretKey, isMailAdmin, mayReactivateMailbox, } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { defineWriteHandler, } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { CREDENTIAL_PREVIEW, checkMailboxLogin, connectMailboxSchema, credentialDocumentOf, } from "./connect-mailbox.js";
+import { findReconnectableAccount } from "./reconnect-account.js";
+const reconnectMailboxSchema = connectMailboxSchema
+    .pick({
+    host: true,
+    port: true,
+    user: true,
+    password: true,
+    smtpHost: true,
+    smtpPort: true,
+    trustedAuthservId: true,
+})
+    .extend({ accountId: z.uuid() });
+const SECRET_TRANSACTION_REASON = "the credential secret is written on the request transaction so a failed reconnect rolls the account status back too";
+export const createReconnectMailboxHandler = ({ memberRoles, adminRoles }) => defineWriteHandler({
+    name: "reconnect-mailbox",
+    description: "Replaces the credentials of an existing password IMAP mailbox: checks the IMAP login and the SMTP login of the outgoing server first, then overwrites the credential secret of the same account and sets it back to active, keeping its threads and sync cursor.",
+    // The payload carries the plaintext password: as a tool call it would reach the model provider.
+    agent: { expose: false },
+    schema: reconnectMailboxSchema,
+    // Members: the owner re-arms a personal mailbox; the lookup gate keeps shared ones to admins.
+    access: { roles: [...memberRoles] },
+    // Same cap as connect: each call opens a connection to a host the caller picks.
+    rateLimit: { per: "tenant+handler", limit: 10, windowSeconds: 600 },
+    escapeHatch: { grants: ["unsafeRaw"], reason: SECRET_TRANSACTION_REASON },
+    beforeTransaction: async (event, ctx) => {
+        const lookup = await findReconnectableAccount(ctx.db, event.payload.accountId);
+        if (!lookup.isSuccess)
+            return lookup;
+        // Before the login check, so a denied caller cannot make the server probe a host; same answer as a missing account.
+        if (!mayReactivateMailbox(lookup.row.ownerUserId, ctx.user, adminRoles)) {
+            return failNotFound("mail-account", event.payload.accountId);
+        }
+        return checkMailboxLogin(credentialDocumentOf(event.payload), ctx.obs.log);
+    },
+    handler: async (event, ctx) => {
+        const { accountId } = event.payload;
+        // Secret first: reactivate from disconnected requires the credential to exist.
+        const secrets = requireSecretsContext({ secrets: ctx.services.secrets, user: ctx.user }, "reconnect-mailbox").withRunner(ctx.db.unsafeRaw());
+        await secrets.set(event.user.tenantId, inboundCredentialSecretKey(accountId), JSON.stringify(credentialDocumentOf(event.payload)), {
+            redact: () => CREDENTIAL_PREVIEW,
+            hint: `IMAP credentials for inbound mail account ${accountId}`,
+            updatedBy: event.user.id,
+        });
+        const reactivated = await ctx.dispatch.write(InboundMailFoundationHandlers.reactivateAccount, {
+            accountId,
+        });
+        if (!reactivated.isSuccess)
+            return reactivated;
+        // The sender-check policy is tenant-wide: only admins set it, the owner's form does not carry it.
+        if (isMailAdmin(event.user, adminRoles)) {
+            // The admin form shows the stored id, so an empty field means the admin cleared it.
+            const trusted = await ctx.dispatch.write(InboundMailFoundationHandlers.setTrustedAuthservId, {
+                accountId,
+                trustedAuthservId: event.payload.trustedAuthservId ?? null,
+            });
+            if (!trusted.isSuccess)
+                return trusted;
+        }
+        return { isSuccess: true, data: { accountId } };
+    },
+});

package/dist/inbound-provider-imap/reconnect-prefill.query.d.ts

@@ -0,0 +1,3 @@
+import { type InboundMailRoles } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+export declare const createReconnectPrefillQuery: ({ memberRoles, adminRoles, }: InboundMailRoles) => QueryHandlerDef;

package/dist/inbound-provider-imap/reconnect-prefill.query.js

@@ -0,0 +1,34 @@
+// Initial values of the reconnect form: the server settings of the stored credential, never the
+// password. A missing or unreadable credential leaves the fields empty for the admin to fill in.
+import { inboundCredentialSecretKey, mayReactivateMailbox, } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import * as z from "zod";
+import { FEATURE_NAME } from "./constants.js";
+import { parseImapCredentialDocument } from "./credential-document.js";
+import { findReconnectableAccount } from "./reconnect-account.js";
+const reconnectPrefillSchema = z.object({ accountId: z.uuid() }).strict();
+export const createReconnectPrefillQuery = ({ memberRoles, adminRoles, }) => ({
+    name: "reconnect-prefill",
+    schema: reconnectPrefillSchema,
+    access: { roles: [...memberRoles] },
+    // Only the reconnect form needs these settings; the agent has no write to use them with.
+    agent: { expose: false },
+    description: "Returns the server settings (IMAP host and port, user name, SMTP host and port, trusted authserv-id) stored for a password IMAP mailbox without its password, or null when the mailbox is not found or not a password IMAP mailbox; use it to prefill the reconnect form.",
+    handler: async (query, ctx) => {
+        const { accountId } = reconnectPrefillSchema.parse(query.payload);
+        const lookup = await findReconnectableAccount(ctx.db, accountId);
+        // Same null as for a missing account: a caller who may not reconnect it learns nothing about it.
+        if (!lookup.isSuccess || !mayReactivateMailbox(lookup.row.ownerUserId, ctx.user, adminRoles)) {
+            return null;
+        }
+        const secrets = requireSecretsContext({ secrets: ctx.services.secrets, user: ctx.user }, FEATURE_NAME);
+        const stored = await secrets.get(ctx.user.tenantId, inboundCredentialSecretKey(accountId));
+        const parsed = stored ? parseImapCredentialDocument(stored.reveal()) : undefined;
+        const displayName = lookup.row.displayName ?? "";
+        const trustedAuthservId = lookup.row.trustedAuthservId ?? "";
+        if (!parsed?.ok)
+            return { accountId, displayName, trustedAuthservId };
+        const { host, port, user, smtpHost, smtpPort } = parsed.doc;
+        return { accountId, displayName, host, port, user, smtpHost, smtpPort, trustedAuthservId };
+    },
+});