domma-cms 0.49.2 → 0.51.0

package/server/routes/api/pages.js

@@ -5,9 +5,21 @@
  * POST   /api/pages          - create page
  * PUT    /api/pages/*        - update page
  * DELETE /api/pages/*        - delete page
+ * POST   /api/pages/preview  - render markdown body to HTML (no page shell)
+ * POST   /api/pages/preview/full      - render UNSAVED frontmatter+body as a complete page
+ * GET    /api/pages/preview-links     - list share links (optionally ?urlPath=)
+ * POST   /api/pages/preview-links     - mint a share link for one page
+ * DELETE /api/pages/preview-links/:id - revoke a share link
  */
-import {createPage, deletePage, getPage, listPages, renamePage, updatePage} from '../../services/content.js';
+import {buildPreviewPage, createPage, deletePage, getPage, listPages, renamePage, updatePage} from '../../services/content.js';
 import {parseMarkdown} from '../../services/markdown.js';
+import {renderPage} from '../../services/renderer.js';
+import {
+    createPreviewLink,
+    deletePreviewLinksForPage,
+    listPreviewLinks,
+    revokePreviewLink
+} from '../../services/previewLinks.js';
 import {getVersionCount} from '../../services/versions.js';
 import {authenticate, requirePermission} from '../../middleware/auth.js';
 import {getConfig, saveConfig} from '../../config.js';
@@ -26,6 +38,73 @@ export async function pagesRoutes(fastify) {
     return {html};
   });
 
+    // Full-page preview of UNSAVED editor state.
+    //
+    // The body-only route above answers "did my shortcodes parse". This one
+    // answers "is the page right" - it runs the same parseMarkdown and
+    // renderPage the public site runs on save, so layout, navbar, footer,
+    // theme, menus, dconfig and custom CSS are all exactly what shipping
+    // would produce. No draft banner: the editor is already telling the user
+    // what they are looking at.
+    fastify.post('/pages/preview/full', canRead, async (request, reply) => {
+        const {frontmatter = {}, body = '', urlPath = '/'} = request.body || {};
+        if (typeof body !== 'string') return reply.status(400).send({error: 'body must be a string'});
+        if (typeof urlPath !== 'string' || !urlPath.startsWith('/')) {
+            return reply.status(400).send({error: 'urlPath must begin with /'});
+        }
+        if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+            return reply.status(400).send({error: 'frontmatter must be an object'});
+        }
+
+        const page = await buildPreviewPage(urlPath, frontmatter, body, {user: request.user || null});
+        const html = await renderPage(page, {
+            baseUrl: `${request.protocol}://${request.host}`,
+            user: request.user || null
+        });
+        return {html};
+    });
+
+    // --- Share links --------------------------------------------------------
+    // Minting is gated on `pages.update`, not `pages.read`: handing an
+    // unauthenticated stranger a URL that renders unpublished content is an act
+    // of publishing, however narrow, and should sit with the people who could
+    // publish the page outright.
+
+    fastify.get('/pages/preview-links', canRead, async (request) => {
+        const {urlPath} = request.query || {};
+        return {links: await listPreviewLinks(urlPath || undefined)};
+    });
+
+    fastify.post('/pages/preview-links', canUpdate, async (request, reply) => {
+        const {urlPath, expiresIn, label} = request.body || {};
+        if (!urlPath || typeof urlPath !== 'string' || !urlPath.startsWith('/')) {
+            return reply.status(400).send({error: 'urlPath must begin with /'});
+        }
+        // Refuse to mint for a page that does not exist - otherwise a typo
+        // produces a link that 404s for the recipient and looks like a bug.
+        if (!(await getPage(urlPath))) {
+            return reply.status(404).send({error: 'Page not found'});
+        }
+        const link = await createPreviewLink({
+            urlPath,
+            jwt: fastify.jwt,
+            label,
+            expiresIn,
+            createdBy: request.user?.id || null,
+            createdByName: request.user?.name || ''
+        });
+        return reply.status(201).send({
+            ...link,
+            url: `${request.protocol}://${request.host}/_preview?token=${encodeURIComponent(link.token)}`
+        });
+    });
+
+    fastify.delete('/pages/preview-links/:id', canUpdate, async (request, reply) => {
+        const ok = await revokePreviewLink(request.params.id);
+        if (!ok) return reply.status(404).send({error: 'Link not found'});
+        return {success: true};
+    });
+
     // Aggregate unique tags from all pages - must be registered before the wildcard /pages/* route
     fastify.get('/pages/tags', canRead, async (request, reply) => {
         const pages = await listPages();
@@ -105,6 +184,9 @@ export async function pagesRoutes(fastify) {
 
             await renamePage(urlPath, newUrlPath);
             await rewriteNavLinks(urlPath, newUrlPath);
+            // Links name the old path in their signed payload, so they cannot
+            // follow the move - drop them rather than leave them 404ing.
+            await deletePreviewLinksForPage(urlPath);
 
             const page = await updatePage(newUrlPath, frontmatter || {}, body, {author: request.user.username});
             return page;
@@ -121,6 +203,8 @@ export async function pagesRoutes(fastify) {
         if (!existing) return reply.status(404).send({ error: 'Page not found' });
 
         await deletePage(urlPath);
+        // A share link must not outlive the page it pointed at.
+        await deletePreviewLinksForPage(urlPath);
         return { success: true };
     });
 }

package/server/routes/public.js

@@ -1,7 +1,9 @@
 /**
  * Public Site Routes
  * Catch-all that resolves URL paths to Markdown pages and renders them server-side.
- * Draft pages are not served publicly.
+ * Draft pages are not served publicly - but a signed-in user holding
+ * `pages.read` is shown the real page with a draft banner, so designers and
+ * developers can verify a page before it is released.
  * The admin panel is excluded (handled by static serving).
  */
 import {getPage, getPageMtime} from '../services/content.js';
@@ -9,6 +11,10 @@ import {getProjectForPage, isProjectEnabled} from '../services/projects.js';
 import {renderPage} from '../services/renderer.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';
 import * as cache from '../services/cache/index.js';
@@ -76,6 +82,61 @@ export async function publicRoutes(fastify) {
         return reply.type('text/plain').send(buildRobotsTxt(getBaseUrl(request)));
     });
 
+    // Share-link preview: one signed token, one page, no account needed.
+    //
+    // The token rides in the query string, not the path: Fastify caps a route
+    // parameter at 100 characters by default and a signed token is three times
+    // that, so `/_preview/:token` silently fell through to the catch-all and
+    // 404'd. Raising maxParamLength would fix it only for instances that
+    // remember to set it - tests and embedders included - so the query string
+    // is the form that cannot come apart.
+    //
+    // The token names the page, so a holder cannot repoint the link; the
+    // server-side index means it can be withdrawn after the fact.
+    fastify.get('/_preview', async (request, reply) => {
+        // Referrer-Policy matters more here than anywhere else on the site: the
+        // credential is IN the URL, so a default referrer would hand the whole
+        // token to every third-party asset the page loads.
+        reply.header('referrer-policy', 'no-referrer');
+        reply.header('cache-control', 'no-store, private');
+        reply.header('x-robots-tag', 'noindex, nofollow');
+
+        const link = await verifyPreviewToken((request.query || {}).token, fastify.jwt);
+        if (!link) {
+            reply.status(404);
+            return reply.type('text/html').send(await render404('/_preview'));
+        }
+
+        const page = await getPage(link.urlPath);
+        if (!page) {
+            reply.status(404);
+            return reply.type('text/html').send(await render404(link.urlPath));
+        }
+
+        // A disabled project stays a hard kill switch. A share link narrows who
+        // may see one page; it is not a way around taking a whole project down.
+        const project = await getProjectForPage(page.urlPath || link.urlPath, page.project);
+        if (!(await isProjectEnabled(project))) {
+            reply.status(404);
+            return reply.type('text/html').send(await render404(link.urlPath));
+        }
+
+        // Rendered as anonymous on purpose: the recipient has no account, so
+        // menus and role-gated shortcodes must show them the least, not the
+        // most. The token satisfies this page's own gate and nothing else.
+        await touchPreviewLink(link.id);
+        const html = await renderPage(page, {
+            baseUrl: getBaseUrl(request),
+            user: null,
+            preview: {
+                status: page.status || 'draft',
+                urlPath: page.urlPath || link.urlPath,
+                shared: {expiresAt: link.expiresAt, label: link.label}
+            }
+        });
+        return reply.type('text/html').send(html);
+    });
+
     // Public pages catch-all
     fastify.get('/*', async (request, reply) => {
         const rawPath = request.params['*'];
@@ -103,12 +164,6 @@ export async function publicRoutes(fastify) {
             return reply.type('text/html').send(await render404(urlPath));
         }
 
-        // Don't serve draft pages publicly
-        if (page.status !== 'published') {
-            reply.status(404);
-            return reply.type('text/html').send(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);
@@ -117,14 +172,21 @@ export async function publicRoutes(fastify) {
             return reply.type('text/html').send(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 - role only resolved for gated pages,
         // so public pages share a single cache entry keyed `roleanon`.
         //
         // `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 JWT verification entirely so anonymous traffic hits
-        // the shared cache without auth cost.
+        // '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.
         // For per-role cache keying we use the primary role only - multi-role
         // users still see correctly-gated content (checkVisibility consults
         // additionalRoles too) but the cache key stays bounded to one entry
@@ -139,45 +201,74 @@ export async function publicRoutes(fastify) {
             || vis === 'public'
             || (Array.isArray(vis) && (vis.length === 0 || vis.includes('public')));
 
-        if (!isPublic) {
-            try {
-                const decoded = await request.jwtVerify();
-                if (decoded.type === 'access') {
-                    userRole = decoded.role;
-                    userObj  = { role: decoded.role, additionalRoles: decoded.additionalRoles || [] };
-                }
-            } catch { /* no token - treat as unauthenticated */ }
-
-            if (!checkVisibility(userObj, vis)) {
-                reply.status(403);
-                return reply.type('text/html').send(accessDeniedHtml(urlPath));
-            }
+        // A draft always needs the viewer resolved, whatever its visibility.
+        if (isDraft || !isPublic) {
+            userObj  = await resolveViewer(request);
+            userRole = userObj ? userObj.role : null;
+        }
+
+        if (isDraft && !canPreviewDrafts(userObj)) {
+            reply.status(404);
+            return reply.type('text/html').send(await render404(urlPath));
+        }
+
+        if (!isPublic && !checkVisibility(userObj, vis)) {
+            reply.status(403);
+            return reply.type('text/html').send(accessDeniedHtml(urlPath));
         }
 
         const baseUrl = getBaseUrl(request);
+
+        // Re-parse with user context so the body's [menu] shortcode sees the
+        // visitor's role for visibility filtering. The first getPage() above
+        // was anonymous because we hadn't resolved the viewer yet.
+        const render = async () => {
+            const pageForRole = await getPage(page.urlPath, {user: userObj}) || page;
+            return renderPage(pageForRole, {
+                baseUrl,
+                user: userObj,
+                ...(isDraft && {preview: {status: page.status || 'draft', urlPath: page.urlPath || urlPath, user: userObj}})
+            });
+        };
+
+        // A draft render is private to one viewer and changes on every editor
+        // save. It must never enter the shared response cache - an entry
+        // written here would be served to the next anonymous visitor under
+        // the same key - and must never be indexed.
+        if (isDraft) {
+            reply.header('cache-control', 'no-store, private');
+            reply.header('x-robots-tag', 'noindex, nofollow');
+            return reply.type('text/html').send(await render());
+        }
+
         // mtime in the key: any change to the backing file - editor save,
         // script, git pull - yields a fresh entry even if no invalidation
         // hook fired. Stale-mtime entries age out via TTL/LRU.
         const pageMtime = await getPageMtime(page.urlPath || urlPath);
         const cacheKey = `page:${urlPath}:m${pageMtime}:role${userRole ?? 'anon'}:o${baseUrl}`;
         const cacheTags = [`page:${urlPath}`, ...(page.cacheTags || []), 'nav', 'site'];
-        const html = await cache.wrap(
-            cacheKey,
-            async () => {
-                // Re-parse with user context so the body's [menu] shortcode
-                // sees the visitor's role for visibility filtering. The first
-                // getPage() above was anonymous because we hadn't decoded the
-                // JWT yet; this second pass uses the resolved userObj.
-                const pageForRole = await getPage(page.urlPath, {user: userObj}) || page;
-                return renderPage(pageForRole, {baseUrl, user: userObj});
-            },
-            {tags: cacheTags}
-        );
+        const html = await cache.wrap(cacheKey, render, {tags: cacheTags});
         hooks.emit('content:pageViewed', {urlPath, title: page.title || ''});
         return reply.type('text/html').send(html);
     });
 }
 
+/**
+ * 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/services/content.js

@@ -76,6 +76,33 @@ export async function getPage(urlPath, opts = {}) {
     }
 }
 
+/**
+ * Compose a page object from unsaved frontmatter and body, without touching
+ * disk.
+ *
+ * Deliberately runs the same `parseMarkdown` call as readPageFile() and
+ * returns the same shape, so the editor's full-page preview renders through
+ * the identical pipeline the public site would use on save. Anything that
+ * diverges here becomes a preview that lies.
+ *
+ * `urlPath` matters even for an unsaved page: `[menu location="…"]` and menu
+ * bindings resolve against it, so a preview of a page destined for
+ * /projects/x sees the menus that page will actually get.
+ *
+ * @param {string} urlPath
+ * @param {object} frontmatter
+ * @param {string} body
+ * @param {object} [opts]
+ * @param {object|null} [opts.user]
+ * @returns {Promise<object>} Same shape as getPage()
+ */
+export async function buildPreviewPage(urlPath, frontmatter, body, opts = {}) {
+    const raw = serialiseMarkdown({...(frontmatter || {})}, body || '');
+    const {data, content, html, usedComponents, tags} =
+        await parseMarkdown(raw, {user: opts.user || null, urlPath});
+    return {...data, urlPath, content, html, usedComponents, cacheTags: tags};
+}
+
 /**
  * Create a new page. Auto-creates parent directories.
  *

package/server/services/previewLinks.js

@@ -0,0 +1,215 @@
+/**
+ * Preview Links
+ *
+ * Revocable, expiring, single-page share links for unpublished content. They
+ * exist for the reviewer who has no account: a client, an external designer,
+ * a copywriter. The holder of the link sees exactly one page and nothing else.
+ *
+ * Why a server-side index rather than a bare signed token: a JWT alone cannot
+ * be withdrawn. Once a link is out it is out until it expires, and "I sent that
+ * to the wrong address" is precisely the moment you need it gone. Every token
+ * carries a `jti` that must still be present and unrevoked in the index, so
+ * revocation is immediate.
+ *
+ * The index lives at content/preview-links.json and is small by construction -
+ * expired records are pruned whenever it is written.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'node:crypto';
+import {config} from '../config.js';
+
+const STORE_PATH = path.join(config.content.contentDir, 'preview-links.json');
+
+/** Token type claim - a page-preview token must never satisfy an API guard. */
+export const PREVIEW_TOKEN_TYPE = 'page-preview';
+
+/** Expiry choices offered to the issuer, in seconds. */
+export const EXPIRY_CHOICES = {
+    '1h':  3600,
+    '24h': 86_400,
+    '7d':  604_800,
+    '30d': 2_592_000
+};
+
+const DEFAULT_EXPIRY = EXPIRY_CHOICES['7d'];
+const MAX_EXPIRY     = EXPIRY_CHOICES['30d'];
+
+/**
+ * Read the link index. Missing or corrupt file yields an empty index rather
+ * than throwing - a broken store must not take the public site down, it must
+ * only mean no link validates.
+ *
+ * @returns {Promise<object[]>}
+ */
+async function readStore() {
+    try {
+        const raw = await fs.readFile(STORE_PATH, 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Write the index, dropping records that expired more than a day ago.
+ *
+ * @param {object[]} links
+ * @returns {Promise<void>}
+ */
+async function writeStore(links) {
+    const cutoff = Date.now() - 86_400_000;
+    const kept = links.filter(l => new Date(l.expiresAt).getTime() > cutoff);
+    await fs.mkdir(path.dirname(STORE_PATH), {recursive: true});
+    await fs.writeFile(STORE_PATH, JSON.stringify(kept, null, 2), 'utf8');
+}
+
+/**
+ * Normalise a requested lifetime to a whole number of seconds within bounds.
+ *
+ * @param {string|number} [requested] - A key of EXPIRY_CHOICES or seconds
+ * @returns {number}
+ */
+export function resolveExpirySeconds(requested) {
+    if (typeof requested === 'string' && requested in EXPIRY_CHOICES) {
+        return EXPIRY_CHOICES[requested];
+    }
+    const n = Number(requested);
+    if (Number.isFinite(n) && n > 0) return Math.min(Math.floor(n), MAX_EXPIRY);
+    return DEFAULT_EXPIRY;
+}
+
+/**
+ * Mint a share link for one page.
+ *
+ * @param {object} params
+ * @param {string} params.urlPath          - Page the link unlocks; nothing else
+ * @param {object} params.jwt              - fastify.jwt
+ * @param {string} [params.label]          - Free-text note for the issuer's own use
+ * @param {string} [params.createdBy]      - Issuing user's id
+ * @param {string} [params.createdByName]  - Issuing user's display name
+ * @param {string|number} [params.expiresIn]
+ * @returns {Promise<{id: string, token: string, urlPath: string, expiresAt: string, label: string}>}
+ */
+export async function createPreviewLink({urlPath, jwt, label = '', createdBy = null, createdByName = '', expiresIn}) {
+    if (!urlPath || typeof urlPath !== 'string' || !urlPath.startsWith('/')) {
+        throw new Error('A urlPath beginning with / is required');
+    }
+    const seconds   = resolveExpirySeconds(expiresIn);
+    const id        = crypto.randomUUID();
+    const createdAt = new Date().toISOString();
+    const expiresAt = new Date(Date.now() + seconds * 1000).toISOString();
+
+    // The page is named in the token, so a holder cannot repoint it, and the
+    // index is consulted on every use, so it can be withdrawn.
+    const token = jwt.sign({type: PREVIEW_TOKEN_TYPE, jti: id, urlPath}, {expiresIn: seconds});
+
+    const links = await readStore();
+    links.push({
+        id, urlPath, label: String(label || '').slice(0, 200),
+        createdBy, createdByName: String(createdByName || '').slice(0, 120),
+        createdAt, expiresAt, revokedAt: null, lastUsedAt: null, useCount: 0
+    });
+    await writeStore(links);
+
+    return {id, token, urlPath, expiresAt, label};
+}
+
+/**
+ * List links, newest first. Optionally filtered to one page.
+ *
+ * @param {string} [urlPath]
+ * @returns {Promise<object[]>}
+ */
+export async function listPreviewLinks(urlPath) {
+    const links = await readStore();
+    const filtered = urlPath ? links.filter(l => l.urlPath === urlPath) : links;
+    return filtered
+        .map(l => ({...l, expired: new Date(l.expiresAt).getTime() <= Date.now()}))
+        .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+}
+
+/**
+ * Revoke a link. Idempotent; returns false when the id is unknown.
+ *
+ * @param {string} id
+ * @returns {Promise<boolean>}
+ */
+export async function revokePreviewLink(id) {
+    const links = await readStore();
+    const link = links.find(l => l.id === id);
+    if (!link) return false;
+    link.revokedAt = link.revokedAt || new Date().toISOString();
+    await writeStore(links);
+    return true;
+}
+
+/**
+ * Verify a share token and return the page it unlocks.
+ *
+ * Every check is a separate reason to refuse: a bad signature, the wrong token
+ * type (an access token must not double as a share link, nor the reverse), an
+ * expired `exp`, an unknown `jti`, a revoked record, an index expiry that has
+ * passed, or a token whose `urlPath` no longer matches the record it names.
+ *
+ * @param {string} token
+ * @param {object} jwt - fastify.jwt
+ * @returns {Promise<{urlPath: string, id: string, expiresAt: string, label: string}|null>}
+ */
+export async function verifyPreviewToken(token, jwt) {
+    if (!token || typeof token !== 'string') return null;
+
+    let payload;
+    try {
+        payload = jwt.verify(token);
+    } catch {
+        return null;
+    }
+    if (payload?.type !== PREVIEW_TOKEN_TYPE || !payload.jti || !payload.urlPath) return null;
+
+    const links = await readStore();
+    const link = links.find(l => l.id === payload.jti);
+    if (!link) return null;
+    if (link.revokedAt) return null;
+    if (link.urlPath !== payload.urlPath) return null;
+    if (new Date(link.expiresAt).getTime() <= Date.now()) return null;
+
+    return {urlPath: link.urlPath, id: link.id, expiresAt: link.expiresAt, label: link.label || ''};
+}
+
+/**
+ * Record a use of a link. Best-effort - a failure to write the counter must
+ * never deny an otherwise valid preview.
+ *
+ * @param {string} id
+ * @returns {Promise<void>}
+ */
+export async function touchPreviewLink(id) {
+    try {
+        const links = await readStore();
+        const link = links.find(l => l.id === id);
+        if (!link) return;
+        link.lastUsedAt = new Date().toISOString();
+        link.useCount = (link.useCount || 0) + 1;
+        await writeStore(links);
+    } catch { /* counters are not load-bearing */ }
+}
+
+/**
+ * Drop every link for a page - used when the page is deleted or renamed, so a
+ * link cannot outlive the thing it pointed at.
+ *
+ * @param {string} urlPath
+ * @returns {Promise<number>} how many were removed
+ */
+export async function deletePreviewLinksForPage(urlPath) {
+    const links = await readStore();
+    const remaining = links.filter(l => l.urlPath !== urlPath);
+    const removed = links.length - remaining.length;
+    if (removed) await writeStore(remaining);
+    return removed;
+}
+
+/** Absolute path of the backing store - exported for tests. */
+export const storePath = STORE_PATH;