@nexus_js/server 0.9.29 → 0.9.30

package/dist/index.js

@@ -4,30 +4,60 @@
  */
 import { createServer } from 'node:http';
 import { readFile, stat } from 'node:fs/promises';
-import { join, extname } from 'node:path';
+import { join, extname, resolve, sep } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { Readable } from 'node:stream';
 import { buildRouteManifest, matchRoute } from '@nexus_js/router';
 import { handleActionRequest } from './actions.js';
 import { handleSSERequestNode, isConnectRequest, topicFromUrl } from '@nexus_js/connect';
-import { buildAggregatedNxStylesheet, bustAggregatedStylesCache, compileIslandClientBundle, isIslandClientRequest, tryServeRuntimeAsset, } from './dev-assets.js';
+import { buildAggregatedNxStylesheet, buildGlobalStylesheet, bustAggregatedStylesCache, bustGlobalStylesCache, compileIslandClientBundle, getAggregatedCssETag, getGlobalCssETag, isIslandClientRequest, tryServeRuntimeAsset, } from './dev-assets.js';
+import { tryServeLibAsset } from './dev-assets.js';
 import { devErrorHtmlPage } from './dev-error-html.js';
 import { broadcastDevHotReload, subscribeDevHotClient } from './dev-hot.js';
-import { renderRoute, renderRouteStreaming, wrapWithDocument } from './renderer.js';
+import { renderRoute, renderRouteStreaming } from './renderer.js';
 import { pipeToNodeResponse } from './streaming.js';
-import { findNotFoundBoundary } from './error-boundary.js';
-import { loadRouteModule } from './load-module.js';
 import { handleNavigationRequest } from './navigate.js';
 import { bumpDevReloadGeneration, preloadRegisteredServerActions } from './load-module.js';
 import { createContext, RedirectSignal, NotFoundSignal } from './context.js';
-import { nexusVault } from '@nexus_js/security';
+import { nexusVault, getTenantVaultSecretsMap, getVaultSecretsMap } from '@nexus_js/security';
 import { handleDevVaultPost } from './dev-vault.js';
+import { resolveTenant } from './tenancy.js';
 import { refreshShieldAllowlist, isActionBlockedByShield, setShieldLite, } from './shield-runtime.js';
+import { loadAndCacheNexusBuildId } from './build-id.js';
 import { emitDevRadar } from './devradar.js';
 export { STUDIO_DEFAULT_PORT } from './constants.js';
-export { createAction, registerAction, ActionError, getRegisteredActionNames } from './actions.js';
+export { createAction, registerAction, ActionError, getRegisteredActionNames, isInternalUrl, isSafeUrl, } from './actions.js';
+export { loadAndCacheNexusBuildId, getExpectedNexusBuildId } from './build-id.js';
 export { createContext } from './context.js';
 export { nexusVault } from '@nexus_js/security';
+export { resolveTenant } from './tenancy.js';
 export { mergeRoutePretext } from './renderer.js';
+export { defineMetadata, escapeHtml } from './metadata.js';
+export { defineHead, useHead, flushHead, renderHeadToString } from '@nexus_js/head';
 export { registerDevRadarSink, emitDevRadar, sanitizeTelemetryValue, newTraceId } from './devradar.js';
+export { wrapExpressMiddleware, wrapExpressHandler } from './legacy-wrapper.js';
+/**
+ * Returns true when an Origin header value is a loopback address (localhost,
+ * 127.x.x.x, ::1, 0.0.0.0) or the opaque "null" value.
+ * Used to protect dev-only endpoints from external network access.
+ * "null" is explicitly rejected here (unlike the action handler) because dev
+ * endpoints must never be reachable from sandboxed or opaque contexts.
+ */
+function isLoopbackOrigin(origin) {
+    if (origin === 'null')
+        return false; // opaque origin — never trusted
+    try {
+        const { hostname } = new URL(origin);
+        return (hostname === 'localhost' ||
+            hostname === '127.0.0.1' ||
+            hostname === '::1' ||
+            hostname === '0.0.0.0' ||
+            /^127\.\d+\.\d+\.\d+$/.test(hostname));
+    }
+    catch {
+        return false;
+    }
+}
 /** Merge ctx response headers (Set-Cookie, etc.) with redirect Location. */
 function redirectHeadersForWriteHead(err) {
     const setCookies = [];
@@ -48,8 +78,8 @@ function redirectHeadersForWriteHead(err) {
     }
     return out;
 }
-/** Merge Hardened Mode headers (changelog v0.5) — CSP nonces are a future enhancement. */
-function mergeHardenedHeaders(headers, hardened, dev) {
+/** Merge Hardened Mode headers — includes per-request CSP nonce when hardened. */
+function mergeHardenedHeaders(headers, hardened, dev, cspNonce, cspOptions) {
     const h = {};
     for (const [k, v] of Object.entries(headers)) {
         if (v !== undefined)
@@ -65,6 +95,34 @@ function mergeHardenedHeaders(headers, hardened, dev) {
     if (!dev) {
         h['strict-transport-security'] = 'max-age=31536000; includeSubDomains';
     }
+    // Content-Security-Policy with per-request nonce for inline scripts.
+    // script-src: 'self' for external scripts, nonce for inline scripts (Nexus-generated).
+    //             Custom inline scripts in templates get the nonce via ctx.cspNonce.
+    // object-src: 'none' blocks Flash / legacy plugin execution.
+    // base-uri: 'self' prevents base tag injection (open redirect via <base href>).
+    if (cspNonce) {
+        const extraStyle = cspOptions?.additionalStyleSrc?.join(' ') ?? '';
+        const extraFont = cspOptions?.additionalFontSrc?.join(' ') ?? '';
+        const extraScript = cspOptions?.additionalScriptSrc?.join(' ') ?? '';
+        const extraConnect = cspOptions?.additionalConnectSrc?.join(' ') ?? '';
+        const extraImg = cspOptions?.additionalImgSrc?.join(' ') ?? '';
+        const extraFrame = cspOptions?.additionalFrameSrc?.join(' ') ?? '';
+        const scriptSrc = dev
+            ? `'self' 'nonce-${cspNonce}' 'unsafe-eval'${extraScript ? ` ${extraScript}` : ''}`
+            : `'self' 'nonce-${cspNonce}'${extraScript ? ` ${extraScript}` : ''}`;
+        h['content-security-policy'] =
+            `default-src 'self'; ` +
+                // default-src does not allow blob: for iframes; leave worker-src unset so it falls back to script-src (CDN workers).
+                `frame-src 'self' blob:${extraFrame ? ` ${extraFrame}` : ''}; ` +
+                `script-src ${scriptSrc}; ` +
+                `style-src 'self' 'unsafe-inline'${extraStyle ? ` ${extraStyle}` : ''}; ` +
+                `img-src 'self' data: blob:${extraImg ? ` ${extraImg}` : ''}; ` +
+                `font-src 'self'${extraFont ? ` ${extraFont}` : ''}; ` +
+                `connect-src 'self'${extraConnect ? ` ${extraConnect}` : ''}; ` +
+                `object-src 'none'; ` +
+                `base-uri 'self'; ` +
+                `form-action 'self'`;
+    }
     return h;
 }
 const MIME_TYPES = {
@@ -90,9 +148,11 @@ export async function createNexusServer(opts) {
     const publicDir = join(opts.root, opts.publicDir ?? 'public');
     setShieldLite(opts.security?.shieldLite === true);
     let manifest = await buildRouteManifest(routesDir);
+    const nexusBuildId = loadAndCacheNexusBuildId(opts.root);
     const renderOpts = {
         dev,
         appRoot: opts.root,
+        ...(nexusBuildId ? { buildId: nexusBuildId } : {}),
         ...(opts.browserImportMap ? { browserImportMap: opts.browserImportMap } : {}),
         assets: {
             /** ESM entry + chunks served from @nexus_js/runtime/dist via /_nexus/rt/* */
@@ -101,11 +161,32 @@ export async function createNexusServer(opts) {
             islands: new Map(),
         },
     };
-    const sec = (h) => mergeHardenedHeaders(h, opts.security?.hardened, dev);
+    const hardened = opts.security?.hardened === true;
+    const cspConfig = opts.security?.csp;
+    // `sec` without a nonce — used for non-HTML responses (JSON, static files, actions).
+    const sec = (h) => mergeHardenedHeaders(h, hardened, dev, undefined, cspConfig);
     const server = createServer(async (req, res) => {
         const t0 = Date.now();
         const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
         const method = req.method ?? 'GET';
+        if ((method === 'GET' || method === 'HEAD') && url.pathname === '/_nexus/health') {
+            const payload = {
+                ok: true,
+                ts: Date.now(),
+                buildId: nexusBuildId ?? null,
+            };
+            res.writeHead(200, sec({ 'content-type': 'application/json; charset=utf-8' }));
+            if (method === 'HEAD') {
+                res.end();
+            }
+            else {
+                res.end(JSON.stringify(payload));
+            }
+            return;
+        }
+        // Generate a per-request CSP nonce for HTML responses (hardened mode only).
+        // Same nonce is injected into inline <script> tags and the CSP header.
+        const cspNonce = hardened ? randomBytes(16).toString('base64url') : undefined;
         // Capture cache strategy before headers are flushed, then call onRequest hook
         let _cacheStrategy;
         let _isAction = false;
@@ -124,12 +205,27 @@ export async function createNexusServer(opts) {
             });
         }
         // ── Dev hot-reload (SSE) — browser listens and calls location.reload() ──
+        // Guard dev-only endpoints against external origin access. Browsers on the
+        // same machine will send no Origin (direct navigation) or a loopback Origin.
+        // An attacker on the network sending a cross-origin request is rejected.
         if (dev && method === 'GET' && url.pathname === '/_nexus/dev/hot') {
+            const devOrigin = req.headers['origin'];
+            if (devOrigin && !isLoopbackOrigin(devOrigin)) {
+                res.writeHead(403, { 'content-type': 'text/plain' });
+                res.end('Forbidden: dev endpoint requires loopback origin');
+                return;
+            }
             subscribeDevHotClient(req, res);
             return;
         }
         // ── Vault-lite (dev) — hot-reload secrets without restart ───────────────
         if (dev && method === 'POST' && url.pathname === '/_nexus/dev/vault') {
+            const devOrigin = req.headers['origin'];
+            if (devOrigin && !isLoopbackOrigin(devOrigin)) {
+                res.writeHead(403, { 'content-type': 'text/plain' });
+                res.end('Forbidden: dev endpoint requires loopback origin');
+                return;
+            }
             const request = await incomingMessageToWebRequest(req);
             const response = await handleDevVaultPost(request);
             await webToNodeResponse(response, res, sec);
@@ -166,6 +262,39 @@ export async function createNexusServer(opts) {
         }
         // ── Nexus Connect — SSE (/_nexus/connect/:topic) ────────────────────────
         if (method === 'GET' && isConnectRequest(url)) {
+            const origin = typeof req.headers['origin'] === 'string' ? req.headers['origin'] : undefined;
+            const host = typeof req.headers['host'] === 'string' ? req.headers['host'] : undefined;
+            const corsMode = opts.connect?.corsOrigins ?? (dev ? '*' : 'self');
+            let allowOrigin;
+            if (corsMode === '*') {
+                allowOrigin = '*';
+            }
+            else if (corsMode === 'self') {
+                if (!origin) {
+                    allowOrigin = '*';
+                }
+                else {
+                    try {
+                        const o = new URL(origin);
+                        if (host && o.host === host) {
+                            allowOrigin = origin;
+                        }
+                    }
+                    catch {
+                        allowOrigin = undefined;
+                    }
+                }
+            }
+            else if (Array.isArray(corsMode)) {
+                if (origin && corsMode.includes(origin)) {
+                    allowOrigin = origin;
+                }
+            }
+            if (origin && !allowOrigin) {
+                res.writeHead(403, sec({ 'content-type': 'text/plain; charset=utf-8' }));
+                res.end('Forbidden');
+                return;
+            }
             handleSSERequestNode(req, res, topicFromUrl(url));
             return;
         }
@@ -176,12 +305,34 @@ export async function createNexusServer(opts) {
             res.end(rt.body);
             return;
         }
+        const libAsset = await tryServeLibAsset(url.pathname, opts.root, dev);
+        if (libAsset) {
+            res.writeHead(200, {
+                'content-type': libAsset.contentType,
+                'cache-control': dev ? 'no-store' : 'public, max-age=0, must-revalidate',
+            });
+            res.end(libAsset.body);
+            return;
+        }
         // ── Client island ESM (dynamic import target for <nexus-island>) ───────
         if (isIslandClientRequest(url.pathname) && method === 'GET') {
-            const out = await compileIslandClientBundle(opts.root, url);
+            let out;
+            try {
+                out = await compileIslandClientBundle(opts.root, url);
+            }
+            catch (err) {
+                // Last-resort catch: bundle compilers should never throw (they
+                // wrap their internals), but if they do we must still respond with valid
+                // JavaScript so the browser gets a parseable error rather than HTML.
+                const msg = err instanceof Error ? err.message : String(err);
+                out = {
+                    body: `throw new Error(${JSON.stringify(`[Nexus] Unexpected island error: ${msg}`)});`,
+                    status: 500,
+                };
+            }
             res.writeHead(out.status, {
                 'content-type': 'application/javascript; charset=utf-8',
-                'cache-control': dev ? 'no-store' : 'public, max-age=120',
+                'cache-control': 'no-store',
             });
             res.end(out.body);
             return;
@@ -202,13 +353,35 @@ export async function createNexusServer(opts) {
             return;
         }
         // ── Aggregated scoped CSS from all .nx files under src/
+        // ── Aggregated scoped CSS from all .nx files under src/
         if (url.pathname === '/_nexus/styles.css' && method === 'GET') {
             try {
                 const css = await buildAggregatedNxStylesheet(opts.root);
-                res.writeHead(200, {
+                const etag = getAggregatedCssETag();
+                // Conditional GET (If-None-Match) — eliminates FOUC on hard refresh
+                // (Cmd+R / Ctrl+F5).  The browser caches the stylesheet and on each
+                // reload sends If-None-Match with the stored ETag.  When the CSS has
+                // not changed the server responds 304 instantly (no recompilation
+                // needed) and the browser reuses its cached copy, applying styles
+                // before the first paint rather than waiting for a full roundtrip.
+                //
+                // `cache-control: no-cache` (not `no-store`) lets the browser keep
+                // the response in its local cache but forces it to revalidate before
+                // use.  When a file changes, `bustAggregatedStylesCache()` resets the
+                // ETag, so the next request returns 200 with the updated CSS.
+                if (etag && req.headers['if-none-match'] === etag) {
+                    res.writeHead(304, { 'cache-control': dev ? 'no-cache' : 'public, max-age=300', etag });
+                    res.end();
+                    return;
+                }
+                const cacheControl = dev ? 'no-cache' : 'public, max-age=300';
+                const headers = {
                     'content-type': 'text/css; charset=utf-8',
-                    'cache-control': dev ? 'no-store' : 'public, max-age=300',
-                });
+                    'cache-control': cacheControl,
+                };
+                if (etag)
+                    headers['etag'] = etag;
+                res.writeHead(200, headers);
                 res.end(css);
             }
             catch (err) {
@@ -218,6 +391,37 @@ export async function createNexusServer(opts) {
             }
             return;
         }
+        // ── Global CSS (Tailwind / PostCSS / plain CSS) ──────────────────────────
+        if (url.pathname === '/_nexus/global.css' && method === 'GET') {
+            try {
+                const css = await buildGlobalStylesheet(opts.root, opts.cssEntry);
+                if (css === null) {
+                    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+                    res.end('Not found');
+                    return;
+                }
+                const etag = getGlobalCssETag();
+                if (etag && req.headers['if-none-match'] === etag) {
+                    res.writeHead(304, { 'cache-control': dev ? 'no-cache' : 'public, max-age=300', etag });
+                    res.end();
+                    return;
+                }
+                const headers = {
+                    'content-type': 'text/css; charset=utf-8',
+                    'cache-control': dev ? 'no-cache' : 'public, max-age=300',
+                };
+                if (etag)
+                    headers['etag'] = etag;
+                res.writeHead(200, headers);
+                res.end(css);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
+                res.end(`[Nexus] Failed to build global styles: ${msg}`);
+            }
+            return;
+        }
         // ── SPA navigation JSON (/_nexus/navigate?path=…) — must run before SSR matchRoute
         if (url.pathname === '/_nexus/navigate' && method === 'GET') {
             const request = nodeToWebRequest(req);
@@ -225,6 +429,32 @@ export async function createNexusServer(opts) {
             await webToNodeResponse(response, res, sec);
             return;
         }
+        // ── Custom mounts (GraphQL, webhooks, etc.) ──────────────────────────────
+        // Evaluated before static files so handlers can shadow public/ assets.
+        for (const mount of opts.mounts ?? []) {
+            const allowedMethods = mount.methods
+                ? mount.methods.map(m => m.toUpperCase())
+                : null; // null = allow all
+            if (allowedMethods && !allowedMethods.includes(method))
+                continue;
+            const pathname = url.pathname;
+            const matches = pathname === mount.path || pathname.startsWith(mount.path + '/');
+            if (!matches)
+                continue;
+            const request = await incomingMessageToWebRequest(req);
+            const ctx = createContext(request, {}, cspNonce ?? '');
+            try {
+                const response = await mount.handler(request, ctx);
+                await webToNodeResponse(response, res, sec);
+            }
+            catch (err) {
+                if (dev)
+                    console.error(`[Nexus] Mount handler error (${mount.path}):`, err);
+                res.writeHead(500, sec({ 'content-type': 'application/json' }));
+                res.end(JSON.stringify({ error: 'Internal Server Error', status: 500 }));
+            }
+            return;
+        }
         // ── Static files ────────────────────────────────────────────────────────
         // Browsers still request /favicon.ico and /apple-touch-icon.png even when the
         // app only ships favicon.svg — avoid noisy 404s by falling back to SVG.
@@ -248,21 +478,127 @@ export async function createNexusServer(opts) {
         }
         const staticResult = await serveStatic(url.pathname, publicDir);
         if (staticResult) {
-            res.writeHead(200, { 'content-type': staticResult.mime });
+            // Conditional GET — eliminates re-downloading large static assets
+            // (Tailwind output, sourcemaps, big SVGs) on every Cmd+R.  Without
+            // ETag/Last-Modified the browser cannot revalidate, must re-download
+            // the full body, and renders the page unstyled while it waits.
+            const ifNoneMatch = req.headers['if-none-match'];
+            const ifModifiedSince = req.headers['if-modified-since'];
+            const notModified = (typeof ifNoneMatch === 'string' && ifNoneMatch === staticResult.etag) ||
+                (typeof ifModifiedSince === 'string' && ifModifiedSince === staticResult.lastModified);
+            if (notModified) {
+                res.writeHead(304, {
+                    etag: staticResult.etag,
+                    'last-modified': staticResult.lastModified,
+                    'cache-control': dev ? 'no-cache' : 'public, max-age=0, must-revalidate',
+                });
+                res.end();
+                return;
+            }
+            res.writeHead(200, {
+                'content-type': staticResult.mime,
+                etag: staticResult.etag,
+                'last-modified': staticResult.lastModified,
+                // `no-cache` (not `no-store`) lets the browser keep a copy and
+                // revalidate via If-None-Match — most reloads return 304 instantly.
+                'cache-control': dev ? 'no-cache' : 'public, max-age=0, must-revalidate',
+            });
             res.end(staticResult.content);
             return;
         }
         // ── SSR routing ─────────────────────────────────────────────────────────
         const matched = matchRoute(url.pathname, manifest);
         if (!matched) {
+            // ── Fallback proxy to legacy backend ──────────────────────────────────
+            if (opts.fallbackProxy) {
+                try {
+                    const targetUrl = new URL(url.pathname + url.search, opts.fallbackProxy);
+                    let body = null;
+                    if (method !== 'GET' && method !== 'HEAD') {
+                        const chunks = [];
+                        await new Promise((resolve, reject) => {
+                            req.on('data', (chunk) => chunks.push(chunk));
+                            req.on('end', () => resolve());
+                            req.on('error', reject);
+                        });
+                        body = chunks.length > 0 ? new Uint8Array(Buffer.concat(chunks)) : null;
+                    }
+                    const proxyReq = await fetch(targetUrl.toString(), {
+                        method,
+                        headers: Object.fromEntries(Object.entries(req.headers)
+                            .filter(([k]) => {
+                            const key = k.toLowerCase();
+                            if (key === 'host')
+                                return false;
+                            if (key === 'connection')
+                                return false;
+                            if (key === 'keep-alive')
+                                return false;
+                            if (key === 'proxy-authenticate')
+                                return false;
+                            if (key === 'proxy-authorization')
+                                return false;
+                            if (key === 'te')
+                                return false;
+                            if (key === 'trailer')
+                                return false;
+                            if (key === 'transfer-encoding')
+                                return false;
+                            if (key === 'upgrade')
+                                return false;
+                            if (key === 'content-length')
+                                return false;
+                            return true;
+                        })
+                            .map(([k, v]) => [k, Array.isArray(v) ? v.join(', ') : String(v ?? '')])),
+                        body: body,
+                    });
+                    const proxyHeaders = {};
+                    proxyReq.headers.forEach((value, key) => {
+                        if (key.toLowerCase() === 'set-cookie') {
+                            const existing = proxyHeaders[key];
+                            if (Array.isArray(existing))
+                                existing.push(value);
+                            else if (existing)
+                                proxyHeaders[key] = [existing, value];
+                            else
+                                proxyHeaders[key] = value;
+                        }
+                        else {
+                            proxyHeaders[key] = value;
+                        }
+                    });
+                    res.writeHead(proxyReq.status, proxyHeaders);
+                    if (proxyReq.body) {
+                        // Safe cast: incoming proxy body from undici/fetch is compatible with Node Readable in this context
+                        Readable.fromWeb(proxyReq.body).pipe(res);
+                    }
+                    else {
+                        res.end();
+                    }
+                    return;
+                }
+                catch (err) {
+                    if (dev)
+                        console.error('[Nexus] Fallback proxy error:', err);
+                    res.writeHead(502, sec({ 'content-type': 'text/html' }));
+                    res.end('<h1>502 Bad Gateway</h1><p>Legacy backend unavailable</p>');
+                    return;
+                }
+            }
             res.writeHead(404, sec({ 'content-type': 'text/html' }));
-            const request = nodeToWebRequest(req);
-            const ctx = createContext(request, {});
-            res.end(await notFoundPage(url.pathname, dev, routesDir, ctx, renderOpts));
+            res.end(notFoundPage(url.pathname, dev));
             return;
         }
         const request = nodeToWebRequest(req);
-        const ctx = createContext(request, matched.params);
+        const tenancyCfg = opts.tenancy;
+        const tenant = tenancyCfg ? resolveTenant(request, tenancyCfg, getVaultSecretsMap()) : null;
+        const ctx = createContext(request, matched.params, cspNonce ?? '');
+        if (tenant) {
+            ctx.locals['tenant'] = tenant;
+            ctx.locals['tenantId'] = tenant.id;
+            ctx.secrets = getTenantVaultSecretsMap(tenant.id, tenancyCfg?.vaultIsolation ?? 'strict');
+        }
         try {
             if (opts.streamingPretext === true && method === 'GET') {
                 _cacheStrategy = 'streaming-no-store';
@@ -270,9 +606,11 @@ export async function createNexusServer(opts) {
                 await pipeToNodeResponse(streamRes, res, sec);
                 return;
             }
-            const result = await renderRoute(matched, ctx, renderOpts);
+            const requestRenderOpts = cspNonce ? { ...renderOpts, cspNonce } : renderOpts;
+            const result = await renderRoute(matched, ctx, requestRenderOpts);
             _cacheStrategy = result.headers['x-nexus-cache-strategy'];
-            res.writeHead(result.status, sec(result.headers));
+            const htmlHeaders = mergeHardenedHeaders(result.headers, hardened, dev, cspNonce, cspConfig);
+            res.writeHead(result.status, htmlHeaders);
             res.end(result.html);
         }
         catch (err) {
@@ -283,7 +621,7 @@ export async function createNexusServer(opts) {
             }
             if (err instanceof NotFoundSignal) {
                 res.writeHead(404, sec({ 'content-type': 'text/html' }));
-                res.end(await notFoundPage(url.pathname, dev, routesDir, ctx, renderOpts));
+                res.end(notFoundPage(url.pathname, dev));
                 return;
             }
             if (dev) {
@@ -302,6 +640,21 @@ export async function createNexusServer(opts) {
         listen() {
             return new Promise((resolve, reject) => {
                 void (async () => {
+                    // Fail hard in production when NEXUS_SECRET is absent or is the
+                    // well-known dev placeholder. A predictable secret lets anyone forge
+                    // valid CSRF tokens, bypass replay protection, and hijack sessions.
+                    const envSecret = process.env['NEXUS_SECRET'];
+                    if (!dev) {
+                        if (!envSecret || envSecret === 'nexus-dev-secret-change-me') {
+                            throw new Error('[Nexus Security] NEXUS_SECRET is not set (or is the insecure dev default). ' +
+                                'Set NEXUS_SECRET to a random 32+ character secret in your production environment ' +
+                                'before starting the server. The server refuses to start without it.');
+                        }
+                        if (envSecret.length < 32) {
+                            throw new Error(`[Nexus Security] NEXUS_SECRET is too short (${envSecret.length} chars). ` +
+                                'Use at least 32 random characters (e.g. openssl rand -base64 32).');
+                        }
+                    }
                     try {
                         nexusVault.seedFromProcessEnv();
                         await preloadRegisteredServerActions(opts.root, dev);
@@ -310,6 +663,23 @@ export async function createNexusServer(opts) {
                     catch (err) {
                         console.error('[Nexus] Server action preload failed:', err);
                     }
+                    // Pre-warm the aggregated CSS cache in dev mode so that the very
+                    // first page load (and Cmd+R with "Disable cache" in DevTools) does
+                    // not stall waiting for CSS compilation.  The build runs in the
+                    // background — listen() resolves immediately while the CSS compiles
+                    // concurrently.  Any errors are swallowed; the first CSS request
+                    // will fall back to a normal on-demand build.
+                    if (dev) {
+                        buildAggregatedNxStylesheet(opts.root).catch(() => { });
+                        // Pre-warm global CSS and update renderOpts so SSR includes the link.
+                        buildGlobalStylesheet(opts.root, opts.cssEntry)
+                            .then((css) => {
+                            if (css !== null) {
+                                renderOpts.assets.styles = ['/_nexus/global.css', '/_nexus/styles.css'];
+                            }
+                        })
+                            .catch(() => { });
+                    }
                     server.listen(port, () => resolve());
                 })().catch(reject);
             });
@@ -318,10 +688,47 @@ export async function createNexusServer(opts) {
         async reload() {
             bumpDevReloadGeneration();
             bustAggregatedStylesCache();
+            bustGlobalStylesCache();
             manifest = await buildRouteManifest(routesDir);
             if (dev) {
                 await preloadRegisteredServerActions(opts.root, true);
                 refreshShieldAllowlist(opts.root, true);
+                // Re-evaluate whether a global CSS entry appeared/disappeared so SSR
+                // links stay in sync with the filesystem.
+                try {
+                    const hasGlobal = (await buildGlobalStylesheet(opts.root, opts.cssEntry)) !== null;
+                    renderOpts.assets.styles = hasGlobal
+                        ? ['/_nexus/global.css', '/_nexus/styles.css']
+                        : ['/_nexus/styles.css'];
+                }
+                catch {
+                    renderOpts.assets.styles = ['/_nexus/styles.css'];
+                }
+                // Pre-warm the aggregated CSS cache BEFORE telling the browser to reload.
+                // Without this, the sequence is:
+                //   1. bustAggregatedStylesCache() empties the cache
+                //   2. broadcastDevHotReload() triggers location.reload() in the browser
+                //   3. Browser fetches HTML (fast) then immediately requests /_nexus/styles.css
+                //   4. Cache is empty → server must recompile all .nx files (slow, 50-200ms)
+                //   5. HTML paints first → FOUC until CSS arrives
+                //
+                // By awaiting the CSS build here, the cache is warm before the browser
+                // reloads.  Step 4 becomes an instant cache-hit → styles apply before
+                // first paint, eliminating the flash of unstyled content.
+                try {
+                    await buildAggregatedNxStylesheet(opts.root);
+                }
+                catch {
+                    // CSS build failures are non-fatal — the browser will just get
+                    // whatever partial CSS the next request produces.
+                }
+                // Also pre-warm global CSS (Tailwind/PostCSS) so SSR includes it.
+                try {
+                    await buildGlobalStylesheet(opts.root, opts.cssEntry);
+                }
+                catch {
+                    /* non-fatal */
+                }
                 broadcastDevHotReload();
             }
         },
@@ -370,14 +777,23 @@ async function webToNodeResponse(response, res, mergeHeaders) {
     res.end(body);
 }
 async function serveStatic(pathname, publicDir) {
-    const safePath = join(publicDir, pathname.replace(/^\/+/, ''));
+    const root = resolve(publicDir);
+    const safePath = resolve(join(root, pathname.replace(/^\/+/, '')));
+    // Prevent path-traversal: resolved path must be inside publicDir
+    if (safePath !== root && !safePath.startsWith(root + sep))
+        return null;
     try {
         const info = await stat(safePath);
         if (!info.isFile())
             return null;
         const content = await readFile(safePath);
         const mime = MIME_TYPES[extname(safePath)] ?? 'application/octet-stream';
-        return { content, mime };
+        // ETag derived from size + mtime — fast (no content hash) and changes
+        // whenever the file is rewritten by an external watcher (e.g. Tailwind
+        // CLI, Vite's tw plugin, custom asset pipelines).  Quoted per RFC 7232.
+        const etag = `"${info.size.toString(16)}-${info.mtimeMs.toString(16)}"`;
+        const lastModified = info.mtime.toUTCString();
+        return { content, mime, etag, lastModified };
     }
     catch {
         return null;
@@ -386,28 +802,7 @@ async function serveStatic(pathname, publicDir) {
 function serverErrorPage(err, dev) {
     return devErrorHtmlPage({ context: '500 — unhandled', err, dev });
 }
-async function notFoundPage(pathname, dev, routesRoot, ctx, renderOpts) {
-    const boundary = await findNotFoundBoundary(join(routesRoot, '_'), routesRoot);
-    if (boundary) {
-        try {
-            const mod = await loadRouteModule(boundary, {
-                dev,
-                appRoot: renderOpts.appRoot,
-                pattern: '/not-found',
-            });
-            if (typeof mod.render === 'function') {
-                const result = await mod.render(ctx);
-                const html = result.html ?? '';
-                if (/^<\s*html[\s>]/i.test(html.trimStart()) || /^<!DOCTYPE/i.test(html.trimStart())) {
-                    return html;
-                }
-                return wrapWithDocument(html, renderOpts, [], 0, null);
-            }
-        }
-        catch (err) {
-            console.error('[Nexus] not-found.nx render error:', err);
-        }
-    }
+function notFoundPage(pathname, dev) {
     return `<!DOCTYPE html><html><body style="font-family:monospace;padding:2rem;background:#0a0a0f;color:#e8e8f0">
     <h1 style="color:#00d4aa">◆ Nexus — 404</h1>
     <p>No route found for <code style="color:#ff3e00">${pathname}</code></p>