domma-cms 0.54.2 → 0.66.0

package/plugins/_lib/mail/bodyTokens.js

@@ -0,0 +1,101 @@
+/**
+ * Short-lived tokens authorising one message body fetch.
+ *
+ * ## Why this exists
+ *
+ * A message renders inside an iframe. The obvious way to fill that iframe is
+ * `srcdoc`, and that is what the reader did first - but a `srcdoc` document
+ * **inherits the embedding page's Content-Security-Policy**, and the admin is
+ * served with `img-src 'self' data: blob:`. The consequence was that "Load
+ * images" could flip the `src` to the real URL and the browser would then
+ * refuse to fetch it, silently, with no request ever made. The feature could
+ * not work, however correct the server was.
+ *
+ * A document loaded over the network carries its own CSP instead of
+ * inheriting, so the body is served from a real route. That route cannot read
+ * an Authorization header - an `<iframe src>` sends none - so the URL carries
+ * a signed token that says exactly which message, for which user, and for how
+ * long. Same shape as the CMS's own preview links.
+ *
+ * The token is deliberately narrow: it names one mailbox, one folder and one
+ * message, it expires in minutes, and it grants nothing else.
+ *
+ * @module _lib/mail/bodyTokens
+ */
+import {createHmac, timingSafeEqual} from 'node:crypto';
+
+import {resolveKeySource} from './secretbox.js';
+
+/** Domain separation, so this key can never collide with the sealing key. */
+const DOMAIN = 'domma-mail-body-v1';
+
+/** How long a token stays valid. Long enough to load a page, short enough not to matter. */
+const TTL_MS = 120_000;
+
+/**
+ * Sign a payload.
+ *
+ * @param   {string} body - base64url payload
+ * @returns {string} base64url signature
+ */
+function signature(body) {
+    const {secret} = resolveKeySource();
+    return createHmac('sha256', DOMAIN + ':' + secret).update(body).digest('base64url');
+}
+
+/**
+ * Mint a token authorising one message body fetch.
+ *
+ * @param   {{userId: string, accountId: string, folder: string, uid: number, images: boolean}} grant
+ * @returns {string}
+ */
+export function sign(grant) {
+    const payload = {
+        u: grant.userId,
+        a: grant.accountId,
+        f: grant.folder,
+        m: grant.uid,
+        i: grant.images ? 1 : 0,
+        e: Date.now() + TTL_MS
+    };
+    const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    return `${body}.${signature(body)}`;
+}
+
+/**
+ * Check a token and return what it authorises.
+ *
+ * @param   {string} token
+ * @returns {{userId: string, accountId: string, folder: string, uid: number, images: boolean}|null}
+ */
+export function verify(token) {
+    if (typeof token !== 'string' || !token.includes('.')) return null;
+
+    const [body, provided] = token.split('.');
+    if (!body || !provided) return null;
+
+    const expected = signature(body);
+    // Compare in constant time, and only when the lengths already match -
+    // timingSafeEqual throws on a length mismatch.
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
+
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+    } catch {
+        return null;
+    }
+
+    if (typeof payload?.e !== 'number' || Date.now() > payload.e) return null;
+    if (!payload.u || !payload.a || typeof payload.m !== 'number') return null;
+
+    return {
+        userId: payload.u,
+        accountId: payload.a,
+        folder: typeof payload.f === 'string' ? payload.f : 'INBOX',
+        uid: payload.m,
+        images: payload.i === 1
+    };
+}

package/plugins/_lib/mail/compose.js

@@ -0,0 +1,256 @@
+/**
+ * Turning a message into a reply, and a reply into something sendable.
+ *
+ * Pure, and tested on its own, because the parts that go wrong here are not
+ * the sending - nodemailer does that - but the conventions around it. A reply
+ * that loses its threading headers starts a new conversation in every client
+ * that receives it, a reply-all that includes you talks to yourself, and a
+ * quote that drops the attribution line reads as if you wrote it.
+ *
+ * @module _lib/mail/compose
+ */
+import {readPriority} from './priority.js';
+
+/**
+ * Addresses to reply to.
+ *
+ * Reply-To wins over From when present: a sender who sets it is asking for
+ * replies somewhere else, and ignoring that is how replies to a mailing list
+ * end up in one person's inbox.
+ *
+ * @param   {object} message
+ * @returns {{name: string, address: string}[]}
+ */
+export function replyRecipients(message) {
+    const replyTo = message.replyTo ?? [];
+    if (replyTo.length) return replyTo;
+    return message.from ?? [];
+}
+
+/**
+ * Everyone a reply-all should reach.
+ *
+ * The sender plus the original recipients, minus you - a reply-all that
+ * includes your own address sends you a copy of your own mail, which every
+ * client then has to file.
+ *
+ * @param   {object} message
+ * @param   {string} self - the address replying
+ * @returns {{to: object[], cc: object[]}}
+ */
+export function replyAllRecipients(message, self) {
+    const mine = String(self ?? '').trim().toLowerCase();
+    const notMine = list => (list ?? []).filter(a => String(a.address ?? '').toLowerCase() !== mine);
+
+    const to = replyRecipients(message);
+    const seen = new Set(to.map(a => String(a.address ?? '').toLowerCase()));
+
+    const cc = [...notMine(message.to), ...notMine(message.cc)]
+        .filter(a => {
+            const key = String(a.address ?? '').toLowerCase();
+            if (!key || seen.has(key)) return false;
+            seen.add(key);
+            return true;
+        });
+
+    return {to: notMine(to), cc};
+}
+
+/**
+ * The subject a reply carries.
+ *
+ * Only one "Re:" however many times a thread goes round, and the existing
+ * prefix is recognised case-insensitively because clients disagree about it.
+ *
+ * @param   {string} subject
+ * @param   {string} [prefix]
+ * @returns {string}
+ */
+export function replySubject(subject, prefix = 'Re') {
+    const clean = String(subject ?? '').trim();
+    const pattern = new RegExp(`^${prefix}:\\s*`, 'i');
+    return pattern.test(clean) ? clean : `${prefix}: ${clean}`;
+}
+
+/**
+ * The References header for a reply.
+ *
+ * A thread is reconstructed from this chain, so it carries everything the
+ * parent carried plus the parent itself. Trimmed from the front when it grows
+ * long, keeping the root - which is what identifies the thread - and the most
+ * recent, which is what identifies the position in it.
+ *
+ * @param   {{messageId?: string|null, references?: string|string[]|null}} parent
+ * @param   {number} [limit]
+ * @returns {string[]}
+ */
+export function buildReferences(parent, limit = 20) {
+    const existing = Array.isArray(parent?.references)
+        ? parent.references
+        : String(parent?.references ?? '').split(/\s+/).filter(Boolean);
+
+    const chain = [...existing];
+    if (parent?.messageId) chain.push(parent.messageId);
+
+    const unique = [...new Set(chain)];
+    if (unique.length <= limit) return unique;
+    return [unique[0], ...unique.slice(-(limit - 1))];
+}
+
+/**
+ * The attribution line above a quote.
+ *
+ * @param   {object} message
+ * @returns {string}
+ */
+export function attributionLine(message) {
+    const who = (message.from ?? [])[0];
+    const name = who?.name || who?.address || 'someone';
+    const when = message.date ? new Date(message.date).toUTCString() : 'an earlier message';
+    return `On ${when}, ${name} wrote:`;
+}
+
+/**
+ * Quote a message as plain text.
+ *
+ * Quoting the text part, never the HTML: quoting HTML means either embedding
+ * someone else's markup in your message or stripping it badly, and every mail
+ * client in existence understands "> ".
+ *
+ * @param   {object} message
+ * @param   {string} body
+ * @returns {string}
+ */
+export function quoteText(message, body) {
+    const quoted = String(body ?? '')
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .map(line => (line.startsWith('>') ? `>${line}` : `> ${line}`))
+        .join('\n');
+    return `\n\n${attributionLine(message)}\n${quoted}\n`;
+}
+
+/**
+ * Quote a message as HTML.
+ *
+ * A blockquote, which is what every client renders as a quote, around the
+ * original's own markup once it has been through the same sanitiser the
+ * reader uses. Remote images are dropped rather than blocked: a quote should
+ * not carry a tracking pixel onward to everyone on the reply.
+ *
+ * @param   {object} message
+ * @param   {string} html - the original's HTML, or null
+ * @param   {string} text - the original's text, used when there is no HTML
+ * @param   {(fragment: string) => string} sanitise
+ * @returns {string}
+ */
+export function quoteHtml(message, html, text, sanitise) {
+    const escape = value => String(value ?? '')
+        .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+    const inner = html
+        ? sanitise(html)
+        : `<pre style="white-space:pre-wrap;font-family:inherit;margin:0">${escape(text)}</pre>`;
+
+    return `<p><br></p><p>${escape(attributionLine(message))}</p>`
+        + `<blockquote style="margin:0 0 0 .8em;padding-left:.8em;border-left:3px solid #d0d0d0">${inner}</blockquote>`;
+}
+
+/**
+ * Build a complete draft from a message being answered.
+ *
+ * @param   {{message: object, self: string, mode: 'reply'|'replyAll'|'forward', body: string}} options
+ * @returns {object} a draft the compose window can open with
+ */
+export function buildDraft({message, self, mode, body, html = null, sanitise = null}) {
+    const htmlQuote = sanitise ? quoteHtml(message, html, body, sanitise) : null;
+
+    if (mode === 'forward') {
+        return {
+            to: [],
+            cc: [],
+            subject: replySubject(message.subject, 'Fwd'),
+            // A forward carries no In-Reply-To: it is not an answer to the
+            // message, and claiming otherwise files it into a thread the new
+            // recipient has never seen.
+            inReplyTo: null,
+            references: [],
+            body: quoteText(message, body),
+            html: htmlQuote
+        };
+    }
+
+    const {to, cc} = mode === 'replyAll'
+        ? replyAllRecipients(message, self)
+        : {to: replyRecipients(message), cc: []};
+
+    return {
+        to,
+        cc,
+        subject: replySubject(message.subject),
+        inReplyTo: message.messageId ?? null,
+        references: buildReferences(message),
+        body: quoteText(message, body),
+        html: htmlQuote
+    };
+}
+
+/**
+ * Turn a saved draft back into something the compose window can open.
+ *
+ * Not `buildDraft`, and deliberately not built on it: a reply derives its
+ * recipients, subject and quoted body FROM a message, whereas reopening a
+ * draft means taking the message verbatim - it already is the thing being
+ * written. Routing it through the reply arithmetic would quote the draft
+ * inside itself and address it to whoever it was already addressed to.
+ *
+ * `savedUid` is what makes the round trip work: saving again supersedes this
+ * version rather than adding a second one, and sending tidies it away. Without
+ * it, editing a draft four times leaves four drafts.
+ *
+ * @param   {object} message - a parsed draft (mailparser shape, flattened)
+ * @param   {number|null} uid - the draft's UID in the Drafts folder
+ * @returns {object}
+ */
+export function editableDraft(message, uid = null) {
+    const addresses = list => (list ?? []).map(a => ({
+        name: a.name ?? '', address: a.address ?? ''
+    }));
+
+    return {
+        to: addresses(message.to),
+        cc: addresses(message.cc),
+        // A draft can have one; a received message never does. Dropping it on
+        // reopen would silently change who a half-written message goes to.
+        bcc: addresses(message.bcc),
+        subject: message.subject ?? '',
+        // Kept, so replying to the thread the draft belongs to survives a save
+        // and reopen. A draft written as a reply is still a reply.
+        inReplyTo: message.inReplyTo ?? null,
+        references: normaliseReferences(message.references),
+        body: message.text ?? '',
+        html: message.html || null,
+        // Kept, or a draft marked urgent would quietly become ordinary the
+        // moment it was reopened.
+        priority: readPriority(message.headers),
+        attachments: (message.attachments ?? []).map(file => ({
+            filename: file.filename ?? 'attachment',
+            contentType: file.contentType ?? 'application/octet-stream',
+            content: file.content ?? '',
+            size: file.size ?? 0
+        })),
+        savedUid: uid
+    };
+}
+
+/**
+ * References arrive as a string on one server and an array on the next.
+ *
+ * @param   {string|string[]|null|undefined} value
+ * @returns {string[]}
+ */
+function normaliseReferences(value) {
+    if (Array.isArray(value)) return value.filter(Boolean);
+    if (typeof value === 'string') return value.split(/\s+/).filter(Boolean);
+    return [];
+}

package/plugins/_lib/mail/defaults.js

@@ -0,0 +1,57 @@
+/**
+ * Reading defaults, shared by every edition.
+ *
+ * `mail-reader` uses these as-is; `email-pro` spreads them and adds what its
+ * synchronised store needs. Merged with user overrides from
+ * config/plugins.json by whichever plugin is loading.
+ *
+ * @module _lib/mail/defaults
+ */
+export default {
+    /** Messages per page in the list pane. */
+    listLimit: 50,
+
+    /** Hard ceiling on ?limit=, so a crafted request cannot ask for a whole mailbox. */
+    maxListLimit: 200,
+
+    /** How long an unused IMAP connection is kept before it is closed. */
+    connectionIdleMs: 300_000,
+
+    /** Most simultaneous pooled connections. The least recently used is dropped beyond this. */
+    maxConnections: 20,
+
+    /** Connect, greeting and socket timeout. A dead server should fail fast, not hang the admin. */
+    connectionTimeoutMs: 20_000,
+
+    /**
+     * Load remote images in message bodies by default.
+     *
+     * Off, deliberately: a remote image in an email is usually a tracking
+     * pixel, and loading it reports the open back to the sender. The reader
+     * offers a per-message override that is never persisted.
+     */
+    allowRemoteImages: false,
+
+    /**
+     * Accept TLS certificates that do not verify.
+     *
+     * Only for a mail server with a self-signed certificate that you control.
+     * It disables the check that the server is who it says it is.
+     */
+    allowInsecureTLS: false,
+
+    /** Largest inline image embedded into a rendered body, in bytes. */
+    inlineImageMaxBytes: 2_000_000,
+
+    /** Largest message source fetched for rendering or attachment extraction, in bytes. */
+    maxMessageBytes: 25_000_000,
+
+    /**
+     * Largest total attachment payload on an outgoing message, in bytes.
+     *
+     * Twenty megabytes, because most providers refuse somewhere around
+     * twenty-five and it is better to be told here than to have the message
+     * accepted and then bounced an hour later.
+     */
+    maxAttachmentBytes: 20_000_000
+};

package/plugins/_lib/mail/diagnostics.js

@@ -0,0 +1,154 @@
+/**
+ * What the server knows about itself, for a bug report.
+ *
+ * Built because the expensive failures here were never "what does the code
+ * do" - they were "which build is that browser actually running", which no
+ * amount of reading the source answers. This reports the facts that settle
+ * that question, so a report can start from evidence instead of a description.
+ *
+ * Nothing secret goes in. Hostnames and usernames are needed to tell one
+ * mailbox from another; passwords, sealed or otherwise, are not, and the key
+ * SOURCE is reported without the key.
+ *
+ * @module _lib/mail/diagnostics
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import * as accounts from './accounts.js';
+import {resolveKeySource} from './secretbox.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** The browser-facing files whose versions decide what a page is running. */
+const SHARED_ASSETS = [
+    'reader-view.js', 'folder-tree.js', 'panes.js',
+    'image-senders-section.js', 'diagnostics-section.js',
+    'mail.html', 'mail.css'
+];
+
+/**
+ * The cache-busting token each shared asset would be served with.
+ *
+ * Compared against what the browser actually loaded, this is the difference
+ * between "stale cache" and "real bug" - a distinction that cost most of a
+ * day to make by hand.
+ *
+ * @returns {Promise<Object.<string, number|null>>}
+ */
+async function sharedAssetVersions() {
+    const dir = path.join(__dirname, '..', 'admin', 'mail');
+    const out = {};
+    await Promise.all(SHARED_ASSETS.map(async name => {
+        try {
+            out[name] = Math.floor((await fs.stat(path.join(dir, name))).mtimeMs);
+        } catch {
+            out[name] = null;
+        }
+    }));
+    return out;
+}
+
+/**
+ * The plugin's declared version.
+ *
+ * @param   {string} pluginName
+ * @returns {Promise<string|null>}
+ */
+async function pluginVersion(pluginName) {
+    try {
+        const raw = await fs.readFile(path.join(__dirname, '..', '..', pluginName, 'plugin.json'), 'utf8');
+        return JSON.parse(raw).version ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The stamp the loader would put on this plugin's view entry.
+ *
+ * The newest of the entry itself and the shared admin library, which is what
+ * makes a change to shared code reach a browser. Reported so a page can
+ * compare what it loaded against what it should have.
+ *
+ * @param   {string} pluginName
+ * @returns {Promise<number>}
+ */
+async function expectedStamp(pluginName) {
+    const dir = path.join(__dirname, '..', 'admin');
+    let newest = 0;
+
+    const walk = async current => {
+        let entries;
+        try {
+            entries = await fs.readdir(current, {withFileTypes: true});
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) await walk(full);
+            else {
+                try {
+                    newest = Math.max(newest, Math.floor((await fs.stat(full)).mtimeMs));
+                } catch { /* ignore */ }
+            }
+        }
+    };
+    await walk(dir);
+
+    try {
+        const entry = path.join(__dirname, '..', '..', pluginName, 'admin', 'views', 'mail.js');
+        newest = Math.max(newest, Math.floor((await fs.stat(entry)).mtimeMs));
+    } catch { /* the plugin may name its view differently */ }
+
+    return newest;
+}
+
+/**
+ * Assemble the report for one user.
+ *
+ * @param   {{pluginName: string, userId: string, config: object,
+ *            extra?: () => Promise<object>|object}} options
+ * @returns {Promise<object>}
+ */
+export async function buildDiagnostics({pluginName, userId, config, extra = null}) {
+    const owned = await accounts.listAccounts(userId);
+
+    return {
+        generatedAt: new Date().toISOString(),
+        plugin: {
+            name: pluginName,
+            version: await pluginVersion(pluginName)
+        },
+        runtime: {
+            node: process.version,
+            uptimeSeconds: Math.round(process.uptime())
+        },
+        assets: {...(await sharedAssetVersions()), expectedStamp: await expectedStamp(pluginName)},
+        credentials: {
+            // Which key is sealing passwords, never the key itself. A mailbox
+            // that stops opening after a deploy is usually this having moved.
+            keySource: resolveKeySource().source
+        },
+        config: {
+            listLimit: config.listLimit,
+            allowRemoteImages: config.allowRemoteImages,
+            allowInsecureTLS: config.allowInsecureTLS,
+            connectionIdleMs: config.connectionIdleMs
+        },
+        mailboxes: owned.map(account => ({
+            id: account.id,
+            label: account.label,
+            host: `${account.host}:${account.port}`,
+            secure: account.secure !== false,
+            username: account.username,
+            syncFolders: account.syncFolders ?? '(default)',
+            pollIntervalMinutes: account.pollIntervalMinutes ?? '(default)',
+            trustedImageSenders: (account.imageSenders ?? []).length,
+            rememberImageSenders: account.rememberImageSenders !== false
+        })),
+        ...(extra ? {edition: await extra()} : {})
+    };
+}