domma-cms 0.70.1 → 0.72.0

package/plugins/blog/plugin.public.js

@@ -7,19 +7,23 @@
  * over - search, category pills, sort, display switching and a right-click
  * menu - and adds reading progress, contents tracking, sharing and in-page
  * comments to a post.
+ *
+ * The pages are not fixed routes: one onRequest hook matches the path against
+ * the base path as it is saved NOW, so changing it in Settings moves the blog
+ * without a restart. See the Gotchas in CLAUDE.md.
  */
 import path from 'path';
 import {fileURLToPath} from 'url';
 import {renderBlogPage} from '../../server/services/renderer.js';
-import {byNewest, escapeHtml, pickDisplay, safeImageUrl} from './lib/layouts.js';
+import {byNewest, escapeHtml, matchBlogPath, pickDisplay, safeImageUrl} from './lib/layouts.js';
 import {catalogue, renderCards} from './lib/render.js';
-import {authorNamesFor, isVisible, liveSettings, loadEntries, renderPostPage, resolveAuthorName} from './lib/page.js';
+import {authorNamesFor, isVisible, liveBase, liveSettings, loadEntries, renderPostPage, resolveAuthorName} from './lib/page.js';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const TEMPLATES_DIR = path.join(__dirname, 'templates');
 
 /** Bumped with the plugin, so a release is never served a stale script. */
-const ASSET_V = '1.6.0';
+const ASSET_V = '1.6.3';
 
 /**
  * Above this many posts a listing pages on the server instead: the browser
@@ -56,7 +60,6 @@ function scriptJson(value) {
 
 export default async function blogPublicPlugin(fastify, options) {
     const {settings, config} = options;
-    const base = (settings?.basePath ?? '/blog').replace(/\/$/, '');
 
     /**
      * A listing: the index, a page of it, or a category / tag / author archive.
@@ -64,9 +67,9 @@ export default async function blogPublicPlugin(fastify, options) {
      * @param {object}   request
      * @param {object}   reply
      * @param {object[]} posts   - candidates; drafts are dropped here
-     * @param {object}   opts    - {title, intro, page, pageBase, filter}
+     * @param {object}   opts    - {base, title, intro, page, filter}
      */
-    async function renderArchive(request, reply, posts, {title, intro = '', page = 1, pageBase = base, filter = null}) {
+    async function renderArchive(request, reply, posts, {base, title, intro = '', page = 1, filter = null}) {
         const s = liveSettings(settings);
         const perPage = Math.max(1, Number(s.postsPerPage) || 10);
         const {listDisplays} = await catalogue();
@@ -115,7 +118,7 @@ ${items || ''}
                 archiveTitle: escapeHtml(title),
                 archiveIntro: intro ? `<p class="blog-archive-intro">${escapeHtml(intro)}</p>` : '',
                 archive,
-                pagination: interactive ? '' : buildPagination(safePage, totalPages, pageBase, requested),
+                pagination: interactive ? '' : buildPagination(safePage, totalPages, base, requested),
                 assetV: ASSET_V
             },
             {title, urlPath: request.url.split('?')[0]}
@@ -123,16 +126,18 @@ ${items || ''}
         return reply.type('text/html').send(html);
     }
 
-    // 1. RSS feed
-    fastify.get(`${base}/feed.xml`, async (request, reply) => {
-        const s = liveSettings(settings);
-        const allPosts = await loadEntries('blog-posts');
-        const posts = allPosts.filter(isVisible).sort(byNewest).slice(0, s.feedLength ?? 20);
+    /** One handler per page; `matchBlogPath()` (lib/layouts.js) picks which. */
+    const pages = {
+        /** RSS feed */
+        async feed(request, reply, params, base) {
+            const s = liveSettings(settings);
+            const allPosts = await loadEntries('blog-posts');
+            const posts = allPosts.filter(isVisible).sort(byNewest).slice(0, s.feedLength ?? 20);
 
-        const siteTitle = config?.site?.title ?? 'Blog';
-        const siteUrl = (config?.site?.url ?? '').replace(/\/$/, '');
+            const siteTitle = config?.site?.title ?? 'Blog';
+            const siteUrl = (config?.site?.url ?? '').replace(/\/$/, '');
 
-        const items = posts.map((post) => `  <item>
+            const items = posts.map((post) => `  <item>
     <title>${escapeHtml(post.title)}</title>
     <link>${siteUrl}${base}/${escapeHtml(post.slug)}</link>
     <description>${escapeHtml(post.excerpt || '')}</description>
@@ -140,7 +145,7 @@ ${items || ''}
     <guid>${siteUrl}${base}/${escapeHtml(post.slug)}</guid>
   </item>`).join('\n');
 
-        return reply.type('application/xml').send(`<?xml version="1.0" encoding="UTF-8"?>
+            return reply.type('application/xml').send(`<?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0">
   <channel>
     <title>${escapeHtml(siteTitle)}</title>
@@ -149,69 +154,86 @@ ${items || ''}
 ${items}
   </channel>
 </rss>`);
+        },
+
+        /** Paginated index */
+        async page(request, reply, {n}, base) {
+            const page = parseInt(n, 10) || 1;
+            return renderArchive(request, reply, await loadEntries('blog-posts'), {base, title: 'Blog', page});
+        },
+
+        /** Category archive */
+        async category(request, reply, {slug}, base) {
+            const [allPosts, allCategories] = await Promise.all([loadEntries('blog-posts'), loadEntries('blog-categories')]);
+            const category = allCategories.find((c) => c.slug === slug);
+            if (!category) return reply.code(404).send('Category not found');
+            const posts = allPosts.filter((p) => Array.isArray(p.categories) && p.categories.includes(category.id));
+            return renderArchive(request, reply, posts, {
+                base, title: category.name, intro: category.description || '', filter: {type: 'category', value: category.slug}
+            });
+        },
+
+        /** Tag archive */
+        async tag(request, reply, {tag}, base) {
+            const posts = (await loadEntries('blog-posts')).filter((p) => Array.isArray(p.tags) && p.tags.includes(tag));
+            return renderArchive(request, reply, posts, {base, title: `#${tag}`, filter: {type: 'tag', value: tag}});
+        },
+
+        /** Author archive */
+        async author(request, reply, {id}, base) {
+            const posts = (await loadEntries('blog-posts')).filter((p) => p.authorId === id);
+            const authorName = await resolveAuthorName(id);
+            return renderArchive(request, reply, posts, {base, title: `Posts by ${authorName}`, filter: {type: 'author', value: id}});
+        },
+
+        /** Blog index */
+        async index(request, reply, params, base) {
+            return renderArchive(request, reply, await loadEntries('blog-posts'), {base, title: 'Blog'});
+        },
+
+        /** `{base}/` - the index, rather than a post with an empty slug */
+        async slash(request, reply, params, base) {
+            const query = request.url.includes('?') ? request.url.slice(request.url.indexOf('?')) : '';
+            return reply.redirect(`${base}${query}`, 301);
+        },
+
+        /** Individual post */
+        async post(request, reply, {slug}, base) {
+            const allPosts = await loadEntries('blog-posts');
+            const post = allPosts.find((p) => p.slug === slug);
+            if (!post || !isVisible(post)) return reply.code(404).send('Not found');
+
+            const siteUrl = (config?.site?.url || `${request.protocol}://${request.hostname}`).replace(/\/$/, '');
+            const page = await renderPostPage(post, allPosts, liveSettings(settings), {base, siteUrl});
+
+            const html = await renderBlogPage(
+                path.join(TEMPLATES_DIR, 'post.html'),
+                {post: page.html, assetV: ASSET_V},
+                {
+                    title: post.seo?.title || post.title,
+                    description: post.seo?.description || post.excerpt || '',
+                    ogImage: safeImageUrl(post.featuredImage),
+                    ogType: 'article',
+                    usedComponents: page.usedComponents,
+                    urlPath: `${base}/${slug}`
+                }
+            );
+            return reply.type('text/html').send(html);
+        }
+    };
+
+    // Answered here, ahead of routing, because routes are fixed at boot and the
+    // base path is not. The hook is global (skip-override, below); it answers
+    // only what matchBlogPath() claims and lets everything else through.
+    fastify.addHook('onRequest', async (request, reply) => {
+        if (request.method !== 'GET' && request.method !== 'HEAD') return;
+        const base = liveBase(settings);
+        const hit = matchBlogPath(request.url.split('?')[0], base);
+        if (!hit) return;
+        return pages[hit.name](request, reply, hit.params, base);
     });
-
-    // 2. Paginated index
-    fastify.get(`${base}/page/:n`, async (request, reply) => {
-        const page = parseInt(request.params.n, 10) || 1;
-        return renderArchive(request, reply, await loadEntries('blog-posts'), {title: 'Blog', page});
-    });
-
-    // 3. Category archive
-    fastify.get(`${base}/category/:slug`, async (request, reply) => {
-        const {slug} = request.params;
-        const [allPosts, allCategories] = await Promise.all([loadEntries('blog-posts'), loadEntries('blog-categories')]);
-        const category = allCategories.find((c) => c.slug === slug);
-        if (!category) return reply.code(404).send('Category not found');
-        const posts = allPosts.filter((p) => Array.isArray(p.categories) && p.categories.includes(category.id));
-        return renderArchive(request, reply, posts, {
-            title: category.name, intro: category.description || '', filter: {type: 'category', value: category.slug}
-        });
-    });
-
-    // 4. Tag archive
-    fastify.get(`${base}/tag/:tag`, async (request, reply) => {
-        const {tag} = request.params;
-        const posts = (await loadEntries('blog-posts')).filter((p) => Array.isArray(p.tags) && p.tags.includes(tag));
-        return renderArchive(request, reply, posts, {title: `#${tag}`, filter: {type: 'tag', value: tag}});
-    });
-
-    // 5. Author archive
-    fastify.get(`${base}/author/:id`, async (request, reply) => {
-        const {id} = request.params;
-        const posts = (await loadEntries('blog-posts')).filter((p) => p.authorId === id);
-        const authorName = await resolveAuthorName(id);
-        return renderArchive(request, reply, posts, {title: `Posts by ${authorName}`, filter: {type: 'author', value: id}});
-    });
-
-    // 6. Blog index
-    fastify.get(base, async (request, reply) => {
-        return renderArchive(request, reply, await loadEntries('blog-posts'), {title: 'Blog'});
-    });
-
-    // 7. Individual post - registered LAST so the slug match doesn't shadow archives
-    fastify.get(`${base}/:slug`, async (request, reply) => {
-        const {slug} = request.params;
-        const allPosts = await loadEntries('blog-posts');
-        const post = allPosts.find((p) => p.slug === slug);
-        if (!post || !isVisible(post)) return reply.code(404).send('Not found');
-
-        const siteUrl = (config?.site?.url || `${request.protocol}://${request.hostname}`).replace(/\/$/, '');
-        const page = await renderPostPage(post, allPosts, liveSettings(settings), {base, siteUrl});
-
-        const html = await renderBlogPage(
-            path.join(TEMPLATES_DIR, 'post.html'),
-            {post: page.html, assetV: ASSET_V},
-            {
-                title: post.seo?.title || post.title,
-                description: post.seo?.description || post.excerpt || '',
-                ogImage: safeImageUrl(post.featuredImage),
-                ogType: 'article',
-                usedComponents: page.usedComponents,
-                urlPath: `${base}/${slug}`
-            }
-        );
-        return reply.type('text/html').send(html);
-    });
-
 }
+
+// What fastify-plugin sets: the onRequest hook must see every request, not only
+// routes registered inside this plugin (it registers none).
+blogPublicPlugin[Symbol.for('skip-override')] = true;

package/plugins/blog/tests/layouts.test.js

@@ -95,3 +95,32 @@ test('related posts: shared categories outweigh shared tags; newer breaks a tie'
     assert.deepEqual(relatedPosts(me, all, 3).map(p => p.id), ['cat-new', 'cat-old', 'tag-only']);
     assert.deepEqual(relatedPosts(me, all, 0), []);
 });
+
+test('a base path is tidied, and never the whole site', async () => {
+    const {cleanBasePath} = await import('../lib/layouts.js');
+    assert.equal(cleanBasePath('/news'), '/news');
+    assert.equal(cleanBasePath('news/'), '/news');
+    assert.equal(cleanBasePath('//a//b/'), '/a/b');
+    assert.equal(cleanBasePath('/x?y=1'), '/x');
+    for (const v of ['', '/', ' ', null, undefined]) assert.equal(cleanBasePath(v), '/blog', String(v));
+});
+
+test('matchBlogPath claims the blog\'s pages under whatever base it is given', async () => {
+    const {matchBlogPath} = await import('../lib/layouts.js');
+    assert.deepEqual(matchBlogPath('/news', '/news'), {name: 'index', params: {}});
+    assert.deepEqual(matchBlogPath('/news/', '/news'), {name: 'slash', params: {}});
+    assert.deepEqual(matchBlogPath('/news/feed.xml', '/news'), {name: 'feed', params: {}});
+    assert.deepEqual(matchBlogPath('/news/page/2', '/news'), {name: 'page', params: {n: '2'}});
+    assert.deepEqual(matchBlogPath('/news/category/a%20b', '/news'), {name: 'category', params: {slug: 'a b'}});
+    assert.deepEqual(matchBlogPath('/news/tag/x', '/news'), {name: 'tag', params: {tag: 'x'}});
+    assert.deepEqual(matchBlogPath('/news/author/7', '/news'), {name: 'author', params: {id: '7'}});
+    assert.deepEqual(matchBlogPath('/news/my-post', '/news'), {name: 'post', params: {slug: 'my-post'}});
+    for (const p of ['/blog', '/newsroom', '/news/a/b', '/news/page/', '/news/%E0%A4%A']) assert.equal(matchBlogPath(p, '/news'), null, p);
+});
+
+test('a post Blog Pro filed under another blog is not shown by this one', async () => {
+    const {isVisible} = await import('../lib/page.js');
+    assert.equal(isVisible({status: 'published'}), true);
+    assert.equal(isVisible({status: 'published', blogId: 'main'}), true);
+    assert.equal(isVisible({status: 'published', blogId: 'travel'}), false);
+});

package/plugins/blog/tests/nav-link.test.js

@@ -1,6 +1,6 @@
 import {test} from 'node:test';
 import assert from 'node:assert/strict';
-import {addNavLink, blogItem, hasLink, removeNavLink, withoutLink} from '../lib/nav-link.js';
+import {addNavLink, blogItem, hasLink, moveNavLink, removeNavLink, withoutLink} from '../lib/nav-link.js';
 
 function fakeMenus(items, locations = {navbar: 'main'}) {
     const store = {main: {slug: 'main', name: 'Main', items}};
@@ -55,3 +55,12 @@ test('no navbar menu mapped: nothing happens', async () => {
     assert.equal(await addNavLink('/blog', menus), null);
     assert.deepEqual(withoutLink([{text: 'A', url: '/a'}], '/blog'), [{text: 'A', url: '/a'}]);
 });
+
+test('a new base path moves the link enabling added, and nothing else', async () => {
+    const menus = fakeMenus([{text: 'Home', url: '/'}, {text: 'Blog', url: '/blog'}, {text: 'More', url: '#', items: [{text: 'Old', url: '/blog'}]}]);
+    assert.equal(await moveNavLink({menu: 'main', url: '/blog'}, '/news/', menus), true);
+    assert.deepEqual(menus.store.main.items.map(i => i.url), ['/', '/news', '#']);
+    assert.equal(menus.store.main.items[2].items[0].url, '/blog', 'a nested copy is the site\'s own');
+    assert.equal(await moveNavLink({menu: 'main', url: '/gone'}, '/x', menus), false);
+    assert.equal(await moveNavLink(null, '/x', menus), false);
+});

package/plugins/blog/tests/public.test.js

@@ -69,3 +69,24 @@ test('a post keeps only the fields it has - no authorship, no sample flag, a val
     assert.equal(postFields({template: '../../etc/passwd'}, {role: 'admin'}).template, '');
     assert.equal(postFields({template: ''}, {role: 'admin'}).template, '', 'empty is "use the site default"');
 });
+
+test('/blog/ goes to the index, not the post route with an empty slug', async () => {
+    const app = await buildPublic();
+    const res = await app.inject({method: 'GET', url: '/blog/?display=list'});
+    assert.equal(res.statusCode, 301);
+    assert.equal(res.headers.location, '/blog?display=list');
+});
+
+test('the pages live at the base path in the settings, not a fixed /blog', async () => {
+    const app = Fastify();
+    await app.register(blogPublicPlugin, {settings: {basePath: '/news'}, config: {}});
+    app.get('/*', async () => 'site page');
+    const index = await app.inject({method: 'GET', url: '/news'});
+    assert.equal(index.statusCode, 200);
+    assert.match(index.body, /data-blog-archive/);
+    assert.equal((await app.inject({method: 'GET', url: '/news/'})).headers.location, '/news');
+    assert.equal((await app.inject({method: 'GET', url: '/news/feed.xml'})).statusCode, 200);
+    const other = await app.inject({method: 'GET', url: '/blog'});
+    assert.equal(other.body, 'site page', 'the old path is the site\'s again');
+    assert.equal((await app.inject({method: 'POST', url: '/news'})).statusCode, 404, 'GET only');
+});

package/plugins/free-tier.lock.json

@@ -1,11 +1,11 @@
 {
   "note": "Written by `make sync-free-tier` in dcms-marketplace. Do not edit these plugins here - edit them there and sync.",
-  "source": "dcms-marketplace@cb07e46",
+  "source": "dcms-marketplace@d9bfe49",
   "plugins": {
     "blog": {
-      "version": "1.6.0",
+      "version": "1.6.3",
       "files": {
-        "CLAUDE.md": "155f6e6e09531b8ab87252f942c1c75121a6c10abdebc4316fa7da44edb42642",
+        "CLAUDE.md": "63b11d562db0e0003b929320f55f2a6dedf6ba98a20ed6f5c768fa3177286de9",
         "admin/css/index.css": "6142a6b756e1218157842528830b1e84f592f0b84b7d5ce6449db421b6f4b039",
         "admin/templates/blog.html": "a6054c1febe764bb1edf5c9e466d44a9080d9c83ba5486437b7a8244acf5ba54",
         "admin/templates/categories.html": "ab7d6fc2fedd48876c585bc216a1532b3bdd78c946dee976c1171bfe4664feb6",
@@ -15,7 +15,7 @@
         "admin/views/blog.js": "3fc84f7ea9fce352f150771b4d1f775965592a8690ad7fd1110a3a4e72c49c74",
         "admin/views/categories.js": "75140feb2b382ba0ab4a52c30007845bf576883c99577fc0965783adb8808f6b",
         "admin/views/comments.js": "7c93f964560b5b02df270bd17526b8f749cc7c8871a9e863bb84e9cbfbc4da0e",
-        "admin/views/kit.js": "e7a787836090f622d7108f2e31a041bfedd0aa6ffb9c9d0b341daa2640e13e2e",
+        "admin/views/kit.js": "91292d63a96c1d1e9fdc0c8f931d0f31e07fa37d06f06e0fc45b308863e126aa",
         "admin/views/post-editor.js": "6bb0867d3b57d817497115e5c56479332f2a5324ab99aab2fdabc714c888c543",
         "admin/views/settings-cog.js": "307efc93835863dd8511f8fb17a224cf45a77532c90b854a86d2cd1d4e5f9f18",
         "admin/views/settings.js": "2b7f775e37e034dee4ae3dfadea5e446c2e526bed8a066ef3ca2e777146ada23",
@@ -41,14 +41,14 @@
         "collections/comments/schema.json": "29cbd289cbfcfc4158c9357a218db4ce06eddc3370bfbf9afb7d7f52065a849e",
         "collections/posts/schema.json": "19a5a770d3eefea73f4117454bd1312a7a7e3d727cfcdfde141139fbc81cabd7",
         "config.js": "ee67396262762f5c31269d258affd75f7392a3e364f72f7792c2f1cdafd94bba",
-        "lib/layouts.js": "5b3c22cfdd537777418d3d22ce86ba522576c0101e7d51ea0db9b2667caf1f92",
-        "lib/nav-link.js": "ab68e4f5d86665834d95f845bb9755ee3a7019089be3452571054f4a49befbbb",
-        "lib/page.js": "1fb9a01c3080e8ecf65c19b1273b23d550a131fe30079a493a9f5b1c90b720ae",
+        "lib/layouts.js": "bbb61ac7ec2e0cecd3d59700e9f3bd1064cd53b2e9f639d28b45ffc2ad80ab27",
+        "lib/nav-link.js": "6a8f9368bb8aee1c21e90fb335a691859cb9a9bc250c2b9167a33ca9189fa2ff",
+        "lib/page.js": "464face32871185368de096ed9a6aa635523bf319af6459308cfceb77d66f82c",
         "lib/render.js": "0e97c6a950bc962c8d8ea4b2f21d06cb73fbcdc738d8942d6935d01309a29b1d",
         "lib/samples.js": "e8cdb77ce22e43937707f6854d3a5cb722437dc584e22ac7b24480bef686cf85",
-        "plugin.js": "9e49e3b1d4844cf5ec33abf350ca9cd38e8efa4b93be2c628842a923033350cf",
-        "plugin.json": "20603ae07a6dade8f6fef14539e3b629c7c0c07dea8322834a4827f86dcf204e",
-        "plugin.public.js": "c338fff588ab7bd02baf1bc6d5a729a0f0d2ecfa90c087cadfd792ba4d3fd9c2",
+        "plugin.js": "ccfd8735838bb6c8c5d45c3c3589d6adcf114a89b560f66e93a1077e9bea3bfb",
+        "plugin.json": "5654242b0fd5d4f6039a87dc429bd69a24355a59c3409be10998410fbe6d019b",
+        "plugin.public.js": "8efc1ff3a2ead68d36fbd545f8ce590f600b293896ba6f4947418b1efcdf2947",
         "public/blog.css": "fd733e6b624190da1e70dc1b6613e2376efd7f7570a28fab311d81006d03d960",
         "public/blog.js": "d01c72a9834dcc7c5241923371f2b164ac30d20ac9f1a5c5dc5b71fa3cb09f08",
         "public/samples/aurora.svg": "feb29e2b46465913fc29de9eda221b00b1541f1fa3ea7120f0c1d1cd11a9a4f6",
@@ -61,9 +61,9 @@
         "roles/blog-editor.json": "bea0b673cf9e3da04c5882d51dd33bdcaf035b047c1cfe87624a9f16e6514ffc",
         "templates/index.html": "3c2cf8a4ffde8599d451f6d00b736aeba42fd073b726ada3b0ffe4d56e1ef0f4",
         "templates/post.html": "28e9f06071115ecc4fbba007b35782732bf12ef72528525893d424e3c4f0313f",
-        "tests/layouts.test.js": "f6dc1ac17b1d4841accd673ab34cc127aa2ccdbca453ef1cee8dbb7a637669a6",
-        "tests/nav-link.test.js": "d25a2ec7948df4b042c402e8c5f2cacb2be4743edba48d497a6b67a0ca1fdd5a",
-        "tests/public.test.js": "ef04ba271d03cee86adac332c6834bb51102b20d892d5f84d30eb04507605de5"
+        "tests/layouts.test.js": "5325aad79a153f1d17f49b27223f50be182a2acce8ee8be7da658ae92ae36fe8",
+        "tests/nav-link.test.js": "d36e33ad7483abca27ae6e2098ad2f75bafa18d91f3beba70372ebe6b9b88994",
+        "tests/public.test.js": "0049a6be16c6a8acb44d53ea885909c80563a0afaa3e1e89d3c54d5429feed98"
       }
     },
     "mail-reader": {

package/server/middleware/auth.js

@@ -159,6 +159,13 @@ export function canManageUser(actor, target) {
  * lets both roles in, plus anyone more privileged than either (typically
  * admins inherit access automatically via the level comparison).
  *
+ * Exact tokens: a role name prefixed with `=` (`=candidate`) skips the
+ * hierarchy and passes only for users who HOLD that role, primary or
+ * additional. That is the only way to keep two roles on the same level (or
+ * a lower-privilege role and a higher one) out of each other's pages and menu
+ * items. The root role (level 0) still passes, as it does for 'private'.
+ * Exact and hierarchical tokens mix freely in an array.
+ *
  * @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
@@ -194,12 +201,26 @@ export function checkVisibility(userRoleOrObj, visibility) {
  * @returns {boolean}
  */
 function checkSingleVisibility(userRole, visibility) {
+    const exact = parseExactVisibility(visibility);
+    if (exact) return userRole === exact || getRoleLevel(userRole) === 0;
     const userLevel     = getRoleLevel(userRole);
     const requiredLevel = getRoleLevel(visibility);
     const threshold     = requiredLevel === Infinity ? 0 : requiredLevel;
     return userLevel <= threshold;
 }
 
+/**
+ * The role an exact visibility token names, or null for any other token.
+ * `=candidate` → 'candidate'; `candidate`, `public`, `=` → null.
+ *
+ * @param {*} token
+ * @returns {string|null}
+ */
+export function parseExactVisibility(token) {
+    if (typeof token !== 'string' || token.length < 2 || token[0] !== '=') return null;
+    return token.slice(1);
+}
+
 /**
  * Fastify preHandler factory - gates a route by visibility level.
  * Works identically to the content-page visibility system; accepts the same

package/server/routes/api/auth.js

@@ -9,10 +9,13 @@
  */
 import crypto from 'node:crypto';
 import {config, getConfig} from '../../config.js';
-import {hooks} from '../../services/hooks.js';
-import {authenticate, getPermissionsForRole} from '../../middleware/auth.js';
-import {getRoleLevel} from '../../services/roles.js';
-import {GROUP_ORDER, REGISTRY} from '../../services/permissionRegistry.js';
+import {getRegisteredSidebarItems, hooks} from '../../services/hooks.js';
+import {getMenu} from '../../services/menus.js';
+import {resolveAdminHome} from '../../services/adminHome.js';
+import {authenticate, checkVisibility} from '../../middleware/auth.js';
+import {getAdminScope, getPermissionsForRoles, getRoleLevel} from '../../services/roles.js';
+import {getEffectiveRegistry, GROUP_ORDER} from '../../services/permissionRegistry.js';
+import {getEffectiveRoles} from '../../services/userRoles.js';
 import {
     clearResetToken,
     countUsers,
@@ -118,13 +121,31 @@ export async function authRoutes(fastify) {
 
     // GET /api/auth/permissions - returns the raw permissions array for the authenticated user's role
     fastify.get('/auth/permissions', {preHandler: [authenticate]}, async (request) => {
-        const permissions = getPermissionsForRole(request.user.role);
-        return {permissions};
+        // Every role the user holds, not just the primary one - the server
+        // grants on the union, so the sidebar must hide on the union too.
+        const roles = getEffectiveRoles(request.user);
+        const allResources = getEffectiveRegistry().map(r => r.key);
+        const permissions = getPermissionsForRoles(roles, allResources);
+        // adminScope: null = the whole admin; otherwise {home, allow} - the
+        // screens this user's roles confine them to (see roles.getAdminScope).
+        const adminScope = getAdminScope(roles);
+        // adminHome: the screen `#/` opens for this user - see services/adminHome.js.
+        // The menu is read only when a site home has to be checked against it.
+        const adminHome = await resolveAdminHome({
+            scope: adminScope,
+            permissions,
+            siteHome: getConfig('site')?.adminHome,
+            registered: () => getRegisteredSidebarItems().map(e => e.item),
+            menuItems: async () => (await getMenu('admin-sidebar').catch(() => null))?.items || [],
+            canSee: (visibility) => checkVisibility(request.user, visibility)
+        });
+        return {permissions, adminScope, adminHome};
     });
 
-    // GET /api/auth/permissions-registry - returns the full permissions registry
+    // GET /api/auth/permissions-registry - returns the full permissions registry,
+    // including resources plugins registered, so the role editor can grant them.
     fastify.get('/auth/permissions-registry', {preHandler: [authenticate]}, async () => {
-        return {groups: GROUP_ORDER, resources: REGISTRY};
+        return {groups: GROUP_ORDER, resources: getEffectiveRegistry()};
     });
 
     // GET /api/auth/me

package/server/routes/api/collections.js

@@ -202,6 +202,29 @@ export async function checkPublicAccess(schema, operation, request, reply) {
     }
 }
 
+/**
+ * Role fields the system owns, not the editor: `plugin` says which plugin owns
+ * the role (hooks.unregisterRole and uninstall key off it) and `grantedBy`
+ * records one-time plugin grants. Clients send whole records, so without this
+ * any save from the role editor silently erased both - the role stopped
+ * belonging to its plugin and revoked grants came back on the next boot.
+ * Whatever the client sent for them is ignored in favour of what is stored.
+ *
+ * @param {string} id
+ * @param {object} data
+ * @returns {Promise<object>}
+ */
+const ROLE_SYSTEM_FIELDS = ['plugin', 'grantedBy'];
+async function keepRoleSystemFields(id, data) {
+    const existing = (await getEntry('roles', id))?.data || {};
+    const out = {...data};
+    for (const field of ROLE_SYSTEM_FIELDS) {
+        if (existing[field] !== undefined) out[field] = existing[field];
+        else delete out[field];
+    }
+    return out;
+}
+
 export async function collectionsRoutes(fastify) {
     const canRead = {preHandler: [authenticate, requirePermission('collections', 'read')]};
     const canCreate = {preHandler: [authenticate, requirePermission('collections', 'create')]};
@@ -347,7 +370,13 @@ export async function collectionsRoutes(fastify) {
     fastify.post('/collections/:slug/entries', canCreate, async (request, reply) => {
         const user = request.user;
         try {
-            const entry = await createEntry(request.params.slug, request.body?.data || {}, {
+            let data = request.body?.data || {};
+            // A role created in the admin belongs to no plugin; see keepRoleSystemFields.
+            if (request.params.slug === 'roles') {
+                data = {...data};
+                ROLE_SYSTEM_FIELDS.forEach(field => delete data[field]);
+            }
+            const entry = await createEntry(request.params.slug, data, {
                 createdBy: user?.id || null,
                 source:    'admin'
             });
@@ -395,7 +424,9 @@ export async function collectionsRoutes(fastify) {
 
     fastify.put('/collections/:slug/entries/:id', canUpdate, async (request, reply) => {
         try {
-            const entry = await updateEntry(request.params.slug, request.params.id, request.body?.data || {});
+            let data = request.body?.data || {};
+            if (request.params.slug === 'roles') data = await keepRoleSystemFields(request.params.id, data);
+            const entry = await updateEntry(request.params.slug, request.params.id, data);
             if (request.params.slug === 'roles') await invalidateRoles();
             hooks.emit('collection:entryUpdated', { slug: request.params.slug, entryId: entry.id, data: entry.data, userId: request.user?.id || null });
             return entry;
@@ -701,7 +732,13 @@ export async function collectionsRoutes(fastify) {
         if (denied !== undefined) return;
 
         try {
-            const entry = await createEntry(request.params.slug, request.body?.data || {}, {
+            let data = request.body?.data || {};
+            // A role created in the admin belongs to no plugin; see keepRoleSystemFields.
+            if (request.params.slug === 'roles') {
+                data = {...data};
+                ROLE_SYSTEM_FIELDS.forEach(field => delete data[field]);
+            }
+            const entry = await createEntry(request.params.slug, data, {
                 createdBy: request.apiToken ? `token:${request.apiToken.id}` : (request.user?.id || null),
                 source:    'api'
             });

package/server/routes/api/settings.js

@@ -11,6 +11,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import {fileURLToPath} from 'url';
 import * as cache from '../../services/cache/index.js';
+import {normaliseAdminPath} from '../../services/roles.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CUSTOM_CSS_FILE = path.resolve(__dirname, '../../../content/custom.css');
@@ -41,6 +42,8 @@ export async function settingsRoutes(fastify) {
             'smtp', 'footer', 'analytics', 'social', 'locale',
             'layoutOptions', 'seo', 'backToTop', 'cookieConsent', 'breadcrumbs', 'autoTheme',
             'adminBrand',
+            // The screen `#/` (Dashboard) opens - see services/adminHome.js.
+            'adminHome',
             // Keys that legitimately live in site.json (written elsewhere - e.g.
             // `brand` by the menus migration) and are echoed back by GET /settings.
             // They must be accepted here or any client that round-trips the GET
@@ -51,6 +54,12 @@ export async function settingsRoutes(fastify) {
         if (unknownKeys.length > 0) {
             return reply.status(400).send({ error: `Unknown settings keys: ${unknownKeys.join(', ')}` });
         }
+        if ('adminHome' in data) {
+            // An admin route, or blank for the built-in dashboard.
+            const home = data.adminHome == null || data.adminHome === '' ? '/' : normaliseAdminPath(data.adminHome);
+            if (!home) return reply.status(400).send({error: 'adminHome must be an admin route such as /plugins/blog'});
+            data.adminHome = home;
+        }
         // Merge incoming data with existing config so partial updates (e.g. just adminBrand)
         // don't wipe unrelated keys. Nested objects get a shallow merge so sub-fields are
         // preserved even when only some sub-fields are sent.

package/server/routes/api/sidebar.js

@@ -1,23 +1,44 @@
 /**
  * Admin sidebar API
  *
- * GET /api/sidebar/registered-items - plugin-registered sidebar items
+ * GET /api/sidebar/menu             - the admin-sidebar menu, filtered for the caller
+ * GET /api/sidebar/registered-items - plugin-registered sidebar items, filtered for the caller
+ *
+ * Both need only a signed-in user, NOT `menus.read`: every user who can reach
+ * the admin needs a sidebar, and a role without menu-editing rights (a
+ * `candidate`, say) used to get a 403 here and fall back to a hardcoded tree
+ * holding a Menus link they could not open. Items gated by `visibility` are
+ * dropped on the server, the same way the public navbar drops them; items
+ * gated by `permission`, and `hidden` items, are dropped by the renderer - it
+ * needs the hidden ones to know which Tools a menu has hidden.
  *
  * 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 {authenticate as defaultAuthenticate, checkVisibility} from '../../middleware/auth.js';
 import {getRegisteredSidebarItems} from '../../services/hooks.js';
+import {filterItemsForUser, getMenu} from '../../services/menus.js';
+
+export const ADMIN_SIDEBAR_SLUG = 'admin-sidebar';
 
 export async function sidebarRoutes(fastify, opts = {}) {
-    const authenticate      = opts.authenticate      || defaultAuthenticate;
-    const requirePermission = opts.requirePermission || defaultRequirePermission;
+    const authenticate = opts.authenticate || defaultAuthenticate;
+    const signedIn     = {preHandler: [authenticate]};
 
-    const canRead = {preHandler: [authenticate, requirePermission('menus', 'read')]};
+    fastify.get('/sidebar/menu', signedIn, async (request) => {
+        const menu = await getMenu(ADMIN_SIDEBAR_SLUG);
+        if (!menu) return {items: []};
+        // Hidden items are kept: they are how a menu hides a Tool, and the
+        // renderer needs them to place Tools before it drops them. An item
+        // this user may not see (`visibility`) arrives as a label-less hidden
+        // stub for the same reason - see restrictedStub() in menus.js.
+        return {...menu, items: filterItemsForUser(menu.items || [], request.user, {keepHidden: true})};
+    });
 
-    fastify.get('/sidebar/registered-items', canRead, async () => {
-        return getRegisteredSidebarItems();
+    fastify.get('/sidebar/registered-items', signedIn, async (request) => {
+        return getRegisteredSidebarItems()
+            .filter(entry => !entry?.item?.hidden && checkVisibility(request.user, entry?.item?.visibility))
+            .map(entry => Array.isArray(entry.item?.items)
+                ? {...entry, item: {...entry.item, items: filterItemsForUser(entry.item.items, request.user)}}
+                : entry);
     });
 }