domma-cms 0.23.0 → 0.25.0

package/config/menus/admin-sidebar.json

@@ -95,6 +95,12 @@
           "url": "#/components",
           "icon": "component",
           "permission": "components"
+        },
+        {
+          "text": "API Builder",
+          "url": "#/api-endpoints",
+          "icon": "code",
+          "permission": "api-endpoints"
         }
       ]
     },
@@ -143,6 +149,12 @@
           "text": "My Profile",
           "url": "#/my-profile",
           "icon": "user"
+        },
+        {
+          "text": "API Tokens",
+          "url": "#/api-tokens",
+          "icon": "key",
+          "permission": "api-tokens"
         }
       ]
     },
@@ -171,7 +183,7 @@
   ],
   "meta": {
     "createdAt": "2026-05-25T11:11:15.223Z",
-    "updatedAt": "2026-05-25T13:48:21.541Z",
+    "updatedAt": "2026-06-10T12:43:41.918Z",
     "bundled": false,
     "presetOwner": null,
     "project": null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

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/routes/api/api-endpoints.js

@@ -0,0 +1,96 @@
+/**
+ * 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
+ *
+ * Endpoints are project-scoped artefacts: non-super-admin users with a
+ * `projects: []` access scope only see/manage definitions in their projects.
+ * Auth middlewares are accepted as DI options so tests can supply no-ops.
+ */
+import {
+    authenticate as defaultAuthenticate,
+    requirePermission as defaultRequirePermission
+} from '../../middleware/auth.js';
+import {
+    createEndpoint,
+    deleteEndpoint,
+    getEndpointSanitised,
+    listEndpointsSanitised,
+    updateEndpoint
+} from '../../services/apiEndpoints.js';
+import {canSeeArtefact} from '../../services/projects.js';
+
+/**
+ * Register the api-endpoints routes.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {{authenticate?: Function, requirePermission?: Function}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function apiEndpointsRoutes(fastify, opts = {}) {
+    const authenticate      = opts.authenticate      || defaultAuthenticate;
+    const requirePermission = opts.requirePermission || defaultRequirePermission;
+
+    const canRead   = {preHandler: [authenticate, requirePermission('api-endpoints', 'read')]};
+    const canCreate = {preHandler: [authenticate, requirePermission('api-endpoints', 'create')]};
+    const canUpdate = {preHandler: [authenticate, requirePermission('api-endpoints', 'update')]};
+    const canDelete = {preHandler: [authenticate, requirePermission('api-endpoints', 'delete')]};
+
+    const statusFor = (err) => err.code === 'DUPLICATE' ? 409 : 400;
+
+    fastify.get('/api-endpoints', canRead, async (request) => {
+        return listEndpointsSanitised(request.user);
+    });
+
+    fastify.get('/api-endpoints/:id', canRead, async (request, reply) => {
+        const def = await getEndpointSanitised(request.params.id);
+        if (!def) return reply.status(404).send({error: 'Endpoint not found'});
+        if (!canSeeArtefact(request.user, {meta: {project: def.project}})) {
+            return reply.status(403).send({error: 'Access denied for this project'});
+        }
+        return def;
+    });
+
+    fastify.post('/api-endpoints', canCreate, async (request, reply) => {
+        const input = request.body || {};
+        if (input.project && !canSeeArtefact(request.user, {meta: {project: input.project}})) {
+            return reply.status(403).send({error: 'Access denied for this project'});
+        }
+        try {
+            const creator = request.user?.name || request.user?.email || null;
+            const def = await createEndpoint({...input, createdBy: creator});
+            return reply.status(201).send(def);
+        } catch (err) {
+            return reply.status(statusFor(err)).send({error: err.message});
+        }
+    });
+
+    fastify.put('/api-endpoints/:id', canUpdate, async (request, reply) => {
+        const existing = await getEndpointSanitised(request.params.id);
+        if (!existing) return reply.status(404).send({error: 'Endpoint not found'});
+        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.
+        const {project: _ignored, ...patch} = request.body || {};
+        try {
+            return await updateEndpoint(request.params.id, patch);
+        } catch (err) {
+            return reply.status(statusFor(err)).send({error: err.message});
+        }
+    });
+
+    fastify.delete('/api-endpoints/:id', canDelete, async (request, reply) => {
+        const existing = await getEndpointSanitised(request.params.id);
+        if (!existing) return reply.status(404).send({error: 'Endpoint not found'});
+        if (!canSeeArtefact(request.user, {meta: {project: existing.project}})) {
+            return reply.status(403).send({error: 'Access denied for this project'});
+        }
+        await deleteEndpoint(request.params.id);
+        return {success: true};
+    });
+}