imapflow 2.4.2 → 2.5.0

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;

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

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

@@ -22,6 +22,7 @@ export const ImapFlowErrorCode = {
     // the server
     ETHROTTLE: 'ETHROTTLE',
     UnexpectedTag: 'UnexpectedTag',
+    MissingTag: 'MissingTag',
     InvalidResponse: 'InvalidResponse',
     ResponseProcessingFailed: 'ResponseProcessingFailed',
     STARTTLS_INJECTION: 'STARTTLS_INJECTION',
@@ -53,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