domma-cms 0.55.1 → 0.66.0

package/plugins/_lib/admin/mail/resizable.js

@@ -0,0 +1,26 @@
+/**
+ * The mail reader's resizable slideovers.
+ *
+ * The behaviour is generic and lives in `_lib/admin/ui/resizable.js`; this
+ * supplies the handle class mail.css styles and keeps the import path every
+ * mail module already uses.
+ *
+ * The inner import carries this module's own `?v=` token: a static import
+ * would be fetched unversioned and served from cache for as long as the
+ * browser felt like it, which is exactly the staleness the token exists to
+ * prevent.
+ *
+ * @module _lib/admin/mail/resizable
+ */
+
+const ASSET_VERSION = new URL(import.meta.url).searchParams.get('v') ?? '1';
+const {makeResizable: resize} = await import(`../ui/resizable.js?v=${ASSET_VERSION}`);
+
+/**
+ * @param   {object} slideover - a Domma slideover instance
+ * @param   {{storageKey: string, defaultWidth?: number}} options
+ * @returns {() => void} a teardown for the listeners this adds
+ */
+export function makeResizable(slideover, options) {
+    return resize(slideover, {handleClass: 'mail-slideover-resizer', ...options});
+}

package/plugins/_lib/admin/mail/rules.js

@@ -0,0 +1,343 @@
+/**
+ * Filing rules.
+ *
+ * What a mail client is actually for, once the mailbox is bigger than a day's
+ * reading: mail that files itself. A rule is a set of conditions and a set of
+ * actions, evaluated against the envelope the mirror already holds, so no
+ * extra fetch is needed to decide what to do with a message.
+ *
+ * ## Pure, and browser-side too
+ *
+ * The same module the settings screen uses to describe the vocabulary and to
+ * preview what a rule would have caught. Evaluating a draft rule against the
+ * last few hundred messages, in the browser, before saving it, is the
+ * difference between a rules feature people trust and one they try once.
+ *
+ * See the placement note at the top of `identity.js` for why this is under
+ * `admin/` rather than beside the sync engine that runs it.
+ *
+ * ## No regular expressions
+ *
+ * `matches` is a wildcard, not a regex. A stored regex is a pattern someone
+ * else's CPU evaluates on every message that arrives, which is a denial of
+ * service waiting for a nested quantifier, and `*@example.com` is what people
+ * actually mean when they reach for one anyway.
+ *
+ * @module _lib/admin/mail/rules
+ */
+
+/** How many rules one mailbox may hold. */
+export const MAX_RULES = 50;
+
+/** How many conditions or actions one rule may hold. */
+export const MAX_CLAUSES = 10;
+
+/**
+ * The parts of a message a rule can look at.
+ *
+ * Only what the mirror stores. There is deliberately no `body` - the store
+ * holds envelopes and never message text, and a rule that needed the body
+ * would mean downloading every message to decide whether to file it.
+ */
+export const RULE_FIELDS = [
+    {field: 'from', label: 'Sender', kind: 'address'},
+    {field: 'to', label: 'Recipient', kind: 'address'},
+    {field: 'subject', label: 'Subject', kind: 'text'},
+    {field: 'list', label: 'Mailing list', kind: 'text'},
+    {field: 'hasAttachment', label: 'Has an attachment', kind: 'boolean'},
+    {field: 'priority', label: 'Priority', kind: 'text'},
+    {field: 'size', label: 'Size in KB', kind: 'number'}
+];
+
+/** How a field is compared, and which kinds of field each one suits. */
+export const RULE_OPS = [
+    {op: 'contains', label: 'contains', kinds: ['address', 'text']},
+    {op: 'notContains', label: 'does not contain', kinds: ['address', 'text']},
+    {op: 'equals', label: 'is exactly', kinds: ['address', 'text']},
+    {op: 'startsWith', label: 'starts with', kinds: ['address', 'text']},
+    {op: 'endsWith', label: 'ends with', kinds: ['address', 'text']},
+    {op: 'matches', label: 'matches (use * as a wildcard)', kinds: ['address', 'text']},
+    {op: 'isTrue', label: 'is true', kinds: ['boolean']},
+    {op: 'isFalse', label: 'is false', kinds: ['boolean']},
+    {op: 'greaterThan', label: 'is more than', kinds: ['number']},
+    {op: 'lessThan', label: 'is less than', kinds: ['number']}
+];
+
+/**
+ * What a rule can do to a message.
+ *
+ * `delete` moves to Trash rather than expunging. A rule that silently
+ * destroyed mail would be the one feature in this plugin capable of losing
+ * something that cannot be got back, and a misplaced condition is exactly
+ * the kind of mistake people make while learning rules.
+ */
+export const RULE_ACTIONS = [
+    {type: 'move', label: 'Move to folder', needs: 'folder'},
+    {type: 'copy', label: 'Copy to folder', needs: 'folder'},
+    {type: 'markRead', label: 'Mark as read', needs: null},
+    {type: 'flag', label: 'Flag it', needs: null},
+    {type: 'junk', label: 'Treat as spam', needs: null},
+    {type: 'delete', label: 'Move to Trash', needs: null},
+    {type: 'stop', label: 'Stop processing further rules', needs: null}
+];
+
+/** The field kinds, by field name, for validating an op against a field. */
+const KIND_OF = Object.fromEntries(RULE_FIELDS.map(f => [f.field, f.kind]));
+
+/** The ops that take no value at all. */
+const VALUELESS = new Set(['isTrue', 'isFalse']);
+
+/**
+ * Turn a wildcard pattern into a regular expression.
+ *
+ * Everything is escaped except `*` and `?`, so the pattern cannot smuggle in
+ * a quantifier. `*` and `?` themselves compile to `.*` and `.`, neither of
+ * which can backtrack catastrophically against the other.
+ *
+ * @param   {string} pattern
+ * @returns {RegExp}
+ */
+function wildcard(pattern) {
+    const escaped = String(pattern ?? '')
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '\u0000')
+        .replace(/\?/g, '\u0001')
+        .replace(/\u0000/g, '.*')
+        .replace(/\u0001/g, '.');
+    return new RegExp(`^${escaped}$`, 'i');
+}
+
+/**
+ * A message field as the text a condition is tested against.
+ *
+ * Address lists become "Name <address>" joined by spaces, so one condition
+ * can match either half without the author having to know which they meant.
+ *
+ * @param   {object} message - a mirror record
+ * @param   {string} field
+ * @returns {string|boolean|number}
+ */
+export function fieldValue(message, field) {
+    const addresses = list => (list ?? [])
+        .map(a => [a?.name, a?.address].filter(Boolean).join(' '))
+        .join(' ');
+
+    switch (field) {
+        case 'from': return addresses(message?.from);
+        case 'to': return addresses(message?.to);
+        case 'subject': return String(message?.subject ?? '');
+        case 'list': return String(message?.listId ?? '');
+        case 'hasAttachment': return Boolean(message?.hasAttachment);
+        case 'priority': return String(message?.priority ?? 'normal');
+        // Stored in bytes, asked about in kilobytes. Nobody writes a rule
+        // about 5242880.
+        case 'size': return Math.round(Number(message?.size ?? 0) / 1024);
+        default: return '';
+    }
+}
+
+/**
+ * Does one condition hold?
+ *
+ * @param   {{field: string, op: string, value: string}} condition
+ * @param   {object} message
+ * @returns {boolean}
+ */
+export function conditionHolds(condition, message) {
+    const actual = fieldValue(message, condition?.field);
+    const op = condition?.op;
+    const wanted = condition?.value;
+
+    if (op === 'isTrue') return actual === true;
+    if (op === 'isFalse') return actual === false;
+
+    if (op === 'greaterThan') return Number(actual) > Number(wanted);
+    if (op === 'lessThan') return Number(actual) < Number(wanted);
+
+    const haystack = String(actual).toLowerCase();
+    const needle = String(wanted ?? '').trim().toLowerCase();
+    // An empty needle would make `contains` true for everything, which is a
+    // half-written rule filing the whole inbox. Treated as "does not hold"
+    // so an unfinished condition is inert rather than catastrophic.
+    if (!needle) return false;
+
+    switch (op) {
+        case 'contains': return haystack.includes(needle);
+        case 'notContains': return !haystack.includes(needle);
+        case 'equals': return haystack === needle;
+        case 'startsWith': return haystack.startsWith(needle);
+        case 'endsWith': return haystack.endsWith(needle);
+        case 'matches': return wildcard(needle).test(haystack);
+        default: return false;
+    }
+}
+
+/**
+ * Put a stored rule into shape.
+ *
+ * @param   {object} input
+ * @param   {number} index
+ * @returns {object}
+ */
+export function normaliseRule(input, index = 0) {
+    const source = input && typeof input === 'object' ? input : {};
+
+    const conditions = (Array.isArray(source.conditions) ? source.conditions : [])
+        .slice(0, MAX_CLAUSES)
+        .map(condition => {
+            const field = KIND_OF[condition?.field] ? condition.field : 'from';
+            const kind = KIND_OF[field];
+            const allowed = RULE_OPS.filter(o => o.kinds.includes(kind)).map(o => o.op);
+            const op = allowed.includes(condition?.op) ? condition.op : allowed[0];
+            return {
+                field,
+                op,
+                value: VALUELESS.has(op) ? '' : String(condition?.value ?? '').slice(0, 500)
+            };
+        })
+        .filter(Boolean);
+
+    const known = new Set(RULE_ACTIONS.map(a => a.type));
+    const needsFolder = new Set(RULE_ACTIONS.filter(a => a.needs === 'folder').map(a => a.type));
+    const actions = (Array.isArray(source.actions) ? source.actions : [])
+        .slice(0, MAX_CLAUSES)
+        .filter(action => known.has(action?.type))
+        .map(action => ({
+            type: action.type,
+            folder: needsFolder.has(action.type) ? String(action.folder ?? '').slice(0, 500) : ''
+        }))
+        // An action that needs a destination and has none does nothing but
+        // look configured. Dropped rather than kept, so what is stored is
+        // what will happen.
+        .filter(action => !needsFolder.has(action.type) || action.folder);
+
+    return {
+        id: typeof source.id === 'string' && source.id.trim()
+            ? source.id.trim()
+            : `rule-${Math.random().toString(36).slice(2, 10)}${Date.now().toString(36).slice(-4)}`,
+        name: String(source.name ?? '').replace(/[\r\n]+/g, ' ').trim() || `Rule ${index + 1}`,
+        enabled: source.enabled !== false,
+        match: source.match === 'any' ? 'any' : 'all',
+        conditions,
+        actions
+    };
+}
+
+/**
+ * Every rule a mailbox holds, in the order they run.
+ *
+ * @param   {object|null|undefined} account
+ * @returns {object[]}
+ */
+export function normaliseRules(account) {
+    const source = account && typeof account === 'object' ? account : {};
+    const raw = Array.isArray(source.rules) ? source.rules : [];
+    const list = raw.slice(0, MAX_RULES).map(normaliseRule);
+
+    const seen = new Set();
+    for (const entry of list) {
+        while (seen.has(entry.id)) {
+            entry.id = `rule-${Math.random().toString(36).slice(2, 10)}${Date.now().toString(36).slice(-4)}`;
+        }
+        seen.add(entry.id);
+    }
+    return list;
+}
+
+/**
+ * Does this rule apply to this message?
+ *
+ * A rule with no conditions never matches. "Everything" is a legitimate thing
+ * to want and an illegitimate thing to arrive at by leaving a form blank.
+ *
+ * @param   {object} rule
+ * @param   {object} message
+ * @returns {boolean}
+ */
+export function ruleMatches(rule, message) {
+    if (!rule?.enabled) return false;
+    const conditions = rule.conditions ?? [];
+    if (!conditions.length) return false;
+
+    return rule.match === 'any'
+        ? conditions.some(condition => conditionHolds(condition, message))
+        : conditions.every(condition => conditionHolds(condition, message));
+}
+
+/**
+ * What the rules, run in order, decide about one message.
+ *
+ * Returns the actions to carry out rather than carrying them out: this module
+ * knows nothing about IMAP, which is what makes the decision testable without
+ * a mail server. The caller applies them.
+ *
+ * Conflicts are resolved by order, not by merging. A message moved twice ends
+ * up wherever the LAST move said, because that is what "rules run in order"
+ * means everywhere else that has rules, and a rule list that quietly
+ * reordered itself would be impossible to reason about.
+ *
+ * @param   {object[]} rules
+ * @param   {object} message
+ * @returns {{actions: object[], matched: string[]}}
+ */
+export function planActions(rules, message) {
+    const actions = [];
+    const matched = [];
+
+    for (const rule of rules ?? []) {
+        if (!ruleMatches(rule, message)) continue;
+        matched.push(rule.id);
+
+        let stop = false;
+        for (const action of rule.actions ?? []) {
+            if (action.type === 'stop') { stop = true; continue; }
+            actions.push({...action, rule: rule.id});
+        }
+        if (stop) break;
+    }
+
+    // One destination at most. Two moves is not two moves - IMAP has already
+    // taken the message away after the first, and the second would fail on a
+    // UID that no longer exists. The last one wins, as above.
+    const moves = actions.filter(a => a.type === 'move' || a.type === 'delete' || a.type === 'junk');
+    const finalMove = moves.length ? moves[moves.length - 1] : null;
+
+    return {
+        actions: [
+            ...actions.filter(a => !['move', 'delete', 'junk'].includes(a.type)),
+            ...(finalMove ? [finalMove] : [])
+        ],
+        matched
+    };
+}
+
+/**
+ * Describe a rule in a sentence, for a list that has to be scannable.
+ *
+ * @param   {object} rule
+ * @returns {string}
+ */
+export function describeRule(rule) {
+    const entry = normaliseRule(rule);
+    if (!entry.conditions.length) return 'Matches nothing yet.';
+
+    const label = field => RULE_FIELDS.find(f => f.field === field)?.label ?? field;
+    const opLabel = op => RULE_OPS.find(o => o.op === op)?.label ?? op;
+
+    const when = entry.conditions
+        .map(c => `${label(c.field)} ${opLabel(c.op)}${VALUELESS.has(c.op) ? '' : ` "${c.value}"`}`)
+        .join(entry.match === 'any' ? ' or ' : ' and ');
+
+    // Lower-cased one label at a time, never the whole sentence: a folder
+    // name is part of that sentence and IMAP folder names are case-sensitive,
+    // so "move to lists/github" names a folder that does not exist.
+    const then = entry.actions.length
+        ? entry.actions.map(a => {
+            const action = RULE_ACTIONS.find(x => x.type === a.type);
+            const verb = action.label.replace(/ to folder$/, '').toLowerCase();
+            return a.folder ? `${verb} to ${a.folder}` : action.label.toLowerCase();
+        }).join(', ')
+        : 'do nothing';
+
+    return `When ${when}, ${then}.`;
+}

package/plugins/_lib/admin/mail/scheduling.js

@@ -0,0 +1,203 @@
+/**
+ * When something should happen.
+ *
+ * Three features want the same arithmetic - hold this message for ten seconds
+ * so it can be taken back, send this one at eight tomorrow, put this one out
+ * of sight until Monday - so the arithmetic lives here once, pure, rather
+ * than three times in three routes.
+ *
+ * Shared with the browser (see the placement note in `identity.js`): the
+ * compose window offers the quick choices and the server validates what comes
+ * back, and those two must agree about what "tomorrow morning" means or a
+ * message scheduled from the picker is refused by the route that offered it.
+ *
+ * ## Everything is absolute
+ *
+ * A scheduled time is stored as an absolute instant, never as "in two hours".
+ * The process restarts, the clock changes twice a year, and a relative offset
+ * survives neither.
+ *
+ * @module _lib/admin/mail/scheduling
+ */
+
+/** How long a sent message may be held back so it can be recalled. */
+export const UNDO_SECONDS = [0, 5, 10, 20, 30];
+
+/** The default hold. Long enough to notice the mistake, short enough not to wait. */
+export const DEFAULT_UNDO_SECONDS = 10;
+
+/**
+ * How far ahead anything may be scheduled.
+ *
+ * A ceiling rather than a policy: a queued message holds its attachments in
+ * the store until it goes, and "send this in four years" is a way to find
+ * out, in four years, that the mail server's password changed.
+ */
+export const MAX_SCHEDULE_DAYS = 90;
+
+/** Hours the quick choices use. */
+const MORNING_HOUR = 8;
+const EVENING_HOUR = 18;
+
+/**
+ * How long a message is held after Send, for this mailbox.
+ *
+ * @param   {*} value
+ * @returns {number}
+ */
+export function normaliseUndoSeconds(value) {
+    // Absence is not a choice. `Number(null)` is 0 and 0 is a legal setting
+    // meaning "send immediately", so coercing first would read a mailbox
+    // that has never been asked as one that had opted out of the hold.
+    if (value === null || value === undefined || value === '') return DEFAULT_UNDO_SECONDS;
+    const seconds = Number(value);
+    return UNDO_SECONDS.includes(seconds) ? seconds : DEFAULT_UNDO_SECONDS;
+}
+
+/**
+ * A copy of a date moved to a given hour, with everything below it zeroed.
+ *
+ * @param   {Date} from
+ * @param   {number} hour
+ * @param   {number} [addDays]
+ * @returns {Date}
+ */
+function at(from, hour, addDays = 0) {
+    const when = new Date(from.getTime());
+    when.setDate(when.getDate() + addDays);
+    when.setHours(hour, 0, 0, 0);
+    return when;
+}
+
+/**
+ * The next weekday at a given hour.
+ *
+ * @param   {Date} from
+ * @param   {number} weekday - 0 Sunday .. 6 Saturday
+ * @param   {number} hour
+ * @returns {Date}
+ */
+function nextWeekday(from, weekday, hour) {
+    // Always at least one day ahead: "next Monday" asked on a Monday means
+    // the Monday coming, not the one already underway.
+    const ahead = ((weekday - from.getDay() + 7) % 7) || 7;
+    return at(from, hour, ahead);
+}
+
+/**
+ * The quick choices offered for "send later" and "snooze".
+ *
+ * Only ones still in the future: offering "This evening" at nine at night is
+ * offering a time that has been and gone, and a picker that lets you choose
+ * the past is a picker that has to explain itself afterwards.
+ *
+ * @param   {Date} [now]
+ * @returns {{id: string, label: string, at: string}[]}
+ */
+export function quickTimes(now = new Date()) {
+    const options = [
+        {id: 'hour', label: 'In an hour', when: new Date(now.getTime() + 60 * 60 * 1000)},
+        {id: 'evening', label: 'This evening', when: at(now, EVENING_HOUR)},
+        {id: 'tomorrow', label: 'Tomorrow morning', when: at(now, MORNING_HOUR, 1)},
+        {id: 'weekend', label: 'This weekend', when: nextWeekday(now, 6, MORNING_HOUR)},
+        {id: 'nextweek', label: 'Next week', when: nextWeekday(now, 1, MORNING_HOUR)}
+    ];
+
+    const seen = new Set();
+    return options
+        // A minute's grace, so a choice does not vanish between being drawn
+        // and being clicked.
+        .filter(option => option.when.getTime() > now.getTime() + 60_000)
+        // Two of these land on the same instant more often than it looks:
+        // asked on a Sunday, "tomorrow morning" and "next week" are both
+        // Monday at eight. Offering the same time twice under two names
+        // makes the picker look broken, so the earlier - and more specific -
+        // wording keeps it.
+        .filter(option => {
+            const key = option.when.getTime();
+            if (seen.has(key)) return false;
+            seen.add(key);
+            return true;
+        })
+        .map(({id, label, when}) => ({id, label, at: when.toISOString()}));
+}
+
+/**
+ * Validate a requested time.
+ *
+ * Refused rather than clamped. Someone who asked for a time in the past has
+ * either mistyped or is in a different timezone from the one they think, and
+ * quietly sending immediately answers neither question.
+ *
+ * @param   {*} value
+ * @param   {{now?: Date, maxDays?: number}} [options]
+ * @returns {{ok: true, at: string} | {ok: false, error: string}}
+ */
+export function normaliseSendAt(value, {now = new Date(), maxDays = MAX_SCHEDULE_DAYS} = {}) {
+    const when = value instanceof Date ? value : new Date(String(value ?? ''));
+    if (Number.isNaN(when.getTime())) {
+        return {ok: false, error: 'That is not a time I can read.'};
+    }
+    // Thirty seconds of slack, for a clock that disagrees with the server's
+    // by a little and a form that took a moment to submit.
+    if (when.getTime() < now.getTime() - 30_000) {
+        return {ok: false, error: 'That time has already passed.'};
+    }
+    const limit = now.getTime() + maxDays * 24 * 60 * 60 * 1000;
+    if (when.getTime() > limit) {
+        return {ok: false, error: `Nothing can be scheduled more than ${maxDays} days ahead.`};
+    }
+    return {ok: true, at: when.toISOString()};
+}
+
+/**
+ * Say when something will happen, the way a person would.
+ *
+ * @param   {string|Date} value
+ * @param   {Date} [now]
+ * @returns {string}
+ */
+export function describeWhen(value, now = new Date()) {
+    const when = value instanceof Date ? value : new Date(String(value ?? ''));
+    if (Number.isNaN(when.getTime())) return 'at an unknown time';
+
+    const seconds = Math.round((when.getTime() - now.getTime()) / 1000);
+    if (seconds <= 0) return 'now';
+    if (seconds < 90) return `in ${seconds} seconds`;
+
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60) return `in ${minutes} minutes`;
+
+    const clock = when.toLocaleTimeString([], {hour: '2-digit', minute: '2-digit'});
+    const sameDay = when.toDateString() === now.toDateString();
+    if (sameDay) return `at ${clock}`;
+
+    const tomorrow = new Date(now.getTime());
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    if (when.toDateString() === tomorrow.toDateString()) return `tomorrow at ${clock}`;
+
+    // Inside the week, the day name is what orients people. Beyond it, the
+    // date is - "Thursday" three weeks out tells you nothing.
+    const days = Math.round((when.getTime() - now.getTime()) / 86_400_000);
+    if (days < 7) return `on ${when.toLocaleDateString([], {weekday: 'long'})} at ${clock}`;
+    return `on ${when.toLocaleDateString()} at ${clock}`;
+}
+
+/**
+ * Which queued items are ready to run.
+ *
+ * A separate function so the worker's decision can be tested without a
+ * database: hand it rows and a clock, and it says which ones are due.
+ *
+ * @param   {Array<{at?: string, status?: string}>} items
+ * @param   {Date|number} [now]
+ * @returns {object[]}
+ */
+export function dueNow(items, now = Date.now()) {
+    const at = now instanceof Date ? now.getTime() : Number(now);
+    return (items ?? []).filter(item => {
+        if (item?.status && item.status !== 'pending') return false;
+        const when = new Date(String(item?.at ?? '')).getTime();
+        return Number.isFinite(when) && when <= at;
+    });
+}