domma-cms 0.55.1 → 0.66.0

package/plugins/_lib/mail/sync.js

@@ -0,0 +1,292 @@
+/**
+ * Bringing a folder's local mirror up to date.
+ *
+ * The decision lives in `syncPlan.js`, which is pure and tested on its own.
+ * This is the half that talks to IMAP and MongoDB and carries the plan out.
+ *
+ * ## Still read-only
+ *
+ * Sync opens mailboxes exactly as the reader does - `EXAMINE`, and fetches
+ * through `BODY.PEEK[]` - so mirroring a mailbox never marks anything read.
+ * Writing flags is a separate, deliberate operation that does not belong here.
+ *
+ * ## Envelopes only
+ *
+ * Nothing in this module fetches a message body. The mirror is what a list
+ * view needs; bodies are fetched per view and rendered through the sanitiser,
+ * so a compromised store leaks metadata rather than correspondence.
+ *
+ * @module _lib/mail/sync
+ */
+import * as accounts from './accounts.js';
+import {applyRules, eligible} from './ruleRunner.js';
+import {runVacation} from './vacationRunner.js';
+import {missingUids, planFolderSync} from './syncPlan.js';
+import {resolveSyncFolders} from './syncSelection.js';
+import {ENVELOPE_QUERY, toRecord} from './envelope.js';
+
+/**
+ * Sync one folder.
+ *
+ * @param   {object} client - a connected ImapFlow, mailbox already locked
+ * @param   {object} store
+ * `collectAdded` asks for the records of whatever was newly fetched, so the
+ * caller can run filing rules over them. Off by default and capped, because
+ * the whole point of batching is not to hold a folder in memory - a mailbox
+ * catching up on ten thousand messages must not build a ten thousand element
+ * array to decide none of them matched a rule.
+ *
+ * @param   {{accountId: string, path: string, batchSize?: number, now?: number,
+ *            collectAdded?: boolean, collectLimit?: number}} options
+ * @returns {Promise<{mode: string, reason: string, added: number, flagged: number,
+ *                    removed: number, addedMessages: object[]}>}
+ */
+export async function syncFolder(client, store, {
+    accountId, path, batchSize = 500, now = Date.now(),
+    collectAdded = false, collectLimit = 200
+}) {
+    const mailbox = client.mailbox;
+    const server = {
+        uidValidity: mailbox.uidValidity,
+        uidNext: mailbox.uidNext,
+        exists: mailbox.exists,
+        highestModseq: mailbox.highestModseq ?? null
+    };
+
+    const stored = await store.getFolder(accountId, path);
+    const plan = planFolderSync(stored, server, {now});
+
+    const result = {mode: plan.mode, reason: plan.reason, added: 0, flagged: 0, removed: 0, addedMessages: []};
+    if (plan.mode === 'none') return result;
+
+    // Never collected on a full resync: that is the whole folder arriving
+    // again, not new mail, and filing it would move an archive.
+    const collect = collectAdded && plan.mode !== 'full' ? result.addedMessages : null;
+
+    if (plan.mode === 'full') {
+        // The stored UIDs are meaningless now, so they go before anything new
+        // arrives - leaving them would mix two generations of the same folder.
+        await store.clearFolder(accountId, path);
+        result.added = await fetchRange(client, store, accountId, path, '1:*', batchSize);
+    } else {
+        if (plan.fetchFrom !== null) {
+            result.added = await fetchRange(
+                client, store, accountId, path, `${plan.fetchFrom}:*`, batchSize,
+                collect, collectLimit,
+                // The floor is the point. In an IMAP UID range `*` is the
+                // HIGHEST EXISTING UID, not infinity - so `101:*` on a folder
+                // whose highest UID is 100 is read as `100:101` and returns
+                // UID 100, a message that was already here. Harmless for the
+                // mirror, which just rewrites a row it already had; not
+                // harmless for rules, which would fire again on mail the user
+                // had deliberately left alone.
+                plan.fetchFrom
+            );
+        }
+
+        if (plan.flagScan !== 'none') {
+            result.flagged = await scanFlags(client, store, accountId, path, plan);
+        }
+
+        if (plan.reconcile) {
+            result.removed = await reconcile(client, store, accountId, path);
+        }
+    }
+
+    await store.saveFolder(accountId, path, {
+        uidValidity: String(server.uidValidity),
+        uidNext: Number(server.uidNext),
+        exists: Number(server.exists),
+        highestModseq: server.highestModseq ? String(server.highestModseq) : null,
+        lastSyncAt: new Date(now),
+        ...(plan.mode === 'full' || plan.reconcile ? {lastReconcileAt: now} : {})
+    });
+
+    return result;
+}
+
+/**
+ * Fetch envelopes for a UID range, writing them in batches.
+ *
+ * Batched so a mailbox with tens of thousands of messages does not build one
+ * enormous array before anything is stored.
+ *
+ * @param   {object} client
+ * @param   {object} store
+ * @param   {string} accountId
+ * @param   {string} path
+ * @param   {string} range
+ * @param   {number} batchSize
+ * @param   {object[]|null} [collect] - records are pushed here when given
+ * @param   {number} [collectLimit]
+ * @param   {number} [collectFrom] - only collect UIDs at or above this
+ * @returns {Promise<number>}
+ */
+async function fetchRange(
+    client, store, accountId, path, range, batchSize,
+    collect = null, collectLimit = 200, collectFrom = 0
+) {
+    let batch = [];
+    let written = 0;
+
+    for await (const message of client.fetch(range, ENVELOPE_QUERY, {uid: true})) {
+        const record = toRecord(message);
+        // Collected only when it is genuinely new. See the note at the call
+        // site: an IMAP `n:*` range can hand back a UID below `n`.
+        if (collect && collect.length < collectLimit && record.uid >= collectFrom) {
+            collect.push(record);
+        }
+        batch.push(record);
+        if (batch.length >= batchSize) {
+            await store.putMessages(accountId, path, batch);
+            written += batch.length;
+            batch = [];
+        }
+    }
+
+    if (batch.length) {
+        await store.putMessages(accountId, path, batch);
+        written += batch.length;
+    }
+    return written;
+}
+
+/**
+ * Bring stored flags back in line with the server's.
+ *
+ * @param   {object} client
+ * @param   {object} store
+ * @param   {string} accountId
+ * @param   {string} path
+ * @param   {object} plan
+ * @returns {Promise<number>}
+ */
+async function scanFlags(client, store, accountId, path, plan) {
+    const query = {uid: true, flags: true};
+    const options = {uid: true};
+    // CONDSTORE lets the server send only what moved, which on a large folder
+    // is the difference between a few rows and all of them.
+    if (plan.flagScan === 'changed' && plan.changedSince) {
+        options.changedSince = BigInt(plan.changedSince);
+    }
+
+    const updates = [];
+    for await (const message of client.fetch('1:*', query, options)) {
+        updates.push({uid: message.uid, flags: [...(message.flags ?? [])]});
+    }
+    return store.setFlags(accountId, path, updates);
+}
+
+/**
+ * Drop messages the server no longer lists.
+ *
+ * @param   {object} client
+ * @param   {object} store
+ * @param   {string} accountId
+ * @param   {string} path
+ * @returns {Promise<number>}
+ */
+async function reconcile(client, store, accountId, path) {
+    const onServer = [];
+    for await (const message of client.fetch('1:*', {uid: true}, {uid: true})) {
+        onServer.push(message.uid);
+    }
+
+    const stored = await store.storedUids(accountId, path);
+    const gone = missingUids(stored, onServer);
+    return store.removeMessages(accountId, path, gone);
+}
+
+/**
+ * Mirror every folder one mailbox has chosen.
+ *
+ * Shared by the manual "sync now" route and the background poller, so the two
+ * cannot drift into disagreeing about what a sync pass means.
+ *
+ * @param   {{pool: object, store: object, account: object, config: object}} deps
+ * @returns {Promise<{selection: string, folders: Object.<string, object>}>}
+ */
+export async function syncAccount({pool, store, account, config}) {
+    const connection = accounts.toConnection(account);
+    const poolKey = `${account.userId}:${account.id}`;
+
+    const list = await pool.withClient(poolKey, connection, client => client.list());
+    const folders = list
+        .filter(box => !box.flags?.has('\\Noselect'))
+        .map(box => ({path: box.path, specialUse: box.specialUse ?? null}));
+
+    const {paths, source} = resolveSyncFolders(account, folders);
+    const results = {};
+
+    const rules = accounts.rulesToPublic(account).filter(rule => rule.enabled);
+    const ruleFolders = new Set(rules.length ? accounts.ruleFolders(account) : []);
+
+    // The away message answers mail arriving in the same folders rules run
+    // over - which is the inbox by default. Answering mail that arrived in
+    // Sent, or in an archive a rule had just filed it into, is not what
+    // "I am away" means.
+    const away = accounts.vacationToPublic(account);
+    const awayFolders = new Set(away.enabled ? accounts.ruleFolders(account) : []);
+
+    for (const folderPath of paths) {
+        const filed = ruleFolders.has(folderPath) || awayFolders.has(folderPath);
+        try {
+            results[folderPath] = await pool.withMailbox(poolKey, connection, folderPath,
+                client => syncFolder(client, store, {
+                    accountId: account.id,
+                    path: folderPath,
+                    batchSize: config.syncBatchSize,
+                    collectAdded: filed
+                }));
+        } catch (err) {
+            // One bad folder must not abandon the rest of the mailbox.
+            results[folderPath] = {mode: 'error', reason: err.message};
+            continue;
+        }
+
+        // Outside the `withMailbox` above, deliberately: filing a message
+        // opens its destination on the same connection, and ImapFlow queues
+        // mailbox locks per client - doing it inside would wait on a lock
+        // this very call is holding.
+        if (!filed) continue;
+        const candidates = eligible(results[folderPath].addedMessages, results[folderPath], account.rulesFrom ?? null);
+        if (!candidates.length) continue;
+
+        if (ruleFolders.has(folderPath)) {
+            try {
+                results[folderPath].rules = await applyRules({
+                    pool, store, account, poolKey, connection,
+                    folder: folderPath, messages: candidates, rules
+                });
+            } catch (err) {
+                results[folderPath].rules = {error: err.message};
+            }
+        }
+
+        // After the rules, on the same candidates. A message a rule has just
+        // filed into Junk should not also get a cheerful note saying when its
+        // sender can expect a reply.
+        if (awayFolders.has(folderPath)) {
+            const junked = new Set(
+                (results[folderPath].rules?.actions ?? []).map(action => action.uid)
+            );
+            try {
+                results[folderPath].away = await runVacation({
+                    pool, store, account, poolKey, connection,
+                    smtp: accounts.toSmtpConnection(account),
+                    messages: candidates.filter(message => !junked.has(message.uid)),
+                    config,
+                    addresses: accounts.sendingAddresses(account)
+                });
+            } catch (err) {
+                results[folderPath].away = {error: err.message};
+            }
+        }
+    }
+
+    // The collected records have done their job and would otherwise be
+    // reported back to a diagnostics screen as a wall of envelopes.
+    for (const result of Object.values(results)) delete result.addedMessages;
+
+    return {selection: source, folders: results};
+}

package/plugins/_lib/mail/syncPlan.js

@@ -0,0 +1,126 @@
+/**
+ * Deciding what a folder sync needs to do.
+ *
+ * Kept pure and separate from the IMAP and database calls, because this is
+ * where sync gets subtly wrong and a wrong answer is expensive: too eager and
+ * every poll refetches a 40,000-message mailbox, too lazy and someone's inbox
+ * quietly stops matching their phone.
+ *
+ * The inputs are what we recorded last time and what the server says now. The
+ * output says which of the four things to do, and why - the reason is carried
+ * so a log line can explain a resync rather than just performing one.
+ *
+ * @module _lib/mail/syncPlan
+ */
+
+/** How long before a folder is reconciled even when nothing looks changed. */
+export const DEFAULT_RECONCILE_INTERVAL_MS = 3_600_000;
+
+/**
+ * Compare two IMAP 64-bit counters that may arrive as number, string or BigInt.
+ *
+ * MODSEQ and UIDVALIDITY are unsigned 64-bit, so a driver may hand them over
+ * as any of those. Comparing a BigInt with a Number throws in some operators
+ * and silently loses precision in others, so everything is normalised first.
+ *
+ * @param   {number|string|bigint|null|undefined} a
+ * @param   {number|string|bigint|null|undefined} b
+ * @returns {number} -1, 0 or 1; 0 when either is absent
+ */
+export function compareCounters(a, b) {
+    if (a === null || a === undefined || b === null || b === undefined) return 0;
+    const left = BigInt(a);
+    const right = BigInt(b);
+    if (left < right) return -1;
+    if (left > right) return 1;
+    return 0;
+}
+
+/**
+ * Work out what this folder needs.
+ *
+ * @param   {object|null} stored - the folder record, or null if never synced
+ * @param   {{uidValidity: any, uidNext: number, exists: number, highestModseq?: any}} server
+ * @param   {{now?: number, reconcileIntervalMs?: number}} [options]
+ * @returns {{mode: 'full'|'incremental'|'none', reason: string,
+ *            fetchFrom: number|null, flagScan: 'none'|'full'|'changed',
+ *            changedSince: any, reconcile: boolean}}
+ */
+export function planFolderSync(stored, server, options = {}) {
+    const {now = Date.now(), reconcileIntervalMs = DEFAULT_RECONCILE_INTERVAL_MS} = options;
+
+    const full = reason => ({
+        mode: 'full', reason,
+        fetchFrom: null, flagScan: 'none', changedSince: null, reconcile: false
+    });
+
+    if (!stored) return full('never synced');
+
+    // UIDVALIDITY changing means every UID we hold now refers to a different
+    // message. The mirror is not stale, it is wrong, and the only correct
+    // response is to throw it away.
+    if (compareCounters(stored.uidValidity, server.uidValidity) !== 0) {
+        return full('UIDVALIDITY changed - stored UIDs refer to different messages');
+    }
+
+    const storedUidNext = Number(stored.uidNext) || 1;
+    const serverUidNext = Number(server.uidNext) || 1;
+    const hasArrivals = serverUidNext > storedUidNext;
+
+    // Without CONDSTORE there is no cheap way to ask "what changed", so flags
+    // are rescanned wholesale. With it, only what moved past our MODSEQ.
+    let flagScan = 'full';
+    let changedSince = null;
+    if (server.highestModseq && stored.highestModseq) {
+        if (compareCounters(server.highestModseq, stored.highestModseq) > 0) {
+            flagScan = 'changed';
+            changedSince = stored.highestModseq;
+        } else {
+            flagScan = 'none';
+        }
+    }
+
+    // A count that does not match means something was removed - arrivals alone
+    // would have raised it. Two arriving and two vanishing leaves the count
+    // unchanged, which is why there is also a periodic reconcile: cheap
+    // insurance against the case the counters cannot see.
+    const countMismatch = Number(server.exists) !== Number(stored.exists ?? -1);
+    const lastReconcile = Number(stored.lastReconcileAt ?? 0);
+    const reconcileDue = now - lastReconcile >= reconcileIntervalMs;
+    const reconcile = countMismatch || reconcileDue;
+
+    if (!hasArrivals && flagScan === 'none' && !reconcile) {
+        return {
+            mode: 'none', reason: 'nothing changed',
+            fetchFrom: null, flagScan: 'none', changedSince: null, reconcile: false
+        };
+    }
+
+    const reasons = [];
+    if (hasArrivals) reasons.push(`${serverUidNext - storedUidNext} new UID(s)`);
+    if (flagScan === 'changed') reasons.push('flags changed since last MODSEQ');
+    if (flagScan === 'full') reasons.push('no CONDSTORE - rescanning flags');
+    if (countMismatch) reasons.push('message count differs');
+    else if (reconcileDue) reasons.push('periodic reconcile');
+
+    return {
+        mode: 'incremental',
+        reason: reasons.join(', '),
+        fetchFrom: hasArrivals ? storedUidNext : null,
+        flagScan,
+        changedSince,
+        reconcile
+    };
+}
+
+/**
+ * Which stored UIDs the server no longer has.
+ *
+ * @param   {number[]} stored
+ * @param   {number[]} onServer
+ * @returns {number[]}
+ */
+export function missingUids(stored, onServer) {
+    const live = new Set(onServer);
+    return stored.filter(uid => !live.has(uid));
+}

package/plugins/_lib/mail/syncSelection.js

@@ -0,0 +1,82 @@
+/**
+ * Which folders a mailbox keeps mirrored.
+ *
+ * The free reader fetches everything on demand and holds nothing. The Pro
+ * edition mirrors folders into MongoDB so the list opens instantly and search
+ * can run locally - but mirroring *every* folder is the wrong default. A real
+ * mailbox here has 104 of them; syncing all of those on every poll is a lot of
+ * traffic to keep a decade of archive folders warm that nobody opens.
+ *
+ * So: a sensible default, and an explicit choice that overrides it.
+ *
+ * @module _lib/mail/syncSelection
+ */
+
+/**
+ * Folders worth mirroring without being asked.
+ *
+ * The inbox because it is the one that matters, and Sent because replies are
+ * how threading gets its other half. Drafts, Trash and Junk are deliberately
+ * absent - they churn, and nobody searches them.
+ */
+const DEFAULT_SPECIAL_USE = new Set(['\\Inbox', '\\Sent']);
+
+/**
+ * Resolve the folders to sync for one mailbox.
+ *
+ * An explicit selection is honoured as given, minus anything the server no
+ * longer offers - a folder that was renamed away should not keep failing
+ * every poll forever.
+ *
+ * @param   {{syncFolders?: string[]|null}} account
+ * @param   {{path: string, specialUse?: string|null}[]} folders - as the server lists them
+ * @returns {{paths: string[], source: 'default'|'explicit'}}
+ */
+export function resolveSyncFolders(account, folders) {
+    const available = new Set(folders.map(f => f.path));
+
+    const chosen = account?.syncFolders;
+    if (Array.isArray(chosen)) {
+        // Deduplicated here as well as on write: a record could carry
+        // duplicates from an older version or an edited file, and each one
+        // would otherwise mean syncing the same folder twice every pass.
+        return {
+            paths: [...new Set(chosen.filter(path => available.has(path)))],
+            source: 'explicit'
+        };
+    }
+
+    const paths = folders
+        .filter(f => DEFAULT_SPECIAL_USE.has(f.specialUse)
+            || f.path.toUpperCase() === 'INBOX')
+        .map(f => f.path);
+
+    // A server that advertises no special-use at all still has an inbox worth
+    // syncing; falling back to nothing would leave the Pro edition doing less
+    // than the free one.
+    if (!paths.length && folders.length) {
+        const first = folders.find(f => f.path.toUpperCase() === 'INBOX') ?? folders[0];
+        paths.push(first.path);
+    }
+
+    return {paths: [...new Set(paths)], source: 'default'};
+}
+
+/**
+ * Annotate a folder list with whether each one is mirrored.
+ *
+ * What the settings screen renders: every folder the server offers, each
+ * marked according to the current selection.
+ *
+ * @param   {{syncFolders?: string[]|null}} account
+ * @param   {{path: string, specialUse?: string|null}[]} folders
+ * @returns {{folders: object[], source: 'default'|'explicit'}}
+ */
+export function describeSyncSelection(account, folders) {
+    const {paths, source} = resolveSyncFolders(account, folders);
+    const selected = new Set(paths);
+    return {
+        source,
+        folders: folders.map(folder => ({...folder, sync: selected.has(folder.path)}))
+    };
+}

package/plugins/_lib/mail/unsubscribe.js

@@ -0,0 +1,183 @@
+/**
+ * Getting off a mailing list.
+ *
+ * Every bulk sender that follows the conventions puts a `List-Unsubscribe`
+ * header on its mail, and almost no webmail client surfaces it usefully -
+ * which is why people hunt for the six-point grey link at the bottom instead.
+ * Reading the header is a dozen lines; not reading it is why unsubscribing is
+ * unpleasant.
+ *
+ * ## One-click, and why it is not the default
+ *
+ * RFC 8058 adds `List-Unsubscribe-Post: List-Unsubscribe=One-Click`, which
+ * says the HTTPS URL accepts a POST and will action it without further
+ * confirmation. Where that is offered, this plugin can do it from the reader.
+ * Where it is not, the URL is opened in a tab instead: POSTing to a URL that
+ * never advertised one-click is sending an unsolicited request to a third
+ * party on the user's behalf, which is not ours to decide.
+ *
+ * The `mailto:` form is always a real message from the user's own mailbox, so
+ * it is offered but never sent without asking - an unsubscribe mail is
+ * indistinguishable from any other mail they send.
+ *
+ * @module _lib/mail/unsubscribe
+ */
+
+/**
+ * Read a header out of either shape headers arrive in.
+ *
+ * @param   {Map|object|null} headers
+ * @param   {string} name
+ * @returns {string}
+ */
+function header(headers, name) {
+    if (!headers) return '';
+    const value = typeof headers.get === 'function' ? headers.get(name) : headers[name];
+    // mailparser hands back an object for some structured headers.
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return String(value.value ?? '');
+    }
+    return String(Array.isArray(value) ? value[0] ?? '' : value ?? '');
+}
+
+/**
+ * What a message offers by way of unsubscribing.
+ *
+ * @param   {Map|object|null} headers - the parsed message's headers
+ * @returns {{available: boolean, http: string|null, oneClick: boolean,
+ *            mailto: {to: string, subject: string, body: string}|null}}
+ */
+export function readUnsubscribe(headers) {
+    const raw = header(headers, 'list-unsubscribe');
+    const none = {available: false, http: null, oneClick: false, mailto: null};
+    if (!raw.trim()) return none;
+
+    // The header is a comma-separated list of angle-bracketed URIs. Split on
+    // the brackets rather than on commas: a mailto: with a subject containing
+    // a comma is legal and would otherwise be torn in half.
+    const uris = [...raw.matchAll(/<([^>]+)>/g)].map(match => match[1].trim()).filter(Boolean);
+    if (!uris.length) return none;
+
+    // https only. An http:// unsubscribe link is a plaintext request carrying
+    // a token that identifies the recipient, and there is no version of
+    // "click here to prove this address is live" worth sending in the clear.
+    const http = uris.find(uri => /^https:\/\//i.test(uri)) ?? null;
+    const mailtoUri = uris.find(uri => /^mailto:/i.test(uri)) ?? null;
+
+    const post = header(headers, 'list-unsubscribe-post');
+    const oneClick = Boolean(http) && /list-unsubscribe\s*=\s*one-click/i.test(post);
+
+    return {
+        available: Boolean(http || mailtoUri),
+        http,
+        oneClick,
+        mailto: mailtoUri ? parseMailto(mailtoUri) : null
+    };
+}
+
+/**
+ * Pull a mailto: URI apart into something sendable.
+ *
+ * @param   {string} uri
+ * @returns {{to: string, subject: string, body: string}|null}
+ */
+export function parseMailto(uri) {
+    const withoutScheme = String(uri ?? '').replace(/^mailto:/i, '');
+    const [addresses, query = ''] = withoutScheme.split('?');
+
+    const to = decodeURIComponent(addresses ?? '').trim();
+    if (!to) return null;
+
+    const params = new URLSearchParams(query);
+    return {
+        to,
+        // "unsubscribe" is the conventional body and subject when the sender
+        // asks for nothing in particular, and an empty message is refused by
+        // a fair number of list managers.
+        subject: (params.get('subject') ?? 'unsubscribe').trim(),
+        body: (params.get('body') ?? 'unsubscribe').trim()
+    };
+}
+
+/**
+ * Is this a host the server may be asked to POST to?
+ *
+ * One-click unsubscribe is the only place in this plugin where the SERVER
+ * makes a request to a URL chosen by whoever sent the message. Without a
+ * guard that is a server-side request forgery with a button on it: the
+ * sender supplies `https://attacker.example/u`, the admin clicks Unsubscribe,
+ * and the attacker's 302 sends the request to `http://127.0.0.1:8192/…` or
+ * to a cloud metadata endpoint - from inside the network, with the response
+ * status handed back to the caller as a working port scanner.
+ *
+ * Two halves, and both are needed:
+ *
+ *   - Redirects are NOT followed. A validated host that redirects is a
+ *     validated host pointing somewhere unvalidated.
+ *   - The host must resolve to a PUBLIC address. Checking the literal is not
+ *     enough, because `unsubscribe.attacker.example` can resolve to
+ *     127.0.0.1 - so the caller resolves it and checks every answer.
+ *
+ * This function is the pure half: given resolved addresses, is it allowed?
+ *
+ * @param   {string[]} addresses - every A/AAAA the host resolved to
+ * @returns {boolean}
+ */
+export function addressesArePublic(addresses) {
+    const list = (addresses ?? []).map(a => String(a ?? '').trim().toLowerCase()).filter(Boolean);
+    // No answer is not permission. A host that resolves to nothing cannot be
+    // reached anyway, and treating "unknown" as "fine" is the wrong default
+    // for a security check.
+    if (!list.length) return false;
+    return list.every(address => !isPrivateAddress(address));
+}
+
+/**
+ * Is this IP one that must never be reached on a sender's say-so?
+ *
+ * Loopback, link-local (which covers the cloud metadata endpoints), the
+ * RFC 1918 ranges, carrier-grade NAT, and the IPv6 equivalents including
+ * IPv4-mapped addresses - `::ffff:127.0.0.1` is loopback wearing a hat.
+ *
+ * @param   {string} address
+ * @returns {boolean}
+ */
+export function isPrivateAddress(address) {
+    const value = String(address ?? '').trim().toLowerCase();
+    if (!value) return true;
+
+    // IPv4-mapped IPv6, so the v4 rules below actually apply to it.
+    const mapped = value.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    const ip = mapped ? mapped[1] : value;
+
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(ip)) {
+        const [a, b] = ip.split('.').map(Number);
+        if (a === 0 || a === 10 || a === 127) return true;
+        if (a === 169 && b === 254) return true;          // link-local, incl. metadata
+        if (a === 172 && b >= 16 && b <= 31) return true; // RFC 1918
+        if (a === 192 && b === 168) return true;          // RFC 1918
+        if (a === 100 && b >= 64 && b <= 127) return true; // carrier-grade NAT
+        if (a >= 224) return true;                         // multicast and reserved
+        return false;
+    }
+
+    // IPv6.
+    if (ip === '::' || ip === '::1') return true;
+    if (/^f[cd]/.test(ip)) return true;  // unique local
+    if (/^fe[89ab]/.test(ip)) return true; // link-local
+    return false;
+}
+
+/**
+ * Names that are never a public unsubscribe endpoint, whatever they resolve
+ * to. A cheap first pass, so the common cases are refused without a lookup.
+ *
+ * @param   {string} hostname
+ * @returns {boolean}
+ */
+export function isLocalName(hostname) {
+    const host = String(hostname ?? '').trim().toLowerCase().replace(/\.$/, '');
+    if (!host) return true;
+    if (host === 'localhost') return true;
+    return /\.(local|internal|localhost|home|lan|intranet)$/.test(host);
+}