feat: sign og image urls by default

Previously runtime OG image URLs were only signed when a `security.secret`
was configured; without one the `/_og/d/**` endpoint accepted arbitrary
unsigned requests. Now a per-build secret is auto-generated when none is set,
so URL signing is on by default with no configuration.

- Resolve the signing secret via a pure `resolveSigningSecret()`: explicit
  opt-out (`secret: false`) > explicit config/env value > auto-generated.
- The auto value is random, server-only, and baked into the build. It is
  stable within a build artifact (runtime sign + verify agree) but rotates per
  build, so an explicit secret is still recommended for rolling/multi-instance
  deploys — surfaced via a dev warning, gated on having a server runtime (no
  warning for pure SSG/static builds).
- Only an explicit secret is baked into the `ogImage.secret` override channel,
  keeping the `NUXT_OG_IMAGE_SECRET` runtime override (e.g. Cloudflare env)
  reachable. The auto value lives solely in the build-time `security.secret`.
- `strict` still requires an explicit secret (the auto value's per-build
  rotation isn't a strong enough guarantee).
- `security.secret: false` disables signing entirely.

Test fixtures that assert unsigned dynamic URLs (basic, cloudflare-satori,
vercel-edge-satori) opt out via `secret: false`; signing remains covered by the
url-signing unit tests and the cloudflare-runtime-config e2e.

Author: harlan-zw

docs/content/3.guides/13.security.md

@@ -44,11 +44,29 @@ npx nuxt-og-image generate-secret
 
 ## URL Signing
 
-When you configure a signing secret, every OG image URL includes a cryptographic signature in the path. The server verifies this signature before rendering, rejecting any URL that has been tampered with or crafted manually.
+OG image URLs are signed by default. Every URL includes a cryptographic signature in the path, and the server rejects any runtime request whose signature is missing or invalid with a `403`. This prevents unauthorized image generation requests that would otherwise consume server resources.
 
-This prevents unauthorized image generation requests that would otherwise consume server resources.
+### Default: auto-generated secret
 
-### Setup
+When you do not configure a secret, the module generates a random one at build time, so signing works with no setup. The auto-generated secret **changes on every build**. That is fine for prerendered images (served as static files) and single-instance runtime deploys, but during a rolling or multi-instance deploy a URL signed by one build can fail verification on another.
+
+For those deploys, set a stable secret so every instance shares the same value.
+
+### Disabling signing
+
+To serve unsigned runtime URLs (not recommended), set `secret` to `false`:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  ogImage: {
+    security: {
+      secret: false,
+    }
+  }
+})
+```
+
+### Setup (stable secret)
 
 1. Generate a secret:
 
@@ -76,7 +94,7 @@ export default defineNuxtConfig({
 
 ### How It Works
 
-When you configure a secret:
+With signing active:
 - `defineOgImage()`{lang="ts"} appends a signature to the URL path: `/_og/d/w_1200,h_600,s_abc123def456.png`
 - The server extracts and verifies the signature before processing the request
 - Requests with missing or invalid signatures receive a `403` response

docs/content/4.api/3.config.md

@@ -197,7 +197,7 @@ See the [Browser Renderer](/docs/og-image/renderers/browser) guide for more deta
 
 Security limits for image generation. See the [Security Guide](/docs/og-image/guides/security) for full details.
 
-- **`secret`**: Signing secret for URL tamper protection. When set, all runtime OG image URLs are signed and unsigned requests are rejected with `403`. Generate one with `npx nuxt-og-image generate-secret`. See the [Security Guide](/docs/og-image/guides/security#url-signing) for details.
+- **`secret`**: Signing secret for URL tamper protection. Runtime OG image URLs are signed by default; unsigned requests are rejected with `403`. Leave unset to auto-generate a per-build secret, set an explicit stable string for rolling/multi-instance deploys, or `false` to disable signing. Generate one with `npx nuxt-og-image generate-secret`. See the [Security Guide](/docs/og-image/guides/security#url-signing) for details.
 - **`maxDimension`**: Maximum width or height in pixels. Default `2048`.
 - **`maxDpr`**: Maximum device pixel ratio (Takumi renderer). Default `2`.
 - **`renderTimeout`**: Milliseconds before the render is aborted with a `408` response. Default `15000`.

src/build/signing-secret.ts

@@ -0,0 +1,36 @@
+export interface SigningSecretResolution {
+  /** Secret to bake into the runtime config (`''` when signing is disabled). */
+  secret: string
+  /** True when the user provided an explicit secret (config value or env var). */
+  hasExplicit: boolean
+  /** True when the user explicitly disabled signing via `security.secret: false`. */
+  optOut: boolean
+  /** True when `secret` was auto-generated (no explicit value, not opted out). */
+  generated: boolean
+}
+
+/**
+ * Resolve the URL-signing secret at build time.
+ *
+ * Precedence: explicit opt-out (`secret: false`) → explicit config/env value →
+ * auto-generated. Auto-generation turns signing on by default; the generated
+ * value is random and server-only but rotates per build, so an explicit secret
+ * is still recommended for rolling/multi-instance deploys.
+ *
+ * `generate` is injected so callers control the source (and tests stay
+ * deterministic); production passes a CSPRNG.
+ */
+export function resolveSigningSecret(
+  configSecret: string | false | undefined,
+  envSecret: string | undefined,
+  generate: () => string,
+): SigningSecretResolution {
+  if (configSecret === false)
+    return { secret: '', hasExplicit: false, optOut: true, generated: false }
+
+  const explicit = (configSecret || '') || (envSecret || '')
+  if (explicit)
+    return { secret: explicit, hasExplicit: true, optOut: false, generated: false }
+
+  return { secret: generate(), hasExplicit: false, optOut: false, generated: true }
+}

src/module.ts

@@ -15,6 +15,7 @@ import type {
   RuntimeCompatibilityMeta,
   RuntimeCompatibilitySchema,
 } from './runtime/types'
+import { randomBytes } from 'node:crypto'
 import * as fs from 'node:fs'
 import { existsSync } from 'node:fs'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
@@ -39,6 +40,7 @@ import {
 import { setupGenerateHandler } from './build/generate'
 import { setupPrerenderHandler } from './build/prerender'
 import { extractPropNamesFromVue, loadSfcCompiler } from './build/props'
+import { resolveSigningSecret } from './build/signing-secret'
 import { TreeShakeComposablesPlugin } from './build/tree-shake-plugin'
 import { AssetTransformPlugin } from './build/vite-asset-transform'
 import { ComponentImportRewritePlugin } from './build/vite-component-import-rewrite'
@@ -302,12 +304,14 @@ export interface ModuleOptions {
      * keyed hash signature and the handler rejects requests with missing or
      * invalid signatures.
      *
-     * Must be a stable string across deployments. Generate one with:
+     * Leave unset to auto-generate a per-build secret (signing on by default).
+     * Set an explicit, stable string for rolling or multi-instance deploys, or
+     * `false` to disable signing entirely. Generate one with:
      * `npx nuxt-og-image generate-secret`
      *
-     * Required when `strict` is enabled.
+     * Required (explicitly) when `strict` is enabled.
      */
-    secret?: string
+    secret?: string | false
     /**
      * Enable strict security mode. When enabled:
      * - `secret` is required (URL signing)
@@ -421,25 +425,41 @@ export default defineNuxtModule<ModuleOptions>({
       logger.warn('`ogImage.debug` is enabled in production. This exposes the `/_og/debug.json` endpoint and should not be enabled in production. Disable it before deploying.')
     }
 
-    const hasSecret = !!(config.security?.secret || process.env.NUXT_OG_IMAGE_SECRET)
+    // Resolve the URL-signing secret. No explicit secret → auto-generate one so
+    // signing is on by default; the value is random, server-only, and baked into
+    // the build (stable within a build artifact so runtime sign + verify agree).
+    const signing = resolveSigningSecret(
+      config.security?.secret,
+      process.env.NUXT_OG_IMAGE_SECRET,
+      () => randomBytes(32).toString('base64url'),
+    )
+    const resolvedSecret = signing.secret
 
-    if (config.security?.strict && !hasSecret) {
+    // Strict still requires an explicit, stable secret — the auto value's
+    // per-build rotation isn't a strong enough guarantee for strict mode.
+    if (config.security?.strict && !signing.hasExplicit) {
       throw new Error('[nuxt-og-image] `security.strict` requires a signing secret. Generate one with: npx nuxt-og-image generate-secret')
     }
 
-    if (nuxt.options.dev && !config.zeroRuntime && !hasSecret) {
-      logger.warn([
-        'OG image URLs are not signed. Anyone can craft arbitrary image generation requests.',
-        '',
-        'Set a signing secret via env variable:',
-        '  NUXT_OG_IMAGE_SECRET=<secret>',
-        '',
-        '  Generate one with: npx nuxt-og-image generate-secret',
-        '',
-        'Or enable zero-runtime mode to disable dynamic generation entirely:',
-        '  ogImage: { zeroRuntime: true }',
-      ].join('\n'))
-    }
+    // Signing only happens at runtime, so the secret warnings are irrelevant for
+    // pure SSG/static deploys (no server, images served as files). Defer them to
+    // nitro:init where `nitro.options.static` authoritatively reflects the preset.
+    nuxt.hook('nitro:init', (nitro) => {
+      const hasServerRuntime = !nitro.options.static && !(nuxt.options as any)._generate
+      if (!nuxt.options.dev || config.zeroRuntime || !hasServerRuntime)
+        return
+      if (signing.optOut) {
+        logger.warn('OG image URL signing is disabled (`security.secret: false`). Anyone can craft arbitrary image generation requests.')
+      }
+      else if (signing.generated) {
+        logger.warn([
+          'OG image URLs are signed with an auto-generated secret that changes every build.',
+          'This is fine for single-instance deploys; for rolling or multi-instance deploys set a stable secret:',
+          '  NUXT_OG_IMAGE_SECRET=<secret>',
+          '  Generate one with: npx nuxt-og-image generate-secret',
+        ].join('\n'))
+      }
+    })
 
     // Check for removed/deprecated config options
     const ogImageConfig = config as unknown as Record<string, unknown>
@@ -1629,7 +1649,7 @@ export const rootDir = ${JSON.stringify(nuxt.options.rootDir)}`
           restrictRuntimeImagesToOrigin: config.security?.restrictRuntimeImagesToOrigin === true || (config.security?.strict && config.security?.restrictRuntimeImagesToOrigin == null)
             ? []
             : (config.security?.restrictRuntimeImagesToOrigin || false),
-          secret: config.security?.secret || process.env.NUXT_OG_IMAGE_SECRET || '',
+          secret: resolvedSecret,
         },
       }
       if (nuxt.options.dev) {
@@ -1647,10 +1667,15 @@ export const rootDir = ${JSON.stringify(nuxt.options.rootDir)}`
       // Read by useOgImageRuntimeConfig and prefers this value over security.secret
       // when set, allowing runtime overrides on platforms like Cloudflare Workers
       // where env bindings are surfaced through the event context.
+      // Only an EXPLICIT secret is baked into this override channel — never the
+      // auto-generated one. Leaving it empty when auto-generating keeps the
+      // `NUXT_OG_IMAGE_SECRET` runtime override (e.g. Cloudflare env bindings)
+      // reachable; the auto value lives solely in the build-time `security.secret`
+      // fallback below, which the runtime override still supersedes.
       const existingOgImageCfg = (nuxt.options.runtimeConfig as Record<string, any>).ogImage
       ;(nuxt.options.runtimeConfig as Record<string, any>).ogImage = {
         ...(existingOgImageCfg && typeof existingOgImageCfg === 'object' ? existingOgImageCfg : {}),
-        secret: (existingOgImageCfg as any)?.secret || config.security?.secret || process.env.NUXT_OG_IMAGE_SECRET || '',
+        secret: (existingOgImageCfg as any)?.secret || (signing.hasExplicit ? signing.secret : ''),
       }
 
       // Non-sensitive subset exposed to the browser so defineOgImage can refresh

test/fixtures/basic/nuxt.config.ts

@@ -13,6 +13,12 @@ export default defineNuxtConfig({
 
   ogImage: {
     debug: true,
+    // URLs are signed by default; these tests assert unsigned dynamic URLs and
+    // hand-construct /_og/d/ requests. Signing is covered by the url-signing unit
+    // tests and the cloudflare-runtime-config e2e.
+    security: {
+      secret: false,
+    },
   },
 
   routeRules: {

test/fixtures/cloudflare-satori/nuxt.config.ts

@@ -24,6 +24,11 @@ export default defineNuxtConfig({
     defaults: {
       renderer: 'satori',
     },
+    // Signing is on by default; this fixture hand-constructs unsigned /_og/d/
+    // requests at runtime. Disable signing here (covered elsewhere).
+    security: {
+      secret: false,
+    },
   },
 
   nitro: {

test/fixtures/vercel-edge-satori/nuxt.config.ts

@@ -16,6 +16,11 @@ export default defineNuxtConfig({
     defaults: {
       renderer: 'satori',
     },
+    // Signing is on by default; this test rewrites the static og:image URL to an
+    // unsigned /_og/d/ request. Disable signing here (covered elsewhere).
+    security: {
+      secret: false,
+    },
   },
 
   nitro: {

test/unit/signing-secret.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest'
+import { resolveSigningSecret } from '../../src/build/signing-secret'
+
+const gen = () => 'GENERATED'
+
+describe('resolveSigningSecret', () => {
+  it('uses an explicit config secret', () => {
+    const r = resolveSigningSecret('cfg-secret', undefined, gen)
+    expect(r).toEqual({ secret: 'cfg-secret', hasExplicit: true, optOut: false, generated: false })
+  })
+
+  it('falls back to the env secret when no config value', () => {
+    const r = resolveSigningSecret(undefined, 'env-secret', gen)
+    expect(r).toEqual({ secret: 'env-secret', hasExplicit: true, optOut: false, generated: false })
+  })
+
+  it('prefers the config secret over the env secret', () => {
+    const r = resolveSigningSecret('cfg-secret', 'env-secret', gen)
+    expect(r.secret).toBe('cfg-secret')
+  })
+
+  it('auto-generates when neither config nor env is set', () => {
+    const generate = vi.fn(() => 'RANDOM')
+    const r = resolveSigningSecret(undefined, undefined, generate)
+    expect(generate).toHaveBeenCalledOnce()
+    expect(r).toEqual({ secret: 'RANDOM', hasExplicit: false, optOut: false, generated: true })
+  })
+
+  it('treats an empty-string config/env as unset and auto-generates', () => {
+    const r = resolveSigningSecret('', '', gen)
+    expect(r).toEqual({ secret: 'GENERATED', hasExplicit: false, optOut: false, generated: true })
+  })
+
+  it('opts out of signing entirely on `secret: false`', () => {
+    const generate = vi.fn(gen)
+    const r = resolveSigningSecret(false, 'env-secret', generate)
+    // Opt-out wins over an env var, and never generates.
+    expect(r).toEqual({ secret: '', hasExplicit: false, optOut: true, generated: false })
+    expect(generate).not.toHaveBeenCalled()
+  })
+})