domma-cms 0.54.2 → 0.66.0

package/plugins/_lib/mail/accounts.js

@@ -0,0 +1,919 @@
+/**
+ * Per-user IMAP account store for the Mail Reader plugin.
+ *
+ * ## Why this is not a collection
+ *
+ * Every other plugin keeps its records in `server/services/collections.js`.
+ * This one does not, on purpose. A plugin-owned collection is still listed in
+ * the admin Collections screen with a working Entries link (`schema.plugin` is
+ * a badge, not a visibility gate), it is reachable through the `/api/v1`
+ * surface, and it can be pointed at a shared Mongo by global config. None of
+ * those are places a mailbox hostname, username and sealed password belong.
+ *
+ * So: a plugin-local JSON file, written 0600, gitignored, and never exposed
+ * through any generic data route. `_lib/dataStore` would do the atomic write
+ * for us but writes with default permissions, and a credentials file should
+ * not exist world-readable even briefly - hence the local writer below.
+ *
+ * ## Ownership
+ *
+ * A user may hold several mailboxes. Each record carries its own `id` and the
+ * `userId` that owns it, and **every** lookup here takes the user id as well
+ * as the account id. There is no function that resolves an account by id
+ * alone, so a route cannot accidentally hand one user another's mailbox.
+ *
+ * @module _lib/mail/accounts
+ */
+import {randomUUID} from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {normaliseIdentity, normaliseIdentityList, findIdentity} from '../admin/mail/identity.js';
+import {normaliseRules} from '../admin/mail/rules.js';
+import {normaliseUndoSeconds} from '../admin/mail/scheduling.js';
+import {normaliseVacation} from '../admin/mail/vacation.js';
+import {normaliseTemplates} from '../admin/mail/templates.js';
+import {sanitiseSignature} from './render.js';
+import {open, seal} from './secretbox.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Where mail state lives. Overridable so tests can point at a temp directory:
+ * without that they would have to operate on the real store, and a test that
+ * cleans up after itself would delete live mailbox credentials.
+ */
+const DATA_DIR = process.env.DOMMA_MAIL_DATA_DIR || path.join(__dirname, '..', 'data');
+// `plugins/<name>/data` is the ONLY path bin/update.js preserves across an
+// engine update - it deletes and replaces the rest of the directory. A
+// nested `_lib/mail/data` would be wiped on every upgrade, taking every
+// saved mailbox with it.
+const STORE_FILE = path.join(DATA_DIR, 'mail-accounts.json');
+
+/** Where the store lived while this code belonged to the mail-reader plugin. */
+const LEGACY_STORE_FILE = path.join(__dirname, '..', '..', 'mail-reader', 'data', 'accounts.json');
+
+/**
+ * Bring a stored record up to the current shape.
+ *
+ * The first release kept one account per user, keyed by the user id itself.
+ * Those records have no `userId` and their `id` is the owner - carry them
+ * forward rather than stranding anyone's saved mailbox.
+ *
+ * @param   {object} record
+ * @returns {object}
+ */
+function normalise(record) {
+    if (record.userId) return record;
+    return {...record, userId: record.id, id: randomUUID()};
+}
+
+/**
+ * Take over the store from the old mail-reader-owned location, once.
+ *
+ * Returns the records so the caller can carry on, or null when there is
+ * nothing to adopt. The old file is left where it is: an engine update
+ * preserves it, and leaving it costs nothing while deleting it would throw
+ * away the only copy if this went wrong.
+ *
+ * @returns {Promise<object[]|null>}
+ */
+async function adoptLegacyStore() {
+    let legacy;
+    try {
+        legacy = JSON.parse(await fs.readFile(LEGACY_STORE_FILE, 'utf8'));
+    } catch {
+        return null;
+    }
+    if (!Array.isArray(legacy) || !legacy.length) return null;
+
+    const records = legacy.map(normalise);
+    await writeAll(records);
+    return records;
+}
+
+/**
+ * Read every stored account, migrating any legacy records as a side effect.
+ *
+ * The migration is WRITTEN BACK, not just applied in memory. Normalising on
+ * every read without persisting would hand a legacy record a fresh `id` each
+ * time it was read, so it could never be selected twice or deleted at all -
+ * an upgraded user would be left with a ghost mailbox they could not remove.
+ *
+ * @returns {Promise<object[]>}
+ */
+async function readAll() {
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(STORE_FILE, 'utf8'));
+    } catch {
+        parsed = await adoptLegacyStore();
+        if (!parsed) return [];
+    }
+    if (!Array.isArray(parsed)) return [];
+
+    const normalised = parsed.map(normalise);
+    // normalise() returns the same reference when nothing changed.
+    if (normalised.some((record, i) => record !== parsed[i])) {
+        await writeAll(normalised);
+    }
+    return normalised;
+}
+
+/**
+ * Atomically write the store with owner-only permissions.
+ *
+ * The temp file is created 0600 rather than chmod-ed after the fact, so the
+ * sealed passwords are never briefly readable by other local users.
+ *
+ * @param   {object[]} accounts
+ * @returns {Promise<void>}
+ */
+async function writeAll(accounts) {
+    await fs.mkdir(path.dirname(STORE_FILE), {recursive: true});
+    const tmp = STORE_FILE + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(accounts, null, 2) + '\n', {encoding: 'utf8', mode: 0o600});
+    await fs.rename(tmp, STORE_FILE);
+}
+
+/**
+ * Strip everything the browser must never see.
+ *
+ * @param   {object|null} account
+ * @returns {object|null}
+ */
+export function toPublic(account) {
+    if (!account) return null;
+    const {passwordSealed, userId, smtp, ...rest} = account;
+    return {
+        ...rest,
+        // Pulled out and rebuilt rather than spread through: `smtp` carries a
+        // sealed password of its own, and a top-level destructure does not
+        // reach it. Spreading the record verbatim shipped that ciphertext to
+        // every browser that listed its mailboxes.
+        ...(smtp ? {smtp: smtpToPublic(account)} : {}),
+        hasPassword: typeof passwordSealed === 'string' && passwordSealed.length > 0
+    };
+}
+
+/**
+ * Store the outgoing server for a mailbox.
+ *
+ * Kept beside the IMAP settings and sealed the same way. A blank password
+ * means "use the IMAP one", which is right far more often than not - most
+ * providers use one credential for both - and saves asking for the same
+ * secret twice.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {{host: string, port: number, secure: boolean, username: string,
+ *            password: string, from: string, sentFolder: string|null}} smtp
+ * @returns {Promise<object|null>}
+ */
+export async function setSmtp(userId, accountId, smtp) {
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    const existing = all[index].smtp ?? {};
+    all[index] = {
+        ...all[index],
+        smtp: {
+            host: smtp.host,
+            port: smtp.port,
+            secure: smtp.secure,
+            username: smtp.username,
+            passwordSealed: smtp.password
+                ? seal(smtp.password)
+                : (existing.passwordSealed ?? null),
+            from: smtp.from,
+            sentFolder: smtp.sentFolder ?? null
+        },
+        updatedAt: new Date().toISOString()
+    };
+    await writeAll(all);
+    return all[index];
+}
+
+/**
+ * Build a nodemailer transport config for a mailbox.
+ *
+ * Falls back to the IMAP credentials when the outgoing server has none of its
+ * own, which is the common case.
+ *
+ * `identityId` chooses which of the mailbox's identities is sending. Absent,
+ * it is the default one - which is what every message sent before aliases
+ * existed did, and what most messages still do.
+ *
+ * @param   {object} account
+ * @param   {string|null} [identityId]
+ * @returns {{transport: object, from: string}|null}
+ */
+export function toSmtpConnection(account, identityId = null) {
+    const smtp = account?.smtp;
+    if (!smtp?.host) return null;
+
+    const pass = smtp.passwordSealed
+        ? open(smtp.passwordSealed)
+        : open(account.passwordSealed);
+
+    const identity = findIdentity(normaliseIdentityList(account), identityId);
+    const mailboxAddress = smtp.from || account.username;
+
+    return {
+        transport: {
+            host: smtp.host,
+            port: smtp.port,
+            secure: smtp.secure !== false,
+            auth: {user: smtp.username || account.username, pass}
+        },
+        // Still the bare address, as it always was. The display name travels
+        // beside it rather than folded into it, because the two go to
+        // different places: the name belongs in the From header and must stay
+        // out of the SMTP envelope.
+        //
+        // An alias replaces it outright: sending AS sales@ means the From and
+        // the envelope both say sales@, or the alias fails DMARC alignment
+        // and lands in spam at a good many receivers.
+        from: identity?.address || mailboxAddress,
+        fromName: identity?.displayName ?? '',
+        replyTo: identity?.replyTo ?? '',
+        identity: identity ?? null,
+        sentFolder: smtp.sentFolder ?? null
+    };
+}
+
+/**
+ * The outgoing settings, without the password.
+ *
+ * @param   {object} account
+ * @returns {object|null}
+ */
+export function smtpToPublic(account) {
+    const smtp = account?.smtp;
+    if (!smtp) return null;
+    const {passwordSealed, ...rest} = smtp;
+    return {...rest, hasPassword: typeof passwordSealed === 'string' && passwordSealed.length > 0};
+}
+
+/**
+ * What this mailbox signs its mail with.
+ *
+ * Always an object, never null: a mailbox with nothing configured has an
+ * empty identity rather than an absent one, so the settings form and the send
+ * path both have the same shape to read and neither needs a null branch.
+ *
+ * @param   {object|null} account
+ * @returns {object}
+ */
+export function identityToPublic(account) {
+    return normaliseIdentity(account?.identity);
+}
+
+/**
+ * Every identity this mailbox can send as.
+ *
+ * Always a list, possibly empty. The migration from the single-identity shape
+ * lives in `normaliseIdentityList`, so a mailbox configured before aliases
+ * existed answers a one-entry list here without anything being rewritten on
+ * disk - the rewrite happens the first time the list is saved, which is the
+ * only moment it is safe to assume the new shape is what was meant.
+ *
+ * @param   {object|null} account
+ * @returns {object[]}
+ */
+export function identitiesToPublic(account) {
+    return normaliseIdentityList(account);
+}
+
+/**
+ * Store the identities for a mailbox.
+ *
+ * A full replace, not a merge - which is what PUT means, and what makes
+ * deleting one possible at all. Each signature is sanitised HERE rather than
+ * in the route, for the reason `setIdentity` gives: this markup is handed
+ * back to an editor that sets it as innerHTML and mailed to third parties, so
+ * the guarantee has to hold for the next caller too.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {object[]} identities
+ * @returns {Promise<object|null>}
+ */
+export async function setIdentities(userId, accountId, identities) {
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    const cleaned = (Array.isArray(identities) ? identities : []).map(entry => ({
+        ...entry,
+        signatureHtml: sanitiseSignature(entry?.signatureHtml ?? '')
+    }));
+
+    const {identity, ...rest} = all[index];
+    all[index] = {
+        ...rest,
+        identities: normaliseIdentityList({identities: cleaned}),
+        updatedAt: new Date().toISOString()
+    };
+    await writeAll(all);
+    return all[index];
+}
+
+/**
+ * The canned responses this mailbox holds.
+ *
+ * @param   {object|null} account
+ * @returns {object[]}
+ */
+export function templatesToPublic(account) {
+    return normaliseTemplates(account);
+}
+
+/**
+ * Store the canned responses for a mailbox.
+ *
+ * Sanitised on the way in, exactly as signatures are, and for exactly the
+ * same reasons.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {object[]} templates
+ * @returns {Promise<object|null>}
+ */
+export async function setTemplates(userId, accountId, templates) {
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    const cleaned = (Array.isArray(templates) ? templates : []).map(entry => ({
+        ...entry,
+        bodyHtml: sanitiseSignature(entry?.bodyHtml ?? '')
+    }));
+
+    all[index] = {
+        ...all[index],
+        templates: normaliseTemplates({templates: cleaned}),
+        updatedAt: new Date().toISOString()
+    };
+    await writeAll(all);
+    return all[index];
+}
+
+/**
+ * The filing rules this mailbox runs, in order.
+ *
+ * @param   {object|null} account
+ * @returns {object[]}
+ */
+export function rulesToPublic(account) {
+    return normaliseRules(account);
+}
+
+/**
+ * Store the filing rules for a mailbox.
+ *
+ * `rulesFrom` is stamped the first time rules are saved and never moved
+ * afterwards. It is what stops a newly written rule reaching back through a
+ * decade of archive on the next sync: rules apply to mail that arrives from
+ * now on, which is what every other mail client means by a rule, and what
+ * someone writing their first one expects.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {object[]} rules
+ * @returns {Promise<object|null>}
+ */
+export async function setRules(userId, accountId, rules) {
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    all[index] = {
+        ...all[index],
+        rules: normaliseRules({rules}),
+        rulesFrom: all[index].rulesFrom ?? new Date().toISOString(),
+        updatedAt: new Date().toISOString()
+    };
+    await writeAll(all);
+    return all[index];
+}
+
+/**
+ * Which folders rules are applied to.
+ *
+ * The inbox alone by default. A rule that also ran over Sent would file your
+ * own replies, and one that ran over Archive would undo the archiving.
+ *
+ * @param   {object|null} account
+ * @returns {string[]}
+ */
+export function ruleFolders(account) {
+    const chosen = Array.isArray(account?.ruleFolders) ? account.ruleFolders : null;
+    return (chosen && chosen.length) ? chosen : ['INBOX'];
+}
+
+/**
+ * How long this mailbox holds a message after Send, in seconds.
+ *
+ * @param   {object|null} account
+ * @returns {number}
+ */
+export function undoSendSeconds(account) {
+    return normaliseUndoSeconds(account?.undoSendSeconds);
+}
+
+/**
+ * Set the sending behaviour that is neither the server nor the identity:
+ * how long Send can be taken back, and which folder snoozed mail waits in.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {{undoSendSeconds?: number, snoozeFolder?: string, ruleFolders?: string[]}} options
+ * @returns {Promise<object|null>}
+ */
+export async function setSendingOptions(userId, accountId, options) {
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    const folders = Array.isArray(options?.ruleFolders)
+        ? [...new Set(options.ruleFolders.filter(f => typeof f === 'string' && f.trim()))]
+        : null;
+
+    all[index] = {
+        ...all[index],
+        undoSendSeconds: normaliseUndoSeconds(options?.undoSendSeconds),
+        snoozeFolder: String(options?.snoozeFolder ?? '').trim() || null,
+        ...(folders ? {ruleFolders: folders} : {}),
+        updatedAt: new Date().toISOString()
+    };
+    await writeAll(all);
+    return all[index];
+}
+
+/**
+ * Every address this mailbox sends as.
+ *
+ * The away message needs all of them for two of its refusals: never answer
+ * something this mailbox sent, and never answer something it was merely
+ * Bcc'd on. Both need to know which addresses count as "us", and a mailbox
+ * with aliases has more than one.
+ *
+ * @param   {object|null} account
+ * @returns {string[]}
+ */
+export function sendingAddresses(account) {
+    const addresses = new Set();
+    if (account?.username) addresses.add(String(account.username).trim().toLowerCase());
+    const from = account?.smtp?.from;
+    if (from) addresses.add(String(from).replace(/^.*<|>.*$/g, '').trim().toLowerCase());
+    for (const identity of normaliseIdentityList(account)) {
+        if (identity.address) addresses.add(identity.address.toLowerCase());
+    }
+    return [...addresses].filter(Boolean);
+}
+
+/**
+ * The away message this mailbox is configured with.
+ *
+ * @param   {object|null} account
+ * @returns {object}
+ */
+export function vacationToPublic(account) {
+    return normaliseVacation(account);
+}
+
+/**
+ * Store the away message.
+ *
+ * The body is sanitised on the way in, exactly as a signature is: it is
+ * authored by hand, handed back to an editor that sets it as innerHTML, and
+ * mailed to strangers - which is a wider audience than a signature reaches,
+ * since it goes to everyone who writes while it is on.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {object} vacation
+ * @returns {Promise<object|null>}
+ */
+export async function setVacation(userId, accountId, vacation) {
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    all[index] = {
+        ...all[index],
+        vacation: normaliseVacation({
+            vacation: {
+                ...vacation,
+                bodyHtml: sanitiseSignature(vacation?.bodyHtml ?? '')
+            }
+        }),
+        updatedAt: new Date().toISOString()
+    };
+    await writeAll(all);
+    return all[index];
+}
+
+/** The folder snoozed mail waits in, for a mailbox that has not chosen one. */
+export const DEFAULT_SNOOZE_FOLDER = 'Snoozed';
+
+/**
+ * Where this mailbox parks snoozed mail.
+ *
+ * @param   {object|null} account
+ * @returns {string}
+ */
+export function snoozeFolder(account) {
+    return String(account?.snoozeFolder ?? '').trim() || DEFAULT_SNOOZE_FOLDER;
+}
+
+/**
+ * Store the sending identity for a mailbox.
+ *
+ * Normalised on the way in rather than on the way out. The signature HTML is
+ * embedded in outgoing mail and handed back to the settings editor, so the
+ * copy on disk should already be the safe, known-shaped one - sanitising at
+ * read time leaves the raw thing sitting in the store waiting for the next
+ * reader that forgets.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {object} identity
+ * @returns {Promise<object|null>}
+ */
+export async function setIdentity(userId, accountId, identity) {
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    all[index] = {
+        ...all[index],
+        // Sanitised HERE, not in the route that happens to be the only caller
+        // today. This markup is handed back to an editor that sets it as
+        // innerHTML and mailed to third parties, so the guarantee has to hold
+        // for the next caller too - an import, a fleet tool, a second route -
+        // none of which would think to reach for the sanitiser themselves.
+        identity: normaliseIdentity({
+            ...identity,
+            signatureHtml: sanitiseSignature(identity?.signatureHtml ?? '')
+        }),
+        updatedAt: new Date().toISOString()
+    };
+    await writeAll(all);
+    return all[index];
+}
+
+/**
+ * Trust a sender's remote images from now on.
+ *
+ * The per-message "Load images" button is deliberately not persisted - it is a
+ * decision about one message. This is the other thing people want: a sender
+ * whose images are always fine, chosen explicitly, listed in settings and
+ * revocable. That is a different act from silently remembering a click, which
+ * is why it is a separate button and a visible list rather than a side effect.
+ *
+ * Matching is on the address, lower-cased. Display names are trivially forged
+ * and are not part of the decision.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {string} address
+ * @returns {Promise<object|null>}
+ */
+export async function trustImageSender(userId, accountId, address) {
+    const clean = String(address ?? '').trim().toLowerCase();
+    if (!clean) return null;
+
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    const current = Array.isArray(all[index].imageSenders) ? all[index].imageSenders : [];
+    if (current.includes(clean)) return all[index];
+
+    all[index] = {...all[index], imageSenders: [...current, clean], updatedAt: new Date().toISOString()};
+    await writeAll(all);
+    return all[index];
+}
+
+/**
+ * Stop trusting a sender's images.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {string} address
+ * @returns {Promise<object|null>}
+ */
+export async function untrustImageSender(userId, accountId, address) {
+    const clean = String(address ?? '').trim().toLowerCase();
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    const current = Array.isArray(all[index].imageSenders) ? all[index].imageSenders : [];
+    all[index] = {
+        ...all[index],
+        imageSenders: current.filter(a => a !== clean),
+        updatedAt: new Date().toISOString()
+    };
+    await writeAll(all);
+    return all[index];
+}
+
+/**
+ * Turn the whole remembering feature on or off for a mailbox.
+ *
+ * Off means the button is never offered and any existing list is ignored
+ * without being thrown away - turning it back on should not mean rebuilding
+ * a list someone curated.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {boolean} enabled
+ * @returns {Promise<object|null>}
+ */
+export async function setRememberImageSenders(userId, accountId, enabled) {
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    all[index] = {...all[index], rememberImageSenders: !!enabled, updatedAt: new Date().toISOString()};
+    await writeAll(all);
+    return all[index];
+}
+
+/**
+ * Should this message's remote images load without being asked?
+ *
+ * @param   {object} account
+ * @param   {Array<{address?: string}>} from
+ * @returns {boolean}
+ */
+export function sendersImagesTrusted(account, from) {
+    if (account?.rememberImageSenders === false) return false;
+    const trusted = Array.isArray(account?.imageSenders) ? account.imageSenders : [];
+    if (!trusted.length) return false;
+    return (from ?? []).some(entry => trusted.includes(String(entry?.address ?? '').trim().toLowerCase()));
+}
+
+/**
+ * Poll intervals a mailbox may be set to, in minutes.
+ *
+ * A short list on purpose. A free-text field invites someone to type 1 and
+ * spend the day being rate-limited by their mail server, and the difference
+ * between 11 and 12 minutes is not worth a decision.
+ */
+export const POLL_INTERVALS = [3, 5, 10, 15];
+
+/**
+ * Set how often a mailbox is polled.
+ *
+ * `null` means "inherit the plugin default" rather than "never" - there is no
+ * off switch here, because a mailbox that is mirrored but never refreshed is
+ * worse than one that is not mirrored at all.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {number|null} minutes
+ * @returns {Promise<{ok: true, account: object} | {ok: false, error: string}>}
+ */
+export async function setPollInterval(userId, accountId, minutes) {
+    if (minutes !== null && !POLL_INTERVALS.includes(minutes)) {
+        return {ok: false, error: `Poll interval must be one of ${POLL_INTERVALS.join(', ')} minutes.`};
+    }
+
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return {ok: false, error: 'That mailbox does not exist.'};
+
+    all[index] = {...all[index], pollIntervalMinutes: minutes, updatedAt: new Date().toISOString()};
+    await writeAll(all);
+    return {ok: true, account: all[index]};
+}
+
+/**
+ * Every stored mailbox, for every user.
+ *
+ * Only the poller needs this - it runs on a timer with no request and so no
+ * user to scope by. Nothing that serves a request should call it.
+ *
+ * @returns {Promise<object[]>}
+ */
+export async function listAllAccounts() {
+    return readAll();
+}
+
+/**
+ * Choose which folders to keep mirrored.
+ *
+ * `null` means "the sensible default" rather than "none": a mailbox that has
+ * never been configured should still sync its inbox. Only the Pro edition
+ * writes this - the free reader fetches on demand and ignores it entirely.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {string[]|null} folders - explicit paths, or null to go back to the default
+ * @returns {Promise<object|null>} the stored record, or null if not theirs
+ */
+export async function setSyncFolders(userId, accountId, folders) {
+    const all = await readAll();
+    const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+    if (index === -1) return null;
+
+    const value = folders === null
+        ? null
+        : [...new Set(folders.filter(f => typeof f === 'string' && f.trim()))];
+
+    all[index] = {...all[index], syncFolders: value, updatedAt: new Date().toISOString()};
+    await writeAll(all);
+    return all[index];
+}
+
+/**
+ * Validate and normalise submitted account fields.
+ *
+ * @param   {object} input
+ * @param   {object|null} existing
+ * @returns {{ok: true, value: object} | {ok: false, error: string}}
+ */
+export function validate(input, existing) {
+    const host = String(input.host ?? '').trim();
+    const username = String(input.username ?? '').trim();
+    const label = String(input.label ?? '').trim();
+    const port = Number(input.port ?? (input.secure === false ? 143 : 993));
+    const secure = input.secure !== false;
+    const password = typeof input.password === 'string' ? input.password : '';
+
+    if (!host) return {ok: false, error: 'A mail server hostname is required.'};
+    if (!username) return {ok: false, error: 'A username is required.'};
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return {ok: false, error: 'Port must be a whole number between 1 and 65535.'};
+    }
+    if (!password && !existing?.passwordSealed) {
+        return {ok: false, error: 'A password is required.'};
+    }
+
+    return {
+        ok: true,
+        value: {
+            label: label || host,
+            host,
+            port,
+            secure,
+            username,
+            // An empty password on update means "keep the one you have" - the
+            // admin form never round-trips the stored password, so a blank
+            // field is the normal case when editing the hostname.
+            password
+        }
+    };
+}
+
+/**
+ * Every mailbox belonging to one user, oldest first.
+ *
+ * @param   {string} userId
+ * @returns {Promise<object[]>}
+ */
+export async function listAccounts(userId) {
+    const all = await readAll();
+    return all
+        .filter(a => a.userId === userId)
+        .sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+}
+
+/**
+ * One mailbox, but only if this user owns it.
+ *
+ * Takes both ids on purpose: there is no way to ask for an account without
+ * saying who is asking.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @returns {Promise<object|null>}
+ */
+export async function getAccount(userId, accountId) {
+    const all = await readAll();
+    return all.find(a => a.id === accountId && a.userId === userId) ?? null;
+}
+
+/**
+ * Create a mailbox, or update one this user owns.
+ *
+ * @param   {string} userId
+ * @param   {string|null} accountId - null to create
+ * @param   {object} fields - output of validate()
+ * @returns {Promise<object|null>} the stored record, or null if not theirs
+ */
+export async function saveAccount(userId, accountId, fields) {
+    const all = await readAll();
+    const now = new Date().toISOString();
+
+    if (accountId) {
+        const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+        if (index === -1) return null;
+        const existing = all[index];
+        all[index] = {
+            ...existing,
+            label: fields.label,
+            host: fields.host,
+            port: fields.port,
+            secure: fields.secure,
+            username: fields.username,
+            passwordSealed: fields.password ? seal(fields.password) : existing.passwordSealed,
+            updatedAt: now
+        };
+        await writeAll(all);
+        return all[index];
+    }
+
+    const record = {
+        id: randomUUID(),
+        userId,
+        label: fields.label,
+        host: fields.host,
+        port: fields.port,
+        secure: fields.secure,
+        username: fields.username,
+        passwordSealed: seal(fields.password),
+        createdAt: now,
+        updatedAt: now
+    };
+    all.push(record);
+    await writeAll(all);
+    return record;
+}
+
+/**
+ * Remove a mailbox this user owns.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @returns {Promise<boolean>} true when something was removed
+ */
+export async function deleteAccount(userId, accountId) {
+    const all = await readAll();
+    const next = all.filter(a => !(a.id === accountId && a.userId === userId));
+    if (next.length === all.length) return false;
+    await writeAll(next);
+    return true;
+}
+
+/**
+ * Forget every mailbox belonging to one user.
+ *
+ * Called when a CMS user is deleted. Their stored passwords have no owner
+ * left and must not outlive the account.
+ *
+ * @param   {string} userId
+ * @returns {Promise<number>} how many were removed
+ */
+export async function deleteAccountsForUser(userId) {
+    const all = await readAll();
+    const next = all.filter(a => a.userId !== userId);
+    const removed = all.length - next.length;
+    if (removed) await writeAll(next);
+    return removed;
+}
+
+/**
+ * Drop mailboxes whose owner no longer exists.
+ *
+ * The `user:deleted` hook covers the normal case, but only while a plugin
+ * using this core is loaded to hear it - a user deleted while the Mail Reader
+ * was disabled would otherwise leave credentials behind for good. This sweeps
+ * those up on the next start, so the hook is the fast path rather than the
+ * only one.
+ *
+ * @param   {Set<string>|string[]} existingUserIds
+ * @returns {Promise<number>} how many were removed
+ */
+export async function pruneOrphans(existingUserIds) {
+    const live = existingUserIds instanceof Set ? existingUserIds : new Set(existingUserIds);
+    const all = await readAll();
+    const next = all.filter(a => live.has(a.userId));
+    const removed = all.length - next.length;
+    if (removed) await writeAll(next);
+    return removed;
+}
+
+/**
+ * Build an ImapFlow-shaped connection config.
+ *
+ * Throws MailKeyError (from secretbox) if the stored password cannot be
+ * opened - callers surface that message directly, it is written for humans.
+ *
+ * @param   {object} account
+ * @returns {{host: string, port: number, secure: boolean, auth: {user: string, pass: string}}}
+ */
+export function toConnection(account) {
+    return {
+        host: account.host,
+        port: account.port,
+        secure: account.secure,
+        auth: {user: account.username, pass: open(account.passwordSealed)}
+    };
+}