feat(security): HMAC signing infrastructure for proxy endpoints

Adds the foundation for locking down proxy endpoints (Google Maps, Gravatar,
embed image proxies) against cost/quota abuse. Signed URLs are generated
server-side during SSR/prerender and verified at the endpoint so only
legitimate requests reach upstream APIs.

- sign/verify primitives with canonical query form and constant-time compare
- withSigning handler wrapper (opt-in per endpoint via requiresSigning flag)
- Secret management: env var > config > dev auto-generate to .env
- /_scripts/sign endpoint for reactive client-side URLs (origin + rate-limited)
- nuxt-scripts CLI with generate-secret command for explicit secret setup

No existing endpoints are wired to signing yet; this PR is infrastructure only.

Author: harlan-zw

packages/script/bin/cli.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/cli.mjs')

packages/script/build.config.ts

@@ -6,6 +6,7 @@ export default defineBuildConfig({
     './src/registry',
     './src/stats',
     './src/types-source',
+    './src/cli',
   ],
   externals: [
     'nuxt',

packages/script/package.json

@@ -45,7 +45,11 @@
       ]
     }
   },
+  "bin": {
+    "nuxt-scripts": "./bin/cli.mjs"
+  },
   "files": [
+    "bin",
     "dist"
   ],
   "scripts": {

packages/script/src/cli.ts

@@ -0,0 +1,67 @@
+/**
+ * @nuxt/scripts CLI.
+ *
+ * Currently hosts a single command — `generate-secret` — which produces a
+ * cryptographically random HMAC secret for `NUXT_SCRIPTS_PROXY_SECRET`. This
+ * is an alternative to letting the module auto-write a secret into `.env`,
+ * for users who want explicit control (e.g. teams that commit secrets to a
+ * vault rather than `.env`).
+ *
+ * Keep this file zero-dependency: it runs standalone via `npx @nuxt/scripts`
+ * and should boot instantly.
+ */
+
+import { randomBytes } from 'node:crypto'
+import process from 'node:process'
+
+function generateSecret(): void {
+  const secret = randomBytes(32).toString('hex')
+  process.stdout.write(
+    [
+      '',
+      '  @nuxt/scripts — proxy signing secret',
+      '',
+      `  Secret: ${secret}`,
+      '',
+      '  Add this to your environment:',
+      `    NUXT_SCRIPTS_PROXY_SECRET=${secret}`,
+      '',
+      '  The secret is automatically picked up by the module via runtime config.',
+      '  It must be the same across all deployments and prerender builds so that',
+      '  signed URLs remain valid.',
+      '',
+      '',
+    ].join('\n'),
+  )
+}
+
+function showHelp(): void {
+  process.stdout.write(
+    [
+      '',
+      '  @nuxt/scripts CLI',
+      '',
+      '  Usage: npx @nuxt/scripts <command>',
+      '',
+      '  Commands:',
+      '    generate-secret   Generate a signing secret for proxy URL tamper protection',
+      '    help              Show this help',
+      '',
+      '',
+    ].join('\n'),
+  )
+}
+
+const command = process.argv[2]
+
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  showHelp()
+}
+else if (command === 'generate-secret') {
+  generateSecret()
+}
+else {
+  process.stderr.write(`Unknown command: ${command}\n`)
+  showHelp()
+  process.exit(1)
+}

packages/script/src/module.ts

@@ -13,7 +13,8 @@ import type {
   RegistryScripts,
   ResolvedProxyAutoInject,
 } from './runtime/types'
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { appendFileSync, existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import {
   addBuildPlugin,
   addComponentsDir,
@@ -114,6 +115,80 @@ function fixSelfClosingScriptComponents(nuxt: any) {
 const UPPER_RE = /([A-Z])/g
 const toScreamingSnake = (s: string) => s.replace(UPPER_RE, '_$1').toUpperCase()
 
+const PROXY_SECRET_ENV_KEY = 'NUXT_SCRIPTS_PROXY_SECRET'
+const PROXY_SECRET_ENV_LINE_RE = /^NUXT_SCRIPTS_PROXY_SECRET=/m
+const PROXY_SECRET_ENV_VALUE_RE = /^NUXT_SCRIPTS_PROXY_SECRET=(.+)$/m
+const WILDCARD_SUFFIX_RE = /\/\*\*$/
+
+export interface ResolvedProxySecret {
+  secret: string
+  /** True when the secret exists only in memory (dev-only fallback; won't survive restarts). */
+  ephemeral: boolean
+  /** Where the secret came from, for logging. */
+  source: 'config' | 'env' | 'dotenv-generated' | 'memory-generated'
+}
+
+/**
+ * Resolve the HMAC signing secret used for proxy URL signing.
+ *
+ * Precedence:
+ * 1. `scripts.security.secret` in nuxt.config
+ * 2. `NUXT_SCRIPTS_PROXY_SECRET` env var
+ * 3. Dev-only auto-generation: write to `.env` (or keep in memory as last resort)
+ * 4. Empty string (prod without secret — caller decides whether this is fatal)
+ */
+export function resolveProxySecret(
+  rootDir: string,
+  isDev: boolean,
+  configSecret?: string,
+  autoGenerate: boolean = true,
+): ResolvedProxySecret | undefined {
+  if (configSecret)
+    return { secret: configSecret, ephemeral: false, source: 'config' }
+
+  const envSecret = process.env[PROXY_SECRET_ENV_KEY]
+  if (envSecret)
+    return { secret: envSecret, ephemeral: false, source: 'env' }
+
+  if (!isDev || !autoGenerate)
+    return undefined
+
+  // Dev fallback: generate a 32-byte hex secret and try to persist to .env.
+  // Persisting matters because the same dev machine restarts many times and
+  // we don't want signed URLs cached in the browser to stop working across HMR.
+  const secret = randomBytes(32).toString('hex')
+  const envPath = resolvePath_(rootDir, '.env')
+  const line = `${PROXY_SECRET_ENV_KEY}=${secret}\n`
+
+  try {
+    if (existsSync(envPath)) {
+      const contents = readFileSync(envPath, 'utf-8')
+      // Safety: don't append if another process already wrote one between the read above
+      // and this branch. The regex check is cheap and idempotent.
+      if (PROXY_SECRET_ENV_LINE_RE.test(contents)) {
+        // Another instance already wrote it — re-read and return that value
+        const match = contents.match(PROXY_SECRET_ENV_VALUE_RE)
+        if (match?.[1])
+          return { secret: match[1].trim(), ephemeral: false, source: 'dotenv-generated' }
+      }
+      appendFileSync(envPath, contents.endsWith('\n') ? line : `\n${line}`)
+    }
+    else {
+      writeFileSync(envPath, `# Generated by @nuxt/scripts\n${line}`)
+    }
+    // Also populate process.env so that anything reading it later in the same
+    // dev process (e.g. child workers) sees the value without a restart.
+    process.env[PROXY_SECRET_ENV_KEY] = secret
+    return { secret, ephemeral: false, source: 'dotenv-generated' }
+  }
+  catch {
+    // Writing .env failed (read-only FS, permission denied). Fall back to
+    // in-memory only — URLs signed this session won't verify after restart.
+    process.env[PROXY_SECRET_ENV_KEY] = secret
+    return { secret, ephemeral: true, source: 'memory-generated' }
+  }
+}
+
 export function isProxyDisabled(
   registryKey: string,
   registry?: NuxtConfigScriptRegistry,
@@ -227,6 +302,38 @@ export interface ModuleOptions {
      */
     integrity?: boolean | 'sha256' | 'sha384' | 'sha512'
   }
+  /**
+   * 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
+   * signing, these are open to cost/quota abuse. Enable signing to require that only
+   * URLs generated server-side (during SSR/prerender, or via `/_scripts/sign`) are
+   * accepted.
+   *
+   * The secret must be deterministic across deployments so that prerendered URLs
+   * remain valid. Set it via `NUXT_SCRIPTS_PROXY_SECRET` or `security.secret`.
+   */
+  security?: {
+    /**
+     * HMAC secret used to sign proxy URLs.
+     *
+     * Falls back to `process.env.NUXT_SCRIPTS_PROXY_SECRET` if unset. In dev,
+     * the module auto-generates a secret into your `.env` file when neither is
+     * provided (disable via `autoGenerateSecret: false`). In production, a
+     * missing secret is a fatal error when any signed endpoint is registered.
+     *
+     * Generate one with: `npx @nuxt/scripts generate-secret`
+     */
+    secret?: string
+    /**
+     * Automatically generate and persist a signing secret to `.env` when running
+     * `nuxt dev` without one configured.
+     *
+     * @default true
+     */
+    autoGenerateSecret?: boolean
+  }
   /**
    * Google Static Maps proxy configuration.
    * Proxies static map images through your server to fix CORS issues and enable caching.
@@ -374,11 +481,28 @@ export default defineNuxtModule<ModuleOptions>({
       )
     }
 
+    // Resolve the HMAC signing secret used to lock down proxy endpoints.
+    // Deterministic across deploys is mandatory: signed URLs embedded in prerendered
+    // HTML must still verify against the runtime server. The module auto-generates
+    // and persists one into `.env` in dev so users don't hit friction on first run.
+    const proxySecretResolved = resolveProxySecret(
+      nuxt.options.rootDir,
+      !!nuxt.options.dev,
+      config.security?.secret,
+      config.security?.autoGenerateSecret !== false,
+    )
+    if (proxySecretResolved?.source === 'dotenv-generated')
+      logger.info(`[security] Generated ${PROXY_SECRET_ENV_KEY} in .env for signed proxy URLs.`)
+    else if (proxySecretResolved?.source === 'memory-generated')
+      logger.warn(`[security] Generated an in-memory ${PROXY_SECRET_ENV_KEY} (could not write .env). Signed URLs will break across restarts.`)
+
     // Setup runtimeConfig for proxies and devtools.
     // Must run AFTER env var resolution above so the API key is populated.
     const googleMapsEnabled = config.googleStaticMapsProxy?.enabled || !!config.registry?.googleMaps
     nuxt.options.runtimeConfig['nuxt-scripts'] = {
       version: version!,
+      // HMAC secret for signed proxy URLs (server-only private config)
+      proxySecret: proxySecretResolved?.secret || '',
       // Private proxy config with API key (server-side only)
       googleStaticMapsProxy: googleMapsEnabled
         ? { apiKey: (nuxt.options.runtimeConfig.public.scripts as any)?.googleMaps?.apiKey }
@@ -697,6 +821,9 @@ export default defineNuxtModule<ModuleOptions>({
     // Register server handlers for enabled registry scripts
     const scriptsPrefix = config.prefix || '/_scripts'
     const enabledEndpoints: Record<string, boolean> = {}
+    /** Signable routes that the `/_scripts/sign` endpoint is allowed to sign. */
+    const signableRoutes: string[] = []
+    let anyHandlerRequiresSigning = false
     for (const script of scripts) {
       if (!script.serverHandlers?.length || !script.registryKey)
         continue
@@ -711,11 +838,17 @@ export default defineNuxtModule<ModuleOptions>({
 
       enabledEndpoints[script.registryKey] = true
       for (const handler of script.serverHandlers) {
+        const resolvedRoute = handler.route.replace('/_scripts', scriptsPrefix)
         addServerHandler({
-          route: handler.route.replace('/_scripts', scriptsPrefix),
+          route: resolvedRoute,
           handler: handler.handler,
           middleware: handler.middleware,
         })
+        if (handler.requiresSigning) {
+          anyHandlerRequiresSigning = true
+          // Store the non-wildcard prefix so `/sign` can exact-match against it.
+          signableRoutes.push(resolvedRoute.replace(WILDCARD_SUFFIX_RE, ''))
+        }
       }
 
       // Script-specific runtimeConfig setup
@@ -740,5 +873,33 @@ export default defineNuxtModule<ModuleOptions>({
       { endpoints: enabledEndpoints },
       nuxt.options.runtimeConfig.public['nuxt-scripts'] as any,
     ) as any
+
+    // Fail hard if a signed endpoint is enabled in production without a secret.
+    // Dev falls back to auto-generated secrets above, so this only trips real
+    // deployments that forgot to set the env var.
+    if (anyHandlerRequiresSigning && !proxySecretResolved?.secret && !nuxt.options.dev) {
+      throw new Error(
+        `[@nuxt/scripts] ${PROXY_SECRET_ENV_KEY} is required in production when signed proxy endpoints are enabled.\n`
+        + 'Generate one with: npx @nuxt/scripts generate-secret\n'
+        + `Then set the env var: ${PROXY_SECRET_ENV_KEY}=<secret>`,
+      )
+    }
+
+    // Publish the signable routes list to server runtime so `/sign` knows what
+    // paths it's allowed to sign on behalf of clients.
+    if (anyHandlerRequiresSigning) {
+      nuxt.options.runtimeConfig['nuxt-scripts'] = defu(
+        { signableRoutes },
+        nuxt.options.runtimeConfig['nuxt-scripts'] as any,
+      ) as any
+
+      // Register the `/_scripts/sign` endpoint so reactive client-side URL
+      // changes (e.g. Google Static Maps size recomputed on mount) can get a
+      // fresh signature without exposing the secret.
+      addServerHandler({
+        route: `${scriptsPrefix}/sign`,
+        handler: await resolvePath('./runtime/server/sign-proxy'),
+      })
+    }
   },
 })