diff --git a/config/hosting/cache-policy.json b/config/hosting/cache-policy.json index 1bf46db8..7fcc3936 100644 --- a/config/hosting/cache-policy.json +++ b/config/hosting/cache-policy.json @@ -27,6 +27,19 @@ }, "sourceMap": { "public": false + }, + "appRoute": { + "path": "/__probe/deep-link", + "cacheControl": "no-cache", + "contentTypes": ["text/html"], + "securityHeaders": true + }, + "serviceWorker": { + "path": "/service-worker.js", + "requiredWhen": "service-worker-shipped", + "cacheControl": "no-cache", + "contentTypes": ["text/javascript", "application/javascript"], + "securityHeaders": false } } } diff --git a/config/hosting/response-headers.fixture.json b/config/hosting/response-headers.fixture.json index 88ece613..504b10e5 100644 --- a/config/hosting/response-headers.fixture.json +++ b/config/hosting/response-headers.fixture.json @@ -34,6 +34,20 @@ "hashedAsset": { "cache-control": "public, max-age=31536000, immutable", "content-type": "text/javascript; charset=utf-8" + }, + "appRoute": { + "cache-control": "no-cache", + "content-type": "text/html; charset=utf-8", + "content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests", + "strict-transport-security": "max-age=31536000; includeSubDomains", + "x-frame-options": "DENY", + "referrer-policy": "strict-origin-when-cross-origin", + "x-content-type-options": "nosniff", + "permissions-policy": "camera=(), microphone=(), geolocation=()" + }, + "serviceWorker": { + "cache-control": "no-cache", + "content-type": "text/javascript; charset=utf-8" } } } diff --git a/docs/operations/release-cache-rollback.md b/docs/operations/release-cache-rollback.md index c09e7f54..a7c11402 100644 --- a/docs/operations/release-cache-rollback.md +++ b/docs/operations/release-cache-rollback.md @@ -42,6 +42,10 @@ The provider-independent cache defaults are: - hashed assets: `public, max-age=31536000, immutable` - HTML: `no-cache` +- app routes: the router uses browser history, so every path the build has + no file for (a reload, a bookmark, a shared link) is answered with the + release's `index.html` and the HTML headers (SPA fallback). A missing + hashed asset stays a 404; it never falls back to HTML - runtime config and release manifest: `no-store` - public source maps: disabled - service worker/offline cache: disabled, unless the static selection in @@ -63,6 +67,80 @@ HTTPS root URL. Each required surface must return HTTP 200 without leaving that origin before its cache, content-type, and security headers can count as deployment evidence. The hashed asset it requests is the entry script named by the served `index.html`, so it checks the release that is actually deployed. +It also requests `appRoute` (`/__probe/deep-link`, a path no build has a file +for): the host must answer 200 with the same `index.html` (the same entry +script) and the HTML headers, so a host without the SPA fallback fails +(review 1101/13-04). When the build ships a worker it requests +`/service-worker.js` and expects `no-cache`. The surfaces and their headers are +declared in `config/hosting/cache-policy.json`. + +### Example: nginx on a single server + +Written by hand for the default base path `/`; nothing in CI runs it. The live +probe above is what checks the host. `add_header` in a `location` replaces the +ones inherited from `server`, so the security headers +(`config/hosting/security-headers.json`) are an include repeated in each block. + +```nginx +# /etc/nginx/snippets/frontend-security-headers.conf +add_header Content-Security-Policy "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests" always; +add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; +add_header X-Frame-Options "DENY" always; +add_header Referrer-Policy "strict-origin-when-cross-origin" always; +add_header X-Content-Type-Options "nosniff" always; +add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always; +``` + +```nginx +server { + listen 443 ssl; + server_name app.example.com; + # ssl_certificate / ssl_certificate_key ... + + # The active release directory. Switch it with an atomic symlink rename. + root /srv/frontend/current; + + # index.html, and every app route through the fallback below. + location = /index.html { + add_header Cache-Control "no-cache"; + include snippets/frontend-security-headers.conf; + } + location / { + try_files $uri /index.html; + include snippets/frontend-security-headers.conf; + } + + location = /config.json { + add_header Cache-Control "no-store"; + include snippets/frontend-security-headers.conf; + } + location = /release-manifest.json { + add_header Cache-Control "no-store"; + include snippets/frontend-security-headers.conf; + } + + # Hashed files of every retained release in one directory (names never + # collide). Prune by age, not on switch. A missing chunk is a 404, never + # index.html: an old tab has to see the failure to reload once (FE-RB-002). + location /assets/ { + root /srv/frontend/shared; + add_header Cache-Control "public, max-age=31536000, immutable"; + try_files $uri =404; + } + + # Only when the build ships a worker (cache-policy.json `serviceWorker`). + location = /service-worker.js { + add_header Cache-Control "no-cache"; + try_files $uri =404; + } + + location ~ \.map$ { + return 404; + } +} +``` + +`Cache-Control` has no `always`, so a 404 is never stored as immutable. FE-GATE-019 is therefore a production-stage gate (`production_gate` job, `PROD_PROMOTION_READY`). It runs after `promotion` and after the project has diff --git a/scripts/lib/hosting-probe.ts b/scripts/lib/hosting-probe.ts index 4122d1b6..ec81fffb 100644 --- a/scripts/lib/hosting-probe.ts +++ b/scripts/lib/hosting-probe.ts @@ -28,6 +28,104 @@ export function servedEntryScript(indexHtml: string): string | null { } return null; } +export type ProbeResult = Readonly<{ + surface: string; + header: string; + expected: unknown; + observed: unknown; + reason?: string; + passed: boolean; +}>; +export type ResponseHeaders = Record>; +export type HostingFetcher = (url: URL) => Promise; + +/** + * 13-05 (D-14). Runs after the promoted release is deployed. Every surface must + * answer 200 without leaving the probed origin, and the hashed asset it + * requests is the entry script the served index.html names. + * + * 1101/13-04. `appRoute` is a path the build has no file for. The router uses + * browser history, so a reload or a shared link of any route reaches the host + * as such a path, and the host must answer it with the same index.html (SPA + * fallback). A 404 or any other page there fails, although `/` still works. + */ +export async function probeLiveRelease( + base: URL, + paths: Readonly>, + fetcher: HostingFetcher = (url) => fetch(url, { redirect: "follow" }), +): Promise<{ responses: ResponseHeaders; results: ProbeResult[] }> { + const responses: ResponseHeaders = {}; + const results: ProbeResult[] = []; + const probe = async (surface: string, pathname: string): Promise => { + try { + const response = await fetcher(new URL(pathname, base)); + const finalOrigin = new URL(response.url).origin; + results.push( + { + surface, + header: "http-status", + expected: 200, + observed: response.status, + passed: response.status === 200, + }, + { + surface, + header: "final-origin", + expected: base.origin, + observed: finalOrigin, + passed: finalOrigin === base.origin, + }, + ); + responses[surface] = Object.fromEntries( + [...response.headers.entries()].map(([name, value]) => [name.toLowerCase(), value]), + ); + return await response.text(); + } catch (error: unknown) { + results.push({ + surface, + header: "transport", + expected: "reachable", + observed: error instanceof Error ? error.name : "UnknownError", + passed: false, + }); + return null; + } + }; + + const bodies: Record = {}; + for (const [surface, pathname] of Object.entries(paths)) { + bodies[surface] = await probe(surface, pathname); + } + const entryScript = servedEntryScript(bodies["index"] ?? ""); + if (entryScript) { + await probe("hashedAsset", entryScript); + } else { + results.push({ + surface: "hashedAsset", + header: "entry-script", + expected: "a module script named by the served index.html", + observed: null, + passed: false, + }); + } + if ("appRoute" in paths) { + const observed = servedEntryScript(bodies["appRoute"] ?? ""); + results.push({ + surface: "appRoute", + header: "entry-script", + expected: entryScript, + observed, + passed: entryScript !== null && observed === entryScript, + }); + } + return { responses, results }; +} + +/** A build ships a worker script for these selections (06-03: REMOVE_REGISTRATION ships the self-unregistering one). */ +export function shipsServiceWorker(selection: InstalledServiceWorkerSelection | null): boolean { + return selection?.mode === "ACTIVE" || selection?.mode === "REMOVE_REGISTRATION"; +} + const PUBLIC_SERVICE_WORKER = /(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i; /** @@ -41,9 +139,7 @@ export function checkPublicServiceWorkers( ) { const found = distFiles.filter((file) => PUBLIC_SERVICE_WORKER.test(file)); const allowed: string[] = - selection?.mode === "ACTIVE" || selection?.mode === "REMOVE_REGISTRATION" - ? [selection.scriptPath] - : []; + selection && shipsServiceWorker(selection) ? [selection.scriptPath] : []; const passed = found.length === allowed.length && found.every((file) => allowed.includes(file)); diff --git a/scripts/verify-hosting-headers.ts b/scripts/verify-hosting-headers.ts index 8bc55330..1e8005ef 100644 --- a/scripts/verify-hosting-headers.ts +++ b/scripts/verify-hosting-headers.ts @@ -6,21 +6,15 @@ import { checkPublicServiceWorkers, classifyLiveHostingBaseUrl, hostingVerdict, - servedEntryScript, + probeLiveRelease, + shipsServiceWorker, type HostingMode, + type ProbeResult, + type ResponseHeaders, } from "./lib/hosting-probe.ts"; import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; type Document = Record; -type ResponseHeaders = Record>; -type ProbeResult = Readonly<{ - surface: string; - header: string; - expected: unknown; - observed: unknown; - reason?: string; - passed: boolean; -}>; function isRecord(value: unknown): value is Document { return Boolean(value) && typeof value === "object" && !Array.isArray(value); @@ -70,68 +64,26 @@ const liveTarget = baseUrl ? classifyLiveHostingBaseUrl(baseUrl) : null; const distFiles = (await readdir("dist", { recursive: true })).map(String); const publicSourceMaps = distFiles.filter((file) => file.endsWith(".map")); +// 1101/13-04. The worker script surface exists only in a build that ships one. +const workerShipped = shipsServiceWorker(INSTALLED_RUNTIME_CAPABILITIES.serviceWorker); +const requiredSurfaces = Object.entries(cacheSurfaces) + .map(([surface, policy]) => [surface, recordValue(policy)] as const) + .filter(([, policy]) => policy.requiredWhen !== "service-worker-shipped" || workerShipped); + let responses: ResponseHeaders = {}; let mode: HostingMode; const probeResults: ProbeResult[] = []; if (liveTarget?.passed) { mode = "live"; - // 13-05: FE-GATE-019 runs after the promoted release is deployed, and the - // hashed asset it probes is the entry script that release's index.html names. - const probe = async (surface: string, pathname: string): Promise => { - const requestedUrl = new URL(pathname, liveTarget.url); - try { - const response = await fetch(requestedUrl, { redirect: "follow" }); - const finalUrl = new URL(response.url); - probeResults.push( - { - surface, - header: "http-status", - expected: 200, - observed: response.status, - passed: response.status === 200, - }, - { - surface, - header: "final-origin", - expected: liveTarget.url.origin, - observed: finalUrl.origin, - passed: finalUrl.origin === liveTarget.url.origin, - }, - ); - responses[surface] = Object.fromEntries( - [...response.headers.entries()].map(([name, value]) => [ - name.toLowerCase(), - value, - ]), - ); - return await response.text(); - } catch (error: unknown) { - probeResults.push({ - surface, - header: "transport", - expected: "reachable", - observed: error instanceof Error ? error.name : "UnknownError", - passed: false, - }); - return null; - } - }; - const indexHtml = await probe("index", "/"); - await probe("runtimeConfig", "/config.json"); - await probe("releaseManifest", "/release-manifest.json"); - const entryScript = indexHtml === null ? null : servedEntryScript(indexHtml); - if (entryScript) { - await probe("hashedAsset", entryScript); - } else { - probeResults.push({ - surface: "hashedAsset", - header: "entry-script", - expected: "a module script named by the served index.html", - observed: null, - passed: false, - }); - } + const paths = Object.fromEntries( + requiredSurfaces.flatMap(([surface, policy]) => + typeof policy.path === "string" ? [[surface, policy.path] as const] : [], + ), + ); + const probed = await probeLiveRelease(liveTarget.url, paths); + responses = probed.responses; + probeResults.push(...probed.results); } else if (liveTarget) { mode = "invalid-live"; probeResults.push({ @@ -151,8 +103,7 @@ if (liveTarget?.passed) { } const results: ProbeResult[] = [...probeResults]; -for (const [surface, rawPolicy] of Object.entries(cacheSurfaces)) { - const policy = recordValue(rawPolicy); +for (const [surface, policy] of requiredSurfaces) { if (typeof policy.cacheControl !== "string") continue; const contentTypes = strings(policy.contentTypes); const observed = responses[surface]?.["cache-control"]; diff --git a/tests/unit/hosting-probe.test.ts b/tests/unit/hosting-probe.test.ts index 5f796756..1c5bab01 100644 --- a/tests/unit/hosting-probe.test.ts +++ b/tests/unit/hosting-probe.test.ts @@ -1,11 +1,15 @@ +import { readFile } from "node:fs/promises"; + import { describe, expect, it } from "vitest"; import { checkPublicServiceWorkers, classifyLiveHostingBaseUrl, hostingVerdict, + probeLiveRelease, servedEntryScript, } from "../../scripts/lib/hosting-probe.ts"; +import { SERVICE_WORKER_SCRIPT_PATH } from "../../src/contracts/service-worker.ts"; describe("public service worker in dist", () => { const app = ["index.html", "config.json", "assets/index-abc.js"]; @@ -96,3 +100,76 @@ describe("hosting header verdict", () => { expect(servedEntryScript("maintenance")).toBeNull(); }); }); + +// 1101/13-04. The router uses browser history, so a reload or a shared link of +// any route reaches the host as a path the build has no file for. The host has +// to answer it with the release's index.html; without that fallback `/` still +// opens and only deep links are 404, which no other check sees. +describe("SPA fallback and worker script surfaces (1101/13-04)", () => { + type Surface = Partial<{ + path: string; + cacheControl: string; + contentTypes: string[]; + securityHeaders: boolean; + requiredWhen: string; + }>; + const surfaces = async () => + (JSON.parse(await readFile("config/hosting/cache-policy.json", "utf8")) as { + surfaces: Record; + }).surfaces; + + it("declares an app route the build has no file for, served like index.html", async () => { + const { appRoute, index } = await surfaces(); + expect(appRoute).toMatchObject({ + cacheControl: index?.cacheControl, + contentTypes: index?.contentTypes, + securityHeaders: true, + }); + expect(appRoute?.path).toMatch(/^\/[^.]+$/u); + const { responses } = JSON.parse( + await readFile("config/hosting/response-headers.fixture.json", "utf8"), + ) as { responses: Record }; + expect(responses["appRoute"]).toEqual(responses["index"]); + }); + + it("declares the worker script, served no-cache, only for a build that ships it", async () => { + expect((await surfaces())["serviceWorker"]).toMatchObject({ + path: `/${SERVICE_WORKER_SCRIPT_PATH}`, + cacheControl: "no-cache", + requiredWhen: "service-worker-shipped", + }); + }); + + const INDEX = ''; + const PATHS = { index: "/", runtimeConfig: "/config.json", appRoute: "/__probe/deep-link" }; + const RELEASE: Record = { + "/": [200, INDEX], + "/config.json": [200, "{}"], + "/assets/index-A1.js": [200, ""], + }; + const host = (routes: Record) => async (url: URL) => { + const [status, body] = routes[url.pathname] ?? [404, "Not Found"]; + const response = new Response(body, { status, headers: { "cache-control": "no-cache" } }); + Object.defineProperty(response, "url", { value: url.href }); + return response; + }; + const base = new URL("https://frontend.example.test/"); + const failed = async (routes: Record) => + (await probeLiveRelease(base, PATHS, host(routes))).results + .filter((result) => !result.passed) + .map((result) => `${result.surface} ${result.header}`); + + it("passes a host that answers every route with the release's index.html", async () => { + expect(await failed({ ...RELEASE, "/__probe/deep-link": [200, INDEX] })).toEqual([]); + }); + + it("fails a host without the fallback", async () => { + expect(await failed(RELEASE)).toEqual(["appRoute http-status", "appRoute entry-script"]); + }); + + it("fails a fallback that answers 200 with a page that is not the release's index.html", async () => { + expect( + await failed({ ...RELEASE, "/__probe/deep-link": [200, "

Not found

"] }), + ).toEqual(["appRoute entry-script"]); + }); +});