From 5661694dd721b88dc244925242014936b34287c3 Mon Sep 17 00:00:00 2001
From: M <>
Date: Mon, 14 Sep 2026 21:38:10 +0200
Subject: [PATCH] CON-44: a Content-Security-Policy behind the Markdown
 sanitiser
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The app renders Markdown written by arbitrary public keys, and the sanitiser is
the only thing standing between that and script execution. This adds the second
layer: one policy in `src/csp.ts`, pinned by `src/csp.test.ts`, delivered as an
HTTP response header — never as `<meta http-equiv>`, which ignores
`frame-ancestors`, the directive this policy needs.

`script-src 'self'` with no `'unsafe-inline'` and no `'unsafe-eval'` is the
directive that matters, so the theme bootstrap moved out of `index.html` into
`public/theme-bootstrap.js`; it stays classic and render-blocking, or a reload
flashes light mode. `style-src` keeps `'unsafe-inline'` because CodeMirror
mounts its theme through style-mod, which assigns `textContent` to a `<style>`
element it creates — no refactor of our own code removes that, only a
per-response nonce a static host cannot mint. `connect-src` stays
scheme-scoped: the space relay comes from the link, so a build-time host
allowlist would break every shared space address.

`vite preview` is the only thing in this repo that sends the header, and it
sends it on the real build, so the policy can be checked on the artefact that
ships — with one deliberate difference. The shipped `connect-src` permits
`https:` and `wss:` only, which blocks the local relay (`ws://localhost:<port>`
plus its `http://` NIP-11 fetch) and the local Blossom server, so a preview run
under it never loads a space and proves nothing beyond the header arriving.
`PREVIEW_CSP_DIRECTIVES` therefore adds loopback to `connect-src`, and nothing
else: `script-src` and the rest are served exactly as they ship. The cost is
that `connect-src` is the one directive a preview run no longer checks as
shipped — the cheapest one to give up, since the relay host comes out of the
link at runtime (CON-46) and it can never be narrow in production either.
Both policies are derived from one set of directives, and the tests fail if
they ever differ anywhere but `connect-src`, or if the shipped one grows a
plaintext scheme.

The dev server deliberately sends none: the React plugin injects its own
inline preamble, so a dev policy would need the very `'unsafe-inline'` this
ticket is about. Nothing in production delivers the header yet — there is no
host configuration in this repo at all — which is CON-48.
---
 docs/09-security-privacy.md | 196 +++++++++++++++++++++++++++++++++++-
 docs/10-roadmap.md          |   2 +-
 docs/12-theming.md          |  24 ++++-
 index.html                  |  22 ++--
 public/theme-bootstrap.js   |  20 ++++
 src/csp.test.ts             | 108 ++++++++++++++++++++
 src/csp.ts                  | 150 +++++++++++++++++++++++++++
 vite.config.ts              |  25 ++++-
 8 files changed, 527 insertions(+), 20 deletions(-)
 create mode 100644 public/theme-bootstrap.js
 create mode 100644 src/csp.test.ts
 create mode 100644 src/csp.ts

diff --git a/docs/09-security-privacy.md b/docs/09-security-privacy.md
index 8aeffc8..3fea340 100644
--- a/docs/09-security-privacy.md
+++ b/docs/09-security-privacy.md
@@ -34,7 +34,7 @@
 
 | Risk | Countermeasure |
 |---|---|
-| XSS through Markdown from arbitrary npubs | `rehype-sanitize` with a strict allowlist, no `dangerouslySetInnerHTML`, no raw HTML, no `javascript:` links |
+| XSS through Markdown from arbitrary npubs | `rehype-sanitize` with a strict allowlist, no `dangerouslySetInnerHTML`, no raw HTML, no `javascript:` links — and a Content-Security-Policy behind it as a second layer, see below |
 | Images/iframes used as trackers | **Accepted trade:** every image is loaded directly, whatever host it points at — so a host learns the reader's IP, which page is being read and when, and can count reads. No iframes. See "Images are loaded directly" below |
 | Forged `h` tags (an event from another group smuggled in) | Checked after loading: `h` must match the open space, otherwise the event is discarded |
 | Forgetting to verify signatures | Verification is enforced in the data layer, not optional per call |
@@ -42,6 +42,200 @@
 | Spam in open spaces | Relay rate limits + moderated deletion (`9005`) + a "members only" UI filter |
 | Key theft through the app | No handling of nsec at all. NIP-07/NIP-46 only |
 
+## Content-Security-Policy
+
+The sanitising pipeline above is the first layer, and as of this writing it is
+correct — the CSP closes no hole that is open today. It is the **second** layer,
+and it exists for the day a regression in that pipeline, or a compromised npm
+dependency somewhere in the tree, puts a script into the page anyway. The app
+renders Markdown written by arbitrary public keys, so that day is worth
+planning for.
+
+**This section describes a policy the app is *meant* to be served with. Today
+nothing in production sends it — see "The risk" at the end before reading any
+further.**
+
+The policy is defined once, in `src/csp.ts`, which `vite.config.ts` imports:
+
+```
+default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';
+img-src * data:; connect-src 'self' https: wss:; font-src 'self';
+object-src 'none'; frame-src 'none'; worker-src 'none'; base-uri 'none';
+form-action 'none'; frame-ancestors 'none'
+```
+
+### A header, not a meta tag
+
+`<meta http-equiv="Content-Security-Policy">` silently ignores
+`frame-ancestors`, `report-uri`/`report-to` and `sandbox`; they are only
+honoured on an HTTP response header. `frame-ancestors 'none'` is part of this
+policy, so a meta tag could not deliver it. A meta tag would also break
+`npm run dev` (see below) and leave two copies of the policy to keep in sync.
+
+`vite.config.ts` puts the header on `preview.headers`, so
+`npm run build && npm run preview` serves the **production build** under the
+policy. That makes it checkable on the artefact that actually ships, without
+inventing a deployment — with one deliberate difference in `connect-src`, see
+"Preview relaxes `connect-src`, and only that" below.
+
+### The directives that are not obvious
+
+- **`script-src 'self'`** — no `'unsafe-inline'`, no `'unsafe-eval'`. This is
+  the whole point of the exercise. It cost one change: the theme bootstrap that
+  used to sit inline in `index.html` now lives in `public/theme-bootstrap.js`
+  ([12](12-theming.md)). `src/` contains no `eval` and no `new Function`.
+- **`style-src 'unsafe-inline'`** — forced, and deliberate. The **binding**
+  constraint is CodeMirror, not our own components: `@codemirror/view` mounts
+  its theme through `style-mod`'s `StyleModule.mount`, which for a document
+  root — every mount in this app, since nothing here uses shadow DOM — creates
+  a `<style>` element and assigns its `textContent`. That is an inline style
+  *element* (`style-src-elem`), and no refactor on our side removes it: the
+  only alternative is a per-response nonce (`EditorView.cspNonce` exists for
+  exactly that), which a static host cannot mint. Secondary, and by itself
+  removable: five computed React `style` attributes — `src/ui/Markdown.tsx`
+  twice, including the per-token Shiki styles that are by far the most
+  numerous at runtime, `src/ui/layout/TableOfContents.tsx` once and
+  `src/ui/layout/Sidebar.tsx` twice. CSP governs style *attributes* too,
+  through `style-src-attr`, so without this they would silently stop applying
+  — no error, just wrong indentation and unhighlighted code. Inline **styles**
+  cannot execute script; the directive that must stay clean is `script-src`.
+- **`img-src * data:`** — deliberately open, and **not** to be tightened by
+  mistake. Pages embed images from arbitrary hosts and the app loads them
+  directly, by the decision under "Images are loaded directly" below. `*` does
+  not cover the `data:` scheme, hence listing it; no `blob:`, because `src/`
+  never calls `createObjectURL`.
+- **`connect-src 'self' https: wss:`** — scheme-scoped rather than an
+  allowlist of hosts, because **no host allowlist can exist here**. The space
+  relay is chosen at runtime from the route — whoever wrote the link picks the
+  host — and a static CSP is fixed at build time. The app also fetches that
+  host's NIP-11 document over `https` (`src/nostr/relay-status.ts`), the
+  profile relays from `VITE_PROFILE_RELAYS` and the Blossom server from
+  `VITE_BLOSSOM_SERVER`. This follows from the relay-trust decision (CON-46);
+  tightening it breaks every shared space link.
+
+### The dev server gets no policy
+
+`@vitejs/plugin-react` injects an inline `<script type="module">` (the Fast
+Refresh preamble) into `index.html` in dev, and the HMR client opens a
+WebSocket to the dev server. A dev policy would therefore need
+`'unsafe-inline'` in `script-src`, which neuters the one directive this is
+about, on top of a second policy to keep in sync. `npm run preview` is where
+the policy can be checked against the real build. The preview policy below
+does relax `connect-src` for the same local hosts a dev policy would need —
+but it leaves `script-src` exactly as it ships, which is what makes it worth
+serving at all.
+
+### Preview relaxes `connect-src`, and only that
+
+The shipped policy allows outbound connections over `https:` and `wss:` only.
+The local setup is plaintext — the dev relay is `ws://localhost:<port>` with
+an `http://` NIP-11 fetch to the same host, and the Blossom server is
+`http://localhost:3355` — and `'self'` does not cover them, because the
+previewed origin is a different port. Under the shipped policy verbatim,
+`npm run preview` therefore never loads a space, and exactly the paths that
+need one cannot be walked: Shiki highlighting on a real page, a foreign-host
+image, relay connect and AUTH, an upload. The only thing such a run would
+prove is that a header arrives.
+
+That defeats the purpose of `preview.headers`, so the preview server sends a
+derived policy instead: the shipped directives with
+`ws://localhost:* http://localhost:* ws://127.0.0.1:* http://127.0.0.1:*`
+appended to `connect-src`, and nothing else changed. Both spellings are
+listed because CSP matches a host source by name and resolves nothing;
+`[::1]` cannot be listed at all, since CSP's host grammar has no form for an
+IPv6 literal, so an IPv6-only relay stays blocked there. The ports are open
+(`:*`) because they are configuration, not constants.
+
+**What this costs:** `connect-src` is the one directive `npm run preview`
+does not verify. That is the cheapest one to give up. It can never be narrow
+in production either — the relay host comes out of the link at runtime
+(CON-46) — so it is scheme-scoped by necessity rather than by measurement.
+Every directive this section is actually about is verified exactly as it
+ships: `script-src 'self'` with no `'unsafe-inline'`, `style-src`,
+`frame-ancestors`, `object-src`, `img-src`.
+
+**What was rejected:** putting `ws:` into the shipped policy. It would permit
+plaintext to *any* host, which is most of what CON-45 exists to prevent, and
+`src/csp.test.ts` now fails if someone tries. Also rejected: accepting that
+the content-dependent half is simply unverifiable locally, which would leave
+the second layer's behaviour unknown until a real deployment exercises it.
+
+Both policies come from one set of directives (`CSP_DIRECTIVES` and the
+`PREVIEW_CSP_DIRECTIVES` derived from it, in `src/csp.ts`) rather than being
+written out twice, because two hand-kept strings drift and the drift would be
+invisible — only one of them is ever served by anything.
+
+### How to exercise the policy by hand
+
+```bash
+./scripts/dev-relay-up.sh    # the local relay the preview policy allows
+npm run build && npm run preview
+curl -sI http://localhost:4173/ | grep -i content-security-policy
+```
+
+With the page open, keep the DevTools console visible and walk the paths that
+each touch a different directive: first paint and theme (no flash, no
+`script-src` violation for `/theme-bootstrap.js`), a page with a code block
+(Shiki and CodeMirror's injected `<style>`), a page with an image from a
+foreign host (`img-src`), relay connect plus NIP-42 AUTH, and a Blossom
+upload. A clean console across those five is what acceptance #3 means.
+
+Two things the local run still cannot show. `connect-src` as it ships is not
+under test here, by the trade above; checking that needs a `wss://` relay and
+`VITE_RELAY_URL=wss://<host> npm run build`. And the dev signer
+(`?devsigner`) is gated on `import.meta.env.DEV`, so it does not exist in a
+production build — signing in under the preview policy needs a real browser
+extension.
+
+### What is checked automatically
+
+`src/csp.test.ts` pins the invariants this document argues for, so that a
+future edit cannot quietly widen them: `script-src` carries neither
+`'unsafe-inline'` nor `'unsafe-eval'`, `object-src`/`base-uri`/
+`frame-ancestors` stay exactly `'none'`, `img-src` still allows `*`, the
+shipped `connect-src` names no plaintext scheme and no loopback host, and
+`index.html` contains no inline `<script>` body. The policy lives in its own
+module (`src/csp.ts`) so the test can import it without booting Vite's
+plugins — there is still exactly one definition of it.
+
+The preview variant is pinned against the shipped one: the two differ in
+`connect-src` and nowhere else, preview only ever *adds* sources to it, and
+deriving it leaves the shipped policy unmutated. That is what keeps the
+relaxation from growing — a second directive loosened "for preview" fails the
+suite rather than quietly making the preview run say nothing about what a
+host will serve.
+
+### The risk: the app does not have a CSP yet
+
+**State it without hedging: the shipped app has no Content-Security-Policy.**
+What this repo has is a policy that is defined, reviewed and testable — one
+definition in `src/csp.ts`, guarded by `src/csp.test.ts`, and exercisable on
+the production build through `npm run preview` (bar `connect-src`, see
+above). What it does not have is any path by which a browser visiting a
+deployed Akasha receives the header.
+
+The gap is not an oversight in the policy, it is the missing serve step. This
+repo does not deploy itself: there is no app Dockerfile, no nginx or Caddy
+config, no `_headers`, `netlify.toml` or `vercel.json`, and no deployment yet
+([08](08-relay-setup.md) covers the relay, not the app). `preview.headers`
+configures Vite's own preview server and **nothing else** — it is a local
+development server, and its header never reaches a user. A static bundle
+cannot set its own response headers, and a `<meta>` tag cannot carry
+`frame-ancestors`, so nothing inside `dist/` can close this on its own.
+
+Consequences, in the order they matter:
+
+1. Until a host is configured to send the header, the app's only defence
+   against injected script is the Markdown sanitiser. The second layer this
+   section describes is **not** in force for any real reader.
+2. Wiring it is a deployment task, deliberately left to whoever picks the
+   host — adding a `Dockerfile`, `public/_headers` or an nginx snippet here
+   would pick that decision for the project, and it is tracked as its own
+   follow-up instead.
+3. Whatever that host turns out to be, the header value must come from
+   `src/csp.ts` rather than being retyped, or the guard test stops guarding
+   what is actually served.
+
 ## Images are loaded directly
 
 Loading an image from a foreign host tells that host who is reading which page,
diff --git a/docs/10-roadmap.md b/docs/10-roadmap.md
index 560ef88..6f7378d 100644
--- a/docs/10-roadmap.md
+++ b/docs/10-roadmap.md
@@ -19,7 +19,7 @@ Completed and verified:
 | Vite + React 19 + TS, routing per [06](06-ui-information-architecture.md) | `src/routes/router.tsx` |
 | Light/dark theme tokens, `@theme inline` | `src/index.css` |
 | System/light/dark switch with persistence | `src/theme/theme.tsx`, `src/ui/ThemeToggle.tsx` |
-| No flash on load | Inline script in `index.html` |
+| No flash on load | `public/theme-bootstrap.js`, loaded render-blocking from `index.html` |
 | All kinds and tags in one place, slug normalisation | `src/nostr/kinds.ts` |
 | Parsing the group address `host'id` | `src/nostr/group-address.ts` |
 | Relay connection + NIP-11 + backoff | `src/nostr/relay-status.ts` |
diff --git a/docs/12-theming.md b/docs/12-theming.md
index bc19ead..0a3bf6b 100644
--- a/docs/12-theming.md
+++ b/docs/12-theming.md
@@ -123,9 +123,27 @@ never downloads it.
 
 ## No flash on load
 
-A tiny blocking inline script in `index.html` reads `localStorage` and sets
-`data-theme` **before** the bundle loads. Without that step, every reload
-briefly flashes light mode.
+A tiny blocking script reads `localStorage` and sets `data-theme` **before** the
+bundle loads. Without that step, every reload briefly flashes light mode.
+
+It used to be inline in `index.html`. It now lives in
+`public/theme-bootstrap.js` and is loaded with
+`<script src="/theme-bootstrap.js"></script>` — **classic and
+render-blocking**, deliberately not `type="module"` and not `defer`, both of
+which are deferred and would bring back exactly the flash this script exists to
+prevent. Vite copies `public/` verbatim, so there is no build entry for it.
+
+The reason for the move is the Content-Security-Policy
+([09](09-security-privacy.md)): under `script-src 'self'` an inline block is
+blocked, and the alternatives are worse. A hash has to be recomputed every time
+the script is touched, and silently blocks the script when someone forgets; a
+nonce has to be minted per response, which a static host cannot do at all. The
+cost is one extra request before first paint. It is a few hundred bytes from
+the same origin, requested from `<head>` before the bundle, so on a local
+preview build it lands well ahead of the paint it has to beat — but that is
+the shape of the trade, not a budget: no figure here is a contract, and the
+margin on a cold cache over a slow link is the case to re-measure if the flash
+ever comes back.
 
 ## Timing
 
diff --git a/index.html b/index.html
index 71bec79..ba344d5 100644
--- a/index.html
+++ b/index.html
@@ -5,20 +5,14 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Akasha</title>
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <script>
-      // Must run BEFORE the bundle, otherwise light mode flashes on every
-      // reload. See docs/12-theming.md.
-      ;(function () {
-        try {
-          var mode = localStorage.getItem('nc-theme') || 'system'
-          var dark =
-            mode === 'dark' ||
-            (mode === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches)
-          document.documentElement.dataset.theme = dark ? 'dark' : 'light'
-          document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
-        } catch (e) {}
-      })()
-    </script>
+    <!--
+      Theme bootstrap: classic and render-blocking on purpose. It must run
+      before the bundle so a reload does not flash light mode, and it is an
+      external file so the shipped CSP can be `script-src 'self'` with no
+      'unsafe-inline'. See public/theme-bootstrap.js, docs/12-theming.md and
+      docs/09-security-privacy.md.
+    -->
+    <script src="/theme-bootstrap.js"></script>
   </head>
   <body>
     <div id="root"></div>
diff --git a/public/theme-bootstrap.js b/public/theme-bootstrap.js
new file mode 100644
index 0000000..f50aa56
--- /dev/null
+++ b/public/theme-bootstrap.js
@@ -0,0 +1,20 @@
+// Must run BEFORE the bundle, otherwise light mode flashes on every
+// reload. See docs/12-theming.md.
+//
+// This lives in `public/` rather than inline in `index.html` so that the
+// shipped Content-Security-Policy can be `script-src 'self'` with no
+// 'unsafe-inline' and no hash or nonce to keep in sync — a static host cannot
+// mint a per-response nonce anyway. See docs/09-security-privacy.md.
+// It is loaded as a classic, render-blocking script: `type="module"` is
+// deferred, which would reintroduce exactly the flash this file prevents.
+// Vite copies `public/` verbatim, so no build entry is needed.
+;(function () {
+  try {
+    var mode = localStorage.getItem('nc-theme') || 'system'
+    var dark =
+      mode === 'dark' ||
+      (mode === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches)
+    document.documentElement.dataset.theme = dark ? 'dark' : 'light'
+    document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
+  } catch (e) {}
+})()
diff --git a/src/csp.test.ts b/src/csp.test.ts
new file mode 100644
index 0000000..9660c4d
--- /dev/null
+++ b/src/csp.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest'
+import {
+  CONTENT_SECURITY_POLICY,
+  CSP_DIRECTIVES,
+  LOCAL_CONNECT_SOURCES,
+  PREVIEW_CONTENT_SECURITY_POLICY,
+  PREVIEW_CSP_DIRECTIVES,
+} from './csp'
+// The raw document, not the DOM: what matters is what ships in index.html,
+// including anything a `<script>` tag would carry that jsdom might normalise
+// away. `?raw` is Vite's own text import, so this needs no Node types.
+import indexHtml from '../index.html?raw'
+
+/**
+ * Guards for the CSP invariants (CON-44). Every one of these is a rule the
+ * docs state in prose and nothing enforced until now — the failure mode they
+ * exist for is a future edit that silences a console error by widening the
+ * policy, or that puts an inline script back into index.html, and passes CI
+ * untouched.
+ */
+describe('Content-Security-Policy', () => {
+  it('keeps script-src free of unsafe-inline and unsafe-eval', () => {
+    expect(CSP_DIRECTIVES['script-src']).not.toContain("'unsafe-inline'")
+    expect(CSP_DIRECTIVES['script-src']).not.toContain("'unsafe-eval'")
+  })
+
+  it("pins object-src, base-uri and frame-ancestors to 'none'", () => {
+    expect(CSP_DIRECTIVES['object-src']).toBe("'none'")
+    expect(CSP_DIRECTIVES['base-uri']).toBe("'none'")
+    expect(CSP_DIRECTIVES['frame-ancestors']).toBe("'none'")
+  })
+
+  it('leaves img-src open to any host', () => {
+    // Deliberate, and the one directive most likely to be "tidied up" by
+    // someone who has not read docs/09-security-privacy.md: pages embed
+    // images from arbitrary hosts and the app loads them directly.
+    expect(CSP_DIRECTIVES['img-src'].split(/\s+/)).toContain('*')
+  })
+
+  it.each([
+    ['shipped', CSP_DIRECTIVES, CONTENT_SECURITY_POLICY],
+    ['preview', PREVIEW_CSP_DIRECTIVES, PREVIEW_CONTENT_SECURITY_POLICY],
+  ])('serialises every %s directive into its header value', (_name, directives, header) => {
+    expect(header.split('; ')).toHaveLength(Object.keys(directives).length)
+    for (const [directive, value] of Object.entries(directives)) {
+      expect(header).toContain(`${directive} ${value}`)
+    }
+  })
+
+  it('keeps the shipped policy free of plaintext schemes', () => {
+    // The rejected way out of the preview problem: widening the shipped
+    // connect-src by `ws:`/`http:` would permit plaintext to *any* host,
+    // which is most of what CON-45 exists to prevent. Loopback belongs in
+    // the preview variant only.
+    const sources = CSP_DIRECTIVES['connect-src'].split(/\s+/)
+    expect(sources).not.toContain('ws:')
+    expect(sources).not.toContain('http:')
+    expect(CONTENT_SECURITY_POLICY).not.toContain('localhost')
+  })
+
+  it('has no inline script in index.html', () => {
+    // script-src 'self' blocks inline script bodies outright, with no hash
+    // and no nonce to fall back on. This assertion fails against the tree as
+    // it stood before CON-44, where the theme bootstrap sat inline here.
+    const inlineBodies = [...indexHtml.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)]
+      .map((match) => match[1].trim())
+      .filter((body) => body.length > 0)
+
+    expect(inlineBodies).toEqual([])
+  })
+})
+
+/**
+ * The preview policy is the shipped one with loopback allowed in
+ * `connect-src`, so that `npm run preview` can walk the app against the
+ * local relay under the real header. These exist to keep that difference
+ * from growing: the moment a second directive is relaxed "just for preview",
+ * the run stops saying anything about what a host will serve.
+ */
+describe('the preview policy', () => {
+  it('differs from the shipped policy in connect-src and nowhere else', () => {
+    expect(Object.keys(PREVIEW_CSP_DIRECTIVES)).toEqual(Object.keys(CSP_DIRECTIVES))
+    for (const directive of Object.keys(CSP_DIRECTIVES)) {
+      if (directive === 'connect-src') continue
+      expect(PREVIEW_CSP_DIRECTIVES[directive]).toBe(CSP_DIRECTIVES[directive])
+    }
+  })
+
+  it('adds the loopback sources to connect-src and removes none', () => {
+    expect(PREVIEW_CSP_DIRECTIVES['connect-src'].split(/\s+/)).toEqual([
+      ...CSP_DIRECTIVES['connect-src'].split(/\s+/),
+      ...LOCAL_CONNECT_SOURCES.split(/\s+/),
+    ])
+  })
+
+  it('covers the local relay under both spellings, on any port', () => {
+    // CSP matches a host source by name and resolves nothing, so localhost
+    // and 127.0.0.1 are different sources and both have to be listed. The
+    // ports are configuration (VITE_RELAY_URL, VITE_PROFILE_RELAYS,
+    // VITE_BLOSSOM_SERVER), hence `:*`. `[::1]` has no valid CSP spelling.
+    expect(LOCAL_CONNECT_SOURCES.split(/\s+/)).toEqual([
+      'ws://localhost:*',
+      'http://localhost:*',
+      'ws://127.0.0.1:*',
+      'http://127.0.0.1:*',
+    ])
+  })
+})
diff --git a/src/csp.ts b/src/csp.ts
new file mode 100644
index 0000000..7c2549d
--- /dev/null
+++ b/src/csp.ts
@@ -0,0 +1,150 @@
+/**
+ * The Content-Security-Policy the app expects to be served with (CON-44).
+ *
+ * This is the second layer behind the Markdown sanitiser, not a replacement
+ * for it: the app renders Markdown written by arbitrary public keys, so a
+ * regression in the sanitising pipeline — or a compromised npm dependency —
+ * should still find no way to execute a script. See
+ * docs/09-security-privacy.md.
+ *
+ * It is delivered as an HTTP response header, never as a
+ * `<meta http-equiv>` tag: `frame-ancestors`, `report-to` and `sandbox` are
+ * ignored in meta form, and `frame-ancestors 'none'` is part of this policy.
+ * `vite.config.ts` puts it on `preview.headers`, so
+ * `npm run build && npm run preview` serves the production build under the
+ * policy and it can be checked on the artefact that ships — with one
+ * deliberate difference, `connect-src`, so that the local relay stays
+ * reachable there. See `PREVIEW_CSP_DIRECTIVES` at the bottom of this file.
+ *
+ * The repo does not deploy itself — there is no app Dockerfile, no nginx or
+ * Caddy config, no `_headers`/`netlify.toml`/`vercel.json`. Whatever host is
+ * eventually chosen has to send this header; until then the policy is tested
+ * but nothing in production delivers it.
+ *
+ * It lives in its own module, rather than inside `vite.config.ts`, so that
+ * `src/csp.test.ts` can assert the invariants below without importing the
+ * config and booting its plugins. There is still exactly one definition:
+ * the config imports this one. Nothing under `src/` imports it, so it never
+ * reaches the bundle.
+ */
+export const CSP_DIRECTIVES: Record<string, string> = {
+  'default-src': "'self'",
+
+  // No 'unsafe-inline' and no 'unsafe-eval'. The theme bootstrap moved out of
+  // index.html into public/theme-bootstrap.js for this, and src/ contains no
+  // eval and no `new Function`.
+  'script-src': "'self'",
+
+  // 'unsafe-inline' here is forced and deliberate, and the binding constraint
+  // is CodeMirror, not React. @codemirror/view mounts its theme through
+  // style-mod's StyleModule.mount, which — for a document root, i.e. every
+  // mount in this app, since nothing here uses shadow DOM — creates a
+  // `<style>` element and assigns its textContent
+  // (node_modules/style-mod/dist/style-mod.cjs:87-94,128). That is an inline
+  // style *element*, governed by style-src-elem, and no refactor of our own
+  // code removes it: only a per-response nonce would
+  // (@codemirror/view exposes EditorView.cspNonce for that), which a static
+  // host cannot mint.
+  //
+  // Secondary, and by itself removable: five computed React `style`
+  // attributes — src/ui/Markdown.tsx:131 and :180 (the per-token Shiki
+  // styles, by far the most numerous at runtime),
+  // src/ui/layout/TableOfContents.tsx:39, src/ui/layout/Sidebar.tsx:481
+  // and :626. CSP governs style attributes too, through style-src-attr, so
+  // without 'unsafe-inline' those would silently stop applying — no error,
+  // just wrong indentation and unhighlighted code.
+  //
+  // Only script-src has to stay free of 'unsafe-inline'; an inline style
+  // cannot execute script.
+  'style-src': "'self' 'unsafe-inline'",
+
+  // Deliberately open — do not "fix" this. Pages may embed images from any
+  // host and the app loads them directly, by an explicit decision documented
+  // under "Images are loaded directly" in docs/09-security-privacy.md.
+  // `*` does not cover the `data:` scheme, so it is listed separately. No
+  // `blob:`: src/ never calls createObjectURL.
+  'img-src': '* data:',
+
+  // Scheme-scoped on purpose. The space relay is chosen at runtime from the
+  // route — whoever wrote the link picks the host — and the app also fetches
+  // that host's NIP-11 document over https (src/nostr/relay-status.ts), plus
+  // the profile relays from VITE_PROFILE_RELAYS and the Blossom server from
+  // VITE_BLOSSOM_SERVER. A static policy is fixed at build time, so no host
+  // allowlist can be built without breaking every shared space link. This
+  // follows from the relay-trust decision (CON-46), it is not an oversight.
+  'connect-src': "'self' https: wss:",
+
+  // No web fonts in the repo.
+  'font-src': "'self'",
+
+  // No <object>/<embed>, no iframes, and Shiki highlights on the main thread.
+  'object-src': "'none'",
+  'frame-src': "'none'",
+  'worker-src': "'none'",
+
+  // No <base> rewriting, no form posts anywhere (the app submits none), and
+  // the app is never meant to be framed. frame-ancestors is the directive
+  // that needs the header form.
+  'base-uri': "'none'",
+  'form-action': "'none'",
+  'frame-ancestors': "'none'",
+}
+
+function serialize(directives: Record<string, string>): string {
+  return Object.entries(directives)
+    .map(([directive, value]) => `${directive} ${value}`)
+    .join('; ')
+}
+
+/**
+ * The policy a host is expected to send. This is the one that ships, and the
+ * one `src/csp.test.ts` pins.
+ */
+export const CONTENT_SECURITY_POLICY: string = serialize(CSP_DIRECTIVES)
+
+/**
+ * Loopback origins, added to `connect-src` for `npm run preview` only.
+ *
+ * Both spellings are needed: CSP matches a host source by name and resolves
+ * nothing, so `localhost` and `127.0.0.1` are different sources. `[::1]`
+ * cannot be expressed at all — CSP's host-part grammar allows only letters,
+ * digits, hyphens and dots, so an IPv6 literal is an invalid source
+ * expression that a browser drops. A dev relay reachable only over IPv6
+ * therefore stays blocked under the preview policy; the scripts in this repo
+ * bind IPv4.
+ *
+ * The port is left open (`:*`) rather than pinned to 8080/8081/3355: the
+ * relay, the profile relay and the Blossom server all sit on different ports
+ * and the values are configuration (`VITE_RELAY_URL`, `VITE_PROFILE_RELAYS`,
+ * `VITE_BLOSSOM_SERVER`), so pinning them would only produce a policy that
+ * has to be edited whenever a port moves.
+ */
+export const LOCAL_CONNECT_SOURCES =
+  'ws://localhost:* http://localhost:* ws://127.0.0.1:* http://127.0.0.1:*'
+
+/**
+ * The shipped directives with loopback added to `connect-src`, and nothing
+ * else touched — what `npm run preview` serves.
+ *
+ * Under the shipped `connect-src` a preview run cannot load a space at all:
+ * the dev relay is `ws://localhost:<port>` with an `http://` NIP-11 fetch to
+ * the same host, the Blossom server is `http://localhost:3355`, and `'self'`
+ * does not cover them because the previewed origin is a different port. The
+ * run would then prove only that a header arrives, which is not what
+ * `preview.headers` is for. The cost — `connect-src` is the one directive a
+ * preview run no longer checks as shipped — and why that is the cheapest one
+ * to give up are argued in docs/09-security-privacy.md.
+ *
+ * Derived rather than written out a second time: two hand-kept policy
+ * strings drift, and the drift would be invisible, since only one of them is
+ * ever served by anything. `src/csp.test.ts` asserts that the two differ in
+ * `connect-src` and nowhere else, so relaxing a second directive "just for
+ * preview" fails the suite.
+ */
+export const PREVIEW_CSP_DIRECTIVES: Record<string, string> = {
+  ...CSP_DIRECTIVES,
+  'connect-src': `${CSP_DIRECTIVES['connect-src']} ${LOCAL_CONNECT_SOURCES}`,
+}
+
+/** What `vite.config.ts` puts on `preview.headers`. Never served by a host. */
+export const PREVIEW_CONTENT_SECURITY_POLICY: string = serialize(PREVIEW_CSP_DIRECTIVES)
diff --git a/vite.config.ts b/vite.config.ts
index f1c32c4..5f1fcd5 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -1,9 +1,32 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
+import { PREVIEW_CONTENT_SECURITY_POLICY } from './src/csp'
 
 export default defineConfig({
   plugins: [react(), tailwindcss()],
   // 5173 is taken by a container on this machine
-  server: { port: 5273, strictPort: true },
+  server: {
+    port: 5273,
+    strictPort: true,
+    // No CSP on the dev server, on purpose. @vitejs/plugin-react injects an
+    // inline <script type="module"> (the Fast Refresh preamble) into
+    // index.html and the HMR client opens a WebSocket to the dev server, so a
+    // dev policy would need 'unsafe-inline' in script-src plus ws: and http:
+    // in connect-src for the local relay and Blossom. That neuters the one
+    // directive this ticket is about while adding a second policy to keep in
+    // sync, and it would verify nothing that `npm run preview` does not
+    // verify better — there the policy sits on the real build, and the only
+    // thing it relaxes for the local setup is connect-src.
+  },
+  preview: {
+    // The only thing in this repo that sends a policy at all. It sends the
+    // preview variant: the shipped policy (CONTENT_SECURITY_POLICY, what a
+    // host has to be configured to send) plus loopback in connect-src, so
+    // the local relay and Blossom server stay reachable and the other
+    // directives can be walked against a loaded space. The two are derived
+    // from one set of directives and src/csp.test.ts asserts they differ in
+    // connect-src and nowhere else.
+    headers: { 'Content-Security-Policy': PREVIEW_CONTENT_SECURITY_POLICY },
+  },
 })