imapflow 1.3.5 → 1.3.6

package/.github/codeql/codeql-config.yml

@@ -0,0 +1,12 @@
+name: "ImapFlow CodeQL config"
+
+# Exclude code that is not part of the published library runtime from analysis.
+# These paths generate only false-positive noise:
+#   - test fixtures intentionally feed malformed/hostile input and exercise
+#     edge cases that are not representative of production usage
+#   - the example scripts hardcode demo credentials and connection details for
+#     local experimentation and are not maintained as production code
+paths-ignore:
+    - test
+    - '**/test/**'
+    - examples

package/.github/workflows/codeql.yml

@@ -0,0 +1,102 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+  schedule:
+    - cron: '40 17 * * 6'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: javascript-typescript
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        config-file: ./.github/codeql/codeql-config.yml
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

package/.github/workflows/stale.yml

@@ -3,6 +3,11 @@ on:
     schedule:
         - cron: '30 1 * * *'
 
+permissions:
+    contents: read
+    issues: write
+    pull-requests: write
+
 jobs:
     stale:
         runs-on: ubuntu-latest

package/.github/workflows/test.yml

@@ -4,6 +4,9 @@ on:
     push:
     pull_request:
 
+permissions:
+    contents: read
+
 jobs:
     test:
         strategy:

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.3.5"
+    ".": "1.3.6"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.3.6](https://github.com/postalsys/imapflow/compare/v1.3.5...v1.3.6) (2026-06-05)
+
+
+### Bug Fixes
+
+* harden STARTTLS upgrade, literal bounds, and connection error paths ([35eca81](https://github.com/postalsys/imapflow/commit/35eca81075401e89f0b3aca84e26c41710a62c28))
+
 ## [1.3.5](https://github.com/postalsys/imapflow/compare/v1.3.4...v1.3.5) (2026-06-01)
 
 

package/lib/commands/starttls.js

@@ -15,6 +15,9 @@ module.exports = async connection => {
     let response;
     try {
         response = await connection.exec('STARTTLS');
+        // Whether the server sent anything after the STARTTLS OK and before the TLS
+        // handshake. upgradeToSTARTTLS() uses this to reject a plaintext injection.
+        connection._starttlsHadTrailingData = !!(response && response.hasTrailingData);
         response.next();
         return true;
     } catch (err) {

package/lib/handler/imap-stream.js

@@ -43,6 +43,9 @@ class ImapStream extends Transform {
      *   line (a response without a literal). Defaults to MAX_LITERAL_SIZE (1GB). Guards against a
      *   malicious or broken server that never sends a line terminator, which would otherwise grow
      *   the internal line buffer without bound.
+     * @param {number} [options.maxLiteralSize] - Maximum allowed size (in bytes) of a single
+     *   literal block. Defaults to MAX_LITERAL_SIZE (1GB). Lower it to bound peak memory
+     *   allocation against a malicious or broken server announcing an oversized literal.
      */
     constructor(options) {
         super({
@@ -65,8 +68,16 @@ class ImapStream extends Transform {
         this.readBytesCounter = 0;
 
         // Maximum length of a single line (response without a literal). Bounds the line buffer
-        // so a server that never sends a line terminator cannot exhaust memory.
-        this.maxLineLength = this.options.maxLineLength || MAX_LINE_SIZE;
+        // so a server that never sends a line terminator cannot exhaust memory. A non-negative
+        // integer is honored as-is (including 0); anything else falls back to the default, so an
+        // explicit 0 is not silently swallowed into the 1GB default the way `|| MAX_LINE_SIZE` was.
+        this.maxLineLength = Number.isInteger(this.options.maxLineLength) && this.options.maxLineLength >= 0 ? this.options.maxLineLength : MAX_LINE_SIZE;
+
+        // Maximum size of a single literal block. Bounds peak memory allocation so a server
+        // announcing an oversized literal cannot exhaust memory. As above, a non-negative integer
+        // (including an explicit 0, meaning "reject all non-empty literals") is honored as-is.
+        this.maxLiteralSize =
+            Number.isInteger(this.options.maxLiteralSize) && this.options.maxLiteralSize >= 0 ? this.options.maxLiteralSize : MAX_LITERAL_SIZE;
 
         this.state = LINE;
         this.literalWaiting = 0;
@@ -125,11 +136,11 @@ class ImapStream extends Transform {
             if (c === CURLY_OPEN && numBytes.length) {
                 const literalSize = Number(Buffer.from(numBytes).toString());
 
-                if (literalSize > MAX_LITERAL_SIZE) {
-                    const err = new Error(`Literal size ${literalSize} exceeds maximum allowed size of ${MAX_LITERAL_SIZE} bytes`);
+                if (literalSize > this.maxLiteralSize) {
+                    const err = new Error(`Literal size ${literalSize} exceeds maximum allowed size of ${this.maxLiteralSize} bytes`);
                     err.code = 'LiteralTooLarge';
                     err.literalSize = literalSize;
-                    err.maxSize = MAX_LITERAL_SIZE;
+                    err.maxSize = this.maxLiteralSize;
                     this.emit('error', err);
                     return false;
                 }
@@ -197,8 +208,14 @@ class ImapStream extends Transform {
                             }
 
                             if (payload.length) {
+                                // Whether more buffered input already followed this command on the
+                                // wire — more bytes in this chunk or another queued chunk. Captured
+                                // per emitted command (immutable on the pushed object) so a later
+                                // command cannot overwrite it; consumers that care about pipelining
+                                // boundaries can read it from the pushed object.
+                                let trailingAfterLine = lineStart < chunk.length || this.inputQueue.length > 0;
                                 await new Promise(resolve => {
-                                    this.push({ payload, literals, next: resolve });
+                                    this.push({ payload, literals, next: resolve, trailingAfterLine });
                                 });
                             }
                         }

package/lib/imap-flow.d.ts

@@ -66,6 +66,11 @@ export interface ImapFlowOptions {
      * 1GB.
      */
     maxLineLength?: number;
+    /**
+     * Maximum allowed size in bytes of a single IMAP literal block. Bounds peak memory allocation
+     * against a malicious or broken server announcing an oversized literal. Defaults to 1GB.
+     */
+    maxLiteralSize?: number;
     /**
      * Threshold in milliseconds for warning that a mailbox lock has been held
      * for a long time (diagnostic for forgotten release() calls). Defaults to

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);
     }
@@ -689,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;
             }
@@ -725,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':
@@ -796,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;
+                                }
                             }
                         }
 
@@ -1013,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.
@@ -1139,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(
                 {
@@ -1231,20 +1345,29 @@ 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);
                 } 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) {
@@ -1692,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);
 
@@ -1802,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.
      *
@@ -1819,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;
 
@@ -1829,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.
@@ -1865,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

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

@@ -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')

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.3.5",
+    "version": "1.3.6",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",

package/test/connection-edge-cases-test.js

@@ -2,6 +2,7 @@
 
 const { ImapFlow } = require('../lib/imap-flow');
 const { EventEmitter } = require('events');
+const net = require('net');
 
 // Edge Cases Tests
 
@@ -1539,7 +1540,14 @@ async function setupCompressedClient() {
     mockSocket.destroy = () => {};
     mockSocket.destroyed = false;
     client.socket = mockSocket;
-    client.streamer = new EventEmitter();
+    // Mock streamer that tracks destruction like a real stream, so close() drives it into
+    // the destroyed state the post-close guards actually check.
+    client.streamer = Object.assign(new EventEmitter(), {
+        destroyed: false,
+        destroy() {
+            this.destroyed = true;
+        }
+    });
 
     client.run = async command => {
         if (command === 'COMPRESS') {
@@ -1630,6 +1638,33 @@ module.exports['Connection Edge: compress _deflate error after close does not cr
     test.done();
 };
 
+module.exports['Connection Edge: compress _inflate error after close does not crash'] = async test => {
+    let { client } = await setupCompressedClient();
+
+    let inflate = client._inflate;
+
+    // close() removes the streamer 'error' listener and destroys the streamer.
+    // A late inflate error must not be forwarded into the destroyed streamer
+    // (which would throw an unhandled 'error' and crash the process).
+    client.close();
+
+    // Confirm we actually reached the post-close state the guard targets.
+    test.ok(client.streamer.destroyed, 'streamer is destroyed after close()');
+
+    // Re-attach an 'error' listener so listenerCount('error') > 0: this isolates the
+    // `!streamer.destroyed` term of the guard. If forwarding still happened, this listener
+    // would throw and escape doesNotThrow — proving the destroyed-check is what suppresses it.
+    client.streamer.on('error', () => {
+        throw new Error('inflate error must not be forwarded into a destroyed streamer');
+    });
+
+    test.doesNotThrow(() => {
+        inflate.emit('error', new Error('late inflate error'));
+    });
+
+    test.done();
+};
+
 // ============================================
 // Mailbox Lock Tests
 // ============================================
@@ -1723,3 +1758,105 @@ module.exports['Connection Edge: multiple locks rejected when no connection'] =
     }
     test.done();
 };
+
+// ============================================
+// reader() survives a write() throw without stalling the stream
+// ============================================
+
+module.exports['Connection Edge: reader survives write throw on + continuation'] = async test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        port: 993,
+        auth: { user: 'test', pass: 'test' },
+        logger: false
+    });
+
+    client.currentRequest = false;
+    client.commandParts = [Buffer.from('literal-bytes')];
+
+    let writeAttempted = false;
+    client.write = () => {
+        writeAttempted = true;
+        throw new Error('write boom');
+    };
+
+    let nextCalled = false;
+    let done = false;
+    client.streamer.read = () => {
+        if (done) {
+            return null;
+        }
+        done = true;
+        return {
+            payload: Buffer.from('+ Ready'),
+            literals: [],
+            next: () => {
+                nextCalled = true;
+            }
+        };
+    };
+
+    let rejected = false;
+    await client.reader().catch(() => {
+        rejected = true;
+    });
+
+    test.ok(writeAttempted, 'the literal-continuation write path was exercised');
+    test.equal(rejected, false, 'reader did not reject on write throw');
+    test.ok(nextCalled, 'data.next() was still called so the stream is not stalled');
+    test.done();
+};
+
+// ============================================
+// BYE greeting surfaces its reason on the connect rejection
+// ============================================
+
+module.exports['Connection Edge: BYE greeting surfaces reason on connect rejection'] = async test => {
+    // Deterministic ordering: the server ends the socket only AFTER the client has parsed the
+    // BYE and set byeReason, instead of racing a fixed 50ms timer that could flake on slow CI.
+    let signalByeParsed;
+    let byeParsed = new Promise(resolve => {
+        signalByeParsed = resolve;
+    });
+
+    let server = net.createServer(socket => {
+        socket.on('error', () => {});
+        socket.write('* BYE Server too busy\r\n');
+        byeParsed.then(() => socket.end());
+    });
+
+    await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+    let port = server.address().port;
+
+    let client = new ImapFlow({
+        host: '127.0.0.1',
+        port,
+        secure: false,
+        disableAutoIdle: true,
+        logger: false,
+        auth: { user: 'test', pass: 'test' }
+    });
+    client.on('error', () => {});
+
+    // Signal once the client's BYE handler has run, so byeReason is guaranteed set before close().
+    let origServerBye = client.serverBye.bind(client);
+    client.serverBye = async parsed => {
+        await origServerBye(parsed);
+        signalByeParsed();
+    };
+
+    let connectErr = null;
+    try {
+        await client.connect();
+        test.ok(false, 'connect() should reject after a BYE greeting');
+    } catch (err) {
+        connectErr = err;
+    }
+
+    test.ok(connectErr, 'connect() rejected');
+    test.equal(connectErr.reason, 'Server too busy', 'BYE reason surfaced on the rejection');
+
+    client.close();
+    server.close();
+    test.done();
+};

package/test/imap-stream-edge-cases-test.js

@@ -131,6 +131,64 @@ module.exports['LiteralTooLarge error'] = test => {
     stream.write(Buffer.from('A APPEND {1073741825}\r\n'));
 };
 
+module.exports['LiteralTooLarge error honors configured maxLiteralSize'] = test => {
+    const cap = 1024; // 1KB cap
+    const stream = new ImapStream({ cid: 'test', maxLiteralSize: cap });
+
+    stream.on('error', err => {
+        test.equal(err.code, 'LiteralTooLarge', 'error code should be LiteralTooLarge');
+        test.equal(err.maxSize, cap, 'maxSize should reflect the configured cap');
+        test.equal(err.literalSize, 2048, 'literalSize should be the offending value');
+        stream.destroy();
+        test.done();
+    });
+
+    stream.write(Buffer.from('A APPEND {2048}\r\n'));
+};
+
+module.exports['maxLiteralSize: 0 is honored (not swallowed into the default)'] = test => {
+    // Regression: `this.options.maxLiteralSize || MAX_LITERAL_SIZE` turned an explicit 0 into
+    // the 1GB default. An explicit 0 must mean "reject any non-empty literal".
+    test.expect(2);
+
+    const stream = new ImapStream({ cid: 'test', maxLiteralSize: 0 });
+    test.equal(stream.maxLiteralSize, 0, 'an explicit 0 cap is preserved, not replaced by the default');
+
+    stream.on('error', err => {
+        test.equal(err.code, 'LiteralTooLarge', 'a 1-byte literal exceeds the 0 cap');
+        stream.destroy();
+        test.done();
+    });
+
+    stream.write(Buffer.from('A APPEND {1}\r\n'));
+};
+
+module.exports['Literal within configured maxLiteralSize parses cleanly'] = test => {
+    // Require both literal assertions to actually run: 'end' fires even if the parser never
+    // emits the command, so without expect() a dropped-literal regression would pass green.
+    test.expect(2);
+
+    const stream = new ImapStream({ cid: 'test', maxLiteralSize: 1024 });
+    const literal = Buffer.alloc(512, 0x61); // 512 * 'a'
+
+    stream.on('readable', () => {
+        let cmd;
+        while ((cmd = stream.read()) !== null) {
+            test.equal(cmd.literals.length, 1, 'should have one literal');
+            test.equal(cmd.literals[0].length, 512, 'literal length should be 512');
+            cmd.next();
+        }
+    });
+
+    stream.on('error', err => test.ifError(err));
+
+    stream.on('end', () => test.done());
+
+    stream.write(Buffer.from('A APPEND {512}\r\n'));
+    stream.write(literal);
+    stream.end(Buffer.from('\r\n'));
+};
+
 module.exports['Incomplete line continued in next chunk'] = test => {
     runStreamTest(
         test,

package/test/proxy-connection-test.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const proxyquire = require('proxyquire').noCallThru();
+const { EventEmitter } = require('events');
 
 // Mock socket object
 const createMockSocket = () => ({
@@ -10,6 +11,16 @@ const createMockSocket = () => ({
     destroy: () => {}
 });
 
+// Real EventEmitter-backed mock socket, for tests that need listener tracking / emit.
+const createMockEmitterSocket = () => Object.assign(new EventEmitter(), { write() {}, end() {}, destroy() {} });
+
+// Asserts proxyConnection returned the socket and guarded it with an error listener.
+const assertEarlyErrorHandler = (test, socket, mockSocket) => {
+    test.equal(socket, mockSocket);
+    test.ok(socket.listenerCount('error') >= 1, 'proxy socket carries an error listener before being returned');
+    test.doesNotThrow(() => socket.emit('error', new Error('early proxy error')), 'an early proxy socket error does not throw');
+};
+
 // Mock logger
 const createMockLogger = () => {
     const logs = { info: [], error: [] };
@@ -539,3 +550,78 @@ module.exports['Proxy Connection: SOCKS with username only'] = async test => {
     await proxyConnection(logger, 'socks5://testuser@proxy.example.com:1080', '192.168.1.1', 993);
     test.done();
 };
+
+// ============================================
+// Early error handler (no unhandled 'error' before ImapFlow takes over)
+// ============================================
+
+module.exports['Proxy Connection: HTTP socket has early error handler before return'] = async test => {
+    const mockSocket = createMockEmitterSocket();
+    const logger = createMockLogger();
+
+    const { proxyConnection } = proxyquire('../lib/proxy-connection', {
+        'nodemailer/lib/smtp-connection/http-proxy-client': (url, port, host, cb) => {
+            cb(null, mockSocket);
+        },
+        socks: { SocksClient: {} },
+        dns: { promises: { resolve: async () => ['127.0.0.1'] } },
+        net: { isIP: () => true }
+    });
+
+    const socket = await proxyConnection(logger, 'http://proxy.example.com:8080', '192.168.1.1', 993);
+
+    assertEarlyErrorHandler(test, socket, mockSocket);
+    test.done();
+};
+
+module.exports['Proxy Connection: SOCKS socket has early error handler before return'] = async test => {
+    const mockSocket = createMockEmitterSocket();
+    const logger = createMockLogger();
+
+    const { proxyConnection } = proxyquire('../lib/proxy-connection', {
+        'nodemailer/lib/smtp-connection/http-proxy-client': () => {},
+        socks: {
+            SocksClient: {
+                createConnection: async () => ({ socket: mockSocket })
+            }
+        },
+        dns: { promises: { resolve: async () => ['127.0.0.1'] } },
+        net: { isIP: () => true }
+    });
+
+    const socket = await proxyConnection(logger, 'socks5://proxy.example.com:1080', '192.168.1.1', 993);
+
+    assertEarlyErrorHandler(test, socket, mockSocket);
+    test.done();
+};
+
+// detachEarlyErrorHandler must remove the guard once the caller takes ownership of the socket,
+// so it no longer swallows/logs errors meant for the new owner's handlers.
+module.exports['Proxy Connection: detachEarlyErrorHandler removes the early guard'] = async test => {
+    const mockSocket = createMockEmitterSocket();
+    const logger = createMockLogger();
+
+    const { proxyConnection, detachEarlyErrorHandler } = proxyquire('../lib/proxy-connection', {
+        'nodemailer/lib/smtp-connection/http-proxy-client': (url, port, host, cb) => {
+            cb(null, mockSocket);
+        },
+        socks: { SocksClient: {} },
+        dns: { promises: { resolve: async () => ['127.0.0.1'] } },
+        net: { isIP: () => true }
+    });
+
+    const socket = await proxyConnection(logger, 'http://proxy.example.com:8080', '192.168.1.1', 993);
+    test.ok(socket.listenerCount('error') >= 1, 'early error handler attached on return');
+    test.ok(typeof socket._earlyErrorHandler === 'function', 'handler reference stored on the socket');
+
+    detachEarlyErrorHandler(socket);
+
+    test.equal(socket.listenerCount('error'), 0, 'early error handler removed after detach');
+    test.equal(socket._earlyErrorHandler, null, 'stored handler reference cleared');
+
+    // Detaching again (or on a bare socket) must be a safe no-op.
+    test.doesNotThrow(() => detachEarlyErrorHandler(socket));
+    test.doesNotThrow(() => detachEarlyErrorHandler(createMockEmitterSocket()));
+
+    test.done();
+};

package/test/reliability-improvements-test.js

@@ -368,3 +368,91 @@ module.exports['Reliability: decoder emit(error) does not crash when user has no
 
     test.done();
 };
+
+// ============================================================================
+// Throttle back-off timer is tracked and abortable on close()
+// ============================================================================
+
+// Feed a single throttling BAD response into reader() once, then null.
+const stubThrottleResponse = (client, backoffMs) => {
+    let request = { tag: 'A001', command: 'FETCH', resolve: () => {}, reject: () => {} };
+    client.requestTagMap = new Map([['A001', request]]);
+
+    let done = false;
+    client.streamer.read = () => {
+        if (done) {
+            return null;
+        }
+        done = true;
+        return {
+            payload: Buffer.from(`A001 BAD Request is throttled. Suggested Backoff Time: ${backoffMs} milliseconds`),
+            literals: [],
+            next: () => {}
+        };
+    };
+
+    return request;
+};
+
+module.exports['Reliability: throttle back-off aborts promptly on close()'] = async test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        port: 993,
+        auth: { user: 'test', pass: 'test' },
+        logger: false
+    });
+    client.socket = { destroyed: false, destroy: () => {} };
+    client.writeSocket = client.socket;
+
+    let rejected = null;
+    let request = stubThrottleResponse(client, 300000); // 5 min back-off
+    request.reject = err => {
+        rejected = err;
+    };
+
+    let start = Date.now();
+    let readerDone = client.reader().catch(() => {});
+
+    // Let reader() reach the (tracked) back-off wait.
+    await new Promise(r => setTimeout(r, 50));
+    test.ok(client._throttleTimer, 'back-off timer is tracked while waiting');
+
+    client.close();
+    await new Promise(r => setImmediate(r));
+
+    test.ok(rejected, 'request rejected promptly after close()');
+    test.equal(rejected.code, 'NoConnection', 'rejected with connection error, not ETHROTTLE');
+    test.equal(client._throttleTimer, null, 'throttle timer cleared on close()');
+    test.ok(Date.now() - start < 5000, 'settled well under the 5-minute cap');
+
+    await readerDone;
+    test.done();
+};
+
+module.exports['Reliability: throttle back-off still rejects ETHROTTLE on normal expiry'] = async test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        port: 993,
+        auth: { user: 'test', pass: 'test' },
+        logger: false
+    });
+
+    let rejected = null;
+    let request = stubThrottleResponse(client, 50); // 50ms back-off
+    request.reject = err => {
+        rejected = err;
+    };
+
+    let readerDone = client.reader().catch(() => {});
+
+    await new Promise(r => setTimeout(r, 250));
+
+    test.ok(rejected, 'request rejected after the back-off elapses');
+    test.equal(rejected.code, 'ETHROTTLE', 'normal expiry still rejects ETHROTTLE');
+    test.equal(rejected.throttleReset, 50, 'throttleReset preserved');
+    test.equal(client._throttleTimer, null, 'throttle timer cleared after normal expiry');
+
+    await readerDone;
+    client.close();
+    test.done();
+};

package/test/starttls-injection-test.js

@@ -0,0 +1,181 @@
+'use strict';
+
+const net = require('net');
+const { ImapFlow } = require('../lib/imap-flow');
+const { ImapStream } = require('../lib/handler/imap-stream');
+
+// Minimal pre-STARTTLS IMAP server. Sends the greeting, advertises STARTTLS, and on the
+// STARTTLS command invokes `onStartTls(socket, tag)` so each test controls what (if
+// anything) is written after the tagged OK. It never performs a real TLS handshake.
+const createStartTlsServer = onStartTls =>
+    net.createServer(socket => {
+        socket.on('error', () => {});
+        socket.write('* OK [CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED] ready\r\n');
+
+        let buf = '';
+        socket.on('data', data => {
+            buf += data.toString('binary');
+            let idx;
+            while ((idx = buf.indexOf('\r\n')) >= 0) {
+                let line = buf.slice(0, idx);
+                buf = buf.slice(idx + 2);
+                let parts = line.split(' ');
+                let tag = parts[0];
+                let command = (parts[1] || '').toUpperCase();
+                if (command === 'CAPABILITY') {
+                    socket.write('* CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED\r\n');
+                    socket.write(`${tag} OK CAPABILITY done\r\n`);
+                } else if (command === 'STARTTLS') {
+                    onStartTls(socket, tag);
+                }
+            }
+        });
+    });
+
+const makeClient = port =>
+    new ImapFlow({
+        host: '127.0.0.1',
+        port,
+        secure: false,
+        doSTARTTLS: true,
+        servername: 'localhost',
+        tls: { rejectUnauthorized: false },
+        disableAutoIdle: true,
+        logger: false,
+        auth: { user: 'test', pass: 'test' }
+    });
+
+// A MITM injects a response in the SAME segment as the STARTTLS OK, before the handshake.
+// This is caught by the parser-level trailing-data flag (Check 1 in upgradeToSTARTTLS).
+// Injection that instead arrives after the OK in a separate segment is caught by the
+// socket-level read after unpipe (Check 2) or, failing that, by TLS handshake corruption;
+// those fragmented cases are timing-dependent and not asserted deterministically here.
+module.exports['STARTTLS: rejects same-segment plaintext injection'] = async test => {
+    let server = createStartTlsServer((socket, tag) => {
+        // OK and an injected untagged CAPABILITY in a single write, no TLS handshake.
+        socket.write(`${tag} OK Begin TLS\r\n* CAPABILITY IMAP4rev1 INJECTED\r\n`);
+    });
+
+    await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+    let port = server.address().port;
+
+    let client = makeClient(port);
+    client.on('error', () => {});
+
+    let connectErr = null;
+    try {
+        await client.connect();
+        test.ok(false, 'connect() must reject when data is injected after the STARTTLS OK');
+    } catch (err) {
+        connectErr = err;
+    }
+
+    test.ok(connectErr, 'connect() rejected');
+    test.equal(connectErr.code, 'STARTTLS_INJECTION', 'rejection is flagged as an injection');
+    test.ok(connectErr.tlsFailed, 'rejection is treated as a TLS failure');
+    // The connection must fail closed: it never becomes usable and never authenticates.
+    // (The injected untagged response may be parsed transiently before teardown, so asserting
+    // it never reaches the capability set would be a timing-fragile false assurance.)
+    test.ok(!client.usable, 'the connection did not become usable (failed closed)');
+    test.ok(!client.authenticated, 'the connection never authenticated');
+
+    client.close();
+    server.close();
+    test.done();
+};
+
+// A compliant server stays silent after the STARTTLS OK. The injection guard must NOT
+// fire (no false positive); the upgrade proceeds to the TLS handshake, which then fails
+// here only because this stub server never speaks TLS — proving the guard let it through.
+module.exports['STARTTLS: clean OK is not flagged as injection'] = async test => {
+    let server = createStartTlsServer((socket, tag) => {
+        // Only the tagged OK, nothing after it, then drop the connection.
+        socket.write(`${tag} OK Begin TLS\r\n`);
+        setImmediate(() => socket.destroy());
+    });
+
+    await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+    let port = server.address().port;
+
+    let client = makeClient(port);
+    client.on('error', () => {});
+
+    let connectErr = null;
+    try {
+        await client.connect();
+        test.ok(false, 'connect() rejects because the stub never completes the TLS handshake');
+    } catch (err) {
+        connectErr = err;
+    }
+
+    test.ok(connectErr, 'connect() rejected (no TLS handshake on the stub server)');
+    test.notEqual(connectErr.code, 'STARTTLS_INJECTION', 'a clean OK must not be flagged as injection');
+
+    client.close();
+    server.close();
+    test.done();
+};
+
+// A STARTTLS handshake failure must reject connect() through a single error path: it must
+// not also emit an 'error' event (which would double-report and crash a listener-less client).
+module.exports['STARTTLS: handshake failure has a single error path'] = async test => {
+    let server = createStartTlsServer((socket, tag) => {
+        // Acknowledge STARTTLS, then drop the connection instead of doing TLS.
+        socket.write(`${tag} OK Begin TLS\r\n`);
+        setImmediate(() => socket.destroy());
+    });
+
+    await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+    let port = server.address().port;
+
+    let client = makeClient(port);
+
+    // A second error path would emit here (and crash a listener-less client).
+    let errorEvents = 0;
+    client.on('error', () => {
+        errorEvents++;
+    });
+
+    let connectErr = null;
+    try {
+        await client.connect();
+        test.ok(false, 'connect() should reject on STARTTLS handshake failure');
+    } catch (err) {
+        connectErr = err;
+    }
+
+    // Give any stray async error handler a chance to (wrongly) fire.
+    await new Promise(r => setTimeout(r, 50));
+
+    test.ok(connectErr, 'connect() rejected');
+    test.ok(connectErr.tlsFailed, 'rejection is flagged as a TLS failure');
+    test.equal(errorEvents, 0, 'no duplicate error event emitted (single error path)');
+
+    client.close();
+    server.close();
+    test.done();
+};
+
+// Unit-level check of the per-command trailing flag the guard relies on: each pushed
+// command records whether more input followed it, independently of later commands.
+module.exports['STARTTLS: parser flags trailing data per command'] = test => {
+    const stream = new ImapStream({ cid: 'test' });
+    let flags = [];
+
+    stream.on('readable', () => {
+        let cmd;
+        while ((cmd = stream.read()) !== null) {
+            flags.push(cmd.trailingAfterLine);
+            cmd.next();
+        }
+    });
+    stream.on('error', err => test.ifError(err));
+    stream.on('end', () => {
+        // First command had a second command after it -> true; the last one -> false.
+        test.deepEqual(flags, [true, false], 'trailingAfterLine is per-command and not overwritten');
+        test.done();
+    });
+
+    // Two complete commands in a single write.
+    stream.end(Buffer.from('A OK first\r\nB OK second\r\n'));
+};