imapflow 1.0.194 → 1.0.196

package/.github/workflows/test.yml

@@ -8,7 +8,7 @@ jobs:
     test:
         strategy:
             matrix:
-                node: [16.x, 18.x]
+                node: [20.x, 22.x, 24.x]
                 os: [ubuntu-latest]
         runs-on: ${{ matrix.os }}
         steps:

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [1.0.196](https://github.com/postalsys/imapflow/compare/v1.0.195...v1.0.196) (2025-09-14)
+
+
+### Bug Fixes
+
+* Added authzid option for AUTH=PLAIN authentication ([541c43a](https://github.com/postalsys/imapflow/commit/541c43ab0f15608c7d28f19c810e1a14bc8519bc))
+
+## [1.0.195](https://github.com/postalsys/imapflow/compare/v1.0.194...v1.0.195) (2025-08-26)
+
+
+### Bug Fixes
+
+* Add async yielding to compression readNext() to prevent CPU blocking ([18e806d](https://github.com/postalsys/imapflow/commit/18e806d5485defe6d4a0ef3eb502b17f3b2d8c2d))
+* Add async yielding to lock processing loop ([fbf1d9a](https://github.com/postalsys/imapflow/commit/fbf1d9a3aa93b4733a123553d8be0b1785f4135e))
+* Add async yielding to processInput() to prevent CPU blocking ([6b619ce](https://github.com/postalsys/imapflow/commit/6b619ced453c3ee8556e18646ad476ad82a68fbf))
+* Add async yielding to reader() method to prevent CPU blocking ([40574e3](https://github.com/postalsys/imapflow/commit/40574e322be27d8b3cdd1b32416e8395d7e395b5))
+* Add exponential backoff to FETCH retry logic ([fb99e2d](https://github.com/postalsys/imapflow/commit/fb99e2d26c9cb29e69b6d33083ef101264b4b039))
+* Add rate limiting for compression operations ([f54c1d0](https://github.com/postalsys/imapflow/commit/f54c1d0caf1bd8cc41a0779e12c915adbb55f346))
+* Correct log source indicator for client commands ([bb3ea09](https://github.com/postalsys/imapflow/commit/bb3ea09c3135c131fc8bedd733311aa3fe176261))
+
 ## [1.0.194](https://github.com/postalsys/imapflow/compare/v1.0.193...v1.0.194) (2025-08-13)
 
 

package/README.md

@@ -73,6 +73,31 @@ const main = async () => {
 main().catch(err => console.error(err));
 ```
 
+### Admin Impersonation / Delegation (SASL PLAIN with authzid)
+
+ImapFlow supports admin impersonation for mail systems like Zimbra that allow administrators to access user mailboxes. This is done using the SASL PLAIN mechanism with an authorization identity (`authzid`).
+
+```js
+const { ImapFlow } = require('imapflow');
+const client = new ImapFlow({
+    host: 'mail.example.com',
+    port: 993,
+    secure: true,
+    auth: {
+        user: 'admin@example.com', // Admin credentials (authentication identity)
+        pass: 'adminpassword',
+        authzid: 'user@example.com', // User to impersonate (authorization identity)
+        loginMethod: 'AUTH=PLAIN' // Must use PLAIN mechanism for authzid
+    }
+});
+
+// Connection will authenticate as admin but authorize as the specified user
+await client.connect();
+// Now operating on user@example.com's mailbox as admin
+```
+
+**Note:** The `authzid` parameter only works with the `AUTH=PLAIN` mechanism. The server must support admin delegation/impersonation for this to work.
+
 ## Documentation
 
 [API reference](https://imapflow.com/module-imapflow-ImapFlow.html).

package/lib/commands/authenticate.js

@@ -110,14 +110,18 @@ async function authLogin(connection, username, password) {
     }
 }
 
-async function authPlain(connection, username, password) {
+async function authPlain(connection, username, password, authzid) {
     let errorResponse = false;
     try {
         let response = await connection.exec('AUTHENTICATE', [{ type: 'ATOM', value: 'PLAIN' }], {
             onPlusTag: async () => {
-                let encodedResponse = Buffer.from(['', username, password].join('\x00')).toString('base64');
-                let loggedResponse = Buffer.from(['', username, '(* value hidden *)'].join('\x00')).toString('base64');
-                connection.log.debug({ src: 'c', msg: loggedResponse, comment: `Encoded response for AUTH=PLAIN` });
+                // SASL PLAIN format: [authzid]\x00authcid\x00password
+                // authzid: authorization identity (who to impersonate)
+                // authcid: authentication identity (who is authenticating)
+                let authzidValue = authzid || '';
+                let encodedResponse = Buffer.from([authzidValue, username, password].join('\x00')).toString('base64');
+                let loggedResponse = Buffer.from([authzidValue, username, '(* value hidden *)'].join('\x00')).toString('base64');
+                connection.log.debug({ src: 'c', msg: loggedResponse, comment: `Encoded response for AUTH=PLAIN${authzid ? ' with authzid' : ''}` });
                 connection.write(encodedResponse);
             }
         });
@@ -126,7 +130,8 @@ async function authPlain(connection, username, password) {
 
         connection.authCapabilities.set(`AUTH=PLAIN`, true);
 
-        return username;
+        // Return the identity we're authorized as (authzid if provided, otherwise username)
+        return authzid || username;
     } catch (err) {
         let errorCode = getStatusCode(err.response);
         if (errorCode) {
@@ -142,7 +147,7 @@ async function authPlain(connection, username, password) {
 }
 
 // Authenticates user using LOGIN
-module.exports = async (connection, username, { accessToken, password, loginMethod }) => {
+module.exports = async (connection, username, { accessToken, password, loginMethod, authzid }) => {
     if (connection.state !== connection.states.NOT_AUTHENTICATED) {
         // nothing to do here
         return;
@@ -157,7 +162,7 @@ module.exports = async (connection, username, { accessToken, password, loginMeth
 
     if (password) {
         if ((!loginMethod && connection.capabilities.has('AUTH=PLAIN')) || loginMethod === 'AUTH=PLAIN') {
-            return await authPlain(connection, username, password);
+            return await authPlain(connection, username, password, authzid);
         }
 
         if ((!loginMethod && connection.capabilities.has('AUTH=LOGIN')) || loginMethod === 'AUTH=LOGIN') {

package/lib/commands/fetch.js

@@ -16,7 +16,10 @@ module.exports = async (connection, range, query, options) => {
     const commandKey = connection.capabilities.has('BINARY') && options.binary && !connection.disableBinary ? 'BINARY' : 'BODY';
 
     let retryCount = 0;
-    while (retryCount < 4) {
+    const maxRetries = 4;
+    const baseDelay = 1000; // Start with 1 second delay
+
+    while (retryCount < maxRetries) {
         let messages = {
             count: 0,
             list: []
@@ -189,15 +192,25 @@ module.exports = async (connection, range, query, options) => {
             return messages;
         } catch (err) {
             if (err.code === 'ETHROTTLE') {
-                // retrying
+                // Calculate exponential backoff delay
+                const backoffDelay = Math.min(baseDelay * Math.pow(2, retryCount), 30000); // Cap at 30 seconds
+
+                // Use throttle reset time if provided and longer than backoff
+                const delay = err.throttleReset && err.throttleReset > backoffDelay ? err.throttleReset : backoffDelay;
+
                 connection.log.warn({
-                    msg: 'Retrying throttled request',
+                    msg: 'Retrying throttled request with exponential backoff',
                     cid: connection.id,
                     code: err.code,
                     response: err.responseText,
                     throttleReset: err.throttleReset,
-                    retryCount
+                    retryCount,
+                    delayMs: delay
                 });
+
+                // Wait before retrying
+                await new Promise(resolve => setTimeout(resolve, delay));
+
                 retryCount++;
                 continue;
             }

package/lib/handler/imap-stream.js

@@ -201,10 +201,17 @@ class ImapStream extends Transform {
 
     async processInput() {
         let data;
+        let processedCount = 0;
         while ((data = this.inputQueue.shift())) {
             await this.processInputChunk(data.chunk);
             // mark chunk as processed
             data.next();
+
+            // Yield to event loop every 10 chunks to prevent CPU blocking
+            processedCount++;
+            if (processedCount % 10 === 0) {
+                await new Promise(resolve => setImmediate(resolve));
+            }
         }
     }
 

package/lib/imap-flow.d.ts

@@ -23,6 +23,8 @@ export interface ImapFlowOptions {
         accessToken?: string;
         /** Optional login method override. Set to 'LOGIN', 'AUTH=LOGIN' or 'AUTH=PLAIN' to use specific method */
         loginMethod?: string;
+        /** Authorization identity for SASL PLAIN (used for admin impersonation/delegation). When set, authenticates as `user` but authorizes as `authzid` */
+        authzid?: string;
     };
     /** Client identification info sent to the server if server supports ID extension */
     clientInfo?: IdInfoObject;

package/lib/imap-flow.js

@@ -158,6 +158,12 @@ class ImapFlow extends EventEmitter {
      *     Optional login method for password-based authentication (e.g., "LOGIN", "AUTH=LOGIN", or "AUTH=PLAIN").
      *     If not set, ImapFlow chooses based on available mechanisms.
      *
+     * @property {String} [auth.authzid]
+     *     Authorization identity for SASL PLAIN authentication (used for admin impersonation/delegation).
+     *     When set, authenticates as `auth.user` but authorizes as `auth.authzid`.
+     *     This is typically used in mail systems like Zimbra for admin users to access other users' mailboxes.
+     *     Only works with AUTH=PLAIN mechanism.
+     *
      * @property {IdInfoObject} [clientInfo]
      *     Client identification info sent to the server (via the ID command).
      *
@@ -495,7 +501,7 @@ class ImapFlow extends EventEmitter {
 
         let options = data.options || {};
 
-        this.log.debug({ src: 's', msg: logCompiled.toString(), cid: this.id, comment: options.comment });
+        this.log.debug({ src: 'c', msg: logCompiled.toString(), cid: this.id, comment: options.comment });
 
         this.write(this.commandParts.shift());
 
@@ -572,6 +578,7 @@ class ImapFlow extends EventEmitter {
 
     async reader() {
         let data;
+        let processedCount = 0;
         while ((data = this.streamer.read()) !== null) {
             let parsed;
 
@@ -737,6 +744,12 @@ class ImapFlow extends EventEmitter {
             }
 
             data.next();
+
+            // Yield to event loop every 10 processed messages to prevent CPU blocking
+            processedCount++;
+            if (processedCount % 10 === 0) {
+                await new Promise(resolve => setImmediate(resolve));
+            }
         }
     }
 
@@ -885,11 +898,17 @@ class ImapFlow extends EventEmitter {
             return; // was not able to negotiate compression
         }
 
-        // create deflate/inflate streams
+        // create deflate/inflate streams with rate limiting options
         this._deflate = zlib.createDeflateRaw({
-            windowBits: 15
+            windowBits: 15,
+            level: zlib.constants.Z_DEFAULT_COMPRESSION, // Use default compression level (6)
+            memLevel: 8, // Memory usage level (8 is default)
+            strategy: zlib.constants.Z_DEFAULT_STRATEGY,
+            chunkSize: 16 * 1024 // Process in 16KB chunks to prevent CPU blocking
+        });
+        this._inflate = zlib.createInflateRaw({
+            chunkSize: 16 * 1024 // Process in 16KB chunks to prevent CPU blocking
         });
-        this._inflate = zlib.createInflateRaw();
 
         // route incoming socket via inflate stream
         this.socket.unpipe(this.streamer);
@@ -899,8 +918,10 @@ class ImapFlow extends EventEmitter {
             this.streamer.emit('error', err);
         });
 
-        // route outgoing socket via deflate stream
-        this.writeSocket = new PassThrough();
+        // route outgoing socket via deflate stream with rate limiting
+        this.writeSocket = new PassThrough({
+            highWaterMark: 64 * 1024 // 64KB buffer limit to prevent excessive memory usage
+        });
 
         this.writeSocket.destroySoon = () => {
             try {
@@ -921,15 +942,23 @@ class ImapFlow extends EventEmitter {
         // we need to force flush deflated data to socket so we can't
         // use normal pipes for this.writeSocket -> this._deflate -> this.socket
         let reading = false;
-        let readNext = () => {
+        let processedChunks = 0;
+        let readNext = async () => {
             try {
                 reading = true;
+                processedChunks = 0;
 
                 let chunk;
                 while ((chunk = this.writeSocket.read()) !== null) {
                     if (this._deflate && this._deflate.write(chunk) === false) {
                         return this._deflate.once('drain', readNext);
                     }
+
+                    // Yield to event loop every 100 chunks to prevent CPU blocking
+                    processedChunks++;
+                    if (processedChunks % 100 === 0) {
+                        await new Promise(resolve => setImmediate(resolve));
+                    }
                 }
 
                 // flush data to socket
@@ -1117,7 +1146,11 @@ class ImapFlow extends EventEmitter {
             this.authenticated = await this.run('AUTHENTICATE', this.options.auth.user, { accessToken: this.options.auth.accessToken });
         } else if (this.options.auth.pass) {
             if ((this.capabilities.has('AUTH=LOGIN') || this.capabilities.has('AUTH=PLAIN')) && loginMethod !== 'LOGIN') {
-                this.authenticated = await this.run('AUTHENTICATE', this.options.auth.user, { password: this.options.auth.pass, loginMethod });
+                this.authenticated = await this.run('AUTHENTICATE', this.options.auth.user, {
+                    password: this.options.auth.pass,
+                    loginMethod,
+                    authzid: this.options.auth.authzid
+                });
             } else {
                 if (this.capabilities.has('LOGINDISABLED')) {
                     throw new AuthenticationFailure('Login is disabled');
@@ -3236,6 +3269,7 @@ class ImapFlow extends EventEmitter {
 
         try {
             // Process all locks in queue until empty
+            let processedCount = 0;
             while (this.locks.length > 0) {
                 if (!this.locks.length) {
                     this.log.trace({
@@ -3245,6 +3279,12 @@ class ImapFlow extends EventEmitter {
                     return;
                 }
 
+                // Yield to event loop periodically to prevent CPU blocking
+                processedCount++;
+                if (processedCount % 5 === 0) {
+                    await new Promise(resolve => setImmediate(resolve));
+                }
+
                 const release = () => {
                     if (this.currentLock) {
                         this.log.trace({

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.0.194",
+    "version": "1.0.196",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",
@@ -28,11 +28,11 @@
     },
     "homepage": "https://imapflow.com/",
     "devDependencies": {
-        "@babel/eslint-parser": "7.28.0",
+        "@babel/eslint-parser": "7.28.4",
         "@babel/eslint-plugin": "7.27.1",
         "@babel/plugin-syntax-class-properties": "7.12.13",
-        "@babel/preset-env": "7.28.0",
-        "@types/node": "24.2.1",
+        "@babel/preset-env": "7.28.3",
+        "@types/node": "24.4.0",
         "eslint": "8.57.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "9.1.0",
@@ -42,18 +42,18 @@
         "grunt-eslint": "24.3.0",
         "imapflow-jsdoc-template": "3.4.0-imapflow.3",
         "jsdoc": "4.0.4",
-        "st": "3.0.2",
+        "st": "3.0.3",
         "typescript": "5.9.2"
     },
     "dependencies": {
         "encoding-japanese": "2.2.0",
-        "iconv-lite": "0.6.3",
+        "iconv-lite": "0.7.0",
         "libbase64": "1.3.0",
         "libmime": "5.3.7",
         "libqp": "2.1.1",
         "mailsplit": "5.4.6",
-        "nodemailer": "7.0.5",
-        "pino": "9.8.0",
+        "nodemailer": "7.0.6",
+        "pino": "9.9.5",
         "socks": "2.8.7"
     }
 }

package/test/authentication-test.js

@@ -11,7 +11,7 @@ module.exports['Authentication: Password auth configuration'] = test => {
             pass: 'testpass'
         }
     });
-    
+
     test.equal(client.options.auth.user, 'testuser');
     test.equal(client.options.auth.pass, 'testpass');
     test.done();
@@ -25,7 +25,7 @@ module.exports['Authentication: OAuth2 auth configuration'] = test => {
             accessToken: 'oauth2_token_here'
         }
     });
-    
+
     test.equal(client.options.auth.user, 'testuser');
     test.equal(client.options.auth.accessToken, 'oauth2_token_here');
     test.done();
@@ -40,14 +40,32 @@ module.exports['Authentication: Login method specification'] = test => {
             loginMethod: 'AUTH=PLAIN'
         }
     });
-    
+
+    test.equal(client.options.auth.loginMethod, 'AUTH=PLAIN');
+    test.done();
+};
+
+module.exports['Authentication: SASL PLAIN with authzid for impersonation'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: {
+            user: 'admin@example.com',
+            pass: 'adminpass',
+            authzid: 'user@example.com',
+            loginMethod: 'AUTH=PLAIN'
+        }
+    });
+
+    test.equal(client.options.auth.user, 'admin@example.com');
+    test.equal(client.options.auth.pass, 'adminpass');
+    test.equal(client.options.auth.authzid, 'user@example.com');
     test.equal(client.options.auth.loginMethod, 'AUTH=PLAIN');
     test.done();
 };
 
 module.exports['Authentication: AuthenticationFailure error structure'] = test => {
     let error = new AuthenticationFailure('Invalid credentials');
-    
+
     test.ok(error instanceof Error);
     test.equal(error.constructor.name, 'AuthenticationFailure');
     test.equal(error.message, 'Invalid credentials');
@@ -63,7 +81,7 @@ module.exports['Authentication: Verify-only mode'] = test => {
         },
         verifyOnly: true
     });
-    
+
     test.equal(client.options.verifyOnly, true);
     test.done();
 };
@@ -77,7 +95,7 @@ module.exports['Authentication: Disable auto IDLE'] = test => {
         },
         disableAutoIdle: true
     });
-    
+
     test.equal(client.options.disableAutoIdle, true);
     test.done();
-};
+};