imapkit 0.0.0-stage → 4.0.1

package/lib/plugins/context-search.js

@@ -0,0 +1,321 @@
+'use strict';
+
+/**
+ * @help Adds CONTEXT=SEARCH [RFC5267] capability, loads ESEARCH as well
+ * @help SEARCH RETURN (UPDATE) sends ADDTO and REMOVEFROM updates as the result changes, until CANCELUPDATE or the mailbox is closed
+ * @help SEARCH RETURN (PARTIAL 1:100) returns a window of the results, the CONTEXT hint is accepted and ignored
+ * @help Server option "maxSearchContexts" (default 10) limits the updating contexts of a session, above it NOUPDATE is sent
+ */
+
+const esearch = require('./esearch');
+const { buildCorrelator, registerPartialOption, toSequenceSet, toOrderedSet } = require('../esearch');
+const { states } = require('../command-states');
+
+const DEFAULT_MAX_CONTEXTS = 10;
+
+// commands that close the selected mailbox, updates cease with them (RFC 5267 section 4.3)
+const CLOSING_COMMANDS = new Set(['SELECT', 'EXAMINE', 'CLOSE', 'UNSELECT']);
+
+// searching commands that can create updating contexts, SORT and UID SORT only with CONTEXT=SORT (see the ESORT plugin)
+const SEARCHING_COMMANDS = new Set(['SEARCH', 'UID SEARCH', 'SORT', 'UID SORT']);
+
+const getContexts = connection => {
+    if (!connection.searchContexts) {
+        connection.searchContexts = new Map();
+    }
+    return connection.searchContexts;
+};
+
+/**
+ * Groups updates of one kind into context position and result set pairs (RFC 5267 sections 4.3.3 and
+ * 4.3.4). Updates of a searching command all use position 0 and form one set in mailbox order. Updates of
+ * a sorting command are merged while they continue each other: an insertion right after the previous
+ * inserted results, or a removal at the same position where the previous result was removed
+ *
+ * @param {Array} updates `[position, value]` pairs in the order they are applied
+ * @param {Boolean} isRemoval If true, the updates are REMOVEFROM updates
+ * @return {Array} payload of the ADDTO or REMOVEFROM return data item
+ */
+const groupUpdates = (updates, isRemoval) => {
+    const groups = [];
+    updates.forEach(([position, value]) => {
+        const last = groups[groups.length - 1];
+        const next = last && (isRemoval || !position ? last.position : last.position + last.values.length);
+        if (last && position === next) {
+            last.values.push(value);
+        } else {
+            groups.push({ position, values: [value] });
+        }
+    });
+    const payload = [];
+    groups.forEach(group => {
+        const set = group.position ? toOrderedSet(group.values) : toSequenceSet(group.values);
+        payload.push(group.position, { type: 'SEQUENCE', value: set });
+    });
+    return payload;
+};
+
+/**
+ * Sends ADDTO and REMOVEFROM updates of a context (RFC 5267 sections 4.3.3 and 4.3.4)
+ *
+ * @param {Object} connection IMAP connection
+ * @param {Object} context Updating context
+ * @param {Array} removed `[position, value]` pairs of removed results, applied first
+ * @param {Array} added `[position, value]` pairs of added results
+ */
+const sendUpdate = (connection, context, removed, added) => {
+    const attributes = [buildCorrelator(context.tag, context.correlatorMailbox)];
+    if (context.isUid) {
+        attributes.push({ type: 'ATOM', value: 'UID' });
+    }
+    if (removed.length) {
+        attributes.push({ type: 'ATOM', value: 'REMOVEFROM' }, groupUpdates(removed, true));
+    }
+    if (added.length) {
+        attributes.push({ type: 'ATOM', value: 'ADDTO' }, groupUpdates(added, false));
+    }
+    connection.send({ tag: '*', command: 'ESEARCH', attributes }, 'ESEARCH UPDATE', null, null, context);
+};
+
+/**
+ * Checks every updating context against the selected mailbox as the session sees it, and sends the
+ * changes. Expunged messages are handled when their EXPUNGE response is sent
+ */
+const checkContexts = connection => {
+    const contexts = connection.searchContexts;
+    const mailbox = connection.selectedMailbox;
+    const messages = mailbox ? mailbox.messages : [];
+    const numbers = new Map(messages.map((message, i) => [message, i + 1]));
+    contexts.forEach((context, tag) => {
+        if (context.mailbox !== mailbox) {
+            contexts.delete(tag);
+            return;
+        }
+        const matching = messages.filter((message, i) => context.matches(message, i + 1));
+        const getValue = message => (context.isUid ? message.uid : numbers.get(message));
+        const current = new Set(matching);
+        const removed = [];
+        const added = [];
+
+        if (!context.compare) {
+            // a searching command, positions are 0 (RFC 5267 section 4.3.3)
+            context.results.forEach(message => {
+                // a message that is gone without an EXPUNGE response for this session is just dropped
+                if (!current.has(message) && numbers.has(message)) {
+                    removed.push([0, getValue(message)]);
+                }
+            });
+            matching.forEach(message => {
+                if (!context.results.has(message)) {
+                    added.push([0, getValue(message)]);
+                }
+            });
+        } else {
+            // a sorting command. The sort values of a message do not change, so the results that stay keep their order.
+            // Removals are counted on the list as it shrinks, insertions in ascending order of their final position
+            let kept = 0;
+            context.order.forEach(message => {
+                if (current.has(message)) {
+                    kept++;
+                } else if (numbers.has(message)) {
+                    removed.push([kept + 1, getValue(message)]);
+                }
+            });
+            context.order = matching.sort(context.compare);
+            context.order.forEach((message, i) => {
+                if (!context.results.has(message)) {
+                    added.push([i + 1, getValue(message)]);
+                }
+            });
+        }
+
+        context.results = current;
+        if (removed.length || added.length) {
+            sendUpdate(connection, context, removed, added);
+        }
+    });
+};
+
+/**
+ * Removes expunged messages from the contexts that hold them, with one REMOVEFROM update per context
+ *
+ * @param {Object} connection IMAP connection
+ * @param {Array} messages The expunged messages
+ * @param {Number} seq Sequence number of the EXPUNGE response for a single message, null when there is none (VANISHED)
+ */
+const removeExpunged = (connection, messages, seq) => {
+    connection.searchContexts.forEach(context => {
+        if (context.mailbox !== connection.selectedMailbox) {
+            return;
+        }
+        const removed = [];
+        messages.forEach(message => {
+            if (!context.results.delete(message)) {
+                return;
+            }
+            let position = 0;
+            if (context.order) {
+                position = context.order.indexOf(message) + 1;
+                context.order.splice(position - 1, 1);
+            }
+            if (context.isUid || seq) {
+                removed.push([position, context.isUid ? message.uid : seq]);
+            }
+        });
+        if (removed.length) {
+            sendUpdate(connection, context, removed, []);
+        }
+    });
+};
+
+module.exports = function (server) {
+    // CONTEXT=SORT loads this plugin as well, so it may be called twice
+    if (server.addSearchContext) {
+        return;
+    }
+
+    // the result options of CONTEXT=SEARCH extend the extended SEARCH command (RFC 5267 section 4.1)
+    esearch(server);
+
+    server.registerCapability('CONTEXT=SEARCH');
+
+    const maxContexts = Math.max(Number(server.options.maxSearchContexts) || DEFAULT_MAX_CONTEXTS, 1);
+
+    // RFC 5267 section 4.2: the server MAY ignore the CONTEXT hint
+    server.searchReturnOptions.set('CONTEXT', { hint: true });
+    // RFC 5267 section 4.3: UPDATE has no data of its own, but the ESEARCH response is still sent
+    server.searchReturnOptions.set('UPDATE', { data: false, response: true, once: true });
+    // RFC 5267 section 4.4
+    registerPartialOption(server);
+
+    // RFC 5267 section 4.3: UPDATE with the tag of an earlier searching command that still has an updating
+    // context SHALL be rejected with BAD
+    server.searchReturnChecks.push(
+        (options, connection, parsed) =>
+            options.has('UPDATE') && getContexts(connection).has(parsed.tag) && 'Tag ' + parsed.tag + ' is already in use by an updating search'
+    );
+
+    /**
+     * Creates an updating context once a searching command with UPDATE has completed. Also used by
+     * CONTEXT=SORT and by the ESEARCH command of MULTISEARCH
+     *
+     * @param {Object} connection IMAP connection
+     * @param {Object} parsed Parsed searching command
+     * @param {String} data Raw command
+     * @param {Object} result Search result of the selected mailbox, with the `matches` function, and for a
+     *        sorting command the `sorted` list and the `compare` function
+     * @param {Boolean} isUid If true, the updates list UIDs
+     * @param {Object} [correlatorMailbox] Mailbox for the MAILBOX and UIDVALIDITY correlators (RFC 7377)
+     */
+    server.addSearchContext = (connection, parsed, data, result, isUid, correlatorMailbox) => {
+        const contexts = getContexts(connection);
+        if (contexts.size >= maxContexts) {
+            // RFC 5267 section 4.3.1: an untagged NO with NOUPDATE, the other result options are still honoured
+            connection.send(
+                {
+                    tag: '*',
+                    command: 'NO',
+                    attributes: [
+                        {
+                            type: 'SECTION',
+                            section: [
+                                { type: 'ATOM', value: 'NOUPDATE' },
+                                { type: 'STRING', value: parsed.tag }
+                            ]
+                        },
+                        { type: 'TEXT', value: 'Too many updating contexts' }
+                    ]
+                },
+                'NOUPDATE',
+                parsed,
+                data
+            );
+            return;
+        }
+        contexts.set(parsed.tag, {
+            tag: parsed.tag,
+            isUid,
+            matches: result.matches,
+            results: new Set(result.list),
+            compare: result.compare || null,
+            order: result.compare ? result.sorted.slice() : null,
+            mailbox: connection.selectedMailbox,
+            correlatorMailbox: correlatorMailbox || null
+        });
+    };
+
+    // RFC 5267 section 4.3.5: command-select =/ "CANCELUPDATE" 1*(SP quoted)
+    server.setCommandHandler(
+        'CANCELUPDATE',
+        (connection, parsed, data, callback) => {
+            const tags = parsed.attributes || [];
+            if (!tags.length || tags.some(tag => !tag || tag.type !== 'STRING')) {
+                connection.sendStatus(parsed, data, 'BAD', 'CANCELUPDATE expects one or more quoted tags', false, 'CANCELUPDATE FAILED');
+                return callback();
+            }
+            const contexts = getContexts(connection);
+            const unknown = tags.find(tag => !contexts.has(tag.value));
+            if (unknown) {
+                // nothing is cancelled when a tag has no updating context
+                connection.sendStatus(parsed, data, 'NO', 'Unknown tag', false, 'CANCELUPDATE FAILED');
+                return callback();
+            }
+            tags.forEach(tag => contexts.delete(tag.value));
+            connection.sendStatus(parsed, data, 'OK', 'Updates cancelled', false, 'CANCELUPDATE');
+            return callback();
+        },
+        { states: states.SELECTED }
+    );
+
+    // UNAUTHENTICATE (RFC 8437) closes the mailbox, so the updates end
+    server.resetHandlers.push(connection => {
+        connection.searchContexts = null;
+    });
+
+    server.connectionHandlers.push(connection => {
+        // Notifications from other sessions (and this one) are flushed here. Once none are pending, the session
+        // 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);
+            const command = ((data && data.command) || '').toUpperCase();
+            if (this.searchContexts && this.searchContexts.size && !this.notificationQueue.length && !CLOSING_COMMANDS.has(command)) {
+                checkContexts(this);
+            }
+        };
+    });
+
+    server.outputHandlers.push((connection, response, description, parsed, data, extra) => {
+        // RFC 5267 section 4.3.4: REMOVEFROM for an expunged message MUST be sent before the EXPUNGE response. After
+        // ENABLE QRESYNC a VANISHED response reports the expunged messages (RFC 7162 section 3.2.10), it has no sequence
+        // numbers, so contexts with sequence numbers drop those messages without an update
+        const expunged = response.tag === '*' && (response.message ? [response.message] : response.command === 'VANISHED' && response.messages);
+        if (expunged && connection.searchContexts) {
+            removeExpunged(connection, expunged, response.message ? response.attributes[0] : null);
+            return;
+        }
+
+        if (!parsed) {
+            return;
+        }
+        const command = (parsed.command || '').toUpperCase();
+
+        if (response.tag === parsed.tag && CLOSING_COMMANDS.has(command)) {
+            connection.searchContexts = null;
+            return;
+        }
+
+        if (!SEARCHING_COMMANDS.has(command) || !parsed.searchReturn || !parsed.searchReturn.has('UPDATE')) {
+            return;
+        }
+        // the full search result, the context is created when the command succeeded
+        if (response.tag === '*' && command.endsWith(response.command) && description === command && extra && Array.isArray(extra.list)) {
+            parsed.contextResult = extra;
+            return;
+        }
+        if (response.tag === parsed.tag && response.command === 'OK' && parsed.contextResult) {
+            server.addSearchContext(connection, parsed, data, parsed.contextResult, command.startsWith('UID '));
+        }
+    });
+};

package/lib/plugins/context-sort.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * @help Adds CONTEXT=SORT [RFC5267] capability, loads ESORT and CONTEXT=SEARCH as well
+ * @help SORT RETURN (UPDATE) sends ADDTO and REMOVEFROM updates with context positions in sort order, PARTIAL and CONTEXT work for SORT too
+ */
+
+const esort = require('./esort');
+const contextSearch = require('./context-search');
+
+module.exports = function (server) {
+    // RFC 5267 section 4.1: CONTEXT=SORT means SORT and the extended SORT syntax of section 3. The updating
+    // contexts are shared with CONTEXT=SEARCH, so that is loaded (and advertised) as well
+    esort(server);
+    contextSearch(server);
+
+    server.registerCapability('CONTEXT=SORT');
+    server.contextSort = true;
+};

package/lib/plugins/create-special-use.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * @help Enables CREATE-SPECIAL-USE [RFC6154] capability
+ * @help Allowed special flags can be set with server
+ * @help option "special-use"
+ */
+
+module.exports = function (server) {
+    // Register capability
+    server.registerCapability('CREATE-SPECIAL-USE');
+
+    const createHandler = server.getCommandHandler('CREATE');
+    const allowedList = [].concat(server.options['special-use'] || ['\\Archive', '\\Drafts', '\\Flagged', '\\Junk', '\\Sent', '\\Trash']);
+
+    server.setCommandHandler('CREATE', (connection, parsed, data, callback) => {
+        let i;
+        let len;
+        let specialUseList;
+        const mailboxSpecialUse = [];
+        if (parsed.attributes && Array.isArray(parsed.attributes[1])) {
+            for (i = 0; i < parsed.attributes[1].length; i += 2) {
+                if (
+                    parsed.attributes[1][i] &&
+                    parsed.attributes[1][i].type === 'ATOM' &&
+                    parsed.attributes[1][i].value.toUpperCase() === 'USE' &&
+                    Array.isArray(parsed.attributes[1][i + 1])
+                ) {
+                    specialUseList = parsed.attributes[1][i + 1];
+                    parsed.attributes[1].splice(i, 2);
+                    i -= 2;
+                }
+            }
+
+            // Remove extra arguments if no members were left
+            if (!parsed.attributes[1].length) {
+                parsed.attributes.splice(1, 1);
+            }
+        }
+
+        if (specialUseList) {
+            for (i = 0, len = specialUseList.length; i < len; i++) {
+                if (['ATOM', 'STRING', 'LITERAL'].indexOf(specialUseList[i].type) < 0) {
+                    connection.send(
+                        {
+                            tag: parsed.tag,
+                            command: 'BAD',
+                            attributes: [
+                                {
+                                    type: 'TEXT',
+                                    value: 'Invalid syntax for special use flag #' + (i + 1)
+                                }
+                            ]
+                        },
+                        'CREATE-SPECIAL-USE FAILED',
+                        parsed,
+                        data
+                    );
+                    return callback();
+                }
+                // attribute names are case-insensitive, store the canonical form
+                const specialUse = allowedList.find(value => value.toLowerCase() === String(specialUseList[i].value).toLowerCase());
+                if (!specialUse) {
+                    connection.send(
+                        {
+                            tag: parsed.tag,
+                            command: 'NO',
+                            attributes: [
+                                {
+                                    type: 'SECTION',
+                                    section: [
+                                        {
+                                            type: 'ATOM',
+                                            value: 'USEATTR'
+                                        }
+                                    ]
+                                },
+                                {
+                                    type: 'TEXT',
+                                    value: specialUseList[i].value + ' not supported'
+                                }
+                            ]
+                        },
+                        'CREATE-SPECIAL-USE FAILED',
+                        parsed,
+                        data
+                    );
+                    return callback();
+                }
+                if (mailboxSpecialUse.indexOf(specialUse) < 0) {
+                    mailboxSpecialUse.push(specialUse);
+                }
+            }
+        }
+
+        if (mailboxSpecialUse.length) {
+            parsed.mailboxSpecialUse = mailboxSpecialUse;
+        }
+
+        createHandler(connection, parsed, data, callback);
+    });
+
+    server.outputHandlers.push((connection, response, description, parsed, data, folder) => {
+        if (description === 'CREATE' && folder && parsed.mailboxSpecialUse) {
+            folder['special-use'] = parsed.mailboxSpecialUse;
+        }
+    });
+};

package/lib/plugins/enable.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const { states } = require('../command-states');
+
+/**
+ * @help Adds ENABLE capability [RFC5161]
+ * @help Plugins that can be enabled (eg. CONDSTORE)
+ * @help can be loaded in any order
+ */
+
+/**
+ * Makes an extension available for ENABLE. Plugins call it whether the ENABLE plugin is loaded before or after them
+ *
+ * @param {Object} server IMAPServer instance
+ * @param {String} name Capability name in the spelling it is advertised in, e.g. "IMAP4rev2"
+ */
+function registerEnable(server, name) {
+    server.enableAvailable = server.enableAvailable || [];
+    if (server.enableAvailable.indexOf(name) < 0) {
+        server.enableAvailable.push(name);
+    }
+}
+
+/**
+ * Checks if a session has enabled an extension with ENABLE. UNAUTHENTICATE clears the list (RFC 8437 section 4.1)
+ *
+ * @param {Object} connection IMAP connection
+ * @param {String} name Capability name in the spelling it was registered with, see registerEnable
+ * @return {Boolean} true if the extension is enabled
+ */
+function isEnabled(connection, name) {
+    return !!connection.enabled && connection.enabled.indexOf(name) >= 0;
+}
+
+module.exports = function (server) {
+    server.registerCapability('ENABLE');
+
+    // Shared with plugins that can be enabled, these might be loaded before or after this one
+    server.enableAvailable = server.enableAvailable || [];
+
+    server.connectionHandlers.push(connection => {
+        connection.enabled = connection.enabled || [];
+    });
+
+    // RFC 8437 section 4.1: extensions enabled with ENABLE cease to be enabled after UNAUTHENTICATE
+    server.resetHandlers.push(connection => {
+        connection.enabled = [];
+    });
+
+    server.setCommandHandler(
+        'ENABLE',
+        (connection, parsed, data, callback) => {
+            let capability;
+            let i;
+            let len;
+
+            // RFC 5161 section 3.1: "Clients MUST NOT issue ENABLE once they SELECT/EXAMINE a mailbox".
+            // Servers do not have to check this, ImapKit does to catch the client bug.
+            if (connection.everSelected) {
+                connection.sendStatus(parsed, data, 'BAD', 'ENABLE is not allowed after SELECT or EXAMINE');
+                return callback();
+            }
+
+            if (!parsed.attributes) {
+                connection.send(
+                    {
+                        tag: parsed.tag,
+                        command: 'BAD',
+                        attributes: [
+                            {
+                                type: 'TEXT',
+                                value: 'ENABLE expects capability list'
+                            }
+                        ]
+                    },
+                    'INVALID COMMAND',
+                    parsed,
+                    data
+                );
+                return callback();
+            }
+
+            for (i = 0, len = parsed.attributes.length; i < len; i++) {
+                if (!parsed.attributes[i] || parsed.attributes[i].type !== 'ATOM') {
+                    connection.send(
+                        {
+                            tag: parsed.tag,
+                            command: 'BAD',
+                            attributes: [
+                                {
+                                    type: 'TEXT',
+                                    value: 'Attribute nr ' + (i + 1) + ' is not an ATOM'
+                                }
+                            ]
+                        },
+                        'INVALID COMMAND',
+                        parsed,
+                        data
+                    );
+                    return callback();
+                }
+            }
+
+            // The ENABLED response lists only the extensions enabled by this command
+            // Capability names are matched case-insensitively and listed in the spelling the server advertises them
+            // (`server.enableAvailable`), e.g. "IMAP4rev2", so plugins look them up in `connection.enabled` by that name
+            const enabled = [];
+            for (i = 0, len = parsed.attributes.length; i < len; i++) {
+                const requested = parsed.attributes[i].value.toUpperCase();
+                capability = server.enableAvailable.find(name => name.toUpperCase() === requested);
+                if (capability && connection.enabled.indexOf(capability) < 0) {
+                    connection.enabled.push(capability);
+                    enabled.push(capability);
+                }
+            }
+
+            connection.send(
+                {
+                    tag: '*',
+                    command: 'ENABLED',
+                    attributes: enabled.map(capability => ({
+                        type: 'ATOM',
+                        value: capability
+                    }))
+                },
+                'ENABLED',
+                parsed,
+                data,
+                enabled
+            );
+
+            connection.send(
+                {
+                    tag: parsed.tag,
+                    command: 'OK',
+                    attributes: [
+                        {
+                            type: 'TEXT',
+                            value: 'ENABLE completed'
+                        }
+                    ]
+                },
+                'ENABLE',
+                parsed,
+                data
+            );
+
+            return callback();
+        },
+        { states: states.AUTHENTICATED }
+    );
+};
+
+module.exports.registerEnable = registerEnable;
+module.exports.isEnabled = isEnabled;