domma-cms 1.10.37 → 1.10.38

package/plugins/_lib/admin/mail/reader-view.js

@@ -35,7 +35,7 @@ const {
 } = await import(versioned('folder-tree.js'));
 const {imageSendersSection} = await import(versioned('image-senders-section.js'));
 const {
-    createSettingsSection, READ_DELAY_KEY, readDelaySeconds, scheduleMarkRead,
+    createSettingsSection, READ_DELAY_KEY, readDelaySeconds, scheduleMarkRead, readComposePrefs,
     PAGE_SIZE_KEY, PAGE_SIZES, listPageSize, pageAfterResize
 } = await import(versioned('settings-section.js'));
 const {createSplitters, fitToViewport} = await import(versioned('panes.js'));
@@ -50,6 +50,8 @@ const {fillMessageAction, loadMessageActions, messageFacts} = await import(versi
 const {isPlainKey, keyBelongsElsewhere, resolveKey, SHORTCUTS} = await import(versioned('keyboard.js'));
 const {menuPoint, quoteSelection, readBridgeMessage, selectionItems} = await import(versioned('body-menu.js'));
 const {describeWhen, quickTimes} = await import(versioned('scheduling.js'));
+// Optional for the same reason as oauth-panel.js below.
+const {securityNote} = await import(versioned('security-note.js')).catch(() => ({securityNote: () => null}));
 // Sign in with Microsoft / Google (Email Pro). Optional: an older copy of this
 // directory without it must not take the reader down.
 const {describeSignIn, mountSignIn} = await import(versioned('oauth-panel.js')).catch(() => ({}));
@@ -958,6 +960,8 @@ return {
             const sections = [
                 createSettingsSection({
                     canWrite: features.write,
+                    canSend: features.send === true,
+                    sidebarUrl: sidebarUrl(pluginName),
                     load: () => readDelaySeconds(S.get(READ_DELAY_KEY)),
                     save: seconds => {
                         S.set(READ_DELAY_KEY, seconds);
@@ -3192,6 +3196,29 @@ return {
 
             readerBodyEl.textContent = '';
 
+            // Signed or encrypted: said first, above the images notice, since
+            // it is about whether to believe the rest of the pane at all.
+            const security = securityNote(message.security);
+            if (security) {
+                const strip = document.createElement('div');
+                strip.className = `mail-notice mail-security mail-security--${security.tone}`;
+                const icon = document.createElement('span');
+                icon.dataset.icon = security.icon;
+                icon.dataset.iconSize = '14';
+                icon.setAttribute('aria-hidden', 'true');
+                const text = document.createElement('span');
+                text.textContent = security.text;
+                strip.append(icon, text);
+                if (security.detail) {
+                    const more = document.createElement('span');
+                    more.className = 'mail-security-detail';
+                    more.textContent = security.detail;
+                    strip.appendChild(more);
+                }
+                readerBodyEl.appendChild(strip);
+                Domma.icons.scan(strip);
+            }
+
             if (message.blockedImages > 0 && !message.remoteImagesLoaded) {
                 const notice = document.createElement('div');
                 notice.className = 'mail-notice';
@@ -3923,7 +3950,11 @@ return {
                     identities: identities?.identities ?? [],
                     mailboxAddress: identities?.mailboxAddress ?? '',
                     templates: templates?.templates ?? [],
-                    undoSendSeconds: sending?.undoSendSeconds ?? 0
+                    undoSendSeconds: sending?.undoSendSeconds ?? 0,
+                    // Where this mailbox's ticks start, and whether it can
+                    // sign or encrypt at all (a certificate is set up).
+                    compose: sending?.compose ?? null,
+                    security: sending?.security ?? null
                 })).catch(() => EMPTY_PROFILE);
             }
             return profileRequest;
@@ -3983,6 +4014,11 @@ return {
                 mailboxAddress: profile?.mailboxAddress ?? '',
                 templates: profile?.templates ?? [],
                 undoSeconds: profile?.undoSendSeconds ?? 0,
+                defaults: profile?.compose ?? null,
+                security: profile?.security ?? null,
+                // Read at each opening, so a change in Settings applies to
+                // the next message without a reload.
+                prefs: readComposePrefs(S),
                 onSent: () => loadMessages({quiet: true}),
                 onQueued: (result) => offerRecall(result),
                 ...extra

package/plugins/_lib/admin/mail/security-note.js

@@ -0,0 +1,68 @@
+/**
+ * What the reader says about a signed or encrypted (S/MIME) message.
+ *
+ * Pure: `security` is the `/messages/:uid` answer's field (readRoutes.js
+ * `publicSecurity`), and the result is plain text for the strip above the
+ * message. The wording separates the three things a signature can mean -
+ * the message is unchanged, the signer is who a trusted authority says, and
+ * the signer is the sender shown - because "signed" alone promises all three
+ * and a self-made certificate gives only the first.
+ *
+ * @module _lib/admin/mail/security-note
+ */
+
+/**
+ * @param   {object|null} security
+ * @returns {{tone: 'ok'|'warn'|'bad', icon: string, text: string, detail: string}|null}
+ */
+export function securityNote(security) {
+    if (!security || (!security.signed && !security.encrypted)) return null;
+
+    if (security.encrypted && !security.decrypted) {
+        return {
+            tone: 'bad', icon: 'lock',
+            text: 'Encrypted - this message could not be opened.',
+            detail: security.problem || 'None of your certificates can open it. Add the certificate it was encrypted to in Settings > Security.'
+        };
+    }
+
+    const parts = [];
+    if (security.encrypted) parts.push('Encrypted');
+    let tone = 'ok';
+    let detail = '';
+
+    if (security.signed) {
+        const who = security.signer?.emails?.[0] || security.signer?.subject || 'an unknown signer';
+        if (!security.verified) {
+            tone = 'bad';
+            parts.push('the signature is NOT valid');
+            detail = security.problem || 'The message may have been changed after it was signed.';
+        } else if (!security.trusted) {
+            tone = 'warn';
+            parts.push(`signed by ${who}, whose certificate is not from an authority this server trusts`);
+            detail = 'The message is unchanged since it was signed, but anyone can make a certificate with any address in it. '
+                + 'Check the fingerprint with the sender if it matters.';
+        } else if (!security.fromMatches) {
+            tone = 'warn';
+            parts.push(`signed by ${who}, which is not the sender shown`);
+            detail = 'The signature is valid, but it belongs to a different address than the From line.';
+        } else {
+            parts.push(`signed by ${who}`);
+            detail = 'The signature is valid and the message is unchanged since it was signed.';
+        }
+        if (security.verified && security.problem && tone === 'ok') detail = security.problem;
+        if (security.signer?.fingerprint) {
+            detail += ` Certificate fingerprint (SHA-256): ${security.signer.fingerprint}.`;
+        }
+    } else {
+        detail = 'Only you and the other recipients can read it.';
+    }
+
+    const text = parts.join(', ');
+    return {
+        tone,
+        icon: tone !== 'ok' ? 'shield-alert' : (security.encrypted ? 'lock' : 'shield-check'),
+        text: `${text.charAt(0).toUpperCase()}${text.slice(1)}.`,
+        detail: detail.trim()
+    };
+}

package/plugins/_lib/admin/mail/settings-section.js

@@ -1,5 +1,11 @@
 /** Browser preferences for the shared mail reader. */
 export const READ_DELAY_KEY = 'domma-mail.mark-read-seconds';
+/** Compose preferences - this browser's, like the rest of this tab. */
+export const EDITOR_KEY = 'domma-mail.compose-editor';
+export const AUTOSAVE_KEY = 'domma-mail.autosave-minutes';
+export const SPELLCHECK_KEY = 'domma-mail.spellcheck';
+/** The choices for saving a draft automatically, in minutes; 0 is never. */
+export const AUTOSAVE_CHOICES = [0, 1, 2, 5, 10];
 export const DEFAULT_READ_DELAY_SECONDS = 1;
 export const PAGE_SIZE_KEY = 'domma-mail.page-size';
 /** The choices offered under the list. 200 is the server's maxListLimit. */
@@ -50,39 +56,220 @@ export function scheduleMarkRead(markRead, seconds, schedule = setTimeout) {
     return schedule(markRead, delay * 1000);
 }
 
-export function createSettingsSection({canWrite, load, save}) {
+/**
+ * The editor a new message opens in: 'rich' (formatting, sent as HTML with a
+ * plain-text part) unless this browser chose 'plain'.
+ *
+ * @param   {*} value
+ * @returns {'rich'|'plain'}
+ */
+export function composeEditor(value) {
+    return value === 'plain' ? 'plain' : 'rich';
+}
+
+/**
+ * Minutes between automatic draft saves; 0 (never) for anything not offered.
+ *
+ * @param   {*} value
+ * @returns {number}
+ */
+export function autosaveMinutes(value) {
+    const minutes = Number(value);
+    return AUTOSAVE_CHOICES.includes(minutes) ? minutes : 0;
+}
+
+/**
+ * Whether the browser checks spelling as you type. On unless switched off,
+ * which is the browser's own default for a text field.
+ *
+ * @param   {*} value
+ * @returns {boolean}
+ */
+export function spellcheckOn(value) {
+    return value !== false;
+}
+
+/**
+ * This browser's compose preferences, every key present.
+ *
+ * @param   {{get: Function}} store - Domma's S
+ * @returns {{editor: 'rich'|'plain', autosaveMinutes: number, spellcheck: boolean}}
+ */
+export function readComposePrefs(store) {
+    const read = key => { try { return store?.get(key); } catch { return undefined; } };
+    return {
+        editor: composeEditor(read(EDITOR_KEY)),
+        autosaveMinutes: autosaveMinutes(read(AUTOSAVE_KEY)),
+        spellcheck: spellcheckOn(read(SPELLCHECK_KEY))
+    };
+}
+
+/**
+ * The browser's own answer to "may this site show notifications?", in words.
+ *
+ * @param   {string|undefined} permission - Notification.permission
+ * @returns {string}
+ */
+export function permissionWords(permission) {
+    if (permission === 'granted') return 'This browser allows notifications from this site.';
+    if (permission === 'denied') return 'This browser blocks notifications from this site. Allow them in the browser\u2019s site settings (the padlock by the address).';
+    if (permission === 'default') return 'This browser has not been asked yet - turning popups on asks it.';
+    return 'This browser cannot show notifications.';
+}
+
+/**
+ * The Settings tab: preferences kept in this browser.
+ *
+ * @param   {{canWrite: boolean, canSend?: boolean, load: Function, save: Function,
+ *            sidebarUrl?: string|null, userId?: string|null}} options
+ *          `sidebarUrl` is this edition's sidebar entry, which is what new-mail
+ *          notifications hang off (admin/js/lib/sidebar-notify.js).
+ * @returns {object}
+ */
+export function createSettingsSection({canWrite, canSend = false, load, save, sidebarUrl = null, userId = null}) {
     return {
         id: 'settings',
         label: 'Settings',
-        help: 'Preferences for reading email in this browser.',
+        help: 'Preferences for reading and writing email in this browser.',
         async render(container, ctx) {
             const kit = await import(new URL(`./section-kit.js?v=${ctx.assetVersion ?? '1'}`, import.meta.url).href);
+            // Optional: a core older than the notifications leaves that part out.
+            const notify = sidebarUrl
+                ? await import('/admin/js/lib/sidebar-notify.js').catch(() => null)
+                : null;
+            // The same user id the sidebar keys its notifications by.
+            const who = userId ?? (await import('/admin/js/api.js').catch(() => null))?.getUser?.()?.id ?? null;
             kit.note(container, 'Settings are saved in this browser and apply to all your mailboxes.');
+
+            const saveSteps = [];
+
+            // ---- Reading -------------------------------------------------
+            kit.heading(container, 'Reading');
             if (!canWrite) {
                 kit.note(container, 'This reader leaves messages unread. Automatic marking as read requires an edition that can update messages.');
-                return;
+            } else {
+                const {state} = kit.formIn(container, {
+                    markReadSeconds: {
+                        type: 'number',
+                        label: 'How long before a message is marked as read? (seconds)',
+                        required: true,
+                        min: 0,
+                        max: 2147483,
+                        formConfig: {hint: '0 marks a message as read immediately. Otherwise, it must stay open for this long.'}
+                    }
+                }, {markReadSeconds: load()});
+                saveSteps.push(() => {
+                    const value = state.markReadSeconds;
+                    const seconds = Number(value);
+                    if (value === '' || value === null || value === undefined || !Number.isFinite(seconds) || seconds < 0 || seconds > 2147483) {
+                        throw new Error('Enter a number of seconds between 0 and 2147483.');
+                    }
+                    return () => save(seconds);
+                });
+            }
+
+            // ---- Composing -----------------------------------------------
+            if (canSend) {
+                kit.heading(container, 'Composing');
+                const prefs = readComposePrefs(S);
+                const {state} = kit.formIn(container, {
+                    editor: {
+                        type: 'select', label: 'Default text editor', required: true,
+                        options: [
+                            {value: 'rich', label: 'Rich text (formatting, pictures, links)'},
+                            {value: 'plain', label: 'Plain text'}
+                        ],
+                        formConfig: {hint: 'What a new message, reply or forward opens in. Plain text sends text only - what every mail program shows the same way.'}
+                    },
+                    autosave: {
+                        type: 'select', label: 'Automatically save draft', required: true,
+                        // Strings: Forma reads a 0 as "no value" and shows its
+                        // "-- Select --" placeholder instead of Never.
+                        options: AUTOSAVE_CHOICES.map(n => ({
+                            value: String(n), label: n === 0 ? 'Never' : `Every ${n} minute${n === 1 ? '' : 's'}`
+                        })),
+                        formConfig: {hint: 'Saved to the Drafts folder while you write, so a closed tab or a crash loses little. A message you then discard takes its automatic draft with it.'}
+                    },
+                    spellcheck: {type: 'boolean', label: 'Check spelling as I type'}
+                }, {editor: prefs.editor, autosave: String(prefs.autosaveMinutes), spellcheck: prefs.spellcheck});
+                saveSteps.push(() => () => {
+                    S.set(EDITOR_KEY, composeEditor(state.editor));
+                    S.set(AUTOSAVE_KEY, autosaveMinutes(state.autosave));
+                    S.set(SPELLCHECK_KEY, state.spellcheck !== false);
+                });
+                kit.note(container, 'Receipts, signing, encryption and where replies are filed belong to each mailbox: see the Composing and Security tabs.');
             }
-            const {state} = kit.formIn(container, {
-                markReadSeconds: {
-                    type: 'number',
-                    label: 'How long before a message is marked as read? (seconds)',
-                    required: true,
-                    min: 0,
-                    max: 2147483,
-                    formConfig: {hint: '0 marks a message as read immediately. Otherwise, it must stay open for this long.'}
+
+            // ---- Notifications -------------------------------------------
+            if (notify) {
+                kit.heading(container, 'Notifications');
+                kit.note(container, 'While the admin is open in any tab, new mail in the inbox can pop up a notification and play a sound - checked about once a minute.');
+                const current = notify.readNotifyPrefs(who, sidebarUrl);
+                const supported = typeof Notification === 'function';
+                const {state} = kit.formIn(container, {
+                    popup: {type: 'boolean', label: 'Show new messages notification popups', formConfig: {disabled: !supported}},
+                    sound: {type: 'boolean', label: 'Sound notification'}
+                }, {popup: current.popup && supported, sound: current.sound});
+                const status = kit.note(container, permissionWords(supported ? Notification.permission : undefined));
+                const tools = kit.box(container, 'flex gap-2 items-center mb-2');
+                kit.button(tools, 'Play the sound', () => notify.playChime(), {icon: 'play'});
+                if (supported) {
+                    kit.button(tools, 'Show a test notification', async () => {
+                        if (Notification.permission === 'default') await Notification.requestPermission();
+                        status.textContent = permissionWords(Notification.permission);
+                        if (Notification.permission === 'granted') {
+                            new Notification('New mail', {body: 'This is what a new message looks like.', tag: `dm-notify:${sidebarUrl}`});
+                        }
+                    }, {icon: 'bell'});
                 }
-            }, {markReadSeconds: load()});
+                saveSteps.push(() => async () => {
+                    let popup = state.popup === true && supported;
+                    // Asked here, on the Save click: browsers only let a page
+                    // ask in answer to something the person did.
+                    if (popup && Notification.permission === 'default') {
+                        await Notification.requestPermission();
+                        status.textContent = permissionWords(Notification.permission);
+                    }
+                    if (popup && Notification.permission === 'denied') popup = false;
+                    notify.writeNotifyPrefs(who, sidebarUrl, {popup, sound: state.sound === true});
+                });
+            }
+
+            // ---- Email links ---------------------------------------------
+            if (canSend && typeof navigator?.registerProtocolHandler === 'function') {
+                kit.heading(container, 'Email links');
+                kit.note(container, 'Make this browser open mailto: links - on any website - in a new message here, instead of in a mail program on this computer. The browser asks you to confirm. To undo it, use the browser\u2019s settings (in Chrome: Settings > Privacy and security > Site settings > Protocol handlers).');
+                const linkRow = kit.box(container, 'flex gap-2 items-center mb-2');
+                const linkStatus = kit.box(linkRow, 'flex-1 text-sm mail-status text-muted', 'span');
+                kit.button(linkRow, 'Register as the mailto: links handler', async () => {
+                    try {
+                        const mail = await import('/admin/js/lib/mail-compose.js');
+                        navigator.registerProtocolHandler('mailto', mail.mailtoHandlerUrl(`${location.origin}${location.pathname}`));
+                        linkStatus.textContent = 'Asked. If the browser showed a question, answer it to finish.';
+                    } catch (err) {
+                        linkStatus.textContent = /secure|https/i.test(err?.message ?? '')
+                            ? 'Only a site served over https can handle mailto: links.'
+                            : (err?.message || 'This browser would not register it.');
+                    }
+                }, {icon: 'mail'});
+            }
+
+            if (!saveSteps.length) return;
             const bar = kit.actionBar(container);
-            kit.button(bar.row, 'Save', () => {
-                const value = state.markReadSeconds;
-                const seconds = Number(value);
-                if (value === '' || value === null || value === undefined || !Number.isFinite(seconds) || seconds < 0 || seconds > 2147483) {
-                    bar.say('Enter a number of seconds between 0 and 2147483.', 'bad');
+            kit.button(bar.row, 'Save', async () => {
+                // Every value checked before anything is stored: a bad number
+                // must not leave half the tab saved.
+                let apply;
+                try {
+                    apply = saveSteps.map(step => step());
+                } catch (err) {
+                    bar.say(err.message, 'bad');
                     return;
                 }
                 try {
-                    save(seconds);
+                    for (const run of apply) await run();
                     bar.say('Saved.', 'ok');
+                    await ctx.changed?.();
                 } catch (err) {
                     bar.say(err.message || 'Settings could not be saved.', 'bad');
                 }

package/plugins/_lib/mail/accounts.js

@@ -725,6 +725,65 @@ export async function setSendingOptions(userId, accountId, options) {
     });
 }
 
+/**
+ * How a new message from this mailbox starts out, and two rules about where
+ * and how it leaves.
+ *
+ * All off by default, which is what every message sent before these existed
+ * did. The receipts, signing and encryption are only where the compose
+ * window's ticks START - each message can still change them. The other two
+ * are the mailbox's rules and apply to every message:
+ * `repliesInSourceFolder` files the copy of a reply beside the message it
+ * answers instead of in Sent, and `requireSecureDelivery` refuses to send
+ * unless the outgoing server promises TLS all the way (REQUIRETLS, RFC 8689).
+ */
+export const COMPOSE_DEFAULTS = Object.freeze({
+    readReceipt: false,
+    deliveryReceipt: false,
+    sign: false,
+    encrypt: false,
+    repliesInSourceFolder: false,
+    requireSecureDelivery: false
+});
+
+/**
+ * This mailbox's compose options, every key present.
+ *
+ * @param   {object|null} account
+ * @returns {typeof COMPOSE_DEFAULTS}
+ */
+export function composeOptions(account) {
+    const stored = account?.compose && typeof account.compose === 'object' ? account.compose : {};
+    return Object.fromEntries(Object.keys(COMPOSE_DEFAULTS)
+        .map(key => [key, stored[key] === true]));
+}
+
+/**
+ * Store the compose options. Only the known switches, only as booleans; a key
+ * left out keeps its stored value, so a screen that knows half of them cannot
+ * switch the other half off.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {object} options
+ * @returns {Promise<object|null>}
+ */
+export async function setComposeOptions(userId, accountId, options) {
+    return withStoreLock(async () => {
+        const all = await readAll();
+        const index = all.findIndex(a => a.id === accountId && a.userId === userId);
+        if (index === -1) return null;
+
+        const next = composeOptions(all[index]);
+        for (const key of Object.keys(COMPOSE_DEFAULTS)) {
+            if (typeof options?.[key] === 'boolean') next[key] = options[key];
+        }
+        all[index] = {...all[index], compose: next, updatedAt: new Date().toISOString()};
+        await writeAll(all);
+        return all[index];
+    });
+}
+
 /**
  * Every address this mailbox sends as.
  *

package/plugins/_lib/mail/compose.js

@@ -10,7 +10,7 @@
  * @module _lib/mail/compose
  */
 import {readPriority} from './priority.js';
-import {normaliseMessageSource, readMessageSource} from './message-action.js';
+import {normaliseMessageSource, readComposeFlags, readMessageSource} from './message-action.js';
 
 /**
  * Addresses to reply to.
@@ -237,6 +237,10 @@ export function editableDraft(message, uid = null) {
         // Kept, or a draft marked urgent would quietly become ordinary the
         // moment it was reopened.
         priority: readPriority(message.headers),
+        // Both kept for the same reason: a draft that asked for a receipt, or
+        // to be signed or encrypted, must not quietly stop asking on reopen.
+        readReceipt: hasHeader(message.headers, 'disposition-notification-to'),
+        ...readComposeFlags(message.headers),
         attachments: (message.attachments ?? []).map(file => ({
             filename: file.filename ?? 'attachment',
             contentType: file.contentType ?? 'application/octet-stream',
@@ -248,6 +252,16 @@ export function editableDraft(message, uid = null) {
     };
 }
 
+/**
+ * @param   {Map|object|undefined} headers - mailparser's headers
+ * @param   {string} name - lower case
+ * @returns {boolean}
+ */
+function hasHeader(headers, name) {
+    const value = typeof headers?.get === 'function' ? headers.get(name) : headers?.[name];
+    return value !== undefined && value !== null && value !== '';
+}
+
 /**
  * References arrive as a string on one server and an array on the next.
  *

package/plugins/_lib/mail/message-action.js

@@ -22,6 +22,38 @@ export function readMessageSource(headers) {
     } catch { return null; }
 }
 
+/**
+ * The compose ticks a saved draft carries - delivery receipt, sign, encrypt -
+ * none of which leaves a trace a reopened draft could read back otherwise
+ * (the read receipt does: its own header). Private, like SOURCE_HEADER: only
+ * ever written into a draft, never onto a message that is sent.
+ */
+export const COMPOSE_HEADER = 'X-Domma-Compose';
+const COMPOSE_FLAGS = ['deliveryReceipt', 'sign', 'encrypt'];
+
+/**
+ * @param   {object} draft
+ * @returns {string|null} the header value, or null when nothing is ticked
+ */
+export function composeFlagsHeader(draft) {
+    const on = COMPOSE_FLAGS.filter(key => draft?.[key] === true);
+    return on.length ? Buffer.from(JSON.stringify(Object.fromEntries(on.map(k => [k, true])))).toString('base64url') : null;
+}
+
+/**
+ * @param   {Map|object} headers - mailparser's headers
+ * @returns {{deliveryReceipt: boolean, sign: boolean, encrypt: boolean}}
+ */
+export function readComposeFlags(headers) {
+    const value = typeof headers?.get === 'function'
+        ? headers.get(COMPOSE_HEADER.toLowerCase()) : headers?.[COMPOSE_HEADER.toLowerCase()];
+    let parsed = {};
+    if (typeof value === 'string' && value.length <= 512) {
+        try { parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8')) ?? {}; } catch { parsed = {}; }
+    }
+    return Object.fromEntries(COMPOSE_FLAGS.map(key => [key, parsed[key] === true]));
+}
+
 /** Best effort: recording a delivered message must never turn it into a failed send. */
 export async function recordMessageAction({source, account, pool, poolKey, connection, store = null}) {
     source = normaliseMessageSource(source);

package/plugins/_lib/mail/messageSecurity.js

@@ -0,0 +1,111 @@
+/**
+ * Where signing and encryption plug into the mail core.
+ *
+ * The core builds, sends, files and reads raw messages; it does not know
+ * S/MIME. An edition that does (Email Pro) registers a provider here at boot,
+ * and every path that sends - the send route, the scheduler behind undo and
+ * send-later - or reads a message body goes through it. A registry rather
+ * than an option threaded through each caller, because the scheduler is core
+ * code started by the edition and would otherwise need the provider passed
+ * down three layers to reach the one call that uses it.
+ *
+ * The provider:
+ *   protect({raw, draft, account, userId}) -> Promise<Buffer>
+ *       the message as it should leave and be filed; called only when the
+ *       draft asks for `sign` or `encrypt`. Throws a plain Error to refuse.
+ *   protectDraft({raw, draft, account, userId}) -> Promise<Buffer>   (optional)
+ *       a draft of a message to be encrypted, encrypted to the sender alone.
+ *   unwrap({raw, account, userId}) -> Promise<{raw: Buffer, security: object|null}>
+ *       the message as it should be read; never throws for a bad message,
+ *       it says so in `security.problem` and hands the original back.
+ *
+ * @module _lib/mail/messageSecurity
+ */
+import {simpleParser} from 'mailparser';
+
+let provider = null;
+
+/**
+ * Register (or, with null, remove) the provider. One at a time: the editions
+ * never run together.
+ *
+ * @param   {{protect: Function, unwrap: Function}|null} next
+ * @returns {void}
+ */
+export function setMessageSecurity(next) {
+    provider = next && typeof next.protect === 'function' && typeof next.unwrap === 'function' ? next : null;
+}
+
+/** @returns {boolean} whether a message can be signed or encrypted here */
+export function canProtect() {
+    return provider !== null;
+}
+
+/**
+ * The message as it should leave. A draft that asks for neither comes back as
+ * it was; one that asks with no provider registered is refused, because
+ * sending it unprotected is the one outcome the sender ruled out.
+ *
+ * @param   {{raw: Buffer, draft: object, account?: object|null, userId?: string|null}} input
+ * @returns {Promise<Buffer>}
+ */
+export async function protectRaw(input) {
+    const wanted = input.draft?.sign === true || input.draft?.encrypt === true;
+    if (!wanted) return input.raw;
+    if (!provider) {
+        throw new Error('Signing and encryption need Email Pro with a certificate set up. The message was not sent.');
+    }
+    return provider.protect(input);
+}
+
+/**
+ * A draft as it should be stored: encrypted to the sender alone when the
+ * message is to be encrypted and the provider can (`protectDraft`), so the
+ * Drafts folder - which every client syncs - does not hold the plain text of
+ * a message meant to be secret. Otherwise, and on any failure, as it was: a
+ * draft that cannot be saved is worse, and the send itself still refuses to
+ * go out unencrypted.
+ *
+ * @param   {{raw: Buffer, draft: object, account?: object|null, userId?: string|null}} input
+ * @returns {Promise<Buffer>}
+ */
+export async function protectDraftRaw(input) {
+    if (input.draft?.encrypt !== true || typeof provider?.protectDraft !== 'function') return input.raw;
+    try {
+        return (await provider.protectDraft(input)) ?? input.raw;
+    } catch {
+        return input.raw;
+    }
+}
+
+/**
+ * The message as it should be read.
+ *
+ * @param   {{raw: Buffer, account?: object|null, userId?: string|null}} input
+ * @returns {Promise<{raw: Buffer, security: object|null}>}
+ */
+export async function unwrapRaw(input) {
+    if (!provider) return {raw: input.raw, security: null};
+    try {
+        const result = await provider.unwrap(input);
+        return result?.raw ? result : {raw: input.raw, security: null};
+    } catch {
+        // A provider fault must never cost the reader the message itself.
+        return {raw: input.raw, security: null};
+    }
+}
+
+/**
+ * Parse a message as it should be read: unwrapped first, then mailparser.
+ * Every route that shows, quotes or hands off a message's content goes
+ * through this, so an encrypted message reads the same in the pane, in a
+ * reply's quote and in its attachments.
+ *
+ * @param   {Buffer} raw
+ * @param   {{account?: object|null, userId?: string|null}} [context]
+ * @returns {Promise<{parsed: object, security: object|null}>}
+ */
+export async function parseReadable(raw, {account = null, userId = null} = {}) {
+    const {raw: readable, security} = await unwrapRaw({raw, account, userId});
+    return {parsed: await simpleParser(readable), security};
+}