imapkit 4.3.1 → 5.0.1

package/dist/esm/plugins/metadata.js

@@ -1,3 +1,4 @@
+import { storeError } from '../store-operations.js';
 import { states } from '../command-states.js';
 import { isNumber } from '../numbers.js';
 import { isAstring } from '../arguments.js';
@@ -10,6 +11,7 @@ import { registerEnable, isEnabled } from './enable.js';
  * @help default 65536), "metadataMaxEntries" (per mailbox and for the
  * @help server, default 100). "metadataPrivate": false turns /private
  * @help entries off. ENABLE METADATA turns on unsolicited METADATA responses
+ * @help (loads the ENABLE plugin, RFC 5464 section 4.1)
  */
 // Default limits, RFC 5464 section 4.1 requires at least 1024 octets and 10 entries
 const DEFAULT_MAX_SIZE = 64 * 1024;
@@ -308,6 +310,60 @@ function setup(server, mailboxes) {
         return callback();
     }, { states: states.AUTHENTICATED });
     // RFC 5464 section 4.3: setmetadata = "SETMETADATA" SP mailbox SP entry-values
+    /**
+     * Stores the changes of SETMETADATA (or of the control API) when all of them pass the checks, and tells the
+     * sessions that used ENABLE METADATA about the changed entries. The session that made the change
+     * (`server.activeConnection`) is not told, and without one (the control API) the read-only server entries can
+     * be set too
+     *
+     * @param {Object} holder Mailbox object or state.server
+     * @param {Map} changes Lower case entry name to the new value, null removes the entry
+     * @return {Object|null} `{ text, code }` when a change fails, nothing is changed then
+     */
+    const storeChanges = (holder, changes) => {
+        const origin = server.activeConnection;
+        const entries = getEntries(holder);
+        const computed = getComputedEntries(holder);
+        // changes go to a copy that replaces the entries once every check passed
+        const next = Object.assign(Object.create(null), entries);
+        const changed = [];
+        for (const [name, value] of changes) {
+            if ((!holder.path && origin && READ_ONLY_SERVER_ENTRIES.has(name)) || name in computed) {
+                return { text: 'The ' + name + ' entry is read-only', code: 'CANNOT' };
+            }
+            if (!state.allowPrivate && name.startsWith('/private/')) {
+                return { text: 'Private annotations are not supported', code: ['METADATA', 'NOPRIVATE'] };
+            }
+            if (value !== null && value.length > state.maxSize) {
+                return { text: 'Value of ' + name + ' is too large', code: ['METADATA', 'MAXSIZE', state.maxSize] };
+            }
+            if ((entries[name] ?? null) !== value) {
+                changed.push(name);
+            }
+            if (value === null) {
+                delete next[name];
+            }
+            else {
+                next[name] = value;
+            }
+        }
+        // only adding entries can fail, even when the storage already holds more than the limit
+        const count = Object.keys(next).length;
+        if (count > state.maxEntries && count > Object.keys(entries).length) {
+            return { text: 'Too many annotations', code: ['METADATA', 'TOOMANY'] };
+        }
+        setEntries(holder, next);
+        if (changed.length) {
+            // RFC 5464 section 4.4.2: unsolicited responses only list the entry names. Section 4.1:
+            // only sessions that used ENABLE METADATA (or METADATA-SERVER) get them
+            server.notify({
+                tag: '*',
+                command: 'METADATA',
+                attributes: [mailboxAttribute(holder.path)].concat(changed.map(name => ({ type: 'ATOM', value: name })))
+            }, false, origin, isMetadataEnabled);
+        }
+        return null;
+    };
     server.setCommandHandler('SETMETADATA', (connection, parsed, data, callback) => {
         const attrs = parsed.attributes || [];
         if (attrs.length !== 2 || !isAstring(attrs[0]) || !Array.isArray(attrs[1])) {
@@ -343,79 +399,109 @@ function setup(server, mailboxes) {
         if (!holder) {
             return callback();
         }
-        const entries = getEntries(holder);
-        const computed = getComputedEntries(holder);
-        const fail = (text, code) => {
+        const failure = storeChanges(holder, changes);
+        if (failure) {
             // RFC 5464 section 4.3: when one entry fails, no entry is changed
-            connection.sendStatus(parsed, data, 'NO', text, code);
+            connection.sendStatus(parsed, data, 'NO', failure.text, failure.code);
             return callback();
-        };
-        // changes go to a copy that replaces the entries once every check passed
-        const next = Object.assign(Object.create(null), entries);
-        const changed = [];
-        for (const [name, value] of changes) {
-            if ((!holder.path && READ_ONLY_SERVER_ENTRIES.has(name)) || name in computed) {
-                return fail('The ' + name + ' entry is read-only', 'CANNOT');
-            }
-            if (!state.allowPrivate && name.startsWith('/private/')) {
-                return fail('Private annotations are not supported', ['METADATA', 'NOPRIVATE']);
-            }
-            if (value !== null && value.length > state.maxSize) {
-                return fail('Value of ' + name + ' is too large', ['METADATA', 'MAXSIZE', state.maxSize]);
-            }
-            if ((entries[name] ?? null) !== value) {
-                changed.push(name);
-            }
-            if (value === null) {
-                delete next[name];
-            }
-            else {
-                next[name] = value;
-            }
-        }
-        // only adding entries can fail, even when the storage already holds more than the limit
-        const count = Object.keys(next).length;
-        if (count > state.maxEntries && count > Object.keys(entries).length) {
-            return fail('Too many annotations', ['METADATA', 'TOOMANY']);
-        }
-        setEntries(holder, next);
-        if (changed.length) {
-            // RFC 5464 section 4.4.2: unsolicited responses only list the entry names. Section 4.1:
-            // only sessions that used ENABLE METADATA (or METADATA-SERVER) get them
-            server.notify({
-                tag: '*',
-                command: 'METADATA',
-                attributes: [mailboxAttribute(holder.path)].concat(changed.map(name => ({ type: 'ATOM', value: name })))
-            }, false, connection, isMetadataEnabled);
         }
         connection.sendStatus(parsed, data, 'OK', 'SETMETADATA completed');
         return callback();
     }, 
     // RFC 5464 section 5: values can be literal8, with or without BINARY
     { states: states.AUTHENTICATED, mailboxArguments: [0], literal8: true });
-    server.outputHandlers.push((connection, response, description, parsed, data, extra) => {
-        if (response.command !== 'OK' || !parsed || !parsed.attributes) {
-            return;
-        }
-        if (description === 'RENAME' && extra && extra.path === 'INBOX') {
-            // RFC 5464 section 4.1: renaming INBOX copies its annotations, INBOX keeps them. Other
-            // mailboxes are moved as objects, so their annotations follow without any help
-            const target = connection.server.getMailbox(parsed.attributes[1].value);
-            if (target && target !== extra && extra.metadata) {
-                setEntries(target, Object.assign(Object.create(null), getEntries(extra)));
+    server.on('mailbox', (event) => {
+        if (event.type === 'rename' && event.oldPath === 'INBOX') {
+            // RFC 5464 section 4.1: renaming INBOX copies its annotations, INBOX keeps them. Other mailboxes are
+            // moved as objects, so their annotations follow without any help
+            const inbox = server.getMailbox('INBOX');
+            const target = server.getMailbox(event.path);
+            if (inbox && target && target !== inbox && inbox.metadata) {
+                setEntries(target, Object.assign(Object.create(null), getEntries(inbox)));
             }
         }
-        else if (description === 'DELETE') {
-            // RFC 5464 section 4.1: a mailbox created later with the same name must not inherit the
-            // annotations. A mailbox with children stays as a \Noselect placeholder
-            const placeholder = connection.server.getMailbox(parsed.attributes[0].value);
-            if (placeholder) {
+        else if (event.type === 'delete') {
+            // RFC 5464 section 4.1: a mailbox created later with the same name must not inherit the annotations.
+            // A mailbox with children stays as a \Noselect placeholder
+            const placeholder = server.getMailbox(event.path);
+            if (placeholder && placeholder !== event.mailbox) {
                 delete placeholder.metadata;
             }
         }
     });
+    // Control API (README "Control API"): the stored annotations of a mailbox, or of the server for "". Values are
+    // UTF-8 text, the protocol keeps them as octets
+    // control.reset() restores the server annotations of the options, the mailboxes come with their storage
+    server.on('reset', () => {
+        state.server = { path: '', metadata: options.metadata };
+    });
+    const controlHolder = (path) => {
+        if (path === '') {
+            return state.server;
+        }
+        if (!state.mailboxes) {
+            throw storeError('Mailbox annotations need the METADATA plugin, METADATA-SERVER has server annotations only', 'INVALID');
+        }
+        return server.control.requireMailbox(path);
+    };
+    const getMetadataOperation = (path) => {
+        const entries = getEntries(controlHolder(path));
+        const result = {};
+        Object.keys(entries).forEach(name => {
+            result[name] = Buffer.from(entries[name], 'binary').toString('utf-8');
+        });
+        return result;
+    };
+    const setMetadataOperation = (path, values) => {
+        const holder = controlHolder(path);
+        if (!values || typeof values !== 'object' || Array.isArray(values)) {
+            throw storeError('setMetadata expects an object of entry names and values (null removes an entry)', 'INVALID');
+        }
+        const changes = new Map();
+        Object.keys(values).forEach(name => {
+            const value = values[name];
+            const error = checkEntryName(name, true);
+            if (error) {
+                throw storeError(error, 'INVALID');
+            }
+            if (value !== null && typeof value !== 'string') {
+                throw storeError('Value of ' + name + ' must be a string or null', 'INVALID');
+            }
+            changes.set(name.toLowerCase(), value === null ? null : Buffer.from(value, 'utf-8').toString('binary'));
+        });
+        const failure = storeChanges(holder, changes);
+        if (failure) {
+            throw storeError(failure.text, typeof failure.code === 'string' ? failure.code : 'INVALID');
+        }
+        return getMetadataOperation(path);
+    };
+    server.control.register('getMetadata', getMetadataOperation, [
+        { method: 'GET', path: '/v1/metadata', summary: 'Server annotations (METADATA plugins)', handler: () => server.control.getMetadata('') },
+        {
+            method: 'GET',
+            path: '/v1/mailboxes/{path}/metadata',
+            summary: 'Mailbox annotations (METADATA plugin)',
+            handler: ({ params }) => server.control.getMetadata(params.path)
+        }
+    ]);
+    server.control.register('setMetadata', setMetadataOperation, [
+        {
+            method: 'PUT',
+            path: '/v1/metadata',
+            summary: 'Sets server annotations ({ "/shared/comment": "text" }, null removes one, METADATA plugins)',
+            handler: ({ body }) => server.control.setMetadata('', body)
+        },
+        {
+            method: 'PUT',
+            path: '/v1/mailboxes/{path}/metadata',
+            summary: 'Sets mailbox annotations (METADATA plugin)',
+            handler: ({ params, body }) => server.control.setMetadata(params.path, body)
+        }
+    ]);
 }
 export default function metadataPlugin(server) {
     setup(server, true);
 }
+// RFC 5464 section 4.1: a server that sends unsolicited METADATA responses "MUST support the ENABLE command"
+metadataPlugin.requires = ['ENABLE'];
 export { setup };

package/dist/esm/plugins/objectid.js

@@ -95,6 +95,16 @@ export default function objectidPlugin(server) {
         }
         getMailboxId(mailbox);
     });
+    // Control API (README "Control API"): the object ids in getMailbox() and getMessage()
+    server.control.mailboxInfoHandlers.push((mailbox, info) => {
+        if (mailbox.flags.indexOf('\\Noselect') < 0) {
+            info.mailboxId = getMailboxId(mailbox);
+        }
+    });
+    server.control.messageInfoHandlers.push((message, info) => {
+        info.emailId = message.EMAILID;
+        info.threadId = message.THREADID;
+    });
     server.messageHandlers.push((server, message, mailbox) => {
         const owner = 'a message of mailbox ' + mailbox.path;
         if (message.EMAILID) {

package/dist/esm/plugins/quota.js

@@ -1,3 +1,4 @@
+import { storeError } from '../store-operations.js';
 import { states } from '../command-states.js';
 import { normalizeLineBreaks } from '../mimeparser.js';
 import { MAX_NUMBER64, isNumber } from '../numbers.js';
@@ -29,6 +30,8 @@ export default function quotaPlugin(server) {
         soft: !!config.soft,
         limits: {}
     };
+    // the limits of the quota option, control.reset() restores them
+    const initialLimits = {};
     RESOURCES.forEach(resource => {
         if (config[resource] === undefined || config[resource] === null) {
             return;
@@ -37,8 +40,13 @@ export default function quotaPlugin(server) {
         if (!Number.isSafeInteger(limit) || limit < 0) {
             throw new Error('Invalid quota limit for ' + resource + ': ' + JSON.stringify(config[resource]));
         }
-        root.limits[resource] = limit;
+        initialLimits[resource] = limit;
     });
+    const restoreLimits = () => {
+        root.limits = Object.assign({}, initialLimits);
+    };
+    restoreLimits();
+    server.on('reset', restoreLimits);
     // RFC 9208 sections 3.1.1 and 5: every supported resource is advertised, SETQUOTA needs QUOTASET
     server.registerCapability('QUOTA');
     RESOURCES.forEach(resource => server.registerCapability('QUOTA=RES-' + resource));
@@ -111,7 +119,7 @@ export default function quotaPlugin(server) {
         }
         const added = { MESSAGE: messages.length, bytes: totalSize(messages) };
         // RFC 8508 section 3.4: REPLACE counts only the net usage, the replaced message is removed
-        if (options.replaced && connection.selectedMailbox && inRoot(connection.selectedMailbox)) {
+        if (options.replaced && connection && connection.selectedMailbox && inRoot(connection.selectedMailbox)) {
             added.MESSAGE--;
             added.bytes -= totalSize([options.replaced]);
         }
@@ -236,4 +244,44 @@ export default function quotaPlugin(server) {
         }
     });
     server.statusHandlers['DELETED-STORAGE'] = (connection, mailbox) => totalSize(mailbox.messages.filter(message => message.flags.indexOf('\\Deleted') >= 0));
+    // Control API (README "Control API"): the quota root with its limits and usage, STORAGE in units of 1024 octets
+    const getQuotaOperation = () => {
+        const usage = getUsage();
+        return {
+            root: root.name,
+            limits: Object.assign({}, root.limits),
+            usage: { STORAGE: Math.ceil(usage.bytes / 1024), MESSAGE: usage.MESSAGE, MAILBOX: usage.MAILBOX }
+        };
+    };
+    // the new limits replace all earlier ones, like SETQUOTA (RFC 9208 section 4.1.3)
+    const setQuotaOperation = (limits) => {
+        if (!limits || typeof limits !== 'object' || Array.isArray(limits)) {
+            throw storeError('setQuota expects an object of resource limits, e.g. { STORAGE: 1024 }', 'INVALID');
+        }
+        const next = {};
+        Object.keys(limits).forEach(name => {
+            const resource = name.toUpperCase();
+            const value = limits[name];
+            if (RESOURCES.indexOf(resource) < 0) {
+                throw storeError('Unknown quota resource ' + name + ', expected ' + RESOURCES.join(', '), 'INVALID');
+            }
+            if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+                throw storeError('Limit of ' + resource + ' must be a non-negative integer', 'INVALID');
+            }
+            next[resource] = value;
+        });
+        root.limits = next;
+        return getQuotaOperation();
+    };
+    server.control.register('getQuota', getQuotaOperation, [
+        { method: 'GET', path: '/v1/quota', summary: 'Quota root, limits and usage (QUOTA plugin)', handler: () => server.control.getQuota() }
+    ]);
+    server.control.register('setQuota', setQuotaOperation, [
+        {
+            method: 'PUT',
+            path: '/v1/quota',
+            summary: 'Replaces the quota limits ({ STORAGE, MESSAGE, MAILBOX }, QUOTA plugin)',
+            handler: ({ body }) => server.control.setQuota(body)
+        }
+    ]);
 }

package/dist/esm/plugins/savedate.js

@@ -25,7 +25,7 @@ export default function savedatePlugin(server) {
             delete message.SAVEDATE;
             return;
         }
-        const savedate = server.normalizeDateTime(message.SAVEDATE || new Date());
+        const savedate = server.normalizeDateTime(message.SAVEDATE || server.now());
         if (!server.validateInternalDate(savedate)) {
             throw new Error('Invalid SAVEDATE value ' + JSON.stringify(savedate) + ' in mailbox ' + mailbox.path);
         }

package/dist/esm/plugins/special-use.d.ts

@@ -1,10 +1,2 @@
 import type { IMAPServer } from '../types.js';
-/**
- * @help Enables SPECIAL-USE [RFC6154] capability
- * @help Mailboxes need to have a "special-use"
- * @help property (String or Array) that will be used
- * @help as extra flag for LIST and LSUB responses.
- * @help With LIST-EXTENDED the SPECIAL-USE selection and
- * @help return options work with the other LIST options
- */
 export default function specialUsePlugin(server: IMAPServer): void;

package/dist/esm/plugins/special-use.js

@@ -1,4 +1,5 @@
 import { getListExtensions } from '../list-extensions.js';
+import { storeError } from '../store-operations.js';
 /**
  * @help Enables SPECIAL-USE [RFC6154] capability
  * @help Mailboxes need to have a "special-use"
@@ -7,6 +8,8 @@ import { getListExtensions } from '../list-extensions.js';
  * @help With LIST-EXTENDED the SPECIAL-USE selection and
  * @help return options work with the other LIST options
  */
+// RFC 6154 section 2 and RFC 8457 (\\Important)
+const SPECIAL_USES = new Set(['\\All', '\\Archive', '\\Drafts', '\\Flagged', '\\Junk', '\\Sent', '\\Trash', '\\Important']);
 export default function specialUsePlugin(server) {
     // Register capability
     server.registerCapability('SPECIAL-USE');
@@ -77,4 +80,24 @@ export default function specialUsePlugin(server) {
             }
         }
     });
+    // Control API (README "Control API"): the special-use attributes of a mailbox (RFC 6154 section 2)
+    server.control.mailboxInfoHandlers.push((mailbox, info) => {
+        info.specialUse = getSpecialUse(mailbox);
+    });
+    const setSpecialUseOperation = (path, uses) => {
+        const mailbox = server.control.requireMailbox(path, true);
+        if (!Array.isArray(uses) || uses.some(use => typeof use !== 'string' || !SPECIAL_USES.has(use))) {
+            throw storeError('Special-use attributes must be a list of ' + [...SPECIAL_USES].join(', '), 'INVALID');
+        }
+        mailbox['special-use'] = [...new Set(uses)];
+        return server.control.getMailbox(mailbox.path);
+    };
+    server.control.register('setSpecialUse', setSpecialUseOperation, [
+        {
+            method: 'PUT',
+            path: '/v1/mailboxes/{path}/special-use',
+            summary: 'Sets the special-use attributes of a mailbox ({ specialUse: ["\\Sent"] }, SPECIAL-USE plugin)',
+            handler: ({ params, body }) => server.control.setSpecialUse(params.path, body.specialUse)
+        }
+    ]);
 }

package/dist/esm/quirks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Quirk presets (#87): named sets of script rules (and plugins to leave out) that make the server behave like a known
+ * real server, so a client test reproduces the bug of that server in every run, without the server itself. The
+ * `quirks` option turns them on, the rules come after the rules of the `script` option. The probabilistic ones use
+ * the random numbers of the `scriptSeed` option, so a run can be repeated. The presets are exported as data, copy
+ * and adjust one as script rules when it does not fit
+ */
+import type { ScriptRule } from './script.js';
+/** A quirk preset */
+export interface Quirk {
+    description: string;
+    /** script rules, see README "Scripted faults" */
+    rules?: ScriptRule[] | undefined;
+    /** plugins that are not loaded even when the `plugins` option lists them */
+    removePlugins?: string[] | undefined;
+}
+export declare const quirks: Record<string, Quirk>;
+/**
+ * Resolves the `quirks` option
+ *
+ * @param {Array|String} names Quirk names
+ * @return {Object} `{ rules, removePlugins }` of all of them, removePlugins maps a plugin name to the quirk that removes it
+ * @throws {Error} for an unknown name
+ */
+export declare function resolveQuirks(names: string[] | string | null | undefined): {
+    rules: ScriptRule[];
+    removePlugins: Map<string, string>;
+};

package/dist/esm/quirks.js

@@ -0,0 +1,121 @@
+/**
+ * Quirk presets (#87): named sets of script rules (and plugins to leave out) that make the server behave like a known
+ * real server, so a client test reproduces the bug of that server in every run, without the server itself. The
+ * `quirks` option turns them on, the rules come after the rules of the `script` option. The probabilistic ones use
+ * the random numbers of the `scriptSeed` option, so a run can be repeated. The presets are exported as data, copy
+ * and adjust one as script rules when it does not fit
+ */
+const FETCH_COMMANDS = ['FETCH', 'UID FETCH'];
+/**
+ * The part a body section belongs to: "2.MIME", "2.HEADER" and "2" all belong to part 2, "HEADER" and "TEXT" to the
+ * message itself
+ *
+ * @param {Array} section Section of a BODY item, its first entry is the section spec
+ * @return {String} part path, "" for the message
+ */
+function partPath(section) {
+    const spec = String((section[0] && section[0].value) || '').toUpperCase();
+    return spec.replace(/(^|\.)(MIME|HEADER(\.FIELDS(\.NOT)?)?|TEXT)$/, '');
+}
+/**
+ * Changes the BODY[...] values of an untagged FETCH response
+ *
+ * @param {Object} response Untagged FETCH response
+ * @param {Function} change `(name, value, index)` returns the new value
+ * @return {Object|undefined} the changed response, nothing for other responses
+ */
+function changeBodyValues(response, change) {
+    const items = response.attributes && response.attributes[2];
+    if (!Array.isArray(items) || !response.attributes[1] || response.attributes[1].value !== 'FETCH') {
+        return undefined;
+    }
+    const changed = items.slice();
+    for (let i = 0; i < changed.length - 1; i += 2) {
+        const name = changed[i];
+        if (name && name.type === 'ATOM' && String(name.value).toUpperCase() === 'BODY' && Array.isArray(name.section)) {
+            changed[i + 1] = change(name, changed[i + 1]);
+        }
+    }
+    return Object.assign({}, response, { attributes: [response.attributes[0], response.attributes[1], changed] });
+}
+export const quirks = {
+    'james-fetchgroup': {
+        description: 'Apache James FetchGroup: only the first section asked for a part in one FETCH is answered, later ones for the same ' +
+            'part come back empty. BODY[2.MIME] BODY[2] gives a zero-length body, the reverse order loses the headers',
+        rules: [
+            {
+                on: 'response',
+                command: FETCH_COMMANDS,
+                untagged: true,
+                mutate: response => {
+                    const seen = new Set();
+                    return changeBodyValues(response, (name, value) => {
+                        const path = partPath(name.section);
+                        if (seen.has(path)) {
+                            return { type: 'LITERAL', value: '' };
+                        }
+                        seen.add(path);
+                        return value;
+                    });
+                }
+            }
+        ]
+    },
+    'james-late-fetch': {
+        description: 'Apache James: now and then (1 in 4) a FETCH response comes after the tagged OK of its command',
+        rules: [{ on: 'response', command: FETCH_COMMANDS, untagged: true, chance: 0.25, defer: 'tagged' }]
+    },
+    'yahoo-quoted-sections': {
+        description: 'Yahoo: short body sections (up to 100 octets without line breaks) are quoted strings instead of literals',
+        rules: [
+            {
+                on: 'response',
+                command: FETCH_COMMANDS,
+                untagged: true,
+                mutate: response => changeBodyValues(response, (name, value) => value && value.type === 'LITERAL' && typeof value.value === 'string' && value.value.length <= 100 && /^[\x20-\x7e]*$/.test(value.value)
+                    ? { type: 'STRING', value: value.value }
+                    : value)
+            }
+        ]
+    },
+    'm365-throttle': {
+        description: 'Microsoft 365: 1 in 10 commands (not LOGOUT) is refused with "BAD Request is throttled. Suggested Backoff Time: 1000 milliseconds"',
+        rules: [
+            {
+                on: 'command',
+                chance: 0.1,
+                when: context => context.command !== 'LOGOUT',
+                send: '$TAG BAD Request is throttled. Suggested Backoff Time: 1000 milliseconds\r\n'
+            }
+        ]
+    },
+    'no-uidplus': {
+        description: 'A server without UIDPLUS: no APPENDUID, COPYUID or UID EXPUNGE, even when the plugins list it',
+        removePlugins: ['UIDPLUS']
+    },
+    'no-move': {
+        description: 'A server without MOVE, clients have to COPY, STORE \\Deleted and EXPUNGE',
+        removePlugins: ['MOVE']
+    }
+};
+/**
+ * Resolves the `quirks` option
+ *
+ * @param {Array|String} names Quirk names
+ * @return {Object} `{ rules, removePlugins }` of all of them, removePlugins maps a plugin name to the quirk that removes it
+ * @throws {Error} for an unknown name
+ */
+export function resolveQuirks(names) {
+    const rules = [];
+    const removePlugins = new Map();
+    [].concat(names || []).forEach(name => {
+        const key = String(name).toLowerCase();
+        const quirk = Object.hasOwn(quirks, key) ? quirks[key] : null;
+        if (!quirk) {
+            throw new Error('Unknown quirk "' + name + '". Available quirks: ' + Object.keys(quirks).join(', '));
+        }
+        rules.push(...(quirk.rules || []));
+        (quirk.removePlugins || []).forEach(plugin => removePlugins.set(plugin, key));
+    });
+    return { rules, removePlugins };
+}

package/dist/esm/random.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Seeded random numbers, so that randomized test behavior (UID shuffles, script rule chances) can be repeated
+ */
+/**
+ * A small seeded random number generator (mulberry32), for repeatable "shuffle" orders
+ *
+ * @param {Number} seed Seed
+ * @return {Function} returns numbers from 0 (inclusive) to 1 (exclusive)
+ */
+export declare function seededRandom(seed: number): () => number;

package/dist/esm/random.js

@@ -0,0 +1,19 @@
+/**
+ * Seeded random numbers, so that randomized test behavior (UID shuffles, script rule chances) can be repeated
+ */
+/**
+ * A small seeded random number generator (mulberry32), for repeatable "shuffle" orders
+ *
+ * @param {Number} seed Seed
+ * @return {Function} returns numbers from 0 (inclusive) to 1 (exclusive)
+ */
+export function seededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/esm/rest.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+import http from 'node:http';
+import type { IMAPServer } from './types.js';
+import type { ControlRoute as Route } from './control.js';
+/** The HTTP server of the REST API, `endStreams()` ends the open event streams */
+type RestServer = http.Server & {
+    endStreams?: () => void;
+};
+/** Options of the REST API, the `rest` server option */
+interface RestOptions {
+    port?: number | undefined;
+    /** address to listen on, 127.0.0.1 by default. Any other than a loopback address needs a token */
+    host?: string | undefined;
+    /** bearer token that every request must send in `Authorization: Bearer <token>` */
+    token?: string | undefined;
+}
+/**
+ * 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
+ */
+declare function isLoopback(host: string): boolean;
+/**
+ * Builds the route table of a server
+ *
+ * @param {Object} server IMAP server
+ * @return {Array} routes
+ */
+declare function getRoutes(server: IMAPServer, streams?: Set<http.ServerResponse>): Route[];
+/**
+ * Describes the routes as an OpenAPI 3.1 document
+ *
+ * @param {Array} routes Route table
+ * @return {Object} OpenAPI document
+ */
+declare function openApi(routes: Route[]): Record<string, unknown>;
+/**
+ * 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
+ */
+declare function createRestServer(server: IMAPServer, options: RestOptions): RestServer;
+export { createRestServer, isLoopback, getRoutes, openApi };
+export type { RestOptions, RestServer };