imapflow 1.4.8 → 1.5.0

package/lib/tools.js

@@ -11,6 +11,35 @@ const iconv = require('iconv-lite');
 
 const FLAG_COLORS = ['red', 'orange', 'yellow', 'green', 'blue', 'purple', 'grey'];
 
+// Upper bound for expanding a single server-supplied sequence range (see
+// expandRange). 2^24 entries is far beyond any legitimate mailbox while keeping
+// the worst-case expansion of a hostile range bounded.
+const EXPANDED_RANGE_LIMIT = 0x1000000;
+
+// Extensions that RFC 9051 (IMAP4rev2) folds into the base protocol (Appendix E).
+// When IMAP4rev2 is active, these are available even without their own capability
+// token. BINARY is deliberately excluded - RFC 9051 only folds in the FETCH side,
+// which fetch.js handles with its own isRev2Active check, while the APPEND side
+// stays gated on the BINARY token. The set mirrors the Appendix E list in full,
+// including entries no call site consults yet, so any future capability check
+// gets the rev2 folding for free.
+const IMAP4REV2_FOLDED_CAPABILITIES = new Set([
+    'ENABLE',
+    'ESEARCH',
+    'IDLE',
+    'LIST-EXTENDED',
+    'LIST-STATUS',
+    'LITERAL-',
+    'MOVE',
+    'NAMESPACE',
+    'SASL-IR',
+    'SEARCHRES',
+    'SPECIAL-USE',
+    'STATUS=SIZE',
+    'UIDPLUS',
+    'UNSELECT'
+]);
+
 /**
  * Error subclass thrown when IMAP authentication fails.
  */
@@ -19,6 +48,98 @@ class AuthenticationFailure extends Error {
 }
 
 const tools = {
+    /**
+     * Checks whether IMAP4rev2 semantics are active for the connection: either the
+     * client enabled IMAP4rev2 explicitly, or the server is rev2-only (advertises
+     * IMAP4rev2 without IMAP4rev1), in which case rev2 is the base protocol without
+     * any ENABLE (RFC 9051 Appendix A). UTF-8 mailbox names apply in both cases.
+     *
+     * @param {Object} connection - IMAP connection instance
+     * @returns {Boolean} True if IMAP4rev2 semantics apply to this session
+     */
+    isRev2Active(connection) {
+        return connection.enabled.has('IMAP4REV2') || (connection.capabilities.has('IMAP4rev2') && !connection.capabilities.has('IMAP4rev1'));
+    },
+
+    /**
+     * Checks a capability, accounting for extensions that RFC 9051 folds into base
+     * IMAP4rev2. Falls back to the plain capability lookup on IMAP4rev1 sessions,
+     * so behavior against rev1 servers is unchanged.
+     *
+     * @param {Object} connection - IMAP connection instance
+     * @param {String} capability - Capability name, e.g. 'UIDPLUS'
+     * @returns {Boolean} True if the capability (or its rev2-folded equivalent) is available
+     */
+    hasCapability(connection, capability) {
+        if (connection.capabilities.has(capability)) {
+            return true;
+        }
+        return IMAP4REV2_FOLDED_CAPABILITIES.has(capability) && tools.isRev2Active(connection);
+    },
+
+    /**
+     * Builds the attribute list for a STATUS request - the standalone STATUS command
+     * or the LIST-STATUS return option - from a status query object. Items the current
+     * session cannot request (RECENT under IMAP4rev2, HIGHESTMODSEQ without CONDSTORE)
+     * are silently dropped.
+     *
+     * @param {Object} connection - IMAP connection instance
+     * @param {Object} statusQuery - Status data items to request, e.g. {messages: true}
+     * @returns {Object[]} Attribute token list for the command compiler
+     */
+    buildStatusQueryAttributes(connection, statusQuery) {
+        let attributes = [];
+
+        Object.keys(statusQuery || {}).forEach(key => {
+            if (!statusQuery[key]) {
+                return;
+            }
+
+            switch (key.toUpperCase()) {
+                case 'MESSAGES':
+                case 'UIDNEXT':
+                case 'UIDVALIDITY':
+                case 'UNSEEN':
+                    attributes.push({ type: 'ATOM', value: key.toUpperCase() });
+                    break;
+
+                case 'RECENT':
+                    // RECENT was removed in IMAP4rev2 (RFC 9051) - requesting it from a
+                    // rev2 session would get the whole STATUS request rejected
+                    if (!tools.isRev2Active(connection)) {
+                        attributes.push({ type: 'ATOM', value: key.toUpperCase() });
+                    }
+                    break;
+
+                case 'HIGHESTMODSEQ':
+                    if (connection.capabilities.has('CONDSTORE')) {
+                        attributes.push({ type: 'ATOM', value: key.toUpperCase() });
+                    }
+                    break;
+
+                case 'SIZE':
+                    // STATUS SIZE requires the STATUS=SIZE extension (RFC 8438), which
+                    // RFC 9051 folds into base IMAP4rev2
+                    if (tools.hasCapability(connection, 'STATUS=SIZE')) {
+                        attributes.push({ type: 'ATOM', value: key.toUpperCase() });
+                    }
+                    break;
+
+                case 'DELETED':
+                    // STATUS DELETED is a base IMAP4rev2 addition (RFC 9051 Appendix E
+                    // item 3) with no standalone capability - requesting it from a plain
+                    // rev1 server would get the whole STATUS request rejected. RFC 9208
+                    // additionally makes it mandatory when QUOTA=RES-MESSAGE is advertised.
+                    if (tools.isRev2Active(connection) || connection.capabilities.has('QUOTA=RES-MESSAGE')) {
+                        attributes.push({ type: 'ATOM', value: key.toUpperCase() });
+                    }
+                    break;
+            }
+        });
+
+        return attributes;
+    },
+
     /**
      * Encodes a mailbox path to modified UTF-7 if the server does not support UTF8=ACCEPT.
      *
@@ -28,7 +149,7 @@ const tools = {
      */
     encodePath(connection, path) {
         path = (path || '').toString();
-        if (!connection.enabled.has('UTF8=ACCEPT') && /[&\x00-\x08\x0b-\x0c\x0e-\x1f\u0080-\uffff]/.test(path)) {
+        if (!connection.enabled.has('UTF8=ACCEPT') && !tools.isRev2Active(connection) && /[&\x00-\x08\x0b-\x0c\x0e-\x1f\u0080-\uffff]/.test(path)) {
             try {
                 path = iconv.encode(path, 'utf-7-imap').toString();
             } catch {
@@ -47,7 +168,7 @@ const tools = {
      */
     decodePath(connection, path) {
         path = (path || '').toString();
-        if (!connection.enabled.has('UTF8=ACCEPT') && /[&]/.test(path)) {
+        if (!connection.enabled.has('UTF8=ACCEPT') && !tools.isRev2Active(connection) && /[&]/.test(path)) {
             try {
                 path = iconv.decode(Buffer.from(path), 'utf-7-imap').toString();
             } catch {
@@ -120,6 +241,11 @@ const tools = {
                     return;
                 }
 
+                if (capability === 'IMAP4REV2') {
+                    map.set('IMAP4rev2', true);
+                    return;
+                }
+
                 if (capability.startsWith('APPENDLIMIT=')) {
                     let splitPos = capability.indexOf('=');
                     let appendLimit = Number(capability.substr(splitPos + 1)) || 0;
@@ -222,7 +348,7 @@ const tools = {
                 existing.path = folder.path;
                 existing.subscribed = !!folder.subscribed;
                 existing.listed = !!folder.listed;
-                existing.status = !!folder.status;
+                existing.status = folder.status;
 
                 if (folder.specialUse) {
                     existing.specialUse = folder.specialUse;
@@ -242,7 +368,7 @@ const tools = {
                     path: folder.path,
                     subscribed: !!folder.subscribed,
                     listed: !!folder.listed,
-                    status: !!folder.status
+                    status: folder.status
                 };
 
                 if (folder.delimiter) {
@@ -484,6 +610,19 @@ const tools = {
                             map.bodyParts = new Map();
                         }
                         map.bodyParts.set(partKey, value);
+
+                        if (match[1].toLowerCase() === 'binary') {
+                            // The part arrived via FETCH BINARY (RFC 3516, FETCH side folded
+                            // into IMAP4rev2), so the server has already removed the
+                            // content-transfer-encoding - consumers must not decode it again.
+                            // Recorded from the actual response, not predicted from the
+                            // request, so it stays correct even if a server answers a BINARY
+                            // request with a BODY response or vice versa.
+                            if (!map.binaryParts) {
+                                map.binaryParts = new Set();
+                            }
+                            map.binaryParts.add(partKey);
+                        }
                         break;
                     }
                     break;
@@ -1016,9 +1155,28 @@ const tools = {
         return !mailbox || !mailbox.permanentFlags || mailbox.permanentFlags.has('\\*') || mailbox.permanentFlags.has(flag);
     },
 
+    /**
+     * Checks that a value is a valid IMAP sequence number or UID: a non-zero
+     * 32-bit unsigned integer (nz-number in the RFC 9051 grammar). Guards range
+     * expansion against untrusted server input such as 'Infinity' or '0:*'.
+     *
+     * @param {Number} value - Value to check
+     * @returns {Boolean} True if the value is a valid sequence number/UID
+     */
+    isValidSequenceValue(value) {
+        return Number.isSafeInteger(value) && value > 0 && value <= 0xffffffff;
+    },
+
     /**
      * Expands an IMAP sequence range string (e.g. "1:3,5,7:9") into an array of numbers.
      *
+     * Entries with endpoints that are not valid nz-numbers are skipped - the input
+     * may come from an untrusted server, and 'Infinity' or similar garbage would
+     * otherwise loop without bound. A single range is expanded to at most
+     * EXPANDED_RANGE_LIMIT entries: legitimate responses never reach the limit
+     * (the mailbox would need that many messages), while a hostile range like
+     * 1:4294967295 is cut off instead of exhausting memory.
+     *
      * @param {String} range - IMAP sequence range string
      * @returns {Number[]} Array of expanded sequence numbers
      */
@@ -1027,20 +1185,26 @@ const tools = {
             entry = entry.trim();
             let colon = entry.indexOf(':');
             if (colon < 0) {
-                return Number(entry) || 0;
+                let value = Number(entry);
+                return tools.isValidSequenceValue(value) ? value : [];
+            }
+            let first = Number(entry.substr(0, colon));
+            let second = Number(entry.substr(colon + 1));
+            if (!tools.isValidSequenceValue(first) || !tools.isValidSequenceValue(second)) {
+                return [];
             }
-            let first = Number(entry.substr(0, colon)) || 0;
-            let second = Number(entry.substr(colon + 1)) || 0;
             if (first === second) {
                 return first;
             }
             let list = [];
             if (first < second) {
-                for (let i = first; i <= second; i++) {
+                let last = Math.min(second, first + EXPANDED_RANGE_LIMIT - 1);
+                for (let i = first; i <= last; i++) {
                     list.push(i);
                 }
             } else {
-                for (let i = first; i >= second; i--) {
+                let last = Math.max(second, first - EXPANDED_RANGE_LIMIT + 1);
+                for (let i = first; i >= last; i--) {
                     list.push(i);
                 }
             }

package/package.json

@@ -1,12 +1,13 @@
 {
     "name": "imapflow",
-    "version": "1.4.8",
+    "version": "1.5.0",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",
     "scripts": {
         "test": "grunt",
         "coverage": "c8 --reporter=text --reporter=html npx nodeunit test/*-test.js",
+        "test:rev2": "bash test/integration/run-rev2-tests.sh",
         "update": "rm -rf node_modules package-lock.json && ncu -u && npm install",
         "format": "prettier --write \"**/*.{js,json,md,yml,yaml}\" --ignore-path .prettierignore",
         "lint": "eslint ."
@@ -37,7 +38,7 @@
         "grunt-cli": "1.5.0",
         "grunt-contrib-nodeunit": "5.0.0",
         "grunt-eslint": "26.0.0",
-        "prettier": "3.9.5",
+        "prettier": "3.9.6",
         "proxyquire": "^2.1.3",
         "typescript": "7.0.2"
     },

package/test/commands-branches-test.js

@@ -415,7 +415,7 @@ module.exports['Branches: search with undefined options uses {} fallback'] = asy
 // operand of the OR is evaluated and used to skip it.
 // ============================================================================
 
-module.exports['Branches: search ESEARCH without uid emits SEARCH and skips LIST-typed tag'] = async test => {
+module.exports['Branches: search ESEARCH without uid emits SEARCH and skips the tag correlator'] = async test => {
     let execCmd = null;
     const connection = createMockConnection({
         state: 3,
@@ -423,10 +423,17 @@ module.exports['Branches: search ESEARCH without uid emits SEARCH and skips LIST
         exec: async (cmd, attrs, opts) => {
             execCmd = cmd;
             if (opts && opts.untagged && opts.untagged.ESEARCH) {
-                // attrs[0] is a LIST-typed object (not a plain Array) -> exercises
-                // the `attrs[start].type === 'LIST'` branch on line 150.
+                // attrs[0] is the (TAG "...") correlator group, represented by the
+                // parser as a plain Array - it must be skipped before the keywords
                 await opts.untagged.ESEARCH({
-                    attributes: [{ type: 'LIST' }, { type: 'ATOM', value: 'COUNT' }, { type: 'ATOM', value: '7' }]
+                    attributes: [
+                        [
+                            { type: 'ATOM', value: 'TAG' },
+                            { type: 'STRING', value: 'A1' }
+                        ],
+                        { type: 'ATOM', value: 'COUNT' },
+                        { type: 'ATOM', value: '7' }
+                    ]
                 });
             }
             return { next: () => {} };