@invisibleloop/pulse 0.17.2 → 0.18.0

package/src/agent/guide-server.md

@@ -102,6 +102,40 @@ actions: {
 ```
 `_storeUpdate` is stripped from local page state — it is only forwarded to the store. The rest of `onSuccess` merges into the page's own state as normal.
 
+## Server-side forms — `spec.submit` (works without client JS)
+
+A spec with a `submit` handler accepts POST on its own route. The form works with JavaScript disabled — hydrated `actions` become an enhancement, not a requirement.
+
+```js
+export default {
+  route: '/contact',
+  submit: async (ctx) => {
+    const data = await ctx.formData()
+    if (!data?.email)        return { errors: { email: 'Email is required' }, values: data ?? {} }
+    if (!isValid(data.email)) return { status: 422, errors: { email: 'Invalid email' }, values: data }
+    await sendMessage(data)
+    return { redirect: '/contact?sent=1' }   // 303 POST-redirect-GET
+  },
+  view: (state, server) => `
+    <main id="main-content">
+      ${server.form?.errors?.email ? `<p class="error">${escHtml(server.form.errors.email)}</p>` : ''}
+      <form method="POST">
+        ${server.csrf}
+        ${input({ label: 'Email', name: 'email', type: 'email', required: true, value: server.form?.values?.email ?? '' })}
+        ${button({ label: 'Send', type: 'submit' })}
+      </form>
+    </main>`,
+}
+```
+
+**Rules:**
+- `${server.csrf}` **must be inside every POST form** — CSRF protection is automatic and POSTs without a valid token are rejected with 403. Opt out with `csrf: false` only for endpoints with their own authentication (e.g. signed webhooks).
+- `{ redirect }` → 303 See Other. Always redirect after a successful mutation — rendering success directly from the POST means refresh resubmits the form.
+- Any other return value re-renders the page with it exposed as `server.form` — put `errors` and the submitted `values` there, and echo values back into inputs so failed validation doesn't wipe what the user typed. An optional `status` field sets the response status (e.g. 422).
+- Escape user-submitted values before interpolating them into HTML (`escHtml`).
+- **Progressive enhancement:** add `data-action="send"` to the same form — hydrated visitors get the async action with no page reload; no-JS visitors fall back to the POST.
+- Multi-instance deployments: pass a stable `secret` to `createServer` (e.g. from an env var) so CSRF tokens issued by one instance validate on another.
+
 ## Server context — redirects, cookies, POST bodies
 
 The `ctx` object is available in `guard`, `server.*` fetchers, and `meta` functions.

package/src/agent/guide-spec.md

@@ -46,10 +46,31 @@ export default {
     // Resolved server-side before render. Passed to view() as second arg.
     posts: async () => fetchPostsFromDb(),
   },
+  // Server-side form handling — POST works with JavaScript disabled.
+  // { redirect } → 303 PRG; anything else → re-render with the value as server.form.
+  // CSRF enforced automatically: the view MUST include ${server.csrf} inside the <form>.
+  submit: async (ctx) => {
+    const data = await ctx.formData()
+    if (!data?.email) return { errors: { email: 'Required' }, values: data ?? {} }
+    await save(data)
+    return { redirect: '/thanks' }
+  },
   view: (state, serverState) => `<h1>${state.title}</h1>`,
 }
 ```
 
+## Server-side forms (`submit`)
+
+- A spec with `submit` accepts POST on its own route — plain `<form method="POST">`, no client JS needed.
+- **Always put `${server.csrf}` inside the form** — it renders the hidden CSRF input. POSTs without a valid token are rejected with 403. (`csrf: false` opts out — only for endpoints with their own auth.)
+- `server.form` holds the return value of `submit()` on a re-render: show `server.form?.errors`, echo `server.form?.values` back into inputs via `value=` so failed validation doesn't wipe the form.
+- After a successful mutation always `return { redirect: '/path' }` (POST-redirect-GET) — never render success from the POST itself. An optional `status` field on a re-render return sets the response status (e.g. 422).
+- Progressive enhancement: the same form can also have `data-action="name"` — hydrated visitors get the async action, no-JS visitors use the POST.
+
+## Custom not-found page
+
+A spec with `route: '*'` renders with **status 404** whenever no route matches — same pipeline as any page (layout, styles, hydration, validation). Every site should have one; the default framework 404 is unbranded.
+
 ## Streaming SSR — shell + deferred segments
 
 Use streaming when a page has slow data and you want the shell to paint instantly while slower content streams in.

package/src/runtime/ssr.js

@@ -36,7 +36,7 @@ export async function renderToString(spec, ctx = {}, pageState = {}) {
   const serverState = await resolveServerState(spec, ctx)
 
   // Merge declared store keys into server state — store keys lose to page-level keys
-  const mergedServerState = mergeStoreKeys(spec, serverState, ctx.store)
+  const mergedServerState = applyCtxExtras(mergeStoreKeys(spec, serverState, ctx.store), ctx)
 
   const tData = performance.now()
 
@@ -105,7 +105,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
 
       // Await only the fetchers the shell segments need
       const shellServerState = await awaitFetchersForSegments(spec, shell, fetcherCache)
-      const mergedShellState = mergeStoreKeys(spec, shellServerState, ctx.store)
+      const mergedShellState = applyCtxExtras(mergeStoreKeys(spec, shellServerState, ctx.store), ctx)
 
       // Write shell immediately — deferred fetchers may still be in-flight
       const shellHtml = renderNamedSegments(spec, shell, clientState, mergedShellState)
@@ -122,7 +122,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
         // Promise.all runs them concurrently — the fastest segment wins.
         await Promise.all(deferred.map(async (key) => {
           const segServerState = await awaitFetchersForSegments(spec, [key], fetcherCache)
-          const mergedSegState = mergeStoreKeys(spec, segServerState, ctx.store)
+          const mergedSegState = applyCtxExtras(mergeStoreKeys(spec, segServerState, ctx.store), ctx)
           const segHtml        = renderNamedSegments(spec, [key], clientState, mergedSegState)
 
           // Inline script replaces the placeholder with the rendered content
@@ -145,7 +145,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
       const allServerState = fetcherCache.size > 0
         ? Object.fromEntries(await Promise.all([...fetcherCache.entries()].map(async ([k, p]) => [k, await p])))
         : {}
-      const mergedAllState = mergeStoreKeys(spec, allServerState, ctx.store)
+      const mergedAllState = applyCtxExtras(mergeStoreKeys(spec, allServerState, ctx.store), ctx)
       if (spec.hydrate && Object.keys(mergedAllState).length > 0) {
         controller.enqueue(encode(
           `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(mergedAllState)};</script>`
@@ -218,7 +218,7 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
 
       // 2. Await shell fetchers then send shell HTML
       const shellServerState = await awaitFetchersForSegments(spec, shell, fetcherCache)
-      const mergedShellState = mergeStoreKeys(spec, shellServerState, ctx.store)
+      const mergedShellState = applyCtxExtras(mergeStoreKeys(spec, shellServerState, ctx.store), ctx)
       let shellHtml = renderNamedSegments(spec, shell, clientState, mergedShellState)
 
       // Append <pulse-deferred> placeholders so the client knows where to inject deferred content
@@ -231,7 +231,7 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
       // 3. Stream each deferred segment as soon as its own fetchers resolve
       await Promise.all(deferred.map(async (key) => {
         const segServerState = await awaitFetchersForSegments(spec, [key], fetcherCache)
-        const mergedSegState = mergeStoreKeys(spec, segServerState, ctx.store)
+        const mergedSegState = applyCtxExtras(mergeStoreKeys(spec, segServerState, ctx.store), ctx)
         const segHtml        = renderNamedSegments(spec, [key], clientState, mergedSegState)
         writeLine({ type: 'deferred', id: key, html: segHtml })
       }))
@@ -240,7 +240,7 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
       const allServerState = fetcherCache.size > 0
         ? Object.fromEntries(await Promise.all([...fetcherCache.entries()].map(async ([k, p]) => [k, await p])))
         : {}
-      const mergedAll = mergeStoreKeys(spec, allServerState, ctx.store)
+      const mergedAll = applyCtxExtras(mergeStoreKeys(spec, allServerState, ctx.store), ctx)
 
       writeLine({
         type:        'done',
@@ -426,6 +426,29 @@ function mergeStoreKeys(spec, serverState, storeState) {
   return { ...slice, ...serverState }
 }
 
+/**
+ * Merge per-request extras set by the server into the view's server state:
+ *
+ *   ctx._form      → serverState.form  — the return value of spec.submit() on a
+ *                    POST re-render (validation errors, submitted values, etc.)
+ *   ctx._csrfField → serverState.csrf  — ready-to-embed hidden <input> for CSRF;
+ *                    views include it inside <form method="POST"> as ${server.csrf}
+ *
+ * Only set by the server for specs that declare `submit` — other pages see
+ * neither key. Explicit server fetcher keys with the same names win.
+ *
+ * @param {Object} serverState
+ * @param {Object} ctx
+ * @returns {Object}
+ */
+function applyCtxExtras(serverState, ctx) {
+  if (ctx?._form === undefined && ctx?._csrfField === undefined) return serverState
+  const extras = {}
+  if (ctx._form      !== undefined) extras.form = ctx._form
+  if (ctx._csrfField !== undefined) extras.csrf = ctx._csrfField
+  return { ...extras, ...serverState }
+}
+
 // ---------------------------------------------------------------------------
 // Internal — server state resolution
 // ---------------------------------------------------------------------------

package/src/server/index.js

@@ -367,12 +367,14 @@ function buildCacheKey(spec, ctx) {
  *   - spec.stream.deferred    — deferred segments inject content via inline <script nonce="...">
  *                               tags; caching bakes in one nonce while subsequent CSP headers
  *                               carry a different nonce, causing a violation
+ *   - spec.submit             — form pages embed a per-visitor CSRF token; caching
+ *                               would serve one visitor's token to everyone
  *
  * In all these cases the cached HTML would contain a nonce that doesn't match
  * the nonce-free CSP used for cached responses, causing a CSP violation.
  */
 function isCacheablePage(spec) {
-  return !spec.server && !spec.store?.length && !spec.hydrate && !spec.stream?.deferred?.length
+  return !spec.server && !spec.store?.length && !spec.hydrate && !spec.stream?.deferred?.length && !spec.submit
 }
 
 // ---------------------------------------------------------------------------
@@ -542,6 +544,13 @@ export async function createServer(entries, options = {}) {
     shutdownTimeout = 30000,        // ms to wait for in-flight requests before force-exit
     healthCheck    = '/healthz',    // path for health check endpoint, or false to disable
     csp            = {},            // extra CSP sources: { 'style-src': ['https://fonts.googleapis.com'] }
+    secret         = null,          // HMAC secret for CSRF tokens — set a stable value when running
+                                    // multiple instances; defaults to a random per-boot secret
+    sitemap        = false,         // true | { origin } — auto-serve /sitemap.xml + robots.txt from
+                                    // the registered routes. Dynamic :param routes contribute via
+                                    // spec.sitemap = async () => ['/blog/a', ...]
+    robots         = null,          // robots.txt content when sitemap is enabled:
+                                    // null = auto-generate, false = disable, string = serve verbatim
     onError        = (err, req, res) => defaultErrorHandler(err, req, res, dev),
     onRequest,
     agentMode      = false,        // show agent-active indicator in banner
@@ -585,8 +594,8 @@ export async function createServer(entries, options = {}) {
     const routeErrors = []
     if (!spec.route || typeof spec.route !== 'string') {
       routeErrors.push('spec.route is required and must be a string (e.g. "/contact")')
-    } else if (!spec.route.startsWith('/')) {
-      routeErrors.push('spec.route must start with "/" (e.g. "/contact")')
+    } else if (!spec.route.startsWith('/') && spec.route !== '*') {
+      routeErrors.push('spec.route must start with "/" (e.g. "/contact"), or be "*" for the custom not-found page')
     }
     const allErrors = [...errors, ...routeErrors]
     if (!valid || routeErrors.length > 0) {
@@ -597,8 +606,32 @@ export async function createServer(entries, options = {}) {
     }
   }
 
-  // Build route table — let so it can be swapped on hot reload
-  let router = buildRouter(specs)
+  // Custom not-found page — a spec with route '*' renders (with status 404)
+  // whenever no route matches. It goes through the normal render pipeline, so
+  // it gets the site's layout, styles, hydration, and validation like any page.
+  let notFoundSpec = specs.find(s => s.route === '*') || null
+
+  // Build route table — let so it can be swapped on hot reload.
+  // The '*' spec is excluded: it is not a route, it is the fallback.
+  let router = buildRouter(specs.filter(s => s.route !== '*'))
+
+  // CSRF secret — per-boot random unless pinned via options.secret. Tokens are
+  // tied to a cookie, so a restart only means in-flight forms re-render once.
+  const csrfSecret = secret || crypto.randomBytes(32).toString('hex')
+
+  // Sitemap — track the live spec list (updated on hot reload) and surface a
+  // startup hint for dynamic routes that can't be enumerated automatically.
+  const sitemapEnabled = !!sitemap
+  const sitemapOrigin  = (typeof sitemap === 'object' && sitemap?.origin) ? String(sitemap.origin).replace(/\/$/, '') : null
+  let   allSpecs       = specs
+  if (sitemapEnabled && !quiet) {
+    const unenumerated = specs.filter(s =>
+      !s.contentType && s.route !== '*' && s.route.includes(':') && s.sitemap === undefined
+    )
+    if (unenumerated.length > 0) {
+      console.log(`  ℹ sitemap: ${unenumerated.length} dynamic route${unenumerated.length === 1 ? '' : 's'} not in the sitemap — add \`sitemap: async () => ['/path', …]\` to enumerate: ${unenumerated.map(s => s.route).join(', ')}`)
+    }
+  }
 
   // Resolve the logger module once at startup rather than dynamically importing
   // it on every request's `finish` event. `logRequest` stays null until loaded.
@@ -644,6 +677,39 @@ export async function createServer(entries, options = {}) {
         if (served) return
       }
 
+      // Auto-generated sitemap.xml + robots.txt — after static serving so a
+      // physical file in staticDir always wins over the generated one.
+      if (sitemapEnabled && (req.method === 'GET' || req.method === 'HEAD') &&
+          (pathname === '/sitemap.xml' || (pathname === '/robots.txt' && robots !== false))) {
+        const origin = sitemapOrigin ||
+          `${req.headers['x-forwarded-proto'] || 'http'}://${req.headers['x-forwarded-host'] || req.headers.host || `localhost:${port}`}`
+
+        let body, contentType
+        if (pathname === '/robots.txt') {
+          contentType = 'text/plain; charset=utf-8'
+          body = typeof robots === 'string'
+            ? robots
+            : `User-agent: *\nAllow: /\n\nSitemap: ${origin}/sitemap.xml\n`
+        } else {
+          contentType = 'application/xml; charset=utf-8'
+          const entries = await collectSitemapEntries(allSpecs, trailingSlash)
+          body = buildSitemapXml(entries, origin)
+        }
+
+        const encoding = negotiateEncoding(req)
+        const buf      = await compressBuffer(Buffer.from(body, 'utf8'), encoding)
+        const headers  = {
+          'Content-Type':  contentType,
+          'Cache-Control': dev ? 'no-store' : 'public, max-age=3600',
+          'Vary':          'Accept-Encoding',
+          ...SECURITY_HEADERS, ...httpsHeaders(req),
+        }
+        if (encoding) headers['Content-Encoding'] = encoding
+        res.writeHead(200, headers)
+        res.end(req.method === 'HEAD' ? undefined : buf)
+        return
+      }
+
       // Trailing slash normalisation — GET/HEAD only (redirects don't apply to POST etc.)
       if ((req.method === 'GET' || req.method === 'HEAD') && pathname !== '/') {
         if (trailingSlash === 'remove' && pathname.endsWith('/')) {
@@ -662,20 +728,32 @@ export async function createServer(entries, options = {}) {
       }
 
       // Match route
-      const match = matchRoute(router, pathname)
+      let match          = matchRoute(router, pathname)
+      let responseStatus = 200
 
       if (!match) {
-        res.writeHead(404, { 'Content-Type': 'text/html', ...SECURITY_HEADERS, ...httpsHeaders(req) })
-        res.end(notFoundHtml(pathname))
-        return
+        // Custom not-found page — a '*' spec renders through the normal pipeline
+        // with status 404, so the site's branded 404 gets layout, styles, and
+        // hydration like any other page. Client-side navigation requests still
+        // get the plain 404 (navigate.js falls back to a full page load, which
+        // then renders the custom page).
+        if (notFoundSpec && (req.method === 'GET' || req.method === 'HEAD') && req.headers['x-pulse-navigate'] !== 'true') {
+          match          = { spec: notFoundSpec, params: {} }
+          responseStatus = 404
+        } else {
+          res.writeHead(404, { 'Content-Type': 'text/html', ...SECURITY_HEADERS, ...httpsHeaders(req) })
+          res.end(notFoundHtml(pathname))
+          return
+        }
       }
 
       // Method gating — raw response specs accept any HTTP method.
-      // Page specs default to GET/HEAD only; opt in to other methods via spec.methods.
+      // Page specs default to GET/HEAD only; spec.submit adds POST automatically;
+      // opt in to other methods via spec.methods.
       if (!match.spec.contentType) {
         const allowed = match.spec.methods
           ? match.spec.methods.map(m => m.toUpperCase())
-          : ['GET', 'HEAD']
+          : (typeof match.spec.submit === 'function' ? ['GET', 'HEAD', 'POST'] : ['GET', 'HEAD'])
         if (!allowed.includes(req.method)) {
           res.writeHead(405, {
             'Content-Type': 'text/plain',
@@ -738,6 +816,57 @@ export async function createServer(entries, options = {}) {
         }
       }
 
+      // -----------------------------------------------------------------------
+      // CSRF — specs with a `submit` handler get token protection automatically
+      // (opt out per spec with csrf: false, e.g. for token-authenticated routes).
+      // Double-submit pattern: an HttpOnly cookie holds a random id; the form
+      // carries HMAC(secret, id) in a hidden _csrf field; POST verifies the pair.
+      // Views embed the field inside <form method="POST"> as ${server.csrf}.
+      // -----------------------------------------------------------------------
+      if (typeof spec.submit === 'function' && spec.csrf !== false) {
+        let csrfId = ctx.cookies.pulse_csrf
+        if (!csrfId) {
+          csrfId = crypto.randomBytes(16).toString('base64url')
+          ctx.setCookie('pulse_csrf', csrfId, { httpOnly: true, sameSite: 'Lax', path: '/' })
+        }
+        ctx._csrfField = `<input type="hidden" name="_csrf" value="${csrfToken(csrfSecret, csrfId)}">`
+
+        if (req.method === 'POST') {
+          const form      = await ctx.formData()
+          const submitted = typeof form?._csrf === 'string' ? form._csrf : ''
+          const cookieId  = ctx.cookies.pulse_csrf
+          if (!cookieId || !safeEqual(submitted, csrfToken(csrfSecret, cookieId))) {
+            res.writeHead(403, mergeCtxHeaders(ctx, {
+              'Content-Type': 'text/plain',
+              ...SECURITY_HEADERS, ...httpsHeaders(req),
+            }))
+            res.end('Invalid or missing CSRF token. Reload the page and resubmit the form.')
+            return
+          }
+        }
+      }
+
+      // -----------------------------------------------------------------------
+      // Server-side form handling — spec.submit handles POST without client JS.
+      //   { redirect: '/path' }  → 303 See Other (POST-redirect-GET)
+      //   anything else          → re-render the page; the return value appears
+      //                            in the view as serverState.form (errors,
+      //                            submitted values, etc.). Optional status field
+      //                            sets the response status (e.g. 422).
+      // -----------------------------------------------------------------------
+      if (req.method === 'POST' && typeof spec.submit === 'function') {
+        const result = await spec.submit(ctx)
+        if (result?.redirect) {
+          res.writeHead(303, mergeCtxHeaders(ctx, { Location: result.redirect, ...SECURITY_HEADERS, ...httpsHeaders(req) }))
+          res.end()
+          return
+        }
+        ctx._form = result ?? {}
+        if (typeof result?.status === 'number') responseStatus = result.status
+        // POST re-renders always use the buffered path — the request body is
+        // consumed and streaming a form response has no benefit.
+      }
+
       // Derive the canonical base URL from the request.
       // Canonical path follows the trailingSlash mode so the <link> is consistent with redirects.
       // spec.meta.canonical (string or function) is resolved inside each handler, where serverState
@@ -776,7 +905,12 @@ export async function createServer(entries, options = {}) {
         return
       }
 
-      if (stream) {
+      // Non-200 renders (custom 404) and POST re-renders always use the buffered
+      // string path — they are small, must carry an explicit status, and POST
+      // bodies are already consumed.
+      if (responseStatus !== 200 || req.method === 'POST') {
+        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath, responseStatus)
+      } else if (stream) {
         await handleStreamResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath)
       } else {
         await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath)
@@ -865,7 +999,9 @@ export async function createServer(entries, options = {}) {
     server,
     shutdown,
     updateSpecs(newSpecs) {
-      router = buildRouter(newSpecs)
+      notFoundSpec = newSpecs.find(s => s.route === '*') || null
+      router       = buildRouter(newSpecs.filter(s => s.route !== '*'))
+      allSpecs     = newSpecs
     }
   }
 }
@@ -943,9 +1079,12 @@ async function handleNavStreamResponse(spec, ctx, req, res) {
  * Render to a complete string then send — simpler, easier to cache.
  * Checks the in-process page cache before rendering; stores result after.
  */
-async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null) {
+async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null, status = 200) {
   const cacheKey = buildCacheKey(spec, ctx)
-  const ttl      = isCacheablePage(spec) ? pageCacheTtl(spec, dev, defaultCache) : 0
+  // Never cache POST re-renders or non-200 responses (custom 404s) — POST output
+  // varies per submission and a cached 404 body would be served with a 200 later.
+  const cacheable = status === 200 && ctx.method !== 'POST' && isCacheablePage(spec)
+  const ttl       = cacheable ? pageCacheTtl(spec, dev, defaultCache) : 0
 
   let html, serverTimingValue, fromCache = false
 
@@ -984,7 +1123,7 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
   if (encoding)          headers['Content-Encoding'] = encoding
   if (serverTimingValue) headers['Server-Timing']    = serverTimingValue
 
-  res.writeHead(200, headers)
+  res.writeHead(status, headers)
   res.end(buf)
 }
 
@@ -1585,6 +1724,111 @@ function escHtml(str) {
     .replace(/'/g, '&#39;')
 }
 
+/**
+ * Collect sitemap entries from the registered specs.
+ *
+ * Inclusion rules:
+ *   - page specs with static routes are included automatically
+ *   - route '*' (not-found), raw content specs, and spec.sitemap === false are excluded
+ *   - guarded pages are excluded by default (likely auth-gated) — set spec.sitemap
+ *     to true/array/function to include them explicitly
+ *   - dynamic :param routes contribute only via spec.sitemap — an array of paths
+ *     or an async function returning one. Entries can be strings or
+ *     { path, lastmod } objects.
+ *
+ * @param {Array} specs
+ * @param {'remove'|'add'|'allow'} trailingSlash
+ * @returns {Promise<Array<{ path: string, lastmod?: string }>>}
+ */
+async function collectSitemapEntries(specs, trailingSlash) {
+  const entries = []
+
+  const normalise = (item) => {
+    const e = typeof item === 'string' ? { path: item } : { path: item?.path, lastmod: item?.lastmod }
+    if (!e.path || typeof e.path !== 'string' || !e.path.startsWith('/')) return null
+    // Apply the trailing-slash mode so sitemap URLs match the canonical form
+    if (e.path !== '/') {
+      if (trailingSlash === 'add'    && !e.path.endsWith('/')) e.path = e.path + '/'
+      if (trailingSlash !== 'add'    &&  e.path.endsWith('/')) e.path = e.path.slice(0, -1)
+    }
+    return e
+  }
+
+  for (const spec of specs) {
+    if (spec.contentType || spec.route === '*' || spec.sitemap === false) continue
+
+    const isDynamic = spec.route.includes(':')
+
+    if (typeof spec.sitemap === 'function') {
+      try {
+        const list = await spec.sitemap()
+        for (const item of (Array.isArray(list) ? list : [])) {
+          const e = normalise(item)
+          if (e) entries.push(e)
+        }
+      } catch (err) {
+        // An enumerator failure must not take down the whole sitemap
+        console.error(`[Pulse] sitemap enumerator for "${spec.route}" failed:`, err.message)
+      }
+      continue
+    }
+
+    if (Array.isArray(spec.sitemap)) {
+      for (const item of spec.sitemap) {
+        const e = normalise(item)
+        if (e) entries.push(e)
+      }
+      continue
+    }
+
+    if (isDynamic) continue                                          // no enumerator → skip
+    if (typeof spec.guard === 'function' && spec.sitemap !== true) continue  // auth-gated by default
+
+    const e = normalise(spec.route)
+    if (e) entries.push(e)
+  }
+
+  // Dedupe by path, preserving first occurrence (which may carry lastmod)
+  const seen = new Set()
+  return entries.filter(e => seen.has(e.path) ? false : (seen.add(e.path), true))
+}
+
+/** Escape a value for XML text content. */
+function escXml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+/** Build the sitemap XML document from collected entries. */
+function buildSitemapXml(entries, origin) {
+  const urls = entries.map(e => {
+    const lastmod = e.lastmod ? `\n    <lastmod>${escXml(e.lastmod)}</lastmod>` : ''
+    return `  <url>\n    <loc>${escXml(origin + e.path)}</loc>${lastmod}\n  </url>`
+  }).join('\n')
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`
+}
+
+/**
+ * Derive the CSRF token for a cookie id: HMAC-SHA256(secret, id), base64url.
+ * The token goes in the form's hidden _csrf field; the id stays in an HttpOnly
+ * cookie. An attacker on another origin can trigger the cookie being sent but
+ * cannot read it or compute the HMAC, so they cannot forge the pair.
+ */
+function csrfToken(secret, id) {
+  return crypto.createHmac('sha256', secret).update(String(id)).digest('base64url')
+}
+
+/** Constant-time string comparison — length mismatch returns false without throwing. */
+function safeEqual(a, b) {
+  const ba = Buffer.from(String(a))
+  const bb = Buffer.from(String(b))
+  return ba.length === bb.length && crypto.timingSafeEqual(ba, bb)
+}
+
 function notFoundHtml(pathname) {
   return `<!DOCTYPE html>
 <html lang="en">