domma-cms 0.55.1 → 0.69.3

package/plugins/_lib/mail/render.js

@@ -0,0 +1,291 @@
+/**
+ * Message rendering for the Mail Reader plugin.
+ *
+ * Email HTML is the most hostile content this CMS will ever display: it comes
+ * from strangers, it is full of tracking, and a good deal of it is actively
+ * trying to do something. Three layers stand between it and the admin:
+ *
+ *   1. sanitize-html strips scripts, styles, frames, forms and event handlers.
+ *   2. Remote images are neutered unless the reader explicitly asks for them,
+ *      because loading one tells the sender the mail was opened, and by whom.
+ *   3. The result is handed to a sandboxed iframe (see admin/views/mail.js)
+ *      with neither `allow-scripts` nor `allow-same-origin`, so even a hole in
+ *      the first two layers has no origin to abuse.
+ *
+ * The CSP meta below is a fourth layer that costs nothing. None of these are
+ * individually sufficient, which is the point.
+ *
+ * @module mail-reader/services/render
+ */
+import sanitizeHtml from 'sanitize-html';
+
+/** A 1x1 transparent GIF - stands in for a blocked remote image. */
+const BLOCKED_PIXEL = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
+
+/**
+ * Tags worth keeping in a mail body. Everything absent from this list is
+ * unwrapped or dropped by sanitize-html.
+ */
+const ALLOWED_TAGS = [
+    'a', 'b', 'blockquote', 'br', 'caption', 'code', 'col', 'colgroup', 'dd', 'div', 'dl', 'dt',
+    'em', 'figcaption', 'figure', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img', 'li',
+    'ol', 'p', 'pre', 'q', 's', 'small', 'span', 'strike', 'strong', 'sub', 'sup', 'table',
+    'tbody', 'td', 'tfoot', 'th', 'thead', 'tr', 'u', 'ul'
+];
+
+/**
+ * Build a cid → data URI map from a parsed message's inline attachments.
+ *
+ * Inline images are embedded rather than served from a route: they are already
+ * in memory, they are usually small, and a route would mean a second
+ * authenticated round trip per image.
+ *
+ * @param   {object[]} attachments
+ * @param   {number} maxBytes - per-image ceiling; larger ones are left blocked
+ * @returns {Map<string, string>}
+ */
+function inlineImageMap(attachments, maxBytes) {
+    const map = new Map();
+    for (const attachment of attachments ?? []) {
+        if (!attachment.cid || !attachment.content) continue;
+        if (!String(attachment.contentType ?? '').startsWith('image/')) continue;
+        if (attachment.content.length > maxBytes) continue;
+        map.set(attachment.cid, `data:${attachment.contentType};base64,${attachment.content.toString('base64')}`);
+    }
+    return map;
+}
+
+/**
+ * Sanitise a mail body and rewrite its images and links.
+ *
+ * @param   {string} html
+ * @param   {{allowRemoteImages: boolean, inlineImages: Map<string, string>}} options
+ * @returns {{html: string, blockedImages: number}}
+ */
+function sanitiseBody(html, options) {
+    let blockedImages = 0;
+
+    const clean = sanitizeHtml(html, {
+        allowedTags: ALLOWED_TAGS,
+        allowedAttributes: {
+            // target/rel are added by transformTags below, and attribute
+            // filtering runs AFTER that - leave them off this list and the
+            // rel we just set is stripped straight back off again.
+            a: ['href', 'title', 'target', 'rel'],
+            img: ['src', 'alt', 'title', 'width', 'height', 'data-blocked-src'],
+            td: ['colspan', 'rowspan', 'align', 'valign'],
+            th: ['colspan', 'rowspan', 'align', 'valign'],
+            table: ['width', 'align'],
+            '*': ['style']
+        },
+        // Inline styles are what makes mail readable, so they stay - but only
+        // properties that cannot position, load or overlay anything.
+        allowedStyles: {
+            '*': {
+                'color': [/^.*$/],
+                'background-color': [/^.*$/],
+                'font-size': [/^.*$/],
+                'font-weight': [/^.*$/],
+                'font-style': [/^.*$/],
+                'font-family': [/^.*$/],
+                'text-align': [/^.*$/],
+                'text-decoration': [/^.*$/],
+                'padding': [/^.*$/],
+                'padding-top': [/^.*$/],
+                'padding-bottom': [/^.*$/],
+                'padding-left': [/^.*$/],
+                'padding-right': [/^.*$/],
+                'margin': [/^.*$/],
+                'border': [/^.*$/],
+                'border-collapse': [/^.*$/],
+                'width': [/^.*$/],
+                'max-width': [/^.*$/]
+            }
+        },
+        allowedSchemes: ['http', 'https', 'mailto', 'tel'],
+        allowedSchemesByTag: {img: ['http', 'https', 'data', 'cid']},
+        // Anything not on the tag list loses its markup but keeps its text,
+        // except these, where the text is machinery rather than content.
+        nonTextTags: ['style', 'script', 'textarea', 'option', 'noscript', 'title', 'head'],
+        transformTags: {
+            a: (tagName, attribs) => ({
+                tagName: 'a',
+                attribs: {
+                    ...attribs,
+                    target: '_blank',
+                    rel: 'noopener noreferrer nofollow'
+                }
+            }),
+            img: (tagName, attribs) => {
+                const src = attribs.src ?? '';
+
+                if (src.startsWith('cid:')) {
+                    const resolved = options.inlineImages.get(src.slice(4));
+                    if (resolved) return {tagName: 'img', attribs: {...attribs, src: resolved}};
+                    blockedImages += 1;
+                    return {tagName: 'img', attribs: {...attribs, src: BLOCKED_PIXEL}};
+                }
+
+                if (src.startsWith('data:image/')) {
+                    return {tagName: 'img', attribs};
+                }
+
+                if (!options.allowRemoteImages) {
+                    blockedImages += 1;
+                    return {
+                        tagName: 'img',
+                        attribs: {...attribs, src: BLOCKED_PIXEL, 'data-blocked-src': src}
+                    };
+                }
+
+                return {tagName: 'img', attribs};
+            }
+        }
+    });
+
+    return {html: clean, blockedImages};
+}
+
+/**
+ * Escape text for safe interpolation into HTML.
+ *
+ * @param   {string} value
+ * @returns {string}
+ */
+function escapeHtml(value) {
+    return String(value)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+/**
+ * Wrap a sanitised body in a self-contained document for iframe srcdoc.
+ *
+ * The stylesheet is ours, not the message's, and deliberately minimal: it sets
+ * a readable default and stops wide tables blowing out the pane. Mail that
+ * relies on its own layout still renders, because its inline styles survived.
+ *
+ * @param   {string} bodyHtml
+ * @returns {string}
+ */
+function wrapDocument(bodyHtml) {
+    return `<!DOCTYPE html>
+<html><head>
+<meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src data: http: https:; style-src 'unsafe-inline'; font-src data:;">
+<base target="_blank">
+<style>
+  html, body { margin: 0; padding: 16px; }
+  body {
+    font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    color: #1a1a1a; background: #ffffff; word-wrap: break-word;
+  }
+  img { max-width: 100%; height: auto; }
+  table { max-width: 100%; }
+  pre { white-space: pre-wrap; }
+  blockquote {
+    margin: 0 0 0 8px; padding-left: 12px;
+    border-left: 3px solid #d0d0d0; color: #555;
+  }
+</style>
+</head><body>${bodyHtml}</body></html>`;
+}
+
+/**
+ * Sanitise a fragment of someone else's HTML for inclusion in our own.
+ *
+ * Used when quoting a message into a reply: the original's formatting is
+ * worth keeping, its scripts and styles are not. The same rules as the reader
+ * uses, minus the document wrapper, and with remote images dropped rather
+ * than blocked - a quote should not carry a tracking pixel onward to
+ * everybody on the reply.
+ *
+ * @param   {string} html
+ * @returns {string}
+ */
+export function sanitiseFragment(html) {
+    const {html: clean} = sanitiseBody(String(html ?? ''), {
+        allowRemoteImages: false,
+        inlineImages: new Map()
+    });
+    // The blocked-image placeholders are meaningful in a reader and just
+    // clutter in a quote.
+    return clean.replace(/<img[^>]*data-blocked-src[^>]*>/gi, '');
+}
+
+/**
+ * Sanitise a signature the mailbox owner wrote.
+ *
+ * The same allowlist the reader and the quote use, with remote images ALLOWED
+ * - which is the one thing that separates it from `sanitiseFragment`. A
+ * blocked image in an incoming message is a tracking pixel defused; a blocked
+ * image in your own signature is your company logo missing from every message
+ * you send.
+ *
+ * Applied on save rather than on send, so the stored copy is the safe one:
+ * this HTML is handed back to the settings editor as well as pushed out to
+ * recipients, and a sanitiser that only ran on the way out would leave the
+ * admin rendering whatever was stored.
+ *
+ * @param   {string} html
+ * @returns {string}
+ */
+export function sanitiseSignature(html) {
+    const {html: clean} = sanitiseBody(String(html ?? ''), {
+        allowRemoteImages: true,
+        inlineImages: new Map()
+    });
+    return clean;
+}
+
+/**
+ * Turn a parsed message into everything the reader pane needs.
+ *
+ * @param   {object} parsed - output of mailparser's simpleParser
+ * @param   {{allowRemoteImages: boolean, inlineImageMaxBytes: number}} options
+ * @returns {{document: string, blockedImages: number, isHtml: boolean}}
+ */
+export function renderBody(parsed, options) {
+    const inlineImages = inlineImageMap(parsed.attachments, options.inlineImageMaxBytes);
+
+    if (parsed.html) {
+        const {html, blockedImages} = sanitiseBody(parsed.html, {
+            allowRemoteImages: options.allowRemoteImages,
+            inlineImages
+        });
+        return {document: wrapDocument(html), blockedImages, isHtml: true};
+    }
+
+    // Plain-text mail: escape it and keep its line breaks. mailparser offers
+    // textAsHtml, but it is not sanitised, so it goes through the same path.
+    const text = parsed.text ?? '';
+    const {html} = sanitiseBody(`<pre>${escapeHtml(text)}</pre>`, {
+        allowRemoteImages: options.allowRemoteImages,
+        inlineImages
+    });
+    return {document: wrapDocument(html), blockedImages: 0, isHtml: false};
+}
+
+/**
+ * Summarise a message's attachments for the reader pane.
+ *
+ * Inline images that were embedded in the body are excluded - listing them
+ * as downloads when they are already visible is just noise.
+ *
+ * @param   {object[]} attachments
+ * @returns {{index: number, filename: string, contentType: string, size: number}[]}
+ */
+export function listAttachments(attachments) {
+    return (attachments ?? [])
+        .map((attachment, index) => ({attachment, index}))
+        .filter(({attachment}) => attachment.contentDisposition !== 'inline' || !attachment.cid)
+        .map(({attachment, index}) => ({
+            index,
+            filename: attachment.filename || `attachment-${index + 1}`,
+            contentType: attachment.contentType || 'application/octet-stream',
+            size: attachment.size ?? attachment.content?.length ?? 0
+        }));
+}

package/plugins/_lib/mail/ruleRunner.js

@@ -0,0 +1,152 @@
+/**
+ * Carrying out what the rules decided.
+ *
+ * The decision is `planActions()` in `_lib/admin/mail/rules.js`, which is pure
+ * and knows nothing about IMAP. This is the half that talks to the server.
+ * Splitting them is what makes a rule testable without a mailbox, and what
+ * lets the settings screen preview a rule against real messages using exactly
+ * the code that will run it.
+ *
+ * ## Only new mail, ever
+ *
+ * Two guards, both necessary, because getting this wrong means silently
+ * refiling somebody's archive:
+ *
+ *   1. Rules run only over messages a sync pass has just ADDED, and never
+ *      during a full resync - a UIDVALIDITY change re-adds the entire folder,
+ *      and that is not new mail arriving, it is the same mail being
+ *      re-fetched.
+ *   2. Messages older than `rulesFrom` - stamped the first time rules were
+ *      saved - are skipped even if they were just added, which covers a
+ *      folder being mirrored for the first time.
+ *
+ * Neither guard alone is enough, and the cost of both is a comparison.
+ *
+ * @module _lib/mail/ruleRunner
+ */
+import {planActions} from '../admin/mail/rules.js';
+import {
+    deleteMessage,
+    findJunkFolder,
+    JUNK_KEYWORD,
+    moveMessage
+} from './write.js';
+
+/**
+ * Which of a folder's newly added messages the rules may touch.
+ *
+ * @param   {object[]} messages
+ * @param   {{mode: string}} sync - the sync result for that folder
+ * @param   {string|null} since - ISO timestamp, or null for no floor
+ * @returns {object[]}
+ */
+export function eligible(messages, sync, since) {
+    // A full resync is the whole folder arriving again, not new mail.
+    if (sync?.mode === 'full') return [];
+
+    const floor = since ? new Date(since).getTime() : null;
+    return (messages ?? []).filter(message => {
+        if (floor === null) return true;
+        const date = new Date(String(message?.date ?? '')).getTime();
+        // A message with no date at all is treated as new. The alternative is
+        // skipping it forever, and an undated message is far more often a
+        // quirk of the sending client than an archive.
+        return !Number.isFinite(date) || date >= floor;
+    });
+}
+
+/**
+ * Run the rules over one folder's new mail.
+ *
+ * Must be called with NO mailbox lock held. Moving a message opens its own
+ * mailbox on the same connection, and ImapFlow queues mailbox locks per
+ * client - so calling this from inside the sync's `withMailbox` would wait
+ * for a lock that is only released when the caller returns.
+ *
+ * Each message is handled independently and failures are collected rather
+ * than thrown: one message that has already been moved by another client must
+ * not stop the rest of the folder being filed.
+ *
+ * @param   {{pool: object, store: object|null, account: object, poolKey: string,
+ *            connection: object, folder: string, messages: object[], rules: object[]}} deps
+ * @returns {Promise<{considered: number, acted: number, moved: number, errors: string[]}>}
+ */
+export async function applyRules({
+    pool, store, account, poolKey, connection, folder, messages, rules
+}) {
+    const report = {considered: messages?.length ?? 0, acted: 0, moved: 0, errors: []};
+    if (!report.considered || !(rules ?? []).length) return report;
+
+    // Resolved once for the whole pass rather than per message: it is a LIST
+    // round trip, and a folder of newsletters would otherwise make one per
+    // message.
+    let junk;
+
+    for (const message of messages) {
+        const {actions} = planActions(rules, message);
+        if (!actions.length) continue;
+
+        try {
+            // Flags first, destination last. A message that is moved has a new
+            // UID in its new home, so anything flagged afterwards would be
+            // flagging a UID that no longer exists here.
+            const add = [];
+            for (const action of actions) {
+                if (action.type === 'markRead') add.push('\\Seen');
+                if (action.type === 'flag') add.push('\\Flagged');
+                if (action.type === 'junk') add.push(JUNK_KEYWORD);
+            }
+
+            if (add.length) {
+                await pool.withMailbox(poolKey, connection, folder, client =>
+                    client.messageFlagsAdd({uid: String(message.uid)}, add, {uid: true}),
+                {writable: true});
+            }
+
+            const copy = actions.find(a => a.type === 'copy');
+            if (copy) {
+                await pool.withMailbox(poolKey, connection, folder, client =>
+                    client.messageCopy({uid: String(message.uid)}, copy.folder, {uid: true}),
+                {writable: true});
+            }
+
+            const destination = actions.find(a => ['move', 'junk', 'delete'].includes(a.type));
+            if (destination) {
+                if (destination.type === 'delete') {
+                    await deleteMessage({
+                        pool, store, account, poolKey, connection, folder, uid: message.uid
+                    });
+                } else {
+                    if (destination.type === 'junk' && junk === undefined) {
+                        junk = await findJunkFolder(pool, poolKey, connection);
+                    }
+                    const target = destination.type === 'junk' ? junk : destination.folder;
+                    // A junk action on a server with no junk folder still
+                    // marked the message; there is simply nowhere to put it,
+                    // which is better than inventing a folder name.
+                    if (target && target !== folder) {
+                        await moveMessage({
+                            pool, store, account, poolKey, connection,
+                            folder, uid: message.uid, destination: target
+                        });
+                        report.moved += 1;
+                    }
+                }
+            } else if (add.length && store) {
+                // Flagged in place: the mirror row is still ours to correct,
+                // and leaving it stale means the list shows unread mail that
+                // a rule has just read.
+                await store.setFlags(account.id, folder, [{
+                    uid: message.uid,
+                    flags: [...new Set([...(message.flags ?? []), ...add])]
+                }]);
+            }
+
+            report.acted += 1;
+        } catch (err) {
+            report.errors.push(`uid ${message.uid}: ${err.message}`);
+        }
+    }
+
+    return report;
+}

package/plugins/_lib/mail/scheduler.js

@@ -0,0 +1,254 @@
+/**
+ * The worker behind "send later", "undo send" and "snooze".
+ *
+ * One ticker, two queues, for the same reason the poller is one ticker rather
+ * than a timer per mailbox: the work is small, the queues are short, and a
+ * timer per queued message is a timer to cancel when the message is cancelled.
+ *
+ * ## Why a queue at all, for a ten second undo
+ *
+ * Holding a message in memory for ten seconds would be simpler and would lose
+ * mail. A restart during the hold - a deploy, a crash, `pm2 reload` - takes
+ * the only copy with it, and the sender has already been told it is on its
+ * way. Everything that has been accepted from a person is durable before they
+ * are told it was accepted.
+ *
+ * ## Sent exactly once
+ *
+ * The claim is a conditional update in the store (`claimDueSends`), so a tick
+ * that overruns into the next one cannot pick the same message up twice.
+ * Everything after the claim is best-effort and reported; the claim itself is
+ * the part that must be exact, because a duplicate message cannot be recalled.
+ *
+ * @module _lib/mail/scheduler
+ */
+import * as accounts from './accounts.js';
+import {sendMessage} from './send.js';
+
+/** How often the ticker looks for work. */
+const TICK_MS = 5_000;
+
+/**
+ * How many times a queued send is retried before it is given up on.
+ *
+ * A mail server that is briefly unreachable should not lose the message; one
+ * that refuses it should not be asked forever. Three is enough for the first
+ * and few enough for the second.
+ */
+const MAX_ATTEMPTS = 3;
+
+/** How long to wait before trying a failed send again. */
+const RETRY_MS = 120_000;
+
+/**
+ * Create the scheduler.
+ *
+ * @param   {{store: object, pool: object, config: object, logger: object,
+ *            tickMs?: number}} deps
+ * @returns {{start: Function, stop: Function, runNow: Function}}
+ */
+export function createScheduler({store, pool, config, logger, tickMs = TICK_MS}) {
+    let timer = null;
+    let stopped = false;
+    let running = false;
+
+    /**
+     * Send one claimed message.
+     *
+     * @param   {object} item
+     * @returns {Promise<void>}
+     */
+    async function runSend(item) {
+        const account = await accounts.getAccount(item.userId, item.accountId);
+        if (!account) {
+            // The mailbox was removed while this was queued. There is nothing
+            // to send it from and never will be.
+            await store.finishSend(item._id, {
+                status: 'failed',
+                error: 'That mailbox no longer exists.'
+            });
+            return;
+        }
+
+        const smtp = accounts.toSmtpConnection(account, item.identityId ?? null);
+        if (!smtp) {
+            await store.finishSend(item._id, {
+                status: 'failed',
+                error: 'No outgoing server is configured for this mailbox.'
+            });
+            return;
+        }
+
+        try {
+            const result = await sendMessage({
+                smtp,
+                draft: item.draft,
+                pool,
+                poolKey: `${item.userId}:${item.accountId}`,
+                connection: accounts.toConnection(account),
+                sentFolder: smtp.sentFolder,
+                allowInsecureTLS: config.allowInsecureTLS === true,
+                replaces: item.replaces ?? null
+            });
+            await store.finishSend(item._id, {status: 'sent', result, error: null});
+        } catch (err) {
+            const giveUp = (item.attempts ?? 1) >= MAX_ATTEMPTS;
+            await store.finishSend(item._id, giveUp
+                ? {status: 'failed', error: err.message}
+                // Back to pending, a little later. `finishedAt` is set either
+                // way, which is harmless on a retry and is what tells a
+                // screen when the last attempt was.
+                : {status: 'pending', at: new Date(Date.now() + RETRY_MS), error: err.message});
+
+            logger.warn(
+                `[mail] queued send ${item._id} failed (attempt ${item.attempts}): ${err.message}`
+            );
+        }
+    }
+
+    /**
+     * Bring one snoozed message back.
+     *
+     * Moved back where it came from and marked unread, because the whole
+     * point of putting it away was to be shown it again - a message that
+     * returns already read returns invisibly.
+     *
+     * @param   {object} item
+     * @returns {Promise<void>}
+     */
+    async function runWake(item) {
+        const account = await accounts.getAccount(item.userId, item.accountId);
+        if (!account) {
+            await store.finishSnooze(item._id, {status: 'failed', error: 'That mailbox no longer exists.'});
+            return;
+        }
+
+        const poolKey = `${item.userId}:${item.accountId}`;
+        const connection = accounts.toConnection(account);
+
+        try {
+            // The UID the move reported, when the server has UIDPLUS. Without
+            // it the message is found by its Message-ID instead - a snooze on
+            // such a server is still a snooze, and refusing to bring it back
+            // would be losing the message rather than delaying it.
+            const uid = item.uid ?? await findByMessageId(poolKey, connection, item);
+            if (uid === null) {
+                throw new Error('That message is no longer in the snooze folder.');
+            }
+
+            // Unread first, then moved. The other order would be flagging a
+            // UID that has just stopped existing in this folder.
+            await pool.withMailbox(poolKey, connection, item.folder, client =>
+                client.messageFlagsRemove({uid: String(uid)}, ['\\Seen'], {uid: true}),
+            {writable: true});
+
+            const {moveMessage} = await import('./write.js');
+            const moved = await moveMessage({
+                pool, store, account, poolKey, connection,
+                folder: item.folder, uid, destination: item.returnTo
+            });
+
+            await store.finishSnooze(item._id, {
+                status: 'woken', error: null, newUid: moved.newUid ?? null
+            });
+        } catch (err) {
+            // Retried, not given up on. A mail server that is briefly
+            // unreachable is an ordinary condition, and a snooze abandoned on
+            // the first blip leaves the message parked in a folder the user
+            // does not read, absent from the list that was supposed to bring
+            // it back.
+            const attempts = (item.attempts ?? 0) + 1;
+            const giveUp = attempts >= MAX_ATTEMPTS;
+            await store.finishSnooze(item._id, giveUp
+                ? {status: 'failed', error: err.message, attempts}
+                : {status: 'pending', at: new Date(Date.now() + RETRY_MS), error: err.message, attempts});
+            logger.warn(
+                `[mail] could not wake snoozed message ${item._id} (attempt ${attempts}): ${err.message}`
+            );
+        }
+    }
+
+    /**
+     * Find a parked message by its Message-ID.
+     *
+     * The way back on a server with no UIDPLUS, which cannot report the UID a
+     * moved message was given. A HEADER search is not fast, but the snooze
+     * folder holds only what is waiting, and this runs once per message when
+     * it comes due.
+     *
+     * @param   {string} poolKey
+     * @param   {object} connection
+     * @param   {object} item
+     * @returns {Promise<number|null>}
+     */
+    async function findByMessageId(poolKey, connection, item) {
+        if (!item.messageId) return null;
+        return pool.withMailbox(poolKey, connection, item.folder, async (client) => {
+            const found = await client.search({header: {'message-id': item.messageId}}, {uid: true});
+            // The newest match, in the vanishingly unlikely case a folder
+            // holds two messages with one id.
+            return found?.length ? Number(found[found.length - 1]) : null;
+        });
+    }
+
+    /**
+     * One pass over both queues.
+     *
+     * Guarded against overlapping itself: a slow mail server can make a send
+     * take longer than the tick interval, and a second pass starting
+     * underneath the first would double the connections without doubling the
+     * throughput.
+     *
+     * @returns {Promise<void>}
+     */
+    async function tick() {
+        if (stopped || running) return;
+        running = true;
+        try {
+            for (const item of await store.claimDueSends()) {
+                if (stopped) return;
+                await runSend(item);
+            }
+            for (const item of await store.claimDueSnoozes()) {
+                if (stopped) return;
+                await runWake(item);
+            }
+        } catch (err) {
+            // The store being unreachable is an ordinary condition here -
+            // Mongo restarting, say - and the next tick will try again.
+            logger.warn(`[mail] scheduler tick failed: ${err.message}`);
+        } finally {
+            running = false;
+        }
+    }
+
+    return {
+        /**
+         * @returns {void}
+         */
+        start() {
+            if (timer) return;
+            stopped = false;
+            timer = setInterval(() => {
+                tick().catch(err => logger.warn(`[mail] scheduler tick failed: ${err.message}`));
+            }, tickMs);
+            timer.unref?.();
+        },
+
+        /**
+         * @returns {void}
+         */
+        stop() {
+            stopped = true;
+            if (timer) clearInterval(timer);
+            timer = null;
+        },
+
+        /**
+         * Run a pass immediately - used by "send it now" on a queued message.
+         *
+         * @returns {Promise<void>}
+         */
+        runNow: tick
+    };
+}