proton-mail-bridge-client 2.3.1 → 2.4.0

package/dist/services/simple-imap-service.js

@@ -1,9 +1,9 @@
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { mkdir, open, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve, sep } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { ImapFlow } from "imapflow";
 import { simpleParser } from "mailparser";
-import { classifyAttachment, createEmailId, dedupeEmails, extractAttachments, extractMessageIdList, isSelfAddress, isTextLikeMimeType, mapEnvelopeAddresses, mapParsedAddresses, labelMatchesFolder, matchesLocalSearchFilters, matchesNonAsciiCriteria, splitNonAsciiCriteria, nextDay, normalizeLimit, parseDateInput, htmlToMarkdown, redactInlineData, parseEmailId, previewText, sanitizeFileName, sortEmailsByNewest, stripHtmlToText, summarizeCalendarText, } from "../utils/helpers.js";
+import { classifyAttachment, createEmailId, dedupeEmails, extractAttachments, extractMessageIdList, isSelfAddress, isTextLikeMimeType, mapEnvelopeAddresses, mapParsedAddresses, labelMatchesFolder, matchesLocalSearchFilters, matchesNonAsciiCriteria, splitNonAsciiCriteria, nextDay, InvalidArgumentError, decodeAttachmentText, isPathInside, normalizeLimit, optionalBoolean, optionalNumber, parseDateInput, htmlToMarkdown, redactInlineData, parseEmailId, previewText, sanitizeFileName, sortEmailsByNewest, stripHtmlToText, summarizeCalendarText, } from "../utils/helpers.js";
 import { logger } from "../utils/logger.js";
 import { ensureAccountIdentityMatches } from "../utils/account-identity.js";
 const FETCH_SUMMARY_QUERY = {
@@ -61,6 +61,9 @@ const MAX_ATTACHMENT_TEXT_BYTES = 512_000;
 // per candidate.
 // Newest candidates examined when a non-ASCII criterion has to be verified locally.
 const NON_ASCII_SCAN_CAP = 500;
+// A count with a local-only filter (hasAttachment, senderDomain...) must fetch every candidate, because the
+// server cannot evaluate it. Beyond this many, only the newest are checked and the count is marked approximate.
+const LOCAL_FILTER_COUNT_SCAN_CAP = 5000;
 export const SEARCH_FILTER_BATCH_SIZE = 50;
 // A healthy IMAP IDLE blocks until a mailbox change or the requested timeout.
 // If client.idle() returns faster than this with no events, IDLE never actually
@@ -273,6 +276,66 @@ export function isVirtualMailView(entry) {
 // UID order does not track date order (e.g. after a cross-provider import), so picking
 // the target subset by UID (slice(-limit)) can silently drop the newest messages. This
 // picks by INTERNALDATE instead. See GitHub issue #6.
+const BULK_MATCH_FIELDS = ["from", "subject", "text", "since", "before", "isRead", "isStarred", "sizeLarger", "sizeSmaller"];
+// A bulk `match` selects messages to act on, so it must say what to select. A match with no usable criterion
+// ({}, a misspelled field, an empty string) used to fall back to IMAP "ALL" and resolve to every message in
+// the folder. Values arrive as the client sent them ("false", "1000"), so they are read here, not assumed.
+export function normalizeBulkMatch(match, folder) {
+    const raw = match;
+    const unknown = Object.keys(raw).filter((key) => !BULK_MATCH_FIELDS.includes(key) && raw[key] !== undefined);
+    if (unknown.length > 0) {
+        throw new InvalidArgumentError(`Unknown match field${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. Valid fields: ${BULK_MATCH_FIELDS.join(", ")}.`);
+    }
+    const text = (key) => {
+        const value = raw[key];
+        if (value === undefined || value === null)
+            return undefined;
+        if (typeof value !== "string")
+            throw new InvalidArgumentError(`match.${key} must be a string.`);
+        return value.trim() || undefined;
+    };
+    const input = {
+        folder,
+        from: text("from"),
+        subject: text("subject"),
+        query: text("text"),
+        dateFrom: text("since"),
+        dateTo: text("before"),
+        isRead: optionalBoolean(raw.isRead),
+        isStarred: optionalBoolean(raw.isStarred),
+        sizeLarger: optionalNumber(raw.sizeLarger, 0, Number.MAX_SAFE_INTEGER),
+        sizeSmaller: optionalNumber(raw.sizeSmaller, 0, Number.MAX_SAFE_INTEGER),
+    };
+    const given = [input.from, input.subject, input.query, input.dateFrom, input.dateTo, input.isRead, input.isStarred, input.sizeLarger, input.sizeSmaller];
+    if (given.every((value) => value === undefined)) {
+        throw new InvalidArgumentError(`match needs at least one criterion (${BULK_MATCH_FIELDS.join(", ")}); with none it would select every message in the folder.`);
+    }
+    return input;
+}
+// A thread operation looks up every message whose Message-ID or References contains this value, and then
+// moves, deletes or flags them. IMAP HEADER search is a substring match (RFC 3501), so a value like "@" or
+// "ab" matches far more than one conversation. A real Message-ID is "<local@domain>" (the brackets may have
+// been dropped by the caller): no whitespace, no angle brackets inside, an "@" with something on both sides.
+export function validateThreadMessageId(value) {
+    const trimmed = (value ?? "").trim();
+    const inner = trimmed.startsWith("<") && trimmed.endsWith(">") ? trimmed.slice(1, -1) : trimmed;
+    if (inner.length < 3 || inner.length > 500 || /[\s<>]/.test(inner)) {
+        throw new InvalidArgumentError("messageId must be a Message-ID such as <abc123@mail.example>.");
+    }
+    const at = inner.lastIndexOf("@");
+    if (at < 1 || at === inner.length - 1) {
+        throw new InvalidArgumentError("messageId must be a Message-ID such as <abc123@mail.example>.");
+    }
+    return trimmed.startsWith("<") ? trimmed : `<${trimmed}>`;
+}
+function describeThreadFailure(folder, uid, error) {
+    return `${folder} uid ${uid}: ${error instanceof Error ? error.message : String(error)}`;
+}
+function assertThreadBatchSize(count, max) {
+    if (max !== undefined && count > max) {
+        throw new Error(`The thread has ${count} messages, which exceeds the limit of ${max} (maxBatchSize). Nothing was changed; raise maxBatchSize to act on all of them.`);
+    }
+}
 export function pickNewestUids(dated, limit) {
     return [...dated]
         .sort((a, b) => b.date - a.date)
@@ -615,7 +678,8 @@ export class SimpleIMAPService {
     lastIdleError;
     _lastOpTs = 0;
     _connectingPromise;
-    _idleActive = new Map();
+    // One running IDLE session per folder; later callers wait on it (see waitForMailboxChanges).
+    _idleSession = new Map();
     // Operations currently waiting for the mailbox lock (see withMailbox); the IDLE watcher
     // yields while this is non-zero.
     _pendingMailboxOps = 0;
@@ -664,23 +728,25 @@ export class SimpleIMAPService {
         return this._connectingPromise;
     }
     async disconnect() {
-        if (!this.client) {
+        const client = this.client;
+        if (!client) {
             return;
         }
+        // Forget this client now, not after the logout: a call that connects while the logout is still running
+        // installs a new client, and clearing `this.client` afterwards used to forget THAT one, leaving it open
+        // and never reused (one leaked Bridge session each time).
+        this.client = undefined;
         try {
-            if (this.client.usable) {
-                await this.client.logout();
+            if (client.usable) {
+                await client.logout();
             }
             else {
-                this.client.close();
+                client.close();
             }
         }
         catch (error) {
             this.log.warn("IMAP disconnect failed", "IMAPService", error);
-            this.client.close();
-        }
-        finally {
-            this.client = undefined;
+            client.close();
         }
     }
     isConnected() {
@@ -705,17 +771,48 @@ export class SimpleIMAPService {
         const folder = input.folder?.trim() || "INBOX";
         const timeoutMs = normalizeLimit(input.timeoutMs, this.config.runtime.idleMaxSeconds * 1000, 1_000, 300_000);
         // IDLE semaphore: prevent stacking concurrent IDLE sessions per folder,
-        // which would exhaust Proton Bridge's connection limit.
-        if (this._idleActive.get(folder)) {
+        // which would exhaust Proton Bridge's connection limit. A caller that arrives while a session is
+        // already watching (typically the background watcher, while the wait_for_mailbox_changes tool is
+        // called) does not start another one: it waits, up to its own timeout, for the next session to see a
+        // change, instead of answering "no changes" at once.
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const active = this._idleSession.get(folder);
+            if (!active)
+                break;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                break;
+            let timer;
+            const result = await Promise.race([
+                active.catch(() => undefined),
+                new Promise((resolve) => { timer = setTimeout(() => resolve(undefined), remaining); timer.unref?.(); }),
+            ]);
+            if (timer)
+                clearTimeout(timer);
+            if (result?.changed)
+                return { ...result, timeoutMs };
+            // The session ended without a change (or its caller failed): give the next one a moment to start,
+            // then wait on it, until this caller's own time is up.
+            await new Promise((resolve) => { const t = setTimeout(resolve, 20); t.unref?.(); });
+        }
+        if (this._idleSession.get(folder)) {
             return { folder, timeoutMs, checkedAt: new Date().toISOString(), changed: false, events: [] };
         }
-        this._idleActive.set(folder, true);
-        const client = await this.ensureConnected();
+        // The mark must be cleared whatever happens, including a failure to connect: it used to be set before
+        // connecting, outside the try/finally, so one failed connect (Bridge down at startup) left the folder
+        // "watched" forever and every later call returned "no changes" instantly.
+        const session = (async () => {
+            const client = await this.ensureConnected();
+            return this.waitForMailboxChangesWithClient(client, folder, timeoutMs, true);
+        })();
+        this._idleSession.set(folder, session);
         try {
-            return await this.waitForMailboxChangesWithClient(client, folder, timeoutMs, true);
+            return await session;
         }
         finally {
-            this._idleActive.delete(folder);
+            if (this._idleSession.get(folder) === session)
+                this._idleSession.delete(folder);
         }
     }
     async waitForMailboxChangesWithClient(client, folder, timeoutMs, allowReconnectRetry) {
@@ -757,7 +854,17 @@ export class SimpleIMAPService {
         client.on("exists", onExists);
         client.on("expunge", onExpunge);
         client.on("flags", onFlags);
-        const lock = await client.getMailboxLock(folder, { readOnly: true });
+        let lock;
+        try {
+            lock = await client.getMailboxLock(folder, { readOnly: true });
+        }
+        catch (error) {
+            // The client is reused: listeners left on it would keep collecting events for a call that is gone.
+            client.off("exists", onExists);
+            client.off("expunge", onExpunge);
+            client.off("flags", onFlags);
+            throw error;
+        }
         // Yield to operations waiting for the lock (see IDLE_YIELD_* above). The graceful
         // break is retried on every poll because preCheck only exists once IDLE has actually
         // started; if the lock is still held IDLE_YIELD_FORCE_MS after the first waiter was
@@ -804,7 +911,7 @@ export class SimpleIMAPService {
             // still "usable" — so ensureConnected() won't reconnect, and every
             // subsequent idle() returns instantly. That turns the caller's watch loop
             // into a 100%-CPU busy spin (observed: an orphaned process burning a full
-            // core for days). Our IDLE calls are serialized per folder via _idleActive
+            // core for days). Our IDLE calls are serialized per folder via _idleSession
             // and awaited by the caller, so no legitimate IDLE can be in flight here —
             // if the flag is set, it is stuck. Clear it so idle() actually enters IDLE
             // and blocks.
@@ -1089,20 +1196,22 @@ export class SimpleIMAPService {
         if (!trimmed) {
             throw new Error("Folder path is required.");
         }
-        const reservedRoots = new Set([
-            "INBOX",
-            "Drafts",
-            "Sent",
-            "Trash",
-            "Spam",
-            "Archive",
-            "All Mail",
-            "Folders",
-            "Labels",
+        // System folders, by name (any capitalisation, with or without surrounding slashes) and by the special-use
+        // the server itself reports. Compared on the normalised name: "inbox", "INBOX/" and "/Trash" are the same
+        // folders as "INBOX" and "Trash".
+        const reservedNames = new Set([
+            "inbox", "drafts", "sent", "sent mail", "trash", "deleted messages", "spam", "junk", "archive",
+            "all mail", "starred", "folders", "labels",
         ]);
-        if (reservedRoots.has(trimmed)) {
+        const normalized = trimmed.replace(/^\/+|\/+$/g, "").trim().toLowerCase();
+        if (reservedNames.has(normalized)) {
             throw new Error(`Refusing to delete reserved system folder ${trimmed}.`);
         }
+        const known = await this.getFolders().catch(() => []);
+        const target = known.find((entry) => entry.path.replace(/^\/+|\/+$/g, "").toLowerCase() === normalized);
+        if (target?.specialUse) {
+            throw new Error(`Refusing to delete system folder ${trimmed} (it is the server's ${target.specialUse} folder).`);
+        }
         const response = await this.mutateFolderWithReconnectCheck(async () => {
             const client = await this.ensureConnected();
             return client.mailboxDelete(trimmed);
@@ -1163,6 +1272,11 @@ export class SimpleIMAPService {
             const emails = [];
             const fetchQuery = input.includeSnippet ? FETCH_DETAIL_QUERY : FETCH_SUMMARY_QUERY;
             if (input.beforeUid !== undefined) {
+                // Nothing lies below UID 1. Asking for "1:0" would not mean "empty": IMAP ranges are unordered, so it
+                // is "0:1" and returns UID 1 again, which would keep a cursor loop at the oldest message going forever.
+                if (!(input.beforeUid > 1)) {
+                    return { folder, total, limit, offset, emails: [] };
+                }
                 // UID-based pagination: search for UIDs below the given upper bound
                 const searchQuery = { uid: `1:${input.beforeUid - 1}` };
                 const uids = await client.search(searchQuery, { uid: true });
@@ -1416,8 +1530,12 @@ export class SimpleIMAPService {
         const { parsed } = await this.getParsedMailDetail(input.emailId);
         const attachments = this.mapParsedAttachmentsWithContent(parsed);
         const saved = [];
+        const failed = [];
+        let firstError;
         let skipped = 0;
-        // Track resolved output paths to detect filename collisions within this batch
+        // Track resolved output paths to detect filename collisions within this batch. Compared in lower case:
+        // the default filesystems of macOS and Windows treat "Invoice.pdf" and "invoice.pdf" as one file, and
+        // the second would silently replace the first.
         const usedPaths = new Set();
         for (const attachment of attachments) {
             if (!input.includeInline && attachment.isInline) {
@@ -1444,7 +1562,7 @@ export class SimpleIMAPService {
                 const sanitized = sanitizeFileName(attachment.filename, attachmentId);
                 const base = join(resolve(input.outputPath), sanitized);
                 // Deduplicate: if path already used, append numeric suffix (image.png → image (1).png)
-                if (!usedPaths.has(base)) {
+                if (!usedPaths.has(base.toLowerCase())) {
                     targetPath = base;
                 }
                 else {
@@ -1455,19 +1573,32 @@ export class SimpleIMAPService {
                     do {
                         candidate = join(resolve(input.outputPath), `${stem} (${counter})${ext}`);
                         counter++;
-                    } while (usedPaths.has(candidate));
+                    } while (usedPaths.has(candidate.toLowerCase()));
                     targetPath = candidate;
                 }
-                usedPaths.add(targetPath);
+                usedPaths.add(targetPath.toLowerCase());
             }
             else {
                 targetPath = input.outputPath;
             }
-            saved.push(await this.writeAttachmentToPath(input.emailId, attachment, targetPath));
+            // One attachment that cannot be written must not lose the ones already saved or still to come.
+            try {
+                saved.push(await this.writeAttachmentToPath(input.emailId, attachment, targetPath));
+            }
+            catch (error) {
+                firstError ??= error;
+                failed.push({ id: attachment.id, filename: attachment.filename, error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        // Nothing could be saved at all: that is a failure of the call, not an empty success. The first error is
+        // raised as it was (an account mismatch, a missing download directory...) so its meaning is kept.
+        if (saved.length === 0 && failed.length > 0) {
+            throw firstError;
         }
         return {
             emailId: input.emailId,
             saved,
+            failed,
             skipped,
         };
     }
@@ -1477,14 +1608,15 @@ export class SimpleIMAPService {
             return undefined;
         }
         const contentType = attachment.contentType?.toLowerCase();
-        if (contentType === "text/html") {
-            return stripHtmlToText(attachment.content.toString("utf8"));
-        }
-        if (contentType === "text/calendar") {
-            return summarizeCalendarText(attachment.content.toString("utf8"));
-        }
-        if (isTextLikeMimeType(attachment.contentType)) {
-            return attachment.content.toString("utf8");
+        if (contentType === "text/html" || contentType === "text/calendar" || isTextLikeMimeType(attachment.contentType)) {
+            const text = decodeAttachmentText(attachment.content, attachment.charset);
+            if (text === undefined)
+                return undefined;
+            if (contentType === "text/html")
+                return stripHtmlToText(text);
+            if (contentType === "text/calendar")
+                return summarizeCalendarText(text);
+            return text;
         }
         return undefined;
     }
@@ -1505,8 +1637,12 @@ export class SimpleIMAPService {
             contentDisposition: attachment.disposition,
         };
     }
-    async getAttachmentContent(emailId, attachmentId, includeBase64 = false) {
-        await this.assertAttachmentWithinInlineLimit(emailId, attachmentId);
+    async getAttachmentContent(emailId, attachmentId, options = false) {
+        const { includeBase64 = false, forSave = false } = typeof options === "boolean" ? { includeBase64: options } : options;
+        // The inline-size limit bounds what is put into the reply. A save writes to disk and puts nothing into it.
+        if (!forSave) {
+            await this.assertAttachmentWithinInlineLimit(emailId, attachmentId);
+        }
         const attachment = await this.getParsedAttachment(emailId, attachmentId);
         const base64 = attachment.content.toString("base64");
         return {
@@ -1524,8 +1660,8 @@ export class SimpleIMAPService {
                 isCalendarInvite: attachment.isCalendarInvite,
                 isSignature: attachment.isSignature,
             },
-            text: this.extractAttachmentText(attachment),
-            base64: includeBase64 ? base64 : undefined,
+            text: forSave ? undefined : this.extractAttachmentText(attachment),
+            base64: includeBase64 || forSave ? base64 : undefined,
         };
     }
     // First-class text extraction, deliberately NOT gated by the base64-oriented
@@ -1704,7 +1840,7 @@ export class SimpleIMAPService {
                     .catch(() => undefined)) || undefined;
                 targetFolderUidValidity = targetStatus?.uidValidity?.toString();
             }
-        }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms moving email ${emailId} to ${targetFolder}`);
+        }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms moving email ${emailId} to ${targetFolder}. The outcome is unknown: the server may have completed the move, so check both folders before retrying.`);
         const cached = this.messageCache.get(emailId);
         this.messageCache.delete(emailId);
         const targetEmailId = targetUid ? createEmailId(targetFolder, targetUid, targetFolderUidValidity) : undefined;
@@ -1903,7 +2039,22 @@ export class SimpleIMAPService {
         return { emailId, added: flagsToAdd, removed: flagsToRemove, notApplied };
     }
     async countMessages(input = {}) {
-        const folder = input.folder ?? "INBOX";
+        // A label that names real folder(s) (Proton: "Newsletters" = Labels/Newsletters) is answered by
+        // counting those folders, exactly as searchEmails does: every message in them has the label, and
+        // Bridge never reports labels on the messages themselves.
+        const labelFolders = await this.resolveLabelFolders(input);
+        const folders = labelFolders ?? [input.folder ?? "INBOX"];
+        let count = 0;
+        let approximate = false;
+        for (const folder of folders) {
+            const counted = await this.countInFolder(folder, input, labelFolders !== undefined);
+            count += counted.count;
+            approximate = approximate || counted.approximate;
+        }
+        const folder = labelFolders ? labelFolders.join(", ") || input.folder || "INBOX" : folders[0];
+        return approximate ? { folder, count, approximate: true } : { folder, count };
+    }
+    async countInFolder(folder, input, labelIsFolder) {
         // Bridge cannot match non-ASCII values: send a narrowed ASCII query and verify locally,
         // exactly as searchEmails does, so the two agree.
         const { imapInput, criteria: nonAsciiCriteria } = splitNonAsciiCriteria(input);
@@ -1912,7 +2063,7 @@ export class SimpleIMAPService {
         // this they were silently dropped and the unfiltered SEARCH count was returned.
         const hasLocalOnlyFilters = typeof input.hasAttachment === "boolean" ||
             Boolean(input.threadId) ||
-            Boolean(input.label) ||
+            (Boolean(input.label) && !labelIsFolder) ||
             Boolean(input.attachmentName) ||
             Boolean(input.senderDomain) ||
             Boolean(input.mailboxRole);
@@ -1923,9 +2074,15 @@ export class SimpleIMAPService {
             if ((!hasLocalOnlyFilters && !nonAsciiCriteria) || uids.length === 0) {
                 return uids.length;
             }
-            // The narrowed query can be broad; check only the newest candidates and say so.
-            if (nonAsciiCriteria && uids.length > NON_ASCII_SCAN_CAP) {
-                uids = [...uids].sort((a, b) => b - a).slice(0, NON_ASCII_SCAN_CAP);
+            // The narrowed query can be broad; check only the newest candidates (by date, which is what
+            // searchEmails ranks by: UID order does not follow date order after an import) and say so.
+            const scanCap = nonAsciiCriteria ? NON_ASCII_SCAN_CAP : LOCAL_FILTER_COUNT_SCAN_CAP;
+            if (uids.length > scanCap) {
+                const dated = [];
+                for await (const message of client.fetch(uids, FETCH_INDEX_QUERY, { uid: true })) {
+                    dated.push({ uid: message.uid, date: new Date(message.internalDate ?? 0).getTime() });
+                }
+                uids = pickNewestUids(dated, scanCap);
                 approximate = true;
             }
             // A non-ASCII free-text query is verified against the body, so it needs the source too.
@@ -1945,7 +2102,7 @@ export class SimpleIMAPService {
             }
             return matched;
         });
-        return approximate ? { folder, count, approximate: true } : { folder, count };
+        return { count, approximate };
     }
     async getFolderStats(folder) {
         const target = folder ?? "INBOX";
@@ -1990,6 +2147,9 @@ export class SimpleIMAPService {
         }
         const uidSet = uids.join(",");
         await this.withTimeout(this.withMailbox(folder, false, async (client) => {
+            // The UIDs above were listed under one lock and are deleted under another. If the folder was
+            // recreated in between, those numbers now belong to other messages.
+            this.assertMailboxUidValidity(client, folderUidValidity);
             await client.messageDelete(uidSet, { uid: true });
         }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms emptying folder ${folder}`);
         // Purge from cache — must reconstruct the exact same id toSummary/etc.
@@ -2064,20 +2224,12 @@ export class SimpleIMAPService {
                 .map((parsed) => parsed.uid);
         }
         // match path
-        const searchInput = {
-            folder,
-            from: match.from,
-            subject: match.subject,
-            query: match.text,
-            dateFrom: match.since,
-            dateTo: match.before,
-            isRead: match.isRead,
-            isStarred: match.isStarred,
-            sizeLarger: match.sizeLarger,
-            sizeSmaller: match.sizeSmaller,
-        };
+        const searchInput = normalizeBulkMatch(match, folder);
         const query = this.buildSearchQuery(searchInput);
         const search = () => this.withMailbox(folder, true, async (client) => {
+            // The folder may have been recreated since the caller read its UIDVALIDITY: UIDs found now would
+            // not be the messages the caller saw. Refuse instead of acting on whatever has those numbers.
+            this.assertMailboxUidValidity(client, currentUidValidity);
             const found = await client.search(query, { uid: true });
             return Array.isArray(found) ? found : [];
         });
@@ -2140,7 +2292,7 @@ export class SimpleIMAPService {
                     }
                     uidMap = moved.uidMap;
                     hasUidPlus = client.capabilities.has("UIDPLUS");
-                }), BULK_BATCH_TIMEOUT_MS, `Timed out after ${BULK_BATCH_TIMEOUT_MS}ms moving uid set ${uidSet}`);
+                }), BULK_BATCH_TIMEOUT_MS, `Timed out after ${BULK_BATCH_TIMEOUT_MS}ms moving uid set ${uidSet} The outcome is unknown: the server may have completed the move, so check the folders before retrying.`);
                 for (const uid of uids) {
                     const emailId = createEmailId(folder, uid, sourceUidValidity);
                     // `moved === false` above only catches an empty/invalid range,
@@ -2490,6 +2642,7 @@ export class SimpleIMAPService {
         return { folder, scanned: page.length, senders: sorted };
     }
     async resolveThreadUids(messageId, acrossFolders = true, folders) {
+        messageId = validateThreadMessageId(messageId);
         const results = [];
         // acrossFolders was previously accepted and documented ("Also search
         // Sent and All Mail.", default false) but silently discarded — every
@@ -2553,8 +2706,10 @@ export class SimpleIMAPService {
         if (input.dryRun) {
             return { messageId: input.messageId, destination: input.destination, moved: matches.length, notMoved: 0, dryRun: true };
         }
+        assertThreadBatchSize(matches.length, input.maxBatchSize);
         let moved = 0;
         let notMoved = 0;
+        const errors = [];
         for (const { folder, uid, emailId, uidValidity } of matches) {
             try {
                 await this.withTimeout(this.withMailbox(folder, false, async (client) => {
@@ -2568,12 +2723,13 @@ export class SimpleIMAPService {
                     const result = await client.messageMove(String(uid), input.destination, { uid: true });
                     if (result === false)
                         throw new Error(`Server did not move uid ${uid}`);
-                }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms moving uid ${uid} for thread ${input.messageId}`);
+                }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms moving uid ${uid} for thread ${input.messageId} The outcome is unknown: the server may have completed the move, so check the folders before retrying.`);
                 this.messageCache.delete(emailId);
                 moved++;
             }
-            catch {
+            catch (error) {
                 notMoved++;
+                errors.push(describeThreadFailure(folder, uid, error));
             }
         }
         if (moved > 0) {
@@ -2583,13 +2739,14 @@ export class SimpleIMAPService {
             this.folderCache = undefined;
         }
         this.lastSyncAt = new Date().toISOString();
-        return { messageId: input.messageId, destination: input.destination, moved, notMoved, dryRun: false };
+        return { messageId: input.messageId, destination: input.destination, moved, notMoved, dryRun: false, ...(errors.length > 0 ? { errors: errors.slice(0, 10) } : {}) };
     }
     async deleteThread(input) {
         const matches = await this.resolveThreadUids(input.messageId, input.acrossFolders ?? false);
         if (input.dryRun) {
-            return { messageId: input.messageId, deleted: matches.length, dryRun: true };
+            return { messageId: input.messageId, deleted: matches.length, notDeleted: 0, dryRun: true };
         }
+        assertThreadBatchSize(matches.length, input.maxBatchSize);
         // No .catch() here — a Trash-resolution failure must propagate as a
         // hard error rather than silently falling into the permanent-delete
         // branch below when the caller explicitly asked for permanent:false.
@@ -2600,6 +2757,7 @@ export class SimpleIMAPService {
             ? undefined
             : await this.resolveSpecialFolder("\\Trash", ["Trash", "INBOX.Trash"]);
         let deleted = 0;
+        const deleteErrors = [];
         for (const { folder, uid, emailId, uidValidity } of matches) {
             try {
                 // Re-verify the generation this match was resolved under — see
@@ -2617,7 +2775,9 @@ export class SimpleIMAPService {
                 this.messageCache.delete(emailId);
                 deleted++;
             }
-            catch { /* best-effort */ }
+            catch (error) {
+                deleteErrors.push(describeThreadFailure(folder, uid, error));
+            }
         }
         if (deleted > 0) {
             // Deletion changes the folder's message count — see the
@@ -2626,16 +2786,18 @@ export class SimpleIMAPService {
             this.folderCache = undefined;
         }
         this.lastSyncAt = new Date().toISOString();
-        return { messageId: input.messageId, deleted, dryRun: false };
+        return { messageId: input.messageId, deleted, notDeleted: deleteErrors.length, dryRun: false, ...(deleteErrors.length > 0 ? { errors: deleteErrors.slice(0, 10) } : {}) };
     }
     async flagThread(input) {
         const matches = await this.resolveThreadUids(input.messageId, input.acrossFolders ?? false);
         if (input.dryRun) {
-            return { messageId: input.messageId, affected: matches.length, notApplied: [], dryRun: true };
+            return { messageId: input.messageId, affected: matches.length, notAffected: 0, notApplied: [], dryRun: true };
         }
+        assertThreadBatchSize(matches.length, input.maxBatchSize);
         const flagsToAdd = input.flagsToAdd ?? [];
         const flagsToRemove = input.flagsToRemove ?? [];
         let affected = 0;
+        const flagErrors = [];
         const allNotApplied = [];
         for (const { folder, uid, uidValidity } of matches) {
             try {
@@ -2659,7 +2821,9 @@ export class SimpleIMAPService {
                 }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms flagging uid ${uid} for thread ${input.messageId}`);
                 affected++;
             }
-            catch { /* best-effort */ }
+            catch (error) {
+                flagErrors.push(describeThreadFailure(folder, uid, error));
+            }
         }
         if (affected > 0 && [...flagsToAdd, ...flagsToRemove].some((flag) => flag.toLowerCase() === "\\seen")) {
             // \Seen changes the folder's unseen count — see the markEmailRead
@@ -2667,7 +2831,7 @@ export class SimpleIMAPService {
             // invalidation on the single-email path.
             this.folderCache = undefined;
         }
-        return { messageId: input.messageId, affected, notApplied: [...new Set(allNotApplied)], dryRun: false };
+        return { messageId: input.messageId, affected, notAffected: flagErrors.length, notApplied: [...new Set(allNotApplied)], dryRun: false, ...(flagErrors.length > 0 ? { errors: flagErrors.slice(0, 10) } : {}) };
     }
     async syncEmails(input = {}) {
         const snapshot = await this.collectEmailsForIndex(input);
@@ -3381,6 +3545,7 @@ export class SimpleIMAPService {
                 cid: attachment.cid,
             }),
             content: attachment.content,
+            charset: attachment.headers?.get?.("content-type")?.params?.charset,
         }));
     }
     mapHeaders(parsed) {
@@ -3412,13 +3577,19 @@ export class SimpleIMAPService {
     async getParsedAttachment(emailId, attachmentId) {
         const { detail, parsed } = await this.getParsedMailDetail(emailId);
         const attachments = this.mapParsedAttachmentsWithContent(parsed);
-        const match = attachments.find((attachment) => attachment.id === attachmentId ||
-            attachment.filename === attachmentId ||
-            attachment.checksum === attachmentId);
-        if (!match) {
+        // An id is exact. A checksum or a filename is a convenience, and a filename is not unique: two
+        // attachments can both be "image.png". Returning the first one silently would hand back the wrong file.
+        const byId = attachments.find((attachment) => attachment.id === attachmentId);
+        if (byId)
+            return byId;
+        const candidates = attachments.filter((attachment) => attachment.checksum === attachmentId || attachment.filename === attachmentId);
+        if (candidates.length === 0) {
             throw new Error(`Attachment ${attachmentId} not found on email ${detail.id}`);
         }
-        return match;
+        if (candidates.length > 1) {
+            throw new Error(`${candidates.length} attachments on email ${detail.id} match "${attachmentId}". Use one of these ids instead: ${candidates.map((candidate) => candidate.id ?? "(no id)").join(", ")}`);
+        }
+        return candidates[0];
     }
     async assertAttachmentWithinInlineLimit(emailId, attachmentId) {
         const { folder, uid } = parseEmailId(emailId);
@@ -3565,6 +3736,13 @@ export class SimpleIMAPService {
         }
         return String(err);
     }
+    // Where a save with no path given goes. Attachments are only meant to be written into the configured
+    // download directory (PROTONMAIL_ALLOW_FILE_DOWNLOAD_DIR); the server's private data directory is only the
+    // fallback when none is configured.
+    defaultAttachmentDir() {
+        const allowed = this.config.runtime?.allowFileDownloadDir;
+        return allowed ? resolve(allowed) : join(this.config.dataDir, "attachments");
+    }
     async writeAttachmentToPath(emailId, attachment, outputPath) {
         let outputFilePath;
         if (!outputPath) {
@@ -3589,7 +3767,7 @@ export class SimpleIMAPService {
                 this.identityChecked = true;
             }
             const filename = sanitizeFileName(attachment.filename, attachment.id || "attachment");
-            const dirPath = join(this.config.dataDir, "attachments", encodeURIComponent(emailId));
+            const dirPath = join(this.defaultAttachmentDir(), encodeURIComponent(emailId));
             // 0o700/0o600: this writes the user's own private email content — restrict
             // it to the owner regardless of the destination directory's own permissions.
             await mkdir(dirPath, { recursive: true, mode: 0o700 });
@@ -3664,33 +3842,31 @@ export class SimpleIMAPService {
     // passed. Returning the already-realpath'd path collapses that into the
     // single unavoidable race between this check and the actual write.
     guardAttachmentOutputPath(outputPath) {
-        const allowDir = process.env.PROTONMAIL_ALLOW_FILE_DOWNLOAD_DIR?.trim();
+        const allowDir = (this.config.runtime?.allowFileDownloadDir ?? process.env.PROTONMAIL_ALLOW_FILE_DOWNLOAD_DIR)?.trim();
         if (!allowDir) {
             throw new Error("outputPath requires PROTONMAIL_ALLOW_FILE_DOWNLOAD_DIR to be configured.");
         }
         const targetPath = resolve(outputPath);
         const allowedRealPath = realpathSync(resolve(allowDir));
-        let targetRealPath;
+        // Canonicalise the part of the target that exists (following symlinks) and keep the rest as written:
+        // a save into a directory that does not exist yet is fine as long as the deepest existing ancestor is
+        // inside the download directory. Checked before anything is created.
+        let existing = targetPath;
+        while (!existsSync(existing)) {
+            const parent = dirname(existing);
+            if (parent === existing)
+                break;
+            existing = parent;
+        }
+        let existingReal;
         try {
-            targetRealPath = realpathSync(targetPath);
+            existingReal = realpathSync(existing);
         }
-        catch (error) {
-            if (error &&
-                typeof error === "object" &&
-                "code" in error &&
-                error.code === "ENOENT") {
-                try {
-                    targetRealPath = realpathSync(dirname(targetPath)) + sep + basename(targetPath);
-                }
-                catch {
-                    throw new Error(`Output directory does not exist: ${dirname(targetPath)}`);
-                }
-            }
-            else {
-                throw error;
-            }
+        catch {
+            throw new Error(`Output path cannot be resolved: ${targetPath}`);
         }
-        if (!targetRealPath.startsWith(`${allowedRealPath}${sep}`) && targetRealPath !== allowedRealPath) {
+        const targetRealPath = existing === targetPath ? existingReal : join(existingReal, relative(existing, targetPath));
+        if (!isPathInside(allowedRealPath, targetRealPath)) {
             throw new Error("outputPath path escapes the allowed directory.");
         }
         return targetRealPath;
@@ -3698,8 +3874,10 @@ export class SimpleIMAPService {
     async resolveAttachmentOutputPath(emailId, attachment, outputPath) {
         const filename = sanitizeFileName(attachment.filename, attachment.id || "attachment");
         if (!outputPath) {
-            return join(this.config.dataDir, "attachments", encodeURIComponent(emailId), filename);
+            return join(this.defaultAttachmentDir(), encodeURIComponent(emailId), filename);
         }
+        // Whether a directory was meant has to be read from the string as given: resolve() strips a trailing slash.
+        const wantsDirectory = /[\\/]$/.test(outputPath);
         const resolved = resolve(outputPath);
         try {
             const existing = await stat(resolved);
@@ -3716,7 +3894,7 @@ export class SimpleIMAPService {
                 throw error;
             }
         }
-        if (resolved.endsWith("/") || resolved.endsWith("\\")) {
+        if (wantsDirectory) {
             const directoryTarget = join(resolved, filename);
             return this.guardAttachmentOutputPath(directoryTarget);
         }
@@ -3767,26 +3945,36 @@ export class SimpleIMAPService {
         // there's nothing to dedup against — fall through to a normal import,
         // same as before this fix (not a regression).
         let messageId;
+        let sentAt;
         try {
-            messageId = (await this.parseSource(input.raw)).messageId;
+            const parsed = await this.parseSource(input.raw);
+            messageId = parsed.messageId;
+            sentAt = parsed.date instanceof Date && !Number.isNaN(parsed.date.getTime()) ? parsed.date : undefined;
         }
         catch {
             // Best-effort — an unparseable message still gets imported below.
         }
+        // The server's own INTERNALDATE decides where the message sorts. Without one, every import was stamped
+        // with the time of the import, so migrated mail from years ago sat at the top as if it had just arrived.
+        // The Date header is the best record of when it really came; a missing, unreadable or future one is not.
+        const now = Date.now();
+        const internalDate = input.internalDate ?? (sentAt && sentAt.getTime() <= now + 24 * 60 * 60 * 1000 ? sentAt : new Date(now));
         if (messageId) {
             let existingFolderUidValidity;
             const existingUid = await this.withTimeout(this.withMailbox(folder, true, async (client) => {
                 existingFolderUidValidity = (client.mailbox || undefined)?.uidValidity?.toString();
                 const uids = await client.search({ header: { "Message-ID": messageId } }, { uid: true });
                 return Array.isArray(uids) && uids.length > 0 ? uids[uids.length - 1] : undefined;
-            }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms checking for an existing import of ${messageId} in ${folder}`).catch(() => undefined);
+            }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms checking for an existing import of ${messageId} in ${folder}`);
+            // No .catch(): a failed check used to be treated as "not there" and the import went ahead, so a retry of
+            // an import whose check had failed could silently create a duplicate. The error is raised instead.
             if (existingUid !== undefined) {
                 const existingEmailId = createEmailId(folder, existingUid, existingFolderUidValidity);
                 return { folder, uid: existingUid, emailId: existingEmailId, alreadyExists: true, existingEmailId };
             }
         }
         const client = await this.ensureConnected();
-        const appended = await client.append(folder, input.raw, input.flags ?? [], input.internalDate ?? new Date());
+        const appended = await client.append(folder, input.raw, input.flags ?? [], internalDate);
         if (!appended) {
             throw new Error(`Server did not append the imported message into ${folder}`);
         }