Next.js 16 Security Headers and Content Security Policy

In Blog #25, we scaled our Next.js application across multiple containers. More infrastructure means a larger security surface. The next step is hardening browser-facing responses with security headers and a carefully designed Content Security Policy.

What Are Security Headers in Next.js?

Security headers are HTTP response headers that tell browsers how to handle risky content and capabilities. In Next.js, correctly configured CSP, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy can reduce exposure to script injection, clickjacking, MIME confusion, and unnecessary browser features as part of defense in depth.

Security Headers at a Glance

Why Security Headers Matter

The browser receives markup, scripts, styles, images, frames, and network instructions from your response. Headers add enforceable browser rules around those resources. They can limit the impact of some injection bugs and unsafe embedding, but they do not repair vulnerable code or replace validation, output encoding, authentication, authorization, secure cookies, dependency updates, and monitoring.

Where Should Headers Be Configured?

If Next.js and a proxy set the same ordinary header, the downstream layer may replace or append it. Multiple CSP headers are different: browsers enforce every policy, so the effective result becomes more restrictive. Keep an ownership table for application, proxy, CDN, and platform headers.

Security Headers in next.config

Start with low-breakage headers, test them, and add CSP separately. This sample intentionally leaves out HSTS until HTTPS coverage and subdomains are verified.

import type { NextConfig } from 'next'

const securityHeaders = [
  { key: 'X-Content-Type-Options', value: 'nosniff' },
  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
  {
    key: 'Permissions-Policy',
    value: 'camera=(), microphone=(), geolocation=()',
  },
  // Compatibility fallback; CSP frame-ancestors is the modern control.
  { key: 'X-Frame-Options', value: 'DENY' },
]

const nextConfig: NextConfig = {
  poweredByHeader: false,
  headers() {
    return [{ source: '/(.*)', headers: securityHeaders }]
  },
}

export default nextConfig

Content Security Policy

CSP is a response policy composed of directives. Each directive controls a different browser capability. A production policy should be derived from your routes, rendering mode, inline code, analytics, authentication, payments, media, fonts, images, API calls, workers, and frames. Avoid widening default-src just to silence one violation.

Educational Baseline CSP

default-src 'self';
script-src 'self';
style-src 'self';
img-src 'self' data: blob:;
font-src 'self';
connect-src 'self';
frame-src 'none';
object-src 'none';
base-uri 'self';
form-action 'self';
frame-ancestors 'none';

This baseline is intentionally restrictive and may block Next.js inline bootstrapping or styles, depending on rendering and build behavior. It may also block every external integration. The correct response to those violations is investigation: choose a supported nonce or hash architecture, remove unnecessary inline code, or add only the exact justified sources. Do not jump directly to script-src * or broad 'unsafe-inline'.

CSP Directives Explained

CSP Nonces in Next.js 16

A nonce is an unpredictable, one-use value generated for each response. Current Next.js guidance creates it in proxy.ts, places it in the CSP request and response headers, and dynamically renders the protected page. Next.js can then apply the matching nonce to framework and page scripts.

import { NextRequest, NextResponse } from 'next/server'

export function proxy(request: NextRequest) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64')
  const isDev = process.env.NODE_ENV === 'development'
  const policy = `
    default-src 'self';
    script-src 'self' 'nonce-${nonce}' 'strict-dynamic'${
      isDev ? " 'unsafe-eval'" : ''
    };
    style-src 'self' 'nonce-${nonce}';
    img-src 'self' blob: data:;
    font-src 'self';
    connect-src 'self';
    frame-src 'none';
    frame-ancestors 'none';
    object-src 'none';
    base-uri 'self';
    form-action 'self';
  `.replace(/\s{2,}/g, ' ').trim()

  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-nonce', nonce)
  const response = NextResponse.next({ request: { headers: requestHeaders } })
  response.headers.set('Content-Security-Policy-Report-Only', policy)
  return response
}

export const config = {
  matcher: [{
    source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
    missing: [
      { type: 'header', key: 'next-router-prefetch' },
      { type: 'header', key: 'purpose', value: 'prefetch' },
    ],
  }],
}

Do not copy that provider-free policy directly into enforcement. It deliberately blocks external analytics, authentication, payments, media, remote images, WebSockets, and APIs until their exact requirements are reviewed.

Hash-Based CSP

A hash allows one exact inline script or style. It suits content that is stable across responses; any byte change, including whitespace, changes the hash. Build tooling can calculate hashes, but manually maintained hashes become fragile. Next.js also documents experimental Subresource Integrity support for hash-oriented deployments, so verify the current limitations before choosing it.

Strict CSP Concepts

A strict policy establishes trust with a nonce or hash rather than a broad host list. 'strict-dynamic' can extend that trust to scripts loaded by an already trusted script in supporting browsers. Keep a compatible source strategy for the browsers you support, and test actual script-loading behavior rather than judging policy strength by length.

CSP and Next.js Script

Read the nonce in a Server Component and pass it to a third-party Script. The provider’s host may still need to be represented for browser compatibility and its network calls belong in connect-src.

import { headers } from 'next/headers'
import Script from 'next/script'

export default async function Analytics() {
  const nonce = (await headers()).get('x-nonce') ?? undefined
  return (
    <Script
      src="https://www.googletagmanager.com/gtag/js?id=G-EXAMPLE"
      strategy="afterInteractive"
      nonce={nonce}
    />
  )
}

CSP with Analytics, Authentication, and Third Parties

Do not add a vendor’s entire wildcard domain from memory. Open every important user journey in a production-like environment, record the origins, compare them with current provider documentation, and add the smallest stable set. Re-test login, logout, refresh, account linking, checkout, consent changes, and error flows.

CSP for Images, Fonts, APIs, and WebSockets

Browser Web Workers use CSP controls such as worker-src. They are unrelated to the server-side queue workers introduced in Blog #23. Do not add a browser worker origin because a BullMQ or Redis worker runs on the server.

Detected resource inventory for this publishing repository

Report-Only Mode and Violation Reporting

Content-Security-Policy-Report-Only reports violations without blocking them. Use it to learn what the application actually requires, but remember that report-only success does not prove enforcement is safe. Exercise real routes, roles, locales, error states, and browser families.

A report endpoint is an internet-facing ingestion service. Authenticate where possible, cap body size and rate, validate JSON, avoid logging sensitive document URLs or samples unnecessarily, and never render report values as trusted HTML. Support for report-to, Reporting-Endpoints, and legacy report-uri varies, so test your browser matrix.

X-Content-Type-Options, Referrer-Policy, and Permissions-Policy

X-Content-Type-Options: nosniff

This tells browsers to respect declared MIME types instead of guessing. It works with correct server Content-Type configuration; test scripts, styles, uploads, and downloads.

Referrer-Policy: strict-origin-when-cross-origin

This retains the full referrer for same-origin requests, sends only the origin on secure cross-origin requests, and omits it on HTTPS-to-HTTP downgrades. Choose no-referrer or a different policy only after reviewing privacy, analytics, and partner requirements.

Permissions-Policy

Disable browser capabilities the application does not use. Start from a feature inventory rather than copying a huge list; syntax and browser support differ by directive, and embedded frames may need their own allow attributes.

HSTS

Strict-Transport-Security tells a browser to use HTTPS for future requests. Send it only over HTTPS. Begin with a short reviewed max-age, monitor, and increase it gradually. Add includeSubDomains only when every required subdomain supports HTTPS. Treat preload as a separate, long-lived operational commitment.

Strict-Transport-Security: max-age=31536000

X-Frame-Options vs frame-ancestors

frame-ancestors is the modern, flexible framing control and can allow several explicit parents. X-Frame-Options remains a simple compatibility fallback using DENY or SAMEORIGIN. Keep both semantically aligned. Do not confuse frame-ancestors, which controls who embeds you, with frame-src, which controls frames you load.

Cross-Origin Headers

Cross-Origin-Opener-Policy, Cross-Origin-Embedder-Policy, and Cross-Origin-Resource-Policy can enable strong isolation, but they can also break OAuth popups, payment windows, embedded tools, images, fonts, and resources lacking compatible CORS or CORP responses. Add them only for a documented isolation requirement and test every cross-origin flow.

CSP vs CORS

CSP tells a browser what a protected document may load or do. CORS tells a browser whether JavaScript from one origin may read a response from another origin. Neither proves identity, authorizes a user, validates a webhook, or prevents a server from making an outbound request.

Security Headers Behind Traefik, Nginx, or Vercel

Inspect the final public response, not only source configuration. A CDN can cache an old header, a proxy can add another one, and framework routes, static files, API errors, and redirects may follow different paths.

Common CSP Mistakes

• Enforcing a copied policy before inventory and Report-Only observation.
• Adding 'unsafe-inline' or * to make console errors disappear.
• Using one broad directive instead of narrow resource-specific sources.
• Forgetting analytics collection, OAuth, payments, fonts, images, workers, or WebSockets.
• Reusing a nonce across responses or generating predictable values.
• Adding a nonce to every script through string replacement, including injected scripts.
• Expecting nonce-based pages to remain statically rendered and CDN cacheable.
• Confusing frame-src with frame-ancestors.
• Setting independent CSP headers at several infrastructure layers.
• Enabling HSTS preload before all subdomains are permanently HTTPS-ready.
• Collecting violation reports without rate limits, redaction, retention, or ownership.
• Treating a security scanner grade as proof that application logic is secure.

Testing Security Headers

curl -I https://example.com/
curl -I https://example.com/login
curl -I https://example.com/api/health

# Check for accidental duplicates
curl -sS -D - -o /dev/null https://example.com/ \
  | grep -iE 'content-security|strict-transport|x-content|referrer|permissions|x-frame'

Then use browser DevTools: clear cache, preserve the network log, visit every critical route, inspect response headers, filter CSP console messages, and complete analytics, login, logout, upload, checkout, embed, error, and WebSocket flows. Add integration assertions for representative document and API responses.

Production Checklist

• Record the exact Next.js and provider versions in the real application repository.
• Map which layer owns every response header.
• Inventory all resource and connection origins by environment.
• Choose static, nonce-based, or hash-based CSP from rendering requirements.
• Generate a fresh unpredictable nonce for every dynamic response.
• Keep development-only 'unsafe-eval' out of production.
• Deploy CSP in Report-Only mode and exercise critical journeys.
• Classify and redact violation data; rate-limit the report endpoint.
• Canary enforcement and monitor frontend errors and business flows.
• Verify correct MIME types with nosniff.
• Review referrer privacy and Permissions-Policy features.
• Enable HSTS gradually only after complete HTTPS validation.
• Test framing, OAuth popups, payments, embeds, APIs, and WebSockets.
• Re-audit the policy whenever a dependency or third-party provider changes.

Related Next.js Tutorials

• Blog #11: Metadata & SEO
• Blog #12: Image Optimization
• Blog #13: Authentication
• Blog #14: Performance
• Blog #16: Environment Variables & Security
• Blog #17: Proxy
• Blog #18: Forms & Validation
• Blog #20: Docker + Traefik
• Blog #24: Monitoring & Observability
• Blog #25: Production Scaling

Frequently Asked Questions

Current Official References

• Next.js Content Security Policy guide
• Next.js headers() reference
• MDN Content Security Policy guide
• MDN Strict-Transport-Security reference
• MDN X-Content-Type-Options reference
• MDN Referrer-Policy reference
• MDN Permissions Policy guide
• OWASP Content Security Policy Cheat Sheet
• OWASP HTTP Security Response Headers Cheat Sheet

Next Steps

Begin with an origin inventory and header ownership map for the real Next.js deployment. Ship the low-breakage baseline, observe a route-specific CSP in Report-Only mode, remove unnecessary dependencies and exceptions, then canary enforcement. Re-run the review whenever analytics, authentication, images, fonts, payments, or deployment layers change.