domma-cms 1.8.32 → 1.8.34

package/plugins/messages/plugin.js

@@ -0,0 +1,994 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import defaultConfig from './config.js';
+import {createEntry as rawCreate, deleteEntry as rawDelete, getEntry, listEntries, updateEntry as rawUpdate} from '../../server/services/collections.js';
+import {getUserById, listUsers} from '../../server/services/users.js';
+import {getEffectiveLevel} from '../../server/services/userRoles.js';
+import {getConfig} from '../../server/config.js';
+import {cleanAttachments, indexByThread, unreadBadge, unreadKey, unreadNotices} from './admin/lib/messages.js';
+import {checkInvite, checkJoin, endedText, inviteLink, joinLink, loadSecret, MAX_IN_CALL, RING_MS, whoIsCalling} from './lib/call.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+const THREADS_SLUG  = 'user-message-threads';
+const MESSAGES_SLUG = 'user-messages';
+
+// ---------------------------------------------------------------------------
+// SSE subscriber bus — Map<userId, Set<res>>
+// ---------------------------------------------------------------------------
+const subscribers = new Map();
+
+function subscribe(userId, res) {
+    if (!subscribers.has(userId)) subscribers.set(userId, new Set());
+    subscribers.get(userId).add(res);
+}
+
+function unsubscribe(userId, res) {
+    const set = subscribers.get(userId);
+    if (!set) return;
+    set.delete(res);
+    if (set.size === 0) subscribers.delete(userId);
+}
+
+/**
+ * Push an SSE event to every active connection for the listed user IDs.
+ * Broken sockets are evicted silently.
+ */
+function broadcast(userIds, eventName, payload) {
+    const data = JSON.stringify(payload);
+    for (const uid of userIds) {
+        const set = subscribers.get(uid);
+        if (!set) continue;
+        for (const res of set) {
+            try {
+                res.write(`event: ${eventName}\ndata: ${data}\n\n`);
+            } catch {
+                set.delete(res);
+            }
+        }
+        if (set.size === 0) subscribers.delete(uid);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Writes go through these, so the message cache below is dropped on every one
+// ---------------------------------------------------------------------------
+
+let messagesCache = null;   // {at, entries, byThread} - every message, briefly, and the same list keyed by thread
+const dropCache = () => { messagesCache = null; };
+const createEntry = (...a) => rawCreate(...a).finally(dropCache);
+const updateEntry = (...a) => rawUpdate(...a).finally(dropCache);
+const deleteEntry = (...a) => rawDelete(...a).finally(dropCache);
+
+/**
+ * Every message, kept 30 seconds: the sidebar asks for the unread badge every
+ * minute from every open admin tab, and each ask read the whole collection.
+ * Any write through this plugin drops it at once, so nothing stale is shown
+ * after a send, a read or a delete.
+ */
+async function allMessages() {
+    if (messagesCache && Date.now() - messagesCache.at < 30_000) return messagesCache.entries;
+    const {entries} = await listEntries(MESSAGES_SLUG, {limit: 100000});
+    // Indexed once per fill (1.7.3): before, every thread read, mark-read, prune and the per-thread unread count
+    // in GET /threads filtered the whole site's messages again - O(threads x messages) per list of conversations.
+    messagesCache = {at: Date.now(), entries, byThread: indexByThread(entries)};
+    return entries;
+}
+
+/** Messages keyed by threadId (Map), from the same cache fill as allMessages(). */
+async function messagesByThread() {
+    await allMessages();
+    return messagesCache.byThread;
+}
+
+/** One conversation's messages (every status, undeleted or not) without scanning the others'. */
+async function threadMessages(threadId) {
+    return (await messagesByThread()).get(threadId) || [];
+}
+
+/** The site's address for links in notices and emails: `site.baseUrl`, else the request's. */
+function siteOrigin(request) {
+    let base = '';
+    try { base = String(getConfig('site')?.baseUrl || ''); } catch { /* no site config */ }
+    if (/^https?:\/\/[^/\s]+/i.test(base)) return base.replace(/\/+$/, '');
+    return `${request.protocol}://${request.host || request.headers.host || request.hostname}`;
+}
+
+/** Admin by effective level (roles are data; the JWT carries no `level`). */
+function isAdminUser(request) {
+    try { return getEffectiveLevel(request.user) <= 1; } catch { return false; }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function toThread(entry) {
+    return {id: entry.id, ...entry.data, createdAt: entry.meta?.createdAt};
+}
+
+function toMessage(entry) {
+    return {id: entry.id, ...entry.data};
+}
+
+/** The longest message, and conversation name, the API keeps (1.7.2 - before, only Fastify's 1 MB body limit). */
+const MAX_BODY = 10000;
+const MAX_NAME = 80;
+
+/**
+ * Resolve minimal user summaries for a list of IDs: id, name, avatar - never the email (1.7.2). /people hides
+ * emails so a self-registered member cannot collect the site's addresses; /threads and /count handed them out
+ * for everyone in the member's conversations, which a managed group with staff in it made a directory.
+ */
+async function resolveUsers(ids) {
+    const map = {};
+    await Promise.all(ids.map(async id => {
+        try {
+            const u = await getUserById(id);
+            if (u) map[id] = {id, name: String(u.name || '').trim() || 'Unnamed member', avatar: u.avatar ?? null};
+        } catch { /* user deleted — omit */ }
+    }));
+    return map;
+}
+
+/** Lazy retention pruning — deletes messages older than effectiveRetentionDays. */
+async function pruneOldMessages(threadData, config) {
+    const ceiling = config.globalRetentionCeilingDays;
+    // A stored value below a day (written before 1.2 refused it) is read as the default.
+    const asked = Number(threadData.retentionDays);
+    const effective = Math.min(
+        Number.isFinite(asked) && asked >= 1 ? asked : config.defaultRetentionDays,
+        ceiling
+    );
+    const cutoff = new Date(Date.now() - effective * 86_400_000).toISOString();
+    const stale = (await threadMessages(threadData.id)).filter(e => e.data.createdAt < cutoff);
+    // One at a time: the file adapter rewrites the whole collection on each call,
+    // and parallel read-modify-writes lose all but one of them.
+    for (const e of stale) await deleteEntry(MESSAGES_SLUG, e.id);
+}
+
+/** Verify caller is a participant of a thread, returning the thread entry or null. */
+async function getThreadForUser(threadId, userId) {
+    const entry = await getEntry(THREADS_SLUG, threadId);
+    if (!entry) return null;
+    if (!Array.isArray(entry.data.participants) || !entry.data.participants.includes(userId)) return null;
+    return entry;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+export default async function messagesPlugin(fastify, options) {
+    const {authenticate: signedIn, requireAdmin, requirePermission} = options.auth;
+    // Every route: signed in AND holding the Messages permission (granted to
+    // admin and user; take it from a role under Roles). Until 1.2 any signed-in
+    // account could message - including roles made for people outside the
+    // business. An older core without requirePermission keeps the old rule.
+    const mayUse = typeof requirePermission === 'function' ? requirePermission('messages', 'read') : async () => {};
+    async function authenticate(request, reply) {
+        const out = await signedIn(request, reply);
+        if (reply.sent) return out;
+        return mayUse(request, reply);
+    }
+    const config = {...defaultConfig, ...(options.settings ?? {})};
+
+    function me(request) {
+        return request.user?.id ?? request.user?.sub ?? null;
+    }
+
+    // ---- Notifications (1.3; core 0.80+, feature-detected) ----
+    // A message left unread for 10 minutes: every 15 minutes, one notice per
+    // conversation to each person with one waiting - to THEM only. Reading the
+    // conversation clears it (and desktop notifications carry it off-screen).
+    const hooks = options.hooks || {};
+    const resolveNotice = (key) => { try { hooks.resolveNotification?.(key, 'unread'); } catch { /* never breaks messaging */ } };
+    if (typeof hooks.registerNotificationSource === 'function') {
+        try {
+            hooks.registerNotificationSource({
+                id: 'unread', label: 'Unread messages', severity: 'info', every: '15m',
+                description: 'A message left unread for 10 minutes - told to its recipient, once per conversation. Goes when it is read.',
+                check: async (ctx) => {
+                    const {entries: threads} = await listEntries(THREADS_SLUG, {limit: 10000});
+                    const msgs = await allMessages();
+                    const names = Object.fromEntries((await listUsers().catch(() => [])).map(u => [u.id, u.name || 'Someone']));
+                    const notices = unreadNotices(threads.map(toThread), msgs.map(toMessage), names, ctx.now?.getTime?.() ?? Date.now());
+                    for (const p of notices) await ctx.notify(p);
+                }
+            });
+        } catch { /* older engine */ }
+    }
+
+    /**
+     * SSE-compatible auth: falls back to ?token= query param when the
+     * Authorization header is absent (native EventSource cannot set headers).
+     */
+    async function authenticateSSE(request, reply) {
+        if (!request.headers.authorization && request.query.token) {
+            request.headers.authorization = `Bearer ${request.query.token}`;
+        }
+        return authenticate(request, reply);
+    }
+
+    /**
+     * The people this user may start a conversation with - the one rule for
+     * the picker (/people) and for POST /threads, which until 1.2 took any id
+     * it was sent. An admin: everyone active. Anyone else: staff (admins),
+     * people who share one of their roles, and people they already talk to.
+     */
+    async function reachable(request) {
+        return reachableFor({...(request.user || {}), id: me(request)});
+    }
+    /** reachable() for any account ({id, role, additionalRoles}) - the call's "Add people" (1.7) has no JWT. */
+    async function reachableFor(who) {
+        const users = (await listUsers().catch(() => [])).filter(u => u.disabled !== true && u.active !== false && u.isActive !== false);
+        const uid = who?.id;
+        if (isAdminUser({user: who})) return users.filter(u => u.id !== uid);
+        const rolesOf = (u) => new Set([u.role, ...(Array.isArray(u.additionalRoles) ? u.additionalRoles : [])].filter(Boolean));
+        const mine = rolesOf(who || {});
+        const {entries} = await listEntries(THREADS_SLUG, {limit: 10000});
+        const known = new Set(entries.map(toThread)
+            .filter(t => Array.isArray(t.participants) && t.participants.includes(uid))
+            .flatMap(t => t.participants));
+        const staff = (u) => { try { return getEffectiveLevel(u) <= 1; } catch { return false; } };
+        return users.filter(u => u.id !== uid && (staff(u) || known.has(u.id) || [...rolesOf(u)].some(r => mine.has(r))));
+    }
+
+    // -----------------------------------------------------------------------
+    // Calls (1.4): a video call in a conversation. The engine is core's
+    // (_lib/call, 0.103+), mounted at the end; an older core has no calls.
+    // A room is a conversation. What is running is kept here, in memory, as
+    // the engine keeps its rooms: a restart ends every call.
+    // -----------------------------------------------------------------------
+
+    const dataDir = options.dataDir || path.join(HERE, 'data');
+    let secret = null;
+    const callSecret = () => (secret ??= loadSecret(dataDir));
+    /** threadId -> {startedAt, by, byName, messageId, joinedAt, in, participants} */
+    const live = new Map();
+    let calls = null;
+
+    if (typeof hooks.registerNotificationSource === 'function') {
+        try {
+            hooks.registerNotificationSource({id: 'calls', label: 'Calls', severity: 'info', defaultOn: true,
+                description: 'Someone starts a call in a conversation - told to the others in it. Goes when the call ends.'});
+        } catch { /* older engine */ }
+    }
+
+    async function nameOf(userId) {
+        try { return String((await getUserById(userId))?.name || '').trim() || 'Someone'; } catch { return 'Someone'; }
+    }
+
+    const callInfo = (id) => {
+        const st = live.get(id);
+        return st ? {by: st.by, byName: st.byName, startedAt: new Date(st.startedAt).toISOString(), in: st.in, messageId: st.messageId} : null;
+    };
+
+    /**
+     * A "call started / ended" line in the conversation. Read by everyone
+     * already: the live notice and the notification do the telling, so a
+     * call line never adds to the unread badge or the unread reminders.
+     */
+    /**
+     * Set a thread's last-message fields from a FRESH read - never write back a copy read before an await, or a
+     * member removed meanwhile would be put back (participants is the thread's own list).
+     */
+    async function touchThread(threadId, fields) {
+        const fresh = await getEntry(THREADS_SLUG, threadId).catch(() => null);
+        if (fresh) await updateEntry(THREADS_SLUG, threadId, {...fresh.data, ...fields});
+    }
+
+    async function postCallLine(threadId, senderId, body, call, bringBack) {
+        const entry = await getEntry(THREADS_SLUG, threadId).catch(() => null);
+        if (!entry) return null;
+        const participants = entry.data.participants ?? [];
+        const now = new Date().toISOString();
+        const msgEntry = await createEntry(MESSAGES_SLUG, {
+            threadId, senderId, kind: 'call', call, body, attachments: [],
+            createdAt: now, editedAt: null, deletedAt: null, readBy: [...participants]
+        }, {createdBy: senderId, source: 'messages'});
+        await touchThread(threadId, {...(bringBack ? {archivedBy: []} : {}), lastMessageAt: now, lastMessagePreview: body.slice(0, 120)});
+        const message = toMessage(msgEntry);
+        broadcast(participants, 'message:new', {threadId, message});
+        return message;
+    }
+
+    /** Start a conversation's call, or hand back the one running. One line, one notice, however many ask at once. */
+    async function startCall(entry, userId) {
+        const id = entry.id;
+        if (live.has(id)) return live.get(id);
+        const participants = [...(entry.data.participants ?? [])];
+        // Held before the first await: a second click, or a second person, finds it running.
+        const st = {startedAt: Date.now(), by: userId, byName: 'Someone', messageId: null, joinedAt: 0, in: 0, participants, invited: new Set()};
+        live.set(id, st);
+        st.byName = await nameOf(userId);
+        const line = await postCallLine(id, userId, `${st.byName} started a call`, {event: 'started'}, true).catch(err => {
+            fastify.log?.warn?.(`[messages] call line not written: ${err?.message || err}`);
+            return null;
+        });
+        st.messageId = line?.id ?? null;
+        broadcast(participants, 'call:started', {threadId: id, call: callInfo(id)});
+        const others = participants.filter(p => p !== userId);
+        if (others.length) {
+            const group = entry.data.kind !== 'dm';
+            try {
+                hooks.notify?.({
+                    title: `${st.byName} is calling${group && entry.data.name ? ` - ${entry.data.name}` : ''}`.slice(0, 200),
+                    body: 'Open Messages and click Join.',
+                    severity: 'info', link: '#/plugins/messages', source: 'calls',
+                    dedupeKey: `call:${id}`, audience: {userIds: others}
+                });
+            } catch { /* a notice never breaks a call */ }
+        }
+        return st;
+    }
+
+    async function endCall(id) {
+        const st = live.get(id);
+        if (!st) return;
+        live.delete(id);
+        // Nobody is "in the call" any more: the next call's lines are unread for everyone not in THAT one.
+        present.delete(id);
+        const now = Date.now();
+        await postCallLine(id, st.by, endedText(st.joinedAt || st.startedAt, now, Boolean(st.joinedAt)),
+            {event: 'ended', minutes: st.joinedAt ? Math.round((now - st.joinedAt) / 60e3) : 0}, false)
+            .catch(err => fastify.log?.warn?.(`[messages] call line not written: ${err?.message || err}`));
+        // A new call may have started while the line was written (someone clicked Call, or joined with their
+        // link): it has the same notice key, so this one's ending must not clear it or say "ended".
+        if (live.has(id)) return;
+        broadcast(st.participants, 'call:ended', {threadId: id});
+        try { hooks.resolveNotification?.(`call:${id}`, 'calls'); } catch { /* never breaks messaging */ }
+    }
+
+    /** Every few seconds: how many are in each call; an emptied call (or one nobody came to) ends. */
+    let sweeping = false;
+    async function sweepCalls(now = Date.now()) {
+        if (sweeping || !calls) return;
+        sweeping = true;
+        try {
+            for (const [id, st] of [...live]) {
+                const n = calls.countRoom(id).in;
+                if (n > 0 && !st.joinedAt) st.joinedAt = now;
+                if (n !== st.in) {
+                    st.in = n;
+                    broadcast(st.participants, 'call:updated', {threadId: id, call: callInfo(id)});
+                }
+                if (n === 0 && (st.joinedAt || now - st.startedAt > RING_MS)) await endCall(id);
+            }
+        } finally {
+            sweeping = false;
+        }
+    }
+
+    // -----------------------------------------------------------------------
+    // SSE stream
+    // -----------------------------------------------------------------------
+
+    fastify.get('/stream', {preHandler: [authenticateSSE]}, async (request, reply) => {
+        const userId = me(request);
+
+        reply.raw.setHeader('Content-Type', 'text/event-stream');
+        reply.raw.setHeader('Cache-Control', 'no-cache');
+        reply.raw.setHeader('Connection', 'keep-alive');
+        reply.raw.setHeader('X-Accel-Buffering', 'no');
+        reply.raw.flushHeaders();
+
+        subscribe(userId, reply.raw);
+
+        const keepalive = setInterval(() => {
+            try { reply.raw.write(': ping\n\n'); } catch { clearInterval(keepalive); }
+        }, 25_000);
+
+        request.raw.on('close', () => {
+            clearInterval(keepalive);
+            unsubscribe(userId, reply.raw);
+        });
+
+        // Keep the connection open — do NOT call reply.send()
+        await new Promise(resolve => request.raw.on('close', resolve));
+    });
+
+    // -----------------------------------------------------------------------
+    // Threads — list
+    // -----------------------------------------------------------------------
+
+    fastify.get('/threads', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const {entries} = await listEntries(THREADS_SLUG, {limit: 10000});
+
+        const threads = entries
+            .map(toThread)
+            .filter(t => Array.isArray(t.participants) && t.participants.includes(userId))
+            .sort((a, b) => (b.lastMessageAt ?? '') > (a.lastMessageAt ?? '') ? 1 : -1);
+
+        // Resolve participant names + per-thread unread counts
+        const allUserIds = [...new Set(threads.flatMap(t => t.participants ?? []))];
+        const userMap = await resolveUsers(allUserIds);
+
+        const byThread = await messagesByThread();
+        const withMeta = threads.map(t => {
+            const unread = (byThread.get(t.id) || []).filter(e =>
+                !e.data.deletedAt &&
+                !(e.data.readBy ?? []).includes(userId)
+            ).length;
+            return {...t, participants: (t.participants ?? []).map(id => userMap[id] ?? {id}), unread, call: callInfo(t.id)};
+        });
+
+        return reply.send(withMeta);
+    });
+
+    // -----------------------------------------------------------------------
+    // Threads — create
+    // -----------------------------------------------------------------------
+
+    fastify.post('/threads', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const {kind = 'dm', name, participants = []} = request.body ?? {};
+
+        if (!['dm', 'group-adhoc', 'group-managed'].includes(kind)) {
+            return reply.code(400).send({error: 'Invalid kind'});
+        }
+        if (kind === 'group-managed' && !isAdminUser(request)) {
+            return reply.code(403).send({error: 'Only admins can create managed groups'});
+        }
+
+        // Only real, active people this user may reach - never an id guessed or made up.
+        if (!Array.isArray(participants) || participants.some(p => typeof p !== 'string' || !p) || participants.length > 50) {
+            return reply.code(400).send({error: 'participants must be a list of user ids'});
+        }
+        const allowed = new Set((await reachable(request)).map(u => u.id));
+        if (participants.some(p => p !== userId && !allowed.has(p))) {
+            return reply.code(403).send({error: 'You cannot message one of those people'});
+        }
+
+        // Ensure current user is in the list
+        const allParticipants = [...new Set([userId, ...participants])];
+
+        if (kind === 'dm') {
+            if (allParticipants.length !== 2) {
+                return reply.code(400).send({error: 'DMs require exactly one other participant'});
+            }
+            // Deduplicate: return existing DM if one already exists
+            const sorted = [...allParticipants].sort();
+            const {entries} = await listEntries(THREADS_SLUG, {limit: 10000});
+            const existing = entries.find(e =>
+                e.data.kind === 'dm' &&
+                Array.isArray(e.data.participants) &&
+                [...e.data.participants].sort().join('|') === sorted.join('|')
+            );
+            if (existing) return reply.send(toThread(existing));
+        }
+
+        if ((kind === 'group-adhoc' || kind === 'group-managed') && !name?.trim()) {
+            return reply.code(400).send({error: 'Groups require a name'});
+        }
+
+        const now = new Date().toISOString();
+        const entry = await createEntry(THREADS_SLUG, {
+            kind,
+            name: name?.trim() ?? null,
+            participants: kind === 'dm' ? [...allParticipants].sort() : allParticipants,
+            createdBy: userId,
+            retentionDays: null,
+            lastMessageAt: now,
+            lastMessagePreview: ''
+        }, {createdBy: userId, source: 'messages'});
+
+        const thread = toThread(entry);
+
+        // Notify other participants
+        const others = allParticipants.filter(id => id !== userId);
+        broadcast(others, 'thread:created', thread);
+
+        return reply.code(201).send(thread);
+    });
+
+    // -----------------------------------------------------------------------
+    // Threads — update (rename / change retention)
+    // -----------------------------------------------------------------------
+
+    fastify.put('/threads/:id', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const entry = await getThreadForUser(request.params.id, userId);
+        if (!entry) return reply.code(404).send({error: 'Thread not found'});
+
+        const {name, retentionDays} = request.body ?? {};
+        const data = {...entry.data};
+
+        // Only thread creator can rename ad-hoc; admins can rename managed
+        if (name !== undefined) {
+            if (data.kind !== 'dm' && (data.createdBy === userId || isAdminUser(request))) {
+                data.name = String(name).trim().slice(0, MAX_NAME);
+            }
+        }
+
+        // How long messages are kept is the creator's (or an admin's) to say, and
+        // never less than a day: until 1.2 any participant could set it, and a
+        // negative number put the cut-off in the future - the next read deleted
+        // every message in the conversation, for everyone.
+        if (retentionDays !== undefined) {
+            if (data.createdBy !== userId && !isAdminUser(request)) {
+                return reply.code(403).send({error: 'Only whoever started this conversation can change how long it keeps messages'});
+            }
+            if (retentionDays === null || retentionDays === '') {
+                data.retentionDays = null;
+            } else {
+                const days = Number(retentionDays);
+                if (!Number.isInteger(days) || days < 1) return reply.code(400).send({error: 'retentionDays must be a whole number of days, 1 or more'});
+                data.retentionDays = Math.min(days, config.globalRetentionCeilingDays);
+            }
+        }
+
+        const updated = await updateEntry(THREADS_SLUG, entry.id, data);
+        const thread = toThread(updated);
+        broadcast(data.participants, 'thread:updated', thread);
+        return reply.send(thread);
+    });
+
+    // -----------------------------------------------------------------------
+    // Threads — leave / delete
+    // -----------------------------------------------------------------------
+
+    fastify.delete('/threads/:id', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const entry = await getThreadForUser(request.params.id, userId);
+        if (!entry) return reply.code(404).send({error: 'Thread not found'});
+
+        const data = {...entry.data};
+        data.participants = data.participants.filter(id => id !== userId);
+
+        if (data.participants.length === 0) {
+            // Last participant — purge thread and all its messages
+            for (const e of await threadMessages(entry.id)) await deleteEntry(MESSAGES_SLUG, e.id);
+            await deleteEntry(THREADS_SLUG, entry.id);
+            // Nobody left to call: the call (if any) ends, with no line to write it in.
+            live.delete(entry.id);
+            calls?.closeRoom(entry.id);
+        } else {
+            await updateEntry(THREADS_SLUG, entry.id, data);
+            broadcast(data.participants, 'thread:updated', toThread({id: entry.id, data}));
+            // Out of the conversation, out of its call - and no more news of it.
+            calls?.kickFromRoom?.(entry.id, `${entry.id}:${userId}`);
+            const st = live.get(entry.id);
+            if (st) st.participants = st.participants.filter(p => p !== userId);
+        }
+
+        return reply.send({success: true});
+    });
+
+    // -----------------------------------------------------------------------
+    // Messages — list (paginated)
+    // -----------------------------------------------------------------------
+
+    fastify.get('/threads/:id/messages', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const entry = await getThreadForUser(request.params.id, userId);
+        if (!entry) return reply.code(404).send({error: 'Thread not found'});
+
+        // Lazy retention pruning
+        await pruneOldMessages({id: entry.id, ...entry.data}, config);
+
+        const {before, limit = 50} = request.query;
+        let msgs = (await threadMessages(entry.id))
+            .map(toMessage)
+            .sort((a, b) => (a.createdAt ?? '') < (b.createdAt ?? '') ? -1 : 1);
+
+        if (before) msgs = msgs.filter(m => m.createdAt < before);
+        msgs = msgs.slice(-Math.min(Number(limit) || 50, 200));
+
+        return reply.send(msgs);
+    });
+
+    // -----------------------------------------------------------------------
+    // Messages — send
+    // -----------------------------------------------------------------------
+
+    fastify.post('/threads/:id/messages', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const threadEntry = await getThreadForUser(request.params.id, userId);
+        if (!threadEntry) return reply.code(404).send({error: 'Thread not found'});
+
+        const body = String(request.body?.body ?? '').slice(0, MAX_BODY);
+        // Only media names and file facts are kept - the address is rebuilt from the name,
+        // so a message can never carry a javascript: or off-site link into someone's screen.
+        const attachments = cleanAttachments(request.body?.attachments);
+        if (!body.trim() && attachments.length === 0) {
+            return reply.code(400).send({error: 'Message must have a body or attachment'});
+        }
+
+        const now = new Date().toISOString();
+        const msgEntry = await createEntry(MESSAGES_SLUG, {
+            threadId: threadEntry.id,
+            senderId: userId,
+            body: String(body).trim(),
+            attachments,
+            createdAt: now,
+            editedAt: null,
+            deletedAt: null,
+            readBy: [userId]
+        }, {createdBy: userId, source: 'messages'});
+
+        // Update thread preview
+        const preview = body.trim().slice(0, 120)
+            || (attachments.length ? `Attachment: ${attachments[0].filename}`.slice(0, 120) : '');
+        // A new message brings an archived conversation back to everyone's inbox, as mail does.
+        await updateEntry(THREADS_SLUG, threadEntry.id, {
+            ...threadEntry.data,
+            archivedBy: [],
+            lastMessageAt: now,
+            lastMessagePreview: preview
+        });
+
+        const message = toMessage(msgEntry);
+        const others = (threadEntry.data.participants ?? []).filter(id => id !== userId);
+        broadcast(others, 'message:new', {threadId: threadEntry.id, message});
+
+        return reply.code(201).send(message);
+    });
+
+    // -----------------------------------------------------------------------
+    // Messages — edit
+    // -----------------------------------------------------------------------
+
+    fastify.put('/threads/:id/messages/:msgId', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const threadEntry = await getThreadForUser(request.params.id, userId);
+        if (!threadEntry) return reply.code(404).send({error: 'Thread not found'});
+
+        const msgEntry = await getEntry(MESSAGES_SLUG, request.params.msgId);
+        if (!msgEntry || msgEntry.data.threadId !== threadEntry.id) {
+            return reply.code(404).send({error: 'Message not found'});
+        }
+        if (msgEntry.data.senderId !== userId) {
+            return reply.code(403).send({error: 'Cannot edit another user\'s message'});
+        }
+        if (msgEntry.data.deletedAt) {
+            return reply.code(403).send({error: 'Cannot edit a deleted message'});
+        }
+        if (msgEntry.data.kind === 'call') {
+            return reply.code(403).send({error: 'A call line cannot be edited'});
+        }
+
+        const ageMs = Date.now() - new Date(msgEntry.data.createdAt).getTime();
+        if (ageMs > config.editWindowMinutes * 60_000) {
+            return reply.code(403).send({error: `Edit window of ${config.editWindowMinutes} minutes has passed`});
+        }
+
+        const {body} = request.body ?? {};
+        const now = new Date().toISOString();
+        const updated = await updateEntry(MESSAGES_SLUG, msgEntry.id, {
+            ...msgEntry.data,
+            body: body !== undefined ? String(body).trim().slice(0, MAX_BODY) : msgEntry.data.body,
+            editedAt: now
+        });
+
+        const message = toMessage(updated);
+        const others = (threadEntry.data.participants ?? []).filter(id => id !== userId);
+        broadcast(others, 'message:edited', {threadId: threadEntry.id, message});
+
+        return reply.send(message);
+    });
+
+    // -----------------------------------------------------------------------
+    // Messages — soft delete
+    // -----------------------------------------------------------------------
+
+    fastify.delete('/threads/:id/messages/:msgId', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const threadEntry = await getThreadForUser(request.params.id, userId);
+        if (!threadEntry) return reply.code(404).send({error: 'Thread not found'});
+
+        const msgEntry = await getEntry(MESSAGES_SLUG, request.params.msgId);
+        if (!msgEntry || msgEntry.data.threadId !== threadEntry.id) {
+            return reply.code(404).send({error: 'Message not found'});
+        }
+
+        // The sender, an admin - or in a group, whoever started it. Never the other
+        // side of a one-to-one conversation: starting it first is not moderation.
+        const groupOwner = threadEntry.data.kind !== 'dm' && threadEntry.data.createdBy === userId;
+        if (msgEntry.data.senderId !== userId && !groupOwner && !isAdminUser(request)) {
+            return reply.code(403).send({error: 'Cannot delete this message'});
+        }
+
+        const now = new Date().toISOString();
+        const updated = await updateEntry(MESSAGES_SLUG, msgEntry.id, {
+            ...msgEntry.data,
+            body: '',
+            attachments: [],
+            deletedAt: now
+        });
+
+        const message = toMessage(updated);
+        const others = (threadEntry.data.participants ?? []).filter(id => id !== userId);
+        broadcast(others, 'message:deleted', {threadId: threadEntry.id, message});
+
+        return reply.send(message);
+    });
+
+    // -----------------------------------------------------------------------
+    // Calls (1.4) - start this conversation's call, or join the one running.
+    // Answers the caller's OWN short-lived link to the call page.
+    // -----------------------------------------------------------------------
+
+    fastify.post('/threads/:id/call', {preHandler: [authenticate], config: {rateLimit: {max: 30, timeWindow: '1 minute'}}}, async (request, reply) => {
+        const userId = me(request);
+        const entry = await getThreadForUser(request.params.id, userId);
+        if (!entry) return reply.code(404).send({error: 'Thread not found'});
+        if (!calls) return reply.code(501).send({error: 'Calls need Domma CMS 0.103 or later.'});
+        await startCall(entry, userId);
+        return reply.send({url: joinLink(callSecret(), entry.id, userId), call: callInfo(entry.id), max: MAX_IN_CALL});
+    });
+
+    // -----------------------------------------------------------------------
+    // Messages — mark read
+    // -----------------------------------------------------------------------
+
+    fastify.post('/threads/:id/read', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const threadEntry = await getThreadForUser(request.params.id, userId);
+        if (!threadEntry) return reply.code(404).send({error: 'Thread not found'});
+
+        const unread = (await threadMessages(threadEntry.id)).filter(e =>
+            !e.data.deletedAt &&
+            !(e.data.readBy ?? []).includes(userId)
+        );
+
+        // Sequential for the same reason as pruning: parallel updates lose all but one.
+        for (const e of unread) {
+            await updateEntry(MESSAGES_SLUG, e.id, {...e.data, readBy: [...(e.data.readBy ?? []), userId]});
+        }
+        resolveNotice(unreadKey(threadEntry.id, userId));
+
+        return reply.send({unread: 0});
+    });
+
+    // -----------------------------------------------------------------------
+    // Who am I here - the screen's rights come from the server, not from the
+    // stored user (which carries a role name, not a level).
+    // -----------------------------------------------------------------------
+
+    fastify.get('/me', {preHandler: [authenticate]}, async (request) => ({
+        id: me(request),
+        name: await nameOf(me(request)),   // 1.5: Call… names a new group after everyone in it
+        isAdmin: isAdminUser(request),
+        editWindowMinutes: config.editWindowMinutes,
+        defaultRetentionDays: config.defaultRetentionDays,
+        globalRetentionCeilingDays: config.globalRetentionCeilingDays
+    }));
+
+    // People to start a conversation with. /api/users needs the users
+    // permission, which most people who message do not hold - so the picker
+    // was empty for them. Id and NAME only - never an email (a self-registered
+    // member must not be able to collect the site's addresses). An admin sees
+    // everyone; anyone else sees staff (admins), people who share one of their
+    // roles, and people they already have a conversation with.
+    fastify.get('/people', {preHandler: [authenticate]}, async (request) => {
+        return (await reachable(request)).map(u => ({id: u.id, name: String(u.name || '').trim() || 'Unnamed member'}));
+    });
+
+    // The sidebar badge (countUrl): unread in conversations this user has not archived.
+    fastify.get('/count', {preHandler: [authenticate]}, async (request) => {
+        const userId = me(request);
+        const {entries} = await listEntries(THREADS_SLUG, {limit: 10000});
+        const mine = entries.map(toThread).filter(t => Array.isArray(t.participants) && t.participants.includes(userId));
+        const users = await resolveUsers([...new Set(mine.flatMap(t => t.participants))]);
+        const msgs = await allMessages();
+        const unreadBy = {};
+        for (const e of msgs) {
+            if (e.data.deletedAt || (e.data.readBy ?? []).includes(userId)) continue;
+            unreadBy[e.data.threadId] = (unreadBy[e.data.threadId] || 0) + 1;
+        }
+        return unreadBadge(mine.map(t => ({...t, participants: t.participants.map(id => users[id] ?? {id}), unread: unreadBy[t.id] || 0})), userId);
+    });
+
+    // Mark unread: the newest message from someone else counts as unread again.
+    fastify.post('/threads/:id/unread', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const threadEntry = await getThreadForUser(request.params.id, userId);
+        if (!threadEntry) return reply.code(404).send({error: 'Thread not found'});
+        const latest = (await threadMessages(threadEntry.id))
+            .filter(e => !e.data.deletedAt && e.data.senderId !== userId)
+            .sort((a, b) => String(b.data.createdAt).localeCompare(String(a.data.createdAt)))[0];
+        if (!latest) return reply.code(409).send({error: 'Nothing from anyone else to mark unread'});
+        await updateEntry(MESSAGES_SLUG, latest.id, {...latest.data, readBy: (latest.data.readBy ?? []).filter(id => id !== userId)});
+        return reply.send({unread: 1});
+    });
+
+    // Archive / unarchive - per person: the others still see the conversation.
+    fastify.post('/threads/:id/archive', {preHandler: [authenticate]}, async (request, reply) => {
+        const userId = me(request);
+        const entry = await getThreadForUser(request.params.id, userId);
+        if (!entry) return reply.code(404).send({error: 'Thread not found'});
+        const archived = request.body?.archived !== false;
+        const others = (entry.data.archivedBy ?? []).filter(id => id !== userId);
+        const data = {...entry.data, archivedBy: archived ? [...others, userId] : others};
+        await updateEntry(THREADS_SLUG, entry.id, data);
+        if (archived) resolveNotice(unreadKey(entry.id, userId));   // put away: not waiting on them any more
+        return reply.send({archived});
+    });
+
+    // -----------------------------------------------------------------------
+    // Managed groups (admin only)
+    // -----------------------------------------------------------------------
+
+    fastify.get('/managed-groups', {preHandler: [authenticate, requireAdmin]}, async (request, reply) => {
+        const {entries} = await listEntries(THREADS_SLUG, {limit: 10000});
+        const groups = entries
+            .filter(e => e.data.kind === 'group-managed')
+            .map(toThread)
+            .sort((a, b) => (a.name ?? '') < (b.name ?? '') ? -1 : 1);
+        return reply.send(groups);
+    });
+
+    fastify.post('/managed-groups', {preHandler: [authenticate, requireAdmin]}, async (request, reply) => {
+        const userId = me(request);
+        const {name, participants = []} = request.body ?? {};
+
+        if (!name?.trim()) return reply.code(400).send({error: 'Group name is required'});
+
+        const allParticipants = [...new Set([userId, ...participants])];
+        const now = new Date().toISOString();
+
+        const entry = await createEntry(THREADS_SLUG, {
+            kind: 'group-managed',
+            name: name.trim(),
+            participants: allParticipants,
+            createdBy: userId,
+            retentionDays: null,
+            lastMessageAt: now,
+            lastMessagePreview: ''
+        }, {createdBy: userId, source: 'messages'});
+
+        const thread = toThread(entry);
+        const others = allParticipants.filter(id => id !== userId);
+        broadcast(others, 'thread:created', thread);
+
+        return reply.code(201).send(thread);
+    });
+
+    // -----------------------------------------------------------------------
+    // Calls (1.4): the engine's routes, under /call. Who may join: someone
+    // holding a link made for them (POST /threads/:id/call) who is still in
+    // the conversation. Joining a conversation whose call is not running
+    // (given up unanswered, or the site restarted) starts it again.
+    // -----------------------------------------------------------------------
+    // The call's chat (1.6) lives IN the conversation: what someone types in the call is posted as an ordinary
+    // message from them (saved with `callChat: {id, seq, who}` - the engine's item), so it is in the thread
+    // afterwards, once. System lines are not posted (the started/ended lines say it). The engine hands save()
+    // the joiner's identity, `<thread>:<user>` (never sent to a browser), which names the sender. Everyone in
+    // the call at the time (tracked from the joined/left lines) has already read it; the others get it unread.
+    // load() gives the call the conversation's earlier call messages, so a call reopened shows them.
+    const present = new Map();   // threadId -> Set<userId> in the call now
+    const callChat = {
+        async load(threadId) {
+            const msgs = (await threadMessages(threadId)).filter(e => e.data.callChat && !e.data.deletedAt)
+                .map(toMessage).sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt))).slice(-500);
+            const names = {};
+            for (const id of new Set(msgs.map(m => m.senderId))) names[id] = await nameOf(id);
+            return msgs.map(m => ({id: String(m.callChat.id || m.id), seq: Number(m.callChat.seq) || 0, at: m.createdAt, kind: 'chat',
+                from: '', who: String(m.callChat.who || ''), name: names[m.senderId] || 'Someone', text: String(m.body || '')}));
+        },
+        async save(threadId, item, meta = {}) {
+            const identity = String(meta.identity || '');
+            const userId = identity.startsWith(`${threadId}:`) ? identity.slice(threadId.length + 1) : '';
+            if (!userId) return;
+            if (item.kind === 'system') {
+                const inCall = present.get(threadId) || new Set();
+                if (item.event === 'joined') inCall.add(userId);
+                else if (item.event === 'left') inCall.delete(userId);
+                if (inCall.size) present.set(threadId, inCall); else present.delete(threadId);
+                return;
+            }
+            if (item.kind !== 'chat' || !String(item.text || '').trim()) return;
+            // Still in the conversation (someone taken out of it is taken out of its call too).
+            const threadEntry = await getThreadForUser(threadId, userId);
+            if (!threadEntry) return;
+            const now = new Date().toISOString();
+            const body = String(item.text).trim().slice(0, 1000);
+            const readBy = [...new Set([userId, ...(present.get(threadId) || [])])]
+                .filter(id => (threadEntry.data.participants ?? []).includes(id));
+            const msgEntry = await createEntry(MESSAGES_SLUG, {
+                threadId, senderId: userId, body, attachments: [], createdAt: now, editedAt: null, deletedAt: null, readBy,
+                callChat: {id: String(item.id).slice(0, 64), seq: Number(item.seq) || 0, who: String(item.who || '').slice(0, 64)}
+            }, {createdBy: userId, source: 'messages'});
+            await touchThread(threadId, {archivedBy: [], lastMessageAt: now, lastMessagePreview: body.slice(0, 120)});
+            // Everyone - the sender too: their Messages screen did not send it.
+            broadcast(threadEntry.data.participants ?? [], 'message:new', {threadId, message: toMessage(msgEntry)});
+        }
+    };
+
+    try {
+        const {mountCallRoutes} = await import('../_lib/call/routes.js');
+        // Add people (1.7; a core with services/callInvites.js): anyone in the call rings a team member who is not in
+        // the conversation - someone they may reach (reachableFor). The invitee gets a notification, a direct message
+        // (Messages itself, through core's messenger hook) and, when ticked, the email - each with their OWN
+        // invitation link, good for this call while it runs (`st.invited`). No contacts, no typed emails, no copied link.
+        let invites = null;
+        try { invites = await import('../../server/services/callInvites.js'); } catch { invites = null; }
+        const inviterOf = (room, identity) => (String(identity || '').startsWith(`${room}:`) ? String(identity).slice(room.length + 1) : '');
+        const invite = invites ? {
+            search: async (room, q, {identity}) => {
+                const uid = inviterOf(room, identity);
+                const entry = uid && live.has(room) ? await getThreadForUser(room, uid) : null;
+                if (!entry) return [];
+                const reach = new Set((await reachableFor(await getUserById(uid).catch(() => null))).map(u => u.id));
+                return invites.searchInvitees({hostUserId: uid, q, contacts: false, excludeUserIds: entry.data.participants ?? [], teamFilter: (u) => reach.has(u.id)});
+            },
+            send: async (room, people, {identity, name, via, request}) => {
+                const uid = inviterOf(room, identity);
+                const entry = uid ? await getThreadForUser(room, uid) : null;
+                const st = live.get(room);
+                if (!entry || !st) return {error: 'This call has ended.'};
+                if (!people.length) return {error: 'A call in Messages has no link to copy - add team members instead.'};
+                const inConversation = new Set(entry.data.participants ?? []);
+                const reach = new Set((await reachableFor(await getUserById(uid).catch(() => null))).map(u => u.id));
+                const targets = await invites.resolveInvitees(people, {hostUserId: uid, contacts: false, emails: false,
+                    teamFilter: (u) => reach.has(u.id) && !inConversation.has(u.id)});
+                for (const t of targets) if (t.kind === 'user') st.invited.add(t.id);
+                const base = invites.inviteOrigin ? invites.inviteOrigin(request) : siteOrigin(request);
+                const results = await invites.deliverInvites(targets, {linkFor: (t) => `${base}${inviteLink(callSecret(), room, t.id)}`,
+                    hostName: name || await nameOf(uid), hostUserId: uid, title: entry.data.kind === 'dm' ? '' : String(entry.data.name || ''),
+                    via, key: `messages:${room}`, log: fastify.log, expiresAt: new Date(Date.now() + 2 * 3600e3).toISOString()});
+                return {results};
+            }
+        } : null;
+        calls = mountCallRoutes(fastify, {prefix: '/call', ns: 'messages', chat: callChat, ...(invite ? {invite} : {}), resolve: async (request, room, body) => {
+            const invited = String(body?.i ?? '') === '1';
+            const userId = invited ? checkInvite(callSecret(), room, body) : checkJoin(callSecret(), room, body);
+            if (!userId) return null;
+            const entry = await getEntry(THREADS_SLUG, room).catch(() => null);
+            if (!entry) return null;
+            const thread = {id: entry.id, ...entry.data};
+            // An invitation lets its person into THIS call only, while it runs.
+            if (invited && !live.get(entry.id)?.invited?.has(userId)) return null;
+            const user = await getUserById(userId).catch(() => null);
+            const names = {};
+            if (thread.kind === 'dm') for (const id of thread.participants ?? []) names[id] = await nameOf(id);
+            const who = whoIsCalling(thread, user, userId, names, {invited});
+            if (!who) return null;
+            // Someone rung in from outside the conversation sees the call's chat only from when they joined - never
+            // the conversation's earlier call messages (the engine's `history: false`).
+            if (invited && !(thread.participants ?? []).includes(userId)) who.history = false;
+            const st = live.get(entry.id) || await startCall(entry, userId);
+            if (!st.joinedAt) st.joinedAt = Date.now();
+            return who;
+        }});
+        const sweeper = setInterval(() => { sweepCalls().catch(() => {}); }, options.callSweepMs || 5000);
+        sweeper.unref?.();
+        fastify.addHook('onClose', async () => clearInterval(sweeper));
+    } catch (err) {
+        fastify.log?.warn?.(`[messages] calls unavailable on this CMS: ${err?.message || err}`);
+    }
+
+    // Direct messages for core (1.7; hooks.js 7c): a call's "Add people" in any Tool sends its Join link as a direct
+    // message from the host to a team member - the pair's DM (made when there is none), posted as the host.
+    if (typeof hooks.registerDirectMessenger === 'function') {
+        try { hooks.registerDirectMessenger((msg) => sendDirect(msg)); } catch { /* older engine */ }
+    }
+    async function sendDirect({fromUserId, toUserId, text}) {
+        const body = String(text || '').trim().slice(0, 4000);
+        if (!fromUserId || !toUserId || fromUserId === toUserId || !body) return {sent: false, reason: 'nobody to send it to'};
+        const [from, to] = await Promise.all([getUserById(fromUserId).catch(() => null), getUserById(toUserId).catch(() => null)]);
+        const active = (u) => u && u.disabled !== true && u.active !== false && u.isActive !== false;
+        if (!active(from) || !active(to)) return {sent: false, reason: 'the account is switched off'};
+        // Messages' own rule for who may message whom (the same as the picker and POST /threads).
+        if (!(await reachableFor(from)).some(u => u.id === to.id)) return {sent: false, reason: 'you cannot message them in Messages'};
+        const pair = [String(fromUserId), String(toUserId)].sort();
+        const {entries} = await listEntries(THREADS_SLUG, {limit: 10000});
+        let thread = entries.find(e => e.data.kind === 'dm' && Array.isArray(e.data.participants) && [...e.data.participants].sort().join('|') === pair.join('|'));
+        const now = new Date().toISOString();
+        if (!thread) {
+            thread = await createEntry(THREADS_SLUG, {kind: 'dm', name: null, participants: pair, createdBy: fromUserId, retentionDays: null,
+                lastMessageAt: now, lastMessagePreview: ''}, {createdBy: fromUserId, source: 'messages'});
+            broadcast([toUserId], 'thread:created', toThread(thread));
+        }
+        const msgEntry = await createEntry(MESSAGES_SLUG, {threadId: thread.id, senderId: fromUserId, body, attachments: [], createdAt: now,
+            editedAt: null, deletedAt: null, readBy: [fromUserId]}, {createdBy: fromUserId, source: 'messages'});
+        await touchThread(thread.id, {archivedBy: [], lastMessageAt: now, lastMessagePreview: body.slice(0, 120)});
+        broadcast(pair, 'message:new', {threadId: thread.id, message: toMessage(msgEntry)});
+        return {sent: true};
+    }
+
+    // For the tests: the sweep, run now, and what is running.
+    options.onCalls?.({sweep: (now) => sweepCalls(now), live, rooms: calls, present, sendDirect});
+}