feat(polish): phase 10 — search, accessibility, SEO and a real CSP

PLAN.md §13 phase 10, with four decisions of record — D47-D50, taking the count
to fifty. Three were straightforward; the CSP turned into the phase's real work,
because the thing meant to be a configuration flag was broken in a dependency and
broken silently.

D47 — search reaches the marketing pages, and the header gets a box.
Base.astro marks its <main> as a Pagefind body, so all ten join the index the
docs already query, and Search.astro opens it in a <dialog>. Nothing is fetched
until the dialog is opened (the bundle is 120 kB and these pages otherwise ship
almost no JavaScript). Pagefind titles a result from the first <h1>, and these
pages have editorial ones — "The app for a deployment you already use" — so the
index is given the page's short name instead. applyBrand.mjs now re-indexes after
a rewrite, closing a note phase 2 left for this phase.

D48 — the CSP is a real response header, sent by the container. Not a <meta>,
which ignores frame-ancestors, and not advice for someone's reverse proxy, which
puts the strictest promise in §6 outside what this repo tests. Three things
fought it, all the same shape — correct build, broken page, no error:

  * Astro does not hash <script is:inline>, and Starlight ships six per docs
    page, so the first build with CSP on had a strict header and a dead theme
    switcher. The hashes are now generated into src/config/cspHashes.mjs and
    checkCsp.mjs verifies every inline block against its own page's policy.
  * Expressive Code writes ~3,700 inline style ATTRIBUTES, which cannot be
    hashed, hence style-src-attr 'unsafe-inline' — scoped to that directive, so
    script-src is untouched.
  * @astrojs/node matched a request to a policy with pathname.includes(), a
    substring test: /modules/ was served /docs/modules/building-a-module's
    policy and rendered with its own stylesheet refused. scripts/serve.mjs keeps
    the same _headers.json and matches by equality; test/headers.test.mjs starts
    the server and reads the responses, because nothing that reads dist/ can see
    this.

D49 — robots.txt allows everything and names the sitemap (there was no way to
find it: no robots.txt, and D9 rules out a search console). D50 — Organization
and SoftwareApplication, no ratings and no docs-wide Article markup.

checkA11y.mjs is the eleventh check: seven structural rules over all fifty pages,
verified by breaking each in turn. The walk at 390/768/1280 found no overflow
anywhere, the CSP violations above, a 17x17 consent checkbox (WCAG 2.2 SC 2.5.8
wants 24), and a skip link that moved the scroll but not the focus.

npm run verify is green: fourteen steps, both test suites, all eleven checks.

Co-Authored-By: Claude <noreply@anthropic.com>

test/headers.test.mjs

@@ -0,0 +1,136 @@
+/**
+ * The headers the built site actually sends. PLAN.md §6 / D48, phase 10.
+ *
+ * ---------------------------------------------------------------------------------------
+ * WHY THIS IS A TEST AND NOT A CHECK SCRIPT
+ * ---------------------------------------------------------------------------------------
+ * `scripts/checkCsp.mjs` reads `dist/_headers.json` and proves the build computed the right
+ * policy for every route. That is necessary and it is not sufficient, because the defect
+ * this file exists for happened entirely *after* the build was correct: `@astrojs/node`
+ * matched a request to a policy with `pathname.includes(...)`, a substring test, and served
+ * `/modules/` the policy built for `/docs/modules/building-a-module`. Every file on disk was
+ * right. The bytes on the wire were not.
+ *
+ * Nothing that reads `dist/` can see that. The only way to know what a reader receives is
+ * to start the server and ask it, so this starts `scripts/serve.mjs` on an ephemeral port
+ * and reads the responses.
+ *
+ * The symptom is worth restating, because it is what makes this worth a test rather than a
+ * comment: a page served another page's hash list renders with its own stylesheet REFUSED.
+ * `/modules/` and `/architecture/` were shipping unstyled sections, and the only trace was
+ * a console message. The homepage looked perfect throughout — it happened to share a hash
+ * with the 404 page it was being given.
+ *
+ * ---------------------------------------------------------------------------------------
+ * IT NEEDS A BUILD
+ * ---------------------------------------------------------------------------------------
+ * `dist/` is an input here, so this file is NOT in `npm test` — that runs before the build,
+ * both locally and in CI. It is `npm run test:served`, which `npm run verify` runs after
+ * `npm run build`. With no build present it skips rather than fails, so that a developer
+ * running the whole file by hand gets an explanation instead of a stack trace.
+ */
+
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { after, before, describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const built = fs.existsSync(path.join(root, 'dist', 'server', 'entry.mjs'));
+
+const PORT = 41732;
+const base = `http://127.0.0.1:${PORT}`;
+
+let server;
+
+/** Wait for the port to answer rather than sleeping a guessed number of milliseconds. */
+async function waitForServer(timeoutMs = 30000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      await fetch(base + '/', { signal: AbortSignal.timeout(1000) });
+      return;
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+  }
+  throw new Error(`serve.mjs did not answer on ${base} within ${timeoutMs}ms`);
+}
+
+describe('the headers the server sends', { skip: built ? false : 'no build in dist/ — run npm run build first' }, () => {
+  before(async () => {
+    server = spawn(process.execPath, [path.join(root, 'scripts', 'serve.mjs')], {
+      cwd: root,
+      env: { ...process.env, PORT: String(PORT), HOST: '127.0.0.1' },
+      stdio: 'ignore',
+    });
+    await waitForServer();
+  });
+
+  after(() => server?.kill());
+
+  const cspOf = async (route) => {
+    const res = await fetch(base + route);
+    assert.equal(res.status, route === '/404' ? 404 : 200, `${route} status`);
+    const csp = res.headers.get('content-security-policy');
+    assert.ok(csp, `${route} has no Content-Security-Policy header`);
+    return csp;
+  };
+
+  it('gives each prerendered route its OWN policy, not a substring match', async () => {
+    // The exact pair the upstream bug confused: one is a substring of the other.
+    const marketing = await cspOf('/modules/');
+    const docs = await cspOf('/docs/modules/building-a-module/');
+    assert.notEqual(marketing, docs, '/modules/ was served the docs page\'s policy');
+
+    // And the homepage, which matched whichever record came first in the file.
+    const home = await cspOf('/');
+    const notFound = await cspOf('/404');
+    assert.notEqual(home, notFound, '/ was served the 404 page\'s policy');
+  });
+
+  it("covers a page's own inline styles with hashes in the policy it is served", async () => {
+    for (const route of ['/', '/modules/', '/architecture/', '/docs/']) {
+      const csp = await cspOf(route);
+      const html = await (await fetch(base + route)).text();
+
+      let counted = 0;
+      for (const [, body] of html.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/g)) {
+        if (body.trim() === '') continue;
+        counted++;
+        const hash = `sha256-${createHash('sha256').update(body, 'utf8').digest('base64')}`;
+        assert.ok(csp.includes(hash), `${route}: an inline <style> is not hashed in its own policy`);
+      }
+      assert.ok(counted > 0, `${route}: expected at least one inline style to check`);
+    }
+  });
+
+  it('refuses framing everywhere, including the routes that render per request', async () => {
+    for (const route of ['/', '/docs/', '/beta/', '/brand/theme.css']) {
+      const res = await fetch(base + route);
+      const csp = res.headers.get('content-security-policy') ?? '';
+      assert.match(csp, /frame-ancestors 'none'/, `${route} can be framed`);
+    }
+  });
+
+  it('sends the non-CSP security headers on every response', async () => {
+    for (const route of ['/', '/docs/', '/beta/']) {
+      const res = await fetch(base + route);
+      assert.equal(res.headers.get('x-content-type-options'), 'nosniff', route);
+      assert.equal(res.headers.get('x-frame-options'), 'DENY', route);
+      assert.match(res.headers.get('referrer-policy') ?? '', /strict-origin/, route);
+      assert.match(res.headers.get('permissions-policy') ?? '', /camera=\(\)/, route);
+    }
+  });
+
+  it("never falls back to 'unsafe-inline' for scripts", async () => {
+    for (const route of ['/', '/docs/', '/beta/']) {
+      const csp = (await fetch(base + route)).headers.get('content-security-policy') ?? '';
+      const scriptSrc = /script-src ([^;]*)/.exec(csp)?.[1] ?? '';
+      assert.ok(!scriptSrc.includes("'unsafe-inline'"), `${route} script-src allows unsafe-inline`);
+    }
+  });
+});