Compare commits
7
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 donghyeon-ka
|
c089e749d0 | ||
|
donghyeon-ka
|
4667cafa43 | ||
|
donghyeon-ka
|
18bea3a852 | ||
|
donghyeon-ka
|
eb37cbe8be | ||
|
donghyeon-ka
|
b82bc73c6c | ||
|
donghyeon-ka
|
89f3c69413 | ||
|
donghyeon-ka
|
5ad6fb032e |
@@ -0,0 +1,63 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"families": {
|
||||
"api": {
|
||||
"additive": {
|
||||
"before": { "required": ["id"], "properties": { "id": {} } },
|
||||
"after": {
|
||||
"required": ["id"],
|
||||
"properties": { "id": {}, "displayName": {} }
|
||||
}
|
||||
},
|
||||
"breaking": {
|
||||
"before": { "required": ["id"], "properties": { "id": {} } },
|
||||
"after": {
|
||||
"required": ["id", "name"],
|
||||
"properties": { "id": {}, "name": {} }
|
||||
}
|
||||
}
|
||||
},
|
||||
"config": {
|
||||
"additive": {
|
||||
"before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
|
||||
"after": {
|
||||
"required": ["APP_ENV"],
|
||||
"properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} }
|
||||
}
|
||||
},
|
||||
"breaking": {
|
||||
"before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
|
||||
"after": {
|
||||
"required": ["APP_ENV", "NEW_REQUIRED"],
|
||||
"properties": { "APP_ENV": {}, "NEW_REQUIRED": {} }
|
||||
}
|
||||
}
|
||||
},
|
||||
"storage": {
|
||||
"additive": {
|
||||
"before": { "properties": { "theme": {} } },
|
||||
"after": { "properties": { "theme": {}, "contrast": {} } }
|
||||
},
|
||||
"breaking": {
|
||||
"before": { "properties": { "theme": {} } },
|
||||
"after": { "properties": {} }
|
||||
}
|
||||
},
|
||||
"release": {
|
||||
"additive": {
|
||||
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
|
||||
"after": {
|
||||
"required": ["buildId"],
|
||||
"properties": { "buildId": {}, "builtAt": {} }
|
||||
}
|
||||
},
|
||||
"breaking": {
|
||||
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
|
||||
"after": {
|
||||
"required": ["buildId", "assetManifestHash"],
|
||||
"properties": { "buildId": {}, "assetManifestHash": {} }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -106,49 +106,7 @@
|
||||
"path": "src/contracts/release-tokens.js",
|
||||
"exportName": "RELEASE_TOKEN_REGISTRY",
|
||||
"owner": "feature-frontend-release-cache-rollback-contract",
|
||||
"requiredFields": ["token", "source", "compatibilityRole"],
|
||||
"declaredRows": {
|
||||
"appVersion": {
|
||||
"token": "appVersion",
|
||||
"source": "manifest",
|
||||
"compatibilityRole": "human release label"
|
||||
},
|
||||
"buildId": {
|
||||
"token": "buildId",
|
||||
"source": "CI build",
|
||||
"compatibilityRole": "asset and HTML coherence"
|
||||
},
|
||||
"commitSha": {
|
||||
"token": "commitSha",
|
||||
"source": "VCS",
|
||||
"compatibilityRole": "source traceability"
|
||||
},
|
||||
"configSchemaVersion": {
|
||||
"token": "configSchemaVersion",
|
||||
"source": "runtime config schema",
|
||||
"compatibilityRole": "boot compatibility"
|
||||
},
|
||||
"apiContractVersion": {
|
||||
"token": "apiContractVersion",
|
||||
"source": "frontend/backend agreement",
|
||||
"compatibilityRole": "schema compatibility"
|
||||
},
|
||||
"assetManifestHash": {
|
||||
"token": "assetManifestHash",
|
||||
"source": "build output",
|
||||
"compatibilityRole": "chunk integrity"
|
||||
},
|
||||
"releaseId": {
|
||||
"token": "releaseId",
|
||||
"source": "deploy system",
|
||||
"compatibilityRole": "rollback target"
|
||||
},
|
||||
"builtAt": {
|
||||
"token": "builtAt",
|
||||
"source": "CI",
|
||||
"compatibilityRole": "diagnostics only"
|
||||
}
|
||||
}
|
||||
"requiredFields": ["token", "source", "compatibilityRole"]
|
||||
}
|
||||
],
|
||||
"compatibilityImpact": {
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"surfaces": {
|
||||
"index": {
|
||||
"path": "/",
|
||||
"cacheControl": "no-cache",
|
||||
"contentTypes": ["text/html"],
|
||||
"securityHeaders": true
|
||||
},
|
||||
"runtimeConfig": {
|
||||
"path": "/config.json",
|
||||
"cacheControl": "no-store",
|
||||
"contentTypes": ["application/json"],
|
||||
"securityHeaders": true
|
||||
},
|
||||
"releaseManifest": {
|
||||
"path": "/release-manifest.json",
|
||||
"cacheControl": "no-store",
|
||||
"contentTypes": ["application/json"],
|
||||
"securityHeaders": true
|
||||
},
|
||||
"hashedAsset": {
|
||||
"pathPattern": "/assets/*",
|
||||
"cacheControl": "public, max-age=31536000, immutable",
|
||||
"contentTypes": ["text/javascript", "application/javascript"],
|
||||
"securityHeaders": false
|
||||
},
|
||||
"sourceMap": {
|
||||
"public": false
|
||||
},
|
||||
"serviceWorker": {
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"responses": {
|
||||
"index": {
|
||||
"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=()"
|
||||
},
|
||||
"runtimeConfig": {
|
||||
"cache-control": "no-store",
|
||||
"content-type": "application/json; 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=()"
|
||||
},
|
||||
"releaseManifest": {
|
||||
"cache-control": "no-store",
|
||||
"content-type": "application/json; 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=()"
|
||||
},
|
||||
"hashedAsset": {
|
||||
"cache-control": "public, max-age=31536000, immutable",
|
||||
"content-type": "text/javascript; charset=utf-8"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,77 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"fixtures": [
|
||||
{
|
||||
"name": "coherent-release",
|
||||
"expectedCompatible": true,
|
||||
"frontend": {
|
||||
"buildId": "build-a",
|
||||
"configSchemaVersion": "1.0",
|
||||
"apiContractVersion": "1.0",
|
||||
"assetManifestHash": "assets-a",
|
||||
"releaseId": "release-a"
|
||||
},
|
||||
"runtime": {
|
||||
"buildId": "build-a",
|
||||
"configSchemaVersion": "1.1",
|
||||
"apiContractVersion": "1.2",
|
||||
"assetManifestHash": "assets-a",
|
||||
"releaseId": "release-a"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "mixed-html-and-assets",
|
||||
"expectedCompatible": false,
|
||||
"frontend": {
|
||||
"buildId": "build-a",
|
||||
"configSchemaVersion": "1.0",
|
||||
"apiContractVersion": "1.0",
|
||||
"assetManifestHash": "assets-a",
|
||||
"releaseId": "release-a"
|
||||
},
|
||||
"runtime": {
|
||||
"buildId": "build-b",
|
||||
"configSchemaVersion": "1.0",
|
||||
"apiContractVersion": "1.0",
|
||||
"assetManifestHash": "assets-b",
|
||||
"releaseId": "release-b"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "incompatible-runtime-config",
|
||||
"expectedCompatible": false,
|
||||
"frontend": {
|
||||
"buildId": "build-a",
|
||||
"configSchemaVersion": "1.0",
|
||||
"apiContractVersion": "1.0",
|
||||
"assetManifestHash": "assets-a",
|
||||
"releaseId": "release-a"
|
||||
},
|
||||
"runtime": {
|
||||
"buildId": "build-a",
|
||||
"configSchemaVersion": "2.0",
|
||||
"apiContractVersion": "1.0",
|
||||
"assetManifestHash": "assets-a",
|
||||
"releaseId": "release-a"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "incompatible-api-contract",
|
||||
"expectedCompatible": false,
|
||||
"frontend": {
|
||||
"buildId": "build-a",
|
||||
"configSchemaVersion": "1.0",
|
||||
"apiContractVersion": "1.0",
|
||||
"assetManifestHash": "assets-a",
|
||||
"releaseId": "release-a"
|
||||
},
|
||||
"runtime": {
|
||||
"buildId": "build-a",
|
||||
"configSchemaVersion": "1.0",
|
||||
"apiContractVersion": "2.0",
|
||||
"assetManifestHash": "assets-a",
|
||||
"releaseId": "release-a"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "ART-FE-003@1",
|
||||
"type": "object",
|
||||
"required": ["schemaVersion", "generatedAt", "artifact", "fixtures", "passed"],
|
||||
"properties": {
|
||||
"schemaVersion": { "const": 1 },
|
||||
"generatedAt": { "type": "string", "format": "date-time" },
|
||||
"artifact": {
|
||||
"type": "object",
|
||||
"required": ["checked", "compatible", "mismatches"]
|
||||
},
|
||||
"fixtures": { "type": "array", "minItems": 2 },
|
||||
"passed": { "type": "boolean" }
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
# Contract compatibility and rollback rules
|
||||
|
||||
The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion,
|
||||
assetManifestHash, releaseId)`. Versions are parsed numerically.
|
||||
|
||||
1. additive changes preserve current required fields
|
||||
2. breaking changes require a major version bump
|
||||
3. persisted cache is discarded unless an explicit tested migration exists
|
||||
4. an incompatible config or API contract blocks product mount
|
||||
5. rollback restores HTML, assets, runtime config, API compatibility, and
|
||||
release manifest as one coherent set
|
||||
@@ -0,0 +1,32 @@
|
||||
# Release, cache, and rollback contract
|
||||
|
||||
Each deployment is an immutable `releases/<releaseId>/` artifact set. The
|
||||
provider adapter must upload assets, release manifest, runtime config, and
|
||||
verify asset reachability before atomically switching the active HTML pointer.
|
||||
The post-switch boot, route, API, telemetry, and reload-loop smoke checks close
|
||||
the deployment.
|
||||
|
||||
Rollback selects a prior release tuple, confirms its assets and runtime/API
|
||||
compatibility, atomically switches the complete set, performs the provider
|
||||
cache action, and repeats the smoke checks. Rebuilding an old commit, replacing
|
||||
HTML alone, or declaring recovery from cache-purge completion is prohibited.
|
||||
Recovery is established by old/new reachability probes.
|
||||
|
||||
The provider-independent cache defaults are:
|
||||
|
||||
- hashed assets: `public, max-age=31536000, immutable`
|
||||
- HTML: `no-cache`
|
||||
- runtime config and release manifest: `no-store`
|
||||
- public source maps: disabled
|
||||
- service worker/offline cache: disabled
|
||||
|
||||
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.
|
||||
+4
-1
@@ -30,7 +30,10 @@
|
||||
"generate:supply-chain": "node scripts/generate-supply-chain.mjs",
|
||||
"scan:security": "node scripts/security-scan.mjs",
|
||||
"check:browser-security": "node scripts/check-browser-security.mjs",
|
||||
"check:registries": "node scripts/check-registries.mjs"
|
||||
"check:registries": "node scripts/check-registries.mjs",
|
||||
"verify:compatibility": "node scripts/check-compatibility.mjs",
|
||||
"verify:release": "node scripts/verify-release.mjs",
|
||||
"verify:hosting-headers": "node scripts/verify-hosting-headers.mjs"
|
||||
},
|
||||
"dependencies": {
|
||||
"@tanstack/react-query": "5.101.4",
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"appVersion": "0.1.0",
|
||||
"buildId": "local-build",
|
||||
"commitSha": "local",
|
||||
"configSchemaVersion": "1",
|
||||
"apiContractVersion": "1",
|
||||
"assetManifestHash": "generated-during-build",
|
||||
"releaseId": "local-release",
|
||||
"builtAt": "1970-01-01T00:00:00.000Z"
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
|
||||
import { classifyObjectSchemaChange } from "../src/application/policies/compatibility.js";
|
||||
|
||||
const fixtures = JSON.parse(
|
||||
await readFile("config/compatibility/fixtures.json", "utf8"),
|
||||
);
|
||||
const results = [];
|
||||
|
||||
for (const [family, cases] of Object.entries(fixtures.families)) {
|
||||
for (const expected of ["additive", "breaking"]) {
|
||||
const fixture = cases[expected];
|
||||
const actual = classifyObjectSchemaChange(fixture.before, fixture.after);
|
||||
results.push({ family, expected, actual, passed: actual === expected });
|
||||
}
|
||||
}
|
||||
|
||||
await mkdir("artifacts/release", { recursive: true });
|
||||
await writeFile(
|
||||
"artifacts/release/compatibility.json",
|
||||
`${JSON.stringify(
|
||||
{
|
||||
schemaVersion: 1,
|
||||
generatedAt: new Date().toISOString(),
|
||||
rules: [
|
||||
"additive changes preserve required fields",
|
||||
"breaking changes require version bump and migration, discard, fallback, or rollback",
|
||||
"config and API major versions must match",
|
||||
"incompatible persisted cache is discarded by default",
|
||||
"rollback uses a coherent compatibility tuple",
|
||||
],
|
||||
results,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
)}\n`,
|
||||
);
|
||||
|
||||
if (results.some((result) => !result.passed)) {
|
||||
process.stderr.write("Compatibility fixture classification failed.\n");
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write("Compatibility fixtures: PASS\n");
|
||||
@@ -1,3 +1,4 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
import process from "node:process";
|
||||
|
||||
@@ -5,13 +6,23 @@ const packageJson = JSON.parse(await readFile("package.json", "utf8"));
|
||||
const packageManagerVersion = packageJson.packageManager.split("@").at(-1);
|
||||
const buildId = process.env.VITE_BUILD_ID ?? "local-build";
|
||||
const commitSha = process.env.VITE_COMMIT_SHA ?? "local";
|
||||
const releaseId = process.env.RELEASE_ID ?? "local-release";
|
||||
const runnerImage = process.env.CI_RUNNER_IMAGE ?? `${process.platform}-${process.arch}`;
|
||||
const builtAt = new Date().toISOString();
|
||||
const viteManifest = await readFile("dist/.vite/manifest.json");
|
||||
const assetManifestHash = createHash("sha256")
|
||||
.update(viteManifest)
|
||||
.digest("hex");
|
||||
const runtimeConfig = JSON.parse(await readFile("dist/config.json", "utf8"));
|
||||
|
||||
runtimeConfig.BUILD_ID = buildId;
|
||||
runtimeConfig.RELEASE_ID = releaseId;
|
||||
|
||||
const manifest = {
|
||||
schemaVersion: 1,
|
||||
buildId,
|
||||
commitSha,
|
||||
generatedAt: new Date().toISOString(),
|
||||
generatedAt: builtAt,
|
||||
buildContext: {
|
||||
nodeVersion: process.version,
|
||||
packageManagerVersion,
|
||||
@@ -23,7 +34,24 @@ const manifest = {
|
||||
},
|
||||
};
|
||||
|
||||
const releaseManifest = {
|
||||
schemaVersion: 1,
|
||||
appVersion: packageJson.version,
|
||||
buildId,
|
||||
commitSha,
|
||||
configSchemaVersion: runtimeConfig.CONFIG_SCHEMA_VERSION,
|
||||
apiContractVersion: runtimeConfig.API_CONTRACT_VERSION,
|
||||
assetManifestHash,
|
||||
releaseId,
|
||||
builtAt,
|
||||
};
|
||||
|
||||
await mkdir("artifacts/release", { recursive: true });
|
||||
await writeFile("dist/config.json", `${JSON.stringify(runtimeConfig, null, 2)}\n`);
|
||||
await writeFile(
|
||||
"dist/release-manifest.json",
|
||||
`${JSON.stringify(releaseManifest, null, 2)}\n`,
|
||||
);
|
||||
await writeFile(
|
||||
"artifacts/release/build-manifest.json",
|
||||
`${JSON.stringify(manifest, null, 2)}\n`,
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/;
|
||||
|
||||
/**
|
||||
* A release gate must not promote a local preview server as live hosting
|
||||
* evidence.
|
||||
*
|
||||
* @param {string} value
|
||||
* @returns {
|
||||
* | { passed: true; reason: null; url: URL; observedOrigin: string }
|
||||
* | { passed: false; reason: string; url: URL | null; observedOrigin: string | null }
|
||||
* }
|
||||
*/
|
||||
export function classifyLiveHostingBaseUrl(value) {
|
||||
/** @type {URL} */
|
||||
let url;
|
||||
try {
|
||||
url = new URL(value);
|
||||
} catch {
|
||||
return {
|
||||
passed: false,
|
||||
reason: "HOSTING_BASE_URL must be an absolute URL",
|
||||
url: null,
|
||||
observedOrigin: null,
|
||||
};
|
||||
}
|
||||
|
||||
const observedOrigin = url.origin;
|
||||
const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
|
||||
if (url.protocol !== "https:") {
|
||||
return {
|
||||
passed: false,
|
||||
reason: "live hosting evidence requires HTTPS",
|
||||
url,
|
||||
observedOrigin,
|
||||
};
|
||||
}
|
||||
if (url.username || url.password) {
|
||||
return {
|
||||
passed: false,
|
||||
reason: "HOSTING_BASE_URL must not contain credentials",
|
||||
url,
|
||||
observedOrigin,
|
||||
};
|
||||
}
|
||||
if (
|
||||
hostname === "localhost" ||
|
||||
hostname.endsWith(".localhost") ||
|
||||
hostname === "::1" ||
|
||||
hostname === "0.0.0.0" ||
|
||||
LOOPBACK_IPV4.test(hostname)
|
||||
) {
|
||||
return {
|
||||
passed: false,
|
||||
reason: "local or loopback hosts are not live deployment evidence",
|
||||
url,
|
||||
observedOrigin,
|
||||
};
|
||||
}
|
||||
if (url.pathname !== "/" || url.search || url.hash) {
|
||||
return {
|
||||
passed: false,
|
||||
reason: "HOSTING_BASE_URL must be the canonical root URL",
|
||||
url,
|
||||
observedOrigin,
|
||||
};
|
||||
}
|
||||
return { passed: true, reason: null, url, observedOrigin };
|
||||
}
|
||||
@@ -0,0 +1,183 @@
|
||||
import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
|
||||
|
||||
import { classifyLiveHostingBaseUrl } from "./lib/hosting-probe.mjs";
|
||||
|
||||
const cachePolicy = JSON.parse(
|
||||
await readFile("config/hosting/cache-policy.json", "utf8"),
|
||||
);
|
||||
const securityPolicy = JSON.parse(
|
||||
await readFile("config/hosting/security-headers.json", "utf8"),
|
||||
);
|
||||
const baseUrl = process.env.HOSTING_BASE_URL;
|
||||
const liveTarget = baseUrl ? classifyLiveHostingBaseUrl(baseUrl) : null;
|
||||
const distFiles = (await readdir("dist", { recursive: true })).map(String);
|
||||
const publicSourceMaps = distFiles.filter((file) => file.endsWith(".map"));
|
||||
const publicServiceWorkers = distFiles.filter((file) =>
|
||||
/(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i.test(file),
|
||||
);
|
||||
|
||||
/** @type {Record<string, Record<string, string>>} */
|
||||
let responses = {};
|
||||
let mode;
|
||||
/** @type {Array<{
|
||||
* surface: string;
|
||||
* header: string;
|
||||
* expected: unknown;
|
||||
* observed: unknown;
|
||||
* reason?: string;
|
||||
* passed: boolean;
|
||||
* }>} */
|
||||
const probeResults = [];
|
||||
|
||||
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}`,
|
||||
};
|
||||
responses = {};
|
||||
for (const [surface, pathname] of Object.entries(paths)) {
|
||||
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,
|
||||
]),
|
||||
);
|
||||
} catch (error) {
|
||||
probeResults.push({
|
||||
surface,
|
||||
header: "transport",
|
||||
expected: "reachable",
|
||||
observed: error instanceof Error ? error.name : "UnknownError",
|
||||
passed: false,
|
||||
});
|
||||
}
|
||||
}
|
||||
} else if (liveTarget) {
|
||||
mode = "invalid-live";
|
||||
probeResults.push({
|
||||
surface: "deployment",
|
||||
header: "base-url",
|
||||
expected: "canonical non-loopback HTTPS root URL",
|
||||
observed: liveTarget.observedOrigin,
|
||||
reason: liveTarget.reason,
|
||||
passed: false,
|
||||
});
|
||||
} else {
|
||||
mode = "fixture";
|
||||
responses = JSON.parse(
|
||||
await readFile("config/hosting/response-headers.fixture.json", "utf8"),
|
||||
).responses;
|
||||
}
|
||||
|
||||
const results = [...probeResults];
|
||||
for (const [surface, policy] of Object.entries(cachePolicy.surfaces)) {
|
||||
if (!("cacheControl" in policy)) continue;
|
||||
const observed = responses[surface]?.["cache-control"];
|
||||
results.push({
|
||||
surface,
|
||||
header: "cache-control",
|
||||
expected: policy.cacheControl,
|
||||
observed,
|
||||
passed: observed === policy.cacheControl,
|
||||
});
|
||||
const observedContentType = responses[surface]?.["content-type"];
|
||||
const observedMime = observedContentType
|
||||
?.split(";", 1)[0]
|
||||
.trim()
|
||||
.toLowerCase();
|
||||
results.push({
|
||||
surface,
|
||||
header: "content-type",
|
||||
expected: policy.contentTypes,
|
||||
observed: observedContentType,
|
||||
passed: policy.contentTypes.includes(observedMime),
|
||||
});
|
||||
if (policy.securityHeaders) {
|
||||
for (const [header, expected] of Object.entries(securityPolicy.headers)) {
|
||||
const observedSecurity = responses[surface]?.[header.toLowerCase()];
|
||||
results.push({
|
||||
surface,
|
||||
header: header.toLowerCase(),
|
||||
expected,
|
||||
observed: observedSecurity,
|
||||
passed: observedSecurity === expected,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
results.push({
|
||||
surface: "sourceMap",
|
||||
header: "public",
|
||||
expected: false,
|
||||
observed: publicSourceMaps.length > 0,
|
||||
passed:
|
||||
cachePolicy.surfaces.sourceMap.public === false &&
|
||||
publicSourceMaps.length === 0,
|
||||
});
|
||||
results.push({
|
||||
surface: "serviceWorker",
|
||||
header: "enabled",
|
||||
expected: false,
|
||||
observed: publicServiceWorkers.length > 0,
|
||||
passed:
|
||||
cachePolicy.surfaces.serviceWorker.enabled === false &&
|
||||
publicServiceWorkers.length === 0,
|
||||
});
|
||||
|
||||
const passed = results.every((result) => result.passed);
|
||||
await mkdir("artifacts/release", { recursive: true });
|
||||
await writeFile(
|
||||
"artifacts/release/hosting-headers.json",
|
||||
`${JSON.stringify(
|
||||
{
|
||||
schemaVersion: 1,
|
||||
generatedAt: new Date().toISOString(),
|
||||
mode,
|
||||
baseUrl: liveTarget?.observedOrigin ?? null,
|
||||
providerVerificationRequired: mode !== "live",
|
||||
results,
|
||||
passed,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
)}\n`,
|
||||
);
|
||||
|
||||
if (!passed) {
|
||||
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`,
|
||||
);
|
||||
@@ -0,0 +1,98 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
|
||||
import { verifyCompatibilityTuple } from "../src/application/policies/compatibility.js";
|
||||
import {
|
||||
compareReleaseToRuntime,
|
||||
RELEASE_TOKEN_REGISTRY,
|
||||
} from "../src/contracts/release-tokens.js";
|
||||
|
||||
const fixturesDocument =
|
||||
/** @type {{
|
||||
* fixtures: Array<{
|
||||
* name: string,
|
||||
* expectedCompatible: boolean,
|
||||
* frontend: {
|
||||
* buildId: string,
|
||||
* configSchemaVersion: string,
|
||||
* apiContractVersion: string,
|
||||
* assetManifestHash: string,
|
||||
* releaseId: string
|
||||
* },
|
||||
* runtime: {
|
||||
* buildId: string,
|
||||
* configSchemaVersion: string,
|
||||
* apiContractVersion: string,
|
||||
* assetManifestHash: string,
|
||||
* releaseId: string
|
||||
* }
|
||||
* }>
|
||||
* }} */ (
|
||||
JSON.parse(
|
||||
await readFile("config/release/coherence-fixtures.json", "utf8"),
|
||||
)
|
||||
);
|
||||
const release = JSON.parse(await readFile("dist/release-manifest.json", "utf8"));
|
||||
const runtimeConfig = JSON.parse(await readFile("dist/config.json", "utf8"));
|
||||
const viteManifest = await readFile("dist/.vite/manifest.json");
|
||||
const actualAssetManifestHash = createHash("sha256")
|
||||
.update(viteManifest)
|
||||
.digest("hex");
|
||||
|
||||
const artifactComparison = compareReleaseToRuntime(release, runtimeConfig);
|
||||
const artifactMismatches = [...artifactComparison.mismatches];
|
||||
for (const token of Object.keys(RELEASE_TOKEN_REGISTRY)) {
|
||||
if (typeof release[token] !== "string" || release[token].length === 0) {
|
||||
artifactMismatches.push(`releaseToken:${token}`);
|
||||
}
|
||||
}
|
||||
if (!Number.isFinite(Date.parse(release.builtAt))) {
|
||||
artifactMismatches.push("releaseToken:builtAtFormat");
|
||||
}
|
||||
if (release.assetManifestHash !== actualAssetManifestHash) {
|
||||
artifactMismatches.push("assetManifestContent");
|
||||
}
|
||||
|
||||
const fixtures = fixturesDocument.fixtures.map((fixture) => {
|
||||
const result = verifyCompatibilityTuple({
|
||||
frontend: fixture.frontend,
|
||||
runtime: fixture.runtime,
|
||||
});
|
||||
return {
|
||||
name: fixture.name,
|
||||
expectedCompatible: fixture.expectedCompatible,
|
||||
actualCompatible: result.compatible,
|
||||
mismatches: result.mismatches,
|
||||
passed: result.compatible === fixture.expectedCompatible,
|
||||
};
|
||||
});
|
||||
const artifact = {
|
||||
checked: true,
|
||||
compatible: artifactComparison.compatible && artifactMismatches.length === 0,
|
||||
mismatches: artifactMismatches,
|
||||
releaseId: release.releaseId,
|
||||
};
|
||||
const passed = artifact.compatible && fixtures.every((fixture) => fixture.passed);
|
||||
const report = {
|
||||
schemaVersion: 1,
|
||||
generatedAt: new Date().toISOString(),
|
||||
artifact,
|
||||
fixtures,
|
||||
passed,
|
||||
};
|
||||
|
||||
await mkdir("artifacts/release", { recursive: true });
|
||||
await writeFile(
|
||||
"artifacts/release/verification.json",
|
||||
`${JSON.stringify(report, null, 2)}\n`,
|
||||
);
|
||||
|
||||
if (!passed) {
|
||||
process.stderr.write(
|
||||
`Release coherence failed: ${artifactMismatches.join(", ") || "fixture"}\n`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Release coherence: PASS (${fixtures.length - 1} mixed fixtures rejected)\n`,
|
||||
);
|
||||
@@ -0,0 +1,102 @@
|
||||
export const COMPATIBILITY_TUPLE_FIELDS = Object.freeze([
|
||||
"buildId",
|
||||
"configSchemaVersion",
|
||||
"apiContractVersion",
|
||||
"assetManifestHash",
|
||||
"releaseId",
|
||||
]);
|
||||
|
||||
/** @param {string} version */
|
||||
export function parseNumericVersion(version) {
|
||||
const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(version);
|
||||
if (!match) return null;
|
||||
return {
|
||||
major: Number(match[1]),
|
||||
minor: Number(match[2] ?? 0),
|
||||
patch: Number(match[3] ?? 0),
|
||||
};
|
||||
}
|
||||
|
||||
/** @param {string} supported @param {string} actual */
|
||||
export function isVersionCompatible(supported, actual) {
|
||||
const expected = parseNumericVersion(supported);
|
||||
const candidate = parseNumericVersion(actual);
|
||||
if (!expected || !candidate) return false;
|
||||
return (
|
||||
expected.major === candidate.major &&
|
||||
candidate.minor >= expected.minor
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {{
|
||||
* frontend: {
|
||||
* buildId: string,
|
||||
* configSchemaVersion: string,
|
||||
* apiContractVersion: string,
|
||||
* assetManifestHash: string,
|
||||
* releaseId: string
|
||||
* },
|
||||
* runtime: {
|
||||
* buildId: string,
|
||||
* configSchemaVersion: string,
|
||||
* apiContractVersion: string,
|
||||
* assetManifestHash: string,
|
||||
* releaseId: string
|
||||
* }
|
||||
* }} input
|
||||
*/
|
||||
export function verifyCompatibilityTuple(input) {
|
||||
const mismatches = [];
|
||||
if (input.frontend.buildId !== input.runtime.buildId) mismatches.push("buildId");
|
||||
if (
|
||||
!isVersionCompatible(
|
||||
input.frontend.configSchemaVersion,
|
||||
input.runtime.configSchemaVersion,
|
||||
)
|
||||
) {
|
||||
mismatches.push("configSchemaVersion");
|
||||
}
|
||||
if (
|
||||
!isVersionCompatible(
|
||||
input.frontend.apiContractVersion,
|
||||
input.runtime.apiContractVersion,
|
||||
)
|
||||
) {
|
||||
mismatches.push("apiContractVersion");
|
||||
}
|
||||
if (input.frontend.assetManifestHash !== input.runtime.assetManifestHash) {
|
||||
mismatches.push("assetManifestHash");
|
||||
}
|
||||
|
||||
const releaseWarning =
|
||||
input.frontend.releaseId === input.runtime.releaseId
|
||||
? null
|
||||
: "releaseId";
|
||||
return Object.freeze({
|
||||
compatible: mismatches.length === 0,
|
||||
mismatches: Object.freeze(mismatches),
|
||||
warnings: Object.freeze(releaseWarning ? [releaseWarning] : []),
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {{ required?: string[], properties?: Record<string, unknown> }} before
|
||||
* @param {{ required?: string[], properties?: Record<string, unknown> }} after
|
||||
*/
|
||||
export function classifyObjectSchemaChange(before, after) {
|
||||
const beforeRequired = new Set(before.required ?? []);
|
||||
const afterRequired = new Set(after.required ?? []);
|
||||
const removedProperties = Object.keys(before.properties ?? {}).filter(
|
||||
(key) => !(key in (after.properties ?? {})),
|
||||
);
|
||||
const addedRequired = [...afterRequired].filter(
|
||||
(key) => !beforeRequired.has(key),
|
||||
);
|
||||
if (removedProperties.length > 0 || addedRequired.length > 0) return "breaking";
|
||||
|
||||
const addedProperties = Object.keys(after.properties ?? {}).filter(
|
||||
(key) => !(key in (before.properties ?? {})),
|
||||
);
|
||||
return addedProperties.length > 0 ? "additive" : "none";
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
import { verifyCompatibilityTuple } from "../application/policies/compatibility.js";
|
||||
|
||||
export const RELEASE_TOKEN_REGISTRY = Object.freeze({
|
||||
appVersion: token("appVersion", "manifest", "human release label"),
|
||||
buildId: token("buildId", "CI build", "asset and HTML coherence"),
|
||||
commitSha: token("commitSha", "VCS", "source traceability"),
|
||||
configSchemaVersion: token(
|
||||
"configSchemaVersion",
|
||||
"runtime config schema",
|
||||
"boot compatibility",
|
||||
),
|
||||
apiContractVersion: token(
|
||||
"apiContractVersion",
|
||||
"frontend/backend agreement",
|
||||
"schema compatibility",
|
||||
),
|
||||
assetManifestHash: token(
|
||||
"assetManifestHash",
|
||||
"build output",
|
||||
"chunk integrity and mismatch detection",
|
||||
),
|
||||
releaseId: token("releaseId", "deploy system", "rollback target"),
|
||||
builtAt: token("builtAt", "CI", "diagnostics only; never cache identity"),
|
||||
});
|
||||
|
||||
/**
|
||||
* @param {string} name
|
||||
* @param {string} source
|
||||
* @param {string} compatibilityRole
|
||||
*/
|
||||
function token(name, source, compatibilityRole) {
|
||||
return Object.freeze({ token: name, source, compatibilityRole });
|
||||
}
|
||||
|
||||
/**
|
||||
* Compare a release manifest and runtime configuration structurally. Version
|
||||
* fields are delegated to the numeric compatibility policy, never compared
|
||||
* lexically.
|
||||
*
|
||||
* @param {{
|
||||
* buildId: string,
|
||||
* configSchemaVersion: string,
|
||||
* apiContractVersion: string,
|
||||
* assetManifestHash: string,
|
||||
* releaseId: string
|
||||
* }} release
|
||||
* @param {{
|
||||
* BUILD_ID: string,
|
||||
* CONFIG_SCHEMA_VERSION: string,
|
||||
* API_CONTRACT_VERSION: string,
|
||||
* RELEASE_ID: string
|
||||
* }} runtimeConfig
|
||||
*/
|
||||
export function compareReleaseToRuntime(release, runtimeConfig) {
|
||||
return verifyCompatibilityTuple({
|
||||
frontend: release,
|
||||
runtime: {
|
||||
buildId: runtimeConfig.BUILD_ID,
|
||||
configSchemaVersion: runtimeConfig.CONFIG_SCHEMA_VERSION,
|
||||
apiContractVersion: runtimeConfig.API_CONTRACT_VERSION,
|
||||
assetManifestHash: release.assetManifestHash,
|
||||
releaseId: runtimeConfig.RELEASE_ID,
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,77 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
classifyObjectSchemaChange,
|
||||
isVersionCompatible,
|
||||
parseNumericVersion,
|
||||
verifyCompatibilityTuple,
|
||||
} from "../../src/application/policies/compatibility.js";
|
||||
|
||||
describe("contract compatibility", () => {
|
||||
it("uses numeric version parsing rather than lexical comparison", () => {
|
||||
expect(parseNumericVersion("1.10.0")).toEqual({ major: 1, minor: 10, patch: 0 });
|
||||
expect(isVersionCompatible("1.9", "1.10")).toBe(true);
|
||||
expect(isVersionCompatible("1.9", "2.0")).toBe(false);
|
||||
expect(isVersionCompatible("next", "1.0")).toBe(false);
|
||||
});
|
||||
|
||||
it("distinguishes additive and breaking object changes", () => {
|
||||
const base = { required: ["id"], properties: { id: {} } };
|
||||
expect(
|
||||
classifyObjectSchemaChange(base, {
|
||||
required: ["id"],
|
||||
properties: { id: {}, name: {} },
|
||||
}),
|
||||
).toBe("additive");
|
||||
expect(
|
||||
classifyObjectSchemaChange(base, {
|
||||
required: ["id", "name"],
|
||||
properties: { id: {}, name: {} },
|
||||
}),
|
||||
).toBe("breaking");
|
||||
});
|
||||
|
||||
it("treats release ID mismatch as a warning when the blocking tuple is coherent", () => {
|
||||
const frontend = {
|
||||
buildId: "build-a",
|
||||
configSchemaVersion: "1.0",
|
||||
apiContractVersion: "1.0",
|
||||
assetManifestHash: "hash-a",
|
||||
releaseId: "release-a",
|
||||
};
|
||||
expect(
|
||||
verifyCompatibilityTuple({
|
||||
frontend,
|
||||
runtime: { ...frontend, releaseId: "release-b" },
|
||||
}),
|
||||
).toEqual({
|
||||
compatible: true,
|
||||
mismatches: [],
|
||||
warnings: ["releaseId"],
|
||||
});
|
||||
});
|
||||
|
||||
it("blocks mixed build, config, API, or asset tuples", () => {
|
||||
const frontend = {
|
||||
buildId: "build-a",
|
||||
configSchemaVersion: "1.0",
|
||||
apiContractVersion: "1.0",
|
||||
assetManifestHash: "hash-a",
|
||||
releaseId: "release-a",
|
||||
};
|
||||
expect(
|
||||
verifyCompatibilityTuple({
|
||||
frontend,
|
||||
runtime: {
|
||||
...frontend,
|
||||
buildId: "build-b",
|
||||
configSchemaVersion: "2.0",
|
||||
assetManifestHash: "hash-b",
|
||||
},
|
||||
}),
|
||||
).toMatchObject({
|
||||
compatible: false,
|
||||
mismatches: ["buildId", "configSchemaVersion", "assetManifestHash"],
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,27 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { classifyLiveHostingBaseUrl } from "../../scripts/lib/hosting-probe.mjs";
|
||||
|
||||
describe("live hosting evidence target", () => {
|
||||
it("accepts a canonical production HTTPS root", () => {
|
||||
expect(
|
||||
classifyLiveHostingBaseUrl("https://frontend.example.test/"),
|
||||
).toMatchObject({
|
||||
passed: true,
|
||||
observedOrigin: "https://frontend.example.test",
|
||||
});
|
||||
});
|
||||
|
||||
it.each([
|
||||
["http://frontend.example.test/", "requires HTTPS"],
|
||||
["https://localhost:4173/", "not live deployment evidence"],
|
||||
["https://127.0.0.1/", "not live deployment evidence"],
|
||||
["https://frontend.example.test/app/", "canonical root URL"],
|
||||
["https://user:secret@frontend.example.test/", "must not contain credentials"],
|
||||
])("rejects %s", (url, reason) => {
|
||||
expect(classifyLiveHostingBaseUrl(url)).toMatchObject({
|
||||
passed: false,
|
||||
reason: expect.stringContaining(reason),
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,54 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
compareReleaseToRuntime,
|
||||
RELEASE_TOKEN_REGISTRY,
|
||||
} from "../../src/contracts/release-tokens.js";
|
||||
|
||||
describe("release coherence", () => {
|
||||
it("owns all eight release tokens and keeps builtAt diagnostic-only", () => {
|
||||
expect(Object.keys(RELEASE_TOKEN_REGISTRY)).toHaveLength(8);
|
||||
expect(RELEASE_TOKEN_REGISTRY.builtAt.compatibilityRole).toContain(
|
||||
"never cache identity",
|
||||
);
|
||||
});
|
||||
|
||||
it("compares the runtime config to the release structurally", () => {
|
||||
const release = {
|
||||
buildId: "build-a",
|
||||
configSchemaVersion: "1.0",
|
||||
apiContractVersion: "1.0",
|
||||
assetManifestHash: "assets-a",
|
||||
releaseId: "release-a",
|
||||
};
|
||||
expect(
|
||||
compareReleaseToRuntime(release, {
|
||||
BUILD_ID: "build-a",
|
||||
CONFIG_SCHEMA_VERSION: "1.2",
|
||||
API_CONTRACT_VERSION: "1.1",
|
||||
RELEASE_ID: "release-a",
|
||||
}),
|
||||
).toMatchObject({ compatible: true, mismatches: [] });
|
||||
});
|
||||
|
||||
it("rejects HTML-only rollback against a newer runtime config", () => {
|
||||
const oldRelease = {
|
||||
buildId: "build-old",
|
||||
configSchemaVersion: "1.0",
|
||||
apiContractVersion: "1.0",
|
||||
assetManifestHash: "assets-old",
|
||||
releaseId: "release-old",
|
||||
};
|
||||
expect(
|
||||
compareReleaseToRuntime(oldRelease, {
|
||||
BUILD_ID: "build-new",
|
||||
CONFIG_SCHEMA_VERSION: "2.0",
|
||||
API_CONTRACT_VERSION: "2.0",
|
||||
RELEASE_ID: "release-new",
|
||||
}),
|
||||
).toMatchObject({
|
||||
compatible: false,
|
||||
mismatches: ["buildId", "configSchemaVersion", "apiContractVersion"],
|
||||
});
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user