diff --git a/.gitea/workflows/quality-gates.yml b/.gitea/workflows/quality-gates.yml index 195b9b55..421c2ffe 100644 --- a/.gitea/workflows/quality-gates.yml +++ b/.gitea/workflows/quality-gates.yml @@ -83,15 +83,12 @@ jobs: if: ${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }} runs-on: ubuntu-latest timeout-minutes: 45 - env: - HOSTING_BASE_URL: "${{ vars.HOSTING_BASE_URL }}" strategy: fail-fast: false matrix: include: - { gate: FE-GATE-012, name: bundle, browser: false } - { gate: FE-GATE-014, name: config-compatibility, browser: false } - - { gate: FE-GATE-019, name: hosting-header, browser: false } - { gate: FE-GATE-026, name: lab-performance, browser: true } - { gate: FE-GATE-028, name: manual-accessibility-review, browser: false } steps: @@ -375,10 +372,13 @@ jobs: if: ${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }} runs-on: ubuntu-latest timeout-minutes: 45 + env: + HOSTING_BASE_URL: "${{ vars.HOSTING_BASE_URL }}" strategy: fail-fast: false matrix: include: + - { gate: FE-GATE-019, name: hosting-header } - { gate: FE-GATE-021, name: runbook-boot-config } - { gate: FE-GATE-022, name: runbook-chunk-mismatch } - { gate: FE-GATE-023, name: runbook-api-degradation } diff --git a/README.md b/README.md index eefc9f96..e251b7d1 100644 --- a/README.md +++ b/README.md @@ -169,7 +169,9 @@ Two gates intentionally need external evidence: - `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum eligible-sample threshold and 28 days of production data exist. -Live release verification additionally requires `HOSTING_BASE_URL`. +Live hosting verification (FE-GATE-019, production stage) requires +`HOSTING_BASE_URL` and a deployed promoted release; without it the result is +`UNVERIFIED`, not `PASS`. ## CI and evidence diff --git a/config/ci/contract-baseline.json b/config/ci/contract-baseline.json index 8134b889..bd1568c4 100644 --- a/config/ci/contract-baseline.json +++ b/config/ci/contract-baseline.json @@ -1,11 +1,11 @@ { "schemaVersion": 1, "owner": "frontend-platform", - "reason": "11-03: FE-GATE-005 runs the CPU-independent scale PR tier (check:scale:pr)", + "reason": "13-05 (D-14): FE-GATE-019 probes the deployed promoted release in the production stage; the fixture is UNVERIFIED", "gates": 27, "commands": 95, "commandReferences": 105, "artifacts": 109, "stages": 5, - "gateShapeSha256": "58e5be2bdf92c9ee355fa93ced794b6cc948a960905e80919d95087e56262d94" + "gateShapeSha256": "648066f2ba0dd38c3193550ecb4bd030a2e0f66027919256648f78333564db3c" } diff --git a/config/ci/gates.json b/config/ci/gates.json index 3d75cb03..3778db53 100644 --- a/config/ci/gates.json +++ b/config/ci/gates.json @@ -2054,7 +2054,7 @@ "evidenceArtifactIds": [ "artifact-artifacts-release-hosting-headers-json" ], - "retentionClassId": "release-coherence", + "retentionClassId": "prod-drill", "requiresEnvironment": [ "HOSTING_BASE_URL" ] @@ -2217,7 +2217,6 @@ "FE-GATE-012", "FE-GATE-014", "FE-GATE-015", - "FE-GATE-019", "FE-GATE-026", "FE-GATE-027", "FE-GATE-028" @@ -2230,6 +2229,7 @@ "release" ], "gateIds": [ + "FE-GATE-019", "FE-GATE-021", "FE-GATE-022", "FE-GATE-023", @@ -2323,19 +2323,13 @@ "gateIds": [ "FE-GATE-012", "FE-GATE-014", - "FE-GATE-019", "FE-GATE-026", "FE-GATE-028" ], "browserGateIds": [ "FE-GATE-026" ], - "environment": [ - { - "name": "HOSTING_BASE_URL", - "value": "${{ vars.HOSTING_BASE_URL }}" - } - ], + "environment": [], "steps": [ { "kind": "checkout" @@ -2760,6 +2754,7 @@ "condition": "production", "timeoutMinutes": 45, "gateIds": [ + "FE-GATE-019", "FE-GATE-021", "FE-GATE-022", "FE-GATE-023", @@ -2767,7 +2762,12 @@ "FE-GATE-025" ], "browserGateIds": [], - "environment": [], + "environment": [ + { + "name": "HOSTING_BASE_URL", + "value": "${{ vars.HOSTING_BASE_URL }}" + } + ], "steps": [ { "kind": "checkout" diff --git a/docs/architecture/static-delivery.md b/docs/architecture/static-delivery.md index 022787ca..130739e0 100644 --- a/docs/architecture/static-delivery.md +++ b/docs/architecture/static-delivery.md @@ -29,5 +29,10 @@ sequenceDiagram CI->>Browser: boot, route, API, and reload-loop smoke ``` +In this repository the workflow stops at promotion. The upload, pointer switch +and smoke steps above belong to the project's provider adapter; after it has +deployed the promoted release, FE-GATE-019 probes the live headers (review +13-05, [`release-cache-rollback.md`](../operations/release-cache-rollback.md)). + Rollback changes the active pointer only after confirming that the prior immutable release has a coherent HTML/assets/config/API/manifest tuple. diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index e7fc020e..dffabc88 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -371,7 +371,9 @@ Repository variables required by higher tiers: - `RUNNER_IMAGE_DIGEST` for the immutable job-container image digest used by the `ubuntu-latest` runner label; the workflow exposes it to gates as `CI_RUNNER_IMAGE` (required by every tier) -- `HOSTING_BASE_URL` for live header verification +- `HOSTING_BASE_URL` for live header verification of the deployed promoted + release (FE-GATE-019, production stage). Without it the gate fails; the + local fixture result is `UNVERIFIED` - `APP_PROFILE` for the runtime profile the release candidate is built from (`local`, `development`, `staging`, `production`; `scripts/generate-runtime-config.ts`). An unset value builds `local`; an empty diff --git a/docs/operations/release-cache-rollback.md b/docs/operations/release-cache-rollback.md index d0f71f34..aa18c558 100644 --- a/docs/operations/release-cache-rollback.md +++ b/docs/operations/release-cache-rollback.md @@ -52,9 +52,24 @@ HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared to the declared allowlist; a cache-correct response with a mismatched `Content-Type` still fails the hosting gate. -`corepack pnpm verify:hosting-headers` uses a deterministic fixture locally. -Set `HOSTING_BASE_URL` to probe deployed responses; production promotion -requires the artifact to report `mode: "live"`. The live target must be its -canonical, non-loopback 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. +`corepack pnpm verify:hosting-headers` compares the declared headers with a +deterministic fixture when `HOSTING_BASE_URL` is unset. That only shows the +declarations agree with each other, so its result is `UNVERIFIED` (exit 3), not +`PASS` (review 13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). Only +`mode: "live"` can pass. The live target must be its canonical, non-loopback +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. + +FE-GATE-019 is therefore a production-stage gate (`production_gate` job, +`PROD_PROMOTION_READY`). It runs after `promotion` and after the project has +deployed the promoted release. This repository's workflow stops at promotion: +uploading the release, switching the active pointer, and the post-switch smoke +are the project's provider adapter, chosen with the hosting provider. + +Keep a retired release's hashed assets reachable while any open tab may still +request them. The minimum is the previous release while the next one is +active (the rolling window modeled in `tests/release/release-fixture.ts`). +Size it to the longest session the product supports; a tab older than that +depends on the reload-once recovery (FE-RB-002). diff --git a/scripts/contracts/ci-gates.ts b/scripts/contracts/ci-gates.ts index 648e6429..bf045c46 100644 --- a/scripts/contracts/ci-gates.ts +++ b/scripts/contracts/ci-gates.ts @@ -874,12 +874,12 @@ function validateContractSemantics( } const expectedJobOwnership: Readonly> = { merge_gate: ["FE-GATE-001", "FE-GATE-002", "FE-GATE-003", "FE-GATE-004", "FE-GATE-005", "FE-GATE-006", "FE-GATE-007", "FE-GATE-008", "FE-GATE-009", "FE-GATE-010", "FE-GATE-011", "FE-GATE-013", "FE-GATE-020"], - release_gate: ["FE-GATE-012", "FE-GATE-014", "FE-GATE-019", "FE-GATE-026", "FE-GATE-028"], + release_gate: ["FE-GATE-012", "FE-GATE-014", "FE-GATE-026", "FE-GATE-028"], immutable_build: ["FE-GATE-015", "FE-GATE-027"], vulnerability_provider: [], provenance_provider: [], promotion: [], - production_gate: ["FE-GATE-021", "FE-GATE-022", "FE-GATE-023", "FE-GATE-024", "FE-GATE-025"], + production_gate: ["FE-GATE-019", "FE-GATE-021", "FE-GATE-022", "FE-GATE-023", "FE-GATE-024", "FE-GATE-025"], field_gate: ["FE-GATE-018"], documentation_gate: ["FE-GATE-017"], }; @@ -928,7 +928,7 @@ function validateContractSemantics( } const expectedEnvironmentBindings: Readonly []>> = { merge_gate: [], - release_gate: [{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" }], + release_gate: [], immutable_build: [ // FE-GATE-027 admits the built artifact to a named environment, so both // the profile it was built from and the destination it is claimed for are @@ -974,7 +974,9 @@ function validateContractSemantics( { name: "VULNERABILITY_INVOCATION_NONCE", value: "${{ needs.vulnerability_provider.outputs.invocation_nonce }}" }, { name: "PROVENANCE_INVOCATION_NONCE", value: "${{ needs.provenance_provider.outputs.invocation_nonce }}" }, ], - production_gate: [], + // 13-05: FE-GATE-019 probes the promoted release after the provider has + // deployed it, so the live base URL belongs to the production stage. + production_gate: [{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" }], field_gate: [ { name: "FIELD_WEB_VITALS_INPUT", value: "${{ vars.FIELD_WEB_VITALS_INPUT }}" }, { name: "MIN_ELIGIBLE_SAMPLES", value: "${{ vars.MIN_ELIGIBLE_SAMPLES }}" }, diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index baa63804..9a2ad575 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -1453,9 +1453,15 @@ export const hostingHeadersArtifactSchema = z .strict(), ).min(1), passed: z.boolean(), + // 13-05 (D-14): only a live probe can PASS; the fixture is UNVERIFIED. + status: z.enum(["PASS", "FAIL", "UNVERIFIED"]), }) .strict() .superRefine((artifact, context) => { + const expectedStatus = !artifact.passed ? "FAIL" : artifact.mode === "live" ? "PASS" : "UNVERIFIED"; + if (artifact.status !== expectedStatus) { + context.addIssue({ code: "custom", path: ["status"], message: `must be ${expectedStatus} for this mode and result` }); + } const keys = artifact.results.map(({ surface, header }) => `${surface}\0${header}`); addUniqueStringIssues(keys, ["results"], context); const requiredKeys = [ diff --git a/scripts/lib/hosting-probe.ts b/scripts/lib/hosting-probe.ts index 5f6ec9c2..4aa752f7 100644 --- a/scripts/lib/hosting-probe.ts +++ b/scripts/lib/hosting-probe.ts @@ -1,6 +1,33 @@ import type { InstalledServiceWorkerSelection } from "../../src/contracts/service-worker.ts"; const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/; + +export type HostingMode = "live" | "invalid-live" | "fixture"; +export type HostingVerdict = "PASS" | "FAIL" | "UNVERIFIED"; + +/** + * 13-05 (D-14). The fixture compares the declared headers with a copy of + * themselves, so it can only find a contradiction, never prove hosting. Only a + * live probe of the deployed release can PASS. + */ +export function hostingVerdict(mode: HostingMode, passed: boolean): HostingVerdict { + if (!passed) return "FAIL"; + return mode === "live" ? "PASS" : "UNVERIFIED"; +} + +/** + * 13-05. The live probe requests the entry script the served index.html names, + * so it checks the release that is deployed rather than the first asset of a + * local build, which the deployed release may not contain. + */ +export function servedEntryScript(indexHtml: string): string | null { + for (const tag of indexHtml.match(/]*>/gu) ?? []) { + if (!/\btype=["']module["']/u.test(tag)) continue; + const source = /\bsrc=["']([^"']+\.js)["']/u.exec(tag)?.[1]; + if (source) return source; + } + return null; +} const PUBLIC_SERVICE_WORKER = /(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i; /** diff --git a/scripts/lib/promotion-readiness.ts b/scripts/lib/promotion-readiness.ts index 607f1649..781f6a52 100644 --- a/scripts/lib/promotion-readiness.ts +++ b/scripts/lib/promotion-readiness.ts @@ -18,7 +18,6 @@ export const PROMOTION_FORMULA = Object.freeze({ "FE-GATE-012", "FE-GATE-014", "FE-GATE-015", - "FE-GATE-019", "FE-GATE-026", // FE-GATE-027. A candidate is only release-ready once it has been admitted // to a named environment; coherence alone never proved it belonged there. @@ -28,6 +27,9 @@ export const PROMOTION_FORMULA = Object.freeze({ "FE-GATE-028", ]), PROD_PROMOTION_READY: Object.freeze([ + // FE-GATE-019 (13-05, D-14). Live hosting headers of the deployed promoted + // release; the declared-header fixture alone is UNVERIFIED, not PASS. + "FE-GATE-019", // FE-GATE-016 is retired (D-14): it repeated FE-GATE-025's FE-RB-005 drill. "FE-GATE-021", "FE-GATE-022", diff --git a/scripts/verify-hosting-headers.ts b/scripts/verify-hosting-headers.ts index afcfdf53..8bc55330 100644 --- a/scripts/verify-hosting-headers.ts +++ b/scripts/verify-hosting-headers.ts @@ -5,12 +5,14 @@ import { hostingHeadersArtifactSchema } from "./contracts/release-artifacts.ts"; import { checkPublicServiceWorkers, classifyLiveHostingBaseUrl, + hostingVerdict, + servedEntryScript, + type HostingMode, } from "./lib/hosting-probe.ts"; import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; type Document = Record; type ResponseHeaders = Record>; -type HostingMode = "live" | "invalid-live" | "fixture"; type ProbeResult = Readonly<{ surface: string; header: string; @@ -74,16 +76,9 @@ const probeResults: ProbeResult[] = []; if (liveTarget?.passed) { mode = "live"; - const assets = await readdir("dist/assets"); - const hashedJavaScript = assets.find((file) => file.endsWith(".js")); - if (!hashedJavaScript) throw new Error("No built hashed JavaScript found."); - const paths = { - index: "/", - runtimeConfig: "/config.json", - releaseManifest: "/release-manifest.json", - hashedAsset: `/assets/${hashedJavaScript}`, - }; - for (const [surface, pathname] of Object.entries(paths)) { + // 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" }); @@ -110,6 +105,7 @@ if (liveTarget?.passed) { value, ]), ); + return await response.text(); } catch (error: unknown) { probeResults.push({ surface, @@ -118,7 +114,23 @@ if (liveTarget?.passed) { 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, + }); } } else if (liveTarget) { mode = "invalid-live"; @@ -193,6 +205,7 @@ results.push( ); const passed = results.every((result) => result.passed); +const status = hostingVerdict(mode, passed); await mkdir("artifacts/release", { recursive: true }); await writeValidatedJsonArtifact({ path: "artifacts/release/hosting-headers.json", @@ -205,17 +218,21 @@ await writeValidatedJsonArtifact({ providerVerificationRequired: mode !== "live", results, passed, + status, }, }); -if (!passed) { +if (status === "FAIL") { process.stderr.write( "Hosting cache/content-type/security header verification failed.\n", ); process.exit(1); } -process.stdout.write( - `Hosting header contract: PASS (${mode}; live verification ${ - mode === "live" ? "complete" : "required before promotion" - })\n`, -); +if (status === "UNVERIFIED") { + // Not a pass (D-14): set HOSTING_BASE_URL to the deployed release. + process.stderr.write( + "Hosting header contract: UNVERIFIED (fixture: declared headers are consistent; set HOSTING_BASE_URL to probe the deployed release)\n", + ); + process.exit(3); +} +process.stdout.write("Hosting header contract: PASS (live)\n"); diff --git a/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap b/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap index d85bd21f..9ce2eeab 100644 --- a/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap +++ b/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap @@ -86,15 +86,12 @@ jobs: if: \${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }} runs-on: ubuntu-latest timeout-minutes: 45 - env: - HOSTING_BASE_URL: "\${{ vars.HOSTING_BASE_URL }}" strategy: fail-fast: false matrix: include: - { gate: FE-GATE-012, name: bundle, browser: false } - { gate: FE-GATE-014, name: config-compatibility, browser: false } - - { gate: FE-GATE-019, name: hosting-header, browser: false } - { gate: FE-GATE-026, name: lab-performance, browser: true } - { gate: FE-GATE-028, name: manual-accessibility-review, browser: false } steps: @@ -378,10 +375,13 @@ jobs: if: \${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }} runs-on: ubuntu-latest timeout-minutes: 45 + env: + HOSTING_BASE_URL: "\${{ vars.HOSTING_BASE_URL }}" strategy: fail-fast: false matrix: include: + - { gate: FE-GATE-019, name: hosting-header } - { gate: FE-GATE-021, name: runbook-boot-config } - { gate: FE-GATE-022, name: runbook-chunk-mismatch } - { gate: FE-GATE-023, name: runbook-api-degradation } diff --git a/tests/unit/ci-workflow-generation.test.ts b/tests/unit/ci-workflow-generation.test.ts index 1a112315..e237df08 100644 --- a/tests/unit/ci-workflow-generation.test.ts +++ b/tests/unit/ci-workflow-generation.test.ts @@ -229,6 +229,18 @@ describe("CI gate contract", () => { expect(contract.stages.find(({ id }) => id === "merge")?.gateIds).toContain("FE-GATE-005"); }); + it("probes live hosting headers after promotion, not before the release is built (13-05)", async () => { + const contract = await loadCiGateContract(process.cwd()); + expect(contract.stages.find(({ id }) => id === "production")?.gateIds).toContain("FE-GATE-019"); + expect(contract.stages.find(({ id }) => id === "release")?.gateIds).not.toContain("FE-GATE-019"); + const productionGate = contract.jobs.find(({ id }) => id === "production_gate"); + expect(productionGate?.gateIds).toContain("FE-GATE-019"); + expect(productionGate?.environment).toContainEqual({ + name: "HOSTING_BASE_URL", + value: "${{ vars.HOSTING_BASE_URL }}", + }); + }); + it("keeps the action registry recursively immutable and resolves only known actions", () => { expect(Object.isFrozen(CI_ACTION_REGISTRY)).toBe(true); expect(Object.values(CI_ACTION_REGISTRY).every((action) => Object.isFrozen(action))).toBe(true); diff --git a/tests/unit/hosting-probe.test.ts b/tests/unit/hosting-probe.test.ts index 87c74296..df5668c1 100644 --- a/tests/unit/hosting-probe.test.ts +++ b/tests/unit/hosting-probe.test.ts @@ -3,6 +3,8 @@ import { describe, expect, it } from "vitest"; import { checkPublicServiceWorkers, classifyLiveHostingBaseUrl, + hostingVerdict, + servedEntryScript, } from "../../scripts/lib/hosting-probe.ts"; describe("public service worker in dist", () => { @@ -64,3 +66,24 @@ describe("live hosting evidence target", () => { }); }); }); + +// 13-05 (D-14). The declared-header fixture proves nothing about hosting, so it +// is UNVERIFIED, and a live probe checks the release actually served. +describe("hosting header verdict", () => { + it("passes only a live probe of the deployed release", () => { + expect(hostingVerdict("live", true)).toBe("PASS"); + expect(hostingVerdict("fixture", true)).toBe("UNVERIFIED"); + expect(hostingVerdict("fixture", false)).toBe("FAIL"); + expect(hostingVerdict("invalid-live", false)).toBe("FAIL"); + expect(hostingVerdict("live", false)).toBe("FAIL"); + }); + + it("probes the entry script named by the served index.html", () => { + expect( + servedEntryScript( + '', + ), + ).toBe("/app/assets/index-Dpjd89Th.js"); + expect(servedEntryScript("maintenance")).toBeNull(); + }); +});