imapflow 2.4.3 → 2.5.1

package/dist/cjs/types.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectionOptions, CipherNameAndProtocol } from 'node:tls';
-import type { Readable } from 'node:stream';
+import type { Duplex, Readable } from 'node:stream';
 /**
  * Logger interface. Any object with `debug`, `info`, `warn` and `error` methods can be used,
  * for example a pino or bunyan instance. `trace` and `fatal` are used when present.
@@ -95,6 +95,14 @@ export interface ImapFlowOptions {
      * Node as-is. Proxy DNS and negotiation run inside `connectionTimeout`.
      */
     proxy?: string | undefined;
+    /**
+     * Opens the connection through this transport instead of `node:net` and `node:tls`, for
+     * runtimes without those modules. `createSocketsTransport()` builds one from the
+     * `connect()` of the `cloudflare:sockets` API (celld, Cloudflare Workers),
+     * `createStreamsTransport()` from any socket API built on web streams. Can not be combined
+     * with `proxy`.
+     */
+    transport?: ImapTransport | undefined;
     /** If true, then use QRESYNC instead of CONDSTORE. EXPUNGE notifications will include UID instead of sequence number */
     qresync?: boolean | undefined;
     /** If set, then breaks and restarts IDLE every maxIdleTime ms */
@@ -162,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 */
@@ -882,3 +891,70 @@ export interface ImapFlowEvents {
     /** The server sent an ALERT: text meant for the user, such as a planned shutdown or an account problem */
     alert: [alert: AlertEvent];
 }
+/** Where {@link ImapTransport} connects to, and the `tls` options of the client */
+export interface ImapTransportOptions {
+    host: string;
+    port: number;
+    /** The SNI name, absent for an IP literal host without the `servername` option */
+    servername?: string | undefined;
+    /** The `tls` option of the client */
+    tls?: ConnectionOptions | undefined;
+}
+/** What {@link ImapTransport.connect} gets: the destination, and whether to open a TLS connection */
+export interface ImapTransportConnectOptions extends ImapTransportOptions {
+    /** Open a TLS connection (the `secure` option), otherwise a cleartext one */
+    secure: boolean;
+}
+/**
+ * The socket a {@link ImapTransport} returns: a Duplex stream of Buffers that emits `error`,
+ * `end` and `close`, and `timeout` once `setTimeout(ms)` was called and `ms` passed without
+ * traffic (0 disables it, like `net.Socket#setTimeout()`), the watchdog behind the
+ * `socketTimeout` option. The rest of what a `net.Socket` has is optional; ImapFlow uses it when
+ * it is there (the addresses for logging, the cipher of a TLS connection for `client.tls`).
+ */
+export type ImapTransportSocket = Duplex & {
+    setTimeout(ms: number): unknown;
+    setKeepAlive?: ((enable?: boolean, initialDelay?: number) => unknown) | undefined;
+    remoteAddress?: string | undefined;
+    remotePort?: number | undefined;
+    localAddress?: string | undefined;
+    localPort?: number | undefined;
+    getCipher?: (() => CipherNameAndProtocol | null) | undefined;
+    authorized?: boolean | undefined;
+};
+/**
+ * Opens and upgrades the socket carrying the session, see the `transport` option.
+ * `createStreamsTransport()` builds one over any socket API built on web streams,
+ * `createSocketsTransport()` over `cloudflare:sockets`.
+ */
+export interface ImapTransport {
+    /**
+     * Opens a connection, cleartext or TLS. Connection errors are emitted on the returned
+     * socket; a connection refused up front (an option the transport can not honor) may throw.
+     *
+     * @param options - Destination, TLS options and whether to open a TLS connection
+     * @param onConnect - Called once the connection (and the TLS handshake) is established
+     */
+    connect(options: ImapTransportConnectOptions, onConnect: () => void): ImapTransportSocket;
+    /**
+     * Called right before the STARTTLS command is sent on the cleartext socket, so a transport
+     * that can only start TLS without a read in flight can stop reading once it is answered.
+     * STARTTLS is the only command in flight then: the next tagged response line (one that does
+     * not start with `* ` or `+ `) answers it, and if it is an OK, the server sends nothing more
+     * before the TLS handshake.
+     *
+     * @param socket - The cleartext socket returned by connect()
+     */
+    prepareUpgrade?: ((socket: ImapTransportSocket) => void) | undefined;
+    /**
+     * Starts TLS on a connected cleartext socket after STARTTLS. May throw if the upgrade is
+     * refused before any handshake, handshake errors are emitted on the returned socket. A
+     * transport that can not start TLS leaves it out: ImapFlow then treats the server as one
+     * without STARTTLS (see the `doSTARTTLS` option).
+     *
+     * @param socket - The cleartext socket returned by connect()
+     * @param options - Destination and TLS options
+     * @param onSecure - Called once the TLS handshake is complete
+     */
+    upgrade?: ((socket: ImapTransportSocket, options: ImapTransportOptions, onSecure: () => void) => ImapTransportSocket) | undefined;
+}

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";
@@ -47,6 +48,7 @@ export declare const ImapFlowErrorCode: {
     readonly EPROXY: "EPROXY";
     readonly UnsupportedProxyAddress: "UnsupportedProxyAddress";
     readonly ERR_INVALID_URL: "ERR_INVALID_URL";
+    readonly UnsupportedTransportOption: "UnsupportedTransportOption";
     readonly InstanceReused: "InstanceReused";
 };
 /** One of the {@link ImapFlowErrorCode} values */

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',
@@ -54,6 +56,8 @@ export const ImapFlowErrorCode = {
     EPROXY: 'EPROXY',
     UnsupportedProxyAddress: 'UnsupportedProxyAddress',
     ERR_INVALID_URL: 'ERR_INVALID_URL',
+    // the transport option
+    UnsupportedTransportOption: 'UnsupportedTransportOption',
     // API misuse
     InstanceReused: 'InstanceReused'
 };

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)

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

@@ -9,14 +9,23 @@ const STATE_PARTIAL = 0x004;
 const STATE_SEQUENCE = 0x005;
 const STATE_STRING = 0x006;
 const RE_SINGLE_DIGIT = /^\d$/;
-// Prevents stack overflow from maliciously crafted deeply-nested IMAP input (e.g., (((((...))))))
-const MAX_NODE_DEPTH = 25;
+// Prevents stack overflow from maliciously crafted deeply-nested IMAP input (e.g., (((((...)))))).
+// The tokenizer itself is iterative; what recurses is the getAttributes() walk and the
+// consumers of its output (the body structure parser, the compiler used for logging), and
+// a hundred frames is nothing to any of them. The old bound of 25 was reached by a message
+// with 22 nested multiparts, which an external sender can produce, and the whole FETCH row
+// then failed to parse and was dropped silently.
+const MAX_NODE_DEPTH = 100;
+// The depth at which the data items of a FETCH response sit: TREE (0) > the item list (1) >
+// a key or value (2). See createNode() for what happens when nesting overflows below one.
+const FETCH_DATA_ITEM_DEPTH = 2;
 /**
  * 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.
+ * 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 class TokenParser {
     /**
@@ -38,6 +47,7 @@ export class TokenParser {
         // Same normalization and default as the streaming parser, so a direct user of this parser
         // gets the same bound (an explicit 0 means "reject any non-empty inline literal").
         this.maxLiteralSize = normalizeLimit(this.options.maxLiteralSize, MAX_LITERAL_SIZE);
+        this.truncatedAttributes = [];
         this.tree = this.currentNode = this.createNode();
         this.pos = startPos || 0;
         this.currentNode.type = 'TREE';
@@ -86,6 +96,16 @@ export class TokenParser {
                 throw this.parserError(`Unexpected end of input at position ${this.pos + this.str.length - 1} [E9]`, 'ParserError9', this.pos + this.str.length - 1);
             }
             let type = (node.type || '').toString().toUpperCase();
+            if (node.truncated) {
+                // The item nested deeper than MAX_NODE_DEPTH, see createNode(). Its subtree is
+                // not walked (that is what keeps this recursion bounded). A list is replaced by
+                // NIL so the data items keep pairing up as key and value; a section is attached
+                // to the item before it, so it is dropped whole.
+                if (type === 'LIST') {
+                    branch.push(null);
+                }
+                return;
+            }
             switch (type) {
                 case 'LITERAL':
                 case 'STRING':
@@ -136,7 +156,7 @@ export 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, startPos) {
         let node = {
@@ -154,8 +174,20 @@ export class TokenParser {
             node.depth = 0;
         }
         if (node.depth > MAX_NODE_DEPTH) {
-            // A bounded prefix only, the error travels whole into logs and rejections
-            throw createImapError('Too much nesting in IMAP string', 'MAX_IMAP_NESTING_REACHED', { _imapStr: this.str.slice(0, ERROR_CONTEXT_LENGTH) });
+            if (!this.isFetchResponse()) {
+                // A bounded prefix only, the error travels whole into logs and rejections
+                throw createImapError('Too much nesting in IMAP string', 'MAX_IMAP_NESTING_REACHED', { _imapStr: this.str.slice(0, ERROR_CONTEXT_LENGTH) });
+            }
+            // A FETCH row carries the data of one message, and the item nesting this deep (a
+            // BODYSTRUCTURE of a message with a hundred nested multiparts, which the sender of
+            // that message controls) is one of several. Failing the line would drop the whole
+            // row, and with it the message, from the FETCH result. The data item is marked
+            // instead, which getAttributes() turns into NIL, and the tokenizer carries on: it
+            // keeps no stack, so the depth costs it nothing. Marked on the first crossing only,
+            // every node below that one is already inside a marked item.
+            if (parentNode.depth === MAX_NODE_DEPTH) {
+                this.truncateFetchDataItem(parentNode);
+            }
         }
         if (typeof startPos === 'number') {
             node.startPos = startPos;
@@ -165,6 +197,44 @@ export class TokenParser {
         }
         return node;
     }
+    /**
+     * 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() {
+        let command = this.parent.command;
+        let first = this.tree.childNodes[0];
+        return (typeof command === 'string' &&
+            /^\d+$/.test(command) &&
+            !!first &&
+            first.type === 'ATOM' &&
+            typeof first.value === 'string' &&
+            first.value.toUpperCase() === 'FETCH');
+    }
+    /**
+     * 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) {
+        let item = node;
+        while (item.depth > FETCH_DATA_ITEM_DEPTH && item.parentNode) {
+            item = item.parentNode;
+        }
+        if (item.truncated) {
+            return;
+        }
+        item.truncated = true;
+        // The item is the last child of the list while it is being parsed, so its key is the
+        // child before it. A key is an atom (BODYSTRUCTURE, ENVELOPE, BODY); anything else means
+        // the row itself is malformed, and the key is reported as unknown.
+        let siblings = item.parentNode ? item.parentNode.childNodes : [];
+        let key = siblings[siblings.length - 2];
+        this.truncatedAttributes.push(key && key.type === 'ATOM' && typeof key.value === 'string' ? key.value.toUpperCase() : '?');
+    }
     /**
      * Processes the entire input string character by character using a state machine.
      * Transitions between states (NORMAL, ATOM, STRING, LITERAL, SEQUENCE, PARTIAL, TEXT)

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

@@ -39,6 +39,11 @@ export interface ImapResponse {
     attributes?: ImapAttributeList | undefined;
     /** Number of leading NUL bytes stripped from the line, if any */
     nullBytesRemoved?: number | undefined;
+    /**
+     * Keys of the FETCH data items (e.g. BODYSTRUCTURE) that were replaced by NIL because they
+     * nested deeper than the parser's limit, if any
+     */
+    truncatedAttributes?: string[] | undefined;
 }
 /**
  * What the command compiler accepts as a node: parsed tokens and lists, and also bare

package/dist/esm/imap-flow.d.ts

@@ -1,15 +1,17 @@
 /**
  * @module imapflow
  */
-import tls from 'node:tls';
-import net from 'node:net';
 import { EventEmitter } from 'node:events';
 import { PassThrough, type Readable } from 'node:stream';
 import { AuthenticationFailure } from './errors.js';
-import type { AppendResponseObject, CopyResponseObject, DownloadManyOptions, DownloadManyResult, DownloadObject, DownloadNotFound, DownloadOptions, ESearchResult, FetchMessageObject, FetchOptions, FetchQueryObject, IdInfoObject, ImapFlowEvents, ImapFlowOptions, InternalLogger, ListOptions, ListResponse, ListTreeResponse, MailboxCreateResponse, MailboxDeleteResponse, MailboxLockObject, MailboxLockOptions, MailboxObject, MailboxOpenOptions, MailboxRenameResponse, MessageRange, MessageRangeOptions, NamespaceObject, NamespacesObject, QuotaResponse, SearchObject, SearchOptions, SearchReturnOption, SequenceString, StatusObject, StatusQuery, StoreOptions, TlsInfo } from './types.js';
+import type { AppendResponseObject, CopyResponseObject, DownloadManyOptions, DownloadManyResult, DownloadObject, DownloadNotFound, DownloadOptions, ESearchResult, FetchMessageObject, FetchOptions, FetchQueryObject, IdInfoObject, ImapFlowEvents, ImapFlowOptions, InternalLogger, ListOptions, ListResponse, ListTreeResponse, MailboxCreateResponse, MailboxDeleteResponse, MailboxLockObject, MailboxLockOptions, MailboxObject, MailboxOpenOptions, MailboxRenameResponse, MessageRange, MessageRangeOptions, NamespaceObject, NamespacesObject, QuotaResponse, SearchObject, SearchOptions, SearchReturnOption, SequenceString, StatusObject, StatusQuery, StoreOptions, TlsInfo, ImapTransportSocket } from './types.js';
 export type * from './types.js';
 export type { ImapFlowError } from './errors.js';
 export { AuthenticationFailure, ImapFlowErrorCode } from './errors.js';
+export { createSocketsTransport } from './sockets-transport.js';
+export type { SocketsApiSocket, SocketsConnect } from './sockets-transport.js';
+export { createStreamsTransport } from './streams-transport.js';
+export type { StreamsReader, StreamsSocket, StreamsSocketInfo, StreamsTlsInfo, StreamsTransportApi, StreamsWriter } from './streams-transport.js';
 export type { ImapAttribute, ImapAttributeList, ImapAttributeNode, ImapResponse } from './handler/types.js';
 declare const stateValues: {
     readonly NOT_AUTHENTICATED: 1;
@@ -27,13 +29,11 @@ export type ConnectionStates = {
     readonly [K in keyof typeof stateValues]: ConnectionState;
 };
 /**
- * The socket carrying the IMAP session. A TLS socket exposes `getCipher()` and `authorized`, a
- * cleartext socket does not, and the code checks for them at runtime.
+ * The socket carrying the IMAP session: a `net.Socket` or `tls.TLSSocket` on Node.js, or what a
+ * transport returns. Typed as {@link ImapTransportSocket}, so the client only relies on what
+ * every transport provides and checks for the optional members at runtime.
  */
-export type ImapSocket = net.Socket & {
-    getCipher?: (() => tls.CipherNameAndProtocol) | undefined;
-    authorized?: boolean | undefined;
-};
+export type ImapSocket = ImapTransportSocket;
 /**
  * Where outgoing bytes are written: the socket itself, or the PassThrough that feeds the
  * DEFLATE stream once compression is active