imapkit 5.0.0 → 5.0.1

package/dist/esm/control.d.ts

@@ -4,7 +4,7 @@
  * unsolicited FETCH, BYE, NOTIFY events, CONDSTORE mod-sequences), with no session as its origin. The API is the
  * operator: ACL does not apply, but every argument is checked. Mailboxes are addressed by their storage name
  * (modified UTF-7), messages by mailbox and UID. Methods return plain data and throw an ImapKitError with a `code`:
- * NONEXISTENT, ALREADYEXISTS, INVALID, or a RFC 5530 code of a failed mailbox operation (CANNOT, HASCHILDREN ...)
+ * NONEXISTENT, ALREADYEXISTS, INVALID, or the response code of a failed mailbox operation (CANNOT, HASCHILDREN ...)
  */
 import { ImapKitError } from './store-operations.js';
 import type { FlagMode, UidValidityOptions } from './store-operations.js';
@@ -22,7 +22,7 @@ interface MailboxInfo {
     unseen: number;
     uidnext: number;
     uidvalidity: number;
-    /** flags that can be stored, \* when new keywords are allowed */
+    /** the flags of the FLAGS response, SELECT adds \* to PERMANENTFLAGS when new keywords are allowed */
     permanentFlags: string[];
     /** only with CONDSTORE */
     highestModseq?: number;
@@ -67,13 +67,8 @@ interface NewMessage {
     /** a Date or a RFC 3501 date-time string, the current time if not set */
     internaldate?: Date | string | undefined;
 }
-interface UserOptions {
-    password?: string | undefined;
-    xoauth2?: {
-        accessToken?: string | undefined;
-        sessionTimeout?: number | undefined;
-    } | undefined;
-}
+/** The credentials of a user, see UserData */
+type UserOptions = Pick<UserData, 'password' | 'xoauth2'>;
 /** What a REST route handler gets, see src/rest.ts */
 interface RouteRequest {
     params: Record<string, string>;

package/dist/esm/control.js

@@ -4,7 +4,7 @@
  * unsolicited FETCH, BYE, NOTIFY events, CONDSTORE mod-sequences), with no session as its origin. The API is the
  * operator: ACL does not apply, but every argument is checked. Mailboxes are addressed by their storage name
  * (modified UTF-7), messages by mailbox and UID. Methods return plain data and throw an ImapKitError with a `code`:
- * NONEXISTENT, ALREADYEXISTS, INVALID, or a RFC 5530 code of a failed mailbox operation (CANNOT, HASCHILDREN ...)
+ * NONEXISTENT, ALREADYEXISTS, INVALID, or the response code of a failed mailbox operation (CANNOT, HASCHILDREN ...)
  */
 import validateMailboxName from './mailbox-name.js';
 import { DEFAULT_SESSION_TIMEOUT, ImapKitError, expungeMessages, checkFlags, changeFlags, createMailbox, deleteMailbox, renameMailbox, resetUidValidity, subscribeMailbox, unsubscribeMailbox } from './store-operations.js';

package/dist/esm/dates.d.ts

@@ -36,6 +36,14 @@ declare function isRealDate(day: number | string | undefined, month: number, yea
  * @return {String|Boolean} the date, or false for an impossible date
  */
 declare function dateKey(day: number | string, month: number, year: number | string): string | false;
+/**
+ * Checks a date-time string of RFC 3501 section 9, like an INTERNALDATE ("14-Sep-2013 21:22:28 -0300"):
+ * date-time = DQUOTE date-day-fixed "-" date-month "-" date-year SP time SP zone DQUOTE
+ *
+ * @param {String} value Value to check
+ * @return {Boolean} true if the value is a date-time string of a real date and time
+ */
+declare function isDateTime(value: unknown): boolean;
 /**
  * Parses a date-time value of the RFC 3501 section 9 form, like an INTERNALDATE ("14-Sep-2013 21:22:28 -0300").
  * A value with only the date part is accepted as well, its time fields are left undefined
@@ -61,4 +69,4 @@ declare function parseHeaderDate(header: string | undefined): DateParts | null;
  * @return {Number} timestamp
  */
 declare function toTimestamp(date: DateParts): number;
-export { MONTHS, monthIndex, isRealDate, dateKey, parseDateTime, parseHeaderDate, toTimestamp };
+export { MONTHS, monthIndex, isRealDate, isDateTime, dateKey, parseDateTime, parseHeaderDate, toTimestamp };

package/dist/esm/dates.js

@@ -40,6 +40,25 @@ function dateKey(day, month, year) {
     }
     return String(year).padStart(4, '0') + '-' + String(month + 1).padStart(2, '0') + '-' + String(day).padStart(2, '0');
 }
+/**
+ * Checks a date-time string of RFC 3501 section 9, like an INTERNALDATE ("14-Sep-2013 21:22:28 -0300"):
+ * date-time = DQUOTE date-day-fixed "-" date-month "-" date-year SP time SP zone DQUOTE
+ *
+ * @param {String} value Value to check
+ * @return {Boolean} true if the value is a date-time string of a real date and time
+ */
+function isDateTime(value) {
+    if (!value || typeof value !== 'string') {
+        return false;
+    }
+    // month names are case-insensitive like all ABNF strings
+    const match = value.match(/^( \d|\d\d)-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-(\d{4}) (\d{2}):(\d{2}):(\d{2}) [-+](\d{2})(\d{2})$/i);
+    if (!match) {
+        return false;
+    }
+    // the values must also make a real date and time
+    return (isRealDate(match[1], monthIndex(match[2]), match[3]) && Number(match[4]) < 24 && Number(match[5]) < 60 && Number(match[6]) < 61 && Number(match[8]) < 60);
+}
 /**
  * Parses a date-time value of the RFC 3501 section 9 form, like an INTERNALDATE ("14-Sep-2013 21:22:28 -0300").
  * A value with only the date part is accepted as well, its time fields are left undefined
@@ -112,4 +131,4 @@ function toTimestamp(date) {
     }
     return Date.UTC(date.year, date.month, date.day, date.hours || 0, date.minutes || 0, date.seconds || 0) - offset * 60 * 1000;
 }
-export { MONTHS, monthIndex, isRealDate, dateKey, parseDateTime, parseHeaderDate, toTimestamp };
+export { MONTHS, monthIndex, isRealDate, isDateTime, dateKey, parseDateTime, parseHeaderDate, toTimestamp };

package/dist/esm/envelope.d.ts

@@ -1,7 +1,7 @@
 import type { ParsedAddress } from './addressparser.js';
 import type { ParsedHeader } from './mimeparser.js';
 /** An address of the ENVELOPE (RFC 3501 section 9): name, source route, mailbox and host, all NIL for a group end */
-export type EnvelopeAddress = [name: string | null, adl: null, mailbox: string | null, host: string | null];
+export type EnvelopeAddress = [name: string | null, adl: string | null, mailbox: string | null, host: string | null];
 /** The fields of the ENVELOPE (RFC 3501 section 7.4.2), in order */
 export type Envelope = [
     date: string | null,

package/dist/esm/envelope.js

@@ -1,4 +1,27 @@
 // This module converts message structure into an ENVELOPE object
+// RFC 5322 section 4.4: obs-angle-addr = [CFWS] "<" obs-route addr-spec ">" [CFWS], obs-route = obs-domain-list ":",
+// obs-domain-list = *(CFWS / ",") "@" domain *("," [CFWS] ["@" domain]). A domain-literal can hold a colon
+const OBS_ROUTE = /^[\s,]*(@(?:[^:[]|\[[^\]]*\])*):/;
+/**
+ * Splits an obsolete source route from an address: the route goes to addr-adl, the rest is the addr-spec
+ * (RFC 9051 section 7.5.2: the at-domain-list is the "source route and obs-route ABNF production from [RFC5322]",
+ * the mailbox name the "local-part ABNF production"). The route is sent like Dovecot does, "@a,@b"
+ *
+ * @param {String} address Address from the angle brackets
+ * @return {Array} [route or null, addr-spec]
+ */
+function splitRoute(address) {
+    const match = address.match(OBS_ROUTE);
+    if (!match) {
+        return [null, address];
+    }
+    const route = match[1]
+        .split(',')
+        .map(domain => domain.trim())
+        .filter(domain => domain)
+        .join(',');
+    return [route, address.substr(match[0].length).trim()];
+}
 /**
  * Convert a message object to an ENVELOPE object
  *
@@ -57,12 +80,14 @@ function processAddress(arr, def) {
         if (!address) {
             return;
         }
+        const [route, addrSpec] = splitRoute(address);
+        address = addrSpec;
         const at = address.lastIndexOf('@');
         const user = at >= 0 ? address.substr(0, at) : address;
         // RFC 3501 7.4.2 reserves a NIL host for group markers, so an address without a domain gets
         // the placeholder host that Dovecot uses for the same input
         const domain = (at >= 0 ? address.substr(at + 1) : '') || 'MISSING_DOMAIN';
-        result.push([name, null, user || null, domain]);
+        result.push([name, route, user || null, domain]);
     });
     // env-from = "(" 1*address ")", there is no SP between the addresses (RFC 3501 section 9)
     Object.defineProperty(result, 'adjacentLists', { value: true });

package/dist/esm/index.d.ts

@@ -6,7 +6,8 @@ export { TAG_REGEX, IMAPServer, IMAPConnection, ImapKitError, quirks, storageSch
 export type { Attribute, ParsedCommand, IMAPResponse, Notification, Callback, CommandHandler, CommandOptions, Plugin, IMAPError, Message, Mailbox, StorageNamespace, UserData, IMAPServerOptions } from './types.js';
 export type { ScriptRule, ScriptContext, ScriptEvent, ScriptBytes, ScriptHandle } from './script.js';
 export type { Quirk } from './quirks.js';
-export type { Control, MailboxInfo, MessageInfo, SessionInfo, NewMessage, UserOptions, SessionFilter } from './control.js';
+export type { Control, MailboxInfo, MessageInfo, SessionInfo, NewMessage, UserOptions, SessionFilter, ControlRoute, RouteRequest } from './control.js';
+export type { FlagMode, UidMode, UidValidityOptions } from './store-operations.js';
 declare const imapkit: typeof createServer & {
     TAG_REGEX: RegExp;
     IMAPServer: typeof IMAPServer;

package/dist/esm/load-plugins.d.ts

@@ -15,7 +15,9 @@ declare function listPlugins(): string[];
  *
  * @param {Object} server IMAPServer instance
  * @param {Array|String|Function} plugins List of plugins to load
+ * @param {Map} [exclude] Plugins a quirk preset leaves out, plugin name to quirk name
+ * @throws {Error} when a loaded plugin requires an excluded one
  */
-declare function loadPlugins(server: IMAPServer, plugins: (string | Plugin)[] | string | Plugin | null | undefined, exclude?: string[]): void;
+declare function loadPlugins(server: IMAPServer, plugins: (string | Plugin)[] | string | Plugin | null | undefined, exclude?: Map<string, string>): void;
 export default loadPlugins;
 export { listPlugins };

package/dist/esm/load-plugins.js

@@ -46,12 +46,21 @@ function resolvePlugin(name) {
  *
  * @param {Object} server IMAPServer instance
  * @param {Array|String|Function} plugins List of plugins to load
+ * @param {Map} [exclude] Plugins a quirk preset leaves out, plugin name to quirk name
+ * @throws {Error} when a loaded plugin requires an excluded one
  */
 function loadPlugins(server, plugins, exclude) {
     const loaded = new Set();
-    // plugins a quirk preset leaves out (no-move), they are not loaded even when listed
-    const excluded = new Set((exclude || []).map(name => resolvePlugin(name)).flatMap(name => (name ? [builtinPlugins[name]] : [])));
-    const load = (entry) => {
+    // plugins a quirk preset leaves out (no-move), they are not loaded even when listed, and the quirk that removes them
+    const excluded = new Map();
+    (exclude || new Map()).forEach((quirk, name) => {
+        const resolved = resolvePlugin(name);
+        if (resolved) {
+            excluded.set(builtinPlugins[resolved], quirk);
+        }
+    });
+    // `requiredBy` names the plugin whose `requires` lists this one
+    const load = (entry, requiredBy) => {
         let plugin = entry;
         if (typeof plugin === 'string') {
             const name = resolvePlugin(plugin);
@@ -66,14 +75,24 @@ function loadPlugins(server, plugins, exclude) {
         if (typeof plugin !== 'function') {
             throw new TypeError('Invalid plugin, expecting a plugin name or a function');
         }
-        if (loaded.has(plugin) || excluded.has(plugin)) {
+        const quirk = excluded.get(plugin);
+        if (quirk) {
+            if (requiredBy) {
+                // the plugin can not work without it (IMAP4rev2 folds in MOVE and UIDPLUS, RFC 9051 Appendix E), so
+                // advertising it without the required plugin would break its RFC
+                throw new Error(requiredBy + ' requires ' + entry + ', which the "' + quirk + '" quirk removes');
+            }
+            return;
+        }
+        if (loaded.has(plugin)) {
             return;
         }
         loaded.add(plugin);
-        [].concat(plugin.requires || []).forEach(load);
+        const name = typeof entry === 'string' ? entry.trim() : plugin.name;
+        [].concat(plugin.requires || []).forEach(required => load(required, name));
         plugin(server);
     };
-    [].concat(plugins || []).forEach(load);
+    [].concat(plugins || []).forEach(entry => load(entry));
     server.emit('pluginsLoaded');
 }
 export default loadPlugins;

package/dist/esm/plugins/binary.js

@@ -103,7 +103,8 @@ function getDecodedSection(connection, message, query) {
     }
     const node = resolveNode(getMessageData(message).tree, section[0].value, connection.messageGlobal);
     if (!node) {
-        // like BODY[<section>], a part that does not exist is empty
+        // like BODY[<section>], a part that does not exist is empty: RFC 3516 and RFC 9051 section 6.4.5 define no
+        // error for it, and BINARY follows the semantics of BODY (RFC 3516 section 4.2)
         return '';
     }
     if (!isLeaf(node, connection.messageGlobal)) {

package/dist/esm/plugins/context-search.js

@@ -246,8 +246,8 @@ export default function contextSearchPlugin(server) {
         // knows the current message list, so new matches can be reported after their EXISTS and FETCH responses
         // (RFC 5267 section 4.3.2). A command that closes the mailbox gets no updates, its tagged response ends them
         const processNotifications = connection.processNotifications;
-        connection.processNotifications = function (data) {
-            processNotifications.call(this, data);
+        connection.processNotifications = function (data, beforeCommand) {
+            processNotifications.call(this, data, beforeCommand);
             const command = ((data && data.command) || '').toUpperCase();
             if (this.searchContexts && this.searchContexts.size && !this.notificationQueue.length && !CLOSING_COMMANDS.has(command)) {
                 checkContexts(this);

package/dist/esm/plugins/create-special-use.d.ts

@@ -1,7 +1,2 @@
 import type { IMAPServer } from '../types.js';
-/**
- * @help Enables CREATE-SPECIAL-USE [RFC6154] capability
- * @help Allowed special flags can be set with server
- * @help option "special-use"
- */
 export default function createSpecialUsePlugin(server: IMAPServer): void;

package/dist/esm/plugins/create-special-use.js

@@ -1,8 +1,12 @@
+import formalSyntax from 'imap-handler/lib/formal';
+import { isAtom } from '../arguments.js';
 /**
  * @help Enables CREATE-SPECIAL-USE [RFC6154] capability
  * @help Allowed special flags can be set with server
  * @help option "special-use"
  */
+// use-attr-ext = "\" atom (RFC 6154 section 6), with the ATOM-CHAR of the imap-handler grammar (RFC 3501 section 9)
+const USE_ATTR = new RegExp('^\\\\[' + formalSyntax['ATOM-CHAR']().replace(/[\\\]^-]/g, '\\$&') + ']+$');
 export default function createSpecialUsePlugin(server) {
     // Register capability
     server.registerCapability('CREATE-SPECIAL-USE');
@@ -31,7 +35,10 @@ export default function createSpecialUsePlugin(server) {
         }
         if (specialUseList) {
             for (i = 0, len = specialUseList.length; i < len; i++) {
-                if (['ATOM', 'STRING', 'LITERAL'].indexOf(specialUseList[i].type) < 0) {
+                // RFC 6154 section 6: use-attr-ext = "\" atom, so every entry is an atom that starts with a backslash,
+                // not NIL, a string, a literal, a number or a list
+                const entry = specialUseList[i];
+                if (!isAtom(entry) || !USE_ATTR.test(entry.value)) {
                     connection.send({
                         tag: parsed.tag,
                         command: 'BAD',

package/dist/esm/plugins/imap4rev2.js

@@ -122,6 +122,11 @@ export default function imap4rev2Plugin(server) {
         }, 'SELECT LIST', parsed, data, mailbox);
     };
     server.outputHandlers.push((connection, response, description, parsed, data) => {
+        if (description === 'RECENT NOTIFICATION' && isRev2(connection)) {
+            // Appendix E item 12: no RECENT response after the EXISTS of new messages either
+            response.skipResponse = true;
+            return;
+        }
         if (!parsed || !response || !isRev2(connection)) {
             return;
         }

package/dist/esm/plugins/metadata-server.d.ts

@@ -1,7 +1,11 @@
 import type { IMAPServer } from '../types.js';
 /**
  * @help Adds METADATA-SERVER [RFC5464] capability, like METADATA but
- * @help only for server annotations (mailbox name ""). With METADATA
+ * @help only for server annotations (mailbox name ""), loads ENABLE. With METADATA
  * @help also loaded, only METADATA is advertised
  */
-export default function metadataServerPlugin(server: IMAPServer): void;
+declare function metadataServerPlugin(server: IMAPServer): void;
+declare namespace metadataServerPlugin {
+    var requires: string[];
+}
+export default metadataServerPlugin;

package/dist/esm/plugins/metadata-server.js

@@ -1,9 +1,11 @@
 import { setup } from './metadata.js';
 /**
  * @help Adds METADATA-SERVER [RFC5464] capability, like METADATA but
- * @help only for server annotations (mailbox name ""). With METADATA
+ * @help only for server annotations (mailbox name ""), loads ENABLE. With METADATA
  * @help also loaded, only METADATA is advertised
  */
 export default function metadataServerPlugin(server) {
     setup(server, false);
 }
+// RFC 5464 section 4.1: a server that sends unsolicited METADATA responses "MUST support the ENABLE command"
+metadataServerPlugin.requires = ['ENABLE'];

package/dist/esm/plugins/metadata.d.ts

@@ -7,5 +7,9 @@ import type { IMAPServer } from '../types.js';
  * @param {Boolean} mailboxes If true, mailbox annotations are supported, otherwise only server annotations
  */
 declare function setup(server: IMAPServer, mailboxes: boolean): void;
-export default function metadataPlugin(server: IMAPServer): void;
+declare function metadataPlugin(server: IMAPServer): void;
+declare namespace metadataPlugin {
+    var requires: string[];
+}
+export default metadataPlugin;
 export { setup };

package/dist/esm/plugins/metadata.js

@@ -11,6 +11,7 @@ import { registerEnable, isEnabled } from './enable.js';
  * @help default 65536), "metadataMaxEntries" (per mailbox and for the
  * @help server, default 100). "metadataPrivate": false turns /private
  * @help entries off. ENABLE METADATA turns on unsolicited METADATA responses
+ * @help (loads the ENABLE plugin, RFC 5464 section 4.1)
  */
 // Default limits, RFC 5464 section 4.1 requires at least 1024 octets and 10 entries
 const DEFAULT_MAX_SIZE = 64 * 1024;
@@ -501,4 +502,6 @@ function setup(server, mailboxes) {
 export default function metadataPlugin(server) {
     setup(server, true);
 }
+// RFC 5464 section 4.1: a server that sends unsolicited METADATA responses "MUST support the ENABLE command"
+metadataPlugin.requires = ['ENABLE'];
 export { setup };

package/dist/esm/quirks.d.ts

@@ -19,10 +19,10 @@ export declare const quirks: Record<string, Quirk>;
  * Resolves the `quirks` option
  *
  * @param {Array|String} names Quirk names
- * @return {Object} `{ rules, removePlugins }` of all of them
+ * @return {Object} `{ rules, removePlugins }` of all of them, removePlugins maps a plugin name to the quirk that removes it
  * @throws {Error} for an unknown name
  */
 export declare function resolveQuirks(names: string[] | string | null | undefined): {
     rules: ScriptRule[];
-    removePlugins: Set<string>;
+    removePlugins: Map<string, string>;
 };

package/dist/esm/quirks.js

@@ -102,19 +102,20 @@ export const quirks = {
  * Resolves the `quirks` option
  *
  * @param {Array|String} names Quirk names
- * @return {Object} `{ rules, removePlugins }` of all of them
+ * @return {Object} `{ rules, removePlugins }` of all of them, removePlugins maps a plugin name to the quirk that removes it
  * @throws {Error} for an unknown name
  */
 export function resolveQuirks(names) {
     const rules = [];
-    const removePlugins = new Set();
+    const removePlugins = new Map();
     [].concat(names || []).forEach(name => {
-        const quirk = Object.hasOwn(quirks, String(name).toLowerCase()) ? quirks[String(name).toLowerCase()] : null;
+        const key = String(name).toLowerCase();
+        const quirk = Object.hasOwn(quirks, key) ? quirks[key] : null;
         if (!quirk) {
             throw new Error('Unknown quirk "' + name + '". Available quirks: ' + Object.keys(quirks).join(', '));
         }
         rules.push(...(quirk.rules || []));
-        (quirk.removePlugins || []).forEach(plugin => removePlugins.add(plugin));
+        (quirk.removePlugins || []).forEach(plugin => removePlugins.set(plugin, key));
     });
     return { rules, removePlugins };
 }

package/dist/esm/rest.d.ts

@@ -8,6 +8,10 @@
 import http from 'node:http';
 import type { IMAPServer } from './types.js';
 import type { ControlRoute as Route } from './control.js';
+/** The HTTP server of the REST API, `endStreams()` ends the open event streams */
+type RestServer = http.Server & {
+    endStreams?: () => void;
+};
 /** Options of the REST API, the `rest` server option */
 interface RestOptions {
     port?: number | undefined;
@@ -29,7 +33,7 @@ declare function isLoopback(host: string): boolean;
  * @param {Object} server IMAP server
  * @return {Array} routes
  */
-declare function getRoutes(server: IMAPServer): Route[];
+declare function getRoutes(server: IMAPServer, streams?: Set<http.ServerResponse>): Route[];
 /**
  * Describes the routes as an OpenAPI 3.1 document
  *
@@ -45,6 +49,6 @@ declare function openApi(routes: Route[]): Record<string, unknown>;
  * @return {Object} HTTP server
  * @throws {Error} for a host that is not a loopback address without a token
  */
-declare function createRestServer(server: IMAPServer, options: RestOptions): http.Server;
+declare function createRestServer(server: IMAPServer, options: RestOptions): RestServer;
 export { createRestServer, isLoopback, getRoutes, openApi };
-export type { RestOptions };
+export type { RestOptions, RestServer };

package/dist/esm/rest.js

@@ -98,8 +98,9 @@ function eventData(type, args) {
  * @param {Array} types Event types to send
  * @return {Function} writes the stream to a response
  */
-function eventStream(server, types) {
+function eventStream(server, types, streams) {
     return (res, req) => {
+        streams.add(res);
         res.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store' });
         res.write(': connected\n\n');
         const listeners = types.map(type => {
@@ -111,6 +112,7 @@ function eventStream(server, types) {
         const ping = setInterval(() => res.write(': ping\n\n'), 15000);
         ping.unref();
         req.on('close', () => {
+            streams.delete(res);
             clearInterval(ping);
             listeners.forEach(({ type, listener }) => server.removeListener(type, listener));
         });
@@ -122,7 +124,7 @@ function eventStream(server, types) {
  * @param {Object} server IMAP server
  * @return {Array} routes
  */
-function getRoutes(server) {
+function getRoutes(server, streams = new Set()) {
     const control = server.control;
     const ruleJson = (handle) => ({ id: handle.id, rule: handle.rule, matched: handle.matched, hits: handle.hits });
     const routes = [
@@ -158,7 +160,7 @@ function getRoutes(server) {
                 if (unknown.length) {
                     throw storeError('Unknown event type ' + unknown.join(', ') + ', expected ' + EVENT_TYPES.join(', '), 'INVALID');
                 }
-                return { stream: eventStream(server, types) };
+                return { stream: eventStream(server, types, streams) };
             }
         },
         {
@@ -499,7 +501,9 @@ function createRestServer(server, options) {
     if (!token && !isLoopback(host)) {
         throw new Error('The REST API controls the whole server, it needs a token (rest.token, --rest-token) to listen on ' + host);
     }
-    const routes = getRoutes(server);
+    // open event streams, a shutdown ends them so that the server can close
+    const streams = new Set();
+    const routes = getRoutes(server, streams);
     const send = (res, status, body) => {
         const json = JSON.stringify(body);
         res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(json), 'Cache-Control': 'no-store' });
@@ -539,7 +543,7 @@ function createRestServer(server, options) {
         }
         send(res, 200, result === undefined ? {} : result);
     };
-    return http.createServer((req, res) => {
+    const rest = http.createServer((req, res) => {
         handle(req, res).catch((err) => {
             const code = err instanceof ImapKitError ? err.code : 'SERVERERROR';
             // RFC 5530 codes of failed mailbox operations (CANNOT, HASCHILDREN ...) are conflicts with the state
@@ -549,5 +553,7 @@ function createRestServer(server, options) {
             }
         });
     });
+    rest.endStreams = () => streams.forEach(res => res.end());
+    return rest;
 }
 export { createRestServer, isLoopback, getRoutes, openApi };

package/dist/esm/server.d.ts

@@ -1,10 +1,10 @@
 import { Stream } from 'node:stream';
 import net from 'node:net';
-import http from 'node:http';
 import tls from 'node:tls';
 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 type { SessionInfo } from './control.js';
 import { ServerScript } from './script.js';
 import type { DeferredOutput, OutputOperation, ScriptContext, ScriptEvent, ScriptRule } from './script.js';
@@ -85,7 +85,7 @@ declare class IMAPServer extends Stream {
     /** 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: http.Server | null;
+    restServer: RestServer | null;
     constructor(options?: IMAPServerOptions);
     /**
      * Sets the users from the `users` option, or the default user. The users are deep copied, so that runtime changes
@@ -370,6 +370,25 @@ declare class IMAPServer extends Stream {
      * @param {Array} flags Flags of a message
      */
     rememberFlags(mailbox: Mailbox, flags: string[]): void;
+    /**
+     * Checks if a flag can be stored on messages of a mailbox: any flag when the mailbox allows new keywords
+     * (PERMANENTFLAGS has `\*`), otherwise only a flag in the PERMANENTFLAGS list that getStatus() builds, the
+     * `permanentFlags` of the mailbox and every flag its messages had. RFC 3501 section 7.1 (RFC 9051 section 7.1):
+     * PERMANENTFLAGS "indicates which of the known flags the client can change permanently", STORE ignores the others
+     *
+     * @param {Object} mailbox Mailbox object
+     * @param {String} flag Normalized flag
+     * @return {Boolean} true if the flag is a permanent flag of the mailbox
+     */
+    isPermanentFlag(mailbox: Mailbox, flag: string): boolean;
+    /**
+     * The flags of the PERMANENTFLAGS list (without `\*`): the `permanentFlags` of the mailbox and every flag its
+     * messages have or had (`knownFlags`, see rememberFlags)
+     *
+     * @param {Object} mailbox Mailbox object
+     * @return {Array} flags, a new list
+     */
+    permanentFlagList(mailbox: Mailbox): string[];
     /**
      * The current time for dates the server sets itself (INTERNALDATE of a message without one, SAVEDATE). The `now`
      * option fixes it for repeatable tests: a Date, a timestamp, or a function that returns one
@@ -548,6 +567,8 @@ interface QueuedCommand {
         rule: ScriptRule;
         context: ScriptContext;
     } | undefined;
+    /** handler for a command that has no registered one (AUTHENTICATE with an unknown mechanism) */
+    handler?: CommandHandler | undefined;
 }
 declare class IMAPConnection {
     [key: string]: any;
@@ -921,7 +942,36 @@ declare class IMAPConnection {
      * @return {Array} Notifications to send
      */
     prepareNotifications(queue: Notification[]): Notification[];
-    processNotifications(data?: CommandContext | null): void;
+    /**
+     * Checks if EXPUNGE responses must wait while a command runs: during FETCH, STORE and SEARCH (RFC 3501 section
+     * 7.4.1), during the commands that extensions add to this list (see the noExpunge command option), and during UID
+     * SEARCH with message numbers in the search criteria (RFC 7162 section 3.2.10.2 for VANISHED, EXPUNGE may wait as
+     * well, RFC 3501 only allows it during UID commands)
+     *
+     * @param {Object} data Parsed command
+     * @return {Boolean} true if the command holds back EXPUNGE responses
+     */
+    holdsExpunge(data: CommandContext): boolean;
+    /**
+     * Sends the queued notifications. During a command that holds back EXPUNGE responses (see holdsExpunge), or with
+     * `beforeCommand` before a command that refers to messages by sequence number, only the notifications queued before
+     * the first pending EXPUNGE go out: new messages (EXISTS) and flag changes. RFC 3501 section 5.2: "A server MUST send
+     * mailbox size updates automatically if a mailbox size change is observed during the processing of a command",
+     * section 7.4.1 forbids only EXPUNGE during FETCH, STORE and SEARCH. What was queued after the EXPUNGE waits with it,
+     * an EXISTS sent before it would describe a list that the client can not know yet
+     *
+     * @param {Object} [data] Parsed command that runs, or null between commands
+     * @param {Boolean} [beforeCommand] true when the command has not run yet, then a command with message sequence
+     *     numbers (COPY, MOVE) also waits with the EXPUNGE responses, its numbers refer to the messages before them
+     */
+    processNotifications(data?: CommandContext | null, beforeCommand?: boolean): void;
+    /**
+     * Sends an untagged RECENT response with the number of \Recent messages among the first `count` messages
+     *
+     * @param {Number} count Number of messages the client was told about
+     * @param {Map} sequence Message to the sequence number this session knows it by
+     */
+    sendRecent(count: number, sequence: Map<Message, number>): void;
     /**
      * Compile a command object to a response string and write it to socket.
      * If the command object has a skipResponse property, the command is
@@ -990,6 +1040,7 @@ declare class IMAPConnection {
      * @return {Boolean} true if the command uses message sequence numbers
      */
     usesSequenceNumbers(parsed: CommandContext): boolean;
+    findSequenceNumbers(parsed: CommandContext): boolean;
     /**
      * Decodes a SASL client response. It must be valid base64 by the RFC 3501 section 9 grammar,
      * "=" stands for an empty initial response (RFC 4959 section 3).