imapflow 2.4.3 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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)
 
 

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

@@ -47,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

@@ -58,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;
         }
@@ -1185,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() {
@@ -1370,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
         }
@@ -1490,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;
         }
@@ -1501,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
@@ -1528,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();
@@ -1630,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) {
@@ -1682,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
@@ -2029,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.
@@ -2155,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 {
@@ -2271,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.3";
+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.3";
+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());
+        }
+    });
+}

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

@@ -0,0 +1,84 @@
+import type { ImapTransport, ImapTransportConnectOptions, ImapTransportOptions } from './types.js';
+/** The reader of {@link StreamsSocketInfo.readable} */
+export interface StreamsReader {
+    read(): Promise<{
+        done: boolean;
+        value?: Uint8Array | undefined;
+    }>;
+    releaseLock(): void;
+}
+/** The writer of {@link StreamsSocketInfo.writable} */
+export interface StreamsWriter {
+    write(chunk: Uint8Array): Promise<void>;
+    releaseLock(): void;
+}
+/** What a {@link StreamsSocket} resolves with once it is open */
+export interface StreamsSocketInfo {
+    /** Bytes from the server, a ReadableStream of Uint8Array */
+    readable: {
+        getReader(): StreamsReader;
+    };
+    /** Bytes to the server, a WritableStream of Uint8Array */
+    writable: {
+        getWriter(): StreamsWriter;
+    };
+    remoteAddress?: string | undefined;
+    remotePort?: number | undefined;
+    localAddress?: string | undefined;
+    localPort?: number | undefined;
+    /** Details of a TLS connection, reported as `client.tls`. Left out when the API has none */
+    tls?: StreamsTlsInfo | undefined;
+}
+/** What a socket API knows about a TLS connection */
+export interface StreamsTlsInfo {
+    /** Whether the server certificate was verified */
+    authorized: boolean;
+    /** Cipher name, e.g. `TLS_AES_256_GCM_SHA384` */
+    name?: string | undefined;
+    standardName?: string | undefined;
+    /** Protocol version, e.g. `TLSv1.3` */
+    version?: string | undefined;
+}
+/** A connection of a web streams socket API, as {@link StreamsTransportApi} opens it */
+export interface StreamsSocket {
+    /** Resolves once the connection (and the TLS handshake, if any) is established, rejects if it fails */
+    opened: Promise<StreamsSocketInfo>;
+    /** Rejects if the connection fails after it was opened */
+    closed?: Promise<unknown> | undefined;
+    /** Closes the connection */
+    close(): unknown;
+}
+/** The socket API that {@link createStreamsTransport} drives */
+export interface StreamsTransportApi<S extends StreamsSocket = StreamsSocket> {
+    /**
+     * Opens a connection, cleartext or TLS as `options.secure` says. Throws to refuse it, for
+     * example with an `UnsupportedTransportOption` error for TLS options the API can not honor.
+     */
+    open(options: ImapTransportConnectOptions): S;
+    /**
+     * Starts TLS on an open cleartext connection after STARTTLS and returns the TLS connection,
+     * the old one stays open as its transport. Throws to refuse the upgrade. Leave it out when
+     * the API can not upgrade a connection: ImapFlow then does not try STARTTLS.
+     */
+    upgrade?: ((socket: S, options: ImapTransportOptions) => S) | undefined;
+}
+/**
+ * Builds a transport for the `transport` option over a socket API built on web streams. A new
+ * API needs only `open()`, and `upgrade()` if it can start TLS on an open connection:
+ *
+ * ```js
+ * const transport = createStreamsTransport({
+ *     open: ({ host, port, secure }) => {
+ *         const socket = openSomeSocket(host, port, secure);
+ *         return { opened: socket.ready.then(() => ({ readable: socket.readable, writable: socket.writable })), close: () => socket.close() };
+ *     }
+ * });
+ * ```
+ *
+ * The transport stops reading once the server accepted a STARTTLS, so the API never has to start
+ * TLS with a read in flight, and releases the stream locks before `upgrade()` is called.
+ *
+ * @param api - Opens (and upgrades) connections
+ * @returns A transport for the `transport` option
+ */
+export declare function createStreamsTransport<S extends StreamsSocket>(api: StreamsTransportApi<S>): ImapTransport;