imapkit 5.2.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

@@ -61,7 +61,7 @@ function decodeBody(value, encoding) {
     return encoding === 'base64' && typeof value === 'string' ? Buffer.from(value, 'base64') : value;
 }
 // the server events that GET /v1/events streams by default
-const EVENT_TYPES = ['session', 'command', 'mailbox', 'append', 'expunge', 'flags', 'acl', 'script', 'reset'];
+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);
@@ -197,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 };
             }
         },
@@ -449,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
  *
@@ -566,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';
@@ -89,6 +92,10 @@ declare class IMAPServer extends Stream {
     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
@@ -123,6 +130,23 @@ declare class IMAPServer extends Stream {
      * @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
      *
@@ -158,7 +182,7 @@ declare class IMAPServer extends Stream {
      */
     closeImapListeners(callback?: (err?: Error) => void): void;
     /**
-     * Stops the SMTP and REST listeners of `start()`
+     * 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)

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) {
@@ -222,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
@@ -255,7 +267,8 @@ class IMAPServer extends Stream {
         await Promise.all([
             this.options.tls ? this.startTlsListener(host) : null,
             this.options.smtp ? this.startSmtp() : null,
-            this.options.rest ? this.startRest() : null
+            this.options.rest ? this.startRest() : null,
+            this.oauth ? this.startOAuth() : null
         ]);
         return imapPort;
     }
@@ -281,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
      *
@@ -347,7 +395,7 @@ class IMAPServer extends Stream {
         }));
     }
     /**
-     * Stops the SMTP and REST listeners of `start()`
+     * 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)
@@ -360,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
@@ -464,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
@@ -3221,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 = [];

package/dist/esm/types.d.ts

@@ -1,5 +1,7 @@
 import type { IMAPServer, IMAPConnection } from './server.js';
 import type { ScriptRule } from './script.js';
+import type { OAuthOptions } from './oauth/provider.js';
+import type { ConsentPolicy } from './oauth/policy.js';
 export type { IMAPServer, IMAPConnection };
 /**
  * A value of the parsed command or of a response, as imap-handler parses and compiles it: an
@@ -210,6 +212,12 @@ export interface MailboxStatus {
 }
 export interface UserData {
     password?: string | undefined;
+    /** the display name, the `name` claim of the OAuth provider */
+    displayName?: string | undefined;
+    /** OAuth provider settings of the user: the consent policy of sign-ins that name the user in login_hint */
+    oauth?: {
+        consent?: ConsentPolicy | undefined;
+    } | undefined;
     xoauth2?: {
         accessToken?: string | undefined;
         /**
@@ -246,6 +254,8 @@ export interface IMAPServerOptions {
         host?: string | undefined;
         token?: string | undefined;
     } | undefined;
+    /** starts the OAuth 2.0 / OpenID Connect provider with `server.start()`, see src/oauth/provider.ts */
+    oauth?: OAuthOptions | undefined;
     credentials?: {
         key: string | Buffer;
         cert: string | Buffer;

package/dist/plugin-help.json

@@ -144,7 +144,7 @@
         "Works with and without SASL-IR [RFC4959]",
         "Valid login info, same as for XOAUTH2:",
         "  Username (authzid, optional): testuser",
-        "  Access Token: testtoken"
+        "  Access Token: testtoken, or a token of the OAuth provider"
     ],
     "OBJECTID": [
         "Adds OBJECTID [RFC8474] capability",
@@ -280,6 +280,6 @@
         "SASL-IR enabled and used while Gmail does not",
         "Valid login info:",
         "  Username: testuser",
-        "  Access Token: testtoken"
+        "  Access Token: testtoken, or a token of the OAuth provider"
     ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapkit",
-    "version": "5.2.0",
+    "version": "5.3.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.13.0",
+        "eslint": "10.14.0",
         "eslint-config-prettier": "10.1.8",
         "events": "3.3.0",
-        "globals": "17.13.0",
-        "imapflow": "2.5.6",
+        "globals": "17.14.0",
+        "imapflow": "2.10.0",
         "prettier": "3.9.10",
-        "smtp-server": "3.20.2",
+        "smtp-server": "3.21.3",
         "tsx": "4.23.15",
         "typescript": "6.0.3",
-        "typescript-eslint": "8.71.2"
+        "typescript-eslint": "8.72.1"
     },
     "engines": {
         "node": ">=20.0.0"