feat: add CSP generation and serving scripts for enhanced security in built docs

Author: paustint

docs/package.json

@@ -5,11 +5,12 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
-    "build": "docusaurus build",
+    "build": "docusaurus build && node scripts/generate-csp.mjs",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
+    "serve:csp": "node scripts/serve-csp.mjs",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc"

docs/scripts/generate-csp.mjs

@@ -0,0 +1,94 @@
+/**
+ * Generates a Content-Security-Policy for the built docs site.
+ *
+ * Docusaurus emits a small number of inline <script> tags (the color-mode/theme bootstrap and
+ * the base-url-issue banner). Allowing them via 'unsafe-inline' defeats the purpose of a CSP,
+ * so instead this script scans the build output, computes the sha256 hash of every executable
+ * inline script, and produces a policy that allows exactly those scripts and nothing else.
+ *
+ * Run automatically as part of `npm run build`. Outputs:
+ *   1. `build/_headers` — applied automatically when hosting on Cloudflare Pages
+ *   2. `build/serve.json` — applies the same header when testing locally via `npx serve build`
+ *   3. The policy printed to stdout — paste into a Cloudflare Response Header Transform Rule
+ *      if the header is managed at the zone level instead
+ *
+ * Hashes are derived from the build output itself, so Docusaurus upgrades or config changes
+ * that alter the inline scripts are picked up automatically on the next build.
+ */
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const BUILD_DIR = fileURLToPath(new URL('../build', import.meta.url));
+
+// Script types that browsers execute and CSP script-src applies to.
+// Anything else (e.g. application/ld+json structured data) is inert and needs no hash.
+const EXECUTABLE_SCRIPT_TYPES = new Set(['', 'module', 'text/javascript', 'application/javascript']);
+
+const SCRIPT_TAG_REGEX = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+
+function collectHtmlFiles(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      return collectHtmlFiles(fullPath);
+    }
+    return entry.name.endsWith('.html') ? [fullPath] : [];
+  });
+}
+
+function getInlineScriptHashes() {
+  const hashes = new Set();
+  for (const htmlFile of collectHtmlFiles(BUILD_DIR)) {
+    const html = readFileSync(htmlFile, 'utf-8');
+    for (const [, attrs, body] of html.matchAll(SCRIPT_TAG_REGEX)) {
+      const hasSrc = /\bsrc\s*=/i.test(attrs);
+      const type = (attrs.match(/\btype\s*=\s*["']?([^"'\s>]*)/i)?.[1] ?? '').toLowerCase();
+      if (hasSrc || !EXECUTABLE_SCRIPT_TYPES.has(type) || !body.trim()) {
+        continue;
+      }
+      // CSP hashes are computed over the exact script content, byte for byte
+      hashes.add(`'sha256-${createHash('sha256').update(body).digest('base64')}'`);
+    }
+  }
+  return [...hashes].sort();
+}
+
+const scriptHashes = getInlineScriptHashes();
+
+const csp = [
+  `default-src 'self'`,
+  `script-src 'self' ${scriptHashes.join(' ')}`,
+  `style-src 'self' 'unsafe-inline'`,
+  `img-src 'self' data:`,
+  `font-src 'self' data:`,
+  `connect-src 'self'`,
+  `frame-ancestors 'none'`,
+  `base-uri 'self'`,
+  `form-action 'self'`,
+  `object-src 'none'`,
+  `upgrade-insecure-requests`,
+].join('; ');
+
+const headers = {
+  'Content-Security-Policy': csp,
+  'Permissions-Policy': 'camera=(), microphone=(), geolocation=(), interest-cohort=()',
+  'Referrer-Policy': 'strict-origin-when-cross-origin',
+  'X-Content-Type-Options': 'nosniff',
+};
+
+const headerLines = Object.entries(headers)
+  .map(([key, value]) => `  ${key}: ${value}`)
+  .join('\n');
+writeFileSync(join(BUILD_DIR, '_headers'), `/*\n${headerLines}\n`);
+
+const serveConfig = {
+  headers: [{ source: '**', headers: Object.entries(headers).map(([key, value]) => ({ key, value })) }],
+};
+writeFileSync(join(BUILD_DIR, 'serve.json'), `${JSON.stringify(serveConfig, null, 2)}\n`);
+
+console.log(`Found ${scriptHashes.length} inline script hash(es):`);
+scriptHashes.forEach((hash) => console.log(`  ${hash}`));
+console.log('\nWrote build/_headers with the following policy:\n');
+console.log(csp);

docs/scripts/serve-csp.mjs

@@ -0,0 +1,59 @@
+/**
+ * Serves the built docs site locally with the security headers from `build/_headers` applied
+ * to every response, so header changes can be tested in a real browser before deploy.
+ * (`docusaurus serve` cannot set custom headers, hence this script.)
+ *
+ * Usage: node scripts/serve-csp.mjs [port]   (default port 3939)
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { extname, join, normalize } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const BUILD_DIR = fileURLToPath(new URL('../build', import.meta.url));
+const PORT = Number(process.argv[2]) || 3939;
+
+const headersFile = readFileSync(join(BUILD_DIR, '_headers'), 'utf-8');
+const securityHeaders = [...headersFile.matchAll(/^\s+([\w-]+):\s*(.+)$/gm)].map(([, key, value]) => [key, value.trim()]);
+if (!securityHeaders.some(([key]) => key === 'Content-Security-Policy')) {
+  console.error('No Content-Security-Policy found in build/_headers — run a build first');
+  process.exit(1);
+}
+
+const CONTENT_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.xml': 'application/xml',
+  '.txt': 'text/plain',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+// Mirrors static host routing: exact file, then `page.html`, then `page/index.html`, then 404
+function resolveFile(urlPath) {
+  const safePath = normalize(decodeURIComponent(urlPath)).replace(/^(\.\.[/\\])+/, '');
+  const candidates = [
+    join(BUILD_DIR, safePath, safePath.endsWith('/') || safePath === '' ? 'index.html' : ''),
+    join(BUILD_DIR, safePath),
+    join(BUILD_DIR, `${safePath}.html`),
+    join(BUILD_DIR, safePath, 'index.html'),
+  ];
+  return candidates.find((candidate) => existsSync(candidate) && extname(candidate) !== '') ?? join(BUILD_DIR, '404.html');
+}
+
+createServer((req, res) => {
+  const filePath = resolveFile(new URL(req.url, 'http://localhost').pathname.slice(1));
+  res.setHeader('Content-Type', CONTENT_TYPES[extname(filePath)] ?? 'application/octet-stream');
+  securityHeaders.forEach(([key, value]) => res.setHeader(key, value));
+  res.end(readFileSync(filePath));
+}).listen(PORT, () => {
+  console.log(`Serving build/ with headers from build/_headers at http://localhost:${PORT}`);
+  securityHeaders.forEach(([key, value]) => console.log(`  ${key}: ${value}`));
+});