imapflow 1.2.8 → 1.2.9

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;