imapflow 1.4.8 → 1.5.0

package/.github/workflows/test.yml

@@ -29,3 +29,23 @@ jobs:
                   cache: npm
             - run: npm install
             - run: npm test
+
+    test-rev2:
+        # Live IMAP4rev2 integration tests against a real Dovecot 2.4 server in
+        # Docker on linux/amd64 (ubuntu runners are amd64 with Docker preinstalled).
+        # This is the only place the suite runs on amd64 - Apple Silicon dev
+        # machines cannot run the amd64 image under Rosetta.
+        name: Live IMAP4rev2 tests (Dovecot, linux/amd64)
+        timeout-minutes: 15
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v6
+            - name: Use Node.js 24.x
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 24.x
+                  cache: npm
+            - run: npm install
+            - run: npm run test:rev2
+              env:
+                  IMAPFLOW_DOVECOT_PLATFORM: linux/amd64

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.5.0](https://github.com/postalsys/imapflow/compare/v1.4.9...v1.5.0) (2026-07-23)
+
+
+### Features
+
+* add STATUS SIZE/DELETED and rev2 BINARY fetch support, fix protocol bugs found in an RFC 9051 review ([04f5bf6](https://github.com/postalsys/imapflow/commit/04f5bf6c1a49e155dd23b2af062e570530b814b1))
+
+## [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)
 
 

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
@@ -72,7 +81,7 @@ CommonJS-compatible:
     1. Run `npm run format` and `npm run lint`
     2. Run `npm test` and keep it green
     3. For non-trivial changes, run `/simplify` to review changed code and `/security-review` to check for security issues before committing
-- After pushing, check the GitHub Actions runs for the push (e.g. `gh run list --branch master`) and report their status, including the CodeQL "CodeQL Advanced" code-scanning run. If a run fails for a strange or unrelated reason (for example a checkout step reporting "account suspended", HTTP 403, or other auth/infrastructure errors that have nothing to do with the change), check <https://www.githubstatus.com/> for an active GitHub incident before assuming the failure is caused by the change.
+- After pushing, check the GitHub Actions runs for the push (e.g. `gh run list --branch master`) and report their status. If a run fails for a strange or unrelated reason (for example a checkout step reporting "account suspended", HTTP 403, or other auth/infrastructure errors that have nothing to do with the change), check <https://www.githubstatus.com/> for an active GitHub incident before assuming the failure is caused by the change.
 
 ## Relationship to EmailEngine
 
@@ -88,9 +97,7 @@ Packaging Constraints).
 ## Security
 
 Security policy and private reporting channels are documented in
-[`SECURITY.md`](SECURITY.md) / [`SECURITY.txt`](SECURITY.txt). Code scanning runs
-through the "CodeQL Advanced" GitHub Actions workflow
-(`.github/workflows/codeql.yml`, config in `.github/codeql/codeql-config.yml`).
+[`SECURITY.md`](SECURITY.md) / [`SECURITY.txt`](SECURITY.txt).
 
 ## Release Process
 

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

@@ -45,9 +45,14 @@ async function authOauth(connection, username, accessToken) {
         // `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'
-        );
+        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/fetch.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { formatMessageResponse } = require('../tools');
+const { formatMessageResponse, isRev2Active } = require('../tools');
 
 /**
  * Fetches emails from the server.
@@ -25,8 +25,12 @@ module.exports = async (connection, range, query, options) => {
 
     let mailbox = connection.mailbox;
 
-    // Use BINARY extension for fetching if supported and requested, otherwise fall back to BODY
-    const commandKey = connection.capabilities.has('BINARY') && options.binary && !connection.disableBinary ? 'BINARY' : 'BODY';
+    // Use BINARY extension for fetching if supported and requested, otherwise fall back to BODY.
+    // RFC 9051 folds the FETCH side of the BINARY extension into base IMAP4rev2, so an active
+    // rev2 session can use it even without the BINARY capability token (the APPEND side is NOT
+    // folded in and stays gated on the token in append.js)
+    const canUseBinary = connection.capabilities.has('BINARY') || isRev2Active(connection);
+    const commandKey = canUseBinary && options.binary && !connection.disableBinary ? 'BINARY' : 'BODY';
 
     // Retry logic for ETHROTTLE errors (server rate limiting) with exponential backoff
     let retryCount = 0;
@@ -50,21 +54,21 @@ module.exports = async (connection, range, query, options) => {
             // PEEK avoids marking messages as \Seen. Section identifies what to fetch (HEADER, specific part, etc.)
             // Partial is an optional byte range [start, maxLength].
             let setBodyPeek = (attributes, partial) => {
+                let section = [].concat(attributes || []);
+
+                // BINARY may only address the empty section or a numeric part specifier
+                // (RFC 3516 / RFC 9051 section-binary) - HEADER, HEADER.FIELDS, TEXT and
+                // n.MIME are invalid after BINARY and must stay BODY fetches
+                let binaryAddressable =
+                    !section.length || (section.length === 1 && typeof section[0].value === 'string' && /^\d+(\.\d+)*$/.test(section[0].value));
+
                 let bodyPeek = {
                     type: 'ATOM',
-                    value: `${commandKey}.PEEK`,
-                    section: [],
+                    value: `${binaryAddressable ? commandKey : 'BODY'}.PEEK`,
+                    section,
                     partial
                 };
 
-                if (Array.isArray(attributes)) {
-                    attributes.forEach(attribute => {
-                        bodyPeek.section.push(attribute);
-                    });
-                } else if (attributes) {
-                    bodyPeek.section.push(attributes);
-                }
-
                 queryStructure.push(bodyPeek);
             };
 
@@ -88,7 +92,7 @@ module.exports = async (connection, range, query, options) => {
                         partial.push(Number(query.source.maxLength));
                     }
                 }
-                queryStructure.push({ type: 'ATOM', value: `${commandKey}.PEEK`, section: [], partial });
+                setBodyPeek(null, partial);
             }
 
             // Always request a unique email ID for message deduplication.

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