imapkit 4.1.1 → 4.2.0

package/dist/cjs/script.js

@@ -0,0 +1,332 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerScript = void 0;
+exports.sendOutput = sendOutput;
+exports.handleLine = handleLine;
+const EVENTS = ['greeting', 'command', 'input', 'response', 'continuation'];
+const OUTPUT_EVENTS = ['greeting', 'response', 'continuation'];
+// the events where a key is valid, every other key is a typo and refused
+const KEYS = {
+    on: EVENTS,
+    command: ['command', 'input', 'response', 'continuation'],
+    tag: ['command', 'input', 'response', 'continuation'],
+    description: ['response', 'continuation'],
+    session: EVENTS,
+    user: EVENTS,
+    state: EVENTS,
+    mailbox: EVENTS,
+    untagged: ['response'],
+    match: EVENTS,
+    when: EVENTS,
+    nth: EVENTS,
+    times: EVENTS,
+    mutate: ['response', 'continuation'],
+    send: EVENTS,
+    before: OUTPUT_EVENTS,
+    after: OUTPUT_EVENTS,
+    run: ['command', 'input'],
+    drop: EVENTS,
+    delay: ['greeting', 'command', 'response', 'continuation'],
+    chunk: EVENTS,
+    chunkDelay: EVENTS,
+    truncate: EVENTS,
+    close: EVENTS
+};
+const ACTIONS = ['mutate', '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'];
+/**
+ * Turns bytes of a rule into a Buffer. A string is a binary string (one character per octet) like everywhere
+ * in ImapKit, unless it has characters above U+00FF, then it is sent as UTF-8
+ */
+function resolveBytes(value, context) {
+    if (value === undefined) {
+        return null;
+    }
+    const bytes = typeof value === 'function' ? value(context) : value;
+    if (Buffer.isBuffer(bytes)) {
+        return bytes;
+    }
+    const text = String(bytes).replace(/\$TAG/g, () => context.tag || '*');
+    return Buffer.from(text, /[\u0100-\uffff]/.test(text) ? 'utf-8' : 'binary');
+}
+/**
+ * Checks a rule given by the caller, a mistake is a TypeError right away instead of a rule that silently never fires
+ *
+ * @param {Object} rule Rule to check
+ * @return {RegExp|null} the `match` expression
+ */
+function validateRule(rule) {
+    if (!rule || typeof rule !== 'object') {
+        throw new TypeError('A script rule must be an object');
+    }
+    if (!EVENTS.includes(rule.on)) {
+        throw new TypeError('Script rule "on" must be one of ' + EVENTS.join(', '));
+    }
+    for (const key of Object.keys(rule)) {
+        const events = Object.hasOwn(KEYS, key) ? KEYS[key] : null;
+        if (!events) {
+            throw new TypeError('Unknown script rule option "' + key + '"');
+        }
+        if (!events.includes(rule.on)) {
+            throw new TypeError('Script rule option "' + key + '" can not be used with "on": "' + rule.on + '"');
+        }
+    }
+    if (!ACTIONS.some(key => rule[key] !== undefined && rule[key] !== false)) {
+        throw new TypeError('A script rule needs an action (' + ACTIONS.join(', ') + ')');
+    }
+    if (rule.drop && (rule.send !== undefined || rule.run)) {
+        throw new TypeError('Script rule option "drop" can not be combined with "send" or "run"');
+    }
+    if (rule.run && (rule.close || rule.truncate !== undefined)) {
+        throw new TypeError('Script rule option "run" can not be combined with "close" or "truncate"');
+    }
+    if (rule.chunkDelay !== undefined && rule.chunk === undefined) {
+        throw new TypeError('Script rule option "chunkDelay" needs "chunk"');
+    }
+    if (!OUTPUT_EVENTS.includes(rule.on) && rule.send === undefined && (rule.chunk !== undefined || rule.truncate !== undefined)) {
+        // a command or input line has no output of its own to cut or split
+        throw new TypeError('Script rule options "chunk" and "truncate" need "send" with "on": "' + rule.on + '"');
+    }
+    for (const key of ['nth', 'times', 'chunk']) {
+        if (rule[key] !== undefined && !(Number.isInteger(rule[key]) && rule[key] > 0)) {
+            throw new TypeError('Script rule option "' + key + '" must be a positive integer');
+        }
+    }
+    for (const key of ['delay', 'chunkDelay', 'truncate']) {
+        if (rule[key] !== undefined && !(Number.isInteger(rule[key]) && rule[key] >= 0)) {
+            throw new TypeError('Script rule option "' + key + '" must be a non-negative integer');
+        }
+    }
+    for (const key of ['when', 'mutate']) {
+        if (rule[key] !== undefined && typeof rule[key] !== 'function') {
+            throw new TypeError('Script rule option "' + key + '" must be a function');
+        }
+    }
+    for (const key of ['send', 'before', 'after']) {
+        const value = rule[key];
+        if (value !== undefined && typeof value !== 'string' && typeof value !== 'function' && !Buffer.isBuffer(value)) {
+            throw new TypeError('Script rule option "' + key + '" must be a string, a Buffer or a function');
+        }
+    }
+    if (rule.close !== undefined && typeof rule.close !== 'boolean' && rule.close !== 'reset') {
+        throw new TypeError('Script rule option "close" must be true, false or "reset"');
+    }
+    if (rule.match === undefined) {
+        return null;
+    }
+    if (rule.match instanceof RegExp) {
+        // a global or sticky expression would keep its position between events
+        return new RegExp(rule.match.source, rule.match.flags.replace(/[gy]/g, ''));
+    }
+    if (typeof rule.match !== 'string') {
+        throw new TypeError('Script rule option "match" must be a string or a RegExp');
+    }
+    try {
+        return new RegExp(rule.match);
+    }
+    catch (err) {
+        throw new TypeError('Script rule option "match" is not a valid regular expression: ' + err.message, { cause: err });
+    }
+}
+/**
+ * The script of a server, `server.script`
+ */
+class ServerScript {
+    constructor(server, rules) {
+        this.server = server;
+        this.entries = [];
+        this.watched = new Set();
+        if (rules) {
+            this.add(rules);
+        }
+    }
+    /** the rules that were added, in the order they are checked */
+    get rules() {
+        return this.entries.slice();
+    }
+    add(rules) {
+        if (Array.isArray(rules)) {
+            // all rules are checked before any is added
+            const matches = rules.map(validateRule);
+            return rules.map((rule, i) => this.addEntry(rule, matches[i]));
+        }
+        return this.addEntry(rules, validateRule(rules));
+    }
+    /** removes every rule */
+    clear() {
+        this.setEntries([]);
+    }
+    /**
+     * Checks if any rule watches an event, so that the event can skip building a context
+     *
+     * @param {String} event Event name
+     * @return {Boolean} true if a rule watches the event
+     */
+    watches(event) {
+        return this.watched.has(event);
+    }
+    /**
+     * Finds the rule that handles an event of a connection
+     *
+     * @param {Object} connection IMAP connection
+     * @param {String} event Event name
+     * @param {Object} fields `data`, and `tag`, `command`, `description`, `response` where they are known
+     * @return {Object|null} `{ rule, context }`, or null if no rule handles the event
+     */
+    check(connection, event, fields) {
+        if (!this.watched.has(event)) {
+            return null;
+        }
+        const context = scriptContext(connection, event, fields);
+        const rule = this.find(context);
+        return rule ? { rule, context } : null;
+    }
+    setEntries(entries) {
+        this.entries = entries;
+        this.watched = new Set(entries.map(entry => entry.rule.on));
+    }
+    addEntry(rule, match) {
+        // a copy, so that changing the caller's object later does not change the rule
+        const copy = Object.freeze(Object.assign({}, rule));
+        const sets = {};
+        for (const key of SET_MATCHERS) {
+            if (copy[key] !== undefined) {
+                // command names are compared in upper case
+                const values = [].concat(copy[key]);
+                sets[key] = new Set(key === 'command' ? values.map(value => String(value).toUpperCase()) : values);
+            }
+        }
+        const entry = {
+            rule: copy,
+            match,
+            sets,
+            matched: 0,
+            hits: 0,
+            remove: () => this.setEntries(this.entries.filter(item => item !== entry))
+        };
+        this.setEntries(this.entries.concat(entry));
+        return entry;
+    }
+    /**
+     * Finds the rule that handles an event and counts it
+     *
+     * @param {Object} context Event context
+     * @return {Object|null} the rule, or null if no rule handles the event
+     */
+    find(context) {
+        for (const entry of this.entries) {
+            const rule = entry.rule;
+            if (rule.on !== context.event || !this.matches(entry, context)) {
+                continue;
+            }
+            entry.matched++;
+            if (entry.matched < (rule.nth || 1) || (rule.times !== undefined && entry.hits >= rule.times)) {
+                continue;
+            }
+            entry.hits++;
+            this.server.emit('script', { rule, event: context.event, session: context.session, tag: context.tag, command: context.command });
+            return rule;
+        }
+        return null;
+    }
+    matches(entry, context) {
+        const rule = entry.rule;
+        for (const key of SET_MATCHERS) {
+            const set = entry.sets[key];
+            const value = context[key];
+            if (set && (value === null || value === undefined || !set.has(value))) {
+                return false;
+            }
+        }
+        if (rule.tag !== undefined && (context.tag === null || (rule.tag instanceof RegExp ? !rule.tag.test(context.tag) : rule.tag !== context.tag))) {
+            return false;
+        }
+        if (rule.untagged !== undefined && rule.untagged !== (!context.response || context.response.tag === '*')) {
+            return false;
+        }
+        if (entry.match && !entry.match.test(context.data)) {
+            return false;
+        }
+        return !rule.when || !!rule.when(context);
+    }
+}
+exports.ServerScript = ServerScript;
+/**
+ * Builds the context of an event on a connection
+ *
+ * @param {Object} connection IMAP connection
+ * @param {String} event Event name
+ * @param {Object} fields `data`, and `tag`, `command`, `description`, `response` where they are known
+ * @return {Object} Event context
+ */
+function scriptContext(connection, event, fields) {
+    // after its handler returned, a command whose input handler reads the lines (IDLE, AUTHENTICATE) is the one
+    // the events belong to
+    const running = connection._runningCommand
+        ? connection._runningCommand.parsed
+        : connection.inputHandler
+            ? connection.inputCommand
+            : null;
+    return Object.assign({
+        event,
+        connection,
+        session: connection.sessionNumber,
+        state: connection.state,
+        user: connection.username || null,
+        mailbox: connection.selectedMailbox ? connection.selectedMailbox.path : null,
+        tag: running ? running.tag : null,
+        command: running ? String(running.command).toUpperCase() : null
+    }, fields);
+}
+/**
+ * Sends output through the rule that handles it: the output itself (unless dropped or replaced with `send`)
+ * between `before` and `after`, cut by `truncate`, with the timing of `delay` and `chunk`
+ *
+ * @param {Object} connection IMAP connection
+ * @param {Object} rule Rule that handles the output
+ * @param {Object} context Event context
+ * @param {Buffer} output The output
+ */
+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);
+    sendBytes(connection, rule, Buffer.concat(parts), rule.delay);
+}
+/**
+ * Sends the bytes of a rule with its timing, `truncate` closes the connection after the cut
+ *
+ * @param {Object} connection IMAP connection
+ * @param {Object} rule Rule
+ * @param {Buffer} data Bytes to send
+ * @param {Number} [delay] Milliseconds to wait first
+ */
+function sendBytes(connection, rule, data, delay) {
+    connection.queueOutput({
+        data: rule.truncate === undefined ? data : data.subarray(0, rule.truncate),
+        delay,
+        chunk: rule.chunk,
+        chunkDelay: rule.chunkDelay === undefined ? DEFAULT_CHUNK_DELAY : rule.chunkDelay,
+        close: rule.close || (rule.truncate === undefined ? undefined : true)
+    });
+}
+/**
+ * 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)
+ *
+ * @param {Object} connection IMAP connection
+ * @param {Object} rule Rule that matched
+ * @param {Object} context Event context
+ * @param {Function} run Processes the line as usual
+ */
+function handleLine(connection, rule, context, run) {
+    const bytes = resolveBytes(rule.send, context);
+    if (bytes || rule.close) {
+        sendBytes(connection, rule, bytes || Buffer.alloc(0));
+    }
+    // a rule that only delays the line does not replace it
+    if (rule.run || (!rule.drop && !bytes && !rule.close)) {
+        run();
+    }
+}

package/dist/cjs/server.d.ts

@@ -3,6 +3,8 @@ import net from 'node:net';
 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 { 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;
 /**
@@ -58,6 +60,10 @@ declare class IMAPServer extends Stream {
     uidvalidityCounter: number;
     subscriptions: Set<string>;
     folderCache: Record<string, Mailbox>;
+    /** scripted faults, see src/script.ts */
+    script: ServerScript;
+    /** connections accepted so far, the number of a connection is `connection.sessionNumber` */
+    sessionCounter: number;
     constructor(options?: IMAPServerOptions);
     /**
      * Starts accepting connections, takes the arguments of `net.Server#listen()`
@@ -446,6 +452,11 @@ declare class IMAPServer extends Stream {
 interface QueuedCommand {
     parsed: ParsedCommand;
     data: string;
+    /** a command line that a script rule handles instead of the parser and the command handler */
+    script?: {
+        rule: ScriptRule;
+        context: ScriptContext;
+    } | undefined;
 }
 declare class IMAPConnection {
     [key: string]: any;
@@ -471,6 +482,13 @@ declare class IMAPConnection {
     /** notifications are sent right away instead of before the next tagged response (IDLE) */
     directNotifications: boolean;
     notificationQueue: Notification[];
+    /** the number of the connection, 1 for the first one the server accepted (script rules match it) */
+    sessionNumber: number;
+    /** the tag and name of the command whose input handler reads the lines that follow (IDLE, AUTHENTICATE) */
+    inputCommand: {
+        tag: string;
+        command: string;
+    } | null | undefined;
     _remainder: string;
     _command: string;
     _literalRemaining: number;
@@ -488,6 +506,9 @@ declare class IMAPConnection {
         command: string;
         read: number | undefined;
     } | undefined;
+    /** 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;
     constructor(server: IMAPServer, socket: net.Socket);
     /**
      * Writes protocol output to the client, through the transport layer if there is one
@@ -495,6 +516,45 @@ declare class IMAPConnection {
      * @param {Buffer|String} data Data to send, a string is sent as a binary string
      */
     write(data: Buffer | string): void;
+    /**
+     * 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: OutputOperation): void;
+    /**
+     * Writes the output queue until it is empty or a delay stops it
+     */
+    flushOutput(): void;
+    /**
+     * Drops the output that waits for a delay of a script rule
+     */
+    clearOutputQueue(): void;
+    /**
+     * Writes output through a transport layer, or to the socket
+     *
+     * @param {Buffer} data Output
+     * @param {Object|null} transport Transport layer
+     */
+    writeLayer(data: Buffer, transport: Transport | null): void;
+    /**
+     * 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: ScriptEvent, output: string, fields: Partial<ScriptContext>, compile?: (response: IMAPResponse) => string | null): void;
+    /**
+     * 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: string, description: string, getLine?: () => string): void;
     /**
      * Writes data to the socket, below the transport layer
      *
@@ -512,6 +572,12 @@ declare class IMAPConnection {
      * holds, is written out
      */
     end(): void;
+    /**
+     * 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: boolean | 'reset'): void;
     /**
      * Sends an untagged BYE, drops unprocessed input and closes the connection (RFC 3501 section 7.1.5)
      *
@@ -564,6 +630,12 @@ declare class IMAPConnection {
     closeMailbox(): void;
     onClose(): void;
     onError(err: Error): void;
+    /**
+     * Passes a line to the input handler (IDLE, AUTHENTICATE), unless a script rule handles it
+     *
+     * @param {String} line Input line without CRLF
+     */
+    handleInput(line: string): void;
     onData(chunk: Buffer): void;
     /**
      * Reads literal data that the current command is waiting for. The data of a command that was
@@ -752,6 +824,13 @@ 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;
+    /**
+     * 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: IMAPResponse): string | null;
     /**
      * Sends a tagged status response to a command
      *
@@ -848,7 +927,21 @@ declare class IMAPConnection {
      * @return {String} Mailbox name as a binary string
      */
     exportMailboxName(path: string): string;
-    scheduleCommand(data: string): void;
+    /**
+     * 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: string, scripted?: boolean): void;
+    /**
+     * 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: QueuedCommand, next: () => void): void;
     processQueue(force?: boolean): void;
     /**
      * Removes messages with \Deleted flag