imapflow 1.0.169 → 1.0.170

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.0.170](https://github.com/postalsys/imapflow/compare/v1.0.169...v1.0.170) (2024-12-05)
+
+
+### Bug Fixes
+
+* **uidvalidity:** Do not expect UIDVALIDITY to always exist ([7761653](https://github.com/postalsys/imapflow/commit/7761653e92965a09be8a872813363eb81f7f3d9a))
+
 ## [1.0.169](https://github.com/postalsys/imapflow/compare/v1.0.168...v1.0.169) (2024-11-08)
 
 

package/lib/commands/authenticate.js

@@ -151,13 +151,12 @@ module.exports = async (connection, username, { accessToken, password }) => {
     }
 
     if (password) {
-        if (connection.capabilities.has('AUTH=LOGIN')) {
-            return await authLogin(connection, username, password);
-        }
-
         if (connection.capabilities.has('AUTH=PLAIN')) {
             return await authPlain(connection, username, password);
         }
+        if (connection.capabilities.has('AUTH=LOGIN')) {
+            return await authLogin(connection, username, password);
+        }
     }
 
     throw new Error('Unsupported authentication mechanism');

package/lib/commands/select.js

@@ -40,7 +40,7 @@ module.exports = async (connection, path, options) => {
             extraArgs.push([
                 { type: 'ATOM', value: 'QRESYNC' },
                 [
-                    { type: 'ATOM', value: options.uidValidity.toString() },
+                    { type: 'ATOM', value: options.uidValidity?.toString() },
                     { type: 'ATOM', value: options.changedSince.toString() }
                 ]
             ]);

package/lib/imap-flow.js

@@ -119,8 +119,19 @@ class ImapFlow extends EventEmitter {
      * @param {Object} options IMAP connection options
      * @param {String} options.host Hostname of the IMAP server
      * @param {Number} options.port Port number for the IMAP server
-     * @param {Boolean} [options.secure=false] Should the connection be established over TLS.
-     *      If `false` then connection is upgraded to TLS using STARTTLS extension before authentication
+     * @param {Boolean} [options.secure=false] Should the connection be established immediately and directly over TLS? Typically on port 993.
+     * @param {Boolean} [options.doSTARTTLS=undefined] Should the connection be established using STARTTLS?
+     *      * If `true`, the connection is first established as unencrypted and then upgraded to TLS using STARTTLS, before authentication.
+     *        If the server does not advertize the `STARTTLS` `CAPABILITY`, or the upgrade fails for other reasons, then the connection fails.
+     *        Note: The combination `secure=true` (direct TLS) and `doSTARTTLS=true` is invalid.
+     *      * If `false`, then STARTTLS will not be used, even if the server advertizes it in IMAP `CAPABILITY`.
+     *        This helps with servers that have a broken TLS configuration.
+     *        If `doSTARTTLS=false` and `secure=false`, then a plain unencrypted socket is used.
+     *        Be sure to clearly warn the user about the consequences.
+     *      * If `undefined` (default) and `secure=false` (default), the connection is upgraded using STARTTLS before authentication, /only if possible/ .
+     *        If not possible, the connection will use an unencrypted plain socket.
+     *        This can mean TLS is used under normal circumstances, but a serious attacker can force an unencrypted connection and steal passwords,
+     *        called "downgrade attack". This can lead to a false sense of security. Be sure to warn the user.
      * @param {String} [options.servername] Servername for SNI (or when host is set to an IP address)
      * @param {Boolean} [options.disableCompression=false] if `true` then client does not try to use COMPRESS=DEFLATE extension
      * @param {Object} options.auth Authentication options. Authentication is requested automatically during <code>connect()</code>
@@ -589,7 +600,7 @@ class ImapFlow extends EventEmitter {
 
                             if (err.responseStatus === 'NO' && txt.includes('Some of the requested messages no longer exist')) {
                                 // Treat as successful response
-                                this.log.warn({ msg: 'Partial Gmail response', cid: this.id, err });
+                                this.log.warn({ msg: 'Partial FETCH response', cid: this.id, err });
                                 await new Promise(resolve => request.resolve({ response: parsed, next: resolve }));
                                 break;
                             }
@@ -715,10 +726,7 @@ class ImapFlow extends EventEmitter {
             this.idRequested = await this.run('ID', this.clientInfo);
         }
 
-        // try to use STARTTLS is possible
-        if (!this.secureConnection) {
-            await this.upgradeConnection();
-        }
+        await this.upgradeToSTARTTLS();
 
         let authenticated = await this.authenticate();
         if (!authenticated) {
@@ -837,21 +845,47 @@ class ImapFlow extends EventEmitter {
         });
     }
 
-    async upgradeConnection() {
+    _failSTARTTLS() {
+        if (this.options.doSTARTTLS === true) {
+            // STARTTLS configured as requirement
+            let err = new Error('Server does not support STARTTLS');
+            err.tlsFailed = true;
+            throw err;
+        } else {
+            // Opportunistic STARTTLS. But it's not possible right now.
+            // Attention: Could be a downgrade attack.
+            return false;
+        }
+    }
+
+    /**
+     * Tries to upgrade the connection to TLS using STARTTLS.
+     * @throws if STARTTLS is required, but not possible.
+     * @returns {boolean} true, if the connection is now protected by TLS, either direct TLS or STARTTLS.
+     */
+    async upgradeToSTARTTLS() {
+        if (this.options.doSTARTTLS === true && this.options.secure === true) {
+            throw new Error('Misconfiguration: Cannot set both secure=true for TLS and doSTARTTLS=true for STARTTLS.');
+        }
+
         if (this.secureConnection) {
-            // already secure
+            // Already using direct TLS. No need for STARTTLS.
             return true;
         }
 
-        if (!this.capabilities.has('STARTTLS')) {
-            // can not upgrade
+        if (this.options.doSTARTTLS === false) {
+            // STARTTLS explictly disabled by config
             return false;
         }
 
+        if (!this.capabilities.has('STARTTLS')) {
+            return this._failSTARTTLS();
+        }
+
         this.expectCapabilityUpdate = true;
         let canUpgrade = await this.run('STARTTLS');
         if (!canUpgrade) {
-            return;
+            return this._failSTARTTLS();
         }
 
         this.socket.unpipe(this.streamer);
@@ -875,6 +909,7 @@ class ImapFlow extends EventEmitter {
                 }
                 setImmediate(() => this.close());
                 this.upgrading = false;
+                err.tlsFailed = true;
                 reject(err);
             });
 
@@ -884,6 +919,7 @@ class ImapFlow extends EventEmitter {
                 }
                 setImmediate(() => this.close());
                 let err = new Error('Failed to upgrade connection in required time');
+                err.tlsFailed = true;
                 err.code = 'UPGRADE_TIMEOUT';
                 reject(err);
             }, UPGRADE_TIMEOUT);

package/lib/tools.js

@@ -390,7 +390,11 @@ module.exports = {
                 }
             }
 
-            map.id = map.emailId || createHash('md5').update([path, mailbox.uidValidity.toString(), map.uid.toString()].join(':')).digest('hex');
+            map.id =
+                map.emailId ||
+                createHash('md5')
+                    .update([path, mailbox.uidValidity?.toString() || '', map.uid.toString()].join(':'))
+                    .digest('hex');
         }
 
         if (map.flags) {

package/lib/types.d.ts

@@ -8,8 +8,19 @@ declare module "imapflow" {
      * @param options - IMAP connection options
      * @param options.host - Hostname of the IMAP server
      * @param options.port - Port number for the IMAP server
-     * @param [options.secure = false] - Should the connection be established over TLS.
-     *      If `false` then connection is upgraded to TLS using STARTTLS extension before authentication
+     * @param [options.secure = false] - Should the connection be established immediately and directly over TLS? Typically on port 993.
+     * @param [options.doSTARTTLS] - Should the connection be established using STARTTLS?
+     *      * If `true`, the connection is first established as unencrypted and then upgraded to TLS using STARTTLS, before authentication.
+     *        If the server does not advertize the `STARTTLS` `CAPABILITY`, or the upgrade fails for other reasons, then the connection fails.
+     *        Note: The combination `secure=true` (direct TLS) and `doSTARTTLS=true` is invalid.
+     *      * If `false`, then STARTTLS will not be used, even if the server advertizes it in IMAP `CAPABILITY`.
+     *        This helps with servers that have a broken TLS configuration.
+     *        If `doSTARTTLS=false` and `secure=false`, then a plain unencrypted socket is used.
+     *        Be sure to clearly warn the user about the consequences.
+     *      * If `undefined` (default) and `secure=false` (default), the connection is upgraded using STARTTLS before authentication, /only if possible/ .
+     *        If not possible, the connection will use an unencrypted plain socket.
+     *        This can mean TLS is used under normal circumstances, but a serious attacker can force an unencrypted connection and steal passwords,
+     *        called "downgrade attack". This can lead to a false sense of security. Be sure to warn the user.
      * @param [options.servername] - Servername for SNI (or when host is set to an IP address)
      * @param [options.disableCompression = false] - if `true` then client does not try to use COMPRESS=DEFLATE extension
      * @param options.auth - Authentication options. Authentication is requested automatically during <code>connect()</code>
@@ -41,6 +52,7 @@ declare module "imapflow" {
             host: string;
             port: number;
             secure?: boolean;
+            doSTARTTLS?: boolean;
             servername?: string;
             disableCompression?: boolean;
             auth: {
@@ -122,6 +134,11 @@ declare module "imapflow" {
          * If `true` then in addition of sending data to logger, ImapFlow emits 'log' events with the same data
          */
         emitLogs: boolean;
+        /**
+         * Tries to upgrade the connection to TLS using STARTTLS.
+         * @returns true, if the connection is now protected by TLS, either direct TLS or STARTTLS.
+         */
+        upgradeToSTARTTLS(): boolean;
         /**
          * Initiates a connection against IMAP server. Throws if anything goes wrong. This is something you have to call before you can run any IMAP commands
          * @example

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.0.169",
+    "version": "1.0.170",
     "description": "IMAP Client for Node",
     "main": "./lib/imap-flow.js",
     "scripts": {
@@ -32,7 +32,7 @@
         "@babel/eslint-plugin": "7.25.9",
         "@babel/plugin-syntax-class-properties": "7.12.13",
         "@babel/preset-env": "7.26.0",
-        "@types/node": "22.9.0",
+        "@types/node": "22.10.1",
         "eslint": "8.57.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "9.1.0",
@@ -40,7 +40,7 @@
         "grunt-cli": "1.5.0",
         "grunt-contrib-nodeunit": "5.0.0",
         "grunt-eslint": "24.3.0",
-        "imapflow-jsdoc-template": "3.4.0-imapflow.1",
+        "imapflow-jsdoc-template": "3.4.0-imapflow.2",
         "jsdoc": "3.6.11",
         "st": "3.0.1",
         "tsd-jsdoc": "2.5.0"
@@ -49,9 +49,9 @@
         "encoding-japanese": "2.2.0",
         "iconv-lite": "0.6.3",
         "libbase64": "1.3.0",
-        "libmime": "5.3.5",
-        "libqp": "2.1.0",
-        "mailsplit": "5.4.0",
+        "libmime": "5.3.6",
+        "libqp": "2.1.1",
+        "mailsplit": "5.4.2",
         "nodemailer": "6.9.16",
         "pino": "9.5.0",
         "socks": "2.8.3"