imapflow 1.3.6 → 1.3.7

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.3.7](https://github.com/postalsys/imapflow/compare/v1.3.6...v1.3.7) (2026-06-08)
+
+
+### Bug Fixes
+
+* harden FLAGS guard and bring lib to full test coverage ([6666bec](https://github.com/postalsys/imapflow/commit/6666bec7f82072e5aa8a1e63736e35d5c6644d4c))
+
 ## [1.3.6](https://github.com/postalsys/imapflow/compare/v1.3.5...v1.3.6) (2026-06-05)
 
 

package/lib/commands/authenticate.js

@@ -7,7 +7,7 @@ const { getStatusCode, getErrorText } = require('../tools.js');
  *
  * @param {Error} err - The original authentication error
  * @param {Object} [errorResponse] - Optional OAuth error response from the server
- * @throws {Error} Always throws the enriched error
+ * @returns {Error} The enriched error; the caller is expected to throw it
  */
 async function handleAuthError(err, errorResponse) {
     let errorCode = getStatusCode(err.response);
@@ -19,7 +19,7 @@ async function handleAuthError(err, errorResponse) {
     if (errorResponse) {
         err.oauthError = errorResponse;
     }
-    throw err;
+    return err;
 }
 
 /**
@@ -84,7 +84,7 @@ async function authOauth(connection, username, accessToken) {
 
         return username;
     } catch (err) {
-        await handleAuthError(err, errorResponse);
+        throw await handleAuthError(err, errorResponse);
     }
 }
 
@@ -132,7 +132,7 @@ async function authLogin(connection, username, password) {
 
         return username;
     } catch (err) {
-        await handleAuthError(err, errorResponse);
+        throw await handleAuthError(err, errorResponse);
     }
 }
 
@@ -169,7 +169,7 @@ async function authPlain(connection, username, password, authzid) {
         // Return the identity we're authorized as (authzid if provided, otherwise username)
         return authzid || username;
     } catch (err) {
-        await handleAuthError(err, errorResponse);
+        throw await handleAuthError(err, errorResponse);
     }
 }
 

package/lib/commands/fetch.js

@@ -41,6 +41,7 @@ module.exports = async (connection, range, query, options) => {
 
         let response;
         try {
+            /* c8 ignore next */ // range is guaranteed truthy by the early-return guard above, so the '*' fallback is unreachable
             let attributes = [{ type: 'SEQUENCE', value: (range || '*').toString() }];
 
             let queryStructure = [];

package/lib/commands/logout.js

@@ -30,6 +30,7 @@ module.exports = async connection => {
         }
         connection.log.warn({ err, cid: connection.id });
         return false;
+        /* c8 ignore next */ // the catch above is exhaustive (never re-throws), so finally is only ever reached via normal completion
     } finally {
         // Set state to LOGOUT before closing to prevent any further commands from
         // being queued. The socket is closed unconditionally in this finally block

package/lib/commands/select.js

@@ -70,6 +70,7 @@ module.exports = async (connection, path, options) => {
         // send as quoted STRING to avoid parser issues with the ampersand.
         let selectCommand = {
             command: !options.readOnly ? 'SELECT' : 'EXAMINE',
+            /* c8 ignore next */ // extraArgs is always initialised to an array, so the [] fallback is unreachable
             arguments: [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }].concat(extraArgs || [])
         };
 
@@ -164,7 +165,7 @@ module.exports = async (connection, path, options) => {
                 // Untagged FLAGS response lists all flags defined for this mailbox
                 // (both system flags and custom flags). Example: * FLAGS (\Seen \Answered \Flagged)
                 FLAGS: async untagged => {
-                    if (!untagged.attributes || (!untagged.attributes.length && Array.isArray(untagged.attributes[0]))) {
+                    if (!untagged.attributes || !untagged.attributes.length || !Array.isArray(untagged.attributes[0])) {
                         return;
                     }
                     let flags = untagged.attributes[0].map(flag => (typeof flag.value === 'string' ? flag.value : false)).filter(flag => flag);

package/lib/commands/store.js

@@ -22,6 +22,7 @@ module.exports = async (connection, range, flags, options) => {
         return false;
     }
 
+    /* c8 ignore next */ // options.useLabels is dereferenced in the guard above, so options is always defined here
     options = options || {};
 
     // Build the IMAP STORE operation name. The format is:

package/lib/handler/token-parser.js

@@ -10,7 +10,6 @@ const STATE_NORMAL = 0x003;
 const STATE_PARTIAL = 0x004;
 const STATE_SEQUENCE = 0x005;
 const STATE_STRING = 0x006;
-const STATE_TEXT = 0x007;
 
 const RE_DIGITS = /^\d+$/;
 const RE_SINGLE_DIGIT = /^\d$/;
@@ -706,10 +705,6 @@ class TokenParser {
 
                     this.currentNode.value += chr;
                     break;
-
-                case STATE_TEXT:
-                    this.currentNode.value += chr;
-                    break;
             }
         }
     }

package/lib/imap-flow.js

@@ -576,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 });
@@ -925,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 => {
@@ -1108,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) {
@@ -1119,6 +1115,7 @@ class ImapFlow extends EventEmitter {
                 throw err;
             }
         };
+        /* c8 ignore stop */
 
         Object.defineProperty(this.writeSocket, 'destroyed', {
             get: () => !this.socket || this.socket.destroyed
@@ -1142,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) {
@@ -1156,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);
             }
@@ -1252,6 +1251,7 @@ class ImapFlow extends EventEmitter {
         // 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();
         }
@@ -1270,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);
@@ -1282,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;
@@ -1294,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
@@ -1302,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();
@@ -1317,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.
@@ -1328,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;
@@ -1336,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
                         });
@@ -1356,6 +1366,7 @@ class ImapFlow extends EventEmitter {
 
                     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);
                 }
@@ -1805,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 });
@@ -1825,10 +1837,12 @@ class ImapFlow extends EventEmitter {
 
                     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 });
@@ -1853,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;
                     }
@@ -1866,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);
@@ -1976,6 +1992,7 @@ 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.
@@ -3314,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);
@@ -3444,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;
 
@@ -3452,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 {
@@ -3463,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) {
@@ -3488,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({
@@ -3498,6 +3521,7 @@ class ImapFlow extends EventEmitter {
                             cid: this.id
                         });
                     }
+                    /* c8 ignore stop */
                 })
                 .finally(() => {
                     if (!fetchAborted && stream && !stream.destroyed) {
@@ -3512,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', () => {
@@ -3622,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);
@@ -3761,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
                         });
@@ -3868,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/tools.js

@@ -353,10 +353,12 @@ const tools = {
                     .replace(/<\d+(\.\d+)?>$/, '');
                 continue;
             }
+            /* c8 ignore start */ // defensive: key is always a string produced by the compiler above
             if (typeof key !== 'string') {
                 // should not happen
                 continue;
             }
+            /* c8 ignore stop */
 
             let getString = attribute => {
                 if (!attribute) {
@@ -554,10 +556,12 @@ const tools = {
             if (Buffer.isBuffer(obj.value)) {
                 return obj.value.toString();
             }
+            /* c8 ignore next */ // defensive: envelope tokens are always string/Buffer/NIL, never another type
             return obj.value;
         };
 
         let processAddresses = function (list) {
+                /* c8 ignore next 2 */ // defensive: processAddresses is only called with non-empty arrays, so the [] fallback is unreachable
                 return []
                     .concat(list || [])
                     .map(addr => {
@@ -612,10 +616,12 @@ const tools = {
         }
 
         if (entry[8] && entry[8].value) {
+            /* c8 ignore next */ // the guard ensures getStrValue is truthy here, so the '' fallback is unreachable
             envelope.inReplyTo = (getStrValue(entry[8]) || '').toString().trim();
         }
 
         if (entry[9] && entry[9].value) {
+            /* c8 ignore next */ // the guard ensures getStrValue is truthy here, so the '' fallback is unreachable
             envelope.messageId = (getStrValue(entry[9]) || '').toString().trim();
         }
 
@@ -819,6 +825,7 @@ const tools = {
 
                     // envelope of the encapsulated message
                     if (node[i]) {
+                        /* c8 ignore next */ // node[i] is truthy inside this guard, so the [] fallback is unreachable
                         curNode.envelope = tools.parseEnvelope([].concat(node[i] || []));
                     }
                     i++;
@@ -886,6 +893,7 @@ const tools = {
             // body language
             if (i < node.length - 1) {
                 if (node[i]) {
+                    /* c8 ignore next */ // node[i] is truthy inside this guard, so the [] fallback is unreachable
                     curNode.language = [].concat(node[i] || []).map(val => ((val && val.value) || '').toString().toLowerCase());
                 }
                 i++;

package/package.json

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