domma-cms 0.54.2 → 0.66.0

package/plugins/_lib/mail/secretbox.js

@@ -0,0 +1,229 @@
+/**
+ * Sealed-secret helper for the Mail Reader plugin.
+ *
+ * IMAP is a password protocol: to reconnect without asking the user every time
+ * we have to keep their mailbox password, and keeping it in plain text on disk
+ * is not an option. Everything stored goes through seal()/open() here.
+ *
+ * ## Key resolution
+ *
+ * The key is derived from whichever of these is present, in order:
+ *
+ *   1. `MAIL_SECRET`      — explicit override for anyone who wants mail
+ *                           credentials on their own rotatable key.
+ *   2. `INSTANCE_SECRET`  — written by `npm run setup` and by manager
+ *                           registration. Present on fresh installs; NOT
+ *                           present on sites that predate it, which is why
+ *                           this is a chain and not a single source.
+ *   3. a generated key in `data/.mailkey` (0600) — last resort so the plugin
+ *                           works out of the box. It sits next to the sealed
+ *                           data, so it defends a leaked *backup* of
+ *                           accounts.json, not a compromised host.
+ *
+ * Deliberately NOT derived from JWT_SECRET: rotating that logs everyone out,
+ * which is recoverable, and silently bricking every stored mailbox password at
+ * the same time is not.
+ *
+ * The source that sealed a value is recorded in the token, so moving up the
+ * chain (adding MAIL_SECRET to a site that had been using .mailkey) fails with
+ * a sentence that says what happened instead of a bare auth error.
+ *
+ * @module _lib/mail/secretbox
+ */
+import {createCipheriv, createDecipheriv, randomBytes, scryptSync} from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Domain separation - stops this key colliding with any other use of the same
+ * secret. Deliberately NOT named after the plugin: `email-pro` is expected to
+ * open the same sealed accounts, and renaming this tag would invalidate every
+ * stored password for the sake of cosmetics.
+ */
+const DOMAIN = 'domma-mail-v1';
+
+/** Minimum acceptable length for an env-supplied secret. */
+const MIN_SECRET_LENGTH = 32;
+
+/** Shares the override used by accounts.js - see the note there. */
+const DATA_DIR = process.env.DOMMA_MAIL_DATA_DIR || path.join(__dirname, '..', 'data');
+
+const KEY_FILE = path.join(DATA_DIR, '.mailkey');
+
+/** Where the key lived while this code belonged to the mail-reader plugin. */
+const LEGACY_KEY_FILE = path.join(__dirname, '..', '..', 'mail-reader', 'data', '.mailkey');
+
+/** scrypt is deliberately slow; cache derived keys so a reconnect is not a CPU event. */
+const keyCache = new Map();
+
+/**
+ * Raised when a sealed value cannot be opened with the key we can derive.
+ * Carries the two sources so the caller can explain the mismatch.
+ */
+export class MailKeyError extends Error {
+    /**
+     * @param {string} message
+     * @param {{sealedWith?: string, availableFrom?: string}} [detail]
+     */
+    constructor(message, detail = {}) {
+        super(message);
+        this.name = 'MailKeyError';
+        this.sealedWith = detail.sealedWith ?? null;
+        this.availableFrom = detail.availableFrom ?? null;
+    }
+}
+
+/**
+ * Read, or create, the local fallback key.
+ *
+ * Written 0600 at create time rather than chmod-ed afterwards, so there is no
+ * window where the file exists and is world-readable.
+ *
+ * @returns {string} hex key material
+ */
+function localKeyMaterial() {
+    try {
+        const existing = fs.readFileSync(KEY_FILE, 'utf8').trim();
+        if (existing.length >= MIN_SECRET_LENGTH) return existing;
+    } catch {
+        // Missing or unreadable - fall through.
+    }
+
+    // Adopt the key from the old mail-reader-owned location before generating
+    // a new one. Generating first would strand every password already sealed
+    // with it, and the user would have no way to tell why.
+    try {
+        const legacy = fs.readFileSync(LEGACY_KEY_FILE, 'utf8').trim();
+        if (legacy.length >= MIN_SECRET_LENGTH) {
+            fs.mkdirSync(path.dirname(KEY_FILE), {recursive: true});
+            fs.writeFileSync(KEY_FILE, legacy + '\n', {encoding: 'utf8', mode: 0o600});
+            return legacy;
+        }
+    } catch {
+        // No legacy key - fall through and generate.
+    }
+
+    const generated = randomBytes(32).toString('hex');
+    fs.mkdirSync(path.dirname(KEY_FILE), {recursive: true});
+    fs.writeFileSync(KEY_FILE, generated + '\n', {encoding: 'utf8', mode: 0o600});
+    return generated;
+}
+
+/**
+ * Resolve the key material and say where it came from.
+ *
+ * @returns {{secret: string, source: 'env-mail'|'env-instance'|'local'}}
+ */
+export function resolveKeySource() {
+    const mailSecret = process.env.MAIL_SECRET;
+    if (typeof mailSecret === 'string' && mailSecret.length >= MIN_SECRET_LENGTH) {
+        return {secret: mailSecret, source: 'env-mail'};
+    }
+
+    const instanceSecret = process.env.INSTANCE_SECRET;
+    if (typeof instanceSecret === 'string' && instanceSecret.length >= MIN_SECRET_LENGTH) {
+        return {secret: instanceSecret, source: 'env-instance'};
+    }
+
+    return {secret: localKeyMaterial(), source: 'local'};
+}
+
+/**
+ * Derive a 32-byte key for a given salt, memoised per (source, salt).
+ *
+ * @param   {string} secret
+ * @param   {string} source
+ * @param   {Buffer} salt
+ * @returns {Buffer}
+ */
+function deriveKey(secret, source, salt) {
+    const cacheKey = source + ':' + salt.toString('base64');
+    const cached = keyCache.get(cacheKey);
+    if (cached) return cached;
+
+    const key = scryptSync(DOMAIN + ':' + secret, salt, 32);
+    keyCache.set(cacheKey, key);
+    return key;
+}
+
+/**
+ * Encrypt a string for storage.
+ *
+ * Format: `v1.<source>.<salt>.<iv>.<tag>.<ciphertext>`, each part base64url.
+ *
+ * @param   {string} plaintext
+ * @returns {string} sealed token
+ */
+export function seal(plaintext) {
+    const {secret, source} = resolveKeySource();
+    const salt = randomBytes(16);
+    const iv = randomBytes(12);
+    const key = deriveKey(secret, source, salt);
+
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([cipher.update(String(plaintext), 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+
+    return [
+        'v1',
+        source,
+        salt.toString('base64url'),
+        iv.toString('base64url'),
+        tag.toString('base64url'),
+        ciphertext.toString('base64url')
+    ].join('.');
+}
+
+/**
+ * Decrypt a sealed token.
+ *
+ * @param   {string} token
+ * @returns {string} plaintext
+ * @throws  {MailKeyError} when the token is malformed or the key no longer matches
+ */
+export function open(token) {
+    if (typeof token !== 'string' || !token.startsWith('v1.')) {
+        throw new MailKeyError('Stored password is not in a recognised format.');
+    }
+
+    const [, sealedWith, saltPart, ivPart, tagPart, ctPart] = token.split('.');
+    if (!saltPart || !ivPart || !tagPart || !ctPart) {
+        throw new MailKeyError('Stored password is malformed.');
+    }
+
+    const {secret, source} = resolveKeySource();
+    const key = deriveKey(secret, source, Buffer.from(saltPart, 'base64url'));
+
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(ivPart, 'base64url'));
+        decipher.setAuthTag(Buffer.from(tagPart, 'base64url'));
+        return Buffer.concat([
+            decipher.update(Buffer.from(ctPart, 'base64url')),
+            decipher.final()
+        ]).toString('utf8');
+    } catch {
+        const moved = sealedWith !== source;
+        throw new MailKeyError(
+            moved
+                ? `This password was saved using the ${describeSource(sealedWith)} and the server is now using the ${describeSource(source)}. Re-enter the password to save it against the new key.`
+                : 'Stored password could not be decrypted - the encryption key has changed. Re-enter the password.',
+            {sealedWith, availableFrom: source}
+        );
+    }
+}
+
+/**
+ * Human-readable name for a key source, for error messages.
+ *
+ * @param   {string} source
+ * @returns {string}
+ */
+export function describeSource(source) {
+    if (source === 'env-mail') return 'MAIL_SECRET environment variable';
+    if (source === 'env-instance') return 'INSTANCE_SECRET environment variable';
+    if (source === 'local') return 'plugin-local key file';
+    return 'unknown key source';
+}

package/plugins/_lib/mail/send.js

@@ -0,0 +1,396 @@
+/**
+ * Sending, and keeping a copy where the rest of your clients will find it.
+ *
+ * The message is built once, as raw RFC822, and that same buffer is both sent
+ * and appended to Sent. Building it twice - once for the transport and once
+ * for the copy - is how a Sent folder ends up holding something subtly unlike
+ * what the recipient received.
+ *
+ * @module _lib/mail/send
+ */
+import {createRequire} from 'node:module';
+
+import nodemailer from 'nodemailer';
+
+import {bareAddress, formatFrom} from '../admin/mail/identity.js';
+import {normalisePriority, priorityHeaders} from './priority.js';
+
+// MailComposer is not on nodemailer's public export, but it is the piece that
+// turns a message object into the bytes that go on the wire - which is what a
+// faithful Sent copy needs.
+const MailComposer = createRequire(import.meta.url)('nodemailer/lib/mail-composer');
+
+/**
+ * Turn an address list into what nodemailer expects.
+ *
+ * @param   {Array<{name?: string, address?: string}>|string|undefined} list
+ * @returns {object[]}
+ */
+function addresses(list) {
+    if (!list) return [];
+    if (typeof list === 'string') {
+        return list.split(',').map(part => ({address: part.trim()})).filter(a => a.address);
+    }
+    return list
+        .map(entry => (typeof entry === 'string' ? {address: entry.trim()} : entry))
+        .filter(entry => entry?.address);
+}
+
+/**
+ * Check a draft is worth trying to send.
+ *
+ * @param   {object} draft
+ * @returns {{ok: true} | {ok: false, error: string}}
+ */
+export function validateDraft(draft, {maxAttachmentBytes = 20_000_000} = {}) {
+    const to = addresses(draft?.to);
+    const cc = addresses(draft?.cc);
+    const bcc = addresses(draft?.bcc);
+
+    if (!to.length && !cc.length && !bcc.length) {
+        return {ok: false, error: 'A message needs at least one recipient.'};
+    }
+
+    const bad = [...to, ...cc, ...bcc]
+        .map(a => a.address)
+        .filter(address => !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(address));
+    if (bad.length) {
+        return {ok: false, error: `Not a valid address: ${bad.join(', ')}`};
+    }
+
+    if (!String(draft?.body ?? '').trim() && !String(draft?.subject ?? '').trim()) {
+        return {ok: false, error: 'A message needs a subject or a body.'};
+    }
+
+    const attachments = draft?.attachments ?? [];
+    if (!Array.isArray(attachments)) {
+        return {ok: false, error: 'Attachments must be a list.'};
+    }
+
+    let total = 0;
+    for (const file of attachments) {
+        if (!file?.filename || typeof file.content !== 'string') {
+            return {ok: false, error: 'Every attachment needs a filename and its content.'};
+        }
+        // Base64 length maps to bytes without decoding it first, which means
+        // an oversized payload is refused before it is turned into memory.
+        total += Math.floor(file.content.length * 3 / 4);
+    }
+
+    if (total > maxAttachmentBytes) {
+        const mb = n => `${(n / 1_000_000).toFixed(1)}MB`;
+        return {
+            ok: false,
+            error: `Attachments total ${mb(total)}, over the ${mb(maxAttachmentBytes)} limit. Most providers refuse around 25MB, so this is better refused here than bounced later.`
+        };
+    }
+
+    return {ok: true, attachmentBytes: total};
+}
+
+/**
+ * Build the raw bytes of a message.
+ *
+ * `from` is the header value, display name and all. The envelope address is
+ * the caller's business, not this function's - see `sendMessage`.
+ *
+ * @param   {object} draft
+ * @param   {string} from
+ * @param   {{replyTo?: string, readReceiptTo?: string, headers?: object}} [options]
+ * @returns {Promise<Buffer>}
+ */
+function buildRaw(draft, from, {replyTo = '', readReceiptTo = '', headers = {}} = {}) {
+    const composer = new MailComposer({
+        from,
+        // Only when the mailbox asks for one. An absent Reply-To means
+        // "answer the From address", which is what every client already does -
+        // setting it to the From address says the same thing in a header that
+        // some mailing lists then rewrite.
+        ...(replyTo ? {replyTo} : {}),
+        to: addresses(draft.to),
+        cc: addresses(draft.cc),
+        bcc: addresses(draft.bcc),
+        subject: draft.subject ?? '',
+        // Set by the caller for a QUEUED send, so that a retry after a
+        // failure carries the same id as the attempt before it.
+        //
+        // The claim in the store makes a send exactly-once up to the moment
+        // the message leaves; it cannot make SMTP exactly-once. A connection
+        // dropped between the terminating dot and the 250 looks identical to
+        // a message that was never accepted, and the only honest options are
+        // to risk losing it or to risk sending it twice. This takes the
+        // second and makes the duplicate detectable: both copies carry one
+        // Message-ID, which is what every receiver deduplicates on.
+        ...(draft.messageId ? {messageId: draft.messageId} : {}),
+        text: draft.body ?? '',
+        // Both parts when there is formatting, so the message is
+        // multipart/alternative: clients that render HTML get it, and those
+        // that do not - and anyone reading in a terminal - still get something
+        // written for them rather than a wall of tags.
+        ...(String(draft.html ?? '').trim() ? {html: draft.html} : {}),
+        // Threading. Present only for a reply - a forward deliberately carries
+        // neither, so it does not file itself into a conversation its new
+        // recipient has never seen.
+        ...(draft.inReplyTo ? {inReplyTo: draft.inReplyTo} : {}),
+        ...(draft.references?.length ? {references: draft.references} : {}),
+        // All three priority headers, or none. A recipient's client reads
+        // whichever one it knows, and setting only one is how a message looks
+        // urgent in Outlook and ordinary everywhere else. Normal sends none:
+        // the absence of the header IS normal.
+        headers: {
+            ...priorityHeaders(normalisePriority(draft.priority)),
+            // Both spellings when a receipt is wanted. `Disposition-Notification-To`
+            // is the standard one (RFC 8098) and `Return-Receipt-To` is what
+            // older clients read; sending one and not the other is how a
+            // receipt request works in half the world. A receipt is a request,
+            // not a mechanism - every client is free to ignore it, and many
+            // do, which is worth knowing before relying on one.
+            ...(readReceiptTo
+                ? {
+                    'Disposition-Notification-To': readReceiptTo,
+                    'Return-Receipt-To': readReceiptTo
+                }
+                : {}),
+            // Anything the caller must put on the wire itself. Today that is
+            // the away message announcing itself as automatic, which is what
+            // stops the responder at the far end answering it back.
+            ...headers
+        },
+        attachments: (draft.attachments ?? []).map(file => ({
+            filename: file.filename,
+            content: Buffer.from(file.content, 'base64'),
+            contentType: file.contentType
+        }))
+    });
+
+    return new Promise((resolve, reject) => {
+        composer.compile().build((err, message) => (err ? reject(err) : resolve(message)));
+    });
+}
+
+/**
+ * Thrown to skip filing a copy, rather than checked around the whole block.
+ *
+ * The filing is already wrapped in a try/catch that treats any failure as
+ * "delivered but not filed", which is exactly the outcome wanted here - so
+ * the cheapest correct way in is through the same door.
+ */
+class SkipFiling extends Error {}
+
+/**
+ * Send a draft, and file a copy.
+ *
+ * The copy is best effort. A message that was delivered but could not be
+ * filed is still delivered, and failing the send at that point would invite
+ * someone to send it a second time.
+ *
+ * @param   {{smtp: object, draft: object, pool: object, poolKey: string,
+ *            connection: object, sentFolder: string|null}} options
+ * @returns {Promise<{messageId: string, accepted: string[], rejected: string[], filedTo: string|null, fileError: string|null}>}
+ */
+export async function sendMessage({
+    smtp, draft, pool, poolKey, connection, sentFolder = null, allowInsecureTLS = false,
+    replaces = null, draftsFolder = null, headers = {}, fileCopy = true
+}) {
+    // The header carries the display name; the envelope never can. They are
+    // built from the same stored address so they cannot name two different
+    // mailboxes, but they are not the same string.
+    const raw = await buildRaw(draft, formatFrom(smtp.from, smtp.fromName), {
+        replyTo: smtp.replyTo,
+        // Asked for per message, addressed to wherever replies would go -
+        // which is the Reply-To when there is one and the From otherwise.
+        // A receipt sent to an address the sender does not read is a receipt
+        // nobody sees.
+        readReceiptTo: draft.readReceipt
+            ? (smtp.replyTo || bareAddress(smtp.from))
+            : '',
+        headers
+    });
+
+    // The same setting that governs incoming TLS governs outgoing: a site
+    // running its own mail server with a self-signed certificate has the same
+    // problem in both directions, and two switches for one decision is how
+    // one of them ends up wrong.
+    const transport = nodemailer.createTransport({
+        ...smtp.transport,
+        tls: {rejectUnauthorized: !allowInsecureTLS}
+    });
+    const info = await transport.sendMail({
+        envelope: {
+            // Bare, always. A display name here is not decoration the server
+            // ignores - it is a MAIL FROM the server rejects, and `smtp.from`
+            // is a free-text field somebody may well have typed a name into.
+            from: bareAddress(smtp.from),
+            to: [...addresses(draft.to), ...addresses(draft.cc), ...addresses(draft.bcc)]
+                .map(a => a.address)
+        },
+        raw
+    });
+    transport.close();
+
+    let filedTo = null;
+    let fileError = null;
+    try {
+        // An away message deliberately does not file. One holiday can produce
+        // a hundred of them, and a Sent folder that is mostly "Out of office"
+        // is a Sent folder nobody can find anything in - the responder keeps
+        // its own log instead.
+        if (!fileCopy) throw new SkipFiling();
+        const destination = sentFolder ?? await findSentFolder(pool, poolKey, connection);
+        if (destination) {
+            await pool.withClient(poolKey, connection,
+                client => client.append(destination, raw, ['\\Seen']));
+            filedTo = destination;
+        }
+    } catch (err) {
+        if (!(err instanceof SkipFiling)) fileError = err.message;
+    }
+
+    // Only once it has actually gone. A draft cleared before the send would
+    // be a draft lost to a rejected recipient, and the text only existed
+    // there.
+    const draftRemoved = replaces ? await discardDraft({
+        pool, poolKey, connection, uid: replaces, draftsFolder
+    }) : false;
+
+    return {
+        messageId: info.messageId,
+        accepted: info.accepted ?? [],
+        rejected: info.rejected ?? [],
+        filedTo,
+        fileError,
+        draftRemoved
+    };
+}
+
+/**
+ * Take a superseded draft out of the Drafts folder.
+ *
+ * Expunged rather than moved to Trash, which is the one place this codebase
+ * departs from "deleting means Trash": the draft has just been sent, so the
+ * message still exists in Sent, and putting a copy of it in the bin as well
+ * leaves someone three copies of one email to reason about.
+ *
+ * Best-effort. A leftover draft is untidy; a send reported as failed because
+ * the tidying did is worse.
+ *
+ * @param   {{pool: object, poolKey: string, connection: object, uid: number,
+ *            draftsFolder?: string|null}} options
+ * @returns {Promise<boolean>}
+ */
+async function discardDraft({pool, poolKey, connection, uid, draftsFolder = null}) {
+    try {
+        const destination = draftsFolder
+            ?? await findSpecialFolder(pool, poolKey, connection, '\\Drafts');
+        if (!destination) return false;
+
+        await pool.withMailbox(poolKey, connection, destination, async (client) => {
+            await client.messageFlagsAdd({uid: String(uid)}, ['\\Deleted'], {uid: true});
+            await client.messageDelete({uid: String(uid)}, {uid: true});
+        }, {writable: true});
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Save a draft to the Drafts folder.
+ *
+ * Built with the same code that builds a sendable message, so what is stored
+ * is what would have gone out. Saved with `\\Draft` so other clients treat it
+ * as editable rather than as received mail.
+ *
+ * A previous version is replaced rather than accumulated: editing a draft four
+ * times should leave one draft, not four. The old copy is removed only after
+ * the new one is stored, so an interruption loses nothing.
+ *
+ * @param   {{draft: object, from: string, replyTo?: string, pool: object, poolKey: string,
+ *            connection: object, draftsFolder?: string|null, replaces?: number|null}} options
+ * @returns {Promise<{savedTo: string, uid: number|null, replaced: number|null}>}
+ */
+export async function saveDraft({
+    draft, from, replyTo = '', pool, poolKey, connection, draftsFolder = null, replaces = null
+}) {
+    // Written into the draft, not applied when it is eventually sent: a draft
+    // opened on the phone should show the same headers it will go out with.
+    const raw = await buildRaw(draft, from, {
+        replyTo,
+        readReceiptTo: draft.readReceipt ? (replyTo || bareAddress(from)) : ''
+    });
+
+    const destination = draftsFolder ?? await findSpecialFolder(pool, poolKey, connection, '\\Drafts');
+    if (!destination) {
+        throw new Error('This server has no Drafts folder to save into.');
+    }
+
+    const appended = await pool.withClient(poolKey, connection,
+        client => client.append(destination, raw, ['\\Draft', '\\Seen']));
+
+    // Only now is the previous version expendable.
+    let replaced = null;
+    if (replaces) {
+        try {
+            await pool.withMailbox(poolKey, connection, destination, async (client) => {
+                await client.messageFlagsAdd({uid: String(replaces)}, ['\\Deleted'], {uid: true});
+                await client.messageDelete({uid: String(replaces)}, {uid: true});
+            }, {writable: true});
+            replaced = replaces;
+        } catch {
+            // The new draft is saved; a leftover old one is untidy, not broken.
+        }
+    }
+
+    return {savedTo: destination, uid: appended?.uid ?? null, replaced};
+}
+
+/**
+ * Find a folder by its SPECIAL-USE attribute.
+ *
+ * @param   {object} pool
+ * @param   {string} poolKey
+ * @param   {object} connection
+ * @param   {string} use
+ * @returns {Promise<string|null>}
+ */
+async function findSpecialFolder(pool, poolKey, connection, use) {
+    const boxes = await pool.withClient(poolKey, connection, client => client.list());
+    return boxes.find(box => box.specialUse === use)?.path ?? null;
+}
+
+/**
+ * Where this server keeps sent mail.
+ *
+ * By SPECIAL-USE, never by name: it is localised on plenty of servers, and
+ * guessing wrong means the copy lands in a folder nobody looks at.
+ *
+ * @param   {object} pool
+ * @param   {string} poolKey
+ * @param   {object} connection
+ * @returns {Promise<string|null>}
+ */
+async function findSentFolder(pool, poolKey, connection) {
+    return findSpecialFolder(pool, poolKey, connection, '\\Sent');
+}
+
+/**
+ * Try the outgoing server without sending anything.
+ *
+ * @param   {object} transportConfig
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+export async function verifySmtp(transportConfig, allowInsecureTLS = false) {
+    const transport = nodemailer.createTransport({
+        ...transportConfig,
+        connectionTimeout: 10_000,
+        tls: {rejectUnauthorized: !allowInsecureTLS}
+    });
+    try {
+        await transport.verify();
+        return {ok: true};
+    } catch (err) {
+        return {ok: false, error: err.message};
+    } finally {
+        transport.close();
+    }
+}