proton-mail-bridge-client 2.0.2 → 2.0.4

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

@@ -35,6 +35,11 @@ const FETCH_INDEX_DETAIL_QUERY = {
     source: true,
 };
 const MAX_ATTACHMENT_TEXT_BYTES = 512_000;
+// searchEmails' local-filter branch batches its detail fetch independently of the
+// caller's result `limit` (see the comment above that loop) — this is the floor on
+// each network batch so a small limit (e.g. 1) can't degrade into one `fetch` call
+// per candidate.
+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
 // engaged (e.g. imapflow's `idling` flag stuck true after Proton Bridge ended
@@ -95,7 +100,20 @@ const BULK_BATCH_TIMEOUT_MS = 60_000;
 // single-message fetch.
 const LABEL_RESOLVE_PER_FOLDER_TIMEOUT_MS = 5_000;
 const LABEL_RESOLVE_BUDGET_MS = 15_000;
-const UID_VALIDITY_MISMATCH_ERROR = "UID validity mismatch - local index is stale, run sync_emails to refresh";
+// Deliberately not phrased like a generic integrity/checksum failure (that's
+// EMAIL_ID_INVALID_MESSAGE's job in helpers.ts, for a genuinely corrupted
+// id) — this is a *different* failure mode: the id's folder+uid are
+// internally consistent and correctly formed, they just no longer identify
+// a real message, because the mailbox they were minted against was
+// recreated (full recreation, some migration scenarios) between then and
+// now. "Stale index, re-sync" undersold the risk here: re-syncing doesn't
+// make the *old* id valid again, it can only mint new, current ones — the
+// old one must never be silently honored against the new generation.
+// Exported so index.ts's bulk-operation resolution path (getBulkNotFoundEmailIds)
+// can report a stale-generation id with the exact same wording a single-message
+// mutation would raise via assertMailboxUidValidity, rather than drifting into
+// two subtly different phrasings for what is the same underlying failure.
+export const UID_VALIDITY_MISMATCH_ERROR = "This email reference is from before the mailbox changed (folder was recreated or migrated) and no longer points to a valid message. Re-fetch the email (e.g. via search_emails or get_emails) to get a current reference.";
 function collectErrorText(error) {
     const values = [];
     if (error instanceof Error) {
@@ -895,6 +913,7 @@ export class SimpleIMAPService {
             if (total === 0 || offset >= total) {
                 return { folder, total, limit, offset, emails: [] };
             }
+            const uidValidity = (client.mailbox || undefined)?.uidValidity?.toString();
             const emails = [];
             const fetchQuery = input.includeSnippet ? FETCH_DETAIL_QUERY : FETCH_SUMMARY_QUERY;
             if (input.beforeUid !== undefined) {
@@ -917,7 +936,7 @@ export class SimpleIMAPService {
                 }
                 const uidSet = page.join(",");
                 for await (const message of client.fetch(uidSet, fetchQuery, { uid: true })) {
-                    const summary = this.toSummary(folder, message);
+                    const summary = this.toSummary(folder, message, uidValidity);
                     const enriched = input.includeSnippet && message.source
                         ? await this.enrichSummaryFromParsed(summary, await this.parseSource(message.source), false)
                         : summary;
@@ -946,7 +965,7 @@ export class SimpleIMAPService {
                     startSeq = Math.max(1, endSeq - limit + 1);
                 }
                 for await (const message of client.fetch(`${startSeq}:${endSeq}`, fetchQuery)) {
-                    const summary = this.toSummary(folder, message);
+                    const summary = this.toSummary(folder, message, uidValidity);
                     const enriched = input.includeSnippet && message.source
                         ? await this.enrichSummaryFromParsed(summary, await this.parseSource(message.source), false)
                         : summary;
@@ -977,51 +996,145 @@ export class SimpleIMAPService {
         const searchQuery = this.buildSearchQuery(input);
         const collected = [];
         let totalMatched = 0;
+        let anyCandidatesUnexamined = false;
+        // Local-only filters (hasAttachment/attachmentName/label/threadId/senderDomain/
+        // mailboxRole) are everything matchesLocalSearchFilters checks — IMAP SEARCH
+        // (buildSearchQuery above) can't express any of them server-side, so they can
+        // only be evaluated after a candidate's full data is fetched.
+        const hasLocalOnlyFilters = typeof input.hasAttachment === "boolean" ||
+            Boolean(input.threadId) ||
+            Boolean(input.label) ||
+            Boolean(input.attachmentName) ||
+            Boolean(input.senderDomain) ||
+            Boolean(input.mailboxRole);
         for (const folder of folders) {
-            const emails = await this.withMailbox(folder, true, async (client) => {
+            const { results: emails, moreRemain } = await this.withMailbox(folder, true, async (client) => {
                 const searchResult = await client.search(searchQuery, { uid: true });
                 const uids = searchResult || [];
                 totalMatched += uids.length;
                 if (uids.length === 0) {
-                    return [];
+                    return { results: [], moreRemain: false };
                 }
-                // UID order does not track date order (e.g. after a cross-provider import),
-                // so a naive slice(-limit) on UIDs can silently drop the newest messages.
-                // Fetch cheap INTERNALDATE-only headers first, sort by date, then pick the target UIDs.
-                let targetUids = uids;
-                if (uids.length > limit) {
-                    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() });
+                const fetchQuery = input.includeSnippet ? FETCH_DETAIL_QUERY : FETCH_SUMMARY_QUERY;
+                const uidValidity = (client.mailbox || undefined)?.uidValidity?.toString();
+                if (!hasLocalOnlyFilters) {
+                    // UID order does not track date order (e.g. after a cross-provider import),
+                    // so a naive slice(-limit) on UIDs can silently drop the newest messages.
+                    // Fetch cheap INTERNALDATE-only headers first, sort by date, then pick the target UIDs.
+                    let targetUids = uids;
+                    if (uids.length > limit) {
+                        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() });
+                        }
+                        targetUids = pickNewestUids(dated, limit);
+                    }
+                    else {
+                        targetUids = [...uids].reverse();
+                    }
+                    const results = [];
+                    for await (const message of client.fetch(targetUids, fetchQuery, { uid: true })) {
+                        const summary = this.toSummary(folder, message, uidValidity);
+                        const enriched = input.includeSnippet && message.source
+                            ? await this.enrichSummaryFromParsed(summary, await this.parseSource(message.source), false)
+                            : summary;
+                        results.push(enriched);
+                        this.messageCache.set(enriched.id, enriched);
+                        this.capMessageCache();
                     }
-                    targetUids = pickNewestUids(dated, limit);
+                    return { results, moreRemain: false };
                 }
-                else {
-                    targetUids = [...uids].reverse();
+                // A local-only filter narrows the FINAL result, not the IMAP-SEARCH candidate
+                // set — applying it after picking the newest `limit` UIDs (as the branch above
+                // does) can silently drop a genuine match that isn't among the newest `limit`
+                // candidates by date, because it never even gets fetched. E.g.: an older
+                // message with a real attachment, behind a newer attachment-less one, and
+                // limit:1 — the old newest-N selection would pick only the newer non-match and
+                // return nothing, even though a true match exists.
+                //
+                // Fix: order every candidate newest-first by INTERNALDATE (same cheap header
+                // fetch as above), then walk it in bounded batches — fetch a batch, apply the
+                // FULL filter (matchesLocalSearchFilters included) to it, keep genuine matches,
+                // and continue to the next batch only if `limit` genuine matches haven't been
+                // found yet. This mirrors the bounded-batch/resume-cursor reasoning used for
+                // large incremental-sync gaps: bound the work done per call instead of fetching
+                // the entire broad candidate set regardless of `limit`.
+                //
+                // The batch SIZE is deliberately not just `limit` — a caller asking for a small
+                // number of RESULTS (e.g. limit:1) shouldn't force pathologically small network
+                // batches when nothing matches (worst case: one `fetch` call per candidate).
+                // SEARCH_FILTER_BATCH_SIZE is a floor under `limit` for the actual batch size;
+                // the early-stop-once-`limit`-matches-are-found behavior above is unaffected.
+                const batchSize = Math.max(limit, SEARCH_FILTER_BATCH_SIZE);
+                // FETCH_INDEX_QUERY's response already includes BODYSTRUCTURE, which is enough
+                // to resolve hasAttachment (see extractAttachments/toSummary) without fetching
+                // full detail again — so when hasAttachment is the filter, resolve it here and
+                // drop the candidates that already fail it, before they ever reach the detail
+                // fetch loop below.
+                const needsAttachmentPrefilter = typeof input.hasAttachment === "boolean";
+                const dated = [];
+                const hasAttachmentByUid = needsAttachmentPrefilter ? new Map() : undefined;
+                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() });
+                    if (hasAttachmentByUid) {
+                        hasAttachmentByUid.set(message.uid, extractAttachments(message.bodyStructure).length > 0);
+                    }
+                }
+                let orderedUids = pickNewestUids(dated, dated.length);
+                if (hasAttachmentByUid) {
+                    orderedUids = orderedUids.filter((uid) => hasAttachmentByUid.get(uid) === input.hasAttachment);
                 }
                 const results = [];
-                const fetchQuery = input.includeSnippet ? FETCH_DETAIL_QUERY : FETCH_SUMMARY_QUERY;
-                for await (const message of client.fetch(targetUids, fetchQuery, { uid: true })) {
-                    const summary = this.toSummary(folder, message);
-                    const enriched = input.includeSnippet && message.source
-                        ? await this.enrichSummaryFromParsed(summary, await this.parseSource(message.source), false)
-                        : summary;
-                    results.push(enriched);
-                    this.messageCache.set(enriched.id, enriched);
-                    this.capMessageCache();
+                let moreRemain = false;
+                for (let offset = 0; offset < orderedUids.length; offset += batchSize) {
+                    const batch = orderedUids.slice(offset, offset + batchSize);
+                    for await (const message of client.fetch(batch, fetchQuery, { uid: true })) {
+                        const summary = this.toSummary(folder, message, uidValidity);
+                        const enriched = input.includeSnippet && message.source
+                            ? await this.enrichSummaryFromParsed(summary, await this.parseSource(message.source), false)
+                            : summary;
+                        this.messageCache.set(enriched.id, enriched);
+                        this.capMessageCache();
+                        if (matchesLocalSearchFilters(enriched, input)) {
+                            results.push(enriched);
+                        }
+                    }
+                    if (results.length >= limit) {
+                        moreRemain = offset + batchSize < orderedUids.length;
+                        break;
+                    }
                 }
-                // FIX #3: verified — hasAttachment, attachmentName, label, threadId handled above
-                return results.filter((email) => matchesLocalSearchFilters(email, input));
+                return { results, moreRemain };
             });
             collected.push(...emails);
+            anyCandidatesUnexamined = anyCandidatesUnexamined || moreRemain;
         }
         const sorted = sortEmailsByNewest(dedupeEmails(collected)).slice(0, limit);
+        // totalMatched/hasMore mean different things depending on whether a local-only
+        // filter is present:
+        // - No local-only filters: every IMAP-SEARCH candidate is a genuine match (IMAP
+        //   already applied every requested filter), so the raw SEARCH count (totalMatched)
+        //   is exact, and totalMatched > sorted.length is an exact "more exist" signal.
+        // - A local-only filter is present: the raw SEARCH count is pre-filter and can be
+        //   wildly misleading here — e.g. this method's own repro (hasAttachment:true over
+        //   2 candidates where only 1 genuinely matches) would otherwise report
+        //   totalMatched:2 and hasMore:true for a query with nothing further to find.
+        //   Report the exact number of genuine matches found among the candidates actually
+        //   examined instead (not the full universe — an exact post-filter total would
+        //   require scanning every candidate in every folder regardless of `limit`, which
+        //   defeats the bounded-batch fix above), and derive hasMore from whether any
+        //   folder's bounded scan stopped early with candidates still unexamined, or the
+        //   combined cross-folder result was itself truncated to `limit`.
+        const totalMatchedForResponse = hasLocalOnlyFilters ? collected.length : totalMatched;
+        const hasMore = hasLocalOnlyFilters
+            ? anyCandidatesUnexamined || collected.length > sorted.length
+            : totalMatched > sorted.length;
         return {
             folders,
             limit,
             total: sorted.length,
-            totalMatched,
-            hasMore: totalMatched > sorted.length,
+            totalMatched: totalMatchedForResponse,
+            hasMore,
             emails: sorted,
         };
     }
@@ -1214,10 +1327,19 @@ export class SimpleIMAPService {
         return notApplied;
     }
     async markEmailRead(emailId, isRead = true, uidValidity) {
-        const { folder, uid } = parseEmailId(emailId);
+        // The id's own embedded uidValidity (parsed above) is the actual source
+        // of protection — the `uidValidity` parameter only tightens it further
+        // for a caller with some other reason to supply one. Previously this was
+        // backwards: a caller that omitted the parameter (e.g. cli.ts, which
+        // never threaded it) got zero staleness protection even though the id it
+        // passed in already carried a perfectly valid generation. Found live:
+        // delete_email's CLI shortcut on a generation-1 id against a
+        // generation-2 mailbox deleted the message with no error.
+        const { folder, uid, uidValidity: idUidValidity } = parseEmailId(emailId);
+        const expectedUidValidity = uidValidity ?? idUidValidity;
         let notApplied = [];
         await this.withTimeout(this.withMailbox(folder, false, async (client) => {
-            this.assertMailboxUidValidity(client, uidValidity);
+            this.assertMailboxUidValidity(client, expectedUidValidity);
             if (isRead) {
                 await client.messageFlagsAdd(String(uid), ["\\Seen"], { uid: true });
             }
@@ -1243,10 +1365,14 @@ export class SimpleIMAPService {
         return { emailId, folder, uid, isRead, notApplied };
     }
     async starEmail(emailId, isStarred = true, uidValidity) {
-        const { folder, uid } = parseEmailId(emailId);
+        // Same reasoning as markEmailRead above: the id's own embedded
+        // uidValidity is what actually protects this call, the parameter only
+        // tightens it further.
+        const { folder, uid, uidValidity: idUidValidity } = parseEmailId(emailId);
+        const expectedUidValidity = uidValidity ?? idUidValidity;
         let notApplied = [];
         await this.withTimeout(this.withMailbox(folder, false, async (client) => {
-            this.assertMailboxUidValidity(client, uidValidity);
+            this.assertMailboxUidValidity(client, expectedUidValidity);
             if (isStarred) {
                 await client.messageFlagsAdd(String(uid), ["\\Flagged"], { uid: true });
             }
@@ -1263,10 +1389,16 @@ export class SimpleIMAPService {
         return { emailId, folder, uid, isStarred, notApplied };
     }
     async moveEmail(emailId, targetFolder, uidValidity) {
-        const { folder, uid } = parseEmailId(emailId);
+        // Same reasoning as markEmailRead above: the id's own embedded
+        // uidValidity is what actually protects this call, the parameter only
+        // tightens it further. archiveEmail/trashEmail/restoreEmail all delegate
+        // to this method, so they inherit the same protection.
+        const { folder, uid, uidValidity: idUidValidity } = parseEmailId(emailId);
+        const expectedUidValidity = uidValidity ?? idUidValidity;
         let targetUid;
+        let targetFolderUidValidity;
         await this.withTimeout(this.withMailbox(folder, false, async (client) => {
-            this.assertMailboxUidValidity(client, uidValidity);
+            this.assertMailboxUidValidity(client, expectedUidValidity);
             const moved = await client.messageMove(String(uid), targetFolder, { uid: true });
             if (moved === false) {
                 throw new Error(`Server did not move email ${emailId} to ${targetFolder}`);
@@ -1287,10 +1419,25 @@ export class SimpleIMAPService {
             if (targetUid === undefined && client.capabilities.has("UIDPLUS")) {
                 throw new Error(`Email not found for id ${emailId}`);
             }
+            // targetEmailId (below) must embed the *target* folder's own
+            // UIDVALIDITY, not the source folder's — they're different mailboxes
+            // and can carry unrelated values. STATUS works against a
+            // non-selected mailbox (same primitive getFolderStats already uses),
+            // so this doesn't require a second SELECT/lock on targetFolder.
+            // Best-effort: a failure here shouldn't fail an otherwise-successful
+            // move, it just means the returned targetEmailId falls back to the
+            // no-uidValidity (still fully valid, just not staleness-checkable)
+            // format, same as it always did before this field existed.
+            if (targetUid !== undefined) {
+                const targetStatus = await client
+                    .status(targetFolder, { uidValidity: true })
+                    .catch(() => undefined);
+                targetFolderUidValidity = targetStatus?.uidValidity?.toString();
+            }
         }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms moving email ${emailId} to ${targetFolder}`);
         const cached = this.messageCache.get(emailId);
         this.messageCache.delete(emailId);
-        const targetEmailId = targetUid ? createEmailId(targetFolder, targetUid) : undefined;
+        const targetEmailId = targetUid ? createEmailId(targetFolder, targetUid, targetFolderUidValidity) : undefined;
         if (cached && targetUid && targetEmailId) {
             this.messageCache.set(targetEmailId, {
                 ...cached,
@@ -1316,9 +1463,13 @@ export class SimpleIMAPService {
         };
     }
     async deleteEmail(emailId, uidValidity) {
-        const { folder, uid } = parseEmailId(emailId);
+        // Same reasoning as markEmailRead above: the id's own embedded
+        // uidValidity is what actually protects this call, the parameter only
+        // tightens it further.
+        const { folder, uid, uidValidity: idUidValidity } = parseEmailId(emailId);
+        const expectedUidValidity = uidValidity ?? idUidValidity;
         await this.withTimeout(this.withMailbox(folder, false, async (client) => {
-            this.assertMailboxUidValidity(client, uidValidity);
+            this.assertMailboxUidValidity(client, expectedUidValidity);
             // messageDelete's own truthy/falsy result only reflects whether the
             // server accepted the EXPUNGE command, not whether any message
             // actually matched — a nonexistent UID's preceding \Deleted flag add
@@ -1349,8 +1500,12 @@ export class SimpleIMAPService {
             deleted: true,
         };
     }
-    async updateMessageLabels(emailId, labelsToAdd, labelsToRemove) {
-        const { folder, uid } = parseEmailId(emailId);
+    async updateMessageLabels(emailId, labelsToAdd, labelsToRemove, uidValidity) {
+        // Same reasoning as markEmailRead above: the id's own embedded
+        // uidValidity is what actually protects this call, the parameter only
+        // tightens it further.
+        const { folder, uid, uidValidity: idUidValidity } = parseEmailId(emailId);
+        const expectedUidValidity = uidValidity ?? idUidValidity;
         const added = [];
         const removed = [];
         const notFound = [];
@@ -1369,6 +1524,7 @@ export class SimpleIMAPService {
         let messageId;
         let sourceExists = false;
         await this.withTimeout(this.withMailbox(folder, true, async (client) => {
+            this.assertMailboxUidValidity(client, expectedUidValidity);
             const msg = await client.fetchOne(String(uid), { uid: true, envelope: true }, { uid: true });
             if (msg !== false) {
                 sourceExists = true;
@@ -1433,10 +1589,14 @@ export class SimpleIMAPService {
         return { emailId, added, removed, notFound, failedLabels: failedLabels.length > 0 ? failedLabels : undefined };
     }
     async updateMessageFlags(emailId, flagsToAdd, flagsToRemove, uidValidity) {
-        const { folder, uid } = parseEmailId(emailId);
+        // Same reasoning as markEmailRead above: the id's own embedded
+        // uidValidity is what actually protects this call, the parameter only
+        // tightens it further.
+        const { folder, uid, uidValidity: idUidValidity } = parseEmailId(emailId);
+        const expectedUidValidity = uidValidity ?? idUidValidity;
         let notApplied = [];
         await this.withTimeout(this.withMailbox(folder, false, async (client) => {
-            this.assertMailboxUidValidity(client, uidValidity);
+            this.assertMailboxUidValidity(client, expectedUidValidity);
             if (flagsToAdd.length > 0) {
                 await client.messageFlagsAdd(String(uid), flagsToAdd, { uid: true });
             }
@@ -1495,11 +1655,26 @@ export class SimpleIMAPService {
             };
         });
     }
+    // Lightweight, lock-free UIDVALIDITY lookup — IMAP STATUS works against a
+    // mailbox that isn't currently SELECTed, so this doesn't need (and
+    // deliberately avoids) taking a getMailboxLock the way withMailbox does.
+    // Used at bulk-operation resolution time (resolveUidsForBulkOp) to learn
+    // the folder's *current* generation once, up front, so every id in the
+    // batch can be checked against that single point-in-time value rather than
+    // each mutation discovering staleness independently and inconsistently
+    // partway through the batch.
+    async getMailboxUidValidity(folder) {
+        const client = await this.ensureConnected();
+        const status = await client.status(folder, { uidValidity: true });
+        return status?.uidValidity?.toString();
+    }
     async emptyFolder(folder) {
         if (folder.toUpperCase() === "INBOX") {
             throw new Error("emptyFolder cannot be used on INBOX. Move messages to Trash first.");
         }
+        let folderUidValidity;
         const uids = await this.withTimeout(this.withMailbox(folder, true, async (client) => {
+            folderUidValidity = (client.mailbox || undefined)?.uidValidity?.toString();
             const found = await client.search({ all: true }, { uid: true });
             return Array.isArray(found) ? found : [];
         }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms listing messages to empty in ${folder}`);
@@ -1510,9 +1685,11 @@ export class SimpleIMAPService {
         await this.withTimeout(this.withMailbox(folder, false, async (client) => {
             await client.messageDelete(uidSet, { uid: true });
         }), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms emptying folder ${folder}`);
-        // Purge from cache
+        // Purge from cache — must reconstruct the exact same id toSummary/etc.
+        // would have cached these messages under (including the folder's
+        // UIDVALIDITY at the time), or a stale cache entry survives this purge.
         for (const uid of uids) {
-            this.messageCache.delete(createEmailId(folder, uid));
+            this.messageCache.delete(createEmailId(folder, uid, folderUidValidity));
         }
         this.folderCache = undefined;
         return { folder, deleted: uids.length };
@@ -1528,7 +1705,18 @@ export class SimpleIMAPService {
     // maxBatchSize 1, a first resolution returned [1], a second (between the
     // dry-run check and the real run) returned [1,2], and the real run acted
     // on both — silently exceeding the limit.
-    async resolveUidsForBulkOp(folder, emailIds, match) {
+    async resolveUidsForBulkOp(folder, emailIds, match, 
+    // Pre-fetched current UIDVALIDITY for `folder`, from a single shared
+    // getMailboxUidValidity call at the top of the caller's bulk handler
+    // (see index.ts's bulk_delete/bulk_update_flags/bulk_update_labels
+    // cases) — reused here instead of resolveUidsForBulkOp fetching its own,
+    // so the exact same point-in-time value backs both the uid resolution
+    // below and index.ts's own stale-id reporting (getBulkNotFoundEmailIds).
+    // Callers with no pre-fetched value (e.g. bulkMove's internal call,
+    // which has no resolve-once wiring of its own) leave this undefined and
+    // resolveUidsForBulkOp fetches it itself, so the staleness check below
+    // still applies uniformly to every bulk entry point.
+    currentUidValidity) {
         if (emailIds !== undefined && match !== undefined) {
             throw new Error("Provide either emailIds or match, not both");
         }
@@ -1536,6 +1724,7 @@ export class SimpleIMAPService {
             throw new Error("Provide either emailIds or match");
         }
         if (emailIds !== undefined) {
+            const uidValidity = currentUidValidity ?? (await this.getMailboxUidValidity(folder));
             // parseEmailId throws on anything malformed. index.ts's
             // getBulkNotFoundEmailIds already expects a bad/wrong-folder id to be
             // silently excluded here and reported separately as notFound — but a
@@ -1543,6 +1732,16 @@ export class SimpleIMAPService {
             // live: bulk_move with 10 valid ids and one malformed one threw
             // "Invalid emailId" and moved none of the 10 valid ones, instead of
             // moving them and reporting just the bad one as notFound.
+            //
+            // Same exclude-not-throw treatment now applies to a *stale* id (one
+            // whose embedded uidValidity doesn't match the folder's current
+            // generation) — excluded from the uids this batch actually acts on,
+            // rather than either silently resolving against the wrong-generation
+            // UID or failing the whole batch over one stale entry. An id with no
+            // embedded uidValidity at all (pre-this-fix format) is unverifiable,
+            // not stale — same "can't check it, so don't block on it" stance
+            // assertMailboxUidValidity already takes for the single-message
+            // mutation path.
             return emailIds
                 .map((id) => {
                 try {
@@ -1552,7 +1751,9 @@ export class SimpleIMAPService {
                     return undefined;
                 }
             })
-                .filter((parsed) => parsed !== undefined && parsed.folder === folder)
+                .filter((parsed) => parsed !== undefined &&
+                parsed.folder === folder &&
+                (parsed.uidValidity === undefined || parsed.uidValidity === uidValidity))
                 .map((parsed) => parsed.uid);
         }
         // match path
@@ -1611,10 +1812,17 @@ export class SimpleIMAPService {
         const results = [];
         if (uids.length > 0) {
             const uidSet = uids.join(",");
+            // Captured for the source-folder emailIds built below — these
+            // identify the *pre-move* message (source folder + uid), matching
+            // sourceEmailId's role in the single-email moveEmail, not a
+            // resolvable post-move reference, so the source folder's own
+            // UIDVALIDITY (not the target's) is the correct one to embed.
+            let sourceUidValidity;
             try {
                 let uidMap;
                 let hasUidPlus = false;
                 await this.withTimeout(this.withMailbox(folder, false, async (client) => {
+                    sourceUidValidity = (client.mailbox || undefined)?.uidValidity?.toString();
                     const moved = await client.messageMove(uidSet, input.targetFolder, { uid: true });
                     if (moved === false) {
                         throw new Error(`Server did not move uid set ${uidSet}`);
@@ -1623,7 +1831,7 @@ export class SimpleIMAPService {
                     hasUidPlus = client.capabilities.has("UIDPLUS");
                 }), BULK_BATCH_TIMEOUT_MS, `Timed out after ${BULK_BATCH_TIMEOUT_MS}ms moving uid set ${uidSet}`);
                 for (const uid of uids) {
-                    const emailId = createEmailId(folder, uid);
+                    const emailId = createEmailId(folder, uid, sourceUidValidity);
                     // `moved === false` above only catches an empty/invalid range,
                     // not a syntactically valid UID that doesn't match any message —
                     // IMAP's MOVE silently succeeds with nothing moved in that case
@@ -1646,7 +1854,7 @@ export class SimpleIMAPService {
             }
             catch (err) {
                 for (const uid of uids) {
-                    const emailId = createEmailId(folder, uid);
+                    const emailId = createEmailId(folder, uid, sourceUidValidity);
                     results.push({ uid, emailId, ok: false, error: String(err) });
                     failed++;
                 }
@@ -1682,6 +1890,7 @@ export class SimpleIMAPService {
         const results = [];
         if (uids.length > 0) {
             const uidSet = uids.join(",");
+            let folderUidValidity;
             try {
                 let existingUids;
                 if (input.permanent || !trashFolder) {
@@ -1694,10 +1903,17 @@ export class SimpleIMAPService {
                     // after the fact. Found live: bulk_delete with one real id and
                     // one deliberately fake one reported ok:true for both.
                     existingUids = await this.withMailbox(folder, true, async (client) => {
+                        folderUidValidity = (client.mailbox || undefined)?.uidValidity?.toString();
                         const found = await client.search({ uid: uidSet }, { uid: true });
                         return new Set(Array.isArray(found) ? found : []);
                     });
                     await this.withMailbox(folder, false, async (client) => {
+                        // Re-verify the generation resolvedUids was resolved under,
+                        // inside the same lock the actual delete runs under — the
+                        // filtering in resolveUidsForBulkOp only caught a stale id at
+                        // resolution time, not a mailbox change in the gap between then
+                        // and this lock being acquired.
+                        this.assertMailboxUidValidity(client, input.uidValidity);
                         const deleted = await client.messageDelete(uidSet, { uid: true });
                         if (!deleted)
                             throw new Error(`Server did not delete uid set ${uidSet}`);
@@ -1707,6 +1923,9 @@ export class SimpleIMAPService {
                     let uidMap;
                     let hasUidPlus = false;
                     await this.withMailbox(folder, false, async (client) => {
+                        folderUidValidity = (client.mailbox || undefined)?.uidValidity?.toString();
+                        // Same lock-scoped re-check as the permanent-delete branch above.
+                        this.assertMailboxUidValidity(client, input.uidValidity);
                         const moved = await client.messageMove(uidSet, trashFolder, { uid: true });
                         if (moved === false)
                             throw new Error(`Server did not move uid set ${uidSet} to trash`);
@@ -1718,7 +1937,7 @@ export class SimpleIMAPService {
                     existingUids = hasUidPlus && uidMap ? new Set(uidMap.keys()) : new Set(uids);
                 }
                 for (const uid of uids) {
-                    const emailId = createEmailId(folder, uid);
+                    const emailId = createEmailId(folder, uid, folderUidValidity);
                     if (!existingUids.has(uid)) {
                         results.push({ uid, emailId, ok: false, error: `Email not found for uid ${uid}` });
                         failed++;
@@ -1730,9 +1949,10 @@ export class SimpleIMAPService {
                 }
             }
             catch (err) {
+                const error = this.bulkExecutionErrorMessage(err);
                 for (const uid of uids) {
-                    const emailId = createEmailId(folder, uid);
-                    results.push({ uid, emailId, ok: false, error: String(err) });
+                    const emailId = createEmailId(folder, uid, folderUidValidity);
+                    results.push({ uid, emailId, ok: false, error });
                     failed++;
                 }
             }
@@ -1766,9 +1986,15 @@ export class SimpleIMAPService {
         const results = [];
         if (uids.length > 0) {
             const uidSet = uids.join(",");
+            let folderUidValidity;
             try {
                 const notAppliedByUid = new Map();
                 await this.withMailbox(folder, false, async (client) => {
+                    folderUidValidity = (client.mailbox || undefined)?.uidValidity?.toString();
+                    // Re-verify the generation resolvedUids was resolved under,
+                    // inside the same lock the flag mutation runs under — see
+                    // bulkDelete's identical check for the full rationale.
+                    this.assertMailboxUidValidity(client, input.uidValidity);
                     if (flagsToAdd.length > 0) {
                         await client.messageFlagsAdd(uidSet, flagsToAdd, { uid: true });
                     }
@@ -1785,7 +2011,7 @@ export class SimpleIMAPService {
                     }
                 });
                 for (const uid of uids) {
-                    const emailId = createEmailId(folder, uid);
+                    const emailId = createEmailId(folder, uid, folderUidValidity);
                     // A UID absent from the fetch loop above (never got a
                     // notAppliedByUid entry) means the IMAP FETCH found no message
                     // for it — the earlier STORE call already silently no-op'd for
@@ -1804,9 +2030,10 @@ export class SimpleIMAPService {
                 }
             }
             catch (err) {
+                const error = this.bulkExecutionErrorMessage(err);
                 for (const uid of uids) {
-                    const emailId = createEmailId(folder, uid);
-                    results.push({ uid, emailId, ok: false, error: String(err) });
+                    const emailId = createEmailId(folder, uid, folderUidValidity);
+                    results.push({ uid, emailId, ok: false, error });
                     failed++;
                 }
             }
@@ -1837,8 +2064,30 @@ export class SimpleIMAPService {
         let succeeded = 0;
         let failed = 0;
         const results = [];
+        // Fetched once for the whole batch rather than inside the per-uid loop
+        // below — resolveUidsForBulkOp already validated every uid against this
+        // exact generation at resolution time; re-passing that same value into
+        // each updateMessageLabels call below is a cheap, no-extra-round-trip
+        // defense-in-depth recheck (updateMessageLabels's own withMailbox call
+        // re-verifies it against the *live* mailbox at execution time), not a
+        // second independent resolution.
+        const folderUidValidity = input.uidValidity ?? await this.getMailboxUidValidity(folder).catch(() => undefined);
+        // Unlike bulkDelete/bulkUpdateFlags (one command mutating the whole uid
+        // set under a single withMailbox lock), labels are applied per-uid,
+        // each under its own lock via updateMessageLabels. So a lock-scoped
+        // generation mismatch can only be caught per-uid, not once up front —
+        // but per the same "fail the whole batch, not just this id" contract,
+        // once one is caught the rest of the batch is aborted too rather than
+        // silently continuing to mutate under a mailbox that's no longer the
+        // one this batch was resolved against.
+        let batchAborted = false;
         for (const uid of uids) {
-            const emailId = createEmailId(folder, uid);
+            const emailId = createEmailId(folder, uid, folderUidValidity);
+            if (batchAborted) {
+                results.push({ uid, emailId, ok: false, error: this.bulkExecutionErrorMessage(new Error(UID_VALIDITY_MISMATCH_ERROR)) });
+                failed++;
+                continue;
+            }
             try {
                 // updateMessageLabels never throws for a failed COPY/removal — it
                 // catches per-label and reports failures via its own return value
@@ -1850,7 +2099,7 @@ export class SimpleIMAPService {
                 // adding a brand-new label reported ok:true for an item whose label
                 // folder was never actually created — get_folders afterward showed
                 // no such folder at all.
-                const result = await this.withTimeout(this.updateMessageLabels(emailId, labelsToAdd, labelsToRemove), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms updating labels for ${emailId}`);
+                const result = await this.withTimeout(this.updateMessageLabels(emailId, labelsToAdd, labelsToRemove, folderUidValidity), BULK_ITEM_TIMEOUT_MS, `Timed out after ${BULK_ITEM_TIMEOUT_MS}ms updating labels for ${emailId}`);
                 if (result.failedLabels && result.failedLabels.length > 0) {
                     results.push({
                         uid,
@@ -1866,7 +2115,10 @@ export class SimpleIMAPService {
                 }
             }
             catch (err) {
-                results.push({ uid, emailId, ok: false, error: String(err) });
+                if (err instanceof Error && err.message === UID_VALIDITY_MISMATCH_ERROR) {
+                    batchAborted = true;
+                }
+                results.push({ uid, emailId, ok: false, error: this.bulkExecutionErrorMessage(err) });
                 failed++;
             }
         }
@@ -1953,8 +2205,10 @@ export class SimpleIMAPService {
         }
         for (const folder of foldersToSearch) {
             try {
+                let folderUidValidity;
                 const [byMsgId, byRefs] = await Promise.all([
                     this.withMailbox(folder, true, async (client) => {
+                        folderUidValidity = (client.mailbox || undefined)?.uidValidity?.toString();
                         const found = await client.search({ header: { "Message-ID": messageId } }, { uid: true });
                         return Array.isArray(found) ? found : [];
                     }).catch(() => []),
@@ -1967,7 +2221,7 @@ export class SimpleIMAPService {
                 for (const uid of [...byMsgId, ...byRefs]) {
                     if (!seen.has(uid)) {
                         seen.add(uid);
-                        results.push({ folder, uid, emailId: createEmailId(folder, uid) });
+                        results.push({ folder, uid, emailId: createEmailId(folder, uid, folderUidValidity) });
                     }
                 }
             }
@@ -2165,7 +2419,7 @@ export class SimpleIMAPService {
             const fetchQuery = needsFullDetail ? FETCH_INDEX_DETAIL_QUERY : FETCH_INDEX_QUERY;
             const emails = [];
             for await (const message of client.fetch(`${plan.startUid}:${plan.endUid}`, fetchQuery, { uid: true })) {
-                const summary = this.toSummary(folder, message);
+                const summary = this.toSummary(folder, message, uidValidity);
                 const enriched = message.source
                     ? this.enrichSummaryFromParsed(summary, await this.parseSource(message.source), input.includeAttachmentText)
                     : summary;
@@ -2211,17 +2465,17 @@ export class SimpleIMAPService {
             };
         });
     }
-    async archiveEmail(emailId) {
+    async archiveEmail(emailId, uidValidity) {
         const targetFolder = await this.resolveSpecialFolder("\\Archive", ["Archive", "All Mail"]);
-        return this.moveEmail(emailId, targetFolder);
+        return this.moveEmail(emailId, targetFolder, uidValidity);
     }
-    async trashEmail(emailId) {
+    async trashEmail(emailId, uidValidity) {
         const targetFolder = await this.resolveSpecialFolder("\\Trash", ["Trash"]);
-        return this.moveEmail(emailId, targetFolder);
+        return this.moveEmail(emailId, targetFolder, uidValidity);
     }
-    async restoreEmail(emailId, targetFolder) {
+    async restoreEmail(emailId, targetFolder, uidValidity) {
         const destination = targetFolder?.trim() || (await this.resolveSpecialFolder("\\Inbox", ["INBOX"]));
-        return this.moveEmail(emailId, destination);
+        return this.moveEmail(emailId, destination, uidValidity);
     }
     async getAnalyticsSample(days = 30, limitPerFolder = 100) {
         const dateFrom = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
@@ -2260,6 +2514,15 @@ export class SimpleIMAPService {
         if (!uid) {
             uid = await this.findUidByHeader(folder, "message-id", input.messageId);
         }
+        // STATUS works against a mailbox that isn't currently SELECTed (same
+        // reasoning as getMailboxUidValidity/getFolderStats) — append() above
+        // doesn't guarantee `folder` is selected on this client, so this can't
+        // just read client.mailbox.uidValidity the way a withMailbox callback
+        // would. Best-effort: a failure here shouldn't fail an otherwise-
+        // successful append, it just means the returned emailId falls back to
+        // the no-uidValidity format, same as it always did before this field
+        // existed.
+        const uidValidity = uid ? await this.getMailboxUidValidity(folder).catch(() => undefined) : undefined;
         this.folderCache = undefined;
         this.lastSyncAt = new Date().toISOString();
         // Build the result BEFORE attempting to clean up the superseded old
@@ -2276,7 +2539,7 @@ export class SimpleIMAPService {
         const result = {
             folder,
             uid,
-            emailId: uid ? createEmailId(folder, uid) : undefined,
+            emailId: uid ? createEmailId(folder, uid, uidValidity) : undefined,
             messageId: input.messageId,
             syncedAt: this.lastSyncAt,
         };
@@ -2426,11 +2689,11 @@ export class SimpleIMAPService {
             return [...result].sort((left, right) => right - left)[0];
         });
     }
-    toSummary(folder, message) {
+    toSummary(folder, message, uidValidity) {
         const flags = [...(message.flags ?? [])];
         const attachments = extractAttachments(message.bodyStructure);
         return {
-            id: createEmailId(folder, message.uid),
+            id: createEmailId(folder, message.uid, uidValidity),
             folder,
             uid: message.uid,
             seq: message.seq,
@@ -2484,17 +2747,25 @@ export class SimpleIMAPService {
         return simpleParser(source);
     }
     async getParsedMailDetail(emailId) {
-        const { folder, uid } = parseEmailId(emailId);
+        const { folder, uid, uidValidity: expectedUidValidity } = parseEmailId(emailId);
         const { enriched, parsed } = await this.withTimeout(this.withMailbox(folder, true, async (client) => {
-            // NOTE: UIDs can be reused after mailbox recreation (UIDVALIDITY change).
-            // assertMailboxUidValidity handles this at the withMailbox level for mutating
-            // ops. For read-only fetches, callers should re-sync after a UIDVALIDITY
-            // change to avoid fetching the wrong message with a recycled UID.
+            // UIDs can be reused after mailbox recreation (UIDVALIDITY change).
+            // This backs content reads used for quoting/forwarding/replying, so a
+            // stale id here isn't just a failed fetch — it silently returns a
+            // *different real message's* content under a freshly-recomputed,
+            // correct-looking-for-that-message new id, with no error at all.
+            // Found live: get_email_by_id on a generation-1 id for UID 42 against
+            // a generation-2 mailbox with a different message at UID 42 returned
+            // that other message's subject/content with no exception. Enforce the
+            // same check mutations already do; an id with no embedded
+            // uidValidity (pre-this-fix format) still no-ops here via
+            // assertMailboxUidValidity's own `if (!expectedUidValidity) return`.
+            this.assertMailboxUidValidity(client, expectedUidValidity);
             const message = await client.fetchOne(String(uid), FETCH_DETAIL_QUERY, { uid: true });
             if (!message || !message.source) {
                 throw new Error(`Email not found for id ${emailId}`);
             }
-            const summary = this.toSummary(folder, message);
+            const summary = this.toSummary(folder, message, (client.mailbox || undefined)?.uidValidity?.toString());
             const parsed = await this.parseSource(message.source);
             const enriched = this.enrichSummaryFromParsed(summary, parsed, true);
             return { enriched, parsed };
@@ -2844,6 +3115,20 @@ export class SimpleIMAPService {
             throw new Error(UID_VALIDITY_MISMATCH_ERROR);
         }
     }
+    // Distinguishes a bulk batch's execution-time generation mismatch (caught
+    // here, from assertMailboxUidValidity re-checking the whole resolved set
+    // right before the mutation) from the per-id "this one id's own embedded
+    // generation was stale" filtering resolveUidsForBulkOp already does before
+    // the batch ever gets here. Both ultimately trace back to the same
+    // UID_VALIDITY_MISMATCH_ERROR wording, but callers need to tell them apart:
+    // this one means the *entire* resolved batch was invalidated by a mailbox
+    // change after resolution, not just some individual ids.
+    bulkExecutionErrorMessage(err) {
+        if (err instanceof Error && err.message === UID_VALIDITY_MISMATCH_ERROR) {
+            return `Bulk operation aborted: the mailbox's UIDVALIDITY changed after this batch's UIDs were resolved and before the mutation ran, invalidating the entire resolved batch (not just individual ids). ${UID_VALIDITY_MISMATCH_ERROR}`;
+        }
+        return String(err);
+    }
     async writeAttachmentToPath(emailId, attachment, outputPath) {
         let outputFilePath;
         if (!outputPath) {
@@ -3034,12 +3319,14 @@ export class SimpleIMAPService {
             // Best-effort — an unparseable message still gets imported below.
         }
         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);
             if (existingUid !== undefined) {
-                const existingEmailId = createEmailId(folder, existingUid);
+                const existingEmailId = createEmailId(folder, existingUid, existingFolderUidValidity);
                 return { folder, uid: existingUid, emailId: existingEmailId, alreadyExists: true, existingEmailId };
             }
         }
@@ -3052,9 +3339,15 @@ export class SimpleIMAPService {
         if (!uid && messageId) {
             uid = await this.findUidByHeader(folder, "message-id", messageId);
         }
+        // Best-effort, same reasoning as upsertRemoteDraft's identical lookup —
+        // append() doesn't guarantee `folder` stays selected on this client, so
+        // STATUS (works on a non-selected mailbox) is used instead of trusting
+        // client.mailbox here. A failure just falls back to the no-uidValidity
+        // format, same as before this field existed.
+        const uidValidity = uid ? await this.getMailboxUidValidity(folder).catch(() => undefined) : undefined;
         this.folderCache = undefined;
         this.lastSyncAt = new Date().toISOString();
-        return { folder, uid, emailId: uid ? createEmailId(folder, uid) : undefined };
+        return { folder, uid, emailId: uid ? createEmailId(folder, uid, uidValidity) : undefined };
     }
 }
 //# sourceMappingURL=simple-imap-service.js.map