imapkit 4.3.1 → 5.0.1

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

@@ -1,10 +1,18 @@
 import createServer, { TAG_REGEX, IMAPServer, IMAPConnection } from './server.js';
-export { TAG_REGEX, IMAPServer, IMAPConnection };
+import { ImapKitError } from './control.js';
+import { quirks } from './quirks.js';
+import { storageSchema, validateStorage } from './storage-schema.js';
+export { TAG_REGEX, IMAPServer, IMAPConnection, ImapKitError, quirks, storageSchema, validateStorage };
 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, 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;
     IMAPConnection: typeof IMAPConnection;
+    ImapKitError: typeof ImapKitError;
+    quirks: Record<string, import("./quirks.js").Quirk>;
 };
 export default imapkit;

package/dist/esm/index.js

@@ -1,6 +1,9 @@
 import createServer, { TAG_REGEX, IMAPServer, IMAPConnection } from './server.js';
-export { TAG_REGEX, IMAPServer, IMAPConnection };
+import { ImapKitError } from './control.js';
+import { quirks } from './quirks.js';
+import { storageSchema, validateStorage } from './storage-schema.js';
+export { TAG_REGEX, IMAPServer, IMAPConnection, ImapKitError, quirks, storageSchema, validateStorage };
 // `imapkit(options)` creates a server. TAG_REGEX was a property of the CommonJS export, it and the
 // classes are properties of the factory with both module formats
-const imapkit = Object.assign(createServer, { TAG_REGEX, IMAPServer, IMAPConnection });
+const imapkit = Object.assign(createServer, { TAG_REGEX, IMAPServer, IMAPConnection, ImapKitError, quirks });
 export default imapkit;

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): 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,13 +46,27 @@ 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) {
+function loadPlugins(server, plugins, exclude) {
     const loaded = new Set();
-    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);
+            if (!name && plugin.toUpperCase() === 'XTOYBIRD') {
+                throw new Error('XTOYBIRD was removed in 5.0.0, use the control API (server.control.snapshot(), server.control.addUser() ...) instead, see the README');
+            }
             if (!name) {
                 throw new Error('Unknown plugin "' + plugin + '". Available plugins: ' + listPlugins().join(', '));
             }
@@ -61,14 +75,24 @@ function loadPlugins(server, plugins) {
         if (typeof plugin !== 'function') {
             throw new TypeError('Invalid plugin, expecting a plugin name or a function');
         }
+        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/acl.js

@@ -5,6 +5,7 @@ import { getListExtensions } from '../list-extensions.js';
 import { beginSelect } from '../commands/select.js';
 import { getPendingTarget } from '../commands/append.js';
 import { isAstring } from '../arguments.js';
+import { storeError } from '../store-operations.js';
 /**
  * @help Adds ACL [RFC4314] capability with RIGHTS=texk
  * @help The owner (server option "aclOwner", default "testuser")
@@ -199,6 +200,33 @@ export default function aclPlugin(server) {
         change(acl);
         server.emit('acl', mailbox, previous);
     };
+    /**
+     * Changes the rights of an identifier like SETACL (RFC 4314 section 3.1): "+" adds, "-" removes, no mode
+     * replaces. An identifier without rights is removed from the ACL
+     *
+     * @param {Object} mailbox Mailbox
+     * @param {String} identifier Identifier
+     * @param {String} mode "+", "-" or ""
+     * @param {Set} rights Parsed rights
+     */
+    const applyRights = (mailbox, identifier, mode, rights) => {
+        changeAcl(mailbox, acl => {
+            const current = new Set(acl.get(identifier) || []);
+            if (mode === '+') {
+                rights.forEach(right => current.add(right));
+            }
+            else if (mode === '-') {
+                rights.forEach(right => current.delete(right));
+            }
+            const updated = mode ? current : rights;
+            if (updated.size) {
+                acl.set(identifier, updated);
+            }
+            else {
+                acl.delete(identifier);
+            }
+        });
+    };
     // CATENATE (RFC 4469 section 5): reading a message through an IMAP URL needs the "r" right, a
     // mailbox without "l" is reported like one that does not exist (RFC 4314 section 6)
     server.urlAccessChecks.push((connection, mailbox) => {
@@ -354,22 +382,7 @@ export default function aclPlugin(server) {
         if (!checkAclCommand(connection, parsed, data, mailbox, hasAdmin) || refuseOwnerIdentifier(connection, parsed, data)) {
             return;
         }
-        changeAcl(mailbox, acl => {
-            const current = new Set(acl.get(identifier) || []);
-            if (mode === '+') {
-                rights.forEach(right => current.add(right));
-            }
-            else if (mode === '-') {
-                rights.forEach(right => current.delete(right));
-            }
-            const updated = mode ? current : rights;
-            if (updated.size) {
-                acl.set(identifier, updated);
-            }
-            else {
-                acl.delete(identifier);
-            }
-        });
+        applyRights(mailbox, identifier, mode, rights);
         connection.sendStatus(parsed, data, 'OK', 'Setacl complete');
     }), Object.assign({ astringArguments: [1, 2] }, aclOptions));
     // RFC 4314 section 3.2
@@ -467,7 +480,7 @@ export default function aclPlugin(server) {
                 }
                 flags = [].concat(flags);
                 // invalid flags are still refused with BAD, even if the user could not set them anyway
-                flags.forEach((flag) => checkSystemFlags(connection, normalizeSystemFlag(flagValue(flag))));
+                flags.forEach((flag) => checkSystemFlags(connection.server, normalizeSystemFlag(flagValue(flag))));
                 let allowed = flags.filter((flag) => canSetFlag(rights, flag));
                 if (item.charAt(0) !== '+' && item.charAt(0) !== '-') {
                     // replacing the flags keeps the ones the user can not change
@@ -562,7 +575,7 @@ export default function aclPlugin(server) {
         const flags = parsed.attributes[1];
         if (Array.isArray(flags) && flags.every((flag) => flag && flag.type === 'ATOM')) {
             try {
-                flags.forEach((flag) => checkSystemFlags(connection, normalizeSystemFlag(flag.value)));
+                flags.forEach((flag) => checkSystemFlags(connection.server, normalizeSystemFlag(flag.value)));
                 // the server MUST NOT fail APPEND for flags the user can not set
                 parsed.attributes[1] = flags.filter((flag) => canSetFlag(rights, flag));
             }
@@ -734,7 +747,7 @@ export default function aclPlugin(server) {
         }
         const flags = [].concat(args[args.length - 1] || []);
         try {
-            flags.forEach(flag => checkSystemFlags(connection, normalizeSystemFlag(flagValue(flag))));
+            flags.forEach(flag => checkSystemFlags(connection.server, normalizeSystemFlag(flagValue(flag))));
         }
         catch {
             // invalid flags are refused with BAD by the STORE handler
@@ -833,38 +846,92 @@ export default function aclPlugin(server) {
             });
         }
     });
-    // The DELETE command MUST delete the ACL of the mailbox (RFC 4314 section 4), this matters when a
-    // \Noselect placeholder stays for the children of the mailbox
-    // DELETE and CREATE are core commands, so the handlers exist
-    const prevDelete = server.getCommandHandler('DELETE');
-    server.setCommandHandler('DELETE', (connection, parsed, data, callback) => {
-        const mailbox = argumentMailbox(parsed, 0);
-        prevDelete(connection, parsed, data, () => {
-            const placeholder = argumentMailbox(parsed, 0);
-            if (placeholder && placeholder !== mailbox) {
+    server.on('mailbox', (event) => {
+        if (event.type === 'delete') {
+            // DELETE MUST delete the ACL of the mailbox (RFC 4314 section 4), this matters when a \Noselect
+            // placeholder stays for the children of the mailbox
+            const placeholder = server.getMailbox(event.path);
+            if (placeholder && placeholder !== event.mailbox) {
                 delete placeholder.acl;
             }
-            callback();
-        });
-    });
-    // A new mailbox inherits the ACL of its parent (RFC 4314 section 4, CREATE SHOULD)
-    const prevCreate = server.getCommandHandler('CREATE');
-    server.setCommandHandler('CREATE', (connection, parsed, data, callback) => {
-        const existing = new Set(Object.keys(server.folderCache));
-        prevCreate(connection, parsed, data, () => {
-            Object.keys(server.folderCache)
-                .filter(path => !existing.has(path))
-                .sort((a, b) => a.length - b.length)
-                .forEach(path => {
+        }
+        else if (event.type === 'create') {
+            // A new mailbox inherits the ACL of its parent (RFC 4314 section 4, CREATE SHOULD)
+            (event.created || []).forEach((path) => {
                 const parent = getParent(path);
                 const mailbox = server.folderCache[path];
-                if (parent && parent !== mailbox) {
+                if (parent && mailbox && parent !== mailbox) {
                     const acl = new Map();
                     getAcl(parent).forEach((rights, identifier) => acl.set(identifier, new Set(rights)));
                     mailbox.acl = acl;
                 }
             });
-            callback();
+        }
+    });
+    // Control API (README "Control API"): ACLs as objects of identifier to rights, like the storage option
+    const aclObject = (mailbox) => {
+        const result = {};
+        getAcl(mailbox).forEach((rights, identifier) => {
+            result[identifier] = formatRights(rights);
         });
+        return result;
+    };
+    const controlMailbox = (path) => server.control.requireMailbox(path);
+    // the snapshot keeps ACLs in the form of the storage option, the parsed ACL is a Map
+    server.control.snapshotHandlers.push((mailbox, copy) => {
+        if (mailbox.acl instanceof Map) {
+            copy.acl = aclObject(mailbox);
+        }
     });
+    const getAclOperation = (path) => aclObject(controlMailbox(path));
+    // rights replace the rights of the identifier, "+rights" adds and "-rights" removes like SETACL (RFC 4314
+    // section 3.1), empty rights remove the identifier
+    const setAclOperation = (path, identifier, rights) => {
+        const mailbox = controlMailbox(path);
+        if (typeof identifier !== 'string' || !identifier || typeof rights !== 'string') {
+            throw storeError('setAcl expects an identifier and a rights string', 'INVALID');
+        }
+        const mode = /^[+-]/.test(rights) ? rights.charAt(0) : '';
+        let parsed;
+        try {
+            parsed = parseRights(rights.substr(mode.length));
+        }
+        catch (err) {
+            throw storeError(err.message, 'INVALID');
+        }
+        applyRights(mailbox, identifier, mode, parsed);
+        return aclObject(mailbox);
+    };
+    const deleteAclOperation = (path, identifier) => {
+        const mailbox = controlMailbox(path);
+        if (typeof identifier !== 'string' || !getAcl(mailbox).has(identifier)) {
+            throw storeError('No ACL entry for ' + JSON.stringify(identifier), 'NONEXISTENT');
+        }
+        changeAcl(mailbox, acl => acl.delete(identifier));
+        return aclObject(mailbox);
+    };
+    server.control.register('getAcl', getAclOperation, [
+        {
+            method: 'GET',
+            path: '/v1/mailboxes/{path}/acl',
+            summary: 'The ACL of a mailbox (ACL plugin)',
+            handler: ({ params }) => server.control.getAcl(params.path)
+        }
+    ]);
+    server.control.register('setAcl', setAclOperation, [
+        {
+            method: 'PUT',
+            path: '/v1/mailboxes/{path}/acl/{identifier}',
+            summary: 'Sets the rights of an identifier ({ rights }, "+" or "-" in front adds or removes, ACL plugin)',
+            handler: ({ params, body }) => server.control.setAcl(params.path, params.identifier, body.rights)
+        }
+    ]);
+    server.control.register('deleteAcl', deleteAclOperation, [
+        {
+            method: 'DELETE',
+            path: '/v1/mailboxes/{path}/acl/{identifier}',
+            summary: 'Removes an identifier from the ACL (ACL plugin)',
+            handler: ({ params }) => server.control.deleteAcl(params.path, params.identifier)
+        }
+    ]);
 }

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/condstore.js

@@ -75,6 +75,13 @@ export default function condstorePlugin(server) {
     server.on('expunge', mailbox => {
         bumpModseq(mailbox);
     });
+    // Flags changed outside of STORE (the control API, see changeFlags() in store-operations.ts): every changed
+    // message gets a new mod-sequence (RFC 7162 section 3.1.1), before the sessions are told
+    server.on('flags', (mailbox, messages) => {
+        messages.forEach(message => {
+            message.MODSEQ = bumpModseq(mailbox);
+        });
+    });
     // RFC 7162 section 3.2.11: SELECT or EXAMINE closes the selected mailbox, a CONDSTORE server marks
     // where the responses for the new mailbox start
     server.closedChecks.push(() => true);

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/index.js

@@ -53,7 +53,6 @@ import unselectPlugin from './unselect.js';
 import utf8AcceptPlugin from './utf8-accept.js';
 import xGmExt1Plugin from './x-gm-ext-1.js';
 import xoauth2Plugin from './xoauth2.js';
-import xtoybirdPlugin from './xtoybird.js';
 export const plugins = {
     acl: aclPlugin,
     appendlimit: appendlimitPlugin,
@@ -108,6 +107,5 @@ export const plugins = {
     unselect: unselectPlugin,
     'utf8-accept': utf8AcceptPlugin,
     'x-gm-ext-1': xGmExt1Plugin,
-    xoauth2: xoauth2Plugin,
-    xtoybird: xtoybirdPlugin
+    xoauth2: xoauth2Plugin
 };

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 };