imapkit 0.0.0-stage → 4.0.1

package/lib/framing.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * IMAP framing helpers shared by the mock client, the test helpers and the compare tool.
+ * Both functions take a Buffer or a binary string (one character per octet).
+ */
+
+const LF = 0x0a;
+const CR = 0x0d;
+
+/**
+ * Splits received server data into responses. A response is one line, or a line that ends with a
+ * literal marker `{n}` or `~{n}` (RFC 3516 literal8), followed by n octets and the rest of the
+ * response. Lenient: lines end at LF, a CR before it is not required. Callers that need strict
+ * framing check the line ends themselves.
+ *
+ * @param {Buffer|String} data Received data, possibly ending with an incomplete response
+ * @return {Object} `{ responses, end, incomplete }`. Every response is `{ start, end, lines, literals }`,
+ *         where `lines` lists `{ start, end, lf }` (end excludes the CR before the LF, `lf` is the
+ *         offset of the LF) and `literals` lists `{ start, end, literal8 }`. `end` is the offset right
+ *         after the last complete response. `incomplete` is false when all data was used, otherwise
+ *         `{ reason, lines }` with the complete lines of the unfinished response, where reason is
+ *         'line' for a line without LF, 'literal' for literal data that is cut short (with `size`
+ *         and `available`), or 'response' when the data ends right after literal data.
+ */
+function splitResponses(data) {
+    const isBuffer = Buffer.isBuffer(data);
+    const length = data.length;
+    const charAt = isBuffer ? i => data[i] : i => data.charCodeAt(i);
+    const slice = isBuffer ? (start, end) => data.toString('binary', start, end) : (start, end) => data.slice(start, end);
+
+    const responses = [];
+    let pos = 0;
+    let end = 0;
+    let current = null;
+
+    while (pos < length) {
+        const lf = data.indexOf(isBuffer ? LF : '\n', pos);
+        if (lf < 0) {
+            return { responses, end, incomplete: { reason: 'line', lines: current ? current.lines : [] } };
+        }
+
+        const lineStart = pos;
+        const lineEnd = lf > pos && charAt(lf - 1) === CR ? lf - 1 : lf;
+        if (!current) {
+            current = { start: pos, end: 0, lines: [], literals: [] };
+        }
+        current.lines.push({ start: lineStart, end: lineEnd, lf });
+        pos = lf + 1;
+
+        // only lines that end with "}" can carry a literal marker, so most lines are not sliced
+        const marker = lineEnd > lineStart && charAt(lineEnd - 1) === 0x7d && slice(Math.max(lineEnd - 32, lineStart), lineEnd).match(/(~?)\{(\d+)\}$/);
+        if (marker) {
+            const size = Number(marker[2]);
+            if (pos + size > length) {
+                return { responses, end, incomplete: { reason: 'literal', size, available: length - pos, lines: current.lines } };
+            }
+            current.literals.push({ start: pos, end: pos + size, literal8: !!marker[1] });
+            pos += size;
+            continue;
+        }
+
+        current.end = end = pos;
+        responses.push(current);
+        current = null;
+    }
+
+    // the data ended right after a literal, the rest of the response is missing
+    return { responses, end, incomplete: current ? { reason: 'response', lines: current.lines } : false };
+}
+
+/**
+ * Splits an outgoing command after every synchronizing literal marker, as a client must wait for the
+ * continuation request before it sends the literal data (RFC 3501 section 4.3). The data of every
+ * literal, synchronizing or not ({n+}, RFC 7888), is skipped, so markers inside it are not matched.
+ *
+ * @param {Buffer|String} payload Command, as a Buffer or a binary string
+ * @return {Array} Chunks to send, of the same type as the payload
+ */
+function splitAtLiterals(payload) {
+    const isBuffer = Buffer.isBuffer(payload);
+    const str = isBuffer ? payload.toString('binary') : String(payload);
+    const cut = (start, end) => (isBuffer ? payload.subarray(start, end) : str.slice(start, end));
+    const chunks = [];
+    const re = /~?\{(\d+)(\+?)\}\r\n/g;
+    let start = 0;
+    let match;
+
+    while ((match = re.exec(str))) {
+        const end = match.index + match[0].length;
+        if (!match[2]) {
+            chunks.push(cut(start, end));
+            start = end;
+        }
+        re.lastIndex = end + Number(match[1]);
+    }
+    chunks.push(cut(start));
+
+    return chunks.filter(chunk => chunk.length);
+}
+
+module.exports = { splitResponses, splitAtLiterals };

package/lib/list-extensions.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Returns the registry of extended LIST options (RFC 5258 section 3), shared by the LIST-EXTENDED
+ * plugin and the plugins that add their own options (SPECIAL-USE, LIST-STATUS). These can be loaded
+ * in any order, so whichever comes first creates the registry. Options are only accepted when the
+ * LIST-EXTENDED plugin is loaded (`enabled`).
+ *
+ * Selection options: `{ type, returnOption, includeNonExistent, match(folder, connection) }`
+ *   - `type` is "base", "independent" or "modifier" (list-select-base-opt, list-select-independent-opt
+ *     and list-select-mod-opt in the RFC 5258 section 6 grammar)
+ *   - `returnOption` is the return option the selection option implies
+ *   - `match` is the filter the mailboxes must pass, `includeNonExistent` if it can select mailbox
+ *     names that do not exist (like SUBSCRIBED)
+ *
+ * Return options: `{ parse(list, connection), onItem(connection, folder, value, info, parsed, data) }`
+ *   - `parse` is set for options that take a value (option-value), it returns the parsed value or
+ *     throws an Error with a message for the BAD response
+ *   - `onItem` runs after the LIST response of every listed mailbox. `info.matched` is true if the
+ *     mailbox matched the selection criteria, `info.exists` if it is not \NonExistent
+ *
+ * @param {Object} server IMAPServer instance
+ * @return {Object} `{ enabled, selectionOptions, returnOptions }`
+ */
+function getListExtensions(server) {
+    if (!server.listExtensions) {
+        server.listExtensions = {
+            enabled: false,
+            selectionOptions: Object.create(null),
+            returnOptions: Object.create(null)
+        };
+    }
+    return server.listExtensions;
+}
+
+module.exports = { getListExtensions };

package/lib/load-plugins.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PLUGINS_DIR = path.join(__dirname, 'plugins');
+
+// Capability spellings that do not match a plugin file name
+const ALIASES = {
+    'literal+': 'literalplus',
+    'literal-': 'literalminus',
+    'compress=deflate': 'compress',
+    'auth=plain': 'auth-plain',
+    'auth=xoauth2': 'xoauth2',
+    'status=size': 'status-size',
+    'sort=display': 'sort-display',
+    'thread=orderedsubject': 'thread-orderedsubject',
+    'thread=references': 'thread-references',
+    'auth=oauthbearer': 'oauthbearer',
+    'utf8=accept': 'utf8-accept',
+    'context=search': 'context-search',
+    'context=sort': 'context-sort'
+};
+
+let available = null;
+
+/**
+ * Lists the modules of a directory (file names without the .js extension)
+ *
+ * @param {String} dir Directory path
+ * @return {Array} module names
+ */
+function listModules(dir) {
+    return fs
+        .readdirSync(dir)
+        .filter(fileName => /\.js$/.test(fileName))
+        .map(fileName => fileName.replace(/\.js$/, ''));
+}
+
+/**
+ * Lists the names of the built-in plugins (file names without extension)
+ *
+ * @return {Array} plugin names
+ */
+function listPlugins() {
+    if (!available) {
+        available = listModules(PLUGINS_DIR);
+    }
+    return available;
+}
+
+/**
+ * Resolves a plugin name, as given in options.plugins, to a built-in plugin
+ *
+ * @param {String} name Plugin name, eg. "IDLE" or "LITERAL+"
+ * @return {String|false} Resolved plugin name or false if no such plugin exists
+ */
+function resolvePlugin(name) {
+    let key = String(name).trim().toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(ALIASES, key)) {
+        key = ALIASES[key];
+    }
+    return listPlugins().includes(key) ? key : false;
+}
+
+/**
+ * Loads plugins for a server instance. Built-in plugins are referenced by name,
+ * custom plugins are functions. Unknown names throw, repeated plugins are loaded only once.
+ * A plugin that needs another plugin lists its name in `plugin.requires`, the required
+ * plugin is then loaded first. Once every plugin is loaded, the server emits `pluginsLoaded`: a plugin
+ * that has to wrap what other plugins set up (commands, output handlers), whatever the load order,
+ * does that in a `server.once('pluginsLoaded', ...)` listener. Listeners run in plugin load order.
+ *
+ * @param {Object} server IMAPServer instance
+ * @param {Array|String|Function} plugins List of plugins to load
+ */
+function loadPlugins(server, plugins) {
+    const loaded = new Set();
+
+    const load = plugin => {
+        if (typeof plugin === 'string') {
+            const name = resolvePlugin(plugin);
+            if (!name) {
+                throw new Error('Unknown plugin "' + plugin + '". Available plugins: ' + listPlugins().join(', '));
+            }
+            plugin = require(path.join(PLUGINS_DIR, name));
+        }
+
+        if (typeof plugin !== 'function') {
+            throw new TypeError('Invalid plugin, expecting a plugin name or a function');
+        }
+
+        if (loaded.has(plugin)) {
+            return;
+        }
+        loaded.add(plugin);
+
+        [].concat(plugin.requires || []).forEach(load);
+
+        plugin(server);
+    };
+
+    [].concat(plugins || []).forEach(load);
+
+    server.emit('pluginsLoaded');
+}
+
+module.exports = loadPlugins;
+module.exports.listModules = listModules;

package/lib/mailbox-name.js

@@ -0,0 +1,133 @@
+'use strict';
+
+// Modified BASE64 alphabet of RFC 3501 section 5.1.3 ("," instead of "/")
+const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,';
+
+/**
+ * Checks a mailbox name against the modified UTF-7 rules of RFC 3501 section 5.1.3:
+ * printable US-ASCII represents itself, "&" is written as "&-", everything else
+ * is encoded in modified BASE64 between "&" and "-", without superfluous shifts
+ * and without encoding printable US-ASCII.
+ *
+ * @param {String} name Mailbox name as a binary string
+ * @return {String|Boolean} Description of the problem, or false if the name is valid
+ */
+function validateMailboxName(name) {
+    if (typeof name !== 'string') {
+        return 'Invalid mailbox name';
+    }
+
+    let i = 0;
+    while (i < name.length) {
+        const code = name.charCodeAt(i);
+
+        if (code < 0x20 || code > 0x7e) {
+            return 'Mailbox name must use modified UTF-7 for non-ASCII characters (RFC 3501 section 5.1.3)';
+        }
+
+        if (name.charAt(i) !== '&') {
+            i++;
+            continue;
+        }
+
+        if (name.charAt(i + 1) === '-') {
+            // "&-" is the "&" character
+            i += 2;
+            continue;
+        }
+
+        const end = name.indexOf('-', i + 1);
+        if (end < 0) {
+            return 'Modified BASE64 in mailbox name must end with "-" (RFC 3501 section 5.1.3)';
+        }
+
+        const error = checkBase64(name.slice(i + 1, end));
+        if (error) {
+            return error;
+        }
+
+        if (name.charAt(end + 1) === '&' && name.charAt(end + 2) !== '-') {
+            return 'Mailbox name contains a superfluous shift (RFC 3501 section 5.1.3)';
+        }
+
+        i = end + 1;
+    }
+
+    return false;
+}
+
+function checkBase64(encoded) {
+    let bits = 0;
+    let bitCount = 0;
+    const units = [];
+
+    for (let i = 0; i < encoded.length; i++) {
+        const value = BASE64_CHARS.indexOf(encoded.charAt(i));
+        if (value < 0) {
+            return 'Invalid modified BASE64 in mailbox name (RFC 3501 section 5.1.3)';
+        }
+        bits = (bits << 6) | value;
+        bitCount += 6;
+        if (bitCount >= 16) {
+            bitCount -= 16;
+            units.push((bits >> bitCount) & 0xffff);
+            bits &= (1 << bitCount) - 1;
+        }
+    }
+
+    // leftover bits are padding and must be zero, and must not hold a partial character
+    if (!units.length || bitCount >= 6 || bits !== 0) {
+        return 'Invalid modified BASE64 in mailbox name (RFC 3501 section 5.1.3)';
+    }
+
+    for (let i = 0; i < units.length; i++) {
+        const unit = units[i];
+        if (unit >= 0x20 && unit <= 0x7e) {
+            return 'Modified BASE64 must not encode printable US-ASCII (RFC 3501 section 5.1.3)';
+        }
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            if (!(units[i + 1] >= 0xdc00 && units[i + 1] <= 0xdfff)) {
+                return 'Invalid UTF-16 in mailbox name';
+            }
+            i++;
+        } else if (unit >= 0xdc00 && unit <= 0xdfff) {
+            return 'Invalid UTF-16 in mailbox name';
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Encodes a mailbox name in modified UTF-7 (RFC 3501 section 5.1.3)
+ *
+ * @param {String} name Mailbox name as a unicode string
+ * @return {String} Modified UTF-7 name
+ */
+function encodeMailboxName(name) {
+    return name.replace(/&|[^\x20-\x7e]+/g, chunk => {
+        if (chunk === '&') {
+            return '&-';
+        }
+        return '&' + Buffer.from(chunk, 'utf16le').swap16().toString('base64').replace(/=+$/, '').replace(/\//g, ',') + '-';
+    });
+}
+
+/**
+ * Decodes a modified UTF-7 mailbox name (RFC 3501 section 5.1.3)
+ *
+ * @param {String} name Mailbox name as a binary string
+ * @return {String|Boolean} Mailbox name as a unicode string, or false if the name is not valid modified UTF-7
+ */
+function decodeMailboxName(name) {
+    if (validateMailboxName(name)) {
+        return false;
+    }
+    return name.replace(/&([^-]*)-/g, (match, encoded) => (encoded ? Buffer.from(encoded.replace(/,/g, '/'), 'base64').swap16().toString('utf16le') : '&'));
+}
+
+module.exports = validateMailboxName;
+module.exports.encode = encodeMailboxName;
+module.exports.decode = decodeMailboxName;
+// CATENATE resolves URL mailbox names with it
+module.exports.encodeMailboxName = encodeMailboxName;