imapflow 2.2.7 → 2.2.8

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.2.8](https://github.com/postalsys/imapflow/compare/v2.2.7...v2.2.8) (2026-10-07)
+
+
+### Bug Fixes
+
+* decrement mailbox.exists on untagged VANISHED (RFC 7162 section 3.2.10) ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* do not send sequence sets to an empty mailbox ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* drop flags and keywords that are not atoms instead of sending them quoted ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* encode and decode non-ASCII Gmail labels as modified UTF-7 like mailbox names ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* expand the FETCH ALL, FAST and FULL macros instead of sending them in a list ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* leave servername out of tls.connect() for IP literal hosts, which Bun rejects ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* refetch body sections Apache James drops, check FETCH answers belong to the download, enable CONDSTORE with QRESYNC ([6973263](https://github.com/postalsys/imapflow/commit/697326393a4a66e743822d7fb0ac045454458492))
+* send the OAuth token after the continuation request when SASL-IR is not advertised ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* send the STORE UNCHANGEDSINCE modifier before the flags (RFC 7162 section 3.1.3) ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+
 ## [2.2.7](https://github.com/postalsys/imapflow/compare/v2.2.6...v2.2.7) (2026-10-07)
 
 

package/dist/cjs/commands/authenticate.js

@@ -66,15 +66,26 @@ async function authOauth(connection, username, accessToken) {
         // Empty breaker: XOAUTH2 expects an empty response to abort the SASL exchange
         breaker = '';
     }
+    let encoded = Buffer.from(oauthbearer).toString('base64');
+    // Without SASL-IR the payload may not ride on the command line (RFC 4959 section 3): it is
+    // sent as the answer to the first, empty continuation request instead
+    let payloadPending = !connection.capabilities.has('SASL-IR');
     let errorResponse = false;
     try {
-        let response = await connection.exec('AUTHENTICATE', [
-            { type: 'ATOM', value: command },
-            { type: 'ATOM', value: Buffer.from(oauthbearer).toString('base64'), sensitive: true }
-        ], {
+        let attributes = [{ type: 'ATOM', value: command }];
+        if (!payloadPending) {
+            attributes.push({ type: 'ATOM', value: encoded, sensitive: true });
+        }
+        let response = await connection.exec('AUTHENTICATE', attributes, {
             // Server sends a "+" continuation if auth fails, with a base64 JSON error payload.
             // We decode it for diagnostics, then send the breaker to terminate the exchange.
             onPlusTag: async (resp) => {
+                if (payloadPending) {
+                    payloadPending = false;
+                    connection.log.debug({ src: 'c', msg: '(* value hidden *)', comment: `Encoded response for AUTH=${command}`, cid: connection.id });
+                    connection.write(encoded);
+                    return;
+                }
                 if (resp.attributes && resp.attributes[0] && resp.attributes[0].type === 'TEXT') {
                     try {
                         errorResponse = JSON.parse(Buffer.from(resp.attributes[0].value, 'base64').toString());

package/dist/cjs/commands/enable.js

@@ -49,6 +49,12 @@ async function enable(connection, extensionList) {
         // extensions enabled by this command (RFC 5161), so a replace would drop
         // grants from an earlier ENABLE call
         connection.enabled = new Set([...connection.enabled, ...enabled]);
+        if (connection.enabled.has('QRESYNC')) {
+            // ENABLE QRESYNC is a CONDSTORE enabling command (RFC 7162 3.2.3), whether or not the
+            // server lists CONDSTORE in its ENABLED answer. Apache James advertises only QRESYNC
+            // and leaves a lone ENABLE CONDSTORE unanswered, which the RFC allows.
+            connection.enabled.add('CONDSTORE');
+        }
         response.next();
         return connection.enabled;
     }

package/dist/cjs/commands/fetch.js

@@ -65,13 +65,30 @@ async function fetch(connection, range, query, options) {
                 };
                 queryStructure.push(bodyPeek);
             };
-            // IMAP fetch macros (ALL, FAST, FULL) and standard data items map directly to IMAP atoms
-            ['all', 'fast', 'full', 'uid', 'flags', 'bodyStructure', 'envelope', 'internalDate'].forEach(key => {
-                if (query[key]) {
+            // The ALL, FAST and FULL macros may only be sent on their own, never in a list with other
+            // items (RFC 3501 section 9), and UID is always in the list, so they are expanded into
+            // the items they stand for. FULL is expanded to BODYSTRUCTURE rather than the
+            // non-extensible BODY, as documented for the full option.
+            let full = !!query.full;
+            let all = !!query.all || full;
+            let fast = !!query.fast || all;
+            let items = {
+                flags: query.flags || fast,
+                internalDate: query.internalDate || fast,
+                size: query.size || fast,
+                envelope: query.envelope || all,
+                bodyStructure: query.bodyStructure || full
+            };
+            // standard data items map directly to IMAP atoms
+            if (query.uid) {
+                queryStructure.push({ type: 'ATOM', value: 'UID' });
+            }
+            ['flags', 'bodyStructure', 'envelope', 'internalDate'].forEach(key => {
+                if (items[key]) {
                     queryStructure.push({ type: 'ATOM', value: key.toUpperCase() });
                 }
             });
-            if (query.size) {
+            if (items.size) {
                 queryStructure.push({ type: 'ATOM', value: 'RFC822.SIZE' });
             }
             // Fetch full message source, optionally with byte range (start/maxLength)
@@ -194,7 +211,7 @@ async function fetch(connection, range, query, options) {
                         if (consumerError) {
                             return;
                         }
-                        let formatted = await (0, tools_js_1.formatMessageResponse)(untagged, mailbox, connection.idHashAlgorithm);
+                        let formatted = await (0, tools_js_1.formatMessageResponse)(untagged, mailbox, connection.idHashAlgorithm, connection);
                         if (typeof options.onUntaggedFetch === 'function') {
                             /* c8 ignore next */ // a UID FETCH row without its UID is a non-compliant server, so the seq fallback is not exercised
                             let key = options.uid ? formatted.uid || formatted.seq : formatted.seq;

package/dist/cjs/commands/store.js

@@ -61,7 +61,10 @@ async function store(connection, range, flags, options) {
     const dropped = [];
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
         .map(flag => {
-        let formatted = (0, tools_js_1.formatFlag)(flag);
+        // Gmail labels other than the \-prefixed system labels are mailbox names: astrings in
+        // the form mailbox names take on the session (modified UTF-7 unless UTF-8 is enabled),
+        // not atoms like IMAP keywords
+        let formatted = options.useLabels && flag && flag.charAt(0) !== '\\' ? (0, tools_js_1.encodePath)(connection, flag) : (0, tools_js_1.formatFlag)(flag);
         if (!formatted || (!(0, tools_js_1.canUseFlag)(flagSource, formatted) && operationName !== 'remove')) {
             dropped.push(flag);
             return false;
@@ -83,13 +86,10 @@ async function store(connection, range, flags, options) {
     if (!flags.length && !clearAll) {
         return false;
     }
-    let attributes = [
-        { type: 'SEQUENCE', value: range },
-        { type: 'ATOM', value: operation },
-        flags.map(flag => ({ type: 'ATOM', value: flag }))
-    ];
+    let attributes = [{ type: 'SEQUENCE', value: range }];
     // CONDSTORE (RFC 7162): UNCHANGEDSINCE modifier prevents updating messages whose
     // mod-sequence is higher than the specified value, avoiding overwriting concurrent changes.
+    // The store-modifiers list goes between the sequence set and the item name (section 3.1.3).
     if (options.unchangedSince && connection.enabled.has('CONDSTORE') && !mailbox.noModseq) {
         attributes.push([
             {
@@ -102,6 +102,7 @@ async function store(connection, range, flags, options) {
             }
         ]);
     }
+    attributes.push({ type: 'ATOM', value: operation }, flags.map(flag => ({ type: 'ATOM', value: flag })));
     let response;
     try {
         response = await connection.exec(options.uid ? 'UID STORE' : 'STORE', attributes);

package/dist/cjs/download.js

@@ -19,6 +19,113 @@ const limited_passthrough_js_1 = require("./limited-passthrough.js");
 // away (a consumer destroying it closes it without a 'drain')
 const DRAIN_WAIT_EVENTS = ['drain', 'error', 'close'];
 const tools_js_1 = require("./tools.js");
+const isEmptySection = (value) => !value?.length;
+/**
+ * The section to ask again when exactly one of a part's MIME headers and content came back
+ * empty (see refetchDroppedSections()), undefined when both or neither did
+ */
+const droppedSection = (mime, content, mimeRequest, contentRequest) => {
+    if (isEmptySection(mime) === isEmptySection(content)) {
+        return undefined;
+    }
+    return isEmptySection(content) ? contentRequest : mimeRequest;
+};
+/** Start offset of every partial section among the requests, keyed by section */
+const partialStarts = (requests) => {
+    let starts = new Map();
+    for (let request of requests) {
+        if (typeof request !== 'string') {
+            starts.set(request.key, Number(request.start) || 0);
+        }
+    }
+    return starts;
+};
+// How many times a request is repeated after answers that belong to another request
+const MAX_FOREIGN_ANSWERS = 3;
+const requestedUid = (range, options) => options.uid && /^\d+$/.test(String(range)) ? Number(range) : undefined;
+const isForeignAnswer = (response, expected) => {
+    if (expected.uid && response.uid && response.uid !== expected.uid) {
+        return true;
+    }
+    for (let [key, start] of expected.origins) {
+        let origin = response.partialOrigins && response.partialOrigins.get(key);
+        // An answer without the origin is taken as is: some servers leave it out, and some
+        // ignore the partial specifier altogether
+        if (typeof origin === 'number' && origin !== start) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * fetchOne() that takes only an answer belonging to the request. Apache James now and then
+ * writes the head of a FETCH answer after its tagged OK, so the data of one request shows up
+ * within the answer to the next one. Taken at face value it would be the data of that next
+ * request, and a download would end without an error but with misplaced bytes. An answer for
+ * another UID, or with a partial section that starts at another offset than asked, is dropped
+ * and the request repeated.
+ */
+async function fetchExpected(client, range, query, options, expected) {
+    for (let attempt = 1;; attempt++) {
+        let response = await client.fetchOne(range, query, options);
+        if (!response || !isForeignAnswer(response, expected)) {
+            return response;
+        }
+        client.log.warn({
+            msg: 'Server answered with data of another request, asking again',
+            uid: response.uid,
+            origins: response.partialOrigins && Object.fromEntries(response.partialOrigins),
+            attempt,
+            cid: client.id
+        });
+        if (attempt >= MAX_FOREIGN_ANSWERS) {
+            let err = new Error('Server kept answering with data of another request');
+            err.code = 'DownloadIncomplete';
+            err.cid = client.id;
+            throw err;
+        }
+    }
+}
+/**
+ * Apache James (and the servers built on it, Twake Mail among them) answers only the first
+ * section it is asked for each MIME part of one FETCH and returns the other one empty:
+ * BODY[2.MIME] with BODY[2] yields the headers and a zero-length body, the reverse order loses
+ * the headers (FetchGroup.addPartContent() keeps the first descriptor for a part path). Asks the
+ * sections that came back empty again, in a FETCH of their own, and merges the answer into
+ * `response`. Callers only list a section whose companion did arrive, so a compliant server
+ * pays the extra round trip only for a part that really is empty.
+ */
+async function refetchDroppedSections(client, response, range, options, sections) {
+    if (!sections.length) {
+        return;
+    }
+    client.log.debug({
+        msg: 'Server answered a body section empty while its companion section was not, asking it again separately',
+        sections: sections.map(section => (typeof section === 'string' ? section : section.key)),
+        cid: client.id
+    });
+    // the UID pins the message even when the first command addressed it by sequence number
+    let uid = response.uid;
+    let retry = await fetchExpected(client, uid || range, { uid: true, bodyParts: sections }, uid ? { ...options, uid: true } : options, {
+        uid,
+        origins: partialStarts(sections)
+    });
+    if (!retry) {
+        return;
+    }
+    if (retry.headers) {
+        response.headers = retry.headers;
+    }
+    for (let [key, value] of retry.bodyParts || []) {
+        (response.bodyParts ??= new Map()).set(key, value);
+        if (retry.binaryParts && retry.binaryParts.has(key)) {
+            (response.binaryParts ??= new Set()).add(key);
+        }
+        else if (response.binaryParts) {
+            response.binaryParts.delete(key);
+        }
+    }
+}
 /**
  * Implements ImapFlow.download(), see its documentation
  *
@@ -66,6 +173,7 @@ async function downloadMessage(client, range, part, options) {
     let getNextPart = async (query) => {
         query = query || {};
         let mimeKey;
+        let contentRequest;
         if (!part) {
             query.source = {
                 start: processed,
@@ -88,13 +196,18 @@ async function downloadMessage(client, range, part, options) {
                     query.bodyParts.push(mimeKey);
                 }
             }
-            query.bodyParts.push({
+            contentRequest = {
                 key: part,
                 start: processed,
                 maxLength: chunkSize
-            });
+            };
+            query.bodyParts.push(contentRequest);
         }
-        let response = await client.fetchOne(range, query, downloadOptions);
+        let expected = {
+            uid: uid || requestedUid(range, downloadOptions),
+            origins: new Map([[part || '', processed]])
+        };
+        let response = await fetchExpected(client, range, query, downloadOptions, expected);
         if (!response) {
             return { response: false, chunk: false };
         }
@@ -104,6 +217,12 @@ async function downloadMessage(client, range, part, options) {
             range = uid;
             downloadOptions.uid = true;
         }
+        if (mimeKey && contentRequest) {
+            let dropped = droppedSection(mimeKey === 'header' ? response.headers : response.bodyParts?.get(mimeKey), response.bodyParts?.get(part), mimeKey, contentRequest);
+            if (dropped) {
+                await refetchDroppedSections(client, response, range, downloadOptions, [dropped]);
+            }
+        }
         let chunk = !part ? response.source : response.bodyParts && response.bodyParts.get(part);
         if (!chunk) {
             return {};
@@ -458,16 +577,31 @@ async function downloadMessageParts(client, range, parts, options) {
     // again on the answer for servers that ignore the partial specifier
     let maxBytes = (0, limited_passthrough_js_1.normalizeByteLimit)(downloadOptions.maxBytes);
     let query = { bodyParts: [] };
+    let contentRequests = new Map();
     for (let part of parts) {
         query.bodyParts.push(part + '.mime');
         // The partial specifier carries a 32-bit length (RFC 9051 "number"), so a cap beyond
         // that is applied on the answer alone
-        query.bodyParts.push(maxBytes > 0xffffffff ? part : { key: part, start: 0, maxLength: maxBytes });
+        let contentRequest = maxBytes > 0xffffffff ? part : { key: part, start: 0, maxLength: maxBytes };
+        contentRequests.set(part, contentRequest);
+        query.bodyParts.push(contentRequest);
     }
-    let response = await client.fetchOne(range, query, downloadOptions);
+    let response = await fetchExpected(client, range, query, downloadOptions, {
+        uid: requestedUid(range, downloadOptions),
+        origins: partialStarts(query.bodyParts)
+    });
     if (!response || !response.bodyParts) {
         return {};
     }
+    let dropped = [];
+    for (let [part, contentRequest] of contentRequests) {
+        let section = droppedSection(response.bodyParts.get(part + '.mime'), response.bodyParts.get(part), part + '.mime', contentRequest);
+        if (section) {
+            dropped.push(section);
+        }
+    }
+    // Sections of different parts do not collide, so every dropped one fits in one FETCH
+    await refetchDroppedSections(client, response, range, downloadOptions, dropped);
     let data = {};
     for (let [part, content] of response.bodyParts) {
         let keyParts = part.split('.mime');

package/dist/cjs/imap-flow.d.ts

@@ -122,8 +122,8 @@ export declare class ImapFlow extends EventEmitter {
      */
     usable: boolean;
     /**
-     * Currently authenticated user or `false` if mailbox is not open
-     * or `true` if connection was authenticated by PREAUTH
+     * `true` once the connection is authenticated (by LOGIN, AUTHENTICATE or a PREAUTH greeting),
+     * `false` before that. The user name is in `options.auth.user`
      */
     authenticated: string | boolean;
     /**

package/dist/cjs/imap-flow.js

@@ -1500,9 +1500,8 @@ class ImapFlow extends node_events_1.EventEmitter {
                 // of the IP - accepting any "localhost" certificate for any IP-hosted
                 // server, and rejecting legitimate IP-SAN certificates.
                 host: this.host,
-                servername: this.servername,
                 port: this.port
-            }, this.options.tls || {});
+            }, this.tlsServername(), this.options.tls || {});
             this.clearSocketHandlers();
             let settled = false;
             // Single settlement path for the upgrade. Every terminal outcome - handshake
@@ -1892,12 +1891,18 @@ class ImapFlow extends node_events_1.EventEmitter {
             uids = untagged.attributes[0].value;
         }
         let uidList = (0, tools_js_1.expandRange)(uids);
+        let earlier = tags.includes('EARLIER');
+        // RFC 7162 section 3.2.10: unlike VANISHED (EARLIER), a plain VANISHED reports messages the
+        // client knows about and decrements the message count like the same number of EXPUNGEs would
+        if (!earlier) {
+            mailbox.exists = Math.max(0, mailbox.exists - uidList.length);
+        }
         for (let uid of uidList) {
             let payload = {
                 path: mailbox.path,
                 uid,
                 vanished: true,
-                earlier: tags.includes('EARLIER')
+                earlier
             };
             await this.notifyExpunge(payload);
         }
@@ -1909,7 +1914,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             // mailbox closed, ignore
             return;
         }
-        let message = await (0, tools_js_1.formatMessageResponse)(untagged, mailbox, this.idHashAlgorithm);
+        let message = await (0, tools_js_1.formatMessageResponse)(untagged, mailbox, this.idHashAlgorithm, this);
         if (message.flags) {
             let updateEvent = {
                 path: mailbox.path,
@@ -1938,6 +1943,12 @@ class ImapFlow extends node_events_1.EventEmitter {
         }
         return true;
     }
+    // servername for tls.connect(), left out for an IP literal host (this.servername is false then):
+    // Node treats a false value like a missing one, but Bun throws a TypeError for it
+    /** @internal */
+    tlsServername() {
+        return this.servername ? { servername: this.servername } : {};
+    }
     // Normalizes a message range from various input formats into an IMAP-compatible
     // sequence string (e.g., "1:5,7,10:*"). Handles: numbers, "*", {all:true},
     // {uid:value}, search query objects (resolved via SEARCH), and arrays of numbers.
@@ -1980,6 +1991,11 @@ class ImapFlow extends node_events_1.EventEmitter {
         if (!value) {
             return false;
         }
+        // An empty mailbox has no message numbers: every sequence set, "1:*" included, would get a
+        // BAD (RFC 9051 section 9, seq-number). UID sets may point past the end, so they are sent.
+        if (!options.uid && this.mailbox && !this.mailbox.exists) {
+            return false;
+        }
         return value;
     }
     // The single definition of "the connection is not free". A held or queued mailbox lock, a
@@ -2049,9 +2065,8 @@ class ImapFlow extends node_events_1.EventEmitter {
         let connector = this.secureConnection ? node_tls_1.default : node_net_1.default;
         let opts = Object.assign({
             host: this.host,
-            servername: this.servername,
             port: this.port
-        }, this.options.tls || {});
+        }, this.tlsServername(), this.options.tls || {});
         this.untaggedHandlers.OK = (...args) => this.initialOK(...args);
         this.untaggedHandlers.BYE = (...args) => this.serverBye(...args);
         this.untaggedHandlers.PREAUTH = () => this.initialPREAUTH();

package/dist/cjs/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.2.7";
+export declare const version = "2.2.8";
 export declare const homepage = "https://imapflow.com/";

package/dist/cjs/package-info.js

@@ -3,5 +3,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.homepage = exports.version = exports.name = void 0;
 exports.name = "imapflow";
-exports.version = "2.2.7";
+exports.version = "2.2.8";
 exports.homepage = "https://imapflow.com/";

package/dist/cjs/search-compiler.js

@@ -371,10 +371,13 @@ const searchCompiler = (connection, query) => {
                             fail('InvalidSearchQuery', `Search value for ${term.toLowerCase()} must be a string`);
                         }
                         let flag = (0, tools_js_1.formatFlag)(params[term]);
-                        // formatFlag() refuses \Recent, which is not a keyword. Dropping the
-                        // criterion would widen the search, so the query is refused instead
+                        // formatFlag() refuses \Recent, which is not a keyword, and values that are
+                        // not atoms. Dropping the criterion would widen the search, so the query is
+                        // refused instead
                         if (flag === false) {
-                            fail('InvalidSearchQuery', `${params[term]} can not be searched as a keyword, use the "recent" search key instead`);
+                            fail('InvalidSearchQuery', /^\\recent$/i.test(params[term])
+                                ? `${params[term]} can not be searched as a keyword, use the "recent" search key instead`
+                                : `${params[term]} is not a valid keyword`);
                         }
                         // Compiled even when the mailbox does not allow the keyword: the
                         // correct answer is then the empty set, which dropping the

package/dist/cjs/tools.d.ts

@@ -293,9 +293,10 @@ export declare function getColorFlags(color: string | null | undefined): {
  * @param untagged - Parsed untagged IMAP response
  * @param mailbox - Current mailbox state object
  * @param idHashAlgorithm - Hash for the fallback message id, `md5` unless the client was told otherwise
+ * @param connection - Connection the response arrived on, decodes Gmail labels like mailbox names
  * @returns Formatted message object with properties like seq, uid, flags, envelope, etc.
  */
-export declare function formatMessageResponse(untagged: ImapResponse, mailbox: MailboxObject, idHashAlgorithm?: string): Promise<FetchMessageObject>;
+export declare function formatMessageResponse(untagged: ImapResponse, mailbox: MailboxObject, idHashAlgorithm?: string, connection?: ImapFlow): Promise<FetchMessageObject>;
 /**
  * Strips surrounding double quotes from a name string.
  *
@@ -364,8 +365,8 @@ export declare function formatDate(value: unknown): string | undefined;
  */
 export declare function formatDateTime(value: unknown): string | undefined;
 /**
- * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent),
- * and capitalizes system flags properly.
+ * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent) and for
+ * values that are not valid flags (keywords must be atoms), and capitalizes system flags properly.
  *
  * @param flag - Flag string to normalize
  * @returns Normalized flag string, or false if the flag cannot be set

package/dist/cjs/tools.js

@@ -56,6 +56,7 @@ exports.packMessageRange = packMessageRange;
 const libmime_1 = __importDefault(require("libmime"));
 const charsets_js_1 = require("./charsets.js");
 const imap_handler_js_1 = require("./handler/imap-handler.js");
+const imap_formal_syntax_js_1 = __importDefault(require("./handler/imap-formal-syntax.js"));
 const node_crypto_1 = require("node:crypto");
 const jp_decoder_js_1 = require("./jp-decoder.js");
 const iconv_lite_1 = __importDefault(require("iconv-lite"));
@@ -336,7 +337,8 @@ function buildStatusQueryAttributes(connection, statusQuery) {
                 }
                 break;
             case 'HIGHESTMODSEQ':
-                if (connection.capabilities.has('CONDSTORE')) {
+                // QRESYNC implies CONDSTORE (RFC 7162 3.2.3)
+                if (connection.capabilities.has('CONDSTORE') || connection.capabilities.has('QRESYNC')) {
                     attributes.push({ type: 'ATOM', value: key.toUpperCase() });
                 }
                 break;
@@ -717,24 +719,40 @@ function getColorFlags(color) {
  * @param untagged - Parsed untagged IMAP response
  * @param mailbox - Current mailbox state object
  * @param idHashAlgorithm - Hash for the fallback message id, `md5` unless the client was told otherwise
+ * @param connection - Connection the response arrived on, decodes Gmail labels like mailbox names
  * @returns Formatted message object with properties like seq, uid, flags, envelope, etc.
  */
-async function formatMessageResponse(untagged, mailbox, idHashAlgorithm) {
+async function formatMessageResponse(untagged, mailbox, idHashAlgorithm, connection) {
     let map = {};
     // The sequence number indexes into mailbox state, so an unusable one is dropped rather
     // than coerced to NaN or Infinity
     map.seq = parseUintValue(untagged.command, exports.MAX_UINT32_DIGITS) || undefined;
     let key;
+    // the <origin> of a partial section ("BODY[2]<1024>"), kept for the value that follows
+    let origin = false;
+    let partialOrigins;
+    let recordOrigin = (sectionKey) => {
+        if (origin !== false) {
+            if (!partialOrigins) {
+                partialOrigins = new Map();
+            }
+            partialOrigins.set(sectionKey, origin);
+        }
+    };
     let attributes = ((untagged.attributes && untagged.attributes[1]) || []);
     for (let i = 0, len = attributes.length; i < len; i++) {
         let attribute = attributes[i];
         if (i % 2 === 0) {
+            origin = false;
             key = (await (0, imap_handler_js_1.compiler)({
                 attributes: [attribute]
             }))
                 .toString()
                 .toLowerCase()
-                .replace(/<\d+(\.\d+)?>$/, '');
+                .replace(/<(\d+)(\.\d+)?>$/, (match, start) => {
+                origin = parseUintValue(start, exports.MAX_UINT32_DIGITS);
+                return '';
+            });
             continue;
         }
         /* c8 ignore start */ // defensive: key is always a string produced by the compiler above
@@ -779,6 +797,7 @@ async function formatMessageResponse(untagged, mailbox, idHashAlgorithm) {
             case 'body[]':
             case 'binary[]':
                 map.source = getBuffer(attribute);
+                recordOrigin('');
                 break;
             case 'uid':
                 // A UID feeds mailbox.uidNext one line below, and from there every range
@@ -825,7 +844,8 @@ async function formatMessageResponse(untagged, mailbox, idHashAlgorithm) {
                 map.threadId = getString(attribute);
                 break;
             case 'x-gm-labels':
-                map.labels = new Set(getArray(attribute));
+                // labels are mailbox names, modified UTF-7 unless UTF-8 is enabled
+                map.labels = new Set(getArray(attribute).map(label => (connection ? decodePath(connection, label) : label)));
                 break;
             case 'rfc822.size':
                 map.size = getUint(attribute) || 0;
@@ -871,6 +891,7 @@ async function formatMessageResponse(untagged, mailbox, idHashAlgorithm) {
                         map.bodyParts = new Map();
                     }
                     map.bodyParts.set(partKey, value);
+                    recordOrigin(partKey);
                     if (match[1].toLowerCase() === 'binary') {
                         // The part arrived via FETCH BINARY (RFC 3516, FETCH side folded
                         // into IMAP4rev2), so the server has already removed the
@@ -912,6 +933,10 @@ async function formatMessageResponse(untagged, mailbox, idHashAlgorithm) {
                     .update([path, mailbox.uidValidity?.toString() || '', map.uid.toString()].join(':'))
                     .digest('hex');
     }
+    if (partialOrigins) {
+        // non-enumerable, so it stays out of logged and serialized fetch results
+        Object.defineProperty(map, 'partialOrigins', { value: partialOrigins, writable: true, configurable: true });
+    }
     if (map.flags) {
         let flagColor = getFlagColor(map.flags);
         if (flagColor) {
@@ -1354,14 +1379,22 @@ function formatDateTime(value) {
     let timeStr = date.toISOString().substring(11, 19);
     return `${dateStr} ${timeStr} +0000`;
 }
+// the memoized ATOM-CHAR set of RFC 9051 section 9
+const atomChars = imap_formal_syntax_js_1.default['ATOM-CHAR'];
 /**
- * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent),
- * and capitalizes system flags properly.
+ * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent) and for
+ * values that are not valid flags (keywords must be atoms), and capitalizes system flags properly.
  *
  * @param flag - Flag string to normalize
  * @returns Normalized flag string, or false if the flag cannot be set
  */
 function formatFlag(flag) {
+    // RFC 9051 section 9: flag-keyword is an atom and flag-extension is "\\" atom, the same check
+    // the compiler uses to decide what it can send unquoted
+    let atom = flag.charAt(0) === '\\' ? flag.slice(1) : flag;
+    if (!atom || imap_formal_syntax_js_1.default.verify(atom, atomChars()) >= 0) {
+        return false;
+    }
     switch (flag.toLowerCase()) {
         case '\\recent':
             // can not set or remove

package/dist/esm/commands/authenticate.js

@@ -63,15 +63,26 @@ async function authOauth(connection, username, accessToken) {
         // Empty breaker: XOAUTH2 expects an empty response to abort the SASL exchange
         breaker = '';
     }
+    let encoded = Buffer.from(oauthbearer).toString('base64');
+    // Without SASL-IR the payload may not ride on the command line (RFC 4959 section 3): it is
+    // sent as the answer to the first, empty continuation request instead
+    let payloadPending = !connection.capabilities.has('SASL-IR');
     let errorResponse = false;
     try {
-        let response = await connection.exec('AUTHENTICATE', [
-            { type: 'ATOM', value: command },
-            { type: 'ATOM', value: Buffer.from(oauthbearer).toString('base64'), sensitive: true }
-        ], {
+        let attributes = [{ type: 'ATOM', value: command }];
+        if (!payloadPending) {
+            attributes.push({ type: 'ATOM', value: encoded, sensitive: true });
+        }
+        let response = await connection.exec('AUTHENTICATE', attributes, {
             // Server sends a "+" continuation if auth fails, with a base64 JSON error payload.
             // We decode it for diagnostics, then send the breaker to terminate the exchange.
             onPlusTag: async (resp) => {
+                if (payloadPending) {
+                    payloadPending = false;
+                    connection.log.debug({ src: 'c', msg: '(* value hidden *)', comment: `Encoded response for AUTH=${command}`, cid: connection.id });
+                    connection.write(encoded);
+                    return;
+                }
                 if (resp.attributes && resp.attributes[0] && resp.attributes[0].type === 'TEXT') {
                     try {
                         errorResponse = JSON.parse(Buffer.from(resp.attributes[0].value, 'base64').toString());

package/dist/esm/commands/enable.js

@@ -46,6 +46,12 @@ export default async function enable(connection, extensionList) {
         // extensions enabled by this command (RFC 5161), so a replace would drop
         // grants from an earlier ENABLE call
         connection.enabled = new Set([...connection.enabled, ...enabled]);
+        if (connection.enabled.has('QRESYNC')) {
+            // ENABLE QRESYNC is a CONDSTORE enabling command (RFC 7162 3.2.3), whether or not the
+            // server lists CONDSTORE in its ENABLED answer. Apache James advertises only QRESYNC
+            // and leaves a lone ENABLE CONDSTORE unanswered, which the RFC allows.
+            connection.enabled.add('CONDSTORE');
+        }
         response.next();
         return connection.enabled;
     }

package/dist/esm/commands/fetch.js

@@ -62,13 +62,30 @@ export default async function fetch(connection, range, query, options) {
                 };
                 queryStructure.push(bodyPeek);
             };
-            // IMAP fetch macros (ALL, FAST, FULL) and standard data items map directly to IMAP atoms
-            ['all', 'fast', 'full', 'uid', 'flags', 'bodyStructure', 'envelope', 'internalDate'].forEach(key => {
-                if (query[key]) {
+            // The ALL, FAST and FULL macros may only be sent on their own, never in a list with other
+            // items (RFC 3501 section 9), and UID is always in the list, so they are expanded into
+            // the items they stand for. FULL is expanded to BODYSTRUCTURE rather than the
+            // non-extensible BODY, as documented for the full option.
+            let full = !!query.full;
+            let all = !!query.all || full;
+            let fast = !!query.fast || all;
+            let items = {
+                flags: query.flags || fast,
+                internalDate: query.internalDate || fast,
+                size: query.size || fast,
+                envelope: query.envelope || all,
+                bodyStructure: query.bodyStructure || full
+            };
+            // standard data items map directly to IMAP atoms
+            if (query.uid) {
+                queryStructure.push({ type: 'ATOM', value: 'UID' });
+            }
+            ['flags', 'bodyStructure', 'envelope', 'internalDate'].forEach(key => {
+                if (items[key]) {
                     queryStructure.push({ type: 'ATOM', value: key.toUpperCase() });
                 }
             });
-            if (query.size) {
+            if (items.size) {
                 queryStructure.push({ type: 'ATOM', value: 'RFC822.SIZE' });
             }
             // Fetch full message source, optionally with byte range (start/maxLength)
@@ -191,7 +208,7 @@ export default async function fetch(connection, range, query, options) {
                         if (consumerError) {
                             return;
                         }
-                        let formatted = await formatMessageResponse(untagged, mailbox, connection.idHashAlgorithm);
+                        let formatted = await formatMessageResponse(untagged, mailbox, connection.idHashAlgorithm, connection);
                         if (typeof options.onUntaggedFetch === 'function') {
                             /* c8 ignore next */ // a UID FETCH row without its UID is a non-compliant server, so the seq fallback is not exercised
                             let key = options.uid ? formatted.uid || formatted.seq : formatted.seq;

package/dist/esm/commands/store.js

@@ -1,4 +1,4 @@
-import { formatFlag, canUseFlag, reportCommandError, getSelectedMailbox } from '../tools.js';
+import { formatFlag, canUseFlag, encodePath, reportCommandError, getSelectedMailbox } from '../tools.js';
 /**
  * Updates flags or labels for messages in the selected mailbox.
  *
@@ -58,7 +58,10 @@ export default async function store(connection, range, flags, options) {
     const dropped = [];
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
         .map(flag => {
-        let formatted = formatFlag(flag);
+        // Gmail labels other than the \-prefixed system labels are mailbox names: astrings in
+        // the form mailbox names take on the session (modified UTF-7 unless UTF-8 is enabled),
+        // not atoms like IMAP keywords
+        let formatted = options.useLabels && flag && flag.charAt(0) !== '\\' ? encodePath(connection, flag) : formatFlag(flag);
         if (!formatted || (!canUseFlag(flagSource, formatted) && operationName !== 'remove')) {
             dropped.push(flag);
             return false;
@@ -80,13 +83,10 @@ export default async function store(connection, range, flags, options) {
     if (!flags.length && !clearAll) {
         return false;
     }
-    let attributes = [
-        { type: 'SEQUENCE', value: range },
-        { type: 'ATOM', value: operation },
-        flags.map(flag => ({ type: 'ATOM', value: flag }))
-    ];
+    let attributes = [{ type: 'SEQUENCE', value: range }];
     // CONDSTORE (RFC 7162): UNCHANGEDSINCE modifier prevents updating messages whose
     // mod-sequence is higher than the specified value, avoiding overwriting concurrent changes.
+    // The store-modifiers list goes between the sequence set and the item name (section 3.1.3).
     if (options.unchangedSince && connection.enabled.has('CONDSTORE') && !mailbox.noModseq) {
         attributes.push([
             {
@@ -99,6 +99,7 @@ export default async function store(connection, range, flags, options) {
             }
         ]);
     }
+    attributes.push({ type: 'ATOM', value: operation }, flags.map(flag => ({ type: 'ATOM', value: flag })));
     let response;
     try {
         response = await connection.exec(options.uid ? 'UID STORE' : 'STORE', attributes);

package/dist/esm/download.js

@@ -12,6 +12,113 @@ import { LimitedPassthrough, normalizeByteLimit } from './limited-passthrough.js
 // away (a consumer destroying it closes it without a 'drain')
 const DRAIN_WAIT_EVENTS = ['drain', 'error', 'close'];
 import { getDecoder, isUnsafeKey } from './tools.js';
+const isEmptySection = (value) => !value?.length;
+/**
+ * The section to ask again when exactly one of a part's MIME headers and content came back
+ * empty (see refetchDroppedSections()), undefined when both or neither did
+ */
+const droppedSection = (mime, content, mimeRequest, contentRequest) => {
+    if (isEmptySection(mime) === isEmptySection(content)) {
+        return undefined;
+    }
+    return isEmptySection(content) ? contentRequest : mimeRequest;
+};
+/** Start offset of every partial section among the requests, keyed by section */
+const partialStarts = (requests) => {
+    let starts = new Map();
+    for (let request of requests) {
+        if (typeof request !== 'string') {
+            starts.set(request.key, Number(request.start) || 0);
+        }
+    }
+    return starts;
+};
+// How many times a request is repeated after answers that belong to another request
+const MAX_FOREIGN_ANSWERS = 3;
+const requestedUid = (range, options) => options.uid && /^\d+$/.test(String(range)) ? Number(range) : undefined;
+const isForeignAnswer = (response, expected) => {
+    if (expected.uid && response.uid && response.uid !== expected.uid) {
+        return true;
+    }
+    for (let [key, start] of expected.origins) {
+        let origin = response.partialOrigins && response.partialOrigins.get(key);
+        // An answer without the origin is taken as is: some servers leave it out, and some
+        // ignore the partial specifier altogether
+        if (typeof origin === 'number' && origin !== start) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * fetchOne() that takes only an answer belonging to the request. Apache James now and then
+ * writes the head of a FETCH answer after its tagged OK, so the data of one request shows up
+ * within the answer to the next one. Taken at face value it would be the data of that next
+ * request, and a download would end without an error but with misplaced bytes. An answer for
+ * another UID, or with a partial section that starts at another offset than asked, is dropped
+ * and the request repeated.
+ */
+async function fetchExpected(client, range, query, options, expected) {
+    for (let attempt = 1;; attempt++) {
+        let response = await client.fetchOne(range, query, options);
+        if (!response || !isForeignAnswer(response, expected)) {
+            return response;
+        }
+        client.log.warn({
+            msg: 'Server answered with data of another request, asking again',
+            uid: response.uid,
+            origins: response.partialOrigins && Object.fromEntries(response.partialOrigins),
+            attempt,
+            cid: client.id
+        });
+        if (attempt >= MAX_FOREIGN_ANSWERS) {
+            let err = new Error('Server kept answering with data of another request');
+            err.code = 'DownloadIncomplete';
+            err.cid = client.id;
+            throw err;
+        }
+    }
+}
+/**
+ * Apache James (and the servers built on it, Twake Mail among them) answers only the first
+ * section it is asked for each MIME part of one FETCH and returns the other one empty:
+ * BODY[2.MIME] with BODY[2] yields the headers and a zero-length body, the reverse order loses
+ * the headers (FetchGroup.addPartContent() keeps the first descriptor for a part path). Asks the
+ * sections that came back empty again, in a FETCH of their own, and merges the answer into
+ * `response`. Callers only list a section whose companion did arrive, so a compliant server
+ * pays the extra round trip only for a part that really is empty.
+ */
+async function refetchDroppedSections(client, response, range, options, sections) {
+    if (!sections.length) {
+        return;
+    }
+    client.log.debug({
+        msg: 'Server answered a body section empty while its companion section was not, asking it again separately',
+        sections: sections.map(section => (typeof section === 'string' ? section : section.key)),
+        cid: client.id
+    });
+    // the UID pins the message even when the first command addressed it by sequence number
+    let uid = response.uid;
+    let retry = await fetchExpected(client, uid || range, { uid: true, bodyParts: sections }, uid ? { ...options, uid: true } : options, {
+        uid,
+        origins: partialStarts(sections)
+    });
+    if (!retry) {
+        return;
+    }
+    if (retry.headers) {
+        response.headers = retry.headers;
+    }
+    for (let [key, value] of retry.bodyParts || []) {
+        (response.bodyParts ??= new Map()).set(key, value);
+        if (retry.binaryParts && retry.binaryParts.has(key)) {
+            (response.binaryParts ??= new Set()).add(key);
+        }
+        else if (response.binaryParts) {
+            response.binaryParts.delete(key);
+        }
+    }
+}
 /**
  * Implements ImapFlow.download(), see its documentation
  *
@@ -59,6 +166,7 @@ export async function downloadMessage(client, range, part, options) {
     let getNextPart = async (query) => {
         query = query || {};
         let mimeKey;
+        let contentRequest;
         if (!part) {
             query.source = {
                 start: processed,
@@ -81,13 +189,18 @@ export async function downloadMessage(client, range, part, options) {
                     query.bodyParts.push(mimeKey);
                 }
             }
-            query.bodyParts.push({
+            contentRequest = {
                 key: part,
                 start: processed,
                 maxLength: chunkSize
-            });
+            };
+            query.bodyParts.push(contentRequest);
         }
-        let response = await client.fetchOne(range, query, downloadOptions);
+        let expected = {
+            uid: uid || requestedUid(range, downloadOptions),
+            origins: new Map([[part || '', processed]])
+        };
+        let response = await fetchExpected(client, range, query, downloadOptions, expected);
         if (!response) {
             return { response: false, chunk: false };
         }
@@ -97,6 +210,12 @@ export async function downloadMessage(client, range, part, options) {
             range = uid;
             downloadOptions.uid = true;
         }
+        if (mimeKey && contentRequest) {
+            let dropped = droppedSection(mimeKey === 'header' ? response.headers : response.bodyParts?.get(mimeKey), response.bodyParts?.get(part), mimeKey, contentRequest);
+            if (dropped) {
+                await refetchDroppedSections(client, response, range, downloadOptions, [dropped]);
+            }
+        }
         let chunk = !part ? response.source : response.bodyParts && response.bodyParts.get(part);
         if (!chunk) {
             return {};
@@ -451,16 +570,31 @@ export async function downloadMessageParts(client, range, parts, options) {
     // again on the answer for servers that ignore the partial specifier
     let maxBytes = normalizeByteLimit(downloadOptions.maxBytes);
     let query = { bodyParts: [] };
+    let contentRequests = new Map();
     for (let part of parts) {
         query.bodyParts.push(part + '.mime');
         // The partial specifier carries a 32-bit length (RFC 9051 "number"), so a cap beyond
         // that is applied on the answer alone
-        query.bodyParts.push(maxBytes > 0xffffffff ? part : { key: part, start: 0, maxLength: maxBytes });
+        let contentRequest = maxBytes > 0xffffffff ? part : { key: part, start: 0, maxLength: maxBytes };
+        contentRequests.set(part, contentRequest);
+        query.bodyParts.push(contentRequest);
     }
-    let response = await client.fetchOne(range, query, downloadOptions);
+    let response = await fetchExpected(client, range, query, downloadOptions, {
+        uid: requestedUid(range, downloadOptions),
+        origins: partialStarts(query.bodyParts)
+    });
     if (!response || !response.bodyParts) {
         return {};
     }
+    let dropped = [];
+    for (let [part, contentRequest] of contentRequests) {
+        let section = droppedSection(response.bodyParts.get(part + '.mime'), response.bodyParts.get(part), part + '.mime', contentRequest);
+        if (section) {
+            dropped.push(section);
+        }
+    }
+    // Sections of different parts do not collide, so every dropped one fits in one FETCH
+    await refetchDroppedSections(client, response, range, downloadOptions, dropped);
     let data = {};
     for (let [part, content] of response.bodyParts) {
         let keyParts = part.split('.mime');

package/dist/esm/imap-flow.d.ts

@@ -122,8 +122,8 @@ export declare class ImapFlow extends EventEmitter {
      */
     usable: boolean;
     /**
-     * Currently authenticated user or `false` if mailbox is not open
-     * or `true` if connection was authenticated by PREAUTH
+     * `true` once the connection is authenticated (by LOGIN, AUTHENTICATE or a PREAUTH greeting),
+     * `false` before that. The user name is in `options.auth.user`
      */
     authenticated: string | boolean;
     /**

package/dist/esm/imap-flow.js

@@ -1459,9 +1459,8 @@ export class ImapFlow extends EventEmitter {
                 // of the IP - accepting any "localhost" certificate for any IP-hosted
                 // server, and rejecting legitimate IP-SAN certificates.
                 host: this.host,
-                servername: this.servername,
                 port: this.port
-            }, this.options.tls || {});
+            }, this.tlsServername(), this.options.tls || {});
             this.clearSocketHandlers();
             let settled = false;
             // Single settlement path for the upgrade. Every terminal outcome - handshake
@@ -1851,12 +1850,18 @@ export class ImapFlow extends EventEmitter {
             uids = untagged.attributes[0].value;
         }
         let uidList = expandRange(uids);
+        let earlier = tags.includes('EARLIER');
+        // RFC 7162 section 3.2.10: unlike VANISHED (EARLIER), a plain VANISHED reports messages the
+        // client knows about and decrements the message count like the same number of EXPUNGEs would
+        if (!earlier) {
+            mailbox.exists = Math.max(0, mailbox.exists - uidList.length);
+        }
         for (let uid of uidList) {
             let payload = {
                 path: mailbox.path,
                 uid,
                 vanished: true,
-                earlier: tags.includes('EARLIER')
+                earlier
             };
             await this.notifyExpunge(payload);
         }
@@ -1868,7 +1873,7 @@ export class ImapFlow extends EventEmitter {
             // mailbox closed, ignore
             return;
         }
-        let message = await formatMessageResponse(untagged, mailbox, this.idHashAlgorithm);
+        let message = await formatMessageResponse(untagged, mailbox, this.idHashAlgorithm, this);
         if (message.flags) {
             let updateEvent = {
                 path: mailbox.path,
@@ -1897,6 +1902,12 @@ export class ImapFlow extends EventEmitter {
         }
         return true;
     }
+    // servername for tls.connect(), left out for an IP literal host (this.servername is false then):
+    // Node treats a false value like a missing one, but Bun throws a TypeError for it
+    /** @internal */
+    tlsServername() {
+        return this.servername ? { servername: this.servername } : {};
+    }
     // Normalizes a message range from various input formats into an IMAP-compatible
     // sequence string (e.g., "1:5,7,10:*"). Handles: numbers, "*", {all:true},
     // {uid:value}, search query objects (resolved via SEARCH), and arrays of numbers.
@@ -1939,6 +1950,11 @@ export class ImapFlow extends EventEmitter {
         if (!value) {
             return false;
         }
+        // An empty mailbox has no message numbers: every sequence set, "1:*" included, would get a
+        // BAD (RFC 9051 section 9, seq-number). UID sets may point past the end, so they are sent.
+        if (!options.uid && this.mailbox && !this.mailbox.exists) {
+            return false;
+        }
         return value;
     }
     // The single definition of "the connection is not free". A held or queued mailbox lock, a
@@ -2008,9 +2024,8 @@ export class ImapFlow extends EventEmitter {
         let connector = this.secureConnection ? tls : net;
         let opts = Object.assign({
             host: this.host,
-            servername: this.servername,
             port: this.port
-        }, this.options.tls || {});
+        }, this.tlsServername(), this.options.tls || {});
         this.untaggedHandlers.OK = (...args) => this.initialOK(...args);
         this.untaggedHandlers.BYE = (...args) => this.serverBye(...args);
         this.untaggedHandlers.PREAUTH = () => this.initialPREAUTH();

package/dist/esm/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.2.7";
+export declare const version = "2.2.8";
 export declare const homepage = "https://imapflow.com/";

package/dist/esm/package-info.js

@@ -1,4 +1,4 @@
 // Generated by scripts/build.js from package.json. Do not edit by hand.
 export const name = "imapflow";
-export const version = "2.2.7";
+export const version = "2.2.8";
 export const homepage = "https://imapflow.com/";

package/dist/esm/search-compiler.js

@@ -368,10 +368,13 @@ export const searchCompiler = (connection, query) => {
                             fail('InvalidSearchQuery', `Search value for ${term.toLowerCase()} must be a string`);
                         }
                         let flag = formatFlag(params[term]);
-                        // formatFlag() refuses \Recent, which is not a keyword. Dropping the
-                        // criterion would widen the search, so the query is refused instead
+                        // formatFlag() refuses \Recent, which is not a keyword, and values that are
+                        // not atoms. Dropping the criterion would widen the search, so the query is
+                        // refused instead
                         if (flag === false) {
-                            fail('InvalidSearchQuery', `${params[term]} can not be searched as a keyword, use the "recent" search key instead`);
+                            fail('InvalidSearchQuery', /^\\recent$/i.test(params[term])
+                                ? `${params[term]} can not be searched as a keyword, use the "recent" search key instead`
+                                : `${params[term]} is not a valid keyword`);
                         }
                         // Compiled even when the mailbox does not allow the keyword: the
                         // correct answer is then the empty set, which dropping the

package/dist/esm/tools.d.ts

@@ -293,9 +293,10 @@ export declare function getColorFlags(color: string | null | undefined): {
  * @param untagged - Parsed untagged IMAP response
  * @param mailbox - Current mailbox state object
  * @param idHashAlgorithm - Hash for the fallback message id, `md5` unless the client was told otherwise
+ * @param connection - Connection the response arrived on, decodes Gmail labels like mailbox names
  * @returns Formatted message object with properties like seq, uid, flags, envelope, etc.
  */
-export declare function formatMessageResponse(untagged: ImapResponse, mailbox: MailboxObject, idHashAlgorithm?: string): Promise<FetchMessageObject>;
+export declare function formatMessageResponse(untagged: ImapResponse, mailbox: MailboxObject, idHashAlgorithm?: string, connection?: ImapFlow): Promise<FetchMessageObject>;
 /**
  * Strips surrounding double quotes from a name string.
  *
@@ -364,8 +365,8 @@ export declare function formatDate(value: unknown): string | undefined;
  */
 export declare function formatDateTime(value: unknown): string | undefined;
 /**
- * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent),
- * and capitalizes system flags properly.
+ * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent) and for
+ * values that are not valid flags (keywords must be atoms), and capitalizes system flags properly.
  *
  * @param flag - Flag string to normalize
  * @returns Normalized flag string, or false if the flag cannot be set

package/dist/esm/tools.js

@@ -2,6 +2,7 @@
 import libmime from 'libmime';
 import { resolveCharset } from './charsets.js';
 import { compiler } from './handler/imap-handler.js';
+import imapFormalSyntax from './handler/imap-formal-syntax.js';
 import { createHash } from 'node:crypto';
 import { JPDecoder } from './jp-decoder.js';
 import iconv from 'iconv-lite';
@@ -280,7 +281,8 @@ export function buildStatusQueryAttributes(connection, statusQuery) {
                 }
                 break;
             case 'HIGHESTMODSEQ':
-                if (connection.capabilities.has('CONDSTORE')) {
+                // QRESYNC implies CONDSTORE (RFC 7162 3.2.3)
+                if (connection.capabilities.has('CONDSTORE') || connection.capabilities.has('QRESYNC')) {
                     attributes.push({ type: 'ATOM', value: key.toUpperCase() });
                 }
                 break;
@@ -661,24 +663,40 @@ export function getColorFlags(color) {
  * @param untagged - Parsed untagged IMAP response
  * @param mailbox - Current mailbox state object
  * @param idHashAlgorithm - Hash for the fallback message id, `md5` unless the client was told otherwise
+ * @param connection - Connection the response arrived on, decodes Gmail labels like mailbox names
  * @returns Formatted message object with properties like seq, uid, flags, envelope, etc.
  */
-export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm) {
+export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm, connection) {
     let map = {};
     // The sequence number indexes into mailbox state, so an unusable one is dropped rather
     // than coerced to NaN or Infinity
     map.seq = parseUintValue(untagged.command, MAX_UINT32_DIGITS) || undefined;
     let key;
+    // the <origin> of a partial section ("BODY[2]<1024>"), kept for the value that follows
+    let origin = false;
+    let partialOrigins;
+    let recordOrigin = (sectionKey) => {
+        if (origin !== false) {
+            if (!partialOrigins) {
+                partialOrigins = new Map();
+            }
+            partialOrigins.set(sectionKey, origin);
+        }
+    };
     let attributes = ((untagged.attributes && untagged.attributes[1]) || []);
     for (let i = 0, len = attributes.length; i < len; i++) {
         let attribute = attributes[i];
         if (i % 2 === 0) {
+            origin = false;
             key = (await compiler({
                 attributes: [attribute]
             }))
                 .toString()
                 .toLowerCase()
-                .replace(/<\d+(\.\d+)?>$/, '');
+                .replace(/<(\d+)(\.\d+)?>$/, (match, start) => {
+                origin = parseUintValue(start, MAX_UINT32_DIGITS);
+                return '';
+            });
             continue;
         }
         /* c8 ignore start */ // defensive: key is always a string produced by the compiler above
@@ -723,6 +741,7 @@ export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm)
             case 'body[]':
             case 'binary[]':
                 map.source = getBuffer(attribute);
+                recordOrigin('');
                 break;
             case 'uid':
                 // A UID feeds mailbox.uidNext one line below, and from there every range
@@ -769,7 +788,8 @@ export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm)
                 map.threadId = getString(attribute);
                 break;
             case 'x-gm-labels':
-                map.labels = new Set(getArray(attribute));
+                // labels are mailbox names, modified UTF-7 unless UTF-8 is enabled
+                map.labels = new Set(getArray(attribute).map(label => (connection ? decodePath(connection, label) : label)));
                 break;
             case 'rfc822.size':
                 map.size = getUint(attribute) || 0;
@@ -815,6 +835,7 @@ export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm)
                         map.bodyParts = new Map();
                     }
                     map.bodyParts.set(partKey, value);
+                    recordOrigin(partKey);
                     if (match[1].toLowerCase() === 'binary') {
                         // The part arrived via FETCH BINARY (RFC 3516, FETCH side folded
                         // into IMAP4rev2), so the server has already removed the
@@ -856,6 +877,10 @@ export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm)
                     .update([path, mailbox.uidValidity?.toString() || '', map.uid.toString()].join(':'))
                     .digest('hex');
     }
+    if (partialOrigins) {
+        // non-enumerable, so it stays out of logged and serialized fetch results
+        Object.defineProperty(map, 'partialOrigins', { value: partialOrigins, writable: true, configurable: true });
+    }
     if (map.flags) {
         let flagColor = getFlagColor(map.flags);
         if (flagColor) {
@@ -1298,14 +1323,22 @@ export function formatDateTime(value) {
     let timeStr = date.toISOString().substring(11, 19);
     return `${dateStr} ${timeStr} +0000`;
 }
+// the memoized ATOM-CHAR set of RFC 9051 section 9
+const atomChars = imapFormalSyntax['ATOM-CHAR'];
 /**
- * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent),
- * and capitalizes system flags properly.
+ * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent) and for
+ * values that are not valid flags (keywords must be atoms), and capitalizes system flags properly.
  *
  * @param flag - Flag string to normalize
  * @returns Normalized flag string, or false if the flag cannot be set
  */
 export function formatFlag(flag) {
+    // RFC 9051 section 9: flag-keyword is an atom and flag-extension is "\\" atom, the same check
+    // the compiler uses to decide what it can send unquoted
+    let atom = flag.charAt(0) === '\\' ? flag.slice(1) : flag;
+    if (!atom || imapFormalSyntax.verify(atom, atomChars()) >= 0) {
+        return false;
+    }
     switch (flag.toLowerCase()) {
         case '\\recent':
             // can not set or remove

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.2.7",
+    "version": "2.2.8",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",
@@ -51,7 +51,8 @@
         "lint": "npm run typecheck && eslint .",
         "lint:fix": "eslint . --fix",
         "prepare": "npm run build",
-        "update": "rm -rf node_modules package-lock.json && ncu -u && npm install"
+        "update": "rm -rf node_modules package-lock.json && ncu -u && npm install",
+        "test:james": "bash test/integration/run-james-tests.sh"
     },
     "repository": {
         "type": "git",
@@ -74,12 +75,13 @@
         "eslint": "10.12.0",
         "eslint-config-prettier": "10.1.8",
         "globals": "17.13.0",
+        "imapkit": "4.1.0",
         "prettier": "3.9.9",
         "tsx": "4.23.15",
         "types-node-legacy": "npm:@types/node@20.0.0",
         "typescript": "6.0.3",
         "typescript-eslint": "8.71.1",
-        "wrangler": "4.147.0"
+        "wrangler": "4.148.0"
     },
     "dependencies": {
         "@zone-eu/mailsplit": "5.4.20",