imapkit 5.0.0 → 5.1.0

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,11 +1,12 @@
 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 type { MemorySocket } from './memory-socket.js';
 import { ServerScript } from './script.js';
 import type { DeferredOutput, OutputOperation, ScriptContext, ScriptEvent, ScriptRule } from './script.js';
 import type { AppendCheck, AppendCheckOptions, AppendDataHandler, AppendMessage, CapabilityCheck, CheckResult, ClosedCheck, CommandCheck, CommandContext, CommandOptions, CommandHandler, ConnectionHandler, ConnectionState, CopyHandler, FetchHandler, IMAPResponse, IMAPServerOptions, ListedMailbox, LiteralFilter, Mailbox, MailboxHandler, MailboxStatus, Message, MessageFilter, MessageHandler, MessageRange, Namespace, Notification, NotifyEvent, NotifyFilter, OutputHandler, ParsedCommand, RangeLimit, Refusal, SearchAccessCheck, SearchHandler, SearchLimit, ServerStorage, StatusHandler, StorageMailbox, StorageMessage, StoreHandler, SubscriptionStandIn, Transport, UrlAccessCheck, UserData } from './types.js';
@@ -85,7 +86,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
@@ -158,6 +159,18 @@ declare class IMAPServer extends Stream {
     };
     address(): ReturnType<net.Server['address']>;
     createClient(socket: net.Socket): void;
+    /**
+     * Opens a connection to the server in memory, without a network socket (no `listen()` needed). This is how the
+     * server runs in a browser, see the README "Run in a browser"
+     *
+     * @param {Object} [options] `{ secure }`: false makes the connection a plaintext one, where STARTTLS turns on the
+     *   encryption (nothing is encrypted, the session only counts as encrypted). By default the connection counts as
+     *   one over TLS
+     * @return {MemorySocket} the client end, write commands to it and read the responses from its `data` events
+     */
+    connect(options?: {
+        secure?: boolean | undefined;
+    }): MemorySocket;
     registerCapability(keyword: string, handler?: CapabilityCheck | null): void;
     /**
      * Sets the handler of a command
@@ -370,6 +383,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 +580,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 +955,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 +1053,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).