imapkit 4.3.1 → 5.0.1

package/dist/esm/store-operations.js

@@ -0,0 +1,410 @@
+/**
+ * Changes of the message store that IMAP commands and the control API share: expunge, flag changes, and the
+ * mailbox operations of DELETE, RENAME, SUBSCRIBE and UNSUBSCRIBE. Each one tells the sessions about the change
+ * the way another session's command would (EXISTS, EXPUNGE, unsolicited FETCH, BYE, `mailbox` events). The
+ * session that caused a change is `server.activeConnection` (null for the control API), the commands keep only
+ * what is specific to a session: argument checks, the selected mailbox, read-only state and the responses.
+ */
+import { normalizeSystemFlag, checkSystemFlags } from './commands/handlers/flags.js';
+import { seededRandom } from './random.js';
+import { MAX_NUMBER } from './numbers.js';
+/**
+ * the deprecated XOAUTH2 session timeout of the default user, and of a user the control API adds without one. It is
+ * stored and listed but never used, access tokens do not expire
+ */
+const DEFAULT_SESSION_TIMEOUT = 3600 * 1000;
+/** An error of a failed store operation or control API call, `code` is a RFC 5530 response code or INVALID */
+class ImapKitError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = 'ImapKitError';
+        this.code = code;
+    }
+}
+/**
+ * Creates an error for a failed operation, with a RFC 5530 response code
+ *
+ * @param {String} message Error message
+ * @param {String} code Response code, e.g. "NONEXISTENT"
+ * @return {Error} Error object
+ */
+function storeError(message, code) {
+    return new ImapKitError(message, code);
+}
+/**
+ * Removes messages from a mailbox and tells the sessions that have it selected with EXPUNGE responses
+ * (VANISHED with QRESYNC) and a new EXISTS. The `expunge` event goes out before the notifications
+ *
+ * @param {Object} server IMAP server
+ * @param {Object} mailbox Mailbox of the messages
+ * @param {Array|Function} messagesOrFilterFunc Messages to remove, or a function that returns true for them
+ * @param {Object} [options] `{ origin, skip, skipExists, highestFirst }`
+ * @return {Array} the removed messages
+ */
+function expungeMessages(server, mailbox, messagesOrFilterFunc, options = {}) {
+    let filterFunc;
+    if (Array.isArray(messagesOrFilterFunc)) {
+        const messageSet = new Set(messagesOrFilterFunc);
+        filterFunc = (message) => messageSet.has(message);
+    }
+    else {
+        filterFunc = messagesOrFilterFunc;
+    }
+    // sequence numbers of the removed messages, each one as it is after the earlier EXPUNGE responses. From the
+    // highest message down, the earlier responses do not change the sequence numbers of the later ones
+    const expunged = [];
+    const kept = [];
+    mailbox.messages.forEach((message, i) => {
+        if (filterFunc(message)) {
+            message.ghost = true;
+            expunged.push({ seq: options.highestFirst ? i + 1 : kept.length + 1, message });
+        }
+        else {
+            kept.push(message);
+        }
+    });
+    if (!expunged.length) {
+        return [];
+    }
+    // old copy is required for those sessions that run FETCH before
+    // displaying the EXPUNGE notice
+    const mailboxCopy = mailbox.messages.slice();
+    // update the list in place, other code might hold a reference to it
+    kept.forEach((message, i) => {
+        mailbox.messages[i] = message;
+    });
+    mailbox.messages.length = kept.length;
+    const messages = expunged.map(entry => entry.message);
+    const origin = options.origin !== undefined ? options.origin : server.activeConnection;
+    // lets plugins track the removal (e.g. mod-sequences of CONDSTORE and QRESYNC) before any notification
+    server.emit('expunge', mailbox, messages, origin);
+    (options.highestFirst ? expunged.slice().reverse() : expunged).forEach(entry => {
+        server.notify({
+            tag: '*',
+            attributes: [
+                entry.seq,
+                {
+                    type: 'ATOM',
+                    value: 'EXPUNGE'
+                }
+            ],
+            // the removed message, for plugins that report it differently (e.g. VANISHED of QRESYNC)
+            message: entry.message
+        }, mailbox, options.skip);
+    });
+    server.notify({
+        tag: '*',
+        attributes: [
+            mailbox.messages.length,
+            {
+                type: 'ATOM',
+                value: 'EXISTS'
+            }
+        ],
+        // distribute the old mailbox data with the notification
+        mailboxCopy: mailboxCopy
+    }, mailbox, options.skip || options.skipExists);
+    return messages;
+}
+/**
+ * Tells the sessions that have a mailbox selected about changed flags, they get an untagged FETCH with the
+ * new flags (RFC 3501 section 5.2)
+ *
+ * @param {Object} server IMAP server
+ * @param {Object} mailbox Mailbox of the messages
+ * @param {Array} messages Messages with changed flags
+ * @param {Object} [ignoreConnection] A session that is not told, e.g. the one whose STORE changed the flags
+ */
+function notifyFlagChanges(server, mailbox, messages, ignoreConnection) {
+    if (messages.length) {
+        server.notify({ tag: '*', flagUpdate: messages }, mailbox, ignoreConnection);
+    }
+}
+/**
+ * Checks flags the way STORE does: system flags the server knows (never \Recent), valid keywords, and only
+ * permanent flags in a mailbox that does not allow new keywords
+ *
+ * @param {Object} server IMAP server
+ * @param {Object} mailbox Mailbox the flags are for
+ * @param {Array} flags Flags to check
+ * @param {Boolean} stored true if the flags are stored, so they must be permanent flags of the mailbox
+ * @return {Array} the normalized flags without duplicates
+ * @throws {Error} INVALID for a flag that can not be used
+ */
+function checkFlags(server, mailbox, flags, stored) {
+    if (!Array.isArray(flags)) {
+        throw storeError('Flags must be an array', 'INVALID');
+    }
+    const list = [];
+    flags.forEach((value) => {
+        if (typeof value !== 'string') {
+            throw storeError('Flags must be strings', 'INVALID');
+        }
+        const flag = normalizeSystemFlag(value);
+        try {
+            checkSystemFlags(server, flag);
+        }
+        catch (err) {
+            throw storeError(err.message, 'INVALID');
+        }
+        if (stored && !server.isPermanentFlag(mailbox, flag)) {
+            throw storeError('Flag ' + flag + ' is not a permanent flag of ' + mailbox.path, 'INVALID');
+        }
+        if (list.indexOf(flag) < 0) {
+            list.push(flag);
+        }
+    });
+    return list;
+}
+/**
+ * Changes the flags of messages outside of a STORE command. The flags follow the rules of STORE: system flags
+ * the server knows (never \Recent), valid keywords, and only permanent flags in a mailbox that does not allow
+ * new keywords. Plugins learn about the changed messages from the `flags` event `(mailbox, messages, origin)`
+ * before the sessions are told (CONDSTORE gives them new mod-sequences there)
+ *
+ * @param {Object} server IMAP server
+ * @param {Object} mailbox Mailbox of the messages
+ * @param {Array} messages Messages to change
+ * @param {Array} flags Flags to set, add or remove
+ * @param {String} mode "set", "add" or "remove"
+ * @return {Array} the messages whose flags changed
+ */
+function changeFlags(server, mailbox, messages, flags, mode) {
+    if (['set', 'add', 'remove'].indexOf(mode) < 0) {
+        throw storeError('Invalid flag mode ' + JSON.stringify(mode) + ', expected set, add or remove', 'INVALID');
+    }
+    const list = checkFlags(server, mailbox, flags, mode !== 'remove');
+    const changed = [];
+    messages.forEach(message => {
+        const before = message.flags.join(' ');
+        if (mode === 'set') {
+            message.flags = list.slice();
+        }
+        else if (mode === 'add') {
+            list.forEach(flag => server.ensureFlag(message.flags, flag));
+        }
+        else {
+            list.forEach(flag => server.removeFlag(message.flags, flag));
+        }
+        server.rememberFlags(mailbox, message.flags);
+        if (message.flags.join(' ') !== before) {
+            changed.push(message);
+        }
+    });
+    if (changed.length) {
+        server.emit('flags', mailbox, changed, server.activeConnection);
+        notifyFlagChanges(server, mailbox, changed, null);
+    }
+    return changed;
+}
+/**
+ * Creates a mailbox (CREATE), with any missing superior hierarchy levels
+ *
+ * @param {Object} server IMAP server
+ * @param {String} path Storage name of the mailbox
+ * @return {Object} the created mailbox
+ * @throws {Error} with a RFC 5530 `code` (ALREADYEXISTS, CANNOT ...)
+ */
+function createMailbox(server, path) {
+    const existing = new Set(Object.keys(server.folderCache));
+    const mailbox = server.createMailbox(path);
+    // the superior levels that did not exist are new mailboxes as well, plugins set them up like the target (ACL)
+    const created = Object.keys(server.folderCache)
+        .filter(name => !existing.has(name))
+        .sort((a, b) => a.length - b.length);
+    server.mailboxChanged('create', mailbox.path, { created });
+    return mailbox;
+}
+/**
+ * Deletes a mailbox (DELETE). Other sessions that have it selected are disconnected with an untagged BYE
+ * (RFC 2180 section 3.3, RFC 2683 section 3.1.2), as they can not be told about the deletion in any other way
+ *
+ * @param {Object} server IMAP server
+ * @param {String} path Storage name of the mailbox
+ * @throws {Error} with a response `code` (NONEXISTENT, CANNOT, HASCHILDREN ...)
+ */
+function deleteMailbox(server, path) {
+    const mailbox = server.getMailbox(path);
+    if (!mailbox) {
+        throw storeError('Mailbox does not exist', 'NONEXISTENT');
+    }
+    server.deleteMailbox(path);
+    server.mailboxChanged('delete', mailbox.path, { mailbox });
+    byeSelected(server, mailbox, 'Selected mailbox was deleted', 'MAILBOX DELETED');
+}
+/**
+ * Disconnects the sessions that have a mailbox selected with an untagged BYE, except the one that made the change
+ *
+ * @param {Object} server IMAP server
+ * @param {Object} mailbox Mailbox
+ * @param {String} text Text of the BYE
+ * @param {String} description Description for output handlers
+ */
+function byeSelected(server, mailbox, text, description) {
+    const origin = server.activeConnection;
+    server.connections.forEach(connection => {
+        if (connection !== origin && connection.selectedMailbox === mailbox) {
+            connection.bye(text, description);
+        }
+    });
+}
+/**
+ * Renames a mailbox (RENAME). Renaming INBOX moves its messages to the new mailbox and leaves INBOX
+ * empty (RFC 3501 section 6.3.5). Everything that can be checked is checked up front, so that a failed
+ * rename never loses the source
+ *
+ * @param {Object} server IMAP server
+ * @param {String} source Storage name of the mailbox
+ * @param {String} destination New storage name
+ * @return {Object} `{ path, mailbox }`: the new name, and the source mailbox object, which is INBOX itself for
+ *   a rename of INBOX
+ * @throws {Error} with a RFC 5530 `code` (NONEXISTENT, ALREADYEXISTS, CANNOT ...)
+ */
+function renameMailbox(server, source, destination) {
+    const mailbox = server.getMailbox(source);
+    const target = server.getMailbox(destination);
+    if (!mailbox || mailbox.flags.indexOf('\\Noselect') >= 0) {
+        throw storeError('Mailbox does not exist', 'NONEXISTENT');
+    }
+    if (target && target.flags.indexOf('\\Noselect') < 0) {
+        throw storeError('Mailbox already exists', 'ALREADYEXISTS');
+    }
+    const separator = server.getSeparator(mailbox);
+    if (destination.substr(0, mailbox.path.length + separator.length) === mailbox.path + separator) {
+        throw storeError('Can not move a mailbox into itself', 'CANNOT');
+    }
+    const oldPath = mailbox.path;
+    let path;
+    if (source.toUpperCase() === 'INBOX') {
+        const renamed = server.createMailbox(destination);
+        path = renamed.path;
+        mailbox.messages.forEach((message) => {
+            server.copyMessage(renamed, message);
+        });
+        expungeMessages(server, mailbox, () => true);
+    }
+    else {
+        server.deleteMailbox(source, true);
+        try {
+            server.createMailbox(destination, mailbox);
+        }
+        catch (E) {
+            // put the source mailbox back where it was
+            server.createMailbox(source, mailbox);
+            server.indexFolders();
+            throw E;
+        }
+        server.indexFolders();
+        path = mailbox.path;
+    }
+    server.mailboxChanged('rename', path, { oldPath });
+    return { path, mailbox };
+}
+/**
+ * Gives a mailbox a new UIDVALIDITY, optionally with new UIDs. A UID never changes during a session (RFC 9051
+ * section 2.3.1.1), so the sessions that have the mailbox selected are disconnected with BYE, and the new value
+ * is greater than every earlier one, as UIDs that do not persist require. A client that keeps its cached UIDs
+ * without checking UIDVALIDITY gets other messages ("shuffle") or none ("offset") for them
+ *
+ * @param {Object} server IMAP server
+ * @param {Object} mailbox Mailbox, not \Noselect
+ * @param {Object} [options] `{ uidvalidity, uids, offset, seed }`
+ * @return {Object} `{ uidvalidity, uidnext, uids }`, `uids` maps every old UID to its new one
+ * @throws {Error} INVALID for a UIDVALIDITY that is not greater, or invalid options
+ */
+function resetUidValidity(server, mailbox, options = {}) {
+    const mode = options.uids || 'keep';
+    if (['keep', 'renumber', 'shuffle', 'offset'].indexOf(mode) < 0) {
+        throw storeError('Invalid UID mode ' + JSON.stringify(mode) + ', expected keep, renumber, shuffle or offset', 'INVALID');
+    }
+    const offset = options.offset === undefined ? 0 : options.offset;
+    if (!Number.isSafeInteger(offset) || offset < 0) {
+        throw storeError('Offset must be a non-negative integer', 'INVALID');
+    }
+    let uidvalidity = options.uidvalidity;
+    if (uidvalidity === undefined) {
+        uidvalidity = Math.max(mailbox.uidvalidity, server.uidvalidityCounter) + 1;
+    }
+    else if (!Number.isSafeInteger(uidvalidity) || uidvalidity <= mailbox.uidvalidity || uidvalidity > 0xffffffff) {
+        // nz-number of RFC 3501 section 9, a 32-bit value
+        throw storeError('UIDVALIDITY must be an integer above ' + mailbox.uidvalidity + ' and below 2^32', 'INVALID');
+    }
+    if (options.seed !== undefined && !Number.isSafeInteger(options.seed)) {
+        throw storeError('Seed must be an integer', 'INVALID');
+    }
+    byeSelected(server, mailbox, 'UIDVALIDITY of the selected mailbox changed', 'UIDVALIDITY CHANGED');
+    const messages = mailbox.messages;
+    const oldUids = messages.map(message => message.uid);
+    let newUids = oldUids;
+    if (mode === 'renumber' || mode === 'shuffle') {
+        newUids = messages.map((message, i) => i + 1);
+        if (mode === 'shuffle') {
+            const random = seededRandom(options.seed === undefined ? Math.floor(Math.random() * MAX_NUMBER) : options.seed);
+            // Fisher-Yates
+            for (let i = newUids.length - 1; i > 0; i--) {
+                const j = Math.floor(random() * (i + 1));
+                [newUids[i], newUids[j]] = [newUids[j], newUids[i]];
+            }
+        }
+        mailbox.uidnext = messages.length + 1;
+    }
+    else if (mode === 'offset') {
+        const shift = mailbox.uidnext - 1 + offset;
+        newUids = oldUids.map(uid => uid + shift);
+        mailbox.uidnext += shift;
+    }
+    messages.forEach((message, i) => {
+        message.uid = newUids[i];
+    });
+    if (mode === 'shuffle') {
+        // the other modes keep the UID order
+        messages.sort((a, b) => a.uid - b.uid);
+    }
+    mailbox.uidvalidity = uidvalidity;
+    server.uidvalidityCounter = Math.max(server.uidvalidityCounter, uidvalidity);
+    return {
+        uidvalidity,
+        uidnext: mailbox.uidnext,
+        uids: oldUids.map((uid, i) => ({ uid, newUid: newUids[i] }))
+    };
+}
+/**
+ * Subscribes a mailbox (SUBSCRIBE), only an existing mailbox can be subscribed
+ *
+ * @param {Object} server IMAP server
+ * @param {String} path Storage name of the mailbox
+ * @return {Boolean} true if the subscription changed
+ * @throws {Error} NONEXISTENT for a name that is not a mailbox
+ */
+function subscribeMailbox(server, path) {
+    const mailbox = server.getMailbox(path);
+    if (!mailbox || mailbox.flags.indexOf('\\Noselect') >= 0) {
+        throw storeError('Mailbox does not exist', 'NONEXISTENT');
+    }
+    if (mailbox.subscribed) {
+        return false;
+    }
+    mailbox.subscribed = true;
+    server.mailboxChanged('subscribe', mailbox.path);
+    return true;
+}
+/**
+ * Unsubscribes a name (UNSUBSCRIBE). The subscription list holds names, so a name stays removable after its
+ * mailbox is deleted (RFC 3501 section 6.3.6). Removing a name that is not subscribed is not an error
+ * (RFC 9051 section 6.3.8)
+ *
+ * @param {Object} server IMAP server
+ * @param {String} path Storage name
+ * @return {Boolean} true if the subscription changed
+ */
+function unsubscribeMailbox(server, path) {
+    if (path.toUpperCase() === 'INBOX') {
+        path = 'INBOX';
+    }
+    if (!server.subscriptions.delete(path)) {
+        return false;
+    }
+    server.mailboxChanged('unsubscribe', path);
+    return true;
+}
+export { DEFAULT_SESSION_TIMEOUT, ImapKitError, storeError, expungeMessages, notifyFlagChanges, checkFlags, changeFlags, createMailbox, deleteMailbox, renameMailbox, resetUidValidity, subscribeMailbox, unsubscribeMailbox };

package/dist/esm/types.d.ts

@@ -72,6 +72,8 @@ export interface MailboxChangeEvent {
     oldPath: string | null;
     mailbox: Mailbox | null;
     origin: IMAPConnection | null;
+    /** "create": every mailbox the change created, superior hierarchy levels first */
+    created?: string[] | undefined;
 }
 export type Callback = (err?: any, ...args: any[]) => void;
 /** Handler of an IMAP command, it must send a tagged response and then call the callback */
@@ -210,6 +212,10 @@ export interface UserData {
     password?: string | undefined;
     xoauth2?: {
         accessToken?: string | undefined;
+        /**
+         * @deprecated kept from hoodiecrow and ignored: access tokens never expire. Change the token with
+         * `control.updateUser()` to test a client against an expired one
+         */
         sessionTimeout?: number | undefined;
     } | undefined;
     [key: string]: any;
@@ -222,6 +228,18 @@ export interface IMAPServerOptions {
     plugins?: (string | Plugin)[] | string | Plugin | undefined;
     users?: Record<string, UserData> | undefined;
     secureConnection?: boolean | undefined;
+    /** starts an SMTP server with `server.start()` that appends every received message to INBOX, needs the optional
+     * smtp-server package */
+    smtp?: {
+        port?: number | undefined;
+        host?: string | undefined;
+    } | undefined;
+    /** starts the REST API with `server.start()`, see src/rest.ts. A host other than a loopback address needs a token */
+    rest?: {
+        port?: number | undefined;
+        host?: string | undefined;
+        token?: string | undefined;
+    } | undefined;
     credentials?: {
         key: string | Buffer;
         cert: string | Buffer;
@@ -232,6 +250,12 @@ export interface IMAPServerOptions {
     maxLiteralSize?: number | undefined;
     /** script rules that make the server misbehave on purpose, see src/script.ts and README "Scripted faults" */
     script?: ScriptRule | ScriptRule[] | undefined;
+    /** the current time for the dates the server sets (INTERNALDATE, SAVEDATE): a Date, a timestamp or a function */
+    now?: Date | number | (() => Date | number) | undefined;
+    /** quirk presets that make the server behave like a known real server, see src/quirks.ts */
+    quirks?: string[] | string | undefined;
+    /** seed of the random numbers of script rules with `chance`, so that a run can be repeated */
+    scriptSeed?: number | undefined;
     [key: string]: any;
 }
 /**
@@ -318,7 +342,8 @@ export type MessageHandler = (server: IMAPServer, message: Message, mailbox: Mai
 export type MailboxHandler = (server: IMAPServer, mailbox: Mailbox) => void;
 export type CopyHandler = (server: IMAPServer, source: Message, properties: Record<string, any>, mailbox: Mailbox) => void;
 export type NotifyFilter = (connection: IMAPConnection, event: NotifyEvent) => boolean;
-export type AppendCheck = (connection: IMAPConnection, mailbox: Mailbox, messages: AppendMessage[], options: AppendCheckOptions) => CheckResult | false | null | undefined | void;
+/** `server.appendChecks`, `connection` is null for the control API (`addMessage` with `checks`) */
+export type AppendCheck = (connection: IMAPConnection | null, mailbox: Mailbox, messages: AppendMessage[], options: AppendCheckOptions) => CheckResult | false | null | undefined | void;
 export type LiteralFilter = (connection: IMAPConnection, command: string, line: string, size: number) => Refusal | false | null | undefined;
 export type UrlAccessCheck = (connection: IMAPConnection, mailbox: Mailbox, url: any) => {
     text: string;

package/dist/plugin-help.json

@@ -104,7 +104,7 @@
     ],
     "METADATA-SERVER": [
         "Adds METADATA-SERVER [RFC5464] capability, like METADATA but",
-        "only for server annotations (mailbox name \"\"). With METADATA",
+        "only for server annotations (mailbox name \"\"), loads ENABLE. With METADATA",
         "also loaded, only METADATA is advertised"
     ],
     "METADATA": [
@@ -114,7 +114,8 @@
         "\"metadata\" option. Limits: \"metadataMaxSize\" (octets per value,",
         "default 65536), \"metadataMaxEntries\" (per mailbox and for the",
         "server, default 100). \"metadataPrivate\": false turns /private",
-        "entries off. ENABLE METADATA turns on unsolicited METADATA responses"
+        "entries off. ENABLE METADATA turns on unsolicited METADATA responses",
+        "(loads the ENABLE plugin, RFC 5464 section 4.1)"
     ],
     "MOVE": [
         "Adds MOVE [RFC6851] capability"
@@ -280,19 +281,5 @@
         "Valid login info:",
         "  Username: testuser",
         "  Access Token: testtoken"
-    ],
-    "XTOYBIRD": [
-        "Custom plugin to allow programmatic control of the server",
-        "Available commands:",
-        " XTOYBIRD SERVER dumps server internals",
-        " XTOYBIRD CONNECTION dumps connection internals",
-        " XTOYBIRD STORAGE dumps storage as JSON",
-        " XTOYBIRD USERADD \"username\" \"password\" adds or updates user",
-        " XTOYBIRD USERDEL \"username\" removes a user",
-        " XTOYBIRD SHUTDOWN Closes the server after the last client",
-        "                 disconnects. New connections are rejected.",
-        "Commands are only allowed after login, and only for the owner",
-        "(aclOwner option) when ACL is loaded. A test control plugin,",
-        "any user it allows can read and change everything"
     ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapkit",
-    "version": "4.3.1",
+    "version": "5.0.1",
     "description": "Scriptable, strictly RFC compliant in-memory IMAP server for testing IMAP clients",
     "type": "module",
     "main": "./dist/cjs/index.js",
@@ -83,8 +83,7 @@
     "author": "Postal Systems OÜ",
     "license": "MIT",
     "dependencies": {
-        "imap-handler": "1.4.0",
-        "smtp-server": "3.19.17"
+        "imap-handler": "1.4.0"
     },
     "devDependencies": {
         "@eslint/js": "10.0.1",
@@ -95,11 +94,20 @@
         "globals": "17.13.0",
         "imapflow": "2.2.9",
         "prettier": "3.9.9",
+        "smtp-server": "3.19.17",
         "tsx": "4.23.15",
         "typescript": "6.0.3",
         "typescript-eslint": "8.71.1"
     },
     "engines": {
         "node": ">=20.0.0"
+    },
+    "peerDependencies": {
+        "smtp-server": "^3.19.17"
+    },
+    "peerDependenciesMeta": {
+        "smtp-server": {
+            "optional": true
+        }
     }
 }

package/dist/cjs/plugins/xtoybird.d.ts

@@ -1,2 +0,0 @@
-import type { IMAPServer } from '../types.js';
-export default function xtoybirdPlugin(server: IMAPServer): void;