imapflow 1.3.4 → 1.3.6

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,
@@ -291,13 +291,25 @@ class ImapFlow extends EventEmitter {
             logger: this.log,
             cid: this.id,
             logRaw: this.logRaw,
-            secureConnection: this.secureConnection
+            secureConnection: this.secureConnection,
+            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;
@@ -326,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>}
@@ -404,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);
     }
@@ -688,8 +732,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;
             }
@@ -724,15 +774,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':
@@ -795,7 +852,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;
+                                }
                             }
                         }
 
@@ -1012,7 +1091,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.
@@ -1138,11 +1223,41 @@ 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;
+        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(
                 {
@@ -1180,6 +1295,24 @@ class ImapFlow extends EventEmitter {
                 reject(err);
             }, UPGRADE_TIMEOUT);
 
+            // 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
+            // upgrade promise would only settle via the timeout and connect() would reject with a
+            // generic "Unexpected close" instead of the actual TLS error.
+            const tlsSocketErrorHandler = err => {
+                clearTimeout(this.connectTimeout);
+                clearTimeout(this.upgradeTimeout);
+                if (!this.upgrading) {
+                    // already settled
+                    return;
+                }
+                this.upgrading = false;
+                err.tlsFailed = true;
+                this.clearSocketHandlers();
+                this.closeAfter();
+                reject(err);
+            };
+
             this.upgrading = true;
             this.socket = tls.connect(opts, () => {
                 try {
@@ -1208,18 +1341,33 @@ class ImapFlow extends EventEmitter {
                         });
                     }
 
-                    // Clean up the plain socket error handler after successful upgrade
+                    // Clean up the error handlers after successful upgrade
                     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);
                 } catch (ex) {
                     this.emitError(ex);
                 }
             });
 
-            this.writeSocket = this.socket;
+            // 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.setSocketHandlers();
+            this.writeSocket = this.socket;
         });
 
         if (upgraded && this.expectCapabilityUpdate) {
@@ -1667,6 +1815,11 @@ 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);
 
@@ -1777,6 +1930,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.
      *
@@ -1794,6 +1958,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;
 
@@ -1804,6 +1977,11 @@ class ImapFlow extends EventEmitter {
                 this.initialReject = false;
                 let err = new Error('Unexpected close');
                 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.
@@ -1840,15 +2018,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
@@ -3829,6 +4000,7 @@ class ImapFlow extends EventEmitter {
      * @returns {Object} Socket objects
      * @returns {Object} return.readSocket The read socket (inflated socket if compression is enabled, raw socket otherwise)
      * @returns {Object} return.writeSocket The write socket
+     * @returns {Object} return.socket The raw underlying socket (same as readSocket/writeSocket when compression is disabled)
      */
     unbind() {
         this.socket.unpipe(this.streamer);
@@ -3836,15 +4008,32 @@ class ImapFlow extends EventEmitter {
             this._inflate.unpipe(this.streamer);
         }
 
-        this.socket.removeListener('error', this._socketError);
-        this.socket.removeListener('close', this._socketClose);
-        this.socket.removeListener('end', this._socketEnd);
-        this.socket.removeListener('tlsClientError', this._socketError);
-        this.socket.removeListener('timeout', this._socketTimeout);
+        // Detach all of ImapFlow's socket listeners — the raw socket plus, when
+        // compression is active, the PassThrough writeSocket — so the connection
+        // is fully released to the caller.
+        this.clearSocketHandlers();
+
+        const readSocket = this._inflate || this.socket;
+        const writeSocket = this.writeSocket || this.socket;
+
+        // Defense-in-depth: when compression is active the raw socket is orphaned
+        // (neither readSocket nor writeSocket) yet still live and still the target
+        // of the deflate/writeSocket error forwarders. We just stripped our own
+        // error listener, so any post-unbind error (e.g. an upstream ECONNRESET)
+        // would become an unhandled 'error' that crashes the host process. Attach
+        // a benign listener so the orphaned socket can never throw after handoff.
+        // Non-compression path: socket === readSocket === writeSocket and the
+        // caller owns it directly, so leave it untouched (no behavior change).
+        if (this.socket !== readSocket && this.socket !== writeSocket) {
+            this.socket.on('error', err => {
+                this.log.debug({ msg: 'Suppressed error on unbound socket', err, cid: this.id });
+            });
+        }
 
         return {
-            readSocket: this._inflate || this.socket,
-            writeSocket: this.writeSocket || this.socket
+            readSocket,
+            writeSocket,
+            socket: this.socket
         };
     }
 }

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 };

package/lib/tools.js

@@ -494,7 +494,7 @@ const tools = {
 
             // normalize path to use ascii, so we would always get the same ID
             let path = mailbox.path;
-            if (/[0x80-0xff]/.test(path)) {
+            if (/[\u0080-\uffff]/.test(path)) {
                 try {
                     path = iconv.encode(path, 'utf-7-imap').toString();
                 } catch {
@@ -502,6 +502,10 @@ const tools = {
                 }
             }
 
+            // Non-cryptographic identifier: MD5 is used only to derive a stable, compact
+            // account-unique id from non-secret data (path:uidValidity:uid). No security
+            // property (collision/preimage resistance, secrecy) is relied upon, so a fast
+            // hash is the appropriate choice here — not a security-sensitive use.
             map.id =
                 map.emailId ||
                 createHash('md5')
@@ -1069,7 +1073,9 @@ const tools = {
             return '';
         }
 
-        list.sort((a, b) => a - b);
+        // Deduplicate before sorting so that repeated values do not produce
+        // overlapping/non-canonical tokens (e.g. [1,1,2,3] -> "1:3", not "1,1:3").
+        list = Array.from(new Set(list)).sort((a, b) => a - b);
 
         let last = list[list.length - 1];
         let result = [[last]];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.3.4",
+    "version": "1.3.6",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",
@@ -30,7 +30,7 @@
         "@eslint/js": "10.0.1",
         "@types/node": "25.9.1",
         "c8": "11.0.0",
-        "eslint": "10.4.0",
+        "eslint": "10.4.1",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "10.1.8",
         "grunt": "1.6.2",

package/test/commands-integration-test.js

@@ -582,6 +582,51 @@ module.exports['Commands: store remove flags'] = async test => {
     test.done();
 };
 
+module.exports['Commands: store remove keeps a flag not in permanentFlags'] = async test => {
+    // Mailbox permits only \Seen (no \*), so \Custom is not a permanent flag. Removal must still be
+    // sent: a flag does not need to be permitted to be removed. Regression guard — the check used
+    // to test the rewritten wire-form operation instead of options.operation and dropped the flag.
+    let execArgs = null;
+    const connection = createMockConnection({
+        state: 3,
+        mailbox: { permanentFlags: new Set(['\\Seen']) },
+        exec: async (cmd, attrs) => {
+            execArgs = { cmd, attrs };
+            return { next: () => {} };
+        }
+    });
+
+    const result = await storeCommand(connection, '1:10', ['\\Custom'], { operation: 'remove' });
+    test.equal(result, true);
+    test.ok(execArgs, 'a STORE command should be issued');
+    test.equal(execArgs.attrs[1].value, '-FLAGS');
+    test.deepEqual(
+        execArgs.attrs[2].map(flag => flag.value),
+        ['\\Custom'],
+        'the removed flag must be present in the command'
+    );
+    test.done();
+};
+
+module.exports['Commands: store add drops a flag not in permanentFlags'] = async test => {
+    // Control for the regression above: the permanentFlags guard must still apply to non-remove
+    // operations. Adding a flag the mailbox does not permit yields no command and a false result.
+    let execCalled = false;
+    const connection = createMockConnection({
+        state: 3,
+        mailbox: { permanentFlags: new Set(['\\Seen']) },
+        exec: async () => {
+            execCalled = true;
+            return { next: () => {} };
+        }
+    });
+
+    const result = await storeCommand(connection, '1:10', ['\\Custom'], { operation: 'add' });
+    test.equal(result, false, 'adding a non-permitted flag should fail');
+    test.equal(execCalled, false, 'no STORE command should be issued');
+    test.done();
+};
+
 module.exports['Commands: store set flags'] = async test => {
     let execArgs = null;
     const connection = createMockConnection({