domma-cms 0.30.0 → 0.32.1

package/plugins/surveys/plugin.json

@@ -0,0 +1,65 @@
+{
+  "name": "surveys",
+  "displayName": "Surveys",
+  "version": "1.0.0",
+  "description": "Targeted surveys over the Forms engine: shared audiences, tokenised invites, reminders, and per-survey statistics.",
+  "author": "Darryl Waterhouse",
+  "date": "2026-06-26",
+  "icon": "clipboard-list",
+  "admin": {
+    "sidebar": [
+      {
+        "id": "surveys",
+        "text": "Surveys",
+        "icon": "clipboard-list",
+        "url": "#/plugins/surveys",
+        "section": "#/plugins/surveys"
+      }
+    ],
+    "routes": [
+      {
+        "path": "/plugins/surveys",
+        "view": "plugin-surveys",
+        "title": "Surveys - Domma CMS"
+      },
+      {
+        "path": "/plugins/surveys/new",
+        "view": "plugin-survey-editor",
+        "title": "New Survey - Domma CMS"
+      },
+      {
+        "path": "/plugins/surveys/edit/:slug",
+        "view": "plugin-survey-editor",
+        "title": "Edit Survey - Domma CMS"
+      },
+      {
+        "path": "/plugins/surveys/audience",
+        "view": "plugin-survey-audience",
+        "title": "Survey Audience - Domma CMS"
+      },
+      {
+        "path": "/plugins/surveys/results/:slug",
+        "view": "plugin-survey-results",
+        "title": "Survey Results - Domma CMS"
+      }
+    ],
+    "views": {
+      "plugin-surveys": {
+        "entry": "surveys/admin/views/surveys.js?v=62e94063",
+        "exportName": "surveysView"
+      },
+      "plugin-survey-editor": {
+        "entry": "surveys/admin/views/survey-editor.js?v=322a3ad4",
+        "exportName": "surveyEditorView"
+      },
+      "plugin-survey-audience": {
+        "entry": "surveys/admin/views/audience.js?v=66eea1d5",
+        "exportName": "audienceView"
+      },
+      "plugin-survey-results": {
+        "entry": "surveys/admin/views/results.js?v=13ceda01",
+        "exportName": "resultsView"
+      }
+    }
+  }
+}

package/plugins/surveys/public/dist-shared.mjs

@@ -0,0 +1 @@
+export function renderDistribution(a){return'<div class="survey-dist">'+a.map(s=>`<div class="survey-dist-row"><span class="survey-dist-label">${e(s.label)}</span><span class="survey-dist-bar"><span class="survey-dist-fill" data-pct="${s.pct}" style="width:${s.pct}%"></span></span><span class="survey-dist-val">${s.value} (${s.pct}%)</span></div>`).join("")+"</div>"}function e(a){return String(a??"").replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")}

package/plugins/surveys/public/survey.css

@@ -0,0 +1 @@
+.survey-container{max-width:720px;margin:0 auto;padding:2rem 1rem 4rem}.survey-title{margin-bottom:1.5rem}.survey-code{margin-bottom:1.5rem;padding:1rem 1.25rem;border:1px solid var(--dm-border-color, #d0d0d0);border-radius:var(--dm-radius, 8px);background:var(--dm-surface, #fafafa)}.survey-code label{display:block;margin-bottom:.5rem;font-weight:600}.survey-code-row{display:flex;gap:.5rem;align-items:stretch;flex-wrap:wrap}.survey-code-row input{flex:1 1 200px;padding:.5rem .75rem;border:1px solid var(--dm-border-color, #d0d0d0);border-radius:var(--dm-radius, 6px);font:inherit}.survey-state{padding:1.5rem;border-radius:var(--dm-radius, 8px);text-align:center;font-size:1.05rem;line-height:1.5}.survey-state-success{background:var(--dm-success-bg, #e8f6ec);color:var(--dm-success-text, #1c6b34);border:1px solid var(--dm-success-border, #b6e0c2)}.survey-state-error{background:var(--dm-danger-bg, #fcebec);color:var(--dm-danger-text, #8a1f28);border:1px solid var(--dm-danger-border, #f0bfc4)}.survey-state-info{background:var(--dm-surface, #f4f4f4);color:var(--dm-text-muted, #555);border:1px solid var(--dm-border-color, #d8d8d8)}.survey-dist{display:flex;flex-direction:column;gap:.5rem;margin:.75rem 0}.survey-dist-row{display:grid;grid-template-columns:minmax(80px,30%) 1fr auto;align-items:center;gap:.75rem}.survey-dist-label{font-size:.9rem;color:var(--dm-text, #333);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.survey-dist-bar{position:relative;height:.9rem;background:var(--dm-surface-alt, #ececec);border-radius:var(--dm-radius, 6px);overflow:hidden}.survey-dist-fill{position:absolute;inset:0 auto 0 0;height:100%;background:var(--dm-primary, #3b6ef0);border-radius:inherit;transition:width .3s ease}.survey-dist-val{font-size:.85rem;color:var(--dm-text-muted, #666);min-width:3.5rem;text-align:right}.survey-intro{margin:0 0 1.5rem}.survey-footer{margin:1.5rem 0 0;padding-top:1rem;border-top:1px solid var(--dm-border, #e5e7eb);color:var(--dm-text-muted, #6b7280);font-size:.92rem}.survey-intro:empty,.survey-footer:empty{display:none;border:0;margin:0;padding:0}

package/plugins/surveys/public/survey.mjs

@@ -0,0 +1 @@
+const SKIP_TYPES=new Set(["page-break","spacer","heading","paragraph","html"]);function mapType(e){switch(e){case"textarea":return"textarea";case"select":case"dropdown":return"select";case"radio":return"radio";case"checkbox":case"checkboxes":return"checkbox";case"email":return"email";case"number":return"number";case"date":return"date";case"tel":case"phone":return"tel";default:return"text"}}function buildBlueprint(e){const r={};return(e||[]).forEach(t=>{!t||!t.name||SKIP_TYPES.has(t.type)||(r[t.name]={type:mapType(t.type),label:t.label||t.name,required:!!t.required,options:t.options})}),r}function toast(e,r){typeof E<"u"&&E&&typeof E.toast=="function"&&E.toast(e,{type:r||"info"})}function clear(e){for(;e.firstChild;)e.removeChild(e.firstChild)}function showState(e,r,t){clear(e);const o=document.createElement("div");o.className="survey-state survey-state-"+(t||"info"),o.textContent=r,e.appendChild(o)}async function submitResponse(e,r,t){if(typeof H<"u"&&H&&typeof H.post=="function")return H.post("/api/plugins/surveys/submit/"+e,{token:r,data:t});const o=await fetch("/api/plugins/surveys/submit/"+e,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({token:r,data:t})}),s=await o.json().catch(()=>({}));if(!o.ok){const n=new Error(s.error||"Submission failed");throw n.body=s,n}return s}async function renderForm(e,r,t,o){let s;try{const i=await fetch("/api/forms/"+r+"/public");if(!i.ok)throw new Error("Form not found");s=await i.json()}catch{showState(e,"This survey form could not be loaded.","error");return}const n=s.fields||[],u=s.settings||{},c=buildBlueprint(n),f=async i=>{try{const a=await submitResponse(t,o,i||{});showState(e,a.message||"Thank you for completing this survey.","success"),toast(a.message||"Response recorded","success")}catch(a){const d=a.body&&a.body.error||a.message||"Submission failed";toast(d,"error"),showState(e,d,"error")}};clear(e),typeof Domma<"u"&&Domma.forms&&typeof Domma.forms.render=="function"?Domma.forms.render(e,c,{},{submitText:u.submitText||"Submit",onSubmit:f}):showState(e,"This survey requires JavaScript components that failed to load.","error")}function startMount(e){const r=e.getAttribute("data-survey-slug"),t=e.getAttribute("data-form-slug");if(!r||!t){showState(e,"This survey is misconfigured.","error");return}let s=new URLSearchParams(window.location.search).get("t");if(s){renderForm(e,t,r,s);return}const n=document.getElementById("survey-code");if(!n){showState(e,"Please use the personalised link from your invitation, or enter your code via the survey page.","info");return}n.style.display="",showState(e,"Enter your code above to begin.","info"),n.addEventListener("submit",u=>{u.preventDefault();const c=n.querySelector('[name="code"]');s=c?c.value.trim():"",s&&(n.style.display="none",clear(e),renderForm(e,t,r,s))})}function start(){const e=new Set,r=document.getElementById("survey-mount");r&&e.add(r),document.querySelectorAll(".survey-mount").forEach(t=>e.add(t)),e.forEach(startMount)}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",start):start();

package/plugins/surveys/templates/survey-page.html

@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html lang="en-GB">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>
+    <meta name="robots" content="noindex">
+
+    <!-- DommaJS CSS -->
+    <link rel="stylesheet" href="/dist/domma/domma.css">
+    <link rel="stylesheet" href="/dist/domma/grid.css">
+    <link rel="stylesheet" href="/dist/domma/elements.css">
+    <link rel="stylesheet" href="/dist/domma/themes/domma-themes.css">
+
+    <!-- Site CSS -->
+    <link rel="stylesheet" href="/public/css/site.css">
+    <link rel="stylesheet" href="/public/css/forms.css">
+
+    <!-- Survey CSS -->
+    <link rel="stylesheet" href="/plugins/surveys/public/survey.css">
+</head>
+<body class="dm-cloaked">
+
+    <main class="site-main">
+        <article class="site-content">
+            <div class="container survey-container">
+                <h1 class="survey-title">{{title}}</h1>
+
+                <form id="survey-code" class="survey-code" style="display:none">
+                    <label for="survey-code-input">Enter your code</label>
+                    <div class="survey-code-row">
+                        <input id="survey-code-input" name="code" type="text" placeholder="Enter your code" autocomplete="off">
+                        <button type="submit" class="btn btn-primary">Start</button>
+                    </div>
+                </form>
+
+                <div class="survey-intro">{{intro}}</div>
+
+                <div id="survey-mount" data-survey-slug="{{slug}}" data-form-slug="{{formSlug}}"></div>
+
+                <div class="survey-footer">{{footer}}</div>
+            </div>
+        </article>
+    </main>
+
+    <!-- DOMPurify - must load before DommaJS -->
+    <script src="https://cdn.jsdelivr.net/npm/dompurify@3/dist/purify.min.js"></script>
+
+    <!-- DommaJS -->
+    <script src="/dist/domma/domma.min.js"></script>
+    <script>
+        if (window.Domma && typeof window.Domma.init === 'function') {
+            window.Domma.init();
+        }
+    </script>
+
+    <!-- Core Forms (logic engine must load before renderer) -->
+    <script src="/public/js/form-logic-engine.js"></script>
+
+    <!-- Survey client -->
+    <script type="module" src="/plugins/surveys/public/survey.mjs"></script>
+</body>
+</html>

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();
+}