imapflow 2.4.2 → 2.5.0

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;
         }
@@ -740,7 +741,7 @@ export class ImapFlow extends 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
@@ -752,11 +753,45 @@ export class ImapFlow extends 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 = 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 => logConnectionError(this, 'Failed to dispatch command', sendErr));
     }
@@ -806,7 +841,9 @@ export class ImapFlow extends 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) {
@@ -911,7 +948,8 @@ export class ImapFlow extends 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();
@@ -949,7 +987,7 @@ export class ImapFlow extends EventEmitter {
                 this.failProtocol(err);
                 return false;
             }
-            else {
+            else if (!this.rejectTaglessCompletion(data.payload)) {
                 this.countUnknownTag(parsed.tag);
             }
         }
@@ -1107,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() {
@@ -1225,10 +1267,14 @@ export class ImapFlow extends 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
@@ -1288,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
         }
@@ -1408,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;
         }
@@ -1419,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
@@ -1446,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();
@@ -1548,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) {
@@ -1600,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
@@ -1947,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.
@@ -2073,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 {
@@ -2189,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.2";
+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.2";
+export const version = "2.5.0";
 export const homepage = "https://imapflow.com/";

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

@@ -0,0 +1,86 @@
+// 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.
+import { createImapError } from './errors.js';
+import { createStreamsTransport } from './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 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
+ */
+export function createSocketsTransport(connect) {
+    return 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/esm/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;