imapkit 0.0.0-stage → 4.0.1

package/lib/plugins/oauthbearer.js

@@ -0,0 +1,217 @@
+'use strict';
+
+/**
+ * @help Adds AUTH=OAUTHBEARER [RFC7628] capability
+ * @help Works with and without SASL-IR [RFC4959]
+ * @help Valid login info, same as for XOAUTH2:
+ * @help   Username (authzid, optional): testuser
+ * @help   Access Token: testtoken
+ */
+
+const KVSEP = '\x01';
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+
+/**
+ * Parses an OAUTHBEARER client response (RFC 7628 section 3.1)
+ *
+ *     client-resp = (gs2-header kvsep *kvpair kvsep) / kvsep
+ *     kvpair      = key "=" value kvsep
+ *     key         = 1*(ALPHA)
+ *     value       = *(VCHAR / SP / HTAB / CR / LF)
+ *
+ * and its GS2 header (RFC 5801 section 4)
+ *
+ *     gs2-header = [gs2-nonstd-flag ","] gs2-cb-flag "," [gs2-authzid] ","
+ *     gs2-cb-flag = ("p=" cb-name) / "n" / "y"
+ *     gs2-authzid = "a=" saslname
+ *
+ * @param {Buffer} input Decoded client response
+ * @return {Object} `{ kvsepOnly }`, `{ error }` when the response breaks the grammar, or
+ *   `{ channelBinding, authzid, pairs }` where pairs maps keys to values
+ */
+function parseClientResponse(input) {
+    const str = input.toString('binary');
+    if (str === KVSEP) {
+        return { kvsepOnly: true };
+    }
+
+    const header = str.match(/^(?:F,)?(n|y|p=[A-Za-z0-9.-]+),(?:a=([^,]+))?,/);
+    if (!header || str.charAt(header[0].length) !== KVSEP) {
+        return { error: 'Invalid GS2 header' };
+    }
+
+    let authzid = false;
+    if (header[2]) {
+        // saslname: "," and "=" are only allowed as "=2C" and "=3D", NUL is not allowed
+        if (/=(?!2C|3D)/.test(header[2]) || header[2].includes('\x00')) {
+            return { error: 'Invalid authorization identity' };
+        }
+        try {
+            authzid = utf8.decode(Buffer.from(header[2].replace(/=2C/g, ',').replace(/=3D/g, '='), 'binary'));
+        } catch {
+            return { error: 'Invalid UTF-8 in the authorization identity' };
+        }
+    }
+
+    // *kvpair kvsep: every pair ends with a kvsep of its own, so the split ends with two empty parts
+    const parts = str.substr(header[0].length + 1).split(KVSEP);
+    if (parts.pop() !== '' || parts.pop() !== '') {
+        return { error: 'The client response must end with %x01' };
+    }
+
+    const pairs = Object.create(null);
+    for (const pair of parts) {
+        const match = pair.match(/^([A-Za-z]+)=([\x20-\x7e\t\r\n]*)$/);
+        if (!match) {
+            return { error: 'Invalid key/value pair' };
+        }
+        pairs[match[1]] = match[2];
+    }
+
+    return { channelBinding: header[1].charAt(0) === 'p', authzid, pairs };
+}
+
+module.exports = function (server) {
+    server.registerCapability('AUTH=OAUTHBEARER', connection => connection.state === 'Not Authenticated');
+
+    const fail = (connection, parsed, data, command, text) => {
+        // RFC 5530 section 3: a rejected login is AUTHENTICATIONFAILED
+        connection.sendStatus(parsed, data, command, text, command === 'NO' && 'AUTHENTICATIONFAILED', 'AUTHENTICATE OAUTHBEARER FAILED');
+    };
+
+    /**
+     * Checks the client response. Returns the OAuth error status (RFC 6750 section 3.1) if the
+     * credentials are not accepted, or false if the user is logged in
+     */
+    const checkCredentials = request => {
+        if (request.channelBinding) {
+            // RFC 5801 section 5: "p" asks for channel binding, which this mechanism does not support
+            return 'invalid_request';
+        }
+
+        const { auth, port } = request.pairs;
+        // port: a decimal positive integer string without leading zeros (RFC 7628 section 3.1)
+        if (typeof port === 'string' && !/^[1-9][0-9]*$/.test(port)) {
+            return 'invalid_request';
+        }
+
+        // RFC 6750 section 2.1: "Bearer" 1*SP b64token, the scheme name is case insensitive
+        const bearer = typeof auth === 'string' && auth.match(/^Bearer +([A-Za-z0-9\-._~+/]+=*)$/i);
+        if (!bearer) {
+            // an empty auth value is how a client asks for the error details (RFC 7628 section 4.3)
+            return auth === '' ? 'invalid_token' : 'invalid_request';
+        }
+        const token = bearer[1];
+
+        let username = request.authzid;
+        if (username === false) {
+            // without an authzid the token tells who the user is
+            username = Object.keys(server.users).find(name => {
+                const user = server.users[name];
+                return user && user.xoauth2 && user.xoauth2.accessToken === token;
+            });
+        }
+        const user = server.getUser(username);
+        if (!user || !user.xoauth2 || user.xoauth2.accessToken !== token) {
+            return 'invalid_token';
+        }
+        request.username = username;
+        return false;
+    };
+
+    // Decodes a base64 client response, sends BAD and returns false if it is not valid base64
+    const decode = (connection, parsed, data, input) => {
+        const decoded = connection.decodeSaslResponse(input);
+        if (!decoded) {
+            fail(connection, parsed, data, 'BAD', 'Invalid base64 in SASL response');
+        }
+        return decoded;
+    };
+
+    // Waits for the next client response line. "*" cancels the exchange, which RFC 3501 section 6.2.2
+    // answers with BAD
+    const readResponse = (connection, parsed, data, onResponse) => {
+        connection.inputHandler = line => {
+            connection.inputHandler = false;
+            if (line === '*') {
+                return fail(connection, parsed, data, 'BAD', 'Authentication cancelled');
+            }
+            const decoded = decode(connection, parsed, data, line);
+            if (decoded) {
+                onResponse(decoded);
+            }
+        };
+    };
+
+    // Handles the decoded client response, sent with SASL-IR or after the empty continuation request
+    const authenticate = (connection, parsed, data, decoded) => {
+        const request = parseClientResponse(decoded);
+        if (request.error) {
+            return fail(connection, parsed, data, 'BAD', request.error + ' in the OAUTHBEARER client response');
+        }
+        if (request.kvsepOnly) {
+            // RFC 7628 section 3.1: as the first message the server may fail without discovery information
+            return fail(connection, parsed, data, 'NO', 'SASL authentication failed');
+        }
+
+        const status = checkCredentials(request);
+        if (!status) {
+            connection.state = 'Authenticated';
+            connection.username = request.username;
+            return connection.sendStatus(parsed, data, 'OK', 'SASL authentication succeeded', false, 'AUTHENTICATE OAUTHBEARER SUCCESS');
+        }
+
+        // RFC 7628 section 3.2.2: the error result is a JSON document in a continuation request, the
+        // client MUST answer with a single %x01 or cancel, and the server then fails the exchange
+        readResponse(connection, parsed, data, response => {
+            if (response.toString('binary') !== KVSEP) {
+                return fail(connection, parsed, data, 'BAD', 'The client must answer the error result with a single %x01 (RFC 7628 section 3.2.3)');
+            }
+            fail(connection, parsed, data, 'NO', 'SASL authentication failed');
+        });
+        connection.send(
+            {
+                tag: '+',
+                attributes: [
+                    {
+                        type: 'ATOM',
+                        value: Buffer.from(JSON.stringify({ status })).toString('base64')
+                    }
+                ]
+            },
+            'AUTHENTICATE OAUTHBEARER CHALLENGE',
+            parsed,
+            data
+        );
+    };
+
+    server.setCommandHandler('AUTHENTICATE OAUTHBEARER', (connection, parsed, data, callback) => {
+        const args = parsed.attributes || [];
+
+        if (!args.length) {
+            // without an initial response the client sends its response after an empty challenge
+            readResponse(connection, parsed, data, decoded => authenticate(connection, parsed, data, decoded));
+            connection.write('+ \r\n');
+            return callback();
+        }
+
+        if (args.length !== 1 || !args[0] || args[0].type !== 'ATOM') {
+            fail(connection, parsed, data, 'BAD', 'Invalid arguments for AUTHENTICATE OAUTHBEARER');
+            return callback();
+        }
+
+        // RFC 4959 section 3: an initial response is only allowed when SASL-IR is advertised
+        if (!server.capabilities['SASL-IR'] || !server.capabilities['SASL-IR'](connection)) {
+            fail(connection, parsed, data, 'BAD', 'SASL-IR must be enabled to send Initial Response with the request');
+            return callback();
+        }
+
+        const decoded = decode(connection, parsed, data, args[0].value);
+        if (decoded) {
+            authenticate(connection, parsed, data, decoded);
+        }
+        return callback();
+    });
+};
+
+module.exports.parseClientResponse = parseClientResponse;

package/lib/plugins/objectid.js

@@ -0,0 +1,243 @@
+'use strict';
+
+const { badError } = require('../commands/handlers/search');
+
+// RFC 8474 section 7: objectid = 1*255(ALPHA / DIGIT / "_" / "-"), case sensitive
+const OBJECTID = /^[A-Za-z0-9_-]{1,255}$/;
+
+// header fields that threading uses, in an unfolded header
+const MESSAGE_ID_HEADER = /^Message-ID[ \t]*:(.*)$/im;
+const REFERENCES_HEADER = /^References[ \t]*:(.*)$/im;
+const IN_REPLY_TO_HEADER = /^In-Reply-To[ \t]*:(.*)$/im;
+
+// uidvalidity a MAILBOXID was assigned for
+const ASSIGNED_FOR = Symbol('mailboxid-uidvalidity');
+
+/**
+ * @help Adds OBJECTID [RFC8474] capability
+ * @help MAILBOXID, EMAILID and THREADID values are generated (F1, M1, T1, ...)
+ * @help unless storage sets them for a mailbox ("MAILBOXID") or a message
+ * @help ("EMAILID", "THREADID"). Messages are threaded by their Message-ID,
+ * @help In-Reply-To and References headers across all mailboxes
+ *
+ * OBJECTID: https://www.rfc-editor.org/rfc/rfc8474.txt
+ *
+ * Additional response codes:
+ * - MAILBOXID for CREATE, SELECT and EXAMINE
+ *
+ * Additional STATUS items:
+ * - MAILBOXID
+ *
+ * Additional FETCH items:
+ * - EMAILID, THREADID
+ *
+ * Additional SEARCH keys:
+ * - EMAILID, THREADID
+ */
+module.exports = function (server) {
+    server.registerCapability('OBJECTID');
+
+    // kind (F, M or T) of every value ever used, generated values must not collide with them
+    const used = new Map();
+    const counters = { F: 0, M: 0, T: 0 };
+    // current owner of each MAILBOXID, RFC 8474 section 4: never two mailboxes at the same time
+    const mailboxOwners = new Map();
+    // THREADID by EMAILID, RFC 8474 section 5.2: the same EMAILID always has the same THREADID
+    const emailThreads = new Map();
+    // THREADID by Message-ID, for threading
+    const messageIdThreads = new Map();
+
+    // RFC 8474 section 8.1: the prefix keeps generated ids from starting with a digit or a dash
+    const generate = prefix => {
+        let id;
+        do {
+            id = prefix + ++counters[prefix];
+        } while (used.has(id));
+        used.set(id, prefix);
+        return id;
+    };
+
+    const checkValue = (value, what, owner) => {
+        if (typeof value !== 'string' || !OBJECTID.test(value)) {
+            throw new Error('Invalid ' + what + ' value ' + JSON.stringify(value) + ' in ' + owner);
+        }
+    };
+
+    // RFC 8474 section 5.2: an id is used for one kind of object only
+    const checkUnique = (value, prefix) => {
+        if (used.has(value) && used.get(value) !== prefix) {
+            throw new Error('Object identifier ' + JSON.stringify(value) + ' is already used for another kind of object');
+        }
+        used.set(value, prefix);
+    };
+
+    /**
+     * Returns the MAILBOXID of a mailbox. A mailbox that got a new UIDVALIDITY (re-created after
+     * DELETE) is a new mailbox and gets a new id (RFC 8474 section 4)
+     */
+    const getMailboxId = mailbox => {
+        if (mailbox[ASSIGNED_FOR] === mailbox.uidvalidity && mailboxOwners.get(mailbox.MAILBOXID) === mailbox) {
+            return mailbox.MAILBOXID;
+        }
+
+        let id;
+        if (mailbox.MAILBOXID && mailbox[ASSIGNED_FOR] === undefined && !mailboxOwners.has(mailbox.MAILBOXID)) {
+            // value from storage
+            id = mailbox.MAILBOXID;
+            checkValue(id, 'MAILBOXID', 'mailbox ' + mailbox.path);
+            checkUnique(id, 'F');
+        } else {
+            // a new mailbox, or a copy of a deleted one (a \Noselect placeholder that is created again)
+            id = generate('F');
+        }
+
+        mailbox.MAILBOXID = id;
+        mailbox[ASSIGNED_FOR] = mailbox.uidvalidity;
+        mailboxOwners.set(id, mailbox);
+        return id;
+    };
+
+    // Assign ids when mailboxes are loaded or created. A \Noselect placeholder is not a mailbox
+    server.mailboxHandlers.push((server, mailbox) => {
+        if (mailbox.flags.indexOf('\\Noselect') >= 0) {
+            return;
+        }
+        if (mailbox.MAILBOXID && mailbox[ASSIGNED_FOR] === undefined && mailboxOwners.has(mailbox.MAILBOXID)) {
+            // two mailboxes in storage with the same id
+            throw new Error('Duplicate MAILBOXID value ' + JSON.stringify(mailbox.MAILBOXID) + ' in mailbox ' + mailbox.path);
+        }
+        getMailboxId(mailbox);
+    });
+
+    server.messageHandlers.push((server, message, mailbox) => {
+        const owner = 'a message of mailbox ' + mailbox.path;
+
+        if (message.EMAILID) {
+            checkValue(message.EMAILID, 'EMAILID', owner);
+            checkUnique(message.EMAILID, 'M');
+        } else {
+            message.EMAILID = generate('M');
+        }
+
+        if (message.THREADID) {
+            checkValue(message.THREADID, 'THREADID', owner);
+            checkUnique(message.THREADID, 'T');
+        }
+
+        const threadOfEmail = emailThreads.get(message.EMAILID);
+        if (threadOfEmail && message.THREADID && message.THREADID !== threadOfEmail) {
+            throw new Error('Messages with EMAILID ' + JSON.stringify(message.EMAILID) + ' must have the same THREADID');
+        }
+
+        const ids = getThreadingIds(message.raw);
+        message.THREADID = message.THREADID || threadOfEmail || findThread(ids.references) || generate('T');
+        emailThreads.set(message.EMAILID, message.THREADID);
+
+        // later replies, and later messages with a common parent, join this thread
+        [ids.messageId].concat(ids.references).forEach(id => {
+            if (id && !messageIdThreads.has(id)) {
+                messageIdThreads.set(id, message.THREADID);
+            }
+        });
+    });
+
+    // the nearest known parent decides the thread
+    const findThread = references => {
+        for (let i = references.length - 1; i >= 0; i--) {
+            if (messageIdThreads.has(references[i])) {
+                return messageIdThreads.get(references[i]);
+            }
+        }
+        return false;
+    };
+
+    // RFC 8474 section 5.1: the copy in the COPYUID pairing has the EMAILID of the source, after COPY as well as after MOVE
+    server.copyHandlers.push((server, source, copy) => {
+        if (source.EMAILID) {
+            copy.EMAILID = source.EMAILID;
+            copy.THREADID = source.THREADID;
+        }
+    });
+
+    // RFC 8474 section 4.3
+    server.allowedStatus.push('MAILBOXID');
+    server.statusHandlers.MAILBOXID = (connection, mailbox) => [{ type: 'ATOM', value: getMailboxId(mailbox) }];
+
+    // RFC 8474 section 5.3
+    server.fetchHandlers.EMAILID = (connection, message) => [{ type: 'ATOM', value: message.EMAILID }];
+    server.fetchHandlers.THREADID = (connection, message) => [{ type: 'ATOM', value: message.THREADID }];
+
+    // RFC 8474 section 6: search-key =/ "EMAILID" SP objectid / "THREADID" SP objectid
+    const objectIdArgument = value => {
+        if (!OBJECTID.test(value)) {
+            throw badError('Invalid object identifier');
+        }
+        return value;
+    };
+
+    const searchHandler = name => {
+        const handler = (connection, message, index, value) => message[name] === value;
+        handler.argumentTypes = () => [objectIdArgument];
+        server.searchHandlers[name] = handler;
+    };
+    searchHandler('EMAILID');
+    searchHandler('THREADID');
+
+    // resp-text-code =/ "MAILBOXID" SP "(" objectid ")"
+    const mailboxIdCode = mailbox => ({
+        type: 'SECTION',
+        section: [{ type: 'ATOM', value: 'MAILBOXID' }, [{ type: 'ATOM', value: getMailboxId(mailbox) }]]
+    });
+
+    server.outputHandlers.push((connection, response, description, parsed, data, extra) => {
+        // RFC 8474 section 4.1: MAILBOXID response code in the tagged OK of CREATE
+        if (description === 'CREATE' && response.command === 'OK' && extra) {
+            response.attributes = [mailboxIdCode(extra)].concat(response.attributes || []);
+            return;
+        }
+
+        // RFC 8474 section 4.2: untagged OK with MAILBOXID on every successful SELECT and EXAMINE
+        if (
+            (description === 'SELECT' || description === 'EXAMINE') &&
+            parsed &&
+            response.tag === parsed.tag &&
+            response.command === 'OK' &&
+            connection.selectedMailbox
+        ) {
+            connection.send(
+                {
+                    tag: '*',
+                    command: 'OK',
+                    attributes: [mailboxIdCode(connection.selectedMailbox), { type: 'TEXT', value: 'Ok' }]
+                },
+                description + ' MAILBOXID',
+                parsed,
+                data
+            );
+        }
+    });
+};
+
+/**
+ * Reads the message ids that threading uses from the header of a message
+ *
+ * @param {String} raw Message source
+ * @return {Object} `{ messageId, references }`, references lists the ids of References and In-Reply-To, the parent last
+ */
+function getThreadingIds(raw) {
+    raw = raw || '';
+    const end = raw.search(/\r?\n\r?\n/);
+    // unfolded header lines
+    const header = (end >= 0 ? raw.substr(0, end) : raw).replace(/\r?\n(?=[ \t])/g, '');
+
+    const getIds = regex => {
+        const match = header.match(regex);
+        return match ? match[1].match(/<[^<>\s]+>/g) || [] : [];
+    };
+
+    return {
+        messageId: getIds(MESSAGE_ID_HEADER)[0] || false,
+        // In-Reply-To names the parent, which is also the last entry of References
+        references: getIds(REFERENCES_HEADER).concat(getIds(IN_REPLY_TO_HEADER))
+    };
+}

package/lib/plugins/partial.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * @help Adds PARTIAL [RFC9394] capability, loads ESEARCH as well
+ * @help SEARCH RETURN (PARTIAL 1:100) or (PARTIAL -1:-100) returns a window of the results, FETCH and UID FETCH take a PARTIAL modifier
+ */
+
+const esearch = require('./esearch');
+const { parsePartialRange, selectPartial, registerPartialOption } = require('../esearch');
+
+const isPartial = item => !!item && item.type === 'ATOM' && String(item.value).toUpperCase() === 'PARTIAL';
+
+module.exports = function (server) {
+    // the PARTIAL search return option is returned in an ESEARCH response (RFC 9394 section 3.1)
+    esearch(server);
+
+    server.registerCapability('PARTIAL');
+    server.partialRangeLast = true;
+    registerPartialOption(server);
+
+    // RFC 9394 section 3.3: fetch-modifier =/ modifier-partial. The grammar (RFC 4466 section 2.4) allows
+    // the modifier for FETCH as well as for UID FETCH. The modifier is taken off the list, CHANGEDSINCE of
+    // CONDSTORE then filters the messages in the range (RFC 9394 section 3.4)
+    const fetchWrapper = (prevHandler, connection, parsed, data, callback) => {
+        const modifiers = parsed.attributes && parsed.attributes[2];
+        if (Array.isArray(modifiers)) {
+            for (let i = 0; i < modifiers.length; i += 2) {
+                if (!isPartial(modifiers[i])) {
+                    continue;
+                }
+                try {
+                    if (parsed.partialFetch) {
+                        throw new Error('PARTIAL can be used only once');
+                    }
+                    parsed.partialFetch = parsePartialRange(modifiers[i + 1], true);
+                } catch (E) {
+                    connection.sendStatus(parsed, data, 'BAD', E.message, false, (parsed.command || '').toUpperCase() + ' FAILED');
+                    return callback();
+                }
+                modifiers.splice(i, 2);
+                i -= 2;
+            }
+            if (!modifiers.length) {
+                parsed.attributes.splice(2, 1);
+            }
+        }
+        prevHandler(connection, parsed, data, callback);
+    };
+
+    ['FETCH', 'UID FETCH'].forEach(command => {
+        const prevHandler = server.getCommandHandler(command);
+        server.setCommandHandler(command, (connection, parsed, data, callback) => fetchWrapper(prevHandler, connection, parsed, data, callback));
+    });
+
+    // only the messages in the PARTIAL range of the messages that the sequence set matched are returned,
+    // checked before the other filters
+    server.fetchFilters.unshift((connection, message, parsed) => {
+        if (!parsed.partialFetch) {
+            return true;
+        }
+        if (!parsed.partialFetchSet) {
+            const isUid = (parsed.command || '').toUpperCase() === 'UID FETCH';
+            const range = connection.getMessageRange(parsed.attributes[0].value, isUid).map(item => item[1]);
+            parsed.partialFetchSet = new Set(selectPartial(range, parsed.partialFetch));
+        }
+        return parsed.partialFetchSet.has(message);
+    });
+};