imapkit 5.1.0 → 5.3.0

package/dist/esm/plugins/oauthbearer.js

@@ -3,7 +3,7 @@
  * @help Works with and without SASL-IR [RFC4959]
  * @help Valid login info, same as for XOAUTH2:
  * @help   Username (authzid, optional): testuser
- * @help   Access Token: testtoken
+ * @help   Access Token: testtoken, or a token of the OAuth provider
  */
 const KVSEP = '\x01';
 const utf8 = new TextDecoder('utf-8', { fatal: true });
@@ -89,21 +89,16 @@ export default function oauthbearerPlugin(server) {
             return auth === '' ? 'invalid_token' : 'invalid_request';
         }
         const token = bearer[1];
-        let username = request.authzid;
-        if (username === false) {
-            // without an authzid the token tells who the user is
-            username = Object.keys(server.users).find(name => {
-                const user = server.users[name];
-                return user && user.xoauth2 && user.xoauth2.accessToken === token;
-            });
-        }
-        const user = server.getUser(username);
-        if (!user || !user.xoauth2 || user.xoauth2.accessToken !== token) {
-            return 'invalid_token';
-        }
-        request.username = username;
+        // without an authzid the token tells who the user is
+        const result = server.checkAccessToken(token, request.authzid === false ? undefined : request.authzid);
+        if ('error' in result) {
+            return result.error;
+        }
+        request.username = result.user;
         return false;
     };
+    // RFC 7628 section 3.2.2: with the OAuth provider the error result also says where to get a token and for which scope
+    const errorResult = (status) => server.oauth && server.oauth.issuer ? { status, scope: server.oauth.mailScope, 'openid-configuration': server.oauth.discoveryUrl() } : { status };
     // Decodes a base64 client response, sends BAD and returns false if it is not valid base64
     const decode = (connection, parsed, data, input) => {
         const decoded = connection.decodeSaslResponse(input);
@@ -155,7 +150,7 @@ export default function oauthbearerPlugin(server) {
             attributes: [
                 {
                     type: 'ATOM',
-                    value: Buffer.from(JSON.stringify({ status })).toString('base64')
+                    value: Buffer.from(JSON.stringify(errorResult(status))).toString('base64')
                 }
             ]
         }, 'AUTHENTICATE OAUTHBEARER CHALLENGE', parsed, data);

package/dist/esm/plugins/xoauth2.js

@@ -5,7 +5,7 @@
  * @help SASL-IR enabled and used while Gmail does not
  * @help Valid login info:
  * @help   Username: testuser
- * @help   Access Token: testtoken
+ * @help   Access Token: testtoken, or a token of the OAuth provider
  */
 const utf8 = new TextDecoder('utf-8', { fatal: true });
 export default function xoauth2Plugin(server) {
@@ -91,7 +91,7 @@ export default function xoauth2Plugin(server) {
             }, 'AUTHENTICATE XOAUTH2 FAILED', parsed, data);
             return callback();
         }
-        if (!userData.xoauth2 || userData.xoauth2.accessToken !== accessToken) {
+        if ('error' in server.checkAccessToken(accessToken, user)) {
             connection.send({
                 tag: '+',
                 attributes: [
@@ -100,7 +100,8 @@ export default function xoauth2Plugin(server) {
                         value: Buffer.from(JSON.stringify({
                             status: '400',
                             schemes: 'Bearer',
-                            scope: 'https://mail.google.com/'
+                            // the scope the OAuth provider of this server asks for, Gmail's without one
+                            scope: server.oauth ? server.oauth.mailScope : 'https://mail.google.com/'
                         })).toString('base64')
                     }
                 ]

package/dist/esm/rest.d.ts

@@ -41,6 +41,23 @@ declare function getRoutes(server: IMAPServer, streams?: Set<http.ServerResponse
  * @return {Object} OpenAPI document
  */
 declare function openApi(routes: Route[]): Record<string, unknown>;
+/**
+ * Compares two strings in constant time, also when their lengths differ
+ *
+ * @param {String} a First
+ * @param {String} b Second
+ * @return {Boolean} true if equal
+ */
+declare function safeEqual(a: string, b: string): boolean;
+/**
+ * Reads a request body
+ *
+ * @param {Object} req HTTP request
+ * @param {Number} limit Largest body in octets
+ * @param {Function} tooBig Makes the error for a larger body
+ * @return {Promise<Buffer>} the body
+ */
+declare function readRaw(req: http.IncomingMessage, limit: number, tooBig: () => Error): Promise<Buffer>;
 /**
  * Creates the HTTP server of the REST API, it does not listen yet
  *
@@ -50,5 +67,5 @@ declare function openApi(routes: Route[]): Record<string, unknown>;
  * @throws {Error} for a host that is not a loopback address without a token
  */
 declare function createRestServer(server: IMAPServer, options: RestOptions): RestServer;
-export { createRestServer, isLoopback, getRoutes, openApi };
+export { createRestServer, isLoopback, safeEqual, readRaw, getRoutes, openApi };
 export type { RestOptions, RestServer };

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', 'oauth'];
+// 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) };
             }
@@ -187,18 +197,18 @@ function getRoutes(server, streams = new Set()) {
         {
             method: 'POST',
             path: '/v1/users',
-            summary: 'Adds a user ({ name, password, xoauth2 })',
+            summary: 'Adds a user ({ name, password, xoauth2, displayName, oauth })',
             handler: ({ body }) => {
-                control.addUser(body.name, { password: body.password, xoauth2: body.xoauth2 });
+                control.addUser(body.name, { password: body.password, xoauth2: body.xoauth2, displayName: body.displayName, oauth: body.oauth });
                 return { status: 201, body: { name: body.name } };
             }
         },
         {
             method: 'PUT',
             path: '/v1/users/{name}',
-            summary: 'Changes the password or the XOAUTH2 token of a user',
+            summary: 'Changes the password, the XOAUTH2 token, the display name (displayName) or the OAuth settings ({ oauth: { consent } }) of a user',
             handler: ({ params, body }) => {
-                control.updateUser(params.name, { password: body.password, xoauth2: body.xoauth2 });
+                control.updateUser(params.name, { password: body.password, xoauth2: body.xoauth2, displayName: body.displayName, oauth: body.oauth });
                 return { name: params.name };
             }
         },
@@ -439,51 +449,67 @@ function matchRoute(routes, method, pathname) {
  */
 function hasToken(header, token) {
     const match = /^Bearer (.+)$/i.exec(header || '');
-    if (!match) {
-        return false;
-    }
+    return !!match && safeEqual(match[1], token);
+}
+/**
+ * Compares two strings in constant time, also when their lengths differ
+ *
+ * @param {String} a First
+ * @param {String} b Second
+ * @return {Boolean} true if equal
+ */
+function safeEqual(a, b) {
     const digest = (value) => crypto.createHash('sha256').update(value).digest();
-    return crypto.timingSafeEqual(digest(match[1]), digest(token));
+    return crypto.timingSafeEqual(digest(a), digest(b));
 }
 /**
- * Reads a JSON request body
+ * Reads a request body
  *
  * @param {Object} req HTTP request
- * @return {Promise<Object>} the body, an empty object without one
+ * @param {Number} limit Largest body in octets
+ * @param {Function} tooBig Makes the error for a larger body
+ * @return {Promise<Buffer>} the body
  */
-function readBody(req) {
+function readRaw(req, limit, tooBig) {
     return new Promise((resolve, reject) => {
         const chunks = [];
         let size = 0;
         req.on('data', (chunk) => {
             size += chunk.length;
-            if (size > BODY_LIMIT) {
-                reject(storeError('Request body is larger than 64 MiB', 'TOOBIG'));
+            if (size > limit) {
+                reject(tooBig());
                 req.destroy();
                 return;
             }
             chunks.push(chunk);
         });
         req.on('error', reject);
-        req.on('end', () => {
-            const text = Buffer.concat(chunks).toString('utf-8');
-            if (!text) {
-                return resolve({});
-            }
-            let body;
-            try {
-                body = JSON.parse(text);
-            }
-            catch {
-                return reject(storeError('Request body is not valid JSON', 'INVALID'));
-            }
-            if (!body || typeof body !== 'object') {
-                return reject(storeError('Request body must be a JSON object or array', 'INVALID'));
-            }
-            resolve(body);
-        });
+        req.on('end', () => resolve(Buffer.concat(chunks)));
     });
 }
+/**
+ * Reads a JSON request body
+ *
+ * @param {Object} req HTTP request
+ * @return {Promise<Object>} the body, an empty object without one
+ */
+async function readBody(req) {
+    const text = (await readRaw(req, BODY_LIMIT, () => storeError('Request body is larger than 64 MiB', 'TOOBIG'))).toString('utf-8');
+    if (!text) {
+        return {};
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw storeError('Request body is not valid JSON', 'INVALID');
+    }
+    if (!body || typeof body !== 'object') {
+        throw storeError('Request body must be a JSON object or array', 'INVALID');
+    }
+    return body;
+}
 /**
  * Creates the HTTP server of the REST API, it does not listen yet
  *
@@ -556,4 +582,4 @@ function createRestServer(server, options) {
     rest.endStreams = () => streams.forEach(res => res.end());
     return rest;
 }
-export { createRestServer, isLoopback, getRoutes, openApi };
+export { createRestServer, isLoopback, safeEqual, readRaw, getRoutes, openApi };

package/dist/esm/server.d.ts

@@ -5,6 +5,9 @@ import type { CompilerOptions, ParserOptions } from 'imap-handler';
 import type { ResolvedCommandOptions } from './command-states.js';
 import { Control } from './control.js';
 import type { RestServer } from './rest.js';
+import { OAuthProvider } from './oauth/provider.js';
+import type { TokenCheck } from './oauth/provider.js';
+import type http from 'node:http';
 import type { SessionInfo } from './control.js';
 import type { MemorySocket } from './memory-socket.js';
 import { ServerScript } from './script.js';
@@ -83,10 +86,16 @@ 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 */
     restServer: RestServer | null;
+    /** the OAuth 2.0 / OpenID Connect provider of the `oauth` option, see src/oauth/provider.ts */
+    oauth: OAuthProvider | null;
+    /** the HTTP server of the OAuth provider that `start()` runs */
+    oauthServer: http.Server | null;
     constructor(options?: IMAPServerOptions);
     /**
      * Sets the users from the `users` option, or the default user. The users are deep copied, so that runtime changes
@@ -107,12 +116,37 @@ 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
      *
      * @return {Promise<Number>} resolves with the HTTP port
      */
     startRest(): Promise<number>;
+    /**
+     * Starts the HTTP server of the OAuth provider (the `oauth` option, see src/oauth/http.ts). The issuer is its
+     * URL unless the `issuer` option sets another
+     *
+     * @return {Promise<Number>} resolves with the HTTP port
+     */
+    startOAuth(): Promise<number>;
+    /**
+     * Checks a bearer token of an IMAP or SMTP login: a token of the OAuth provider, or the static
+     * `xoauth2.accessToken` of a user, which never expires
+     *
+     * @param {String} token Access token
+     * @param {String} [username] The user the client logs in as, the owner of the token if not set
+     * @param {String} [via] "imap" or "smtp", for the events of the provider
+     * @return {Object} `{ user }`, or `{ error, reason }` with the OAuth error code (invalid_token, insufficient_scope)
+     */
+    checkAccessToken(token: string, username?: string, via?: string): TokenCheck;
     /**
      * Starts the SMTP server of the `smtp` option. smtp-server is an optional dependency, loaded only here
      *
@@ -141,7 +175,14 @@ declare class IMAPServer extends Stream {
     listen(options: net.ListenOptions, listeningListener?: () => void): void;
     close(callback?: (err?: Error) => void): void;
     /**
-     * Stops the SMTP and REST listeners of `start()`
+     * 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, REST and OAuth listeners of `start()`
      *
      * @param {Boolean} force true closes the open REST connections too, otherwise only the idle ones (a request that
      *   is answered, like POST /v1/shutdown, finishes first)
@@ -677,6 +718,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

@@ -14,10 +14,12 @@ import { isSequenceSet } from './numbers.js';
 import { restoreNilAtoms, isAtom } from './arguments.js';
 import { refuseMissingTarget } from './commands/append.js';
 import { DEFAULT_SESSION_TIMEOUT, storeError, expungeMessages, notifyFlagChanges } from './store-operations.js';
-import { Control } from './control.js';
+import { Control, checkUserOAuth } from './control.js';
 import { resolveQuirks } from './quirks.js';
 import { validateStorage } from './storage-schema.js';
 import { createRestServer } from './rest.js';
+import { OAuthProvider } from './oauth/provider.js';
+import { createOAuthServer } from './oauth/http.js';
 import * as bundledCert from './cert.js';
 import { createSocketPair } from './memory-socket.js';
 import { ServerScript, sendOutput, handleLine, handleQuiet, literalResponse, releaseDeferred } from './script.js';
@@ -193,6 +195,9 @@ class IMAPServer extends Stream {
         this.loadUsers();
         // plugins register their control operations
         this.control = new Control(this);
+        // registers its control operations too, so it exists only with the option
+        this.oauth = this.options.oauth ? new OAuthProvider(this, this.options.oauth) : null;
+        this.oauthServer = null;
         // a quirk preset can leave plugins out (no-move, no-uidplus)
         loadPlugins(this, this.options.plugins, quirks.removePlugins);
         if (this.options.storage) {
@@ -201,6 +206,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;
     }
@@ -221,6 +227,13 @@ class IMAPServer extends Stream {
                     }
                 }
             });
+        // a typo in an OAuth consent policy fails here
+        for (const name of Object.keys(this.users)) {
+            const user = this.users[name];
+            if (user && user.oauth !== undefined) {
+                user.oauth = checkUserOAuth(user.oauth, 'users[' + JSON.stringify(name) + '].oauth');
+            }
+        }
     }
     /**
      * Builds the mailboxes from the `storage` option, a deep copy of it. Message and mailbox handlers of plugins run
@@ -251,9 +264,26 @@ 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,
+            this.oauth ? this.startOAuth() : 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
      *
@@ -264,6 +294,41 @@ class IMAPServer extends Stream {
         this.restServer = createRestServer(this, { host, token });
         return listenOn(this.restServer, port, host || '127.0.0.1');
     }
+    /**
+     * Starts the HTTP server of the OAuth provider (the `oauth` option, see src/oauth/http.ts). The issuer is its
+     * URL unless the `issuer` option sets another
+     *
+     * @return {Promise<Number>} resolves with the HTTP port
+     */
+    async startOAuth() {
+        const oauth = this.oauth;
+        const { port, host = '127.0.0.1', secure } = oauth.options;
+        this.oauthServer = createOAuthServer(oauth, { secure, host, credentials: this.getCredentials() });
+        const listening = await listenOn(this.oauthServer, port, host);
+        oauth.listening(host, listening);
+        return listening;
+    }
+    /**
+     * Checks a bearer token of an IMAP or SMTP login: a token of the OAuth provider, or the static
+     * `xoauth2.accessToken` of a user, which never expires
+     *
+     * @param {String} token Access token
+     * @param {String} [username] The user the client logs in as, the owner of the token if not set
+     * @param {String} [via] "imap" or "smtp", for the events of the provider
+     * @return {Object} `{ user }`, or `{ error, reason }` with the OAuth error code (invalid_token, insufficient_scope)
+     */
+    checkAccessToken(token, username, via = 'imap') {
+        const issued = this.oauth && this.oauth.verifyAccessToken(token, username, via);
+        if (issued) {
+            return issued;
+        }
+        const owns = (name) => {
+            const user = this.users[name];
+            return !!(user && user.xoauth2 && user.xoauth2.accessToken === token);
+        };
+        const user = username === undefined ? Object.keys(this.users).find(owns) : owns(username) ? username : undefined;
+        return user === undefined ? { error: 'invalid_token', reason: 'unknown access token' } : { user };
+    }
     /**
      * Starts the SMTP server of the `smtp` option. smtp-server is an optional dependency, loaded only here
      *
@@ -303,7 +368,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) {
@@ -312,7 +377,25 @@ class IMAPServer extends Stream {
         });
     }
     /**
-     * Stops the SMTP and REST listeners of `start()`
+     * 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, REST and OAuth listeners of `start()`
      *
      * @param {Boolean} force true closes the open REST connections too, otherwise only the idle ones (a request that
      *   is answered, like POST /v1/shutdown, finishes first)
@@ -325,16 +408,13 @@ class IMAPServer extends Stream {
         if (this.restServer) {
             // event streams never end on their own, a graceful shutdown would wait for them forever
             this.restServer.endStreams?.();
-            this.restServer.close();
-            // keep-alive connections would hold the server open
-            if (force) {
-                this.restServer.closeAllConnections?.();
-            }
-            else {
-                this.restServer.closeIdleConnections?.();
-            }
+            closeHttp(this.restServer, force);
             this.restServer = null;
         }
+        if (this.oauthServer) {
+            closeHttp(this.oauthServer, force);
+            this.oauthServer = null;
+        }
     }
     /**
      * Returns TLS key and certificate. Without credentials in the options the
@@ -429,7 +509,8 @@ class IMAPServer extends Stream {
      * @return {Object|false} User data or false if there is no such user
      */
     getUser(username) {
-        return (typeof username === 'string' && this.users[username]) || false;
+        // users is a null-prototype object, but a plain object from the control API or a test may still be assigned
+        return (typeof username === 'string' && Object.hasOwn(this.users, username) && this.users[username]) || false;
     }
     /**
      * Returns a mailbox object from folderCache
@@ -1111,6 +1192,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 +1637,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 +1648,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 +1969,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');
@@ -3169,6 +3267,22 @@ const IS_DENO = 'Deno' in globalThis;
 function nextTurn(fn) {
     return IS_DENO ? setTimeout(fn, 0) : setImmediate(fn);
 }
+/**
+ * Stops an HTTP listener of `start()`
+ *
+ * @param {Object} server HTTP server
+ * @param {Boolean} force true closes the open connections too, otherwise only the idle ones (keep-alive connections
+ *   would hold the server open)
+ */
+function closeHttp(server, force) {
+    server.close();
+    if (force) {
+        server.closeAllConnections?.();
+    }
+    else {
+        server.closeIdleConnections?.();
+    }
+}
 /**
  * Starts listening, resolves with the port or rejects with the listen error (EADDRINUSE)
  *

package/dist/esm/smtp-listener.d.ts

@@ -2,8 +2,9 @@ import { SMTPServer } from 'smtp-server';
 import type { IMAPServer } from './types.js';
 /**
  * Starts an SMTP server that appends every received message to the INBOX
- * of the given ImapKit IMAP server. Any sender, recipient and credentials
- * are accepted.
+ * of the given ImapKit IMAP server. Any sender, recipient and password are
+ * accepted. With the OAuth provider, AUTH XOAUTH2 is offered too and checks
+ * the access token like the IMAP login does.
  *
  * @param {Number} smtpPort - port to listen on for SMTP commands
  * @param {Object} imapServer - the ImapKit IMAP server

package/dist/esm/smtp-listener.js

@@ -1,8 +1,9 @@
 import { SMTPServer } from 'smtp-server';
 /**
  * Starts an SMTP server that appends every received message to the INBOX
- * of the given ImapKit IMAP server. Any sender, recipient and credentials
- * are accepted.
+ * of the given ImapKit IMAP server. Any sender, recipient and password are
+ * accepted. With the OAuth provider, AUTH XOAUTH2 is offered too and checks
+ * the access token like the IMAP login does.
  *
  * @param {Number} smtpPort - port to listen on for SMTP commands
  * @param {Object} imapServer - the ImapKit IMAP server
@@ -17,9 +18,20 @@ export function startSMTPServer(smtpPort, imapServer, callback, host) {
         key: credentials.key,
         cert: credentials.cert,
         authOptional: true,
+        // with the OAuth provider, clients can also log in with its access tokens
+        authMethods: imapServer.oauth ? ['PLAIN', 'LOGIN', 'XOAUTH2'] : ['PLAIN', 'LOGIN'],
         logger: false,
         onAuth(auth, session, done) {
-            done(null, { user: auth.username });
+            // XOAUTH2 is only offered with the OAuth provider
+            if (auth.method !== 'XOAUTH2') {
+                return done(null, { user: auth.username });
+            }
+            const result = imapServer.checkAccessToken(auth.accessToken || '', auth.username, 'smtp');
+            if ('error' in result) {
+                // the JSON error of Gmail's XOAUTH2, the client answers it and gets 535
+                return done(null, { data: { status: '401', schemes: 'bearer', scope: imapServer.oauth.mailScope } });
+            }
+            done(null, { user: result.user });
         },
         onData(stream, session, done) {
             const chunks = [];