imapflow 1.5.0 → 1.6.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.5.0"
+    ".": "1.6.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.6.0](https://github.com/postalsys/imapflow/compare/v1.5.0...v1.6.0) (2026-07-27)
+
+
+### Features
+
+* expand localized special-use folder names from client localization catalogs ([e766c41](https://github.com/postalsys/imapflow/commit/e766c411a71bc2e6578017a9029050e5026ca9de))
+
+
+### Bug Fixes
+
+* add missing localized special-use folder names and normalize to NFC ([1951438](https://github.com/postalsys/imapflow/commit/19514381a05d519ced1ab52716aa2256f7be169a))
+* declare specialUseHints.archive and specialUseSource in the types ([a372a50](https://github.com/postalsys/imapflow/commit/a372a50a0365b202d1c8d144663f8280ee63214c))
+* harden response parsing, tag correlation, IDLE polling and proxy connection setup ([21fe354](https://github.com/postalsys/imapflow/commit/21fe3541e9eff24060f1ef61f668fdfb5ae18115))
+* match decorated folder names and normalize special use names to NFKC ([8f3bed6](https://github.com/postalsys/imapflow/commit/8f3bed6fcd0daca48ad4ab8446fc1581792fb754))
+
 ## [1.5.0](https://github.com/postalsys/imapflow/compare/v1.4.9...v1.5.0) (2026-07-23)
 
 

package/CLAUDE.md

@@ -28,7 +28,7 @@ npm as `imapflow` and ships TypeScript type definitions.
 - **Module system**: CommonJS (see Packaging Constraints below)
 - **Testing**: Grunt + grunt-contrib-nodeunit, ESLint via grunt-eslint
 - **Lint/format**: ESLint (`eslint.config.js`, flat config) + Prettier
-- **Key dependencies**: `@zone-eu/mailsplit`, `libmime`, `libqp`, `libbase64`, `iconv-lite`, `encoding-japanese`, `nodemailer`, `pino`, `socks`
+- **Key dependencies**: `@zone-eu/mailsplit`, `libmime`, `libqp`, `libbase64`, `iconv-lite`, `encoding-japanese`, `pino`, `socks`
 
 ## Development Commands
 

package/lib/commands/idle.js

@@ -1,9 +1,32 @@
 'use strict';
 
-const { hasCapability } = require('../tools.js');
+const { hasCapability, unrefTimer } = require('../tools.js');
 
 const NOOP_INTERVAL = 2 * 60 * 1000;
 
+/**
+ * Marks the connection as idling on behalf of one session and returns a release function.
+ *
+ * Both IDLE modes use this so ownership of the shared `idling` flag is explicit: a session that
+ * finishes late (a poll that completes after cancellation, an IDLE that unwinds after a restart)
+ * cannot clear the flag of the session that has since taken over.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @returns {Function} Release function, safe to call more than once
+ */
+function claimIdling(connection) {
+    let token = {};
+    connection._idleSession = token;
+    connection.idling = true;
+
+    return () => {
+        if (connection._idleSession === token) {
+            connection._idleSession = null;
+            connection.idling = false;
+        }
+    };
+}
+
 /**
  * Runs a single IDLE session on the connection.
  *
@@ -16,9 +39,13 @@ async function runIdle(connection) {
     // Queue of promises waiting for IDLE to break. When another command needs to run,
     // it calls connection.preCheck() which queues a promise here and sends DONE to break IDLE.
     let preCheckWaitQueue = [];
-    try {
-        connection.idling = true;
 
+    // The preCheck function this session owns. Only this session may clear it from the
+    // connection, so a newer IDLE session that already installed its own is left alone.
+    let ownPreCheck = null;
+    let releaseIdling = claimIdling(connection);
+
+    try {
         // State flags for the IDLE lifecycle:
         // - doneRequested: someone wants to break IDLE (e.g., to run another command)
         // - doneSent: we've already sent the DONE command to server
@@ -42,8 +69,10 @@ async function runIdle(connection) {
                 connection.write('DONE');
                 doneSent = true;
 
-                connection.idling = false;
-                connection.preCheck = false; // unset itself
+                releaseIdling();
+                if (connection.preCheck === ownPreCheck) {
+                    connection.preCheck = false; // unset itself
+                }
 
                 while (preCheckWaitQueue.length) {
                     let { resolve } = preCheckWaitQueue.shift();
@@ -75,6 +104,7 @@ async function runIdle(connection) {
         };
 
         // Register preCheck on the connection so other code (e.g., getMailboxLock) can break IDLE
+        ownPreCheck = connectionPreCheck;
         connection.preCheck = connectionPreCheck;
 
         response = await connection.exec('IDLE', false, {
@@ -95,37 +125,165 @@ async function runIdle(connection) {
             onSend: () => {}
         });
 
-        // Clean up: unset preCheck and resolve any remaining waiters before processing the response.
-        // Usually preCheck is already cleared by the DONE handler, but this handles edge cases.
-        if (typeof connection.preCheck === 'function' && connection.preCheck === connectionPreCheck) {
-            connection.log.trace({
-                msg: 'Clearing pre-check function',
-                lockId: connection.currentLock?.lockId,
-                path: connection.mailbox && connection.mailbox.path,
-                queued: preCheckWaitQueue.length,
-                doneRequested,
-                canEnd,
-                doneSent
-            });
-            connection.preCheck = false;
-            while (preCheckWaitQueue.length) {
-                let { resolve } = preCheckWaitQueue.shift();
-                resolve();
-            }
-        }
-
         response.next();
         return;
     } catch (err) {
-        connection.preCheck = false;
-        connection.idling = false;
-
         connection.log.warn({ err, cid: connection.id });
         while (preCheckWaitQueue.length) {
             let { reject } = preCheckWaitQueue.shift();
             reject(err);
         }
         return false;
+    } finally {
+        // Single ownership cleanup for every outcome: explicit break, tagged completion
+        // (including a server-terminated IDLE, where preCheck never ran), rejected command,
+        // parser failure and connection close. `idling` drives socket-timeout handling, so it
+        // must always describe reality rather than being left over from a previous state.
+        releaseIdling();
+        if (connection.preCheck === ownPreCheck) {
+            connection.preCheck = false;
+        }
+        while (preCheckWaitQueue.length) {
+            let { resolve } = preCheckWaitQueue.shift();
+            resolve();
+        }
+    }
+}
+
+/**
+ * Runs one fallback poll. The real SELECT and STATUS commands are reused instead of replaying the
+ * saved wire arguments, so a poll applies exactly the same mailbox state transitions, events and
+ * failure handling as a caller-issued command. They go through connection.runInternal() rather
+ * than connection.run(), because run() awaits preCheck() - and the preCheck it would await is the
+ * one this very polling session installed, so the session would cancel itself.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {Object} session - Polling session state
+ * @returns {Promise<void>}
+ */
+async function pollOnce(connection, session) {
+    let path = connection.mailbox && connection.mailbox.path;
+
+    switch (connection.missingIdleCommand) {
+        case 'SELECT':
+            connection.log.debug({ src: 'c', msg: `Running SELECT to detect changes in folder`, cid: connection.id });
+            await connection.runInternal('SELECT', path, { readOnly: session.selectCommand.command === 'EXAMINE' });
+            break;
+
+        case 'STATUS': {
+            connection.log.debug({ src: 'c', msg: `Running STATUS to detect changes in folder`, cid: connection.id });
+            // HIGHESTMODSEQ is filtered out again unless the server advertises CONDSTORE, so a
+            // CONDSTORE session keeps mailbox.highestModseq current without asking a plain
+            // server for an item it does not know.
+            let status = await connection.runInternal('STATUS', path, {
+                messages: true,
+                uidNext: true,
+                uidValidity: true,
+                unseen: true,
+                highestModseq: true
+            });
+            if (!status) {
+                let err = new Error('STATUS poll failed');
+                err.code = 'PollFailed';
+                throw err;
+            }
+            break;
+        }
+
+        case 'NOOP':
+        default: {
+            let response = await connection.exec('NOOP', false, { comment: 'IDLE not supported' });
+            response.next();
+            break;
+        }
+    }
+}
+
+/**
+ * Polls the selected mailbox at a fixed interval, for servers without IDLE support.
+ *
+ * The loop is one explicitly identified session: cancellation is idempotent, is checked before
+ * a poll starts and again before the next timer is scheduled, and a poll that completes after
+ * cancellation can neither run again nor take ownership away from a newer IDLE session.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {number} [maxIdleTime] - Upper bound for the polling interval
+ * @returns {Promise<void>}
+ */
+async function runPollingFallback(connection, maxIdleTime) {
+    if (!connection.currentSelectCommand) {
+        return;
+    }
+
+    let session = {
+        cancelled: false,
+        timer: null,
+        preCheck: null,
+        selectCommand: connection.currentSelectCommand
+    };
+
+    let interval = maxIdleTime ? Math.min(NOOP_INTERVAL, maxIdleTime) : NOOP_INTERVAL;
+    let releaseIdling = claimIdling(connection);
+
+    try {
+        await new Promise(resolve => {
+            // Idempotent cancellation. Never keyed off connection.preCheck, because a newer IDLE
+            // session may already own that property by the time an old poll settles.
+            const cancel = () => {
+                if (session.cancelled) {
+                    return;
+                }
+                session.cancelled = true;
+                clearTimeout(session.timer);
+                session.timer = null;
+                resolve();
+            };
+
+            session.preCheck = async () => {
+                connection.log.debug({ src: 'c', msg: `breaking NOOP loop`, cid: connection.id });
+                cancel();
+            };
+            connection.preCheck = session.preCheck;
+
+            const runPoll = () => {
+                if (session.cancelled) {
+                    return;
+                }
+
+                // The transport or the mailbox may be gone by the time the timer fires
+                if (!connection.socket || connection.socket.destroyed || connection.state !== connection.states.SELECTED || !connection.mailbox) {
+                    return cancel();
+                }
+
+                pollOnce(connection, session)
+                    .then(() => {
+                        // Cancellation is re-checked here: the session may have been broken while
+                        // this poll was in flight, and an orphaned poller must not schedule again.
+                        if (session.cancelled) {
+                            return;
+                        }
+                        session.timer = setTimeout(runPoll, interval);
+                        // Background polling must not keep the process alive
+                        unrefTimer(session.timer);
+                    })
+                    .catch(err => {
+                        connection.log.warn({ err, cid: connection.id });
+                        cancel();
+                    });
+            };
+
+            connection.log.debug({ src: 'c', msg: `initiated NOOP loop`, cid: connection.id });
+            // Keep the immediate first poll
+            runPoll();
+        });
+    } finally {
+        session.cancelled = true;
+        clearTimeout(session.timer);
+        session.timer = null;
+        releaseIdling();
+        if (connection.preCheck === session.preCheck) {
+            connection.preCheck = false;
+        }
     }
 }
 
@@ -148,9 +306,11 @@ module.exports = async (connection, maxIdleTime) => {
     if (hasCapability(connection, 'IDLE')) {
         let idleTimer;
         let stillIdling = false;
-        // IDLE loop: runs IDLE, and if maxIdleTime is reached, breaks and restarts
-        // to keep the connection alive (some servers drop long-running IDLEs).
-        let runIdleLoop = async () => {
+        // IDLE loop: runs IDLE, and if maxIdleTime is reached, breaks and restarts to keep the
+        // connection alive (some servers drop long-running IDLEs). Iterative rather than
+        // recursive, so a long-lived idling connection does not retain one pending frame per
+        // restart.
+        for (;;) {
             if (maxIdleTime) {
                 idleTimer = setTimeout(() => {
                     if (connection.idling) {
@@ -162,86 +322,19 @@ module.exports = async (connection, maxIdleTime) => {
                         }
                     }
                 }, maxIdleTime);
+                // Background IDLE restart timer must not keep the process alive
+                unrefTimer(idleTimer);
             }
             let resp = await runIdle(connection);
             clearTimeout(idleTimer);
-            if (stillIdling) {
-                stillIdling = false;
-                return runIdleLoop();
+            if (!stillIdling) {
+                return resp;
             }
-            return resp;
-        };
-        return runIdleLoop();
+            stillIdling = false;
+        }
     }
 
     // Fallback for servers without IDLE support: poll at regular intervals using
     // NOOP (default), STATUS, or SELECT depending on missingIdleCommand config.
-    let idleTimer;
-    return new Promise(resolve => {
-        if (!connection.currentSelectCommand) {
-            return resolve();
-        }
-
-        // Set up preCheck so other commands can break the polling loop
-        connection.preCheck = async () => {
-            connection.preCheck = false; // unset itself
-            clearTimeout(idleTimer);
-            connection.log.debug({ src: 'c', msg: `breaking NOOP loop` });
-            connection.idling = false;
-            resolve();
-        };
-
-        let selectCommand = connection.currentSelectCommand;
-
-        // Run one polling check. The method used depends on configuration:
-        // SELECT re-selects the mailbox (may detect changes), STATUS queries mailbox counters,
-        // NOOP is the simplest but relies on server pushing untagged responses.
-        let idleCheck = async () => {
-            let response;
-            switch (connection.missingIdleCommand) {
-                case 'SELECT':
-                    // FIXME: somehow a loop occurs after some time of idling with SELECT
-                    connection.log.debug({ src: 'c', msg: `Running SELECT to detect changes in folder` });
-                    response = await connection.exec(selectCommand.command, selectCommand.arguments);
-                    break;
-
-                case 'STATUS':
-                    {
-                        let statusArgs = [
-                            selectCommand.arguments[0],
-                            ['MESSAGES', 'UIDNEXT', 'UIDVALIDITY', 'UNSEEN'].map(key => ({ type: 'ATOM', value: key }))
-                        ];
-                        connection.log.debug({ src: 'c', msg: `Running STATUS to detect changes in folder` });
-                        response = await connection.exec('STATUS', statusArgs);
-                    }
-                    break;
-
-                case 'NOOP':
-                default:
-                    response = await connection.exec('NOOP', false, { comment: 'IDLE not supported' });
-                    break;
-            }
-            response.next();
-        };
-
-        let noopInterval = maxIdleTime ? Math.min(NOOP_INTERVAL, maxIdleTime) : NOOP_INTERVAL;
-
-        let runLoop = () => {
-            idleCheck()
-                .then(() => {
-                    clearTimeout(idleTimer);
-                    idleTimer = setTimeout(runLoop, noopInterval);
-                })
-                .catch(err => {
-                    clearTimeout(idleTimer);
-                    connection.preCheck = false;
-                    connection.log.warn({ err, cid: connection.id });
-                    resolve();
-                });
-        };
-
-        connection.log.debug({ src: 'c', msg: `initiated NOOP loop` });
-        connection.idling = true;
-        runLoop();
-    });
+    return runPollingFallback(connection, maxIdleTime);
 };

package/lib/commands/list.js

@@ -23,9 +23,15 @@ module.exports = async (connection, reference, mailbox, options) => {
     // Used in the final sort to group special-use mailboxes at the top of the list.
     const FLAG_SORT_ORDER = ['\\Inbox', '\\Flagged', '\\Sent', '\\Drafts', '\\All', '\\Archive', '\\Junk', '\\Trash'];
     // Priority for how a special-use flag was determined: explicit user hint > server
-    // extension flag (SPECIAL-USE/XLIST) > name-based guess. When multiple mailboxes
-    // claim the same special-use type, the highest-priority source wins.
-    const SOURCE_SORT_ORDER = ['user', 'extension', 'name'];
+    // extension flag (SPECIAL-USE/XLIST) > known localized name > relaxed name guess.
+    // When multiple mailboxes claim the same special-use type, the highest-priority
+    // source wins, so an exactly named folder beats one matched by a decorated or
+    // morphological variant of that name.
+    const SOURCE_SORT_ORDER = ['user', 'extension', 'name', 'name-guess'];
+    // "name-guess" is an internal precedence tier only. It is reported as "name" so
+    // that specialUseSource keeps its documented set of values for consumers.
+    const PUBLIC_SOURCE = { 'name-guess': 'name' };
+    const isNameSource = source => source === 'name' || source === 'name-guess';
 
     // Prefer XLIST (legacy Gmail extension) only if SPECIAL-USE (RFC 6154) is unavailable.
     // Both provide special-use flags, but SPECIAL-USE is the standardized approach.
@@ -210,10 +216,11 @@ module.exports = async (connection, reference, mailbox, options) => {
                             entry
                         );
 
-                        // A name-based guess for a \NonExistent phantom entry could win the
+                        // A name-based match for a \NonExistent phantom entry could win the
                         // special-use slot over the real folder - only server-provided flags
-                        // are trusted for nonexistent entries
-                        if (specialUseFlag && (flagSource !== 'name' || !entry.flags.has('\\NonExistent'))) {
+                        // are trusted for nonexistent entries. Covers every name-derived
+                        // source, exact and relaxed alike.
+                        if (specialUseFlag && (!isNameSource(flagSource) || !entry.flags.has('\\NonExistent'))) {
                             addSpecialUseMatch(entry, specialUseFlag, flagSource);
                         }
 
@@ -511,8 +518,9 @@ module.exports = async (connection, reference, mailbox, options) => {
             });
 
             if (!sortedEntries[0].entry.specialUse) {
+                let source = sortedEntries[0].source;
                 sortedEntries[0].entry.specialUse = type;
-                sortedEntries[0].entry.specialUseSource = sortedEntries[0].source;
+                sortedEntries[0].entry.specialUseSource = PUBLIC_SOURCE[source] || source;
             }
         }
 

package/lib/commands/quota.js

@@ -110,6 +110,9 @@ module.exports = async (connection, path) => {
                     }
                 }
             });
+            // Release the parser: without this the connection stalls, because the reader loop
+            // waits for the response to be handed back before parsing any further input.
+            response.next();
         }
 
         return map;

package/lib/commands/select.js

@@ -25,6 +25,11 @@ module.exports = async (connection, path, options) => {
 
     // Ensure we have folder metadata (delimiter, flags, specialUse) by running LIST if needed.
     // This is cached in connection.folders to avoid repeated LIST calls.
+    // Note: this uses run() rather than runInternal(), so it terminates a running IDLE first,
+    // which is what a caller-issued mailboxOpen() needs. Fallback polling reaches SELECT through
+    // runInternal(), and on a cache miss this LIST awaits the polling session's own preCheck and
+    // so cancels that session. Not a deadlock, and only reachable when the folder is uncached,
+    // but a polled SELECT of an unlisted folder ends the poll early.
     if (!connection.folders.has(path)) {
         let folders = await connection.run('LIST', '', path);
         if (!folders) {

package/lib/commands/status.js

@@ -132,6 +132,10 @@ module.exports = async (connection, path, query) => {
         // A NO response usually means the mailbox doesn't exist. Verify by
         // running LIST -- if no results, throw a clear NotFound error instead
         // of the generic IMAP error.
+        // Note: this uses run(), so when STATUS was dispatched by fallback polling through
+        // runInternal() the LIST awaits that polling session's own preCheck and cancels it.
+        // Not a deadlock, and only reachable when the server rejects the STATUS, but a polled
+        // STATUS of a missing folder ends the poll early.
         if (err.responseStatus === 'NO') {
             let folders = await connection.run('LIST', '', path, { listOnly: true });
             if (folders && !folders.length) {

package/lib/connection-deadline.js

@@ -0,0 +1,98 @@
+'use strict';
+
+// Default upper bound for establishing a usable transport, including DNS and proxy negotiation.
+const CONNECT_TIMEOUT = 90 * 1000;
+
+/**
+ * One deadline for an entire connection attempt.
+ *
+ * DNS resolution, proxy negotiation and the transport handshake all draw from the same budget, so
+ * a phase that stalls cannot extend the documented `connectionTimeout`. Every expiry - whether it
+ * comes from this deadline or is normalized from a dependency - is reported with the same
+ * `CONNECT_TIMEOUT` error shape, so callers do not need to know which phase was blocked.
+ */
+class ConnectionDeadline {
+    /**
+     * @param {Number} [timeout] Configured connection timeout in milliseconds. Normalized once
+     *   here; 0 and any other falsy or invalid value fall back to the 90 second default.
+     */
+    constructor(timeout) {
+        this.timeout = Number(timeout) || CONNECT_TIMEOUT;
+        this.startedAt = Date.now();
+    }
+
+    /**
+     * @returns {Number} Milliseconds left in the budget, never negative.
+     */
+    remaining() {
+        return Math.max(0, this.timeout - (Date.now() - this.startedAt));
+    }
+
+    /**
+     * @returns {Error} The shared `CONNECT_TIMEOUT` error.
+     */
+    error() {
+        let err = new Error('Failed to establish connection in required time');
+        err.code = 'CONNECT_TIMEOUT';
+        err.details = { connectionTimeout: this.timeout };
+        return err;
+    }
+
+    /**
+     * Maps a dependency's own expiry onto the shared `CONNECT_TIMEOUT` shape, so callers see one
+     * timeout error whichever layer noticed first. The original error is kept as `_err`. Anything
+     * that is not a timeout is returned unchanged.
+     *
+     * @param {Error} err Error raised by a dependency during a connection phase.
+     * @returns {Error} Either the normalized timeout error or the original error.
+     */
+    normalize(err) {
+        if (!err || err.code === 'CONNECT_TIMEOUT') {
+            return err;
+        }
+
+        // The `socks` client reports its own expiry as "Proxy connection timed out"
+        if (err.code !== 'ETIMEDOUT' && !/timed out/i.test(err.message || '')) {
+            return err;
+        }
+
+        let normalized = this.error();
+        normalized._err = err;
+        return normalized;
+    }
+
+    /**
+     * Throws before a phase is started if the budget is already used up, so no work is begun
+     * that could only ever time out.
+     */
+    check() {
+        if (!this.remaining()) {
+            throw this.error();
+        }
+    }
+
+    /**
+     * Races a phase against the remaining budget. The timer is always cleared, so a completed
+     * phase never leaves a pending timer behind.
+     *
+     * @param {Promise} promise Phase to run under the deadline.
+     * @returns {Promise<*>} Resolves with the phase result, rejects with `CONNECT_TIMEOUT`.
+     */
+    async race(promise) {
+        this.check();
+
+        let timer = null;
+        try {
+            return await Promise.race([
+                promise,
+                new Promise((resolve, reject) => {
+                    timer = setTimeout(() => reject(this.error()), this.remaining());
+                })
+            ]);
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+}
+
+module.exports = { ConnectionDeadline, CONNECT_TIMEOUT };

package/lib/handler/imap-compiler.js

@@ -65,11 +65,14 @@ module.exports = async (response, options) => {
             lastRespByte = String.fromCharCode(lastRespByte);
         }
 
-        // Add a space separator unless:
-        // - The previous token was a LITERAL (literal data is self-delimiting after CRLF)
-        // - The last byte was '(', '<', or '[' (opening delimiters suppress the space)
-        // - This is the first token (resp is empty)
-        // - This is a sub-array element in a consecutive-list context (no space between adjacent lists)
+        // Add a space separator when:
+        // - The previous token was a LITERAL. Literal data ends exactly at its declared length, so
+        //   a following token always needs an explicit separator, even though the last written byte
+        //   is arbitrary literal content.
+        // - Otherwise: there is something written already (resp is not empty) and the last byte is
+        //   not an opening delimiter ('(', '<' or '['), which suppresses the space.
+        // A sub-array element in a consecutive-list context never gets one (no space between
+        // adjacent lists).
         if (lastType === 'LITERAL' || (!['(', '<', '['].includes(lastRespByte) && resp.length)) {
             if (!options.subArray) {
                 resp.push(formatRespEntry(' '));