imapflow 1.4.9 → 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.9"
+    ".": "1.5.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

package/CLAUDE.md

@@ -81,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
 
@@ -97,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/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/list.js

@@ -235,7 +235,10 @@ module.exports = async (connection, reference, mailbox, options) => {
                             UIDNEXT: { key: 'uidNext', parser: Number },
                             UIDVALIDITY: { key: 'uidValidity', parser: BigInt },
                             UNSEEN: { key: 'unseen', parser: Number },
-                            HIGHESTMODSEQ: { key: 'highestModseq', parser: BigInt }
+                            HIGHESTMODSEQ: { key: 'highestModseq', parser: BigInt },
+                            // IMAP4rev2 additions (RFC 9051): mailbox size and \Deleted count
+                            SIZE: { key: 'size', parser: Number },
+                            DELETED: { key: 'deleted', parser: Number }
                         };
 
                         let key;

package/lib/commands/status.js

@@ -86,7 +86,12 @@ module.exports = async (connection, path, query) => {
                             updateMailbox: (val, conn) => {
                                 conn.mailbox.highestModseq = val;
                             }
-                        }
+                        },
+                        // IMAP4rev2 additions (RFC 9051): total mailbox size in octets
+                        // (number64, exact as a JS number up to 2^53-1) and count of
+                        // messages with the \Deleted flag
+                        SIZE: { key: 'size', parser: Number },
+                        DELETED: { key: 'deleted', parser: Number }
                     };
 
                     let key;

package/lib/handler/imap-compiler.js

@@ -130,15 +130,18 @@ module.exports = async (response, options) => {
                 if (isLogging) {
                     resp.push(formatRespEntry('"(* ' + node.value.length + 'B literal *)"'));
                 } else {
-                    let literalLength = !node.value ? 0 : Math.max(node.value.length, 0);
-
-                    // canAppend: whether the literal data can be sent in the same buffer segment.
-                    // With LITERAL+ (RFC 7888) the client does not wait for a continuation response.
-                    // With LITERAL- (RFC 7888) the client can skip the wait only for literals <= 4096 bytes.
-                    // When asArray is false we always append inline (single-buffer mode).
-                    let canAppend = !asArray || literalPlus || (literalMinus && literalLength <= 4096);
-                    // Append '+' to the size marker when using LITERAL+ or LITERAL- (non-synchronizing)
-                    let usePlus = canAppend && (literalMinus || literalPlus);
+                    // The literal size marker counts octets - string values are written as
+                    // UTF-8, so their UTF-16 .length would undercount multi-byte characters
+                    let literalLength = !node.value ? 0 : Buffer.isBuffer(node.value) ? node.value.length : Buffer.byteLength(node.value.toString());
+
+                    // Append '+' to the size marker only when the extension actually permits a
+                    // non-synchronizing literal of this size (RFC 7888): LITERAL+ always,
+                    // LITERAL- only up to 4096 bytes
+                    let usePlus = literalPlus || (literalMinus && literalLength <= 4096);
+                    // canAppend: whether the literal data can be sent in the same buffer segment -
+                    // non-synchronizing literals always, and everything in single-buffer mode
+                    // (asArray false), which has no continuation flow
+                    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`));

package/lib/handler/token-parser.js

@@ -580,6 +580,13 @@ class TokenParser {
                         if (!this.currentNode.literalLength) {
                             // special case where literal content length is 0
                             // close the node right away, do not wait for additional input
+                            if (this.options.literals && this.options.literals.length) {
+                                // ImapStream queues a Buffer for every literal marker it
+                                // extracts, including {0} - consume the queue entry so
+                                // subsequent literals in the same response stay aligned
+                                // with their markers instead of shifting by one
+                                this.currentNode.value = this.options.literals.shift();
+                            }
                             this.currentNode.endPos = this.pos + i;
                             this.currentNode.isClosed = true;
                             this.currentNode = this.currentNode.parentNode;

package/lib/imap-flow.d.ts

@@ -207,6 +207,10 @@ export interface ListOptions {
         unseen?: boolean;
         /** If true request last known modseq value */
         highestModseq?: boolean;
+        /** If true request total mailbox size in octets (requires STATUS=SIZE or IMAP4rev2) */
+        size?: boolean;
+        /** If true request count of messages with \Deleted flag (requires IMAP4rev2) */
+        deleted?: boolean;
     };
     /** Set specific paths as special use folders */
     specialUseHints?: {
@@ -282,6 +286,10 @@ export interface StatusObject {
     unseen?: number;
     /** Last known modseq value (if CONDSTORE extension is enabled) */
     highestModseq?: bigint;
+    /** Total size of the mailbox in octets (only if requested and the server supports STATUS=SIZE or IMAP4rev2) */
+    size?: number;
+    /** Count of messages with \Deleted flag (only if requested and IMAP4rev2 is active) */
+    deleted?: number;
 }
 
 export type SequenceString = string | number | bigint;
@@ -493,6 +501,8 @@ export interface FetchMessageObject {
     internalDate?: Date | string;
     /** A Map of message body parts where key is requested part identifier and value is a Buffer */
     bodyParts?: Map<string, Buffer>;
+    /** Part identifiers from bodyParts that arrived via FETCH BINARY, i.e. with the content-transfer-encoding already decoded by the server */
+    binaryParts?: Set<string>;
     /** Requested header lines as Buffer */
     headers?: Buffer;
     /** Account unique ID for this email */
@@ -755,6 +765,10 @@ export class ImapFlow extends EventEmitter {
             uidValidity?: boolean;
             unseen?: boolean;
             highestModseq?: boolean;
+            /** Requires STATUS=SIZE or IMAP4rev2 */
+            size?: boolean;
+            /** Requires IMAP4rev2 */
+            deleted?: boolean;
         }
     ): Promise<StatusObject>;
 

package/lib/imap-flow.js

@@ -1541,6 +1541,9 @@ class ImapFlow extends EventEmitter {
             return;
         }
         this.state = this.states.AUTHENTICATED;
+        // documented contract for the `authenticated` property: `true` when the
+        // connection was authenticated by a PREAUTH greeting (no credentials known)
+        this.authenticated = true;
         this.beginSession(err => {
             this.log.error({ err, cid: this.id });
             this.closeAfter();
@@ -2258,6 +2261,8 @@ class ImapFlow extends EventEmitter {
      * @property {Boolean} [statusQuery.uidValidity] if `true` request mailbox `UIDVALIDITY` value
      * @property {Boolean} [statusQuery.unseen] if `true` request count of unseen messages
      * @property {Boolean} [statusQuery.highestModseq] if `true` request last known modseq value
+     * @property {Boolean} [statusQuery.size] if `true` request total mailbox size in octets (requires STATUS=SIZE or IMAP4rev2)
+     * @property {Boolean} [statusQuery.deleted] if `true` request count of messages with \\Deleted flag (requires IMAP4rev2)
      * @property {Object} [specialUseHints] set specific paths as special use folders, this would override special use flags provided from the server
      * @property {String} [specialUseHints.sent] Path to "Sent Mail" folder
      * @property {String} [specialUseHints.trash] Path to "Trash" folder
@@ -2462,6 +2467,8 @@ class ImapFlow extends EventEmitter {
      * @property {BigInt} [uidValidity] Mailbox `UIDVALIDITY` value
      * @property {Number} [unseen] Count of unseen messages
      * @property {BigInt} [highestModseq] Last known modseq value (if CONDSTORE extension is enabled)
+     * @property {Number} [size] Total size of the mailbox in octets (only if requested and the server supports STATUS=SIZE or IMAP4rev2)
+     * @property {Number} [deleted] Count of messages with \\Deleted flag (only if requested and IMAP4rev2 is active)
      */
 
     /**
@@ -2475,6 +2482,8 @@ class ImapFlow extends EventEmitter {
      * @param {Boolean} query.uidValidity if `true` request mailbox `UIDVALIDITY` value
      * @param {Boolean} query.unseen if `true` request count of unseen messages
      * @param {Boolean} query.highestModseq if `true` request last known modseq value
+     * @param {Boolean} query.size if `true` request total mailbox size in octets (requires STATUS=SIZE or IMAP4rev2)
+     * @param {Boolean} query.deleted if `true` request count of messages with \\Deleted flag (requires IMAP4rev2)
      * @returns {Promise<StatusObject>} status of the indicated mailbox
      *
      * @example
@@ -2969,6 +2978,7 @@ class ImapFlow extends EventEmitter {
      * @property {MessageStructureObject} [bodyStructure] message body structure
      * @property {Date} [internalDate] message internal date
      * @property {Map<string, Buffer>} [bodyParts] a Map of message body parts where key is requested part identifier and value is a Buffer
+     * @property {Set<string>} [binaryParts] part identifiers from `bodyParts` that arrived via FETCH BINARY, i.e. with the content-transfer-encoding already decoded by the server
      * @property {Buffer} [headers] Requested header lines as Buffer
      */
 
@@ -3403,7 +3413,11 @@ class ImapFlow extends EventEmitter {
         //   4. Byte limiter (enforces maxBytes cap)
         // `stream` is the head of the pipeline (where raw chunks are written),
         // `output` is the tail (what the caller reads from).
-        switch (meta.encoding) {
+        // Parts that arrived via FETCH BINARY (response.binaryParts) are already
+        // decoded by the server - decoding again would corrupt the data, so stage 1
+        // is skipped for them.
+        let clientEncoding = response.binaryParts && response.binaryParts.has(part) ? false : meta.encoding;
+        switch (clientEncoding) {
             case 'base64':
                 output = stream = new libbase64.Decoder();
                 break;
@@ -3713,7 +3727,10 @@ class ImapFlow extends EventEmitter {
         for (let part of Object.keys(data)) {
             let meta = data[part].meta;
 
-            switch (meta.encoding) {
+            // parts that arrived via FETCH BINARY (response.binaryParts) are already
+            // decoded by the server - decoding again would corrupt the data
+            let clientEncoding = response.binaryParts && response.binaryParts.has(part) ? false : meta.encoding;
+            switch (clientEncoding) {
                 case 'base64':
                     data[part].content = data[part].content ? libbase64.decode(data[part].content.toString()) : null;
                     break;

package/lib/tools.js

@@ -19,9 +19,10 @@ 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,
-// and the BINARY consumers have safe fallbacks of their own. 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.
+// 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',
@@ -115,6 +116,24 @@ const tools = {
                         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;
             }
         });
 
@@ -591,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;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.4.9",
+    "version": "1.5.0",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",