imapkit 4.2.0 → 4.3.0

package/README.md

@@ -410,21 +410,16 @@ const server = imapkit({
     ]
 });
 
-// a rule added later, it returns a handle
-const rule = server.script.add({
-    on: 'response',
-    command: 'FETCH',
-    untagged: true,
-    // strings in the response tree become literals, valid IMAP that a client must handle
-    mutate: response => {
-        const walk = list =>
-            list.forEach((node, i) => (Array.isArray(node) ? walk(node) : typeof node === 'string' && (list[i] = { type: 'LITERAL', value: node })));
-        walk(response.attributes);
-    }
-});
+// rules added later return handles
+const [literals, late] = server.script.add([
+    // every string the grammar allows is sent as a literal, valid IMAP that a client must handle
+    { on: 'response', untagged: true, literals: true },
+    // the FETCH response of UID 2 arrives after the tagged OK, like some servers do now and then
+    { on: 'response', command: 'UID FETCH', untagged: true, match: /UID 2\b/, times: 1, defer: 'tagged' }
+]);
 // ... run the client
-assert.strictEqual(rule.hits, 1);
-rule.remove();
+assert.strictEqual(late.hits, 1);
+literals.remove();
 ```
 
 Every rule watches one event (`on`):
@@ -452,17 +447,19 @@ The matchers of a rule all have to match. Rules are checked in the order they we
 
 The actions say what happens instead of the usual behavior. Strings are sent as they are (binary strings, one character per octet, or UTF-8 when they have characters above U+00FF) without an added CRLF, and `$TAG` in a string is replaced with the tag of the command. A Buffer is sent as it is, a function gets the event context and returns a string or a Buffer.
 
-| Action                | Events                 | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| --------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `send`                | all                    | output events: bytes sent instead of the output. command and input: bytes sent instead of processing the line                                                                                                                                                                                                                                                                                                                                                  |
-| `run`                 | command, input         | process the line as usual after `send` (to add output before the real response)                                                                                                                                                                                                                                                                                                                                                                                |
-| `drop`                | all                    | output events: send nothing. command and input: ignore the line, the client gets no answer                                                                                                                                                                                                                                                                                                                                                                     |
-| `mutate`              | response, continuation | `(response, context)` gets a copy of the response object before it is compiled and changes it, or returns another one. Continuation requests have a response object only when a plugin sends them with `connection.send()` (the error challenges of XOAUTH2 and OAUTHBEARER), other events ignore `mutate`. A tagged response that does not compile then is sent as `NO [SERVERBUG]`, an untagged one is dropped. Use `send` for output that is not valid IMAP |
-| `before`, `after`     | output events          | bytes sent before or after the output, e.g. an unsolicited response                                                                                                                                                                                                                                                                                                                                                                                            |
-| `delay`               | all but input          | milliseconds to wait before the output goes out, all later output waits behind it. For a command, the wait before the rule acts or the command runs, later commands wait too                                                                                                                                                                                                                                                                                   |
-| `chunk`, `chunkDelay` | all                    | write the bytes in pieces of `chunk` octets, `chunkDelay` milliseconds apart (default 10)                                                                                                                                                                                                                                                                                                                                                                      |
-| `truncate`            | all                    | send only this many octets of the bytes, then close the connection                                                                                                                                                                                                                                                                                                                                                                                             |
-| `close`               | all                    | close the connection after the bytes are sent, `'reset'` destroys the socket instead (a TCP RST where the runtime supports it)                                                                                                                                                                                                                                                                                                                                 |
+| Action                | Events                 | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| --------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `send`                | all                    | output events: bytes sent instead of the output. command and input: bytes sent instead of processing the line                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `run`                 | command, input         | process the line as usual after `send` (to add output before the real response)                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `drop`                | all                    | output events: send nothing. command and input: ignore the line, the client gets no answer                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `mutate`              | response, continuation | `(response, context)` gets a copy of the response object before it is compiled and changes it, or returns another one. Continuation requests have a response object only when a plugin sends them with `connection.send()` (the error challenges of XOAUTH2 and OAUTHBEARER), other events ignore `mutate`. A tagged response that does not compile then is sent as `NO [SERVERBUG]`, an untagged one is dropped. Use `send` for output that is not valid IMAP                                                                          |
+| `literals`            | response               | sends every string of the response that the grammar allows (string, nstring, astring) as a literal. The positions that take only a quoted string stay quoted: the hierarchy delimiter of LIST, LSUB and NAMESPACE, CHILDINFO values, INTERNALDATE and SAVEDATE, and the media types `"TEXT"` and `"MESSAGE" "RFC822"` in a body structure (RFC 9051 section 9, RFC 5258 section 6). Atoms, response codes and text stay as they are. Works together with `mutate`, after it                                                             |
+| `defer`               | response               | holds an untagged response back: `'tagged'` sends it right after the tagged response of its command, `'next'` with the answer to the next command, before its first response. Needs `untagged: true`. `send`, `before` and `after` change the held output, `drop`, `delay`, `chunk`, `truncate` and `close` can not be combined with it. A response that does not belong to a command (one that arrives in IDLE belongs to IDLE) is held for the next tagged response or command. Held responses are dropped when the connection closes |
+| `before`, `after`     | output events          | bytes sent before or after the output, e.g. an unsolicited response                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `delay`               | all but input          | milliseconds to wait before the output goes out, all later output waits behind it. For a command, the wait before the rule acts or the command runs, later commands wait too                                                                                                                                                                                                                                                                                                                                                            |
+| `chunk`, `chunkDelay` | all                    | write the bytes in pieces of `chunk` octets, `chunkDelay` milliseconds apart (default 10)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `truncate`            | all                    | send only this many octets of the bytes, then close the connection                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `close`               | all                    | close the connection after the bytes are sent, `'reset'` destroys the socket instead (a TCP RST where the runtime supports it), 20 ms after the bytes so that the RST does not overtake them. Input that arrives meanwhile is not processed                                                                                                                                                                                                                                                                                             |
 
 A rule needs at least one action, and for command and input events `chunk` and `truncate` need `send`. A rule with only `delay` (and `run`) delays the line and then processes it as usual. Rules are checked when they are added: an unknown option, an option that does not apply to the event, or an invalid value throws a `TypeError`, so a typo can not turn into a rule that never fires.
 

package/dist/cjs/script.d.ts

@@ -56,6 +56,13 @@ export interface ScriptRule {
     nth?: number | undefined;
     /** the rule fires this many times at most (default unlimited) */
     times?: number | undefined;
+    /** sends every string of the response that the grammar allows as a literal (response events) */
+    literals?: boolean | undefined;
+    /**
+     * holds an untagged response back: `"tagged"` sends it after the tagged response of its command, `"next"` with the
+     * first response that belongs to another command (response events)
+     */
+    defer?: 'tagged' | 'next' | undefined;
     /** changes or replaces the response object before it is compiled (response events) */
     mutate?: ((response: IMAPResponse, context: ScriptContext) => IMAPResponse | void) | undefined;
     /** bytes to send instead of the output, or instead of answering the command or input line. `$TAG` in a string is the tag */
@@ -170,6 +177,32 @@ export declare class ServerScript {
  * @param {Buffer} output The output
  */
 export declare function sendOutput(connection: IMAPConnection, rule: ScriptRule, context: ScriptContext, output: Buffer): void;
+/** Output held back by `defer`, see releaseDeferred */
+export interface DeferredOutput {
+    mode: 'tagged' | 'next';
+    /** tag of the command the response belongs to, null for an unsolicited response */
+    tag: string | null;
+    data: Buffer;
+}
+/**
+ * Sends the held back responses whose turn has come (`defer`). Before a response of another command go the ones held
+ * with `"next"`, after the tagged response of their command the ones held with `"tagged"`. A response held without a
+ * command goes with the next command, or after the next tagged response
+ *
+ * @param {Object} connection IMAP connection
+ * @param {String|null} tag Tag of the command the response that is sent belongs to
+ * @param {Boolean} tagged false before the response is sent, true after a tagged response was sent
+ */
+export declare function releaseDeferred(connection: IMAPConnection, tag: string | null, tagged: boolean): void;
+/**
+ * Turns the strings of a response into literals wherever the grammar allows a string (RFC 9051 section 9: string,
+ * nstring and astring). Positions that take only a quoted string stay quoted: the hierarchy delimiter of LIST, LSUB
+ * and NAMESPACE, CHILDINFO values (RFC 5258 section 6), date-time values and the quoted media types of a body structure
+ *
+ * @param {Object} response Response object
+ * @return {Object} a copy of the response with literals, the response is not changed
+ */
+export declare function literalResponse(response: IMAPResponse): IMAPResponse;
 /**
  * Handles a command or input line with the rule that matched it: sends the bytes of `send`, closes the connection,
  * and processes the line as usual with `run` (or when the rule only delays it)

package/dist/cjs/script.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServerScript = void 0;
 exports.sendOutput = sendOutput;
+exports.releaseDeferred = releaseDeferred;
+exports.literalResponse = literalResponse;
 exports.handleLine = handleLine;
 const EVENTS = ['greeting', 'command', 'input', 'response', 'continuation'];
 const OUTPUT_EVENTS = ['greeting', 'response', 'continuation'];
@@ -21,6 +23,8 @@ const KEYS = {
     nth: EVENTS,
     times: EVENTS,
     mutate: ['response', 'continuation'],
+    literals: ['response'],
+    defer: ['response'],
     send: EVENTS,
     before: OUTPUT_EVENTS,
     after: OUTPUT_EVENTS,
@@ -32,7 +36,7 @@ const KEYS = {
     truncate: EVENTS,
     close: EVENTS
 };
-const ACTIONS = ['mutate', 'send', 'before', 'after', 'run', 'drop', 'delay', 'chunk', 'truncate', 'close'];
+const ACTIONS = ['mutate', 'literals', 'defer', 'send', 'before', 'after', 'run', 'drop', 'delay', 'chunk', 'truncate', 'close'];
 const DEFAULT_CHUNK_DELAY = 10;
 // matchers that list accepted values, kept as Sets so that matching an event allocates nothing
 const SET_MATCHERS = ['command', 'description', 'session', 'state', 'user', 'mailbox'];
@@ -110,6 +114,22 @@ function validateRule(rule) {
             throw new TypeError('Script rule option "' + key + '" must be a string, a Buffer or a function');
         }
     }
+    if (rule.literals !== undefined && typeof rule.literals !== 'boolean') {
+        throw new TypeError('Script rule option "literals" must be true or false');
+    }
+    if (rule.defer !== undefined) {
+        if (rule.defer !== 'tagged' && rule.defer !== 'next') {
+            throw new TypeError('Script rule option "defer" must be "tagged" or "next"');
+        }
+        if (rule.untagged !== true) {
+            // a tagged response ends its command, there is nothing to hold it back for
+            throw new TypeError('Script rule option "defer" needs "untagged": true');
+        }
+        const conflict = ['drop', 'delay', 'chunk', 'truncate', 'close'].find(key => rule[key] !== undefined && rule[key] !== false);
+        if (conflict) {
+            throw new TypeError('Script rule option "defer" can not be combined with "' + conflict + '"');
+        }
+    }
     if (rule.close !== undefined && typeof rule.close !== 'boolean' && rule.close !== 'reset') {
         throw new TypeError('Script rule option "close" must be true, false or "reset"');
     }
@@ -292,8 +312,137 @@ function scriptContext(connection, event, fields) {
 function sendOutput(connection, rule, context, output) {
     const replaced = rule.drop ? Buffer.alloc(0) : resolveBytes(rule.send, context) || output;
     const parts = [resolveBytes(rule.before, context), replaced, resolveBytes(rule.after, context)].filter((part) => !!part);
+    if (rule.defer) {
+        (connection._deferredOutput ||= []).push({ mode: rule.defer, tag: context.tag, data: Buffer.concat(parts) });
+        return;
+    }
     sendBytes(connection, rule, Buffer.concat(parts), rule.delay);
 }
+/**
+ * Sends the held back responses whose turn has come (`defer`). Before a response of another command go the ones held
+ * with `"next"`, after the tagged response of their command the ones held with `"tagged"`. A response held without a
+ * command goes with the next command, or after the next tagged response
+ *
+ * @param {Object} connection IMAP connection
+ * @param {String|null} tag Tag of the command the response that is sent belongs to
+ * @param {Boolean} tagged false before the response is sent, true after a tagged response was sent
+ */
+function releaseDeferred(connection, tag, tagged) {
+    const ready = [];
+    const waiting = [];
+    for (const entry of connection._deferredOutput) {
+        const due = tagged ? entry.mode === 'tagged' && (entry.tag === null || entry.tag === tag) : entry.mode === 'next' && tag !== null && entry.tag !== tag;
+        (due ? ready : waiting).push(entry);
+    }
+    if (ready.length) {
+        connection._deferredOutput = waiting.length ? waiting : null;
+        ready.forEach(entry => connection.write(entry.data));
+    }
+}
+/**
+ * Turns strings into literals: plain strings and STRING nodes, also in lists. Atoms, numbers, NIL, text and
+ * response codes (SECTION) stay as they are, a response code takes no literals (RFC 9051 section 9 resp-text-code)
+ *
+ * @param {*} node Response attribute
+ * @return {*} the attribute with literals, a new object where something changed
+ */
+function literalValue(node) {
+    if (typeof node === 'string') {
+        return { type: 'LITERAL', value: node };
+    }
+    if (Array.isArray(node)) {
+        return node.map(literalValue);
+    }
+    if (node && typeof node === 'object' && node.type === 'STRING') {
+        return { type: 'LITERAL', value: node.value };
+    }
+    return node;
+}
+const nodeText = (node) => String(typeof node === 'string' ? node : node && typeof node === 'object' ? node.value : '').toUpperCase();
+/**
+ * Turns the strings of a body structure into literals, except the media types that the grammar writes as quoted
+ * strings: `"TEXT"` (media-text) and `"MESSAGE" "RFC822"` or `"GLOBAL"` (media-message, RFC 9051 section 9). A literal
+ * "TEXT" would read as a basic part, and the lines count after it would break the grammar
+ *
+ * @param {*} body Body structure, a list
+ * @return {*} the body structure with literals
+ */
+function literalBody(body) {
+    if (!Array.isArray(body)) {
+        return literalValue(body);
+    }
+    if (Array.isArray(body[0])) {
+        // body-type-mpart: the parts, then the subtype and the extension data
+        const subtype = body.findIndex(item => !Array.isArray(item));
+        return body.map((item, i) => (subtype < 0 || i < subtype ? literalBody(item) : literalValue(item)));
+    }
+    const type = nodeText(body[0]);
+    const message = type === 'MESSAGE' && ['RFC822', 'GLOBAL'].includes(nodeText(body[1]));
+    return body.map((item, i) => {
+        if ((i === 0 && (type === 'TEXT' || message)) || (i === 1 && message)) {
+            return item;
+        }
+        // body-type-msg: the envelope, then the body of the encapsulated message
+        return i === 8 && message ? literalBody(item) : literalValue(item);
+    });
+}
+// FETCH items with a date-time value, which is a quoted string (RFC 9051 section 9, SAVEDATE: RFC 8514 section 4)
+const DATE_TIME_ITEMS = new Set(['INTERNALDATE', 'SAVEDATE']);
+/**
+ * Turns the strings of a response into literals wherever the grammar allows a string (RFC 9051 section 9: string,
+ * nstring and astring). Positions that take only a quoted string stay quoted: the hierarchy delimiter of LIST, LSUB
+ * and NAMESPACE, CHILDINFO values (RFC 5258 section 6), date-time values and the quoted media types of a body structure
+ *
+ * @param {Object} response Response object
+ * @return {Object} a copy of the response with literals, the response is not changed
+ */
+function literalResponse(response) {
+    const attributes = Array.isArray(response.attributes) ? response.attributes : null;
+    if (!attributes) {
+        return response;
+    }
+    const command = nodeText(response.command);
+    const name = nodeText(attributes[1]);
+    let converted;
+    if (name === 'FETCH' || name === 'UIDFETCH') {
+        // message-data: number SP "FETCH" SP msg-att, the items are name and value pairs
+        const items = Array.isArray(attributes[2]) ? attributes[2] : [];
+        const fetched = items.map((item, i) => {
+            if (i % 2 === 0) {
+                return item;
+            }
+            const key = items[i - 1];
+            const itemName = key && !key.section ? nodeText(key) : '';
+            if (DATE_TIME_ITEMS.has(itemName)) {
+                return item;
+            }
+            return itemName === 'BODY' || itemName === 'BODYSTRUCTURE' ? literalBody(item) : literalValue(item);
+        });
+        converted = attributes.map((item, i) => (i === 2 ? fetched : item));
+    }
+    else if (command === 'LIST' || command === 'LSUB') {
+        // mailbox-list: flags, the delimiter (quoted only), the name and the extended data items
+        converted = attributes.map((item, i) => {
+            if (i === 1) {
+                return item;
+            }
+            if (i === 3 && Array.isArray(item)) {
+                return item.map((value, j) => (j % 2 === 1 && nodeText(item[j - 1]) === 'CHILDINFO' ? value : literalValue(value)));
+            }
+            return literalValue(item);
+        });
+    }
+    else if (command === 'NAMESPACE') {
+        // namespace-descr: "(" string SP (DQUOTE QUOTED-CHAR DQUOTE / nil) [extensions] ")"
+        converted = attributes.map(namespace => Array.isArray(namespace)
+            ? namespace.map(descr => (Array.isArray(descr) ? descr.map((value, i) => (i === 1 ? value : literalValue(value))) : descr))
+            : namespace);
+    }
+    else {
+        converted = attributes.map(literalValue);
+    }
+    return Object.assign({}, response, { attributes: converted });
+}
 /**
  * Sends the bytes of a rule with its timing, `truncate` closes the connection after the cut
  *

package/dist/cjs/server.d.ts

@@ -4,7 +4,7 @@ import tls from 'node:tls';
 import type { CompilerOptions, ParserOptions } from 'imap-handler';
 import type { ResolvedCommandOptions } from './command-states.js';
 import { ServerScript } from './script.js';
-import type { OutputOperation, ScriptContext, ScriptEvent, ScriptRule } from './script.js';
+import type { DeferredOutput, OutputOperation, ScriptContext, ScriptEvent, ScriptRule } from './script.js';
 import type { AppendCheck, AppendCheckOptions, AppendDataHandler, AppendMessage, CapabilityCheck, CheckResult, ClosedCheck, CommandCheck, CommandContext, CommandOptions, CommandHandler, ConnectionHandler, ConnectionState, CopyHandler, FetchHandler, IMAPResponse, IMAPServerOptions, ListedMailbox, LiteralFilter, Mailbox, MailboxHandler, MailboxStatus, Message, MessageFilter, MessageHandler, MessageRange, Namespace, Notification, NotifyEvent, NotifyFilter, OutputHandler, ParsedCommand, RangeLimit, Refusal, SearchAccessCheck, SearchHandler, SearchLimit, ServerStorage, StatusHandler, StorageMailbox, StorageMessage, StoreHandler, SubscriptionStandIn, Transport, UrlAccessCheck, UserData } from './types.js';
 declare const TAG_REGEX: RegExp;
 /**
@@ -509,6 +509,10 @@ declare class IMAPConnection {
     /** output that waits behind a delay of a script rule, null when output is written right away */
     _outputQueue: OutputOperation[] | null;
     _outputTimer: ReturnType<typeof setTimeout> | null;
+    /** untagged responses that `defer` rules hold back, see releaseDeferred in src/script.ts */
+    _deferredOutput: DeferredOutput[] | null;
+    /** a script rule closes the connection with a RST, see closeNow */
+    _resetting: boolean | undefined;
     constructor(server: IMAPServer, socket: net.Socket);
     /**
      * Writes protocol output to the client, through the transport layer if there is one
@@ -528,7 +532,7 @@ declare class IMAPConnection {
      */
     flushOutput(): void;
     /**
-     * Drops the output that waits for a delay of a script rule
+     * Drops the output that waits for a delay of a script rule or for its release (`defer`)
      */
     clearOutputQueue(): void;
     /**
@@ -824,6 +828,15 @@ declare class IMAPConnection {
      *   FETCH result.  (This may have other names when used, like "affected".)
      */
     send(response: IMAPResponse, description?: string, parsed?: CommandContext | null, data?: string | null, ...extra: any[]): void;
+    /**
+     * 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: IMAPResponse, compiled: string, description?: string, parsed?: CommandContext | null): void;
     /**
      * Compiles a response for the wire
      *

package/dist/cjs/server.js

@@ -57,6 +57,8 @@ 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
@@ -1261,6 +1263,7 @@ class IMAPConnection {
         this.sessionNumber = ++this.server.sessionCounter;
         this._outputQueue = null;
         this._outputTimer = null;
+        this._deferredOutput = null;
         this.secureConnection = !!this.options.secureConnection;
         this._remainder = '';
         this._command = '';
@@ -1363,7 +1366,7 @@ class IMAPConnection {
         this._outputQueue = null;
     }
     /**
-     * Drops the output that waits for a delay of a script rule
+     * Drops the output that waits for a delay of a script rule or for its release (`defer`)
      */
     clearOutputQueue() {
         if (this._outputTimer) {
@@ -1371,6 +1374,7 @@ class IMAPConnection {
             this._outputTimer = null;
         }
         this._outputQueue = null;
+        this._deferredOutput = null;
     }
     /**
      * Writes output through a transport layer, or to the socket
@@ -1401,10 +1405,14 @@ class IMAPConnection {
             return;
         }
         const { rule, context } = found;
-        if (rule.mutate && compile && context.response) {
-            // a copy, a notification object is shared by every session
-            const copy = cloneResponse(context.response);
-            const changed = compile(rule.mutate(copy, context) || copy);
+        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;
             }
@@ -1478,13 +1486,23 @@ class IMAPConnection {
         this.clearOutputQueue();
         if (mode === 'reset') {
             this.discardInput();
-            // resetAndDestroy sends a TCP RST (Node 16.17), not every runtime has it
-            if (typeof socket.resetAndDestroy === 'function') {
-                socket.resetAndDestroy();
-            }
-            else {
-                socket.destroy();
-            }
+            // 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());
@@ -1621,6 +1639,9 @@ class IMAPConnection {
     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');
@@ -2240,6 +2261,24 @@ class IMAPConnection {
         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);

package/dist/esm/script.d.ts

@@ -56,6 +56,13 @@ export interface ScriptRule {
     nth?: number | undefined;
     /** the rule fires this many times at most (default unlimited) */
     times?: number | undefined;
+    /** sends every string of the response that the grammar allows as a literal (response events) */
+    literals?: boolean | undefined;
+    /**
+     * holds an untagged response back: `"tagged"` sends it after the tagged response of its command, `"next"` with the
+     * first response that belongs to another command (response events)
+     */
+    defer?: 'tagged' | 'next' | undefined;
     /** changes or replaces the response object before it is compiled (response events) */
     mutate?: ((response: IMAPResponse, context: ScriptContext) => IMAPResponse | void) | undefined;
     /** bytes to send instead of the output, or instead of answering the command or input line. `$TAG` in a string is the tag */
@@ -170,6 +177,32 @@ export declare class ServerScript {
  * @param {Buffer} output The output
  */
 export declare function sendOutput(connection: IMAPConnection, rule: ScriptRule, context: ScriptContext, output: Buffer): void;
+/** Output held back by `defer`, see releaseDeferred */
+export interface DeferredOutput {
+    mode: 'tagged' | 'next';
+    /** tag of the command the response belongs to, null for an unsolicited response */
+    tag: string | null;
+    data: Buffer;
+}
+/**
+ * Sends the held back responses whose turn has come (`defer`). Before a response of another command go the ones held
+ * with `"next"`, after the tagged response of their command the ones held with `"tagged"`. A response held without a
+ * command goes with the next command, or after the next tagged response
+ *
+ * @param {Object} connection IMAP connection
+ * @param {String|null} tag Tag of the command the response that is sent belongs to
+ * @param {Boolean} tagged false before the response is sent, true after a tagged response was sent
+ */
+export declare function releaseDeferred(connection: IMAPConnection, tag: string | null, tagged: boolean): void;
+/**
+ * Turns the strings of a response into literals wherever the grammar allows a string (RFC 9051 section 9: string,
+ * nstring and astring). Positions that take only a quoted string stay quoted: the hierarchy delimiter of LIST, LSUB
+ * and NAMESPACE, CHILDINFO values (RFC 5258 section 6), date-time values and the quoted media types of a body structure
+ *
+ * @param {Object} response Response object
+ * @return {Object} a copy of the response with literals, the response is not changed
+ */
+export declare function literalResponse(response: IMAPResponse): IMAPResponse;
 /**
  * Handles a command or input line with the rule that matched it: sends the bytes of `send`, closes the connection,
  * and processes the line as usual with `run` (or when the rule only delays it)

package/dist/esm/script.js

@@ -16,6 +16,8 @@ const KEYS = {
     nth: EVENTS,
     times: EVENTS,
     mutate: ['response', 'continuation'],
+    literals: ['response'],
+    defer: ['response'],
     send: EVENTS,
     before: OUTPUT_EVENTS,
     after: OUTPUT_EVENTS,
@@ -27,7 +29,7 @@ const KEYS = {
     truncate: EVENTS,
     close: EVENTS
 };
-const ACTIONS = ['mutate', 'send', 'before', 'after', 'run', 'drop', 'delay', 'chunk', 'truncate', 'close'];
+const ACTIONS = ['mutate', 'literals', 'defer', 'send', 'before', 'after', 'run', 'drop', 'delay', 'chunk', 'truncate', 'close'];
 const DEFAULT_CHUNK_DELAY = 10;
 // matchers that list accepted values, kept as Sets so that matching an event allocates nothing
 const SET_MATCHERS = ['command', 'description', 'session', 'state', 'user', 'mailbox'];
@@ -105,6 +107,22 @@ function validateRule(rule) {
             throw new TypeError('Script rule option "' + key + '" must be a string, a Buffer or a function');
         }
     }
+    if (rule.literals !== undefined && typeof rule.literals !== 'boolean') {
+        throw new TypeError('Script rule option "literals" must be true or false');
+    }
+    if (rule.defer !== undefined) {
+        if (rule.defer !== 'tagged' && rule.defer !== 'next') {
+            throw new TypeError('Script rule option "defer" must be "tagged" or "next"');
+        }
+        if (rule.untagged !== true) {
+            // a tagged response ends its command, there is nothing to hold it back for
+            throw new TypeError('Script rule option "defer" needs "untagged": true');
+        }
+        const conflict = ['drop', 'delay', 'chunk', 'truncate', 'close'].find(key => rule[key] !== undefined && rule[key] !== false);
+        if (conflict) {
+            throw new TypeError('Script rule option "defer" can not be combined with "' + conflict + '"');
+        }
+    }
     if (rule.close !== undefined && typeof rule.close !== 'boolean' && rule.close !== 'reset') {
         throw new TypeError('Script rule option "close" must be true, false or "reset"');
     }
@@ -286,8 +304,137 @@ function scriptContext(connection, event, fields) {
 export function sendOutput(connection, rule, context, output) {
     const replaced = rule.drop ? Buffer.alloc(0) : resolveBytes(rule.send, context) || output;
     const parts = [resolveBytes(rule.before, context), replaced, resolveBytes(rule.after, context)].filter((part) => !!part);
+    if (rule.defer) {
+        (connection._deferredOutput ||= []).push({ mode: rule.defer, tag: context.tag, data: Buffer.concat(parts) });
+        return;
+    }
     sendBytes(connection, rule, Buffer.concat(parts), rule.delay);
 }
+/**
+ * Sends the held back responses whose turn has come (`defer`). Before a response of another command go the ones held
+ * with `"next"`, after the tagged response of their command the ones held with `"tagged"`. A response held without a
+ * command goes with the next command, or after the next tagged response
+ *
+ * @param {Object} connection IMAP connection
+ * @param {String|null} tag Tag of the command the response that is sent belongs to
+ * @param {Boolean} tagged false before the response is sent, true after a tagged response was sent
+ */
+export function releaseDeferred(connection, tag, tagged) {
+    const ready = [];
+    const waiting = [];
+    for (const entry of connection._deferredOutput) {
+        const due = tagged ? entry.mode === 'tagged' && (entry.tag === null || entry.tag === tag) : entry.mode === 'next' && tag !== null && entry.tag !== tag;
+        (due ? ready : waiting).push(entry);
+    }
+    if (ready.length) {
+        connection._deferredOutput = waiting.length ? waiting : null;
+        ready.forEach(entry => connection.write(entry.data));
+    }
+}
+/**
+ * Turns strings into literals: plain strings and STRING nodes, also in lists. Atoms, numbers, NIL, text and
+ * response codes (SECTION) stay as they are, a response code takes no literals (RFC 9051 section 9 resp-text-code)
+ *
+ * @param {*} node Response attribute
+ * @return {*} the attribute with literals, a new object where something changed
+ */
+function literalValue(node) {
+    if (typeof node === 'string') {
+        return { type: 'LITERAL', value: node };
+    }
+    if (Array.isArray(node)) {
+        return node.map(literalValue);
+    }
+    if (node && typeof node === 'object' && node.type === 'STRING') {
+        return { type: 'LITERAL', value: node.value };
+    }
+    return node;
+}
+const nodeText = (node) => String(typeof node === 'string' ? node : node && typeof node === 'object' ? node.value : '').toUpperCase();
+/**
+ * Turns the strings of a body structure into literals, except the media types that the grammar writes as quoted
+ * strings: `"TEXT"` (media-text) and `"MESSAGE" "RFC822"` or `"GLOBAL"` (media-message, RFC 9051 section 9). A literal
+ * "TEXT" would read as a basic part, and the lines count after it would break the grammar
+ *
+ * @param {*} body Body structure, a list
+ * @return {*} the body structure with literals
+ */
+function literalBody(body) {
+    if (!Array.isArray(body)) {
+        return literalValue(body);
+    }
+    if (Array.isArray(body[0])) {
+        // body-type-mpart: the parts, then the subtype and the extension data
+        const subtype = body.findIndex(item => !Array.isArray(item));
+        return body.map((item, i) => (subtype < 0 || i < subtype ? literalBody(item) : literalValue(item)));
+    }
+    const type = nodeText(body[0]);
+    const message = type === 'MESSAGE' && ['RFC822', 'GLOBAL'].includes(nodeText(body[1]));
+    return body.map((item, i) => {
+        if ((i === 0 && (type === 'TEXT' || message)) || (i === 1 && message)) {
+            return item;
+        }
+        // body-type-msg: the envelope, then the body of the encapsulated message
+        return i === 8 && message ? literalBody(item) : literalValue(item);
+    });
+}
+// FETCH items with a date-time value, which is a quoted string (RFC 9051 section 9, SAVEDATE: RFC 8514 section 4)
+const DATE_TIME_ITEMS = new Set(['INTERNALDATE', 'SAVEDATE']);
+/**
+ * Turns the strings of a response into literals wherever the grammar allows a string (RFC 9051 section 9: string,
+ * nstring and astring). Positions that take only a quoted string stay quoted: the hierarchy delimiter of LIST, LSUB
+ * and NAMESPACE, CHILDINFO values (RFC 5258 section 6), date-time values and the quoted media types of a body structure
+ *
+ * @param {Object} response Response object
+ * @return {Object} a copy of the response with literals, the response is not changed
+ */
+export function literalResponse(response) {
+    const attributes = Array.isArray(response.attributes) ? response.attributes : null;
+    if (!attributes) {
+        return response;
+    }
+    const command = nodeText(response.command);
+    const name = nodeText(attributes[1]);
+    let converted;
+    if (name === 'FETCH' || name === 'UIDFETCH') {
+        // message-data: number SP "FETCH" SP msg-att, the items are name and value pairs
+        const items = Array.isArray(attributes[2]) ? attributes[2] : [];
+        const fetched = items.map((item, i) => {
+            if (i % 2 === 0) {
+                return item;
+            }
+            const key = items[i - 1];
+            const itemName = key && !key.section ? nodeText(key) : '';
+            if (DATE_TIME_ITEMS.has(itemName)) {
+                return item;
+            }
+            return itemName === 'BODY' || itemName === 'BODYSTRUCTURE' ? literalBody(item) : literalValue(item);
+        });
+        converted = attributes.map((item, i) => (i === 2 ? fetched : item));
+    }
+    else if (command === 'LIST' || command === 'LSUB') {
+        // mailbox-list: flags, the delimiter (quoted only), the name and the extended data items
+        converted = attributes.map((item, i) => {
+            if (i === 1) {
+                return item;
+            }
+            if (i === 3 && Array.isArray(item)) {
+                return item.map((value, j) => (j % 2 === 1 && nodeText(item[j - 1]) === 'CHILDINFO' ? value : literalValue(value)));
+            }
+            return literalValue(item);
+        });
+    }
+    else if (command === 'NAMESPACE') {
+        // namespace-descr: "(" string SP (DQUOTE QUOTED-CHAR DQUOTE / nil) [extensions] ")"
+        converted = attributes.map(namespace => Array.isArray(namespace)
+            ? namespace.map(descr => (Array.isArray(descr) ? descr.map((value, i) => (i === 1 ? value : literalValue(value))) : descr))
+            : namespace);
+    }
+    else {
+        converted = attributes.map(literalValue);
+    }
+    return Object.assign({}, response, { attributes: converted });
+}
 /**
  * Sends the bytes of a rule with its timing, `truncate` closes the connection after the cut
  *

package/dist/esm/server.d.ts

@@ -4,7 +4,7 @@ import tls from 'node:tls';
 import type { CompilerOptions, ParserOptions } from 'imap-handler';
 import type { ResolvedCommandOptions } from './command-states.js';
 import { ServerScript } from './script.js';
-import type { OutputOperation, ScriptContext, ScriptEvent, ScriptRule } from './script.js';
+import type { DeferredOutput, OutputOperation, ScriptContext, ScriptEvent, ScriptRule } from './script.js';
 import type { AppendCheck, AppendCheckOptions, AppendDataHandler, AppendMessage, CapabilityCheck, CheckResult, ClosedCheck, CommandCheck, CommandContext, CommandOptions, CommandHandler, ConnectionHandler, ConnectionState, CopyHandler, FetchHandler, IMAPResponse, IMAPServerOptions, ListedMailbox, LiteralFilter, Mailbox, MailboxHandler, MailboxStatus, Message, MessageFilter, MessageHandler, MessageRange, Namespace, Notification, NotifyEvent, NotifyFilter, OutputHandler, ParsedCommand, RangeLimit, Refusal, SearchAccessCheck, SearchHandler, SearchLimit, ServerStorage, StatusHandler, StorageMailbox, StorageMessage, StoreHandler, SubscriptionStandIn, Transport, UrlAccessCheck, UserData } from './types.js';
 declare const TAG_REGEX: RegExp;
 /**
@@ -509,6 +509,10 @@ declare class IMAPConnection {
     /** output that waits behind a delay of a script rule, null when output is written right away */
     _outputQueue: OutputOperation[] | null;
     _outputTimer: ReturnType<typeof setTimeout> | null;
+    /** untagged responses that `defer` rules hold back, see releaseDeferred in src/script.ts */
+    _deferredOutput: DeferredOutput[] | null;
+    /** a script rule closes the connection with a RST, see closeNow */
+    _resetting: boolean | undefined;
     constructor(server: IMAPServer, socket: net.Socket);
     /**
      * Writes protocol output to the client, through the transport layer if there is one
@@ -528,7 +532,7 @@ declare class IMAPConnection {
      */
     flushOutput(): void;
     /**
-     * Drops the output that waits for a delay of a script rule
+     * Drops the output that waits for a delay of a script rule or for its release (`defer`)
      */
     clearOutputQueue(): void;
     /**
@@ -824,6 +828,15 @@ declare class IMAPConnection {
      *   FETCH result.  (This may have other names when used, like "affected".)
      */
     send(response: IMAPResponse, description?: string, parsed?: CommandContext | null, data?: string | null, ...extra: any[]): void;
+    /**
+     * 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: IMAPResponse, compiled: string, description?: string, parsed?: CommandContext | null): void;
     /**
      * Compiles a response for the wire
      *

package/dist/esm/server.js

@@ -14,9 +14,11 @@ import { isSequenceSet } from './numbers.js';
 import { restoreNilAtoms } from './arguments.js';
 import { refuseMissingTarget } from './commands/append.js';
 import * as bundledCert from './cert.js';
-import { ServerScript, sendOutput, handleLine } from './script.js';
+import { ServerScript, sendOutput, handleLine, literalResponse, releaseDeferred } from './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
@@ -1219,6 +1221,7 @@ class IMAPConnection {
         this.sessionNumber = ++this.server.sessionCounter;
         this._outputQueue = null;
         this._outputTimer = null;
+        this._deferredOutput = null;
         this.secureConnection = !!this.options.secureConnection;
         this._remainder = '';
         this._command = '';
@@ -1321,7 +1324,7 @@ class IMAPConnection {
         this._outputQueue = null;
     }
     /**
-     * Drops the output that waits for a delay of a script rule
+     * Drops the output that waits for a delay of a script rule or for its release (`defer`)
      */
     clearOutputQueue() {
         if (this._outputTimer) {
@@ -1329,6 +1332,7 @@ class IMAPConnection {
             this._outputTimer = null;
         }
         this._outputQueue = null;
+        this._deferredOutput = null;
     }
     /**
      * Writes output through a transport layer, or to the socket
@@ -1359,10 +1363,14 @@ class IMAPConnection {
             return;
         }
         const { rule, context } = found;
-        if (rule.mutate && compile && context.response) {
-            // a copy, a notification object is shared by every session
-            const copy = cloneResponse(context.response);
-            const changed = compile(rule.mutate(copy, context) || copy);
+        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 ? literalResponse(response) : response);
             if (changed === null) {
                 return;
             }
@@ -1436,13 +1444,23 @@ class IMAPConnection {
         this.clearOutputQueue();
         if (mode === 'reset') {
             this.discardInput();
-            // resetAndDestroy sends a TCP RST (Node 16.17), not every runtime has it
-            if (typeof socket.resetAndDestroy === 'function') {
-                socket.resetAndDestroy();
-            }
-            else {
-                socket.destroy();
-            }
+            // 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());
@@ -1579,6 +1597,9 @@ class IMAPConnection {
     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');
@@ -2198,6 +2219,24 @@ class IMAPConnection {
         if (compiled === null) {
             return;
         }
+        if (this._deferredOutput) {
+            // responses that `defer` rules hold back go before the first response of another command
+            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 !== '+') {
+            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);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapkit",
-    "version": "4.2.0",
+    "version": "4.3.0",
     "description": "Scriptable, strictly RFC compliant in-memory IMAP server for testing IMAP clients",
     "type": "module",
     "main": "./dist/cjs/index.js",