imapflow 2.0.7 → 2.1.0

package/dist/esm/imap-flow.js

@@ -7,22 +7,17 @@ import crypto from 'node:crypto';
 import zlib from 'node:zlib';
 import { EventEmitter } from 'node:events';
 import { PassThrough } from 'node:stream';
-import libmime from 'libmime';
-import libqp from 'libqp';
-import libbase64 from 'libbase64';
-import { Headers } from '@zone-eu/mailsplit';
-import FlowedDecoder from '@zone-eu/mailsplit/lib/flowed-decoder.js';
 import logger from './logger.js';
 import * as packageInfo from './package-info.js';
-import { LimitedPassthrough, normalizeByteLimit } from './limited-passthrough.js';
 import { ImapStream } from './handler/imap-stream.js';
 import { parser, compiler } from './handler/imap-handler.js';
 import { proxyConnection, detachEarlyErrorHandler } from './proxy-connection.js';
 import { ConnectionDeadline } from './connection-deadline.js';
+import { downloadMessage, downloadMessageParts } from './download.js';
 import { AuthenticationFailure } from './errors.js';
 import imapCommands from './imap-commands.js';
-import { comparePaths, updateCapabilities, getFolderTree, formatMessageResponse, getDecoder, packMessageRange, normalizePath, expandRange, getColorFlags, hasCapability, isRev2Active, logConnectionError, unrefTimer, clearTimer, parseUintValue, isUnsafeKey, getStringList, buildConnectionError, guardedPromise, guardedReject, MAX_UINT32_DIGITS } from './tools.js';
-export { AuthenticationFailure } from './errors.js';
+import { comparePaths, updateCapabilities, getFolderTree, formatMessageResponse, packMessageRange, normalizePath, expandRange, getColorFlags, hasCapability, isRev2Active, logConnectionError, unrefTimer, clearTimer, parseUintValue, getStringList, getTextValues, emitSafe, buildConnectionError, guardedPromise, guardedReject, MAX_UINT32_DIGITS } from './tools.js';
+export { AuthenticationFailure, ImapFlowErrorCode } from './errors.js';
 const GREETING_TIMEOUT = 16 * 1000;
 const UPGRADE_TIMEOUT = 10 * 1000;
 const SOCKET_TIMEOUT = 5 * 60 * 1000;
@@ -160,6 +155,9 @@ export class ImapFlow extends EventEmitter {
      * Current module version as a static class property
      */
     static { this.version = packageInfo.version; }
+    /**
+     * Creates a client for one IMAP connection. Nothing is sent before `connect()` is called
+     */
     constructor(options) {
         super({ captureRejections: true });
         this.options = options || {};
@@ -310,7 +308,7 @@ export class ImapFlow extends EventEmitter {
             rid = '0'.repeat(20 - rid.length) + rid;
         }
         if (rid.length > 20) {
-            rid = rid.substr(0, 20);
+            rid = rid.substring(0, 20);
         }
         return rid;
     }
@@ -898,11 +896,9 @@ export class ImapFlow extends EventEmitter {
                 break;
             case 'NO':
             case 'BAD': {
-                let txt = parsed.attributes &&
-                    parsed.attributes
-                        .filter(val => val.type === 'TEXT')
-                        .map(val => val.value.trim())
-                        .join(' ');
+                let txt = getTextValues(parsed.attributes)
+                    .map(val => val.trim())
+                    .join(' ');
                 let err = new Error('Command failed');
                 err.response = parsed;
                 err.responseStatus = parsed.command.toUpperCase();
@@ -933,7 +929,7 @@ export class ImapFlow extends EventEmitter {
                     // Example: "tag BAD Request is throttled. Suggested Backoff Time: 92415 milliseconds"
                     if (/Request is throttled/i.test(txt) && /Backoff Time/i.test(txt)) {
                         let throttlingMatch = txt.match(/Backoff Time[:=\s]+(\d+)/i);
-                        if (throttlingMatch && throttlingMatch[1] && !isNaN(throttlingMatch[1])) {
+                        if (throttlingMatch) {
                             throttleDelay = Number(throttlingMatch[1]);
                         }
                     }
@@ -941,8 +937,14 @@ export class ImapFlow extends EventEmitter {
                     if (throttleDelay) {
                         err.code = 'ETHROTTLE';
                         err.throttleReset = throttleDelay;
-                        // The server-suggested delay can be very large, so throttleWait() caps it
-                        let delayResponse = Math.min(throttleDelay, MAX_THROTTLE_DELAY);
+                        // The server-suggested delay can be very large, so throttleWait() caps it.
+                        // The reader loop is parked for the whole wait, so it also stays well
+                        // inside the socket inactivity timeout: a wait that outlasted it would
+                        // fire the timeout handler, and the keepalive NOOP it sends can not be
+                        // read while the loop is parked, so the connection would be torn down.
+                        // A caller that retries (fetch) waits out the rest of the hint itself.
+                        let delayResponse = Math.min(throttleDelay, MAX_THROTTLE_DELAY, Math.floor(this.socketTimeout / 2));
+                        err.throttleWaited = delayResponse;
                         this.log.warn({ msg: 'Throttling detected', cid: this.id, throttleDelay, delayResponse, err });
                         let aborted = await this.throttleWait(delayResponse);
                         if (aborted) {
@@ -1241,7 +1243,9 @@ export class ImapFlow extends EventEmitter {
                 let chunk;
                 while (this.writeSocket && (chunk = this.writeSocket.read()) !== null) {
                     if (this._deflate && this._deflate.write(chunk) === false) {
-                        this._deflate.once('drain', readNext);
+                        this._deflate.once('drain', () => {
+                            void readNext();
+                        });
                         return;
                     }
                     // Yield to event loop every 100 chunks to prevent CPU blocking
@@ -1267,7 +1271,8 @@ export class ImapFlow extends EventEmitter {
         };
         writeSocket.on('readable', () => {
             if (!reading && this.writeSocket) {
-                readNext();
+                // readNext() reports its own failures, the returned promise never rejects
+                void readNext();
             }
         });
         writeSocket.on('error', err => {
@@ -1556,6 +1561,7 @@ export class ImapFlow extends EventEmitter {
     /** @internal */
     beginSession(onUnhandledError) {
         clearTimer(this.greetingTimeout);
+        this.greetingReceived = true;
         this.untaggedHandlers.OK = null;
         this.untaggedHandlers.PREAUTH = null;
         if (this.isClosed) {
@@ -1585,9 +1591,7 @@ export class ImapFlow extends EventEmitter {
     }
     /** @internal */
     async initialOK(message) {
-        this.greeting = (message.attributes || [])
-            .filter(entry => entry.type === 'TEXT')
-            .map(entry => entry.value)
+        this.greeting = getTextValues(message.attributes)
             .filter(entry => entry)
             .join('');
         // ALWAYS emit the error so users can handle it
@@ -1611,14 +1615,18 @@ export class ImapFlow extends EventEmitter {
     async serverBye(parsed) {
         // Extract BYE reason from response for better error messages
         let reason = parsed &&
-            parsed.attributes &&
-            parsed.attributes
-                .filter(val => val.type === 'TEXT')
-                .map(val => val.value.trim())
+            getTextValues(parsed.attributes)
+                .map(val => val.trim())
                 .join(' ');
         this.byeReason = reason || 'Server closed connection';
         this.untaggedHandlers.BYE = null;
         this.state = this.states.LOGOUT;
+        // A BYE greeting rejects the connection outright. Do not wait for the server to close
+        // the socket: one that keeps it open would leave connect() pending until the greeting
+        // timeout.
+        if (!this.greetingReceived) {
+            this.closeAfter();
+        }
     }
     // Drops every capability-derived field together - the counterpart of
     // updateCapabilitiesFromRaw() below, which sets them together. rawCapabilities is
@@ -1801,7 +1809,7 @@ export class ImapFlow extends EventEmitter {
         // Replace "*" with the actual message count. Some servers reject bare "*"
         // in certain commands, and this also forces a sequence query (not UID).
         if (value === '*') {
-            if (!this.mailbox.exists) {
+            if (!this.mailbox || !this.mailbox.exists) {
                 return false;
             }
             value = this.mailbox.exists.toString();
@@ -1851,7 +1859,7 @@ export class ImapFlow extends EventEmitter {
     /** @internal */
     autoidle() {
         clearTimer(this.idleStartTimer);
-        if (this.options.disableAutoIdle || this.state !== this.states.SELECTED) {
+        if (this.options.disableAutoIdle || !this.usable || this.state !== this.states.SELECTED) {
             return;
         }
         if (this.connectionBusy()) {
@@ -1863,7 +1871,7 @@ export class ImapFlow extends EventEmitter {
             // missed clearTimeout would inject IDLE between a caller's own commands. Declining
             // postpones rather than cancels: whatever made the connection busy calls autoidle()
             // again when it finishes.
-            if (this.state !== this.states.SELECTED || this.connectionBusy()) {
+            if (!this.usable || this.state !== this.states.SELECTED || this.connectionBusy()) {
                 return;
             }
             this.idle().catch(err => logConnectionError(this, 'Auto-IDLE failed', err));
@@ -2069,50 +2077,14 @@ export class ImapFlow extends EventEmitter {
      */
     close() {
         try {
-            // clear pending timers
-            clearTimer(this.idleStartTimer);
-            clearTimer(this.upgradeTimeout);
-            clearTimer(this.connectTimeout);
-            clearTimer(this.greetingTimeout);
-            // Abort every in-flight throttle back-off so each waiter unblocks and its request is
-            // settled promptly rather than after the full delay.
-            for (let entry of this._throttleWaits) {
-                clearTimer(entry.timer);
-                entry.resolve(true);
-            }
-            this._throttleWaits.clear();
+            this.closeTimers();
             this.usable = false;
             // close() takes over ownership of the idling state: dropping the session token means a
             // poll or IDLE that unwinds after this point sees that it no longer owns the flag and
             // leaves it alone (see claimIdling() in commands/idle.ts).
             this._idleSession = null;
             this.idling = false;
-            // An in-flight STARTTLS upgrade has to be settled through its own single settlement
-            // path, otherwise the upgrade promise (and the session it belongs to) stays pending
-            // for the lifetime of the process.
-            if (typeof this._upgradeReject === 'function') {
-                let reject = this._upgradeReject;
-                this._upgradeReject = null;
-                reject(this.createNoConnectionError(false, { rejectedFrom: 'upgrade' }));
-            }
-            if (typeof this.initialReject === 'function' && !this.options.verifyOnly) {
-                clearTimer(this.greetingTimeout);
-                let reject = this.initialReject;
-                this.initialResolve = false;
-                this.initialReject = false;
-                let err = new Error('Unexpected close');
-                /* c8 ignore next */ // closing a pending connect over an already-secure socket (the TLS branch) is not separately exercised
-                err.code = `ClosedAfterConnect${this.secureConnection ? 'TLS' : 'Text'}`;
-                // Surface the server's BYE reason (e.g. "Too many connections") when the
-                // connection was closed by an untagged BYE, so the caller sees why.
-                if (this.byeReason) {
-                    err.reason = this.byeReason;
-                }
-                // Synchronous rejection is safe: connectPromise was built by guardedPromise(),
-                // so the rejection is already observed. close() is synchronous, so all cleanup
-                // completes before any microtask rejection handler runs.
-                reject(err);
-            }
+            this.closeConnectSteps();
             if (typeof this.preCheck === 'function') {
                 // Runs while the connection is being torn down, so the rejection this sees is
                 // almost always the NoConnection close() is about to raise itself.
@@ -2139,99 +2111,9 @@ export class ImapFlow extends EventEmitter {
                 }
                 this.preCheck = false;
             }
-            // Collect all pending requests to reject
-            let pendingRequests = [];
-            // reject command that is currently processed
-            if (this.currentRequest && this.requestTagMap.has(this.currentRequest.tag)) {
-                let tag = this.currentRequest.tag;
-                let request = this.requestTagMap.get(tag);
-                if (request) {
-                    this.requestTagMap.delete(tag);
-                    pendingRequests.push(request);
-                }
-                this.currentRequest = false;
-            }
-            // reject all other pending commands
-            while (this.requestQueue.length) {
-                let req = this.requestQueue.shift();
-                if (req && this.requestTagMap.has(req.tag)) {
-                    let request = this.requestTagMap.get(req.tag);
-                    if (request) {
-                        this.requestTagMap.delete(req.tag);
-                        pendingRequests.push(request);
-                    }
-                }
-            }
-            // Reject pending requests and locks synchronously. Every promise rejected here was
-            // built by guardedPromise(), so its rejection is already observed and cannot trigger
-            // unhandledRejection. close() is synchronous, so all remaining cleanup runs before
-            // any microtask rejection handler fires.
-            //
-            // The error travels on, though, through await chains and .then() links that
-            // guardedPromise() knows nothing about. Read a crash stack ending here as "this is
-            // the value that escaped", never as "this is the promise that escaped".
-            let byeReason = this.byeReason;
-            for (let request of pendingRequests) {
-                request.reject(this.createNoConnectionError(byeReason, { rejectedFrom: 'pendingRequest', command: request.command }));
-            }
-            // Clear current lock - holder will see errors when they try operations.
-            // Also clear the held-lock diagnostic timer so it doesn't fire post-close.
-            if (this.currentLock && this.currentLock.heldWarnTimer) {
-                clearTimer(this.currentLock.heldWarnTimer);
-                this.currentLock.heldWarnTimer = null;
-            }
-            this.currentLock = false;
-            if (this.locks && this.locks.length) {
-                let pendingLocks = this.locks.splice(0); // Take all locks and clear the array
-                for (let lock of pendingLocks) {
-                    if (lock.acquireTimer) {
-                        clearTimer(lock.acquireTimer);
-                        lock.acquireTimer = null;
-                    }
-                    if (typeof lock.reject === 'function') {
-                        lock.reject(this.createNoConnectionError(byeReason, { rejectedFrom: 'mailboxLock', path: lock.path }));
-                    }
-                }
-            }
-            // cleanup compression streams if they exist
-            if (this._inflate) {
-                try {
-                    this._inflate.unpipe();
-                    this._inflate.destroy();
-                    this._inflate = null;
-                }
-                catch (err) {
-                    this.log.error({ err, msg: 'Failed to destroy inflate stream', cid: this.id });
-                }
-            }
-            if (this._deflate) {
-                try {
-                    this._deflate.unpipe();
-                    this._deflate.destroy();
-                    this._deflate = null;
-                }
-                catch (err) {
-                    this.log.error({ err, msg: 'Failed to destroy deflate stream', cid: this.id });
-                }
-            }
-            // cleanup streamer
-            if (this.streamer) {
-                try {
-                    // remove our listeners explicitly by reference
-                    if (this.socketReadable) {
-                        this.streamer.removeListener('readable', this.socketReadable);
-                    }
-                    if (this._streamerErrorHandler) {
-                        this.streamer.removeListener('error', this._streamerErrorHandler);
-                    }
-                    if (!this.streamer.destroyed) {
-                        this.streamer.destroy();
-                    }
-                }
-                catch (err) {
-                    this.log.error({ err, msg: 'Failed to cleanup streamer', cid: this.id });
-                }
-            }
+            this.closeRequests();
+            this.closeLocks();
+            this.closeStreams();
             // clear socket handlers
             this.clearSocketHandlers();
             // clear cached data
@@ -2244,39 +2126,7 @@ export class ImapFlow extends EventEmitter {
             // Set before teardown so a socket event that re-enters close() during destruction
             // cannot run this block a second time.
             this.isClosed = true;
-            // Socket teardown, in one documented order. Each stream owns and reports its own
-            // lifecycle, so each is destroyed exactly once:
-            //   1. the compression PassThrough (writeSocket), if compression replaced it
-            //   2. the raw socket, which is also writeSocket when compression is not active
-            // The compression streams themselves were destroyed above.
-            if (this.writeSocket && this.writeSocket !== this.socket && !this.writeSocket.destroyed) {
-                try {
-                    this.writeSocket.destroy();
-                }
-                catch (err) {
-                    this.log.error({ err, cid: this.id });
-                }
-            }
-            if (this.socket && !this.socket.destroyed) {
-                try {
-                    this.socket.destroy();
-                }
-                catch (err) {
-                    this.log.error({ err, cid: this.id });
-                }
-            }
-            // Null out all socket and handler references so the GC can collect
-            // them even if the ImapFlow instance itself is still referenced.
-            this.socket = null;
-            this.writeSocket = null;
-            this._inflate = null;
-            this._deflate = null;
-            this._streamerErrorHandler = null;
-            this._connectErrorHandler = null;
-            this._socketError = null;
-            this._socketClose = null;
-            this._socketEnd = null;
-            this._socketTimeout = null;
+            this.closeSockets();
             this.log.debug({
                 msg: 'Connection closed',
                 cid: this.id,
@@ -2286,7 +2136,7 @@ export class ImapFlow extends EventEmitter {
             // whether the session ended with a clean logout or a lost transport. Emitted before
             // 'close' and only from the first close(), so no consumer sees it twice.
             if (closedMailbox) {
-                this.emit('mailboxClose', closedMailbox);
+                emitSafe(this, 'mailboxClose', closedMailbox);
             }
             this.emit('close');
         }
@@ -2295,6 +2145,212 @@ export class ImapFlow extends EventEmitter {
             this.log.error({ err: ex, cid: this.id });
         }
     }
+    /**
+     * Part of close(): clears the pending timers and aborts every throttle back-off.
+     *
+     * @internal
+     */
+    closeTimers() {
+        // clear pending timers
+        clearTimer(this.idleStartTimer);
+        clearTimer(this.upgradeTimeout);
+        clearTimer(this.connectTimeout);
+        clearTimer(this.greetingTimeout);
+        // Abort every in-flight throttle back-off so each waiter unblocks and its request is
+        // settled promptly rather than after the full delay.
+        for (let entry of this._throttleWaits) {
+            clearTimer(entry.timer);
+            entry.resolve(true);
+        }
+        this._throttleWaits.clear();
+    }
+    /**
+     * Part of close(): settles an in-flight STARTTLS upgrade and a pending connect().
+     *
+     * @internal
+     */
+    closeConnectSteps() {
+        // An in-flight STARTTLS upgrade has to be settled through its own single settlement
+        // path, otherwise the upgrade promise (and the session it belongs to) stays pending
+        // for the lifetime of the process.
+        if (typeof this._upgradeReject === 'function') {
+            let reject = this._upgradeReject;
+            this._upgradeReject = null;
+            reject(this.createNoConnectionError(false, { rejectedFrom: 'upgrade' }));
+        }
+        if (typeof this.initialReject === 'function' && !this.options.verifyOnly) {
+            clearTimer(this.greetingTimeout);
+            let reject = this.initialReject;
+            this.initialResolve = false;
+            this.initialReject = false;
+            let err = new Error('Unexpected close');
+            /* c8 ignore next */ // closing a pending connect over an already-secure socket (the TLS branch) is not separately exercised
+            err.code = `ClosedAfterConnect${this.secureConnection ? 'TLS' : 'Text'}`;
+            // Surface the server's BYE reason (e.g. "Too many connections") when the
+            // connection was closed by an untagged BYE, so the caller sees why.
+            if (this.byeReason) {
+                err.reason = this.byeReason;
+            }
+            // Synchronous rejection is safe: connectPromise was built by guardedPromise(),
+            // so the rejection is already observed. close() is synchronous, so all cleanup
+            // completes before any microtask rejection handler runs.
+            reject(err);
+        }
+    }
+    /**
+     * Part of close(): rejects the command in flight and every queued command.
+     *
+     * @internal
+     */
+    closeRequests() {
+        // Collect all pending requests to reject
+        let pendingRequests = [];
+        // reject command that is currently processed
+        if (this.currentRequest && this.requestTagMap.has(this.currentRequest.tag)) {
+            let tag = this.currentRequest.tag;
+            let request = this.requestTagMap.get(tag);
+            if (request) {
+                this.requestTagMap.delete(tag);
+                pendingRequests.push(request);
+            }
+            this.currentRequest = false;
+        }
+        // reject all other pending commands
+        while (this.requestQueue.length) {
+            let req = this.requestQueue.shift();
+            if (req && this.requestTagMap.has(req.tag)) {
+                let request = this.requestTagMap.get(req.tag);
+                if (request) {
+                    this.requestTagMap.delete(req.tag);
+                    pendingRequests.push(request);
+                }
+            }
+        }
+        // Reject pending requests and locks synchronously. Every promise rejected here was
+        // built by guardedPromise(), so its rejection is already observed and cannot trigger
+        // unhandledRejection. close() is synchronous, so all remaining cleanup runs before
+        // any microtask rejection handler fires.
+        //
+        // The error travels on, though, through await chains and .then() links that
+        // guardedPromise() knows nothing about. Read a crash stack ending here as "this is
+        // the value that escaped", never as "this is the promise that escaped".
+        for (let request of pendingRequests) {
+            request.reject(this.createNoConnectionError(this.byeReason, { rejectedFrom: 'pendingRequest', command: request.command }));
+        }
+    }
+    /**
+     * Part of close(): drops the held lock and rejects every pending lock request.
+     *
+     * @internal
+     */
+    closeLocks() {
+        // Clear current lock - holder will see errors when they try operations.
+        // Also clear the held-lock diagnostic timer so it doesn't fire post-close.
+        if (this.currentLock && this.currentLock.heldWarnTimer) {
+            clearTimer(this.currentLock.heldWarnTimer);
+            this.currentLock.heldWarnTimer = null;
+        }
+        this.currentLock = false;
+        if (this.locks && this.locks.length) {
+            let pendingLocks = this.locks.splice(0); // Take all locks and clear the array
+            for (let lock of pendingLocks) {
+                if (lock.acquireTimer) {
+                    clearTimer(lock.acquireTimer);
+                    lock.acquireTimer = null;
+                }
+                if (typeof lock.reject === 'function') {
+                    lock.reject(this.createNoConnectionError(this.byeReason, { rejectedFrom: 'mailboxLock', path: lock.path }));
+                }
+            }
+        }
+    }
+    /**
+     * Part of close(): destroys the compression streams and the response streamer.
+     *
+     * @internal
+     */
+    closeStreams() {
+        // cleanup compression streams if they exist
+        if (this._inflate) {
+            try {
+                this._inflate.unpipe();
+                this._inflate.destroy();
+                this._inflate = null;
+            }
+            catch (err) {
+                this.log.error({ err, msg: 'Failed to destroy inflate stream', cid: this.id });
+            }
+        }
+        if (this._deflate) {
+            try {
+                this._deflate.unpipe();
+                this._deflate.destroy();
+                this._deflate = null;
+            }
+            catch (err) {
+                this.log.error({ err, msg: 'Failed to destroy deflate stream', cid: this.id });
+            }
+        }
+        // cleanup streamer
+        if (this.streamer) {
+            try {
+                // remove our listeners explicitly by reference
+                if (this.socketReadable) {
+                    this.streamer.removeListener('readable', this.socketReadable);
+                }
+                if (this._streamerErrorHandler) {
+                    this.streamer.removeListener('error', this._streamerErrorHandler);
+                }
+                if (!this.streamer.destroyed) {
+                    this.streamer.destroy();
+                }
+            }
+            catch (err) {
+                this.log.error({ err, msg: 'Failed to cleanup streamer', cid: this.id });
+            }
+        }
+    }
+    /**
+     * Part of close(): destroys the sockets once and drops every socket and handler reference.
+     *
+     * @internal
+     */
+    closeSockets() {
+        // Socket teardown, in one documented order. Each stream owns and reports its own
+        // lifecycle, so each is destroyed exactly once:
+        //   1. the compression PassThrough (writeSocket), if compression replaced it
+        //   2. the raw socket, which is also writeSocket when compression is not active
+        // The compression streams themselves were destroyed in closeStreams().
+        if (this.writeSocket && this.writeSocket !== this.socket && !this.writeSocket.destroyed) {
+            try {
+                this.writeSocket.destroy();
+            }
+            catch (err) {
+                this.log.error({ err, cid: this.id });
+            }
+        }
+        if (this.socket && !this.socket.destroyed) {
+            try {
+                this.socket.destroy();
+            }
+            catch (err) {
+                this.log.error({ err, cid: this.id });
+            }
+        }
+        // Null out all socket and handler references so the GC can collect
+        // them even if the ImapFlow instance itself is still referenced.
+        this.socket = null;
+        this.writeSocket = null;
+        // closeStreams() leaves these set when destroying them failed
+        this._inflate = null;
+        this._deflate = null;
+        this._streamerErrorHandler = null;
+        this._connectErrorHandler = null;
+        this._socketError = null;
+        this._socketClose = null;
+        this._socketEnd = null;
+        this._socketTimeout = null;
+    }
     /**
      * Returns current quota
      *
@@ -2452,7 +2508,7 @@ export class ImapFlow extends EventEmitter {
      *
      * @param path mailbox path to check for (unicode string). If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
      * @param query defines requested status items
-     * @returns status of the indicated mailbox
+     * @returns status of the indicated mailbox, or `false` if the server rejected the request
      *
      * @example
      * let status = await client.status('INBOX', {unseen: true});
@@ -2467,7 +2523,7 @@ export class ImapFlow extends EventEmitter {
      * otherwise IDLE is started by default on connection inactivity. NB! If `idle()` is called manually then it does not
      * return until IDLE is finished which means you would have to call some other command out of scope.
      *
-     * @returns Did the operation succeed or not
+     * @returns `false` if IDLE failed, `undefined` otherwise
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -2906,433 +2962,13 @@ export class ImapFlow extends EventEmitter {
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
      * // download body part nr '1.2' from latest message
-     * let {meta, content} = await client.download('*', '1.2');
-     * content.pipe(fs.createWriteStream(meta.filename));
+     * let download = await client.download('*', '1.2');
+     * if (download.content) {
+     *     download.content.pipe(fs.createWriteStream(download.meta.filename));
+     * }
      */
     async download(range, part, options) {
-        if (!this.mailbox) {
-            // no mailbox selected, nothing to do
-            return {};
-        }
-        let downloadOptions = Object.assign({
-            chunkSize: 64 * 1024,
-            maxBytes: Infinity
-        }, options || {});
-        let hasMore = true;
-        let processed = 0;
-        let chunkSize = Number(downloadOptions.chunkSize) || 64 * 1024;
-        // Normalized once here so every bounded stage of the pipeline below agrees on the budget
-        let maxBytes = normalizeByteLimit(downloadOptions.maxBytes);
-        let uid = false;
-        if (part === '1') {
-            // Special handling for part "1": in single-node emails (no childNodes),
-            // the body is accessed via "TEXT" rather than "1", and headers via
-            // "HEADER" instead of "1.MIME". Check bodyStructure to detect this.
-            let response = await this.fetchOne(range, { uid: true, bodyStructure: true }, downloadOptions);
-            if (!response) {
-                return { response: false, chunk: false };
-            }
-            if (!uid && response.uid) {
-                uid = response.uid;
-                // force UID from now on even if first range was a sequence number
-                range = uid;
-                downloadOptions.uid = true;
-            }
-            if (!response.bodyStructure.childNodes) {
-                // single text message
-                part = 'TEXT';
-            }
-        }
-        let getNextPart = async (query) => {
-            query = query || {};
-            let mimeKey;
-            if (!part) {
-                query.source = {
-                    start: processed,
-                    maxLength: chunkSize
-                };
-            }
-            else {
-                part = part.toString().toLowerCase().trim();
-                if (!query.bodyParts) {
-                    query.bodyParts = [];
-                }
-                if (query.size) {
-                    if (/^[\d.]+$/.test(part)) {
-                        // fetch meta as well
-                        mimeKey = part + '.mime';
-                        query.bodyParts.push(mimeKey);
-                    }
-                    else if (part === 'text') {
-                        mimeKey = 'header';
-                        query.bodyParts.push(mimeKey);
-                    }
-                }
-                query.bodyParts.push({
-                    key: part,
-                    start: processed,
-                    maxLength: chunkSize
-                });
-            }
-            let response = await this.fetchOne(range, query, downloadOptions);
-            if (!response) {
-                return { response: false, chunk: false };
-            }
-            if (!uid && response.uid) {
-                uid = response.uid;
-                // force UID from now on even if first range was a sequence number
-                range = uid;
-                downloadOptions.uid = true;
-            }
-            let chunk = !part ? response.source : response.bodyParts && response.bodyParts.get(part);
-            if (!chunk) {
-                return {};
-            }
-            processed += chunk.length;
-            // A compliant server returns at most `chunkSize` bytes for a partial
-            // request. Some servers (Tencent Exmail among them) ignore the partial
-            // spec and answer every request with the complete part. That chunk is
-            // then larger than requested, so treating it as "full, keep going"
-            // would advance the offset past the end forever and never see a short
-            // chunk. An oversized answer already contains the whole part - stop.
-            hasMore = chunk.length === chunkSize;
-            if (chunk.length > chunkSize) {
-                this.log.warn({
-                    msg: 'Server returned more than the requested window, treating the part as complete',
-                    chunkSize,
-                    received: chunk.length,
-                    processed,
-                    cid: this.id
-                });
-            }
-            let result = { chunk };
-            if (query.size) {
-                result.response = response;
-            }
-            if (query.bodyParts) {
-                if (mimeKey === 'header') {
-                    result.mime = response.headers;
-                }
-                else {
-                    result.mime = response.bodyParts && mimeKey ? response.bodyParts.get(mimeKey) : undefined;
-                }
-            }
-            return result;
-        };
-        let { response, chunk, mime } = await getNextPart({
-            size: true,
-            uid: true
-        });
-        if (!response || !chunk) {
-            // ???
-            return {};
-        }
-        let meta = {
-            expectedSize: response.size
-        };
-        if (!part) {
-            meta.contentType = 'message/rfc822';
-        }
-        else if (mime) {
-            let headers = new Headers(mime);
-            let contentType = libmime.parseHeaderValue(headers.getFirst('Content-Type'));
-            let transferEncoding = libmime.parseHeaderValue(headers.getFirst('Content-Transfer-Encoding'));
-            let disposition = libmime.parseHeaderValue(headers.getFirst('Content-Disposition'));
-            if (contentType.value.toLowerCase().trim()) {
-                meta.contentType = contentType.value.toLowerCase().trim();
-            }
-            if (contentType.params.charset) {
-                meta.charset = contentType.params.charset.toLowerCase().trim();
-            }
-            if (transferEncoding.value) {
-                meta.encoding = transferEncoding.value
-                    .replace(/\(.*\)/g, '')
-                    .toLowerCase()
-                    .trim();
-            }
-            if (disposition.value) {
-                /* c8 ignore next */ // a parsed disposition value is never all-whitespace, so the `false` fallback is unreachable
-                meta.disposition = disposition.value.toLowerCase().trim() || false;
-                try {
-                    meta.disposition = libmime.decodeWords(meta.disposition);
-                }
-                catch {
-                    // failed to parse disposition, keep as is (most probably an unknown charset is used)
-                }
-            }
-            if (contentType.params.format && contentType.params.format.toLowerCase().trim() === 'flowed') {
-                meta.flowed = true;
-                if (contentType.params.delsp && contentType.params.delsp.toLowerCase().trim() === 'yes') {
-                    meta.delSp = true;
-                }
-            }
-            let filename = disposition.params.filename || contentType.params.name || false;
-            if (filename) {
-                try {
-                    filename = libmime.decodeWords(filename);
-                }
-                catch {
-                    // failed to parse filename, keep as is (most probably an unknown charset is used)
-                }
-                meta.filename = filename;
-            }
-        }
-        let stream;
-        let output;
-        let fetchAborted = false;
-        // Build a decoder pipeline that progressively transforms the raw FETCH data:
-        //   1. Transfer-encoding decoder (base64 or quoted-printable -> binary)
-        //   2. Format decoder (format=flowed -> plain text, if applicable)
-        //   3. Charset decoder (non-UTF-8 -> UTF-8, for text parts only)
-        //   4. Byte limiter (enforces maxBytes cap)
-        // `stream` is the head of the pipeline (where raw chunks are written),
-        // `output` is the tail (what the caller reads from).
-        // Parts that arrived via FETCH BINARY (response.binaryParts) are already
-        // decoded by the server - decoding again would corrupt the data, so stage 1
-        // is skipped for them.
-        let clientEncoding = response.binaryParts && part && response.binaryParts.has(part) ? false : meta.encoding;
-        switch (clientEncoding) {
-            case 'base64':
-                output = stream = new libbase64.Decoder();
-                break;
-            case 'quoted-printable':
-                output = stream = new libqp.Decoder();
-                break;
-            default:
-                output = stream = new PassThrough();
-        }
-        // Every byte-bounded stage of the pipeline. The fetch loop below stops as soon as any of
-        // them has taken all it will accept. The limiter at the tail is not enough on its own: a
-        // transform in the middle that buffers its whole input before emitting anything (the
-        // format=flowed decoder, the Japanese charset decoder) leaves the tail limiter reporting
-        // `limited === false` however much the server sends, so a download with a small maxBytes
-        // would still pull the entire part off the wire.
-        let limiters = [];
-        let isLimited = () => limiters.some(entry => entry.limited);
-        // Appending a stage means forwarding the current tail's errors to it before piping, so a
-        // failure anywhere reaches the stream the caller is reading
-        let pipeStage = (stage) => {
-            output.on('error', err => {
-                stage.emit('error', err);
-            });
-            output = output.pipe(stage);
-            return stage;
-        };
-        let isTextNode = ['text/html', 'text/plain', 'text/x-amp-html'].includes(meta.contentType) || (part === '1' && !meta.contentType);
-        if ((!meta.disposition || meta.disposition === 'inline') && isTextNode) {
-            // RFC 3676 format=flowed text: unwrap soft line breaks
-            if (meta.flowed) {
-                // FlowedDecoder buffers its whole input before emitting, and being third party it
-                // carries no bound of its own, so bound what it can ever be handed. Unwrapping only
-                // removes bytes, so capping its input at maxBytes cannot push the delivered output
-                // above the cap either.
-                limiters.push(pipeStage(new LimitedPassthrough({ maxBytes })));
-                pipeStage(new FlowedDecoder(meta.delSp ? { delSp: true } : {}));
-            }
-            // Convert non-UTF-8 charsets to UTF-8 via a streaming decoder.
-            // ASCII and UTF-8 need no conversion. Unknown charsets are left as-is.
-            if (meta.charset && !['ascii', 'usascii', 'utf8'].includes(meta.charset.toLowerCase().replace(/[^a-z0-9]+/g, ''))) {
-                try {
-                    let decoder = getDecoder(meta.charset, maxBytes);
-                    // Safety listener attached first so the decoder always has at least
-                    // one 'error' listener. Prevents Node.js from throwing
-                    // ERR_UNHANDLED_ERROR if a later pipe setup step throws and leaves
-                    // the source-forwarding closure attached without a downstream
-                    // listener wired up. Any real listener the caller attaches still
-                    // fires in addition to this one.
-                    decoder.on('error', err => {
-                        this.log.warn({ err, charset: meta.charset, cid: this.id });
-                    });
-                    // The Japanese decoder buffers its whole input as well, and reports the same
-                    // `limited` flag the limiters do so the fetch loop can stop once it is full.
-                    // A streaming decoder has no such flag, which reads as false and is correct.
-                    limiters.push(pipeStage(decoder));
-                    // force to utf-8 for output
-                    meta.charset = 'utf-8';
-                }
-                catch {
-                    // do not decode charset
-                }
-            }
-        }
-        let limiter = pipeStage(new LimitedPassthrough({ maxBytes }));
-        limiters.push(limiter);
-        // Cleanup function
-        const cleanup = () => {
-            fetchAborted = true;
-            if (stream && !stream.destroyed) {
-                stream.destroy();
-            }
-        };
-        // Listen for stream destruction
-        output.once('error', cleanup);
-        output.once('close', cleanup);
-        let writeChunk = (chunk) => {
-            if (isLimited() || fetchAborted || stream.destroyed) {
-                return true;
-            }
-            return stream.write(chunk);
-        };
-        // Ceiling on how many bytes one download may pull off the wire, as the backstop for the
-        // partial-ignoring servers above: a part whose size happens to equal chunkSize exactly
-        // comes back looking like a full window every time, so no test over chunk lengths can end
-        // that loop. RFC822.SIZE bounds any part of the message; doubled for servers that count
-        // line endings differently than they deliver, plus one window so a download sitting right
-        // at the bound still gets its terminating chunk. Infinity when the server reported no
-        // size, which leaves the loop bounded by maxBytes alone.
-        let maxTotalBytes = normalizeByteLimit(meta.expectedSize ? meta.expectedSize * 2 + chunkSize : 0);
-        // Fetch remaining chunks in a loop, writing each to the decoder stream.
-        // Stops when the server returns a short chunk (< chunkSize), answers with more than the
-        // requested window, the byte limiter is satisfied, or the consumer destroys the output
-        // stream. Throws when the ceiling above is crossed.
-        let fetchAllParts = async () => {
-            while (hasMore && !isLimited() && !fetchAborted) {
-                if (processed >= maxTotalBytes) {
-                    // Loud on purpose. Everything written downstream by this point holds
-                    // duplicated content, and a quiet stop is indistinguishable from a clean EOF,
-                    // so the consumer would store a corrupt body believing it intact.
-                    let err = new Error('Download exceeded the expected message size');
-                    err.code = 'DownloadOverflow';
-                    err.maxSize = maxTotalBytes;
-                    err.cid = this.id;
-                    throw err;
-                }
-                let { chunk } = await getNextPart();
-                if (!chunk || fetchAborted) {
-                    break;
-                }
-                // Handle backpressure
-                if (writeChunk(chunk) === false) {
-                    // Wait for drain event before continuing
-                    try {
-                        await new Promise((resolve, reject) => {
-                            // finish() is the listener itself, as settle() is for the TLS upgrade:
-                            // 'drain' and 'close' emit no arguments, 'error' emits the error, and
-                            // removal needs no separate handler references. It removes only the
-                            // three listeners this wait installed - removeAllListeners('error')
-                            // also took off the forwarder pipeStage() attached to the head stream
-                            // when the pipeline was built, and the head must keep that forwarder
-                            // for the life of the download or a chunk failure has nowhere to go.
-                            const finish = (err) => {
-                                for (let event of ['drain', 'error', 'close']) {
-                                    stream.removeListener(event, finish);
-                                }
-                                /* c8 ignore next 2 */ // stream error during a backpressure drain wait is timing-dependent
-                                if (err) {
-                                    reject(err);
-                                }
-                                else {
-                                    resolve();
-                                }
-                            };
-                            stream.once('drain', finish);
-                            stream.once('error', finish);
-                            stream.once('close', finish);
-                        });
-                        /* c8 ignore start */ // re-throw path only triggers on a stream error mid-drain, which is timing-dependent
-                    }
-                    catch (err) {
-                        // Re-throw only if not aborted
-                        if (!fetchAborted) {
-                            throw err;
-                        }
-                    }
-                    /* c8 ignore stop */
-                    // Check if we should abort after waiting
-                    if (fetchAborted) {
-                        break;
-                    }
-                }
-            }
-        };
-        // A download is a sequence of chunk FETCHes with a backpressure wait in between. Those
-        // gaps look exactly like an inactive connection, so without this auto-IDLE would start
-        // between chunks and the next chunk would have to break it again - two extra round
-        // trips per chunk, for as long as the consumer is slow. Counted before control returns
-        // to the event loop: the head chunk's own FETCH already armed the auto-IDLE timer, and
-        // with a very short autoIdleDelay that timer could otherwise fire before the deferred
-        // chunk loop below has marked the download open.
-        this._openDownloads++;
-        let downloadDone = false;
-        let finishDownload = () => {
-            if (!downloadDone) {
-                downloadDone = true;
-                this._openDownloads--;
-                this.autoidle();
-            }
-        };
-        // Kick off the download pipeline asynchronously. The first chunk was
-        // already fetched above (to get metadata); write it to the decoder
-        // stream and then fetch remaining chunks via fetchAllParts().
-        // setImmediate ensures the caller gets the {meta, content} return
-        // value before streaming begins.
-        let runFetchAllParts = () => {
-            fetchAllParts()
-                .catch(err => {
-                if (!fetchAborted && stream && !stream.destroyed) {
-                    stream.emit('error', err);
-                    /* c8 ignore start */ // the else logs when a fetch error arrives after the stream was already torn down (timing-dependent)
-                }
-                else {
-                    // Log when error cannot be emitted to stream
-                    this.log.warn({
-                        msg: 'Download error after stream closed',
-                        err,
-                        fetchAborted,
-                        streamDestroyed: stream?.destroyed,
-                        cid: this.id
-                    });
-                }
-                /* c8 ignore stop */
-            })
-                .finally(() => {
-                finishDownload();
-                if (!fetchAborted && stream && !stream.destroyed) {
-                    stream.end();
-                }
-            })
-                // Terminal guard: nothing consumes this chain, so a throw from either handler
-                // above rejects a promise nobody holds and takes the process down on
-                // unhandledRejection. Reaching it always means an invariant broke - the head
-                // stream kept pipeStage()'s error forwarder for the life of the download, so
-                // emit('error') above has somewhere to go - which is why it logs at error even
-                // for a routine-looking connection code.
-                .catch(err => this.log.error({ msg: 'Failed to fail the download stream', err, cid: this.id }));
-        };
-        setImmediate(() => {
-            let writeResult;
-            try {
-                writeResult = writeChunk(chunk);
-            }
-            catch (err) {
-                stream.emit('error', err);
-                finishDownload();
-                /* c8 ignore next 3 */ // emitting the error above triggers cleanup (fetchAborted=true), so this end() guard is already false here
-                if (!fetchAborted && stream && !stream.destroyed) {
-                    stream.end();
-                }
-                return;
-            }
-            /* c8 ignore next 9 */ // `stream` is piped to the limiter before this runs, so the head write drains synchronously and always returns true (verified for chunkSize up to 8MB); the drain-wait branch is unreachable
-            if (!writeResult) {
-                // Initial chunk filled the buffer, wait for drain
-                stream.once('drain', () => {
-                    if (!fetchAborted) {
-                        runFetchAllParts();
-                    }
-                    else {
-                        finishDownload();
-                    }
-                });
-            }
-            else {
-                runFetchAllParts();
-            }
-        });
-        return {
-            meta,
-            content: output
-        };
+        return await downloadMessage(this, range, part, options);
     }
     /**
      * Fetch multiple attachments as Buffer values
@@ -3350,119 +2986,7 @@ export class ImapFlow extends EventEmitter {
      * process.stdout.write(response[3].content)
      */
     async downloadMany(range, parts, options) {
-        if (!this.mailbox) {
-            // no mailbox selected, nothing to do
-            return {};
-        }
-        let downloadOptions = Object.assign({
-            chunkSize: 64 * 1024,
-            maxBytes: Infinity
-        }, options || {});
-        let query = { bodyParts: [] };
-        for (let part of parts) {
-            query.bodyParts.push(part + '.mime');
-            query.bodyParts.push(part);
-        }
-        let response = await this.fetchOne(range, query, downloadOptions);
-        if (!response || !response.bodyParts) {
-            return { response: false };
-        }
-        let data = {};
-        for (let [part, content] of response.bodyParts) {
-            let keyParts = part.split('.mime');
-            // The server chooses the BODY[...] keys it answers with: never let one be a
-            // prototype-chain name, or the assignments below write onto Object.prototype
-            // (process-wide pollution) instead of the result object.
-            if (isUnsafeKey(keyParts[0])) {
-                continue;
-            }
-            if (keyParts.length === 1) {
-                // content
-                let key = keyParts[0];
-                if (!data[key]) {
-                    data[key] = { content };
-                }
-                else {
-                    data[key].content = content;
-                }
-            }
-            else if (keyParts.length === 2) {
-                // header
-                let key = keyParts[0];
-                if (!data[key]) {
-                    data[key] = {};
-                }
-                let entry = data[key];
-                if (!entry.meta) {
-                    entry.meta = {};
-                }
-                let meta = entry.meta;
-                let headers = new Headers(content);
-                let contentType = libmime.parseHeaderValue(headers.getFirst('Content-Type'));
-                let transferEncoding = libmime.parseHeaderValue(headers.getFirst('Content-Transfer-Encoding'));
-                let disposition = libmime.parseHeaderValue(headers.getFirst('Content-Disposition'));
-                if (contentType.value.toLowerCase().trim()) {
-                    meta.contentType = contentType.value.toLowerCase().trim();
-                }
-                if (contentType.params.charset) {
-                    meta.charset = contentType.params.charset.toLowerCase().trim();
-                }
-                if (transferEncoding.value) {
-                    meta.encoding = transferEncoding.value
-                        .replace(/\(.*\)/g, '')
-                        .toLowerCase()
-                        .trim();
-                }
-                if (disposition.value) {
-                    /* c8 ignore next */ // a parsed disposition value is never all-whitespace, so the `false` fallback is unreachable
-                    meta.disposition = disposition.value.toLowerCase().trim() || false;
-                    try {
-                        meta.disposition = libmime.decodeWords(meta.disposition);
-                    }
-                    catch {
-                        // failed to parse disposition, keep as is (most probably an unknown charset is used)
-                    }
-                }
-                if (contentType.params.format && contentType.params.format.toLowerCase().trim() === 'flowed') {
-                    meta.flowed = true;
-                    if (contentType.params.delsp && contentType.params.delsp.toLowerCase().trim() === 'yes') {
-                        meta.delSp = true;
-                    }
-                }
-                let filename = disposition.params.filename || contentType.params.name || false;
-                if (filename) {
-                    try {
-                        filename = libmime.decodeWords(filename);
-                    }
-                    catch {
-                        // failed to parse filename, keep as is (most probably an unknown charset is used)
-                    }
-                    meta.filename = filename;
-                }
-            }
-        }
-        for (let part of Object.keys(data)) {
-            let entry = data[part];
-            // `meta` is only built from the companion BODY[<part>.MIME] item. A server may
-            // legally answer with fewer items than were requested, and one part arriving
-            // without its MIME headers must not cost the caller the whole download.
-            let meta = entry.meta || {};
-            entry.meta = meta;
-            // parts that arrived via FETCH BINARY (response.binaryParts) are already
-            // decoded by the server - decoding again would corrupt the data
-            let clientEncoding = response.binaryParts && response.binaryParts.has(part) ? false : meta.encoding;
-            switch (clientEncoding) {
-                case 'base64':
-                    entry.content = entry.content ? libbase64.decode(entry.content.toString()) : null;
-                    break;
-                case 'quoted-printable':
-                    entry.content = entry.content ? libqp.decode(entry.content.toString()) : null;
-                    break;
-                default:
-                // keep as is, already a buffer
-            }
-        }
-        return data;
+        return await downloadMessageParts(this, range, parts, options);
     }
     /** @internal */
     async run(command, ...args) {
@@ -3832,7 +3356,8 @@ export class ImapFlow extends EventEmitter {
     }
     /**
      * Detaches sockets from the IMAP pipeline. Useful for upgrading the connection
-     * (e.g., STARTTLS) or transferring socket ownership.
+     * (e.g., STARTTLS) or transferring socket ownership. Call it while the connection is not
+     * idling: an IDLE in progress is not broken first, so the server still expects `DONE`.
      *
      * @returns Socket objects: `readSocket` is the read socket (inflated socket if compression is enabled, raw socket otherwise),
      *   `writeSocket` the write socket and `socket` the raw underlying socket (same as readSocket/writeSocket when compression is disabled)
@@ -3847,6 +3372,11 @@ export class ImapFlow extends EventEmitter {
         // compression is active, the PassThrough writeSocket - so the connection
         // is fully released to the caller.
         this.clearSocketHandlers();
+        // The socket now belongs to the caller. Marking the client unusable keeps
+        // auto-IDLE (armed now, or re-armed by a lock release or a finished download)
+        // and a later dispose from writing IDLE or LOGOUT onto it.
+        this.usable = false;
+        clearTimer(this.idleStartTimer);
         const readSocket = this._inflate || socket;
         const writeSocket = this.writeSocket || socket;
         // Defense-in-depth: when compression is active the raw socket is orphaned
@@ -3944,6 +3474,23 @@ export class ImapFlow extends EventEmitter {
  *     console.log(`${entry.cid} ${entry.msg}`);
  * });
  */
+// Installed outside the class body: a computed `[Symbol.asyncDispose]` key would turn into a
+// method named "undefined" on Node.js 20.0-20.3, which predate the symbol
+if (typeof Symbol.asyncDispose === 'symbol') {
+    ImapFlow.prototype[Symbol.asyncDispose] = async function () {
+        if (this.usable) {
+            try {
+                await this.logout();
+            }
+            catch (err) {
+                logConnectionError(this, 'LOGOUT failed while disposing', err);
+            }
+        }
+        // logout() already closes the connection; close() is idempotent and covers a client
+        // that never connected or whose logout was skipped
+        this.close();
+    };
+}
 // Both `import { ImapFlow } from 'imapflow'` and `import imapflow from 'imapflow'` work, the
 // latter matching the shape `require('imapflow')` has always had
 const imapflow = { ImapFlow, AuthenticationFailure };