imapflow 1.7.0 → 1.7.1

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.7.0"
+    ".": "1.7.1"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.7.1](https://github.com/postalsys/imapflow/compare/v1.7.0...v1.7.1) (2026-08-14)
+
+
+### Bug Fixes
+
+* **logging:** mask credential frames in the raw log and keep error detail ([2d6563b](https://github.com/postalsys/imapflow/commit/2d6563b75410a2cd9d4fbca08a76230589b60079))
+
 ## [1.7.0](https://github.com/postalsys/imapflow/compare/v1.6.6...v1.7.0) (2026-08-11)
 
 

package/README.md

@@ -5,7 +5,7 @@ Modern and easy-to-use IMAP client library for Node.js.
 [![npm](https://img.shields.io/npm/v/imapflow)](https://www.npmjs.com/package/imapflow)
 [![license](https://img.shields.io/npm/l/imapflow)](https://github.com/postalsys/imapflow/blob/master/LICENSE)
 
-ImapFlow provides a clean, promise-based API for working with IMAP, so you don't need in-depth knowledge of the protocol. IMAP extensions are detected and handled automatically. You write the same code regardless of server capabilities, and ImapFlow adapts behind the scenes.
+ImapFlow provides a clean, promise-based API for working with IMAP, so you don't need in-depth knowledge of the protocol. IMAP extensions are detected and handled automatically. You write the same code regardless of server capabilities, and ImapFlow adapts behind the scenes. ImapFlow is the IMAP engine that powers [EmailEngine](https://emailengine.app/?utm_source=imapflow-readme&utm_medium=readme&utm_campaign=oss-docs&utm_content=intro), a self-hosted email API built by the same team.
 
 ## Features
 
@@ -77,8 +77,7 @@ Full documentation is available at **[imapflow.com](https://imapflow.com/docs/)*
 - [Mailbox Management](https://imapflow.com/docs/guides/mailbox-management) - creating, renaming, and deleting mailboxes
 - [API Reference](https://imapflow.com/docs/api/imapflow-client) - complete method and event documentation
 
-> [!NOTE]
-> If you are looking for a complete email integration solution, ImapFlow was built for [EmailEngine](https://emailengine.app/), a self-hosted email gateway that provides REST API access to IMAP and SMTP accounts.
+> ImapFlow was built for **[EmailEngine](https://emailengine.app/?utm_source=imapflow-readme&utm_medium=readme&utm_campaign=oss-docs&utm_content=note)**, a self-hosted email API that turns Gmail, Microsoft 365, and IMAP accounts into REST endpoints, with managed OAuth2 and webhooks for incoming mail. If you need a production email integration rather than an IMAP client, start there.
 
 ## License
 

package/lib/commands/authenticate.js

@@ -81,11 +81,16 @@ async function authOauth(connection, username, accessToken) {
                         try {
                             errorResponse = JSON.parse(Buffer.from(resp.attributes[0].value, 'base64').toString());
                         } catch (err) {
-                            connection.log.debug({ errorResponse: resp.attributes[0].value, err });
+                            connection.log.debug({
+                                msg: 'Failed to parse OAuth error response',
+                                errorResponse: resp.attributes[0].value,
+                                err,
+                                cid: connection.id
+                            });
                         }
                     }
 
-                    connection.log.debug({ src: 'c', msg: breaker, comment: `Error response for ${command}` });
+                    connection.log.debug({ src: 'c', msg: breaker, comment: `Error response for ${command}`, cid: connection.id });
                     connection.write(breaker);
                 }
             }
@@ -126,10 +131,10 @@ async function authLogin(connection, username, password) {
 
                     if (question === 'username' || question === 'user name') {
                         let encodedUsername = Buffer.from(username).toString('base64');
-                        connection.log.debug({ src: 'c', msg: encodedUsername, comment: `Encoded username for AUTH=LOGIN` });
+                        connection.log.debug({ src: 'c', msg: encodedUsername, comment: `Encoded username for AUTH=LOGIN`, cid: connection.id });
                         connection.write(encodedUsername);
                     } else if (question === 'password') {
-                        connection.log.debug({ src: 'c', msg: '(* value hidden *)', comment: `Encoded password for AUTH=LOGIN` });
+                        connection.log.debug({ src: 'c', msg: '(* value hidden *)', comment: `Encoded password for AUTH=LOGIN`, cid: connection.id });
                         connection.write(Buffer.from(password).toString('base64'));
                     } else {
                         throw new Error(`Unknown LOGIN question "${question}"`);
@@ -169,7 +174,12 @@ async function authPlain(connection, username, password, authzid) {
                 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.log.debug({
+                    src: 'c',
+                    msg: loggedResponse,
+                    comment: `Encoded response for AUTH=PLAIN${authzid ? ' with authzid' : ''}`,
+                    cid: connection.id
+                });
                 connection.write(encodedResponse);
             }
         });

package/lib/commands/idle.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { hasCapability, unrefTimer } = require('../tools.js');
+const { hasCapability, logConnectionError, unrefTimer } = require('../tools.js');
 
 const NOOP_INTERVAL = 2 * 60 * 1000;
 
@@ -64,7 +64,8 @@ async function runIdle(connection) {
                     msg: `DONE`,
                     comment: `breaking IDLE`,
                     lockId: connection.currentLock?.lockId,
-                    path: connection.mailbox && connection.mailbox.path
+                    path: connection.mailbox && connection.mailbox.path,
+                    cid: connection.id
                 });
                 connection.write('DONE');
                 doneSent = true;
@@ -95,10 +96,11 @@ async function runIdle(connection) {
                 queued: preCheckWaitQueue.length,
                 doneRequested,
                 canEnd,
-                doneSent
+                doneSent,
+                cid: connection.id
             });
 
-            preCheck().catch(err => connection.log.warn({ err, cid: connection.id }));
+            preCheck().catch(err => logConnectionError(connection, 'Failed to break IDLE', err));
 
             return handler;
         };
@@ -112,13 +114,18 @@ async function runIdle(connection) {
             // After this, the server will push untagged responses for mailbox changes.
             // We can now safely send DONE if a break was already requested.
             onPlusTag: async () => {
-                connection.log.debug({ msg: `Initiated IDLE, waiting for server input`, lockId: connection.currentLock?.lockId, doneRequested });
+                connection.log.debug({
+                    msg: `Initiated IDLE, waiting for server input`,
+                    lockId: connection.currentLock?.lockId,
+                    doneRequested,
+                    cid: connection.id
+                });
                 canEnd = true;
                 if (doneRequested) {
                     try {
                         await preCheck();
                     } catch (err) {
-                        connection.log.warn({ err, cid: connection.id });
+                        logConnectionError(connection, 'Failed to break IDLE', err);
                     }
                 }
             },
@@ -128,7 +135,7 @@ async function runIdle(connection) {
         response.next();
         return;
     } catch (err) {
-        connection.log.warn({ err, cid: connection.id });
+        logConnectionError(connection, 'IDLE session failed', err);
         while (preCheckWaitQueue.length) {
             let { reject } = preCheckWaitQueue.shift();
             reject(err);
@@ -166,12 +173,12 @@ async function pollOnce(connection, session) {
 
     switch (connection.missingIdleCommand) {
         case 'SELECT':
-            connection.log.debug({ src: 'c', msg: `Running SELECT to detect changes in folder`, cid: connection.id });
+            connection.log.debug({ msg: `Running SELECT to detect changes in folder`, cid: connection.id });
             await connection.runInternal('SELECT', path, { readOnly: session.selectCommand.command === 'EXAMINE' });
             break;
 
         case 'STATUS': {
-            connection.log.debug({ src: 'c', msg: `Running STATUS to detect changes in folder`, cid: connection.id });
+            connection.log.debug({ msg: `Running STATUS to detect changes in folder`, cid: connection.id });
             // HIGHESTMODSEQ is filtered out again unless the server advertises CONDSTORE, so a
             // CONDSTORE session keeps mailbox.highestModseq current without asking a plain
             // server for an item it does not know.
@@ -240,7 +247,7 @@ async function runPollingFallback(connection, maxIdleTime) {
             };
 
             session.preCheck = async () => {
-                connection.log.debug({ src: 'c', msg: `breaking NOOP loop`, cid: connection.id });
+                connection.log.debug({ msg: `Breaking NOOP loop`, cid: connection.id });
                 cancel();
             };
             connection.preCheck = session.preCheck;
@@ -269,7 +276,7 @@ async function runPollingFallback(connection, maxIdleTime) {
                         scheduleNextPoll(interval);
                     })
                     .catch(err => {
-                        connection.log.warn({ err, cid: connection.id });
+                        logConnectionError(connection, 'Failed to poll for mailbox changes', err);
                         cancel();
                     });
             };
@@ -280,7 +287,7 @@ async function runPollingFallback(connection, maxIdleTime) {
                 unrefTimer(session.timer);
             }
 
-            connection.log.debug({ src: 'c', msg: `initiated NOOP loop`, cid: connection.id });
+            connection.log.debug({ msg: `Initiated NOOP loop`, cid: connection.id });
 
             // Every auto-IDLE restart begins a fresh polling session, so an unconditional first
             // poll would tie the poll rate to how often the caller runs commands rather than to
@@ -339,7 +346,7 @@ module.exports = async (connection, maxIdleTime) => {
                             stillIdling = true;
                             // request IDLE break if IDLE has been running for allowed time
                             connection.log.trace({ msg: 'Max allowed IDLE time reached', cid: connection.id });
-                            connection.preCheck().catch(err => connection.log.warn({ err, cid: connection.id }));
+                            connection.preCheck().catch(err => logConnectionError(connection, 'Failed to break IDLE for restart', err));
                         }
                     }
                 }, maxIdleTime);

package/lib/imap-flow.d.ts

@@ -45,7 +45,10 @@ export interface ImapFlowOptions {
     tls?: ConnectionOptions;
     /** Custom logger instance. Set to false to disable logging */
     logger?: Logger | false;
-    /** If true, log data read and written to socket encoded in base64 */
+    /**
+     * If true, log data read and written to socket encoded in base64. Client frames that carry
+     * credentials are replaced with a fixed placeholder and marked with `hidden: true`.
+     */
     logRaw?: boolean;
     /** If true, emit 'log' events */
     emitLogs?: boolean;

package/lib/imap-flow.js

@@ -38,6 +38,7 @@ const {
     AuthenticationFailure,
     getColorFlags,
     hasCapability,
+    logConnectionError,
     unrefTimer,
     parseUintValue,
     isUnsafeKey,
@@ -73,6 +74,78 @@ const AUTO_IDLE_DELAY = 15 * 1000;
 // the wire before the watchdog can fire. See normalizeAutoIdleDelay().
 const AUTO_IDLE_SOCKET_MARGIN = 1000;
 
+// Commands whose client frames carry credentials; the raw traffic log withholds frame content
+// while one of these is in flight. See the logRaw branch in write().
+const RAW_SENSITIVE_COMMANDS = new Set(['LOGIN', 'AUTHENTICATE']);
+
+// Stand-in payload for a withheld raw client frame. Fixed width, so the entry says nothing
+// about the length of what it replaced.
+const RAW_HIDDEN_PLACEHOLDER = Buffer.from('(* value hidden *)\r\n').toString('base64');
+
+// Whether any attribute of a command is marked as a secret. Recurses into nested lists because
+// the command compiler honors `sensitive` at any depth, and the two must agree on what counts.
+function hasSensitiveAttribute(attributes) {
+    return [].concat(attributes || []).some(node => (Array.isArray(node) ? hasSensitiveAttribute(node) : !!node && node.sensitive));
+}
+
+// How deep flattenLoggedError() follows a chain of errors. Bounded because the chain comes from
+// whatever failed, not from this library: a cause chain can be arbitrarily long, and the cycle
+// check below only catches errors that repeat.
+const MAX_ERROR_FLATTEN_DEPTH = 4;
+
+// Recognizes an Error without instanceof, which fails for an error that crossed a realm boundary
+// (worker thread, vm context) even though it serializes exactly the same way.
+function isErrorLike(value) {
+    return value instanceof Error || (!!value && typeof value === 'object' && typeof value.message === 'string' && typeof value.stack === 'string');
+}
+
+// An Error carries `message` and `stack` on its prototype rather than as own enumerable
+// properties, so JSON.stringify() renders one as `{}` and both logger fallback paths (the console
+// fallback and emitLogs) would drop everything identifying it. Flattening happens here for both,
+// so their shapes cannot drift apart.
+//
+// Nested errors are flattened too, because the top level is often not where the answer is: this
+// library attaches the underlying failure as an enumerable `_err` (proxy setup, response
+// processing, normalized connection deadlines), and Node reports a multi-address connect failure
+// as an AggregateError whose members hold the per-address causes.
+function flattenLoggedError(value, depth = 0, seen = new Set()) {
+    if (depth >= MAX_ERROR_FLATTEN_DEPTH) {
+        return isErrorLike(value) ? value.message : value;
+    }
+
+    if (Array.isArray(value)) {
+        return value.map(entry => flattenLoggedError(entry, depth + 1, seen));
+    }
+
+    if (!isErrorLike(value)) {
+        // Anything else is left alone: exploding a Buffer would produce one key per byte, and a
+        // Date would become a pair of undefined fields.
+        return value;
+    }
+
+    // A repeat renders as its message alone, so a chain that loops back does not restate a full
+    // stack for every level down to the depth cap
+    if (seen.has(value)) {
+        return value.message;
+    }
+    seen.add(value);
+
+    let flatErr = {
+        message: value.message,
+        stack: value.stack
+    };
+
+    // `cause` (passed through the Error options argument) and the AggregateError members are own
+    // properties but not enumerable, so Object.keys does not list them
+    for (let key of new Set([...Object.keys(value), 'cause', 'errors'])) {
+        if (key in value) {
+            flatErr[key] = flattenLoggedError(value[key], depth + 1, seen);
+        }
+    }
+
+    return flatErr;
+}
+
 // The largest delay setTimeout can honor (2^31 - 1 ms). Anything above fires after 1 ms instead,
 // so the auto-IDLE delay cap has to stay inside this range even when socketTimeout is not.
 const MAX_TIMER_DELAY = 2 ** 31 - 1;
@@ -271,6 +344,7 @@ class ImapFlow extends EventEmitter {
      *
      * @property {Boolean} [logRaw=false]
      *     If `true`, logs all raw data (read and written) in base64 encoding. You can pipe such logs to [eerawlog](https://github.com/postalsys/eerawlog) command for readable output.
+     *     Client frames that carry credentials are replaced with a fixed placeholder and the entry is marked with `hidden: true`.
      *
      * @property {Boolean} [emitLogs=false]
      *     If `true`, emits `'log'` events with the same data passed to the logger.
@@ -438,6 +512,13 @@ class ImapFlow extends EventEmitter {
 
         this.commandParts = [];
 
+        // Whether the command currently being written carries credentials. send() sets this for
+        // every command before its first frame reaches the socket, and the raw traffic log reads
+        // it; every write belongs to the command send() dispatched last, because trySend() keeps
+        // one command in flight at a time. The initial value only covers a write before the
+        // first command, which no current path performs. See write().
+        this.rawSensitiveCommand = true;
+
         /**
          * Active IMAP capabilities. Value is either `true` for toggleable capabilities (eg. `UIDPLUS`)
          * or a number for capabilities with a value (eg. `APPENDLIMIT`)
@@ -632,10 +713,17 @@ class ImapFlow extends EventEmitter {
         }
 
         if (this.logRaw) {
+            // Client frames of an authentication exchange carry credentials: the LOGIN
+            // arguments, and for AUTHENTICATE also the continuation writes (SASL PLAIN
+            // response, AUTH=LOGIN password, OAuth token payload) that bypass send(). The
+            // parsed command log masks these, so the raw log must withhold them too, but
+            // `data` still carries the placeholder rather than being dropped - the field is
+            // part of the documented log format and consumers decode it unconditionally.
             this.log.trace({
                 src: 'c',
                 msg: 'write to socket',
-                data: chunk.toString('base64'),
+                data: this.rawSensitiveCommand ? RAW_HIDDEN_PLACEHOLDER : chunk.toString('base64'),
+                ...(this.rawSensitiveCommand ? { hidden: true } : {}),
                 compress: !!this._deflate,
                 secure: !!this.secureConnection,
                 cid: this.id
@@ -691,6 +779,19 @@ class ImapFlow extends EventEmitter {
             return;
         }
 
+        // Classify before the first await. Every frame of this command - the command line and
+        // any continuation write that follows it - belongs to it until the next send(), because
+        // trySend() keeps one command in flight at a time. Reading currentRequest inside write()
+        // instead would be racy: rejectCurrentRequest() can clear it while the two compiler
+        // awaits below are pending, and the credential frame would then be logged in the clear.
+        // Uppercased because the wire protocol is case-insensitive and exec() passes the
+        // caller's spelling through unchanged. The command list covers the mechanisms whose
+        // secret arrives in a continuation frame, which carries no attributes of its own; the
+        // `sensitive` marker catches anything that instead puts a secret on the command line,
+        // so marking an attribute is enough to keep a new command out of the raw log too.
+        this.rawSensitiveCommand =
+            RAW_SENSITIVE_COMMANDS.has(typeof data.command === 'string' ? data.command.toUpperCase() : '') || hasSensitiveAttribute(data.attributes);
+
         // Compile with asArray=true: splits output into parts for literal handling.
         // First part is the command text up to the first literal, remaining parts
         // are stored in this.commandParts and sent after server "+" continuations.
@@ -788,7 +889,7 @@ class ImapFlow extends EventEmitter {
             // trySend() settles dispatch failures itself, by rejecting the affected
             // command through requestTagMap; this catch exists only so a throw from the
             // dispatch machinery itself can never surface as a floating rejection.
-            this.trySend().catch(err => this.log.warn({ err, cid: this.id }));
+            this.trySend().catch(err => logConnectionError(this, 'Failed to dispatch command', err));
         });
 
         // Prevent unhandled promise rejection if close() rejects this request
@@ -799,15 +900,14 @@ class ImapFlow extends EventEmitter {
         return promise;
     }
 
-    // Resolves the handler for an untagged server response. IMAP untagged responses
-    // come in two forms:
+    // Resolves an untagged server response to the keyword it is dispatched on. IMAP untagged
+    // responses come in two forms:
     //   * CAPABILITY ...       (keyword as command)
     //   * 42 FETCH (...)       (numeric prefix + keyword)
-    // For numeric-prefixed responses, we extract the keyword (FETCH, EXISTS, EXPUNGE, etc.)
-    // and look up the handler by that keyword instead.
-    // Handler priority: command-specific handlers (registered per exec() call) take
-    // precedence over global handlers (registered on the connection).
-    getUntaggedHandler(command, attributes) {
+    // For numeric-prefixed responses the keyword sits in the first attribute, because `command`
+    // holds the sequence number. Also used for logging, so a failure reports FETCH rather than
+    // the message number that happened to precede it.
+    normalizeUntaggedCommand(command, attributes) {
         if (/^[0-9]+$/.test(command)) {
             let type = attributes && attributes.length && typeof attributes[0].value === 'string' ? attributes[0].value.toUpperCase() : false;
             if (type) {
@@ -815,7 +915,13 @@ class ImapFlow extends EventEmitter {
             }
         }
 
-        command = command.toUpperCase().trim();
+        return command.toUpperCase().trim();
+    }
+
+    // Handler priority: command-specific handlers (registered per exec() call) take
+    // precedence over global handlers (registered on the connection).
+    getUntaggedHandler(command, attributes) {
+        command = this.normalizeUntaggedCommand(command, attributes);
         // Check command-specific handler first (registered in exec() options.untagged)
         if (this.currentRequest && this.currentRequest.options && this.currentRequest.options.untagged && this.currentRequest.options.untagged[command]) {
             return this.currentRequest.options.untagged[command];
@@ -993,7 +1099,7 @@ class ImapFlow extends EventEmitter {
         err.parserError = parserError;
         this.rejectCurrentRequest(err);
 
-        this.trySend().catch(sendErr => this.log.warn({ err: sendErr, cid: this.id }));
+        this.trySend().catch(sendErr => logConnectionError(this, 'Failed to dispatch command', sendErr));
     }
 
     /**
@@ -1064,7 +1170,9 @@ class ImapFlow extends EventEmitter {
             try {
                 await this.currentRequest.options.onPlusTag(parsed);
             } catch (err) {
-                this.log.warn({ err, cid: this.id });
+                // The handler ran across an await and may have closed the connection, which
+                // clears currentRequest, so the command name is read defensively
+                this.log.warn({ msg: 'Failed to process continuation response', command: this.currentRequest?.command, err, cid: this.id });
             }
             return true;
         }
@@ -1078,7 +1186,7 @@ class ImapFlow extends EventEmitter {
                 this.write(content);
                 this.log.debug({ src: 'c', msg: `(* ${content.length}B continuation *)`, cid: this.id });
             } catch (err) {
-                this.log.warn({ err, cid: this.id });
+                logConnectionError(this, 'Failed to send literal continuation', err);
             }
             return true;
         }
@@ -1087,12 +1195,13 @@ class ImapFlow extends EventEmitter {
         // section[0] can be a parsed NIL (null), e.g. from a "[NIL]" response code - the
         // dereference must be guarded or one such line tears down the whole connection
         if (section && section.length && section[0] && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
-            let sectionHandler = this.getSectionHandler(section[0].value.toUpperCase().trim());
+            let sectionKey = section[0].value.toUpperCase().trim();
+            let sectionHandler = this.getSectionHandler(sectionKey);
             if (sectionHandler) {
                 try {
                     await sectionHandler(section.slice(1));
                 } catch (err) {
-                    this.log.warn({ err, cid: this.id });
+                    this.log.warn({ msg: 'Failed to process response section', section: sectionKey, err, cid: this.id });
                 }
             }
         }
@@ -1103,7 +1212,14 @@ class ImapFlow extends EventEmitter {
                 try {
                     await untaggedHandler(parsed);
                 } catch (err) {
-                    this.log.warn({ err, cid: this.id });
+                    // Normalized only here: this runs for every untagged response, including
+                    // every FETCH, and the keyword is needed only to describe a failure
+                    this.log.warn({
+                        msg: 'Failed to process untagged response',
+                        command: this.normalizeUntaggedCommand(parsed.command, parsed.attributes),
+                        err,
+                        cid: this.id
+                    });
                     return true;
                 }
             }
@@ -1214,6 +1330,9 @@ class ImapFlow extends EventEmitter {
 
                     if (err.responseStatus === 'NO' && txt.includes('Some of the requested messages no longer exist')) {
                         // Treat as successful response
+                        // Kept at warn: the caller is handed fewer messages than it asked for and
+                        // is told nothing else about it, so this entry is the only record that
+                        // the response was truncated.
                         this.log.warn({ msg: 'Partial FETCH response', cid: this.id, err });
                         await new Promise(resolve => request.resolve({ response: parsed, next: resolve }));
                         break;
@@ -1525,7 +1644,7 @@ class ImapFlow extends EventEmitter {
                 }
                 this.writeSocket.end();
             } catch (err) {
-                this.log.error({ err, info: 'Failed to destroy PassThrough socket', cid: this.id });
+                this.log.error({ err, msg: 'Failed to destroy PassThrough socket', cid: this.id });
                 throw err;
             }
         };
@@ -2031,6 +2150,22 @@ class ImapFlow extends EventEmitter {
         });
     }
 
+    // Reports one expunged message, either through the caller's expungeHandler or as an
+    // 'expunge' event. Shared by the EXPUNGE and VANISHED paths so the two cannot drift.
+    async notifyExpunge(payload) {
+        if (typeof this.options.expungeHandler !== 'function') {
+            this.emit('expunge', payload);
+            return;
+        }
+
+        try {
+            await this.options.expungeHandler(payload);
+        } catch (err) {
+            // The throw comes from the caller's own handler, not from this library
+            this.log.error({ msg: 'Failed to notify expunge event', payload, err, cid: this.id });
+        }
+    }
+
     async untaggedExpunge(untagged) {
         if (!this.mailbox) {
             // mailbox closed, ignore
@@ -2051,15 +2186,7 @@ class ImapFlow extends EventEmitter {
                 vanished: false
             };
 
-            if (typeof this.options.expungeHandler === 'function') {
-                try {
-                    await this.options.expungeHandler(payload);
-                } catch (err) {
-                    this.log.error({ msg: 'Failed to notify expunge event', payload, error: err, cid: this.id });
-                }
-            } else {
-                this.emit('expunge', payload);
-            }
+            await this.notifyExpunge(payload);
         }
     }
 
@@ -2098,15 +2225,7 @@ class ImapFlow extends EventEmitter {
                 earlier: tags.includes('EARLIER')
             };
 
-            if (typeof this.options.expungeHandler === 'function') {
-                try {
-                    await this.options.expungeHandler(payload);
-                } catch (err) {
-                    this.log.error({ msg: 'Failed to notify expunge event', payload, error: err, cid: this.id });
-                }
-            } else {
-                this.emit('expunge', payload);
-            }
+            await this.notifyExpunge(payload);
         }
     }
 
@@ -2234,7 +2353,7 @@ class ImapFlow extends EventEmitter {
             if (this.state !== this.states.SELECTED || this.connectionBusy()) {
                 return;
             }
-            this.idle().catch(err => this.log.warn({ err, cid: this.id }));
+            this.idle().catch(err => logConnectionError(this, 'Auto-IDLE failed', err));
         }, this.autoIdleDelay);
         unrefTimer(this.idleStartTimer);
     }
@@ -2295,16 +2414,21 @@ class ImapFlow extends EventEmitter {
                     throw new Error('Failed to setup proxy connection');
                 }
             } catch (err) {
+                // Logged here rather than relying on proxy-connection.js, which only reports
+                // failures from inside the two connect helpers. An unsupported scheme, a proxy URL
+                // that will not parse and a deadline that expired before the connect started all
+                // reject before any logging happens there, so this is the one place that sees
+                // every way proxy setup can fail.
+                this.log.error({ msg: 'Failed to setup proxy connection', err, cid: this.id });
+
                 if (err.code === 'CONNECT_TIMEOUT') {
                     // The shared deadline expired during proxy setup. Report it as the documented
                     // connection timeout rather than as a generic proxy failure.
-                    this.log.error({ err, cid: this.id });
                     throw err;
                 }
                 let error = new Error('Failed to setup proxy connection');
                 error.code = err.code || 'ProxyError';
                 error._err = err;
-                this.log.error({ error, cid: this.id });
                 throw error;
             }
         }
@@ -2513,7 +2637,9 @@ class ImapFlow extends EventEmitter {
             }
 
             if (typeof this.preCheck === 'function') {
-                this.preCheck().catch(err => this.log.warn({ err, cid: this.id }));
+                // Runs while the connection is being torn down, so the rejection this sees is
+                // almost always the NoConnection close() is about to raise itself.
+                this.preCheck().catch(err => logConnectionError(this, 'Failed to break IDLE while closing', err));
             }
 
             // Session-only public state must not survive the connection it describes: callers read
@@ -2606,7 +2732,7 @@ class ImapFlow extends EventEmitter {
                     this._inflate.destroy();
                     this._inflate = null;
                 } catch (err) {
-                    this.log.error({ err, info: 'Failed to destroy inflate stream', cid: this.id });
+                    this.log.error({ err, msg: 'Failed to destroy inflate stream', cid: this.id });
                 }
             }
 
@@ -2616,7 +2742,7 @@ class ImapFlow extends EventEmitter {
                     this._deflate.destroy();
                     this._deflate = null;
                 } catch (err) {
-                    this.log.error({ err, info: 'Failed to destroy deflate stream', cid: this.id });
+                    this.log.error({ err, msg: 'Failed to destroy deflate stream', cid: this.id });
                 }
             }
 
@@ -2634,7 +2760,7 @@ class ImapFlow extends EventEmitter {
                         this.streamer.destroy();
                     }
                 } catch (err) {
-                    this.log.error({ err, info: 'Failed to cleanup streamer', cid: this.id });
+                    this.log.error({ err, msg: 'Failed to cleanup streamer', cid: this.id });
                 }
             }
 
@@ -2687,7 +2813,7 @@ class ImapFlow extends EventEmitter {
             this._socketEnd = null;
             this._socketTimeout = null;
 
-            this.log.trace({
+            this.log.debug({
                 msg: 'Connection closed',
                 cid: this.id,
                 ...(this._unknownTagCount ? { unknownTagCount: this._unknownTagCount } : {})
@@ -2703,7 +2829,7 @@ class ImapFlow extends EventEmitter {
             this.emit('close');
         } catch (ex) {
             // close failed
-            this.log.error(ex);
+            this.log.error({ err: ex, cid: this.id });
         }
     }
 
@@ -4637,7 +4763,19 @@ class ImapFlow extends EventEmitter {
                         // we are checking to make sure the level is supported.
                         // if it isn't supported but the level is error or fatal, log to console anyway.
                         if (level === 'fatal' || level === 'error') {
-                            console.log(JSON.stringify(...args));
+                            let entry = args[0];
+                            try {
+                                if (entry && typeof entry === 'object' && entry.err) {
+                                    entry = Object.assign({}, entry, { err: flattenLoggedError(entry.err) });
+                                }
+                                console.error(JSON.stringify(entry));
+                            } catch {
+                                // Serializing failed (a circular structure, a BigInt, a throwing
+                                // getter). This fallback exists so an error is never lost, so hand
+                                // the entry to console.error itself - it inspects rather than
+                                // serializes, and handles all three - instead of dropping it.
+                                console.error(entry);
+                            }
                         }
                     } else {
                         mainLogger[level](...args);
@@ -4645,18 +4783,21 @@ class ImapFlow extends EventEmitter {
                 }
 
                 if (this.emitLogs && args && args[0] && typeof args[0] === 'object') {
-                    let logEntry = Object.assign({ level, t: Date.now(), cid: this.id, lo: ++this.lo }, args[0]);
-                    if (logEntry.err && typeof logEntry.err === 'object') {
-                        let err = logEntry.err;
-                        logEntry.err = {
-                            stack: err.stack
-                        };
-                        // enumerable error fields
-                        Object.keys(err).forEach(key => {
-                            logEntry.err[key] = err[key];
-                        });
+                    // Guarded for the same reason as the console fallback above: a log call must
+                    // never throw. Most of these run inside catch blocks in the protocol
+                    // machinery, where a throw would escape the handler that was recovering from
+                    // something else and strand the connection. A throwing property getter on the
+                    // logged error and a throwing 'log' listener both end up here.
+                    try {
+                        let logEntry = Object.assign({ level, t: Date.now(), cid: this.id, lo: ++this.lo }, args[0]);
+                        if (logEntry.err) {
+                            logEntry.err = flattenLoggedError(logEntry.err);
+                        }
+                        this.emit('log', logEntry);
+                    } catch {
+                        // Nothing to do with it: reporting the failure would re-enter this
+                        // same path
                     }
-                    this.emit('log', logEntry);
                 }
             };
         }

package/lib/proxy-connection.js

@@ -53,11 +53,13 @@ const decodeUserInfo = value => {
 };
 
 // The socks client attaches its full options object - proxy password included - to the errors it
-// throws. Any logger that serializes error properties would then write that password out in clear
-// text, so the credentials are dropped before the error is logged or handed to the caller.
+// throws, and Node's URL errors carry the rejected string in `input`. Any logger that serializes
+// error properties would then write that password out in clear text, so the credentials are
+// dropped before the error is logged or handed to the caller.
 const stripProxyCredentials = err => {
-    if (err && typeof err === 'object' && err.options) {
+    if (err && typeof err === 'object') {
         delete err.options;
+        delete err.input;
     }
     return err;
 };
@@ -402,7 +404,15 @@ const proxyConnection = async (logger, connectionUrl, host, port, options) => {
     let deadline = options.deadline || new ConnectionDeadline(options.connectionTimeout);
     deadline.check();
 
-    let proxyUrl = new URL(connectionUrl);
+    let proxyUrl;
+    try {
+        proxyUrl = new URL(connectionUrl);
+    } catch (err) {
+        // new URL() attaches the string it rejected to err.input, which here is the full proxy
+        // endpoint including its password. Any logger that serializes error properties would
+        // write that out in clear text, so the cause is reported without carrying the value.
+        throw proxyError('Invalid proxy URL', err.code || 'ERR_INVALID_URL');
+    }
     let protocol = proxyUrl.protocol.replace(/:$/, '').toLowerCase();
 
     // ImapFlow performs no DNS lookup of its own for the proxy endpoint: net, tls and the SOCKS

package/lib/tools.js

@@ -11,6 +11,9 @@ const iconv = require('iconv-lite');
 
 const FLAG_COLORS = ['red', 'orange', 'yellow', 'green', 'blue', 'purple', 'grey'];
 
+// Error codes that only mean the connection is no longer usable. See logConnectionError().
+const CONNECTION_GONE_CODES = new Set(['NoConnection', 'EConnectionClosed', 'StateLogout']);
+
 // Upper bound for expanding server-supplied sequence ranges (see expandRange). 2^24
 // entries in total is far beyond any legitimate mailbox while keeping the worst-case
 // expansion of a hostile range set bounded.
@@ -84,6 +87,32 @@ const tools = {
         return timer;
     },
 
+    /**
+     * Logs a failure from background connection work at the level its cause deserves.
+     *
+     * Background work (IDLE sessions, polling timers, auto-IDLE) is interrupted by every normal
+     * disconnect, so a rejection carrying one of the CONNECTION_GONE_CODES is expected rather
+     * than notable and goes to debug. The three codes describe the same situation reached
+     * through different guards: write() throws NoConnection or StateLogout, exec() rejects
+     * EConnectionClosed for the window where the socket is destroyed but close() has not run
+     * yet, and close() rejects pending requests with NoConnection.
+     *
+     * A connection error carrying `reason` is the exception. That field holds the server's
+     * untagged BYE text ("Too many simultaneous connections", "Account is disabled"), which
+     * serverBye() only records - this log call is the one place it becomes visible, and it is
+     * usually the answer to why a client is reconnecting in a loop. Those stay at warn.
+     *
+     * Shared so the classification cannot drift between the call sites that make this decision.
+     *
+     * @param {Object} connection - IMAP connection instance
+     * @param {String} msg - What failed, so the entries stay distinguishable in the log
+     * @param {Error} err - The error to log
+     */
+    logConnectionError(connection, msg, err) {
+        let routine = !!err && CONNECTION_GONE_CODES.has(err.code) && !err.reason;
+        connection.log[routine ? 'debug' : 'warn']({ msg, err, cid: connection.id });
+    },
+
     /**
      * Checks whether IMAP4rev2 semantics are active for the connection: either the
      * client enabled IMAP4rev2 explicitly, or the server is rev2-only (advertises

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.7.0",
+    "version": "1.7.1",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",
@@ -30,9 +30,9 @@
     "homepage": "https://imapflow.com/",
     "devDependencies": {
         "@eslint/js": "10.0.1",
-        "@types/node": "26.1.2",
+        "@types/node": "26.2.0",
         "c8": "12.0.0",
-        "eslint": "10.8.0",
+        "eslint": "10.8.1",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "10.1.8",
         "grunt": "1.6.3",

package/test/imap-flow-internals-test.js

@@ -170,27 +170,79 @@ module.exports['Internals: write returns false for non-string non-buffer'] = tes
     test.done();
 };
 
-module.exports['Internals: write logs raw data when logRaw enabled'] = test => {
+// A writable client whose raw traffic log is captured, for the two logRaw branches
+const makeRawLogClient = rawSensitiveCommand => {
     let logs = [];
-    let client = makeClient({ logRaw: true });
-    client.log = {
-        trace: o => logs.push(o),
-        debug: () => {},
-        warn: () => {},
-        error: () => {},
-        info: () => {}
-    };
     let written = [];
+    let client = makeClient({ logRaw: true });
+    client.log = { trace: o => logs.push(o), debug: () => {}, warn: () => {}, error: () => {}, info: () => {} };
     client.socket = { destroyed: false };
     client.writeSocket = { destroyed: false, write: c => written.push(c) };
-    client.state = client.states.AUTHENTICATED;
-    client.commandParts = [];
+    client.rawSensitiveCommand = rawSensitiveCommand;
+    return { client, logs, written };
+};
+
+module.exports['Internals: write logs raw data when logRaw enabled'] = test => {
+    let { client, logs, written } = makeRawLogClient(false);
     client.write('A NOOP');
-    test.ok(logs.some(l => l.src === 'c' && l.msg === 'write to socket'));
+    let entry = logs.find(l => l.src === 'c' && l.msg === 'write to socket');
+    test.ok(entry);
+    test.equal(Buffer.from(entry.data, 'base64').toString(), 'A NOOP\r\n');
+    test.ok(!entry.hidden);
     test.equal(written.length, 1);
     test.done();
 };
 
+module.exports['Internals: write withholds raw data for a credential-bearing command'] = test => {
+    // send() sets this for LOGIN/AUTHENTICATE before the first frame reaches the socket
+    let { client, logs, written } = makeRawLogClient(true);
+    client.write('A1 LOGIN "user" "hunter2"');
+    let entry = logs.find(l => l.src === 'c' && l.msg === 'write to socket');
+    test.ok(entry);
+    test.ok(entry.hidden);
+    // The placeholder is fixed width, so the entry cannot disclose the password length
+    test.equal(Buffer.from(entry.data, 'base64').toString(), '(* value hidden *)\r\n');
+    // The frame itself is still written to the socket unchanged
+    test.equal(written[0].toString(), 'A1 LOGIN "user" "hunter2"\r\n');
+    test.done();
+};
+
+module.exports['Internals: send marks credential-bearing commands for the raw log'] = async test => {
+    let client = makeClient();
+    let written = [];
+    client.socket = { destroyed: false };
+    client.writeSocket = { destroyed: false, write: c => written.push(c) };
+
+    // Lower case on purpose: the wire protocol is case-insensitive and exec() passes the
+    // caller's spelling through unchanged, so the classification must normalize it
+    await client.send({
+        tag: 'A1',
+        command: 'login',
+        attributes: [
+            { type: 'STRING', value: 'user' },
+            { type: 'STRING', value: 'hunter2', sensitive: true }
+        ],
+        options: {}
+    });
+    test.equal(client.rawSensitiveCommand, true);
+
+    await client.send({ tag: 'A2', command: 'NOOP', attributes: [], options: {} });
+    test.equal(client.rawSensitiveCommand, false);
+
+    // A command outside the list still masks if it marks an attribute sensitive, so the
+    // declarative marker alone is enough to keep a new command out of the raw log. Nested
+    // because the command compiler honors the marker at any depth.
+    await client.send({
+        tag: 'A3',
+        command: 'SETMETADATA',
+        attributes: [{ type: 'ATOM', value: 'INBOX' }, [{ type: 'STRING', value: 'token', sensitive: true }]],
+        options: {}
+    });
+    test.equal(client.rawSensitiveCommand, true);
+
+    test.done();
+};
+
 module.exports['Internals: write appends CRLF only on final part'] = test => {
     let client = makeClient();
     let written = [];
@@ -304,7 +356,7 @@ module.exports['Internals: getLogger uses provided logger object'] = test => {
 };
 
 module.exports['Internals: getLogger falls back to console for missing fatal/error level'] = test => {
-    // Logger object missing the 'error' method -> falls through to console.log
+    // Logger object missing the 'error' method -> falls through to console.error
     let partial = {
         trace() {},
         debug() {},
@@ -313,15 +365,99 @@ module.exports['Internals: getLogger falls back to console for missing fatal/err
         // no error, no fatal
     };
     let client = makeClient({ logger: partial });
-    let origConsoleLog = console.log;
+    let origConsoleError = console.error;
     let logged = [];
-    console.log = (...args) => logged.push(args);
+    console.error = (...args) => logged.push(args);
     try {
-        client.log.error({ msg: 'boom' });
+        let err = new Error('boom failure');
+        err.code = 'XBOOM';
+        // The answer is often one level down: this library attaches the underlying failure
+        // as an enumerable `_err`
+        err._err = Object.assign(new Error('inner failure'), { code: 'ECONNREFUSED' });
+        client.log.error({ msg: 'boom', err });
+        // A circular structure must not throw out of the log call, and must not be dropped
+        let circular = { msg: 'loop' };
+        circular.self = circular;
+        client.log.error(circular);
     } finally {
-        console.log = origConsoleLog;
+        console.error = origConsoleError;
     }
-    test.ok(logged.length >= 1);
+    test.equal(logged.length, 2);
+    // The Error was flattened, so message, stack and enumerable fields survive stringify
+    let entry = JSON.parse(logged[0][0]);
+    test.equal(entry.msg, 'boom');
+    test.equal(entry.err.message, 'boom failure');
+    test.equal(entry.err.code, 'XBOOM');
+    test.ok(entry.err.stack);
+    test.equal(entry.err._err.message, 'inner failure');
+    test.equal(entry.err._err.code, 'ECONNREFUSED');
+    // Unserializable entries still reach console.error, just not as JSON
+    test.equal(logged[1][0].msg, 'loop');
+    test.done();
+};
+
+module.exports['Internals: getLogger keeps cause and AggregateError members'] = test => {
+    let client = makeClient({ emitLogs: true });
+    let entries = [];
+    client.on('log', entry => entries.push(entry));
+
+    let inner = Object.assign(new Error('inner failure'), { code: 'ECONNREFUSED' });
+    client.log.error({ msg: 'wrapped', err: new Error('outer failure', { cause: inner }) });
+    // Node reports a multi-address connect failure as an AggregateError
+    client.log.error({ msg: 'aggregate', err: new AggregateError([inner], 'all attempts failed') });
+
+    test.equal(entries[0].err.cause.message, 'inner failure');
+    test.equal(entries[0].err.cause.code, 'ECONNREFUSED');
+    test.equal(entries[1].err.errors.length, 1);
+    test.equal(entries[1].err.errors[0].message, 'inner failure');
+    test.done();
+};
+
+module.exports['Internals: getLogger bounds a looping and a deep error chain'] = test => {
+    let client = makeClient({ emitLogs: true });
+    let entries = [];
+    client.on('log', entry => entries.push(entry));
+
+    // A chain that loops back must terminate rather than recurse forever
+    let looping = new Error('looping failure');
+    looping._err = looping;
+    client.log.error({ msg: 'loop', err: looping });
+    test.equal(entries[0].err.message, 'looping failure');
+    test.equal(entries[0].err._err, 'looping failure');
+
+    // A chain longer than the depth cap is truncated rather than walked to the end
+    let deep = new Error('level 0');
+    for (let i = 1; i <= 6; i++) {
+        deep = Object.assign(new Error(`level ${i}`), { _err: deep });
+    }
+    client.log.error({ msg: 'deep', err: deep });
+    test.equal(entries[1].err._err._err._err.message, 'level 3');
+    // Past the cap the chain collapses to messages instead of being walked to the end
+    test.equal(entries[1].err._err._err._err._err, 'level 2');
+
+    test.done();
+};
+
+module.exports['Internals: getLogger never throws out of a log call'] = test => {
+    let client = makeClient({ emitLogs: true });
+    let entries = [];
+    client.on('log', entry => entries.push(entry));
+
+    // A throwing property getter on the logged error must not escape
+    let hostile = {
+        get message() {
+            throw new Error('getter blew up');
+        },
+        stack: 'x'
+    };
+    test.doesNotThrow(() => client.log.warn({ msg: 'hostile', err: hostile }));
+
+    // Neither must a throwing 'log' listener
+    client.on('log', () => {
+        throw new Error('listener blew up');
+    });
+    test.doesNotThrow(() => client.log.warn({ msg: 'still fine' }));
+
     test.done();
 };