imapkit 4.3.0 → 5.0.0

package/dist/cjs/rest.js

@@ -0,0 +1,561 @@
+"use strict";
+/**
+ * The REST API: the control API over HTTP, for tests written in any language. Off unless the `rest` option (or
+ * `--rest-port`) turns it on. It is full control over the server, including the mail of every user, so it listens
+ * on 127.0.0.1 by default, needs a bearer token on any other address, sends no CORS headers, takes JSON bodies
+ * only (a browser can not send them cross-origin without a CORS preflight) and, without a token, only answers
+ * requests for a loopback host name (DNS rebinding). Built on node:http only.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRestServer = createRestServer;
+exports.isLoopback = isLoopback;
+exports.getRoutes = getRoutes;
+exports.openApi = openApi;
+const node_http_1 = __importDefault(require("node:http"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const store_operations_js_1 = require("./store-operations.js");
+// the largest literal a client can send is 64 MiB as well, see IMAPConnection#getMaxLiteralSize
+const BODY_LIMIT = 64 * 1024 * 1024;
+const STATUS_CODES = {
+    NONEXISTENT: 404,
+    NOTFOUND: 404,
+    ALREADYEXISTS: 409,
+    INVALID: 400,
+    UNAUTHORIZED: 401,
+    METHOD: 405,
+    TOOBIG: 413,
+    UNSUPPORTED: 415
+};
+/**
+ * Checks if a host name or address is a loopback one
+ *
+ * @param {String} host Host name or address, can be in brackets
+ * @return {Boolean} true for localhost, 127.0.0.0/8 and ::1
+ */
+function isLoopback(host) {
+    const name = host.replace(/^\[|\]$/g, '').toLowerCase();
+    return name === 'localhost' || name === '::1' || /^(::ffff:)?127\.\d+\.\d+\.\d+$/.test(name);
+}
+/**
+ * Turns a UID path or query value into a number, the control API checks the rest
+ *
+ * @param {String} value Value from the URL
+ * @return {Number} UID, NaN for anything that is not digits
+ */
+const toUid = (value) => (/^\d+$/.test(value) ? Number(value) : NaN);
+/**
+ * A message for JSON: the source is base64
+ *
+ * @param {Object} message Message info of the control API
+ * @return {Object} message with `raw` in base64
+ */
+function messageJson(message) {
+    const { raw, ...rest } = message;
+    return raw ? Object.assign(rest, { raw: raw.toString('base64'), encoding: 'base64' }) : rest;
+}
+/**
+ * Decodes binary data of a request body, text unless the encoding is "base64"
+ *
+ * @param {*} value Value from the body
+ * @param {*} encoding "utf-8" (default) or "base64"
+ * @return {Buffer|*} data, values that are not strings are left to the control API to refuse
+ */
+function decodeBody(value, encoding) {
+    if (encoding !== undefined && encoding !== 'base64' && encoding !== 'utf-8') {
+        throw (0, store_operations_js_1.storeError)('encoding must be "utf-8" or "base64"', 'INVALID');
+    }
+    return encoding === 'base64' && typeof value === 'string' ? Buffer.from(value, 'base64') : value;
+}
+// the server events that GET /v1/events streams
+const EVENT_TYPES = ['session', 'command', 'mailbox', 'expunge', 'flags', 'acl', 'script', 'reset'];
+const sessionNumber = (origin) => (origin ? origin.sessionNumber : null);
+/**
+ * Turns the arguments of a server event into JSON data: mailboxes become paths, messages UIDs, sessions numbers
+ *
+ * @param {String} type Event name
+ * @param {Array} args Event arguments
+ * @return {Object} event data
+ */
+function eventData(type, args) {
+    switch (type) {
+        case 'mailbox': {
+            const { type: change, path, oldPath, origin } = args[0];
+            return { type: change, path, oldPath, origin: sessionNumber(origin) };
+        }
+        case 'expunge':
+            return { path: args[0].path, uids: args[1].map(message => message.uid), origin: sessionNumber(args[2]) };
+        case 'flags':
+            return {
+                path: args[0].path,
+                messages: args[1].map(message => ({ uid: message.uid, flags: message.flags.slice() })),
+                origin: sessionNumber(args[2])
+            };
+        case 'acl':
+            return { path: args[0].path };
+        default:
+            // session, command and script events are plain data already, reset has none
+            return args[0] || {};
+    }
+}
+/**
+ * Streams server events as Server-Sent Events, `event: <type>` with the JSON data, until the client goes away
+ *
+ * @param {Object} server IMAP server
+ * @param {Array} types Event types to send
+ * @return {Function} writes the stream to a response
+ */
+function eventStream(server, types) {
+    return (res, req) => {
+        res.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store' });
+        res.write(': connected\n\n');
+        const listeners = types.map(type => {
+            const listener = (...args) => res.write('event: ' + type + '\ndata: ' + JSON.stringify(eventData(type, args)) + '\n\n');
+            server.on(type, listener);
+            return { type, listener };
+        });
+        // a comment now and then keeps proxies from closing an idle stream
+        const ping = setInterval(() => res.write(': ping\n\n'), 15000);
+        ping.unref();
+        req.on('close', () => {
+            clearInterval(ping);
+            listeners.forEach(({ type, listener }) => server.removeListener(type, listener));
+        });
+    };
+}
+/**
+ * Builds the route table of a server
+ *
+ * @param {Object} server IMAP server
+ * @return {Array} routes
+ */
+function getRoutes(server) {
+    const control = server.control;
+    const ruleJson = (handle) => ({ id: handle.id, rule: handle.rule, matched: handle.matched, hits: handle.hits });
+    const routes = [
+        { method: 'GET', path: '/v1/snapshot', summary: 'The storage in the shape of the storage option', handler: () => control.snapshot() },
+        {
+            method: 'POST',
+            path: '/v1/reset',
+            summary: 'Restores the mailboxes and users of the server options, disconnects every session',
+            handler: () => {
+                control.reset();
+                return { reset: true };
+            }
+        },
+        {
+            method: 'POST',
+            path: '/v1/shutdown',
+            summary: 'Stops accepting connections, the server closes once the last client is gone ({ graceful: false } closes them)',
+            handler: ({ body }) => {
+                // the answer goes out first
+                setImmediate(() => control.shutdown({ graceful: body.graceful !== false }).catch(() => false));
+                return { status: 202, body: { shutdown: true } };
+            }
+        },
+        { method: 'GET', path: '/v1/sessions', summary: 'Connected sessions', handler: () => control.sessions() },
+        {
+            method: 'GET',
+            path: '/v1/events',
+            summary: 'Server events as Server-Sent Events (?types=session,command to choose: ' + EVENT_TYPES.join(', ') + ')',
+            handler: ({ query }) => {
+                const wanted = query.get('types');
+                const types = wanted === null ? EVENT_TYPES : wanted.split(',');
+                const unknown = types.filter(type => EVENT_TYPES.indexOf(type) < 0);
+                if (unknown.length) {
+                    throw (0, store_operations_js_1.storeError)('Unknown event type ' + unknown.join(', ') + ', expected ' + EVENT_TYPES.join(', '), 'INVALID');
+                }
+                return { stream: eventStream(server, types) };
+            }
+        },
+        {
+            method: 'DELETE',
+            path: '/v1/sessions/{session}',
+            summary: 'Disconnects a session with BYE ({ text }) or a TCP reset ({ reset: true })',
+            handler: ({ params, body }) => {
+                if (!control.disconnect(toUid(params.session), { text: body.text, reset: body.reset })) {
+                    throw (0, store_operations_js_1.storeError)('Session ' + params.session + ' does not exist', 'NONEXISTENT');
+                }
+                return { disconnected: true };
+            }
+        },
+        {
+            method: 'POST',
+            path: '/v1/sessions/{session}/inject',
+            summary: 'Writes bytes to a session as they are ({ data, encoding })',
+            handler: ({ params, body }) => {
+                control.inject(toUid(params.session), body.encoding === 'base64' && typeof body.data === 'string' ? Buffer.from(body.data, 'base64') : body.data);
+                return { injected: true };
+            }
+        },
+        { method: 'GET', path: '/v1/users', summary: 'Users, without credentials', handler: () => control.listUsers() },
+        {
+            method: 'POST',
+            path: '/v1/users',
+            summary: 'Adds a user ({ name, password, xoauth2 })',
+            handler: ({ body }) => {
+                control.addUser(body.name, { password: body.password, xoauth2: body.xoauth2 });
+                return { status: 201, body: { name: body.name } };
+            }
+        },
+        {
+            method: 'PUT',
+            path: '/v1/users/{name}',
+            summary: 'Changes the password or the XOAUTH2 token of a user',
+            handler: ({ params, body }) => {
+                control.updateUser(params.name, { password: body.password, xoauth2: body.xoauth2 });
+                return { name: params.name };
+            }
+        },
+        {
+            method: 'DELETE',
+            path: '/v1/users/{name}',
+            summary: 'Deletes a user and disconnects its sessions ({ disconnect: false } keeps them)',
+            handler: ({ params, body }) => {
+                control.deleteUser(params.name, { disconnect: body.disconnect });
+                return { deleted: true };
+            }
+        },
+        { method: 'GET', path: '/v1/mailboxes', summary: 'Every mailbox', handler: () => control.listMailboxes() },
+        {
+            method: 'POST',
+            path: '/v1/mailboxes',
+            summary: 'Creates a mailbox ({ path, subscribed })',
+            handler: ({ body }) => ({ status: 201, body: control.createMailbox(body.path, { subscribed: body.subscribed }) })
+        },
+        { method: 'GET', path: '/v1/mailboxes/{path}', summary: 'A mailbox', handler: ({ params }) => control.getMailbox(params.path) },
+        {
+            method: 'DELETE',
+            path: '/v1/mailboxes/{path}',
+            summary: 'Deletes a mailbox, sessions that have it selected get BYE',
+            handler: ({ params }) => {
+                control.deleteMailbox(params.path);
+                return { deleted: true };
+            }
+        },
+        {
+            method: 'POST',
+            path: '/v1/mailboxes/{path}/rename',
+            summary: 'Renames a mailbox ({ newPath })',
+            handler: ({ params, body }) => control.renameMailbox(params.path, body.newPath)
+        },
+        {
+            method: 'PUT',
+            path: '/v1/mailboxes/{path}/subscription',
+            summary: 'Subscribes a mailbox',
+            handler: ({ params }) => ({ changed: control.subscribe(params.path) })
+        },
+        {
+            method: 'DELETE',
+            path: '/v1/mailboxes/{path}/subscription',
+            summary: 'Unsubscribes a name',
+            handler: ({ params }) => ({ changed: control.unsubscribe(params.path) })
+        },
+        {
+            method: 'POST',
+            path: '/v1/mailboxes/{path}/uidvalidity',
+            summary: 'Gives the mailbox a new UIDVALIDITY ({ uidvalidity, uids, offset, seed })',
+            handler: ({ params, body }) => control.resetUidValidity(params.path, body)
+        },
+        {
+            method: 'GET',
+            path: '/v1/mailboxes/{path}/messages',
+            summary: 'Messages (?uids=1,2 to choose, ?raw=true for the base64 source)',
+            handler: ({ params, query }) => {
+                const uids = query.get('uids');
+                return control
+                    .listMessages(params.path, { uids: uids === null ? undefined : uids.split(',').map(toUid), raw: query.get('raw') === 'true' })
+                    .map(messageJson);
+            }
+        },
+        {
+            method: 'POST',
+            path: '/v1/mailboxes/{path}/messages',
+            summary: 'Adds a message ({ raw, encoding, flags, internaldate, checks }), like a delivery, checks: true refuses it like APPEND would (quota)',
+            handler: ({ params, body }) => ({
+                status: 201,
+                body: control.addMessage(params.path, {
+                    raw: decodeBody(body.raw, body.encoding),
+                    flags: body.flags,
+                    internaldate: body.internaldate
+                }, { checks: body.checks })
+            })
+        },
+        {
+            method: 'POST',
+            path: '/v1/mailboxes/{path}/messages/flags',
+            summary: 'Changes flags ({ uids, flags, mode }), mode is set, add or remove',
+            handler: ({ params, body }) => control.setFlags(params.path, body.uids, body.flags, body.mode || 'set')
+        },
+        {
+            method: 'POST',
+            path: '/v1/mailboxes/{path}/messages/expunge',
+            summary: 'Removes messages ({ uids })',
+            handler: ({ params, body }) => ({ uids: control.expungeMessages(params.path, body.uids) })
+        },
+        {
+            method: 'POST',
+            path: '/v1/mailboxes/{path}/messages/copy',
+            summary: 'Copies messages ({ uids, target })',
+            handler: ({ params, body }) => control.copyMessages(params.path, body.uids, body.target)
+        },
+        {
+            method: 'POST',
+            path: '/v1/mailboxes/{path}/messages/move',
+            summary: 'Moves messages ({ uids, target })',
+            handler: ({ params, body }) => control.moveMessages(params.path, body.uids, body.target)
+        },
+        {
+            method: 'GET',
+            path: '/v1/mailboxes/{path}/messages/{uid}',
+            summary: 'A message with its base64 source',
+            handler: ({ params }) => messageJson(control.getMessage(params.path, toUid(params.uid)))
+        },
+        {
+            method: 'DELETE',
+            path: '/v1/mailboxes/{path}/messages/{uid}',
+            summary: 'Removes a message',
+            handler: ({ params }) => ({ uids: control.expungeMessages(params.path, [toUid(params.uid)]) })
+        },
+        { method: 'GET', path: '/v1/script/rules', summary: 'Script rules with their hit counts', handler: () => server.script.rules.map(ruleJson) },
+        {
+            method: 'POST',
+            path: '/v1/script/rules',
+            summary: 'Adds a script rule or a list of them, in the JSON form of the --script file',
+            handler: ({ body }) => {
+                let handles;
+                try {
+                    handles = server.script.add(body);
+                }
+                catch (err) {
+                    throw (0, store_operations_js_1.storeError)(err.message, 'INVALID');
+                }
+                return { status: 201, body: Array.isArray(handles) ? handles.map(ruleJson) : ruleJson(handles) };
+            }
+        },
+        {
+            method: 'DELETE',
+            path: '/v1/script/rules',
+            summary: 'Removes every script rule',
+            handler: () => {
+                server.script.clear();
+                return { deleted: true };
+            }
+        },
+        {
+            method: 'DELETE',
+            path: '/v1/script/rules/{id}',
+            summary: 'Removes a script rule',
+            handler: ({ params }) => {
+                const handle = server.script.rules.find(rule => String(rule.id) === params.id);
+                if (!handle) {
+                    throw (0, store_operations_js_1.storeError)('Script rule ' + params.id + ' does not exist', 'NONEXISTENT');
+                }
+                handle.remove();
+                return { deleted: true };
+            }
+        }
+    ];
+    // the operations of plugins (ACL, METADATA, QUOTA)
+    routes.push(...control.routes);
+    routes.push({ method: 'GET', path: '/v1/openapi.json', summary: 'This API as an OpenAPI document', handler: () => openApi(routes) });
+    return routes;
+}
+/**
+ * Describes the routes as an OpenAPI 3.1 document
+ *
+ * @param {Array} routes Route table
+ * @return {Object} OpenAPI document
+ */
+function openApi(routes) {
+    const paths = {};
+    routes.forEach(route => {
+        const parameters = (route.path.match(/\{(\w+)\}/g) || []).map(param => ({
+            name: param.slice(1, -1),
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+            description: param === '{path}' ? 'Storage name of the mailbox (modified UTF-7), URL encoded, a "/" in it as %2F' : undefined
+        }));
+        paths[route.path] = paths[route.path] || {};
+        paths[route.path][route.method.toLowerCase()] = {
+            summary: route.summary,
+            parameters,
+            responses: { default: { description: 'JSON, errors as { error: { code, message } }' } }
+        };
+    });
+    return {
+        openapi: '3.1.0',
+        info: { title: 'ImapKit REST API', version: '1' },
+        components: { securitySchemes: { bearer: { type: 'http', scheme: 'bearer' } } },
+        paths
+    };
+}
+/**
+ * Finds the route of a request
+ *
+ * @param {Array} routes Route table
+ * @param {String} method HTTP method
+ * @param {String} pathname URL path, still URL encoded
+ * @return {Object} `{ route, params }`, route is null if the path is known with other methods only
+ */
+function matchRoute(routes, method, pathname) {
+    const segments = pathname.split('/');
+    let pathKnown = false;
+    for (const route of routes) {
+        const pattern = route.path.split('/');
+        if (pattern.length !== segments.length) {
+            continue;
+        }
+        const params = {};
+        let matched = true;
+        for (let i = 0; i < pattern.length && matched; i++) {
+            if (pattern[i].startsWith('{')) {
+                try {
+                    params[pattern[i].slice(1, -1)] = decodeURIComponent(segments[i]);
+                }
+                catch {
+                    throw (0, store_operations_js_1.storeError)('Invalid URL encoding', 'INVALID');
+                }
+                matched = segments[i] !== '';
+            }
+            else {
+                matched = pattern[i] === segments[i];
+            }
+        }
+        if (matched) {
+            if (route.method === method) {
+                return { route, params };
+            }
+            pathKnown = true;
+        }
+    }
+    if (pathKnown) {
+        throw (0, store_operations_js_1.storeError)('Method ' + method + ' is not allowed here', 'METHOD');
+    }
+    throw (0, store_operations_js_1.storeError)('No such endpoint', 'NOTFOUND');
+}
+/**
+ * Compares a bearer token in constant time
+ *
+ * @param {String} header Authorization header
+ * @param {String} token Expected token
+ * @return {Boolean} true if the header carries the token
+ */
+function hasToken(header, token) {
+    const match = /^Bearer (.+)$/i.exec(header || '');
+    if (!match) {
+        return false;
+    }
+    const digest = (value) => node_crypto_1.default.createHash('sha256').update(value).digest();
+    return node_crypto_1.default.timingSafeEqual(digest(match[1]), digest(token));
+}
+/**
+ * Reads a JSON request body
+ *
+ * @param {Object} req HTTP request
+ * @return {Promise<Object>} the body, an empty object without one
+ */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > BODY_LIMIT) {
+                reject((0, store_operations_js_1.storeError)('Request body is larger than 64 MiB', 'TOOBIG'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('error', reject);
+        req.on('end', () => {
+            const text = Buffer.concat(chunks).toString('utf-8');
+            if (!text) {
+                return resolve({});
+            }
+            let body;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                return reject((0, store_operations_js_1.storeError)('Request body is not valid JSON', 'INVALID'));
+            }
+            if (!body || typeof body !== 'object') {
+                return reject((0, store_operations_js_1.storeError)('Request body must be a JSON object or array', 'INVALID'));
+            }
+            resolve(body);
+        });
+    });
+}
+/**
+ * Creates the HTTP server of the REST API, it does not listen yet
+ *
+ * @param {Object} server IMAP server
+ * @param {Object} options `{ host, token }`
+ * @return {Object} HTTP server
+ * @throws {Error} for a host that is not a loopback address without a token
+ */
+function createRestServer(server, options) {
+    const host = options.host || '127.0.0.1';
+    const token = options.token;
+    if (token !== undefined && (typeof token !== 'string' || !token)) {
+        throw new Error('The REST API token must be a non-empty string');
+    }
+    if (!token && !isLoopback(host)) {
+        throw new Error('The REST API controls the whole server, it needs a token (rest.token, --rest-token) to listen on ' + host);
+    }
+    const routes = getRoutes(server);
+    const send = (res, status, body) => {
+        const json = JSON.stringify(body);
+        res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(json), 'Cache-Control': 'no-store' });
+        res.end(json);
+    };
+    const handle = async (req, res) => {
+        if (token) {
+            if (!hasToken(req.headers.authorization, token)) {
+                res.setHeader('WWW-Authenticate', 'Bearer');
+                throw (0, store_operations_js_1.storeError)('Missing or wrong bearer token', 'UNAUTHORIZED');
+            }
+        }
+        else if (!isLoopback((req.headers.host || '').replace(/:\d+$/, ''))) {
+            // a page that rebinds its DNS name to 127.0.0.1 sends its own host name
+            throw (0, store_operations_js_1.storeError)('Requests must use a loopback host name', 'UNAUTHORIZED');
+        }
+        const url = new URL(req.url || '/', 'http://localhost');
+        const method = (req.method || 'GET').toUpperCase();
+        const { route, params } = matchRoute(routes, method, url.pathname);
+        let body = {};
+        if (method !== 'GET') {
+            const hasBody = Number(req.headers['content-length'] || 0) > 0 || !!req.headers['transfer-encoding'];
+            // a browser page can POST a form or text/plain cross-origin without asking. A JSON request, and every PUT and
+            // DELETE, needs a CORS preflight, which this server never allows
+            if (!/^application\/json\b/i.test(req.headers['content-type'] || '') && (hasBody || method === 'POST')) {
+                throw (0, store_operations_js_1.storeError)('Requests must be application/json', 'UNSUPPORTED');
+            }
+            body = await readBody(req);
+        }
+        const result = route.handler({ params, query: url.searchParams, body });
+        if (result && typeof result === 'object' && typeof result.stream === 'function') {
+            return result.stream(res, req);
+        }
+        if (result && typeof result === 'object' && 'status' in result && 'body' in result) {
+            const { status, body: responseBody } = result;
+            return send(res, status, responseBody);
+        }
+        send(res, 200, result === undefined ? {} : result);
+    };
+    return node_http_1.default.createServer((req, res) => {
+        handle(req, res).catch((err) => {
+            const code = err instanceof store_operations_js_1.ImapKitError ? err.code : 'SERVERERROR';
+            // RFC 5530 codes of failed mailbox operations (CANNOT, HASCHILDREN ...) are conflicts with the state
+            const status = STATUS_CODES[code] || (err instanceof store_operations_js_1.ImapKitError ? 409 : 500);
+            if (!res.headersSent) {
+                send(res, status, { error: { code, message: err.message } });
+            }
+        });
+    });
+}

package/dist/cjs/script.d.ts

@@ -7,7 +7,7 @@ import type { IMAPResponse, Transport } from './types.js';
  * core changed the response, so they can send anything at all, also what the strict server never would.
  */
 /** The events a rule can watch */
-export type ScriptEvent = 'greeting' | 'command' | 'input' | 'response' | 'continuation';
+export type ScriptEvent = 'greeting' | 'command' | 'input' | 'response' | 'continuation' | 'quiet';
 /** Bytes a rule sends, a function gets the context of the event */
 export type ScriptBytes = string | Buffer | ((context: ScriptContext) => string | Buffer);
 /** The event a rule is checked against */
@@ -31,6 +31,8 @@ export interface ScriptContext {
     description?: string | null | undefined;
     /** the response object (response and continuation events sent with `connection.send()`) */
     response?: IMAPResponse | undefined;
+    /** milliseconds without input or output (quiet events) */
+    quiet?: number | undefined;
 }
 /** A rule as it is given to `server.script.add()` or the `script` option */
 export interface ScriptRule {
@@ -56,6 +58,11 @@ export interface ScriptRule {
     nth?: number | undefined;
     /** the rule fires this many times at most (default unlimited) */
     times?: number | undefined;
+    /** the rule fires on a matching event with this probability (0 to 1), from the seeded random numbers of the
+     * server (`scriptSeed` option), so a run can be repeated */
+    chance?: number | undefined;
+    /** milliseconds without input or output before a quiet event fires (quiet events, required) */
+    quietFor?: number | undefined;
     /** sends every string of the response that the grammar allows as a literal (response events) */
     literals?: boolean | undefined;
     /**
@@ -79,8 +86,9 @@ export interface ScriptRule {
     delay?: number | undefined;
     /** write the bytes in pieces of this many octets */
     chunk?: number | undefined;
-    /** milliseconds between the pieces of `chunk` (default 10) */
-    chunkDelay?: number | undefined;
+    /** milliseconds between the pieces of `chunk` (default 10). 0 or "tick" sends each piece on its own event loop
+     * turn, so the pieces leave as separate TCP segments without a wall clock delay */
+    chunkDelay?: number | 'tick' | undefined;
     /** send only this many octets of the bytes, then close the connection */
     truncate?: number | undefined;
     /** close the connection after the bytes are sent, `"reset"` destroys the socket instead of ending it */
@@ -88,6 +96,8 @@ export interface ScriptRule {
 }
 /** A rule that was added, `server.script.add()` returns it */
 export interface ScriptHandle {
+    /** number of the rule, 1 for the first rule added to the server */
+    readonly id: number;
     readonly rule: ScriptRule;
     /** events that matched the rule, also before `nth` */
     readonly matched: number;
@@ -100,7 +110,7 @@ export interface OutputOperation {
     data?: Buffer | undefined;
     delay?: number | undefined;
     chunk?: number | undefined;
-    chunkDelay?: number | undefined;
+    chunkDelay?: number | 'tick' | undefined;
     close?: boolean | 'reset' | undefined;
     /** the transport layer of the connection when the output was queued */
     transport?: Transport | null | undefined;
@@ -119,6 +129,10 @@ interface Entry extends ScriptHandle {
 export declare class ServerScript {
     server: IMAPServer;
     entries: Entry[];
+    /** rules added so far, the id of a rule is its number */
+    ruleCounter: number;
+    /** random numbers for `chance`, seeded with the `scriptSeed` option */
+    random: () => number;
     /** the events that rules watch, so that an event nobody watches costs one lookup */
     watched: Set<ScriptEvent>;
     constructor(server: IMAPServer, rules?: ScriptRule | ScriptRule[] | undefined);
@@ -157,6 +171,13 @@ export declare class ServerScript {
         context: ScriptContext;
     } | null;
     private setEntries;
+    /**
+     * The next quiet time a rule waits for, after the quiet time the rules were checked for already
+     *
+     * @param {Number} checked Milliseconds of quiet the rules were checked for
+     * @return {Number|null} the smallest `quietFor` above it, null if there is none
+     */
+    nextQuiet(checked: number): number | null;
     private addEntry;
     /**
      * Finds the rule that handles an event and counts it
@@ -203,6 +224,14 @@ export declare function releaseDeferred(connection: IMAPConnection, tag: string
  * @return {Object} a copy of the response with literals, the response is not changed
  */
 export declare function literalResponse(response: IMAPResponse): IMAPResponse;
+/**
+ * Handles a quiet event with the rule that matched it: sends the bytes of `send` and closes the connection with `close`
+ *
+ * @param {Object} connection IMAP connection
+ * @param {Object} rule Rule that matched
+ * @param {Object} context Event context
+ */
+export declare function handleQuiet(connection: IMAPConnection, rule: ScriptRule, context: ScriptContext): void;
 /**
  * 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)