domma-cms 0.116.8 → 0.117.0

package/server/services/contentApi.js

@@ -0,0 +1,248 @@
+/**
+ * Content API - settings and payloads.
+ *
+ * Settings live in config/content-api.json (optional; absence = the defaults,
+ * which are OFF - an upgrade must not expose a site that never chose to be).
+ *
+ * Every payload is built from an ALLOWLIST. Frontmatter is open-ended (authors
+ * and plugins add keys freely) and site.json holds SMTP credentials, so a
+ * spread-then-delete is one forgotten key away from a leak.
+ */
+import {getConfig, saveConfig} from '../config.js';
+import {CONTENT_RESOURCES} from './apiTokens.js';
+import {isPubliclyListed} from './search.js';
+import {plural} from './sidebarBadges.js';
+
+export const FORMATS = Object.freeze(['html', 'markdown']);
+
+export const CONTENT_API_DEFAULTS = Object.freeze({
+    enabled: false,
+    access: 'token',
+    resources: Object.freeze(Object.fromEntries(CONTENT_RESOURCES.map(k => [k, Object.freeze({enabled: true})]))),
+    formats: Object.freeze(['html']),
+    listable: true,
+    maxLimit: 200
+});
+
+const MAX_LIMIT = 200;
+
+/**
+ * @param {object} [raw] - config/content-api.json as stored, or a patch merged onto it
+ * @returns {object} A fresh, complete settings object
+ */
+export function normaliseContentApiSettings(raw) {
+    const r = raw && typeof raw === 'object' ? raw : {};
+    const access = typeof r.access === 'string' && r.access.trim() ? r.access.trim() : CONTENT_API_DEFAULTS.access;
+    const formats = Array.isArray(r.formats) ? FORMATS.filter(f => r.formats.includes(f)) : [];
+    const limit = Math.trunc(Number(r.maxLimit));
+    return {
+        enabled: r.enabled === true,
+        access,
+        resources: Object.fromEntries(CONTENT_RESOURCES.map(k => [k, {enabled: r.resources?.[k]?.enabled !== false}])),
+        formats: formats.length ? formats : [...CONTENT_API_DEFAULTS.formats],
+        listable: r.listable !== false,
+        maxLimit: Number.isFinite(limit) ? Math.min(MAX_LIMIT, Math.max(1, limit)) : CONTENT_API_DEFAULTS.maxLimit
+    };
+}
+
+/** Current settings, defaults filled in. A site with no file gets the (off) defaults. */
+export function getContentApiSettings() {
+    try {
+        return normaliseContentApiSettings(getConfig('content-api'));
+    } catch {
+        return normaliseContentApiSettings({});
+    }
+}
+
+/**
+ * Save settings, returning what was actually stored.
+ *
+ * @param {object} patch - Partial or complete settings
+ * @returns {object}
+ */
+export function saveContentApiSettings(patch) {
+    const next = normaliseContentApiSettings({...getContentApiSettings(), ...(patch || {})});
+    saveConfig('content-api', next);
+    return next;
+}
+
+// ---------------------------------------------------------------------------
+// Payloads
+// ---------------------------------------------------------------------------
+
+const SUMMARY_KEYS = ['urlPath', 'title', 'description', 'tags', 'category', 'layout', 'updatedAt'];
+const DETAIL_KEYS  = [...SUMMARY_KEYS, 'createdAt'];
+const SEO_KEYS     = ['title', 'description', 'image', 'canonical', 'noindex'];
+
+const pick = (obj, keys) => Object.fromEntries(keys.filter(k => obj?.[k] !== undefined).map(k => [k, obj[k]]));
+
+/**
+ * The Domma behaviour a page's HTML relies on: the markup public/js/site.js
+ * (and public/js/effects.js) initialise. A client rendering `html` without Domma gets these inert, so
+ * the API names them. `usedComponents` does not cover them - it lists only
+ * custom `[component]`s, and a page of tabs reports none.
+ *
+ * Matched on real attributes only: markup shown in a code block is escaped
+ * (`<div class="tabs`) and never matches. Keep in step with site.js.
+ */
+const DOMMA_MARKERS = [
+    ['tabs',             {cls: 'tabs'}],
+    ['accordion',        {cls: 'accordion'}],
+    ['carousel',         {cls: 'carousel'}],
+    ['countdown',        {cls: 'dm-countdown'}],
+    ['progression',      {cls: 'dm-progression'}],
+    ['slideover',        {cls: 'dm-so-trigger'}],
+    ['cta',              {cls: 'dm-cta-trigger'}],
+    ['collapsible',      {attr: 'data-collapsible'}],
+    ['tooltip',          {attr: 'data-tooltip'}],
+    ['reveal',           {attr: 'data-reveal'}],
+    ['collection-table', {attr: 'data-collection-table'}],
+    ['form',             {attr: 'data-form-inline'}],
+    ['collection',       {cls: 'dm-collection-hydrate'}],
+    ['page-config',      {cls: 'dm-page-config'}],
+    // Every effect (scribe, reveal, celebrate, counter, …) is a dm-fx-<name> class.
+    ['effects',          {prefix: 'dm-fx-'}]
+];
+
+/**
+ * @param {string} html
+ * @returns {string[]} Marker names found, in DOMMA_MARKERS order
+ */
+export function domma(html) {
+    if (typeof html !== 'string' || !html) return [];
+    const classes = new Set();
+    for (const m of html.matchAll(/<[^>]*?\sclass="([^"]*)"/g)) {
+        for (const c of m[1].split(/\s+/)) if (c) classes.add(c);
+    }
+    const hasAttr = (name) => new RegExp(`<[^>]*\\s${name}(?=[\\s=/>])`).test(html);
+    return DOMMA_MARKERS
+        .filter(([, m]) => {
+            if (m.prefix) return [...classes].some(c => c.startsWith(m.prefix));
+            return m.cls ? classes.has(m.cls) : hasAttr(m.attr);
+        })
+        .map(([name]) => name);
+}
+
+/**
+ * A page in a list: enough to link to it, never its body - the list must stay
+ * cheap enough to run over every page without rendering any.
+ *
+ * @param {object} page - a listPages() row
+ * @returns {object}
+ */
+export function pageSummary(page) {
+    return pick(page, SUMMARY_KEYS);
+}
+
+/**
+ * One page. `html` is the body only (page.html), not the full document with
+ * navbar and footer; `markdown` is the source, shortcodes and all.
+ *
+ * @param {object} page - a getPage() result the caller is allowed to see
+ * @param {{format: 'html'|'markdown'|'both'}} opts
+ * @returns {object}
+ */
+export function pageDetail(page, {format}) {
+    const out = pick(page, DETAIL_KEYS);
+    if (page.seo && typeof page.seo === 'object') out.seo = pick(page.seo, SEO_KEYS);
+    if (format === 'html' || format === 'both') out.html = page.html || '';
+    if (format === 'markdown' || format === 'both') out.markdown = page.content || '';
+    const custom = Array.isArray(page.usedComponents) ? page.usedComponents : [];
+    const components = [...new Set([...domma(page.html), ...custom])];
+    out.requires = {domma: components.length > 0, components};
+    out.perViewer = Boolean(page.perViewer);
+    return out;
+}
+
+/**
+ * Site settings safe for any caller: exactly what every public page already
+ * shows - the title, navbar brand, footer (hidden links stay hidden, as in
+ * renderer.js), social links, the SEO defaults in its meta tags, and the theme
+ * class. `tagline`, `url`, `smtp` and the admin settings never reach a public
+ * page, so they never reach this either.
+ *
+ * @param {object} [site] - config/site.json
+ * @returns {object}
+ */
+export function publicSiteSettings(site = {}) {
+    const out = pick(site, ['title', 'social', 'theme']);
+    if (site.brand && typeof site.brand === 'object') out.brand = pick(site.brand, ['text', 'logo', 'url']);
+    if (site.footer && typeof site.footer === 'object') {
+        out.footer = {...site.footer, links: (site.footer.links || []).filter(l => !l?.hidden)};
+    }
+    if (site.seo && typeof site.seo === 'object') out.seo = pick(site.seo, ['defaultTitle', 'titleSeparator', 'defaultDescription']);
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// The admin screen: coverage, and the sidebar badge
+// ---------------------------------------------------------------------------
+
+/**
+ * How many pages the API can serve an anonymous caller - the same rule as its
+ * page list (isPubliclyListed, then `api: false`). A signed-in role-mode caller
+ * may get more: the gated pages they can open.
+ *
+ * @param {object[]} pages - listPages()
+ * @param {{offline?: Set<string>, noindex?: Set<string>}|null} [exclusions] - searchExclusions()
+ * @returns {{served: number, keptOff: number, total: number}}
+ */
+export function contentApiCoverage(pages = [], exclusions = null) {
+    let served = 0;
+    let keptOff = 0;
+    for (const p of pages) {
+        if (!isPubliclyListed(p, null, exclusions)) continue;
+        if (p.api === false) keptOff++;
+        else served++;
+    }
+    return {served, keptOff, total: pages.length};
+}
+
+/** How a settings `access` value reads to a person. */
+export function accessLabel(access) {
+    if (access === 'public') return 'public';
+    if (access === 'token') return 'API token';
+    return `role: ${access} and above`;
+}
+
+const FORMAT_LABEL = {html: 'HTML', markdown: 'Markdown'};
+
+/**
+ * The sidebar badge on System › Content API (its countUrl, GET
+ * /api/content-api/_count): the pages served, and how the API is set up in
+ * the popover. An inventory, not a signal - plain text throughout.
+ *
+ * @param {object} settings
+ * @param {object[]} pages
+ * @param {object|null} [exclusions]
+ */
+export function contentApiBadge(settings, pages = [], exclusions = null) {
+    const s = normaliseContentApiSettings(settings);
+    const c = contentApiCoverage(pages, exclusions);
+    const served = plural(c.served, 'page');
+    const access = accessLabel(s.access);
+    const resources = CONTENT_RESOURCES.filter(k => s.resources[k].enabled);
+    return {
+        count: c.served,
+        label: s.enabled
+            ? `Content API is on (${access}) - ${served} served`
+            : `Content API is off - ${served} would be served`,
+        tone: 'info',
+        details: {
+            title: 'Content API',
+            rows: [
+                {label: 'Status', value: s.enabled ? 'On' : 'Off'},
+                {label: 'Access', value: access.charAt(0).toUpperCase() + access.slice(1)},
+                {label: 'Resources', value: resources.length ? resources.join(', ') : 'none'},
+                {label: 'Formats', value: s.formats.map(f => FORMAT_LABEL[f]).join(', ')},
+                {label: 'Page list', value: s.listable ? 'On' : 'Off - single pages only'},
+                {label: 'Pages served', value: String(c.served)},
+                {label: 'Kept off (api: false)', value: String(c.keptOff)}
+            ],
+            items: [],
+            empty: s.enabled
+                ? 'Callers get the published pages an anonymous visitor could open, except pages marked api: false.'
+                : 'The Content API is switched off - every /api/content/v1 address answers 404.'
+        }
+    };
+}

package/server/services/pagePublishing.js

@@ -0,0 +1,85 @@
+/**
+ * Page publishing - may this viewer see this page?
+ *
+ * The one implementation of the public page access decision. The public site
+ * (routes/public.js) calls it, and so will the Content API, so a page
+ * reachable over the API is reachable on the site by the same viewer and the
+ * reverse. It decides; it never replies or renders.
+ *
+ * Order matters and matches what the site has always done:
+ *   1. the page (with the directory-index fallback)
+ *   2. its project's kill-switch - a disabled project is a 404, no oracle
+ *   3. drafts - anything not `published` is a 404 unless drafts are allowed
+ *      AND the viewer holds pages.read
+ *   4. visibility - checkVisibility(), the ladder / `=role` rule
+ */
+import {getPage} from './content.js';
+import {getProjectForPage, isProjectEnabled} from './projects.js';
+import {checkVisibility} from '../middleware/auth.js';
+import {getPermissionsFor} from './roles.js';
+import {getEffectiveRoles} from './userRoles.js';
+
+/**
+ * Does a visibility value let everyone in? Missing, 'public', an empty array,
+ * or an array containing 'public'.
+ *
+ * @param {string|string[]|undefined} vis
+ * @returns {boolean}
+ */
+export function isEffectivelyPublic(vis) {
+    return !vis
+        || vis === 'public'
+        || (Array.isArray(vis) && (vis.length === 0 || vis.includes('public')));
+}
+
+/**
+ * May this viewer see unpublished pages?
+ *
+ * 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}
+ */
+export function canPreviewDrafts(user) {
+    if (!user) return false;
+    const allowed = getPermissionsFor('pages', 'read');
+    return getEffectiveRoles(user).some(role => allowed.includes(role));
+}
+
+/**
+ * The page is fetched anonymously: the verdict needs only its metadata. A
+ * caller rendering the body for a signed-in viewer re-fetches it with
+ * `getPage(page.urlPath, {user})` so `[menu]` and row-scoped `[view]` see them.
+ *
+ * A `forbidden` verdict carries no page, so nothing downstream can render it
+ * by mistake.
+ *
+ * @param {string} urlPath - '/about', '/services', '/'
+ * @param {object|null} viewer - resolveViewer() result, a JWT user, or null
+ * @param {{allowDrafts?: boolean}} [opts]
+ * @returns {Promise<
+ *   {status: 'ok', page: object, project: string, isDraft: boolean, isPublic: boolean} |
+ *   {status: 'not-found'} |
+ *   {status: 'forbidden'}
+ * >}
+ */
+export async function resolvePublishedPage(urlPath, viewer, {allowDrafts = false} = {}) {
+    let page = await getPage(urlPath);
+    if (!page && !urlPath.endsWith('/index')) {
+        page = await getPage(urlPath.replace(/\/$/, '') || '/');
+    }
+    if (!page) return {status: 'not-found'};
+
+    const project = await getProjectForPage(page.urlPath || urlPath, page.project);
+    if (!(await isProjectEnabled(project))) return {status: 'not-found'};
+
+    const isDraft = page.status !== 'published';
+    if (isDraft && !(allowDrafts && canPreviewDrafts(viewer))) return {status: 'not-found'};
+
+    const isPublic = isEffectivelyPublic(page.visibility);
+    if (!isPublic && !checkVisibility(viewer, page.visibility)) return {status: 'forbidden'};
+
+    return {status: 'ok', page, project, isDraft, isPublic};
+}

package/server/services/permissionRegistry.js

@@ -314,7 +314,7 @@ export const REGISTRY = [
     {
         key: 'api-tokens',
         label: 'API Tokens',
-        description: 'Manage project-scoped tokens for the external collections API.',
+        description: 'Manage project-scoped tokens for the external collections API and the Content API.',
         icon: 'key',
         group: 'Configuration',
         actions: [

package/server/services/search.js

@@ -457,25 +457,43 @@ export function isOffline(page, exclusions = null) {
 }
 
 /**
- * May this page appear in this viewer's search results? Drafts never; pages
- * in a disabled project never; pages that ask not to be indexed (frontmatter
- * or the SEO screen) never; otherwise exactly when the viewer could open the
- * page - checkVisibility() is the one visibility rule, the same the public
- * page renderer applies, so a role-gated page (`member`, `=candidate`,
- * `private`) is found only by someone it would be served to.
+ * Could this viewer open this page from a list? Published, in an enabled
+ * project, and visible to them. Site search and the Content API's page list
+ * share it; noindex is search's own business and is not part of it.
+ *
+ * `status !== 'published'`, not `=== 'draft'`: the public route has always
+ * 404ed every unpublished status, and search used to find a `scheduled` or
+ * status-less page that then 404ed.
+ *
+ * checkVisibility() is the one visibility rule, the same the public page
+ * renderer applies, so a role-gated page (`member`, `=candidate`, `private`)
+ * is listed only for someone it would be served to.
  *
  * @param {object} page
  * @param {object|null} [viewer] - resolved viewer, null for anonymous
  * @param {{offline?: Set<string>, noindex?: Set<string>}|null} [exclusions] - searchExclusions()
  * @returns {boolean}
  */
-export function isSearchable(page, viewer = null, exclusions = null) {
-    if (!page || page.status === 'draft') return false;
+export function isPubliclyListed(page, viewer = null, exclusions = null) {
+    if (!page || page.status !== 'published') return false;
     if (isOffline(page, exclusions)) return false;
-    if (isNoindex(page, exclusions)) return false;
     return checkVisibility(viewer, page.visibility);
 }
 
+/**
+ * May this page appear in this viewer's search results? Exactly when it is
+ * publicly listed for them (isPubliclyListed) and does not ask not to be
+ * indexed (frontmatter or the SEO screen).
+ *
+ * @param {object} page
+ * @param {object|null} [viewer] - resolved viewer, null for anonymous
+ * @param {{offline?: Set<string>, noindex?: Set<string>}|null} [exclusions] - searchExclusions()
+ * @returns {boolean}
+ */
+export function isSearchable(page, viewer = null, exclusions = null) {
+    return isPubliclyListed(page, viewer, exclusions) && !isNoindex(page, exclusions);
+}
+
 /**
  * Search a set of pages.
  *
@@ -536,8 +554,9 @@ export function searchPages(pages, query, {maxResults = 10, onError = () => {},
  * Which pages an anonymous visitor's search can return, and which it leaves
  * out - the same rule searchPages() applies (isSearchable() with no viewer).
  * Each page left out is counted once, under the first reason that applies:
- * a draft, then offline (its project is disabled), then restricted (private
- * or role-gated), then noindex (frontmatter or the SEO screen). A signed-in
+ * unpublished (`drafts` - any status but `published`, as isPubliclyListed()),
+ * then offline (its project is disabled), then restricted (private or
+ * role-gated), then noindex (frontmatter or the SEO screen). A signed-in
  * visitor may find more than `searchable` - the gated pages they can open.
  *
  * @param {object[]} pages
@@ -550,7 +569,7 @@ export function searchCoverage(pages = [], exclusions = null) {
     let restricted = 0;
     let noindex = 0;
     for (const p of pages) {
-        if (p?.status === 'draft') drafts++;
+        if (p?.status !== 'published') drafts++;
         else if (isOffline(p, exclusions)) offline++;
         else if (!checkVisibility(null, p?.visibility)) restricted++;
         else if (isNoindex(p, exclusions)) noindex++;