domma-cms 0.70.0 → 0.71.0

package/server/services/plugins.js

@@ -14,7 +14,7 @@ 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,
@@ -26,6 +26,9 @@ import {
 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');
 
@@ -413,8 +416,8 @@ 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, registerSidebarItem, on: hooks.on.bind(hooks), ...pluginRoleHooks(manifest.name)},
               settings,
               config: {}
           });
@@ -440,6 +443,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 +643,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 +925,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 +1003,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}`);

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,141 @@ 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}
+ */
+export function normaliseAdminScope(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+    const clean = p => (typeof p === 'string' && ADMIN_PATH_RE.test(p.trim()))
+        ? (p.trim().replace(/\/+$/, '') || '/')
+        : null;
+    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 +526,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];
 }
 
 /**