# Content Security Policy

> The CSP the kit enforces in production, how scripts are trusted, and how to allow third-party origins.

*Canonical: https://makerkit.dev/docs/void-cloudflare/security/content-security-policy*

---

Production pages send a Content Security Policy that blocks the usual script injections: inline event handlers, `javascript:` URLs, `eval`, and scripts from origins you haven't allowed that aren't loaded by a trusted script. It's built per response by `apps/web/middleware/03.security.ts` (kit-owned) and extended in `apps/web/config/security.config.ts` (yours).

This page is part of the [Security documentation](./overview).

## The Policy

| Directive | Sources | Why |
|---|---|---|
| `default-src` | `'self'` | Anything not listed below: same origin only. |
| `script-src` | `'self' 'strict-dynamic' 'nonce-…'` + yours | Only scripts carrying this response's nonce run, plus scripts they load. |
| `style-src` | `'self' 'unsafe-inline'` | React `style` props and Base UI's inline `<style>` tags. |
| `img-src` | `'self' data: blob:`, plus the enabled social providers' avatar origins | Inline icons, local previews of uploads, and profile pictures (see [Profile Pictures](#profile-pictures)). |
| `font-src` | `'self' data:` | Bundled fonts. |
| `connect-src`, `frame-src`, `manifest-src`, `media-src` | `'self'` + yours | `fetch`, iframes, the manifest, audio and video. |
| `worker-src` | `'self' blob:` | Web workers. |
| `object-src`, `base-uri`, `frame-ancestors` | `'none'` | No plugins, no `<base>` hijacking, no framing (clickjacking). Not extendable from `security.config.ts`. |
| `form-action` | `'self'` + yours, plus `https://checkout.stripe.com` and `https://billing.stripe.com` with billing on | Forms post only to your app; the billing page's forms redirect to Stripe Checkout and the portal (a Stripe custom domain for Checkout goes in `security.config.ts` → `csp`). |
| `upgrade-insecure-requests` | | `http:` subresources load over https. Omitted on `localhost`, `127.0.0.1` and `[::1]`. |

`security.config.ts` pre-lists Cloudflare Turnstile (`https://challenges.cloudflare.com`) in `script-src`, `frame-src` and `connect-src`, for the auth forms' [bot check](../authentication/captcha).

Only HTML responses the Worker renders carry the policy. Local dev (`pnpm dev`) sends none, because Vite's dev scripts would violate it; `vp preview` and deployed Workers enforce it. Marketing pages requested without cookies are the one exception: see [Cached Marketing Pages](#cached-marketing-pages).

## Cached Marketing Pages

Pages under `apps/web/pages/(marketing)/` (the landing page, FAQ, legal pages) are meant to be served from Void's ISR cache. A nonce can't be shared between visitors, so when a **request without cookies** to one of these pages at its bare URL (`/faq`, not `/it/faq`) gets a response Void will store (status 200, no `Set-Cookie`, no `private`/`no-store`/`no-cache`, no `Vary`), `03.security.ts` sends **no CSP and no nonce** and doesn't mark it `private`. Any other response keeps the nonce CSP. The other [security headers](./headers) (HSTS, `nosniff`, `X-Frame-Options`, `Referrer-Policy`, …) are always set; Void's ISR stores the headers of the response it caches, so cached copies carry them too.

- **Locale prefixes keep the CSP:** Void picks the cache lifetime from the URL before the locale rewrite, so `/it/faq` is never cached; it renders live with the nonce CSP. See [URL prefixes](../internationalization/url-prefixes#cached-marketing-pages).
- **Who gets the cached page:** Void serves cached HTML only to requests without a `Cookie` header, i.e. first visits and crawlers. Anyone with a cookie (signed in, or a saved theme or language) gets a live render with the nonce CSP, as on every other page.
- **The folder decides:** moving a page into `pages/(marketing)/` makes it cacheable; there's no per-page switch and no list to keep. The rule lives in `apps/web/lib/cacheable-routes.server.ts` (`isCacheableRequest`): a request counts only when the page that serves it is a marketing page, the most specific route winning (static over `[param]` over `[...rest]`), so a marketing `[slug].tsx` never strips the CSP from `/password-reset` or `/dashboard`. A marketing route that another page ties with or outranks is never cached, and `pnpm test:unit` fails on it.
- **Keep these pages static:** they render only content from the repo. Never read query parameters, request headers or user input in them, and never pass HTML to `dangerouslySetInnerHTML`: with no CSP, an injection would run on your app's origin. A page that takes user input (a contact form, search, comments) belongs outside `pages/(marketing)/`.
- **Links into the app reload the page:** a visitor who lands on a cached page has a document without a CSP, and Void's client-side navigation keeps that document. Link from marketing pages to sign-in or app pages with `LocalizedLink` and `reloadDocument` (a full page load, so the new page gets its CSP); header and footer links from `config/marketing-navigation.config.ts` always do.
- **Analytics and embeds are allowed:** script tags run for every visitor (cookieless responses have no CSP; the rest get the nonce). Add the script's request, image and frame origins to `security.config.ts` → `csp` so they also work for visitors with cookies. Any cookie the script sets turns off caching for that visitor's later requests.
- **Deploys:** `routing.isr: true` in `apps/web/void.config.ts` lets `void deploy` create the ISR cache without asking. `vp preview` has no ISR cache, so locally these pages render on each request; `apps/e2e/tests/marketing/cacheability.spec.ts` finds every marketing page the way the app does and checks each one without cookies: no `Set-Cookie` or `private`/`no-store`/`no-cache`, the same HTML whatever `Host` or `X-Forwarded-Host` is sent, and identical `shared` page data with `user: null` and no nonce. A page you add is checked automatically (pages with `[params]` are skipped).

## How Scripts Are Trusted

Every response gets a fresh random nonce. As the HTML streams out, the middleware adds `nonce="…"` to every `<script>` and `<link rel="modulepreload">` in it, using Cloudflare's `HTMLRewriter`. That covers Void's bundle, the theme script, React's inline runtime and the scripts Void streams for `defer()` data, none of which can be hashed because their content changes per response.

`'strict-dynamic'` then trusts whatever those scripts load at runtime (code-split chunks, Turnstile's own scripts). In browsers that support it, `'self'` and host sources in `script-src` are ignored; they only matter for older browsers.

**What it blocks:**

- Inline event handlers (`<img onerror="…">`), whether rendered or added to the DOM later.
- `javascript:` URLs.
- `eval`, `new Function` and string `setTimeout`.
- `<script>` tags added through `innerHTML` (browsers never run those anyway).

**What it doesn't block:** a `<script>` tag inside the server-rendered HTML gets the nonce like any other. If you render untrusted HTML with `dangerouslySetInnerHTML`, sanitize it first; the CSP won't save you there.

## Adding a Third-Party Service

Example: an analytics service that loads `https://cdn.example-analytics.com/script.js` and sends events to `https://events.example-analytics.com`.

1. Add the origins to `apps/web/config/security.config.ts`, under the directives the service needs:

   ```ts
   csp: {
     'script-src': [TURNSTILE, 'https://cdn.example-analytics.com'],
     'frame-src': [TURNSTILE],
     'connect-src': [TURNSTILE, 'https://events.example-analytics.com'],
   },
   ```

2. Load the script with a `<script src>` tag your app renders (e.g. through `defineHead`); it gets the nonce automatically. A snippet the vendor tells you to paste inline works the same way.
3. Rebuild and run `vp preview`, then open the browser console: any remaining violation names the directive and the blocked URL. Add that origin to that directive.

The `script-src` entry is for older browsers; `img-src` (tracking pixels) and `connect-src` (events) are what modern browsers check.

Never add `*`, `'unsafe-inline'` or `'unsafe-eval'` to `script-src`: `'unsafe-inline'` is ignored next to a nonce anyway, and the other two reopen the attacks the policy exists to block.

The Worker refuses to start if `security.config.ts` does either: `script-src` with one of those three, or any source containing `;` or `,`. List one source per entry.

## Profile Pictures

Members sign in with Google or GitHub, and Better Auth stores their profile picture URL as `user.image`. The members table and the account menu show it. So those images load, the kit adds each **enabled** social provider's avatar origin to `img-src`:

| Provider | Origin added |
|---|---|
| `google` | `https://lh3.googleusercontent.com` |
| `github` | `https://avatars.githubusercontent.com` |
| `twitter` (X) | `https://pbs.twimg.com`, `https://abs.twimg.com` (the default picture) |

A provider counts when both of its keys are set (`apps/web/config/auth.config.server.ts`). Microsoft sends the picture as a `data:` URL, which is already allowed, and Apple sends none. Facebook isn't listed: its picture URLs redirect between CDNs and expire, so stored ones break anyway.

For another provider, set `imageOrigins` on its entry, next to its `name` and `logo`; it also replaces a listed provider's default:

```ts
discord: {
  clientId: env.AUTH_DISCORD_CLIENT_ID,
  clientSecret: env.AUTH_DISCORD_CLIENT_SECRET,
  name: 'Discord',
  logo: '/images/oauth/discord.svg',
  imageOrigins: ['https://cdn.discordapp.com'],
},
```

Each must be a plain `https://` origin (no path, no `*`); anything else stops the Worker with the provider's name. Turning a provider off drops its origins, so members who signed up with it show their initial; to keep their pictures, list the origin under `img-src` in `security.config.ts`.

The origins come from that list and your entries, never from the stored image URLs: any user can set `user.image`, so allowing whatever host it names would let anyone add a tracking-pixel origin. For the same reason, never widen `img-src` to `*` or `https:`. A picture from an origin that isn't listed falls back to the member's initial.

Dev sends no CSP, so pictures load there either way: check with `vp preview`.

## Billing (Stripe)

With both Stripe keys set, the kit adds Stripe Checkout and the Stripe portal to `form-action`, and nothing else: the billing page's plan buttons are plain form posts that the server redirects to Stripe, with no Stripe.js and no frames. Dev sends no CSP, so check it in the production preview:

1. Put test-mode keys and one price per plan (`STRIPE_PRICE_*`) in `apps/web/.env`, then run `pnpm preview`. It passes the Stripe and `STRIPE_PRICE_*` keys to the Worker.
2. Open `/settings/billing` as an owner and choose a plan.
3. Confirm the browser reaches Stripe Checkout and the console shows no `form-action` violation.

## Rolling Out: Report-Only

To try a policy change on a live environment without breaking anything:

1. `void secret put CSP_MODE` with `report-only`, then deploy. Responses send `Content-Security-Policy-Report-Only` instead: nothing is blocked, violations appear in the browser console.
2. Browse every page that changed and fix each violation reported in the console.
3. Set `CSP_MODE` back to `enforce` (or delete the secret; `enforce` is the default).

`CSP_MODE=off` sends no policy at all. Use it only to rule out the CSP while debugging. There's no violation report endpoint.

## Troubleshooting a Violation

A blocked resource shows in the console as `Refused to load the script 'https://…' because it violates the following Content Security Policy directive: "script-src …"` (wording varies by browser).

- **A URL was refused:** add its origin to the directive named in the message, in `security.config.ts`.
- **An inline handler was refused** (the event reports it as `script-src-attr`; the console names `script-src`): replace `onclick="…"` markup with a React event handler.
- **`eval` was refused:** a library is compiling code at runtime. Use its CSP-safe build, or replace the library.
- **zod and `eval`:** zod 4 probes for `eval` when it builds a schema. With the CSP on, `03.security.ts` sets zod's `jitless` option in a nonce'd head script before any module runs, so the probe never runs and nothing is reported; zod behaves the same, since the CSP blocks `eval` anyway (in `report-only` it gives up zod's compiled fast path, a speed cost only).
- **Base UI's `renderBeforeHydration`** on `Tabs.Indicator` or `Slider.Thumb` renders an inline script; it gets the nonce, so it works.
- **A page needs its own policy:** set `Content-Security-Policy` (or `-Report-Only`) in its handler. The middleware then leaves that response alone, without a nonce, so your policy must allow its scripts another way, including the kit's inline theme and zod scripts.

## Common Pitfalls

- **Expecting CSP in `pnpm dev`:** test with `vp preview` instead.
- **Overriding `CSP_MODE` in local `vp preview`:** preview passes only the required keys to the Worker, so a local `CSP_MODE` value is ignored there.
- **ISR and edge caching:** a cached page would hand the same nonce to every visitor, so the middleware marks each nonced page `Cache-Control: private` (unless it already says `private`, `no-store` or `no-cache`). Void's ISR then skips those pages. To cache a public page, put it in `pages/(marketing)/` ([Cached Marketing Pages](#cached-marketing-pages)).
- **Prerendering a page outside `pages/(marketing)/`:** its cookieless render is nonced and `private`, so Void never stores it; the `prerender` export does nothing there.

---

**Next:** [CSRF Protection →](./csrf)
