@zenithbuild/cli 0.7.3 → 0.7.5

package/dist/preview.js

@@ -14,10 +14,17 @@ import { access, readFile } from 'node:fs/promises';
 import { extname, join, normalize, resolve, sep, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { appLocalRedirectLocation, imageEndpointPath, normalizeBasePath, routeCheckPath, stripBasePath } from './base-path.js';
-import { isConfigKeyExplicit, loadConfig, validateConfig } from './config.js';
+import { resolveBuildAdapter } from './adapters/resolve-adapter.js';
+import { isConfigKeyExplicit, isLoadedConfig, loadConfig, validateConfig } from './config.js';
 import { materializeImageMarkup } from './images/materialize.js';
 import { createImageRuntimePayload, injectImageRuntimePayload } from './images/payload.js';
 import { handleImageRequest } from './images/service.js';
+import { readRequestBodyBuffer } from './request-body.js';
+import { createTrustedOriginResolver } from './request-origin.js';
+import { buildResourceResponseDescriptor } from './resource-response.js';
+import { loadResourceRouteManifest } from './resource-manifest.js';
+import { supportsTargetRouteCheck } from './route-check-support.js';
+import { clientFacingRouteMessage, defaultRouteDenyMessage, logServerException, sanitizeRouteResult } from './server-error.js';
 import { createSilentLogger } from './ui/logger.js';
 import { compareRouteSpecificity, matchRoute as matchManifestRoute, resolveRequestRoute } from './server/resolve-request-route.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -34,6 +41,13 @@ const MIME_TYPES = {
     '.avif': 'image/avif',
     '.gif': 'image/gif'
 };
+const IMAGE_RUNTIME_TAG_RE = /<script\b[^>]*\bid=(["'])zenith-image-runtime\1[^>]*>[\s\S]*?<\/script>/i;
+function appendSetCookieHeaders(headers, setCookies = []) {
+    if (Array.isArray(setCookies) && setCookies.length > 0) {
+        headers['Set-Cookie'] = setCookies.slice();
+    }
+    return headers;
+}
 const SERVER_SCRIPT_RUNNER = String.raw `
 import vm from 'node:vm';
 import fs from 'node:fs/promises';
@@ -49,6 +63,7 @@ const requestHeaders = JSON.parse(process.env.ZENITH_SERVER_REQUEST_HEADERS || '
 const routePattern = process.env.ZENITH_SERVER_ROUTE_PATTERN || '';
 const routeFile = process.env.ZENITH_SERVER_ROUTE_FILE || sourcePath || '';
 const routeId = process.env.ZENITH_SERVER_ROUTE_ID || routePattern || '';
+const routeKind = process.env.ZENITH_SERVER_ROUTE_KIND || 'page';
 const guardOnly = process.env.ZENITH_SERVER_GUARD_ONLY === '1';
 
 if (!source.trim()) {
@@ -203,17 +218,55 @@ function ctxDeny(status = 403, message = undefined) {
     message: typeof message === 'string' ? message : undefined
   };
 }
+function ctxInvalid(payload, status = 400) {
+  return {
+    kind: 'invalid',
+    data: payload,
+    status: Number.isInteger(status) ? status : 400
+  };
+}
 function ctxData(payload) {
   return {
     kind: 'data',
     data: payload
   };
 }
+function ctxJson(payload, status = 200) {
+  return {
+    kind: 'json',
+    data: payload,
+    status: Number.isInteger(status) ? status : 200
+  };
+}
+function ctxText(body, status = 200) {
+  return {
+    kind: 'text',
+    body: typeof body === 'string' ? body : String(body ?? ''),
+    status: Number.isInteger(status) ? status : 200
+  };
+}
 
-const requestSnapshot = new Request(requestUrl, {
+async function readStdinBuffer() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+const requestInit = {
   method: requestMethod,
   headers: new Headers(safeRequestHeaders)
-});
+};
+const requestBodyBuffer =
+  requestMethod !== 'GET' && requestMethod !== 'HEAD'
+    ? await readStdinBuffer()
+    : Buffer.alloc(0);
+if (requestMethod !== 'GET' && requestMethod !== 'HEAD' && requestBodyBuffer.length > 0) {
+  requestInit.body = requestBodyBuffer;
+  requestInit.duplex = 'half';
+}
+const requestSnapshot = new Request(requestUrl, requestInit);
 const routeParams = { ...params };
 const routeMeta = {
   id: routeId,
@@ -229,27 +282,28 @@ const routeContext = {
   method: requestMethod,
   route: routeMeta,
   env: {},
-  auth: {
-    async getSession(_ctx) {
-      return null;
-    },
-    async requireSession(_ctx) {
-      throw ctxRedirect('/login', 302);
-    }
-  },
+  action: null,
   allow: ctxAllow,
   redirect: ctxRedirect,
   deny: ctxDeny,
-  data: ctxData
+  invalid: ctxInvalid,
+  data: ctxData,
+  json: ctxJson,
+  text: ctxText
 };
 
 const context = vm.createContext({
   params: routeParams,
   ctx: routeContext,
   fetch: globalThis.fetch,
+  Blob: globalThis.Blob,
+  File: globalThis.File,
+  FormData: globalThis.FormData,
   Headers: globalThis.Headers,
   Request: globalThis.Request,
   Response: globalThis.Response,
+  TextEncoder: globalThis.TextEncoder,
+  TextDecoder: globalThis.TextDecoder,
   URL,
   URLSearchParams,
   Buffer,
@@ -293,23 +347,31 @@ async function loadFileModule(moduleUrl) {
   if (moduleCache.has(moduleUrl)) {
     return moduleCache.get(moduleUrl);
   }
+  const modulePromise = (async () => {
+    const filename = fileURLToPath(moduleUrl);
+    let code = await fs.readFile(filename, 'utf8');
+    code = await transpileIfNeeded(filename, code);
+    const module = new vm.SourceTextModule(code, {
+      context,
+      identifier: moduleUrl,
+      initializeImportMeta(meta) {
+        meta.url = moduleUrl;
+      }
+    });
 
-  const filename = fileURLToPath(moduleUrl);
-  let code = await fs.readFile(filename, 'utf8');
-  code = await transpileIfNeeded(filename, code);
-  const module = new vm.SourceTextModule(code, {
-    context,
-    identifier: moduleUrl,
-    initializeImportMeta(meta) {
-      meta.url = moduleUrl;
-    }
-  });
+    await module.link((specifier, referencingModule) => {
+      return linkModule(specifier, referencingModule.identifier);
+    });
+    return module;
+  })();
 
-  moduleCache.set(moduleUrl, module);
-  await module.link((specifier, referencingModule) => {
-    return linkModule(specifier, referencingModule.identifier);
-  });
-  return module;
+  moduleCache.set(moduleUrl, modulePromise);
+  try {
+    return await modulePromise;
+  } catch (error) {
+    moduleCache.delete(moduleUrl);
+    throw error;
+  }
 }
 
 async function linkModule(specifier, parentIdentifier) {
@@ -320,11 +382,14 @@ async function linkModule(specifier, parentIdentifier) {
   return loadFileModule(resolvedUrl);
 }
 
-const allowed = new Set(['data', 'load', 'guard', 'ssr_data', 'props', 'ssr', 'prerender']);
+const allowed = new Set(['data', 'load', 'guard', 'action', 'ssr_data', 'props', 'ssr', 'prerender', 'exportPaths']);
 const prelude = "const params = globalThis.params;\n" +
   "const ctx = globalThis.ctx;\n" +
-  "import { resolveRouteResult } from 'zenith:server-contract';\n" +
-  "globalThis.resolveRouteResult = resolveRouteResult;\n";
+  "import { download, resolveRouteResult } from 'zenith:server-contract';\n" +
+  "import { attachRouteAuth } from 'zenith:route-auth';\n" +
+  "ctx.download = download;\n" +
+  "globalThis.resolveRouteResult = resolveRouteResult;\n" +
+  "globalThis.attachRouteAuth = attachRouteAuth;\n";
 const entryIdentifier = sourcePath
   ? pathToFileURL(sourcePath).href
   : 'zenith:server-script';
@@ -345,14 +410,35 @@ moduleCache.set(entryIdentifier, entryModule);
 await entryModule.link((specifier, referencingModule) => {
   if (specifier === 'zenith:server-contract') {
     const defaultPath = path.join(process.cwd(), 'node_modules', '@zenithbuild', 'cli', 'src', 'server-contract.js');
-    const contractUrl = pathToFileURL(process.env.ZENITH_SERVER_CONTRACT_PATH || defaultPath).href;
-    return loadFileModule(contractUrl).catch(() => 
+    const configuredPath = process.env.ZENITH_SERVER_CONTRACT_PATH || '';
+    const contractUrl = pathToFileURL(configuredPath || defaultPath).href;
+    if (configuredPath) {
+      return loadFileModule(contractUrl);
+    }
+    return loadFileModule(contractUrl).catch(() =>
+      loadFileModule(pathToFileURL(defaultPath).href)
+    );
+  }
+  if (specifier === 'zenith:route-auth') {
+    const defaultPath = path.join(process.cwd(), 'node_modules', '@zenithbuild', 'cli', 'src', 'auth', 'route-auth.js');
+    const configuredPath = process.env.ZENITH_SERVER_ROUTE_AUTH_PATH || '';
+    const authUrl = pathToFileURL(configuredPath || defaultPath).href;
+    if (configuredPath) {
+      return loadFileModule(authUrl);
+    }
+    return loadFileModule(authUrl).catch(() =>
       loadFileModule(pathToFileURL(defaultPath).href)
     );
   }
   return linkModule(specifier, referencingModule.identifier);
 });
 await entryModule.evaluate();
+context.attachRouteAuth(routeContext, {
+  requestUrl: routeContext.url,
+  guardOnly,
+  redirect: ctxRedirect,
+  deny: ctxDeny
+});
 
 const namespaceKeys = Object.keys(entryModule.namespace);
 for (const key of namespaceKeys) {
@@ -367,18 +453,21 @@ try {
     exports: exported,
     ctx: context.ctx,
     filePath: sourcePath || 'server_script',
-    guardOnly: guardOnly
+    guardOnly: guardOnly,
+    routeKind: routeKind
   });
 
   process.stdout.write(JSON.stringify(resolved || null));
 } catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
+  const message = error instanceof Error
+    ? (typeof error.stack === 'string' && error.stack.length > 0 ? error.stack : error.message)
+    : String(error);
+  process.stderr.write('[Zenith:Server] preview route execution failed\\n' + message + '\\n');
   process.stdout.write(
     JSON.stringify({
       __zenith_error: {
         status: 500,
-        code: 'LOAD_FAILED',
-        message
+        code: 'LOAD_FAILED'
       }
     })
   );
@@ -395,7 +484,9 @@ export async function createPreviewServer(options) {
     const loadedConfig = await loadConfig(resolvedProjectRoot);
     const resolvedConfig = options?.config && typeof options.config === 'object'
         ? (() => {
-            const overrideConfig = validateConfig(options.config);
+            const overrideConfig = isLoadedConfig(options.config)
+                ? options.config
+                : validateConfig(options.config);
             const mergedConfig = { ...loadedConfig };
             for (const key of Object.keys(overrideConfig)) {
                 if (isConfigKeyExplicit(overrideConfig, key)) {
@@ -411,7 +502,15 @@ export async function createPreviewServer(options) {
     const logger = providedLogger || createSilentLogger();
     const verboseLogging = logger.mode?.logLevel === 'verbose';
     const configuredBasePath = normalizeBasePath(config.basePath || '/');
+    const resolvedTarget = resolveBuildAdapter(config).target;
+    const routeCheckEnabled = supportsTargetRouteCheck(resolvedTarget);
+    const isStaticExportTarget = resolvedTarget === 'static-export';
     let actualPort = port;
+    const resolveServerOrigin = createTrustedOriginResolver({
+        host,
+        getPort: () => actualPort,
+        label: 'preview server'
+    });
     async function loadImageManifest() {
         try {
             const manifestRaw = await readFile(join(distDir, '_zenith', 'image', 'manifest.json'), 'utf8');
@@ -422,24 +521,17 @@ export async function createPreviewServer(options) {
             return {};
         }
     }
-    function publicHost() {
-        if (host === '0.0.0.0' || host === '::') {
-            return '127.0.0.1';
-        }
-        return host;
-    }
-    function serverOrigin() {
-        return `http://${publicHost()}:${actualPort}`;
-    }
     const server = createServer(async (req, res) => {
-        const requestBase = typeof req.headers.host === 'string' && req.headers.host.length > 0
-            ? `http://${req.headers.host}`
-            : serverOrigin();
-        const url = new URL(req.url, requestBase);
-        const { basePath, routes } = await loadRouteManifestState(distDir, configuredBasePath);
+        const url = new URL(req.url, resolveServerOrigin());
+        const { basePath, pageRoutes, resourceRoutes } = await loadRouteSurfaceState(distDir, configuredBasePath);
         const canonicalPath = stripBasePath(url.pathname, basePath);
         try {
             if (url.pathname === routeCheckPath(basePath)) {
+                if (!routeCheckEnabled) {
+                    res.writeHead(501, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'route_check_unsupported' }));
+                    return;
+                }
                 // Security: Require explicitly designated header to prevent public oracle probing
                 if (req.headers['x-zenith-route-check'] !== '1') {
                     res.writeHead(403, { 'Content-Type': 'application/json' });
@@ -467,7 +559,7 @@ export async function createPreviewServer(options) {
                 }
                 const canonicalTargetUrl = new URL(targetUrl.toString());
                 canonicalTargetUrl.pathname = canonicalTargetPath;
-                const resolvedCheck = resolveRequestRoute(canonicalTargetUrl, routes);
+                const resolvedCheck = resolveRequestRoute(canonicalTargetUrl, pageRoutes);
                 if (!resolvedCheck.matched || !resolvedCheck.route) {
                     res.writeHead(404, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: 'route_not_found' }));
@@ -509,13 +601,16 @@ export async function createPreviewServer(options) {
                     'Vary': 'Cookie'
                 });
                 res.end(JSON.stringify({
-                    result: checkResult?.result || checkResult,
+                    result: sanitizeRouteResult(checkResult?.result || checkResult),
                     routeId: resolvedCheck.route.route_id || '',
                     to: targetUrl.toString()
                 }));
                 return;
             }
             if (url.pathname === imageEndpointPath(basePath)) {
+                if (isStaticExportTarget) {
+                    throw new Error('not found');
+                }
                 await handleImageRequest(req, res, {
                     requestUrl: url,
                     projectRoot,
@@ -527,7 +622,9 @@ export async function createPreviewServer(options) {
                 throw new Error('not found');
             }
             if (extname(canonicalPath) && extname(canonicalPath) !== '.html') {
-                const staticPath = resolveWithinDist(distDir, canonicalPath);
+                const staticPath = isStaticExportTarget
+                    ? resolveWithinDist(distDir, url.pathname)
+                    : resolveWithinDist(distDir, canonicalPath);
                 if (!staticPath || !(await fileExists(staticPath))) {
                     throw new Error('not found');
                 }
@@ -537,9 +634,47 @@ export async function createPreviewServer(options) {
                 res.end(content);
                 return;
             }
+            if (isStaticExportTarget) {
+                const directHtmlPath = toStaticFilePath(distDir, url.pathname);
+                if (!directHtmlPath || !(await fileExists(directHtmlPath))) {
+                    throw new Error('not found');
+                }
+                const html = await readFile(directHtmlPath, 'utf8');
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(html);
+                return;
+            }
             const canonicalUrl = new URL(url.toString());
             canonicalUrl.pathname = canonicalPath;
-            const resolved = resolveRequestRoute(canonicalUrl, routes);
+            const resolvedResource = resolveRequestRoute(canonicalUrl, resourceRoutes);
+            if (resolvedResource.matched && resolvedResource.route) {
+                const requestMethod = req.method || 'GET';
+                const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
+                    ? null
+                    : await readRequestBodyBuffer(req);
+                const execution = await executeServerRoute({
+                    source: resolvedResource.route.server_script || '',
+                    sourcePath: resolvedResource.route.server_script_path || '',
+                    params: resolvedResource.params,
+                    requestUrl: url.toString(),
+                    requestMethod,
+                    requestHeaders: req.headers,
+                    requestBodyBuffer,
+                    routePattern: resolvedResource.route.path,
+                    routeFile: resolvedResource.route.server_script_path || '',
+                    routeId: resolvedResource.route.route_id || routeIdFromSourcePath(resolvedResource.route.server_script_path || ''),
+                    routeKind: 'resource'
+                });
+                const descriptor = buildResourceResponseDescriptor(execution?.result, basePath, Array.isArray(execution?.setCookies) ? execution.setCookies : []);
+                res.writeHead(descriptor.status, appendSetCookieHeaders(descriptor.headers, descriptor.setCookies));
+                if ((req.method || 'GET').toUpperCase() === 'HEAD') {
+                    res.end();
+                    return;
+                }
+                res.end(descriptor.body);
+                return;
+            }
+            const resolved = resolveRequestRoute(canonicalUrl, pageRoutes);
             let htmlPath = null;
             if (resolved.matched && resolved.route) {
                 if (verboseLogging) {
@@ -557,48 +692,56 @@ export async function createPreviewServer(options) {
                 throw new Error('not found');
             }
             let ssrPayload = null;
+            let routeExecution = null;
             if (resolved.matched && resolved.route?.server_script && resolved.route.prerender !== true) {
-                let routeExecution = null;
                 try {
+                    const requestMethod = req.method || 'GET';
+                    const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
+                        ? null
+                        : await readRequestBodyBuffer(req);
                     routeExecution = await executeServerRoute({
                         source: resolved.route.server_script,
                         sourcePath: resolved.route.server_script_path || '',
                         params: resolved.params,
                         requestUrl: url.toString(),
-                        requestMethod: req.method || 'GET',
+                        requestMethod,
                         requestHeaders: req.headers,
+                        requestBodyBuffer,
                         routePattern: resolved.route.path,
                         routeFile: resolved.route.server_script_path || '',
                         routeId: resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '')
                     });
                 }
                 catch (error) {
+                    logServerException('preview server route execution failed', error);
                     ssrPayload = {
                         __zenith_error: {
+                            status: 500,
                             code: 'LOAD_FAILED',
-                            message: error instanceof Error ? error.message : String(error)
+                            message: error instanceof Error ? error.message : String(error || '')
                         }
                     };
                 }
-                const trace = routeExecution?.trace || { guard: 'none', load: 'none' };
+                const trace = routeExecution?.trace || { guard: 'none', action: 'none', load: 'none' };
                 const routeId = resolved.route.route_id || routeIdFromSourcePath(resolved.route.server_script_path || '');
+                const setCookies = Array.isArray(routeExecution?.setCookies) ? routeExecution.setCookies : [];
                 if (verboseLogging) {
-                    logger.router(`${routeId} guard=${trace.guard} load=${trace.load}`);
+                    logger.router(`${routeId} guard=${trace.guard} action=${trace.action} load=${trace.load}`);
                 }
                 const result = routeExecution?.result;
                 if (result && result.kind === 'redirect') {
                     const status = Number.isInteger(result.status) ? result.status : 302;
-                    res.writeHead(status, {
+                    res.writeHead(status, appendSetCookieHeaders({
                         Location: appLocalRedirectLocation(result.location, basePath),
                         'Cache-Control': 'no-store'
-                    });
+                    }, setCookies));
                     res.end('');
                     return;
                 }
                 if (result && result.kind === 'deny') {
                     const status = Number.isInteger(result.status) ? result.status : 403;
-                    res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
-                    res.end(result.message || defaultRouteDenyMessage(status));
+                    res.writeHead(status, appendSetCookieHeaders({ 'Content-Type': 'text/plain; charset=utf-8' }, setCookies));
+                    res.end(clientFacingRouteMessage(status, result.message));
                     return;
                 }
                 if (result && result.kind === 'data' && result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
@@ -606,21 +749,24 @@ export async function createPreviewServer(options) {
                 }
             }
             let html = await readFile(htmlPath, 'utf8');
-            if (resolved.matched && resolved.route?.page_asset) {
-                const pageAssetPath = resolveWithinDist(distDir, resolved.route.page_asset);
+            if (resolved.matched) {
                 html = await materializeImageMarkup({
                     html,
-                    pageAssetPath,
                     payload: createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint', basePath),
-                    ssrData: ssrPayload,
-                    routePathname: url.pathname
+                    imageMaterialization: Array.isArray(resolved.route?.image_materialization)
+                        ? resolved.route.image_materialization
+                        : []
                 });
             }
             if (ssrPayload) {
                 html = injectSsrPayload(html, ssrPayload);
             }
-            html = injectImageRuntimePayload(html, createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint', basePath));
-            res.writeHead(200, { 'Content-Type': 'text/html' });
+            if (!IMAGE_RUNTIME_TAG_RE.test(html)) {
+                html = injectImageRuntimePayload(html, createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint', basePath));
+            }
+            res.writeHead(Number.isInteger(routeExecution?.status) ? routeExecution.status : 200, appendSetCookieHeaders({
+                'Content-Type': 'text/html'
+            }, Array.isArray(routeExecution?.setCookies) ? routeExecution.setCookies : []));
             res.end(html);
         }
         catch {
@@ -662,42 +808,46 @@ export async function createPreviewServer(options) {
  * @returns {Promise<PreviewRoute[]>}
  */
 export async function loadRouteManifest(distDir) {
-    const state = await loadRouteManifestState(distDir, '/');
-    return state.routes;
+    const state = await loadRouteSurfaceState(distDir, '/');
+    return state.pageRoutes;
 }
-async function loadRouteManifestState(distDir, fallbackBasePath = '/') {
+export async function loadRouteSurfaceState(distDir, fallbackBasePath = '/') {
     const manifestPath = join(distDir, 'assets', 'router-manifest.json');
+    const resourceState = await loadResourceRouteManifest(distDir, normalizeBasePath(fallbackBasePath || '/'));
     try {
         const source = await readFile(manifestPath, 'utf8');
         const parsed = JSON.parse(source);
         const routes = Array.isArray(parsed?.routes) ? parsed.routes : [];
+        const basePath = normalizeBasePath(parsed?.base_path || resourceState.basePath || fallbackBasePath || '/');
         return {
-            basePath: normalizeBasePath(parsed?.base_path || fallbackBasePath || '/'),
-            routes: routes
+            basePath,
+            pageRoutes: routes
                 .filter((entry) => entry &&
                 typeof entry === 'object' &&
                 typeof entry.path === 'string' &&
                 typeof entry.output === 'string')
-                .sort((a, b) => compareRouteSpecificity(a.path, b.path))
+                .sort((a, b) => compareRouteSpecificity(a.path, b.path)),
+            resourceRoutes: Array.isArray(resourceState.routes) ? resourceState.routes : []
         };
     }
     catch {
         return {
-            basePath: normalizeBasePath(fallbackBasePath || '/'),
-            routes: []
+            basePath: normalizeBasePath(resourceState.basePath || fallbackBasePath || '/'),
+            pageRoutes: [],
+            resourceRoutes: Array.isArray(resourceState.routes) ? resourceState.routes : []
         };
     }
 }
 export const matchRoute = matchManifestRoute;
 /**
- * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, routePattern?: string, routeFile?: string, routeId?: string }} input
- * @returns {Promise<{ result: { kind: string, [key: string]: unknown }, trace: { guard: string, load: string } }>}
+ * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, requestBodyBuffer?: Buffer | null, routePattern?: string, routeFile?: string, routeId?: string, routeKind?: 'page' | 'resource' }} input
+ * @returns {Promise<{ result: { kind: string, [key: string]: unknown }, trace: { guard: string, action: string, load: string }, status?: number, setCookies?: string[] }>}
  */
-export async function executeServerRoute({ source, sourcePath, params, requestUrl, requestMethod, requestHeaders, routePattern, routeFile, routeId, guardOnly = false }) {
+export async function executeServerRoute({ source, sourcePath, params, requestUrl, requestMethod, requestHeaders, requestBodyBuffer, routePattern, routeFile, routeId, routeKind = 'page', guardOnly = false }) {
     if (!source || !String(source).trim()) {
         return {
             result: { kind: 'data', data: {} },
-            trace: { guard: 'none', load: 'none' }
+            trace: { guard: 'none', action: 'none', load: 'none' }
         };
     }
     const payload = await spawnNodeServerRunner({
@@ -707,15 +857,17 @@ export async function executeServerRoute({ source, sourcePath, params, requestUr
         requestUrl: requestUrl || 'http://localhost/',
         requestMethod: requestMethod || 'GET',
         requestHeaders: sanitizeRequestHeaders(requestHeaders || {}),
+        requestBodyBuffer: Buffer.isBuffer(requestBodyBuffer) ? requestBodyBuffer : null,
         routePattern: routePattern || '',
         routeFile: routeFile || sourcePath || '',
         routeId: routeId || routeIdFromSourcePath(sourcePath || ''),
+        routeKind,
         guardOnly
     });
     if (payload === null || payload === undefined) {
         return {
             result: { kind: 'data', data: {} },
-            trace: { guard: 'none', load: 'none' }
+            trace: { guard: 'none', action: 'none', load: 'none' }
         };
     }
     if (typeof payload !== 'object' || Array.isArray(payload)) {
@@ -727,9 +879,9 @@ export async function executeServerRoute({ source, sourcePath, params, requestUr
             result: {
                 kind: 'deny',
                 status: 500,
-                message: String(errorEnvelope.message || 'Server route execution failed')
+                message: defaultRouteDenyMessage(500)
             },
-            trace: { guard: 'none', load: 'deny' }
+            trace: { guard: 'none', action: 'none', load: 'deny' }
         };
     }
     const result = payload.result;
@@ -740,9 +892,14 @@ export async function executeServerRoute({ source, sourcePath, params, requestUr
             trace: trace && typeof trace === 'object'
                 ? {
                     guard: String(trace.guard || 'none'),
+                    action: String(trace.action || 'none'),
                     load: String(trace.load || 'none')
                 }
-                : { guard: 'none', load: 'none' }
+                : { guard: 'none', action: 'none', load: 'none' },
+            status: Number.isInteger(payload.status) ? payload.status : undefined,
+            setCookies: Array.isArray(payload.setCookies)
+                ? payload.setCookies.filter((value) => typeof value === 'string' && value.length > 0)
+                : []
         };
     }
     return {
@@ -750,18 +907,9 @@ export async function executeServerRoute({ source, sourcePath, params, requestUr
             kind: 'data',
             data: payload
         },
-        trace: { guard: 'none', load: 'data' }
+        trace: { guard: 'none', action: 'none', load: 'data' }
     };
 }
-export function defaultRouteDenyMessage(status) {
-    if (status === 401)
-        return 'Unauthorized';
-    if (status === 403)
-        return 'Forbidden';
-    if (status === 404)
-        return 'Not Found';
-    return 'Internal Server Error';
-}
 /**
  * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, routePattern?: string, routeFile?: string, routeId?: string }} input
  * @returns {Promise<Record<string, unknown> | null>}
@@ -790,14 +938,14 @@ export async function executeServerScript(input) {
             __zenith_error: {
                 status,
                 code: status >= 500 ? 'LOAD_FAILED' : (status === 404 ? 'NOT_FOUND' : 'ACCESS_DENIED'),
-                message: String(result.message || defaultRouteDenyMessage(status))
+                message: clientFacingRouteMessage(status, result.message)
             }
         };
     }
     return {};
 }
 /**
- * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl: string, requestMethod: string, requestHeaders: Record<string, string>, routePattern: string, routeFile: string, routeId: string }} input
+ * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl: string, requestMethod: string, requestHeaders: Record<string, string>, requestBodyBuffer?: Buffer | null, routePattern: string, routeFile: string, routeId: string, routeKind?: 'page' | 'resource' }} input
  * @returns {Promise<unknown>}
  */
 function spawnNodeServerRunner(input) {
@@ -814,11 +962,18 @@ function spawnNodeServerRunner(input) {
                 ZENITH_SERVER_ROUTE_PATTERN: input.routePattern || '',
                 ZENITH_SERVER_ROUTE_FILE: input.routeFile || input.sourcePath || '',
                 ZENITH_SERVER_ROUTE_ID: input.routeId || '',
+                ZENITH_SERVER_ROUTE_KIND: input.routeKind || 'page',
                 ZENITH_SERVER_GUARD_ONLY: input.guardOnly ? '1' : '',
-                ZENITH_SERVER_CONTRACT_PATH: join(__dirname, 'server-contract.js')
+                ZENITH_SERVER_CONTRACT_PATH: join(__dirname, 'server-contract.js'),
+                ZENITH_SERVER_ROUTE_AUTH_PATH: join(__dirname, 'auth', 'route-auth.js')
             },
-            stdio: ['ignore', 'pipe', 'pipe']
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        const runnerRequestBody = Buffer.isBuffer(input.requestBodyBuffer) ? input.requestBodyBuffer : null;
+        child.stdin.on('error', () => {
+            // ignore broken pipes when the runner exits before consuming stdin
         });
+        child.stdin.end(runnerRequestBody && runnerRequestBody.length > 0 ? runnerRequestBody : undefined);
         let stdout = '';
         let stderr = '';
         child.stdout.on('data', (chunk) => {
@@ -835,6 +990,11 @@ function spawnNodeServerRunner(input) {
                 rejectPromise(new Error(`[zenith-preview] server script execution failed (${code}): ${stderr.trim() || stdout.trim()}`));
                 return;
             }
+            const stderrOutput = stderr.trim();
+            const internalErrorIndex = stderrOutput.indexOf('[Zenith:Server]');
+            if (internalErrorIndex >= 0) {
+                console.error(stderrOutput.slice(internalErrorIndex).trim());
+            }
             const raw = stdout.trim();
             if (!raw || raw === 'null') {
                 resolvePromise(null);