imapflow 2.3.0 → 2.4.1

package/dist/cjs/handler/imap-compiler.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const imap_formal_syntax_js_1 = __importDefault(require("./imap-formal-syntax.js"));
+const errors_js_1 = require("../errors.js");
 // A single element of a sequence-set as defined by the RFC 9051 grammar: a number
 // or a range, where "*" stands for the largest number in use. Digit strings are not
 // range-checked here (a server rejects "0" or an overlong number on its own); the
@@ -46,13 +47,11 @@ const CRLF = /[\r\n]/;
  */
 const quoteString = (value) => {
     if (NOT_QUOTABLE.test(value)) {
-        let error = new Error('Unquotable character in IMAP string value');
-        error.code = 'InvalidStringValue';
-        throw error;
+        throw (0, errors_js_1.createImapError)('Unquotable character in IMAP string value', 'InvalidStringValue');
     }
     return '"' + value.replace(/["\\]/g, char => '\\' + char) + '"';
 };
-async function compiler(response, options) {
+function compiler(response, options) {
     let { asArray, isLogging, literalPlus, literalMinus } = options || {};
     const respParts = [];
     // Formats an entry (string, number or Buffer) into the Buffer that is written to
@@ -67,9 +66,7 @@ async function compiler(response, options) {
     const emitEntry = (entry, opts) => {
         let { returnEmpty, raw } = opts || {};
         if (!raw && !isLogging && (typeof entry === 'string' || Buffer.isBuffer(entry)) && CRLF.test(entry.toString('latin1'))) {
-            let error = new Error('Line terminator in IMAP token');
-            error.code = 'InvalidTokenValue';
-            throw error;
+            throw (0, errors_js_1.createImapError)('Line terminator in IMAP token', 'InvalidTokenValue');
         }
         if (typeof entry === 'string') {
             return Buffer.from(entry);
@@ -93,7 +90,7 @@ async function compiler(response, options) {
     // Set right after the compiler writes "(" or "[" itself, so the first element inside gets no
     // leading space
     let afterOpener = false;
-    let walk = async (node, options) => {
+    let walk = (node, options) => {
         options = options || {};
         // Add a space separator when:
         // - The previous token was a LITERAL. Literal data ends exactly at its declared length, so
@@ -125,7 +122,7 @@ async function compiler(response, options) {
                 if (subArray && !Array.isArray(child)) {
                     subArray = false;
                 }
-                await walk(child, { subArray });
+                walk(child, { subArray });
             }
             resp.push(emitEntry(')'));
             afterOpener = false;
@@ -159,6 +156,11 @@ async function compiler(response, options) {
                     resp.push(emitEntry(logPlaceholder(node.value.length, 'literal')));
                 }
                 else {
+                    // The size marker must match the bytes emitEntry() writes, and it writes
+                    // nothing for a value that is not a Buffer or a string
+                    if (node.value && !Buffer.isBuffer(node.value) && typeof node.value !== 'string') {
+                        throw (0, errors_js_1.createImapError)('Literal value must be a Buffer or a string', 'InvalidTokenValue');
+                    }
                     // The literal size marker counts octets - string values are written as
                     // UTF-8, so their UTF-16 .length would undercount multi-byte characters
                     let literalLength = !node.value ? 0 : Buffer.isBuffer(node.value) ? node.value.length : Buffer.byteLength(node.value.toString());
@@ -213,9 +215,7 @@ async function compiler(response, options) {
                 if (!isLogging) {
                     val = node.value === null || node.value === undefined ? '' : node.value.toString();
                     if (!isValidSequenceSet(val)) {
-                        let error = new Error('Invalid sequence set value');
-                        error.code = 'InvalidSequenceSet';
-                        throw error;
+                        throw (0, errors_js_1.createImapError)('Invalid sequence set value', 'InvalidSequenceSet');
                     }
                     resp.push(emitEntry(val, { raw: true }));
                 }
@@ -230,9 +230,7 @@ async function compiler(response, options) {
                 // this check runs first only to raise the more specific InvalidTextValue code.
                 if (node.value) {
                     if (!isLogging && CRLF.test(node.value.toString())) {
-                        let error = new Error('Line terminator in IMAP text value');
-                        error.code = 'InvalidTextValue';
-                        throw error;
+                        throw (0, errors_js_1.createImapError)('Line terminator in IMAP text value', 'InvalidTextValue');
                     }
                     resp.push(emitEntry(node.value));
                 }
@@ -267,7 +265,7 @@ async function compiler(response, options) {
                     resp.push(emitEntry('['));
                     afterOpener = true;
                     for (let child of node.section) {
-                        await walk(child);
+                        walk(child);
                     }
                     resp.push(emitEntry(']'));
                     afterOpener = false;
@@ -286,13 +284,15 @@ async function compiler(response, options) {
     if (response.attributes) {
         let attributes = Array.isArray(response.attributes) ? response.attributes : [].concat(response.attributes);
         for (let child of attributes) {
-            await walk(child);
+            walk(child);
         }
     }
     if (resp.length) {
         respParts.push(resp);
     }
-    const compiled = respParts.map(part => Buffer.concat(part));
+    // A part with a single entry (the data of a synchronizing literal) is used as is: copying a
+    // large message only to send it doubles its memory
+    const compiled = respParts.map(part => (part.length === 1 ? part[0] : Buffer.concat(part)));
     // without asArray there is a single part, returned as is instead of copied
     return asArray ? compiled : compiled.length === 1 ? compiled[0] : Buffer.concat(compiled);
 }

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

@@ -6,6 +6,31 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = parser;
 const imap_formal_syntax_js_1 = __importDefault(require("./imap-formal-syntax.js"));
 const parser_instance_js_1 = require("./parser-instance.js");
+const errors_js_1 = require("../errors.js");
+const limits_js_1 = require("./limits.js");
+// The codes the parser raises on purpose: the numbered ParserErrorN codes, ParserErrorExchange,
+// the nesting limit and the inline literal size limit
+const PARSER_ERROR_CODES = /^(?:ParserError\d+|ParserErrorExchange|MAX_IMAP_NESTING_REACHED|LiteralTooLarge)$/;
+/**
+ * Anything the parser throws other than one of its own coded errors - a TypeError from a parser
+ * bug, a RangeError from runaway recursion or a bad Buffer offset (which carries a Node code), a
+ * thrown non-Error - is re-raised as a coded `ParserErrorInternal`, so callers that match on
+ * codes still handle it and settle the command the line belonged to. The fuzz suite treats this
+ * code as a failure, so the guard does not hide parser bugs from the tests.
+ *
+ * @param err - The thrown value
+ * @param input - The line that was being parsed
+ * @returns The error to rethrow
+ */
+function asParserError(err, input) {
+    if (err instanceof Error && PARSER_ERROR_CODES.test(err.code || '')) {
+        return err;
+    }
+    return (0, errors_js_1.createImapError)(`Unexpected parser failure: ${err instanceof Error ? err.message : String(err)}`, 'ParserErrorInternal', {
+        parserContext: (0, limits_js_1.boundedInput)(input.toString()),
+        ...(err instanceof Error ? { _err: err } : {})
+    });
+}
 /**
  * Parses a raw IMAP command or response buffer into a structured object.
  * Handles edge cases such as null-byte-padded responses from buggy servers and
@@ -26,7 +51,7 @@ async function parser(command, options) {
     // Workaround for buggy IMAP servers that pad responses with leading NUL (\x00) bytes.
     // Some servers (observed in the wild) prepend null bytes to their output, which would
     // cause parsing to fail. We strip them and note how many were removed for diagnostics.
-    if (command[0] === 0) {
+    if (Buffer.isBuffer(command) && command[0] === 0) {
         // find the first non null byte and trim
         let firstNonNull = -1;
         for (let i = 0; i < command.length; i++) {
@@ -39,7 +64,7 @@ async function parser(command, options) {
             // All bytes are null, treat as a BAD response
             return { tag: '*', command: 'BAD', attributes: [] };
         }
-        command = command.slice(firstNonNull);
+        command = command.subarray(firstNonNull);
         nullBytesRemoved = firstNonNull;
     }
     const parserInstance = new parser_instance_js_1.ParserInstance(command, options);
@@ -71,7 +96,7 @@ async function parser(command, options) {
         }
     }
     catch (err) {
-        let error = err;
+        let error = asParserError(err, command);
         if (error.code === 'ParserErrorExchange' && error.parserContext && error.parserContext.value) {
             return error.parserContext.value;
         }

package/dist/cjs/handler/imap-stream.js

@@ -4,6 +4,7 @@ exports.ImapStream = void 0;
 const node_stream_1 = require("node:stream");
 const logger_js_1 = require("../logger.js");
 const limits_js_1 = require("./limits.js");
+const errors_js_1 = require("../errors.js");
 const LINE = 0x01;
 const LITERAL = 0x02;
 const LF = 0x0a;
@@ -180,10 +181,10 @@ class ImapStream extends node_stream_1.Transform {
         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;
+        const err = (0, errors_js_1.createImapError)(`Line length ${lineLength} exceeds maximum allowed size of ${this.maxLineLength} bytes`, 'LineTooLarge', {
+            lineLength,
+            maxSize: this.maxLineLength
+        });
         return this.failStream(err);
     }
     /**
@@ -206,10 +207,10 @@ class ImapStream extends node_stream_1.Transform {
             }
             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;
+        const err = (0, errors_js_1.createImapError)(`Response size ${total} exceeds maximum allowed size of ${this.maxResponseSize} bytes`, 'ResponseTooLarge', {
+            responseSize: total,
+            maxSize: this.maxResponseSize
+        });
         return this.failStream(err);
     }
     /**

package/dist/cjs/handler/limits.d.ts

@@ -1,4 +1,4 @@
-import type { ImapFlowError } from '../errors.js';
+import { type ImapFlowError } from '../errors.js';
 export declare const MAX_LITERAL_SIZE: number;
 export declare const MAX_LINE_SIZE: number;
 export declare const MAX_RESPONSE_SIZE: number;

package/dist/cjs/handler/limits.js

@@ -4,6 +4,7 @@
 // defaults in the ImapFlowOptions type describe both paths.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createLiteralTooLargeError = exports.normalizeLimit = exports.boundedInput = exports.ERROR_CONTEXT_LENGTH = exports.MAX_RESPONSE_SIZE = exports.MAX_LINE_SIZE = exports.MAX_LITERAL_SIZE = void 0;
+const errors_js_1 = require("../errors.js");
 // 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:
@@ -56,11 +57,8 @@ exports.normalizeLimit = normalizeLimit;
  * @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;
-};
+const createLiteralTooLargeError = (literalSize, maxSize, reason) => (0, errors_js_1.createImapError)(`Literal size ${literalSize} exceeds ${reason || `maximum allowed size of ${maxSize} bytes`}`, 'LiteralTooLarge', {
+    literalSize,
+    maxSize
+});
 exports.createLiteralTooLargeError = createLiteralTooLargeError;

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

@@ -8,6 +8,7 @@ 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");
 const limits_js_1 = require("./limits.js");
+const errors_js_1 = require("../errors.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
@@ -143,10 +144,7 @@ class ParserInstance {
     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 = this.errorContext();
-            throw error;
+            throw (0, errors_js_1.createImapError)(`Unexpected whitespace at position ${this.pos} [E1]`, 'ParserError1', { parserContext: this.errorContext() });
         }
         if ((match = this.remainder.match(/^\s*[^\s]+(?=\s|$)/))) {
             element = match[0];
@@ -156,29 +154,24 @@ class ParserInstance {
                     // "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 = {
-                        ...this.errorContext(element),
-                        value: {
-                            tag: '*',
-                            command: 'BAD',
-                            attributes: [{ type: 'TEXT', value: this.input }]
+                    throw (0, errors_js_1.createImapError)(`Server returned an error: ${this.input}`, 'ParserErrorExchange', {
+                        parserContext: {
+                            ...this.errorContext(element),
+                            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 = this.errorContext(element);
-                throw error;
+                throw (0, errors_js_1.createImapError)(`Unexpected char at position ${this.pos + errPos} [E2: ${JSON.stringify(element.charAt(errPos))}]`, 'ParserError2', {
+                    parserContext: this.errorContext(element)
+                });
             }
         }
         else {
-            let error = new Error(`Unexpected end of input at position ${this.pos} [E3]`);
-            error.code = 'ParserError3';
-            error.parserContext = this.errorContext();
-            throw error;
+            throw (0, errors_js_1.createImapError)(`Unexpected end of input at position ${this.pos} [E3]`, 'ParserError3', { parserContext: this.errorContext() });
         }
         this.pos += match[0].length;
         this.remainder = this.remainder.slice(match[0].length);
@@ -196,16 +189,12 @@ class ParserInstance {
                 // special case, empty + response
                 return;
             }
-            let error = new Error(`Unexpected end of input at position ${this.pos} [E4]`);
-            error.code = 'ParserError4';
-            error.parserContext = this.errorContext();
-            throw error;
+            throw (0, errors_js_1.createImapError)(`Unexpected end of input at position ${this.pos} [E4]`, 'ParserError4', { parserContext: this.errorContext() });
         }
         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 = this.errorContext(this.remainder);
-            throw error;
+            throw (0, errors_js_1.createImapError)(`Unexpected char at position ${this.pos} [E5: ${JSON.stringify(this.remainder.charAt(0))}]`, 'ParserError5', {
+                parserContext: this.errorContext(this.remainder)
+            });
         }
         this.pos++;
         this.remainder = this.remainder.slice(1);
@@ -220,16 +209,12 @@ class ParserInstance {
      */
     async getAttributes() {
         if (!this.remainder.length) {
-            let error = new Error(`Unexpected end of input at position ${this.pos} [E6]`);
-            error.code = 'ParserError6';
-            error.parserContext = this.errorContext();
-            throw error;
+            throw (0, errors_js_1.createImapError)(`Unexpected end of input at position ${this.pos} [E6]`, 'ParserError6', { parserContext: this.errorContext() });
         }
         if (/^\s/.test(this.remainder)) {
-            let error = new Error(`Unexpected whitespace at position ${this.pos} [E7]`);
-            error.code = 'ParserError7';
-            error.parserContext = this.errorContext(this.remainder);
-            throw error;
+            throw (0, errors_js_1.createImapError)(`Unexpected whitespace at position ${this.pos} [E7]`, 'ParserError7', {
+                parserContext: this.errorContext(this.remainder)
+            });
         }
         const tokenParser = new token_parser_js_1.TokenParser(this, this.pos, this.remainder, this.options);
         return await tokenParser.getAttributes();

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

@@ -1,3 +1,4 @@
+import { type ImapFlowError, type ParserErrorCode } from '../errors.js';
 import type { ImapAttributeList, ParserOptions } from './types.js';
 import type { ParserInstance } from './parser-instance.js';
 /**
@@ -58,6 +59,17 @@ export declare class TokenParser {
      *   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);
+    /**
+     * Builds a numbered parser error that carries a bounded copy of the input and the position
+     * (and character, when there is one) where parsing failed.
+     *
+     * @param message - The error message
+     * @param code - The numbered parser error code
+     * @param pos - Position of the failure in the original input
+     * @param chr - The offending character
+     * @returns The error to throw
+     */
+    parserError(message: string, code: ParserErrorCode, pos: number, chr?: string | undefined): ImapFlowError;
     /**
      * 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")