imapflow 1.5.0 → 1.6.0

package/lib/handler/imap-stream.js

@@ -2,6 +2,7 @@
 
 const Transform = require('stream').Transform;
 const logger = require('../logger');
+const { MAX_LITERAL_SIZE, MAX_LINE_SIZE, normalizeLimit, createLiteralTooLargeError } = require('./limits');
 
 const LINE = 0x01;
 const LITERAL = 0x02;
@@ -13,14 +14,6 @@ const NUM_9 = 0x39;
 const CURLY_OPEN = 0x7b;
 const CURLY_CLOSE = 0x7d;
 
-// Maximum allowed literal size: 1GB (1073741824 bytes)
-const MAX_LITERAL_SIZE = 1024 * 1024 * 1024;
-
-// Default maximum length of a single line (a response without a literal). Matches the literal cap:
-// large literal-free responses (e.g. big SEARCH/LIST results) are legitimate, so this bound exists
-// only to stop a server that never sends a line terminator, not to constrain normal traffic.
-const MAX_LINE_SIZE = MAX_LITERAL_SIZE;
-
 /**
  * A Transform stream that parses raw IMAP protocol data from a socket into structured
  * command/response objects. Reads binary input, splits it into lines delimited by LF,
@@ -42,10 +35,15 @@ class ImapStream extends Transform {
      * @param {number} [options.maxLineLength] - Maximum allowed length (in bytes) of a single
      *   line (a response without a literal). Defaults to MAX_LITERAL_SIZE (1GB). Guards against a
      *   malicious or broken server that never sends a line terminator, which would otherwise grow
-     *   the internal line buffer without bound.
+     *   the internal line buffer without bound. The line terminator counts toward the limit, and a
+     *   line exactly at the limit is accepted. Exceeding it is terminal: the stream is destroyed
+     *   with a `LineTooLarge` error and no further input is parsed.
      * @param {number} [options.maxLiteralSize] - Maximum allowed size (in bytes) of a single
      *   literal block. Defaults to MAX_LITERAL_SIZE (1GB). Lower it to bound peak memory
-     *   allocation against a malicious or broken server announcing an oversized literal.
+     *   allocation against a malicious or broken server announcing an oversized literal. A literal
+     *   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.
      */
     constructor(options) {
         super({
@@ -68,16 +66,12 @@ class ImapStream extends Transform {
         this.readBytesCounter = 0;
 
         // Maximum length of a single line (response without a literal). Bounds the line buffer
-        // so a server that never sends a line terminator cannot exhaust memory. A non-negative
-        // integer is honored as-is (including 0); anything else falls back to the default, so an
-        // explicit 0 is not silently swallowed into the 1GB default the way `|| MAX_LINE_SIZE` was.
-        this.maxLineLength = Number.isInteger(this.options.maxLineLength) && this.options.maxLineLength >= 0 ? this.options.maxLineLength : MAX_LINE_SIZE;
+        // so a server that never sends a line terminator cannot exhaust memory.
+        this.maxLineLength = normalizeLimit(this.options.maxLineLength, MAX_LINE_SIZE);
 
         // Maximum size of a single literal block. Bounds peak memory allocation so a server
-        // announcing an oversized literal cannot exhaust memory. As above, a non-negative integer
-        // (including an explicit 0, meaning "reject all non-empty literals") is honored as-is.
-        this.maxLiteralSize =
-            Number.isInteger(this.options.maxLiteralSize) && this.options.maxLiteralSize >= 0 ? this.options.maxLiteralSize : MAX_LITERAL_SIZE;
+        // announcing an oversized literal cannot exhaust memory.
+        this.maxLiteralSize = normalizeLimit(this.options.maxLiteralSize, MAX_LITERAL_SIZE);
 
         this.state = LINE;
         this.literalWaiting = 0;
@@ -92,6 +86,52 @@ class ImapStream extends Transform {
 
         this.processingInput = false;
         this.inputQueue = []; // unprocessed input chunks
+        this.activeInput = null; // chunk currently being processed (already shifted off inputQueue)
+
+        // Resolver of the in-flight push() backpressure promise, so destruction can settle it
+        // instead of leaving processInput() awaiting a consumer that will never read again.
+        this.pendingPush = null;
+    }
+
+    /**
+     * Terminally fails the stream. Used for response limit violations and for any other
+     * error raised while parsing.
+     *
+     * The stream is destroyed instead of only emitting `error`: emitting on a Transform leaves
+     * it running, so the caller would keep scanning the rejected payload and could emit it as
+     * protocol (an oversized literal body contains attacker-chosen CRLF delimited lines).
+     * Destroying stops all parsing, drops the offending line, and releases every queued
+     * transform callback exactly once (see `_destroy()`).
+     *
+     * `destroyed` (set synchronously by destroy()) is the single liveness flag every other path
+     * checks, so a second failure attempt is a no-op and nothing is parsed after the first.
+     *
+     * @param {Error} err - The error to destroy the stream with.
+     * @returns {boolean} Always false, so callers can `return this.failStream(err)`.
+     */
+    failStream(err) {
+        if (this.destroyed) {
+            return false;
+        }
+        this.destroy(err);
+        return false;
+    }
+
+    /**
+     * Releases a queued input chunk's transform callback exactly once, signalling the writable
+     * side that the chunk was consumed. The mirror image of ImapFlow's releaseStreamData(), which
+     * releases the readable items this stream pushes downstream.
+     *
+     * @param {Object} item - Queue entry holding the chunk and its transform callback.
+     */
+    releaseInput(item) {
+        if (!item || item.released) {
+            return;
+        }
+        item.released = true;
+        if (typeof item.next === 'function') {
+            item.next();
+        }
     }
 
     /**
@@ -137,12 +177,7 @@ class ImapStream extends Transform {
                 const literalSize = Number(Buffer.from(numBytes).toString());
 
                 if (literalSize > this.maxLiteralSize) {
-                    const err = new Error(`Literal size ${literalSize} exceeds maximum allowed size of ${this.maxLiteralSize} bytes`);
-                    err.code = 'LiteralTooLarge';
-                    err.literalSize = literalSize;
-                    err.maxSize = this.maxLiteralSize;
-                    this.emit('error', err);
-                    return false;
+                    return this.failStream(createLiteralTooLargeError(literalSize, this.maxLiteralSize));
                 }
 
                 this.state = LITERAL;
@@ -154,6 +189,25 @@ class ImapStream extends Transform {
         return false;
     }
 
+    /**
+     * Enforces the configured line-length cap for a projected line length. The projected length
+     * covers every byte of the line, the line terminator included, whether or not the line was
+     * split across input chunks. A line exactly at the limit is accepted.
+     *
+     * @param {number} lineLength - Total length the current line would reach.
+     * @returns {boolean} True if the line is within the limit, false if the stream was failed.
+     */
+    checkLineLength(lineLength) {
+        if (lineLength <= this.maxLineLength) {
+            return true;
+        }
+        const err = new Error(`Line length ${lineLength} exceeds maximum allowed size of ${this.maxLineLength} bytes`);
+        err.code = 'LineTooLarge';
+        err.lineLength = lineLength;
+        err.maxSize = this.maxLineLength;
+        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
@@ -166,7 +220,7 @@ class ImapStream extends Transform {
      */
     async processInputChunk(chunk, startPos) {
         startPos = startPos || 0;
-        if (startPos >= chunk.length) {
+        if (this.destroyed || startPos >= chunk.length) {
             return;
         }
 
@@ -175,19 +229,34 @@ class ImapStream extends Transform {
                 let lineStart = startPos;
                 for (let i = startPos, len = chunk.length; i < len; i++) {
                     if (chunk[i] === LF) {
-                        // line end found
-                        this.lineBuffer.push(chunk.slice(lineStart, i + 1));
+                        // line end found. Measure the completed line (terminator included) before
+                        // concatenating or emitting anything, so the cap does not depend on where
+                        // TCP chunk boundaries happen to fall.
+                        let segment = chunk.slice(lineStart, i + 1);
+                        if (!this.checkLineLength(this.lineBytes + segment.length)) {
+                            return;
+                        }
+
+                        this.lineBuffer.push(segment);
                         lineStart = i + 1;
 
-                        let line = Buffer.concat(this.lineBuffer);
+                        let line = this.lineBuffer.length === 1 ? this.lineBuffer[0] : Buffer.concat(this.lineBuffer);
 
-                        this.inputBuffer.push(line);
                         this.lineBuffer = [];
                         this.lineBytes = 0;
 
-                        // try to detect if this is a literal start
-                        if (this.checkLiteralMarker(line)) {
-                            // switch into line mode and start over
+                        // try to detect if this is a literal start. An oversized literal fails the
+                        // stream, so the marker line must not be buffered before the check - it
+                        // would otherwise be emitted as part of the rejected command.
+                        let isLiteralMarker = this.checkLiteralMarker(line);
+                        if (this.destroyed) {
+                            return;
+                        }
+
+                        this.inputBuffer.push(line);
+
+                        if (isLiteralMarker) {
+                            // switch into literal mode and start over
                             return await this.processInputChunk(chunk, lineStart);
                         }
 
@@ -215,27 +284,29 @@ class ImapStream extends Transform {
                                 // boundaries can read it from the pushed object.
                                 let trailingAfterLine = lineStart < chunk.length || this.inputQueue.length > 0;
                                 await new Promise(resolve => {
+                                    // Tracked so destruction can settle the wait instead of leaving
+                                    // this loop (and the chunk's transform callback) pending forever
+                                    // when the consumer stops reading.
+                                    this.pendingPush = resolve;
                                     this.push({ payload, literals, next: resolve, trailingAfterLine });
                                 });
+                                this.pendingPush = null;
+
+                                if (this.destroyed) {
+                                    return;
+                                }
                             }
                         }
                     }
                 }
                 if (lineStart < chunk.length) {
                     // No line terminator was found in the remaining bytes; carry the tail over to
-                    // the next chunk. Enforce the line-length cap here, since this is the only
-                    // path that grows the line buffer across chunks.
+                    // the next chunk after measuring the line it belongs to.
                     let tail = chunk.slice(lineStart);
-                    let lineLength = this.lineBytes + tail.length;
-                    if (lineLength > this.maxLineLength) {
-                        const err = new Error(`Line length ${lineLength} exceeds maximum allowed size of ${this.maxLineLength} bytes`);
-                        err.code = 'LineTooLarge';
-                        err.lineLength = lineLength;
-                        err.maxSize = this.maxLineLength;
-                        this.emit('error', err);
+                    if (!this.checkLineLength(this.lineBytes + tail.length)) {
                         return;
                     }
-                    this.lineBytes = lineLength;
+                    this.lineBytes += tail.length;
                     this.lineBuffer.push(tail);
                 }
                 break;
@@ -273,10 +344,12 @@ class ImapStream extends Transform {
     async processInput() {
         let data;
         let processedCount = 0;
-        while ((data = this.inputQueue.shift())) {
+        while (!this.destroyed && (data = this.inputQueue.shift())) {
+            this.activeInput = data;
             await this.processInputChunk(data.chunk);
+            this.activeInput = null;
             // mark chunk as processed
-            data.next();
+            this.releaseInput(data);
 
             // Yield to event loop every 10 chunks to prevent CPU blocking
             processedCount++;
@@ -317,6 +390,12 @@ class ImapStream extends Transform {
             });
         }
 
+        // A terminal parser failure must not accept any more protocol input, even if the
+        // transport delivers a chunk that was already in flight.
+        if (this.destroyed) {
+            return next();
+        }
+
         // Queue the chunk for async processing. The 'next' callback serves as
         // backpressure: it is called only after this chunk is fully processed,
         // which signals the writable side that more data can be accepted.
@@ -325,7 +404,7 @@ class ImapStream extends Transform {
         if (!this.processingInput) {
             this.processingInput = true;
             this.processInput()
-                .catch(err => this.emit('error', err))
+                .catch(err => this.failStream(err))
                 .finally(() => (this.processingInput = false));
         }
     }
@@ -347,18 +426,30 @@ class ImapStream extends Transform {
      * @param {Function} callback - Callback to signal destruction completion.
      */
     _destroy(err, callback) {
+        // Destruction is the single release point for parser-owned callbacks, so a terminal
+        // failure can never leave the writable side or the processing loop waiting.
         this.inputBuffer = [];
         this.lineBuffer = [];
         this.lineBytes = 0;
         this.literalBuffer = [];
         this.literals = [];
-        // Clear inputQueue and call any pending callbacks
+
+        // Settle an in-flight push() wait so processInput() can unwind
+        if (typeof this.pendingPush === 'function') {
+            const resolve = this.pendingPush;
+            this.pendingPush = null;
+            resolve();
+        }
+
+        // Release the chunk currently being processed, then everything still queued.
+        // releaseInput() is idempotent, so the processing loop releasing the same chunk
+        // afterwards is a no-op.
+        this.releaseInput(this.activeInput);
+        this.activeInput = null;
         while (this.inputQueue.length) {
-            const item = this.inputQueue.shift();
-            if (typeof item.next === 'function') {
-                item.next();
-            }
+            this.releaseInput(this.inputQueue.shift());
         }
+
         callback(err);
     }
 }

package/lib/handler/limits.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// Shared response-size limits for the IMAP parser. Kept in one place so the streaming parser
+// (ImapStream) and the standalone token parser cannot drift apart, and so the documented
+// defaults in imap-flow.d.ts describe both paths.
+
+// Maximum allowed literal size: 1GB (1073741824 bytes)
+const MAX_LITERAL_SIZE = 1024 * 1024 * 1024;
+
+// Default maximum length of a single line (a response without a literal). Matches the literal cap:
+// large literal-free responses (e.g. big SEARCH/LIST results) are legitimate, so this bound exists
+// only to stop a server that never sends a line terminator, not to constrain normal traffic.
+const MAX_LINE_SIZE = 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.
+ *
+ * @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);
+
+/**
+ * Builds the `LiteralTooLarge` error. One shape for every place a literal is refused, so callers
+ * can rely on `code`, `literalSize` and `maxSize` regardless of which parser rejected it.
+ *
+ * @param {number} literalSize - The declared literal size.
+ * @param {number} maxSize - The bound that was exceeded.
+ * @param {string} [reason] - What the bound was, when it is not the configured maximum.
+ * @returns {Error} The error to emit or throw.
+ */
+const createLiteralTooLargeError = (literalSize, maxSize, reason) => {
+    const err = new Error(`Literal size ${literalSize} exceeds ${reason || `maximum allowed size of ${maxSize} bytes`}`);
+    err.code = 'LiteralTooLarge';
+    err.literalSize = literalSize;
+    err.maxSize = maxSize;
+    return err;
+};
+
+module.exports = { MAX_LITERAL_SIZE, MAX_LINE_SIZE, normalizeLimit, createLiteralTooLargeError };

package/lib/handler/token-parser.js

@@ -3,6 +3,7 @@
 'use strict';
 
 const imapFormalSyntax = require('./imap-formal-syntax');
+const { MAX_LITERAL_SIZE, normalizeLimit, createLiteralTooLargeError } = require('./limits');
 
 const STATE_ATOM = 0x001;
 const STATE_LITERAL = 0x002;
@@ -34,12 +35,18 @@ class TokenParser {
      * @param {Object} [options] - Parser options.
      * @param {boolean} [options.literalPlus] - Whether the LITERAL+ extension is in use.
      * @param {Array<Buffer>} [options.literals] - Pre-parsed literal values from the input stream.
+     * @param {number} [options.maxLiteralSize] - Maximum size (in bytes) of a literal parsed inline
+     *   from the input, i.e. when no pre-parsed literal buffers were supplied. Defaults to 1GB.
      */
     constructor(parent, startPos, str, options) {
         this.str = (str || '').toString();
         this.options = options || {};
         this.parent = parent;
 
+        // Same normalization and default as the streaming parser, so a direct user of this parser
+        // gets the same bound (an explicit 0 means "reject any non-empty inline literal").
+        this.maxLiteralSize = normalizeLimit(this.options.maxLiteralSize, MAX_LITERAL_SIZE);
+
         this.tree = this.currentNode = this.createNode();
         this.pos = startPos || 0;
 
@@ -611,8 +618,31 @@ class TokenParser {
                             this.state = STATE_NORMAL;
                             checkSP();
                         } else {
+                            // No pre-parsed literal buffers were supplied, so the literal is read
+                            // inline from this input and its declared length decides an
+                            // allocation. ImapStream always supplies buffers (and has already
+                            // enforced its own cap), so this branch means the parser is being used
+                            // directly and the declared length is untrusted: bound it before
+                            // allocating anything.
+                            // Two bounds apply: the configured maximum, and the bytes actually
+                            // available here - an inline literal has to be present in the input
+                            // being parsed, so a longer declaration can never be satisfied and
+                            // must not reserve memory for itself.
+                            let available = this.str.length - i - 1;
+                            let literalLength = this.currentNode.literalLength;
+                            if (literalLength > this.maxLiteralSize || literalLength > available) {
+                                let overMax = literalLength > this.maxLiteralSize;
+                                let error = createLiteralTooLargeError(
+                                    literalLength,
+                                    overMax ? this.maxLiteralSize : available,
+                                    overMax ? null : `the ${available} bytes available in the input`
+                                );
+                                error.parserContext = { input: this.str, pos: this.pos + i, chr };
+                                throw error;
+                            }
+
                             this.currentNode.started = true;
-                            // Allocate expected size buffer. Max size check is already performed
+                            // Allocate expected size buffer.
                             // Maybe should use allocUnsafe instead?
                             this.currentNode.chBuffer = Buffer.alloc(this.currentNode.literalLength);
                             this.currentNode.chPos = 0;

package/lib/imap-flow.d.ts

@@ -42,7 +42,22 @@ export interface ImapFlowOptions {
     verifyOnly?: boolean;
     /** If true and verifyOnly is set, lists mailboxes */
     includeMailboxes?: boolean;
-    /** Proxy URL. Supports HTTP CONNECT (http:, https:) and SOCKS (socks:, socks4:, socks5:) proxies */
+    /**
+     * Proxy URL. Supports HTTP CONNECT (http:, https:) and SOCKS (socks:, socks4:, socks4a:,
+     * socks5:) proxies. IPv6 proxy endpoints are given in URL form, e.g. `socks5://[2001:db8::1]:1080`.
+     *
+     * DNS behaviour depends on the proxy protocol:
+     *   - `http:`/`https:` - the destination hostname is sent to the proxy unresolved
+     *   - `socks4:` - destination hostnames are resolved locally to IPv4 (SOCKS4 has no IPv6
+     *     destination address type; IPv6 destinations are rejected)
+     *   - `socks4a:` - destination hostnames are sent to the proxy for remote DNS (IPv6
+     *     destinations are rejected)
+     *   - `socks:`/`socks5:` - destination hostnames are sent to the proxy for remote DNS, IPv4
+     *     and IPv6 literals are passed through
+     *
+     * The proxy endpoint itself is never resolved by ImapFlow; a hostname endpoint is handed to
+     * Node as-is. Proxy DNS and negotiation run inside `connectionTimeout`.
+     */
     proxy?: string;
     /** If true, then use QRESYNC instead of CONDSTORE. EXPUNGE notifications will include UID instead of sequence number */
     qresync?: boolean;
@@ -56,7 +71,11 @@ export interface ImapFlowOptions {
     disableAutoEnable?: boolean;
     /** If true, do not enable IMAP4rev2 mode even if the server supports it */
     disableIMAP4rev2?: boolean;
-    /** How long to wait for the connection to be established. Defaults to 90 seconds */
+    /**
+     * How long to wait for a usable transport, covering DNS resolution, proxy negotiation and the
+     * TCP/TLS handshake as a single budget. Defaults to 90 seconds. An expiry in any of those
+     * phases rejects with error code `CONNECT_TIMEOUT`.
+     */
     connectionTimeout?: number;
     /** How long to wait for the greeting. Defaults to 16 seconds */
     greetingTimeout?: number;
@@ -65,12 +84,17 @@ 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.
+     * 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
+     * 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.
+     * 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
+     * with error code `LiteralTooLarge`, and neither the marker line nor any byte of the rejected
+     * literal is interpreted as protocol.
      */
     maxLiteralSize?: number;
     /**
@@ -184,6 +208,8 @@ export interface ListResponse {
     flags: Set<string>;
     /** One of special-use flags (if applicable) */
     specialUse?: string;
+    /** How specialUse was determined: "user" (from specialUseHints), "extension" (SPECIAL-USE or XLIST flag reported by the server) or "name" (matched against known localized folder names) */
+    specialUseSource?: 'user' | 'extension' | 'name';
     /** True if mailbox was found from the output of LIST command */
     listed: boolean;
     /** True if the mailbox is subscribed - reported by LSUB or by LIST RETURN (SUBSCRIBED) on LIST-EXTENDED/IMAP4rev2 servers */
@@ -222,6 +248,8 @@ export interface ListOptions {
         junk?: string;
         /** Path to "Drafts" folder */
         drafts?: string;
+        /** Path to "Archive" folder */
+        archive?: string;
     };
 }
 
@@ -875,7 +903,7 @@ export class ImapFlow extends EventEmitter {
     /** Mailbox was opened */
     on(event: 'mailboxOpen', listener: (mailbox: MailboxObject) => void): this;
 
-    /** Mailbox was closed */
+    /** Mailbox was closed, either explicitly or because the connection went away while a mailbox was still selected */
     on(event: 'mailboxClose', listener: (mailbox: MailboxObject) => void): this;
 
     /** Log event if emitLogs=true */