imapflow 2.4.3 → 2.5.1

package/dist/cjs/imap-flow.js

@@ -39,10 +39,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ImapFlow = exports.ImapFlowErrorCode = exports.AuthenticationFailure = void 0;
+exports.ImapFlow = exports.createStreamsTransport = exports.createSocketsTransport = exports.ImapFlowErrorCode = exports.AuthenticationFailure = void 0;
 const node_tls_1 = __importDefault(require("node:tls"));
 const node_net_1 = __importDefault(require("node:net"));
-const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_zlib_1 = __importDefault(require("node:zlib"));
 const node_events_1 = require("node:events");
 const node_stream_1 = require("node:stream");
@@ -59,6 +58,10 @@ const tools_js_1 = require("./tools.js");
 var errors_js_2 = require("./errors.js");
 Object.defineProperty(exports, "AuthenticationFailure", { enumerable: true, get: function () { return errors_js_2.AuthenticationFailure; } });
 Object.defineProperty(exports, "ImapFlowErrorCode", { enumerable: true, get: function () { return errors_js_2.ImapFlowErrorCode; } });
+var sockets_transport_js_1 = require("./sockets-transport.js");
+Object.defineProperty(exports, "createSocketsTransport", { enumerable: true, get: function () { return sockets_transport_js_1.createSocketsTransport; } });
+var streams_transport_js_1 = require("./streams-transport.js");
+Object.defineProperty(exports, "createStreamsTransport", { enumerable: true, get: function () { return streams_transport_js_1.createStreamsTransport; } });
 const GREETING_TIMEOUT = 16 * 1000;
 // Status responses that can carry an ALERT response code
 const ALERT_RESPONSES = new Set(['OK', 'NO', 'BAD', 'BYE', 'PREAUTH']);
@@ -234,7 +237,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // which is POP3 - a client created without an explicit port could never connect.
         this.port = Number(this.options.port) || (this.secureConnection ? 993 : 143);
         this.host = this.options.host || 'localhost';
-        this.servername = this.options.servername ? this.options.servername : !node_net_1.default.isIP(this.host) ? this.host : false;
+        this.servername = this.options.servername ? this.options.servername : !(0, tools_js_1.isIpLiteral)(this.host) ? this.host : false;
         if (typeof this.options.secure === 'undefined' && this.port === 993) {
             // if secure option is not set but port is 993, then default to secure
             this.secureConnection = true;
@@ -361,7 +364,7 @@ class ImapFlow extends node_events_1.EventEmitter {
     }
     /** @internal */
     getRandomId() {
-        let rid = BigInt('0x' + node_crypto_1.default.randomBytes(13).toString('hex')).toString(36);
+        let rid = BigInt('0x' + Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(13))).toString('hex')).toString(36);
         if (rid.length < 20) {
             rid = '0'.repeat(20 - rid.length) + rid;
         }
@@ -886,6 +889,16 @@ class ImapFlow extends node_events_1.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 &&
@@ -1049,11 +1062,24 @@ class ImapFlow extends node_events_1.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 = (0, tools_js_1.getTextValues)(parsed.attributes)
@@ -1185,6 +1211,10 @@ class ImapFlow extends node_events_1.EventEmitter {
         if (typeof socket.setTimeout === 'function') {
             socket.setTimeout(this.socketTimeout);
         }
+        else {
+            // a transport socket from plain JavaScript can lack it, which disables the watchdog
+            this.log.warn({ msg: 'The socket has no setTimeout(), socketTimeout is not enforced', cid: this.id });
+        }
     }
     /** @internal */
     setSocketHandlers() {
@@ -1370,6 +1400,12 @@ class ImapFlow extends node_events_1.EventEmitter {
     }
     /** @internal */
     async compress() {
+        if (typeof node_zlib_1.default.createDeflateRaw !== 'function') {
+            // The runtime has no streaming DEFLATE (celld implements only the synchronous zlib
+            // functions), so the session stays uncompressed rather than failing after COMPRESS
+            this.log.debug({ msg: 'Streaming DEFLATE is not available, skipping COMPRESS', cid: this.id });
+            return;
+        }
         if (!(await this.run('COMPRESS'))) {
             return; // was not able to negotiate compression
         }
@@ -1490,10 +1526,10 @@ class ImapFlow extends node_events_1.EventEmitter {
         });
     }
     /** @internal */
-    _failSTARTTLS() {
+    _failSTARTTLS(reason = 'Server does not support STARTTLS') {
         if (this.options.doSTARTTLS === true) {
             // STARTTLS configured as requirement
-            let err = new Error('Server does not support STARTTLS');
+            let err = new Error(reason);
             err.tlsFailed = true;
             throw err;
         }
@@ -1501,7 +1537,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // may be a downgrade attack: say so rather than fall back silently (see the doSTARTTLS
         // option for the policy).
         this.log.warn({
-            msg: 'Server does not support STARTTLS, continuing over an unencrypted connection',
+            msg: reason + ', continuing over an unencrypted connection',
             host: this.host,
             port: this.port,
             cid: this.id
@@ -1525,10 +1561,23 @@ class ImapFlow extends node_events_1.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();
@@ -1630,7 +1679,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             this.upgrading = true;
             let tlsSocket;
             try {
-                tlsSocket = node_tls_1.default.connect(opts, () => {
+                let onSecure = () => {
                     try {
                         /* c8 ignore start */ // race: connection closed during the TLS handshake window
                         if (this.isClosed) {
@@ -1682,7 +1731,11 @@ class ImapFlow extends node_events_1.EventEmitter {
                     catch (ex) {
                         this.emitError(ex);
                     }
-                });
+                };
+                // a transport without upgrade() never gets here, see the STARTTLS check above
+                tlsSocket = this.options.transport
+                    ? this.options.transport.upgrade(socketPlain, this.transportOptions(), onSecure)
+                    : node_tls_1.default.connect(opts, onSecure);
             }
             catch (err) {
                 // tls.connect() refused the upgrade before any handshake (an option the runtime
@@ -1959,7 +2012,7 @@ class ImapFlow extends node_events_1.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;
         }
@@ -1970,14 +2023,16 @@ class ImapFlow extends node_events_1.EventEmitter {
         if (untagged.attributes[0] && typeof untagged.attributes[0].value === 'string') {
             uids = untagged.attributes[0].value;
         }
-        let uidList = (0, tools_js_1.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 - (0, tools_js_1.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 (0, tools_js_1.iterateRange)(uids)) {
             let payload = {
                 path: mailbox.path,
                 uid,
@@ -2029,6 +2084,10 @@ class ImapFlow extends node_events_1.EventEmitter {
     tlsServername() {
         return this.servername ? { servername: this.servername } : {};
     }
+    /** @internal */
+    transportOptions() {
+        return Object.assign({ host: this.host, port: this.port, tls: this.options.tls }, this.tlsServername());
+    }
     // Normalizes a message range from various input formats into an IMAP-compatible
     // sequence string (e.g., "1:5,7,10:*"). Handles: numbers, "*", {all:true},
     // {uid:value}, search query objects (resolved via SEARCH), and arrays of numbers.
@@ -2155,6 +2214,10 @@ class ImapFlow extends node_events_1.EventEmitter {
         // these methods take an optional second argument, so make sure that some random IMAP tag is not used as the second argument
         this.untaggedHandlers.FETCH = untagged => this.untaggedFetch(untagged);
         this.untaggedHandlers.VANISHED = untagged => this.untaggedVanished(untagged);
+        let transport = this.options.transport;
+        if (transport && this.options.proxy) {
+            throw (0, errors_js_1.createImapError)('The proxy option can not be combined with a custom transport', 'UnsupportedTransportOption');
+        }
         let socket = false;
         if (this.options.proxy) {
             try {
@@ -2271,6 +2334,19 @@ class ImapFlow extends node_events_1.EventEmitter {
                     setImmediate(onConnect);
                 }
             }
+            else if (transport) {
+                try {
+                    this.socket = transport.connect({ ...this.transportOptions(), secure: this.secureConnection }, onConnect);
+                }
+                catch (err) {
+                    // refused up front: the connection deadline must not stay armed
+                    (0, tools_js_1.clearTimer)(this.connectTimeout);
+                    this.closeAfter();
+                    this.log.error({ err, cid: this.id });
+                    reject(err);
+                    return;
+                }
+            }
             else {
                 this.socket = connector.connect(opts, onConnect);
             }

package/dist/cjs/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.4.3";
+export declare const version = "2.5.1";
 export declare const homepage = "https://imapflow.com/";

package/dist/cjs/package-info.js

@@ -3,5 +3,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.homepage = exports.version = exports.name = void 0;
 exports.name = "imapflow";
-exports.version = "2.4.3";
+exports.version = "2.5.1";
 exports.homepage = "https://imapflow.com/";

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

@@ -0,0 +1,44 @@
+import { type StreamsReader, type StreamsWriter } from './streams-transport.js';
+import type { ImapTransport } from './types.js';
+/** The part of a `cloudflare:sockets` Socket the transport uses */
+export interface SocketsApiSocket {
+    readable: {
+        getReader(): StreamsReader;
+    };
+    writable: {
+        getWriter(): StreamsWriter;
+    };
+    opened: Promise<{
+        remoteAddress?: string | undefined;
+        localAddress?: string | undefined;
+    } | undefined>;
+    closed: Promise<void>;
+    close(): Promise<void>;
+    startTls(): SocketsApiSocket;
+}
+/** The `connect()` function of the `cloudflare:sockets` API */
+export type SocketsConnect = (address: {
+    hostname: string;
+    port: number;
+}, options?: {
+    secureTransport?: 'off' | 'on' | 'starttls' | undefined;
+    allowHalfOpen?: boolean | undefined;
+} | undefined) => SocketsApiSocket;
+/**
+ * Builds a transport for the `transport` option from the `connect()` of the `cloudflare:sockets`
+ * API, for celld and other runtimes without `node:net` and `node:tls`:
+ *
+ * ```js
+ * import { connect } from 'cloudflare:sockets';
+ * const client = new ImapFlow({ host, port: 993, secure: true, auth, transport: createSocketsTransport(connect) });
+ * ```
+ *
+ * The runtime verifies the server certificate against its own root store, so the transport
+ * refuses `tls.rejectUnauthorized: false`, a custom `tls.ca`, client certificates and a
+ * `servername` that differs from `host`. The socket carries no cipher details, so `client.tls`
+ * stays `false` on a secure connection.
+ *
+ * @param connect - The `connect` export of `cloudflare:sockets`
+ * @returns A transport for the `transport` option
+ */
+export declare function createSocketsTransport(connect: SocketsConnect): ImapTransport;

package/dist/cjs/sockets-transport.js

@@ -0,0 +1,89 @@
+"use strict";
+// The `transport` option over the `connect()` of the `cloudflare:sockets` API, for runtimes that
+// have it but no usable `node:net` or `node:tls` (celld, Cloudflare Workers). A thin adapter of
+// the API to createStreamsTransport().
+//
+// The runtime verifies every TLS certificate against its own root store and takes the SNI name
+// from the hostname it connects to, so TLS options that would change either are refused rather
+// than silently ignored.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSocketsTransport = createSocketsTransport;
+const errors_js_1 = require("./errors.js");
+const streams_transport_js_1 = require("./streams-transport.js");
+// TLS options the runtime can not honor: it always verifies the certificate against its own
+// roots, and has no client certificates
+const UNSUPPORTED_TLS_OPTIONS = ['ca', 'cert', 'key', 'pfx', 'passphrase', 'checkServerIdentity'];
+function refuse(option) {
+    throw (0, errors_js_1.createImapError)(`The ${option} option is not supported by this transport`, 'UnsupportedTransportOption');
+}
+function assertOptions(options) {
+    const tlsOptions = options.tls || {};
+    if (tlsOptions.rejectUnauthorized === false) {
+        refuse('tls.rejectUnauthorized=false');
+    }
+    if (options.servername && options.servername !== options.host) {
+        refuse('servername');
+    }
+    const unsupported = UNSUPPORTED_TLS_OPTIONS.find(key => tlsOptions[key] !== undefined);
+    if (unsupported) {
+        refuse('tls.' + unsupported);
+    }
+}
+// "1.2.3.4:993" or "[::1]:993"
+function splitAddress(address) {
+    const match = typeof address === 'string' && address.match(/^\[?(.*?)\]?:(\d+)$/);
+    return match ? { address: match[1], port: Number(match[2]) } : {};
+}
+function wrap(raw) {
+    return {
+        raw,
+        opened: raw.opened.then(info => {
+            const remote = splitAddress(info?.remoteAddress);
+            const local = splitAddress(info?.localAddress);
+            return {
+                readable: raw.readable,
+                writable: raw.writable,
+                remoteAddress: remote.address,
+                remotePort: remote.port,
+                localAddress: local.address,
+                localPort: local.port
+            };
+        }),
+        closed: raw.closed,
+        close: () => raw.close()
+    };
+}
+/**
+ * Builds a transport for the `transport` option from the `connect()` of the `cloudflare:sockets`
+ * API, for celld and other runtimes without `node:net` and `node:tls`:
+ *
+ * ```js
+ * import { connect } from 'cloudflare:sockets';
+ * const client = new ImapFlow({ host, port: 993, secure: true, auth, transport: createSocketsTransport(connect) });
+ * ```
+ *
+ * The runtime verifies the server certificate against its own root store, so the transport
+ * refuses `tls.rejectUnauthorized: false`, a custom `tls.ca`, client certificates and a
+ * `servername` that differs from `host`. The socket carries no cipher details, so `client.tls`
+ * stays `false` on a secure connection.
+ *
+ * @param connect - The `connect` export of `cloudflare:sockets`
+ * @returns A transport for the `transport` option
+ */
+function createSocketsTransport(connect) {
+    return (0, streams_transport_js_1.createStreamsTransport)({
+        open(options) {
+            // TLS options matter only for a TLS connection, a cleartext one gets them checked if
+            // it is upgraded
+            if (options.secure) {
+                assertOptions(options);
+            }
+            // Cleartext sockets are opened in starttls mode, which costs nothing until an upgrade
+            return wrap(connect({ hostname: options.host, port: options.port }, { secureTransport: options.secure ? 'on' : 'starttls' }));
+        },
+        upgrade(socket, options) {
+            assertOptions(options);
+            return wrap(socket.raw.startTls());
+        }
+    });
+}

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

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