imapflow 1.4.7 → 1.4.9

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.4.7"
+    ".": "1.4.9"
 }

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.4.9](https://github.com/postalsys/imapflow/compare/v1.4.8...v1.4.9) (2026-07-22)
+
+
+### Bug Fixes
+
+* **folder:** pass StatusObject value instead of its boolean primitive ([043e248](https://github.com/postalsys/imapflow/commit/043e24802f2d73fac297d051a673fe9bc9eb3b25))
+* **list:** request subscription state inline and support IMAP4rev2 ([93e899d](https://github.com/postalsys/imapflow/commit/93e899ded64b219e7fbac2eff083890cb4baa382))
+
+## [1.4.8](https://github.com/postalsys/imapflow/compare/v1.4.7...v1.4.8) (2026-07-21)
+
+
+### Bug Fixes
+
+* **auth:** describe the real connection in the OAUTHBEARER payload ([aca7cb3](https://github.com/postalsys/imapflow/commit/aca7cb3ab7e67704cb692ad59f6db0792040a888))
+* default a non-secure connection to IMAP port 143, not POP3 110 ([5896488](https://github.com/postalsys/imapflow/commit/589648821c5dd1b1750959fa2917b3571ba93db5))
+
 ## [1.4.7](https://github.com/postalsys/imapflow/compare/v1.4.6...v1.4.7) (2026-07-10)
 
 

package/CLAUDE.md

@@ -38,13 +38,15 @@ npm run coverage   # Run tests under c8 coverage (text + html reports)
 npm run lint       # Lint with ESLint
 npm run format     # Format with Prettier (js, json, md, yml, yaml)
 npm run update     # Refresh deps: remove node_modules + lockfile, ncu -u, npm install
+npm run test:rev2  # Live IMAP4rev2 tests against Dovecot in Docker (see test/integration/)
 ```
 
 ## Testing
 
-- Tests live in `test/` and are named `*-test.js`; the Grunt nodeunit glob only matches that pattern, so helpers/fixtures are never run as tests.
+- Tests live in `test/` and are named `*-test.js`; the Grunt nodeunit glob only matches that pattern, so helpers/fixtures are never run as tests. Exception: `test/integration/` is excluded from the glob - those tests need Docker and run only via `npm run test:rev2`.
 - `npm test` runs `grunt`, which runs ESLint first, then the nodeunit suite. Keep the suite green and lint-clean before committing.
 - New tests go in `test/` as `*-test.js`. The parser, command compiler, and search compiler are the most security-sensitive areas - add hostile/malformed-input cases there.
+- `npm run test:rev2` starts a Dovecot 2.4 container (real IMAP4rev2 server) and runs `test/integration/rev2-live-test.js` against it - use it to verify rev2-facing changes end to end, mocks alone are not enough.
 
 ## Packaging Constraints (IMPORTANT)
 
@@ -59,6 +61,13 @@ CommonJS-compatible:
 - ImapFlow source stays CommonJS (`require`/`module.exports`). Do not convert the library to ESM.
 - Do not add a dependency that is pure ESM (`"type": "module"` with only an `import`/ESM entry and no CommonJS export). It must be `require()`-able.
 - When `npm run update` or a new dependency would pull in a pure-ESM package (a common outcome of major-version bumps), pin to the last CommonJS-compatible version instead, or find a CommonJS alternative. Verify with a quick `require()` of the package after updating.
+- After every `npm run update`, run this check to confirm all production dependencies are still CommonJS (it must print `CJS OK` for every dependency and report no pure-ESM packages), then run `npm test`:
+
+    ```
+    node -e "Object.keys(require('./package.json').dependencies).forEach(d => { require(d); console.log('CJS OK:', d); })"
+    node -e "const fs=require('fs');const bad=Object.keys(require('./package.json').dependencies).filter(d=>JSON.parse(fs.readFileSync(require.resolve(d+'/package.json'),'utf8')).type==='module');console.log(bad.length?'PURE-ESM DEPS FOUND: '+bad.join(', '):'No pure-ESM production dependencies')"
+    ```
+
 - Keep dynamic `require()` paths static enough for `pkg` to detect; avoid building module paths at runtime in ways the bundler can't trace.
 
 ## Code Style Rules

package/Gruntfile.js

@@ -8,7 +8,9 @@ module.exports = function (grunt) {
         },
 
         nodeunit: {
-            all: ['test/**/*-test.js']
+            // test/integration is excluded: those tests need a live Docker server
+            // and run via `npm run test:rev2` instead
+            all: ['test/**/*-test.js', '!test/integration/**']
         }
     });
 

package/lib/commands/authenticate.js

@@ -40,7 +40,19 @@ async function authOauth(connection, username, accessToken) {
         // OAUTHBEARER payload per RFC 7628: fields separated by \x01 (SASL GS2 framing).
         // Format: "n,a=<user>," \x01 "host=..." \x01 "port=..." \x01 "auth=Bearer <token>" \x01 \x01
         // The trailing empty strings produce the required double-\x01 terminator.
-        oauthbearer = [`n,a=${username},`, `host=${connection.servername}`, `port=993`, `auth=Bearer ${accessToken}`, '', ''].join('\x01');
+        // Both fields must describe the connection actually in use. The port was hardcoded to 993,
+        // so an OAuth2 server reached over 143/STARTTLS advertised a payload that did not match, and
+        // `servername` is set to false for a bare-IP host, which rendered as a literal "host=false".
+        // A server validating either field rejects with status `invalid_request` - a permanent
+        // failure that refreshing the access token can never clear.
+        oauthbearer = [
+            `n,a=${username},`,
+            `host=${connection.servername || connection.host}`,
+            `port=${connection.port}`,
+            `auth=Bearer ${accessToken}`,
+            '',
+            ''
+        ].join('\x01');
         command = 'OAUTHBEARER';
         // "AQ==" is base64 for \x01 -- sent as the error continuation to abort the SASL exchange
         breaker = 'AQ==';

package/lib/commands/enable.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { hasCapability } = require('../tools.js');
+
 /**
  * Enables IMAP extensions on the server.
  *
@@ -8,14 +10,18 @@
  * @returns {Promise<Set|boolean|undefined>} Set of enabled extensions, false on failure, or undefined if not applicable
  */
 module.exports = async (connection, extensionList) => {
-    if (!connection.capabilities.has('ENABLE') || connection.state !== connection.states.AUTHENTICATED) {
+    // ENABLE is part of base IMAP4rev2, so rev2-only servers may omit the token
+    if (!hasCapability(connection, 'ENABLE') || connection.state !== connection.states.AUTHENTICATED) {
         // nothing to do here
         return;
     }
 
     // Pre-filter: only request extensions the server actually advertised in its
     // CAPABILITY response. Requesting unsupported extensions would cause an error.
-    extensionList = extensionList.filter(extension => connection.capabilities.has(extension.toUpperCase()));
+    // Compared case-insensitively - the capability map keeps canonical casing for
+    // some keys (e.g. IMAP4rev2).
+    let advertised = new Set([...connection.capabilities.keys()].map(capability => capability.toUpperCase()));
+    extensionList = extensionList.filter(extension => advertised.has(extension.toUpperCase()));
     if (!extensionList.length) {
         return;
     }
@@ -44,9 +50,12 @@ module.exports = async (connection, extensionList) => {
                 }
             }
         );
-        connection.enabled = enabled;
+        // Merge instead of replace - the untagged ENABLED response only lists
+        // extensions enabled by this command (RFC 5161), so a replace would drop
+        // grants from an earlier ENABLE call
+        connection.enabled = new Set([...connection.enabled, ...enabled]);
         response.next();
-        return enabled;
+        return connection.enabled;
     } catch (err) {
         connection.log.warn({ err, cid: connection.id });
         return false;

package/lib/commands/expunge.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { enhanceCommandError } = require('../tools.js');
+const { enhanceCommandError, hasCapability } = require('../tools.js');
 
 /**
  * Deletes specified messages by flagging them as Deleted and expunging.
@@ -27,7 +27,7 @@ module.exports = async (connection, range, options) => {
     // With UIDPLUS (RFC 4315): "UID EXPUNGE <uids>" removes only the specified UIDs,
     // leaving other \Deleted messages untouched -- important for concurrent access.
     // Without UIDPLUS: plain "EXPUNGE" removes ALL messages flagged \Deleted in the mailbox.
-    let byUid = options.uid && connection.capabilities.has('UIDPLUS');
+    let byUid = options.uid && hasCapability(connection, 'UIDPLUS');
     let command = byUid ? 'UID EXPUNGE' : 'EXPUNGE';
     let attributes = byUid ? [{ type: 'SEQUENCE', value: range }] : false;
 

package/lib/commands/idle.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { hasCapability } = require('../tools.js');
+
 const NOOP_INTERVAL = 2 * 60 * 1000;
 
 /**
@@ -140,9 +142,10 @@ module.exports = async (connection, maxIdleTime) => {
         return;
     }
 
-    // If server supports IDLE (RFC 2177), use it for real-time push notifications.
-    // Otherwise, fall back to periodic polling with NOOP/STATUS/SELECT.
-    if (connection.capabilities.has('IDLE')) {
+    // If server supports IDLE (RFC 2177, folded into base IMAP4rev2), use it for
+    // real-time push notifications. Otherwise, fall back to periodic polling with
+    // NOOP/STATUS/SELECT.
+    if (hasCapability(connection, 'IDLE')) {
         let idleTimer;
         let stillIdling = false;
         // IDLE loop: runs IDLE, and if maxIdleTime is reached, breaks and restarts

package/lib/commands/list.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { decodePath, encodePath, normalizePath } = require('../tools.js');
+const { decodePath, encodePath, normalizePath, enhanceCommandError, hasCapability, isRev2Active, buildStatusQueryAttributes } = require('../tools.js');
 const { specialUse } = require('../special-use');
 
 /**
@@ -29,57 +29,78 @@ module.exports = async (connection, reference, mailbox, options) => {
 
     // 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.
-    let listCommand = connection.capabilities.has('XLIST') && !connection.capabilities.has('SPECIAL-USE') ? 'XLIST' : 'LIST';
+    // SPECIAL-USE is checked with rev2 folding - a rev2 session implies SPECIAL-USE,
+    // so LIST is preferred even if a rev2 server also advertised legacy XLIST.
+    let listCommand = connection.capabilities.has('XLIST') && !hasCapability(connection, 'SPECIAL-USE') ? 'XLIST' : 'LIST';
 
-    let response;
     try {
-        let entries = [];
-
-        // statusMap caches STATUS responses received inline via LIST-STATUS extension,
-        // keyed by normalized mailbox path. This avoids separate STATUS commands per mailbox.
-        let statusMap = new Map();
-        let returnArgs = [];
-        let statusQueryAttributes = [];
-
-        // Build the list of STATUS data items to request (MESSAGES, UIDNEXT, etc.)
-        if (options.statusQuery) {
-            Object.keys(options.statusQuery).forEach(key => {
-                if (!options.statusQuery[key]) {
-                    return;
+        // Accumulators filled by the untagged LIST/STATUS handlers below. statusMap
+        // caches STATUS responses received inline via LIST-STATUS extension, keyed by
+        // normalized mailbox path (avoids separate STATUS commands per mailbox), and
+        // specialUseMatches tracks candidate mailboxes for each special-use type.
+        // (Re)initialized at the start of each retry stage of the main listing.
+        let entries;
+        let statusMap;
+        let specialUseMatches;
+
+        // STATUS data items to request (MESSAGES, UIDNEXT, etc.)
+        let statusQueryAttributes = buildStatusQueryAttributes(connection, options.statusQuery);
+
+        // Extended LIST syntax (RETURN options) is understood by servers advertising
+        // LIST-EXTENDED (RFC 5258) or IMAP4rev2 (RFC 9051). Deliberately keyed on the
+        // advertisement alone (not hasCapability/isRev2Active): the staged retry below
+        // handles servers that advertise but reject RETURN options, so the wider gate
+        // is safe for anything it covers, while gates without a retry ladder stay
+        // conservative.
+        let supportsExtendedList = connection.capabilities.has('LIST-EXTENDED') || connection.capabilities.has('IMAP4rev2');
+
+        // RETURN options for the LIST command. Servers occasionally advertise the
+        // extensions but still reject RETURN options - the staged retry below then
+        // re-runs the LIST with fewer options and latches a skip flag for the option
+        // group the server proved to reject, keeping later listings efficient.
+
+        // LIST-STATUS (RFC 5819, folded into base IMAP4rev2): request STATUS data
+        // inline with LIST, avoiding a separate STATUS command for each mailbox.
+        let canRequestStatus =
+            listCommand === 'LIST' && !connection.skipListStatusArgs && hasCapability(connection, 'LIST-STATUS') && !!statusQueryAttributes.length;
+
+        // RETURN (SUBSCRIBED): request subscription state inline instead of a separate
+        // LSUB command. IMAP4rev2 removed LSUB entirely, and some servers (e.g.
+        // Exchange in IMAP4rev2 mode) reject it with BAD even while still advertising
+        // IMAP4rev1.
+        let canRequestSubscribed = listCommand === 'LIST' && !options.listOnly && !connection.skipListSubscribedArg && supportsExtendedList;
+
+        // Auxiliary RETURN options (SPECIAL-USE/CHILDREN) that ride along with the
+        // STATUS/SUBSCRIBED option groups. When RETURN options are present, servers
+        // may report only what was explicitly requested (verified against Dovecot
+        // 2.4: special-use and child attributes disappear from such responses), so
+        // request everything a plain LIST would have provided.
+        let auxArgsAvailable = hasCapability(connection, 'SPECIAL-USE') || connection.capabilities.has('CHILDREN') || supportsExtendedList;
+        let stageHasAuxArgs = stage => (stage.status || stage.subscribed) && stage.aux !== false && !connection.skipListAuxArgs && auxArgsAvailable;
+
+        // Builds the RETURN (...) argument list for one retry stage
+        let buildListArgs = stage => {
+            let args = [];
+            if (stage.status) {
+                args.push({ type: 'ATOM', value: 'STATUS' }, statusQueryAttributes);
+            }
+            if (stageHasAuxArgs(stage)) {
+                if (hasCapability(connection, 'SPECIAL-USE')) {
+                    args.push({ type: 'ATOM', value: 'SPECIAL-USE' });
                 }
-
-                switch (key.toUpperCase()) {
-                    case 'MESSAGES':
-                    case 'RECENT':
-                    case 'UIDNEXT':
-                    case 'UIDVALIDITY':
-                    case 'UNSEEN':
-                        statusQueryAttributes.push({ type: 'ATOM', value: key.toUpperCase() });
-                        break;
-
-                    case 'HIGHESTMODSEQ':
-                        if (connection.capabilities.has('CONDSTORE')) {
-                            statusQueryAttributes.push({ type: 'ATOM', value: key.toUpperCase() });
-                        }
-                        break;
+                if (connection.capabilities.has('CHILDREN') || supportsExtendedList) {
+                    args.push({ type: 'ATOM', value: 'CHILDREN' });
                 }
-            });
-        }
-
-        // LIST-STATUS (RFC 5819): allows requesting STATUS data inline with LIST,
-        // avoiding a separate STATUS command for each mailbox. Adds RETURN (STATUS (...))
-        // and optionally SPECIAL-USE to the LIST command arguments.
-        if (listCommand === 'LIST' && connection.capabilities.has('LIST-STATUS') && statusQueryAttributes.length) {
-            returnArgs.push({ type: 'ATOM', value: 'STATUS' }, statusQueryAttributes);
-            if (connection.capabilities.has('SPECIAL-USE')) {
-                returnArgs.push({ type: 'ATOM', value: 'SPECIAL-USE' });
             }
-        }
+            if (stage.subscribed) {
+                args.push({ type: 'ATOM', value: 'SUBSCRIBED' });
+            }
+            return args;
+        };
 
-        // Tracks all candidate mailboxes for each special-use type (e.g., \\Sent).
-        // Multiple mailboxes may claim the same type via different sources (user hint,
-        // server extension, name match). After listing, the best match wins.
-        let specialUseMatches = {};
+        // Multiple mailboxes may claim the same special-use type (e.g., \\Sent) via
+        // different sources (user hint, server extension, name match). After listing,
+        // the best match wins.
         let addSpecialUseMatch = (entry, type, source) => {
             if (!specialUseMatches[type]) {
                 specialUseMatches[type] = [];
@@ -90,10 +111,17 @@ module.exports = async (connection, reference, mailbox, options) => {
         // RFC 5258: the \NonExistent attribute implies \Noselect. Some servers only
         // return \NonExistent for phantom folders, so add \Noselect as well to keep
         // the flags consistent for consumers that only check \Noselect.
+        // RETURN (SUBSCRIBED) - and some LSUB implementations - report subscription
+        // state as a \Subscribed attribute. Move it to the subscribed property so the
+        // output shape is the same however the state was delivered.
         let normalizeFlags = entry => {
             if (entry.flags.has('\\NonExistent')) {
                 entry.flags.add('\\Noselect');
             }
+            if (entry.flags.has('\\Subscribed')) {
+                entry.flags.delete('\\Subscribed');
+                entry.subscribed = true;
+            }
         };
 
         // User-provided hints map mailbox paths to special-use types (e.g., {sent: "Sent Items"}).
@@ -116,14 +144,14 @@ module.exports = async (connection, reference, mailbox, options) => {
         // Executes a LIST (or XLIST) command and collects mailbox entries.
         // Called once for the main listing and optionally again for INBOX if a
         // namespace prefix was used (INBOX may live outside the namespace).
-        let runList = async (reference, mailbox) => {
+        let runList = async (reference, mailbox, returnArgs) => {
             const cmdArgs = [encodePath(connection, reference), encodePath(connection, mailbox)];
 
             if (returnArgs.length) {
                 cmdArgs.push({ type: 'ATOM', value: 'RETURN' }, returnArgs);
             }
 
-            response = await connection.exec(listCommand, cmdArgs, {
+            let response = await connection.exec(listCommand, cmdArgs, {
                 untagged: {
                     // Each untagged LIST response: * LIST (<flags>) "<delimiter>" "<mailbox name>"
                     // attributes[0] = flags array, attributes[1] = delimiter, attributes[2] = mailbox name
@@ -159,8 +187,9 @@ module.exports = async (connection, reference, mailbox, options) => {
                         }
 
                         // Name-based INBOX detection: any mailbox named "INBOX" (case-insensitive)
-                        // is the inbox per RFC 3501.
-                        if (entry.path.toUpperCase() === 'INBOX') {
+                        // is the inbox per RFC 3501. Phantom \NonExistent entries (subscribed
+                        // leftovers of deleted mailboxes) must not claim the slot by name.
+                        if (entry.path.toUpperCase() === 'INBOX' && !entry.flags.has('\\NonExistent')) {
                             addSpecialUseMatch(entry, '\\Inbox', 'name');
                         }
 
@@ -177,11 +206,14 @@ module.exports = async (connection, reference, mailbox, options) => {
                         // Try to detect special-use from server flags or well-known names
                         // (e.g., "Sent", "Drafts", "Junk", "Trash")
                         let { flag: specialUseFlag, source: flagSource } = specialUse(
-                            connection.capabilities.has('XLIST') || connection.capabilities.has('SPECIAL-USE'),
+                            connection.capabilities.has('XLIST') || hasCapability(connection, 'SPECIAL-USE'),
                             entry
                         );
 
-                        if (specialUseFlag) {
+                        // A name-based guess 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'))) {
                             addSpecialUseMatch(entry, specialUseFlag, flagSource);
                         }
 
@@ -239,7 +271,87 @@ module.exports = async (connection, reference, mailbox, options) => {
         };
 
         let normalizedReference = normalizePath(connection, reference || '');
-        await runList(normalizedReference, normalizePath(connection, mailbox || '', true));
+        let normalizedMailbox = normalizePath(connection, mailbox || '', true);
+
+        // Retry stages for the main listing: start with all applicable RETURN options
+        // and drop one option group per retry. Consecutive stages differ by exactly one
+        // group, so a success right after a rejection identifies the offending group
+        // and only that group's skip flag is latched for the rest of the connection.
+        // When a stage carrying the auxiliary SPECIAL-USE/CHILDREN options is rejected,
+        // a copy of the same stage without them is inserted first (once per listing),
+        // so an auxiliary-only rejection does not get a whole option group blamed.
+        let stages = [];
+        if (canRequestStatus && canRequestSubscribed) {
+            stages.push({ status: true, subscribed: true });
+        }
+        if (canRequestStatus) {
+            stages.push({ status: true, subscribed: false });
+        } else if (canRequestSubscribed) {
+            stages.push({ status: false, subscribed: true });
+        }
+        stages.push({ status: false, subscribed: false });
+
+        // A tagged BAD is how servers reject unrecognized RETURN options (RFC 9051
+        // section 6.3.9). A tagged NO is an operational failure, and throttling
+        // errors (code ETHROTTLE) also surface with a BAD status - neither says
+        // anything about the RETURN options, so they propagate to the caller.
+        let isRejectedCommand = err => err.responseStatus === 'BAD' && err.code !== 'ETHROTTLE';
+
+        // Stage of the successful attempt - reused by the INBOX fixup and the LSUB
+        // decision below
+        let successStage = null;
+
+        let lastRejectedStage = null;
+        let auxRetryInserted = false;
+        for (let i = 0; i < stages.length; i++) {
+            let stage = stages[i];
+            let stageArgs = buildListArgs(stage);
+            // Discard partial results from a rejected attempt
+            entries = [];
+            statusMap = new Map();
+            specialUseMatches = {};
+            try {
+                await runList(normalizedReference, normalizedMailbox, stageArgs);
+                if (lastRejectedStage) {
+                    // Latch only the option group that was present in the rejected
+                    // attempt but missing from this successful one - that group is
+                    // proven to be what the server rejects. An unproven group (e.g.
+                    // SUBSCRIBED when both groups were dropped one by one) is decided
+                    // by the reduced stage list of the next listing.
+                    if (lastRejectedStage.subscribed && !stage.subscribed) {
+                        connection.skipListSubscribedArg = true;
+                    }
+                    if (lastRejectedStage.status && !stage.status) {
+                        connection.skipListStatusArgs = true;
+                    }
+                    if (
+                        stageHasAuxArgs(lastRejectedStage) &&
+                        stage.aux === false &&
+                        lastRejectedStage.status === stage.status &&
+                        lastRejectedStage.subscribed === stage.subscribed
+                    ) {
+                        // Same option groups, only the auxiliary args dropped - the
+                        // auxiliaries are proven to be what the server rejects
+                        connection.skipListAuxArgs = true;
+                    }
+                }
+                successStage = stage;
+                break;
+            } catch (err) {
+                if (i === stages.length - 1 || !isRejectedCommand(err)) {
+                    throw err;
+                }
+                lastRejectedStage = stage;
+                if (!auxRetryInserted && stageHasAuxArgs(stage)) {
+                    // The rejection may be about the auxiliary options rather than the
+                    // option groups - try the same groups without the auxiliaries before
+                    // dropping a group
+                    stages.splice(i + 1, 0, { ...stage, aux: false });
+                    auxRetryInserted = true;
+                }
+                connection.log.warn({ msg: 'LIST RETURN options rejected, retrying with reduced options', err, cid: connection.id });
+            }
+        }
 
         if (options.listOnly) {
             return entries;
@@ -248,17 +360,55 @@ module.exports = async (connection, reference, mailbox, options) => {
         // When listing with a namespace prefix (e.g., "INBOX."), INBOX itself may
         // not appear in results. Run a separate LIST for INBOX to ensure it's included.
         if (normalizedReference && !specialUseMatches['\\Inbox']) {
-            await runList('', 'INBOX');
+            let returnArgs = buildListArgs(successStage);
+            // Snapshot the accumulator sizes: a rejected fixup attempt may have
+            // streamed partial untagged responses before its tagged BAD, and those
+            // must be discarded before the retry or INBOX would be listed twice -
+            // while the main run's results must be kept
+            let entryCountBefore = entries.length;
+            let specialUseCountsBefore = {};
+            for (let type of Object.keys(specialUseMatches)) {
+                specialUseCountsBefore[type] = specialUseMatches[type].length;
+            }
+            try {
+                await runList('', 'INBOX', returnArgs);
+            } catch (err) {
+                // The main listing just succeeded with the same RETURN options, so a
+                // rejection here says nothing about the options themselves - retry
+                // this one call plain without latching any skip flags. Accepted edge:
+                // if the main run filled statusMap, INBOX ends up without inline
+                // status data.
+                if (!returnArgs.length || !isRejectedCommand(err)) {
+                    throw err;
+                }
+                entries.length = entryCountBefore;
+                for (let type of Object.keys(specialUseMatches)) {
+                    if (!(type in specialUseCountsBefore)) {
+                        delete specialUseMatches[type];
+                    } else {
+                        specialUseMatches[type].length = specialUseCountsBefore[type];
+                    }
+                }
+                connection.log.warn({ msg: 'INBOX LIST with RETURN options failed, retrying plain', err, cid: connection.id });
+                await runList('', 'INBOX', []);
+            }
         }
 
         // Attach STATUS data to each selectable mailbox. If LIST-STATUS was used,
         // data is already in statusMap; otherwise, fall back to individual STATUS commands.
         if (options.statusQuery) {
+            // RECENT does not exist in IMAP4rev2, so it is never requested from a rev2
+            // session - its defined value there is always 0 (the STATUS command module
+            // applies the same rule on the per-mailbox fallback path)
+            let syntheticRecent = options.statusQuery.recent && isRev2Active(connection);
             for (let entry of entries) {
                 // \\Noselect and \\NonExistent mailboxes cannot hold messages
                 if (!entry.flags.has('\\Noselect') && !entry.flags.has('\\NonExistent')) {
                     if (statusMap.has(entry.path)) {
                         entry.status = statusMap.get(entry.path);
+                        if (syntheticRecent) {
+                            entry.status.recent = 0;
+                        }
                     } else if (!statusMap.size) {
                         // Server didn't support LIST-STATUS; fall back to per-mailbox STATUS
                         try {
@@ -275,10 +425,8 @@ module.exports = async (connection, reference, mailbox, options) => {
         // We merge subscription info into the entries already collected from LIST.
         // Subscribed-only mailboxes that weren't in LIST are intentionally ignored
         // (they may be phantom entries from old subscriptions to deleted mailboxes).
-        response = await connection.exec(
-            'LSUB',
-            [encodePath(connection, normalizePath(connection, reference || '')), encodePath(connection, normalizePath(connection, mailbox || '', true))],
-            {
+        let runLsub = async () => {
+            let response = await connection.exec('LSUB', [encodePath(connection, normalizedReference), encodePath(connection, normalizedMailbox)], {
                 untagged: {
                     LSUB: async untagged => {
                         if (!untagged.attributes || !untagged.attributes.length) {
@@ -316,9 +464,35 @@ module.exports = async (connection, reference, mailbox, options) => {
                         // Non-listed subscribed folders are intentionally ignored
                     }
                 }
+            });
+            response.next();
+        };
+
+        // Skipped when RETURN (SUBSCRIBED) already provided subscription state or when
+        // this connection's server already rejected LSUB once. Safety net: if the
+        // extended LIST was accepted but not a single mailbox came back subscribed on a
+        // non-rev2 session, assume the server silently ignored RETURN (SUBSCRIBED) and
+        // fall back to LSUB anyway (a rev2 session has no LSUB to fall back to, and an
+        // account without any subscriptions legitimately looks the same).
+        let needsLsub = !successStage.subscribed || (!isRev2Active(connection) && !entries.some(entry => entry.subscribed));
+        if (needsLsub && !connection.skipLsub) {
+            try {
+                await runLsub();
+            } catch (err) {
+                if (isRejectedCommand(err)) {
+                    // Tagged BAD: the server does not recognize the command (IMAP4rev2
+                    // removed LSUB) - skip LSUB for the rest of this connection
+                    connection.skipLsub = true;
+                } else if (err.responseStatus !== 'NO' || err.code === 'ETHROTTLE') {
+                    // Transport failures and throttling: rethrow, every follow-up
+                    // command would fail too or the caller needs to back off
+                    throw err;
+                }
+                // Subscription state is auxiliary - keep the LIST results usable. A
+                // tagged NO is treated as transient, so the next listing tries again.
+                connection.log.warn({ msg: 'Failed to request subscription info', err, cid: connection.id });
             }
-        );
-        response.next();
+        }
 
         // Resolve special-use conflicts: for each type, pick the best candidate
         // based on source priority (user > extension > name), then alphabetically.
@@ -372,6 +546,9 @@ module.exports = async (connection, reference, mailbox, options) => {
             return a.path.localeCompare(b.path);
         });
     } catch (err) {
+        // Rewrite the parsed err.response into the response text and set
+        // serverResponseCode, same as the other command modules
+        await enhanceCommandError(err);
         connection.log.warn({ msg: 'Failed to list folders', err, cid: connection.id });
         throw err;
     }

package/lib/commands/move.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { normalizePath, encodePath, enhanceCommandError } = require('../tools.js');
+const { normalizePath, encodePath, enhanceCommandError, hasCapability } = require('../tools.js');
 const { parseCopyUid } = require('./copyuid-parser.js');
 
 /**
@@ -31,7 +31,7 @@ module.exports = async (connection, range, destination, options) => {
 
     // Fallback for servers without the MOVE extension (RFC 6851):
     // emulate MOVE using COPY + flag as \Deleted + EXPUNGE.
-    if (!connection.capabilities.has('MOVE')) {
+    if (!hasCapability(connection, 'MOVE')) {
         let result = await connection.messageCopy(range, destination, options);
         await connection.messageDelete(range, Object.assign({ silent: true }, options));
         return result;

package/lib/commands/namespace.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { hasCapability } = require('../tools.js');
+
 /**
  * Requests NAMESPACE info from the server.
  *
@@ -12,7 +14,7 @@ module.exports = async connection => {
         return;
     }
 
-    if (!connection.capabilities.has('NAMESPACE')) {
+    if (!hasCapability(connection, 'NAMESPACE')) {
         // Fallback: when the server does not support the NAMESPACE extension (RFC 2342),
         // derive the prefix and delimiter from a LIST "" "" command, which returns
         // the hierarchy delimiter and root name for the default mailbox hierarchy.