imapflow 2.4.3 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.5.1](https://github.com/postalsys/imapflow/compare/v2.5.0...v2.5.1) (2026-10-16)
+
+
+### Bug Fixes
+
+* bound what a hostile server can make the client buffer or wait for, and keep a tagged BYE from passing as success ([9b969a7](https://github.com/postalsys/imapflow/commit/9b969a75090b84e3cbdea408ac4f36035eb2e71b))
+
+## [2.5.0](https://github.com/postalsys/imapflow/compare/v2.4.3...v2.5.0) (2026-10-16)
+
+
+### Features
+
+* add a transport option and createSocketsTransport() for celld ([f4411aa](https://github.com/postalsys/imapflow/commit/f4411aa55635cb46b0e29a31965816e613d10ab9))
+* add createStreamsTransport() for socket APIs built on web streams ([fec7999](https://github.com/postalsys/imapflow/commit/fec79997db36878a8e3222833837d09f011eac3e))
+
 ## [2.4.3](https://github.com/postalsys/imapflow/compare/v2.4.2...v2.4.3) (2026-10-15)
 
 

package/README.md

@@ -26,7 +26,65 @@ npm install imapflow
 
 ImapFlow requires Node.js 20 or newer. The package ships both an ES module build and a CommonJS build with bundled type declarations, so no separate `@types` package is needed.
 
-The ES module build also runs on [Bun](https://bun.sh/) (tested against the latest release) and on [Cloudflare Workers](https://developers.cloudflare.com/workers/) with the `nodejs_compat` compatibility flag. On Workers connect with implicit TLS (`secure: true`, usually port 993) or in cleartext: the runtime can not upgrade an already connected socket, so a STARTTLS negotiation fails with a TLS error, and it does not allow turning certificate validation off, so `tls: { rejectUnauthorized: false }` is rejected with `ERR_OPTION_NOT_IMPLEMENTED`. COMPRESS=DEFLATE, IDLE and the default pino logger work as on Node.js.
+The ES module build also runs on [Bun](https://bun.sh/) (tested against the latest release) and on [Cloudflare Workers](https://developers.cloudflare.com/workers/) with the `nodejs_compat` compatibility flag. On Workers connect with implicit TLS (`secure: true`, usually port 993) or in cleartext: the runtime can not upgrade an already connected socket, so a STARTTLS negotiation fails with a TLS error, and it does not allow turning certificate validation off, so `tls: { rejectUnauthorized: false }` is rejected with `ERR_OPTION_NOT_IMPLEMENTED`. COMPRESS=DEFLATE, IDLE and the default pino logger work as on Node.js. STARTTLS works on Workers when the connection goes through `createSocketsTransport()` (see below).
+
+[celld](https://celld.dev/), the self-hosted runtime for Cloudflare-style Workers, has no `node:net`, `node:tls` or `node:dns`. Pass the `connect()` of `cloudflare:sockets` through the `transport` option:
+
+```js
+import { connect } from 'cloudflare:sockets';
+import { ImapFlow, createSocketsTransport } from 'imapflow';
+
+const client = new ImapFlow({
+    host: 'imap.example.com',
+    port: 993,
+    secure: true,
+    auth: { user: 'user@example.com', pass: 'secret' },
+    transport: createSocketsTransport(connect)
+});
+```
+
+Implicit TLS, STARTTLS, cleartext, IDLE, `download()` and the default logger work. Not available there:
+
+- The runtime verifies every certificate against its own root store, so `tls.rejectUnauthorized: false`, a custom `tls.ca`, client certificates and a `servername` that differs from `host` are refused with `UnsupportedTransportOption`. A TLS connection to an IP address needs a certificate issued for that address.
+- COMPRESS=DEFLATE is skipped, the runtime has no streaming zlib.
+- The `proxy` option can not be combined with a transport.
+- `client.tls` stays `false`, the runtime reports no cipher details.
+- A socket is closed when the request (or Durable Object event) that opened it ends. Run the whole session inside the handler, or inside `ctx.waitUntil()` to keep it going after the response.
+
+### Other connections
+
+The `transport` option takes any object with a `connect()` method, so other socket APIs plug in the same way. For an API built on web streams (a connection that opens with a promise of a `ReadableStream` and a `WritableStream` of bytes, as `cloudflare:sockets` and Chrome's Direct Sockets do), `createStreamsTransport()` does the wrapping:
+
+```js
+import { ImapFlow, createStreamsTransport } from 'imapflow';
+
+const transport = createStreamsTransport({
+    // `secure` says whether ImapFlow wants a TLS connection; throw to refuse what the API can not do
+    open: ({ host, port, secure }) => {
+        const socket = openSocket(host, port, secure);
+        return {
+            opened: socket.opened.then(() => ({ readable: socket.readable, writable: socket.writable })),
+            close: () => socket.close()
+        };
+    },
+    // optional: start TLS on an open connection after STARTTLS. Without it ImapFlow does not try
+    // STARTTLS, and with doSTARTTLS: true the connection fails with err.tlsFailed set
+    upgrade: (socket, options) => startTlsSomehow(socket)
+});
+```
+
+`opened` may also report `remoteAddress`, `remotePort`, `localAddress` and `localPort`, and for a TLS connection `tls: { authorized, name, version }`, which becomes `client.tls`. If `close()` fails while the streams are locked, it is called again with the locks released.
+
+An API built on events instead implements the transport itself: `connect(options, onConnect)` returns a Node.js `Duplex` stream of bytes and calls `onConnect` once the connection is up (or throws to refuse it), and an optional `upgrade(socket, options, onSecure)` starts TLS. The Duplex also needs `setTimeout(ms)`, emitting `timeout` after `ms` without traffic like `net.Socket` does: it is the watchdog behind the `socketTimeout` option.
+
+In a browser, ImapFlow runs from the ES module build when the bundler provides what Node.js has and browsers do not:
+
+- `node:stream` from [readable-stream](https://www.npmjs.com/package/readable-stream), `node:events` from [events](https://www.npmjs.com/package/events), and the `Buffer` global from [buffer](https://www.npmjs.com/package/buffer)
+- the `process` global from [process](https://www.npmjs.com/package/process), and `setImmediate()` and `clearImmediate()` globals
+- `node:crypto` with an MD5 `createHash()` (message ids on servers without OBJECTID), and `path` with `parse()` (used by a dependency for attachment file names)
+- empty modules for `node:net`, `node:tls`, `node:dns` and `node:zlib` (COMPRESS is then skipped)
+
+`test/browser/` in the repository has the complete esbuild setup, with the shims, and runs it in headless Chrome.
 
 ## Quick Example
 

package/dist/cjs/commands/authenticate.js

@@ -2,6 +2,35 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = authenticate;
 const tools_js_1 = require("../tools.js");
+const errors_js_1 = require("../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 (0, errors_js_1.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.
  *
@@ -37,6 +66,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
@@ -47,7 +78,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/cjs/commands/fetch.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = fetch;
 const tools_js_1 = require("../tools.js");
+const errors_js_1 = require("../errors.js");
 /**
  * Fetches emails from the server.
  *
@@ -38,9 +39,10 @@ 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 {
@@ -235,6 +237,11 @@ async function fetch(connection, range, query, options) {
                                 consumerError = err;
                             }
                         }
+                        else if (messages.list.length >= tools_js_1.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 = (0, errors_js_1.createImapError)(`FETCH returned more than ${tools_js_1.MAX_COLLECTED_RESPONSES} messages`, 'TooManyResponses');
+                        }
                         else {
                             messages.list.push(formatted);
                         }

package/dist/cjs/commands/idle.js

@@ -40,6 +40,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 = () => {
+        (0, tools_js_1.clearTimer)(continuationTimer);
+        continuationTimer = null;
+    };
     try {
         // State flags for the IDLE lifecycle:
         // - doneRequested: someone wants to break IDLE (e.g., to run another command)
@@ -105,6 +111,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,
@@ -121,7 +128,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 = (0, tools_js_1.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((0, errors_js_1.createImapError)('IDLE was not acknowledged within the socket timeout', 'ETIMEOUT', {
+                        command: 'IDLE',
+                        details: { socketTimeout: connection.socketTimeout }
+                    }));
+                }, connection.socketTimeout));
+            }
         });
         response.next();
         return;
@@ -153,6 +182,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/cjs/commands/list.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = list;
 const tools_js_1 = require("../tools.js");
+const errors_js_1 = require("../errors.js");
 const status_fields_js_1 = require("./status-fields.js");
 const special_use_js_1 = require("../special-use.js");
 /**
@@ -140,6 +141,8 @@ 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 = [(0, tools_js_1.encodePath)(connection, reference), (0, tools_js_1.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);
             }
@@ -199,6 +202,14 @@ async function list(connection, reference, mailbox, options) {
                         if (specialUseFlag && (!isNameSource(flagSource) || !entry.flags.has('\\NonExistent'))) {
                             addSpecialUseMatch(entry, specialUseFlag, flagSource);
                         }
+                        if (entries.length >= tools_js_1.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 || (0, errors_js_1.createImapError)(`LIST returned more than ${tools_js_1.MAX_COLLECTED_RESPONSES} mailboxes`, 'TooManyResponses');
+                            return;
+                        }
                         entries.push(entry);
                     },
                     // Inline STATUS response from LIST-STATUS extension (RFC 5819).
@@ -218,6 +229,9 @@ async function list(connection, reference, mailbox, options) {
                 }
             });
             response.next();
+            if (overflow) {
+                throw overflow;
+            }
         };
         let normalizedReference = (0, tools_js_1.normalizePath)(connection, reference || '');
         let normalizedMailbox = (0, tools_js_1.normalizePath)(connection, mailbox || '', true);

package/dist/cjs/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/cjs/errors.js

@@ -43,6 +43,8 @@ exports.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',
@@ -58,6 +60,8 @@ exports.ImapFlowErrorCode = {
     EPROXY: 'EPROXY',
     UnsupportedProxyAddress: 'UnsupportedProxyAddress',
     ERR_INVALID_URL: 'ERR_INVALID_URL',
+    // the transport option
+    UnsupportedTransportOption: 'UnsupportedTransportOption',
     // API misuse
     InstanceReused: 'InstanceReused'
 };

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

@@ -87,6 +87,9 @@ 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/cjs/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/cjs/handler/parser-instance.js

@@ -217,7 +217,9 @@ class ParserInstance {
             });
         }
         const tokenParser = new token_parser_js_1.TokenParser(this, this.pos, this.remainder, this.options);
-        return await tokenParser.getAttributes();
+        let attributes = await tokenParser.getAttributes();
+        this.truncatedAttributes = tokenParser.truncatedAttributes;
+        return attributes;
     }
 }
 exports.ParserInstance = ParserInstance;

package/dist/cjs/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/cjs/handler/token-parser.js

@@ -15,14 +15,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.
  */
 class TokenParser {
     /**
@@ -44,6 +53,7 @@ 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 = (0, limits_js_1.normalizeLimit)(this.options.maxLiteralSize, limits_js_1.MAX_LITERAL_SIZE);
+        this.truncatedAttributes = [];
         this.tree = this.currentNode = this.createNode();
         this.pos = startPos || 0;
         this.currentNode.type = 'TREE';
@@ -92,6 +102,16 @@ 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':
@@ -142,7 +162,7 @@ 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 = {
@@ -160,8 +180,20 @@ class TokenParser {
             node.depth = 0;
         }
         if (node.depth > MAX_NODE_DEPTH) {
-            // A bounded prefix only, the error travels whole into logs and rejections
-            throw (0, errors_js_1.createImapError)('Too much nesting in IMAP string', 'MAX_IMAP_NESTING_REACHED', { _imapStr: this.str.slice(0, limits_js_1.ERROR_CONTEXT_LENGTH) });
+            if (!this.isFetchResponse()) {
+                // A bounded prefix only, the error travels whole into logs and rejections
+                throw (0, errors_js_1.createImapError)('Too much nesting in IMAP string', 'MAX_IMAP_NESTING_REACHED', { _imapStr: this.str.slice(0, limits_js_1.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;
@@ -171,6 +203,44 @@ 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/cjs/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/cjs/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