From bfeb8f6cb3eb5d514271881fc9cd39a9ae184737 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 01:13:36 +0530
Subject: [PATCH 1/2] docs: explain the CSP nonce model across client-router
 soft navigations

Add a 'CSP and the client router' subsection to the security docs page and a
paragraph to the built-ins reference: enforcement is the HTTP header (not a
meta http-equiv tag), the meta name=csp-nonce is a client-side carrier, and on
a soft navigation the original page-load nonce stays authoritative and is
re-stamped onto every dynamically-inserted script/preload (#1049/#1052). Gives
users setting up strict CSP the why behind the model.
---
 .agents/skills/webjs/references/built-ins.md | 2 ++
 docs/app/docs/security/page.ts               | 4 ++++
 2 files changed, 6 insertions(+)

diff --git a/.agents/skills/webjs/references/built-ins.md b/.agents/skills/webjs/references/built-ins.md
index af13ea36a..58f554afb 100644
--- a/.agents/skills/webjs/references/built-ins.md
+++ b/.agents/skills/webjs/references/built-ins.md
@@ -136,6 +136,8 @@ On by default (`X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`,
 
 Off by default. `{ "webjs": { "csp": true } }` enables a strict-dynamic + per-request nonce posture. An object form merges `directives` and supports `reportOnly`. Read the nonce with `cspNonce()` from `@webjsdev/core` to stamp your own inline `<script>`.
 
+Enforcement is the HTTP `Content-Security-Policy` HEADER, never a `<meta http-equiv>` tag, so `frame-ancestors` / `report-uri` work. The emitted `<meta name="csp-nonce">` is only the client-side nonce CARRIER. Across a client-router soft navigation the ORIGINAL page-load nonce stays authoritative (the browser enforces the original document's CSP header, not the fetched response's fresh one), so the router preserves that meta and re-stamps every dynamically-inserted script / preload with the original nonce via `getCspNonce()`. The server still mints a fresh nonce per request, and CSP pages are excluded from the HTML cache so a nonce is never served stale. No client config is needed.
+
 ### Redirects, trailing-slash, basePath, allowed origins
 
 ```jsonc
diff --git a/docs/app/docs/security/page.ts b/docs/app/docs/security/page.ts
index 623429eb0..6cef8ffb7 100644
--- a/docs/app/docs/security/page.ts
+++ b/docs/app/docs/security/page.ts
@@ -48,6 +48,10 @@ export default function Security() {
     <p>CSP is off by default and enabled with a <code>webjs.csp</code> key in <code>package.json</code> (<code>true</code> for a strict default policy, or an object to customize directives and toggle report-only). When enabled the server mints a fresh per-request CSPRNG nonce, stamps it on the inline boot script, the importmap, and the modulepreload hints, and emits a matching <code>Content-Security-Policy</code> header carrying that exact nonce. One value flows from mint to header, so there is no drift, and it changes every request.</p>
     <p>To stamp the nonce on your own inline <code>&lt;script&gt;</code>, read it during SSR with <code>import { cspNonce } from '@webjsdev/core'</code>. For a strict <code>script-src 'self'</code> deploy with no CDN, pair CSP with <code>webjs vendor pin --download</code> so vendor bundles serve from your own origin. See <a href="/docs/configuration">Configuration</a> for the directive reference.</p>
 
+    <h3>CSP and the client router</h3>
+    <p>The policy is enforced by the <code>Content-Security-Policy</code> response HEADER, never by a <code>&lt;meta http-equiv&gt;</code> tag, so directives like <code>frame-ancestors</code> and <code>report-uri</code> that a meta-tag CSP cannot express work normally. The <code>&lt;meta name="csp-nonce"&gt;</code> tag WebJs emits is not an enforcement mechanism, it is a carrier: the client router reads the nonce from it to stamp any element it inserts.</p>
+    <p>This matters on a soft navigation. The browser keeps enforcing the ORIGINAL page load's CSP header, because a fetched response's CSP never binds to the already-live document, so the ORIGINAL nonce stays authoritative for the whole session. The router therefore preserves that first <code>&lt;meta name="csp-nonce"&gt;</code> across every swap and re-stamps each script, module preload, and inline script it inserts with the original nonce (via <code>getCspNonce()</code>), even though the server minted a fresh nonce for the navigation response. Nothing gets blocked, and you configure nothing. It is the client-side equivalent of the Rails and Turbo reuse-the-original-nonce workaround. CSP pages are also excluded from the server HTML cache, so a nonce is never replayed stale.</p>
+
     <h2>Secure headers and HSTS</h2>
     <p>Every response carries a baseline of standard security headers, so a scaffolded app is not clickjackable or MIME-sniffable without a reverse proxy:</p>
     <ul>

From 9ac544cd925a290e054c83063cc7713fffbf50b7 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Thu, 23 Jul 2026 01:18:32 +0530
Subject: [PATCH 2/2] docs: scope the soft-nav nonce claim to the document, not
 the session

Review: 'the ORIGINAL nonce stays authoritative for the whole session'
overstated. It holds for the life of the current document. A hard reload or
full page load creates a new document with the response's own fresh nonce.
Reword and add the harmless-full-load case so soft-nav vs hard-reload is
clear (the built-ins reference already stated this conservatively).
---
 docs/app/docs/security/page.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/app/docs/security/page.ts b/docs/app/docs/security/page.ts
index 6cef8ffb7..f3edaa1fc 100644
--- a/docs/app/docs/security/page.ts
+++ b/docs/app/docs/security/page.ts
@@ -50,7 +50,7 @@ export default function Security() {
 
     <h3>CSP and the client router</h3>
     <p>The policy is enforced by the <code>Content-Security-Policy</code> response HEADER, never by a <code>&lt;meta http-equiv&gt;</code> tag, so directives like <code>frame-ancestors</code> and <code>report-uri</code> that a meta-tag CSP cannot express work normally. The <code>&lt;meta name="csp-nonce"&gt;</code> tag WebJs emits is not an enforcement mechanism, it is a carrier: the client router reads the nonce from it to stamp any element it inserts.</p>
-    <p>This matters on a soft navigation. The browser keeps enforcing the ORIGINAL page load's CSP header, because a fetched response's CSP never binds to the already-live document, so the ORIGINAL nonce stays authoritative for the whole session. The router therefore preserves that first <code>&lt;meta name="csp-nonce"&gt;</code> across every swap and re-stamps each script, module preload, and inline script it inserts with the original nonce (via <code>getCspNonce()</code>), even though the server minted a fresh nonce for the navigation response. Nothing gets blocked, and you configure nothing. It is the client-side equivalent of the Rails and Turbo reuse-the-original-nonce workaround. CSP pages are also excluded from the server HTML cache, so a nonce is never replayed stale.</p>
+    <p>This matters on a soft navigation. The browser keeps enforcing the ORIGINAL page load's CSP header, because a fetched response's CSP never binds to the already-live document, so the ORIGINAL nonce stays authoritative for the life of that document. The router therefore preserves that first <code>&lt;meta name="csp-nonce"&gt;</code> across every swap and re-stamps each script, module preload, and inline script it inserts with the original nonce (via <code>getCspNonce()</code>), even though the server minted a fresh nonce for the navigation response. A hard reload or a full page load is the harmless case: it creates a NEW document that enforces that response's own fresh nonce, so the nonce stays consistent either way. Nothing gets blocked, and this needs no configuration. It is the client-side equivalent of the Rails and Turbo reuse-the-original-nonce workaround. CSP pages are also excluded from the server HTML cache, so a nonce is never replayed stale.</p>
 
     <h2>Secure headers and HSTS</h2>
     <p>Every response carries a baseline of standard security headers, so a scaffolded app is not clickjackable or MIME-sniffable without a reverse proxy:</p>