domma-cms 0.116.8 → 0.117.0

package/server/routes/api/content-public.js

@@ -0,0 +1,299 @@
+/**
+ * Content API - /api/content/v1
+ *
+ * Read-only headless access to what the site publishes:
+ *
+ * GET /api/content/v1/pages            - paged page summaries
+ * GET /api/content/v1/pages/*          - one page (?format=html|markdown|both)
+ * GET /api/content/v1/menus/:location  - the menu bound to a location, filtered for the caller
+ * GET /api/content/v1/site             - the site settings public pages already show
+ * GET /api/content/v1/search?q=        - site search
+ *
+ * Its own prefix on purpose: /api/v1/:slug matches any collection slug, and
+ * slugify() happily produces `pages` and `menus`, so living there would
+ * shadow real collections.
+ *
+ * Access is config/content-api.json `access`:
+ *   - 'public' - anyone
+ *   - 'token'  - a project API token, strict (never a JWT), bound to the
+ *                page's project, narrowed by `{content}` scopes
+ *   - a role   - a Bearer access JWT at that role's level or more senior; an
+ *                unknown role admits level 0 only. Never the dm_session
+ *                cookie: that is read only by the page renderer, so no
+ *                API answers to ambient credentials.
+ * Public and token callers are served as an anonymous visitor.
+ *
+ * Every page decision is resolvePublishedPage() - the function the public
+ * site uses - so the two can never disagree.
+ */
+import {getContentApiSettings, pageDetail, pageSummary, publicSiteSettings} from '../../services/contentApi.js';
+import {canPreviewDrafts, resolvePublishedPage} from '../../services/pagePublishing.js';
+import {getPage, getPageMtime, listPages} from '../../services/content.js';
+import {getSearchSettings, isPubliclyListed, searchExclusions, searchPages} from '../../services/search.js';
+import {resolveLocation} from '../../services/menus.js';
+import {authenticateApiToken, contentScopeAllows} from '../../services/apiTokens.js';
+import {getRoleLevel} from '../../services/roles.js';
+import {getEffectiveLevel} from '../../services/userRoles.js';
+import {getConfig} from '../../config.js';
+
+const NOT_FOUND = {error: 'Not found'};
+const DEFAULT_LIMIT = 50;
+const FORMAT_VALUES = ['html', 'markdown', 'both'];
+
+/** Menu slots the API never serves: the admin's own navigation, and page overlays. */
+const PRIVATE_SLOTS = new Set(['admin-sidebar', 'overlay']);
+
+/**
+ * Gate one request. Resolves to `{mode, viewer, token, settings}`, or sends
+ * the refusal and resolves to null.
+ *
+ * Token mode binds no project here: pages carry their own, so the routes
+ * check `inProject()` per page. Menus and site settings are site-wide and
+ * already shown on every public page, so any valid token may read them.
+ *
+ * @param {'pages'|'menus'|'site'|'search'} resource
+ * @returns {Promise<object|null>}
+ */
+export async function checkContentAccess(resource, request, reply) {
+    const settings = getContentApiSettings();
+    if (!settings.enabled || !settings.resources[resource]?.enabled) {
+        reply.status(404).send(NOT_FOUND);
+        return null;
+    }
+
+    if (settings.access === 'public') return {mode: 'public', viewer: null, token: null, settings};
+
+    if (settings.access === 'token') {
+        const auth = await authenticateApiToken(request, {allows: (scopes) => contentScopeAllows(scopes, resource)});
+        if (!auth.ok) {
+            reply.status(auth.status).send({error: auth.error});
+            return null;
+        }
+        return {mode: 'token', viewer: null, token: auth.token, settings};
+    }
+
+    // Role mode. jwtVerify reads the Authorization header only; a refresh
+    // token is refused like any other non-access token.
+    let decoded;
+    try {
+        decoded = await request.jwtVerify();
+    } catch {
+        decoded = null;
+    }
+    if (!decoded || decoded.type !== 'access') {
+        reply.status(401).send({error: 'Unauthorised'});
+        return null;
+    }
+    // A role name that is not a role on this site fails closed to level 0,
+    // as checkPublicAccess() and checkVisibility() do.
+    const named = getRoleLevel(settings.access);
+    const required = Number.isFinite(named) ? named : 0;
+    if (getEffectiveLevel(decoded) > required) {
+        reply.status(403).send({error: 'Insufficient permissions'});
+        return null;
+    }
+    return {mode: 'role', viewer: decoded, token: null, settings};
+}
+
+/** A token sees only its own project's pages; other modes see every project. */
+const inProject = (access, project) => access.mode !== 'token' || access.token.project === project;
+
+/** Frontmatter `api: false` keeps a page off the API; it still renders on the site. */
+const apiOff = (page) => page?.api === false;
+
+function cacheHeaders(reply, access, {draft = false} = {}) {
+    if (draft || access.mode === 'role') reply.header('cache-control', 'no-store');
+    else if (access.mode === 'token') reply.header('cache-control', 'private, no-cache');
+    else reply.header('cache-control', 'public, max-age=60');
+}
+
+/**
+ * Which body formats a request asked for, or an error when the site does not
+ * offer one of them.
+ *
+ * @returns {{format: string} | {error: string}}
+ */
+function pickFormat(raw, settings) {
+    const format = raw == null || raw === '' ? 'html' : String(raw);
+    if (!FORMAT_VALUES.includes(format)) return {error: `Unknown format "${format}" - use html, markdown or both`};
+    const wanted = format === 'both' ? ['html', 'markdown'] : [format];
+    if (!wanted.every(f => settings.formats.includes(f))) return {error: `Format "${format}" is not available on this site`};
+    return {format};
+}
+
+/**
+ * One page as the API serves it - the decision and the payload, without
+ * caching or replies. The admin's Try it console (routes/api/content-api.js)
+ * calls this too, so it shows exactly what a caller would get.
+ *
+ * @param {string} urlPath
+ * @param {{access: object, format: string, allowDrafts?: boolean}} opts
+ * @returns {Promise<{status: 200|403|404, body: object, page?: object, isDraft?: boolean}>}
+ */
+export async function buildPageResponse(urlPath, {access, format, allowDrafts = false}) {
+    const verdict = await resolvePublishedPage(urlPath, access.viewer, {allowDrafts});
+    if (verdict.status === 'forbidden') return {status: 403, body: {error: 'Forbidden'}};
+    if (verdict.status !== 'ok' || apiOff(verdict.page) || !inProject(access, verdict.project)) {
+        return {status: 404, body: NOT_FOUND};
+    }
+    // The verdict's page was parsed anonymously. A signed-in caller gets the
+    // body rendered for them, as the site does - [menu] and row-scoped [view].
+    const page = access.viewer
+        ? (await getPage(verdict.page.urlPath, {user: access.viewer})) || verdict.page
+        : verdict.page;
+    return {status: 200, body: pageDetail(page, {format}), page, isDraft: verdict.isDraft};
+}
+
+const SORTS = {
+    title:     (a, b) => String(a.title || '').localeCompare(String(b.title || '')),
+    updatedAt: (a, b) => String(a.updatedAt || '').localeCompare(String(b.updatedAt || '')),
+    createdAt: (a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || ''))
+};
+
+const intParam = (raw, fallback) => {
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+
+/** Allowlisted menu items: what a navbar needs to draw them, nothing of their gating. */
+function menuItems(items = []) {
+    return items.map(item => {
+        const out = {};
+        for (const k of ['type', 'text', 'url', 'icon', 'target', 'size', 'badge']) {
+            if (item[k] !== undefined) out[k] = item[k];
+        }
+        if (Array.isArray(item.items) && item.items.length) out.items = menuItems(item.items);
+        return out;
+    });
+}
+
+export async function contentPublicRoutes(fastify) {
+    // This prefix is exempt from the global /api no-store hook, so anything a
+    // route did not mark itself - every refusal - is no-store here. A 404 with
+    // no Cache-Control is heuristically cacheable, and would outlive the
+    // admin switching the API on. (Scoped: a hook in this plugin reaches only
+    // these routes.)
+    fastify.addHook('onSend', async (request, reply) => {
+        if (!reply.getHeader('cache-control')) reply.header('cache-control', 'no-store');
+    });
+
+    // -------------------------------------------------------------------------
+    // Pages
+    // -------------------------------------------------------------------------
+
+    fastify.get('/content/v1/pages', async (request, reply) => {
+        const access = await checkContentAccess('pages', request, reply);
+        if (!access) return;
+        if (!access.settings.listable) return reply.status(404).send(NOT_FOUND);
+
+        const q = request.query || {};
+        const limit = Math.min(access.settings.maxLimit, intParam(q.limit, DEFAULT_LIMIT));
+        const pageNo = intParam(q.page, 1);
+
+        const all = await listPages();
+        const exclusions = await searchExclusions(all);
+        let rows = all.filter(p => isPubliclyListed(p, access.viewer, exclusions)
+            && !apiOff(p)
+            && inProject(access, p.resolvedProject));
+        if (q.prefix) rows = rows.filter(p => String(p.urlPath || '').startsWith(String(q.prefix)));
+        if (q.tag) rows = rows.filter(p => Array.isArray(p.tags) && p.tags.includes(String(q.tag)));
+        if (q.category) rows = rows.filter(p => p.category === String(q.category));
+        if (q.project) rows = rows.filter(p => p.resolvedProject === String(q.project));
+        // Default order is listPages' own (sortOrder, then title).
+        if (SORTS[q.sort]) rows = [...rows].sort(SORTS[q.sort]);
+        if (q.order === 'desc') rows = [...rows].reverse();
+
+        cacheHeaders(reply, access);
+        const start = (pageNo - 1) * limit;
+        return {pages: rows.slice(start, start + limit).map(pageSummary), total: rows.length, page: pageNo, limit};
+    });
+
+    fastify.get('/content/v1/pages/*', async (request, reply) => {
+        const access = await checkContentAccess('pages', request, reply);
+        if (!access) return;
+        const picked = pickFormat(request.query?.format, access.settings);
+        if (picked.error) return reply.status(400).send({error: picked.error});
+        const {format} = picked;
+
+        const urlPath = '/' + (request.params['*'] || '');
+        // Drafts only for a role-mode caller who could read them in the admin.
+        const allowDrafts = access.mode === 'role' && request.query?.preview === '1' && canPreviewDrafts(access.viewer);
+
+        // A signed-in or draft render is that caller's alone and never cached.
+        if (access.viewer) {
+            const res = await buildPageResponse(urlPath, {access, format, allowDrafts});
+            cacheHeaders(reply, access, {draft: res.isDraft});
+            return reply.status(res.status).send(res.body);
+        }
+
+        // Anonymous callers (public and token). No response cache: the access
+        // decision has to parse the page anyway - exactly as the site's does -
+        // and the JSON is built straight from that parse. HTTP caching does the
+        // rest; the mtime ETag changes on any edit to the file, however made.
+        const res = await buildPageResponse(urlPath, {access, format});
+        if (res.status !== 200) return reply.status(res.status).send(res.body);
+        const mtime = await getPageMtime(res.page.urlPath || urlPath);
+        cacheHeaders(reply, access);
+        reply.header('etag', `W/"${mtime}-${format}"`);
+        return res.body;
+    });
+
+    // -------------------------------------------------------------------------
+    // Menus, site settings, search
+    // -------------------------------------------------------------------------
+
+    fastify.get('/content/v1/menus/:location', async (request, reply) => {
+        const access = await checkContentAccess('menus', request, reply);
+        if (!access) return;
+        const location = String(request.params.location || '');
+        if (PRIVATE_SLOTS.has(location) || location.startsWith('admin')) return reply.status(404).send(NOT_FOUND);
+
+        // ?page= lets page-bound menus resolve as they would on that page.
+        const urlPath = request.query?.page ? String(request.query.page) : undefined;
+        const menu = await resolveLocation(location, access.viewer, urlPath ? {urlPath} : {});
+        if (!menu) return reply.status(404).send(NOT_FOUND);
+
+        cacheHeaders(reply, access);
+        return {location, slug: menu.slug, name: menu.name, items: menuItems(menu.items)};
+    });
+
+    fastify.get('/content/v1/site', async (request, reply) => {
+        const access = await checkContentAccess('site', request, reply);
+        if (!access) return;
+        let site = {};
+        try { site = getConfig('site') || {}; } catch { /* no site.json - nothing to show */ }
+        cacheHeaders(reply, access);
+        return publicSiteSettings(site);
+    });
+
+    fastify.get('/content/v1/search', async (request, reply) => {
+        const access = await checkContentAccess('search', request, reply);
+        if (!access) return;
+        const settings = getSearchSettings();
+        // Search switched off for the site is off for the API too.
+        if (!settings.enabled) return reply.status(404).send(NOT_FOUND);
+
+        const q = String(request.query?.q || '').trim().slice(0, 200);
+        if (q.length < settings.minQueryLength) {
+            return reply.status(400).send({error: `Query must be at least ${settings.minQueryLength} characters`});
+        }
+        const maxResults = Math.min(settings.maxResults, intParam(request.query?.limit, settings.maxResults));
+
+        const all = await listPages();
+        const pages = all.filter(p => !apiOff(p) && inProject(access, p.resolvedProject));
+        const results = searchPages(pages, q, {
+            maxResults,
+            viewer: access.viewer,
+            exclusions: await searchExclusions(all),
+            onError: (err, page) => request.log.warn({err, page: page.urlPath}, '[content-api] search skipped an unreadable page')
+        });
+
+        // Search results are per viewer in role mode; never shared there.
+        cacheHeaders(reply, access);
+        return {
+            results: results.map(r => ({
+                urlPath: r.url, title: r.title, description: r.description, tags: r.tags, snippet: r.snippet, score: r.score
+            }))
+        };
+    });
+}

package/server/routes/public.js

@@ -9,11 +9,10 @@
 import {getPage, getPageMtime} from '../services/content.js';
 import {getProjectForPage, isProjectEnabled} from '../services/projects.js';
 import {renderPage} from '../services/renderer.js';
+import {resolvePublishedPage} from '../services/pagePublishing.js';
 import {buildRobotsTxt, generate as generateSitemap} from '../services/sitemap.js';
-import {checkVisibility} from '../middleware/auth.js';
 import {resolveViewer} from '../services/viewerSession.js';
 import {touchPreviewLink, verifyPreviewToken} from '../services/previewLinks.js';
-import {getPermissionsFor} from '../services/roles.js';
 import {getEffectiveRoles} from '../services/userRoles.js';
 import {hooks} from '../services/hooks.js';
 import {getConfig} from '../config.js';
@@ -184,70 +183,36 @@ export async function publicRoutes(fastify) {
 
         const urlPath = '/' + (rawPath || '');
 
-        // First-pass page lookup - used only for the visibility decision
-        // (metadata-only is sufficient). We re-fetch below with `user` once
-        // it is resolved so the body's [menu] shortcode renders against the
-        // correct role.
-        let page = await getPage(urlPath);
-
-        // Try fetching index of a directory path
-        if (!page && !urlPath.endsWith('/index')) {
-            page = await getPage(urlPath.replace(/\/$/, '') || '/');
-        }
-
-        if (!page) {
-            reply.status(404);
-            return sendHtml(request, reply, await render404(urlPath));
-        }
-
-        // Hard kill-switch: a disabled project takes its pages off the public
-        // site entirely - 404 (no oracle), regardless of page visibility.
-        const pageProject = await getProjectForPage(page.urlPath || urlPath, page.project);
-        if (!(await isProjectEnabled(pageProject))) {
-            reply.status(404);
-            return sendHtml(request, reply, await render404(urlPath));
-        }
-
-        // Draft preview: a page that is not published stays invisible to the
-        // public, but is served in full to a signed-in user who could read it
-        // in the admin anyway. Everyone else gets the same 404 as before - the
-        // response must not reveal that an unpublished page exists there.
-        const isDraft = page.status !== 'published';
-
-        // Enforce page visibility. The viewer is resolved on EVERY request,
-        // not only for gated pages: the navbar, footers, overlays and [menu]
-        // shortcodes on a public page filter their items by role too, and a
-        // signed-in visitor rendered as anonymous never sees the items meant
-        // for them. Resolving is a cookie read plus a JWT verify, and returns
-        // null at once for anonymous traffic, which still shares one entry.
+        // The viewer is resolved on EVERY request, not only for gated pages:
+        // the navbar, footers, overlays and [menu] shortcodes on a public page
+        // filter their items by role too, and a signed-in visitor rendered as
+        // anonymous never sees the items meant for them. Resolving is a cookie
+        // read plus a JWT verify, and returns null at once for anonymous
+        // traffic, which still shares one entry.
         //
-        // `visibility` may be a string ('public' | 'private' | role name) or
-        // an array of role names - see checkVisibility() for full semantics.
-        // Effectively-public values (missing, 'public', or an array containing
-        // 'public') skip viewer resolution entirely so anonymous traffic hits
-        // the shared cache without auth cost - unless the page is a draft,
-        // which needs the viewer regardless of its visibility.
         // The cache key carries every role the viewer holds (sorted), since
         // exact-role visibility (`=candidate`) makes an additional role change
         // what renders. Real sites hold a handful of role combinations, so
         // the entry count stays bounded by what users actually have.
-        const vis      = page.visibility;
-        const isPublic = !vis
-            || vis === 'public'
-            || (Array.isArray(vis) && (vis.length === 0 || vis.includes('public')));
-
         const userObj  = await resolveViewer(request);
         const userRole = userObj ? [...getEffectiveRoles(userObj)].sort().join('+') : null;
 
-        if (isDraft && !canPreviewDrafts(userObj)) {
+        // The access decision - the directory-index fallback, the project
+        // kill-switch, drafts and visibility - is resolvePublishedPage(), shared
+        // with the Content API so the two can never disagree. Drafts are allowed
+        // here: a viewer holding pages.read gets the real page plus a banner;
+        // everyone else gets the same 404 as a missing page, so the response
+        // never reveals that an unpublished page exists there.
+        const verdict = await resolvePublishedPage(urlPath, userObj, {allowDrafts: true});
+        if (verdict.status === 'not-found') {
             reply.status(404);
             return sendHtml(request, reply, await render404(urlPath));
         }
-
-        if (!isPublic && !checkVisibility(userObj, vis)) {
+        if (verdict.status === 'forbidden') {
             reply.status(403);
             return reply.type('text/html; charset=utf-8').send(accessDeniedHtml(urlPath));
         }
+        const {page, isDraft} = verdict;
 
         const baseUrl = getBaseUrl(request);
 
@@ -294,22 +259,6 @@ export async function publicRoutes(fastify) {
     });
 }
 
-/**
- * May this viewer see unpublished pages on the public site?
- *
- * Gated on `pages.read` - the same permission that opens the Pages list in the
- * admin. Anyone who can already read the draft's source there loses nothing by
- * seeing it rendered, and nobody else gains anything.
- *
- * @param {object|null} user - Resolved viewer (`{role, additionalRoles}`) or null
- * @returns {boolean}
- */
-function canPreviewDrafts(user) {
-    if (!user) return false;
-    const allowed = getPermissionsFor('pages', 'read');
-    return getEffectiveRoles(user).some(role => allowed.includes(role));
-}
-
 /**
  * Render a 404 response - tries content/pages/404.md first, falls back to
  * a minimal inline page so the site theme is applied when possible.

package/server/server.js

@@ -460,14 +460,15 @@ app.setErrorHandler((error, request, reply) => {
 // ---------------------------------------------------------------------------
 // The admin SPA must always see the live state of the site - a stale list is
 // indistinguishable from a missing artefact, and the user is left arguing with
-// their own CMS. Everything under /api is no-store EXCEPT the two externally
+// their own CMS. Everything under /api is no-store EXCEPT the three externally
 // consumable surfaces, which have their own caching contracts:
-//   /api/v1/*  - collection access by API token
-//   /api/x/*   - API Builder endpoints
+//   /api/v1/*          - collection access by API token
+//   /api/x/*           - API Builder endpoints
+//   /api/content/v1/*  - the Content API (public / private / no-store per access mode)
 app.addHook('onSend', async (request, reply) => {
     const url = request.raw.url || '';
     if (!url.startsWith('/api/')) return;
-    if (url.startsWith('/api/v1/') || url.startsWith('/api/x/')) return;
+    if (url.startsWith('/api/v1/') || url.startsWith('/api/x/') || url.startsWith('/api/content/v1/')) return;
     reply.header('Cache-Control', 'no-store, must-revalidate');
     reply.header('Pragma', 'no-cache');
     reply.header('Expires', '0');
@@ -497,6 +498,8 @@ const {rolesRoutes}         = await import('./routes/api/roles.js');
 const {apiTokensRoutes}     = await import('./routes/api/api-tokens.js');
 const {apiEndpointsRoutes}  = await import('./routes/api/api-endpoints.js');
 const {endpointsPublicRoutes} = await import('./routes/api/endpoints-public.js');
+const {contentPublicRoutes} = await import('./routes/api/content-public.js');
+const {contentApiRoutes}    = await import('./routes/api/content-api.js');
 const {sidebarRoutes}       = await import('./routes/api/sidebar.js');
 const {documentationRoutes} = await import('./routes/api/documentation.js');
 const { mediaRoutes }      = await import('./routes/api/media.js');
@@ -536,6 +539,8 @@ await app.register(rolesRoutes,         {prefix: '/api'});
 await app.register(apiTokensRoutes,     {prefix: '/api'});
 await app.register(apiEndpointsRoutes,  {prefix: '/api'});
 await app.register(endpointsPublicRoutes, {prefix: '/api'});
+await app.register(contentPublicRoutes, {prefix: '/api'});
+await app.register(contentApiRoutes,    {prefix: '/api'});
 await app.register(sidebarRoutes,       {prefix: '/api'});
 await app.register(documentationRoutes, {prefix: '/api'});
 await app.register(mediaRoutes,       { prefix: '/api' });
@@ -657,6 +662,7 @@ registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Layouts
 registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Plugins', url: '#/plugins', icon: 'package', permission: 'plugins', countUrl: '/api/plugins/_count', inventory: true}});
 registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'API Tokens', url: '#/api-tokens', icon: 'key', permission: 'api-tokens', countUrl: '/api/api-tokens/_count'}});
 registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Search', url: '#/search', icon: 'search', permission: 'settings', countUrl: '/api/search/_count', inventory: true}});
+registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Content API', url: '#/content-api', icon: 'file-text', permission: 'settings', countUrl: '/api/content-api/_count', inventory: true}});
 // Documentation pages added after the sidebar menu was seeded (0.93.1). The menu is
 // seeded once, so new pages reach existing sites only by registering here. The two
 // sub-folders have no key in older menus; findFolder() falls back to their name.
@@ -666,6 +672,7 @@ registerSidebarItem({folder: 'Usage', item: {source: 'Built in', text: 'Editions
 registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'Forms', url: '#/docs/api/forms', icon: 'layout'}});
 registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'Scaffold', url: '#/docs/api/scaffold', icon: 'package'}});
 registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'External API & Tokens', url: '#/docs/api/external', icon: 'key'}});
+registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'Content API', url: '#/docs/api/content', icon: 'file-text'}});
 registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'API Builder', url: '#/docs/api/builder', icon: 'code'}});
 
 // Core's notification sources, before plugins add theirs (0.80).

package/server/services/apiTokens.js

@@ -17,6 +17,12 @@ export const API_TOKENS_COLLECTION_SLUG = 'api-tokens';
 
 const TOKEN_RE = /^dcms_[a-f0-9]{64}$/;
 const VERBS = ['create', 'read', 'update', 'delete'];
+
+/**
+ * What a `{content}` scope may name - the Content API's resources. Content
+ * scopes are read-only (the API has no writes yet), so they carry no verbs.
+ */
+export const CONTENT_RESOURCES = Object.freeze(['pages', 'menus', 'site', 'search']);
 const LAST_USED_THROTTLE_MS = 60_000;
 
 /** In-memory hash → entry cache; null = needs rebuild. */
@@ -75,16 +81,23 @@ function sanitise(entry) {
 }
 
 /**
- * Validate a scopes declaration: array of { collection, verbs[] }.
- * Empty array = the token covers every collection in its project.
+ * Validate a scopes declaration. Each scope is EITHER a collection scope
+ * `{collection, verbs?}` OR a content scope `{content}` (a Content API
+ * resource). Empty array = the token covers everything in its project.
  *
  * @param {*} scopes
  * @returns {string|null} Error message, or null when valid
  */
-function validateScopes(scopes) {
+export function validateScopes(scopes) {
     if (scopes == null) return null;
     if (!Array.isArray(scopes)) return 'scopes must be an array';
     for (const s of scopes) {
+        if (s && typeof s === 'object' && s.content !== undefined) {
+            if (s.collection !== undefined) return 'a scope names either a collection or a content resource, not both';
+            if (!CONTENT_RESOURCES.includes(s.content)) return `unknown content resource "${s.content}"`;
+            if (s.verbs != null) return 'content scopes are read-only and take no verbs';
+            continue;
+        }
         if (!s || typeof s !== 'object' || typeof s.collection !== 'string' || !s.collection.trim()) {
             return 'each scope needs a collection slug';
         }
@@ -101,18 +114,61 @@ function validateScopes(scopes) {
  * Check whether a token's scopes permit an operation on a collection.
  * Empty/missing scopes → everything in the token's project is allowed.
  *
- * @param {Array<{collection: string, verbs?: string[]}>} scopes
+ * @param {Array<{collection?: string, verbs?: string[], content?: string}>} scopes
  * @param {string} collectionSlug
  * @param {string} verb - create | read | update | delete
  * @returns {boolean}
  */
 export function scopeAllows(scopes, collectionSlug, verb) {
     if (!Array.isArray(scopes) || scopes.length === 0) return true;
-    const scope = scopes.find(s => s.collection === collectionSlug);
+    // Content scopes never match: a collection named `pages` is still a collection.
+    const scope = scopes.find(s => s.collection !== undefined && s.collection === collectionSlug);
     if (!scope) return false;
     return !Array.isArray(scope.verbs) || scope.verbs.length === 0 || scope.verbs.includes(verb);
 }
 
+/**
+ * Does a token's scope list permit a Content API resource? Empty = everything
+ * in the project. A list that names no content resource permits none - a token
+ * scoped to collections is never widened by the Content API existing.
+ *
+ * @param {object[]} scopes
+ * @param {string} resource - one of CONTENT_RESOURCES
+ * @returns {boolean}
+ */
+export function contentScopeAllows(scopes, resource) {
+    if (!Array.isArray(scopes) || scopes.length === 0) return true;
+    return scopes.some(s => s.content === resource);
+}
+
+const BEARER_RE = /^Bearer (dcms_[a-f0-9]{64})$/;
+
+/**
+ * The strict token check, shared by every externally consumable gate - the
+ * collections API (and the API Builder endpoints that reuse it) and the
+ * Content API. A token is the ONLY credential accepted: callers decide when
+ * token mode applies, and this never looks at a JWT.
+ *
+ * `project` binds the token to the resource's project. Omit it when the
+ * caller binds per resource instead (a Content API page list spans projects
+ * and is filtered to the token's). `allows` receives the token's scopes.
+ *
+ * @param {{headers?: object}} request
+ * @param {{project?: string, allows: (scopes: object[]) => boolean, projectError?: string}} opts
+ * @returns {Promise<{ok: true, token: object} | {ok: false, status: 401|403, error: string}>}
+ */
+export async function authenticateApiToken(request, {project, allows, projectError}) {
+    const match = (request.headers?.authorization || '').match(BEARER_RE);
+    if (!match) return {ok: false, status: 401, error: 'API token required'};
+    const token = await validateToken(match[1]);
+    if (!token) return {ok: false, status: 401, error: 'Invalid, disabled or expired API token'};
+    if (project !== undefined && token.project !== project) {
+        return {ok: false, status: 403, error: projectError || "Token is not valid for this resource's project"};
+    }
+    if (!allows(token.scopes)) return {ok: false, status: 403, error: 'Token scope does not permit this operation'};
+    return {ok: true, token};
+}
+
 /**
  * Create a new token. The plaintext is returned ONCE here and never again.
  *

package/server/services/content.js

@@ -167,7 +167,7 @@ export async function createPage(urlPath, frontmatter, body) {
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body || ''), 'utf8');
     const page = await readPageFile(filePath);
-    await cache.invalidateTags([`page:${urlPath}`, 'sitemap']);
+    await cache.invalidateTags([`page:${urlPath}`, 'sitemap', 'pages:list']);
     hooks.emit('content:pageCreated', {page, urlPath});
     return page;
 }
@@ -222,7 +222,7 @@ export async function updatePage(urlPath, frontmatter, body, {author} = {}) {
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body ?? existingContent), 'utf8');
     const page = await readPageFile(filePath);
-    await cache.invalidateTags([`page:${urlPath}`, 'sitemap']);
+    await cache.invalidateTags([`page:${urlPath}`, 'sitemap', 'pages:list']);
     hooks.emit('content:pageUpdated', {page, urlPath});
     return page;
 }
@@ -240,7 +240,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
     const newFile = urlPathToFilePath(newUrlPath);
     await fs.mkdir(path.dirname(newFile), { recursive: true });
     await fs.rename(oldFile, newFile);
-    await cache.invalidateTags([`page:${oldUrlPath}`, `page:${newUrlPath}`, 'sitemap']);
+    await cache.invalidateTags([`page:${oldUrlPath}`, `page:${newUrlPath}`, 'sitemap', 'pages:list']);
     try {
         await renameVersionDir(oldUrlPath, newUrlPath);
     } catch {
@@ -259,7 +259,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
 export async function deletePage(urlPath) {
     const filePath = await resolveExistingFilePath(urlPath);
     await fs.unlink(filePath);
-    await cache.invalidateTags([`page:${urlPath}`, 'sitemap']);
+    await cache.invalidateTags([`page:${urlPath}`, 'sitemap', 'pages:list']);
     hooks.emit('content:pageDeleted', {urlPath});
     try {
         await deleteAllVersions(urlPath);