imapkit 5.0.0 → 5.0.1

package/dist/cjs/load-plugins.js

@@ -49,12 +49,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 ? [index_js_1.plugins[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(index_js_1.plugins[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);
@@ -69,14 +78,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');
 }
 exports.default = loadPlugins;

package/dist/cjs/plugins/binary.js

@@ -109,7 +109,8 @@ function getDecodedSection(connection, message, query) {
     }
     const node = (0, mimeparser_js_1.resolveNode)((0, mimeparser_js_1.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/cjs/plugins/context-search.js

@@ -252,8 +252,8 @@ 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/cjs/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/cjs/plugins/create-special-use.js

@@ -1,11 +1,18 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = createSpecialUsePlugin;
+const formal_1 = __importDefault(require("imap-handler/lib/formal"));
+const arguments_js_1 = require("../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('^\\\\[' + formal_1.default['ATOM-CHAR']().replace(/[\\\]^-]/g, '\\$&') + ']+$');
 function createSpecialUsePlugin(server) {
     // Register capability
     server.registerCapability('CREATE-SPECIAL-USE');
@@ -34,7 +41,10 @@ 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 (!(0, arguments_js_1.isAtom)(entry) || !USE_ATTR.test(entry.value)) {
                     connection.send({
                         tag: parsed.tag,
                         command: 'BAD',

package/dist/cjs/plugins/imap4rev2.js

@@ -128,6 +128,11 @@ 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/cjs/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/cjs/plugins/metadata-server.js

@@ -4,12 +4,14 @@ exports.default = metadataServerPlugin;
 const metadata_js_1 = require("./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
  */
 function metadataServerPlugin(server) {
     (0, metadata_js_1.setup)(server, false);
 }
+// RFC 5464 section 4.1: a server that sends unsolicited METADATA responses "MUST support the ENABLE command"
+metadataServerPlugin.requires = ['ENABLE'];
 {
     const defaultExport = exports.default;
     if (defaultExport && (typeof defaultExport === 'function' || typeof defaultExport === 'object')) {

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

@@ -15,6 +15,7 @@ const enable_js_1 = require("./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;
@@ -505,6 +506,8 @@ function setup(server, mailboxes) {
 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'];
 {
     const defaultExport = exports.default;
     if (defaultExport && (typeof defaultExport === 'function' || typeof defaultExport === 'object')) {

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

@@ -106,19 +106,20 @@ exports.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
  */
 function resolveQuirks(names) {
     const rules = [];
-    const removePlugins = new Set();
+    const removePlugins = new Map();
     [].concat(names || []).forEach(name => {
-        const quirk = Object.hasOwn(exports.quirks, String(name).toLowerCase()) ? exports.quirks[String(name).toLowerCase()] : null;
+        const key = String(name).toLowerCase();
+        const quirk = Object.hasOwn(exports.quirks, key) ? exports.quirks[key] : null;
         if (!quirk) {
             throw new Error('Unknown quirk "' + name + '". Available quirks: ' + Object.keys(exports.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/cjs/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/cjs/rest.js

@@ -107,8 +107,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 => {
@@ -120,6 +121,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));
         });
@@ -131,7 +133,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 = [
@@ -167,7 +169,7 @@ function getRoutes(server) {
                 if (unknown.length) {
                     throw (0, store_operations_js_1.storeError)('Unknown event type ' + unknown.join(', ') + ', expected ' + EVENT_TYPES.join(', '), 'INVALID');
                 }
-                return { stream: eventStream(server, types) };
+                return { stream: eventStream(server, types, streams) };
             }
         },
         {
@@ -508,7 +510,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' });
@@ -548,7 +552,7 @@ function createRestServer(server, options) {
         }
         send(res, 200, result === undefined ? {} : result);
     };
-    return node_http_1.default.createServer((req, res) => {
+    const rest = node_http_1.default.createServer((req, res) => {
         handle(req, res).catch((err) => {
             const code = err instanceof store_operations_js_1.ImapKitError ? err.code : 'SERVERERROR';
             // RFC 5530 codes of failed mailbox operations (CANNOT, HASCHILDREN ...) are conflicts with the state
@@ -558,4 +562,6 @@ function createRestServer(server, options) {
             }
         });
     });
+    rest.endStreams = () => streams.forEach(res => res.end());
+    return rest;
 }

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