imapflow 1.0.195 → 1.0.197

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.0.197](https://github.com/postalsys/imapflow/compare/v1.0.196...v1.0.197) (2025-09-24)
+
+
+### Bug Fixes
+
+* **imap ID:** Re-request ID information if only a single key was returned ([87bc016](https://github.com/postalsys/imapflow/commit/87bc016ae677b4428916d4a2047abcdeb95950bb))
+
+## [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)
 
 

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/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).
      *
@@ -851,7 +857,7 @@ class ImapFlow extends EventEmitter {
 
         await this.authenticate();
 
-        if (!this.idRequested && this.capabilities.has('ID')) {
+        if ((!this.idRequested || Object.keys(this.idRequested).length < 2) && this.capabilities.has('ID')) {
             // re-request ID after LOGIN
             this.idRequested = await this.run('ID', this.clientInfo);
         }
@@ -1140,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');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.0.195",
+    "version": "1.0.197",
     "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.3",
-        "@types/node": "24.3.0",
+        "@types/node": "24.4.0",
         "eslint": "8.57.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "9.1.0",
@@ -52,8 +52,8 @@
         "libmime": "5.3.7",
         "libqp": "2.1.1",
         "mailsplit": "5.4.6",
-        "nodemailer": "7.0.5",
-        "pino": "9.9.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();
-};
+};