security-headers

name

security-headers

description

Configure security headers to defend against clickjacking, XSS, MIME confusion, and SSL stripping attacks. Use this skill when you need to set up Content-Security-Policy, X-Frame-Options, HSTS, configure middleware headers, or understand browser security features. Triggers include "security headers", "CSP", "content security policy", "X-Frame-Options", "HSTS", "clickjacking", "MIME confusion", "middleware headers".

Security Headers - Defense Against Multiple Attack Types

Why Security Headers Are Critical

Think of security headers as the walls and moat around your castle. Even if attackers get past the gate (your authentication), the walls (headers) prevent them from moving freely or exfiltrating data.

The Browser Security Model

Modern browsers have built-in security features, but they're opt-in. Without the right headers, browsers allow:

• Your site to be embedded in malicious iframes (clickjacking)
• Scripts from any origin (XSS amplification)
• Insecure HTTP connections (man-in-the-middle attacks)
• MIME type confusion (executing images as scripts)

Security headers tell the browser: "Enable all your security features for my site."

Real-World Consequences of Missing Headers

According to a 2023 security audit of top 10,000 websites by Scott Helme, only 2.8% properly implement all recommended security headers. The remaining 97.2% are vulnerable to attacks that headers would prevent.

Magecart Attacks (2018-2020): Hundreds of e-commerce sites were compromised by injected payment-stealing JavaScript. Content-Security-Policy headers would have prevented these scripts from executing. Sites without CSP lost millions in fraudulent transactions.

Our Security Headers Architecture

All headers are applied automatically via middleware.ts on every request. You don't need to manually set them—they're already protecting you.

Headers We Apply

1. Content-Security-Policy (CSP) - Controls resource loading
2. X-Frame-Options: DENY - Prevents clickjacking
3. X-Content-Type-Options: nosniff - Prevents MIME confusion
4. Strict-Transport-Security (HSTS) - Forces HTTPS (production only)
5. X-Robots-Tag: noindex, nofollow - Protects private routes

Header Descriptions & Implementation

1. Content-Security-Policy (CSP)

What it does: Controls what resources (scripts, styles, images) can load and from where.

Our configuration:

// Dynamic CSP based on environment variables
const clerkDomain = process.env.NEXT_PUBLIC_CLERK_FRONTEND_API_URL
  ? new URL(process.env.NEXT_PUBLIC_CLERK_FRONTEND_API_URL).origin
  : '';

const convexDomain = process.env.NEXT_PUBLIC_CONVEX_URL
  ? new URL(process.env.NEXT_PUBLIC_CONVEX_URL).origin
  : '';

const csp = [
  "default-src 'self'",
  `script-src 'self' 'unsafe-inline' 'unsafe-eval' ${clerkDomain} https://js.stripe.com`,
  `style-src 'self' 'unsafe-inline' ${clerkDomain}`,
  `connect-src 'self' ${clerkDomain} ${convexDomain} https://api.stripe.com`,
  `frame-src 'self' ${clerkDomain} https://js.stripe.com https://hooks.stripe.com`,
  "img-src 'self' data: https: blob:",
  "font-src 'self' data:",
  "object-src 'none'",
  "base-uri 'self'",
  "form-action 'self'",
  "frame-ancestors 'none'"
].join('; ');

response.headers.set('Content-Security-Policy', csp);

What This Means:

• Scripts: Only from our domain, Clerk, and Stripe
• Styles: Only from our domain and Clerk
• Connections: Only to Clerk, Convex, Stripe APIs
• Frames: Only Clerk and Stripe
• Images: Any HTTPS source (for user avatars, external images)

Why Dynamic Configuration:

const clerkDomain = process.env.NEXT_PUBLIC_CLERK_FRONTEND_API_URL
  ? new URL(process.env.NEXT_PUBLIC_CLERK_FRONTEND_API_URL).origin
  : ''

We don't hardcode Clerk's domain. It comes from environment variables. This means:

• ✅ Different domains for dev/staging/prod (automatic)
• ✅ Easy to change without code modifications
• ✅ No security secrets in codebase

Trade-off: We allow unsafe-inline and unsafe-eval for scripts. This is required for Next.js and Clerk to function. We mitigate this risk through input sanitization and validation.

Prevent Data Exfiltration: The connect-src directive prevents malicious scripts from sending data to unauthorized domains. Even if XSS bypasses sanitization, the browser blocks unauthorized network requests.

2. X-Frame-Options: DENY

What it prevents: Clickjacking attacks where your site is embedded in invisible iframe on attacker's site.

Attack scenario: Attacker embeds your "Delete Account" button in an invisible iframe overlay on a game site. Users think they're clicking "Play Game" but actually click "Delete Account."

Our protection:

response.headers.set('X-Frame-Options', 'DENY');

DENY means browsers refuse to embed our site in ANY iframe, even our own. Maximum security.

Alternative values:

• DENY - No iframes at all (most secure, what we use)
• SAMEORIGIN - Only our own site can iframe us
• ALLOW-FROM uri - Deprecated, don't use

3. X-Content-Type-Options: nosniff

What it prevents: MIME confusion attacks where browsers execute images as JavaScript.

Attack scenario: Attacker uploads file "avatar.jpg" that contains JavaScript. Old browsers try to be "helpful" and "sniff" the file type, detecting JavaScript, and execute it.

Our protection:

response.headers.set('X-Content-Type-Options', 'nosniff');

nosniff tells browsers to strictly follow Content-Type headers, never guess.

Why This Matters: Without this header, an attacker could:

1. Upload "image.jpg" containing <script>evil()</script>
2. Link to it: <img src="/uploads/image.jpg">
3. Browser sniffs file, detects script, executes it
4. XSS achieved despite upload validation

With nosniff, browser sees Content-Type: image/jpeg and refuses to execute as script.

4. Strict-Transport-Security (HSTS) - Production Only

What it prevents: SSL stripping attacks where man-in-the-middle downgrades HTTPS to HTTP.

Attack scenario: User types "yourapp.com" (no https://). Browser initially requests HTTP. Attacker intercepts, serves fake HTTP version, steals credentials.

Our protection:

if (process.env.NODE_ENV === 'production') {
  response.headers.set(
    'Strict-Transport-Security',
    'max-age=31536000; includeSubDomains'
  );
}

Configuration breakdown:

• max-age=31536000 - 1 year duration
• includeSubDomains - Applies to all subdomains
• Once set, browsers ONLY use HTTPS for your domain

Why production only: In development, you're on localhost (HTTP). HSTS would break local development. Our middleware detects environment and enables HSTS only in production.

Important: Once HSTS is set for a domain, browsers remember it. If you need to remove it, you must:

1. Set max-age=0
2. Wait for all users' browsers to receive the new header
3. This can take months if max-age was long

5. X-Robots-Tag: noindex, nofollow (Protected Routes)

What it prevents: Search engines indexing private content.

Why it matters: You don't want /dashboard/payment-details showing up in Google search results.

Our implementation:

if (req.nextUrl.pathname.startsWith('/dashboard')) {
  response.headers.set('X-Robots-Tag', 'noindex, nofollow');
}

Applied to: /dashboard/* routes only (public pages should be indexed)

What this tells search engines:

• noindex - Don't add this page to search results
• nofollow - Don't follow links on this page

Implementation in Middleware

middleware.ts Pattern

import { clerkMiddleware } from '@clerk/nextjs/server';
import { NextResponse } from 'next/server';

export default clerkMiddleware((auth, req) => {
  const response = NextResponse.next();

  // Get dynamic domains from environment
  const clerkDomain = process.env.NEXT_PUBLIC_CLERK_FRONTEND_API_URL
    ? new URL(process.env.NEXT_PUBLIC_CLERK_FRONTEND_API_URL).origin
    : '';

  const convexDomain = process.env.NEXT_PUBLIC_CONVEX_URL
    ? new URL(process.env.NEXT_PUBLIC_CONVEX_URL).origin
    : '';

  // Build CSP dynamically
  const csp = [
    "default-src 'self'",
    `script-src 'self' 'unsafe-inline' 'unsafe-eval' ${clerkDomain} https://js.stripe.com`,
    `style-src 'self' 'unsafe-inline' ${clerkDomain}`,
    `connect-src 'self' ${clerkDomain} ${convexDomain} https://api.stripe.com`,
    `frame-src 'self' ${clerkDomain} https://js.stripe.com https://hooks.stripe.com`,
    "img-src 'self' data: https: blob:",
    "font-src 'self' data:",
    "object-src 'none'",
    "base-uri 'self'",
    "form-action 'self'",
    "frame-ancestors 'none'"
  ].join('; ');

  // Apply security headers
  response.headers.set('Content-Security-Policy', csp);
  response.headers.set('X-Content-Type-Options', 'nosniff');
  response.headers.set('X-Frame-Options', 'DENY');

  // HSTS only in production
  if (process.env.NODE_ENV === 'production') {
    response.headers.set(
      'Strict-Transport-Security',
      'max-age=31536000; includeSubDomains'
    );
  }

  // Prevent indexing of protected routes
  if (req.nextUrl.pathname.startsWith('/dashboard')) {
    response.headers.set('X-Robots-Tag', 'noindex, nofollow');
  }

  return response;
});

export const config = {
  matcher: ['/((?!.*\\..*|_next).*)', '/', '/(api|trpc)(.*)'],
};

Testing Security Headers

Test All Headers

curl -I http://localhost:3000

# Expected headers:
# X-Frame-Options: DENY
# X-Content-Type-Options: nosniff
# Content-Security-Policy: default-src 'self'; ...

Test Production HSTS

# In production
curl -I https://yourapp.com

# Should include:
# Strict-Transport-Security: max-age=31536000; includeSubDomains

Test Protected Route Headers

curl -I http://localhost:3000/dashboard

# Should include:
# X-Robots-Tag: noindex, nofollow

Online Header Testing

Use these online tools to test your deployed site:

• Security Headers: https://securityheaders.com/
• Mozilla Observatory: https://observatory.mozilla.org/
• SSL Labs: https://www.ssllabs.com/ssltest/

Customizing CSP for New Integrations

When adding new third-party services:

Example: Adding Google Analytics

// middleware.ts

// Add Google Analytics domain to CSP
const csp = [
  "default-src 'self'",
  `script-src 'self' 'unsafe-inline' 'unsafe-eval' ${clerkDomain} https://js.stripe.com https://www.googletagmanager.com https://www.google-analytics.com`,
  `style-src 'self' 'unsafe-inline' ${clerkDomain}`,
  `connect-src 'self' ${clerkDomain} ${convexDomain} https://api.stripe.com https://www.google-analytics.com https://analytics.google.com`,
  // ... rest of CSP
].join('; ');

Example: Adding Custom CDN

const cdnDomain = process.env.NEXT_PUBLIC_CDN_URL
  ? new URL(process.env.NEXT_PUBLIC_CDN_URL).origin
  : '';

const csp = [
  "default-src 'self'",
  `script-src 'self' ${cdnDomain}`,
  `style-src 'self' ${cdnDomain}`,
  `img-src 'self' ${cdnDomain} https:`,
  // ... rest of CSP
].join('; ');

Common CSP Issues & Solutions

Issue 1: Inline Scripts Blocked

Symptom: Scripts in <script> tags don't execute

Solution: Next.js requires unsafe-inline and unsafe-eval. Already configured in our CSP.

Better alternative: Use nonces (requires SSR changes):

const nonce = crypto.randomBytes(16).toString('base64');
script-src 'self' 'nonce-${nonce}'

Issue 2: External Images Not Loading

Symptom: User avatars from Gravatar/etc don't show

Current solution: img-src 'self' data: https: blob: allows all HTTPS images

Stricter alternative:

`img-src 'self' data: https://gravatar.com https://images.yourapp.com`

Issue 3: WebSocket Connections Failing

Symptom: Convex real-time updates don't work

Solution: Ensure connect-src includes Convex domain:

`connect-src 'self' ${convexDomain}`

What Security Headers Prevent

✅ Clickjacking (X-Frame-Options) ✅ XSS amplification (CSP) ✅ MIME confusion (X-Content-Type-Options) ✅ SSL stripping (HSTS) ✅ Search engine exposure of private data (X-Robots-Tag) ✅ Data exfiltration (CSP connect-src) ✅ Unauthorized resource loading (CSP default-src)

Common Mistakes to Avoid

❌ DON'T hardcode domains in CSP - Use environment variables ❌ DON'T enable HSTS in development - Breaks localhost ❌ DON'T use X-Frame-Options: ALLOW-FROM - Deprecated ❌ DON'T forget to test headers after deployment ❌ DON'T set overly permissive CSP (like * wildcards)

✅ DO use dynamic CSP with environment variables ✅ DO test headers with online tools after deployment ✅ DO update CSP when adding new third-party services ✅ DO keep HSTS production-only ✅ DO protect dashboard routes from indexing

References

• Mozilla Security Headers Guide: https://infosec.mozilla.org/guidelines/web_security
• OWASP Secure Headers Project: https://owasp.org/www-project-secure-headers/
• Content Security Policy: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
• HSTS Specification: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
• Security Headers Checker: https://securityheaders.com/

Next Steps

• For XSS prevention: Use input-validation skill
• For clickjacking tests: Use security-testing skill
• Headers are automatic - check middleware.ts:1 for implementation
• For adding new integrations: Update CSP in middleware.ts