fix(security): allow opting out of proxy page token in SSR payload (#789)

Author: harlan-zw

docs/content/docs/1.guides/2.first-party.md

@@ -280,6 +280,11 @@ export default defineNuxtConfig({
 // Auto-generate and persist a secret to .env in dev mode.
 // Set to false to disable.
  autoGenerateSecret: true,
+// Emit a per-request proxy page token into the SSR payload so
+// client-driven proxy calls authenticate without pre-signed URLs.
+// Set to false to keep the token out of the payload (e.g. for a
+// stable response etag); client-side calls then need signed URLs.
+ pageToken: true,
  }
  }
 })
@@ -303,6 +308,10 @@ The module only writes this when running `nuxt dev` with a signed endpoint enabl
 
 Page tokens are valid for 1 hour. If a user leaves a tab open longer than that, client-side proxy requests will start returning 403. The page will recover on next navigation or refresh.
 
+**Proxy token changes the response payload on every request**
+
+The module injects a per-request page token into the SSR payload, so the response hash differs each request. If you compute a stable `etag`, set `security.pageToken: false` to keep the token out of the payload. Client-side proxy calls will then need explicitly signed URLs.
+
 #### Static Generation and SPA Mode
 
 URL signing requires a server runtime to verify HMAC signatures. Two deployment modes cannot support signing:

packages/script/src/module.ts

@@ -408,6 +408,17 @@ export interface ModuleOptions {
  * @default 3600
  */
 pageTokenMaxAge?: number
+/**
+ * Emit a per-request proxy page token into the SSR payload so client-driven
+ * proxy calls authenticate without each URL being HMAC-signed up front.
+ *
+ * Set to `false` to keep the token out of the payload (e.g. when computing a
+ * stable response `etag`). Client-side proxy requests that rely on the token
+ * will then need explicitly signed URLs.
+ *
+ * @default true
+ */
+pageToken?: boolean
 }
 /**
  * Google Static Maps proxy configuration.
@@ -1058,10 +1069,14 @@ export default defineNuxtModule<ModuleOptions>({
 // Emit a per-request page token during SSR so client-driven proxy
 // calls (reactive fetches, dynamic image helpers) authenticate via
 // `_pt` + `_ts` without needing each URL to be HMAC-signed up front.
-addPlugin({
-src: awaitresolvePath('./runtime/plugins/proxy-token.server'),
-mode: 'server',
-})
+// Opt out via `security.pageToken: false` to keep the token out of the
+// SSR payload (e.g. for a stable response etag).
+if(config.security?.pageToken!==false){
+addPlugin({
+src: awaitresolvePath('./runtime/plugins/proxy-token.server'),
+mode: 'server',
+})
+}
 }
 elseif(!nuxt.options.dev){
 logger.warn(