imapkit 4.0.2 → 4.1.0

package/dist/cjs/deflate-layer.js

@@ -0,0 +1,232 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_zlib_1 = __importDefault(require("node:zlib"));
+// Z_SYNC_FLUSH ends with an empty stored block, LEN 0 and NLEN 0xFFFF (RFC 1951 section 3.2.4)
+const SYNC_MARKER = Buffer.from([0x00, 0x00, 0xff, 0xff]);
+// Z_FINISH right after a flush is an empty final block with fixed Huffman codes
+const EMPTY_FINAL_BLOCK = Buffer.from([0x03, 0x00]);
+/**
+ * One end of a COMPRESS=DEFLATE layer (RFC 4978): raw DEFLATE (RFC 1951, no zlib header or
+ * checksum) in both directions. The server plugin uses it, and so do the clients of the tests and
+ * the compare tool.
+ *
+ * Either direction can be terminated, which UNAUTHENTICATE requires (RFC 8437 section 4.1). Output
+ * terminates with a final DEFLATE block, data written after that goes out uncompressed once the
+ * compressed data is out. Input terminates where the peer ended its compression: at the end of
+ * its DEFLATE stream if it sent a final block, otherwise at the end of the sync flush that
+ * carried the last compressed data. The input is split at sync flush markers to find that point.
+ */
+class DeflateLayer {
+    /**
+     * @param {Object} options
+     * @param {Function} options.writeRaw `(buffer)` sends octets to the peer
+     * @param {Function} options.onData `(buffer)` gets the input, decompressed while compression is active
+     * @param {Function} [options.onError] `(err)` called when the input is not valid DEFLATE data
+     */
+    constructor(options) {
+        this.writeRaw = options.writeRaw;
+        this.onData = options.onData;
+        this.onError = options.onError || (() => false);
+        // outgoing data is compressed
+        this.active = true;
+        // incoming data is compressed
+        this.inputActive = true;
+        this._deflate = node_zlib_1.default.createDeflateRaw();
+        this._deflate.on('data', (chunk) => this.writeRaw(chunk));
+        this._deflate.on('error', (err) => this.onError(err));
+        // writes that wait for the final compressed data, null when nothing is waiting
+        this._held = null;
+        this._endCallbacks = [];
+        this._flushScheduled = false;
+        this._inflate = node_zlib_1.default.createInflateRaw({ flush: node_zlib_1.default.constants.Z_SYNC_FLUSH });
+        this._inflate.on('data', (chunk) => {
+            // anything the peer compressed after it ended its compression is dropped
+            if (this.inputActive) {
+                this.onData(chunk);
+            }
+        });
+        this._inflate.on('error', (err) => {
+            this.inputActive = false;
+            this._pieces = [];
+            this._busy = false;
+            this.onError(err);
+            this._next();
+        });
+        // input waiting for the inflater, split at sync flush markers
+        this._pieces = [];
+        this._busy = false;
+        // octets given to the inflater
+        this._fed = 0;
+        // the peer may still send the empty final block of its DEFLATE stream
+        this._expectFinal = false;
+        // called once the received data is processed
+        this._idleCallbacks = [];
+    }
+    /**
+     * Sends data to the peer, compressed while compression is active
+     *
+     * @param {Buffer} data Data to send
+     */
+    write(data) {
+        if (this._held) {
+            this._held.push(data);
+            return;
+        }
+        if (!this.active) {
+            this.writeRaw(data);
+            return;
+        }
+        this._deflate.write(data);
+        if (!this._flushScheduled) {
+            // everything written in one go, like a burst of responses, is flushed together, so the peer
+            // gets it right away instead of when the compressor buffer fills up (RFC 4978 section 4)
+            this._flushScheduled = true;
+            process.nextTick(() => {
+                this._flushScheduled = false;
+                if (this.active && !this._deflate.destroyed) {
+                    this._deflate.flush(node_zlib_1.default.constants.Z_SYNC_FLUSH);
+                }
+            });
+        }
+    }
+    /**
+     * Terminates the outgoing compression with a final DEFLATE block. Later writes are sent
+     * uncompressed, after the compressed data.
+     *
+     * @param {Function} [callback] Called once the compressed data is written out
+     */
+    end(callback) {
+        if (callback) {
+            this._endCallbacks.push(callback);
+        }
+        if (!this.active) {
+            if (!this._held) {
+                this._runCallbacks('_endCallbacks');
+            }
+            return;
+        }
+        this.active = false;
+        this._held = [];
+        this._deflate.once('end', () => {
+            const held = this._held || [];
+            this._held = null;
+            held.forEach(data => this.writeRaw(data));
+            this._runCallbacks('_endCallbacks');
+        });
+        this._deflate.end();
+    }
+    // calls the callbacks of a list once, callbacks added meanwhile wait for the next run
+    _runCallbacks(key) {
+        const callbacks = this[key];
+        this[key] = [];
+        callbacks.forEach(callback => callback());
+    }
+    /**
+     * Handles octets received from the peer
+     *
+     * @param {Buffer} chunk Received data
+     */
+    receive(chunk) {
+        if (!this.inputActive && !this._busy && !this._pieces.length) {
+            this._receivePlain(chunk);
+            return;
+        }
+        let start = 0;
+        let pos;
+        while ((pos = chunk.indexOf(SYNC_MARKER, start)) >= 0) {
+            this._pieces.push(chunk.subarray(start, pos + SYNC_MARKER.length));
+            start = pos + SYNC_MARKER.length;
+        }
+        if (start < chunk.length) {
+            this._pieces.push(chunk.subarray(start));
+        }
+        this._next();
+    }
+    /**
+     * Tells the layer that the peer terminates its compression after the data decompressed so far
+     * (RFC 8437 section 4.1). Call it from onData, the rest of the input is then passed on as is.
+     */
+    endInput() {
+        this.inputActive = false;
+    }
+    /**
+     * Calls back once all received data is passed on
+     *
+     * @param {Function} callback Function to call
+     */
+    whenIdle(callback) {
+        this._idleCallbacks.push(callback);
+        this._next();
+    }
+    _next() {
+        if (this._busy) {
+            return;
+        }
+        if (!this._pieces.length) {
+            this._runCallbacks('_idleCallbacks');
+            return;
+        }
+        if (!this.inputActive) {
+            const rest = Buffer.concat(this._pieces);
+            this._pieces = [];
+            this._receivePlain(rest);
+            this._next();
+            return;
+        }
+        const piece = this._pieces.shift();
+        this._busy = true;
+        this._fed += piece.length;
+        this._inflate.write(piece, () => {
+            this._busy = false;
+            // octets the inflater did not use follow the end of the peer's DEFLATE stream
+            const unused = this._fed - this._inflate.bytesWritten;
+            if (unused > 0 || this._inflate.readableEnded) {
+                this.inputActive = false;
+                if (unused > 0) {
+                    this._pieces.unshift(piece.subarray(piece.length - unused));
+                }
+            }
+            else if (!this.inputActive) {
+                // the input ended at a sync flush, the final block may still follow
+                this._expectFinal = true;
+            }
+            this._next();
+        });
+    }
+    _receivePlain(chunk) {
+        if (this._expectFinal) {
+            this._expectFinal = false;
+            if (chunk.subarray(0, EMPTY_FINAL_BLOCK.length).equals(EMPTY_FINAL_BLOCK)) {
+                chunk = chunk.subarray(EMPTY_FINAL_BLOCK.length);
+            }
+        }
+        if (chunk.length) {
+            this.onData(chunk);
+        }
+    }
+    /**
+     * Frees the compressor and the decompressor
+     */
+    destroy() {
+        this.active = this.inputActive = false;
+        this._pieces = [];
+        this._deflate.destroy();
+        this._inflate.destroy();
+    }
+}
+exports.default = DeflateLayer;
+{
+    const defaultExport = exports.default;
+    if (defaultExport && (typeof defaultExport === 'function' || typeof defaultExport === 'object')) {
+        for (const key of Object.keys(exports)) {
+            if (key !== 'default' && !(key in defaultExport)) {
+                defaultExport[key] = exports[key];
+            }
+        }
+        Object.defineProperty(defaultExport, 'default', { value: defaultExport, enumerable: false, writable: true, configurable: true });
+        module.exports = defaultExport;
+    }
+}

package/dist/cjs/encoded-words.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reads a binary string (one char per octet) as UTF-8, invalid sequences become U+FFFD
+ */
+declare function decodeUtf8(value: string): string;
+/**
+ * Decodes an RFC 2047 header value to a Unicode string. Text outside encoded words is read as UTF-8
+ * (invalid sequences become U+FFFD). Adjacent encoded words in the same charset are decoded together,
+ * so a multi-octet character may span them, and the white space between them is dropped (RFC 2047
+ * section 6.2). Encoded words in an unknown charset are kept as they are.
+ *
+ * @param {String} value Header value as a binary string
+ * @return {String} Decoded value
+ */
+declare function decodeHeader(input: unknown): string;
+export { decodeHeader, decodeUtf8 };

package/dist/cjs/encoded-words.js

@@ -0,0 +1,85 @@
+"use strict";
+// RFC 2047 encoded words in header values, decoded for SEARCH, SORT and THREAD
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeHeader = decodeHeader;
+exports.decodeUtf8 = decodeUtf8;
+// RFC 2047 section 2: encoded-word = "=?" charset "?" encoding "?" encoded-text "?=", RFC 2231 section 5
+// adds an optional "*" language suffix to the charset
+const ENCODED_WORD = /=\?([^?\s*]+)(?:\*[^?\s]*)?\?([BbQq])\?([^?\s]*)\?=/g;
+const utf8Decoder = new TextDecoder('utf-8');
+/**
+ * Reads a binary string (one char per octet) as UTF-8, invalid sequences become U+FFFD
+ */
+function decodeUtf8(value) {
+    return utf8Decoder.decode(Buffer.from(value, 'binary'));
+}
+// decoders by lower case charset name, false for a charset that TextDecoder does not know
+const decoders = new Map();
+/**
+ * Decodes the octets of an encoded word, or returns false if the charset is unknown
+ */
+function decodeCharset(charset, octets) {
+    charset = charset.toLowerCase();
+    if (!decoders.has(charset)) {
+        let decoder = false;
+        try {
+            decoder = new TextDecoder(charset);
+        }
+        catch {
+            // unknown charset
+        }
+        decoders.set(charset, decoder);
+    }
+    const decoder = decoders.get(charset);
+    return decoder ? decoder.decode(octets) : false;
+}
+/**
+ * Decodes an RFC 2047 header value to a Unicode string. Text outside encoded words is read as UTF-8
+ * (invalid sequences become U+FFFD). Adjacent encoded words in the same charset are decoded together,
+ * so a multi-octet character may span them, and the white space between them is dropped (RFC 2047
+ * section 6.2). Encoded words in an unknown charset are kept as they are.
+ *
+ * @param {String} value Header value as a binary string
+ * @return {String} Decoded value
+ */
+function decodeHeader(input) {
+    const value = String(input || '');
+    if (value.indexOf('=?') < 0 && !/[\u0080-\u00ff]/.test(value)) {
+        // nothing to decode
+        return value;
+    }
+    let result = '';
+    let pending = null;
+    let lastIndex = 0;
+    const flush = () => {
+        if (pending) {
+            const decoded = decodeCharset(pending.charset, Buffer.concat(pending.octets));
+            result += decoded === false ? pending.source : decoded;
+            pending = null;
+        }
+    };
+    ENCODED_WORD.lastIndex = 0;
+    let match;
+    while ((match = ENCODED_WORD.exec(value))) {
+        const between = value.substring(lastIndex, match.index);
+        const adjacent = pending && /^\s*$/.test(between);
+        if (!adjacent) {
+            flush();
+            result += decodeUtf8(between);
+        }
+        lastIndex = ENCODED_WORD.lastIndex;
+        const octets = match[2].toUpperCase() === 'B'
+            ? Buffer.from(match[3], 'base64')
+            : Buffer.from(match[3].replace(/_/g, ' ').replace(/=([0-9a-fA-F]{2})/g, (m, hex) => String.fromCharCode(parseInt(hex, 16))), 'binary');
+        if (pending && pending.charset.toLowerCase() !== match[1].toLowerCase()) {
+            flush();
+        }
+        if (!pending) {
+            pending = { charset: match[1], octets: [], source: '' };
+        }
+        pending.octets.push(octets);
+        pending.source += (pending.source ? between : '') + match[0];
+    }
+    flush();
+    return result + decodeUtf8(value.substr(lastIndex));
+}

package/dist/cjs/envelope.d.ts

@@ -0,0 +1,33 @@
+import type { ParsedAddress } from './addressparser.js';
+import type { ParsedHeader } from './mimeparser.js';
+/** An address of the ENVELOPE (RFC 3501 section 9): name, source route, mailbox and host, all NIL for a group end */
+export type EnvelopeAddress = [name: string | null, adl: null, mailbox: string | null, host: string | null];
+/** The fields of the ENVELOPE (RFC 3501 section 7.4.2), in order */
+export type Envelope = [
+    date: string | null,
+    subject: string | null,
+    from: EnvelopeAddress[] | null,
+    sender: EnvelopeAddress[] | null,
+    replyTo: EnvelopeAddress[] | null,
+    to: EnvelopeAddress[] | null,
+    cc: EnvelopeAddress[] | null,
+    bcc: EnvelopeAddress[] | null,
+    inReplyTo: string | null,
+    messageId: string | null
+];
+/**
+ * Convert a message object to an ENVELOPE object
+ *
+ * @param {Object} header Parsed header of a mime tree node
+ * @return {Object} ENVELOPE compatible object
+ */
+export default function envelope(header: ParsedHeader): Envelope;
+/**
+ * Converts an address object to a list of arrays
+ * [{name: "User Name", addres:"user@example.com"}] -> [["User Name", null, "user", "example.com"]]
+ *
+ * @param {Array} arr An array of address objects
+ * @return {Array} A list of addresses
+ */
+declare function processAddress(arr: ParsedAddress | ParsedAddress[] | undefined, def?: ParsedAddress | ParsedAddress[]): EnvelopeAddress[] | null;
+export { processAddress };

package/dist/cjs/envelope.js

@@ -0,0 +1,86 @@
+"use strict";
+// This module converts message structure into an ENVELOPE object
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = envelope;
+exports.processAddress = processAddress;
+/**
+ * Convert a message object to an ENVELOPE object
+ *
+ * @param {Object} header Parsed header of a mime tree node
+ * @return {Object} ENVELOPE compatible object
+ */
+function envelope(header) {
+    // RFC 3501 9: env-date and env-subject are nstring, NIL when the header is missing
+    const subject = header.subject;
+    return [
+        header.date || null,
+        typeof subject === 'string' ? subject : null,
+        processAddress(header.from),
+        processAddress(header.sender, header.from),
+        processAddress(header['reply-to'], header.from),
+        processAddress(header.to),
+        processAddress(header.cc),
+        processAddress(header.bcc),
+        // If this is an embedded MESSAGE/RFC822, then Gmail seems to
+        // have a bug here, it states '"NIL"' as the value, not 'NIL'
+        header['in-reply-to'] || null,
+        header['message-id'] || null
+    ];
+}
+/**
+ * Converts an address object to a list of arrays
+ * [{name: "User Name", addres:"user@example.com"}] -> [["User Name", null, "user", "example.com"]]
+ *
+ * @param {Array} arr An array of address objects
+ * @return {Array} A list of addresses
+ */
+function processAddress(arr, def) {
+    let list = [].concat(arr || []);
+    if (!list.length) {
+        list = [].concat(def || []);
+    }
+    if (!list.length) {
+        return null;
+    }
+    let result = [];
+    list.forEach(addr => {
+        if (addr.group) {
+            // Handle group syntax
+            result.push([null, null, addr.name || '', null]);
+            result = result.concat(processAddress(addr.group) || []);
+            result.push([null, null, null, null]);
+            return;
+        }
+        let name = addr.name || null;
+        let address = addr.address || '';
+        if (!address && name) {
+            // a bare word ("To: localuser") is the mailbox, not the name
+            address = name;
+            name = null;
+        }
+        if (!address) {
+            return;
+        }
+        const at = address.lastIndexOf('@');
+        const user = at >= 0 ? address.substr(0, at) : address;
+        // RFC 3501 7.4.2 reserves a NIL host for group markers, so an address without a domain gets
+        // the placeholder host that Dovecot uses for the same input
+        const domain = (at >= 0 ? address.substr(at + 1) : '') || 'MISSING_DOMAIN';
+        result.push([name, null, user || null, domain]);
+    });
+    // env-from = "(" 1*address ")", there is no SP between the addresses (RFC 3501 section 9)
+    Object.defineProperty(result, 'adjacentLists', { value: true });
+    return result.length ? result : null;
+}
+{
+    const defaultExport = exports.default;
+    if (defaultExport && (typeof defaultExport === 'function' || typeof defaultExport === 'object')) {
+        for (const key of Object.keys(exports)) {
+            if (key !== 'default' && !(key in defaultExport)) {
+                defaultExport[key] = exports[key];
+            }
+        }
+        Object.defineProperty(defaultExport, 'default', { value: defaultExport, enumerable: false, writable: true, configurable: true });
+        module.exports = defaultExport;
+    }
+}

package/dist/cjs/esearch.d.ts

@@ -0,0 +1,96 @@
+import type { SearchResult } from './commands/handlers/search.js';
+import type { Attribute, IMAPResponse, IMAPServer, Mailbox, Message } from './types.js';
+/** A parsed PARTIAL range, see parsePartialRange() */
+export interface PartialRange {
+    /** the argument as the client sent it */
+    range: string;
+    from: number;
+    to: number;
+    /** partial-range-last, counted from the last result */
+    fromEnd: boolean;
+}
+/** Upper case result option names to their arguments (`parsed.searchReturn`), PARTIAL has its parsed range */
+export type SearchReturn = Map<string, any>;
+/** The parts of a search result that the ESEARCH response is built from */
+export type EsearchResult = Pick<SearchResult, 'list' | 'numbers'>;
+/**
+ * ESEARCH response helpers (RFC 4731, RFC 4466 section 2.6.2). Used by the ESEARCH, SEARCHRES, PARTIAL,
+ * CONTEXT=SEARCH and MULTISEARCH plugins, and meant to be reused where SEARCH always answers with ESEARCH (IMAP4rev2, RFC 9051).
+ */
+/**
+ * Formats a list of numbers as a compact sequence-set, e.g. [1, 2, 3, 5] becomes "1:3,5"
+ *
+ * @param {Array} numbers List of nz-numbers, in any order
+ * @return {String} sequence-set, empty for an empty list
+ */
+declare function toSequenceSet(numbers: Iterable<number>): string;
+/**
+ * Formats a list of numbers as a sequence-set that keeps their order, for SORT results (RFC 5267
+ * section 3.2): only runs of ascending consecutive numbers become ranges, e.g. [5, 3, 4, 2] becomes "5,3:4,2"
+ *
+ * @param {Array} numbers List of nz-numbers in the requested order
+ * @return {String} sequence-set, empty for an empty list
+ */
+declare function toOrderedSet(numbers: number[]): string;
+/**
+ * Parses the argument of the PARTIAL search return option (RFC 5267 section 4.4, RFC 9394 section 4):
+ * partial-range-first = nz-number ":" nz-number, partial-range-last = "-" nz-number ":" "-" nz-number.
+ * "*" is not allowed, and 500:400 is the same as 400:500
+ *
+ * @param {Object} item Parsed argument
+ * @param {Boolean} allowLast If true, the partial-range-last form of RFC 9394 is accepted
+ * @return {Object} `{ range, from, to, fromEnd }`, `range` is the argument as the client sent it
+ */
+declare function parsePartialRange(item: Attribute, allowLast: boolean): PartialRange;
+/**
+ * Picks the results that a PARTIAL range refers to. The first result is 1, and -1 is the last one
+ * (RFC 9394 section 3.1). Results outside the list are left out
+ *
+ * @param {Array} list Results in mailbox order
+ * @param {Object} partial Parsed range, see parsePartialRange
+ * @return {Array} results in the range, in mailbox order
+ */
+declare function selectPartial<T>(list: T[], partial: PartialRange): T[];
+/**
+ * Registers the PARTIAL search return option, shared by the PARTIAL and CONTEXT=SEARCH plugins. The
+ * partial-range-last form (-1:-100) is only valid with the PARTIAL capability (RFC 9394 section 4)
+ *
+ * @param {Object} server IMAP server, with the ESEARCH plugin loaded
+ */
+declare function registerPartialOption(server: IMAPServer): void;
+/**
+ * Picks the messages that the requested result options return. With COUNT or ALL, or without
+ * MIN, MAX and PARTIAL, these are all matching messages, otherwise the lowest and/or the highest
+ * matching message and the ones in the PARTIAL range. This is the set that the MODSEQ result
+ * option describes (RFC 4731 section 3.2) and that SAVE stores (RFC 5182 section 2.4, RFC 9394
+ * section 3.2)
+ *
+ * @param {Array} list Matching messages, in mailbox order
+ * @param {Map} options Upper case result option names to their arguments, an empty map stands for ALL
+ * @return {Array} returned messages, in mailbox order
+ */
+declare function selectReturned<T>(list: T[], options: SearchReturn): T[];
+/**
+ * Builds the search correlator (RFC 4466 section 2.6.2), with the MAILBOX and UIDVALIDITY
+ * correlators of RFC 7377 section 4 if a mailbox is given
+ *
+ * @param {String} tag Tag of the command
+ * @param {Object} [mailbox] Mailbox the response is about
+ * @return {Array} correlator list
+ */
+declare function buildCorrelator(tag: string, mailbox?: Mailbox | null): Attribute[];
+/**
+ * Builds an ESEARCH response (RFC 4466 section 2.6.2) with the RFC 4731 section 3.1 return data
+ * and PARTIAL (RFC 5267 section 4.4, RFC 9394 section 3.1)
+ *
+ * @param {String} tag Tag of the command, for the search correlator
+ * @param {Boolean} isUid If true, the response lists UIDs and has the UID indicator
+ * @param {Object} result Search result, `{ list, numbers }` (see src/commands/handlers/search.ts)
+ * @param {Map} options Upper case result option names to their arguments, an empty map stands for ALL (RFC 4731 section 3.1)
+ * @param {Object} [mailbox] Adds the MAILBOX and UIDVALIDITY correlators of RFC 7377 for this mailbox
+ * @param {Array} [sorted] The matching messages in sort order, for an extended SORT (RFC 5267 section 3.1): MIN and MAX are
+ *        the first and the last sorted message, ALL and PARTIAL list the results in sort order
+ * @return {Object} response for connection.send()
+ */
+declare function buildEsearchResponse(tag: string, isUid: boolean, result: EsearchResult, options: SearchReturn, mailbox?: Mailbox | null, sorted?: Message[] | null): IMAPResponse;
+export { toSequenceSet, toOrderedSet, selectReturned, selectPartial, parsePartialRange, registerPartialOption, buildCorrelator, buildEsearchResponse };