imapkit 4.1.1 → 4.3.0

package/dist/cjs/server.js

@@ -54,8 +54,11 @@ const numbers_js_1 = require("./numbers.js");
 const arguments_js_1 = require("./arguments.js");
 const append_js_1 = require("./commands/append.js");
 const bundledCert = __importStar(require("./cert.js"));
+const script_js_1 = require("./script.js");
 // longest command line (not counting literals) accepted from a client
 const MAX_LINE_LENGTH = 1024 * 1024;
+// milliseconds between the last output and the RST of a script rule with `close: 'reset'`
+const RESET_DELAY = 20;
 // largest literal accepted after login, override with the maxLiteralSize option
 const MAX_LITERAL_SIZE = 64 * 1024 * 1024;
 // largest literal accepted before login, enough for any user name or password
@@ -196,6 +199,9 @@ class IMAPServer extends node_stream_1.Stream {
         this.referenceNamespace = false;
         // the session whose command is running, see IMAPServer#notify
         this.activeConnection = null;
+        this.sessionCounter = 0;
+        // rules that make the server misbehave on purpose, from the script option or server.script.add()
+        this.script = new script_js_1.ServerScript(this, this.options.script);
         // users and storage are deep copied, so that runtime changes never leak into
         // the caller's objects or into other servers built from the same fixture.
         // Without a prototype, user names like "__proto__" or "toString" are plain keys
@@ -1254,6 +1260,10 @@ class IMAPConnection {
         this.socket = socket;
         this.options = this.server.options;
         this.state = 'Not Authenticated';
+        this.sessionNumber = ++this.server.sessionCounter;
+        this._outputQueue = null;
+        this._outputTimer = null;
+        this._deferredOutput = null;
         this.secureConnection = !!this.options.secureConnection;
         this._remainder = '';
         this._command = '';
@@ -1283,7 +1293,7 @@ class IMAPConnection {
         this.notificationQueue = [];
         this.server.on('notify', this._notificationCallback);
         this.server.connections.add(this);
-        this.write('* OK ImapKit ready for rumble\r\n');
+        this.scriptOutput('greeting', '* OK ImapKit ready for rumble\r\n', {});
     }
     /**
      * Writes protocol output to the client, through the transport layer if there is one
@@ -1292,12 +1302,139 @@ class IMAPConnection {
      */
     write(data) {
         const buffer = typeof data === 'string' ? Buffer.from(data, 'binary') : data;
-        if (this.transport) {
-            this.transport.write(buffer);
+        if (this._outputQueue) {
+            this._outputQueue.push({ data: buffer, transport: this.transport });
+        }
+        else {
+            this.writeLayer(buffer, this.transport);
+        }
+    }
+    /**
+     * Writes output, or puts it in the output queue while earlier output waits for a delay of a script rule.
+     * The transport layer is taken when the output is queued, so output from before COMPRESS is not compressed
+     *
+     * @param {Object} operation `{ data, delay, chunk, chunkDelay, close }`, see OutputOperation in src/script.ts
+     */
+    queueOutput(operation) {
+        if (!this._outputQueue && !operation.delay && !operation.chunk) {
+            if (operation.data) {
+                this.writeLayer(operation.data, this.transport);
+            }
+            if (operation.close) {
+                this.closeNow(operation.close);
+            }
+            return;
+        }
+        this._outputQueue = this._outputQueue || [];
+        this._outputQueue.push(Object.assign({}, operation, { transport: this.transport }));
+        if (!this._outputTimer) {
+            this.flushOutput();
+        }
+    }
+    /**
+     * Writes the output queue until it is empty or a delay stops it
+     */
+    flushOutput() {
+        const queue = this._outputQueue || [];
+        while (queue.length) {
+            const operation = queue[0];
+            if (operation.delay) {
+                const delay = operation.delay;
+                operation.delay = 0;
+                this._outputTimer = setTimeout(() => {
+                    this._outputTimer = null;
+                    this.flushOutput();
+                }, delay);
+                return;
+            }
+            if (operation.data && operation.chunk && operation.data.length > operation.chunk) {
+                // the rest waits for chunkDelay, like a delay of its own
+                this.writeLayer(operation.data.subarray(0, operation.chunk), operation.transport || null);
+                operation.data = operation.data.subarray(operation.chunk);
+                operation.delay = operation.chunkDelay;
+                continue;
+            }
+            if (operation.data) {
+                this.writeLayer(operation.data, operation.transport || null);
+            }
+            queue.shift();
+            if (operation.close) {
+                this.closeNow(operation.close);
+                return;
+            }
+        }
+        this._outputQueue = null;
+    }
+    /**
+     * Drops the output that waits for a delay of a script rule or for its release (`defer`)
+     */
+    clearOutputQueue() {
+        if (this._outputTimer) {
+            clearTimeout(this._outputTimer);
+            this._outputTimer = null;
+        }
+        this._outputQueue = null;
+        this._deferredOutput = null;
+    }
+    /**
+     * Writes output through a transport layer, or to the socket
+     *
+     * @param {Buffer} data Output
+     * @param {Object|null} transport Transport layer
+     */
+    writeLayer(data, transport) {
+        if (transport) {
+            transport.write(data);
         }
         else {
-            this.writeRaw(buffer);
+            this.writeRaw(data);
+        }
+    }
+    /**
+     * Sends output through the script rule that handles its event, if there is one
+     *
+     * @param {String} event Event name: greeting, response or continuation
+     * @param {String} output The output as a binary string
+     * @param {Object} fields Context fields of the event (tag, command, description, response)
+     * @param {Function} [compile] Compiles the response that a `mutate` action changed, null drops the output
+     */
+    scriptOutput(event, output, fields, compile) {
+        const found = this.server.script.check(this, event, Object.assign({}, fields, { data: output }));
+        if (!found) {
+            this.write(output);
+            return;
+        }
+        const { rule, context } = found;
+        if ((rule.mutate || rule.literals) && compile && context.response) {
+            let response = context.response;
+            if (rule.mutate) {
+                // a copy, a notification object is shared by every session
+                const copy = cloneResponse(response);
+                response = rule.mutate(copy, context) || copy;
+            }
+            const changed = compile(rule.literals ? (0, script_js_1.literalResponse)(response) : response);
+            if (changed === null) {
+                return;
+            }
+            context.data = changed;
         }
+        (0, script_js_1.sendOutput)(this, rule, context, Buffer.from(context.data, 'binary'));
+    }
+    /**
+     * Sends a continuation request, `+ text`
+     *
+     * @param {String} text Human readable text, can be empty (SASL)
+     * @param {String} description Description for script rules
+     * @param {Function} [getLine] Returns the command line received so far, for the tag and the command of a literal continuation
+     */
+    sendContinuation(text, description, getLine) {
+        const output = '+ ' + text + '\r\n';
+        if (!this.server.script.watches('continuation')) {
+            this.write(output);
+            return;
+        }
+        const line = getLine ? getLine() : null;
+        this.scriptOutput('continuation', output, line === null ? { description } : { description, tag: getResponseTag(line), command: getLineCommand(line) });
     }
     /**
      * Writes data to the socket, below the transport layer
@@ -1327,12 +1464,47 @@ class IMAPConnection {
      * holds, is written out
      */
     end() {
+        if (this._outputQueue && this.socket) {
+            // output still waits for a delay of a script rule
+            this._closing = true;
+            this._outputQueue.push({ close: true });
+            return;
+        }
+        this.closeNow(true);
+    }
+    /**
+     * Closes the connection now, after the output written so far
+     *
+     * @param {Boolean|String} mode true ends the connection gracefully, "reset" destroys the socket (script rules)
+     */
+    closeNow(mode) {
         const socket = this.socket;
         if (!socket) {
             return;
         }
         this._closing = true;
-        if (this.transport) {
+        this.clearOutputQueue();
+        if (mode === 'reset') {
+            this.discardInput();
+            // input that arrives while the reset waits is not processed, also input a transport layer still holds
+            this._resetting = true;
+            socket.pause();
+            // a RST sent in the same tick as the last output can get lost: on macOS the client received the output but
+            // never the RST (#81). Node has no signal for output that reached the peer, so the RST waits a little
+            setTimeout(() => {
+                if (socket.destroyed) {
+                    return;
+                }
+                // resetAndDestroy sends a TCP RST (Node 16.17), not every runtime has it
+                if (typeof socket.resetAndDestroy === 'function') {
+                    socket.resetAndDestroy();
+                }
+                else {
+                    socket.destroy();
+                }
+            }, RESET_DELAY);
+        }
+        else if (this.transport) {
             this.transport.end(() => socket.end());
         }
         else {
@@ -1433,6 +1605,7 @@ class IMAPConnection {
             this.transport.destroy();
             this.transport = null;
         }
+        this.clearOutputQueue();
         this.server.removeListener('notify', this._notificationCallback);
         this.server.connections.delete(this);
     }
@@ -1448,9 +1621,27 @@ class IMAPConnection {
             // socket is already gone
         }
     }
+    /**
+     * Passes a line to the input handler (IDLE, AUTHENTICATE), unless a script rule handles it
+     *
+     * @param {String} line Input line without CRLF
+     */
+    handleInput(line) {
+        const inputHandler = this.inputHandler;
+        const found = this.server.script.check(this, 'input', { data: line });
+        if (found) {
+            (0, script_js_1.handleLine)(this, found.rule, found.context, () => inputHandler(line));
+        }
+        else {
+            inputHandler(line);
+        }
+    }
     onData(chunk) {
         let match;
         let str;
+        if (this._resetting) {
+            return;
+        }
         // everything in one read arrived before anything this read causes to be sent
         this._readCount = (this._readCount || 0) + 1;
         str = (chunk || '').toString('binary');
@@ -1519,7 +1710,7 @@ class IMAPConnection {
                     this.sendBad(getResponseTag(line), 'Literal data must wait for the continuation request', 'LITERAL TOO EARLY', line);
                 }
                 else if (this.inputHandler) {
-                    this.inputHandler(line);
+                    this.handleInput(line);
                 }
                 else {
                     this.scheduleCommand(line);
@@ -1568,7 +1759,9 @@ class IMAPConnection {
                     this._earlyLiteral = true;
                 }
                 else if (!this._earlyLiteral) {
-                    this.write('+ Go ahead\r\n');
+                    // the line is needed only by script rules that watch continuations
+                    const head = str.substr(0, match.index) + marker;
+                    this.sendContinuation('Go ahead', 'LITERAL', () => this._command + head);
                 }
             }
             this._remainder = '';
@@ -1644,12 +1837,7 @@ class IMAPConnection {
             // not a command, e.g. a SASL response
             return literal8 ? refuse('Literal8 is not allowed here') : false;
         }
-        // tag SP command, and for UID and AUTHENTICATE the word that follows
-        const words = line.match(/^[^ ]* ([^ ]*)(?: ([^ ]*))?/);
-        let command = ((words && words[1]) || '').toUpperCase();
-        if (command === 'UID' || command === 'AUTHENTICATE') {
-            command += ' ' + ((words && words[2]) || '').toUpperCase();
-        }
+        const command = getLineCommand(line);
         if (!COMMAND_REGEX.test(command) || !this.server.getCommandHandler(command)) {
             return refuse('Unknown command');
         }
@@ -2069,6 +2257,44 @@ class IMAPConnection {
                 });
             }
         }
+        const compiled = this.compileResponse(response);
+        if (compiled === null) {
+            return;
+        }
+        if (this._deferredOutput) {
+            // responses that `defer` rules hold back go before the first response of another command
+            (0, script_js_1.releaseDeferred)(this, parsed && parsed.command && parsed.tag && parsed.tag !== '*' ? parsed.tag : null, false);
+        }
+        this.scriptResponse(response, compiled, description, parsed);
+        if (this._deferredOutput && response.tag !== '*' && response.tag !== '+') {
+            (0, script_js_1.releaseDeferred)(this, response.tag, true);
+        }
+    }
+    /**
+     * Sends a compiled response through the script rules that watch responses or continuations
+     *
+     * @param {Object} response Response object
+     * @param {String} compiled The compiled response
+     * @param {String} [description] Description of the response
+     * @param {Object} [parsed] The command the response belongs to
+     */
+    scriptResponse(response, compiled, description, parsed) {
+        const event = response.tag === '+' ? 'continuation' : 'response';
+        if (!this.server.script.watches(event)) {
+            this.write(compiled);
+            return;
+        }
+        // script rules see the response after every plugin and the core changed it. Without a command, an
+        // unsolicited response belongs to the command that runs or idles
+        this.scriptOutput(event, compiled, Object.assign({ description: description || null, response }, parsed && parsed.command ? { tag: parsed.tag || null, command: String(parsed.command).toUpperCase() } : {}), output => this.compileResponse(output));
+    }
+    /**
+     * Compiles a response for the wire
+     *
+     * @param {Object} response Response object
+     * @return {String|null} the response with its CRLF as a binary string, or null for an untagged response that does not compile
+     */
+    compileResponse(response) {
         let compiled;
         try {
             compiled = imap_handler_1.default.compiler(response, this.compilerOptions);
@@ -2079,14 +2305,14 @@ class IMAPConnection {
                 console.log('Failed to compile response: %s', err.message);
             }
             if (response.tag === '*') {
-                return;
+                return null;
             }
             compiled = response.tag + ' NO [SERVERBUG] Failed to compile response';
         }
         if (this.options.debug) {
             console.log('SEND: %s', compiled);
         }
-        this.write(compiled + '\r\n');
+        return compiled + '\r\n';
     }
     /**
      * Sends a tagged status response to a command
@@ -2273,9 +2499,23 @@ class IMAPConnection {
     exportMailboxName(path) {
         return path;
     }
-    scheduleCommand(data) {
+    /**
+     * Parses a command line and queues the command, or answers it right away when it can not run
+     *
+     * @param {String} data Command line with its literals, without the final CRLF
+     * @param {Boolean} [scripted] The line comes from a script rule with `run`, it is next in the queue
+     */
+    scheduleCommand(data, scripted) {
         let parsed;
         const tag = getResponseTag(data);
+        // the rule is chosen when the line arrives, the state it matches is the state at that moment. The rule
+        // acts when the command's turn comes, so that its output keeps the order of the responses
+        const found = !scripted && this.server.script.watches('command') ? this.server.script.check(this, 'command', { data, tag, command: getLineCommand(data) }) : null;
+        if (found) {
+            this._commandQueue.push({ parsed: { tag, command: found.context.command || '' }, data, script: found });
+            this.processQueue();
+            return;
+        }
         try {
             // server.parserOptions are the defaults of plugins, connection.parserOptions win
             parsed = imap_handler_1.default.parser(data, Object.assign({ literalPlus: this.server.literalPlus }, this.server.parserOptions, this.parserOptions));
@@ -2322,10 +2562,14 @@ class IMAPConnection {
                 this.sendStatus(parsed, data, 'BAD', 'Commands with message sequence numbers must wait for the completion of earlier commands');
                 return;
             }
-            this._commandQueue.push({
-                parsed: parsed,
-                data: data
-            });
+            const element = { parsed, data };
+            if (scripted) {
+                // processQueue runs it once the script rule released the queue
+                this._commandQueue.unshift(element);
+            }
+            else {
+                this._commandQueue.push(element);
+            }
             this.processQueue();
         }
         else if (/^AUTHENTICATE /i.test(parsed.command)) {
@@ -2354,6 +2598,33 @@ class IMAPConnection {
             }, 'UNKNOWN COMMAND', parsed, data);
         }
     }
+    /**
+     * Handles a command line with the script rule that matched it, after the rule's delay. With `run` the line
+     * goes through the parser and the command handler as usual afterwards
+     *
+     * @param {Object} element Queued command with the rule
+     * @param {Function} next Releases the queue
+     */
+    runScriptedCommand(element, next) {
+        const { rule, context } = element.script;
+        const act = () => {
+            if (!this.socket || this._closing) {
+                return next();
+            }
+            (0, script_js_1.handleLine)(this, rule, context, () => {
+                // the line is not running yet, it must not count as an earlier command (RFC 3501 section 5.5)
+                this._runningCommand = null;
+                this.scheduleCommand(element.data, true);
+            });
+            next();
+        };
+        if (rule.delay) {
+            setTimeout(act, rule.delay);
+        }
+        else {
+            act();
+        }
+    }
     processQueue(force) {
         if (!force && this._processing) {
             return;
@@ -2386,6 +2657,10 @@ class IMAPConnection {
                 this.processQueue(true);
             }
         };
+        if (element.script) {
+            this.runScriptedCommand(element, next);
+            return;
+        }
         if (options.states && options.states.indexOf(this.state) < 0) {
             this.sendStatus(element.parsed, element.data, 'BAD', stateError(command, this.state));
             return next();
@@ -2428,7 +2703,12 @@ class IMAPConnection {
         try {
             // changes made while the handler runs are attributed to this session (the `origin` of notifications)
             this.server.activeConnection = this;
+            const inputHandler = this.inputHandler;
             this.server.getCommandHandler(element.parsed.command)(this, element.parsed, element.data, next);
+            if (this.inputHandler && this.inputHandler !== inputHandler) {
+                // the command reads the lines that follow (IDLE, AUTHENTICATE), script rules match them with it
+                this.inputCommand = { tag: element.parsed.tag, command: element.parsed.command };
+            }
         }
         catch (E) {
             const ex = E;
@@ -2550,6 +2830,41 @@ class IMAPConnection {
     }
 }
 exports.IMAPConnection = IMAPConnection;
+/**
+ * Copies a response tree for the `mutate` action of a script rule: arrays and plain objects are copied,
+ * other values (Buffers) are shared
+ *
+ * @param {*} value Response or a part of it
+ * @return {*} Copy
+ */
+function cloneResponse(value) {
+    if (Array.isArray(value)) {
+        return value.map(cloneResponse);
+    }
+    if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+        const copy = {};
+        for (const key of Object.keys(value)) {
+            copy[key] = cloneResponse(value[key]);
+        }
+        return copy;
+    }
+    return value;
+}
+/**
+ * Finds the command name in a command line that may not parse: tag SP command, and for UID and AUTHENTICATE
+ * the word that follows
+ *
+ * @param {String} line Command line
+ * @return {String} Command name in upper case, can be empty
+ */
+function getLineCommand(line) {
+    const words = line.match(/^[^ ]* ([^ ]*)(?: ([^ ]*))?/);
+    let command = ((words && words[1]) || '').toUpperCase();
+    if (command === 'UID' || command === 'AUTHENTICATE') {
+        command += ' ' + ((words && words[2]) || '').toUpperCase();
+    }
+    return command;
+}
 /**
  * Formats a mailbox name for a response: an atom when possible, otherwise a string. NIL and names
  * like \\Foo would not read back as mailbox names, so these are strings as well

package/dist/cjs/types.d.ts

@@ -1,4 +1,5 @@
 import type { IMAPServer, IMAPConnection } from './server.js';
+import type { ScriptRule } from './script.js';
 export type { IMAPServer, IMAPConnection };
 /**
  * A value of the parsed command or of a response, as imap-handler parses and compiles it: an
@@ -229,6 +230,8 @@ export interface IMAPServerOptions {
     systemFlags?: string[] | undefined;
     /** largest literal accepted after login, in octets */
     maxLiteralSize?: number | undefined;
+    /** script rules that make the server misbehave on purpose, see src/script.ts and README "Scripted faults" */
+    script?: ScriptRule | ScriptRule[] | undefined;
     [key: string]: any;
 }
 /**

package/dist/esm/index.d.ts

@@ -1,6 +1,7 @@
 import createServer, { TAG_REGEX, IMAPServer, IMAPConnection } from './server.js';
 export { TAG_REGEX, IMAPServer, IMAPConnection };
 export type { Attribute, ParsedCommand, IMAPResponse, Notification, Callback, CommandHandler, CommandOptions, Plugin, IMAPError, Message, Mailbox, StorageNamespace, UserData, IMAPServerOptions } from './types.js';
+export type { ScriptRule, ScriptContext, ScriptEvent, ScriptBytes, ScriptHandle } from './script.js';
 declare const imapkit: typeof createServer & {
     TAG_REGEX: RegExp;
     IMAPServer: typeof IMAPServer;

package/dist/esm/plugins/auth-plain.js

@@ -54,7 +54,7 @@ export default function authPlainPlugin(server) {
                 authenticate(connection, parsed, data, str);
             };
             // Send an empty continuation request to the client
-            connection.write('+ \r\n');
+            connection.sendContinuation('', 'AUTHENTICATE PLAIN');
         }
         else if (parsed.attributes.length === 1 &&
             // second argument must be Base64 string as ATOM

package/dist/esm/plugins/idle.js

@@ -63,7 +63,7 @@ export default function idlePlugin(server) {
                 }, 'INVALID IDLE', parsed, data);
             }
         };
-        connection.write('+ idling\r\n');
+        connection.sendContinuation('idling', 'IDLE');
         connection.processNotifications();
         return callback();
     }, { states: states.AUTHENTICATED, noArguments: true });

package/dist/esm/plugins/oauthbearer.js

@@ -165,7 +165,7 @@ export default function oauthbearerPlugin(server) {
         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');
+            connection.sendContinuation('', 'AUTHENTICATE OAUTHBEARER');
             return callback();
         }
         if (args.length !== 1 || !args[0] || args[0].type !== 'ATOM') {