@remit/mailbox-service 0.0.112 → 0.0.113

package/dist/imapflow-connection.js

@@ -0,0 +1,1147 @@
+/**
+ * ImapFlow-based IMAP connection
+ *
+ * Modern async/await replacement for the node-imap based ImapConnection.
+ * Provides the same interface but uses ImapFlow under the hood.
+ */
+import { Readable } from "node:stream";
+import { ImapFlow } from "imapflow";
+import { simpleParser } from "mailparser";
+import { MailConnectionError } from "./types.js";
+/**
+ * Convert an envelope date into an ISO string, tolerating non-Date values.
+ *
+ * imapflow types `envelope.date` as a Date, but a malformed `Date:` header can
+ * leave it as a string or other value at runtime. Returns "" for absent or
+ * invalid dates so one bad header never poisons the whole fetch batch.
+ */
+export const toIsoDateString = (value) => {
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? "" : value.toISOString();
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        const date = new Date(value);
+        return Number.isNaN(date.getTime()) ? "" : date.toISOString();
+    }
+    return "";
+};
+/**
+ * Coerce an IMAP INTERNALDATE into a valid `Date`, tolerating malformed input.
+ *
+ * INTERNALDATE is the server's receive time and is almost always a clean Date.
+ * But a broken server (or an unexpected imapflow runtime value) can yield a
+ * string that `new Date` cannot parse, or a wholly unexpected type. Either way
+ * `getTime()` would be `NaN`, which is the message's date-of-last-resort — it
+ * is the fallback `parseHeaderDate` uses and is stored as the message's
+ * `internalDate` — so a `NaN` here silently corrupts every downstream date and
+ * gets rejected by ElectroDB, permanently failing the message.
+ *
+ * When the value cannot produce a valid Date we fall back to `now` so the
+ * message still syncs with an approximate receive time rather than being
+ * dropped. Returns `null` only for a genuinely absent value, which the caller
+ * skips (a transient imapflow artifact, see #408 — not bad data).
+ */
+export const toInternalDate = (value) => {
+    if (value == null)
+        return null;
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? new Date() : value;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        const date = new Date(value);
+        return Number.isNaN(date.getTime()) ? new Date() : date;
+    }
+    return new Date();
+};
+const FLAG_CRITERIA = {
+    ALL: {},
+    SEEN: { seen: true },
+    UNSEEN: { seen: false },
+    FLAGGED: { flagged: true },
+    UNFLAGGED: { flagged: false },
+    DELETED: { deleted: true },
+    UNDELETED: { deleted: false },
+    ANSWERED: { answered: true },
+    UNANSWERED: { answered: false },
+    DRAFT: { draft: true },
+    UNDRAFT: { draft: false },
+};
+const VALUE_CRITERIA = {
+    UID: "uid",
+    FROM: "from",
+    TO: "to",
+    SUBJECT: "subject",
+    SINCE: "since",
+    BEFORE: "before",
+};
+const unsupported = (criterion) => new Error(`Unsupported IMAP search criterion ${JSON.stringify(criterion)} — dropping it would widen the query to SEARCH ALL`);
+const applyValueCriterion = (result, header, criterion) => {
+    const [key, ...values] = criterion;
+    if (typeof key !== "string")
+        throw unsupported(criterion);
+    if (key.toUpperCase() === "HEADER") {
+        const [name, value] = values;
+        if (values.length !== 2 || typeof name !== "string") {
+            throw unsupported(criterion);
+        }
+        if (typeof value !== "string" && value !== true) {
+            throw unsupported(criterion);
+        }
+        header.set(name.toLowerCase(), value === true ? "" : value);
+        return;
+    }
+    const field = VALUE_CRITERIA[key.toUpperCase()];
+    if (field === undefined || values.length !== 1)
+        throw unsupported(criterion);
+    result[field] = values[0];
+};
+/**
+ * Compile node-imap style search criteria into an ImapFlow search object.
+ *
+ * A criterion this does not understand throws, and so does an empty criteria
+ * list. imapflow reads an empty object as `SEARCH ALL`
+ * (`imapflow/lib/commands/search.js`), so quietly skipping one turns a narrow
+ * probe into "every message in the mailbox" — the reconcile and move paths then
+ * act on a stranger's UID (#912). Header names accumulate in a Map so that a
+ * name like `__proto__` lands as a query term rather than hitting the
+ * prototype setter and vanishing.
+ *
+ * Values travel as structured tokens, never interpolated into a criterion
+ * string, so a quote or a CRLF in a header value cannot alter the query.
+ */
+export const convertSearchCriteria = (criteria) => {
+    if (criteria.length === 0) {
+        throw new Error("Empty IMAP search criteria list — it would compile to SEARCH ALL");
+    }
+    const result = {};
+    const header = new Map();
+    for (const criterion of criteria) {
+        if (typeof criterion === "string") {
+            const flags = FLAG_CRITERIA[criterion.toUpperCase()];
+            if (flags === undefined)
+                throw unsupported(criterion);
+            Object.assign(result, flags);
+            continue;
+        }
+        if (Array.isArray(criterion)) {
+            applyValueCriterion(result, header, criterion);
+            continue;
+        }
+        throw unsupported(criterion);
+    }
+    if (header.size > 0)
+        result.header = Object.fromEntries(header);
+    return result;
+};
+/**
+ * ImapFlow-based IMAP connection
+ *
+ * Drop-in replacement for ImapConnection using the ImapFlow library.
+ * Benefits:
+ * - Native async/await API (no callback wrapping)
+ * - Built-in envelope parsing that works with mokapi
+ * - Proper IDLE support with events
+ * - Built-in TypeScript types
+ * - Active maintenance
+ */
+export class ImapFlowConnection {
+    client = null;
+    _state = "disconnected";
+    config;
+    currentMailbox = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Current connection state
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Whether the connection is established and authenticated
+     */
+    get isConnected() {
+        return this._state === "authenticated";
+    }
+    /**
+     * Connect to the IMAP server with retry logic.
+     *
+     * Retries up to 3 times with exponential backoff (1s, 2s, 4s) on connection errors.
+     * Authentication errors are not retried.
+     */
+    connect = async () => {
+        if (this.client) {
+            throw new Error("Already connected");
+        }
+        const maxRetries = 3;
+        const baseDelayMs = 1000;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                await this.attemptConnect();
+                return;
+            }
+            catch (error) {
+                const classified = classifyImapError(error, `${this.config.host}:${this.config.port}`);
+                // Auth errors won't fix themselves on retry — throw immediately.
+                if (classified?.kind === "auth") {
+                    throw classified;
+                }
+                // Final attempt exhausted: throw the classified error if we have
+                // one (network failures), otherwise let the raw error bubble.
+                if (attempt === maxRetries) {
+                    throw classified ?? error;
+                }
+                // Network and unknown errors fall through to retry-with-backoff.
+                // Exponential backoff: 1s, 2s, 4s
+                const delay = baseDelayMs * 2 ** (attempt - 1);
+                await this.sleep(delay);
+                // Reset state for retry
+                this.cleanup();
+            }
+        }
+    };
+    /**
+     * Single connection attempt
+     */
+    attemptConnect = async () => {
+        this._state = "connecting";
+        // Determine TLS options
+        // When secure is false, STARTTLS may still be used, so we need to handle self-signed certs
+        const tlsOptions = this.config.tlsOptions
+            ? {
+                rejectUnauthorized: this.config.tlsOptions.rejectUnauthorized ?? true,
+            }
+            : !this.config.tls
+                ? {
+                    // Allow self-signed certs when TLS is disabled (for STARTTLS)
+                    rejectUnauthorized: false,
+                }
+                : undefined;
+        const auth = buildImapAuth(this.config.user, this.config.credentials);
+        this.client = new ImapFlow({
+            host: this.config.host,
+            port: this.config.port,
+            secure: this.config.tls,
+            servername: this.config.tlsOptions?.servername,
+            auth,
+            tls: tlsOptions,
+            // Disable auto IDLE to work around servers that don't handle IDLE correctly
+            // This is equivalent to node-imap's forceNoop: true
+            disableAutoIdle: true,
+            logger: false, // Disable verbose logging
+        });
+        this.client.on("close", () => {
+            this._state = "disconnected";
+            this.client = null;
+            this.currentMailbox = null;
+        });
+        this.client.on("error", () => {
+            this._state = "error";
+        });
+        await this.client.connect();
+        this._state = "authenticated";
+    };
+    /**
+     * Cleanup client state for retry
+     */
+    cleanup = () => {
+        if (this.client) {
+            this.client.close();
+            this.client = null;
+        }
+        this._state = "disconnected";
+        this.currentMailbox = null;
+    };
+    /**
+     * Sleep for a specified duration
+     */
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    /**
+     * Disconnect from the IMAP server
+     */
+    disconnect = async () => {
+        if (!this.client) {
+            return;
+        }
+        const client = this.client;
+        // Use a timeout to avoid hanging on logout
+        const timeoutPromise = new Promise((resolve) => {
+            setTimeout(() => {
+                // Force close if logout doesn't complete
+                client.close();
+                resolve();
+            }, 5000);
+        });
+        try {
+            await Promise.race([client.logout(), timeoutPromise]);
+        }
+        catch {
+            // Ignore errors during disconnect, force close
+            client.close();
+        }
+        finally {
+            this._state = "disconnected";
+            this.client = null;
+            this.currentMailbox = null;
+        }
+    };
+    /**
+     * Get IMAP namespaces
+     *
+     * Note: ImapFlow doesn't expose namespaces directly, so we return
+     * the default namespace. The mailbox listing works without explicit
+     * namespace handling in ImapFlow.
+     */
+    getNamespaces = async () => {
+        this.ensureConnected();
+        // ImapFlow doesn't expose NAMESPACE info, return defaults
+        // This is sufficient as ImapFlow handles namespaces internally
+        return {
+            personal: [{ prefix: "", delimiter: "/" }],
+            other: [],
+            shared: [],
+        };
+    };
+    /**
+     * List all mailboxes as a flat list, preserving original paths from server.
+     * This avoids path corruption from split/join operations.
+     *
+     * @param nsPrefix - Optional namespace prefix to filter mailboxes
+     */
+    listMailboxes = async (nsPrefix) => {
+        this.ensureConnected();
+        const mailboxes = await this.client?.list();
+        if (!mailboxes) {
+            return [];
+        }
+        const result = [];
+        for (const mailbox of mailboxes) {
+            // Filter by namespace prefix if provided
+            if (nsPrefix !== undefined && !mailbox.path.startsWith(nsPrefix)) {
+                continue;
+            }
+            // Extract name from path (last component)
+            const pathParts = mailbox.path.split(mailbox.delimiter);
+            const name = pathParts[pathParts.length - 1] || mailbox.path;
+            const parentPath = pathParts.length > 1
+                ? pathParts.slice(0, -1).join(mailbox.delimiter)
+                : null;
+            result.push({
+                fullPath: mailbox.path, // Use original path from server
+                name,
+                delimiter: mailbox.delimiter,
+                attributes: this.convertFlags(mailbox.flags),
+                parentPath,
+            });
+        }
+        return result;
+    };
+    /**
+     * Convert ImapFlow flags Set to string array
+     */
+    convertFlags = (flags) => {
+        if (!flags)
+            return [];
+        return Array.from(flags);
+    };
+    /**
+     * Open a mailbox for reading
+     *
+     * @param mailboxPath - Full path to the mailbox (e.g., "INBOX", "[Gmail]/Sent")
+     * @param readOnly - Whether to open read-only (default: true)
+     */
+    openBox = async (mailboxPath, readOnly = true) => {
+        this.ensureConnected();
+        // Idempotency guard: re-selecting the currently-open mailbox is a no-op
+        // SELECT on the wire. `mailbox` exposes the live, already-selected box, so
+        // we can return its status without paying for another round-trip — this is
+        // what lets a batch issue one SELECT and many fetches on the same box.
+        if (this.currentMailbox === mailboxPath && this.client?.mailbox) {
+            return this.toBoxStatus(this.client.mailbox, readOnly);
+        }
+        const mailbox = await this.client?.mailboxOpen(mailboxPath, {
+            readOnly,
+        });
+        if (!mailbox) {
+            throw new Error(`Failed to open mailbox: ${mailboxPath}`);
+        }
+        this.currentMailbox = mailboxPath;
+        return this.toBoxStatus(mailbox, readOnly);
+    };
+    /**
+     * Build an ImapBoxStatus from an imapflow MailboxObject.
+     */
+    toBoxStatus = (mailbox, readOnly) => {
+        const pathParts = mailbox.path.split(mailbox.delimiter);
+        const name = pathParts[pathParts.length - 1] || mailbox.path;
+        return {
+            name,
+            readOnly: mailbox.readOnly ?? readOnly,
+            uidvalidity: Number(mailbox.uidValidity),
+            uidnext: mailbox.uidNext,
+            flags: Array.from(mailbox.flags || []),
+            permFlags: Array.from(mailbox.permanentFlags || []),
+            persistentUIDs: true, // ImapFlow assumes persistent UIDs
+            messages: {
+                total: mailbox.exists,
+                new: 0, // ImapFlow doesn't provide unseen count on open
+            },
+            newKeywords: mailbox.permanentFlags?.has("\\*") ?? false,
+        };
+    };
+    /**
+     * Close the currently open mailbox
+     *
+     * @param _expunge - Whether to permanently remove deleted messages (not used in ImapFlow)
+     */
+    closeBox = async (_expunge = false) => {
+        this.ensureConnected();
+        if (this.currentMailbox) {
+            await this.client?.mailboxClose();
+            this.currentMailbox = null;
+        }
+    };
+    /**
+     * Search for messages, answering UIDs.
+     *
+     * imapflow answers a successful SEARCH with an array — empty when the
+     * server matched nothing — and `false` when the command failed or no
+     * mailbox was selected. Collapsing the two into `[]` makes a failed SEARCH
+     * indistinguishable from an empty mailbox, and every caller here acts on
+     * emptiness by deleting something: the cursor rebuild reads it as "every
+     * local row is stale", and {@link isMessageGoneFromOpenMailbox} reads it as
+     * "this message is gone". A failure therefore throws.
+     */
+    search = async (criteria) => {
+        this.ensureConnected();
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        const searchQuery = convertSearchCriteria(criteria);
+        const result = await this.client?.search(searchQuery, { uid: true });
+        if (!Array.isArray(result)) {
+            throw new Error(`IMAP SEARCH failed in mailbox ${this.currentMailbox}`);
+        }
+        return result;
+    };
+    /**
+     * Fetch messages by UID
+     *
+     * Uses ImapFlow's native envelope parsing which works correctly
+     * with all IMAP servers including mokapi.
+     */
+    fetchMessages = async (uids) => {
+        this.ensureConnected();
+        if (uids.length === 0) {
+            return [];
+        }
+        return this.runMessageFetch(uids.join(","), {});
+    };
+    /**
+     * True when this session negotiated CONDSTORE (RFC 7162) and the open
+     * mailbox keeps persistent mod-sequences.
+     *
+     * Both halves matter. `enabled` reflects the ENABLE exchange, not merely
+     * the advertised capability, and a server may still answer NOMODSEQ for an
+     * individual mailbox — in which case RFC 7162 Section 3.1.2.2 requires it
+     * to reject CHANGEDSINCE with a BAD response.
+     */
+    supportsCondstore = () => {
+        const { client } = this;
+        if (!client?.mailbox)
+            return false;
+        return client.enabled.has("CONDSTORE") && !client.mailbox.noModseq;
+    };
+    /**
+     * FETCH everything in the open mailbox whose MODSEQ is strictly greater
+     * than `sinceModseq` — new arrivals and metadata changes to messages
+     * already synced, in one pass over the whole UID space.
+     *
+     * The CONDSTORE guard is load-bearing rather than defensive: imapflow drops
+     * the CHANGEDSINCE modifier when the extension is unavailable, so the same
+     * call would degrade into a fetch of every message in the mailbox.
+     */
+    fetchMessagesChangedSince = async (sinceModseq) => {
+        this.ensureConnected();
+        if (!this.supportsCondstore()) {
+            throw new Error("CHANGEDSINCE requires CONDSTORE on both the session and the open mailbox");
+        }
+        return this.runMessageFetch("1:*", { changedSince: sinceModseq });
+    };
+    /**
+     * One UID FETCH over `range`, mapped to {@link ImapMessage}. The shared
+     * body of {@link fetchMessages} and {@link fetchMessagesChangedSince} —
+     * both need identical message shapes and differ only in what they select.
+     */
+    runMessageFetch = async (range, options) => {
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        const messages = [];
+        const fetchIterator = client.fetch(range, {
+            uid: true,
+            flags: true,
+            envelope: true,
+            bodyStructure: true,
+            internalDate: true,
+            size: true,
+            headers: ["references"],
+        }, { uid: true, ...options });
+        // Connection may have been lost - fetch returns an async iterable
+        if (!fetchIterator) {
+            throw new Error(`IMAP connection lost while fetching messages: ${range}`);
+        }
+        for await (const msg of fetchIterator) {
+            // imapflow occasionally yields a row with undefined uid or internalDate
+            // on back-to-back FETCH calls (e.g. after a body-fetch on the same UID).
+            // See #408 for the investigation. This is the client library glitching,
+            // not the message being malformed, so the row is dropped rather than
+            // quarantined — recording it as a defective message would advance a
+            // cursor past mail that is fine (issue #72).
+            //
+            // Dropping it is only safe because the caller treats a requested UID
+            // with no row as unconsumed and holds its watermark below it. It used
+            // to advance regardless, which is how a transient client glitch turned
+            // into a message never fetched again.
+            if (msg.uid == null || msg.internalDate == null) {
+                continue;
+            }
+            // Coerce INTERNALDATE without ever throwing: a malformed value must not
+            // abort the whole fetch batch. A bad value falls back to now; an absent
+            // one cannot reach here, having been dropped above.
+            const internalDate = toInternalDate(msg.internalDate) ?? new Date();
+            // Parse References header if present
+            const references = await this.parseReferencesHeader(msg.headers);
+            messages.push({
+                uid: msg.uid,
+                seq: msg.seq,
+                flags: Array.from(msg.flags || []),
+                internalDate,
+                size: msg.size ?? 0,
+                envelope: this.convertEnvelope(msg.envelope),
+                references,
+                bodyStructure: msg.bodyStructure,
+                ...(msg.modseq != null ? { modseq: msg.modseq.toString() } : {}),
+            });
+        }
+        return messages;
+    };
+    /**
+     * Cheap envelope-only FETCH for the UIDVALIDITY cursor rebuild (#1272):
+     * UID + Message-ID + INTERNALDATE only — no flags, no BODYSTRUCTURE, no
+     * References header, no body. Deliberately lighter than {@link
+     * fetchMessages} so a rebuild pass over a large mailbox stays cheap (epic
+     * #1281 invariant 6).
+     */
+    fetchEnvelopeSnapshots = async (uids) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        if (uids.length === 0) {
+            return [];
+        }
+        const uidRange = uids.join(",");
+        const fetchIterator = client.fetch(uidRange, { uid: true, envelope: true, internalDate: true }, { uid: true });
+        if (!fetchIterator) {
+            throw new Error(`IMAP connection lost while fetching envelope snapshots: ${uidRange}`);
+        }
+        const snapshots = [];
+        for await (const msg of fetchIterator) {
+            // Same defensive skip as fetchMessages (#408) — an occasional row
+            // with no uid/internalDate must not abort the whole batch.
+            if (msg.uid == null || msg.internalDate == null) {
+                continue;
+            }
+            const internalDate = toInternalDate(msg.internalDate);
+            if (internalDate === null) {
+                continue;
+            }
+            snapshots.push({
+                uid: msg.uid,
+                messageId: msg.envelope?.messageId ?? "",
+                internalDate,
+            });
+        }
+        return snapshots;
+    };
+    /**
+     * Fetch the full message body (RFC822 source) for a single message by UID.
+     *
+     * @param uid - The UID of the message to fetch
+     * @returns The raw message body, or null when the UID FETCH matched no message
+     */
+    fetchMessageBody = async (uid) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        const result = await client.download(String(uid), undefined, {
+            uid: true,
+        });
+        if (result?.content) {
+            const chunks = [];
+            for await (const chunk of result.content) {
+                chunks.push(chunk);
+            }
+            return Buffer.concat(chunks);
+        }
+        if (!client.usable || !client.mailbox) {
+            throw new MailConnectionError("network", `IMAP connection lost while downloading message UID ${uid}`);
+        }
+        return null;
+    };
+    /**
+     * Fetch full message bodies (RFC822 source) for many UIDs in ONE pipelined
+     * ranged UID FETCH on a single connection — the desktop-client pattern.
+     *
+     * Mirrors `fetchMessages`: one comma-joined UID range, one `client.fetch`,
+     * one SELECT (the caller opens the box once for the whole batch). Yields
+     * `{ uid, source }` as each message arrives so the caller can stream each
+     * body straight to storage without buffering the whole batch.
+     *
+     * `source` is a readable stream over the message bytes — callers must
+     * consume it (e.g. pipe to an upload) before requesting the next item.
+     */
+    async *fetchMessageBodies(uids) {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        if (uids.length === 0) {
+            return;
+        }
+        const uidRange = uids.join(",");
+        const fetchIterator = client.fetch(uidRange, { uid: true, source: true }, { uid: true });
+        if (!fetchIterator) {
+            throw new MailConnectionError("network", `IMAP connection lost while fetching message bodies: ${uidRange}`);
+        }
+        try {
+            for await (const msg of fetchIterator) {
+                // imapflow can yield a row with an undefined uid or no source on
+                // back-to-back FETCH calls, and Dovecot answers `source: false` for a
+                // message another client expunged; skip it rather than crash the batch
+                // — the caller treats any UID it never sees as failed and re-enqueues
+                // it. See #408.
+                if (msg.uid == null || !msg.source) {
+                    continue;
+                }
+                yield { uid: msg.uid, source: Readable.from(msg.source) };
+            }
+        }
+        catch (error) {
+            // A mid-stream socket drop surfaces as imapflow's
+            // `new Error("Connection closed")` with code `EConnectionClosed` — a
+            // string the rest of the code never matches on. Re-throw it as the
+            // typed MailConnectionError so the caller's fail-fast path triggers and
+            // re-enqueues the not-yet-yielded UIDs instead of failing the record.
+            throw (classifyImapError(error, `${this.config.host}:${this.config.port}`) ??
+                error);
+        }
+    }
+    /**
+     * Parse the References header from IMAP headers buffer.
+     * Returns an array of Message-IDs, with the first being the thread root.
+     */
+    parseReferencesHeader = async (headers) => {
+        if (!headers)
+            return undefined;
+        // Raw header bytes are untrusted. simpleParser is tolerant but can still
+        // throw on sufficiently broken input; a throw here would abort the whole
+        // fetch batch. Missing references just means "no thread parent", so on any
+        // parse failure treat the message as a thread root rather than crashing.
+        const parsed = await simpleParser(headers).catch(() => null);
+        if (!parsed?.references)
+            return undefined;
+        // mailparser returns references as string or array
+        if (Array.isArray(parsed.references)) {
+            return parsed.references.length > 0 ? parsed.references : undefined;
+        }
+        // Single reference as string
+        return [parsed.references];
+    };
+    /**
+     * Convert ImapFlow envelope to our ImapEnvelope format
+     */
+    convertEnvelope = (envelope) => {
+        // An absent ENVELOPE stays absent. Synthesising an empty one here made
+        // every `if (!msg.envelope)` guard downstream unreachable, so a FETCH row
+        // that carried no envelope was saved as a row with no sender, no subject
+        // and no date, keyed by the `generated:` fallback — indistinguishable
+        // from a real message. The field is optional on `ImapMessage` precisely
+        // so callers can see the difference (issue #72).
+        if (!envelope)
+            return undefined;
+        const convertAddresses = (addrs) => {
+            if (!addrs)
+                return [];
+            return addrs
+                .filter((a) => a.address)
+                .map((a) => {
+                const [mailbox, host] = (a.address || "").split("@");
+                return {
+                    name: a.name || undefined,
+                    mailbox: mailbox || "",
+                    host: host || "",
+                };
+            });
+        };
+        return {
+            date: toIsoDateString(envelope.date),
+            subject: envelope.subject ?? "",
+            from: convertAddresses(envelope.from),
+            sender: convertAddresses(envelope.sender),
+            replyTo: convertAddresses(envelope.replyTo),
+            to: convertAddresses(envelope.to),
+            cc: convertAddresses(envelope.cc),
+            bcc: convertAddresses(envelope.bcc),
+            inReplyTo: envelope.inReplyTo ?? "",
+            messageId: envelope.messageId ?? "",
+        };
+    };
+    /**
+     * Add flags to messages by UID.
+     * Requires mailbox to be open (not read-only).
+     *
+     * @param uids - Array of message UIDs
+     * @param flags - Array of flags to add (e.g., ["\\Seen", "\\Flagged"])
+     */
+    addFlags = async (uids, flags) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        if (uids.length === 0 || flags.length === 0) {
+            return;
+        }
+        const uidRange = uids.join(",");
+        await client.messageFlagsAdd(uidRange, flags, { uid: true });
+    };
+    /**
+     * Remove flags from messages by UID.
+     * Requires mailbox to be open (not read-only).
+     *
+     * @param uids - Array of message UIDs
+     * @param flags - Array of flags to remove (e.g., ["\\Seen", "\\Flagged"])
+     */
+    removeFlags = async (uids, flags) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        if (uids.length === 0 || flags.length === 0) {
+            return;
+        }
+        const uidRange = uids.join(",");
+        await client.messageFlagsRemove(uidRange, flags, { uid: true });
+    };
+    /**
+     * Replace all flags on messages by UID.
+     * Requires mailbox to be open (not read-only).
+     *
+     * @param uids - Array of message UIDs
+     * @param flags - Array of flags to set (replaces all existing flags)
+     */
+    setFlags = async (uids, flags) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        if (uids.length === 0) {
+            return;
+        }
+        const uidRange = uids.join(",");
+        await client.messageFlagsSet(uidRange, flags, { uid: true });
+    };
+    /**
+     * Create a new mailbox.
+     *
+     * @param path - Full path of the mailbox to create (e.g., "Projects/ClientA")
+     * @returns Object with path and whether it was created (false if already exists)
+     */
+    createMailbox = async (path) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        const result = await client.mailboxCreate(path);
+        return {
+            path: result.path,
+            created: result.created ?? true,
+        };
+    };
+    /**
+     * Delete a mailbox.
+     *
+     * @param path - Full path of the mailbox to delete
+     * @returns Object with the deleted path
+     */
+    deleteMailbox = async (path) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        // Cannot delete INBOX
+        if (path.toUpperCase() === "INBOX") {
+            throw new Error("Cannot delete INBOX");
+        }
+        const result = await client.mailboxDelete(path);
+        return { path: result.path };
+    };
+    /**
+     * Rename a mailbox.
+     *
+     * @param oldPath - Current path of the mailbox
+     * @param newPath - New path for the mailbox
+     * @returns Object with old and new paths
+     */
+    renameMailbox = async (oldPath, newPath) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        const result = await client.mailboxRename(oldPath, newPath);
+        // `mailboxRename` resolves `undefined` when the connection is not
+        // AUTHENTICATED or SELECTED — RENAME was never issued. Dereferencing it
+        // raised a `TypeError` where the settle now reads the resolved path, and a
+        // `TypeError` is not an outcome the rename settle can classify.
+        if (!result) {
+            throw new Error(`Rename of "${oldPath}" was not issued: the IMAP connection is not ready`);
+        }
+        return {
+            path: result.path,
+            newPath: result.newPath,
+        };
+    };
+    /**
+     * Subscribe to a mailbox.
+     *
+     * @param path - Full path of the mailbox to subscribe to
+     */
+    subscribeMailbox = async (path) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        await client.mailboxSubscribe(path);
+    };
+    /**
+     * Unsubscribe from a mailbox.
+     *
+     * @param path - Full path of the mailbox to unsubscribe from
+     */
+    unsubscribeMailbox = async (path) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        await client.mailboxUnsubscribe(path);
+    };
+    /**
+     * Move messages to another mailbox.
+     * Uses ImapFlow's messageMove which wraps UID MOVE command.
+     * Returns mapping of source UIDs to destination UIDs from COPYUID response.
+     *
+     * @param uids - Array of message UIDs to move
+     * @param destination - Destination mailbox path
+     * @returns Object with destination path, uidValidity, and uidMap
+     */
+    moveMessages = async (uids, destination) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        if (uids.length === 0) {
+            return { destination, uidValidity: 0, uidMap: new Map() };
+        }
+        const uidRange = uids.join(",");
+        const result = await client.messageMove(uidRange, destination, {
+            uid: true,
+        });
+        // messageMove returns false if no messages were moved
+        if (result === false) {
+            return { destination, uidValidity: 0, uidMap: new Map() };
+        }
+        return {
+            destination: result.destination,
+            uidValidity: Number(result.uidValidity ?? 0),
+            uidMap: result.uidMap ?? new Map(),
+        };
+    };
+    /**
+     * Copy messages to another mailbox.
+     * Uses ImapFlow's messageCopy which wraps UID COPY command.
+     * Returns mapping of source UIDs to destination UIDs from COPYUID response.
+     *
+     * @param uids - Array of message UIDs to copy
+     * @param destination - Destination mailbox path
+     * @returns Object with destination path, uidValidity, and uidMap
+     */
+    copyMessages = async (uids, destination) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        if (uids.length === 0) {
+            return { destination, uidValidity: 0, uidMap: new Map() };
+        }
+        const uidRange = uids.join(",");
+        const result = await client.messageCopy(uidRange, destination, {
+            uid: true,
+        });
+        // messageCopy returns false if no messages were copied
+        if (result === false) {
+            return { destination, uidValidity: 0, uidMap: new Map() };
+        }
+        return {
+            destination: result.destination,
+            uidValidity: Number(result.uidValidity ?? 0),
+            uidMap: result.uidMap ?? new Map(),
+        };
+    };
+    /**
+     * Permanently delete messages (mark \Deleted + expunge).
+     * Uses ImapFlow's messageDelete which wraps STORE +FLAGS.SILENT \Deleted
+     * followed by UID EXPUNGE.
+     *
+     * @param uids - Array of message UIDs to delete
+     * @returns Number of messages deleted
+     */
+    deleteMessages = async (uids) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        if (!this.currentMailbox) {
+            throw new Error("No mailbox selected");
+        }
+        if (uids.length === 0) {
+            return 0;
+        }
+        const uidRange = uids.join(",");
+        const result = await client.messageDelete(uidRange, { uid: true });
+        // messageDelete returns boolean or deleted count
+        if (typeof result === "number") {
+            return result;
+        }
+        return result ? uids.length : 0;
+    };
+    /**
+     * Get mailbox status.
+     *
+     * Message/unseen counts come from the IMAP STATUS command (no SELECT). The
+     * \Deleted count is not part of imapflow's typed STATUS query (there is no
+     * IMAP4rev2 STATUS=DELETED in the API), so it is derived by selecting the
+     * mailbox read-only and running SEARCH \Deleted — a projection re-read from
+     * the server, never a locally computed value.
+     *
+     * @param mailboxPath - Full path to the mailbox
+     * @returns Mailbox status including unseen and deleted counts
+     */
+    getMailboxStatus = async (mailboxPath) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        const status = await client.status(mailboxPath, {
+            messages: true,
+            recent: true,
+            unseen: true,
+            uidNext: true,
+            uidValidity: true,
+            highestModseq: true,
+        });
+        const deletedCount = await this.countDeleted(mailboxPath);
+        return {
+            messages: status.messages ?? 0,
+            recent: status.recent ?? 0,
+            unseen: status.unseen ?? 0,
+            uidNext: status.uidNext ?? 0,
+            uidValidity: Number(status.uidValidity ?? 0),
+            highestModseq: (status.highestModseq ?? 0n).toString(),
+            deletedCount,
+        };
+    };
+    /**
+     * Count messages flagged \Deleted but not yet expunged.
+     *
+     * Selects the mailbox read-only (no state change) and counts SEARCH \Deleted
+     * hits. Read-only SELECT is idempotent against an already-open mailbox.
+     */
+    countDeleted = async (mailboxPath) => {
+        await this.openBox(mailboxPath, true);
+        const deletedUids = await this.search(["DELETED"]);
+        return deletedUids.length;
+    };
+    /**
+     * Append a message to a mailbox.
+     * Used primarily for testing to seed messages.
+     *
+     * @param mailbox - Mailbox path to append to
+     * @param message - RFC 822 message content
+     * @param flags - Optional flags to set on the message
+     * @returns Object with destination path, uidValidity, and uid of the appended message
+     */
+    append = async (mailbox, message, flags) => {
+        this.ensureConnected();
+        const { client } = this;
+        if (!client) {
+            throw new Error("Not connected to IMAP server");
+        }
+        const result = await client.append(mailbox, message, flags);
+        // append returns false if the message could not be appended
+        if (result === false) {
+            throw new Error(`Failed to append message to ${mailbox}`);
+        }
+        return {
+            destination: result.destination,
+            uidValidity: Number(result.uidValidity ?? 0),
+            uid: result.uid ?? 0,
+        };
+    };
+    /**
+     * Ensure the connection is established
+     */
+    ensureConnected = () => {
+        if (!this.client || this._state !== "authenticated") {
+            throw new Error("Not connected to IMAP server");
+        }
+    };
+}
+/**
+ * Create an ImapFlow connection from account data using password credentials.
+ */
+export const createImapFlowConnectionFromAccount = (account, password) => {
+    return new ImapFlowConnection({
+        host: account.imapHost,
+        port: account.imapPort,
+        tls: account.imapTls,
+        user: account.username,
+        credentials: { kind: "password", password },
+    });
+};
+/**
+ * Create an ImapFlow connection using a credentials union (password or OAuth access token).
+ */
+export const createImapFlowConnectionWithCredentials = (account, credentials) => {
+    return new ImapFlowConnection({
+        host: account.imapHost,
+        port: account.imapPort,
+        tls: account.imapTls,
+        user: account.username,
+        credentials,
+    });
+};
+/**
+ * Build the imapflow auth object from mail credentials.
+ *
+ * IMPORTANT: never include access-token values in error messages.
+ */
+const buildImapAuth = (user, credentials) => {
+    if (credentials.kind === "password") {
+        return { user, pass: credentials.password };
+    }
+    if (credentials.kind === "accessToken") {
+        return { user, accessToken: credentials.accessToken };
+    }
+    // Exhaustiveness check — fails to compile if a new credential kind is added
+    // without handling it here.
+    const _exhaustive = credentials;
+    throw new Error(`Unknown credential kind: ${JSON.stringify(_exhaustive)}`);
+};
+/**
+ * The server's own words for the failure: the text of the tagged NO/BAD, which
+ * imapflow hangs off the error as `responseText`. It is the server's side of
+ * the exchange only — never the command we sent, so no credential can ride out
+ * on it. "SmtpClientAuthentication is disabled" and "User is authenticated but
+ * not connected" arrive this way, and neither is fixed by re-authenticating, so
+ * dropping the text leaves the account card telling the user to do the one
+ * thing that cannot help.
+ */
+const serverResponseText = (error) => {
+    const text = error.responseText;
+    return typeof text === "string" ? text.trim() : "";
+};
+/**
+ * Classify a raw IMAP error into a MailConnectionError, or return null if
+ * the error is not recognisable (let it bubble as-is).
+ *
+ * IMPORTANT: never include access-token values in error messages.
+ */
+const classifyImapError = (error, endpoint) => {
+    if (!(error instanceof Error)) {
+        return null;
+    }
+    const msg = error.message;
+    const code = error.code ?? "";
+    // Authentication failures
+    if (msg.includes("Invalid credentials") ||
+        msg.includes("Authentication failed") ||
+        msg.includes("AUTHENTICATIONFAILED") ||
+        msg.includes("AUTHENTICATE") ||
+        error.authenticationFailed === true) {
+        const serverText = serverResponseText(error);
+        return new MailConnectionError("auth", serverText
+            ? `IMAP authentication failed: ${serverText}`
+            : "IMAP authentication failed");
+    }
+    // Network-level failures — NEVER include the original message as it may
+    // echo back tokens in some server implementations. The endpoint (host:port)
+    // is safe and makes DNS/connect failures self-describing.
+    if (code === "ECONNREFUSED" ||
+        code === "ETIMEDOUT" ||
+        code === "ENOTFOUND" ||
+        code === "ECONNRESET" ||
+        code === "EHOSTUNREACH" ||
+        // imapflow raises these when the socket is gone mid-command.
+        code === "EConnectionClosed" ||
+        code === "NoConnection") {
+        const where = endpoint ? ` (${endpoint})` : "";
+        return new MailConnectionError("network", `IMAP connection failed: ${code}${where}`);
+    }
+    return null;
+};