imapflow 1.3.5 → 1.3.7

package/lib/imap-flow.js

@@ -23,7 +23,7 @@ const libbase64 = require('libbase64');
 const FlowedDecoder = require('@zone-eu/mailsplit/lib/flowed-decoder');
 const { PassThrough } = require('stream');
 
-const { proxyConnection } = require('./proxy-connection');
+const { proxyConnection, detachEarlyErrorHandler } = require('./proxy-connection');
 
 const {
     comparePaths,
@@ -292,13 +292,24 @@ class ImapFlow extends EventEmitter {
             cid: this.id,
             logRaw: this.logRaw,
             secureConnection: this.secureConnection,
-            maxLineLength: this.options.maxLineLength
+            maxLineLength: this.options.maxLineLength,
+            maxLiteralSize: this.options.maxLiteralSize
         });
 
         this.reading = false;
         this.socket = false;
         this.writeSocket = false;
 
+        // Tracked throttle back-off timer (see reader()). Stored so close() can clear it
+        // and abort the wait instead of letting it keep the event loop alive for minutes.
+        this._throttleTimer = null;
+        this._throttleAbort = null;
+
+        // Pending rejector of the in-flight STARTTLS upgrade promise (see upgradeToSTARTTLS()).
+        // Stored so emitError() can route a streamer-originated error into the upgrade's single
+        // error path instead of dropping it (which could hang a verifyOnly connect()).
+        this._upgradeReject = null;
+
         this.isClosed = false;
 
         this.states = states;
@@ -327,6 +338,10 @@ class ImapFlow extends EventEmitter {
 
         this.expectCapabilityUpdate = false; // force CAPABILITY after LOGIN
 
+        // Set true if the server sent data after the STARTTLS OK and before the TLS
+        // handshake (a plaintext-injection signal). See upgradeToSTARTTLS().
+        this._starttlsHadTrailingData = false;
+
         /**
          * Enabled capabilities. Usually `CONDSTORE` and `UTF8=ACCEPT` if server supports these.
          * @type {Set<string>}
@@ -405,6 +420,34 @@ class ImapFlow extends EventEmitter {
         }
         err._connId = err._connId || this.id;
 
+        // During a STARTTLS handshake the upgrade promise owns the single error path
+        // (tlsSocketErrorHandler -> reject). Route the error there so a streamer-originated
+        // failure is surfaced with its real code (instead of a generic ClosedAfterConnect*)
+        // and cannot hang a verifyOnly connect() waiting on a 'close' that never rejects.
+        // Fall back to closing if the upgrade has no pending rejector.
+        if (this.upgrading) {
+            this.upgrading = false;
+            this.closeAfter();
+            if (typeof this._upgradeReject === 'function') {
+                let reject = this._upgradeReject;
+                this._upgradeReject = null;
+                reject(err);
+            }
+            return;
+        }
+
+        // While the initial connect promise is still pending it owns error reporting:
+        // reject it once instead of emitting a duplicate 'error' event (which would also
+        // throw if the caller has not attached an 'error' listener yet).
+        if (typeof this.initialReject === 'function') {
+            let reject = this.initialReject;
+            this.initialResolve = false;
+            this.initialReject = false;
+            this.closeAfter();
+            reject(err);
+            return;
+        }
+
         this.closeAfter();
         this.emit('error', err);
     }
@@ -533,6 +576,7 @@ class ImapFlow extends EventEmitter {
             isLogging: true
         });
 
+        /* c8 ignore next */ // send() is always invoked with a request object carrying options, so the {} fallback is unreachable
         let options = data.options || {};
 
         this.log.debug({ src: 'c', msg: logCompiled.toString(), cid: this.id, comment: options.comment });
@@ -689,8 +733,14 @@ class ImapFlow extends EventEmitter {
             // Server acknowledged our literal size with "+", send the actual literal data
             if (parsed.tag === '+' && this.commandParts.length) {
                 let content = this.commandParts.shift();
-                this.write(content);
-                this.log.debug({ src: 'c', msg: `(* ${content.length}B continuation *)`, cid: this.id });
+                // A write() failure here (e.g. socket closed mid-command) must not propagate
+                // out of the loop and skip data.next(), which would stall the parser stream.
+                try {
+                    this.write(content);
+                    this.log.debug({ src: 'c', msg: `(* ${content.length}B continuation *)`, cid: this.id });
+                } catch (err) {
+                    this.log.warn({ err, cid: this.id });
+                }
                 data.next();
                 continue;
             }
@@ -725,15 +775,22 @@ class ImapFlow extends EventEmitter {
                 this.requestTagMap.delete(parsed.tag);
 
                 if (this.currentRequest && this.currentRequest.tag === parsed.tag) {
-                    // send next pending command
+                    // send next pending command. A failure here must not propagate out of the
+                    // loop and skip data.next() below, which would stall the parser stream.
                     this.currentRequest = false;
-                    await this.trySend();
+                    try {
+                        await this.trySend();
+                    } catch (err) {
+                        this.log.warn({ err, cid: this.id });
+                    }
                 }
 
                 switch (parsed.command.toUpperCase()) {
                     case 'OK':
                     case 'BYE':
-                        await new Promise(resolve => request.resolve({ response: parsed, next: resolve }));
+                        // hasTrailingData is forwarded so STARTTLS can detect a plaintext
+                        // injection (data buffered after the tagged OK, before the handshake).
+                        await new Promise(resolve => request.resolve({ response: parsed, next: resolve, hasTrailingData: !!data.trailingAfterLine }));
                         break;
 
                     case 'NO':
@@ -796,7 +853,29 @@ class ImapFlow extends EventEmitter {
                                 }
 
                                 this.log.warn({ msg: 'Throttling detected', cid: this.id, throttleDelay, delayResponse, err });
-                                await new Promise(r => setTimeout(r, delayResponse));
+
+                                // Tracked, abortable wait. Storing the timer lets close() clear it so
+                                // the back-off never keeps the event loop alive, and storing the resolve
+                                // lets close() abort the wait promptly (aborted=true) instead of blocking
+                                // the reader for up to 5 minutes and rejecting long after the connection
+                                // is gone. Normal expiry resolves with aborted=false.
+                                let aborted = await new Promise(resolve => {
+                                    this._throttleAbort = resolve;
+                                    this._throttleTimer = setTimeout(() => resolve(false), delayResponse);
+                                    if (typeof this._throttleTimer.unref === 'function') {
+                                        this._throttleTimer.unref();
+                                    }
+                                });
+                                this._throttleTimer = null;
+                                this._throttleAbort = null;
+
+                                if (aborted) {
+                                    // Connection closed during back-off: reject promptly with a
+                                    // connection error (carrying any server BYE reason) instead of
+                                    // waiting out the throttle delay.
+                                    request.reject(this.createNoConnectionError(this.byeReason));
+                                    break;
+                                }
                             }
                         }
 
@@ -847,12 +926,6 @@ class ImapFlow extends EventEmitter {
         // Clear any existing handlers first to prevent duplicates
         this.clearSocketHandlers();
 
-        // Remove temporary connection error handler if present
-        if (this._connectErrorHandler && this.socket) {
-            this.socket.removeListener('error', this._connectErrorHandler);
-            this._connectErrorHandler = null;
-        }
-
         this._socketError =
             this._socketError ||
             (err => {
@@ -1013,7 +1086,13 @@ class ImapFlow extends EventEmitter {
         this.streamer.compress = true;
         this.socket.pipe(this._inflate).pipe(this.streamer);
         this._inflate.on('error', err => {
-            this.streamer.emit('error', err);
+            // Only forward into the streamer while it is alive and still has an error
+            // listener. After close() the streamer is destroyed and its listener removed,
+            // so emitting 'error' would throw an unhandled error and crash the process.
+            // (this.streamer is assigned once in the constructor and never nulled.)
+            if (!this.streamer.destroyed && this.streamer.listenerCount('error')) {
+                this.streamer.emit('error', err);
+            }
         });
 
         // For outgoing data, replace the writeSocket with a PassThrough buffer.
@@ -1024,6 +1103,7 @@ class ImapFlow extends EventEmitter {
             highWaterMark: 64 * 1024 // 64KB buffer limit to prevent excessive memory usage
         });
 
+        /* c8 ignore start */ // destroySoon override is never invoked by ImapFlow (close() calls destroy()); kept for stream API completeness
         this.writeSocket.destroySoon = () => {
             try {
                 if (this.socket) {
@@ -1035,6 +1115,7 @@ class ImapFlow extends EventEmitter {
                 throw err;
             }
         };
+        /* c8 ignore stop */
 
         Object.defineProperty(this.writeSocket, 'destroyed', {
             get: () => !this.socket || this.socket.destroyed
@@ -1058,6 +1139,7 @@ class ImapFlow extends EventEmitter {
 
                     // Yield to event loop every 100 chunks to prevent CPU blocking
                     processedChunks++;
+                    /* c8 ignore next 6 */ // requires 100+ queued chunks in a single pump pass; not reproducible deterministically
                     if (processedChunks % 100 === 0) {
                         await new Promise(resolve => setImmediate(resolve));
                         if (!this.writeSocket) {
@@ -1072,6 +1154,7 @@ class ImapFlow extends EventEmitter {
                 }
 
                 reading = false;
+                /* c8 ignore next 3 */ // defensive: the pump body does not throw under normal operation
             } catch (ex) {
                 this.emitError(ex);
             }
@@ -1139,11 +1222,42 @@ class ImapFlow extends EventEmitter {
             return this._failSTARTTLS();
         }
 
+        // STARTTLS plaintext-injection guard (RFC 3501 §6.2.1): a compliant server stays
+        // silent after the tagged STARTTLS OK until the TLS handshake, so any data that
+        // followed the OK was injected by a MITM and must not be treated as if it arrived
+        // over TLS. Two complementary best-effort checks fail closed before wrapping the
+        // socket; injection that still races in afterwards corrupts the TLS handshake and
+        // is rejected there instead (with a generic TLS error rather than STARTTLS_INJECTION).
+        const failSTARTTLSInjection = () => {
+            let err = new Error('Server sent data after the STARTTLS response and before the TLS handshake; possible plaintext-injection attack');
+            err.code = 'STARTTLS_INJECTION';
+            err.tlsFailed = true;
+            this.closeAfter();
+            return err;
+        };
+
+        // Check 1: the parser saw more input already buffered right after the tagged OK
+        // (same TCP segment, or an already-queued chunk) — see hasTrailingData / starttls.js.
+        if (this._starttlsHadTrailingData) {
+            throw failSTARTTLSInjection();
+        }
+
         // STARTTLS upgrade sequence: detach the plain socket from the parser,
         // wrap it in a TLS socket, then reconnect the new TLS socket to the
         // parser. The plain socket becomes the underlying transport for TLS.
         this.socket.unpipe(this.streamer);
+
+        // Check 2: now that the parser is detached, any bytes still buffered on the plain
+        // socket arrived after the OK and were not consumed by the handshake — i.e. injected.
+        // This catches late/fragmented injection that the parse-time snapshot cannot see.
+        let injectedTail = typeof this.socket.read === 'function' ? this.socket.read() : null;
+        /* c8 ignore next 3 */ // late/fragmented post-OK injection is timing-dependent and not deterministically reproducible
+        if (injectedTail && injectedTail.length) {
+            throw failSTARTTLSInjection();
+        }
         let upgraded = await new Promise((resolve, reject) => {
+            // Expose this rejector so emitError() can settle the upgrade with a streamer error.
+            this._upgradeReject = reject;
             let socketPlain = this.socket;
             let opts = Object.assign(
                 {
@@ -1156,6 +1270,7 @@ class ImapFlow extends EventEmitter {
             this.clearSocketHandlers();
 
             // Store error handler for cleanup after successful upgrade
+            /* c8 ignore start */ // plain-socket error during the TLS handshake window is timing-dependent (errors surface via the streamer/emitError path in tests)
             const socketPlainErrorHandler = err => {
                 clearTimeout(this.connectTimeout);
                 clearTimeout(this.upgradeTimeout);
@@ -1168,8 +1283,10 @@ class ImapFlow extends EventEmitter {
                 err.tlsFailed = true;
                 reject(err);
             };
+            /* c8 ignore stop */
             socketPlain.once('error', socketPlainErrorHandler);
 
+            /* c8 ignore start */ // UPGRADE_TIMEOUT is 10s; firing it deterministically would make the test suite hang
             this.upgradeTimeout = setTimeout(() => {
                 if (!this.upgrading) {
                     return;
@@ -1180,6 +1297,7 @@ class ImapFlow extends EventEmitter {
                 err.code = 'UPGRADE_TIMEOUT';
                 reject(err);
             }, UPGRADE_TIMEOUT);
+            /* c8 ignore stop */
 
             // A TLS handshake failure (bad certificate, protocol mismatch, etc.) is emitted on the
             // new TLS socket, not on the plain socket, so it must be handled here. Without this the
@@ -1188,10 +1306,12 @@ class ImapFlow extends EventEmitter {
             const tlsSocketErrorHandler = err => {
                 clearTimeout(this.connectTimeout);
                 clearTimeout(this.upgradeTimeout);
+                /* c8 ignore start */ // the already-settled early return is a defensive double-fire guard, not separately exercised
                 if (!this.upgrading) {
                     // already settled
                     return;
                 }
+                /* c8 ignore stop */
                 this.upgrading = false;
                 err.tlsFailed = true;
                 this.clearSocketHandlers();
@@ -1203,10 +1323,12 @@ class ImapFlow extends EventEmitter {
             this.socket = tls.connect(opts, () => {
                 try {
                     clearTimeout(this.upgradeTimeout);
+                    /* c8 ignore start */ // race: connection closed during the TLS handshake window
                     if (this.isClosed) {
                         // not sure if this is possible?
                         return this.close();
                     }
+                    /* c8 ignore stop */
 
                     // TLS handshake complete. Reconnect the now-encrypted socket
                     // to the IMAP parser stream and record the cipher details.
@@ -1214,6 +1336,7 @@ class ImapFlow extends EventEmitter {
                     this.upgrading = false;
                     this.streamer.secureConnection = true;
                     this.socket.pipe(this.streamer);
+                    /* c8 ignore next */ // an upgraded TLS socket always exposes getCipher(), so the false fallback is unreachable
                     this.tls = typeof this.socket.getCipher === 'function' ? this.socket.getCipher() : false;
                     if (this.tls) {
                         this.tls.authorized = this.socket.authorized;
@@ -1222,6 +1345,7 @@ class ImapFlow extends EventEmitter {
                             msg: 'Established TLS session',
                             cid: this.id,
                             authorized: this.tls.authorized,
+                            /* c8 ignore next */ // cipher.standardName is present on modern Node, so the .name fallback rarely runs
                             algo: this.tls.standardName || this.tls.name,
                             version: this.tls.version
                         });
@@ -1231,20 +1355,30 @@ class ImapFlow extends EventEmitter {
                     socketPlain.removeListener('error', socketPlainErrorHandler);
                     this.socket.removeListener('error', tlsSocketErrorHandler);
 
+                    // Install the normal socket handlers only now that the handshake
+                    // succeeded. Doing this during the handshake would leave both
+                    // tlsSocketErrorHandler and the generic _socketError on the socket;
+                    // a handshake 'error' would then fire BOTH (EventEmitter clones its
+                    // listener array on emit), causing a duplicate error and a possible
+                    // unhandled 'error' crash. Keeping tlsSocketErrorHandler as the sole
+                    // listener until here guarantees a single error path for the upgrade.
+                    this.setSocketHandlers();
+
+                    this._upgradeReject = null;
                     return resolve(true);
+                    /* c8 ignore next 3 */ // defensive: the success callback body does not throw under normal operation
                 } catch (ex) {
                     this.emitError(ex);
                 }
             });
 
-            // Registered after tls.connect (the TLS socket now exists) but before
-            // setSocketHandlers() so it fires first on a handshake error and removes the generic
-            // handlers, keeping this the single error path for the upgrade.
+            // Registered after tls.connect (the TLS socket now exists). This is the ONLY
+            // error listener during the handshake window; the generic handlers are installed
+            // by setSocketHandlers() inside the success callback above, so a handshake error
+            // has a single error path (tlsSocketErrorHandler -> reject).
             this.socket.once('error', tlsSocketErrorHandler);
 
             this.writeSocket = this.socket;
-
-            this.setSocketHandlers();
         });
 
         if (upgraded && this.expectCapabilityUpdate) {
@@ -1682,6 +1816,7 @@ class ImapFlow extends EventEmitter {
                 let err = new Error('Failed to establish connection in required time');
                 err.code = 'CONNECT_TIMEOUT';
                 err.details = {
+                    /* c8 ignore next */ // firing the timeout with the default (large) value would hang the suite, so only the explicit-option path is tested
                     connectionTimeout: this.options.connectionTimeout || CONNECT_TIMEOUT
                 };
                 this.log.error({ err, cid: this.id });
@@ -1692,15 +1827,22 @@ class ImapFlow extends EventEmitter {
             let onConnect = () => {
                 try {
                     clearTimeout(this.connectTimeout);
+
+                    // ImapFlow now owns the socket; drop the proxy's early error handler
+                    // (its "before connection setup" message no longer applies).
+                    detachEarlyErrorHandler(socket);
+
                     this.socket.setKeepAlive(true, 5 * 1000);
                     this.socket.setTimeout(this.options.socketTimeout || SOCKET_TIMEOUT);
 
                     this.greetingTimeout = setTimeout(() => {
                         let err = new Error(
+                            /* c8 ignore next */ // the greeting-timeout test uses a plaintext socket; the secure-socket branch of this hint is not separately exercised
                             `Failed to receive greeting from server in required time${!this.secureConnection ? '. Maybe should use TLS?' : ''}`
                         );
                         err.code = 'GREETING_TIMEOUT';
                         err.details = {
+                            /* c8 ignore next */ // firing the timeout with the default (large) value would hang the suite, so only the explicit-option path is tested
                             greetingTimeout: this.options.greetingTimeout || GREETING_TIMEOUT
                         };
                         this.log.error({ err, cid: this.id });
@@ -1725,6 +1867,7 @@ class ImapFlow extends EventEmitter {
 
                     if (this.tls) {
                         logInfo.authorized = this.tls.authorized = this.socket.authorized;
+                        /* c8 ignore next */ // cipher.standardName is present on modern Node, so the .name fallback rarely runs
                         logInfo.algo = this.tls.standardName || this.tls.name;
                         logInfo.version = this.tls.version;
                     }
@@ -1738,6 +1881,7 @@ class ImapFlow extends EventEmitter {
                     // executed by initial "* OK"
                     this.initialResolve = resolve;
                     this.initialReject = reject;
+                    /* c8 ignore next 4 */ // defensive: the onConnect setup body does not throw under normal operation
                 } catch (ex) {
                     // connect failed
                     reject(ex);
@@ -1802,6 +1946,17 @@ class ImapFlow extends EventEmitter {
         setImmediate(() => this.close());
     }
 
+    // Builds the standard "connection not available" error, optionally annotated with the
+    // server's BYE reason. Single source of truth so every NoConnection rejection is consistent.
+    createNoConnectionError(byeReason) {
+        const error = new Error('Connection not available');
+        error.code = 'NoConnection';
+        if (byeReason) {
+            error.reason = byeReason;
+        }
+        return error;
+    }
+
     /**
      * Closes TCP connection without notifying the server.
      *
@@ -1819,6 +1974,15 @@ class ImapFlow extends EventEmitter {
             clearTimeout(this.connectTimeout);
             clearTimeout(this.greetingTimeout);
 
+            // Abort any in-flight throttle back-off so the reader unblocks and the
+            // throttled request is rejected promptly rather than after the full delay.
+            clearTimeout(this._throttleTimer);
+            this._throttleTimer = null;
+            if (typeof this._throttleAbort === 'function') {
+                this._throttleAbort(true);
+                this._throttleAbort = null;
+            }
+
             this.usable = false;
             this.idling = false;
 
@@ -1828,7 +1992,13 @@ class ImapFlow extends EventEmitter {
                 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.catch(noop) is already
                 // attached, so the rejection is observed immediately. close() is synchronous,
                 // so all cleanup completes before any microtask rejection handler runs.
@@ -1865,15 +2035,8 @@ class ImapFlow extends EventEmitter {
                 }
             }
 
-            // Helper to create connection error
-            const createNoConnectionError = byeReason => {
-                const error = new Error('Connection not available');
-                error.code = 'NoConnection';
-                if (byeReason) {
-                    error.reason = byeReason;
-                }
-                return error;
-            };
+            // Helper to create connection error (delegates to the shared builder)
+            const createNoConnectionError = byeReason => this.createNoConnectionError(byeReason);
 
             // Reject pending requests and locks synchronously. Each exec() and
             // getMailboxLock() promise already has .catch(noop) attached, so the
@@ -3168,6 +3331,7 @@ class ImapFlow extends EventEmitter {
             }
 
             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);
@@ -3298,6 +3462,7 @@ class ImapFlow extends EventEmitter {
                             let resolved = false;
 
                             const finish = err => {
+                                /* c8 ignore next */ // the first call removes all three listeners, so a later drain/error/close can't re-enter finish; this guard is belt-and-suspenders
                                 if (resolved) return;
                                 resolved = true;
 
@@ -3306,6 +3471,7 @@ class ImapFlow extends EventEmitter {
                                 stream.removeAllListeners('error');
                                 stream.removeAllListeners('close');
 
+                                /* c8 ignore next 2 */ // stream error during a backpressure drain wait is timing-dependent
                                 if (err) {
                                     reject(err);
                                 } else {
@@ -3317,12 +3483,14 @@ class ImapFlow extends EventEmitter {
                             stream.once('error', err => finish(err));
                             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) {
@@ -3342,6 +3510,7 @@ class ImapFlow extends EventEmitter {
                 .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({
@@ -3352,6 +3521,7 @@ class ImapFlow extends EventEmitter {
                             cid: this.id
                         });
                     }
+                    /* c8 ignore stop */
                 })
                 .finally(() => {
                     if (!fetchAborted && stream && !stream.destroyed) {
@@ -3366,12 +3536,14 @@ class ImapFlow extends EventEmitter {
                 writeResult = writeChunk(chunk);
             } catch (err) {
                 stream.emit('error', err);
+                /* 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 7 */ // `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', () => {
@@ -3476,6 +3648,7 @@ class ImapFlow extends EventEmitter {
                 }
 
                 if (disposition.value) {
+                    /* c8 ignore next */ // a parsed disposition value is never all-whitespace, so the `false` fallback is unreachable
                     data[key].meta.disposition = disposition.value.toLowerCase().trim() || false;
                     try {
                         data[key].meta.disposition = libmime.decodeWords(data[key].meta.disposition);
@@ -3615,6 +3788,7 @@ class ImapFlow extends EventEmitter {
                             lockId: lock.lockId,
                             path,
                             heldFor: Date.now() - lock.heldAt,
+                            /* c8 ignore next */ // the held-lock-warning diagnostic with a description set is a timing-dependent log detail
                             ...(options.description && { description: options.description }),
                             cid: this.id
                         });
@@ -3722,11 +3896,13 @@ class ImapFlow extends EventEmitter {
             // New locks may have been queued while we were processing (e.g.,
             // a lock that failed immediately and the next getMailboxLock call
             // arrived before we finished). Schedule another run if needed.
+            /* c8 ignore start */ // requires a lock to be enqueued during an in-flight processLocks pass; not reproducible deterministically
             if (this.locks.length && !this.currentLock) {
                 setImmediate(() => {
                     this.processLocks().catch(err => this.log.error({ err, cid: this.id }));
                 });
             }
+            /* c8 ignore stop */
         }
     }
 

package/lib/proxy-connection.js

@@ -15,6 +15,29 @@ const hidePassword = proxyUrl => {
     }
 };
 
+// Attaches a benign 'error' listener as soon as the proxied socket exists, so an early
+// socket error (before ImapFlow installs its own handlers) cannot surface as an unhandled
+// 'error' event and crash the process. The handler is stored on the socket so the caller
+// can remove it once it takes ownership of the socket.
+const attachEarlyErrorHandler = (logger, socket) => {
+    if (!socket || typeof socket.on !== 'function') {
+        return;
+    }
+    socket._earlyErrorHandler = err => {
+        logger.error({ msg: 'Proxy socket error before connection setup', err });
+    };
+    socket.on('error', socket._earlyErrorHandler);
+};
+
+// Removes the handler installed by attachEarlyErrorHandler once the caller takes ownership
+// of the socket. Keeps the internal `_earlyErrorHandler` contract inside this module.
+const detachEarlyErrorHandler = socket => {
+    if (socket && socket._earlyErrorHandler) {
+        socket.removeListener('error', socket._earlyErrorHandler);
+        socket._earlyErrorHandler = null;
+    }
+};
+
 const proxyConnection = async (logger, connectionUrl, host, port) => {
     let proxyUrl = new URL(connectionUrl);
 
@@ -44,6 +67,7 @@ const proxyConnection = async (logger, connectionUrl, host, port) => {
                         port,
                         host
                     });
+                    attachEarlyErrorHandler(logger, socket);
                 }
                 return socket;
             } catch (err) {
@@ -106,6 +130,7 @@ const proxyConnection = async (logger, connectionUrl, host, port) => {
                         port,
                         host
                     });
+                    attachEarlyErrorHandler(logger, info.socket);
                 }
                 return info.socket;
             } catch (err) {
@@ -123,4 +148,4 @@ const proxyConnection = async (logger, connectionUrl, host, port) => {
     }
 };
 
-module.exports = { proxyConnection };
+module.exports = { proxyConnection, detachEarlyErrorHandler };