imapkit 4.0.3 → 4.1.0

package/dist/cjs/mock-client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @namespace Mockup module
+ * @name mockup
+ */
+export default runClientMockup;
+/**
+ * <p>Runs a batch of IMAP commands against a server, like a well behaved client would</p>
+ *
+ * <ul>
+ * <li>a command is sent only after the tagged response of the previous command arrived
+ *     (RFC 3501 section 5.5 forbids pipelining in many cases)</li>
+ * <li>the data of a synchronizing literal ({n}) is sent only after the server's "+"
+ *     continuation request (RFC 3501 section 4.3)</li>
+ * <li>when the server sends a "+" continuation request and the command has no literal
+ *     data left, the next entry of the command list is sent as the continuation data
+ *     (an AUTHENTICATE response, or DONE to end IDLE)</li>
+ * <li>after the tagged response of a STARTTLS command the connection is upgraded to TLS</li>
+ * <li>after the tagged OK of a COMPRESS DEFLATE command, data in both directions is compressed
+ *     (RFC 4978). The client ends its compression after an UNAUTHENTICATE command, and expects
+ *     the server to end its compression after the tagged OK (RFC 8437 section 4.1)</li>
+ * <li>the callback gets the decompressed data</li>
+ * <li>after the last command the connection is closed and the callback gets the transcript</li>
+ * </ul>
+ *
+ * <pre>
+ * var cmds = ["A1 CAPABILITY", "A2 STARTTLS", "A3 LOGIN username password", "A4 LOGOUT"];
+ * runClientMockup(143, "localhost", cmds, false, function(resp){
+ *     console.log("Final:", resp.toString("utf-8").trim());
+ * });
+ * </pre>
+ *
+ * @memberOf mockup
+ * @param {Number} port Port number
+ * @param {String} host Hostname to connect to
+ * @param {Array} commands Command list to be sent to server, as binary strings
+ * @param {Boolean} [debug] if set to true log all input/output
+ * @param {Function} callback Callback function to run on completion, gets everything the server sent as a Buffer
+ */
+declare function runClientMockup(port: number | null | undefined, host: string | null | undefined, commands: string[], debug?: boolean | null, callback?: ((response: Buffer) => void) | null): void;

package/dist/cjs/mock-client.js

@@ -0,0 +1,236 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_net_1 = __importDefault(require("node:net"));
+const node_tls_1 = __importDefault(require("node:tls"));
+const framing_js_1 = require("./framing.js");
+const deflate_layer_js_1 = __importDefault(require("./deflate-layer.js"));
+/**
+ * @namespace Mockup module
+ * @name mockup
+ */
+exports.default = runClientMockup;
+/**
+ * <p>Runs a batch of IMAP commands against a server, like a well behaved client would</p>
+ *
+ * <ul>
+ * <li>a command is sent only after the tagged response of the previous command arrived
+ *     (RFC 3501 section 5.5 forbids pipelining in many cases)</li>
+ * <li>the data of a synchronizing literal ({n}) is sent only after the server's "+"
+ *     continuation request (RFC 3501 section 4.3)</li>
+ * <li>when the server sends a "+" continuation request and the command has no literal
+ *     data left, the next entry of the command list is sent as the continuation data
+ *     (an AUTHENTICATE response, or DONE to end IDLE)</li>
+ * <li>after the tagged response of a STARTTLS command the connection is upgraded to TLS</li>
+ * <li>after the tagged OK of a COMPRESS DEFLATE command, data in both directions is compressed
+ *     (RFC 4978). The client ends its compression after an UNAUTHENTICATE command, and expects
+ *     the server to end its compression after the tagged OK (RFC 8437 section 4.1)</li>
+ * <li>the callback gets the decompressed data</li>
+ * <li>after the last command the connection is closed and the callback gets the transcript</li>
+ * </ul>
+ *
+ * <pre>
+ * var cmds = ["A1 CAPABILITY", "A2 STARTTLS", "A3 LOGIN username password", "A4 LOGOUT"];
+ * runClientMockup(143, "localhost", cmds, false, function(resp){
+ *     console.log("Final:", resp.toString("utf-8").trim());
+ * });
+ * </pre>
+ *
+ * @memberOf mockup
+ * @param {Number} port Port number
+ * @param {String} host Hostname to connect to
+ * @param {Array} commands Command list to be sent to server, as binary strings
+ * @param {Boolean} [debug] if set to true log all input/output
+ * @param {Function} callback Callback function to run on completion, gets everything the server sent as a Buffer
+ */
+function runClientMockup(port, host, commands, debug, callback) {
+    const hostname = host || 'localhost';
+    const portNumber = port || 143;
+    const queue = Array.isArray(commands) ? splitLiterals(commands) : [];
+    const responses = [];
+    let buffer = '';
+    // tag of the command waiting for its tagged response
+    let currentTag = null;
+    let currentCommand = '';
+    let lastResponse = '';
+    let greeted = false;
+    let finished = false;
+    let socket = node_net_1.default.connect(portNumber, hostname);
+    // COMPRESS=DEFLATE layer, once the server accepted COMPRESS
+    let layer = null;
+    const log = (prefix, str) => {
+        if (debug) {
+            console.log(prefix + ' ' + str.replace(/\r?\n$/, ''));
+        }
+    };
+    const write = (text) => {
+        log('C:', text);
+        if (layer) {
+            layer.write(Buffer.from(text, 'binary'));
+        }
+        else {
+            socket.write(text, 'binary');
+        }
+    };
+    const finish = () => {
+        if (finished) {
+            return;
+        }
+        finished = true;
+        if (buffer) {
+            // an incomplete response
+            responses.push(Buffer.from(buffer, 'binary'));
+        }
+        if (layer) {
+            layer.destroy();
+        }
+        if (typeof callback === 'function') {
+            callback(Buffer.concat(responses));
+        }
+    };
+    const sendNext = () => {
+        // literal data that the previous command did not get to send is dropped
+        while (queue.length && queue[0].continuation) {
+            queue.shift();
+        }
+        if (!queue.length) {
+            currentTag = null;
+            socket.end();
+            return;
+        }
+        const next = queue.shift();
+        currentCommand = next.text.replace(/\r\n$/, '');
+        currentTag = currentCommand.split(' ').shift();
+        write(next.text);
+        if (layer && /^\S+ UNAUTHENTICATE$/i.test(currentCommand)) {
+            // the client ends its compression after the CRLF of UNAUTHENTICATE (RFC 8437 section 4.1)
+            layer.end();
+        }
+    };
+    // literal data for the current command, or a continuation line such as DONE
+    const onContinuation = () => {
+        if (!queue.length) {
+            return;
+        }
+        write(queue.shift().text);
+    };
+    const upgrade = () => {
+        const plain = socket;
+        plain.removeAllListeners('data');
+        plain.removeAllListeners('close');
+        socket = node_tls_1.default.connect({ socket: plain, host: hostname, rejectUnauthorized: false }, () => {
+            log('TLS', 'connection secured');
+            sendNext();
+        });
+        attach(socket);
+    };
+    // everything after the CRLF of the tagged OK is compressed (RFC 4978 section 3)
+    const startCompression = () => {
+        layer = new deflate_layer_js_1.default({
+            writeRaw: (chunk) => socket.write(chunk),
+            onData: onData,
+            onError: (err) => {
+                log('Compression error:', err.message);
+                socket.destroy();
+            }
+        });
+    };
+    // returns true if compression starts after this response
+    const onTagged = () => {
+        let compress = false;
+        if (/^\S+ OK/i.test(lastResponse)) {
+            if (/^\S+ STARTTLS$/i.test(currentCommand)) {
+                upgrade();
+                return false;
+            }
+            if (/^\S+ COMPRESS DEFLATE$/i.test(currentCommand)) {
+                startCompression();
+                compress = true;
+            }
+            else if (layer && /^\S+ UNAUTHENTICATE$/i.test(currentCommand)) {
+                // the server ends its compression after the CRLF of the OK
+                layer.endInput();
+            }
+        }
+        sendNext();
+        return compress;
+    };
+    // Splits the received data into complete responses, a response may contain literals
+    const processBuffer = () => {
+        const framed = (0, framing_js_1.splitResponses)(buffer);
+        for (const response of framed.responses) {
+            lastResponse = buffer.slice(response.start, response.end);
+            responses.push(Buffer.from(lastResponse, 'binary'));
+            if (!greeted) {
+                greeted = true;
+                sendNext();
+            }
+            else if (lastResponse.charAt(0) === '+') {
+                onContinuation();
+            }
+            else if (currentTag && lastResponse.substr(0, currentTag.length + 1) === currentTag + ' ' && onTagged()) {
+                // compression started, the rest of the data is compressed
+                const rest = buffer.slice(response.end);
+                buffer = '';
+                if (rest) {
+                    // onTagged() started the compression
+                    layer.receive(Buffer.from(rest, 'binary'));
+                }
+                return;
+            }
+        }
+        buffer = buffer.slice(framed.end);
+    };
+    function onData(chunk) {
+        log('S:', chunk.toString('binary'));
+        buffer += chunk.toString('binary');
+        processBuffer();
+    }
+    function attach(sock) {
+        sock.on('data', (chunk) => {
+            if (layer) {
+                layer.receive(chunk);
+            }
+            else {
+                onData(chunk);
+            }
+        });
+        sock.on('error', (err) => {
+            log('Socket error:', err.message);
+            // the close event follows and returns what was received so far
+        });
+        // the last data may still be in the decompressor
+        sock.on('close', () => (layer ? layer.whenIdle(finish) : finish()));
+    }
+    attach(socket);
+}
+/**
+ * Splits commands at synchronizing literals, so that literal data can wait for the
+ * continuation request
+ *
+ * @param {Array} commands Command strings
+ * @return {Array} Parts to send, as {text, continuation}, the last part of a command ends with CRLF
+ */
+function splitLiterals(commands) {
+    const parts = [];
+    commands.forEach((command) => {
+        (0, framing_js_1.splitAtLiterals)(String(command) + '\r\n').forEach((text, i) => {
+            parts.push({ text, continuation: i > 0 });
+        });
+    });
+    return parts;
+}
+{
+    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/numbers.d.ts

@@ -0,0 +1,28 @@
+declare const MAX_NUMBER = 4294967295;
+declare const MAX_NUMBER64: bigint;
+/**
+ * Checks if a value is a number by the grammar: 1*DIGIT, up to a limit
+ *
+ * @param {*} value Value to check, only strings can match
+ * @param {Number|BigInt} [max] Largest allowed value, MAX_NUMBER by default
+ * @return {Boolean} true if the value is a number within the limit
+ */
+declare function isNumber(value: unknown, max?: number | bigint): boolean;
+/**
+ * Checks if a value is a non-zero number (nz-number, nz-number64): digit-nz *DIGIT, up to a limit
+ *
+ * @param {*} value Value to check, only strings can match
+ * @param {Number|BigInt} [max] Largest allowed value, MAX_NUMBER by default
+ * @return {Boolean} true if the value is a non-zero number within the limit
+ */
+declare function isNzNumber(value: unknown, max?: number | bigint): boolean;
+/**
+ * Checks if a value is a sequence set (RFC 3501 and RFC 9051 section 9): seq-number or seq-range items
+ * separated by commas, seq-number = nz-number / "*"
+ *
+ * @param {*} value Value to check, only strings can match
+ * @param {Boolean} [noStar] If true, "*" is not allowed (e.g. known-uids of RFC 7162 section 7)
+ * @return {Boolean} true if the value is a valid sequence set
+ */
+declare function isSequenceSet(value: unknown, noStar?: boolean): boolean;
+export { MAX_NUMBER, MAX_NUMBER64, isNumber, isNzNumber, isSequenceSet };

package/dist/cjs/numbers.js

@@ -0,0 +1,52 @@
+"use strict";
+// Limits and checks of the numbers in the IMAP grammar
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_NUMBER64 = exports.MAX_NUMBER = void 0;
+exports.isNumber = isNumber;
+exports.isNzNumber = isNzNumber;
+exports.isSequenceSet = isSequenceSet;
+// RFC 3501 and RFC 9051 section 9: number and nz-number are unsigned 32-bit integers
+const MAX_NUMBER = 4294967295;
+exports.MAX_NUMBER = MAX_NUMBER;
+// RFC 9051 section 9: number64 is an unsigned 63-bit integer, so is mod-sequence-value (RFC 7162 section 7)
+const MAX_NUMBER64 = 2n ** 63n - 1n;
+exports.MAX_NUMBER64 = MAX_NUMBER64;
+/**
+ * Checks if a value is a number by the grammar: 1*DIGIT, up to a limit
+ *
+ * @param {*} value Value to check, only strings can match
+ * @param {Number|BigInt} [max] Largest allowed value, MAX_NUMBER by default
+ * @return {Boolean} true if the value is a number within the limit
+ */
+function isNumber(value, max) {
+    const limit = String(max === undefined ? MAX_NUMBER : max);
+    // a longer string of digits is too large anyway, so no BigInt is built from it
+    if (typeof value !== 'string' || !/^\d+$/.test(value) || value.replace(/^0+(?=\d)/, '').length > limit.length) {
+        return false;
+    }
+    return BigInt(value) <= BigInt(limit);
+}
+/**
+ * Checks if a value is a non-zero number (nz-number, nz-number64): digit-nz *DIGIT, up to a limit
+ *
+ * @param {*} value Value to check, only strings can match
+ * @param {Number|BigInt} [max] Largest allowed value, MAX_NUMBER by default
+ * @return {Boolean} true if the value is a non-zero number within the limit
+ */
+function isNzNumber(value, max) {
+    return isNumber(value, max) && /^[1-9]/.test(value);
+}
+/**
+ * Checks if a value is a sequence set (RFC 3501 and RFC 9051 section 9): seq-number or seq-range items
+ * separated by commas, seq-number = nz-number / "*"
+ *
+ * @param {*} value Value to check, only strings can match
+ * @param {Boolean} [noStar] If true, "*" is not allowed (e.g. known-uids of RFC 7162 section 7)
+ * @return {Boolean} true if the value is a valid sequence set
+ */
+function isSequenceSet(value, noStar) {
+    if (typeof value !== 'string' || !/^[\d*]+(:[\d*]+)?(,[\d*]+(:[\d*]+)?)*$/.test(value)) {
+        return false;
+    }
+    return value.split(/[,:]/).every(part => (part === '*' ? !noStar : isNzNumber(part)));
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "commonjs"
+}

package/dist/cjs/plugins/acl.d.ts

@@ -0,0 +1,2 @@
+import type { IMAPServer } from '../types.js';
+export default function aclPlugin(server: IMAPServer): void;