imapflow 1.2.8 → 1.2.10

package/lib/handler/imap-stream.js

@@ -16,7 +16,25 @@ const CURLY_CLOSE = 0x7d;
 // Maximum allowed literal size: 1GB (1073741824 bytes)
 const MAX_LITERAL_SIZE = 1024 * 1024 * 1024;
 
+/**
+ * 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,
+ * extracts literal data blocks based on IMAP literal size markers (e.g., "{123}\r\n"),
+ * and emits each complete command as a readable object containing the payload Buffer
+ * and any associated literal Buffers. Enforces a maximum literal size of 1GB.
+ *
+ * @extends Transform
+ */
 class ImapStream extends Transform {
+    /**
+     * Creates a new ImapStream instance.
+     *
+     * @param {Object} [options] - Stream options.
+     * @param {string} [options.cid] - Connection identifier used for logging.
+     * @param {Object} [options.logger] - A pino-compatible logger instance. If not provided, a default child logger is created.
+     * @param {boolean} [options.logRaw] - If true, logs raw socket data at trace level.
+     * @param {boolean} [options.secureConnection] - Whether the connection uses TLS.
+     */
     constructor(options) {
         super({
             //writableHighWaterMark: 3,
@@ -51,6 +69,15 @@ class ImapStream extends Transform {
         this.inputQueue = []; // unprocessed input chunks
     }
 
+    /**
+     * Checks whether the given line buffer ends with an IMAP literal size marker
+     * (e.g., "{123}\r\n"). If a valid marker is found and the literal size is within
+     * the allowed maximum, switches the stream state to LITERAL mode and records
+     * the expected number of literal bytes.
+     *
+     * @param {Buffer} line - The line buffer to check for a trailing literal marker.
+     * @returns {boolean} True if a valid literal marker was found and literal state was activated, false otherwise.
+     */
     checkLiteralMarker(line) {
         if (!line || !line.length) {
             return false;
@@ -58,23 +85,22 @@ class ImapStream extends Transform {
 
         let pos = line.length - 1;
 
-        if (line[pos] === LF) {
-            pos--;
-        } else {
+        if (line[pos] !== LF) {
             return false;
         }
+        pos--;
+
         if (pos >= 0 && line[pos] === CR) {
             pos--;
         }
-        if (pos < 0) {
-            return false;
-        }
 
-        if (!pos || line[pos] !== CURLY_CLOSE) {
+        if (pos < 0 || !pos || line[pos] !== CURLY_CLOSE) {
             return false;
         }
         pos--;
 
+        // Scan backwards through the line to find an IMAP literal marker: {size}\r\n
+        // The format is: '{' followed by one or more ASCII digits followed by '}'
         let numBytes = [];
         for (; pos > 0; pos--) {
             let c = line[pos];
@@ -103,6 +129,16 @@ class ImapStream extends Transform {
         return false;
     }
 
+    /**
+     * 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
+     * of literal bytes. When a complete command (with all its literals) is assembled, it is
+     * pushed downstream as a readable object.
+     *
+     * @param {Buffer} chunk - The raw data chunk to process.
+     * @param {number} [startPos=0] - The byte offset within the chunk to start processing from.
+     * @returns {Promise<void>}
+     */
     async processInputChunk(chunk, startPos) {
         startPos = startPos || 0;
         if (startPos >= chunk.length) {
@@ -164,41 +200,34 @@ class ImapStream extends Transform {
             }
 
             case LITERAL: {
-                // exactly until end of chunk
-                if (chunk.length === startPos + this.literalWaiting) {
-                    if (!startPos) {
-                        this.literalBuffer.push(chunk);
-                    } else {
-                        this.literalBuffer.push(chunk.slice(startPos));
-                    }
+                const remainingInChunk = chunk.length - startPos;
+                const bytesToRead = Math.min(remainingInChunk, this.literalWaiting);
+                const partial = startPos === 0 && bytesToRead === chunk.length ? chunk : chunk.slice(startPos, startPos + bytesToRead);
 
-                    this.literalWaiting -= chunk.length;
-                    this.literals.push(Buffer.concat(this.literalBuffer));
-                    this.literalBuffer = [];
-                    this.state = LINE;
+                this.literalBuffer.push(partial);
+                this.literalWaiting -= bytesToRead;
 
-                    return;
-                } else if (chunk.length > startPos + this.literalWaiting) {
-                    let partial = chunk.slice(startPos, startPos + this.literalWaiting);
-                    this.literalBuffer.push(partial);
-                    startPos += partial.length;
-                    this.literalWaiting -= partial.length;
+                if (this.literalWaiting === 0) {
                     this.literals.push(Buffer.concat(this.literalBuffer));
                     this.literalBuffer = [];
                     this.state = LINE;
 
-                    return await this.processInputChunk(chunk, startPos);
-                } else {
-                    let partial = chunk.slice(startPos);
-                    this.literalBuffer.push(partial);
-                    startPos += partial.length;
-                    this.literalWaiting -= partial.length;
-                    return;
+                    if (remainingInChunk > bytesToRead) {
+                        return await this.processInputChunk(chunk, startPos + bytesToRead);
+                    }
                 }
+                break;
             }
         }
     }
 
+    /**
+     * Drains the input queue by processing each queued chunk sequentially.
+     * Yields to the event loop every 10 chunks to prevent CPU blocking on
+     * large bursts of incoming data.
+     *
+     * @returns {Promise<void>}
+     */
     async processInput() {
         let data;
         let processedCount = 0;
@@ -215,6 +244,15 @@ class ImapStream extends Transform {
         }
     }
 
+    /**
+     * Transform stream implementation. Receives raw data chunks from the writable side,
+     * converts strings to Buffers, tracks total bytes read, optionally logs raw data,
+     * and queues the chunk for asynchronous processing.
+     *
+     * @param {Buffer|string} chunk - The incoming data chunk.
+     * @param {string} encoding - The encoding if chunk is a string.
+     * @param {Function} next - Callback to signal that this chunk has been consumed.
+     */
     _transform(chunk, encoding, next) {
         if (typeof chunk === 'string') {
             chunk = Buffer.from(chunk, encoding);
@@ -237,6 +275,9 @@ class ImapStream extends Transform {
             });
         }
 
+        // 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.
         if (chunk && chunk.length) {
             this.inputQueue.push({ chunk, next });
         }
@@ -249,10 +290,22 @@ class ImapStream extends Transform {
         }
     }
 
+    /**
+     * Flush implementation called when the writable side ends. Signals completion immediately.
+     *
+     * @param {Function} next - Callback to signal flush completion.
+     */
     _flush(next) {
         next();
     }
 
+    /**
+     * Destroy implementation for cleanup. Clears all internal buffers, drains the input queue
+     * by invoking pending callbacks, and forwards the error (if any) to the callback.
+     *
+     * @param {Error|null} err - The error that caused destruction, or null.
+     * @param {Function} callback - Callback to signal destruction completion.
+     */
     _destroy(err, callback) {
         this.inputBuffer = [];
         this.lineBuffer = [];

package/lib/handler/parser-instance.js

@@ -6,7 +6,20 @@ const imapFormalSyntax = require('./imap-formal-syntax');
 
 const { TokenParser } = require('./token-parser');
 
+/**
+ * Parses a single IMAP response line into its structural components: tag, command,
+ * and attributes. Handles status responses (OK, NO, BAD, PREAUTH, BYE) with their
+ * human-readable text and response codes, as well as continuation responses ("+").
+ */
 class ParserInstance {
+    /**
+     * Creates a new ParserInstance for parsing an IMAP response line.
+     *
+     * @param {Buffer|string} input - The raw IMAP response line to parse.
+     * @param {Object} [options] - Parser options passed through to the TokenParser for attribute parsing.
+     * @param {boolean} [options.literalPlus] - Whether the LITERAL+ extension is in use.
+     * @param {Array<Buffer>} [options.literals] - Pre-parsed literal values from the stream.
+     */
     constructor(input, options) {
         this.input = (input || '').toString();
         this.options = options || {};
@@ -14,6 +27,14 @@ class ParserInstance {
         this.pos = 0;
     }
 
+    /**
+     * Extracts and returns the IMAP tag from the beginning of the response.
+     * The tag is typically "*" for untagged responses, "+" for continuation requests,
+     * or a client-assigned command tag like "A1".
+     *
+     * @returns {Promise<string>} The parsed tag string.
+     * @throws {Error} If the tag contains invalid characters.
+     */
     async getTag() {
         if (!this.tag) {
             this.tag = await this.getElement(imapFormalSyntax.tag() + '*+', true);
@@ -21,6 +42,15 @@ class ParserInstance {
         return this.tag;
     }
 
+    /**
+     * Extracts and returns the IMAP command or response name from the input.
+     * For continuation responses (tag "+"), returns an empty string and stores
+     * the remainder as human-readable text. For status responses (OK, NO, BAD,
+     * PREAUTH, BYE), separates the optional response code from the human-readable text.
+     *
+     * @returns {Promise<string>} The parsed command string.
+     * @throws {Error} If the command contains invalid characters or input ends unexpectedly.
+     */
     async getCommand() {
         if (this.tag === '+') {
             // special case
@@ -34,6 +64,10 @@ class ParserInstance {
             this.command = await this.getElement(imapFormalSyntax.command());
         }
 
+        // Status responses have the format: TAG OK/NO/BAD [response-code] human-readable text
+        // Example: * OK [CAPABILITY IMAP4rev1] Server ready
+        // Example: A1 NO [AUTHENTICATIONFAILED] Invalid credentials
+        // We need to separate the optional [response-code] from the human-readable text.
         switch ((this.command || '').toString().toUpperCase()) {
             case 'OK':
             case 'NO':
@@ -69,6 +103,14 @@ class ParserInstance {
         return this.command;
     }
 
+    /**
+     * Extracts the next whitespace-delimited element from the input and validates it
+     * against the given syntax character set. Advances the parser position past the element.
+     *
+     * @param {string} syntax - A string of allowed characters for the element (as returned by imap-formal-syntax methods).
+     * @returns {Promise<string>} The extracted element string.
+     * @throws {Error} If the element contains characters not in the syntax set, or if input ends unexpectedly.
+     */
     async getElement(syntax) {
         let match, element, errPos;
 
@@ -83,7 +125,10 @@ class ParserInstance {
             element = match[0];
             if ((errPos = imapFormalSyntax.verify(element, syntax)) >= 0) {
                 if (this.tag === 'Server' && element === 'Unavailable.') {
-                    // Exchange error
+                    // Microsoft Exchange sometimes sends a non-standard response
+                    // "Server Unavailable." instead of a proper IMAP tagged/untagged response.
+                    // We detect this specific pattern and convert it into a synthetic BAD response
+                    // so the rest of the parser can handle it gracefully.
                     let error = new Error(`Server returned an error: ${this.input}`);
                     error.code = 'ParserErrorExchange';
                     error.parserContext = {
@@ -117,6 +162,13 @@ class ParserInstance {
         return element;
     }
 
+    /**
+     * Consumes a single space character from the current position in the input.
+     * Advances the parser position by one.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If the current character is not a space, or if input has ended unexpectedly.
+     */
     async getSpace() {
         if (!this.remainder.length) {
             if (this.tag === '+' && this.pos === 1) {
@@ -141,6 +193,14 @@ class ParserInstance {
         this.remainder = this.remainder.substr(1);
     }
 
+    /**
+     * Parses the remaining input as IMAP attributes using the TokenParser.
+     * This handles complex structures including nested lists, literals, strings,
+     * atoms, sections, sequences, and partial ranges.
+     *
+     * @returns {Promise<Array>} A promise that resolves to an array of parsed attribute objects.
+     * @throws {Error} If the input contains unexpected whitespace, invalid characters, or ends unexpectedly.
+     */
     async getAttributes() {
         if (!this.remainder.length) {
             let error = new Error(`Unexpected end of input at position ${this.pos} [E6]`);

package/lib/handler/token-parser.js

@@ -15,9 +15,27 @@ const STATE_TEXT = 0x007;
 const RE_DIGITS = /^\d+$/;
 const RE_SINGLE_DIGIT = /^\d$/;
 
+// Prevents stack overflow from maliciously crafted deeply-nested IMAP input (e.g., (((((...))))))
 const MAX_NODE_DEPTH = 25;
 
+/**
+ * Tokenizes an IMAP attribute string into a tree of typed nodes.
+ * Handles all IMAP data types: atoms, quoted strings, literals (including literal8),
+ * sequences, lists (parenthesized groups), sections (bracketed groups), and partial ranges.
+ * Enforces a maximum nesting depth of {@link MAX_NODE_DEPTH} to prevent stack overflow
+ * from malicious input.
+ */
 class TokenParser {
+    /**
+     * Creates a new TokenParser.
+     *
+     * @param {ParserInstance} parent - The parent ParserInstance that owns this token parser. Used to access the parsed command for context-sensitive parsing.
+     * @param {number} startPos - The starting position offset in the original input, used for error reporting.
+     * @param {string} str - The attribute string to tokenize.
+     * @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.
+     */
     constructor(parent, startPos, str, options) {
         this.str = (str || '').toString();
         this.options = options || {};
@@ -31,6 +49,15 @@ class TokenParser {
         this.state = STATE_NORMAL;
     }
 
+    /**
+     * Processes the input string and returns the parsed attributes as a flat array of typed objects.
+     * Each attribute is an object with a `type` (e.g., "ATOM", "STRING", "LITERAL", "SEQUENCE")
+     * and a `value` property. Lists are represented as nested arrays. Sections and partials are
+     * attached as properties on the preceding attribute object.
+     *
+     * @returns {Promise<Array>} A promise that resolves to an array of parsed attribute objects and nested arrays.
+     * @throws {Error} If the input contains syntax errors or unclosed nodes.
+     */
     async getAttributes() {
         await this.processString();
 
@@ -108,6 +135,16 @@ class TokenParser {
         return attributes;
     }
 
+    /**
+     * Creates a new node in the parse tree. Each node represents a token or structural
+     * element (e.g., atom, string, literal, list, section, partial). The node is automatically
+     * appended to the parent's childNodes array if a parent is provided.
+     *
+     * @param {Object} [parentNode] - The parent node to attach this node to. If omitted, creates a root node.
+     * @param {number} [startPos] - The starting position of this node in the original input string.
+     * @returns {Object} The newly created node with childNodes, type, value, and isClosed properties.
+     * @throws {Error} If the nesting depth exceeds MAX_NODE_DEPTH.
+     */
     createNode(parentNode, startPos) {
         let node = {
             childNodes: [],
@@ -141,6 +178,15 @@ class TokenParser {
         return node;
     }
 
+    /**
+     * Processes the entire input string character by character using a state machine.
+     * Transitions between states (NORMAL, ATOM, STRING, LITERAL, SEQUENCE, PARTIAL, TEXT)
+     * based on the current character and builds the parse tree. This is the main parsing
+     * loop that drives the tokenization.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If the input contains unexpected characters, unclosed structures, or other syntax errors.
+     */
     async processString() {
         let chr, i, len;
 
@@ -203,8 +249,11 @@ class TokenParser {
                             checkSP();
                             break;
 
-                        // < starts a new partial
+                        // < starts a new partial byte range (e.g., BODY[]<0.1024>)
                         case '<':
+                            // '<' is only a partial range marker when it immediately follows ']',
+                            // which occurs in BODY[section]<origin.length> responses.
+                            // In all other contexts, '<' is treated as the start of an ATOM.
                             if (this.str.charAt(i - 1) !== ']') {
                                 this.currentNode = this.createNode(this.currentNode, this.pos + i);
                                 this.currentNode.type = 'ATOM';
@@ -218,12 +267,13 @@ class TokenParser {
                             }
                             break;
 
-                        // binary literal8
+                        // literal8 (RFC 3516): uses ~{size} prefix instead of {size}
+                        // literal8 allows binary data containing NUL bytes, unlike regular literals
                         case '~': {
                             let nextChr = this.str.charAt(i + 1);
                             if (nextChr !== '{') {
                                 if (imapFormalSyntax['ATOM-CHAR']().indexOf(nextChr) >= 0) {
-                                    // treat as ATOM
+                                    // '~' not followed by '{' but followed by an ATOM char: treat as ATOM
                                     this.currentNode = this.createNode(this.currentNode, this.pos + i);
                                     this.currentNode.type = 'ATOM';
                                     this.currentNode.value = chr;
@@ -236,14 +286,16 @@ class TokenParser {
                                 error.parserContext = { input: this.str, pos: this.pos + i, chr };
                                 throw error;
                             }
+                            // Mark the next literal as literal8 type; consumed when '{' is encountered
                             this.expectedLiteralType = 'literal8';
                             break;
                         }
 
-                        // { starts a new literal
+                        // { starts a new literal (regular {size}\r\n or literal8 ~{size}\r\n)
                         case '{':
                             this.currentNode = this.createNode(this.currentNode, this.pos + i);
                             this.currentNode.type = 'LITERAL';
+                            // Use literal8 type if '~' was seen immediately before, otherwise standard literal
                             this.currentNode.literalType = this.expectedLiteralType || 'literal';
                             this.expectedLiteralType = false;
                             this.state = STATE_LITERAL;
@@ -267,6 +319,7 @@ class TokenParser {
                         // [ starts section
                         case '[':
                             // If it is the *first* element after response command, then process as a response argument list
+                            // Status responses (OK/NO/BAD/BYE/PREAUTH) use [code] for response codes
                             if (['OK', 'NO', 'BAD', 'BYE', 'PREAUTH'].includes(this.parent.command.toUpperCase()) && this.currentNode === this.tree) {
                                 this.currentNode.endPos = this.pos + i;
 
@@ -278,10 +331,10 @@ class TokenParser {
                                 this.currentNode.isClosed = false;
                                 this.state = STATE_NORMAL;
 
-                                // RFC2221 defines a response code REFERRAL whose payload is an
-                                // RFC2192/RFC5092 imapurl that we will try to parse as an ATOM but
-                                // fail quite badly at parsing.  Since the imapurl is such a unique
-                                // (and crazy) term, we just specialize that case here.
+                                // RFC 2221 REFERRAL special case: the payload is an RFC 2192/RFC 5092
+                                // IMAP URL (e.g., imap://user@host/mailbox) which contains characters
+                                // that would break normal ATOM parsing (colons, slashes, etc.).
+                                // We handle this by consuming everything up to ']' as a single ATOM value.
                                 if (this.str.substr(i + 1, 9).toUpperCase() === 'REFERRAL ') {
                                     // create the REFERRAL atom
                                     this.currentNode = this.createNode(this.currentNode, this.pos + i + 1);
@@ -332,6 +385,8 @@ class TokenParser {
                     break;
 
                 case STATE_ATOM:
+                    // An atom is terminated by: space, closing delimiter of parent node,
+                    // or encountering a '[' that starts a section for BODY/BINARY commands.
                     // space finishes an atom
                     if (chr === ' ') {
                         this.currentNode.endPos = this.pos + i - 1;
@@ -340,7 +395,7 @@ class TokenParser {
                         break;
                     }
 
-                    //
+                    // ')' or ']' terminates the atom AND closes the enclosing LIST or SECTION
                     if (
                         this.currentNode.parentNode &&
                         ((chr === ')' && this.currentNode.parentNode.type === 'LIST') || (chr === ']' && this.currentNode.parentNode.type === 'SECTION'))
@@ -357,6 +412,8 @@ class TokenParser {
                         break;
                     }
 
+                    // If the atom so far is all digits and we see ',' or ':', it is actually
+                    // a sequence set (e.g., "1:5" or "1,3,5"), so reclassify and switch state
                     if ((chr === ',' || chr === ':') && RE_DIGITS.test(this.currentNode.value)) {
                         this.currentNode.type = 'SEQUENCE';
                         this.currentNode.isClosed = true;

package/lib/imap-commands.js

@@ -2,6 +2,17 @@
 
 'use strict';
 
+/**
+ * IMAP command registry. Maps IMAP command names (uppercase strings) to their
+ * corresponding implementation modules from the `lib/commands/` directory.
+ *
+ * Each entry maps a command name (e.g., "FETCH", "SELECT", "IDLE") to a module
+ * that exports functions for building the command request and processing the
+ * server response. This Map is used by the main ImapFlow client to look up
+ * and execute IMAP commands.
+ *
+ * @type {Map<string, Object>}
+ */
 module.exports = new Map([
     ['ID', require('./commands/id.js')],
     ['CAPABILITY', require('./commands/capability.js')],

package/lib/imap-flow.d.ts

@@ -761,6 +761,12 @@ export class ImapFlow extends EventEmitter {
     /** Opens a mailbox if not already open and returns a lock */
     getMailboxLock(path: string | string[], options?: MailboxOpenOptions): Promise<MailboxLockObject>;
 
+    /** Returns byte counters for the current connection, optionally resets them */
+    stats(reset?: boolean): { sent: number; received: number };
+
+    /** Detaches sockets from the IMAP pipeline, returns read and write sockets */
+    unbind(): { readSocket: any; writeSocket: any };
+
     /** Connection close event */
     on(event: 'close', listener: () => void): this;