Security Headers

The security headers the kit sends on every response, why, and how to change them.

Every response the Worker produces carries a fixed set of security headers, set by apps/web/middleware/03.security.ts.

This page is part of the Security documentation.

Headers

HeaderValueWhy
X-Content-Type-OptionsnosniffBrowsers use the declared Content-Type instead of guessing, so an uploaded file can't run as a script or page.
X-Frame-OptionsDENYNo site, including yours, can show the app in a frame (clickjacking).
Referrer-Policystrict-origin-when-cross-originOther sites see only your origin, never full paths or query strings, and nothing over a downgrade to http.
Permissions-Policycamera=(), microphone=(), geolocation=()Turns off camera, microphone and location for the page and any embedded content.
Cross-Origin-Opener-Policysame-originA page you open in a popup (or that opens you) can't script your window.
Strict-Transport-Securitymax-age=63072000; includeSubDomainsProduction builds only. Browsers use https for two years, for the domain and every subdomain.

Where They Apply

  • All Worker responses: pages, page actions, routes/api handlers, the 404 page, the JSON and plain-text 404s, and the 500 page served for errors.
  • Not static files: /assets/* and files in apps/web/public/ are served by Cloudflare's asset layer before the Worker runs, so they keep the default headers. A direct request for /500.html can therefore be framed; it holds no data or actions.
  • Dev and production alike, except HSTS, which is sent only by production builds (vp preview included; browsers ignore it over plain http).

Changing a Header

03.security.ts is kit-owned: edits there will conflict when you merge kit updates. It only fills in headers the response doesn't already have, so override a value instead of editing the file:

  • One route: set the header in its handler, e.g. c.header('Permissions-Policy', 'camera=(self)').
  • The whole app: add your own middleware numbered after the kit's, e.g. apps/web/middleware/20.headers.ts:
import { defineMiddleware } from 'void';
// allow the camera on your own pages
export default defineMiddleware(async (c, next) => {
await next();
c.res.headers.set('Permissions-Policy', 'camera=(self), microphone=(), geolocation=()');
});

To drop a header entirely, set it to a harmless value rather than deleting it, since a deleted header is filled in again.

Common Pitfalls

  • Embedding the app in an iframe (another of your sites, a widget) is blocked by X-Frame-Options: DENY and the CSP's frame-ancestors 'none'. Both must change.
  • includeSubDomains forces https on every subdomain once a browser has seen the header. Make sure all of them serve https before your first production deploy.
  • Removing HSTS later doesn't help users who already received it; it stays in their browser for max-age.

Next: Content Security Policy →