imapflow 2.2.5 → 2.2.7

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

@@ -19,6 +19,10 @@ const safeNumber = (value) => {
     let num = Math.round(Number(value));
     return Number.isSafeInteger(num) && num >= 0 ? num : 0;
 };
+// Log output stands in a placeholder for any value longer than this, so a log entry never
+// carries a copy of a large token (a message body, a long unquoted server token)
+const LOG_VALUE_LIMIT = 100;
+const logPlaceholder = (length, kind) => `"(* ${length}B ${kind} *)"`;
 // Characters that cannot appear in an IMAP quoted string: CR and LF terminate a
 // command line, and NUL is outside the CHAR production entirely. A value carrying
 // any of them has to be sent as a literal, so quoting it is never correct.
@@ -81,28 +85,27 @@ async function compiler(response, options) {
         .concat(response.command ? emitEntry(' ' + response.command) : []);
     let val;
     let lastType;
+    // 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) => {
         options = options || {};
-        // Determine whether a space separator is needed before this node.
-        // Inspect the last byte written to decide context.
-        let lastRespEntry = resp.length && resp[resp.length - 1];
-        let lastRespByte = (lastRespEntry && lastRespEntry.length && lastRespEntry[lastRespEntry.length - 1]) || '';
-        if (typeof lastRespByte === 'number') {
-            lastRespByte = String.fromCharCode(lastRespByte);
-        }
         // Add a space separator when:
         // - The previous token was a LITERAL. Literal data ends exactly at its declared length, so
         //   a following token always needs an explicit separator, even though the last written byte
         //   is arbitrary literal content.
-        // - Otherwise: there is something written already (resp is not empty) and the last byte is
-        //   not an opening delimiter ('(', '<' or '['), which suppresses the space.
+        // - Otherwise: there is something written already (resp is not empty) and the compiler did
+        //   not just open a list or a section. This is tracked rather than read back from the last
+        //   written byte: a token value can itself end in "(", "[" or "<" (an atom such as "X["),
+        //   and suppressing the space after it would fuse it with the next argument.
         // A sub-array element in a consecutive-list context never gets one (no space between
         // adjacent lists).
-        if (lastType === 'LITERAL' || (!['(', '<', '['].includes(lastRespByte) && resp.length)) {
+        if (lastType === 'LITERAL' || (!afterOpener && resp.length)) {
             if (!options.subArray) {
                 resp.push(emitEntry(' '));
             }
         }
+        afterOpener = false;
         if (node && node.buffer && !Buffer.isBuffer(node)) {
             // mongodb binary
             node = node.buffer;
@@ -110,6 +113,7 @@ async function compiler(response, options) {
         if (Array.isArray(node)) {
             lastType = 'LIST';
             resp.push(emitEntry('('));
+            afterOpener = true;
             // check if we need to skip separator WS between two arrays
             let subArray = node.length > 1 && Array.isArray(node[0]);
             for (let child of node) {
@@ -119,6 +123,7 @@ async function compiler(response, options) {
                 await walk(child, { subArray });
             }
             resp.push(emitEntry(')'));
+            afterOpener = false;
             return;
         }
         if (!node && typeof node !== 'string' && typeof node !== 'number' && !Buffer.isBuffer(node)) {
@@ -126,8 +131,8 @@ async function compiler(response, options) {
             return;
         }
         if (typeof node === 'string' || Buffer.isBuffer(node)) {
-            if (isLogging && node.length > 100) {
-                resp.push(emitEntry('"(* ' + node.length + 'B string *)"'));
+            if (isLogging && node.length > LOG_VALUE_LIMIT) {
+                resp.push(emitEntry(logPlaceholder(node.length, 'string')));
             }
             else {
                 resp.push(emitEntry(isLogging ? JSON.stringify(node.toString()) : quoteString(node.toString())));
@@ -146,7 +151,7 @@ async function compiler(response, options) {
         switch (node.type.toUpperCase()) {
             case 'LITERAL':
                 if (isLogging) {
-                    resp.push(emitEntry('"(* ' + node.value.length + 'B literal *)"'));
+                    resp.push(emitEntry(logPlaceholder(node.value.length, 'literal')));
                 }
                 else {
                     // The literal size marker counts octets - string values are written as
@@ -178,8 +183,8 @@ async function compiler(response, options) {
                 }
                 break;
             case 'STRING':
-                if (isLogging && node.value.length > 100) {
-                    resp.push(emitEntry('"(* ' + node.value.length + 'B string *)"'));
+                if (isLogging && node.value.length > LOG_VALUE_LIMIT) {
+                    resp.push(emitEntry(logPlaceholder(node.value.length, 'string')));
                 }
                 else {
                     val = (node.value || '').toString();
@@ -194,19 +199,22 @@ async function compiler(response, options) {
                 // when logging: the incoming token parser accepts sequence-shaped tokens
                 // this strict grammar rejects (an ESEARCH set like "1:2:3", a folder
                 // name like "12:30:00"), and re-compiling a server response for the log
-                // or for error text must never throw.
-                if (!isLogging && (typeof node.value === 'string' || typeof node.value === 'number' || Buffer.isBuffer(node.value))) {
-                    val = node.value.toString();
-                    if (val && !isValidSequenceSet(val)) {
+                // or for error text must never throw. An empty or missing set is refused
+                // too: it would put nothing on the wire and leave the next argument in its
+                // place.
+                // Emitted raw: the validated alphabet cannot contain a line terminator, and
+                // re-scanning a potentially multi-megabyte set in the choke point would
+                // double the cost of exactly the sets this branch exists for
+                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;
                     }
+                    resp.push(emitEntry(val, { raw: true }));
                 }
-                if (node.value) {
-                    // raw: the validated alphabet cannot contain a line terminator, and
-                    // re-scanning a potentially multi-megabyte set in the choke point
-                    // would double the cost of exactly the sets this branch exists for
+                else if (node.value) {
                     resp.push(emitEntry(node.value, { raw: true }));
                 }
                 break;
@@ -234,11 +242,16 @@ async function compiler(response, options) {
             case 'SECTION':
                 val = (node.value || '').toString();
                 if (!node.section || val) {
-                    // Verify the value contains only valid ATOM-CHAR characters.
-                    // Strip a leading backslash before checking (system flags like \Seen start with '\').
-                    // If any character fails verification, fall back to an IMAP quoted string
-                    // (JSON.stringify is used only for log output, where values are display-escaped).
-                    if (node.value === '' || imapFormalSyntax.verify(val.charAt(0) === '\\' ? val.slice(1) : val, imapFormalSyntax['ATOM-CHAR']()) >= 0) {
+                    if (isLogging && val.length > LOG_VALUE_LIMIT) {
+                        // A server can put a line's worth of bytes in one unquoted token
+                        val = logPlaceholder(val.length, 'atom');
+                    }
+                    else if (node.value === '' ||
+                        imapFormalSyntax.verify(val.charAt(0) === '\\' ? val.slice(1) : val, imapFormalSyntax['ATOM-CHAR']()) >= 0) {
+                        // An empty value, or one with a character outside ATOM-CHAR (checked
+                        // past a leading backslash, as system flags like \Seen carry one), goes
+                        // out as an IMAP quoted string. JSON.stringify is used only for log
+                        // output, where values are display-escaped.
                         val = isLogging ? JSON.stringify(val) : quoteString(val);
                     }
                     resp.push(emitEntry(val));
@@ -247,10 +260,12 @@ async function compiler(response, options) {
                 // e.g., BODY[HEADER.FIELDS (Subject)] or BODY[1.MIME]
                 if (node.section) {
                     resp.push(emitEntry('['));
+                    afterOpener = true;
                     for (let child of node.section) {
                         await walk(child);
                     }
                     resp.push(emitEntry(']'));
+                    afterOpener = false;
                 }
                 // Partial range: emit <origin.length> after the section brackets. Coerced
                 // rather than joined as-is: this is the last token component written
@@ -273,6 +288,7 @@ async function compiler(response, options) {
         respParts.push(resp);
     }
     const compiled = respParts.map(part => Buffer.concat(part));
-    return asArray ? compiled : compiled.flatMap(entry => entry);
+    // without asArray there is a single part, returned as is instead of copied
+    return asArray ? compiled : compiled.length === 1 ? compiled[0] : Buffer.concat(compiled);
 }
 export default compiler;

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

@@ -2,6 +2,17 @@ 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;
+export declare const ERROR_CONTEXT_LENGTH = 1024;
+/**
+ * The input a parse error carries: a bounded prefix with the full length.
+ *
+ * @param input - The input that failed to parse
+ * @returns The bounded prefix and the full length
+ */
+export declare const boundedInput: (input: string) => {
+    input: string;
+    inputLength: number;
+};
 /**
  * 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

package/dist/esm/handler/limits.js

@@ -17,6 +17,20 @@ export const MAX_LINE_SIZE = MAX_LITERAL_SIZE;
 // 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.
 export const MAX_RESPONSE_SIZE = 2 * MAX_LITERAL_SIZE;
+// How much of the offending input a parse error carries along. The error travels whole into log
+// entries (pino copies every property of a logged error) and into the rejection of the command
+// the line belonged to, and the line can be as long as the configured line cap.
+export const ERROR_CONTEXT_LENGTH = 1024;
+/**
+ * The input a parse error carries: a bounded prefix with the full length.
+ *
+ * @param input - The input that failed to parse
+ * @returns The bounded prefix and the full length
+ */
+export const boundedInput = (input) => ({
+    input: input.slice(0, ERROR_CONTEXT_LENGTH),
+    inputLength: input.length
+});
 /**
  * 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

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

@@ -21,6 +21,16 @@ export declare class ParserInstance {
      * @param options.literals - Pre-parsed literal values from the stream.
      */
     constructor(input?: Buffer | string | null | undefined, options?: ParserOptions | undefined);
+    /**
+     * The context a parse error carries: a bounded prefix of the input (and of the element that
+     * failed, when there is one) with their full lengths, and the position.
+     *
+     * @param element - The element that failed to parse
+     * @returns The context to attach to the error
+     */
+    errorContext(element?: string | undefined): {
+        [key: string]: unknown;
+    };
     /**
      * Extracts and returns the IMAP tag from the beginning of the response.
      * The tag is typically "*" for untagged responses, "+" for continuation requests,

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

@@ -1,6 +1,7 @@
 /* eslint new-cap: 0 */
 import imapFormalSyntax from './imap-formal-syntax.js';
 import { TokenParser } from './token-parser.js';
+import { boundedInput } from './limits.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
@@ -21,6 +22,22 @@ export class ParserInstance {
         this.remainder = this.input;
         this.pos = 0;
     }
+    /**
+     * The context a parse error carries: a bounded prefix of the input (and of the element that
+     * failed, when there is one) with their full lengths, and the position.
+     *
+     * @param element - The element that failed to parse
+     * @returns The context to attach to the error
+     */
+    errorContext(element) {
+        let context = { ...boundedInput(this.input), pos: this.pos };
+        if (element !== undefined) {
+            let bounded = boundedInput(element);
+            context.element = bounded.input;
+            context.elementLength = bounded.inputLength;
+        }
+        return context;
+    }
     /**
      * Extracts and returns the IMAP tag from the beginning of the response.
      * The tag is typically "*" for untagged responses, "+" for continuation requests,
@@ -122,7 +139,7 @@ export class ParserInstance {
         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 };
+            error.parserContext = this.errorContext();
             throw error;
         }
         if ((match = this.remainder.match(/^\s*[^\s]+(?=\s|$)/))) {
@@ -136,9 +153,7 @@ export class ParserInstance {
                     let error = new Error(`Server returned an error: ${this.input}`);
                     error.code = 'ParserErrorExchange';
                     error.parserContext = {
-                        input: this.input,
-                        element,
-                        pos: this.pos,
+                        ...this.errorContext(element),
                         value: {
                             tag: '*',
                             command: 'BAD',
@@ -149,14 +164,14 @@ export class ParserInstance {
                 }
                 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 };
+                error.parserContext = this.errorContext(element);
                 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 };
+            error.parserContext = this.errorContext();
             throw error;
         }
         this.pos += match[0].length;
@@ -177,13 +192,13 @@ export class ParserInstance {
             }
             let error = new Error(`Unexpected end of input at position ${this.pos} [E4]`);
             error.code = 'ParserError4';
-            error.parserContext = { input: this.input, pos: this.pos };
+            error.parserContext = this.errorContext();
             throw error;
         }
         if (imapFormalSyntax.verify(this.remainder.charAt(0), imapFormalSyntax.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 };
+            error.parserContext = this.errorContext(this.remainder);
             throw error;
         }
         this.pos++;
@@ -201,13 +216,13 @@ export class ParserInstance {
         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 };
+            error.parserContext = this.errorContext();
             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 };
+            error.parserContext = this.errorContext(this.remainder);
             throw error;
         }
         const tokenParser = new TokenParser(this, this.pos, this.remainder, this.options);