domma-cms 1.8.32 → 1.8.34

package/plugins/messages/collections/user-message-threads/schema.json

@@ -0,0 +1,22 @@
+{
+  "slug": "user-message-threads",
+  "title": "Message Threads",
+  "description": "Conversation threads managed by the Messages plugin.",
+  "plugin": "messages",
+  "fields": [
+    { "name": "kind",              "label": "Kind",             "type": "select", "options": ["dm", "group-adhoc", "group-managed"], "required": true },
+    { "name": "name",              "label": "Name",             "type": "text" },
+    { "name": "participants",      "label": "Participants",     "type": "array",  "items": "string", "default": [] },
+    { "name": "createdBy",         "label": "Created By",       "type": "text",   "required": true },
+    { "name": "retentionDays",     "label": "Retention Days",   "type": "number" },
+    { "name": "lastMessageAt",     "label": "Last Message At",  "type": "datetime" },
+    { "name": "lastMessagePreview","label": "Last Preview",     "type": "text" }
+  ],
+  "api": {
+    "create": { "enabled": false, "access": "admin" },
+    "read":   { "enabled": false, "access": "admin" },
+    "update": { "enabled": false, "access": "admin" },
+    "delete": { "enabled": false, "access": "admin" }
+  },
+  "storage": {}
+}

package/plugins/messages/collections/user-messages/schema.json

@@ -0,0 +1,23 @@
+{
+  "slug": "user-messages",
+  "title": "Messages",
+  "description": "Individual messages managed by the Messages plugin.",
+  "plugin": "messages",
+  "fields": [
+    { "name": "threadId",    "label": "Thread ID",   "type": "text",   "required": true },
+    { "name": "senderId",    "label": "Sender ID",   "type": "text",   "required": true },
+    { "name": "body",        "label": "Body",        "type": "textarea" },
+    { "name": "attachments", "label": "Attachments", "type": "array",  "items": "object", "default": [] },
+    { "name": "createdAt",   "label": "Created At",  "type": "datetime", "required": true },
+    { "name": "editedAt",    "label": "Edited At",   "type": "datetime" },
+    { "name": "deletedAt",   "label": "Deleted At",  "type": "datetime" },
+    { "name": "readBy",      "label": "Read By",     "type": "array",  "items": "string", "default": [] }
+  ],
+  "api": {
+    "create": { "enabled": false, "access": "admin" },
+    "read":   { "enabled": false, "access": "admin" },
+    "update": { "enabled": false, "access": "admin" },
+    "delete": { "enabled": false, "access": "admin" }
+  },
+  "storage": {}
+}

package/plugins/messages/config.js

@@ -0,0 +1,14 @@
+/**
+ * Messages defaults. There is no `scope` or `storage` key (both were listed
+ * until 1.3.1 and nothing read either): a conversation's participants are its
+ * scope, and the two collections' own schemas decide their storage - the file
+ * adapter unless a collection is moved to MongoDB (Collections > Storage).
+ */
+export default {
+    /** Hard upper limit on per-thread retention; users cannot exceed this. */
+    globalRetentionCeilingDays: 365,
+    /** Default retention when a thread has no per-thread override. */
+    defaultRetentionDays: 90,
+    /** Minutes after send during which the sender may edit a message. */
+    editWindowMinutes: 15
+};

package/plugins/messages/docs/guide.md

@@ -0,0 +1,176 @@
+---
+title: Guide
+order: 1
+---
+
+Messages is private chat for the people who sign in to your admin. Send direct messages, run group conversations and share files. New messages arrive straight away, without reloading the page.
+
+## What it does
+
+- Direct messages between two people. There is only ever one per pair: starting it again opens the one you have.
+- Groups: a name and any number of people.
+- Managed groups: standing teams, such as Editors, that only an admin can create.
+- File attachments, up to 20 per message.
+- Video calls from any conversation, for up to 6 people.
+- Inbox, Unread and Archived lists, and a search.
+- Drafts kept per conversation, including attached files you have not sent yet.
+- An unread badge on the Messages sidebar entry.
+- A notification if a message sits unread.
+
+## Getting started
+
+1. Open [Messages](#/plugins/messages) in the sidebar.
+2. Click **New conversation** in the banner.
+3. Choose the **Kind**: **Direct message** or **Group**. For a group, enter a **Group name**.
+4. Under **People**, use **Find someone...** to pick who to talk to.
+5. Start the conversation (Ctrl+Enter also starts it).
+6. Type in the message box and click **Send**, or press Ctrl+Enter.
+
+## Screens
+
+### Conversation list
+
+On the left of the screen.
+
+- Filters: **Inbox**, **Unread** and **Archived**, each with a count.
+- A search box to find a conversation.
+- Each conversation shows its unread count.
+
+Right-click a conversation, or use its menu button, for:
+
+| Action | Who sees it |
+|---|---|
+| Open | Everyone |
+| Mark as read / Mark as unread | Everyone |
+| Archive / Move to inbox | Everyone. Archiving only affects your own list |
+| Rename... | Groups only: whoever started it, and admins |
+| Keep messages for... | Whoever started the conversation, and admins |
+| Leave conversation... | Everyone |
+
+### Conversation
+
+The messages, with the message box underneath.
+
+- **Attach files** uploads files to your site's Media library and adds them to the message. This needs the Media > Upload permission (see Permissions and roles).
+- **Send**, or Ctrl+Enter, sends it.
+- What you type is kept as a draft for each conversation, so you can switch away without losing it.
+
+Right-click a message, or use its menu button, for:
+
+- **Copy text**.
+- **Edit...**: your own messages only, for 15 minutes after sending. The menu shows how many minutes are left.
+- **Delete...**: the message is replaced with "message deleted".
+
+### Calls
+
+Click **Call** at the top of a conversation to start a video call with everyone in it.
+
+1. The call opens in a new tab. Check your camera and microphone, then click **Join the call**.
+2. Everyone else in the conversation who has Messages open sees a notice at the bottom right: "Sam is calling", with **Join**. They also get a notification.
+3. They click **Join** and go straight in. There is no waiting room: they are your signed-in team.
+4. The conversation shows "Sam started a call". While the call is on, the button reads **Join call** and the line has a **Join** button.
+5. When the last person leaves, the conversation shows "Call ended" with how long it lasted.
+
+What you type in the call's chat goes into the conversation as your own message, marked "in the call", so it is all there afterwards.
+
+To call people without opening a conversation first, click **Call…** in the banner (or on the empty screen when no conversation is open):
+
+1. Tick the people to call - 1 to 5, since a call holds 6 people including you.
+2. Click **Call** (or press Ctrl+Enter).
+3. One person: the call is in your conversation with them. Several people: it is in your group with exactly those people, or a new group if you have none. A new group can have a name; left empty, it is named after everyone in it, such as "Alex, Priya and Sam". A group you archived is not used.
+4. The call opens in a new tab and the conversation opens here, showing "started a call".
+
+You can also right-click a conversation and choose **Call**.
+
+**Ring someone else into the call.** In the call, click **Add people** and pick a team member who is not in the conversation. They get a notification ("Sam is calling you - Join") and a message from you in Messages, each with a link of their own (tick **Email** to email it too). The link lets them straight into this call while it runs - it does not add them to the conversation, they do not see what was said in the call before they came, and it stops working when the call ends. Anyone in the conversation can ring people in; people rung in cannot ring others.
+
+Other Tools' calls (Booking's online appointments, the Calendar's online meetings and "Call Sam now…") use Messages too: when their host adds a team member, that person gets the link as a message from the host.
+
+Good to know:
+
+- A call holds 6 people. In a bigger group the first 6 to join get in; the next person is told the call is full.
+- Your browser asks to use your camera and microphone the first time.
+- If your browser blocks the new tab, an **Open the call** button appears instead.
+- Your link to a call is yours alone and works for 2 hours. It stops working if you leave the conversation.
+- A call nobody joins ends after 5 minutes.
+- Calls are not recorded, and restarting the site ends any call in progress.
+- Calls need Domma CMS 0.103 or later.
+
+### New conversation
+
+Opened from the banner. Fields: Kind, Group name (groups only) and People.
+
+### Managed groups
+
+Admins only. Click **Managed groups** in the banner to see the existing managed groups and create a new one with a name and its members.
+
+## Who can message whom
+
+This is checked by the server, not just the screen.
+
+- Admins can message every active account.
+- Everyone else can message admins, people who share one of their roles, and people they already have a conversation with.
+
+## Deleting and leaving
+
+- You can delete your own messages at any time.
+- Whoever started a group can delete other people's messages in that group. This never applies to direct messages.
+- Admins can delete any message.
+- Leaving a conversation stops you receiving its messages. If you are the last person in it, the conversation and its messages are deleted.
+- A new message in an archived conversation moves it back to everyone's inbox.
+
+## Settings
+
+There is no settings screen. The defaults are:
+
+| Setting | Default | Meaning |
+|---|---|---|
+| Default retention | 90 days | How long messages are kept when a conversation has no retention of its own |
+| Retention ceiling | 365 days | The longest anyone can set for a conversation |
+| Edit window | 15 minutes | How long after sending a message can be edited |
+
+A message holds up to 10,000 characters and a conversation's name up to 80; anything longer is cut.
+
+These can be changed by whoever manages your site's configuration (`config/plugins.json`). A restart is needed afterwards.
+
+### Keeping messages
+
+**Keep messages for...** sets how many days a conversation's messages are kept, for everyone in it. Enter a whole number of 1 or more, or leave it empty for the site default. It cannot go past the ceiling. Older messages are removed the next time the conversation is opened.
+
+## Permissions and roles
+
+In System > Roles, Messages adds the permission **Messages** with one action:
+
+| Action | Label | Meaning | Granted by default to |
+|---|---|---|---|
+| read | Use | Send, read and manage your own conversations | Admin, User |
+
+Super Admins always have it. Remove it from a role and that role has no Messages entry in the sidebar and no access to messages.
+
+Attaching files uploads them to Media, so it also needs the **Media** permission's **Upload** action. Admins have it; the default **User** role does not, so users can only send text until you give their role Upload.
+
+Admin rights inside Messages (managed groups, deleting anyone's messages, reaching every account) go to Admins and Super Admins, including anyone given the Admin role as an additional role.
+
+## Notifications
+
+Messages adds two sources under Notifications > Sources:
+
+- **Unread messages** checks every 15 minutes. A message left unread for 10 minutes or more (and less than 2 days old) sends its recipient one notice per conversation. Reading or archiving the conversation clears it.
+- **Calls**: someone starts a call. Everyone else in the conversation gets a notice. It clears when the call ends.
+
+## Tips
+
+- Use Archive to tidy your inbox. It only affects your own list.
+- Use Mark as unread to come back to a conversation later.
+- An attachment is a file in your Media library. If that file is deleted from Media, the message still lists it but the download no longer works.
+- Drafts are kept in your browser, so a draft started on one computer does not appear on another.
+
+## Limitations
+
+- Messages are for signed-in admin users only. The only public page is the call page, and it opens only with a call link made for you.
+- There is no settings screen for retention or the edit window.
+- Only admins can create managed groups.
+- Live delivery and calls assume the site runs as a single process, which is the normal set-up.
+- Calls hold 6 people and cannot be recorded.
+
+The Messages sidebar count shows how many unread messages are waiting in your unarchived conversations. It remains visible as **0** when everything is read (Messages 1.7.1, CMS 0.109.5 or later).

package/plugins/messages/lib/call.js

@@ -0,0 +1,138 @@
+/**
+ * Calls in a conversation (1.4): who may join which call, and the join links.
+ *
+ * The call itself is the engine's (`_lib/call`, core 0.103+). A room is a
+ * CONVERSATION (room = thread id); everyone in it is a signed-in member of the
+ * site, so there is no waiting room - everyone goes straight in, up to the
+ * engine's six.
+ *
+ * The call page is a public page (`/messages-call/<thread>`), so it cannot see
+ * the admin sign-in. Instead POST /threads/:id/call hands the member a
+ * SHORT-LIVED link of their own: `?u=<user>&x=<expiry ms>&s=<HMAC>`, the HMAC
+ * over `thread|user|expiry` with a random secret the plugin makes once and
+ * keeps in its data folder. The join checks it again, and that the person is
+ * STILL in the conversation.
+ *
+ * "Add people" (1.7): someone in the call rings another team member who is NOT
+ * in the conversation. They get a link of their own, signed as an invitation
+ * (`&i=1`, the HMAC over `thread|user|expiry|invite`), which lets them into
+ * THIS call while it runs (plugin.js keeps who was invited with the live call) -
+ * they are not added to the conversation, and they cannot add others.
+ *
+ * @module messages/lib/call
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const CALL_PATH = '/messages-call';
+export const CALL_API = '/api/plugins/messages/call';
+export const LINK_TTL_MS = 2 * 3600e3;
+export const MAX_IN_CALL = 6;
+/** A call nobody has joined yet is given up after this long. */
+export const RING_MS = 5 * 60e3;
+
+const ROOM_RE = /^[\w-]{1,120}$/;
+
+/**
+ * The link secret, made once (32 random bytes) and kept as `call-secret` in
+ * `dir`. Losing it only stops links already handed out (they last two hours).
+ */
+export function loadSecret(dir) {
+    const file = path.join(dir, 'call-secret');
+    try {
+        const s = fs.readFileSync(file, 'utf8').trim();
+        if (/^[0-9a-f]{64}$/.test(s)) return s;
+    } catch { /* not made yet */ }
+    const s = crypto.randomBytes(32).toString('hex');
+    fs.mkdirSync(dir, {recursive: true});
+    // Another process may have made one meanwhile: keep theirs.
+    try { fs.writeFileSync(file, s + '\n', {mode: 0o600, flag: 'wx'}); return s; } catch { /* exists */ }
+    return fs.readFileSync(file, 'utf8').trim();
+}
+
+export const signJoin = (secret, threadId, userId, expiry, invited = false) =>
+    crypto.createHmac('sha256', String(secret)).update(`${threadId}|${userId}|${expiry}${invited ? '|invite' : ''}`).digest('base64url');
+
+/** A member's own link into a conversation's call. */
+export function joinLink(secret, threadId, userId, now = Date.now()) {
+    const x = now + LINK_TTL_MS;
+    return `${CALL_PATH}/${encodeURIComponent(threadId)}?u=${encodeURIComponent(userId)}&x=${x}&s=${signJoin(secret, threadId, userId, x)}`;
+}
+
+/** An invited team member's own link into a running call (1.7) - not a member of the conversation. */
+export function inviteLink(secret, threadId, userId, now = Date.now()) {
+    const x = now + LINK_TTL_MS;
+    return `${CALL_PATH}/${encodeURIComponent(threadId)}?u=${encodeURIComponent(userId)}&x=${x}&i=1&s=${signJoin(secret, threadId, userId, x, true)}`;
+}
+
+/** The link's own words, trimmed to size (from a query string or a join body). */
+export const credOf = (q = {}) => ({u: String(q?.u ?? '').slice(0, 64), x: String(q?.x ?? '').slice(0, 16), s: String(q?.s ?? '').slice(0, 64),
+    ...(String(q?.i ?? '') === '1' ? {i: '1'} : {})});
+
+/**
+ * The user a link was made for, or null: forged, altered, for another
+ * conversation, expired, or dated further ahead than a link ever is. A member's
+ * link only - an invitation (`i=1`) is checkInvite's.
+ */
+export function checkJoin(secret, threadId, cred, now = Date.now(), invited = false) {
+    const {u, x, s, i} = credOf(cred);
+    if (Boolean(i) !== invited) return null;
+    if (!secret || !ROOM_RE.test(String(threadId || '')) || !u || !/^\d{1,15}$/.test(x) || !s) return null;
+    const exp = Number(x);
+    if (exp <= now || exp > now + LINK_TTL_MS + 60e3) return null;
+    const want = Buffer.from(signJoin(secret, threadId, u, x, invited));
+    const got = Buffer.from(s);
+    return want.length === got.length && crypto.timingSafeEqual(want, got) ? u : null;
+}
+
+/** The user an INVITATION link (1.7) was made for, or null - the same checks as checkJoin. */
+export const checkInvite = (secret, threadId, cred, now = Date.now()) => checkJoin(secret, threadId, cred, now, true);
+
+/** What the call is called: a group's name, or the two people in a DM. */
+export function callTitle(thread, names = {}) {
+    if (!thread) return 'Call';
+    if (thread.kind !== 'dm') return String(thread.name || 'Group call').slice(0, 80);
+    const who = (thread.participants || []).map(id => names[id]).filter(Boolean);
+    return who.length ? `Call: ${who.join(' and ')}`.slice(0, 80) : 'Call';
+}
+
+/**
+ * Who the caller is in a conversation's call, or null (the engine answers 404).
+ * Everyone in the conversation is let straight in (autoAdmit) - there is
+ * nobody to wait for, so nobody is the host (the engine's host only lets
+ * people in, records, and is captioned "(host)"). No recording.
+ *
+ * @param {object|null} thread - {id, kind, name, participants}
+ * @param {object|null} user - the account the link names ({id, name, disabled?})
+ * @param {string|null} userId - checkJoin()'s answer (or checkInvite()'s, with `invited`)
+ * @param {{invited?: boolean}} [opts] - an invited team member (1.7): not in the conversation, let in all the same;
+ *   the caller has checked they were invited to the call that is running. Members may add people; invitees may not.
+ */
+export function whoIsCalling(thread, user, userId, names = {}, {invited = false} = {}) {
+    if (!thread || !userId || !user || user.id !== userId) return null;
+    if (user.disabled === true || user.active === false || user.isActive === false) return null;
+    const member = Array.isArray(thread.participants) && thread.participants.includes(userId);
+    if (!member && !invited) return null;
+    return {
+        mayInvite: member,
+        inviteExternal: false,
+        title: callTitle(thread, names),
+        host: false,
+        autoAdmit: true,
+        name: String(user.name || '').trim() || 'Member',
+        max: MAX_IN_CALL,
+        recordingAllowed: false,
+        identity: `${thread.id}:${userId}`
+    };
+}
+
+/** "Call ended (12 min)", "Call ended (under a minute)", or nobody came. */
+export function endedText(startedAt, endedAt, anyoneJoined) {
+    if (!anyoneJoined) return 'Call ended - nobody joined';
+    const min = Math.round((endedAt - startedAt) / 60e3);
+    return min < 1 ? 'Call ended (under a minute)' : `Call ended (${min} min)`;
+}
+
+export const escHtml = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');