imapflow 2.4.3 → 2.5.1

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, iterateRange, countRange, 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;
         }
@@ -845,6 +846,16 @@ export class ImapFlow extends EventEmitter {
             }
             return true;
         }
+        if (parsed.truncatedAttributes) {
+            // The row is kept with the item missing rather than dropped with the whole line: the
+            // nesting is the message sender's doing, and the message must still reach the caller
+            this.log.warn({
+                msg: 'FETCH data item exceeded the nesting limit and was dropped',
+                seq: parsed.command,
+                attributes: parsed.truncatedAttributes,
+                cid: this.id
+            });
+        }
         if (parsed.tag && !['*', '+'].includes(parsed.tag) && parsed.command) {
             let payload = { response: parsed.command };
             if (parsed.attributes &&
@@ -1008,11 +1019,24 @@ export class ImapFlow extends EventEmitter {
     async settleRequest(request, parsed, hasTrailingData) {
         switch ((parsed.command || '').toUpperCase()) {
             case 'OK':
-            case 'BYE':
                 // hasTrailingData is forwarded so STARTTLS can detect a plaintext
                 // injection (data buffered after the tagged OK, before the handshake).
                 await this.resolveParked(request, parsed, hasTrailingData);
                 break;
+            case 'BYE': {
+                // BYE is always untagged (RFC 9051 section 7.1.5), it is never the completion
+                // result of a command. It used to resolve the command like an OK, so a server (or
+                // a cleartext MITM) answering LOGIN with a tagged BYE marked the session
+                // authenticated. The server says it is closing: the command fails as a lost
+                // connection and the connection is closed, which for a LOGOUT is the outcome it
+                // was after anyway.
+                await this.serverBye(parsed);
+                let err = this.createNoConnectionError(this.byeReason, { rejectedFrom: 'taggedBye', command: request.command });
+                err.response = parsed;
+                err.responseStatus = 'BYE';
+                request.reject(err);
+                break;
+            }
             case 'NO':
             case 'BAD': {
                 let txt = getTextValues(parsed.attributes)
@@ -1144,6 +1168,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 +1357,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 +1483,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 +1494,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
@@ -1484,10 +1518,23 @@ export class ImapFlow extends EventEmitter {
             // STARTTLS explictly disabled by config
             return false;
         }
+        if (this.state !== this.states.NOT_AUTHENTICATED) {
+            // STARTTLS is only valid in the not-authenticated state (RFC 9051 section 6.2.1),
+            // which a PREAUTH greeting skips, so there is no way left to protect this session.
+            // Required STARTTLS fails here with that reason: the greeting arrived in cleartext,
+            // and a MITM can answer with PREAUTH precisely to keep it that way.
+            return this._failSTARTTLS('STARTTLS is not possible after a PREAUTH greeting');
+        }
         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 +1636,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 +1688,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
@@ -1918,7 +1969,7 @@ export class ImapFlow extends EventEmitter {
         let tags = [];
         let uids = false;
         // A malformed VANISHED can carry no attributes at all, and one carrying only the
-        // (EARLIER) tag leaves `uids` false - expandRange() handles that and yields nothing
+        // (EARLIER) tag leaves `uids` false - iterateRange() handles that and yields nothing
         if (!untagged.attributes || !untagged.attributes.length) {
             return;
         }
@@ -1929,14 +1980,16 @@ export class ImapFlow extends EventEmitter {
         if (untagged.attributes[0] && typeof untagged.attributes[0].value === 'string') {
             uids = untagged.attributes[0].value;
         }
-        let uidList = expandRange(uids);
         let earlier = tags.includes('EARLIER');
         // RFC 7162 section 3.2.10: unlike VANISHED (EARLIER), a plain VANISHED reports messages the
         // client knows about and decrements the message count like the same number of EXPUNGEs would
         if (!earlier) {
-            mailbox.exists = Math.max(0, mailbox.exists - uidList.length);
+            mailbox.exists = Math.max(0, mailbox.exists - countRange(uids));
         }
-        for (let uid of uidList) {
+        // The set is walked one UID at a time rather than expanded first: it is the server's to
+        // choose, and a single "1:16777216" is a few bytes on the wire but sixteen million array
+        // entries expanded, for every such line the server cares to send
+        for (let uid of iterateRange(uids)) {
             let payload = {
                 path: mailbox.path,
                 uid,
@@ -1988,6 +2041,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 +2171,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 +2291,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.1";
 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.1";
 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;