imapflow 1.6.3 → 1.6.5

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.6.3"
+    ".": "1.6.5"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.6.5](https://github.com/postalsys/imapflow/compare/v1.6.4...v1.6.5) (2026-07-29)
+
+
+### Bug Fixes
+
+* resolve regressions from the rev2 hardening commit and harden further ([0739df9](https://github.com/postalsys/imapflow/commit/0739df93709d2c7d572e977c2b37b6d219e69e30))
+
+## [1.6.4](https://github.com/postalsys/imapflow/compare/v1.6.3...v1.6.4) (2026-07-29)
+
+
+### Bug Fixes
+
+* block IMAP command injection and harden rev2 protocol handling ([e107292](https://github.com/postalsys/imapflow/commit/e107292bc907b29d94b0d810dc01e9680f820bfa))
+
 ## [1.6.3](https://github.com/postalsys/imapflow/compare/v1.6.2...v1.6.3) (2026-07-28)
 
 

package/lib/commands/compress.js

@@ -19,10 +19,37 @@ module.exports = async connection => {
     let response;
     try {
         response = await connection.exec('COMPRESS', [{ type: 'ATOM', value: 'DEFLATE' }]);
-        response.next();
-        return true;
     } catch (err) {
+        // The server declined (NO/BAD): nothing switched, staying uncompressed is safe.
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
+
+    // Everything after the tagged OK is already deflate-framed (RFC 4978 section 4) -
+    // the server switches at the OK, so declining the upgrade at this point is not a
+    // protocol option. The socket stays piped into the plaintext parser until the
+    // transport swaps in the inflater, so bytes that arrived in the same chunk as the
+    // OK have been consumed as cleartext and are missing from the head of the deflate
+    // stream: the session is unrecoverable in both directions. Fail it immediately
+    // (the same way STARTTLS treats post-OK trailing data) instead of letting it die
+    // slowly on garbage. Closing this window without failing needs the stream to hand
+    // back its unconsumed tail on unpipe so the transport can feed it into the
+    // inflater - not something a command module can reach from here.
+    if (response.hasTrailingData) {
+        let error = new Error('Server sent data between the COMPRESS response and the compression layer switch');
+        error.code = 'COMPRESS_TRAILING_DATA';
+        connection.log.error({ err: error, cid: connection.id });
+        // Schedule the close before releasing parser backpressure, so the buffered
+        // deflate-framed bytes cannot settle anything before teardown begins. This is
+        // why the decision lives here rather than at the connection layer the way the
+        // STARTTLS guard does (starttls.js records a flag, upgradeToSTARTTLS decides):
+        // only the command module holds the response before its backpressure release,
+        // so only it can order teardown ahead of that release.
+        connection.closeAfter();
+        response.next();
+        throw error;
+    }
+
+    response.next();
+    return true;
 };

package/lib/commands/search.js

@@ -27,6 +27,8 @@ const stripEsearchPrefix = attrs => {
  *
  * ALL and PARTIAL.messages are kept as compact sequence-set strings.
  * Use expandRange() from tools.js if you need to expand them.
+ * MODSEQ (RFC 7162, sent when the search used a MODSEQ criterion) is
+ * returned as a BigInt.
  *
  * @param {Array} attrs - Attribute array from the IMAP parser
  * @returns {Object} ESearchResult object
@@ -61,6 +63,14 @@ function parseEsearchResponse(attrs) {
                 if (!isNaN(n)) result.max = n;
                 break;
             }
+            case 'MODSEQ': {
+                // RFC 7162 section 3.1.5: present when the SEARCH used a MODSEQ
+                // criterion on a CONDSTORE-enabled session. BigInt because
+                // mod-sequence values are unsigned 63-bit
+                const value = attrs[++i]?.value;
+                if (typeof value === 'string' && /^\d+$/.test(value)) result.modseq = BigInt(value);
+                break;
+            }
             case 'ALL': {
                 const allToken = attrs[++i];
                 if (allToken && typeof allToken.value === 'string') {

package/lib/handler/imap-compiler.js

@@ -4,31 +4,53 @@
 
 const imapFormalSyntax = require('./imap-formal-syntax');
 
-/**
- * Formats a response entry into a Buffer.
- *
- * @param {string|number|Buffer} entry - The value to convert to a Buffer.
- * @param {boolean} [returnEmpty] - If true, returns null instead of an empty Buffer when the entry is not a recognized type.
- * @returns {Buffer|null} The entry as a Buffer, or null if returnEmpty is true and the entry is not a recognized type.
- */
-const formatRespEntry = (entry, returnEmpty) => {
-    if (typeof entry === 'string') {
-        return Buffer.from(entry);
-    }
+// A single element of a sequence-set as defined by the RFC 9051 grammar: a number
+// or a range, where "*" stands for the largest number in use. Digit strings are not
+// range-checked here (a server rejects "0" or an overlong number on its own); the
+// point of the check is that nothing outside this alphabet can reach the wire.
+const SEQ_RANGE = /^(\d+|\*)(:(\d+|\*))?$/;
+
+// Validates a full sequence-set: comma-separated SEQ_RANGE elements, or "$"
+// (RFC 5182 SEARCHRES), which references the previous SEARCH result and is only
+// valid as the entire set. Split into per-element tests on purpose - a whole-set
+// regex with an unbounded repeat group overflows the regex engine's backtrack
+// stack with an uncoded RangeError on valid sets in the million-element range,
+// while the per-element regex is bounded.
+const isValidSequenceSet = value => value === '$' || value.split(',').every(part => SEQ_RANGE.test(part));
+
+// Numeric tokens may only put the digit alphabet on the wire. Anything that does
+// not round to a bounded non-negative integer (NaN, Infinity, negatives, unsafe
+// magnitudes) degrades to 0 - the fallback the NaN coercion has always used.
+const safeNumber = value => {
+    let num = Math.round(Number(value));
+    return Number.isSafeInteger(num) && num >= 0 ? num : 0;
+};
 
-    if (typeof entry === 'number') {
-        return Buffer.from(entry.toString());
-    }
+// Characters that cannot appear in an IMAP quoted string: CR and LF terminate a
+// command line, and NUL is outside the CHAR production entirely. A value carrying
+// any of them has to be sent as a literal, so quoting it is never correct.
+const NOT_QUOTABLE = /[\r\n\0]/;
 
-    if (Buffer.isBuffer(entry)) {
-        return entry;
-    }
+// A line terminator ends an IMAP command, so no token may carry one to the wire.
+const CRLF = /[\r\n]/;
 
-    if (returnEmpty) {
-        return null;
+/**
+ * Quotes a value as an IMAP quoted string. Only DQUOTE and backslash are escaped -
+ * the IMAP grammar defines no other escape sequence, so JSON-style escaping (which
+ * turns a tab into a literal backslash-t and a control character into \\uXXXX) would
+ * silently change the value the server receives.
+ *
+ * @param {string} value - The value to quote.
+ * @returns {string} The quoted string, ready to be written to the wire.
+ * @throws {Error} If the value contains CR, LF or NUL, which a quoted string cannot carry.
+ */
+const quoteString = value => {
+    if (NOT_QUOTABLE.test(value)) {
+        let error = new Error('Unquotable character in IMAP string value');
+        error.code = 'InvalidStringValue';
+        throw error;
     }
-
-    return Buffer.alloc(0);
+    return '"' + value.replace(/["\\]/g, char => '\\' + char) + '"';
 };
 
 /**
@@ -50,7 +72,43 @@ module.exports = async (response, options) => {
     let { asArray, isLogging, literalPlus, literalMinus } = options || {};
     const respParts = [];
 
-    let resp = [].concat(formatRespEntry(response.tag, true) || []).concat(response.command ? formatRespEntry(' ' + response.command) : []);
+    // Formats an entry (string, number or Buffer) into the Buffer that is written to
+    // the wire, and is the choke point every emission passes through: a line
+    // terminator ends an IMAP command, so no token - the tag and command name
+    // included - may put one on the wire. The literal size marker and literal data
+    // are the only emissions where CRLF is legitimate; those call sites opt out with
+    // `raw`. Never enforced when logging: re-encoding an incoming server response for
+    // the log or for error text must not throw, whatever the server sent. With
+    // `returnEmpty`, an unrecognized entry type yields null instead of an empty
+    // Buffer.
+    const emitEntry = (entry, opts) => {
+        let { returnEmpty, raw } = opts || {};
+        if (!raw && !isLogging && (typeof entry === 'string' || Buffer.isBuffer(entry)) && CRLF.test(entry.toString('latin1'))) {
+            let error = new Error('Line terminator in IMAP token');
+            error.code = 'InvalidTokenValue';
+            throw error;
+        }
+
+        if (typeof entry === 'string') {
+            return Buffer.from(entry);
+        }
+
+        if (typeof entry === 'number') {
+            return Buffer.from(entry.toString());
+        }
+
+        if (Buffer.isBuffer(entry)) {
+            return entry;
+        }
+
+        if (returnEmpty) {
+            return null;
+        }
+
+        return Buffer.alloc(0);
+    };
+
+    let resp = [].concat(emitEntry(response.tag, { returnEmpty: true }) || []).concat(response.command ? emitEntry(' ' + response.command) : []);
     let val;
     let lastType;
 
@@ -75,7 +133,7 @@ module.exports = async (response, options) => {
         // adjacent lists).
         if (lastType === 'LITERAL' || (!['(', '<', '['].includes(lastRespByte) && resp.length)) {
             if (!options.subArray) {
-                resp.push(formatRespEntry(' '));
+                resp.push(emitEntry(' '));
             }
         }
 
@@ -86,7 +144,7 @@ module.exports = async (response, options) => {
 
         if (Array.isArray(node)) {
             lastType = 'LIST';
-            resp.push(formatRespEntry('('));
+            resp.push(emitEntry('('));
 
             // check if we need to skip separator WS between two arrays
             let subArray = node.length > 1 && Array.isArray(node[0]);
@@ -98,40 +156,40 @@ module.exports = async (response, options) => {
                 await walk(child, { subArray });
             }
 
-            resp.push(formatRespEntry(')'));
+            resp.push(emitEntry(')'));
             return;
         }
 
         if (!node && typeof node !== 'string' && typeof node !== 'number' && !Buffer.isBuffer(node)) {
-            resp.push(formatRespEntry('NIL'));
+            resp.push(emitEntry('NIL'));
             return;
         }
 
         if (typeof node === 'string' || Buffer.isBuffer(node)) {
             if (isLogging && node.length > 100) {
-                resp.push(formatRespEntry('"(* ' + node.length + 'B string *)"'));
+                resp.push(emitEntry('"(* ' + node.length + 'B string *)"'));
             } else {
-                resp.push(formatRespEntry(JSON.stringify(node.toString())));
+                resp.push(emitEntry(isLogging ? JSON.stringify(node.toString()) : quoteString(node.toString())));
             }
             return;
         }
 
         if (typeof node === 'number') {
-            resp.push(formatRespEntry(Math.round(node) || 0)); // Only integers allowed
+            resp.push(emitEntry(safeNumber(node))); // Only bounded non-negative integers allowed
             return;
         }
 
         lastType = node.type;
 
         if (isLogging && node.sensitive) {
-            resp.push(formatRespEntry('"(* value hidden *)"'));
+            resp.push(emitEntry('"(* value hidden *)"'));
             return;
         }
 
         switch (node.type.toUpperCase()) {
             case 'LITERAL':
                 if (isLogging) {
-                    resp.push(formatRespEntry('"(* ' + node.value.length + 'B literal *)"'));
+                    resp.push(emitEntry('"(* ' + node.value.length + 'B literal *)"'));
                 } else {
                     // The literal size marker counts octets - string values are written as
                     // UTF-8, so their UTF-16 .length would undercount multi-byte characters
@@ -147,40 +205,77 @@ module.exports = async (response, options) => {
                     let canAppend = !asArray || usePlus;
 
                     // Emit the literal header: optional '~' prefix for literal8, then {size[+]}\r\n
-                    resp.push(formatRespEntry(`${node.isLiteral8 ? '~' : ''}{${literalLength}${usePlus ? '+' : ''}}\r\n`));
+                    resp.push(emitEntry(`${node.isLiteral8 ? '~' : ''}{${literalLength}${usePlus ? '+' : ''}}\r\n`, { raw: true }));
 
                     if (canAppend) {
                         // Literal data follows immediately in the same buffer segment
                         if (node.value && node.value.length) {
-                            resp.push(formatRespEntry(node.value));
+                            resp.push(emitEntry(node.value, { raw: true }));
                         }
                     } else {
                         // For synchronizing literals in asArray mode, split output into separate
                         // parts. The caller must send each part and wait for a continuation
                         // response from the server before sending the next.
                         respParts.push(resp);
-                        resp = [].concat(formatRespEntry(node.value, true) || []);
+                        resp = [].concat(emitEntry(node.value, { returnEmpty: true, raw: true }) || []);
                     }
                 }
                 break;
 
             case 'STRING':
                 if (isLogging && node.value.length > 100) {
-                    resp.push(formatRespEntry('"(* ' + node.value.length + 'B string *)"'));
+                    resp.push(emitEntry('"(* ' + node.value.length + 'B string *)"'));
                 } else {
-                    resp.push(formatRespEntry(JSON.stringify((node.value || '').toString())));
+                    val = (node.value || '').toString();
+                    resp.push(emitEntry(isLogging ? JSON.stringify(val) : quoteString(val)));
                 }
                 break;
 
-            case 'TEXT':
             case 'SEQUENCE':
+                // Sequence sets are written verbatim - they are the one token type with
+                // no quoting to fall back on. Callers build them from user-supplied
+                // ranges, so validate here, at the single point every outgoing sequence
+                // set passes through, rather than trusting each command module. Skipped
+                // when logging: the incoming token parser accepts sequence-shaped tokens
+                // this strict grammar rejects (an ESEARCH set like "1:2:3", a folder
+                // name like "12:30:00"), and re-compiling a server response for the log
+                // or for error text must never throw.
+                if (!isLogging && (typeof node.value === 'string' || typeof node.value === 'number' || Buffer.isBuffer(node.value))) {
+                    val = node.value.toString();
+                    if (val && !isValidSequenceSet(val)) {
+                        let error = new Error('Invalid sequence set value');
+                        error.code = 'InvalidSequenceSet';
+                        throw error;
+                    }
+                }
+                if (node.value) {
+                    // raw: the validated alphabet cannot contain a line terminator, and
+                    // re-scanning a potentially multi-megabyte set in the choke point
+                    // would double the cost of exactly the sets this branch exists for
+                    resp.push(emitEntry(node.value, { raw: true }));
+                }
+                break;
+
+            case 'TEXT':
+                // Response text is written verbatim. Only the parser produces it today, for
+                // incoming lines, so this is a re-encoding path rather than a command-building
+                // one. The emitEntry choke point would refuse a line terminator here too;
+                // this check runs first only to raise the more specific InvalidTextValue code.
                 if (node.value) {
-                    resp.push(formatRespEntry(node.value));
+                    if (!isLogging && CRLF.test(node.value.toString())) {
+                        let error = new Error('Line terminator in IMAP text value');
+                        error.code = 'InvalidTextValue';
+                        throw error;
+                    }
+                    resp.push(emitEntry(node.value));
                 }
                 break;
 
             case 'NUMBER':
-                resp.push(formatRespEntry(node.value || 0));
+                // Coerced rather than written through: formatRespEntry passes a string or
+                // Buffer straight to the wire, so a numeric token carrying a string value
+                // would be another verbatim channel
+                resp.push(emitEntry(safeNumber(node.value)));
                 break;
 
             case 'ATOM':
@@ -190,28 +285,33 @@ module.exports = async (response, options) => {
                 if (!node.section || val) {
                     // Verify the value contains only valid ATOM-CHAR characters.
                     // Strip a leading backslash before checking (system flags like \Seen start with '\').
-                    // If any character fails verification, quote-escape the entire value with JSON.stringify.
+                    // If any character fails verification, fall back to an IMAP quoted string
+                    // (JSON.stringify is used only for log output, where values are display-escaped).
                     if (node.value === '' || imapFormalSyntax.verify(val.charAt(0) === '\\' ? val.substr(1) : val, imapFormalSyntax['ATOM-CHAR']()) >= 0) {
-                        val = JSON.stringify(val);
+                        val = isLogging ? JSON.stringify(val) : quoteString(val);
                     }
 
-                    resp.push(formatRespEntry(val));
+                    resp.push(emitEntry(val));
                 }
 
                 // Section bracket handling: emit [section-contents] after the ATOM value
                 // e.g., BODY[HEADER.FIELDS (Subject)] or BODY[1.MIME]
                 if (node.section) {
-                    resp.push(formatRespEntry('['));
+                    resp.push(emitEntry('['));
 
                     for (let child of node.section) {
                         await walk(child);
                     }
 
-                    resp.push(formatRespEntry(']'));
+                    resp.push(emitEntry(']'));
                 }
-                // Partial range: emit <origin.length> after the section brackets
+                // Partial range: emit <origin.length> after the section brackets. Coerced
+                // rather than joined as-is: this is the last token component written
+                // verbatim, and the choke point is only worth relying on if it holds for
+                // all of them. Every producer already passes numbers, so nothing changes
+                // for them.
                 if (node.partial) {
-                    resp.push(formatRespEntry(`<${node.partial.join('.')}>`));
+                    resp.push(emitEntry(`<${node.partial.map(safeNumber).join('.')}>`));
                 }
                 break;
         }

package/lib/handler/imap-parser.js

@@ -81,6 +81,13 @@ module.exports = async (command, options) => {
         if (err.code === 'ParserErrorExchange' && err.parserContext && err.parserContext.value) {
             return err.parserContext.value;
         }
+        if (response.tag) {
+            // The tag had already been parsed when the rest of the line failed. Expose it
+            // so the connection can settle the command this line was addressed to - unlike
+            // re-deriving the tag from the raw bytes, this inherits the leading-NUL
+            // workaround above.
+            err.parsedTag = response.tag;
+        }
         throw err;
     }
 

package/lib/handler/imap-stream.js

@@ -165,16 +165,36 @@ class ImapStream extends Transform {
         pos--;
 
         // Scan backwards through the line to find an IMAP literal marker: {size}\r\n
-        // The format is: '{' followed by one or more ASCII digits followed by '}'
-        let numBytes = [];
+        // The format is: '{' followed by one or more ASCII digits followed by '}'.
+        // Only the digit run's bounds are tracked - a single linear pass, unlike
+        // collecting digits into a growing array, which would make a line of n digits
+        // cost O(n^2). The run length is deliberately not capped: the RFC "number"
+        // production permits leading zeros, so a long digit run can still denote a
+        // small, valid size, and treating the marker as an ordinary line instead
+        // would feed the announced literal body to the line parser and desynchronize
+        // the session.
+        let digitsEnd = pos;
         for (; pos >= 0; pos--) {
             let c = line[pos];
             if (c >= NUM_0 && c <= NUM_9) {
-                numBytes.unshift(c);
                 continue;
             }
-            if (c === CURLY_OPEN && numBytes.length) {
-                const literalSize = Number(Buffer.from(numBytes).toString());
+            if (c === CURLY_OPEN && pos < digitsEnd) {
+                // Skip leading zeros so only the significant digits are converted: a
+                // marker padded with megabytes of zeros must not cost a string
+                // allocation and Number() parse of the whole run.
+                let digitsStart = pos + 1;
+                while (digitsStart < digitsEnd && line[digitsStart] === NUM_0) {
+                    digitsStart++;
+                }
+
+                // More significant digits than any number64 has cannot fit any
+                // permissible maxLiteralSize; fail closed without materializing them
+                if (digitsEnd + 1 - digitsStart > 19) {
+                    return this.failStream(createLiteralTooLargeError(Infinity, this.maxLiteralSize, 'the widest permissible literal size (19 digits)'));
+                }
+
+                const literalSize = Number(line.toString('latin1', digitsStart, digitsEnd + 1));
 
                 if (literalSize > this.maxLiteralSize) {
                     return this.failStream(createLiteralTooLargeError(literalSize, this.maxLiteralSize));

package/lib/handler/parser-instance.js

@@ -77,8 +77,13 @@ class ParserInstance {
                 {
                     let match = this.remainder.match(/^\s+\[/);
                     if (match) {
+                        // Find the ']' that closes the response code. Inner brackets are
+                        // tracked because servers do put bracketed values inside a code
+                        // (e.g. a "[css3-page]" keyword in a PERMANENTFLAGS list), which a
+                        // first-']' scan would cut in half.
                         let nesting = 1;
-                        for (let i = match[0].length; i <= this.remainder.length; i++) {
+                        let end = -1;
+                        for (let i = match[0].length; i < this.remainder.length; i++) {
                             let c = this.remainder[i];
 
                             if (c === '[') {
@@ -87,11 +92,25 @@ class ParserInstance {
                                 nesting--;
                             }
                             if (!nesting) {
-                                this.humanReadable = this.remainder.substring(i + 1).trim();
-                                this.remainder = this.remainder.substring(0, i + 1);
+                                end = i;
                                 break;
                             }
                         }
+
+                        // Unbalanced '[' inside the code: the RFC 9051 free-text form
+                        // (`atom [SP 1*<any TEXT-CHAR except "]">]`) permits '[' but not
+                        // ']', so the code really does end at the first ']' here. Without
+                        // this fallback the scan finds no closing bracket at all and the
+                        // human-readable text - what every error message is built from -
+                        // is swallowed into the response code.
+                        if (end < 0) {
+                            end = this.remainder.indexOf(']', match[0].length);
+                        }
+
+                        if (end >= 0) {
+                            this.humanReadable = this.remainder.substring(end + 1).trim();
+                            this.remainder = this.remainder.substring(0, end + 1);
+                        }
                     } else {
                         this.humanReadable = this.remainder.trim();
                         this.remainder = '';

package/lib/imap-flow.d.ts

@@ -699,6 +699,8 @@ export interface ESearchResult {
         /** Matching UIDs in that range as compact sequence-set */
         messages: string;
     };
+    /** Highest mod-sequence of the matching messages (RFC 7162, present when the search used a modseq criterion on a CONDSTORE session) */
+    modseq?: bigint;
 }
 
 export class AuthenticationFailure extends Error {