domma-cms 0.70.1 → 0.72.0

package/server/services/roles.js

@@ -4,7 +4,9 @@
  * Auth middleware calls getRoleMap() / getPermissionsFor() at request time.
  *
  * Base roles: super-admin (0), admin (1), user (2).
- * Plugin-contributed roles are tagged with a `plugin` field and removed on plugin teardown.
+ * Plugin-contributed roles are tagged with a `plugin` field. They are created
+ * once (`ensureRole`) and then belong to the admin; disabling the plugin leaves
+ * them in place so user assignments survive a disable/enable cycle.
  */
 import fs from 'fs/promises';
 import path from 'path';
@@ -100,6 +102,9 @@ let permissionsMap = new Map();
 /** @type {Map<string,string[]>} role name → raw permissions array */
 let rawPermissionsMap = new Map();
 
+/** @type {string[]} names of level-0 roles - they hold every permission, including plugin ones */
+let rootRoles = [];
+
 /**
  * Build in-memory maps from an array of data entries.
  * Supports both bare resource names ('pages') and dotted action strings ('pages.read').
@@ -111,6 +116,7 @@ function buildCache(entries) {
     roleMap = new Map();
     permissionsMap = new Map();
     rawPermissionsMap = new Map();
+    rootRoles = entries.filter(e => e.data?.level === 0).map(e => e.data.name);
 
     const addTo = (key, role) => {
         if (!permissionsMap.has(key)) permissionsMap.set(key, []);
@@ -119,11 +125,13 @@ function buildCache(entries) {
 
     for (const entry of entries) {
         const d = entry.data;
+        const adminScope = d.level === 0 ? null : normaliseAdminScope(d.admin);
         roleMap.set(d.name, {
             label: d.label,
             level: d.level,
             badgeClass: d.badgeClass || '',
-            ...(d.meta != null && {meta: d.meta})
+            ...(d.meta != null && {meta: d.meta}),
+            ...(adminScope && {admin: adminScope})
         });
         rawPermissionsMap.set(d.name, d.permissions || []);
         for (const perm of (d.permissions || [])) {
@@ -312,6 +320,152 @@ export async function createRole(data) {
     buildCache(entries);
 }
 
+/** An admin route: `/`-rooted, hash-router path characters only. */
+const ADMIN_PATH_RE = /^\/[A-Za-z0-9\-_/]*$/;
+
+/**
+ * Validate a role's `admin` block - which admin screens the role is confined
+ * to - and return it in canonical form, or null if it is absent or unusable.
+ *
+ *   {"home": "/portal", "allow": ["/portal"]}
+ *
+ * `allow` lists route prefixes (`/portal` also admits `/portal/orders`).
+ * `home` is where a user is sent from anywhere else; it defaults to the first
+ * allowed route and is always itself allowed. A block with no usable route is
+ * treated as absent - confining someone to nothing would lock them out.
+ *
+ * @param {*} raw
+ * @returns {{home: string, allow: string[]}|null}
+ */
+/**
+ * An admin route path (`/portal`, `/plugins/x/dashboard`), cleaned - or null if
+ * it is not one. Trailing slashes go; the root stays `/`.
+ *
+ * @param {unknown} p
+ * @returns {string|null}
+ */
+export function normaliseAdminPath(p) {
+    return (typeof p === 'string' && ADMIN_PATH_RE.test(p.trim()))
+        ? (p.trim().replace(/\/+$/, '') || '/')
+        : null;
+}
+
+export function normaliseAdminScope(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+    const clean = normaliseAdminPath;
+    const allow = [...new Set((Array.isArray(raw.allow) ? raw.allow : []).map(clean).filter(Boolean))];
+    const home  = clean(raw.home) || allow[0] || null;
+    if (!home) return null;
+    if (!allow.includes(home)) allow.unshift(home);
+    return {home, allow};
+}
+
+/**
+ * The admin scope for a user holding `roleNames`, or null for unrestricted.
+ *
+ * A user is confined only when EVERY role they hold is: one unscoped role
+ * (an `admin` additional role, say) lifts the restriction, because roles
+ * grant, they never take away. The level-0 role is never confined. When
+ * confined, the allowed routes are the union across roles and `home` is the
+ * first role's (the primary role comes first).
+ *
+ * @param {string[]} roleNames
+ * @returns {{home: string, allow: string[]}|null}
+ */
+export function getAdminScope(roleNames) {
+    const scopes = [];
+    for (const name of roleNames || []) {
+        const role = roleMap.get(name);
+        if (!role) continue;                     // an unknown role grants nothing either way
+        if (role.level === 0 || !role.admin) return null;
+        scopes.push(role.admin);
+    }
+    if (!scopes.length) return null;
+    return {
+        home:  scopes[0].home,
+        allow: [...new Set(scopes.flatMap(sc => sc.allow))]
+    };
+}
+
+/**
+ * A role's stored data (as saved, including `plugin` and `grantedBy`), or null.
+ *
+ * @param {string} name
+ * @returns {Promise<object|null>}
+ */
+export async function getRoleData(name) {
+    try {
+        return (await readData()).find(e => e.data?.name === name)?.data ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Create a role only if no role of that name exists yet.
+ *
+ * This is what plugins use on every enable and every boot. A role the admin
+ * has since edited (label, level, permissions) is left exactly as they left
+ * it - the plugin file is the starting point, not a setting that wins.
+ *
+ * @param {{name:string,label:string,level:number,permissions?:string[],badgeClass?:string,plugin?:string}} data
+ * @returns {Promise<boolean>} true if the role was created
+ */
+export async function ensureRole(data) {
+    let entries;
+    try {
+        entries = await readData();
+    } catch {
+        entries = [];
+    }
+    if (entries.some(e => e.data?.name === data.name)) return false;
+    entries.push(makeEntry({permissions: [], ...data}));
+    await writeData(entries);
+    buildCache(entries);
+    return true;
+}
+
+/**
+ * Grant a permission to an existing role ONCE per source.
+ *
+ * A plugin that wants the site's own roles (say `admin`) to be able to use
+ * its screens calls this for each. The grant is recorded on the role under
+ * `grantedBy`, so if the admin later removes the permission it stays
+ * removed - the plugin does not re-add it on the next boot.
+ *
+ * @param {string} roleName
+ * @param {string} permission - `resource` or `resource.action`
+ * @param {string} source     - usually the plugin name
+ * @returns {Promise<boolean>} true if the role changed
+ */
+export async function grantPermissionOnce(roleName, permission, source) {
+    let entries;
+    try {
+        entries = await readData();
+    } catch {
+        return false;
+    }
+    const entry = entries.find(e => e.data?.name === roleName);
+    if (!entry) return false;
+
+    const marker = `${source}:${permission}`;
+    const grantedBy = Array.isArray(entry.data.grantedBy) ? entry.data.grantedBy : [];
+    if (grantedBy.includes(marker)) return false;
+
+    const perms = entry.data.permissions || [];
+    const [resource] = permission.split('.');
+    const alreadyHeld = perms.includes(permission) || perms.includes(resource);
+    entry.data = {
+        ...entry.data,
+        permissions: alreadyHeld ? perms : [...perms, permission],
+        grantedBy: [...grantedBy, marker]
+    };
+    entry.updatedAt = new Date().toISOString();
+    await writeData(entries);
+    buildCache(entries);
+    return true;
+}
+
 /**
  * Remove a role entry by name and rebuild the cache.
  * Refuses to remove base roles (level 0 protection is enforced elsewhere;
@@ -383,9 +537,31 @@ export function getRoleLevel(roleName) {
  * @returns {string[]}
  */
 export function getPermissionsFor(resource, action) {
-    if (action) return permissionsMap.get(`${resource}.${action}`) ?? [];
-    if (resource.includes('.')) return permissionsMap.get(resource) ?? [];
-    return permissionsMap.get(resource) ?? [];
+    const key = action ? `${resource}.${action}` : resource;
+    const granted = permissionsMap.get(key) ?? [];
+    // The root role is seeded with the base registry only, so a resource a
+    // plugin registers later would otherwise lock out the one role that is
+    // meant to be able to do everything.
+    const missingRoot = rootRoles.filter(r => !granted.includes(r));
+    return missingRoot.length ? [...granted, ...missingRoot] : granted;
+}
+
+/**
+ * The permissions a set of roles holds between them - the union of each
+ * role's raw list, so a user with additional roles sees everything any of
+ * them grants. A level-0 role holds every resource in the effective registry.
+ *
+ * @param {string[]} roleNames
+ * @param {string[]} [allResources] - effective registry keys, for the root role
+ * @returns {string[]}
+ */
+export function getPermissionsForRoles(roleNames, allResources = RESOURCES) {
+    const out = new Set();
+    for (const name of roleNames || []) {
+        if (rootRoles.includes(name)) allResources.forEach(r => out.add(r));
+        for (const perm of rawPermissionsMap.get(name) ?? []) out.add(perm);
+    }
+    return [...out];
 }
 
 /**

package/server/services/sidebar-migration.js

@@ -3,8 +3,13 @@
  *
  * Runs once on server boot. Idempotent - guarded by the existence of
  * config/menus/admin-sidebar.json. Seeds the admin sidebar menu with the
- * standard tree (Overview, Projects, Content, Data, System, Documentation)
- * and patches config/menu-locations.json to map the `admin-sidebar` slot.
+ * standard tree (Overview, Projects, Content, Data, Tools, System,
+ * Documentation) and patches config/menu-locations.json to map the
+ * `admin-sidebar` slot.
+ *
+ * Top-level folders carry a stable `key`. A Tool names its default folder by
+ * key, so an admin can rename a folder without the Tools that live in it
+ * falling out of it. ensureFolderKeys() brings menus seeded before keys up.
  */
 import fs from 'fs/promises';
 import path from 'path';
@@ -16,19 +21,19 @@ const DEFAULT_CONFIG_DIR = path.resolve(path.dirname(__filename), '..', '..', 'c
 
 const SEED_ITEMS = [
     {
-        text: 'Overview', icon: 'home',
+        text: 'Overview', key: 'overview', icon: 'home',
         items: [
             {text: 'Dashboard', url: '#/', icon: 'home'}
         ]
     },
     {
-        text: 'Projects', icon: 'folder', permission: 'projects',
+        text: 'Projects', key: 'projects', icon: 'folder', permission: 'projects',
         items: [
             {text: 'Manage projects', url: '#/projects', icon: 'folder', permission: 'projects'}
         ]
     },
     {
-        text: 'Content', icon: 'edit',
+        text: 'Content', key: 'content', icon: 'edit',
         items: [
             {text: 'Pages', url: '#/pages', icon: 'file-text', permission: 'pages'},
             {text: 'Media', url: '#/media', icon: 'image',     permission: 'media'},
@@ -36,7 +41,7 @@ const SEED_ITEMS = [
         ]
     },
     {
-        text: 'Data', icon: 'database',
+        text: 'Data', key: 'data', icon: 'database',
         items: [
             {text: 'Collections', url: '#/collections', icon: 'database',  permission: 'collections'},
             {text: 'Forms',       url: '#/forms',       icon: 'layout',    permission: 'collections'},
@@ -47,8 +52,12 @@ const SEED_ITEMS = [
             {text: 'Components',  url: '#/components',  icon: 'component', permission: 'components'}
         ]
     },
+    // Enabled Tools are placed here at render time (placeTools in
+    // admin/js/lib/sidebar-grouping.js); the folder is persisted so an admin
+    // can rename, move or reorder it like any other.
+    {text: 'Tools', key: 'tools', icon: 'tool', items: []},
     {
-        text: 'System', icon: 'settings',
+        text: 'System', key: 'system', icon: 'settings',
         items: [
             {text: 'Notifications', url: '#/system/notifications', icon: 'bell',     permission: 'notifications'},
             {text: 'Roles',         url: '#/roles',                icon: 'shield',   permission: 'plugins'},
@@ -63,7 +72,7 @@ const SEED_ITEMS = [
         ]
     },
     {
-        text: 'Documentation', icon: 'book',
+        text: 'Documentation', key: 'documentation', icon: 'book',
         items: [
             DOC_USAGE_SUBMENU(),
             DOC_TUTORIALS_SUBMENU(),
@@ -307,3 +316,68 @@ export async function ensureDocumentationSubmenus(opts = {}) {
     console.log('[admin-sidebar] Upgraded Documentation group with per-topic submenus');
     return {updated: true};
 }
+
+/** Keys for the folders the seed has always created, matched by their original name. */
+const SEED_FOLDER_KEYS = {
+    overview: 'overview', projects: 'projects', content: 'content', data: 'data',
+    tools: 'tools', system: 'system', documentation: 'documentation'
+};
+
+/**
+ * Give an existing install's top-level folders their stable `key`, and - once -
+ * a persisted Tools folder for enabled Tools to be placed into.
+ *
+ *  - A folder is keyed only if it has no key yet and still carries one of the
+ *    seed's names; a folder the admin made, or renamed before keys existed, is
+ *    left alone (placement falls back to Tools for it).
+ *  - The Tools folder is added only on the first run (`meta.toolsFolder`), so
+ *    an admin who later deletes it does not get it back on every boot. Until
+ *    then placement synthesises one, exactly as before.
+ *
+ * Returns `{updated: boolean, reason?: string}`.
+ *
+ * @param {{configDir?: string}} [opts]
+ */
+export async function ensureFolderKeys(opts = {}) {
+    const configDir = opts.configDir || DEFAULT_CONFIG_DIR;
+    const menuPath  = path.join(configDir, 'menus', 'admin-sidebar.json');
+
+    if (!await exists(menuPath)) {
+        return {updated: false, reason: 'admin-sidebar.json not present'};
+    }
+
+    const menu  = await readJson(menuPath);
+    const items = Array.isArray(menu.items) ? menu.items : (menu.items = []);
+    const isFolder = (n) => n && typeof n === 'object' && !n.url && n.type !== 'separator' && n.type !== 'spacer';
+
+    let changed = false;
+    const used = new Set(items.filter(n => isFolder(n) && n.key).map(n => n.key));
+    for (const node of items) {
+        if (!isFolder(node) || node.key) continue;
+        const key = SEED_FOLDER_KEYS[String(node.text || '').trim().toLowerCase()];
+        if (!key || used.has(key)) continue;
+        node.key = key;
+        used.add(key);
+        changed = true;
+    }
+
+    // An empty menu is left empty: the renderer's minimal fallback (Dashboard,
+    // Menus) is what an admin needs to repair it, and a lone Tools folder would
+    // stop that fallback from applying.
+    if (!menu.meta?.toolsFolder && items.length) {
+        if (!used.has('tools')) {
+            const idx = items.findIndex(n => isFolder(n) && ['system', 'documentation'].includes(n.key));
+            const tools = {text: 'Tools', key: 'tools', icon: 'tool', items: []};
+            items.splice(idx === -1 ? items.length : idx, 0, tools);
+        }
+        menu.meta = {...(menu.meta || {}), toolsFolder: true};
+        changed = true;
+    }
+
+    if (!changed) return {updated: false, reason: 'already up to date'};
+
+    menu.meta = {...(menu.meta || {}), updatedAt: new Date().toISOString()};
+    await writeJson(menuPath, menu);
+    console.log('[admin-sidebar] Gave the sidebar folders stable keys');
+    return {updated: true};
+}

package/admin/js/lib/sidebar-grouping.test.js

@@ -1 +0,0 @@
-import{test as o}from"node:test";import s from"node:assert/strict";import{groupPluginItems as a,stripItemByUrl as p,insertFoldersBeforeSystem as u,pruneEmptySynthesisedFolders as i,TOOLS_FOLDER_TEXT as m,MANAGE_PLUGINS_URL as d}from"./sidebar-grouping.js";const n=(e,t=null)=>({parent:t,item:e});o("groupPluginItems routes every enabled item to Tools, whatever its core flag",()=>{const{toolsFolder:e}=a([n({text:"Analytics",url:"#/plugins/analytics",core:!0}),n({text:"Todo",url:"#/plugins/todo",core:!1}),n({text:"Notes",url:"#/plugins/notes"})]);s.equal(e.text,m),s.deepEqual(e.items.map(t=>t.text),["Analytics","Todo","Notes"])}),o("Marketplace is a standalone entry, not a folder",()=>{const{managePluginsItem:e}=a([n({text:"Todo",url:"#/plugins/todo"})]);s.equal(e.text,"Marketplace"),s.equal(e.url,d),s.equal(e.permission,"plugins"),s.ok(!("items"in e),"it must not carry a sub-tree")}),o("groupPluginItems omits the Tools folder only when nothing is enabled",()=>{const e=a([n({text:"Todo",url:"#/plugins/todo"})]);s.deepEqual(e.toolsFolder.items.map(l=>l.text),["Todo"]);const t=a([]);s.equal(t.toolsFolder,null),s.equal(t.managePluginsItem.text,"Marketplace")}),o("groupPluginItems keeps explicitly-parented items separate",()=>{const{parented:e,toolsFolder:t}=a([n({text:"Nested",url:"#/x"},"Content"),n({text:"Todo",url:"#/plugins/todo",core:!1})]);s.equal(e.length,1),s.equal(e[0].parent,"Content"),s.deepEqual(t.items.map(l=>l.text),["Todo"])}),o("each call returns its own Marketplace object",()=>{const e=a([]).managePluginsItem,t=a([]).managePluginsItem;s.notEqual(e,t),s.deepEqual(e,t)}),o("stripItemByUrl removes the management link at any depth",()=>{const e=[{text:"Overview",items:[{text:"Dashboard",url:"#/"}]},{text:"System",items:[{text:"Users",url:"#/users"},{text:"Plugins",url:"#/plugins"}]}],l=p(e,"#/plugins").find(r=>r.text==="System");s.deepEqual(l.items.map(r=>r.text),["Users"]),s.equal(e.find(r=>r.text==="System").items.length,2)}),o("insertFoldersBeforeSystem places Tools then Marketplace before System",()=>{const t=u([{text:"Overview"},{text:"Data"},{text:"System"},{text:"Documentation"}],[{text:"Tools",items:[]},{text:"Marketplace",url:"#/plugins"},null]);s.deepEqual(t.map(l=>l.text),["Overview","Data","Tools","Marketplace","System","Documentation"])}),o("insertFoldersBeforeSystem appends when no System/Documentation anchor",()=>{const t=u([{text:"Overview"},{text:"Data"}],[{text:"Marketplace",url:"#/plugins"}]);s.deepEqual(t.map(l=>l.text),["Overview","Data","Marketplace"])}),o("pruneEmptySynthesisedFolders drops an empty Tools folder but keeps built-ins",()=>{const e=[{text:"Overview",items:[]},{text:"Tools",items:[]}];s.deepEqual(i(e).map(t=>t.text),["Overview"])}),o("pruneEmptySynthesisedFolders leaves the standalone Marketplace alone",()=>{const e=[{text:"Tools",items:[{text:"Analytics"}]},{text:"Marketplace",url:"#/plugins"}];s.deepEqual(i(e).map(t=>t.text),["Tools","Marketplace"])});