imapflow 1.6.5 → 1.6.6

package/lib/commands/status-fields.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const { parseBigIntValue, parseUintValue, MAX_UINT32_DIGITS } = require('../tools.js');
+
+// STATUS data items (RFC 3501 section 6.3.10, RFC 7162 for HIGHESTMODSEQ, RFC 9051 for SIZE
+// and DELETED) mapped to the property name each one is exposed under, together with the
+// parser that turns the raw response token into a usable value. Shared by the STATUS command
+// and by the inline STATUS responses of LIST-STATUS (RFC 5819) so the two cannot drift apart.
+//
+// Every parser rejects anything that is not a bounded decimal digit run, returning false.
+// These values are server-controlled and several of them are written straight into the live
+// mailbox state, where a NaN or a value coerced to Infinity corrupts every later range
+// computation. A plain isNaN() test is not enough: it passes '1e5', ' 12 ' and 'Infinity',
+// and BigInt() throws on all three, aborting the walk over the remaining fields.
+const uint32 = value => parseUintValue(value, MAX_UINT32_DIGITS);
+
+const STATUS_FIELDS = {
+    MESSAGES: { key: 'messages', parser: uint32 },
+    RECENT: { key: 'recent', parser: uint32 },
+    UIDNEXT: { key: 'uidNext', parser: uint32 },
+    // Nominally 32-bit, but stored as a BigInt precisely so a server that exceeds that still
+    // round-trips, so the wider bound applies
+    UIDVALIDITY: { key: 'uidValidity', parser: value => parseBigIntValue(value) },
+    UNSEEN: { key: 'unseen', parser: uint32 },
+    HIGHESTMODSEQ: { key: 'highestModseq', parser: value => parseBigIntValue(value) },
+    // IMAP4rev2 additions (RFC 9051): total mailbox size in octets (number64, exact as a JS
+    // number up to 2^53-1) and count of messages carrying the \Deleted flag
+    SIZE: { key: 'size', parser: value => parseUintValue(value) },
+    DELETED: { key: 'deleted', parser: uint32 }
+};
+
+/**
+ * Walks a STATUS data-item list - alternating item-name and item-value tokens - and reports
+ * every recognized field that parsed successfully. Unknown item names and unusable values are
+ * skipped, so one bad field never costs the rest of the response.
+ *
+ * @param {Array} list - Parsed attribute list from the untagged STATUS response.
+ * @param {Function} onField - Called as (key, value) for each usable field.
+ */
+const parseStatusList = (list, onField) => {
+    let name;
+    list.forEach((entry, i) => {
+        if (i % 2 === 0) {
+            name = entry && typeof entry.value === 'string' ? entry.value : false;
+            return;
+        }
+
+        if (!name || !entry) {
+            return;
+        }
+
+        // The item name is server-controlled, but uppercasing it before the lookup means no
+        // Object.prototype member can be reached: every builtin name has a lowercase letter.
+        const field = STATUS_FIELDS[name.toUpperCase()];
+        if (!field) {
+            return;
+        }
+
+        const value = field.parser(entry.value);
+        if (value === false) {
+            return;
+        }
+
+        onField(field.key, value);
+    });
+};
+
+module.exports = { parseStatusList };

package/lib/commands/status.js

@@ -1,6 +1,25 @@
 'use strict';
 
 const { encodePath, normalizePath, buildStatusQueryAttributes, isRev2Active } = require('../tools.js');
+const { parseStatusList } = require('./status-fields.js');
+
+// STATUS fields that also refresh the live mailbox state when the queried mailbox is the
+// currently selected one. Keyed by the output property name parseStatusList() reports.
+const MAILBOX_UPDATERS = {
+    messages: (value, connection, path) => {
+        let prevCount = connection.mailbox.exists;
+        if (prevCount !== value) {
+            connection.mailbox.exists = value;
+            connection.emit('exists', { path, count: value, prevCount });
+        }
+    },
+    uidNext: (value, connection) => {
+        connection.mailbox.uidNext = value;
+    },
+    highestModseq: (value, connection) => {
+        connection.mailbox.highestModseq = value;
+    }
+};
 
 /**
  * Requests status information about a mailbox.
@@ -56,68 +75,11 @@ module.exports = async (connection, path, query) => {
                     if (!list) {
                         return;
                     }
-                    // Maps IMAP STATUS field names to their output key names, type parsers,
-                    // and optional callbacks to update the live mailbox state.
-                    const STATUS_FIELD_MAP = {
-                        MESSAGES: {
-                            key: 'messages',
-                            parser: Number,
-                            updateMailbox: (val, conn) => {
-                                let prevCount = conn.mailbox.exists;
-                                if (prevCount !== val) {
-                                    conn.mailbox.exists = val;
-                                    conn.emit('exists', { path, count: val, prevCount });
-                                }
-                            }
-                        },
-                        RECENT: { key: 'recent', parser: Number },
-                        UIDNEXT: {
-                            key: 'uidNext',
-                            parser: Number,
-                            updateMailbox: (val, conn) => {
-                                conn.mailbox.uidNext = val;
-                            }
-                        },
-                        UIDVALIDITY: { key: 'uidValidity', parser: BigInt },
-                        UNSEEN: { key: 'unseen', parser: Number },
-                        HIGHESTMODSEQ: {
-                            key: 'highestModseq',
-                            parser: BigInt,
-                            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;
-                    list.forEach((entry, i) => {
-                        if (i % 2 === 0) {
-                            key = entry && typeof entry.value === 'string' ? entry.value : false;
-                            return;
-                        }
-                        if (!key || !entry || typeof entry.value !== 'string') {
-                            return;
-                        }
-
-                        const fieldConfig = STATUS_FIELD_MAP[key.toUpperCase()];
-                        if (!fieldConfig) {
-                            return;
-                        }
-
-                        const value = !isNaN(entry.value) ? fieldConfig.parser(entry.value) : false;
-                        if (value === false) {
-                            return;
-                        }
-
-                        map[fieldConfig.key] = value;
+                    parseStatusList(list, (key, value) => {
+                        map[key] = value;
 
-                        if (updateCurrent && fieldConfig.updateMailbox) {
-                            fieldConfig.updateMailbox(value, connection);
+                        if (updateCurrent && MAILBOX_UPDATERS[key]) {
+                            MAILBOX_UPDATERS[key](value, connection, path);
                         }
                     });
                 }

package/lib/handler/imap-stream.js

@@ -2,7 +2,7 @@
 
 const Transform = require('stream').Transform;
 const logger = require('../logger');
-const { MAX_LITERAL_SIZE, MAX_LINE_SIZE, normalizeLimit, createLiteralTooLargeError } = require('./limits');
+const { MAX_LITERAL_SIZE, MAX_LINE_SIZE, MAX_RESPONSE_SIZE, normalizeLimit, createLiteralTooLargeError } = require('./limits');
 
 const LINE = 0x01;
 const LITERAL = 0x02;
@@ -44,6 +44,16 @@ class ImapStream extends Transform {
      *   exactly at the limit is accepted. Exceeding it is terminal: the stream is destroyed with a
      *   `LiteralTooLarge` error, the marker line is not emitted, and no byte of the rejected
      *   literal body is parsed as protocol.
+     * @param {number} [options.maxResponseSize] - Maximum allowed total size (in bytes) of a
+     *   single assembled response: every line segment and literal of one response combined.
+     *   Defaults to MAX_RESPONSE_SIZE (2GB), which leaves room above the literal cap for a
+     *   maximum-size literal plus its marker line. The per-line and per-literal caps alone
+     *   cannot stop a server that spreads attacker-controlled bytes across an unbounded
+     *   number of tokens of a single response. Declared literal sizes count when their
+     *   marker is parsed, so an oversized total is rejected before the literal bytes arrive,
+     *   and a line still being assembled counts against whatever budget is left.
+     *   Exceeding the limit is terminal: the stream is destroyed with a `ResponseTooLarge`
+     *   error and no further input is parsed.
      */
     constructor(options) {
         super({
@@ -73,6 +83,8 @@ class ImapStream extends Transform {
         // announcing an oversized literal cannot exhaust memory.
         this.maxLiteralSize = normalizeLimit(this.options.maxLiteralSize, MAX_LITERAL_SIZE);
 
+        this.maxResponseSize = normalizeLimit(this.options.maxResponseSize, MAX_RESPONSE_SIZE);
+
         this.state = LINE;
         this.literalWaiting = 0;
         this.inputBuffer = []; // lines
@@ -80,6 +92,7 @@ class ImapStream extends Transform {
         this.lineBytes = 0; // bytes currently buffered for the in-progress line
         this.literalBuffer = [];
         this.literals = [];
+        this.responseBytes = 0; // bytes accumulated for the in-progress response (lines + declared literals)
 
         this.compress = false;
         this.secureConnection = this.options.secureConnection;
@@ -228,6 +241,33 @@ class ImapStream extends Transform {
         return this.failStream(err);
     }
 
+    /**
+     * Enforces the configured per-response size cap: the cumulative bytes of every line
+     * segment and declared literal of the response currently being assembled. Counting
+     * declared literal sizes at marker time means an oversized total is rejected before
+     * the literal bytes even arrive. The counter is reset when a response is emitted.
+     *
+     * @param {number} additionalBytes - Bytes the next token would add to the response.
+     * @param {boolean} [peek] - Measure only, without committing the bytes to the counter.
+     *   Used for a line that is still being assembled: its bytes are committed once, when the
+     *   line completes.
+     * @returns {boolean} True if within the limit, false if the stream was failed.
+     */
+    checkResponseSize(additionalBytes, peek) {
+        let total = this.responseBytes + additionalBytes;
+        if (total <= this.maxResponseSize) {
+            if (!peek) {
+                this.responseBytes = total;
+            }
+            return true;
+        }
+        const err = new Error(`Response size ${total} exceeds maximum allowed size of ${this.maxResponseSize} bytes`);
+        err.code = 'ResponseTooLarge';
+        err.responseSize = total;
+        err.maxSize = this.maxResponseSize;
+        return this.failStream(err);
+    }
+
     /**
      * Processes a single input chunk of raw data. In LINE state, scans for LF-terminated
      * lines and checks for literal markers. In LITERAL state, collects the expected number
@@ -273,6 +313,13 @@ class ImapStream extends Transform {
                             return;
                         }
 
+                        // Count the line itself and, for a literal marker, the declared
+                        // literal bytes against the cumulative per-response budget, so a
+                        // response assembled from many tokens stays bounded as a whole
+                        if (!this.checkResponseSize(line.length + (isLiteralMarker ? this.literalWaiting : 0))) {
+                            return;
+                        }
+
                         this.inputBuffer.push(line);
 
                         if (isLiteralMarker) {
@@ -285,6 +332,7 @@ class ImapStream extends Transform {
                         let literals = this.literals;
                         this.inputBuffer = [];
                         this.literals = [];
+                        this.responseBytes = 0;
 
                         if (payload.length) {
                             // remove final line terminator (\n or \r\n)
@@ -323,7 +371,12 @@ class ImapStream extends Transform {
                     // No line terminator was found in the remaining bytes; carry the tail over to
                     // the next chunk after measuring the line it belongs to.
                     let tail = chunk.slice(lineStart);
-                    if (!this.checkLineLength(this.lineBytes + tail.length)) {
+                    // The response counter is only committed when a line completes, so an
+                    // in-progress line is measured against the remaining budget separately.
+                    // Without this a response cap lowered to bound parser memory buys nothing
+                    // while a server streams a line that never terminates - only the much
+                    // larger line cap would hold it back.
+                    if (!this.checkLineLength(this.lineBytes + tail.length) || !this.checkResponseSize(this.lineBytes + tail.length, true)) {
                         return;
                     }
                     this.lineBytes += tail.length;
@@ -453,6 +506,7 @@ class ImapStream extends Transform {
         this.lineBytes = 0;
         this.literalBuffer = [];
         this.literals = [];
+        this.responseBytes = 0;
 
         // Settle an in-flight push() wait so processInput() can unwind
         if (typeof this.pendingPush === 'function') {

package/lib/handler/limits.js

@@ -12,16 +12,28 @@ const MAX_LITERAL_SIZE = 1024 * 1024 * 1024;
 // only to stop a server that never sends a line terminator, not to constrain normal traffic.
 const MAX_LINE_SIZE = MAX_LITERAL_SIZE;
 
+// Default maximum total size of a single assembled response: every line segment and literal of
+// one response combined. The per-line and per-literal caps alone cannot stop a server that
+// spreads attacker-controlled bytes across an unbounded number of tokens of a single response
+// (e.g. one FETCH answer carrying many maximum-size literals).
+//
+// Deliberately above the literal cap: the response total also carries the literal's marker line
+// and the rest of the response framing, so a cap equal to MAX_LITERAL_SIZE would make a literal
+// of exactly the maximum permitted size impossible to receive. Configuring both limits calls for
+// the same headroom - set maxResponseSize above maxLiteralSize, not equal to it.
+const MAX_RESPONSE_SIZE = 2 * MAX_LITERAL_SIZE;
+
 /**
  * Normalizes a configured size limit. A non-negative integer is honored as-is (including 0, which
- * means "reject anything non-empty"); anything else falls back to the default, so an explicit 0 is
- * not silently swallowed the way `value || DEFAULT` would swallow it.
+ * means "reject anything non-empty"), and `Infinity` disables the limit; anything else falls back
+ * to the default, so an explicit 0 is not silently swallowed the way `value || DEFAULT` would
+ * swallow it.
  *
  * @param {*} value - The configured value.
  * @param {number} defaultValue - Fallback when the value is not a usable limit.
  * @returns {number} The normalized limit.
  */
-const normalizeLimit = (value, defaultValue) => (Number.isInteger(value) && value >= 0 ? value : defaultValue);
+const normalizeLimit = (value, defaultValue) => ((Number.isInteger(value) || value === Infinity) && value >= 0 ? value : defaultValue);
 
 /**
  * Builds the `LiteralTooLarge` error. One shape for every place a literal is refused, so callers
@@ -40,4 +52,4 @@ const createLiteralTooLargeError = (literalSize, maxSize, reason) => {
     return err;
 };
 
-module.exports = { MAX_LITERAL_SIZE, MAX_LINE_SIZE, normalizeLimit, createLiteralTooLargeError };
+module.exports = { MAX_LITERAL_SIZE, MAX_LINE_SIZE, MAX_RESPONSE_SIZE, normalizeLimit, createLiteralTooLargeError };

package/lib/imap-flow.d.ts

@@ -85,18 +85,34 @@ export interface ImapFlowOptions {
      * Maximum allowed length in bytes of a single response line (a response without a literal).
      * Guards against a malicious or broken server that never sends a line terminator. Defaults to
      * 1GB. The line terminator counts towards the limit and a line exactly at the limit is
-     * accepted. Exceeding it is terminal: the connection fails with error code `LineTooLarge` and
+     * accepted. `Infinity` disables the limit. An in-progress line is additionally bounded by
+     * whatever is left of `maxResponseSize`, so lowering that also bounds line buffering.
+     * Exceeding it is terminal: the connection fails with error code `LineTooLarge` and
      * no further input is parsed.
      */
     maxLineLength?: number;
     /**
      * Maximum allowed size in bytes of a single IMAP literal block. Bounds peak memory allocation
      * against a malicious or broken server announcing an oversized literal. Defaults to 1GB. A
-     * literal exactly at the limit is accepted. Exceeding it is terminal: the connection fails
+     * literal exactly at the limit is accepted, provided `maxResponseSize` leaves room for the
+     * marker line as the defaults do. `Infinity` disables the limit. Exceeding it is terminal: the connection fails
      * with error code `LiteralTooLarge`, and neither the marker line nor any byte of the rejected
      * literal is interpreted as protocol.
      */
     maxLiteralSize?: number;
+    /**
+     * Maximum allowed total size in bytes of a single assembled IMAP response (every line
+     * segment and literal of one response combined). Bounds peak memory allocation against
+     * a malicious or broken server that spreads response data across an unbounded number of
+     * tokens, which the per-line and per-literal caps alone cannot stop. Defaults to 2GB,
+     * which is above the default literal cap on purpose: the total also carries the literal
+     * marker line and the rest of the response framing, so a value equal to `maxLiteralSize`
+     * would make a literal of exactly the maximum permitted size impossible to receive. Set
+     * this above `maxLiteralSize` when configuring both. `Infinity` disables the limit.
+     * Exceeding it is terminal: the connection fails with error code `ResponseTooLarge` and
+     * no further input is parsed.
+     */
+    maxResponseSize?: number;
     /**
      * Threshold in milliseconds for warning that a mailbox lock has been held
      * for a long time (diagnostic for forgotten release() calls). Defaults to
@@ -145,6 +161,10 @@ export interface MailboxObject {
     uidNext: number;
     /** Messages in this folder */
     exists: number;
+    /** Sequence number of the first unseen message, if the server reported [UNSEEN] on SELECT. Not a count of unseen messages - use mailboxStatus() with {unseen: true} for that */
+    unseen?: number;
+    /** Largest message size in octets the server accepts for APPEND into this mailbox, if it reported [APPENDLIMIT] (RFC 7889) */
+    appendlimit?: number;
     /** Read-only state */
     readOnly?: boolean;
 }