imapflow 1.7.7 → 2.0.0

package/dist/cjs/handler/limits.js

@@ -0,0 +1,51 @@
+"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 the ImapFlowOptions type describe both paths.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLiteralTooLargeError = exports.normalizeLimit = exports.MAX_RESPONSE_SIZE = exports.MAX_LINE_SIZE = exports.MAX_LITERAL_SIZE = void 0;
+// Maximum allowed literal size: 1GB (1073741824 bytes)
+exports.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.
+exports.MAX_LINE_SIZE = exports.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.
+exports.MAX_RESPONSE_SIZE = 2 * exports.MAX_LITERAL_SIZE;
+/**
+ * Normalizes a configured size limit. A non-negative integer is honored as-is (including 0, which
+ * 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 defaultValue - Fallback when the value is not a usable limit.
+ * @returns The normalized limit.
+ */
+const normalizeLimit = (value, defaultValue) => (Number.isInteger(value) || value === Infinity) && value >= 0 ? value : defaultValue;
+exports.normalizeLimit = normalizeLimit;
+/**
+ * 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 literalSize - The declared literal size.
+ * @param maxSize - The bound that was exceeded.
+ * @param reason - What the bound was, when it is not the configured maximum.
+ * @returns 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;
+};
+exports.createLiteralTooLargeError = createLiteralTooLargeError;

package/dist/cjs/handler/parser-instance.d.ts

@@ -0,0 +1,68 @@
+import type { ImapAttributeList, ParserOptions } from './types.js';
+/**
+ * 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 ("+").
+ */
+export declare class ParserInstance {
+    input: string;
+    options: ParserOptions;
+    remainder: string;
+    pos: number;
+    tag?: string | undefined;
+    command?: string | undefined;
+    humanReadable?: string | undefined;
+    /**
+     * Creates a new ParserInstance for parsing an IMAP response line.
+     *
+     * @param input - The raw IMAP response line to parse.
+     * @param options - Parser options passed through to the TokenParser for attribute parsing.
+     * @param options.literalPlus - Whether the LITERAL+ extension is in use.
+     * @param options.literals - Pre-parsed literal values from the stream.
+     */
+    constructor(input?: Buffer | string | null | undefined, options?: ParserOptions | undefined);
+    /**
+     * 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 The parsed tag string.
+     * @throws {Error} If the tag contains invalid characters.
+     */
+    getTag(): Promise<string>;
+    /**
+     * 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 The parsed command string.
+     * @throws {Error} If the command contains invalid characters or input ends unexpectedly.
+     */
+    getCommand(): Promise<string>;
+    /**
+     * 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 syntax - A string of allowed characters for the element (as returned by imap-formal-syntax methods).
+     * @returns The extracted element string.
+     * @throws {Error} If the element contains characters not in the syntax set, or if input ends unexpectedly.
+     */
+    getElement(syntax: string): Promise<string>;
+    /**
+     * Consumes a single space character from the current position in the input.
+     * Advances the parser position by one.
+     *
+     * @throws {Error} If the current character is not a space, or if input has ended unexpectedly.
+     */
+    getSpace(): Promise<void>;
+    /**
+     * 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 A promise that resolves to an array of parsed attribute objects.
+     * @throws {Error} If the input contains unexpected whitespace, invalid characters, or ends unexpectedly.
+     */
+    getAttributes(): Promise<ImapAttributeList>;
+}

package/dist/cjs/handler/parser-instance.js

@@ -0,0 +1,223 @@
+"use strict";
+/* eslint new-cap: 0 */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParserInstance = void 0;
+const imap_formal_syntax_js_1 = __importDefault(require("./imap-formal-syntax.js"));
+const token_parser_js_1 = require("./token-parser.js");
+/**
+ * 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 input - The raw IMAP response line to parse.
+     * @param options - Parser options passed through to the TokenParser for attribute parsing.
+     * @param options.literalPlus - Whether the LITERAL+ extension is in use.
+     * @param options.literals - Pre-parsed literal values from the stream.
+     */
+    constructor(input, options) {
+        this.input = (input || '').toString();
+        this.options = options || {};
+        this.remainder = this.input;
+        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 The parsed tag string.
+     * @throws {Error} If the tag contains invalid characters.
+     */
+    async getTag() {
+        if (!this.tag) {
+            this.tag = await this.getElement(imap_formal_syntax_js_1.default.tag() + '*+');
+        }
+        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 The parsed command string.
+     * @throws {Error} If the command contains invalid characters or input ends unexpectedly.
+     */
+    async getCommand() {
+        if (this.tag === '+') {
+            // special case
+            this.humanReadable = this.remainder.trim();
+            this.remainder = '';
+            return '';
+        }
+        if (!this.command) {
+            this.command = await this.getElement(imap_formal_syntax_js_1.default.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':
+            case 'BAD':
+            case 'PREAUTH':
+            case 'BYE':
+                {
+                    let match = this.remainder.match(/^\s+\[/);
+                    if (match) {
+                        // Find the ']' that closes the response code. Inner brackets are
+                        // tracked because servers do put bracketed values inside a code
+                        // (e.g. a "[css3-page]" keyword in a PERMANENTFLAGS list), which a
+                        // first-']' scan would cut in half.
+                        let nesting = 1;
+                        let end = -1;
+                        for (let i = match[0].length; i < this.remainder.length; i++) {
+                            let c = this.remainder[i];
+                            if (c === '[') {
+                                nesting++;
+                            }
+                            else if (c === ']') {
+                                nesting--;
+                            }
+                            if (!nesting) {
+                                end = i;
+                                break;
+                            }
+                        }
+                        // Unbalanced '[' inside the code: the RFC 9051 free-text form
+                        // (`atom [SP 1*<any TEXT-CHAR except "]">]`) permits '[' but not
+                        // ']', so the code really does end at the first ']' here. Without
+                        // this fallback the scan finds no closing bracket at all and the
+                        // human-readable text - what every error message is built from -
+                        // is swallowed into the response code.
+                        if (end < 0) {
+                            end = this.remainder.indexOf(']', match[0].length);
+                        }
+                        if (end >= 0) {
+                            this.humanReadable = this.remainder.substring(end + 1).trim();
+                            this.remainder = this.remainder.substring(0, end + 1);
+                        }
+                    }
+                    else {
+                        this.humanReadable = this.remainder.trim();
+                        this.remainder = '';
+                    }
+                }
+                break;
+        }
+        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 syntax - A string of allowed characters for the element (as returned by imap-formal-syntax methods).
+     * @returns 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;
+        if (/^\s/.test(this.remainder)) {
+            let error = new Error(`Unexpected whitespace at position ${this.pos} [E1]`);
+            error.code = 'ParserError1';
+            error.parserContext = { input: this.input, pos: this.pos };
+            throw error;
+        }
+        if ((match = this.remainder.match(/^\s*[^\s]+(?=\s|$)/))) {
+            element = match[0];
+            if ((errPos = imap_formal_syntax_js_1.default.verify(element, syntax)) >= 0) {
+                if (this.tag === 'Server' && element === 'Unavailable.') {
+                    // 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 = {
+                        input: this.input,
+                        element,
+                        pos: this.pos,
+                        value: {
+                            tag: '*',
+                            command: 'BAD',
+                            attributes: [{ type: 'TEXT', value: this.input }]
+                        }
+                    };
+                    throw error;
+                }
+                let error = new Error(`Unexpected char at position ${this.pos + errPos} [E2: ${JSON.stringify(element.charAt(errPos))}]`);
+                error.code = 'ParserError2';
+                error.parserContext = { input: this.input, element, pos: this.pos };
+                throw error;
+            }
+        }
+        else {
+            let error = new Error(`Unexpected end of input at position ${this.pos} [E3]`);
+            error.code = 'ParserError3';
+            error.parserContext = { input: this.input, pos: this.pos };
+            throw error;
+        }
+        this.pos += match[0].length;
+        this.remainder = this.remainder.substr(match[0].length);
+        return element;
+    }
+    /**
+     * Consumes a single space character from the current position in the input.
+     * Advances the parser position by one.
+     *
+     * @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) {
+                // special case, empty + response
+                return;
+            }
+            let error = new Error(`Unexpected end of input at position ${this.pos} [E4]`);
+            error.code = 'ParserError4';
+            error.parserContext = { input: this.input, pos: this.pos };
+            throw error;
+        }
+        if (imap_formal_syntax_js_1.default.verify(this.remainder.charAt(0), imap_formal_syntax_js_1.default.SP()) >= 0) {
+            let error = new Error(`Unexpected char at position ${this.pos} [E5: ${JSON.stringify(this.remainder.charAt(0))}]`);
+            error.code = 'ParserError5';
+            error.parserContext = { input: this.input, element: this.remainder, pos: this.pos };
+            throw error;
+        }
+        this.pos++;
+        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 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]`);
+            error.code = 'ParserError6';
+            error.parserContext = { input: this.input, pos: this.pos };
+            throw error;
+        }
+        if (/^\s/.test(this.remainder)) {
+            let error = new Error(`Unexpected whitespace at position ${this.pos} [E7]`);
+            error.code = 'ParserError7';
+            error.parserContext = { input: this.input, element: this.remainder, pos: this.pos };
+            throw error;
+        }
+        const tokenParser = new token_parser_js_1.TokenParser(this, this.pos, this.remainder, this.options);
+        return await tokenParser.getAttributes();
+    }
+}
+exports.ParserInstance = ParserInstance;

package/dist/cjs/handler/token-parser.d.ts

@@ -0,0 +1,91 @@
+import type { ImapAttributeList, ParserOptions } from './types.js';
+import type { ParserInstance } from './parser-instance.js';
+/**
+ * A node of the parse tree built by TokenParser. `type` is false for a node that has not
+ * been classified yet, 'TREE' for the root, and otherwise the token or structure type
+ * (ATOM, string, LITERAL, SEQUENCE, LIST, SECTION, PARTIAL).
+ */
+export interface TokenNode {
+    childNodes: TokenNode[];
+    type: string | false;
+    value: string | Buffer;
+    isClosed: boolean;
+    parentNode?: TokenNode | undefined;
+    depth: number;
+    startPos?: number | undefined;
+    endPos?: number | undefined;
+    literalType?: string | undefined;
+    /** Digits accumulated as a string while the literal marker is read, converted to a number once the marker closes */
+    literalLength?: string | number | undefined;
+    literalPlus?: boolean | undefined;
+    started?: boolean | undefined;
+    chBuffer?: Buffer | undefined;
+    chPos?: number | undefined;
+}
+/**
+ * The parent object a TokenParser reads the parsed command from
+ */
+export interface TokenParserParent {
+    command?: string | undefined;
+}
+/**
+ * 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.
+ */
+export declare class TokenParser {
+    str: string;
+    options: ParserOptions;
+    parent: TokenParserParent | ParserInstance;
+    maxLiteralSize: number;
+    tree: TokenNode;
+    currentNode: TokenNode;
+    pos: number;
+    state: number;
+    expectedLiteralType?: string | false | undefined;
+    /**
+     * Creates a new TokenParser.
+     *
+     * @param parent - The parent ParserInstance that owns this token parser. Used to access the parsed command for context-sensitive parsing.
+     * @param startPos - The starting position offset in the original input, used for error reporting.
+     * @param str - The attribute string to tokenize.
+     * @param options - Parser options.
+     * @param options.literalPlus - Whether the LITERAL+ extension is in use.
+     * @param options.literals - Pre-parsed literal values from the input stream.
+     * @param 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: TokenParserParent | ParserInstance, startPos?: number | undefined, str?: string | null | undefined, options?: ParserOptions | undefined);
+    /**
+     * 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 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.
+     */
+    getAttributes(): Promise<ImapAttributeList>;
+    /**
+     * 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 parentNode - The parent node to attach this node to. If omitted, creates a root node.
+     * @param startPos - The starting position of this node in the original input string.
+     * @returns The newly created node with childNodes, type, value, and isClosed properties.
+     * @throws {Error} If the nesting depth exceeds MAX_NODE_DEPTH.
+     */
+    createNode(parentNode?: TokenNode | undefined, startPos?: number | undefined): TokenNode;
+    /**
+     * 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.
+     *
+     * @throws {Error} If the input contains unexpected characters, unclosed structures, or other syntax errors.
+     */
+    processString(): Promise<void>;
+}