imapkit 4.0.2 → 4.1.0

package/{lib → dist/esm}/plugins/oauthbearer.js

@@ -1,5 +1,3 @@
-'use strict';
-
 /**
  * @help Adds AUTH=OAUTHBEARER [RFC7628] capability
  * @help Works with and without SASL-IR [RFC4959]
@@ -7,10 +5,8 @@
  * @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)
  *
@@ -34,12 +30,10 @@ function parseClientResponse(input) {
     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
@@ -48,17 +42,16 @@ function parseClientResponse(input) {
         }
         try {
             authzid = utf8.decode(Buffer.from(header[2].replace(/=2C/g, ',').replace(/=3D/g, '='), 'binary'));
-        } catch {
+        }
+        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]*)$/);
@@ -67,34 +60,28 @@ function parseClientResponse(input) {
         }
         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');
-
+export default function oauthbearerPlugin(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 => {
+    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) {
@@ -102,7 +89,6 @@ module.exports = function (server) {
             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
@@ -118,7 +104,6 @@ module.exports = function (server) {
         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);
@@ -127,11 +112,10 @@ module.exports = function (server) {
         }
         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 = (line) => {
             connection.inputHandler = false;
             if (line === '*') {
                 return fail(connection, parsed, data, 'BAD', 'Authentication cancelled');
@@ -142,7 +126,6 @@ module.exports = function (server) {
             }
         };
     };
-
     // 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);
@@ -153,65 +136,52 @@ module.exports = function (server) {
             // 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 => {
+        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
-        );
+        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;
+}
+export { parseClientResponse };

package/dist/esm/plugins/objectid.d.ts

@@ -0,0 +1,23 @@
+import type { IMAPServer } from '../types.js';
+/**
+ * @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
+ */
+export default function objectidPlugin(server: IMAPServer): void;

package/{lib → dist/esm}/plugins/objectid.js

@@ -1,18 +1,12 @@
-'use strict';
-
-const { badError } = require('../commands/handlers/search');
-
+import { badError } from '../commands/handlers/search.js';
 // 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, ...)
@@ -34,9 +28,8 @@ const ASSIGNED_FOR = Symbol('mailboxid-uidvalidity');
  * Additional SEARCH keys:
  * - EMAILID, THREADID
  */
-module.exports = function (server) {
+export default function objectidPlugin(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 };
@@ -46,9 +39,8 @@ module.exports = function (server) {
     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 => {
+    const generate = (prefix) => {
         let id;
         do {
             id = prefix + ++counters[prefix];
@@ -56,13 +48,11 @@ module.exports = function (server) {
         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) {
@@ -70,33 +60,30 @@ module.exports = function (server) {
         }
         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 => {
+    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 {
+        }
+        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) {
@@ -108,31 +95,26 @@ module.exports = function (server) {
         }
         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 {
+        }
+        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)) {
@@ -140,9 +122,8 @@ module.exports = function (server) {
             }
         });
     });
-
     // the nearest known parent decides the thread
-    const findThread = references => {
+    const findThread = (references) => {
         for (let i = references.length - 1; i >= 0; i--) {
             if (messageIdThreads.has(references[i])) {
                 return messageIdThreads.get(references[i]);
@@ -150,7 +131,6 @@ module.exports = function (server) {
         }
         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) {
@@ -158,66 +138,51 @@ module.exports = function (server) {
             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 => {
+    const objectIdArgument = (value) => {
         if (!OBJECTID.test(value)) {
             throw badError('Invalid object identifier');
         }
         return value;
     };
-
-    const searchHandler = name => {
+    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 => ({
+    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') &&
+        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
-            );
+            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
  *
@@ -229,12 +194,10 @@ function getThreadingIds(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 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

package/dist/esm/plugins/partial.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @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
+ */
+import type { IMAPServer } from '../types.js';
+export default function partialPlugin(server: IMAPServer): void;

package/{lib → dist/esm}/plugins/partial.js

@@ -1,23 +1,16 @@
-'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) {
+import esearch from './esearch.js';
+import { parsePartialRange, selectPartial, registerPartialOption } from '../esearch.js';
+const isPartial = (item) => !!item && item.type === 'ATOM' && String(item.value).toUpperCase() === 'PARTIAL';
+export default function partialPlugin(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)
@@ -33,7 +26,8 @@ module.exports = function (server) {
                         throw new Error('PARTIAL can be used only once');
                     }
                     parsed.partialFetch = parsePartialRange(modifiers[i + 1], true);
-                } catch (E) {
+                }
+                catch (E) {
                     connection.sendStatus(parsed, data, 'BAD', E.message, false, (parsed.command || '').toUpperCase() + ' FAILED');
                     return callback();
                 }
@@ -46,12 +40,10 @@ module.exports = function (server) {
         }
         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) => {
@@ -65,4 +57,4 @@ module.exports = function (server) {
         }
         return parsed.partialFetchSet.has(message);
     });
-};
+}

package/dist/esm/plugins/preview.d.ts

@@ -0,0 +1,31 @@
+import type { MimeNode } from '../mimeparser.js';
+import type { IMAPServer } from '../types.js';
+/**
+ * @help Adds PREVIEW [RFC8970] capability
+ * @help Previews come from the first text/plain or text/html body part,
+ * @help or from the "preview" property of a message in storage.
+ * @help PREVIEW (LAZY) returns NIL until a preview has been generated
+ *
+ * PREVIEW: https://www.rfc-editor.org/rfc/rfc8970
+ *
+ * Message storage property:
+ * - preview: preview text to return instead of a generated one
+ */
+export default function previewPlugin(server: IMAPServer): void;
+/**
+ * Generates the preview text of a message (RFC 8970 3.3) from the first text/plain or text/html part
+ *
+ * @param {Object} tree Root node of the MIME tree
+ * @return {String} Preview, an empty string if there is no text to show
+ */
+declare function generatePreview(tree: MimeNode): string;
+/**
+ * Normalizes preview text: control characters are removed, whitespace runs become a single space (so there are no
+ * CR or LF characters) and the text is cut to at most `length` characters (code points, RFC 8970 3.3)
+ *
+ * @param {String} text Text
+ * @param {Number} length Maximum number of characters
+ * @return {String} Preview
+ */
+declare function finishPreview(text: string, length: number): string;
+export { generatePreview, finishPreview };