imapflow 2.5.0 → 2.5.1

package/dist/cjs/tools.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.noop = exports.MAX_UINT32_DIGITS = exports.EXPANDED_RANGE_LIMIT = exports.AuthenticationFailure = void 0;
+exports.noop = exports.MAX_UINT32_DIGITS = exports.MAX_COLLECTED_RESPONSES = exports.EXPANDED_RANGE_LIMIT = exports.AuthenticationFailure = void 0;
 exports.isIpLiteral = isIpLiteral;
 exports.buildConnectionError = buildConnectionError;
 exports.restampConnectionError = restampConnectionError;
@@ -53,6 +53,8 @@ exports.getStringList = getStringList;
 exports.getStringValue = getStringValue;
 exports.parseBigIntValue = parseBigIntValue;
 exports.parseUintValue = parseUintValue;
+exports.iterateRange = iterateRange;
+exports.countRange = countRange;
 exports.expandRange = expandRange;
 exports.getDecoder = getDecoder;
 exports.packMessageRange = packMessageRange;
@@ -77,6 +79,15 @@ const CONNECTION_GONE_CODES = new Set([errors_js_1.ImapFlowErrorCode.NoConnectio
 // expand server sequences (e.g. ESEARCH ALL in commands/search.ts) can apply the same absolute
 // ceiling instead of inventing their own.
 exports.EXPANDED_RANGE_LIMIT = 0x1000000;
+// Upper bound for the untagged responses one command may accumulate in memory: the FETCH rows
+// fetchAll() collects and the mailboxes list() collects. The response size limits bound one
+// response at a time, not how many of them a server sends in reply to one command, so a hostile
+// server answering a single-message FETCH with an endless stream of unsolicited FETCH rows (or a
+// LIST with endless mailboxes) would otherwise grow the process without limit. Generous on
+// purpose: a million rows is far beyond any legitimate listing, and a mailbox that large is read
+// through the streaming fetch() generator, which keeps nothing. Reaching it therefore fails the
+// command (code TooManyResponses) instead of silently truncating its result.
+exports.MAX_COLLECTED_RESPONSES = 1000000;
 // Digit bounds for untrusted numeric values in server responses. UIDs, UIDVALIDITY and
 // message counts are 32-bit unsigned (nz-number in the RFC 9051 grammar, so at most 10
 // digits); MODSEQ and number64 values are 63-bit unsigned (RFC 7162, RFC 9051), at most
@@ -606,13 +617,30 @@ function getFolderTree(folders) {
         root: true,
         folders: []
     };
+    // Children of every node indexed by name. Looking a child up with folders.find() made the
+    // tree quadratic in the number of siblings: a listing of 50k mailboxes at one level (a size
+    // the server chooses) took seconds of event loop time. A name is unique among its siblings,
+    // as the loop below updates an existing entry rather than adding a second one.
+    let childIndex = new Map();
+    let childByName = (node, name) => {
+        let index = childIndex.get(node);
+        return index ? index.get(name) : undefined;
+    };
+    let indexChild = (node, child) => {
+        let index = childIndex.get(node);
+        if (!index) {
+            index = new Map();
+            childIndex.set(node, index);
+        }
+        index.set(child.name, child);
+    };
     let getTreeNode = (parents) => {
         let node = tree;
         if (!parents || !parents.length) {
             return node;
         }
         for (let parent of parents) {
-            let cur = node.folders && node.folders.find(folder => folder.name === parent);
+            let cur = childByName(node, parent);
             if (cur) {
                 node = cur;
             }
@@ -627,7 +655,7 @@ function getFolderTree(folders) {
     for (let folder of byDepth) {
         let parent = getTreeNode(folder.parent);
         // see if entry already exists
-        let existing = parent.folders && parent.folders.find(existing => existing.name === folder.name);
+        let existing = childByName(parent, folder.name);
         if (existing) {
             // update values
             existing.name = folder.name;
@@ -672,6 +700,7 @@ function getFolderTree(folders) {
                 parent.folders = [];
             }
             parent.folders.push(data);
+            indexChild(parent, data);
         }
     }
     return tree;
@@ -1566,67 +1595,103 @@ function parseUintValue(value, maxDigits) {
     return Number.isSafeInteger(num) ? num : false;
 }
 /**
- * Expands an IMAP sequence range string (e.g. "1:3,5,7:9") into an array of numbers.
+ * Parses an IMAP sequence set string (e.g. "1:3,5,9:7") into its entries, each as the pair of
+ * endpoints in the order written: a reversed "9:7" stays reversed, and iterateRange() walks it
+ * downwards. Entries with an endpoint that is not a valid nz-number are skipped - the input may
+ * come from an untrusted server, and 'Infinity' or similar garbage would otherwise loop without
+ * bound.
  *
- * Entries with endpoints that are not valid nz-numbers are skipped - the input
- * may come from an untrusted server, and 'Infinity' or similar garbage would
- * otherwise loop without bound. The whole set is expanded to at most
- * EXPANDED_RANGE_LIMIT entries in total: legitimate responses never reach the limit
- * (the mailbox would need that many messages), while hostile input is cut off
- * instead of exhausting memory. The total is capped, not just each range -
- * otherwise "1:16777216,1:16777216,..." would multiply the per-range bound by an
- * unbounded number of ranges.
- *
- * @param range - IMAP sequence range string
- * @returns Array of expanded sequence numbers
+ * @param range - IMAP sequence set string, or whatever the response parser produced for it
+ * @returns The validated entries
  */
-function expandRange(range) {
-    let result = [];
+function parseRangeEntries(range) {
+    let entries = [];
     // Callers pass whatever the response parser produced for the sequence set, and a
     // malformed response can leave that as `false` (e.g. a VANISHED response carrying
     // only the (EARLIER) tag). Nothing to expand then, and throwing here would abort
     // the handler for the rest of the response.
     if (typeof range !== 'string') {
-        return result;
+        return entries;
     }
     for (let entry of range.split(',')) {
-        if (result.length >= exports.EXPANDED_RANGE_LIMIT) {
-            break;
-        }
         entry = entry.trim();
         let colon = entry.indexOf(':');
         if (colon < 0) {
             let value = Number(entry);
             if (isValidSequenceValue(value)) {
-                result.push(value);
+                entries.push([value, value]);
             }
             continue;
         }
         let first = Number(entry.substring(0, colon));
         let second = Number(entry.slice(colon + 1));
-        if (!isValidSequenceValue(first) || !isValidSequenceValue(second)) {
-            continue;
+        if (isValidSequenceValue(first) && isValidSequenceValue(second)) {
+            entries.push([first, second]);
         }
-        if (first === second) {
-            result.push(first);
-            continue;
-        }
-        // Remaining total budget doubles as the per-range bound
-        let remaining = exports.EXPANDED_RANGE_LIMIT - result.length;
-        if (first < second) {
-            let last = Math.min(second, first + remaining - 1);
-            for (let i = first; i <= last; i++) {
-                result.push(i);
+    }
+    return entries;
+}
+/**
+ * Walks an IMAP sequence range string (e.g. "1:3,5,7:9") one number at a time, without
+ * materializing it. A single "1:16777216" is a few bytes on the wire but sixteen million
+ * entries expanded, so a consumer that only needs to visit each number (the VANISHED handler)
+ * iterates instead of calling expandRange().
+ *
+ * The same bound as expandRange() applies: at most EXPANDED_RANGE_LIMIT numbers in total are
+ * produced, over all entries of the set.
+ *
+ * @param range - IMAP sequence range string
+ * @returns The sequence numbers, in the order the set lists them
+ */
+function* iterateRange(range) {
+    let count = 0;
+    for (let [first, second] of parseRangeEntries(range)) {
+        let step = first <= second ? 1 : -1;
+        for (let i = first; count < exports.EXPANDED_RANGE_LIMIT; i += step) {
+            yield i;
+            count++;
+            if (i === second) {
+                break;
             }
         }
-        else {
-            let last = Math.max(second, first - remaining + 1);
-            for (let i = first; i >= last; i--) {
-                result.push(i);
-            }
+        if (count >= exports.EXPANDED_RANGE_LIMIT) {
+            break;
         }
     }
-    return result;
+}
+/**
+ * Counts the numbers iterateRange() produces for a sequence range string, without walking it.
+ *
+ * @param range - IMAP sequence range string
+ * @returns The number of entries, capped at EXPANDED_RANGE_LIMIT like the expansion itself
+ */
+function countRange(range) {
+    let count = 0;
+    for (let [first, second] of parseRangeEntries(range)) {
+        count += Math.abs(second - first) + 1;
+        if (count >= exports.EXPANDED_RANGE_LIMIT) {
+            return exports.EXPANDED_RANGE_LIMIT;
+        }
+    }
+    return count;
+}
+/**
+ * Expands an IMAP sequence range string (e.g. "1:3,5,7:9") into an array of numbers.
+ *
+ * Entries with endpoints that are not valid nz-numbers are skipped - the input
+ * may come from an untrusted server, and 'Infinity' or similar garbage would
+ * otherwise loop without bound. The whole set is expanded to at most
+ * EXPANDED_RANGE_LIMIT entries in total: legitimate responses never reach the limit
+ * (the mailbox would need that many messages), while hostile input is cut off
+ * instead of exhausting memory. The total is capped, not just each range -
+ * otherwise "1:16777216,1:16777216,..." would multiply the per-range bound by an
+ * unbounded number of ranges.
+ *
+ * @param range - IMAP sequence range string
+ * @returns Array of expanded sequence numbers
+ */
+function expandRange(range) {
+    return Array.from(iterateRange(range));
 }
 /**
  * Returns a stream decoder for the given charset. Uses a special Japanese
@@ -1668,20 +1733,21 @@ function packMessageRange(list) {
     // Deduplicate before sorting so that repeated values do not produce
     // overlapping/non-canonical tokens (e.g. [1,1,2,3] -> "1:3", not "1,1:3").
     items = Array.from(new Set(items)).sort((a, b) => a - b);
-    let last = items[items.length - 1];
-    let result = [[last]];
-    for (let i = items.length - 2; i >= 0; i--) {
-        if (items[i] === items[i + 1] - 1) {
-            result[0].unshift(items[i]);
+    // One forward pass: a run of consecutive values is written out as soon as it ends. The runs
+    // used to be built with unshift(), which copies the array on every call, so packing a large
+    // SEARCH result (a server-chosen size) took seconds for 200k UIDs and about a minute for 1M,
+    // all of it on the event loop.
+    let parts = [];
+    let start = items[0];
+    let prev = start;
+    for (let i = 1; i <= items.length; i++) {
+        let value = items[i];
+        if (i < items.length && value === prev + 1) {
+            prev = value;
             continue;
         }
-        result.unshift([items[i]]);
+        parts.push(start === prev ? String(start) : start + ':' + prev);
+        start = prev = value;
     }
-    let parts = result.map(item => {
-        if (item.length === 1) {
-            return item[0];
-        }
-        return item.shift() + ':' + item.pop();
-    });
     return parts.join(',');
 }

package/dist/cjs/types.d.ts

@@ -170,7 +170,8 @@ export interface ImapFlowOptions {
      * when the server offers STARTTLS and otherwise continues in cleartext with a warning logged:
      * the capability list that decides this was itself received in cleartext, so an attacker on
      * the path can strip it. Set `doSTARTTLS: true` whenever the credentials must never cross the
-     * wire unencrypted.
+     * wire unencrypted. STARTTLS is only possible before authentication, so a server greeting
+     * with PREAUTH is a connection failure when the upgrade is required.
      */
     doSTARTTLS?: boolean | undefined;
     /** Custom instance ID string for logs */

package/dist/esm/commands/authenticate.js

@@ -1,4 +1,33 @@
 import { getStatusCode, getErrorText, isServerRefusal } from '../tools.js';
+import { createImapError } from '../errors.js';
+// The OAuth SASL payloads are framed with \x01 (RFC 7628 section 3.1, and the XOAUTH2 format
+// copies it), so a control character in a value ends the field early and the rest of the value
+// becomes fields of its own, auth= included. RFC 7628 allows only VCHAR, SP, HTAB, CR and LF in
+// a value, and none of the controls has a place in a username or a bearer token.
+const RE_CONTROL_CHARS = /[\x00-\x1f\x7f]/;
+/**
+ * Refuses a username or token that could not be framed as one SASL field.
+ *
+ * @param value - The value about to be placed in the payload
+ * @param what - What the value is, for the error message
+ * @throws If the value contains a control character
+ */
+function assertSaslValue(value, what) {
+    if (RE_CONTROL_CHARS.test(value)) {
+        throw createImapError(`The ${what} contains control characters`, 'InvalidStringValue');
+    }
+}
+/**
+ * Escapes a value for the authzid of a GS2 header (RFC 5801 section 4): "," and "=" delimit
+ * the header, so they are written as =2C and =3D. "=" goes first, so the "=" the escaping
+ * itself introduces is not escaped again.
+ *
+ * @param value - The saslname
+ * @returns The escaped saslname
+ */
+function escapeSaslName(value) {
+    return value.replace(/[=]/g, '=3D').replace(/,/g, '=2C');
+}
 /**
  * Handles authentication errors by enriching the error object with server response details.
  *
@@ -34,6 +63,8 @@ async function authOauth(connection, username, accessToken) {
     let oauthbearer;
     let command;
     let breaker;
+    assertSaslValue(username, 'username');
+    assertSaslValue(accessToken, 'access token');
     if (connection.capabilities.has('AUTH=OAUTHBEARER')) {
         // OAUTHBEARER payload per RFC 7628: fields separated by \x01 (SASL GS2 framing).
         // Format: "n,a=<user>," \x01 "host=..." \x01 "port=..." \x01 "auth=Bearer <token>" \x01 \x01
@@ -44,7 +75,7 @@ async function authOauth(connection, username, accessToken) {
         // A server validating either field rejects with status `invalid_request` - a permanent
         // failure that refreshing the access token can never clear.
         oauthbearer = [
-            `n,a=${username},`,
+            `n,a=${escapeSaslName(username)},`,
             `host=${connection.servername || connection.host}`,
             `port=${connection.port}`,
             `auth=Bearer ${accessToken}`,

package/dist/esm/commands/fetch.js

@@ -1,4 +1,5 @@
-import { formatMessageResponse, isRev2Active, getSelectedMailbox } from '../tools.js';
+import { formatMessageResponse, isRev2Active, getSelectedMailbox, MAX_COLLECTED_RESPONSES } from '../tools.js';
+import { createImapError } from '../errors.js';
 /**
  * Fetches emails from the server.
  *
@@ -35,9 +36,10 @@ export default async function fetch(connection, range, query, options) {
             count: 0,
             list: []
         };
-        // The first error the onUntaggedFetch consumer reported through next(err). Errors thrown
-        // by untagged handlers are only logged by the connection, so it is kept here and fails
-        // the command once the FETCH completes; later messages are no longer handed to the consumer.
+        // The first error the onUntaggedFetch consumer reported through next(err), or the row
+        // limit being reached. Errors thrown by untagged handlers are only logged by the
+        // connection, so it is kept here and fails the command once the FETCH completes; later
+        // messages are no longer handed to the consumer or collected.
         let consumerError = null;
         let response;
         try {
@@ -232,6 +234,11 @@ export default async function fetch(connection, range, query, options) {
                                 consumerError = err;
                             }
                         }
+                        else if (messages.list.length >= MAX_COLLECTED_RESPONSES) {
+                            // The rows are the server's to send and the memory holding them is
+                            // this process's, see MAX_COLLECTED_RESPONSES
+                            consumerError = createImapError(`FETCH returned more than ${MAX_COLLECTED_RESPONSES} messages`, 'TooManyResponses');
+                        }
                         else {
                             messages.list.push(formatted);
                         }

package/dist/esm/commands/idle.js

@@ -37,6 +37,12 @@ async function runIdle(connection) {
     // connection, so a newer IDLE session that already installed its own is left alone.
     let ownPreCheck = null;
     let releaseIdling = claimIdling(connection);
+    // The deadline for the server's "+" continuation, see the onSend handler below
+    let continuationTimer = null;
+    let clearContinuationTimer = () => {
+        clearTimer(continuationTimer);
+        continuationTimer = null;
+    };
     try {
         // State flags for the IDLE lifecycle:
         // - doneRequested: someone wants to break IDLE (e.g., to run another command)
@@ -102,6 +108,7 @@ async function runIdle(connection) {
             // After this, the server will push untagged responses for mailbox changes.
             // We can now safely send DONE if a break was already requested.
             onPlusTag: async () => {
+                clearContinuationTimer();
                 connection.log.debug({
                     msg: `Initiated IDLE, waiting for server input`,
                     lockId: connection.currentLock ? connection.currentLock.lockId : undefined,
@@ -118,7 +125,29 @@ async function runIdle(connection) {
                     }
                 }
             },
-            onSend: () => { }
+            // The server has socketTimeout from the moment IDLE is on the wire to acknowledge it
+            // with the "+". The socket watchdog only covers a server that goes quiet: one that
+            // keeps sending untagged lines without ever answering "+" kept the IDLE in flight for
+            // good, and every later command queued behind it. DONE can not be sent before the
+            // "+" (RFC 2177 section 3), so there is no way to break such an IDLE and fall back
+            // to polling; the connection is failed the way the watchdog fails a dead peer.
+            onSend: () => {
+                continuationTimer = unrefTimer(setTimeout(() => {
+                    continuationTimer = null;
+                    if (canEnd || connection.isClosed) {
+                        return;
+                    }
+                    connection.log.error({
+                        msg: 'Server did not acknowledge IDLE, closing the connection',
+                        timeout: connection.socketTimeout,
+                        cid: connection.id
+                    });
+                    connection.emitError(createImapError('IDLE was not acknowledged within the socket timeout', 'ETIMEOUT', {
+                        command: 'IDLE',
+                        details: { socketTimeout: connection.socketTimeout }
+                    }));
+                }, connection.socketTimeout));
+            }
         });
         response.next();
         return;
@@ -150,6 +179,7 @@ async function runIdle(connection) {
         // (including a server-terminated IDLE, where preCheck never ran), rejected command,
         // parser failure and connection close. `idling` drives socket-timeout handling, so it
         // must always describe reality rather than being left over from a previous state.
+        clearContinuationTimer();
         releaseIdling();
         if (connection.preCheck === ownPreCheck) {
             connection.preCheck = false;

package/dist/esm/commands/list.js

@@ -1,4 +1,5 @@
-import { decodePath, encodePath, normalizePath, enhanceCommandError, hasCapability, isRev2Active, buildStatusQueryAttributes, getStringList, getStringValue } from '../tools.js';
+import { decodePath, encodePath, normalizePath, enhanceCommandError, hasCapability, isRev2Active, buildStatusQueryAttributes, getStringList, getStringValue, MAX_COLLECTED_RESPONSES } from '../tools.js';
+import { createImapError } from '../errors.js';
 import { parseStatusList } from './status-fields.js';
 import { specialUse } from '../special-use.js';
 /**
@@ -137,6 +138,8 @@ export default async function list(connection, reference, mailbox, options) {
         // namespace prefix was used (INBOX may live outside the namespace).
         let runList = async (reference, mailbox, returnArgs) => {
             const cmdArgs = [encodePath(connection, reference), encodePath(connection, mailbox)];
+            // Set once the entry limit is reached, fails the command when it completes
+            let overflow = null;
             if (returnArgs.length) {
                 cmdArgs.push({ type: 'ATOM', value: 'RETURN' }, returnArgs);
             }
@@ -196,6 +199,14 @@ export default async function list(connection, reference, mailbox, options) {
                         if (specialUseFlag && (!isNameSource(flagSource) || !entry.flags.has('\\NonExistent'))) {
                             addSpecialUseMatch(entry, specialUseFlag, flagSource);
                         }
+                        if (entries.length >= MAX_COLLECTED_RESPONSES) {
+                            // The entries are the server's to send and the memory holding them
+                            // is this process's, see MAX_COLLECTED_RESPONSES. A throw from an
+                            // untagged handler is only logged, so the error is raised below,
+                            // once the command completes
+                            overflow = overflow || createImapError(`LIST returned more than ${MAX_COLLECTED_RESPONSES} mailboxes`, 'TooManyResponses');
+                            return;
+                        }
                         entries.push(entry);
                     },
                     // Inline STATUS response from LIST-STATUS extension (RFC 5819).
@@ -215,6 +226,9 @@ export default async function list(connection, reference, mailbox, options) {
                 }
             });
             response.next();
+            if (overflow) {
+                throw overflow;
+            }
         };
         let normalizedReference = normalizePath(connection, reference || '');
         let normalizedMailbox = normalizePath(connection, mailbox || '', true);

package/dist/esm/errors.d.ts

@@ -35,6 +35,7 @@ export declare const ImapFlowErrorCode: {
     readonly LineTooLarge: "LineTooLarge";
     readonly LiteralTooLarge: "LiteralTooLarge";
     readonly ResponseTooLarge: "ResponseTooLarge";
+    readonly TooManyResponses: "TooManyResponses";
     readonly InvalidStringValue: "InvalidStringValue";
     readonly InvalidTokenValue: "InvalidTokenValue";
     readonly InvalidTextValue: "InvalidTextValue";

package/dist/esm/errors.js

@@ -39,6 +39,8 @@ export const ImapFlowErrorCode = {
     LineTooLarge: 'LineTooLarge',
     LiteralTooLarge: 'LiteralTooLarge',
     ResponseTooLarge: 'ResponseTooLarge',
+    // one command received more untagged responses than are kept, see MAX_COLLECTED_RESPONSES
+    TooManyResponses: 'TooManyResponses',
     // invalid values in a command
     InvalidStringValue: 'InvalidStringValue',
     InvalidTokenValue: 'InvalidTokenValue',

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

@@ -81,6 +81,9 @@ export default async function parser(command, options) {
         if (parserInstance.remainder.trim().length) {
             await parserInstance.getSpace();
             response.attributes = await parserInstance.getAttributes();
+            if (parserInstance.truncatedAttributes && parserInstance.truncatedAttributes.length) {
+                response.truncatedAttributes = parserInstance.truncatedAttributes;
+            }
         }
         if (parserInstance.humanReadable) {
             response.attributes = (response.attributes || []).concat({

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

@@ -12,6 +12,8 @@ export declare class ParserInstance {
     tag?: string | undefined;
     command?: string | undefined;
     humanReadable?: string | undefined;
+    /** The keys of the FETCH data items the token parser dropped for exceeding the nesting limit */
+    truncatedAttributes?: string[] | undefined;
     /**
      * Creates a new ParserInstance for parsing an IMAP response line.
      *

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

@@ -211,6 +211,8 @@ export class ParserInstance {
             });
         }
         const tokenParser = new TokenParser(this, this.pos, this.remainder, this.options);
-        return await tokenParser.getAttributes();
+        let attributes = await tokenParser.getAttributes();
+        this.truncatedAttributes = tokenParser.truncatedAttributes;
+        return attributes;
     }
 }

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

@@ -22,6 +22,8 @@ export interface TokenNode {
     started?: boolean | undefined;
     chBuffer?: Buffer | undefined;
     chPos?: number | undefined;
+    /** Set on a FETCH data item whose nesting exceeded MAX_NODE_DEPTH, see createNode() */
+    truncated?: boolean | undefined;
 }
 /**
  * The parent object a TokenParser reads the parsed command from
@@ -34,7 +36,8 @@ export interface TokenParserParent {
  * 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.
+ * from malicious input: a FETCH data item that nests deeper is replaced by NIL and listed in
+ * `truncatedAttributes`, any other input that nests deeper fails to parse.
  */
 export declare class TokenParser {
     str: string;
@@ -45,6 +48,8 @@ export declare class TokenParser {
     currentNode: TokenNode;
     pos: number;
     state: number;
+    /** The keys of the FETCH data items that were dropped for exceeding MAX_NODE_DEPTH */
+    truncatedAttributes: string[];
     expectedLiteralType?: string | false | undefined;
     /**
      * Creates a new TokenParser.
@@ -88,9 +93,23 @@ export declare class TokenParser {
      * @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.
+     * @throws {Error} If the nesting depth exceeds MAX_NODE_DEPTH outside a FETCH data item.
      */
     createNode(parentNode?: TokenNode | undefined, startPos?: number | undefined): TokenNode;
+    /**
+     * Whether the line being parsed is a message data response (`* 12 FETCH (...)`): a numeric
+     * command with FETCH as its first attribute. Only those get the per-item nesting fallback.
+     *
+     * @returns True for an untagged FETCH response
+     */
+    isFetchResponse(): boolean;
+    /**
+     * Marks the FETCH data item a too deeply nested node belongs to as truncated and records
+     * its key (the item before it in the list, e.g. BODYSTRUCTURE) for the caller to report.
+     *
+     * @param node - The node at MAX_NODE_DEPTH whose child would exceed the limit
+     */
+    truncateFetchDataItem(node: TokenNode): void;
     /**
      * Processes the entire input string character by character using a state machine.
      * Transitions between states (NORMAL, ATOM, STRING, LITERAL, SEQUENCE, PARTIAL, TEXT)