imapflow 2.4.2 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [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)
+
+
+### Bug Fixes
+
+* fail the command on a NO or BAD status line without a tag ([5a38e17](https://github.com/postalsys/imapflow/commit/5a38e171ad8405583b090872076f464c4dc6f0e2))
+* send ID after STARTTLS instead of before it ([7d6f37a](https://github.com/postalsys/imapflow/commit/7d6f37a4e8eb2f9b0f921f6b004a1ba5e45b1867))
+* send ID after STARTTLS instead of before it ([197ecdc](https://github.com/postalsys/imapflow/commit/197ecdc49f2f64c45ee98c4e4284534662e26942))
+
 ## [2.4.2](https://github.com/postalsys/imapflow/compare/v2.4.1...v2.4.2) (2026-10-14)
 
 

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/errors.d.ts

@@ -20,6 +20,7 @@ export declare const ImapFlowErrorCode: {
     readonly LockTimeout: "LockTimeout";
     readonly ETHROTTLE: "ETHROTTLE";
     readonly UnexpectedTag: "UnexpectedTag";
+    readonly MissingTag: "MissingTag";
     readonly InvalidResponse: "InvalidResponse";
     readonly ResponseProcessingFailed: "ResponseProcessingFailed";
     readonly STARTTLS_INJECTION: "STARTTLS_INJECTION";
@@ -46,6 +47,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

@@ -26,6 +26,7 @@ exports.ImapFlowErrorCode = {
     // the server
     ETHROTTLE: 'ETHROTTLE',
     UnexpectedTag: 'UnexpectedTag',
+    MissingTag: 'MissingTag',
     InvalidResponse: 'InvalidResponse',
     ResponseProcessingFailed: 'ResponseProcessingFailed',
     STARTTLS_INJECTION: 'STARTTLS_INJECTION',
@@ -57,6 +58,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/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

package/dist/cjs/imap-flow.js

@@ -39,10 +39,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ImapFlow = exports.ImapFlowErrorCode = exports.AuthenticationFailure = void 0;
+exports.ImapFlow = exports.createStreamsTransport = exports.createSocketsTransport = exports.ImapFlowErrorCode = exports.AuthenticationFailure = void 0;
 const node_tls_1 = __importDefault(require("node:tls"));
 const node_net_1 = __importDefault(require("node:net"));
-const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_zlib_1 = __importDefault(require("node:zlib"));
 const node_events_1 = require("node:events");
 const node_stream_1 = require("node:stream");
@@ -59,6 +58,10 @@ const tools_js_1 = require("./tools.js");
 var errors_js_2 = require("./errors.js");
 Object.defineProperty(exports, "AuthenticationFailure", { enumerable: true, get: function () { return errors_js_2.AuthenticationFailure; } });
 Object.defineProperty(exports, "ImapFlowErrorCode", { enumerable: true, get: function () { return errors_js_2.ImapFlowErrorCode; } });
+var sockets_transport_js_1 = require("./sockets-transport.js");
+Object.defineProperty(exports, "createSocketsTransport", { enumerable: true, get: function () { return sockets_transport_js_1.createSocketsTransport; } });
+var streams_transport_js_1 = require("./streams-transport.js");
+Object.defineProperty(exports, "createStreamsTransport", { enumerable: true, get: function () { return streams_transport_js_1.createStreamsTransport; } });
 const GREETING_TIMEOUT = 16 * 1000;
 // Status responses that can carry an ALERT response code
 const ALERT_RESPONSES = new Set(['OK', 'NO', 'BAD', 'BYE', 'PREAUTH']);
@@ -234,7 +237,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // which is POP3 - a client created without an explicit port could never connect.
         this.port = Number(this.options.port) || (this.secureConnection ? 993 : 143);
         this.host = this.options.host || 'localhost';
-        this.servername = this.options.servername ? this.options.servername : !node_net_1.default.isIP(this.host) ? this.host : false;
+        this.servername = this.options.servername ? this.options.servername : !(0, tools_js_1.isIpLiteral)(this.host) ? this.host : false;
         if (typeof this.options.secure === 'undefined' && this.port === 993) {
             // if secure option is not set but port is 993, then default to secure
             this.secureConnection = true;
@@ -361,7 +364,7 @@ class ImapFlow extends node_events_1.EventEmitter {
     }
     /** @internal */
     getRandomId() {
-        let rid = BigInt('0x' + node_crypto_1.default.randomBytes(13).toString('hex')).toString(36);
+        let rid = BigInt('0x' + Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(13))).toString('hex')).toString(36);
         if (rid.length < 20) {
             rid = '0'.repeat(20 - rid.length) + rid;
         }
@@ -781,7 +784,7 @@ class ImapFlow extends node_events_1.EventEmitter {
      */
     rejectUnparsedCompletion(payload, parserError) {
         if (!this.currentRequest || !this.currentRequest.sent) {
-            return;
+            return false;
         }
         // Prefer the tag the parser had already extracted before it failed - it went
         // through the same leading-NUL workaround as every parsed response. Fall back
@@ -793,11 +796,45 @@ class ImapFlow extends node_events_1.EventEmitter {
             tag = match && match[1];
         }
         if (!tag || tag !== this.currentRequest.tag) {
-            return;
+            return false;
         }
         let err = new Error('Failed to parse the server response for this command');
         err.code = parserError.code || 'ParserError';
         err.parserError = parserError;
+        this.failInFlight(err);
+        return true;
+    }
+    /**
+     * Fails the in-flight command when the server answered it with a NO or BAD status line that
+     * has no tag at all (Namecheap Private Email: `BAD "Must issue a STARTTLS command first"`).
+     * Only one command is ever on the wire, and leaving it pending would stall the connection
+     * until the socket timeout. Tags are uppercase hex, so a command can carry the tag BAD:
+     * callers check for the command's own tag first.
+     *
+     * @param payload - Raw bytes of the line.
+     * @returns `true` when the line failed the in-flight command
+     * @internal
+     */
+    rejectTaglessCompletion(payload) {
+        if (!this.currentRequest || !this.currentRequest.sent) {
+            return false;
+        }
+        let match = payload.toString('latin1', 0, 1024).match(/^\0*(BAD|NO)(?:\s+([^]*))?$/i);
+        if (!match) {
+            return false;
+        }
+        let err = (0, errors_js_1.createImapError)('Command failed', 'MissingTag', {
+            command: this.currentRequest.command,
+            responseStatus: match[1].toUpperCase(),
+            responseText: (match[2] || '').trim().replace(/^"(.*)"$/, '$1')
+        });
+        this.log.warn({ msg: 'Server sent a status response without a tag', err, cid: this.id });
+        this.failInFlight(err);
+        return true;
+    }
+    // Rejects the in-flight command and moves on to the next queued one
+    /** @internal */
+    failInFlight(err) {
         this.rejectCurrentRequest(err);
         this.trySend().catch(sendErr => (0, tools_js_1.logConnectionError)(this, 'Failed to dispatch command', sendErr));
     }
@@ -847,7 +884,9 @@ class ImapFlow extends node_events_1.EventEmitter {
             // timeout fires. The tag is recovered from the raw bytes (a tag is
             // ASTRING-CHAR only, so it survives whatever made the rest unparseable) and
             // the command is failed with the parser error instead of hanging.
-            this.rejectUnparsedCompletion(data.payload, err);
+            if (!this.rejectUnparsedCompletion(data.payload, err)) {
+                this.rejectTaglessCompletion(data.payload);
+            }
             return true;
         }
         if (parsed.tag && !['*', '+'].includes(parsed.tag) && parsed.command) {
@@ -952,7 +991,8 @@ class ImapFlow extends node_events_1.EventEmitter {
         // actually written to the socket (invariant 2), so the three cases below are kept apart:
         // the active command completes, a command that has not been written yet is proof of
         // desynchronization (queued behind another command, or current but not yet on the wire),
-        // and an entirely unknown tag is recorded but tolerated.
+        // and an entirely unknown tag is recorded but tolerated, unless the line is a NO or BAD
+        // that came without a tag (see rejectTaglessCompletion()).
         if (parsed.tag && !['*', '+'].includes(parsed.tag)) {
             if (this.currentRequest && this.currentRequest.tag === parsed.tag && this.currentRequest.sent) {
                 let request = this.takeCurrentRequest();
@@ -990,7 +1030,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                 this.failProtocol(err);
                 return false;
             }
-            else {
+            else if (!this.rejectTaglessCompletion(data.payload)) {
                 this.countUnknownTag(parsed.tag);
             }
         }
@@ -1148,6 +1188,10 @@ class ImapFlow extends node_events_1.EventEmitter {
         if (typeof socket.setTimeout === 'function') {
             socket.setTimeout(this.socketTimeout);
         }
+        else {
+            // a transport socket from plain JavaScript can lack it, which disables the watchdog
+            this.log.warn({ msg: 'The socket has no setTimeout(), socketTimeout is not enforced', cid: this.id });
+        }
     }
     /** @internal */
     setSocketHandlers() {
@@ -1266,10 +1310,14 @@ class ImapFlow extends node_events_1.EventEmitter {
     /** @internal */
     async startSession() {
         await this.run('CAPABILITY');
+        await this.upgradeToSTARTTLS();
+        // ID goes after STARTTLS: the client info should not travel in cleartext, and some
+        // servers refuse every command but STARTTLS before the upgrade with an untagged BAD
+        // the client can not tie to ID, which then waits for the socket timeout (Namecheap
+        // Private Email). The capability list was refreshed by the upgrade.
         if (this.capabilities.has('ID')) {
             this.idRequested = await this.run('ID', this.clientInfo);
         }
-        await this.upgradeToSTARTTLS();
         await this.authenticate();
         if ((!this.idRequested || Object.keys(this.idRequested).length < 2) && this.capabilities.has('ID')) {
             // re-request ID after LOGIN
@@ -1329,6 +1377,12 @@ class ImapFlow extends node_events_1.EventEmitter {
     }
     /** @internal */
     async compress() {
+        if (typeof node_zlib_1.default.createDeflateRaw !== 'function') {
+            // The runtime has no streaming DEFLATE (celld implements only the synchronous zlib
+            // functions), so the session stays uncompressed rather than failing after COMPRESS
+            this.log.debug({ msg: 'Streaming DEFLATE is not available, skipping COMPRESS', cid: this.id });
+            return;
+        }
         if (!(await this.run('COMPRESS'))) {
             return; // was not able to negotiate compression
         }
@@ -1449,10 +1503,10 @@ class ImapFlow extends node_events_1.EventEmitter {
         });
     }
     /** @internal */
-    _failSTARTTLS() {
+    _failSTARTTLS(reason = 'Server does not support STARTTLS') {
         if (this.options.doSTARTTLS === true) {
             // STARTTLS configured as requirement
-            let err = new Error('Server does not support STARTTLS');
+            let err = new Error(reason);
             err.tlsFailed = true;
             throw err;
         }
@@ -1460,7 +1514,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // may be a downgrade attack: say so rather than fall back silently (see the doSTARTTLS
         // option for the policy).
         this.log.warn({
-            msg: 'Server does not support STARTTLS, continuing over an unencrypted connection',
+            msg: reason + ', continuing over an unencrypted connection',
             host: this.host,
             port: this.port,
             cid: this.id
@@ -1487,7 +1541,13 @@ class ImapFlow extends node_events_1.EventEmitter {
         if (!this.capabilities.has('STARTTLS')) {
             return this._failSTARTTLS();
         }
+        if (this.options.transport && !this.options.transport.upgrade) {
+            return this._failSTARTTLS('The transport can not start TLS');
+        }
         this.expectCapabilityUpdate = true;
+        if (this.options.transport?.prepareUpgrade && this.socket) {
+            this.options.transport.prepareUpgrade(this.socket);
+        }
         let canUpgrade = await this.run('STARTTLS');
         if (!canUpgrade) {
             return this._failSTARTTLS();
@@ -1589,7 +1649,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             this.upgrading = true;
             let tlsSocket;
             try {
-                tlsSocket = node_tls_1.default.connect(opts, () => {
+                let onSecure = () => {
                     try {
                         /* c8 ignore start */ // race: connection closed during the TLS handshake window
                         if (this.isClosed) {
@@ -1641,7 +1701,11 @@ class ImapFlow extends node_events_1.EventEmitter {
                     catch (ex) {
                         this.emitError(ex);
                     }
-                });
+                };
+                // a transport without upgrade() never gets here, see the STARTTLS check above
+                tlsSocket = this.options.transport
+                    ? this.options.transport.upgrade(socketPlain, this.transportOptions(), onSecure)
+                    : node_tls_1.default.connect(opts, onSecure);
             }
             catch (err) {
                 // tls.connect() refused the upgrade before any handshake (an option the runtime
@@ -1988,6 +2052,10 @@ class ImapFlow extends node_events_1.EventEmitter {
     tlsServername() {
         return this.servername ? { servername: this.servername } : {};
     }
+    /** @internal */
+    transportOptions() {
+        return Object.assign({ host: this.host, port: this.port, tls: this.options.tls }, this.tlsServername());
+    }
     // Normalizes a message range from various input formats into an IMAP-compatible
     // sequence string (e.g., "1:5,7,10:*"). Handles: numbers, "*", {all:true},
     // {uid:value}, search query objects (resolved via SEARCH), and arrays of numbers.
@@ -2114,6 +2182,10 @@ class ImapFlow extends node_events_1.EventEmitter {
         // these methods take an optional second argument, so make sure that some random IMAP tag is not used as the second argument
         this.untaggedHandlers.FETCH = untagged => this.untaggedFetch(untagged);
         this.untaggedHandlers.VANISHED = untagged => this.untaggedVanished(untagged);
+        let transport = this.options.transport;
+        if (transport && this.options.proxy) {
+            throw (0, errors_js_1.createImapError)('The proxy option can not be combined with a custom transport', 'UnsupportedTransportOption');
+        }
         let socket = false;
         if (this.options.proxy) {
             try {
@@ -2230,6 +2302,19 @@ class ImapFlow extends node_events_1.EventEmitter {
                     setImmediate(onConnect);
                 }
             }
+            else if (transport) {
+                try {
+                    this.socket = transport.connect({ ...this.transportOptions(), secure: this.secureConnection }, onConnect);
+                }
+                catch (err) {
+                    // refused up front: the connection deadline must not stay armed
+                    (0, tools_js_1.clearTimer)(this.connectTimeout);
+                    this.closeAfter();
+                    this.log.error({ err, cid: this.id });
+                    reject(err);
+                    return;
+                }
+            }
             else {
                 this.socket = connector.connect(opts, onConnect);
             }

package/dist/cjs/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.4.2";
+export declare const version = "2.5.0";
 export declare const homepage = "https://imapflow.com/";

package/dist/cjs/package-info.js

@@ -3,5 +3,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.homepage = exports.version = exports.name = void 0;
 exports.name = "imapflow";
-exports.version = "2.4.2";
+exports.version = "2.5.0";
 exports.homepage = "https://imapflow.com/";

package/dist/cjs/sockets-transport.d.ts

@@ -0,0 +1,44 @@
+import { type StreamsReader, type StreamsWriter } from './streams-transport.js';
+import type { ImapTransport } from './types.js';
+/** The part of a `cloudflare:sockets` Socket the transport uses */
+export interface SocketsApiSocket {
+    readable: {
+        getReader(): StreamsReader;
+    };
+    writable: {
+        getWriter(): StreamsWriter;
+    };
+    opened: Promise<{
+        remoteAddress?: string | undefined;
+        localAddress?: string | undefined;
+    } | undefined>;
+    closed: Promise<void>;
+    close(): Promise<void>;
+    startTls(): SocketsApiSocket;
+}
+/** The `connect()` function of the `cloudflare:sockets` API */
+export type SocketsConnect = (address: {
+    hostname: string;
+    port: number;
+}, options?: {
+    secureTransport?: 'off' | 'on' | 'starttls' | undefined;
+    allowHalfOpen?: boolean | undefined;
+} | undefined) => SocketsApiSocket;
+/**
+ * Builds a transport for the `transport` option from the `connect()` of the `cloudflare:sockets`
+ * API, for celld and other runtimes without `node:net` and `node:tls`:
+ *
+ * ```js
+ * import { connect } from 'cloudflare:sockets';
+ * const client = new ImapFlow({ host, port: 993, secure: true, auth, transport: createSocketsTransport(connect) });
+ * ```
+ *
+ * The runtime verifies the server certificate against its own root store, so the transport
+ * refuses `tls.rejectUnauthorized: false`, a custom `tls.ca`, client certificates and a
+ * `servername` that differs from `host`. The socket carries no cipher details, so `client.tls`
+ * stays `false` on a secure connection.
+ *
+ * @param connect - The `connect` export of `cloudflare:sockets`
+ * @returns A transport for the `transport` option
+ */
+export declare function createSocketsTransport(connect: SocketsConnect): ImapTransport;

package/dist/cjs/sockets-transport.js

@@ -0,0 +1,89 @@
+"use strict";
+// The `transport` option over the `connect()` of the `cloudflare:sockets` API, for runtimes that
+// have it but no usable `node:net` or `node:tls` (celld, Cloudflare Workers). A thin adapter of
+// the API to createStreamsTransport().
+//
+// The runtime verifies every TLS certificate against its own root store and takes the SNI name
+// from the hostname it connects to, so TLS options that would change either are refused rather
+// than silently ignored.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSocketsTransport = createSocketsTransport;
+const errors_js_1 = require("./errors.js");
+const streams_transport_js_1 = require("./streams-transport.js");
+// TLS options the runtime can not honor: it always verifies the certificate against its own
+// roots, and has no client certificates
+const UNSUPPORTED_TLS_OPTIONS = ['ca', 'cert', 'key', 'pfx', 'passphrase', 'checkServerIdentity'];
+function refuse(option) {
+    throw (0, errors_js_1.createImapError)(`The ${option} option is not supported by this transport`, 'UnsupportedTransportOption');
+}
+function assertOptions(options) {
+    const tlsOptions = options.tls || {};
+    if (tlsOptions.rejectUnauthorized === false) {
+        refuse('tls.rejectUnauthorized=false');
+    }
+    if (options.servername && options.servername !== options.host) {
+        refuse('servername');
+    }
+    const unsupported = UNSUPPORTED_TLS_OPTIONS.find(key => tlsOptions[key] !== undefined);
+    if (unsupported) {
+        refuse('tls.' + unsupported);
+    }
+}
+// "1.2.3.4:993" or "[::1]:993"
+function splitAddress(address) {
+    const match = typeof address === 'string' && address.match(/^\[?(.*?)\]?:(\d+)$/);
+    return match ? { address: match[1], port: Number(match[2]) } : {};
+}
+function wrap(raw) {
+    return {
+        raw,
+        opened: raw.opened.then(info => {
+            const remote = splitAddress(info?.remoteAddress);
+            const local = splitAddress(info?.localAddress);
+            return {
+                readable: raw.readable,
+                writable: raw.writable,
+                remoteAddress: remote.address,
+                remotePort: remote.port,
+                localAddress: local.address,
+                localPort: local.port
+            };
+        }),
+        closed: raw.closed,
+        close: () => raw.close()
+    };
+}
+/**
+ * Builds a transport for the `transport` option from the `connect()` of the `cloudflare:sockets`
+ * API, for celld and other runtimes without `node:net` and `node:tls`:
+ *
+ * ```js
+ * import { connect } from 'cloudflare:sockets';
+ * const client = new ImapFlow({ host, port: 993, secure: true, auth, transport: createSocketsTransport(connect) });
+ * ```
+ *
+ * The runtime verifies the server certificate against its own root store, so the transport
+ * refuses `tls.rejectUnauthorized: false`, a custom `tls.ca`, client certificates and a
+ * `servername` that differs from `host`. The socket carries no cipher details, so `client.tls`
+ * stays `false` on a secure connection.
+ *
+ * @param connect - The `connect` export of `cloudflare:sockets`
+ * @returns A transport for the `transport` option
+ */
+function createSocketsTransport(connect) {
+    return (0, streams_transport_js_1.createStreamsTransport)({
+        open(options) {
+            // TLS options matter only for a TLS connection, a cleartext one gets them checked if
+            // it is upgraded
+            if (options.secure) {
+                assertOptions(options);
+            }
+            // Cleartext sockets are opened in starttls mode, which costs nothing until an upgrade
+            return wrap(connect({ hostname: options.host, port: options.port }, { secureTransport: options.secure ? 'on' : 'starttls' }));
+        },
+        upgrade(socket, options) {
+            assertOptions(options);
+            return wrap(socket.raw.startTls());
+        }
+    });
+}