domma-cms 0.70.1 → 0.72.0

package/server/services/plugins.js

@@ -14,18 +14,22 @@ import fs from 'fs/promises';
 import path from 'path';
 import matter from 'gray-matter';
 import {getConfig, saveConfig} from '../config.js';
-import {authenticate, requireAdmin, requireRole, requireVisibility} from '../middleware/auth.js';
+import {authenticate, requireAdmin, requirePermission, requireRole, requireVisibility} from '../middleware/auth.js';
 import {
     hooks,
     registerMenuLocation,
     registerSanitizeRules,
     registerShortcode,
+    hideSidebarUrl,
     registerSidebarItem,
     registerTransform
 } from './hooks.js';
 import {registerPluginResource, unregisterPluginResourcesByPlugin} from './permissionRegistry.js';
 import {classifyEntitlement, mayLoad} from './pluginEntitlement.js';
 import {createCollection, getCollection} from './collections.js';
+import * as defaultRolesService from './roles.js';
+import {normaliseAdminScope} from './roles.js';
+import * as defaultUsersService from './users.js';
 
 const PLUGINS_DIR = path.resolve('plugins');
 
@@ -135,6 +139,49 @@ const CORE_PLUGINS = new Set([]);
 /** Is this plugin a built-in feature rather than an optional add-on? */
 export function isCorePlugin(name) { return CORE_PLUGINS.has(name); }
 
+/**
+ * The Tools promoted out of plugins/ in 0.67.0 - core code now, each with its
+ * own `#/<name>` screen and sidebar entry (server/server.js).
+ *
+ * Not plugins, so `supersedes` could never reach them the way it reaches the
+ * free Blog. A plugin that names one in `supersedes` TAKES IT OVER instead:
+ * the core Tool's sidebar entry is hidden and its screen hands over to the
+ * plugin's first admin route. The core Tool's API stays up - other plugins
+ * (Invoices reads contacts) depend on it, and the paid edition works over the
+ * same data - and, like supersession, nothing is written down: a lapsed
+ * licence means the plugin does not load and the core Tool is simply back.
+ */
+export const BUILT_IN_TOOLS = new Set(['notes', 'todo', 'analytics', 'contacts']);
+
+/** Built-in Tool → {plugin, route}, for the plugins that loaded this boot. */
+const _toolTakeovers = {};
+
+/**
+ * Which built-in Tools a loaded plugin has taken over.
+ *
+ * @returns {Object.<string, {plugin: string, route: string|null}>}
+ */
+export function getToolTakeovers() {
+    return {..._toolTakeovers};
+}
+
+/**
+ * The takeovers one manifest claims: every built-in Tool in its `supersedes`
+ * that no earlier plugin has claimed. Pure, for the test.
+ *
+ * @param   {object} manifest
+ * @param   {object} [taken] - claims already made
+ * @returns {Object.<string, {plugin: string, route: string|null}>}
+ */
+export function toolTakeoversOf(manifest, taken = {}) {
+    const out = {};
+    const route = manifest?.admin?.routes?.[0]?.path ?? null;
+    for (const tool of Array.isArray(manifest?.supersedes) ? manifest.supersedes : []) {
+        if (BUILT_IN_TOOLS.has(tool) && !taken[tool] && !out[tool]) out[tool] = {plugin: manifest.name, route};
+    }
+    return out;
+}
+
 /**
  * Scan the plugins/ directory and return all valid manifests.
  * Validates mandatory fields and required files (plugin.js, config.js).
@@ -413,24 +460,35 @@ export async function registerPlugins(fastify) {
           const prefix = `/api/plugins/${manifest.name}`;
           await fastify.register(plugin, {
             prefix,
-            auth: {authenticate, requireRole, requireAdmin, requireVisibility},
-              hooks: {registerShortcode, registerSanitizeRules, registerTransform, registerMenuLocation, registerSidebarItem, on: hooks.on.bind(hooks)},
+            auth: {authenticate, requireRole, requireAdmin, requireVisibility, requirePermission},
+              hooks: {registerShortcode, registerSanitizeRules, registerTransform, registerMenuLocation,
+                  // Stamped with the plugin's name, so the Menus editor can say where a Tool came from.
+                  registerSidebarItem: (opts) => registerSidebarItem({...opts, item: {source: manifest.displayName || manifest.name, ...opts?.item}}),
+                  on: hooks.on.bind(hooks), ...pluginRoleHooks(manifest.name)},
               settings,
               config: {}
           });
             loaded.push(manifest.name);
 
+            // A built-in Tool this plugin replaces: hide the core sidebar entry
+            // (the admin sends its screen to the plugin - getAdminPluginConfig).
+            for (const [tool, claim] of Object.entries(toolTakeoversOf(manifest, _toolTakeovers))) {
+                _toolTakeovers[tool] = claim;
+                hideSidebarUrl(`#/${tool}`);
+                fastify.log.info(`[plugins] built-in Tool "${tool}" taken over by "${manifest.name}".`);
+            }
+
             // Bridge plugin.json `admin.sidebar` entries into the sidebar
             // registry so they render in the admin sidebar. The admin renderer
             // reads plugin nav from /api/sidebar/registered-items; plugins
             // declare their nav in the manifest rather than calling
-            // registerSidebarItem, so register it here on their behalf.
-            // Tag each item with the plugin's core status so the admin sidebar
-            // can auto-group it: core plugins → Tools folder, optional → Plugins.
+            // registerSidebarItem, so register it here on their behalf. An
+            // entry's `folder` is its default place (Tools when it names none);
+            // an admin can move it anywhere in the menu.
             const isCore = CORE_PLUGINS.has(manifest.name);
             for (const item of manifest.admin?.sidebar || []) {
                 try {
-                    registerSidebarItem({item: {...item, core: isCore}});
+                    registerSidebarItem({item: {source: manifest.displayName || manifest.name, ...item, core: isCore}});
                 } catch (err) {
                     fastify.log.warn(`[plugins] sidebar item for "${manifest.name}" skipped: ${err.message}`);
                 }
@@ -440,6 +498,12 @@ export async function registerPlugins(fastify) {
             await setupPlugin(manifest.name, {collections: {getCollection, createCollection}})
                 .catch(err => fastify.log.warn(`[plugins] Collection setup for "${manifest.name}" failed: ${err.message}`));
 
+            // Permissions are held in memory, so they are registered on every
+            // boot, not only on enable (roles are created once, then kept).
+            await import('./roles.js')
+                .then(rolesService => registerPluginAccess(manifest.name, rolesService))
+                .catch(err => fastify.log.warn(`[plugins] Access setup for "${manifest.name}" failed: ${err.message}`));
+
             // Detect optional plugin.public.js for root-level route registration
             _loadedPlugins[manifest.name] = { enabled: true, publicEntry: null };
             const publicEntryPath = path.join(PLUGINS_DIR, manifest.name, 'plugin.public.js');
@@ -634,38 +698,240 @@ export async function setupPlugin(pluginName, services) {
         }
     }
 
-    // Roles - read plugins/<name>/roles/*.json, register resources + persist roles
+    // Roles and permissions - see registerPluginAccess()
     if (services.roles) {
-        const rolesDir = path.join(pluginDir, 'roles');
-        let roleFiles;
-        try {
-            roleFiles = await fs.readdir(rolesDir);
-        } catch {
-            roleFiles = [];
+        result.roles.push(...(await registerPluginAccess(pluginName, services.roles)).roles);
+    }
+
+    return result;
+}
+
+/**
+ * Register what a plugin declares about access: the permission resources it
+ * guards its own routes with, the roles it brings, and which of the site's
+ * existing roles should start out holding its permissions.
+ *
+ * Two places declare these, and both are read:
+ *
+ *   plugin.json   "permissions": [{key, label?, actions?, group?, grant?}]
+ *   roles/*.json  {name, label, level, permissions, badgeClass?, resources?: [...]}
+ *
+ * A resource's `grant: ["admin"]` gives those roles the permission once; a
+ * role file creates its role once. After that both belong to the admin: an
+ * edited role is never overwritten and a revoked grant is never re-added.
+ *
+ * Resources live in memory, so this runs on every boot for each enabled
+ * plugin as well as on enable - otherwise a plugin's permissions vanish from
+ * the role editor after the first restart.
+ *
+ * @param {string} pluginName
+ * @param {object} rolesService - server/services/roles.js (injectable for tests)
+ * @returns {Promise<{roles: string[], resources: string[]}>}
+ */
+export async function registerPluginAccess(pluginName, rolesService) {
+    const out = {roles: [], resources: []};
+    const pluginDir = path.join(PLUGINS_DIR, pluginName);
+    const grants = [];
+
+    const addResource = (resource) => {
+        if (!resource || typeof resource.key !== 'string' || !resource.key) return;
+        const {grant, ...definition} = resource;
+        registerPluginResource(definition, pluginName);
+        out.resources.push(resource.key);
+        for (const role of Array.isArray(grant) ? grant : []) {
+            if (typeof role === 'string' && role) grants.push([role, resource.key]);
         }
-        for (const file of roleFiles.filter(f => f.endsWith('.json'))) {
-            try {
-                const raw = await fs.readFile(path.join(rolesDir, file), 'utf8');
-                const def = JSON.parse(raw);
-
-                // Register any declared resources into the permission overlay
-                if (Array.isArray(def.resources)) {
-                    for (const resource of def.resources) {
-                        registerPluginResource(resource, pluginName);
-                    }
-                }
+    };
 
-                // Persist the role (idempotent)
-                const {resources: _resources, ...roleData} = def;
-                await services.roles.createRole({...roleData, plugin: pluginName});
-                result.roles.push(def.name);
-            } catch {
-                // Skip missing or invalid role files
+    try {
+        const manifest = JSON.parse(await fs.readFile(path.join(pluginDir, 'plugin.json'), 'utf8'));
+        if (Array.isArray(manifest.permissions)) manifest.permissions.forEach(addResource);
+    } catch { /* no manifest permissions */ }
+
+    let roleFiles = [];
+    try {
+        roleFiles = (await fs.readdir(path.join(pluginDir, 'roles'))).filter(f => f.endsWith('.json'));
+    } catch { /* no roles dir */ }
+
+    const roleDefs = [];
+    for (const file of roleFiles) {
+        try {
+            const def = JSON.parse(await fs.readFile(path.join(pluginDir, 'roles', file), 'utf8'));
+            if (Array.isArray(def.resources)) def.resources.forEach(addResource);
+            if (typeof def.name === 'string' && def.name) roleDefs.push(def);
+        } catch { /* skip an unreadable role file */ }
+    }
+
+    for (const def of roleDefs) {
+        const {resources: _resources, ...roleData} = def;
+        if (validateRoleDef(roleData)) continue;
+        try {
+            const ensure = rolesService.ensureRole || rolesService.createRole;
+            await ensure({...roleData, plugin: pluginName});
+            out.roles.push(def.name);
+        } catch { /* skip */ }
+    }
+
+    for (const [role, permission] of grants) {
+        try {
+            await rolesService.grantPermissionOnce?.(role, permission, pluginName);
+        } catch { /* a role that does not exist is simply not granted */ }
+    }
+
+    // Bare permissions ('blog-posts') expand to the resource's actions when
+    // the cache is built, which happened before these resources existed.
+    if (out.resources.length) await rolesService.invalidate?.();
+    return out;
+}
+
+/** Role names: what a role slug has always looked like in the roles collection. */
+const ROLE_NAME_RE = /^[a-z0-9][a-z0-9-_]{0,63}$/;
+
+/**
+ * Why a role definition is unusable, or null if it is fine. Level 0 is the
+ * root role; a plugin can never mint another one.
+ *
+ * @param {object} def
+ * @returns {string|null}
+ */
+function validateRoleDef(def) {
+    if (!def || typeof def !== 'object') return 'a role definition object is required';
+    if (typeof def.name !== 'string' || !ROLE_NAME_RE.test(def.name)) {
+        return 'name must be lowercase letters, digits, "-" or "_" (max 64)';
+    }
+    if (!Number.isInteger(def.level) || def.level < 1) return 'level must be a whole number of 1 or more';
+    if (def.label != null && typeof def.label !== 'string') return 'label must be a string';
+    if (def.permissions != null && !(Array.isArray(def.permissions) && def.permissions.every(p => typeof p === 'string'))) {
+        return 'permissions must be an array of strings';
+    }
+    if (def.admin != null && !normaliseAdminScope(def.admin)) {
+        return 'admin must be {home?, allow: ["/route", ...]} with at least one /-rooted route';
+    }
+    return null;
+}
+
+/**
+ * Register a role on behalf of a plugin - the code behind `hooks.registerRole()`.
+ *
+ * Same rules as a `roles/*.json` file: created once, then the admin's. Calling
+ * it again (every boot, say) is a no-op for a role this plugin already owns,
+ * so an admin's edits survive. A name held by the site or by another plugin is
+ * refused with an error rather than skipped - a plugin asking for `admin`
+ * should find out, not silently share the site's role.
+ *
+ * `resources` (permission definitions, as in plugin.json `permissions`) are
+ * registered too, `grant` included.
+ *
+ * @param {string} pluginName
+ * @param {{name:string,label?:string,level:number,permissions?:string[],badgeClass?:string,resources?:object[]}} def
+ * @param {object} [rolesService]
+ * @returns {Promise<{name: string, created: boolean}>}
+ */
+export async function registerRoleForPlugin(pluginName, def, rolesService = defaultRolesService) {
+    if (!def || typeof def !== 'object') throw new Error('registerRole: a role definition object is required');
+    const {resources, ...roleData} = def;
+    const problem = validateRoleDef(roleData);
+    if (problem) throw new Error(`registerRole: ${problem}`);
+
+    const existing = await rolesService.getRoleData(roleData.name);
+    if (existing && existing.plugin !== pluginName) {
+        throw new Error(`registerRole: role "${roleData.name}" already exists and does not belong to plugin "${pluginName}"`);
+    }
+
+    let registered = false;
+    for (const resource of Array.isArray(resources) ? resources : []) {
+        if (!resource || typeof resource.key !== 'string' || !resource.key) continue;
+        const {grant, ...definition} = resource;
+        registerPluginResource(definition, pluginName);
+        registered = true;
+        for (const role of Array.isArray(grant) ? grant : []) {
+            if (typeof role === 'string' && role) {
+                await rolesService.grantPermissionOnce(role, resource.key, pluginName).catch(() => {});
             }
         }
     }
 
-    return result;
+    const created = existing ? false : await rolesService.ensureRole({
+        label: roleData.name, permissions: [], ...roleData, plugin: pluginName
+    });
+    if (registered) await rolesService.invalidate();
+    return {name: roleData.name, created: !!created};
+}
+
+/**
+ * Remove a role a plugin registered - the code behind `hooks.unregisterRole()`.
+ *
+ * Only the owning plugin can remove its role; the site's roles and other
+ * plugins' roles are refused. Users are moved off the role in the same step:
+ * one holding it as their primary role becomes `user` (the base role that
+ * always exists), and it is dropped from everyone's additional roles. That is
+ * what the next boot would do anyway (seed() demotes unknown roles), done now
+ * so nobody is left holding a role that grants nothing.
+ *
+ * @param {string} pluginName
+ * @param {string} name
+ * @param {{rolesService?: object, usersService?: object}} [services]
+ * @returns {Promise<{name: string, removed: boolean, usersReassigned: number}>}
+ */
+export async function unregisterRoleForPlugin(pluginName, name, {
+    rolesService = defaultRolesService,
+    usersService = defaultUsersService
+} = {}) {
+    const existing = await rolesService.getRoleData(name);
+    if (!existing) return {name, removed: false, usersReassigned: 0};
+    if (existing.plugin !== pluginName) {
+        throw new Error(`unregisterRole: role "${name}" does not belong to plugin "${pluginName}"`);
+    }
+
+    await rolesService.removeRole(name);
+
+    let usersReassigned = 0;
+    for (const user of await usersService.listUsers()) {
+        const additional = Array.isArray(user.additionalRoles) ? user.additionalRoles : [];
+        const holdsPrimary = user.role === name;
+        if (!holdsPrimary && !additional.includes(name)) continue;
+        await usersService.updateUser(user.id, {
+            ...(holdsPrimary && {role: 'user'}),
+            additionalRoles: additional.filter(r => r !== name)
+        });
+        usersReassigned++;
+    }
+    return {name, removed: true, usersReassigned};
+}
+
+/**
+ * Remove every role a plugin owns - used when the plugin is uninstalled.
+ * (Disabling keeps them; see teardownPlugin.)
+ *
+ * @param {string} pluginName
+ * @param {{rolesService?: object, usersService?: object}} [services]
+ * @returns {Promise<string[]>} the removed role names
+ */
+export async function unregisterAllRolesForPlugin(pluginName, services = {}) {
+    const rolesService = services.rolesService || defaultRolesService;
+    const owned = [...rolesService.getRoleMap().keys()];
+    const removed = [];
+    for (const name of owned) {
+        const data = await rolesService.getRoleData(name);
+        if (data?.plugin !== pluginName) continue;
+        const res = await unregisterRoleForPlugin(pluginName, name, services);
+        if (res.removed) removed.push(name);
+    }
+    return removed;
+}
+
+/**
+ * The role hooks handed to one plugin, bound to its name so it can only ever
+ * register and remove roles of its own.
+ *
+ * @param {string} pluginName
+ * @returns {{registerRole: Function, unregisterRole: Function}}
+ */
+export function pluginRoleHooks(pluginName) {
+    return {
+        registerRole:   (def)  => registerRoleForPlugin(pluginName, def),
+        unregisterRole: (name) => unregisterRoleForPlugin(pluginName, name)
+    };
 }
 
 /**
@@ -714,16 +980,11 @@ export async function teardownPlugin(pluginName, services, fastify) {
         }
     }
 
-    // Roles - remove plugin-contributed roles and unregister their resources
-    if (services.roles) {
-        try {
-            await services.roles.removeRolesByPlugin(pluginName);
-            unregisterPluginResourcesByPlugin(pluginName);
-            result.roles.push(pluginName);
-        } catch (err) {
-            fastify.log.warn(`[plugins] Could not remove roles for "${pluginName}": ${err.message}`);
-        }
-    }
+    // Permissions - unregister the plugin's resources. Its roles are KEPT: a
+    // role removed here would leave every user holding it with a role the
+    // next boot's migrateUserRoles() rewrites to 'user', so a disable/enable
+    // cycle would silently demote them. Like collections, they stay put.
+    unregisterPluginResourcesByPlugin(pluginName);
 
     if (_loadedPlugins[pluginName]) {
         _loadedPlugins[pluginName].enabled = false;
@@ -797,11 +1058,10 @@ export async function runLifecycleHook(name, hook, fastify) {
             const torn = await teardownPlugin(name, services, fastify);
             if (torn.pages.length) fastify.log.info(`[plugins] Removed pages for "${name}": ${torn.pages.join(', ')}`);
             if (torn.forms.length) fastify.log.info(`[plugins] Removed forms for "${name}": ${torn.forms.join(', ')}`);
-            if (torn.roles.length) fastify.log.info(`[plugins] Removed roles for "${name}"`);
         }
 
         if (typeof mod[hook] === 'function') {
-            await mod[hook]({ fastify, services });
+            await mod[hook]({ fastify, services, hooks: pluginRoleHooks(name) });
         }
     } catch (err) {
         fastify.log.error(`Plugin "${name}" lifecycle hook "${hook}" failed: ${err.message}`);
@@ -908,6 +1168,33 @@ export function pluginExpiry(manifest, given) {
         : null;
 }
 
+
+/**
+ * The sidebar name of the screen a view draws, for its banner - '' when the
+ * plugin has one screen or the view has no sidebar entry of its own.
+ *
+ * A route maps a path to a view and a sidebar entry links to a path, so the
+ * entry whose link is one of the view's routes names it. Sub-entries win over
+ * the top-level one: Site Manager's top entry and its "Sites" entry share a
+ * link, and "Sites" is the screen.
+ *
+ * @param   {object} manifest
+ * @param   {string} viewName
+ * @returns {string}
+ */
+export function viewSection(manifest, viewName) {
+    const admin = manifest.admin || {};
+    const paths = new Set((admin.routes || [])
+        .filter(r => r && r.view === viewName && typeof r.path === 'string')
+        .map(r => `#${r.path}`));
+    if (!paths.size) return '';
+    const top = admin.sidebar || [];
+    const entries = [...top.flatMap(e => (e && e.items) || []), ...top];
+    const hit = entries.find(e => e && paths.has(e.url));
+    const text = hit ? String(hit.text || '').trim() : '';
+    return text && text !== (manifest.displayName || manifest.name) ? text : '';
+}
+
 export async function getAdminPluginConfig() {
     const manifests = await discoverPlugins();
     const states = getPluginStates();
@@ -955,6 +1242,7 @@ export async function getAdminPluginConfig() {
             meta[viewName] = {
                 plugin:      manifest.name,
                 displayName: manifest.displayName || manifest.name,
+                section:     viewSection(manifest, viewName),
                 version:     manifest.version || '1.0.0',
                 date:        manifest.date || '',
                 author:      manifest.author || '',
@@ -984,5 +1272,5 @@ export async function getAdminPluginConfig() {
         }
     }
 
-    return { sidebar, routes, views, css, meta };
+    return { sidebar, routes, views, css, meta, takeovers: getToolTakeovers() };
 }