imapkit 5.1.0 → 5.2.0

package/dist/cjs/control.js

@@ -629,7 +629,7 @@ class Control {
             }
             else {
                 this.server.closeListeners(false);
-                this.server.server.close(done);
+                this.server.closeImapListeners(done);
             }
         });
     }

package/dist/cjs/rest.js

@@ -69,8 +69,10 @@ function decodeBody(value, encoding) {
     }
     return encoding === 'base64' && typeof value === 'string' ? Buffer.from(value, 'base64') : value;
 }
-// the server events that GET /v1/events streams
-const EVENT_TYPES = ['session', 'command', 'mailbox', 'expunge', 'flags', 'acl', 'script', 'reset'];
+// the server events that GET /v1/events streams by default
+const EVENT_TYPES = ['session', 'command', 'mailbox', 'append', 'expunge', 'flags', 'acl', 'script', 'reset'];
+// event types that are streamed only when ?types= asks for them, the protocol trace of every session is a lot of data
+const OPT_IN_EVENT_TYPES = ['trace'];
 const sessionNumber = (origin) => (origin ? origin.sessionNumber : null);
 /**
  * Turns the arguments of a server event into JSON data: mailboxes become paths, messages UIDs, sessions numbers
@@ -85,8 +87,13 @@ function eventData(type, args) {
             const { type: change, path, oldPath, origin } = args[0];
             return { type: change, path, oldPath, origin: sessionNumber(origin) };
         }
+        case 'append':
         case 'expunge':
             return { path: args[0].path, uids: args[1].map(message => message.uid), origin: sessionNumber(args[2]) };
+        case 'trace': {
+            const { session, direction, data } = args[0];
+            return { session, direction, data: Buffer.from(data).toString('base64'), encoding: 'base64' };
+        }
         case 'flags':
             return {
                 path: args[0].path,
@@ -161,13 +168,16 @@ function getRoutes(server, streams = new Set()) {
         {
             method: 'GET',
             path: '/v1/events',
-            summary: 'Server events as Server-Sent Events (?types=session,command to choose: ' + EVENT_TYPES.join(', ') + ')',
+            summary: 'Server events as Server-Sent Events (?types=session,command to choose: ' +
+                EVENT_TYPES.concat(OPT_IN_EVENT_TYPES).join(', ') +
+                ', trace only when asked for)',
             handler: ({ query }) => {
                 const wanted = query.get('types');
                 const types = wanted === null ? EVENT_TYPES : wanted.split(',');
-                const unknown = types.filter(type => EVENT_TYPES.indexOf(type) < 0);
+                const known = EVENT_TYPES.concat(OPT_IN_EVENT_TYPES);
+                const unknown = types.filter(type => known.indexOf(type) < 0);
                 if (unknown.length) {
-                    throw (0, store_operations_js_1.storeError)('Unknown event type ' + unknown.join(', ') + ', expected ' + EVENT_TYPES.join(', '), 'INVALID');
+                    throw (0, store_operations_js_1.storeError)('Unknown event type ' + unknown.join(', ') + ', expected ' + known.join(', '), 'INVALID');
                 }
                 return { stream: eventStream(server, types, streams) };
             }

package/dist/cjs/server.d.ts

@@ -83,6 +83,8 @@ declare class IMAPServer extends Stream {
     sessionCounter: number;
     /** the control API, see src/control.ts */
     control: Control;
+    /** the implicit TLS listener that `start()` runs for the `tls` option */
+    tlsServer: tls.Server | null;
     /** the SMTP server that `start()` runs for the `smtp` option */
     smtpServer: SMTPListener | null;
     /** the HTTP server of the REST API that `start()` runs for the `rest` option */
@@ -107,6 +109,14 @@ declare class IMAPServer extends Stream {
      * @return {Promise<Number>} resolves with the port the server listens on
      */
     start(port?: number, host?: string): Promise<number>;
+    /**
+     * Starts the implicit TLS listener of the `tls` option. Its sessions are sessions of this server like the ones of
+     * the main listener, they share the storage and count as encrypted
+     *
+     * @param {String} [defaultHost] Address to listen on when the `tls` option has no host
+     * @return {Promise<Number>} resolves with the port of the TLS listener
+     */
+    startTlsListener(defaultHost?: string): Promise<number>;
     /**
      * Starts the REST API of the `rest` option, see src/rest.ts
      *
@@ -140,6 +150,13 @@ declare class IMAPServer extends Stream {
     listen(port: number, hostname: string, listeningListener?: () => void): void;
     listen(options: net.ListenOptions, listeningListener?: () => void): void;
     close(callback?: (err?: Error) => void): void;
+    /**
+     * Stops accepting IMAP connections, on the main listener and on the TLS listener of the `tls` option
+     *
+     * @param {Function} [callback] Called once both listeners are closed, which is after their last connection is
+     *   gone, with the first error
+     */
+    closeImapListeners(callback?: (err?: Error) => void): void;
     /**
      * Stops the SMTP and REST listeners of `start()`
      *
@@ -677,6 +694,13 @@ declare class IMAPConnection {
      * @param {Function} [callback] Called once the data was handed to the system (a transport: on the next turn)
      */
     writeLayer(data: Buffer, transport: Transport | null, callback?: () => void): void;
+    /**
+     * Emits the protocol traffic of the session as `trace` events, as the IMAP layer sees it: above TLS and COMPRESS
+     *
+     * @param {String} direction "in" for client input, "out" for server output
+     * @param {Buffer} data The octets
+     */
+    trace(direction: 'in' | 'out', data: Buffer): void;
     /**
      * Sends output through the script rule that handles its event, if there is one
      *

package/dist/cjs/server.js

@@ -242,6 +242,7 @@ class IMAPServer extends node_stream_1.Stream {
         }
         this.systemFlags = [].concat(this.options.systemFlags || ['\\Answered', '\\Flagged', '\\Draft', '\\Deleted', '\\Seen']);
         this.loadStorage();
+        this.tlsServer = null;
         this.smtpServer = null;
         this.restServer = null;
     }
@@ -292,9 +293,25 @@ class IMAPServer extends node_stream_1.Stream {
      */
     async start(port, host) {
         const imapPort = await listenOn(this.server, port, host);
-        await Promise.all([this.options.smtp ? this.startSmtp() : null, this.options.rest ? this.startRest() : null]);
+        await Promise.all([
+            this.options.tls ? this.startTlsListener(host) : null,
+            this.options.smtp ? this.startSmtp() : null,
+            this.options.rest ? this.startRest() : null
+        ]);
         return imapPort;
     }
+    /**
+     * Starts the implicit TLS listener of the `tls` option. Its sessions are sessions of this server like the ones of
+     * the main listener, they share the storage and count as encrypted
+     *
+     * @param {String} [defaultHost] Address to listen on when the `tls` option has no host
+     * @return {Promise<Number>} resolves with the port of the TLS listener
+     */
+    startTlsListener(defaultHost) {
+        const { port, host } = this.options.tls || {};
+        this.tlsServer = node_tls_1.default.createServer(this.getCredentials(), this.createClient.bind(this));
+        return listenOn(this.tlsServer, port, host || defaultHost);
+    }
     /**
      * Starts the REST API of the `rest` option, see src/rest.ts
      *
@@ -344,7 +361,7 @@ class IMAPServer extends node_stream_1.Stream {
     }
     close(callback) {
         this.closeListeners(true);
-        this.server.close(callback);
+        this.closeImapListeners(callback);
         // close() only completes once all connections are gone
         this.connections.forEach((connection) => {
             if (connection.socket) {
@@ -352,6 +369,24 @@ class IMAPServer extends node_stream_1.Stream {
             }
         });
     }
+    /**
+     * Stops accepting IMAP connections, on the main listener and on the TLS listener of the `tls` option
+     *
+     * @param {Function} [callback] Called once both listeners are closed, which is after their last connection is
+     *   gone, with the first error
+     */
+    closeImapListeners(callback) {
+        const listeners = this.tlsServer ? [this.server, this.tlsServer] : [this.server];
+        this.tlsServer = null;
+        let pending = listeners.length;
+        let error;
+        listeners.forEach(listener => listener.close(err => {
+            error = error || err;
+            if (--pending === 0) {
+                callback?.(error);
+            }
+        }));
+    }
     /**
      * Stops the SMTP and REST listeners of `start()`
      *
@@ -1152,6 +1187,8 @@ class IMAPServer extends node_stream_1.Stream {
                 break;
             }
         }
+        // like expunge, before the sessions are told: APPEND, COPY, MOVE, REPLACE, SMTP and the control API all add here
+        this.emit('append', mailbox, [message], this.activeConnection);
         this.notify({
             tag: '*',
             attributes: [
@@ -1596,6 +1633,7 @@ class IMAPConnection {
      * @param {Function} [callback] Called once the data was handed to the system (a transport: on the next turn)
      */
     writeLayer(data, transport, callback) {
+        this.trace('out', data);
         if (transport) {
             transport.write(data);
             if (callback) {
@@ -1606,6 +1644,17 @@ class IMAPConnection {
             this.writeRaw(data, callback);
         }
     }
+    /**
+     * Emits the protocol traffic of the session as `trace` events, as the IMAP layer sees it: above TLS and COMPRESS
+     *
+     * @param {String} direction "in" for client input, "out" for server output
+     * @param {Buffer} data The octets
+     */
+    trace(direction, data) {
+        if (this.server.listenerCount('trace')) {
+            this.server.emit('trace', { session: this.sessionNumber, direction, data });
+        }
+    }
     /**
      * Sends output through the script rule that handles its event, if there is one
      *
@@ -1916,6 +1965,9 @@ class IMAPConnection {
         if (this._resetting) {
             return;
         }
+        if (chunk && chunk.length) {
+            this.trace('in', chunk);
+        }
         // everything in one read arrived before anything this read causes to be sent
         this._readCount = (this._readCount || 0) + 1;
         str = (chunk || '').toString('binary');

package/dist/cjs/types.d.ts

@@ -228,6 +228,12 @@ export interface IMAPServerOptions {
     plugins?: (string | Plugin)[] | string | Plugin | undefined;
     users?: Record<string, UserData> | undefined;
     secureConnection?: boolean | undefined;
+    /** starts a second IMAP listener for implicit TLS (IMAPS) with `server.start()`, its sessions share the storage
+     * with the main listener. Without a host it listens on the host given to `start()` */
+    tls?: {
+        port?: number | undefined;
+        host?: string | undefined;
+    } | undefined;
     /** starts an SMTP server with `server.start()` that appends every received message to INBOX, needs the optional
      * smtp-server package */
     smtp?: {

package/dist/esm/control.js

@@ -622,7 +622,7 @@ class Control {
             }
             else {
                 this.server.closeListeners(false);
-                this.server.server.close(done);
+                this.server.closeImapListeners(done);
             }
         });
     }

package/dist/esm/rest.js

@@ -60,8 +60,10 @@ function decodeBody(value, encoding) {
     }
     return encoding === 'base64' && typeof value === 'string' ? Buffer.from(value, 'base64') : value;
 }
-// the server events that GET /v1/events streams
-const EVENT_TYPES = ['session', 'command', 'mailbox', 'expunge', 'flags', 'acl', 'script', 'reset'];
+// the server events that GET /v1/events streams by default
+const EVENT_TYPES = ['session', 'command', 'mailbox', 'append', 'expunge', 'flags', 'acl', 'script', 'reset'];
+// event types that are streamed only when ?types= asks for them, the protocol trace of every session is a lot of data
+const OPT_IN_EVENT_TYPES = ['trace'];
 const sessionNumber = (origin) => (origin ? origin.sessionNumber : null);
 /**
  * Turns the arguments of a server event into JSON data: mailboxes become paths, messages UIDs, sessions numbers
@@ -76,8 +78,13 @@ function eventData(type, args) {
             const { type: change, path, oldPath, origin } = args[0];
             return { type: change, path, oldPath, origin: sessionNumber(origin) };
         }
+        case 'append':
         case 'expunge':
             return { path: args[0].path, uids: args[1].map(message => message.uid), origin: sessionNumber(args[2]) };
+        case 'trace': {
+            const { session, direction, data } = args[0];
+            return { session, direction, data: Buffer.from(data).toString('base64'), encoding: 'base64' };
+        }
         case 'flags':
             return {
                 path: args[0].path,
@@ -152,13 +159,16 @@ function getRoutes(server, streams = new Set()) {
         {
             method: 'GET',
             path: '/v1/events',
-            summary: 'Server events as Server-Sent Events (?types=session,command to choose: ' + EVENT_TYPES.join(', ') + ')',
+            summary: 'Server events as Server-Sent Events (?types=session,command to choose: ' +
+                EVENT_TYPES.concat(OPT_IN_EVENT_TYPES).join(', ') +
+                ', trace only when asked for)',
             handler: ({ query }) => {
                 const wanted = query.get('types');
                 const types = wanted === null ? EVENT_TYPES : wanted.split(',');
-                const unknown = types.filter(type => EVENT_TYPES.indexOf(type) < 0);
+                const known = EVENT_TYPES.concat(OPT_IN_EVENT_TYPES);
+                const unknown = types.filter(type => known.indexOf(type) < 0);
                 if (unknown.length) {
-                    throw storeError('Unknown event type ' + unknown.join(', ') + ', expected ' + EVENT_TYPES.join(', '), 'INVALID');
+                    throw storeError('Unknown event type ' + unknown.join(', ') + ', expected ' + known.join(', '), 'INVALID');
                 }
                 return { stream: eventStream(server, types, streams) };
             }

package/dist/esm/server.d.ts

@@ -83,6 +83,8 @@ declare class IMAPServer extends Stream {
     sessionCounter: number;
     /** the control API, see src/control.ts */
     control: Control;
+    /** the implicit TLS listener that `start()` runs for the `tls` option */
+    tlsServer: tls.Server | null;
     /** the SMTP server that `start()` runs for the `smtp` option */
     smtpServer: SMTPListener | null;
     /** the HTTP server of the REST API that `start()` runs for the `rest` option */
@@ -107,6 +109,14 @@ declare class IMAPServer extends Stream {
      * @return {Promise<Number>} resolves with the port the server listens on
      */
     start(port?: number, host?: string): Promise<number>;
+    /**
+     * Starts the implicit TLS listener of the `tls` option. Its sessions are sessions of this server like the ones of
+     * the main listener, they share the storage and count as encrypted
+     *
+     * @param {String} [defaultHost] Address to listen on when the `tls` option has no host
+     * @return {Promise<Number>} resolves with the port of the TLS listener
+     */
+    startTlsListener(defaultHost?: string): Promise<number>;
     /**
      * Starts the REST API of the `rest` option, see src/rest.ts
      *
@@ -140,6 +150,13 @@ declare class IMAPServer extends Stream {
     listen(port: number, hostname: string, listeningListener?: () => void): void;
     listen(options: net.ListenOptions, listeningListener?: () => void): void;
     close(callback?: (err?: Error) => void): void;
+    /**
+     * Stops accepting IMAP connections, on the main listener and on the TLS listener of the `tls` option
+     *
+     * @param {Function} [callback] Called once both listeners are closed, which is after their last connection is
+     *   gone, with the first error
+     */
+    closeImapListeners(callback?: (err?: Error) => void): void;
     /**
      * Stops the SMTP and REST listeners of `start()`
      *
@@ -677,6 +694,13 @@ declare class IMAPConnection {
      * @param {Function} [callback] Called once the data was handed to the system (a transport: on the next turn)
      */
     writeLayer(data: Buffer, transport: Transport | null, callback?: () => void): void;
+    /**
+     * Emits the protocol traffic of the session as `trace` events, as the IMAP layer sees it: above TLS and COMPRESS
+     *
+     * @param {String} direction "in" for client input, "out" for server output
+     * @param {Buffer} data The octets
+     */
+    trace(direction: 'in' | 'out', data: Buffer): void;
     /**
      * Sends output through the script rule that handles its event, if there is one
      *

package/dist/esm/server.js

@@ -201,6 +201,7 @@ class IMAPServer extends Stream {
         }
         this.systemFlags = [].concat(this.options.systemFlags || ['\\Answered', '\\Flagged', '\\Draft', '\\Deleted', '\\Seen']);
         this.loadStorage();
+        this.tlsServer = null;
         this.smtpServer = null;
         this.restServer = null;
     }
@@ -251,9 +252,25 @@ class IMAPServer extends Stream {
      */
     async start(port, host) {
         const imapPort = await listenOn(this.server, port, host);
-        await Promise.all([this.options.smtp ? this.startSmtp() : null, this.options.rest ? this.startRest() : null]);
+        await Promise.all([
+            this.options.tls ? this.startTlsListener(host) : null,
+            this.options.smtp ? this.startSmtp() : null,
+            this.options.rest ? this.startRest() : null
+        ]);
         return imapPort;
     }
+    /**
+     * Starts the implicit TLS listener of the `tls` option. Its sessions are sessions of this server like the ones of
+     * the main listener, they share the storage and count as encrypted
+     *
+     * @param {String} [defaultHost] Address to listen on when the `tls` option has no host
+     * @return {Promise<Number>} resolves with the port of the TLS listener
+     */
+    startTlsListener(defaultHost) {
+        const { port, host } = this.options.tls || {};
+        this.tlsServer = tls.createServer(this.getCredentials(), this.createClient.bind(this));
+        return listenOn(this.tlsServer, port, host || defaultHost);
+    }
     /**
      * Starts the REST API of the `rest` option, see src/rest.ts
      *
@@ -303,7 +320,7 @@ class IMAPServer extends Stream {
     }
     close(callback) {
         this.closeListeners(true);
-        this.server.close(callback);
+        this.closeImapListeners(callback);
         // close() only completes once all connections are gone
         this.connections.forEach((connection) => {
             if (connection.socket) {
@@ -311,6 +328,24 @@ class IMAPServer extends Stream {
             }
         });
     }
+    /**
+     * Stops accepting IMAP connections, on the main listener and on the TLS listener of the `tls` option
+     *
+     * @param {Function} [callback] Called once both listeners are closed, which is after their last connection is
+     *   gone, with the first error
+     */
+    closeImapListeners(callback) {
+        const listeners = this.tlsServer ? [this.server, this.tlsServer] : [this.server];
+        this.tlsServer = null;
+        let pending = listeners.length;
+        let error;
+        listeners.forEach(listener => listener.close(err => {
+            error = error || err;
+            if (--pending === 0) {
+                callback?.(error);
+            }
+        }));
+    }
     /**
      * Stops the SMTP and REST listeners of `start()`
      *
@@ -1111,6 +1146,8 @@ class IMAPServer extends Stream {
                 break;
             }
         }
+        // like expunge, before the sessions are told: APPEND, COPY, MOVE, REPLACE, SMTP and the control API all add here
+        this.emit('append', mailbox, [message], this.activeConnection);
         this.notify({
             tag: '*',
             attributes: [
@@ -1554,6 +1591,7 @@ class IMAPConnection {
      * @param {Function} [callback] Called once the data was handed to the system (a transport: on the next turn)
      */
     writeLayer(data, transport, callback) {
+        this.trace('out', data);
         if (transport) {
             transport.write(data);
             if (callback) {
@@ -1564,6 +1602,17 @@ class IMAPConnection {
             this.writeRaw(data, callback);
         }
     }
+    /**
+     * Emits the protocol traffic of the session as `trace` events, as the IMAP layer sees it: above TLS and COMPRESS
+     *
+     * @param {String} direction "in" for client input, "out" for server output
+     * @param {Buffer} data The octets
+     */
+    trace(direction, data) {
+        if (this.server.listenerCount('trace')) {
+            this.server.emit('trace', { session: this.sessionNumber, direction, data });
+        }
+    }
     /**
      * Sends output through the script rule that handles its event, if there is one
      *
@@ -1874,6 +1923,9 @@ class IMAPConnection {
         if (this._resetting) {
             return;
         }
+        if (chunk && chunk.length) {
+            this.trace('in', chunk);
+        }
         // everything in one read arrived before anything this read causes to be sent
         this._readCount = (this._readCount || 0) + 1;
         str = (chunk || '').toString('binary');

package/dist/esm/types.d.ts

@@ -228,6 +228,12 @@ export interface IMAPServerOptions {
     plugins?: (string | Plugin)[] | string | Plugin | undefined;
     users?: Record<string, UserData> | undefined;
     secureConnection?: boolean | undefined;
+    /** starts a second IMAP listener for implicit TLS (IMAPS) with `server.start()`, its sessions share the storage
+     * with the main listener. Without a host it listens on the host given to `start()` */
+    tls?: {
+        port?: number | undefined;
+        host?: string | undefined;
+    } | undefined;
     /** starts an SMTP server with `server.start()` that appends every received message to INBOX, needs the optional
      * smtp-server package */
     smtp?: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapkit",
-    "version": "5.1.0",
+    "version": "5.2.0",
     "description": "Scriptable, strictly RFC compliant in-memory IMAP server for testing IMAP clients",
     "type": "module",
     "main": "./dist/cjs/index.js",
@@ -95,16 +95,16 @@
         "@types/smtp-server": "3.5.13",
         "buffer": "6.0.3",
         "esbuild": "0.28.2",
-        "eslint": "10.12.0",
+        "eslint": "10.13.0",
         "eslint-config-prettier": "10.1.8",
         "events": "3.3.0",
         "globals": "17.13.0",
-        "imapflow": "2.2.9",
-        "prettier": "3.9.9",
-        "smtp-server": "3.19.17",
+        "imapflow": "2.5.6",
+        "prettier": "3.9.10",
+        "smtp-server": "3.20.2",
         "tsx": "4.23.15",
         "typescript": "6.0.3",
-        "typescript-eslint": "8.71.1"
+        "typescript-eslint": "8.71.2"
     },
     "engines": {
         "node": ">=20.0.0"