Add pages API: model, controller, routes, preview (steps 4/6/7/8)

Backend for the CMS page builder, all under the existing /api/v1:

- pages.model: authoritative save gate — validates blocks against the
  registry and sanitizes them on every create/update; maps rows to/from the
  grouped API shape (metadata / settings); slug validated + reserved-checked
  at create and immutable after; `protected` can be set true via PATCH but
  only cleared via the unprotect path; published_at stamped on first publish.
- sanitizeBlocks: post-validation normalizer (applies each block's sanitize,
  stamps version, defaults visible, recurses container slots).
- reservedSlugs: guards page slugs from shadowing named routes/API namespaces.
- Admin routes (staff-gated): GET/POST /pages, GET/PATCH/DELETE /pages/:id,
  POST /pages/:id/unprotect (password step-up, verified against the caller's
  own hash, never logged), POST /pages/:id/preview (1h token). Audit-logs
  create/publish/unpublish/protect/unprotect/delete.
- Public routes: GET /public/pages/:slug (published; staff see drafts; site-
  mode gated) and GET /public/pages/:id/preview/:token (ungated, token is the
  access control). Preview token primitives added to auth/token.js.
- Swagger annotations for all new endpoints.

Verified end-to-end: model integration test against the dev DB (sanitize,
invalid-block rejection, slug immutability, protected/unprotect, dup/reserved
slug, published_at) + authenticated HTTP smoke (201 create, 400 invalid
blocks, publish, public slug fetch, preview mint+fetch, 403 delete-protected,
401 wrong-password unprotect).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

server/src/router/v1/public/public.controller.js

@@ -1,10 +1,21 @@
 const posts = require('../../../model/posts/posts.model')
 const wiki = require('../../../model/wiki/wiki.model')
 const settings = require('../../../model/settings/settings.model')
+const pages = require('../../../model/pages/pages.model')
 const mailer = require('../../../utils/mailer')
+const { getUserFromRequest } = require('../../../utils/auth')
+const token = require('../../../auth/token')
 
 const log = require('../../../utils/logger')('public')
 
+// Staff (non-player) roles may see draft pages on the public route; everyone else
+// gets a 404 for a draft, indistinguishable from a missing page.
+const STAFF_ROLES = ['admin', 'editor', 'moderator']
+function isStaff(req) {
+  const user = getUserFromRequest(req)
+  return Boolean(user && STAFF_ROLES.includes(user.role))
+}
+
 async function getSettings(req, res) {
   try {
     return res.json(await settings.getPublic())
@@ -100,6 +111,34 @@ async function getWikiPage(req, res) {
   }
 }
 
+async function getPage(req, res) {
+  try {
+    // Staff see drafts (live preview); the public sees published pages only.
+    const page = await pages.getBySlug(req.params.slug, { includeUnpublished: isStaff(req) })
+    if (!page) return res.status(404).json({ message: 'Not found' })
+    return res.json(page)
+  } catch (err) {
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// Token-gated draft preview: renders the page's current block state regardless of
+// status, for anyone holding the (short-lived, unguessable) link.
+async function getPagePreview(req, res) {
+  try {
+    const id = Number(req.params.id)
+    const decoded = token.verifyPagePreview(req.params.token)
+    if (!decoded || decoded.pageId !== id) {
+      return res.status(404).json({ message: 'Preview not found or expired' })
+    }
+    const page = await pages.getById(id)
+    if (!page) return res.status(404).json({ message: 'Not found' })
+    return res.json(page)
+  } catch (err) {
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
 async function contact(req, res) {
   const { name, email, message } = req.body
   try {
@@ -120,5 +159,7 @@ module.exports = {
   getWikiTags,
   getWikiList,
   getWikiPage,
+  getPage,
+  getPagePreview,
   contact,
 }

server/src/router/v1/public/public.routes.js

@@ -102,4 +102,30 @@ publicRouter.get(
   ctrl.getWikiPage,
 )
 
+// ── CMS pages (block-based) ────────────────────────────────────────────
+// Preview is registered before /pages/:slug and is NOT site-mode gated, so a
+// draft-preview link keeps working during maintenance. The token itself is the
+// access control.
+publicRouter.get(
+  '/pages/:id/preview/:token',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Render a page from a draft-preview token'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Page id.' }
+  // #swagger.parameters['token'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Preview token from POST /admin/pages/:id/preview.' }
+  /* #swagger.responses[200] = { description: 'The page (any status)', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[404] = { description: 'Token invalid/expired or page missing', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.getPagePreview,
+)
+publicRouter.get(
+  '/pages/:slug',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Get a published CMS page by slug'
+  // #swagger.description = 'Drafts 404 for the public; staff sessions see drafts. Gated by site mode.'
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page slug.' }
+  /* #swagger.responses[200] = { description: 'The page', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  siteMode,
+  ctrl.getPage,
+)
+
 module.exports = publicRouter