docs: add proxy endpoint security section to first-party guide

Documents HMAC URL signing, page tokens, the generate-secret CLI,
dev auto-generation, and production setup requirements.

Author: harlan-zw

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

@@ -200,6 +200,60 @@ The same pattern applies to [Netlify](https://netlify.com) (`[[redirects]]` with
 Platform-level rewrites bypass the privacy anonymisation layer. The proxy handler only runs in a Nitro server runtime.
 ::
 
+## Proxy Endpoint Security
+
+Several proxy endpoints (Google Static Maps, Geocode, Gravatar, embed image proxies) inject server-side API keys or forward requests to third-party services. Without protection, anyone who discovers these endpoints could call them directly and consume your API quota.
+
+### HMAC URL Signing
+
+The module provides optional HMAC signing to lock down proxy endpoints. When enabled, only URLs generated server-side (during SSR or prerender) or accompanied by a valid page token are accepted. Unsigned requests receive a `403`.
+
+#### Setup
+
+Generate a signing secret:
+
+```bash
+npx @nuxt/scripts generate-secret
+```
+
+Then set it as an environment variable:
+
+```bash
+NUXT_SCRIPTS_PROXY_SECRET=<your-secret>
+```
+
+Or configure it directly:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    security: {
+      secret: process.env.NUXT_SCRIPTS_PROXY_SECRET,
+    }
+  }
+})
+```
+
+#### How It Works
+
+The module uses two verification modes:
+
+1. **URL signatures** for server-rendered content. During SSR/prerender, proxy URLs include a `sig` parameter: an HMAC of the path and query params. The proxy endpoint verifies the signature before forwarding.
+
+2. **Page tokens** for client-side reactive updates. Some components recompute their proxy URL after mount (e.g. measuring element dimensions). The server embeds a short-lived token (`_pt` + `_ts` params) in the SSR payload. The token is valid for any params on any proxy path and expires after 1 hour.
+
+#### Development
+
+In development, the module auto-generates a secret and writes it to your `.env` file on first run. You don't need to configure anything for local dev.
+
+#### Production
+
+Set `NUXT_SCRIPTS_PROXY_SECRET` in your deployment environment. The secret must be the same across all replicas and across build/runtime so that URLs signed at prerender time remain valid.
+
+::callout{type="warning"}
+Without a secret, proxy endpoints remain functional but unprotected. The module logs a warning at startup when it detects signed endpoints without a secret.
+::
+
 ## Supported Scripts
 
 ### Full First-Party (Bundled + Proxied)