imapflow 2.4.3 → 2.5.0

package/dist/cjs/streams-transport.js

@@ -0,0 +1,281 @@
+"use strict";
+// The `transport` option over a socket API built on web streams: the socket opens with a promise
+// that resolves to a ReadableStream and a WritableStream of bytes. `cloudflare:sockets` (celld,
+// Cloudflare Workers) is one, see sockets-transport.ts; Chrome's Direct Sockets and in-memory
+// connections fit the same shape. The streams are wrapped into a Duplex that behaves like the
+// net.Socket ImapFlow drives.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStreamsTransport = createStreamsTransport;
+const node_stream_1 = require("node:stream");
+const tools_js_1 = require("./tools.js");
+function closeQuietly(socket) {
+    try {
+        Promise.resolve(socket.close()).catch(tools_js_1.noop);
+    }
+    catch {
+        // already closed
+    }
+}
+class StreamsDuplex extends node_stream_1.Duplex {
+    constructor(api, socket, onConnect, plain) {
+        super({ allowHalfOpen: false });
+        // Taken once the socket is open: locking the streams of a socket returned by startTls()
+        // before its handshake completes stalls the handshake on celld
+        this._reader = null;
+        this._writer = null;
+        this._pumping = false;
+        this._readRequested = false;
+        // A runtime may only start TLS on a socket without a read in flight (with one, celld never
+        // completes the handshake), while the read loop always keeps one. So once the client
+        // announced a STARTTLS (holdAfterStarttls), reading stops after the tagged line that answers
+        // it, the only command in flight then, and resumes only when that line is not an OK.
+        this._awaitingStarttls = false;
+        this._lineTail = '';
+        // Set when the partial line got too long to be the one looked for and was dropped: the rest
+        // of it, up to the next line break, is skipped too
+        this._tailDropped = false;
+        this._readsHeld = false;
+        // Set once startTls() handed the connection to a TLS socket: the read that ends then is not
+        // the end of the connection, and closing this socket would close the TLS one
+        this._upgraded = false;
+        this._timeout = 0;
+        this._timer = null;
+        // Traffic only records the time, the one timer re-arms itself for the rest of the idle period
+        this._lastActivity = 0;
+        this._api = api;
+        this._socket = socket;
+        this._plain = plain || null;
+        socket.opened.then(info => {
+            if (this.destroyed) {
+                return;
+            }
+            try {
+                this._reader = info.readable.getReader();
+                this._writer = info.writable.getWriter();
+            }
+            catch (err) {
+                // streams already locked by someone else
+                this.destroy(err);
+                return;
+            }
+            this.remoteAddress = info.remoteAddress;
+            this.remotePort = info.remotePort;
+            this.localAddress = info.localAddress;
+            this.localPort = info.localPort;
+            const tls = info.tls;
+            if (tls) {
+                this.authorized = tls.authorized;
+                this.getCipher = () => ({ name: tls.name || '', standardName: tls.standardName || tls.name || '', version: tls.version || '' });
+            }
+            this._touch();
+            onConnect();
+            if (this._readRequested) {
+                void this._pump();
+            }
+        }, (err) => this.destroy(err));
+        socket.closed?.catch((err) => {
+            if (!this._upgraded) {
+                this.destroy(err);
+            }
+        });
+    }
+    _read() {
+        if (this._readsHeld) {
+            return;
+        }
+        if (!this._reader) {
+            this._readRequested = true;
+        }
+        else if (!this._pumping) {
+            void this._pump();
+        }
+    }
+    async _pump() {
+        const reader = this._reader;
+        this._pumping = true;
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (this._upgraded || this.destroyed) {
+                    return;
+                }
+                if (done || !value) {
+                    this.push(null);
+                    return;
+                }
+                this._touch();
+                const chunk = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+                const pushed = this.push(chunk);
+                if (this._awaitingStarttls && this._starttlsCompleted(chunk)) {
+                    this._readsHeld = true;
+                    return;
+                }
+                if (!pushed) {
+                    return;
+                }
+            }
+        }
+        catch (err) {
+            if (!this._upgraded) {
+                this.destroy(err);
+            }
+        }
+        finally {
+            this._pumping = false;
+        }
+    }
+    // Whether the chunk holds the tagged response of the STARTTLS command and it is an OK. Lines
+    // end with LF, CR is optional, as for the parser
+    _starttlsCompleted(chunk) {
+        const skipFirst = this._tailDropped;
+        const lines = (this._lineTail + chunk.toString('latin1')).split('\n');
+        const tail = lines.pop();
+        if (skipFirst && !lines.length) {
+            // still inside the dropped line
+            return false;
+        }
+        this._tailDropped = tail.length > 1024;
+        this._lineTail = this._tailDropped ? '' : tail;
+        for (let i = skipFirst ? 1 : 0; i < lines.length; i++) {
+            const tagged = /^(?![*+] )\S+ (OK|NO|BAD)\b/i.exec(lines[i]);
+            if (tagged) {
+                this._awaitingStarttls = false;
+                return tagged[1].toUpperCase() === 'OK';
+            }
+        }
+        return false;
+    }
+    /** Stops reading after the tagged response of the STARTTLS command about to be sent, if it is an OK */
+    holdAfterStarttls() {
+        this._awaitingStarttls = true;
+        this._lineTail = '';
+        this._tailDropped = false;
+    }
+    _write(chunk, _encoding, callback) {
+        if (!this._writer) {
+            // ImapFlow writes only after onConnect, this is a misuse
+            callback(new Error('Socket is not open yet'));
+            return;
+        }
+        this._touch();
+        this._writer.write(chunk).then(() => callback(), callback);
+    }
+    _destroy(err, callback) {
+        this._clearTimer();
+        if (!this._upgraded) {
+            this._close();
+        }
+        if (this._plain) {
+            // the plain connection went with the TLS one, unless the API keeps it open
+            this._plain._close();
+            this._plain.destroy();
+        }
+        callback(err);
+    }
+    // Closes the connection. An API that refuses to close while its streams are locked (Direct
+    // Sockets) gets a second attempt with the locks released; releasing them right away would
+    // fail the read in flight, which ends the request on celld
+    _close() {
+        const retry = () => {
+            for (const stream of [this._reader, this._writer]) {
+                try {
+                    stream?.releaseLock();
+                }
+                catch {
+                    // an older streams implementation refuses with a read in flight
+                }
+            }
+            closeQuietly(this._socket);
+        };
+        try {
+            const closing = this._socket.close();
+            if (typeof closing?.then === 'function') {
+                closing.then(undefined, retry);
+            }
+        }
+        catch {
+            retry();
+        }
+    }
+    /** Like net.Socket#setTimeout(): emits 'timeout' after `ms` without traffic, 0 disables */
+    setTimeout(ms) {
+        this._timeout = ms;
+        this._clearTimer();
+        this._touch();
+        return this;
+    }
+    setKeepAlive() {
+        return this;
+    }
+    /** Hands the connection over to a TLS socket, this one only stays as its transport */
+    startTls(options, onSecure) {
+        this._upgraded = true;
+        this._clearTimer();
+        // workerd refuses to start TLS while the streams are locked, nothing is in flight on them
+        this._reader?.releaseLock();
+        this._writer?.releaseLock();
+        let tlsSocket;
+        try {
+            tlsSocket = this._api.upgrade(this._socket, options);
+        }
+        catch (err) {
+            // refused before any handshake, the connection is closed with this socket
+            this._upgraded = false;
+            throw err;
+        }
+        return new StreamsDuplex(this._api, tlsSocket, onSecure, this);
+    }
+    _touch() {
+        this._lastActivity = Date.now();
+        if (!this._timer) {
+            this._arm(this._timeout);
+        }
+    }
+    _arm(ms) {
+        if (this._timeout > 0 && !this.destroyed && !this._upgraded) {
+            this._timer = (0, tools_js_1.unrefTimer)(setTimeout(() => {
+                this._timer = null;
+                const idle = Date.now() - this._lastActivity;
+                if (idle >= this._timeout) {
+                    this.emit('timeout');
+                }
+                else {
+                    this._arm(this._timeout - idle);
+                }
+            }, ms));
+        }
+    }
+    _clearTimer() {
+        (0, tools_js_1.clearTimer)(this._timer);
+        this._timer = null;
+    }
+}
+/**
+ * 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
+ */
+function createStreamsTransport(api) {
+    const transport = {
+        connect: (options, onConnect) => new StreamsDuplex(api, api.open(options), onConnect)
+    };
+    if (api.upgrade) {
+        transport.prepareUpgrade = socket => socket.holdAfterStarttls();
+        transport.upgrade = (socket, options, onSecure) => socket.startTls(options, onSecure);
+    }
+    return transport;
+}

package/dist/cjs/tools.d.ts

@@ -7,6 +7,15 @@ export { AuthenticationFailure } from './errors.js';
 export declare const EXPANDED_RANGE_LIMIT = 16777216;
 export declare const MAX_UINT32_DIGITS = 10;
 export declare const noop: () => void;
+/**
+ * Tells an IP literal from a hostname without `node:net`, which some runtimes do not implement.
+ * Only used to decide whether a host can be a TLS servername: a dotted quad, or anything with a
+ * colon (an IPv6 literal, a hostname never contains one).
+ *
+ * @param host - Hostname or IP address
+ * @returns true for an IP literal
+ */
+export declare function isIpLiteral(host: string): boolean;
 /**
  * A stream decoder returned by getDecoder(). The Japanese decoder reports the `limited`
  * flag once it has buffered all it will accept; a streaming iconv decoder never sets it.

package/dist/cjs/tools.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.noop = exports.MAX_UINT32_DIGITS = exports.EXPANDED_RANGE_LIMIT = exports.AuthenticationFailure = void 0;
+exports.isIpLiteral = isIpLiteral;
 exports.buildConnectionError = buildConnectionError;
 exports.restampConnectionError = restampConnectionError;
 exports.guardedPromise = guardedPromise;
@@ -122,6 +123,17 @@ const IMAP4REV2_FOLDED_CAPABILITIES = new Set([
 // Deliberate no-op, used as the observer a guarded promise attaches to its own rejection.
 const noop = () => { };
 exports.noop = noop;
+/**
+ * Tells an IP literal from a hostname without `node:net`, which some runtimes do not implement.
+ * Only used to decide whether a host can be a TLS servername: a dotted quad, or anything with a
+ * colon (an IPv6 literal, a hostname never contains one).
+ *
+ * @param host - Hostname or IP address
+ * @returns true for an IP literal
+ */
+function isIpLiteral(host) {
+    return /^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(':');
+}
 // The fields buildConnectionError() stamps to say *where* a connection error was rejected, as
 // opposed to what went wrong. restampConnectionError() clears them, because they belong to the
 // site that built the error rather than to the failure it describes.

package/dist/cjs/types.d.ts

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

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

@@ -54,6 +54,8 @@ export const ImapFlowErrorCode = {
     EPROXY: 'EPROXY',
     UnsupportedProxyAddress: 'UnsupportedProxyAddress',
     ERR_INVALID_URL: 'ERR_INVALID_URL',
+    // the transport option
+    UnsupportedTransportOption: 'UnsupportedTransportOption',
     // API misuse
     InstanceReused: 'InstanceReused'
 };

package/dist/esm/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/esm/imap-flow.js

@@ -3,7 +3,6 @@
  */
 import tls from 'node:tls';
 import net from 'node:net';
-import crypto from 'node:crypto';
 import zlib from 'node:zlib';
 import { EventEmitter } from 'node:events';
 import { PassThrough } from 'node:stream';
@@ -16,8 +15,10 @@ import { ConnectionDeadline } from './connection-deadline.js';
 import { downloadMessage, downloadMessageParts } from './download.js';
 import { AuthenticationFailure, createImapError } from './errors.js';
 import imapCommands from './imap-commands.js';
-import { comparePaths, updateCapabilities, getFolderTree, formatMessageResponse, mergeFetchRows, packMessageRange, normalizePath, expandRange, getColorFlags, hasCapability, isRev2Active, logConnectionError, unrefTimer, clearTimer, parseUintValue, getStringList, getTextValues, emitSafe, buildConnectionError, guardedPromise, guardedReject, MAX_UINT32_DIGITS } from './tools.js';
+import { comparePaths, updateCapabilities, getFolderTree, formatMessageResponse, mergeFetchRows, packMessageRange, normalizePath, expandRange, getColorFlags, hasCapability, isRev2Active, logConnectionError, unrefTimer, clearTimer, parseUintValue, getStringList, getTextValues, emitSafe, buildConnectionError, guardedPromise, guardedReject, isIpLiteral, MAX_UINT32_DIGITS } from './tools.js';
 export { AuthenticationFailure, ImapFlowErrorCode } from './errors.js';
+export { createSocketsTransport } from './sockets-transport.js';
+export { createStreamsTransport } from './streams-transport.js';
 const GREETING_TIMEOUT = 16 * 1000;
 // Status responses that can carry an ALERT response code
 const ALERT_RESPONSES = new Set(['OK', 'NO', 'BAD', 'BYE', 'PREAUTH']);
@@ -193,7 +194,7 @@ export class ImapFlow extends 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 : !net.isIP(this.host) ? this.host : false;
+        this.servername = this.options.servername ? this.options.servername : !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;
@@ -320,7 +321,7 @@ export class ImapFlow extends EventEmitter {
     }
     /** @internal */
     getRandomId() {
-        let rid = BigInt('0x' + crypto.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;
         }
@@ -1144,6 +1145,10 @@ export class ImapFlow extends 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() {
@@ -1329,6 +1334,12 @@ export class ImapFlow extends EventEmitter {
     }
     /** @internal */
     async compress() {
+        if (typeof zlib.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 +1460,10 @@ export class ImapFlow extends 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 +1471,7 @@ export class ImapFlow extends 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 +1498,13 @@ export class ImapFlow extends 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 +1606,7 @@ export class ImapFlow extends EventEmitter {
             this.upgrading = true;
             let tlsSocket;
             try {
-                tlsSocket = tls.connect(opts, () => {
+                let onSecure = () => {
                     try {
                         /* c8 ignore start */ // race: connection closed during the TLS handshake window
                         if (this.isClosed) {
@@ -1641,7 +1658,11 @@ export class ImapFlow extends 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)
+                    : tls.connect(opts, onSecure);
             }
             catch (err) {
                 // tls.connect() refused the upgrade before any handshake (an option the runtime
@@ -1988,6 +2009,10 @@ export class ImapFlow extends 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 +2139,10 @@ export class ImapFlow extends 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 createImapError('The proxy option can not be combined with a custom transport', 'UnsupportedTransportOption');
+        }
         let socket = false;
         if (this.options.proxy) {
             try {
@@ -2230,6 +2259,19 @@ export class ImapFlow extends 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
+                    clearTimer(this.connectTimeout);
+                    this.closeAfter();
+                    this.log.error({ err, cid: this.id });
+                    reject(err);
+                    return;
+                }
+            }
             else {
                 this.socket = connector.connect(opts, onConnect);
             }

package/dist/esm/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/esm/package-info.js

@@ -1,4 +1,4 @@
 // Generated by scripts/build.js from package.json. Do not edit by hand.
 export const name = "imapflow";
-export const version = "2.4.3";
+export const version = "2.5.0";
 export const homepage = "https://imapflow.com/";