13.security.md

title	Security
description	Learn about the security defaults and how to further harden your OG image endpoint.

Nuxt OG Image ships with secure defaults by default. Image dimensions are clamped, renders are time limited, internal network requests are blocked, and user provided props are sanitized. No configuration is needed for these protections.

If you want to lock things down further, the security config key gives you additional controls.

export default defineNuxtConfig({
  ogImage: {
    security: {
      restrictRuntimeImagesToOrigin: true,
      maxQueryParamSize: 2048,
    }
  }
})

Prerender Your Images

The most effective security measure is to prerender your OG images at build time using Zero Runtime mode. Prerendered images are served as static files with no runtime rendering code in your production build.

export default defineNuxtConfig({
  ogImage: {
    zeroRuntime: true
  }
})

When zero runtime is enabled:

• No server-side rendering code is included in your production build
• Images are generated once at build time and served as static assets
• The /_og endpoint is not available at runtime

If your OG images don't need to change dynamically after deployment, this is the recommended approach.

For sites that need a mix of static and dynamic images, you can prerender specific routes while keeping runtime generation available for others. See the Zero Runtime guide for configuration details.

Dimension and Render Limits

Every request has its width and height clamped to maxDimension (default 2048 pixels). The Takumi renderer's devicePixelRatio is capped to maxDpr (default 2).

If a render exceeds renderTimeout (default 15000ms), it is aborted and the server returns a 408 status.

These are all enabled by default. You only need to configure them if you want different limits.

export default defineNuxtConfig({
  ogImage: {
    security: {
      maxDimension: 2048,
      maxDpr: 2,
      renderTimeout: 15000,
    }
  }
})

Query String Size Limit

OG image options can be passed via query parameters. By default there is no size limit on the query string, but you can set maxQueryParamSize to reject requests with oversized query strings.

export default defineNuxtConfig({
  ogImage: {
    security: {
      maxQueryParamSize: 2048, // characters
    }
  }
})

Requests exceeding this limit receive a 400 response.

If you find yourself passing large amounts of data through query parameters (titles, descriptions, full text), consider loading that data inside your OG image component instead. See the Performance guide for the recommended pattern.

Restrict Runtime Images to Origin

When runtime image generation is enabled, anyone who knows the /_og endpoint pattern can request an image directly. The restrictRuntimeImagesToOrigin option limits runtime generation to requests whose Host header matches your configured site URL.

export default defineNuxtConfig({
  ogImage: {
    security: {
      restrictRuntimeImagesToOrigin: true,
    }
  }
})

How It Works

The module reads the Host header from each runtime request using h3's getRequestHost (with X-Forwarded-Host support for reverse proxies) and compares it against the host from your Nuxt Site Config url. If the hosts don't match, the request receives a 403 response.

Because the Host header is mandatory in HTTP/1.1, this check works with all clients including social media crawlers. No Origin or Referer header is required.

Allowing Additional Origins

To allow extra origins (e.g. a CDN or preview deployment), pass an array. Your site config origin is always included automatically.

export default defineNuxtConfig({
  ogImage: {
    security: {
      restrictRuntimeImagesToOrigin: ['https://cdn.example.com', 'https://preview.example.com'],
    }
  }
})

This option is disabled by default to avoid surprises for sites behind non-standard proxy setups. If your reverse proxy forwards the correct Host or X-Forwarded-Host header, you can safely enable it.

::note Prerendering and dev mode bypass the host check entirely. ::

Debug Mode Warning

Enabling ogImage.debug in production exposes the /_og/debug.json endpoint. The module will log a warning at build time if debug is enabled outside of dev mode. Make sure to disable it before deploying.

export default defineNuxtConfig({
  ogImage: {
    debug: false, // never enable in production
  }
})