domma-cms 0.82.0 → 0.83.0

package/plugins/security/admin/lib/blocks.js

@@ -0,0 +1,46 @@
+/**
+ * Security - blocking an address: manual rules (ip.js syntax) and temporary
+ * blocks (an address that kept probing). An address that signed in recently is
+ * "trusted": probing never blocks it (an admin mistyping /wp-admin must not lock
+ * themselves out) - a manual rule still does. Loopback is never blocked. Pure.
+ */
+import {ipMatches, isLoopbackIp, plainIp} from './ip.js';
+
+export const TRUST_DAYS = 7;
+
+/**
+ * Why an address is blocked, or null.
+ *
+ * @param {{rules: {rule: string}[], temp: Object<string, {until: number, reason: string}>}} state
+ */
+export function blockedBy(state, ip, now = Date.now()) {
+    const a = plainIp(ip);
+    if (!a || isLoopbackIp(a)) return null;
+    const rule = (state.rules || []).find(r => ipMatches(a, [r.rule]));
+    if (rule) return {kind: 'rule', rule: rule.rule, reason: rule.note || 'Blocked by hand'};
+    const t = state.temp?.[a];
+    if (t && t.until > now) return {kind: 'temp', until: t.until, reason: t.reason};
+    return null;
+}
+
+export const isTrusted = (state, ip, now = Date.now()) => (state.trusted?.[plainIp(ip)] || 0) > now - TRUST_DAYS * 86_400_000;
+
+/**
+ * Count a probe from an address (in `recent`, a Map kept in memory). True when
+ * it should now be blocked.
+ */
+export function recordProbe(recent, ip, {now = Date.now(), blockAfter = 5, withinMin = 10} = {}) {
+    const a = plainIp(ip);
+    const list = (recent.get(a) || []).filter(t => t > now - withinMin * 60_000);
+    list.push(now);
+    recent.set(a, list);
+    if (recent.size > 10_000) recent.delete(recent.keys().next().value);
+    return list.length >= blockAfter;
+}
+
+/** Forget ended temporary blocks and old trust. */
+export function pruneBlocks(state, now = Date.now()) {
+    for (const [ip, t] of Object.entries(state.temp || {})) if (t.until < now) delete state.temp[ip];
+    for (const [ip, at] of Object.entries(state.trusted || {})) if (at < now - TRUST_DAYS * 86_400_000) delete state.trusted[ip];
+    return state;
+}

package/plugins/security/admin/lib/health.js

@@ -0,0 +1,148 @@
+/**
+ * Security - the health check: facts about the site in, checks out. Pure; the
+ * server gathers the facts (server/facts.js). Each check says what it found,
+ * why it matters and how to fix it - a check that cannot be answered is 'info',
+ * never a pass.
+ *
+ * status: 'pass' | 'warn' | 'fail' | 'info'; `critical` makes a fail red in the badge.
+ */
+
+const DAY = 86_400_000;
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const names = (list) => (list.length <= 3 ? list.join(', ') : `${list.slice(0, 3).join(', ')} and ${list.length - 3} more`);
+
+function semverBehind(installed, latest) {
+    const a = String(installed || '').split('.').map(Number);
+    const b = String(latest || '').split('.').map(Number);
+    if (a.length < 3 || b.length < 3 || [...a, ...b].some(Number.isNaN)) return null;
+    for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i] ? {major: i === 0, minor: i === 1, patch: i === 2} : false;
+    return false;
+}
+
+/**
+ * @param {object} f - facts (see server/facts.js)
+ * @param {{now?: number, staleAdminDays?: number}} [opts]
+ * @returns {{checks: object[], score: number, failing: number, critical: number}}
+ */
+export function evaluate(f = {}, {now = Date.now(), staleAdminDays = 90} = {}) {
+    const checks = [];
+    const add = (c) => checks.push({critical: false, link: '', ...c});
+
+    // --- People ---
+    const admins = f.admins || [];
+    const stale = admins.filter(a => !a.lastLogin || Date.parse(a.lastLogin) < now - staleAdminDays * DAY);
+    add({id: 'admins-stale', group: 'People', title: 'Unused admin accounts',
+        status: !admins.length ? 'info' : stale.length ? 'warn' : 'pass',
+        detail: stale.length ? `${plural(stale.length, 'admin')} not signed in for ${staleAdminDays}+ days: ${names(stale.map(a => a.name || a.email))}.` : `Every admin has signed in within ${staleAdminDays} days.`,
+        why: 'An admin account nobody uses is one nobody would notice being used by someone else.',
+        fix: 'Switch off or remove admin accounts that are no longer needed, or lower their role.', link: '#/users'});
+    add({id: 'admins-count', group: 'People', title: 'How many admins',
+        status: admins.length > 5 ? 'warn' : admins.length ? 'pass' : 'info',
+        detail: `${plural(admins.length, 'admin')} (admin or super admin).`,
+        why: 'Every admin can change everything. Fewer admins, fewer ways in.',
+        fix: 'Give people the lowest role that lets them do their job.', link: '#/users'});
+    const never = (f.users || []).filter(u => !u.lastLogin && u.createdAt && Date.parse(u.createdAt) < now - 30 * DAY);
+    add({id: 'users-never', group: 'People', title: 'Accounts never used',
+        status: never.length ? 'warn' : 'pass',
+        detail: never.length ? `${plural(never.length, 'account')} made over 30 days ago and never signed in: ${names(never.map(u => u.name || u.email))}.` : 'Every account older than 30 days has been used.',
+        why: 'An account with a password nobody changed is an easy one to guess.',
+        fix: 'Remove accounts nobody uses.', link: '#/users'});
+
+    // --- Sign-in ---
+    add({id: 'lockout', group: 'Sign-in', title: 'Sign-in lockout',
+        status: f.protections?.checks === false ? 'fail' : f.protections?.lockout ? 'pass' : 'warn', critical: f.protections?.checks === false,
+        detail: f.protections?.checks === false ? 'This engine is too old for sign-in checks (needs Domma CMS 0.83 or later).'
+            : f.protections?.lockout ? 'Repeated wrong passwords lock the account and the address for a while.' : 'Switched off in the settings.',
+        why: 'Without it, a password can be guessed as fast as the rate limit allows, forever.',
+        fix: f.protections?.checks === false ? 'Update the CMS.' : 'Switch it on in the settings (the cog).'});
+    add({id: 'policy', group: 'Sign-in', title: 'Password rules',
+        status: f.protections?.policy ? (f.policyMin >= 10 ? 'pass' : 'warn') : 'warn',
+        detail: f.protections?.policy ? `New passwords: at least ${f.policyMin} characters, not a common one, not your name or email.` : 'Only the CMS minimum (8 characters) applies.',
+        why: 'Most break-ins use passwords that are short, common or guessable from the person.',
+        fix: 'Switch the password rules on, with at least 10 characters.'});
+    add({id: 'two-factor', group: 'Sign-in', title: 'Two-factor sign-in',
+        status: f.twoFactor ? 'pass' : 'info',
+        detail: f.twoFactor ? 'Available.' : 'Not available - Security Pro adds two-factor sign-in with an authenticator app.',
+        why: 'A stolen or guessed password alone is then not enough to get in.',
+        fix: 'Security Pro.'});
+    add({id: 'smtp', group: 'Sign-in', title: 'Email for resets and alerts',
+        status: f.smtp ? 'pass' : 'warn',
+        detail: f.smtp ? 'Email is set up.' : 'No outgoing email: password resets and alerts cannot be sent.',
+        why: 'Without email, a locked-out admin has no self-service way back, and alerts go unseen.',
+        fix: 'Set up email in Settings.', link: '#/settings'});
+
+    // --- Server ---
+    const behind = semverBehind(f.engine?.installed, f.engine?.latest);
+    add({id: 'engine', group: 'Server', title: 'Domma CMS up to date',
+        status: behind === null ? 'info' : behind ? (behind.major || behind.minor ? 'warn' : 'pass') : 'pass',
+        detail: behind === null ? `Running ${f.engine?.installed || 'an unknown version'}; the latest could not be checked.`
+            : behind ? `Running ${f.engine.installed}; ${f.engine.latest} is out.` : `Running ${f.engine.installed}, the latest.`,
+        why: 'Updates carry security fixes.', fix: 'Update the CMS (or ask whoever hosts it).'});
+    add({id: 'production', group: 'Server', title: 'Production mode',
+        status: f.nodeEnv === 'production' ? 'pass' : 'warn',
+        detail: f.nodeEnv === 'production' ? 'NODE_ENV is production.' : `NODE_ENV is "${f.nodeEnv || 'not set'}".`,
+        why: 'Outside production, errors can show more than a visitor should see.',
+        fix: 'Set NODE_ENV=production in the site\'s .env and restart.'});
+    if (f.proxy?.via) {
+        const t = f.proxy.trust;
+        add({id: 'proxy', group: 'Server', title: 'Visitor addresses',
+            status: t === false ? 'fail' : t === true ? 'warn' : 'pass', critical: t === false,
+            detail: t === false ? 'The site is behind a proxy but does not trust it: every visitor looks like the proxy.'
+                : t === true ? 'Every proxy hop is trusted (TRUST_PROXY=1): a visitor can choose the address they appear as.' : `TRUST_PROXY=${t}.`,
+            why: 'Rate limits, lockouts and blocks all go by the visitor\'s address.',
+            fix: 'Set TRUST_PROXY=loopback in the site\'s .env and restart.'});
+    }
+    if (f.bind) {
+        add({id: 'bind', group: 'Server', title: 'Listening address',
+            status: f.bind === '0.0.0.0' && f.proxy?.via ? 'warn' : 'pass',
+            detail: f.bind === '0.0.0.0' && f.proxy?.via ? 'The CMS listens on every network interface although a proxy fronts it.' : `Listening on ${f.bind}.`,
+            why: 'Reached directly, the CMS bypasses the proxy and its protections.',
+            fix: 'Set "host": "127.0.0.1" in config/server.json when a proxy sits in front.'});
+    }
+
+    // --- Web ---
+    if (f.cert) {
+        const d = f.cert.daysLeft;
+        add({id: 'certificate', group: 'Web', title: 'HTTPS certificate',
+            status: d === null || d === undefined ? 'info' : d < 7 ? 'fail' : d < 21 ? 'warn' : 'pass', critical: d !== null && d < 7,
+            detail: d === null || d === undefined ? `Could not read the certificate${f.cert.error ? `: ${f.cert.error}` : ''}.` : d < 0 ? `Expired ${-d} days ago.` : `Valid for ${plural(d, 'more day')}${f.cert.issuer ? ` (${f.cert.issuer})` : ''}.`,
+            why: 'An expired certificate turns every visitor away with a warning.',
+            fix: 'Renew it (Site Manager renews automatically on the fleet).'});
+    }
+    const h = f.headers;
+    if (h) {
+        const missing = [['csp', 'Content-Security-Policy'], ['nosniff', 'X-Content-Type-Options'], ['frame', 'frame protection'],
+            ['referrer', 'Referrer-Policy'], ...(h.https ? [['hsts', 'Strict-Transport-Security']] : [])].filter(([k]) => !h[k]).map(([, n]) => n);
+        add({id: 'headers', group: 'Web', title: 'Security headers',
+            status: h.error ? 'info' : missing.length ? 'warn' : 'pass',
+            detail: h.error ? `Could not fetch the home page: ${h.error}.` : missing.length ? `Missing: ${missing.join(', ')}.` : 'All present.',
+            why: 'They stop pages being framed, content being mis-typed and scripts being injected.',
+            fix: 'The CMS sets them; missing ones are usually stripped by a proxy in front.'});
+        add({id: 'https', group: 'Web', title: 'HTTPS',
+            status: h.error ? 'info' : h.https ? 'pass' : 'warn',
+            detail: h.https ? 'The site is served over HTTPS.' : 'The site was reached over plain HTTP.',
+            why: 'Without it, passwords and sessions cross the network readable.', fix: 'Serve the site over HTTPS only.'});
+    }
+    const exposed = (f.probeFiles || []).filter(p => p.status === 200);
+    add({id: 'exposed', group: 'Web', title: 'Private files not served',
+        status: !(f.probeFiles || []).length ? 'info' : exposed.length ? 'fail' : 'pass', critical: exposed.length > 0,
+        detail: exposed.length ? `Served to anyone: ${exposed.map(p => p.path).join(', ')}.` : `${plural((f.probeFiles || []).length, 'private path')} checked - none served.`,
+        why: 'These hold secrets (keys, passwords, the code\'s history).',
+        fix: 'Remove the file from the site, or block it in the web server.'});
+
+    // --- Plugins ---
+    const lapsed = (f.licences || []).filter(l => !['valid', 'grace', 'support-ended', 'not-required'].includes(l.state));
+    add({id: 'licences', group: 'Plugins', title: 'Plugin licences',
+        status: lapsed.length ? 'warn' : 'pass',
+        detail: lapsed.length ? `Not loaded for want of a licence: ${names(lapsed.map(l => l.name))}.` : 'Every licensed plugin loaded.',
+        why: 'A plugin that does not load does not protect or do what you think it does.', fix: 'Renew or remove it.', link: '#/plugins'});
+
+    const scored = checks.filter(c => c.status !== 'info');
+    const points = scored.reduce((a, c) => a + (c.status === 'pass' ? 1 : c.status === 'warn' ? 0.5 : 0), 0);
+    return {
+        checks,
+        score: scored.length ? Math.round((points / scored.length) * 100) : 0,
+        failing: checks.filter(c => c.status === 'fail' || c.status === 'warn').length,
+        critical: checks.filter(c => c.status === 'fail' && c.critical).length
+    };
+}

package/plugins/security/admin/lib/ip.js

@@ -0,0 +1,44 @@
+/**
+ * Security - address rules: an address (81.2.69.142), a trailing wildcard
+ * (192.168.1.*), an IPv4 CIDR (10.0.0.0/8) or an IPv6 prefix (2a00:23c7:*).
+ * Pure. Copied from Analytics Pro (admin/lib/settings.js) - keep them alike.
+ */
+
+/** Is this a rule we understand? */
+export function ipRuleValid(rule) {
+    const r = String(rule).trim();
+    if (/^(\d{1,3}\.){3}\d{1,3}\/(\d|[12]\d|3[0-2])$/.test(r)) return r.split('/')[0].split('.').every(o => +o <= 255);
+    if (/^(\d{1,3}\.){3}\d{1,3}$/.test(r)) return r.split('.').every(o => +o <= 255);
+    if (/^(\d{1,3}\.){1,3}\*$/.test(r)) return true;
+    if (/^[0-9a-f:]+(\*)?$/i.test(r) && r.includes(':')) return true;
+    return false;
+}
+
+const v4num = (ip) => ip.split('.').reduce((n, o) => n * 256 + (+o), 0);
+
+/** The address as rules see it: no IPv4-mapped prefix, lower case. */
+export const plainIp = (ip) => String(ip ?? '').trim().replace(/^::ffff:(?=\d+\.)/i, '').toLowerCase();
+
+/** Does an address match one of the rules? */
+export function ipMatches(ip, rules = []) {
+    const a = plainIp(ip);
+    if (!a) return false;
+    for (const raw of rules) {
+        const r = String(raw).trim().toLowerCase();
+        if (!r) continue;
+        if (r.endsWith('*')) { if (a.startsWith(r.slice(0, -1))) return true; continue; }
+        if (r.includes('/')) {
+            if (!/^(\d{1,3}\.){3}\d{1,3}$/.test(a)) continue;
+            const [base, bits] = r.split('/');
+            const size = 2 ** (32 - Number(bits));
+            if (Math.floor(v4num(a) / size) === Math.floor(v4num(base) / size)) return true;
+            continue;
+        }
+        if (a === r) return true;
+    }
+    return false;
+}
+
+const LOOPBACK = /^(127\.\d+\.\d+\.\d+|::1)$/;
+/** Loopback: this machine. Never blocked or locked out. */
+export const isLoopbackIp = (ip) => LOOPBACK.test(plainIp(ip));

package/plugins/security/admin/lib/lockout.js

@@ -0,0 +1,78 @@
+/**
+ * Security - sign-in lockout. Failures are counted per ACCOUNT and per ADDRESS
+ * inside a window; reaching the threshold locks that key, first for `baseMin`,
+ * each further lock twice as long, up to `maxMin`. A success clears the account
+ * (not the address - an attacker with one right password should not wipe their
+ * address's record). Pure: the state is a plain object the plugin saves.
+ *
+ * state: {[key]: {fails: number[] (ms), locks: number, until: number}}
+ * keys:  'a:<email>' and 'i:<address>'
+ */
+
+export const DEFAULT_LOCKOUT = {
+    accountThreshold: 5,     // failures on one account...
+    addressThreshold: 20,    // ...or from one address (offices share one)...
+    windowMin: 15,           // ...within this many minutes
+    baseMin: 1,              // first lock
+    maxMin: 60               // longest lock
+};
+
+export const accountKey = (email) => `a:${String(email ?? '').trim().toLowerCase()}`;
+export const addressKey = (ip) => `i:${String(ip ?? '').trim().toLowerCase()}`;
+
+/** Until when a key is locked (ms), or 0. */
+export function lockedUntil(state, key, now = Date.now()) {
+    const e = state[key];
+    return e && e.until > now ? e.until : 0;
+}
+
+/**
+ * Count a failure against a key; lock it when the threshold is reached.
+ *
+ * @returns {number} until when it is now locked (ms), or 0
+ */
+export function recordFailure(state, key, {now = Date.now(), threshold, windowMin, baseMin, maxMin} = {}) {
+    const cfg = {...DEFAULT_LOCKOUT, windowMin: windowMin ?? DEFAULT_LOCKOUT.windowMin, baseMin: baseMin ?? DEFAULT_LOCKOUT.baseMin, maxMin: maxMin ?? DEFAULT_LOCKOUT.maxMin};
+    const limit = threshold ?? (key.startsWith('i:') ? cfg.addressThreshold : cfg.accountThreshold);
+    const e = state[key] ??= {fails: [], locks: 0, until: 0};
+    e.fails = e.fails.filter(t => t > now - cfg.windowMin * 60_000);
+    e.fails.push(now);
+    if (e.fails.length >= limit) {
+        const minutes = Math.min(cfg.maxMin, cfg.baseMin * 2 ** e.locks);
+        e.locks++;
+        e.until = now + minutes * 60_000;
+        e.fails = [];
+        return e.until;
+    }
+    return 0;
+}
+
+/** A successful sign-in: the account starts afresh. */
+export function recordSuccess(state, key) {
+    delete state[key];
+}
+
+/** Drop what no longer matters (no recent failure, no lock, locks forgotten after a day). */
+export function pruneLockouts(state, {now = Date.now(), windowMin = DEFAULT_LOCKOUT.windowMin} = {}) {
+    for (const [k, e] of Object.entries(state)) {
+        e.fails = (e.fails || []).filter(t => t > now - windowMin * 60_000);
+        if (!e.fails.length && e.until < now - 24 * 3_600_000) delete state[k];
+    }
+    return state;
+}
+
+/** Live locks, soonest-ending last: [{key, kind, who, until}]. */
+export function activeLocks(state, now = Date.now()) {
+    return Object.entries(state)
+        .filter(([, e]) => e.until > now)
+        .map(([key, e]) => ({key, kind: key.startsWith('a:') ? 'account' : 'address', who: key.slice(2), until: e.until, locks: e.locks}))
+        .sort((a, b) => b.until - a.until);
+}
+
+/** "in 3 minutes" / "in 1 hour" - for the refusal message. */
+export function retryText(until, now = Date.now()) {
+    const min = Math.max(1, Math.ceil((until - now) / 60_000));
+    if (min < 60) return `in ${min} minute${min === 1 ? '' : 's'}`;
+    const h = Math.ceil(min / 60);
+    return `in ${h} hour${h === 1 ? '' : 's'}`;
+}

package/plugins/security/admin/lib/policy.js

@@ -0,0 +1,32 @@
+/**
+ * Security - the password policy. Pure: the common-password list is handed in
+ * (the server loads server/common-passwords.txt once).
+ */
+
+export const DEFAULT_POLICY = {minLength: 10, blockCommon: true, blockPersonal: true};
+
+const norm = (s) => String(s ?? '').toLowerCase();
+
+/**
+ * What is wrong with a password, as sentences ([] = fine).
+ *
+ * @param {string} password
+ * @param {{email?: string, name?: string}} who
+ * @param {{minLength?: number, blockCommon?: boolean, blockPersonal?: boolean, common?: Set<string>}} policy
+ */
+export function passwordProblems(password, {email = '', name = ''} = {}, {minLength = DEFAULT_POLICY.minLength, blockCommon = true, blockPersonal = true, common = new Set()} = {}) {
+    const pw = String(password ?? '');
+    const out = [];
+    if (pw.length < minLength) out.push(`Use at least ${minLength} characters.`);
+    const low = norm(pw);
+    if (blockCommon && (common.has(low) || common.has(low.replace(/[\d!?.]+$/, '')))) {
+        out.push('That password is one of the most common - pick something less guessable.');
+    }
+    if (blockPersonal) {
+        const local = norm(email).split('@')[0];
+        const parts = [local, ...norm(name).split(/\s+/)].filter(p => p && p.length >= 3);
+        if (parts.some(p => low.includes(p))) out.push('Leave your name and email out of your password.');
+    }
+    if (pw.length >= 4 && new Set(pw).size <= 2) out.push('Use more than one or two different characters.');
+    return out;
+}

package/plugins/security/admin/lib/probes.js

@@ -0,0 +1,39 @@
+/**
+ * Security - probe paths: what scanners ask for on every site they find, and a
+ * Domma CMS never serves. Answered with an empty 404 before any rendering, and
+ * counted: an address that keeps probing is blocked for a while. Pure.
+ */
+
+/** Path prefixes and patterns, lower-cased; a trailing / matches everything under it. */
+export const DEFAULT_PROBES = [
+    '/wp-login.php', '/wp-admin/', '/wp-content/', '/wp-includes/', '/wp-json/', '/xmlrpc.php', '/wordpress/',
+    '/.env', '/.git/', '/.svn/', '/.hg/', '/.ds_store', '/.htaccess', '/.htpasswd', '/.aws/', '/.ssh/', '/.vscode/', '/.idea/',
+    '/phpmyadmin/', '/pma/', '/myadmin/', '/adminer.php', '/phpinfo.php', '/info.php', '/server-status', '/server-info',
+    '/cgi-bin/', '/vendor/phpunit/', '/boaform/', '/hnap1', '/actuator/', '/solr/', '/owa/', '/ecp/', '/autodiscover/',
+    '/config.json', '/config.yml', '/web.config', '/backup.zip', '/backup.sql', '/database.sql', '/dump.sql', '/db.sql',
+    '/debug/default/view', '/telescope/', '/_ignition/', '/api/jsonws/', '/remote/login', '/global-protect/', '/sslvpn'
+];
+
+/** Extensions no Domma CMS page has: a request ending so is a probe. */
+export const PROBE_EXTENSIONS = ['.php', '.asp', '.aspx', '.jsp', '.cgi', '.pl', '.bak', '.old', '.sql', '.swp', '.env'];
+
+/**
+ * Is this path a probe?
+ *
+ * @param {string} path - the request path, without the query
+ * @param {{extra?: string[], allow?: string[]}} [opts] - the site's own additions; paths it DOES serve
+ */
+export function isProbe(path, {extra = [], allow = []} = {}) {
+    let p;
+    try { p = decodeURIComponent(String(path || '')).toLowerCase(); } catch { p = String(path || '').toLowerCase(); }
+    p = p.split('?')[0].replace(/\/{2,}/g, '/');
+    if (!p.startsWith('/')) p = `/${p}`;
+    if (allow.some(a => a && p.startsWith(String(a).toLowerCase()))) return false;
+    // A traversal attempt is a probe whatever it asks for.
+    if (p.includes('/../') || p.endsWith('/..')) return true;
+    const list = [...DEFAULT_PROBES, ...extra.map(e => String(e).toLowerCase()).filter(Boolean)];
+    for (const rule of list) {
+        if (rule.endsWith('/') ? (p === rule.slice(0, -1) || p.startsWith(rule)) : (p === rule || p.startsWith(`${rule}/`))) return true;
+    }
+    return PROBE_EXTENSIONS.some(ext => p.endsWith(ext));
+}

package/plugins/security/admin/lib/settings.js

@@ -0,0 +1,86 @@
+/**
+ * Security - settings (config/plugins.json `security.settings`), checked the
+ * same way by the server and the settings slideover. Pure.
+ */
+import {DEFAULT_LOCKOUT} from './lockout.js';
+import {DEFAULT_POLICY} from './policy.js';
+
+export const DEFAULT_SETTINGS = {
+    lockout: {...DEFAULT_LOCKOUT, enabled: true},
+    policy: {...DEFAULT_POLICY, enabled: true},
+    probes: {enabled: true, blockAfter: 5, withinMin: 10, blockForMin: 60, extra: [], allow: []},
+    signinDays: 30,
+    staleAdminDays: 90,
+    notify: {lockouts: true, successAfterFails: true, probeBlocks: false}
+};
+
+const int = (v, min, max) => {
+    const n = Number(v);
+    return Number.isInteger(n) && n >= min && n <= max ? n : null;
+};
+const bool = (v, d) => (v === undefined ? d : v === true || v === 'true');
+const lines = (v) => (Array.isArray(v) ? v : String(v ?? '').split(/[\n,]+/)).map(s => String(s).trim()).filter(Boolean);
+
+/**
+ * The stored settings merged over the defaults, every value checked.
+ *
+ * @param {object} input - a full or partial settings object
+ * @param {object} [base] - what is stored now (defaults when absent)
+ * @returns {{errors: Record<string, string>, settings: object}}
+ */
+export function checkSettings(input = {}, base = DEFAULT_SETTINGS) {
+    const errors = {};
+    const b = mergeDefaults(base);
+    const out = JSON.parse(JSON.stringify(b));
+    const num = (group, key, min, max, label) => {
+        const v = input?.[group]?.[key];
+        if (v === undefined) return;
+        const n = int(v, min, max);
+        if (n === null) errors[`${group}.${key}`] = `${label}: a whole number, ${min} to ${max}.`;
+        else out[group][key] = n;
+    };
+    for (const g of ['lockout', 'policy', 'probes']) if (input?.[g]?.enabled !== undefined) out[g].enabled = bool(input[g].enabled, true);
+    num('lockout', 'accountThreshold', 3, 50, 'Failures on one account');
+    num('lockout', 'addressThreshold', 5, 500, 'Failures from one address');
+    num('lockout', 'windowMin', 1, 1440, 'Counted over (minutes)');
+    num('lockout', 'baseMin', 1, 60, 'First lock (minutes)');
+    num('lockout', 'maxMin', 1, 10080, 'Longest lock (minutes)');
+    num('policy', 'minLength', 8, 64, 'Shortest password');
+    for (const k of ['blockCommon', 'blockPersonal']) if (input?.policy?.[k] !== undefined) out.policy[k] = bool(input.policy[k], true);
+    num('probes', 'blockAfter', 1, 100, 'Probes before a block');
+    num('probes', 'withinMin', 1, 1440, 'Probes counted over (minutes)');
+    num('probes', 'blockForMin', 1, 10080, 'Block for (minutes)');
+    for (const k of ['extra', 'allow']) {
+        if (input?.probes?.[k] === undefined) continue;
+        const list = lines(input.probes[k]);
+        const bad = list.filter(p => !p.startsWith('/'));
+        if (bad.length) errors[`probes.${k}`] = `Each starts with "/": ${bad.slice(0, 3).join(', ')}`;
+        else out.probes[k] = [...new Set(list)].slice(0, 200);
+    }
+    if (out.lockout.maxMin < out.lockout.baseMin) errors['lockout.maxMin'] = 'The longest lock cannot be shorter than the first.';
+    if (input.signinDays !== undefined) {
+        const n = int(input.signinDays, 7, 365);
+        if (n === null) errors.signinDays = 'Keep the sign-in log 7 to 365 days.';
+        else out.signinDays = n;
+    }
+    if (input.staleAdminDays !== undefined) {
+        const n = int(input.staleAdminDays, 14, 730);
+        if (n === null) errors.staleAdminDays = '14 to 730 days.';
+        else out.staleAdminDays = n;
+    }
+    for (const k of Object.keys(DEFAULT_SETTINGS.notify)) if (input?.notify?.[k] !== undefined) out.notify[k] = bool(input.notify[k], true);
+    return {errors, settings: out};
+}
+
+/** Stored settings (possibly old or partial) with every default filled in. */
+export function mergeDefaults(s = {}) {
+    const d = DEFAULT_SETTINGS;
+    return {
+        lockout: {...d.lockout, ...(s.lockout || {})},
+        policy: {...d.policy, ...(s.policy || {})},
+        probes: {...d.probes, ...(s.probes || {})},
+        signinDays: s.signinDays ?? d.signinDays,
+        staleAdminDays: s.staleAdminDays ?? d.staleAdminDays,
+        notify: {...d.notify, ...(s.notify || {})}
+    };
+}