imapkit 4.0.3 → 4.1.0

package/dist/cjs/utf8-session.js

@@ -0,0 +1,148 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateSession = updateSession;
+const node_buffer_1 = require("node:buffer");
+const mailbox_name_js_1 = __importStar(require("./mailbox-name.js"));
+const enable_js_1 = require("./plugins/enable.js");
+/**
+ * UTF-8 support of a session, shared by the UTF8=ACCEPT (RFC 9755) and IMAP4rev2 (RFC 9051) plugins. Both
+ * turn on UTF-8 mailbox names and quoted strings with ENABLE, and they can be loaded in any order, so the
+ * state of a session is always computed from what it has enabled, see updateSession().
+ */
+// RFC 9755 section 3: mailbox names MUST NOT contain control characters, DEL, LINE SEPARATOR or
+// PARAGRAPH SEPARATOR. RFC 5198 section 2 (Net-Unicode) also forbids a leading BOM and unassigned code points
+// eslint-disable-next-line no-control-regex
+const INVALID_NAME_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]|^\ufeff|\p{Cn}/u;
+function badError(message) {
+    const err = new Error(message);
+    err.imapResponse = 'BAD';
+    return err;
+}
+/**
+ * Throws a BAD error for a mailbox name that is not Net-Unicode (RFC 9755 section 3, RFC 9051 section 5.1).
+ * RFC 5198 section 2 also requires Normalization Form C
+ *
+ * @param {String|Boolean} decoded Mailbox name as a unicode string, false if it could not be decoded
+ * @return {String} the decoded name
+ */
+function checkNetUnicode(decoded) {
+    if (decoded === false || INVALID_NAME_CHARS.test(decoded)) {
+        throw badError('Mailbox name must be valid Net-Unicode without control characters (RFC 9755 section 3)');
+    }
+    if (decoded.normalize('NFC') !== decoded) {
+        throw badError('Mailbox name must be in Unicode Normalization Form C (RFC 5198 section 2, RFC 9051 section 5.1)');
+    }
+    return decoded;
+}
+/**
+ * Checks a modified UTF-7 mailbox name from a client that did not enable UTF-8. The RFC 9755
+ * section 3 rules apply to these names as well, e.g. "&AA0-" encodes CR
+ *
+ * @param {String} name Mailbox name as a binary string
+ * @return {String} Storage name
+ * @throws {Error} BAD error if the name is not valid
+ */
+function importMutf7Name(name) {
+    const error = (0, mailbox_name_js_1.default)(name);
+    if (error) {
+        throw badError(error);
+    }
+    checkNetUnicode((0, mailbox_name_js_1.decode)(name));
+    return name;
+}
+/**
+ * Converts a UTF-8 mailbox name from the client to the modified UTF-7 storage name
+ *
+ * @param {String} name Mailbox name as a binary string
+ * @return {String} Storage name
+ * @throws {Error} BAD error if the name is not valid
+ */
+function importUtf8Name(name) {
+    const buf = Buffer.from(name, 'binary');
+    return (0, mailbox_name_js_1.encode)(checkNetUnicode((0, node_buffer_1.isUtf8)(buf) && buf.toString('utf-8')));
+}
+/**
+ * Converts a modified UTF-7 storage name to UTF-8. A name that is not valid modified UTF-7
+ * is sent as it is.
+ *
+ * @param {String} path Storage name
+ * @return {String} Mailbox name as a binary string
+ */
+function exportUtf8Name(path) {
+    const decoded = (0, mailbox_name_js_1.decode)(path);
+    return decoded === false ? path : Buffer.from(decoded, 'utf-8').toString('binary');
+}
+/**
+ * Sets the UTF-8 options of a session from the extensions it has enabled. Run it when the session starts,
+ * after ENABLE and after UNAUTHENTICATE (once the ENABLE plugin has cleared `connection.enabled`).
+ *
+ * - With the UTF8=ACCEPT plugin, quoted strings may hold UTF-8 even before ENABLE (RFC 9755 section 3) and
+ *   modified UTF-7 names must decode to Net-Unicode. Without it, 8-bit quoted strings are a syntax error until
+ *   ENABLE IMAP4rev2, like RFC 3501 says
+ * - ENABLE UTF8=ACCEPT or IMAP4rev2: mailbox names are UTF-8 in both directions and strings that are valid
+ *   UTF-8 are sent quoted (RFC 9755 section 3, RFC 9051 sections 4.3 and 5.1)
+ * - ENABLE UTF8=ACCEPT: SEARCH strings are UTF-8 and CHARSET is refused (RFC 9755 section 3)
+ * - ENABLE IMAP4rev2: SEARCH strings are UTF-8 unless a CHARSET says otherwise (RFC 9051 section 6.4.4)
+ *
+ * @param {Object} connection IMAP connection
+ */
+function updateSession(connection) {
+    const server = connection.server;
+    const accept = (0, enable_js_1.isEnabled)(connection, 'UTF8=ACCEPT');
+    const rev2 = (0, enable_js_1.isEnabled)(connection, 'IMAP4rev2');
+    const utf8Names = accept || rev2;
+    // UTF-8 names and quoted strings are on, plugins check this instead of the extension names
+    connection.utf8Enabled = utf8Names;
+    connection.parserOptions.utf8 = !!server.utf8Accept || rev2;
+    connection.compilerOptions.utf8 = utf8Names;
+    connection.searchCharset = accept ? 'UTF-8' : false;
+    connection.defaultSearchCharset = rev2 ? 'UTF-8' : false;
+    if (utf8Names) {
+        connection.importMailboxName = importUtf8Name;
+        connection.exportMailboxName = exportUtf8Name;
+    }
+    else {
+        // back to the IMAPConnection methods, the overrides are own properties of the connection
+        const overrides = connection;
+        delete overrides.exportMailboxName;
+        if (server.utf8Accept) {
+            connection.importMailboxName = importMutf7Name;
+        }
+        else {
+            delete overrides.importMailboxName;
+        }
+    }
+}

package/dist/cjs/vanished.d.ts

@@ -0,0 +1,21 @@
+/**
+ * VANISHED responses (RFC 7162 section 3.2.10) in place of EXPUNGE notifications. Used by QRESYNC
+ * and by UIDONLY (RFC 9586 section 3.4), which both report expunged messages by UID.
+ */
+import type { IMAPResponse, Notification } from './types.js';
+/**
+ * Checks if a queued notification is an EXPUNGE response for a removed message
+ *
+ * @param {Object} notification Queued notification
+ * @return {Boolean} true for an EXPUNGE notification
+ */
+declare function isExpungeNotification(notification: Notification): boolean;
+/**
+ * Replaces the EXPUNGE notifications of a queue with VANISHED responses, consecutive EXPUNGE
+ * notifications become one VANISHED response. The queue is not changed
+ *
+ * @param {Array} queue Queued notifications
+ * @return {Array} notifications to send
+ */
+declare function toVanished(queue: Notification[]): IMAPResponse[];
+export { isExpungeNotification, toVanished };

package/dist/cjs/vanished.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * VANISHED responses (RFC 7162 section 3.2.10) in place of EXPUNGE notifications. Used by QRESYNC
+ * and by UIDONLY (RFC 9586 section 3.4), which both report expunged messages by UID.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExpungeNotification = isExpungeNotification;
+exports.toVanished = toVanished;
+const esearch_js_1 = require("./esearch.js");
+/**
+ * Checks if a queued notification is an EXPUNGE response for a removed message
+ *
+ * @param {Object} notification Queued notification
+ * @return {Boolean} true for an EXPUNGE notification
+ */
+function isExpungeNotification(notification) {
+    const name = !!notification.message && !!notification.attributes && notification.attributes[1];
+    return !!name && name.type === 'ATOM' && String(name.value).toUpperCase() === 'EXPUNGE';
+}
+/**
+ * Replaces the EXPUNGE notifications of a queue with VANISHED responses, consecutive EXPUNGE
+ * notifications become one VANISHED response. The queue is not changed
+ *
+ * @param {Array} queue Queued notifications
+ * @return {Array} notifications to send
+ */
+function toVanished(queue) {
+    if (!queue.some(isExpungeNotification)) {
+        return queue;
+    }
+    // groups of consecutive expunges, as lists of UIDs, between the other notifications
+    const groups = [];
+    queue.forEach(notification => {
+        if (!isExpungeNotification(notification)) {
+            groups.push(notification);
+        }
+        else if (Array.isArray(groups[groups.length - 1])) {
+            // an EXPUNGE notification always carries its message
+            groups[groups.length - 1].push(notification.message);
+        }
+        else {
+            groups.push([notification.message]);
+        }
+    });
+    // the removed messages go with the response for output handlers, like `message` of EXPUNGE
+    return groups.map(group => Array.isArray(group)
+        ? {
+            tag: '*',
+            command: 'VANISHED',
+            attributes: [{ type: 'SEQUENCE', value: (0, esearch_js_1.toSequenceSet)(group.map(message => message.uid)) }],
+            notification: true,
+            messages: group
+        }
+        : group);
+}

package/dist/esm/addressparser.d.ts

@@ -0,0 +1,21 @@
+/** An address, or a group with its member addresses */
+export interface ParsedAddress {
+    name: string;
+    address?: string;
+    group?: ParsedAddress[];
+}
+/**
+ * Parses structured e-mail addresses from an address field
+ *
+ * Example:
+ *
+ *    "Name <address@domain>"
+ *
+ * will be converted to
+ *
+ *     [{name: "Name", address: "address@domain"}]
+ *
+ * @param {String} str Address field
+ * @return {Array} An array of address objects
+ */
+export default function parse(str: string, inGroup?: boolean): ParsedAddress[];

package/{lib → dist/esm}/addressparser.js

@@ -1,5 +1,3 @@
-'use strict';
-
 /**
  * Parses structured e-mail addresses from an address field
  *
@@ -14,39 +12,34 @@
  * @param {String} str Address field
  * @return {Array} An array of address objects
  */
-const parse = (module.exports = function (str, inGroup) {
+export default function parse(str, inGroup) {
     const tokenizer = new Tokenizer(str);
     const tokens = tokenizer.tokenize();
-
     const addresses = [];
     let address = [];
     let parsedAddresses = [];
-
     tokens.forEach(token => {
         if (token.type === 'operator' && (token.value === ',' || token.value === ';')) {
             if (address.length) {
                 addresses.push(address);
             }
             address = [];
-        } else {
+        }
+        else {
             address.push(token);
         }
     });
-
     if (address.length) {
         addresses.push(address);
     }
-
     addresses.forEach(address => {
-        address = _handleAddress(address, inGroup);
-        if (address.length) {
-            parsedAddresses = parsedAddresses.concat(address);
+        const handled = _handleAddress(address, inGroup);
+        if (handled.length) {
+            parsedAddresses = parsedAddresses.concat(handled);
         }
     });
-
     return parsedAddresses;
-});
-
+}
 /**
  * Converts tokens for a single address into an address object
  *
@@ -69,11 +62,9 @@ function _handleAddress(tokens, inGroup) {
     };
     let i;
     let len;
-
     // Filter out <addresses>, (comments) and regular text
     for (i = 0, len = tokens.length; i < len; i++) {
         token = tokens[i];
-
         if (token.type === 'operator') {
             switch (token.value) {
                 case '<':
@@ -93,27 +84,28 @@ function _handleAddress(tokens, inGroup) {
                 default:
                     state = 'text';
             }
-        } else {
+        }
+        else {
             if (token.value) {
                 data[state].push(token.value);
             }
         }
     }
-
     // If there is no text but a comment, replace the two
     if (!data.text.length && data.comment.length) {
         data.text = data.comment;
         data.comment = [];
     }
-
     if (isGroup) {
         // http://tools.ietf.org/html/rfc2822#appendix-A.1.3
-        data.text = data.text.join(' ');
+        const text = data.text.join(' ');
         addresses.push({
-            name: data.text || address.name,
+            // address is never set here, so an empty group name throws like the JavaScript original did
+            name: text || address.name,
             group: data.group.length ? parse(data.group.join(','), true) : []
         });
-    } else {
+    }
+    else {
         // If no address was found, try to detect one from regular text
         if (!data.address.length && data.text.length) {
             for (i = data.text.length - 1; i >= 0; i--) {
@@ -122,16 +114,15 @@ function _handleAddress(tokens, inGroup) {
                     break;
                 }
             }
-
             const _regexHandler = function (address) {
                 if (!data.address.length) {
                     data.address = [address.trim()];
                     return ' ';
-                } else {
+                }
+                else {
                     return address;
                 }
             };
-
             // still no address
             if (!data.address.length) {
                 for (i = data.text.length - 1; i >= 0; i--) {
@@ -142,61 +133,123 @@ function _handleAddress(tokens, inGroup) {
                 }
             }
         }
-
         // If there's still is no text but a comment exixts, replace the two
         if (!data.text.length && data.comment.length) {
             data.text = data.comment;
             data.comment = [];
         }
-
         // Keep only the first address occurence, push others to regular text
         if (data.address.length > 1) {
             data.text = data.text.concat(data.address.splice(1));
         }
-
         // Join values with spaces
-        data.text = data.text.join(' ');
-        data.address = data.address.join(' ');
-
-        if (!data.address && isGroup) {
+        const text = data.text.join(' ');
+        const addressText = data.address.join(' ');
+        if (!addressText && isGroup) {
             return [];
-        } else {
+        }
+        else {
             address = {
-                address: data.address || data.text || '',
-                name: data.text || data.address || ''
+                address: addressText || text || '',
+                name: text || addressText || ''
             };
-
             if (address.address === address.name) {
                 if ((address.address || '').match(/@/)) {
                     address.name = '';
-                } else {
+                }
+                else {
                     address.address = '';
                 }
             }
-
             addresses.push(address);
         }
     }
-
     return addresses;
 }
-
 /**
  * Creates a Tokenizer object for tokenizing address field strings
  *
  * @constructor
  * @param {String} str Address field string
  */
-function Tokenizer(str) {
-    this.str = (str || '').toString();
-    this.operatorCurrent = '';
-    this.operatorExpecting = '';
-    this.node = null;
-    this.escaped = false;
-
-    this.list = [];
+class Tokenizer {
+    constructor(str) {
+        this.str = (str || '').toString();
+        this.operatorCurrent = '';
+        this.operatorExpecting = '';
+        this.node = null;
+        this.escaped = false;
+        this.list = [];
+    }
+    /**
+     * Tokenizes the original input string
+     *
+     * @return {Array} An array of operator|text tokens
+     */
+    tokenize() {
+        let chr;
+        const list = [];
+        for (let i = 0, len = this.str.length; i < len; i++) {
+            chr = this.str.charAt(i);
+            this.checkChar(chr);
+        }
+        this.list.forEach(node => {
+            node.value = (node.value || '').toString().trim();
+            if (node.value) {
+                list.push(node);
+            }
+        });
+        return list;
+    }
+    /**
+     * Checks if a character is an operator or text and acts accordingly
+     *
+     * @param {String} chr Character from the address field
+     */
+    checkChar(chr) {
+        if ((chr in this.operators || chr === '\\') && this.escaped) {
+            this.escaped = false;
+        }
+        else if (this.operatorExpecting && chr === this.operatorExpecting) {
+            this.node = {
+                type: 'operator',
+                value: chr
+            };
+            this.list.push(this.node);
+            this.node = null;
+            this.operatorExpecting = '';
+            this.escaped = false;
+            return;
+        }
+        else if (!this.operatorExpecting && chr in this.operators) {
+            this.node = {
+                type: 'operator',
+                value: chr
+            };
+            this.list.push(this.node);
+            this.node = null;
+            this.operatorExpecting = this.operators[chr];
+            this.escaped = false;
+            return;
+        }
+        if (!this.escaped && chr === '\\') {
+            this.escaped = true;
+            return;
+        }
+        if (!this.node) {
+            this.node = {
+                type: 'text',
+                value: ''
+            };
+            this.list.push(this.node);
+        }
+        if (this.escaped && chr !== '\\') {
+            this.node.value += '\\';
+        }
+        this.node.value += chr;
+        this.escaped = false;
+    }
 }
-
 /**
  * Operator tokens and which tokens are expected to end the sequence
  */
@@ -207,77 +260,3 @@ Tokenizer.prototype.operators = {
     ',': '',
     ':': ';'
 };
-
-/**
- * Tokenizes the original input string
- *
- * @return {Array} An array of operator|text tokens
- */
-Tokenizer.prototype.tokenize = function () {
-    let chr;
-    const list = [];
-    for (let i = 0, len = this.str.length; i < len; i++) {
-        chr = this.str.charAt(i);
-        this.checkChar(chr);
-    }
-
-    this.list.forEach(node => {
-        node.value = (node.value || '').toString().trim();
-        if (node.value) {
-            list.push(node);
-        }
-    });
-
-    return list;
-};
-
-/**
- * Checks if a character is an operator or text and acts accordingly
- *
- * @param {String} chr Character from the address field
- */
-Tokenizer.prototype.checkChar = function (chr) {
-    if ((chr in this.operators || chr === '\\') && this.escaped) {
-        this.escaped = false;
-    } else if (this.operatorExpecting && chr === this.operatorExpecting) {
-        this.node = {
-            type: 'operator',
-            value: chr
-        };
-        this.list.push(this.node);
-        this.node = null;
-        this.operatorExpecting = '';
-        this.escaped = false;
-        return;
-    } else if (!this.operatorExpecting && chr in this.operators) {
-        this.node = {
-            type: 'operator',
-            value: chr
-        };
-        this.list.push(this.node);
-        this.node = null;
-        this.operatorExpecting = this.operators[chr];
-        this.escaped = false;
-        return;
-    }
-
-    if (!this.escaped && chr === '\\') {
-        this.escaped = true;
-        return;
-    }
-
-    if (!this.node) {
-        this.node = {
-            type: 'text',
-            value: ''
-        };
-        this.list.push(this.node);
-    }
-
-    if (this.escaped && chr !== '\\') {
-        this.node.value += '\\';
-    }
-
-    this.node.value += chr;
-    this.escaped = false;
-};

package/dist/esm/arguments.d.ts

@@ -0,0 +1,31 @@
+import type { Attribute, ParsedCommand } from './types.js';
+/**
+ * Checks if a parsed argument is an atom, optionally a specific one
+ *
+ * @param {Object} value Parsed argument
+ * @param {String} [name] Upper case atom to match, the value is compared case-insensitively
+ * @return {Boolean} true for an atom (with that name)
+ */
+declare function isAtom(value: Attribute, name?: string): boolean;
+/**
+ * Checks if a parsed argument is an astring (RFC 3501 section 9): an atom, a quoted string or a literal. An
+ * atom the parser split into a section or partial range (like BODY[1]<0.5>) is not
+ *
+ * @param {Object} value Parsed argument
+ * @return {Boolean} true for an astring
+ */
+declare function isAstring(value: Attribute): boolean;
+/**
+ * The parser turns every NIL atom into null, as in an nstring. Where the grammar has an astring (mailbox names, user
+ * names, search strings, ...) NIL is an ordinary atom, so these nulls are turned back into atoms with the spelling
+ * the client used
+ *
+ * @param {Object} parsed Parsed command, changed in place
+ * @param {String} data Raw command line with its literals
+ * @param {Function} select `(path)` returns true for the nulls to restore, `path` lists the indexes from the
+ *   top-level arguments down, e.g. [2, 0] for the first item of a list in the third argument
+ */
+/** Indexes from the top-level arguments down to a nested value, `'section'` steps into the section of an atom */
+export type ArgumentPath = (number | string)[];
+declare function restoreNilAtoms(parsed: ParsedCommand, data: string, select: (path: ArgumentPath) => boolean): void;
+export { isAtom, isAstring, restoreNilAtoms };