imapkit 5.2.0 → 5.3.0

package/dist/cjs/plugins/oauthbearer.js

@@ -7,7 +7,7 @@ exports.parseClientResponse = parseClientResponse;
  * @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 });
@@ -93,21 +93,16 @@ 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);
@@ -159,7 +154,7 @@ 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/cjs/plugins/xoauth2.js

@@ -8,7 +8,7 @@ exports.default = xoauth2Plugin;
  * @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 });
 function xoauth2Plugin(server) {
@@ -94,7 +94,7 @@ 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: [
@@ -103,7 +103,8 @@ 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/cjs/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/cjs/rest.js

@@ -12,6 +12,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRestServer = createRestServer;
 exports.isLoopback = isLoopback;
+exports.safeEqual = safeEqual;
+exports.readRaw = readRaw;
 exports.getRoutes = getRoutes;
 exports.openApi = openApi;
 const node_http_1 = __importDefault(require("node:http"));
@@ -70,7 +72,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);
@@ -206,18 +208,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 };
             }
         },
@@ -458,51 +460,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) => node_crypto_1.default.createHash('sha256').update(value).digest();
-    return node_crypto_1.default.timingSafeEqual(digest(match[1]), digest(token));
+    return node_crypto_1.default.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((0, store_operations_js_1.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((0, store_operations_js_1.storeError)('Request body is not valid JSON', 'INVALID'));
-            }
-            if (!body || typeof body !== 'object') {
-                return reject((0, store_operations_js_1.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, () => (0, store_operations_js_1.storeError)('Request body is larger than 64 MiB', 'TOOBIG'))).toString('utf-8');
+    if (!text) {
+        return {};
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw (0, store_operations_js_1.storeError)('Request body is not valid JSON', 'INVALID');
+    }
+    if (!body || typeof body !== 'object') {
+        throw (0, store_operations_js_1.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
  *

package/dist/cjs/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/cjs/server.js

@@ -58,6 +58,8 @@ const control_js_1 = require("./control.js");
 const quirks_js_1 = require("./quirks.js");
 const storage_schema_js_1 = require("./storage-schema.js");
 const rest_js_1 = require("./rest.js");
+const provider_js_1 = require("./oauth/provider.js");
+const http_js_1 = require("./oauth/http.js");
 const bundledCert = __importStar(require("./cert.js"));
 const memory_socket_js_1 = require("./memory-socket.js");
 const script_js_1 = require("./script.js");
@@ -234,6 +236,9 @@ class IMAPServer extends node_stream_1.Stream {
         this.loadUsers();
         // plugins register their control operations
         this.control = new control_js_1.Control(this);
+        // registers its control operations too, so it exists only with the option
+        this.oauth = this.options.oauth ? new provider_js_1.OAuthProvider(this, this.options.oauth) : null;
+        this.oauthServer = null;
         // a quirk preset can leave plugins out (no-move, no-uidplus)
         (0, load_plugins_js_1.default)(this, this.options.plugins, quirks.removePlugins);
         if (this.options.storage) {
@@ -263,6 +268,13 @@ class IMAPServer extends node_stream_1.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 = (0, control_js_1.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
@@ -296,7 +308,8 @@ class IMAPServer extends node_stream_1.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;
     }
@@ -322,6 +335,41 @@ class IMAPServer extends node_stream_1.Stream {
         this.restServer = (0, rest_js_1.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 = (0, http_js_1.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
      *
@@ -388,7 +436,7 @@ class IMAPServer extends node_stream_1.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)
@@ -401,16 +449,13 @@ class IMAPServer extends node_stream_1.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
@@ -505,7 +550,8 @@ class IMAPServer extends node_stream_1.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
@@ -3264,6 +3310,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/cjs/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/cjs/smtp-listener.js

@@ -4,8 +4,9 @@ exports.startSMTPServer = startSMTPServer;
 const smtp_server_1 = require("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
@@ -20,9 +21,20 @@ 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/cjs/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/esm/control.d.ts

@@ -8,6 +8,7 @@
  */
 import { ImapKitError } from './store-operations.js';
 import type { FlagMode, UidValidityOptions } from './store-operations.js';
+import type { ConsentPolicy } from './oauth/policy.js';
 import type { IMAPConnection, IMAPServer, Mailbox, Message, StorageMailbox, StorageNamespace, UserData } from './types.js';
 /** A mailbox as `getMailbox()` and `listMailboxes()` describe it */
 interface MailboxInfo {
@@ -68,7 +69,7 @@ interface NewMessage {
     internaldate?: Date | string | undefined;
 }
 /** The credentials of a user, see UserData */
-type UserOptions = Pick<UserData, 'password' | 'xoauth2'>;
+type UserOptions = Pick<UserData, 'password' | 'xoauth2' | 'displayName' | 'oauth'>;
 /** What a REST route handler gets, see src/rest.ts */
 interface RouteRequest {
     params: Record<string, string>;
@@ -89,6 +90,16 @@ type SessionFilter = number | {
     session?: number | undefined;
     user?: string | undefined;
 };
+/**
+ * Checks the `oauth` settings of a user
+ *
+ * @param {*} value `{ consent }`
+ * @param {String} what Setting name for the error message
+ * @return {Object} a copy
+ */
+declare function checkUserOAuth(value: unknown, what: string): {
+    consent?: ConsentPolicy;
+};
 declare class Control {
     [key: string]: any;
     server: IMAPServer;
@@ -364,14 +375,14 @@ declare class Control {
      * Adds a user
      *
      * @param {String} name User name
-     * @param {Object} options `{ password, xoauth2: { accessToken, sessionTimeout } }`
+     * @param {Object} options `{ password, xoauth2: { accessToken, sessionTimeout }, displayName, oauth: { consent } }`
      */
     addUser(name: string, options: UserOptions): void;
     /**
-     * Changes the password or the XOAUTH2 token of a user
+     * Changes the password, the XOAUTH2 token, the display name or the OAuth consent policy of a user
      *
      * @param {String} name User name
-     * @param {Object} options `{ password, xoauth2 }`, null xoauth2 removes the token
+     * @param {Object} options `{ password, xoauth2, displayName, oauth }`, null xoauth2, displayName or oauth removes it
      */
     updateUser(name: string, options: UserOptions): void;
     /**
@@ -421,5 +432,5 @@ declare class Control {
         graceful?: boolean | undefined;
     }): Promise<void>;
 }
-export { Control, ImapKitError };
+export { Control, ImapKitError, checkUserOAuth };
 export type { MailboxInfo, MessageInfo, SessionInfo, NewMessage, UserOptions, SessionFilter, ControlRoute, RouteRequest };

package/dist/esm/control.js

@@ -8,6 +8,7 @@
  */
 import validateMailboxName from './mailbox-name.js';
 import { DEFAULT_SESSION_TIMEOUT, ImapKitError, expungeMessages, checkFlags, changeFlags, createMailbox, deleteMailbox, renameMailbox, resetUidValidity, subscribeMailbox, unsubscribeMailbox } from './store-operations.js';
+import { checkOutcome } from './oauth/policy.js';
 /**
  * Copies a value of a plugin into the snapshot as JSON data, values that JSON can not hold are left out
  *
@@ -43,6 +44,20 @@ const NAMESPACE_SKIP = new Set(['folders']);
 // properties the server derives when it loads a mailbox, a snapshot leaves them out
 const DERIVED_MAILBOX_KEYS = new Set(['path', 'namespace', 'messages', 'folders', 'subscribed', 'flags']);
 const DERIVED_FLAGS = new Set(['\\HasChildren', '\\HasNoChildren']);
+/**
+ * Checks the `oauth` settings of a user
+ *
+ * @param {*} value `{ consent }`
+ * @param {String} what Setting name for the error message
+ * @return {Object} a copy
+ */
+function checkUserOAuth(value, what) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ImapKitError(what + ' must be { consent }', 'INVALID');
+    }
+    const { consent } = value;
+    return consent === undefined ? {} : { consent: checkOutcome(consent, what + '.consent') };
+}
 class Control {
     constructor(server) {
         this.server = server;
@@ -494,7 +509,7 @@ class Control {
      * Adds a user
      *
      * @param {String} name User name
-     * @param {Object} options `{ password, xoauth2: { accessToken, sessionTimeout } }`
+     * @param {Object} options `{ password, xoauth2: { accessToken, sessionTimeout }, displayName, oauth: { consent } }`
      */
     addUser(name, options) {
         if (typeof name !== 'string' || !name) {
@@ -506,10 +521,10 @@ class Control {
         this.server.users[name] = this.userData({}, options);
     }
     /**
-     * Changes the password or the XOAUTH2 token of a user
+     * Changes the password, the XOAUTH2 token, the display name or the OAuth consent policy of a user
      *
      * @param {String} name User name
-     * @param {Object} options `{ password, xoauth2 }`, null xoauth2 removes the token
+     * @param {Object} options `{ password, xoauth2, displayName, oauth }`, null xoauth2, displayName or oauth removes it
      */
     updateUser(name, options) {
         this.server.users[name] = this.userData(this.requireUser(name), options);
@@ -534,8 +549,23 @@ class Control {
         return this.server.users[name];
     }
     userData(user, options) {
-        const { password, xoauth2 } = options || {};
+        const { password, xoauth2, displayName, oauth } = options || {};
         const result = Object.assign({}, user);
+        if (displayName === null) {
+            delete result.displayName;
+        }
+        else if (displayName !== undefined) {
+            if (typeof displayName !== 'string') {
+                throw new ImapKitError('displayName must be a string', 'INVALID');
+            }
+            result.displayName = displayName;
+        }
+        if (oauth === null) {
+            delete result.oauth;
+        }
+        else if (oauth !== undefined) {
+            result.oauth = checkUserOAuth(oauth, 'oauth');
+        }
         if (password !== undefined) {
             if (typeof password !== 'string') {
                 throw new ImapKitError('Password must be a string', 'INVALID');
@@ -627,4 +657,4 @@ class Control {
         });
     }
 }
-export { Control, ImapKitError };
+export { Control, ImapKitError, checkUserOAuth };