domma-cms 0.44.0 → 0.45.1

package/server/middleware/auth.js

@@ -1,253 +1,253 @@
-/**
- * Authentication Middleware
- * JWT-based authentication with role guards for Domma CMS.
- * Role data is read from the roles cache (not config.auth.roles).
- */
-import {getPermissionsFor, getPermissionsForRole, getRoleHierarchy, getRoleLevel} from '../services/roles.js';
-import {getEffectiveLevel, getEffectiveRoles} from '../services/userRoles.js';
-
-/**
- * Verify JWT Bearer token. Populates request.user on success.
- *
- * @param {FastifyRequest} request
- * @param {FastifyReply} reply
- * @returns {Promise<void>}
- */
-export async function authenticate(request, reply) {
-    try {
-        const decoded = await request.jwtVerify();
-        if (decoded.type !== 'access') {
-            return reply.code(401).send({
-                statusCode: 401,
-                error: 'Unauthorised',
-                message: 'Invalid token type'
-            });
-        }
-    } catch {
-        return reply.code(401).send({
-            statusCode: 401,
-            error: 'Unauthorised',
-            message: 'Invalid or missing authentication token'
-        });
-    }
-}
-
-/**
- * Return a preHandler that enforces one of the specified roles.
- * Must be used after authenticate.
- *
- * @param {string[]} allowedRoles
- * @returns {Function}
- */
-export function requireRole(allowedRoles) {
-    const allowed = Array.isArray(allowedRoles) ? allowedRoles : [allowedRoles];
-
-    return async (request, reply) => {
-        if (!request.user) {
-            return reply.code(401).send({
-                statusCode: 401,
-                error: 'Unauthorised',
-                message: 'Authentication required'
-            });
-        }
-
-        if (!allowed.includes(request.user.role)) {
-            return reply.code(403).send({
-                statusCode: 403,
-                error: 'Forbidden',
-                message: `Access denied. Required role: ${allowed.join(' or ')}`
-            });
-        }
-    };
-}
-
-/**
- * Return a preHandler that checks the current user's role has access to a resource.
- * Reads from the roles cache at request time — reflects live role changes.
- *
- * @param {string}  resource - Resource key (e.g. 'pages', 'users')
- * @param {string} [action]  - Optional action (read | create | update | delete)
- * @returns {Function}
- */
-export function requirePermission(resource, action) {
-    return async (request, reply) => {
-        if (!request.user) {
-            return reply.code(401).send({
-                statusCode: 401,
-                error: 'Unauthorised',
-                message: 'Authentication required'
-            });
-        }
-
-        // Check ANY of the user's effective roles (primary + additional) against
-        // the resource's permission list — union semantics so a user with both
-        // candidate and recruiter roles can do either role's actions.
-        const allowed = getPermissionsFor(resource, action);
-        const roles   = getEffectiveRoles(request.user);
-        if (!roles.some(r => allowed.includes(r))) {
-            return reply.code(403).send({
-                statusCode: 403,
-                error: 'Forbidden',
-                message: 'Insufficient permissions'
-            });
-        }
-    };
-}
-
-/**
- * Export getPermissionsForRole for use in route handlers.
- *
- * @param {string} roleName
- * @returns {string[]}
- */
-export {getPermissionsForRole};
-
-/**
- * Shorthand preHandler — admin-tier role (level ≤ 1) or above.
- * Matches the base role hierarchy documented in roles.js:
- *   super-admin (0), admin (1), user (2).
- * Both super-admin and admin pass; regular users and anything below do not.
- *
- * @param {FastifyRequest} request
- * @param {FastifyReply} reply
- * @returns {Promise<void>}
- */
-export async function requireAdmin(request, reply) {
-    if (!request.user) {
-        return reply.code(401).send({ statusCode: 401, error: 'Unauthorised', message: 'Authentication required' });
-    }
-    // Use effective level — a user with "additionalRoles: ['admin']" can do admin work
-    // even if their primary role is something lower-privilege.
-    if (getEffectiveLevel(request.user) > 1) {
-        return reply.code(403).send({ statusCode: 403, error: 'Forbidden', message: 'Admin access required' });
-    }
-}
-
-/**
- * Determine whether an actor can manage a target user.
- * Managers cannot create, edit, or delete users with a lower level number (higher privilege).
- *
- * Accepts either user objects (preferred — uses effective level across all roles)
- * or bare role-name strings (legacy compat). Strings are looked up via
- * `getRoleLevel`; objects via `getEffectiveLevel` so multi-role actors and
- * targets are compared by their HIGHEST-privilege role.
- *
- * @param {string|object} actor   - Role name OR user object
- * @param {string|object} target  - Role name OR user object
- * @returns {boolean}
- */
-export function canManageUser(actor, target) {
-    const actorLevel  = typeof actor  === 'string' ? getRoleLevel(actor)  : getEffectiveLevel(actor);
-    const targetLevel = typeof target === 'string' ? getRoleLevel(target) : getEffectiveLevel(target);
-    return actorLevel < targetLevel;
-}
-
-/**
- * Check whether a user role satisfies a visibility requirement.
- * Used by both requireVisibility() and the public page renderer.
- *
- * Visibility may be either:
- *   - A single string ('public', 'private', or a role name)
- *   - An array of role names — granted if ANY entry passes the per-role check
- *
- * Per-role semantics are unchanged: each role check passes if the visitor's
- * role level is at or above the required role (lower or equal level number).
- * 'private' resolves to super-admin only (Infinity → level 0).
- *
- * The "any of" semantics for arrays means siblings at different tiers of the
- * hierarchy are all granted access — e.g. `visibility: [candidate, employer]`
- * lets both roles in, plus anyone more privileged than either (typically
- * admins inherit access automatically via the level comparison).
- *
- * @param {string|null}      userRole   - The visitor's role, or null if unauthenticated
- * @param {string|string[]}  visibility - Required visibility — single value or array
- * @returns {boolean} true if access is granted
- */
-export function checkVisibility(userRoleOrObj, visibility) {
-    if (!visibility) return true;
-
-    // Accept either a bare role name (legacy) or a user object with multi-role
-    // support. When given an object we walk every effective role and grant
-    // access if ANY satisfies — same union semantics as permissions.
-    const roles = typeof userRoleOrObj === 'string'
-        ? (userRoleOrObj ? [userRoleOrObj] : [])
-        : getEffectiveRoles(userRoleOrObj);
-
-    if (Array.isArray(visibility)) {
-        if (visibility.length === 0) return true;
-        if (visibility.includes('public')) return true;
-        if (!roles.length) return false;
-        return roles.some(r => visibility.some(v => checkSingleVisibility(r, v)));
-    }
-
-    if (visibility === 'public') return true;
-    if (!roles.length) return false;
-    return roles.some(r => checkSingleVisibility(r, visibility));
-}
-
-/**
- * Internal helper — single-role visibility check.
- * Returns true if the user role is at or above the required role's level.
- *
- * @param {string} userRole   - Must not be null
- * @param {string} visibility - Single visibility token (role name or 'private')
- * @returns {boolean}
- */
-function checkSingleVisibility(userRole, visibility) {
-    const userLevel     = getRoleLevel(userRole);
-    const requiredLevel = getRoleLevel(visibility);
-    const threshold     = requiredLevel === Infinity ? 0 : requiredLevel;
-    return userLevel <= threshold;
-}
-
-/**
- * Fastify preHandler factory — gates a route by visibility level.
- * Works identically to the content-page visibility system; accepts the same
- * single-string or array-of-roles syntax as checkVisibility().
- *
- * Returns a no-op for 'public' (or any array containing 'public') so it is
- * safe to apply unconditionally.
- *
- * @param {string|string[]} visibility - 'public' | 'private' | role name | array of role names
- * @returns {Function} Fastify preHandler
- */
-export function requireVisibility(visibility) {
-    const isPublic = !visibility
-        || visibility === 'public'
-        || (Array.isArray(visibility) && (visibility.length === 0 || visibility.includes('public')));
-
-    if (isPublic) {
-        return (_request, _reply, done) => { if (done) done(); };
-    }
-
-    return async (request, reply) => {
-        // Build a user-shaped object so checkVisibility can see multi-role
-        // (primary + additional). Unauthenticated → null → public-only access.
-        let userObj = null;
-        try {
-            const decoded = await request.jwtVerify();
-            if (decoded.type === 'access') {
-                userObj = { role: decoded.role, additionalRoles: decoded.additionalRoles || [] };
-            }
-        } catch { /* unauthenticated */ }
-
-        if (!checkVisibility(userObj, visibility)) {
-            const code = userObj ? 403 : 401;
-            return reply.code(code).send({
-                statusCode: code,
-                error:      code === 403 ? 'Forbidden' : 'Unauthorised',
-                message:    code === 403 ? 'Insufficient role for this resource' : 'Authentication required'
-            });
-        }
-    };
-}
-
-/**
- * Return role names ordered from most to least privileged.
- * Computed from the roles cache.
- *
- * @returns {string[]}
- */
-export function getRoleHierarchyList() {
-    return getRoleHierarchy();
-}
+/**
+ * Authentication Middleware
+ * JWT-based authentication with role guards for Domma CMS.
+ * Role data is read from the roles cache (not config.auth.roles).
+ */
+import {getPermissionsFor, getPermissionsForRole, getRoleHierarchy, getRoleLevel} from '../services/roles.js';
+import {getEffectiveLevel, getEffectiveRoles} from '../services/userRoles.js';
+
+/**
+ * Verify JWT Bearer token. Populates request.user on success.
+ *
+ * @param {FastifyRequest} request
+ * @param {FastifyReply} reply
+ * @returns {Promise<void>}
+ */
+export async function authenticate(request, reply) {
+    try {
+        const decoded = await request.jwtVerify();
+        if (decoded.type !== 'access') {
+            return reply.code(401).send({
+                statusCode: 401,
+                error: 'Unauthorised',
+                message: 'Invalid token type'
+            });
+        }
+    } catch {
+        return reply.code(401).send({
+            statusCode: 401,
+            error: 'Unauthorised',
+            message: 'Invalid or missing authentication token'
+        });
+    }
+}
+
+/**
+ * Return a preHandler that enforces one of the specified roles.
+ * Must be used after authenticate.
+ *
+ * @param {string[]} allowedRoles
+ * @returns {Function}
+ */
+export function requireRole(allowedRoles) {
+    const allowed = Array.isArray(allowedRoles) ? allowedRoles : [allowedRoles];
+
+    return async (request, reply) => {
+        if (!request.user) {
+            return reply.code(401).send({
+                statusCode: 401,
+                error: 'Unauthorised',
+                message: 'Authentication required'
+            });
+        }
+
+        if (!allowed.includes(request.user.role)) {
+            return reply.code(403).send({
+                statusCode: 403,
+                error: 'Forbidden',
+                message: `Access denied. Required role: ${allowed.join(' or ')}`
+            });
+        }
+    };
+}
+
+/**
+ * Return a preHandler that checks the current user's role has access to a resource.
+ * Reads from the roles cache at request time - reflects live role changes.
+ *
+ * @param {string}  resource - Resource key (e.g. 'pages', 'users')
+ * @param {string} [action]  - Optional action (read | create | update | delete)
+ * @returns {Function}
+ */
+export function requirePermission(resource, action) {
+    return async (request, reply) => {
+        if (!request.user) {
+            return reply.code(401).send({
+                statusCode: 401,
+                error: 'Unauthorised',
+                message: 'Authentication required'
+            });
+        }
+
+        // Check ANY of the user's effective roles (primary + additional) against
+        // the resource's permission list - union semantics so a user with both
+        // candidate and recruiter roles can do either role's actions.
+        const allowed = getPermissionsFor(resource, action);
+        const roles   = getEffectiveRoles(request.user);
+        if (!roles.some(r => allowed.includes(r))) {
+            return reply.code(403).send({
+                statusCode: 403,
+                error: 'Forbidden',
+                message: 'Insufficient permissions'
+            });
+        }
+    };
+}
+
+/**
+ * Export getPermissionsForRole for use in route handlers.
+ *
+ * @param {string} roleName
+ * @returns {string[]}
+ */
+export {getPermissionsForRole};
+
+/**
+ * Shorthand preHandler - admin-tier role (level ≤ 1) or above.
+ * Matches the base role hierarchy documented in roles.js:
+ *   super-admin (0), admin (1), user (2).
+ * Both super-admin and admin pass; regular users and anything below do not.
+ *
+ * @param {FastifyRequest} request
+ * @param {FastifyReply} reply
+ * @returns {Promise<void>}
+ */
+export async function requireAdmin(request, reply) {
+    if (!request.user) {
+        return reply.code(401).send({ statusCode: 401, error: 'Unauthorised', message: 'Authentication required' });
+    }
+    // Use effective level - a user with "additionalRoles: ['admin']" can do admin work
+    // even if their primary role is something lower-privilege.
+    if (getEffectiveLevel(request.user) > 1) {
+        return reply.code(403).send({ statusCode: 403, error: 'Forbidden', message: 'Admin access required' });
+    }
+}
+
+/**
+ * Determine whether an actor can manage a target user.
+ * Managers cannot create, edit, or delete users with a lower level number (higher privilege).
+ *
+ * Accepts either user objects (preferred - uses effective level across all roles)
+ * or bare role-name strings (legacy compat). Strings are looked up via
+ * `getRoleLevel`; objects via `getEffectiveLevel` so multi-role actors and
+ * targets are compared by their HIGHEST-privilege role.
+ *
+ * @param {string|object} actor   - Role name OR user object
+ * @param {string|object} target  - Role name OR user object
+ * @returns {boolean}
+ */
+export function canManageUser(actor, target) {
+    const actorLevel  = typeof actor  === 'string' ? getRoleLevel(actor)  : getEffectiveLevel(actor);
+    const targetLevel = typeof target === 'string' ? getRoleLevel(target) : getEffectiveLevel(target);
+    return actorLevel < targetLevel;
+}
+
+/**
+ * Check whether a user role satisfies a visibility requirement.
+ * Used by both requireVisibility() and the public page renderer.
+ *
+ * Visibility may be either:
+ *   - A single string ('public', 'private', or a role name)
+ *   - An array of role names - granted if ANY entry passes the per-role check
+ *
+ * Per-role semantics are unchanged: each role check passes if the visitor's
+ * role level is at or above the required role (lower or equal level number).
+ * 'private' resolves to super-admin only (Infinity → level 0).
+ *
+ * The "any of" semantics for arrays means siblings at different tiers of the
+ * hierarchy are all granted access - e.g. `visibility: [candidate, employer]`
+ * lets both roles in, plus anyone more privileged than either (typically
+ * admins inherit access automatically via the level comparison).
+ *
+ * @param {string|null}      userRole   - The visitor's role, or null if unauthenticated
+ * @param {string|string[]}  visibility - Required visibility - single value or array
+ * @returns {boolean} true if access is granted
+ */
+export function checkVisibility(userRoleOrObj, visibility) {
+    if (!visibility) return true;
+
+    // Accept either a bare role name (legacy) or a user object with multi-role
+    // support. When given an object we walk every effective role and grant
+    // access if ANY satisfies - same union semantics as permissions.
+    const roles = typeof userRoleOrObj === 'string'
+        ? (userRoleOrObj ? [userRoleOrObj] : [])
+        : getEffectiveRoles(userRoleOrObj);
+
+    if (Array.isArray(visibility)) {
+        if (visibility.length === 0) return true;
+        if (visibility.includes('public')) return true;
+        if (!roles.length) return false;
+        return roles.some(r => visibility.some(v => checkSingleVisibility(r, v)));
+    }
+
+    if (visibility === 'public') return true;
+    if (!roles.length) return false;
+    return roles.some(r => checkSingleVisibility(r, visibility));
+}
+
+/**
+ * Internal helper - single-role visibility check.
+ * Returns true if the user role is at or above the required role's level.
+ *
+ * @param {string} userRole   - Must not be null
+ * @param {string} visibility - Single visibility token (role name or 'private')
+ * @returns {boolean}
+ */
+function checkSingleVisibility(userRole, visibility) {
+    const userLevel     = getRoleLevel(userRole);
+    const requiredLevel = getRoleLevel(visibility);
+    const threshold     = requiredLevel === Infinity ? 0 : requiredLevel;
+    return userLevel <= threshold;
+}
+
+/**
+ * Fastify preHandler factory - gates a route by visibility level.
+ * Works identically to the content-page visibility system; accepts the same
+ * single-string or array-of-roles syntax as checkVisibility().
+ *
+ * Returns a no-op for 'public' (or any array containing 'public') so it is
+ * safe to apply unconditionally.
+ *
+ * @param {string|string[]} visibility - 'public' | 'private' | role name | array of role names
+ * @returns {Function} Fastify preHandler
+ */
+export function requireVisibility(visibility) {
+    const isPublic = !visibility
+        || visibility === 'public'
+        || (Array.isArray(visibility) && (visibility.length === 0 || visibility.includes('public')));
+
+    if (isPublic) {
+        return (_request, _reply, done) => { if (done) done(); };
+    }
+
+    return async (request, reply) => {
+        // Build a user-shaped object so checkVisibility can see multi-role
+        // (primary + additional). Unauthenticated → null → public-only access.
+        let userObj = null;
+        try {
+            const decoded = await request.jwtVerify();
+            if (decoded.type === 'access') {
+                userObj = { role: decoded.role, additionalRoles: decoded.additionalRoles || [] };
+            }
+        } catch { /* unauthenticated */ }
+
+        if (!checkVisibility(userObj, visibility)) {
+            const code = userObj ? 403 : 401;
+            return reply.code(code).send({
+                statusCode: code,
+                error:      code === 403 ? 'Forbidden' : 'Unauthorised',
+                message:    code === 403 ? 'Insufficient role for this resource' : 'Authentication required'
+            });
+        }
+    };
+}
+
+/**
+ * Return role names ordered from most to least privileged.
+ * Computed from the roles cache.
+ *
+ * @returns {string[]}
+ */
+export function getRoleHierarchyList() {
+    return getRoleHierarchy();
+}

package/server/middleware/managerAuth.js

@@ -1,11 +1,11 @@
 /**
- * Manager auth middleware — shared-secret guard for inbound requests from domma-cms-manager.
+ * Manager auth middleware - shared-secret guard for inbound requests from domma-cms-manager.
  * Completely separate from JWT authenticate. Do NOT mix these two auth surfaces.
  */
 import { timingSafeEqual, createHmac } from 'crypto';
 
 /**
- * Fastify preHandler — validates the X-Manager-Token or Authorization: Bearer header
+ * Fastify preHandler - validates the X-Manager-Token or Authorization: Bearer header
  * against the MANAGER_SECRET environment variable using timing-safe comparison.
  *
  * @param {import('fastify').FastifyRequest} request
@@ -26,7 +26,7 @@ export function requireManager(request, reply, done) {
         return reply.code(401).send({ error: 'Manager token required.' });
     }
 
-    // Compare HMAC digests — always 32 bytes regardless of input length, preventing timing oracle
+    // Compare HMAC digests - always 32 bytes regardless of input length, preventing timing oracle
     const digest = (s) => createHmac('sha256', 'domma-cms').update(s).digest();
     if (!timingSafeEqual(digest(token), digest(secret))) {
         return reply.code(403).send({ error: 'Invalid manager token.' });

package/server/routes/api/actions.js

@@ -1,5 +1,5 @@
 /**
- * Actions API (Pro — requires MongoDB)
+ * Actions API (Pro - requires MongoDB)
  *
  * Admin endpoints (authenticated + actions permission):
  * GET    /actions                        - List all action configs
@@ -43,7 +43,7 @@ export async function actionsRoutes(fastify) {
         try {
             const {canSeeArtefact} = await import('../../services/projects.js');
             const all = await listActions();
-            // listActions returns full records with meta inline — filter directly
+            // listActions returns full records with meta inline - filter directly
             return all.filter(a => canSeeArtefact(request.user, a));
         } catch (err) {
             return reply.status(503).send({ error: err.message });
@@ -188,7 +188,7 @@ export async function actionsRoutes(fastify) {
 
         const user          = request.user;
         const allowedRoles  = action.access?.roles || ['admin', 'super-admin'];
-        // Use effective level — a candidate-with-also-admin can run admin-tier actions.
+        // Use effective level - a candidate-with-also-admin can run admin-tier actions.
         const userLevel     = getEffectiveLevel(user);
         const minAllowed    = Math.min(...allowedRoles.map(r => getRoleLevel(r)));
 
@@ -217,7 +217,7 @@ export async function actionsRoutes(fastify) {
      * shortcode to render only the buttons that will actually succeed.
      *
      * Auth: optional. Anonymous calls return actions accessible to anonymous
-     * users (rare — most transitions require a role). With a JWT we narrow
+     * users (rare - most transitions require a role). With a JWT we narrow
      * to what the signed-in user can do.
      *
      * Response: { transitions: [{slug, title, trigger, transition}, ...] }

package/server/routes/api/api-endpoints.js

@@ -1,11 +1,11 @@
 /**
  * API Endpoints API (admin management of custom endpoint definitions)
  *
- * GET    /api/api-endpoints      — list definitions visible to the caller
- * GET    /api/api-endpoints/:id  — single definition (the builder editor)
- * POST   /api/api-endpoints      — create (400 validation, 409 duplicate path shape)
- * PUT    /api/api-endpoints/:id  — update (project binding immutable)
- * DELETE /api/api-endpoints/:id  — delete
+ * GET    /api/api-endpoints      - list definitions visible to the caller
+ * GET    /api/api-endpoints/:id  - single definition (the builder editor)
+ * POST   /api/api-endpoints      - create (400 validation, 409 duplicate path shape)
+ * PUT    /api/api-endpoints/:id  - update (project binding immutable)
+ * DELETE /api/api-endpoints/:id  - delete
  *
  * Endpoints are project-scoped artefacts: non-super-admin users with a
  * `projects: []` access scope only see/manage definitions in their projects.
@@ -28,7 +28,7 @@ import {getCollection} from '../../services/collections.js';
 /**
  * Scoped users must not expose data they cannot see: the collection an
  * endpoint queries is itself an artefact subject to project access scope.
- * Returns true when the user may use the collection (or it doesn't exist —
+ * Returns true when the user may use the collection (or it doesn't exist -
  * the service's validation produces the clearer 400 for that case).
  *
  * @param {object} user
@@ -96,7 +96,7 @@ export async function apiEndpointsRoutes(fastify, opts = {}) {
         if (!canSeeArtefact(request.user, {meta: {project: existing.project}})) {
             return reply.status(403).send({error: 'Access denied for this project'});
         }
-        // The project binding is the endpoint's URL namespace — immutable.
+        // The project binding is the endpoint's URL namespace - immutable.
         const {project: _ignored, ...patch} = request.body || {};
         if (!await canUseCollection(request.user, patch.collection ?? existing.collection)) {
             return reply.status(403).send({error: 'Access denied for this collection'});

package/server/routes/api/api-tokens.js

@@ -1,10 +1,10 @@
 /**
  * API Tokens API
  *
- * GET    /api/api-tokens      — list tokens visible to the caller (sanitised; never the hash)
- * POST   /api/api-tokens      — create; response carries the plaintext ONCE
- * PUT    /api/api-tokens/:id  — rename, enable/disable, edit scopes/expiry
- * DELETE /api/api-tokens/:id  — revoke (immediate)
+ * GET    /api/api-tokens      - list tokens visible to the caller (sanitised; never the hash)
+ * POST   /api/api-tokens      - create; response carries the plaintext ONCE
+ * PUT    /api/api-tokens/:id  - rename, enable/disable, edit scopes/expiry
+ * DELETE /api/api-tokens/:id  - revoke (immediate)
  *
  * Tokens are project-scoped artefacts: non-super-admin users with a
  * `projects: []` access scope only see/manage tokens in their projects.
@@ -51,7 +51,7 @@ export async function apiTokensRoutes(fastify, opts = {}) {
         try {
             const creator = request.user?.name || request.user?.email || null;
             const {entry, plaintext} = await createToken({name, project, scopes, expiresAt, createdBy: creator});
-            // The plaintext appears here and nowhere else — only the hash is stored.
+            // The plaintext appears here and nowhere else - only the hash is stored.
             return reply.status(201).send({token: entry, plaintext});
         } catch (err) {
             return reply.status(400).send({error: err.message});